1. 项目概述embedded-cli是一款专为资源受限嵌入式系统设计的单头文件single-header命令行接口CLI库。其核心目标是在 STM32、ESP32、ArduinoATmega328P、nRF52 等典型 MCU 平台上以极低的内存开销提供健壮、可配置、生产就绪的交互式调试与控制能力。它并非对 POSIX shell 的简单移植而是从嵌入式底层约束出发重新定义 CLI 的抽象模型无动态内存分配依赖可选、无标准 C 库依赖stdio.h、stdlib.h非必需、无线程/RTOS 依赖但天然兼容、零外部构建依赖。该库的“单头文件”特性意味着其全部实现包括数据结构定义、状态机逻辑、命令解析器、历史缓冲区管理、自动补全引擎均封装于一个.h文件中。开发者无需构建过程、无需链接额外库、无需管理头文件依赖树——仅需将embedded_cli.h复制到项目中按约定宏展开即可获得完整功能。这种设计极大简化了在裸机Bare-Metal或轻量级 RTOS如 FreeRTOS、Zephyr环境下的集成流程尤其适合需要快速迭代硬件固件调试接口的开发场景。embedded-cli的设计理念可概括为“显式控制、最小假设、最大可裁剪”显式控制所有内存分配策略动态/静态、输入输出通道UART/SPI/I2C/USB-CDC、命令绑定时机、处理周期均由用户代码显式指定库本身不隐式调用malloc、不轮询外设、不启动后台任务。最小假设仅假设存在一个字节流byte-stream收发能力如HAL_UART_Receive_IT 回调或Serial.read()不假设存在printf、getchar或文件系统。最大可裁剪通过编译时配置宏如EMBEDDED_CLI_DISABLE_HISTORY、EMBEDDED_CLI_DISABLE_AUTOCOMPLETE可彻底移除未使用功能最终 ROM 占用可压缩至 2KB 以下RAM 占用含缓冲区可低至 256 字节。这使其区别于其他嵌入式 CLI 方案如cli、microrl它不追求语法糖的丰富性如管道、重定向、变量替换而聚焦于工程师最常使用的子集——命令触发、参数传递、状态查询、历史回溯与基础编辑——并确保每一行代码在 Cortex-M0 上都能确定性执行。2. 核心架构与数据流embedded-cli的运行模型是一个典型的双阶段事件驱动状态机严格分离字符接收与命令处理以适配嵌入式中断上下文与主循环上下文的隔离需求。2.1 状态机分层整个 CLI 生命周期由两个核心函数协同驱动// 阶段一字符接收可安全在 ISR 中调用 void embeddedCliReceiveChar(EmbeddedCli *cli, char c); // 阶段二命令处理必须在主循环或任务上下文中调用 void embeddedCliProcess(EmbeddedCli *cli);embeddedCliReceiveChar是纯粹的“数据泵”。它将接收到的每个字节c按序存入 CLI 内部的环形输入缓冲区inputBuffer。此函数内部仅执行指针移动、边界检查与简单转义处理如\r→\n规范化无任何字符串解析、无函数调用、无条件分支跳转。因此它可在 UART 接收中断服务程序ISR中直接调用满足硬实时要求。embeddedCliProcess是“大脑”。它在主循环while(1)或 FreeRTOS 任务中周期性调用推荐 10–100Hz。该函数负责行缓冲组装扫描inputBuffer识别行结束符\r、\n或\r\n将完整命令行提取到currentLine缓冲区编辑操作执行响应退格\b、Tab 补全、上下箭头ESC[A / ESC[B等控制序列更新currentLine内容与光标位置历史管理维护一个固定大小的环形历史缓冲区historyBuffer支持up/down导航命令解析与分发对确认的命令行进行空格/引号分词匹配已注册的命令绑定并调用对应的回调函数。这种分离设计规避了在 ISR 中执行复杂字符串操作的风险如栈溢出、不可重入函数调用同时保证了用户交互的响应性——按键即时回显命令提交后立即处理。2.2 内存布局与分配策略embedded-cli提供两种内存管理模式由EmbeddedCliConfig结构体中的cliBuffer字段决定分配模式配置方式RAM 开销适用场景动态分配config-cliBuffer NULL运行时malloc()分配大小由embeddedCliRequiredSize()计算快速原型、RAM 充裕的 Cortex-M4/M7静态分配config-cliBuffer myStaticBuffer编译时确定无堆碎片风险安全关键系统、小内存 MCUATmega328P静态分配是嵌入式首选。所需缓冲区大小字节由embeddedCliRequiredSize(const EmbeddedCliConfig *config)计算其值取决于maxBindingCount最大命令绑定数影响哈希表/线性搜索空间maxHistoryCount历史记录条数每条历史最大长度由maxLineLength决定maxLineLength单行命令最大长度直接影响currentLine和inputBuffer大小maxTokenCount分词后最大参数个数影响tokenizedArgs数组例如针对 Arduino Nano2KB RAM典型配置为#define CLI_BUFFER_SIZE 512 CLI_UINT cliBuffer[BYTES_TO_CLI_UINTS(CLI_BUFFER_SIZE)]; // AVR: CLI_UINT uint16_t EmbeddedCliConfig *config embeddedCliDefaultConfig(); config-maxBindingCount 8; // 支持 8 条命令 config-maxHistoryCount 5; // 保留 5 条历史 config-maxLineLength 64; // 单行最长 64 字符 config-maxTokenCount 8; // 最多 8 个参数 config-cliBuffer cliBuffer; config-cliBufferSize CLI_BUFFER_SIZE;CLI_UINT类型根据平台自动选择AVR→uint16_tARM→uint32_tx86_64→uint64_t确保缓冲区内存对齐避免因未对齐访问导致的 ARM Cortex-M 硬故障。3. API 详解与工程实践3.1 初始化与配置初始化是使用embedded-cli的第一步其关键在于正确配置EmbeddedCliConfig并创建实例。以下是符合工业级实践的初始化模板以 STM32 HAL FreeRTOS 为例#include embedded_cli.h #include stm32f4xx_hal.h #include FreeRTOS.h #include task.h // 静态缓冲区放置于 .bss 段确保零初始化 #define CLI_BUFFER_SIZE 1024 CLI_UINT g_cliBuffer[BYTES_TO_CLI_UINTS(CLI_BUFFER_SIZE)]; // CLI 实例指针全局便于 ISR 访问 static EmbeddedCli *g_cli NULL; // UART 发送回调HAL_UART_Transmit 不可重入需用 DMA 或轮询 static void cliWriteChar(EmbeddedCli *cli, char c) { HAL_UART_Transmit(huart2, (uint8_t*)c, 1, HAL_MAX_DELAY); } // UART 接收完成回调HAL 库风格 void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if (huart huart2) { uint8_t rx_byte; HAL_UART_Receive(huart2, rx_byte, 1, HAL_MAX_DELAY); if (g_cli ! NULL) { embeddedCliReceiveChar(g_cli, (char)rx_byte); // 安全ISR 中仅此调用 } HAL_UART_Receive_IT(huart2, rx_byte, 1); // 重新启动中断 } } // CLI 初始化函数在 main() 或任务中调用 void cliInit(void) { EmbeddedCliConfig *config embeddedCliDefaultConfig(); config-maxBindingCount 12; config-maxHistoryCount 10; config-maxLineLength 128; config-maxTokenCount 10; config-cliBuffer g_cliBuffer; config-cliBufferSize CLI_BUFFER_SIZE; g_cli embeddedCliNew(config); if (g_cli NULL) { Error_Handler(); // 缓冲区不足需增大 CLI_BUFFER_SIZE } g_cli-writeChar cliWriteChar; // 绑定输出函数 // 注册命令见 3.2 节 embeddedCliAddBinding(g_cli, (EmbeddedCliBinding){ .name led, .help Toggle LED (on/off), .tokenizeArgs true, .context NULL, .callback cmdLed }); }关键工程要点g_cli声明为static全局指针确保 ISRHAL_UART_RxCpltCallback能安全访问 CLI 实例cliWriteChar使用HAL_UART_Transmit轮询发送避免在 ISR 中调用可能阻塞的 DMA 启动函数若需更高性能可改用HAL_UART_Transmit_DMA并在HAL_UART_TxCpltCallback中唤醒 CLI 处理任务embeddedCliNew()返回NULL表示静态缓冲区不足必须通过embeddedCliRequiredSize()重新计算并增大CLI_BUFFER_SIZE。3.2 命令绑定与参数处理命令绑定是 CLI 的灵魂。embeddedCliAddBinding接受一个EmbeddedCliBinding结构体其字段含义如下表字段类型必填说明nameconst char*✓命令名称仅允许字母、数字、下划线、连字符a-z, A-Z, 0-9, _, -禁止空格与特殊字符helpconst char*✗帮助字符串用于help命令输出NULL则不显示tokenizeArgsbool✓true启用智能分词支持引号、转义falseargs为原始字符串contextvoid*✗用户自定义上下文指针透传给回调函数callbackEmbeddedCliCallback✓命令执行回调函数指针3.2.1 分词模式tokenizeArgs true当tokenizeArgs为true时CLI 将对命令行进行 RFC 2822 风格分词正确处理空格、引号与转义。例如输入led on red green blue\→ 分词为[led, on, red green, blue]输入adc read 0x1234→ 分词为[adc, read, 0x1234]回调函数签名void cmdLed(EmbeddedCli *cli, char *args, void *context) { uint8_t tokenCount embeddedCliGetTokenCount(args); if (tokenCount 2) { embeddedCliWriteString(cli, Usage: led on|off\r\n); return; } const char *state embeddedCliGetToken(args, 1); // args[1], 第一个参数 if (strcmp(state, on) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET); embeddedCliWriteString(cli, LED ON\r\n); } else if (strcmp(state, off) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); embeddedCliWriteString(cli, LED OFF\r\n); } else { embeddedCliWriteString(cli, Unknown state\r\n); } }分词 API 详解embeddedCliTokenizeArgs(char *line)原地修改line插入\0分隔符返回分词后token数组首地址即line自身。调用后line不再是有效 C 字符串embeddedCliGetTokenCount(const char *tokenizedStr)返回分词总数token[0]到token[n-1]。embeddedCliGetToken(const char *tokenizedStr, uint8_t pos)获取第pos个参数pos从1开始tokenizedStr是embeddedCliTokenizeArgs返回值。embeddedCliFindToken(const char *tokenizedStr, const char *target)查找target在分词数组中的位置1-based未找到返回0。3.2.2 原始模式tokenizeArgs false当tokenizeArgs为false时args是指向原始命令行不含命令名的char*开发者需自行解析。适用于简单场景或需自定义语法void cmdVersion(EmbeddedCli *cli, char *args, void *context) { // args 是 1.2.3 或 直接使用 embeddedCliWriteString(cli, Firmware v); embeddedCliWriteString(cli, args[0] ? args : 1.0.0); embeddedCliWriteString(cli, \r\n); }3.3 运行时交互协议embedded-cli定义了一套精简但完备的终端控制协议确保与标准串口终端PuTTY、Tera Term、screen无缝协作控制序列功能说明\r或\n提交命令触发embeddedCliProcess中的命令解析\b或^H退格删除光标前一个字符\tTab 补全自动补全当前输入的命令名基于注册的nameESC[A上箭头加载上一条历史命令ESC[B下箭头加载下一条历史命令ESC[C右箭头光标右移CLI 未实现由终端处理ESC[D左箭头光标左移CLI 未实现由终端处理工程提示某些 USB-UART 转换器如 CH340默认不发送ESC序列。若上下箭头无效请在终端软件中启用“ANSI 转义序列”或切换至xterm模式。4. 高级配置与裁剪embedded-cli通过预处理器宏提供细粒度功能开关可在编译时彻底移除未使用代码减小固件体积。这些宏需在包含embedded_cli.h之前定义宏定义默认值效果典型适用场景EMBEDDED_CLI_DISABLE_HISTORY未定义移除历史缓冲区、up/down箭头支持RAM 512B 的 MCUEMBEDDED_CLI_DISABLE_AUTOCOMPLETE未定义移除 Tab 补全、命令名哈希表仅需基本命令触发EMBEDDED_CLI_DISABLE_HELP未定义移除help命令及help字段存储极简部署无调试需求EMBEDDED_CLI_DISABLE_ECHO未定义关闭本地回显需终端自行处理安全敏感场景密码输入EMBEDDED_CLI_USE_SMALL_HASH未定义使用 8-bit 哈希冲突概率略升对哈希性能无要求的小系统裁剪示例Arduino Nano#define EMBEDDED_CLI_DISABLE_HISTORY #define EMBEDDED_CLI_DISABLE_AUTOCOMPLETE #define EMBEDDED_CLI_DISABLE_HELP #include embedded_cli.h // ... 初始化与绑定代码启用EMBEDDED_CLI_DISABLE_HISTORY后maxHistoryCount配置项失效embeddedCliRequiredSize()计算的缓冲区大小将显著减少。5. 与主流嵌入式生态集成5.1 FreeRTOS 集成在 FreeRTOS 环境中embedded-cli可作为独立任务运行实现非阻塞交互TaskHandle_t cliTaskHandle; void cliTask(void *pvParameters) { for(;;) { if (g_cli ! NULL) { embeddedCliProcess(g_cli); // 主处理循环 } vTaskDelay(pdMS_TO_TICKS(10)); // 10ms 周期 } } // 在 main() 中创建任务 xTaskCreate(cliTask, CLI, configMINIMAL_STACK_SIZE * 2, NULL, tskIDLE_PRIORITY 1, cliTaskHandle);优势CLI 处理与主应用逻辑完全解耦避免while(1)循环中embeddedCliProcess()调用阻塞其他任务。5.2 Zephyr RTOS 集成Zephyr 提供shell子系统但embedded-cli可作为轻量替代方案。关键在于适配 Zephyr 的 UART API#include zephyr/drivers/uart.h #include zephyr/kernel.h const struct device *uart_dev DEVICE_DT_GET(DT_CHOSEN(zephyr_shell_uart)); static EmbeddedCli *z_cli; void zephyrUartCallback(const struct device *dev, void *user_data) { uint8_t c; while (uart_poll_in(dev, c) 0) { embeddedCliReceiveChar(z_cli, (char)c); } } void zephyrCliInit(void) { uart_callback_set(uart_dev, zephyrUartCallback, NULL); // ... 配置与初始化 z_cli }5.3 与 CMSIS-RTOS v2 (Keil RTX5) 集成利用 RTX5 的osTimer实现周期性处理osTimerId_t cliTimerId; void cliTimerCallback(void *arg) { if (g_cli ! NULL) { embeddedCliProcess(g_cli); } } // 创建定时器 cliTimerId osTimerNew(cliTimerCallback, osTimerPeriodic, NULL, NULL); osTimerStart(cliTimerId, 10); // 10ms 周期6. 调试技巧与常见问题6.1 调试技巧缓冲区溢出检测在embeddedCliReceiveChar调用前后添加断点监控inputBuffer的head/tail指针确保未发生覆盖命令未响应排查使用逻辑分析仪抓取 UART 波形确认\r/\n是否被正确发送检查writeChar回调是否真正执行了发送分词失败定位在cmdXXX回调中打印原始args字符串embeddedCliWriteString(cli, args);确认输入是否被正确截断。6.2 典型问题与解决方案问题现象根本原因解决方案输入字符无回显writeChar未正确绑定或 UART 发送失败检查g_cli-writeChar是否为NULL用示波器验证 UART TX 引脚电平Tab 补全无反应EMBEDDED_CLI_DISABLE_AUTOCOMPLETE已定义或命令名含非法字符检查宏定义确保name仅含[a-zA-Z0-9_-]上下箭头显示^[[A终端未启用 ANSI 模式或 USB-UART 芯片不支持 ESC 序列更换终端软件如 Tera Term或在 MCU 端增加 ESC 序列映射逻辑embeddedCliNew()返回NULL静态缓冲区CLI_BUFFER_SIZE不足调用embeddedCliRequiredSize(config)获取精确大小增大缓冲区7. 性能与资源占用实测在 STM32F407VG168MHz平台上使用arm-none-eabi-gcc -O2编译embedded-cli的典型资源占用如下配置ROM (Flash)RAM (Stack Heap)处理延迟128B 命令默认全功能~3.2 KB~1.1 KB含 1KB 缓冲区 50 μs裁剪版禁用 History/AutoComplete/Help~1.8 KB~0.4 KB 20 μs所有测量均基于embeddedCliProcess()单次调用的最坏情况长命令、多参数、历史满载。其确定性性能使其适用于对响应时间有硬性要求的工业控制场景。embedded-cli的价值不在于功能的炫目而在于它将嵌入式 CLI 这一基础能力提炼为一套经过千锤百炼、可预测、可审计、可嵌入任何裸机或 RTOS 环境的工业级构件。当你的下一个项目需要在 32KB Flash 的 MCU 上用不到 2KB 代码实现一个稳定可靠的调试接口时它已是经过验证的最优解。
嵌入式单头文件CLI库：资源受限MCU的轻量命令行接口
1. 项目概述embedded-cli是一款专为资源受限嵌入式系统设计的单头文件single-header命令行接口CLI库。其核心目标是在 STM32、ESP32、ArduinoATmega328P、nRF52 等典型 MCU 平台上以极低的内存开销提供健壮、可配置、生产就绪的交互式调试与控制能力。它并非对 POSIX shell 的简单移植而是从嵌入式底层约束出发重新定义 CLI 的抽象模型无动态内存分配依赖可选、无标准 C 库依赖stdio.h、stdlib.h非必需、无线程/RTOS 依赖但天然兼容、零外部构建依赖。该库的“单头文件”特性意味着其全部实现包括数据结构定义、状态机逻辑、命令解析器、历史缓冲区管理、自动补全引擎均封装于一个.h文件中。开发者无需构建过程、无需链接额外库、无需管理头文件依赖树——仅需将embedded_cli.h复制到项目中按约定宏展开即可获得完整功能。这种设计极大简化了在裸机Bare-Metal或轻量级 RTOS如 FreeRTOS、Zephyr环境下的集成流程尤其适合需要快速迭代硬件固件调试接口的开发场景。embedded-cli的设计理念可概括为“显式控制、最小假设、最大可裁剪”显式控制所有内存分配策略动态/静态、输入输出通道UART/SPI/I2C/USB-CDC、命令绑定时机、处理周期均由用户代码显式指定库本身不隐式调用malloc、不轮询外设、不启动后台任务。最小假设仅假设存在一个字节流byte-stream收发能力如HAL_UART_Receive_IT 回调或Serial.read()不假设存在printf、getchar或文件系统。最大可裁剪通过编译时配置宏如EMBEDDED_CLI_DISABLE_HISTORY、EMBEDDED_CLI_DISABLE_AUTOCOMPLETE可彻底移除未使用功能最终 ROM 占用可压缩至 2KB 以下RAM 占用含缓冲区可低至 256 字节。这使其区别于其他嵌入式 CLI 方案如cli、microrl它不追求语法糖的丰富性如管道、重定向、变量替换而聚焦于工程师最常使用的子集——命令触发、参数传递、状态查询、历史回溯与基础编辑——并确保每一行代码在 Cortex-M0 上都能确定性执行。2. 核心架构与数据流embedded-cli的运行模型是一个典型的双阶段事件驱动状态机严格分离字符接收与命令处理以适配嵌入式中断上下文与主循环上下文的隔离需求。2.1 状态机分层整个 CLI 生命周期由两个核心函数协同驱动// 阶段一字符接收可安全在 ISR 中调用 void embeddedCliReceiveChar(EmbeddedCli *cli, char c); // 阶段二命令处理必须在主循环或任务上下文中调用 void embeddedCliProcess(EmbeddedCli *cli);embeddedCliReceiveChar是纯粹的“数据泵”。它将接收到的每个字节c按序存入 CLI 内部的环形输入缓冲区inputBuffer。此函数内部仅执行指针移动、边界检查与简单转义处理如\r→\n规范化无任何字符串解析、无函数调用、无条件分支跳转。因此它可在 UART 接收中断服务程序ISR中直接调用满足硬实时要求。embeddedCliProcess是“大脑”。它在主循环while(1)或 FreeRTOS 任务中周期性调用推荐 10–100Hz。该函数负责行缓冲组装扫描inputBuffer识别行结束符\r、\n或\r\n将完整命令行提取到currentLine缓冲区编辑操作执行响应退格\b、Tab 补全、上下箭头ESC[A / ESC[B等控制序列更新currentLine内容与光标位置历史管理维护一个固定大小的环形历史缓冲区historyBuffer支持up/down导航命令解析与分发对确认的命令行进行空格/引号分词匹配已注册的命令绑定并调用对应的回调函数。这种分离设计规避了在 ISR 中执行复杂字符串操作的风险如栈溢出、不可重入函数调用同时保证了用户交互的响应性——按键即时回显命令提交后立即处理。2.2 内存布局与分配策略embedded-cli提供两种内存管理模式由EmbeddedCliConfig结构体中的cliBuffer字段决定分配模式配置方式RAM 开销适用场景动态分配config-cliBuffer NULL运行时malloc()分配大小由embeddedCliRequiredSize()计算快速原型、RAM 充裕的 Cortex-M4/M7静态分配config-cliBuffer myStaticBuffer编译时确定无堆碎片风险安全关键系统、小内存 MCUATmega328P静态分配是嵌入式首选。所需缓冲区大小字节由embeddedCliRequiredSize(const EmbeddedCliConfig *config)计算其值取决于maxBindingCount最大命令绑定数影响哈希表/线性搜索空间maxHistoryCount历史记录条数每条历史最大长度由maxLineLength决定maxLineLength单行命令最大长度直接影响currentLine和inputBuffer大小maxTokenCount分词后最大参数个数影响tokenizedArgs数组例如针对 Arduino Nano2KB RAM典型配置为#define CLI_BUFFER_SIZE 512 CLI_UINT cliBuffer[BYTES_TO_CLI_UINTS(CLI_BUFFER_SIZE)]; // AVR: CLI_UINT uint16_t EmbeddedCliConfig *config embeddedCliDefaultConfig(); config-maxBindingCount 8; // 支持 8 条命令 config-maxHistoryCount 5; // 保留 5 条历史 config-maxLineLength 64; // 单行最长 64 字符 config-maxTokenCount 8; // 最多 8 个参数 config-cliBuffer cliBuffer; config-cliBufferSize CLI_BUFFER_SIZE;CLI_UINT类型根据平台自动选择AVR→uint16_tARM→uint32_tx86_64→uint64_t确保缓冲区内存对齐避免因未对齐访问导致的 ARM Cortex-M 硬故障。3. API 详解与工程实践3.1 初始化与配置初始化是使用embedded-cli的第一步其关键在于正确配置EmbeddedCliConfig并创建实例。以下是符合工业级实践的初始化模板以 STM32 HAL FreeRTOS 为例#include embedded_cli.h #include stm32f4xx_hal.h #include FreeRTOS.h #include task.h // 静态缓冲区放置于 .bss 段确保零初始化 #define CLI_BUFFER_SIZE 1024 CLI_UINT g_cliBuffer[BYTES_TO_CLI_UINTS(CLI_BUFFER_SIZE)]; // CLI 实例指针全局便于 ISR 访问 static EmbeddedCli *g_cli NULL; // UART 发送回调HAL_UART_Transmit 不可重入需用 DMA 或轮询 static void cliWriteChar(EmbeddedCli *cli, char c) { HAL_UART_Transmit(huart2, (uint8_t*)c, 1, HAL_MAX_DELAY); } // UART 接收完成回调HAL 库风格 void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if (huart huart2) { uint8_t rx_byte; HAL_UART_Receive(huart2, rx_byte, 1, HAL_MAX_DELAY); if (g_cli ! NULL) { embeddedCliReceiveChar(g_cli, (char)rx_byte); // 安全ISR 中仅此调用 } HAL_UART_Receive_IT(huart2, rx_byte, 1); // 重新启动中断 } } // CLI 初始化函数在 main() 或任务中调用 void cliInit(void) { EmbeddedCliConfig *config embeddedCliDefaultConfig(); config-maxBindingCount 12; config-maxHistoryCount 10; config-maxLineLength 128; config-maxTokenCount 10; config-cliBuffer g_cliBuffer; config-cliBufferSize CLI_BUFFER_SIZE; g_cli embeddedCliNew(config); if (g_cli NULL) { Error_Handler(); // 缓冲区不足需增大 CLI_BUFFER_SIZE } g_cli-writeChar cliWriteChar; // 绑定输出函数 // 注册命令见 3.2 节 embeddedCliAddBinding(g_cli, (EmbeddedCliBinding){ .name led, .help Toggle LED (on/off), .tokenizeArgs true, .context NULL, .callback cmdLed }); }关键工程要点g_cli声明为static全局指针确保 ISRHAL_UART_RxCpltCallback能安全访问 CLI 实例cliWriteChar使用HAL_UART_Transmit轮询发送避免在 ISR 中调用可能阻塞的 DMA 启动函数若需更高性能可改用HAL_UART_Transmit_DMA并在HAL_UART_TxCpltCallback中唤醒 CLI 处理任务embeddedCliNew()返回NULL表示静态缓冲区不足必须通过embeddedCliRequiredSize()重新计算并增大CLI_BUFFER_SIZE。3.2 命令绑定与参数处理命令绑定是 CLI 的灵魂。embeddedCliAddBinding接受一个EmbeddedCliBinding结构体其字段含义如下表字段类型必填说明nameconst char*✓命令名称仅允许字母、数字、下划线、连字符a-z, A-Z, 0-9, _, -禁止空格与特殊字符helpconst char*✗帮助字符串用于help命令输出NULL则不显示tokenizeArgsbool✓true启用智能分词支持引号、转义falseargs为原始字符串contextvoid*✗用户自定义上下文指针透传给回调函数callbackEmbeddedCliCallback✓命令执行回调函数指针3.2.1 分词模式tokenizeArgs true当tokenizeArgs为true时CLI 将对命令行进行 RFC 2822 风格分词正确处理空格、引号与转义。例如输入led on red green blue\→ 分词为[led, on, red green, blue]输入adc read 0x1234→ 分词为[adc, read, 0x1234]回调函数签名void cmdLed(EmbeddedCli *cli, char *args, void *context) { uint8_t tokenCount embeddedCliGetTokenCount(args); if (tokenCount 2) { embeddedCliWriteString(cli, Usage: led on|off\r\n); return; } const char *state embeddedCliGetToken(args, 1); // args[1], 第一个参数 if (strcmp(state, on) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET); embeddedCliWriteString(cli, LED ON\r\n); } else if (strcmp(state, off) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); embeddedCliWriteString(cli, LED OFF\r\n); } else { embeddedCliWriteString(cli, Unknown state\r\n); } }分词 API 详解embeddedCliTokenizeArgs(char *line)原地修改line插入\0分隔符返回分词后token数组首地址即line自身。调用后line不再是有效 C 字符串embeddedCliGetTokenCount(const char *tokenizedStr)返回分词总数token[0]到token[n-1]。embeddedCliGetToken(const char *tokenizedStr, uint8_t pos)获取第pos个参数pos从1开始tokenizedStr是embeddedCliTokenizeArgs返回值。embeddedCliFindToken(const char *tokenizedStr, const char *target)查找target在分词数组中的位置1-based未找到返回0。3.2.2 原始模式tokenizeArgs false当tokenizeArgs为false时args是指向原始命令行不含命令名的char*开发者需自行解析。适用于简单场景或需自定义语法void cmdVersion(EmbeddedCli *cli, char *args, void *context) { // args 是 1.2.3 或 直接使用 embeddedCliWriteString(cli, Firmware v); embeddedCliWriteString(cli, args[0] ? args : 1.0.0); embeddedCliWriteString(cli, \r\n); }3.3 运行时交互协议embedded-cli定义了一套精简但完备的终端控制协议确保与标准串口终端PuTTY、Tera Term、screen无缝协作控制序列功能说明\r或\n提交命令触发embeddedCliProcess中的命令解析\b或^H退格删除光标前一个字符\tTab 补全自动补全当前输入的命令名基于注册的nameESC[A上箭头加载上一条历史命令ESC[B下箭头加载下一条历史命令ESC[C右箭头光标右移CLI 未实现由终端处理ESC[D左箭头光标左移CLI 未实现由终端处理工程提示某些 USB-UART 转换器如 CH340默认不发送ESC序列。若上下箭头无效请在终端软件中启用“ANSI 转义序列”或切换至xterm模式。4. 高级配置与裁剪embedded-cli通过预处理器宏提供细粒度功能开关可在编译时彻底移除未使用代码减小固件体积。这些宏需在包含embedded_cli.h之前定义宏定义默认值效果典型适用场景EMBEDDED_CLI_DISABLE_HISTORY未定义移除历史缓冲区、up/down箭头支持RAM 512B 的 MCUEMBEDDED_CLI_DISABLE_AUTOCOMPLETE未定义移除 Tab 补全、命令名哈希表仅需基本命令触发EMBEDDED_CLI_DISABLE_HELP未定义移除help命令及help字段存储极简部署无调试需求EMBEDDED_CLI_DISABLE_ECHO未定义关闭本地回显需终端自行处理安全敏感场景密码输入EMBEDDED_CLI_USE_SMALL_HASH未定义使用 8-bit 哈希冲突概率略升对哈希性能无要求的小系统裁剪示例Arduino Nano#define EMBEDDED_CLI_DISABLE_HISTORY #define EMBEDDED_CLI_DISABLE_AUTOCOMPLETE #define EMBEDDED_CLI_DISABLE_HELP #include embedded_cli.h // ... 初始化与绑定代码启用EMBEDDED_CLI_DISABLE_HISTORY后maxHistoryCount配置项失效embeddedCliRequiredSize()计算的缓冲区大小将显著减少。5. 与主流嵌入式生态集成5.1 FreeRTOS 集成在 FreeRTOS 环境中embedded-cli可作为独立任务运行实现非阻塞交互TaskHandle_t cliTaskHandle; void cliTask(void *pvParameters) { for(;;) { if (g_cli ! NULL) { embeddedCliProcess(g_cli); // 主处理循环 } vTaskDelay(pdMS_TO_TICKS(10)); // 10ms 周期 } } // 在 main() 中创建任务 xTaskCreate(cliTask, CLI, configMINIMAL_STACK_SIZE * 2, NULL, tskIDLE_PRIORITY 1, cliTaskHandle);优势CLI 处理与主应用逻辑完全解耦避免while(1)循环中embeddedCliProcess()调用阻塞其他任务。5.2 Zephyr RTOS 集成Zephyr 提供shell子系统但embedded-cli可作为轻量替代方案。关键在于适配 Zephyr 的 UART API#include zephyr/drivers/uart.h #include zephyr/kernel.h const struct device *uart_dev DEVICE_DT_GET(DT_CHOSEN(zephyr_shell_uart)); static EmbeddedCli *z_cli; void zephyrUartCallback(const struct device *dev, void *user_data) { uint8_t c; while (uart_poll_in(dev, c) 0) { embeddedCliReceiveChar(z_cli, (char)c); } } void zephyrCliInit(void) { uart_callback_set(uart_dev, zephyrUartCallback, NULL); // ... 配置与初始化 z_cli }5.3 与 CMSIS-RTOS v2 (Keil RTX5) 集成利用 RTX5 的osTimer实现周期性处理osTimerId_t cliTimerId; void cliTimerCallback(void *arg) { if (g_cli ! NULL) { embeddedCliProcess(g_cli); } } // 创建定时器 cliTimerId osTimerNew(cliTimerCallback, osTimerPeriodic, NULL, NULL); osTimerStart(cliTimerId, 10); // 10ms 周期6. 调试技巧与常见问题6.1 调试技巧缓冲区溢出检测在embeddedCliReceiveChar调用前后添加断点监控inputBuffer的head/tail指针确保未发生覆盖命令未响应排查使用逻辑分析仪抓取 UART 波形确认\r/\n是否被正确发送检查writeChar回调是否真正执行了发送分词失败定位在cmdXXX回调中打印原始args字符串embeddedCliWriteString(cli, args);确认输入是否被正确截断。6.2 典型问题与解决方案问题现象根本原因解决方案输入字符无回显writeChar未正确绑定或 UART 发送失败检查g_cli-writeChar是否为NULL用示波器验证 UART TX 引脚电平Tab 补全无反应EMBEDDED_CLI_DISABLE_AUTOCOMPLETE已定义或命令名含非法字符检查宏定义确保name仅含[a-zA-Z0-9_-]上下箭头显示^[[A终端未启用 ANSI 模式或 USB-UART 芯片不支持 ESC 序列更换终端软件如 Tera Term或在 MCU 端增加 ESC 序列映射逻辑embeddedCliNew()返回NULL静态缓冲区CLI_BUFFER_SIZE不足调用embeddedCliRequiredSize(config)获取精确大小增大缓冲区7. 性能与资源占用实测在 STM32F407VG168MHz平台上使用arm-none-eabi-gcc -O2编译embedded-cli的典型资源占用如下配置ROM (Flash)RAM (Stack Heap)处理延迟128B 命令默认全功能~3.2 KB~1.1 KB含 1KB 缓冲区 50 μs裁剪版禁用 History/AutoComplete/Help~1.8 KB~0.4 KB 20 μs所有测量均基于embeddedCliProcess()单次调用的最坏情况长命令、多参数、历史满载。其确定性性能使其适用于对响应时间有硬性要求的工业控制场景。embedded-cli的价值不在于功能的炫目而在于它将嵌入式 CLI 这一基础能力提炼为一套经过千锤百炼、可预测、可审计、可嵌入任何裸机或 RTOS 环境的工业级构件。当你的下一个项目需要在 32KB Flash 的 MCU 上用不到 2KB 代码实现一个稳定可靠的调试接口时它已是经过验证的最优解。
