做嵌入式开发的朋友应该都有过这种经历板子跑起来以后想知道某个外设寄存器的值、想知道任务堆栈还剩多少最原始的办法就是加 printf串口一顿刷刷完还得在日志里翻。代码里到处都是 DEBUG_PRINTF发布前还要手动清理。后来我换了一种思路给设备塞一个命令行解释器让它自己接收指令、返回状态。这个方案就是 FreeRTOS 官方出的 FreeRTOS-Plus-CLI。这名字听着高大上其实就是一个跑在 MCU 上的轻量级命令解析器。不依赖文件系统不依赖网络只要有一条串口通道就能像操作 Linux 终端一样给开发板发命令查状态、控制 IO、调参数、跑自检全都能在串口终端里完成。这篇文章我不打算把官方文档翻译一遍而是把几个项目里用下来的真实经验写出来怎么把组件跑起来、怎么把自定义命令加进去、哪些配置必须提前设置、哪些坑我踩过还有几个让调试效率明显提升的进阶玩法。适合已经能熟练使用 FreeRTOS、但还没在项目里引入 CLI 的开发者。1. 先搞清楚FreeRTOS-Plus-CLI 到底能干什么1.1 我为什么会从 printf 大法转到 CLI以前调试一个运动控制板现场反馈说电机抖动但正常拍照、抓日志都很难复现。printf 只能看到“程序觉得发生了什么”看不到“我想主动控制它试试什么”。最痛苦的是想在线调 PID 参数改一个浮点常量重新编译、烧录、复位几分钟就没了。如果有 CLI我可以直接在终端里敲一句pid-set kp 1.2立刻试效果不合适再敲一句不用重编译。另一个痛点是日志淹没。嵌入式系统一跑起来串口每秒刷几十条日志关键信息混在一堆普通日志里。printf 是单向的信息量大但噪声也大CLI 是双向的我想要什么就发什么不需要时不刷屏。这种“按需查看”的体验一旦用过了就很难回去。还有个隐蔽的问题printf 对时序有影响。在实时性要求高的代码里printf 串口输出可能阻塞几百微秒甚至几毫秒电机控制环里轻轻一卡就是一顿。CLI 的解析和处理全部放在低优先级任务里只通过中断队列接收字符实时任务完全不受影响。1.2 它解决的核心问题与适用边界FreeRTOS-Plus-CLI 解决的核心问题就是 MCU 的“可交互性”。没有它设备是一个黑盒只能被动看日志有了它设备变成一台可对话的机器你可以查询任务堆栈、读取传感器数值、切换固件模式、开启调试开关甚至在生产线上执行校准步骤。不过要清楚它的边界。它不是一个完整的 Shell不支持管道、重定向、路径遍历也不支持动态加载命令。每条命令本质上是一个 C 函数命令表和解析逻辑都是静态编译进去的。它也不会帮你做字符回显、光标控制、历史记录这些都属于终端工具的功能需要依赖串口终端软件如 SecureCRT、Putty的本地配置。资源占用方面它确实很轻。核心代码就一个 cli.cRAM 主要是命令表、输入缓冲和输出缓冲Flash 也在 KB 级别。但如果你用的是 8KB RAM 都不到的超小 MCU还想要 2048 字节的输出缓冲区那就得掂量掂量了。一般来说RAM 在 16KB 以上的 MCU 用起来毫无压力。1.3 和其他嵌入式 Shell 比到底选哪个网上常见的嵌入式命令行方案还有 FinSH、nr_micro_shell、Letter Shell以及各种“自己撸一个串口命令”。我在选型时做过一个对比直接列出来方案依赖功能丰富度代码量/资源与 FreeRTOS 集成FreeRTOS-Plus-CLI仅 FreeRTOS命令注册、参数解析、help、长输出很小官方原生FinSHRT-Thread补全、历史、脚本较大需要适配Letter Shell无强依赖补全、历史、快捷键中等需自行对接nr_micro_shell无强依赖基本命令解析很小需自行对接自研无取决于投入初期小长期膨胀完全受控如果项目本来就在 FreeRTOS 上我的建议很明确优先用官方组件。理由有三个一是 API 风格和 FreeRTOS 一脉相承看一遍就能上手二是官方维护Bug 修复和版本跟进有保障三是不必在“Shell 对接系统”上花额外精力命令处理函数天然跑在 RTOS 上下文。自研方案最大的问题不是写不出来而是“写得不够全”。你总会遇到参数带引号怎么办、命令太长怎么办、输出超长怎么办、多任务并发调用怎么办这些边角问题。FreeRTOS-Plus-CLI 把这些边界都处理过了直接用就行。2. 核心机制与 API 逐个拆解2.1 一条命令从输入到输出的完整流程搞清楚底层流程比背 API 重要得多。一个完整流程是这样的系统启动后把命令定义结构体通过FreeRTOS_CLIRegisterCommand注册进内部命令表。UART 中断收到字符放入一个队列或直接喂给任务。CLI 任务从队列取字符拼接成一行字符串直到遇到回车或换行。任务调用FreeRTOS_CLIProcessCommand把整行文本交给解析器。解析器在命令表里按字符串匹配命令名匹配成功后调用该命令的处理函数。处理函数通过FreeRTOS_CLIGetParameter获取参数把响应文本写入输出缓冲区返回pdTRUE。FreeRTOS_CLIProcessCommand在输出缓冲区末尾追加\r\nCLI 任务再把整段文本发给串口。关键点在第 6 步命令处理函数是“同步执行”的它在 CLI 任务上下文里跑完整个业务逻辑然后再写输出。因此处理函数里不要做太重的延时或死循环否则会卡住整个 CLI串口输入再快也没用。2.2 命令表结构与处理函数签名注册命令的核心是CLI_Command_Definition_t结构体。直接贴源码typedef struct xCOMMAND_INPUT { const char *pcCommand; /* 命令名 */ const char *pcHelpString; /* help 命令显示的帮助文本 */ const xCommandInterpreterHandler_t pxCommandInterpreterHandler; /* 处理函数 */ int8_t cExpectedNumberOfParameters; /* 期望参数个数 */ } CLI_Command_Definition_t;处理函数原型长这样typedef BaseType_t (* xCommandInterpreterHandler_t)( char *pcWriteBuffer, /* 输出缓冲区 */ size_t xWriteBufferLength, /* 输出缓冲区长度 */ const char *pcCommandString /* 用户输入的完整命令字符串 */ );这里最容易被忽略的是cExpectedNumberOfParameters它统计的是“命令名 参数”的总个数。比如set-led 1 1这条命令cExpectedNumberOfParameters 应该是 3不是 2。我一开始就不小心写错过导致第二个参数取不到。还有一个冷知识这个字段可以是负数。如果你写成 -3表示“命令名 至少 2 个参数”也就是本命令允许可变参数。内部解析时负号会让校验更宽松。没用过这个特性之前我都是固定个数后来做一个配置命令时发现这个设计很有用比如set-cfg key value [flags]。2.3 参数获取FreeRTOS_CLIGetParameter 的细节参数获取只有这一个 API但细节不少const char *FreeRTOS_CLIGetParameter( const char *pcCommandString, UBaseType_t uxWantedParameter, BaseType_t *pxParameterStringLength );重点三条参数索引从 1 开始索引 0 是命令名本身。这与部分工程师的直觉相反很多人按 0 开始取结果取到命令名。返回的指针指向输入字符串中的参数起始位置但这个位置不是以\0结尾的。如果你直接strtol解析整数没问题因为strtol遇到空格或非数字字符会停但如果你拿来当普通 C 字符串strcmp或printf就会越界读到后面内容。第三个参数会返回参数长度适合做按长度拷贝或精确比较。不需要长度时可以传NULL。数值解析我推荐直接strtollong value strtol(param_ptr, NULL, 10);但要注意如果输入是abcstrtol不会报错它会把param_ptr原样返回且置 0。所以更稳妥的写法是结合长度判断或者用pxParameterStringLength限定范围后再解析。字符串参数推荐用双引号包裹例如log-set level error msg带空格的内容会被 CL 内部当作一个参数处理。2.4 输出缓冲与 FreeRTOS_CLIProcessCommand 的隐藏逻辑输出缓冲区大小由configCOMMAND_INT_MAX_OUTPUT_SIZE决定。这个宏不只是“建议值”它是整个组件能正常工作的硬性要求必须在 FreeRTOSConfig.h 里定义。默认源码里如果未定义编译会直接报错。还有一个隐藏逻辑命令处理函数返回值语义。返回pdTRUE即pdPASS表示命令处理完成CLI 会在输出末尾自动追加\r\n返回pdFALSE表示输出未完成需要再次调用同一个命令这是为“长输出”场景设计的。下一章我会专门讲这个。另外一个容易踩的点FreeRTOS_CLIProcessCommand内部用strcat往输出缓冲追加\r\n所以处理函数写入输出缓冲时必须保证缓冲区还剩至少 2 字节否则就有越界风险。实际使用中只要把configCOMMAND_INT_MAX_OUTPUT_SIZE设得足够大通常 1024 以上并且你的命令输出本身小于缓冲这个风险基本可控。3. 实战集成从零跑起来3.1 移植前的配置项把 cli.c 加入工程只是第一步真正决定能不能编译通过的是FreeRTOSConfig.h里的几个宏。我用的配置如下/* FreeRTOS-Plus-CLI 必需 */ #define configCOMMAND_INT_MAX_OUTPUT_SIZE 2048 /* 输出缓冲单位字节 */ #define configCOMMAND_MAX_INPUT_SIZE 256 /* 输入缓冲单位字节 */ /* 如果要支持内置 task-stats 命令 */ #define configUSE_TRACE_FACILITY 1 #define configUSE_STATS_FORMATTING_FUNCTIONS 1configCOMMAND_INT_MAX_OUTPUT_SIZE建议至少 1024。如果任务列表比较多2048 更好但代价是内存。注意这个缓冲如果在 CLI 任务里定义为局部变量任务栈对应的是“字节”而 FreeRTOS 任务栈大小单位是 word通常 4 字节计算时要换算。我见过有人定义char outputBuffer[2048]任务栈却只有 512 words结果一执行命令立刻栈溢出。configCOMMAND_MAX_INPUT_SIZE控制单条命令最大输入长度。默认有些版本是 256如果命令行里常带长参数建议加大到 512。3.2 CLI 任务与串口通道设计串口接收部分我推荐中断 队列的经典组合不要在任务里做忙等轮询。代码大概这样/* UART 接收中断 */ void UART_IRQHandler(void) { BaseType_t xHigherPriorityTaskWoken pdFALSE; char c UART_ReadByte(); xQueueSendFromISR(xCliUartQueue, c, xHigherPriorityTaskWoken); portYIELD_FROM_ISR(xHigherPriorityTaskWoken); }CLI 任务本身不复杂核心是一个字符状态机static void vCLITask(void *pvParameters) { char cRxChar; char cInputBuffer[configCOMMAND_MAX_INPUT_SIZE]; char cOutputBuffer[configCOMMAND_INT_MAX_OUTPUT_SIZE]; size_t xInputLength 0; for (;;) { if (xQueueReceive(xCliUartQueue, cRxChar, portMAX_DELAY) pdPASS) { if ((cRxChar \r) || (cRxChar \n)) { if (xInputLength 0) { cInputBuffer[xInputLength] \0; FreeRTOS_CLIProcessCommand(cInputBuffer, cOutputBuffer, sizeof(cOutputBuffer)); UARTSendString(cOutputBuffer); xInputLength 0; } } else if (cRxChar \b || cRxChar 0x7F) { if (xInputLength 0) { xInputLength--; } } else { if (xInputLength (configCOMMAND_MAX_INPUT_SIZE - 1)) { cInputBuffer[xInputLength] cRxChar; } } } } }这里有个细节收到回车前如果长度是 0直接忽略避免用户敲了一个回车就收到一个空命令。输入缓冲区必须留意越界所以判断里留了一个字节放终止符。删除键如果终端支持能处理一下体验更好但这不是 CLI 的核心需求。输出发送我直接用阻塞式 UARTSendString。如果 UART 驱动支持 DMA 或中断发送可以把输出也做成队列方式但要注意发送期间不能覆盖静态输出缓冲区。简单场景下阻塞发送最省心CLI 本来就是低优先级任务阻塞一下也不影响实时任务。3.3 注册自定义命令完整实例以控制 LED 为例写一个set-led命令完整代码static BaseType_t prvSetLedCommand(char *pcWriteBuffer, size_t xWriteBufferLength, const char *pcCommandString) { const char *pcParam1 FreeRTOS_CLIGetParameter(pcCommandString, 1, NULL); const char *pcParam2 FreeRTOS_CLIGetParameter(pcCommandString, 2, NULL); int xLed pcParam1 ? strtol(pcParam1, NULL, 10) : -1; int xOn pcParam2 ? strtol(pcParam2, NULL, 10) : -1; if ((xLed 0) || (xOn 0)) { snprintf(pcWriteBuffer, xWriteBufferLength, Error: usage: set-led led 0/1); } else { /* 这里替换为实际 GPIO 操作 */ LedSet(xLed, xOn); snprintf(pcWriteBuffer, xWriteBufferLength, LED %d - %s, xLed, xOn ? ON : OFF); } return pdTRUE; } static const CLI_Command_Definition_t xSetLedCommand { set-led, set-led led 0/1 : set LED on/off, prvSetLedCommand, 3 /* 命令名 两个参数 */ };然后在启动代码里注册FreeRTOS_CLIRegisterCommand(xSetLedCommand);效果就是在串口终端输入set-led 1 1终端返回LED 1 - ON这里有几个容易出错的地方。FreeRTOS_CLIGetParameter返回的是const char *但在strtol里可以直接转因为参数后面跟着空格或字符串结束数值解析能正确停止。如果参数缺失返回NULL所以我在代码里做了判空避免空指针崩溃。snprintf一定要传xWriteBufferLength防止输出超长溢出。3.4 处理长输出task-stats 的拆包技巧CLI 内置了task-stats命令可以列出任务状态、优先级、栈高水位。但它的实现是调用vTaskList一次性把表格写入缓冲区如果你的任务很多2048 字节都可能放不下。这时有两种思路第一种把输出缓冲区调大。简单粗暴但注意栈开销。如果缓冲区是 CLI 任务局部数组任务栈需要相应加大。比如 2048 字节缓冲栈至少要增加 512 words。更稳妥的方式是把输出缓冲区定义为static让它落在.bss段不占任务栈。我就是这么干的static char cOutputBuffer[configCOMMAND_INT_MAX_OUTPUT_SIZE];代价是这块内存常驻不能共享。但对 CLI 这种低频工具来说常驻内存可以接受。第二种利用返回pdFALSE实现长输出分片。官方设计是命令处理函数如果返回pdFALSEFreeRTOS_CLIProcessCommand会认为“还没输出完”再次调用时继续执行同一个命令。这种模式适合你自己写一个“按页输出”的命令比如打印一个大数据表格每页输出一部分返回pdFALSE直到输出完才返回pdTRUE。不过要注意长输出模式下处理函数需要通过静态变量保存“当前输出到哪了”。这会带来一个副作用如果用户中途先执行了别的命令状态就乱了。所以我在实际项目里很少用pdFALSE长输出更多是让每条命令的输出控制在输出缓冲以内一条命令完整返回。对于真正超大的数据我会设计成>
