components/nr_micro_shell/README.md

   1 * # nr_micro_shell
   2
   3   ## 介绍
   4
   5   在进行调试和维护时，常常需要与单片机进行交互，获取、设置某些参数或执行某些操作，**nr_micro_shell**正是为满足这一需求，针对资源较少的MCU编写的基本命令行工具。虽然RT_Thread组件中已经提供了强大的**finsh**命令行交互工具，但对于ROM、RAM资源较少的单片机，**finsh**还是略显的庞大，在这些平台上，若仍想保留基本的命令行交互功能，**nr_micro_shell**是一个不错的选择。
   6
   7   **nr_micro_shell**具有以下优点
   8
   9   1.占用资源少，使用简单，灵活方便。使用过程只涉及两个shell_init()和shell()两个函数，无论是使用RTOS还是裸机都可以方便的应用该工具，不需要额外的编码工作。
  10
  11   2.交互体验好。完全类似于linux shell命令行，当串口终端支持ANSI（如Hypertrm终端）时，其不仅支持基本的命令行交互，还提供Tab键命令补全，查询历史命令，方向键移动光标修改功能。
  12
  13   3.扩展性好。**nr_micro_shell**为用户提供自定义命令的标准函数原型，只需要按照命令编写命令函数，并注册命令函数，即可使用命令。
  14
  15   ## 移植:
  16
  17   参考AIR101
  18
  19   ## 配置:
  20
  21   所有配置工作都可以在 **_nr_micro_shell_config.h_** 中完成。有关详细信息，请参见文件中的注释。
  22
  23   ## 用法:
  24
  25   - 确保所有文件都已添加到项目中。
  26
  27   - 确保 **_nr_micro_shell_config.h_** 中的宏函数"shell_printf()，ansi_show_char()"可以在项目中正常使用。
  28
  29   - 使用示例如下
  30
  31   ```c
  32   #include "nr_micro_shell.h"
  33
  34   int main(void)
  35   {
  36       /* 初始化 */
  37       shell_init();
  38
  39       while(1)
  40       {
  41           if(USART GET A CHAR 'c')
  42           {
  43               /* nr_micro_shell接收字符 */
  44               shell(c);
  45           }
  46       }
  47   }
  48   ```
  49
  50   建议直接使用硬件输入前，建议使用如下代码(确保可以正常打印信息)，验证nr_micro_shell是否可以正常运行
  51
  52   ```c
  53   #include "nr_micro_shell.h"
  54
  55   int main(void)
  56   {
  57       unsigned int i = 0;
  58       //匹配好结束符配置 NR_SHELL_END_OF_LINE 0
  59       char test_line[] = "test 1 2 3\n"
  60       /* 初始化 */
  61       shell_init();
  62
  63       /* 初步测试代码 */
  64       for(i = 0; i < sizeof(test_line)-1; i++)
  65       {
  66           shell(test_line[i]);
  67       }
  68
  69       /* 正式工作代码 */
  70       while(1)
  71       {
  72           if(USART GET A CHAR 'c')
  73           {
  74               /* nr_micro_shell接收字符 */
  75               shell(c);
  76           }
  77       }
  78   }
  79   ```
  80
  81   ## 添加自己的命令
  82
  83   **STEP1**:
  84
  85   您需要在**nr_micro_shell_commands.c***中实现一个命令函数。命令函数的原型如下
  86
  87   ```c
  88   void your_command_funtion(char argc, char *argv)
  89   {
  90       .....
  91   }
  92   ```
  93
  94   **argc**是参数的数目。**argv**存储每个参数的起始地址和内容。如果输入字符串是
  95
  96   ```c
  97   test -a 1
  98   ```
  99
 100   则**argc**为3，**argv**的内容为
 101
 102   ```c
 103   -------------------------------------------------------------
 104   0x03|0x08|0x0b|'t'|'e'|'s'|'t'|'\0'|'-'|'a'|'\0'|'1'|'\0'|
 105   -------------------------------------------------------------
 106   ```
 107
 108   如果想知道第一个或第二个参数的内容，应该使用
 109
 110   ```c
 111   /* "-a" */
 112   printf(argv[argv[1]])
 113   /* "1" */
 114   printf(argv[argv[2]])
 115   ```
 116
 117   **STEP2**:
 118   在使用命令前需要注册命令，共有两种方法注册命令
 119
 120   1.当配置文件中NR_SHELL_USING_EXPORT_CMD未被定义，在**static_cmd[]**表中写入
 121
 122   ```c
 123   const static_cmd_st static_cmd[] =
 124   {
 125      .....
 126      {"your_command_name",your_command_funtion},
 127      .....
 128      {"\0",NULL}
 129   };
 130   ```
 131
 132   **_注意：不要删除{"\0"，NULL}！_**
 133
 134   2.当配置文件中NR_SHELL_USING_EXPORT_CMD被定义，且NR_SHELL_CMD_EXPORT()支持使用的编译器时，可以使用以下方式注册命令
 135
 136   ```c
 137   NR_SHELL_CMD_EXPORT(your_command_name,your_command_funtion);
 138   ```
 139
 140   ## 注意事项
 141
 142   根据你的使用习惯使用NR_SHELL_USING_EXPORT_CMD选择命令注册方式。
 143
 144   使用注册表注册命令时，确保您的工程中存在注册表
 145
 146   ```c
 147   const static_cmd_st static_cmd[] ={   .....   {"\0",NULL}};
 148   ```
 149
 150   使用NR_SHELL_CMD_EXPORT()时确保，NR_SHELL_CMD_EXPORT()支持使用的编译器，否则会报错。
 151
 152   nr_micro_shell 不支持ESC键等控制键（控制符）。
 153
 154   ## 原地址连接
 155
 156   - 主页： <https://gitee.com/nrush/nr_micro_shell>