ESPC3-wireless/components/system/source/shell/README.md

简要

shell

是一款适合单片机用的简单的 shell 模块，使单片也能像 Linux 一样，具体基本的命令行功能，适用于示例、调试、应用等场合。

快捷键支持

• Tap： 补全命令或参数
• Up： 查看上一个命令
• Down： 查看下一个命令
• Home： 光标移到开头位置
• End： 光标移到结尾位置
• Ctrl+C: 结束程序
• Ctrl+D: 删除光标后一个字符或结束程序
• Ctrl+L: 清空终端
• Ctrl+A: 同 Home
• Ctrl+E: 同 End
• Ctrl+U: 擦除光标前到行首的全部内容
• Ctrl+K: 擦除光标后到行尾的全部内容
• Ctrl+W: 擦除光标前的单词
• Ctrl+Y: 还原擦除的内容
• Ctrl+Right: 光标移动到单词首位
• Ctrl+Left: 光标移动到单词结尾

如何使用

移植

调用 sh_init_vt100() 进行初始化时指定并实现两个对应的接口即可，实际上在 sh_vt100.c 已做好一系列的工作，一般情况下无需再另外实现，除非有多数据接口的需求。

初始化

在 sh_t100.c 中已通过 _install_shell_vt100() 被初始化，对象 g_uart_handle_vt100 直接可用。

注册命令列表

所有命令都必须先注册才可生效。

• 使用宏 SH_REGISTER_CMD 注册

  使用自动初始化的宏注册一个父命令列表。以下摘自 sc.h 文件的命令定义部分。

SH_DEF_SUB_CMD(
    _cmd_echo_sublist,
    SH_SETUP_CMD("on", "Enable to feedback the command line", _cmd_echo_on, NULL),    //
    SH_SETUP_CMD("off", "Disable to feedback the command line", _cmd_echo_off, NULL), //
);

SH_DEF_SUB_CMD(
    _cmd_sh_sublist,
    SH_SETUP_CMD("echo", "Turn on/off echo through sh_echo()", NULL, _cmd_echo_sublist),                                         //
    SH_SETUP_CMD("history", "Show history control", _cmd_history, _cmd_history_param),                                           //
    SH_SETUP_CMD("list-init", "List all auto initialize function\r\n\t* Usage: list-init [filter]", _cmd_print_init_fn, NULL),   //
    SH_SETUP_CMD("list-module", "List all module structure\r\n\t* Usage: list-module [filter]", _cmd_print_module_struct, NULL), //
    SH_SETUP_CMD("version", "Print the shell version", _cmd_version, NULL),                                                      //
    SH_SETUP_CMD("parse-value", "Parse the value of a string demo", _cmd_parse_test, NULL),                                      //
);

SH_REGISTER_CMD(
    register_internal_command,
    SH_SETUP_CMD("sh", "Internal command", NULL, _cmd_sh_sublist),                                   //
    SH_SETUP_CMD("help", "Print the complete root command", _cmd_print_help, _cmd_print_help_param), //
    SH_SETUP_CMD("select", "Select parent command", _cmd_select, _cmd_select_param),                 //
    SH_SETUP_CMD("exit", "Exit parent command or disconnect", _cmd_exit, NULL),                      //
);

• 使用函数接口动态注册
  • sh_register_cmd(const sh_cmd_reg_t *sh_reg);
  • sh_register_cmd_hide(const sh_cmd_reg_t *sh_reg);
  • sh_unregister_cmd(const sh_cmd_reg_t *sh_reg);

设置子命令、命令勾子和补全勾子

命令勾子和执行补全功能的勾子函数都在命令列表中确定，它们分别位于 SH_SETUP_CMD 的第 3、4 个参数。

• 命令勾子

  如实例中显示，位于 SH_SETUP_CMD 的第 3 个参数，设置命令勾子。
  如果命令勾子取值为函数地址，则表示这个命令为完整命令，此时第 4 个参数必须是 cp_fn ，并且可设置对补全勾子或者为 NULL；
  如果命令勾子取值为NULL，则表示这个命令为父命令，此时第 4 个参数必须是 sub_cmd ，并且指向另一个由 SH_DEF_SUB_CMD 定义的命令列表；

命令勾子的可用接口

• sh_set_prompt()
• sh_reset_line()
• sh_echo()
• sh_parse_value()
• sh_merge_param()

补全勾子的可用接口

• sh_putstr_quiet()
• sh_cmd_info()
• sh_completion_cmd()
• sh_completion_param()
• sh_completion_resource()
• sh_get_cp_result()

数据流向

• 输入

  任何需要解析的数据由 sh_putc() 或 sh_putstr() 开始, 在内部最终完成解析和回调执行的整个过程；

• 输出

  命令勾子或补全勾子可使用如下函数回显：

  • sh_echo()
  • sh_set_prompt()
  • sh_reset_line()

参考实例

• heap_shell.c
• fatfs_shell.c