1. 为什么 MCU 项目需要一个趁手的 shell第一次把 LetterShell 拉进工程时我的诉求很朴素板子跑起来之后能有个地方敲命令、看变量、改参数而不是每次改一个阈值就重新编译烧录。嵌入式开发里这种场景太常见了——调 PID 要看实时误差测传感器要临时读寄存器排查通信问题要手动发一帧数据。如果没有命令行交互这些动作全都要靠「改代码 重新下载 复位」三件套效率低得让人抓狂。LetterShell 就是解决这个问题的。它是一个用纯 C 写的嵌入式 shell 组件不依赖操作系统资源占用小可以跑在裸机、RTOS 甚至 Linux 上。你给它一个字符输入接口和一个字符输出接口它就能把命令行交互跑起来。支持命令注册、参数解析、历史记录、Tab 补全、快捷键还能挂载到串口、USB CDC、RTT 等各种通道上。它适合谁适合所有需要在 MCU 上做调试交互的开发者。不管你是用 STM32、GD32、ESP32 还是国产 RISC-V 芯片只要能把串口收发打通就能把 LetterShell 接进去。这篇内容聚焦初次上手给出可复制的配置骨架讲清楚串口对接和命令表的关键项然后跑通第一条 shell 命令确认整条交互链路是通的。我试过在几个不同平台上接 LetterShell踩过的坑主要集中在串口中断接收和 shell 任务调度这两块。下面按「先跑通、再优化」的思路来写你可以直接跟着操作。2. 把 LetterShell 源码放进工程的前置准备2.1 获取源码与目录结构LetterShell 的源码托管在 GitHub 上直接 clone 或者下载 zip 都行。核心文件不多初次上手只需要关注这几个letter-shell/ ├── src/ │ ├── shell.c # shell 核心逻辑 │ ├── shell.h # 对外接口 │ └── shell_port.c # 移植层需要你自己实现 ├── ext/ # 扩展功能可选 │ ├── shell_fs.c # 文件系统命令 │ ├── shell_log.c # 日志命令 │ └── ... └── examples/ # 各平台示例初次接入把src/shell.c、src/shell.h和src/shell_port.c三个文件加入工程即可。shell_port.c是移植层里面有几个函数需要你根据实际硬件去填。2.2 配置项决定资源占用LetterShell 的行为由shell.h里的一组宏控制。初次上手建议先关注这几个宏作用建议初值SHELL_USING_CMD_EXPORT是否用段属性自动注册命令1方便SHELL_MAX_NUMBER最大命令数20SHELL_BUFFER_SIZE命令行缓冲区大小128SHELL_HISTORY_MAX_NUMBER历史命令条数5SHELL_USING_TAB是否启用 Tab 补全1SHELL_USING_FUNC_SIGNATURE是否显示函数签名0省空间这些宏在shell_cfg.h或直接在shell.h里改。初次跑通用默认值就行等确认链路正常再按需裁剪。注意SHELL_USING_CMD_EXPORT依赖链接器把命令结构体放到特定段里。如果你用的是 IAR 或 Keil需要在链接脚本里保留这个段否则命令注册会失败。GCC 下一般不用额外处理。2.3 串口收发接口是移植的核心shell_port.c里需要你实现两个方向的接口一个是 shell 往外写字符一个是 shell 从外部读字符。写字符通常是阻塞发送读字符则有两种模式——查询和中断。初次上手推荐用中断接收。串口每收到一个字节就丢给 shellshell 内部自己组包。这样不会丢数据也不占用主循环。/* shell_port.c 中的写接口示例 */ void userShellWrite(char *data, unsigned short len) { /* 假设你有一个串口发送函数 uart_send_bytes */ uart_send_bytes(UART_DEBUG, (uint8_t *)data, len); }读接口在中断里调用/* 串口中断服务函数里 */ void UART_DEBUG_IRQHandler(void) { if (uart_rx_ready(UART_DEBUG)) { char ch uart_read_byte(UART_DEBUG); shellHandler(shell, ch); /* 把字节喂给 shell */ } }shellHandler是 shell 的核心入口每收到一个字符就调一次。它内部会处理回车、退格、Tab 等控制字符组好一条完整命令后去命令表里查找并执行。3. 可复制的配置骨架与命令表写法3.1 shell 对象定义与初始化在shell_port.c里定义一个全局 shell 对象然后在初始化函数里把它挂起来#include shell.h Shell shell; /* 全局 shell 对象 */ char shellBuffer[512]; /* 命令行缓冲区 */ /* 写接口shell 通过它输出 */ void userShellWrite(char *data, unsigned short len) { uart_send_bytes(UART_DEBUG, (uint8_t *)data, len); } /* 初始化函数在 main 里调用 */ void userShellInit(void) { shell.write userShellWrite; /* 绑定写接口 */ shellInit(shell, shellBuffer, sizeof(shellBuffer)); }shellInit会把 shell 对象和缓冲区关联起来并初始化内部状态。缓冲区大小决定了单条命令的最大长度512 字节对大多数场景够用了。3.2 命令注册的两种方式第一种是手动注册适合命令少、想精确控制顺序的场景void shellCmdLedOn(void) { led_on(); shellPrint(shell, LED ON\r\n); } void shellCmdLedOff(void) { led_off(); shellPrint(shell, LED OFF\r\n); } /* 在初始化里注册 */ shellSetCmd(shell, ledon, shellCmdLedOn, turn on led); shellSetCmd(shell, ledoff, shellCmdLedOff, turn off led);第二种是自动注册用宏把命令结构体放到特定段里链接时自动收集#include shell.h void shellCmdLedOn(void) { led_on(); shellPrint(shell, LED ON\r\n); } SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), ledon, shellCmdLedOn, turn on led);SHELL_EXPORT_CMD的第一个参数是权限和类型第二个是命令名第三个是函数指针第四个是帮助信息。自动注册的好处是命令和实现放在一起增删命令不用改初始化代码。3.3 带参数的命令怎么写实际调试中命令往往需要带参数。LetterShell 支持把参数解析成整数、字符串等类型void shellCmdSetPid(int kp, int ki, int kd) { pid_set_params(kp / 100.0f, ki / 100.0f, kd / 100.0f); shellPrint(shell, PID set: kp%d ki%d kd%d\r\n, kp, ki, kd); } SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), setpid, shellCmdSetPid, set pid params);在终端里输入setpid 100 20 5shell 会自动把三个参数解析成整数传给函数。参数类型由函数签名决定shell 内部用shellExtractParam做转换。3.4 主循环里要做什么如果用的是中断接收模式主循环里其实不需要为 shell 做太多事。但如果你用的是查询模式或者需要在 shell 之外处理其他任务可以这样组织int main(void) { board_init(); uart_init(UART_DEBUG, 115200); userShellInit(); while (1) { /* 其他任务 */ task_sensor_poll(); task_control_loop(); /* 如果串口是查询模式在这里喂数据 */ /* if (uart_rx_ready(UART_DEBUG)) { */ /* shellHandler(shell, uart_read_byte(UART_DEBUG)); */ /* } */ } }中断模式下shellHandler在中断里被调用主循环不用管。但要注意如果 shell 命令执行时间较长不要在中断里直接执行命令逻辑否则会阻塞其他中断。LetterShell 默认是在shellHandler里同步执行命令的所以命令函数要尽量短小或者把耗时操作丢到主循环里做。4. 验证请求与成功结果确认4.1 最小验证动作烧录之后打开串口终端波特率和你初始化的一致比如 1152008N1。复位板子你应该能看到 shell 的提示符LetterShell v3.x.x shell在提示符后面输入help回车如果命令表注册成功会列出所有可用命令shell help Command list: ledon - turn on led ledoff - turn off led setpid - set pid params help - show command list再输入ledon回车如果 LED 亮了并且终端打印LED ON说明整条链路是通的串口接收 → shell 解析 → 命令执行 → 串口输出。4.2 用 shellPrint 确认输出通道shellPrint是 shell 提供的格式化输出函数用法和printf类似。它内部会调用你绑定的shell.write接口把数据发出去。如果你在命令函数里调了shellPrint但终端没显示先检查shell.write有没有正确绑定。void shellCmdTest(void) { shellPrint(shell, test ok, tick%d\r\n, get_tick()); } SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), test, shellCmdTest, test command);输入test终端应该打印test ok, tick12345。如果只看到命令回显但没有输出多半是写接口的问题。4.3 验证 Tab 补全和历史记录输入led然后按 Tab 键如果补全功能开启会自动补成ledon或列出ledon、ledoff两个候选。按上下方向键可以翻历史命令。这两个功能能正常工作说明 shell 的缓冲区管理和按键解析都没问题。5. 本篇常见错排查5.1 终端没有任何输出先确认串口参数波特率、数据位、停止位、校验位。LetterShell 本身不关心这些它只负责字符流但串口配置错了就什么都收不到。用示波器或者逻辑分析仪看 TX 引脚有没有波形是最直接的判断方法。如果 TX 有波形但终端是乱码检查波特率是否匹配。如果 TX 没波形检查shell.write有没有被调用以及串口发送函数本身是否正常。5.2 输入字符没有回显LetterShell 默认会回显输入的字符。如果没有回显说明shellHandler没有被调用或者串口接收中断没进。检查中断服务函数里有没有调用shellHandler以及串口接收中断是否使能。另一个可能你用的是查询模式但主循环里没有喂数据。确认主循环里有shellHandler(shell, uart_read_byte(...))这样的调用。5.3 命令注册了但 help 里看不到如果用SHELL_EXPORT_CMD自动注册检查链接脚本有没有保留命令段。GCC 下通常用__attribute__((section(shellCommand)))如果链接器把未引用的段优化掉了命令就会丢失。可以在链接脚本里加KEEP(*(shellCommand))。如果用shellSetCmd手动注册检查注册代码有没有被执行到。有时候初始化顺序不对shell 还没初始化就注册命令会导致注册失败。5.4 命令执行到一半卡死多半是命令函数里做了阻塞操作比如死循环等待某个标志位。LetterShell 在中断里同步执行命令如果命令不返回中断就出不来整个系统都会卡住。解决办法是把耗时操作拆成状态机或者用 shell 的异步命令机制如果版本支持。另外检查栈空间shell 命令执行时用的是当前栈如果命令函数里局部变量太大可能栈溢出。增大任务栈或者减少局部变量。5.5 中文或特殊字符显示异常LetterShell 默认按字节处理不关心编码。如果你的终端是 UTF-8而代码里发的是 GBK就会乱码。统一用 ASCII 或者确保两端编码一致。shellPrint本身不做编码转换发什么字节就显示什么。6. 把 shell 接入你的调试工作流跑通第一条命令之后LetterShell 的价值才真正开始体现。你可以把常用的调试动作都做成命令读寄存器、改参数、触发校准、打印状态。配合 Tab 补全和历史记录调试效率会比反复烧录高很多。如果你在多个项目里都用 LetterShell可以考虑把shell_port.c做成一个可复用的模块串口收发用弱符号或者回调注册这样换平台时只需要改硬件相关的几行代码。对于需要长期做嵌入式编码和 Agent 调试的场景可以把 shell 命令和上层工具链结合起来用 Coding Plan 管理你的调试脚本和命令集减少重复配置。接入文档里有具体的接口说明和示例API Keys 页面可以拿到调用凭证。模型对话入口适合快速验证命令逻辑不用每次都烧到板子上。先把help、ledon、test这三条命令跑通确认串口收发、命令解析、输出回显都正常剩下的就是按你的项目需求往里加命令了。