nr_micro_shell在STM32+FreeRTOS平台的移植和使用

1. 基本介绍

nr_micro_shell 就是一个命令行交互工具，可以读取用户的命令输入，解析并执行命令对应的函数。nr_micro_shell 对于 ROM 和 RAM 的资源占用比较少，非常适合用于在嵌入式 MCU 的使用场合。

nr_micro_shell具有以下优点

1.占用资源少，使用简单，灵活方便。使用过程只涉及两个shell_init()和shell()两个函数，无论是使用RTOS还是裸机都可以方便的应用该工具，不需要额外的编码工作。

2.交互体验好。完全类似于linux shell命令行，当串口终端支持ANSI（如Hypertrm终端）时，其不仅支持基本的命令行交互，还提供Tab键命令补全，查询历史命令，方向键移动光标修改功能。

3.扩展性好。nr_micro_shell为用户提供自定义命令的标准函数原型，只需要按照命令编写命令函数，并注册命令函数，即可使用命令。

移植完之后的启动效果如下：

作者的代码仓库地址：

https://gitee.com/nrush/nr_micro_shell

2. 在 STM32+FreeRTOS上移植使用

我所使用的硬件平台是 STM32F407ZGT6，移植前我们需要准备好可以正常运行 FreeRTOS 和可以正常通过 printf 打印输出到串口终端的工程源码。如果使用裸机的话，那么就不用把 FreeRTOS 添加进来了，而且使用裸机移植会更简单。

要有正常运行 FreeRTOS 和串口工程源码，对于 STM32 来说非常方便，直接使用 STM32CubeMX 生成一份 MDK 的工程源码就行，这里我不多介绍这点了。

2.1 添加 nr_micro_shell 源码到工程目录

把 nr_micro_shell 源码拷贝到自己的工程目录下

添加 nr_micro_shell /src 目录的所有C文件，和 nr_micro_shell /examples 目录下的 nr_micro_shell_commands.c 文件。

添加头文件路径包含：

2.2 修改 nr_micro_shell_config.h 配置文件

1、把下面第44、45行包含了 RT-Thread 的头文件给注释掉，或者自己定义 NR_MICRO_SHELL_SIMULATOR 这个宏进行头文件包含屏蔽也可以。

2、对于 shell 输出的末尾行模式，我们选择修改为 1 ，即选择 \r 结尾。原来的代码默认是 0，即 \n 结尾，如果选择默认的行结尾模式的话，会导致 shell 终端运行不正常（我踩了这个坑，输入回车之后，命令不会执行。）

其实选择默认的 \n 结尾模式也可以，但是 shell 接收到 \r 结尾符的时候，要多输出一个 \n 。如下代码：

void task_shell(void const * argument)
{
	char ch;
    
	for(;;)
	{
		ch = uart1_get_char();
		shell(ch);
		if (ch == '\r')			// 遇到 \r 的时候，shell要多接收一个 \n 字符
			shell('\n');
	}
}

2.3 实现串口输出一个字符函数

在 nr_micro_shell_config.h 文件中的 144、145 行使用到了库函数 printf 和 putchar 函数，我们需要重新实现 fputc 函数才能正常打印输出，不然会导致程序死掉。

fputc 函数代码如下：

int fputc(int ch, FILE* f)
{
	char a = '\r';
	
    __HAL_UNLOCK(&huart1);
	
	if (ch == '\n')
	{
		HAL_UART_Transmit(&huart1, (uint8_t *)&a, 1, 1);
	}
	HAL_UART_Transmit(&huart1, (uint8_t *)&ch, 1, 1);
	
	return ch;
}

另外，还需要勾选上配置窗口使用 Use MicroLib 。

2.4 实现 shell 接收一个字符函数

shell 接收一个字符的函数，是必须由用户实现的，因为 nr_micro_shell 是无法确定你从什么设备上接收一个字符的。我这里需要实现一个从串口接收一个字符的函数。

因为我使用的是 STM32 + FreeRTOS 来运行 nr_micro_shell ，运行 FreeRTOS 要考虑到阻塞机制，不能让 shell 任务一直不断的运行，所以实现起来稍微麻烦一点点。

思路就是，在串口中断中接收一个字符放进环形缓冲区中，然后串口中断释放信号量唤醒 shell 任务。shell 线程则获取信号量，并且读取环形缓冲区的数据，没数据可读则进入阻塞状态。

1、环形缓冲区实现：

#define BUFFER_SIZE 64        /* 环形缓冲区的大小 */
typedef struct
{
	volatile unsigned int pR;           /* 读地址 */
	volatile unsigned int pW;           /* 写地址 */   
    unsigned char buffer[BUFFER_SIZE];  /* 缓冲区空间 */    
} ring_buffer;

/*
 *  函数名：void ring_buffer_init(ring_buffer *dst_buf)
 *  输入参数：dst_buf --> 指向目标缓冲区
 *  输出参数：无
 *  返回值：无
 *  函数作用：初始化缓冲区
*/
void ring_buffer_init(ring_buffer *dst_buf)
{
    dst_buf->pW = 0;
    dst_buf->pR = 0;
}

/*
 *  函数名：void ring_buffer_write(unsigned char c, ring_buffer *dst_buf)
 *  输入参数：c --> 要写入的数据
 *            dst_buf --> 指向目标缓冲区
 *  输出参数：无
 *  返回值：无
 *  函数作用：向目标缓冲区写入一个字节的数据，如果缓冲区满了就丢掉此数据
*/
void ring_buffer_write(unsigned char c, ring_buffer *dst_buf)
{
    int i = (dst_buf->pW + 1) % BUFFER_SIZE;
    if(i != dst_buf->pR)    // 环形缓冲区没有写满
    {
        dst_buf->buffer[dst_buf->pW] = c;
        dst_buf->pW = i;
    }
}

/*
 *  函数名：int ring_buffer_read(unsigned char *c, ring_buffer *dst_buf)
 *  输入参数：c --> 指向将读到的数据保存到内存中的地址
 *            dst_buf --> 指向目标缓冲区
 *  输出参数：无
 *  返回值：读到数据返回0，否则返回-1
 *  函数作用：从目标缓冲区读取一个字节的数据，如果缓冲区空了返回-1表明读取失败
*/
int ring_buffer_read(unsigned char *c, ring_buffer *dst_buf)
{
    if(dst_buf->pR == dst_buf->pW)
    {
        return -1;
    }
    else
    {
        *c = dst_buf->buffer[dst_buf->pR];
        dst_buf->pR = (dst_buf->pR + 1) % BUFFER_SIZE;
        return 0;
    }
}

2、串口中断代码

static SemaphoreHandle_t uart1_rx_sem;
static ring_buffer uart1_rx_buf = {0, 0, {0}};

void USART1_IRQHandler(void)
{
    int ch = -1;
	static BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    if ((__HAL_UART_GET_FLAG(&(huart1), UART_FLAG_RXNE) != RESET) &&
        (__HAL_UART_GET_IT_SOURCE(&(huart1), UART_IT_RXNE) != RESET))
    {
        while (1)
        {
            ch = -1;
            if (__HAL_UART_GET_FLAG(&(huart1), UART_FLAG_RXNE) != RESET)
            {
                ch =  huart1.Instance->DR & 0xff;
            }
            if (ch == -1)
            {
                break;
            }
            /* 读取到数据，将数据存入 ringbuffer */
            ring_buffer_write(ch, &uart1_rx_buf);
        }
        /* 释放信号量 */
        xSemaphoreGiveFromISR(uart1_rx_sem, &xHigherPriorityTaskWoken);
    }
}

3、获取一个字符函数实现

char uart1_get_char(void)
{
	unsigned char ch;
	while (ring_buffer_read(&ch, &uart1_rx_buf) != 0)
        xSemaphoreTake(uart1_rx_sem, portMAX_DELAY);
		
	return ch;
}

3. 测试验证

编写完上面要用到的代码之后，我们在 main 函数中创建一个 shell 任务。

/* 任务函数 */
void task_shell(void const * argument)
{
	/* USER CODE BEGIN StartDefaultTask */
	char ch;
	/* Infinite loop */
	for(;;)
	{
        /* 获取串口输入，然后解析执行命令 */
		ch = uart1_get_char();
		shell(ch);
	}
	/* USER CODE END StartDefaultTask */
}

xTaskCreate((TaskFunction_t )task_shell,           	 //任务函数
            (const char*    )"task_shell",           //任务名称
            (uint16_t       )512,        			 //任务堆栈大小
            (void*          )NULL,             		 //传递给任务函数的参数
            (UBaseType_t    )10,       				 //任务优先级
            (TaskHandle_t*  )NULL);     			 //任务句柄

编译下载后，打开 MobaXterm 终端软件，可以看到 shell 运行起来了，而且也可以运行命令。如下图：

目前只实现了两条命令，如果用户需要执行更多的命令，可以自己添加，然后导出到到命令列表就行。

发现一些问题：nr_micro_shell 还不支持一些特殊的按键，如果按下了这些特殊按键会导致程序崩溃。而且在使用方向键获取历史命令的时候，会把前导符 ”:“ 给覆盖掉，所以还是有些需要完善的地方的。

另外，还有一个功能更强大的 letter-shell ，这个 shell 工具支持的功能更多。letter-shell 仓库地址：

https://github.com/NevermindZZT/letter-shell