letter-shell 是纯 C 语言开发、无外部依赖的嵌入式命令行交互开源组件，单片机裸机、RTOS 系统都能直接移植，只用少量代码就能给设备做出串口命令调试界面，新增调试命令只需要一行宏注册，不用修改主程序，是嵌入式项目里做 CLI 调试的首选开源方案，它代码精简、可灵活裁剪，自带 Tab 补全、命令权限、用户登录、历史命令等高级功能，解决了嵌入式设备调试命令不好扩展、交互简陋的痛点，只需要对接串口读写函数，半天就能完成全功能移植，非常适合单片机开发项目落地调试功能。

一、项目基础信息

1. 项目核心信息清单

• 项目名称：letter-shell
• 开发语言：C99 标准 C 语言
• 开源协议：MIT 协议，允许商用，无版权限制
• 最新稳定版本：3.2.4
• 代码体量：核心文件仅几百行，整体代码不到 2000 行，占用 RAM 极小
• 适用平台：STM32、GD32 等各类 MCU，裸机、FreeRTOS、RT-Thread 均可使用
• 核心仓库：GitHub+Gitee 双仓库，配套完整中文文档与工程 demo

2. 核心功能列表

1. 基础交互：行编辑、光标移动、退格删除、历史命令回溯
2. 智能交互：Tab 键命令自动补全，help 命令自动展示所有命令说明
3. 权限管理：多用户账号、分级命令权限，限制普通用户调用高危指令
4. 命令扩展：宏自动注册命令，新增功能不用改动原有代码，支持带参数函数调用
5. 高级扩展：支持自定义全局变量、快捷键绑定、数组参数解析、命令代理函数
6. 资源裁剪：可关闭不需要的功能，进一步减小 ROM 占用

二、核心技术优势

1. 命令注册机制（最大亮点）

采用编译段属性 + 宏自动收集命令，只需要一行代码就能注册新命令，完全做到插件化开发。

示例代码：

SHELL_EXPORT_CMD(reboot, cmd_reboot, "restart system");

新增调试指令不需要修改命令检索逻辑，不会产生代码耦合，后续维护非常方便。

2. 移植门槛极低

只需要实现两个最简单的串口读写回调函数，把串口收到的字符传给 shell，再把 shell 输出内容发送到串口，剩下的初始化调用一行代码即可完成，不需要复杂配置。

3. 资源占用可控

• 最小裁剪版本只保留基础命令解析，ROM 占用不足 2KB；
• 不带文件系统，不依赖操作系统，裸机单片机直接运行；
• 支持关闭用户权限、命令补全，进一步压缩内存开销。

三、快速移植步骤

步骤 1：导入源码

把 src、extensions 文件夹添加到工程，只保留 shell 核心文件，其余非必要扩展可以直接删掉。

步骤 2：对接硬件串口

实现 shell 读、写两个回调函数，绑定设备串口收发接口。

步骤 3：初始化 shell 对象

定义全局 Shell 实例，调用 shellInit 完成初始化，在主循环或者串口中断里调用 shell 处理字符。

步骤 4：注册自定义调试命令

使用 SHELL_EXPORT_CMD 宏绑定函数，编译之后就能在串口终端直接调用该函数，传递参数。

步骤 5：功能测试

串口打开终端，输入 help 查看全部命令，按 Tab 键测试自动补全，输入历史指令测试命令回溯。

四、版本选择建议

五、常见使用场景

1. 单片机产品串口调试：通过命令读写寄存器、控制 IO、打印运行日志，替代零散的 printf 打印；
2. 物联网设备运维：设备上线后，串口 / 网口接入 shell，远程执行运维指令；
3. 项目模块化开发：每个功能模块自行注册调试命令，模块之间互不干扰；
4. 量产设备故障排查：预留调试 shell，现场输入指令读取设备运行状态。

【相关 FAQ】

问题 1：letter-shell 这款嵌入式开源项目，移植到单片机上难不难？

回答 1：letter-shell 移植难度很低，只需要对接串口读写两个回调函数，再做一行初始化代码，半天就能完成基础移植；它自带完整 demo，支持 Keil、IAR、GCC 三种编译器，裸机和 RTOS 环境都能直接跑，不需要额外依赖其他库。

问题 2：使用 letter-shell 开发调试命令，新增指令需要修改原有代码吗？

回答 2：不需要修改原有代码，letter-shell 依靠编译段 + 宏自动注册命令，只需要用 SHELL_EXPORT_CMD 宏绑定函数，就能自动加入命令列表，完全插件化，不会产生代码耦合，后期扩展维护很方便。

问题 3：letter-shell 3.x 版本相比 2.x 版本，新增了哪些实用能力？

回答 3：letter-shell 3.x 新增多用户账号体系、分级命令权限管理，支持全局变量查看、数组参数解析，还增加了命令锁定功能；适合产品正式版本使用，2.x 只适合简单调试场景，没有权限管控能力。

问题 4：letter-shell 占用单片机资源多不多，能不能用在小容量 MCU 上？

回答 4：letter-shell 核心代码仅几百行，基础功能裁剪后 ROM 占用不到 2KB，RAM 开销极小；可以关闭 Tab 补全、用户权限等功能精简体积，STM32F103 这类小容量单片机完全可以稳定运行。

【参考资料】

[2026-11-11]（推荐一个好的嵌入式开源项目之三 ——letter-shell）电子工程专辑

[2025-12-15]（这几个嵌入式软件开源项目值得深度复刻！）电子工程专辑

[2025-03-11]（一个功能强大的嵌入式 shell）电子工程世界

[2020-07-16]（第 2 期 | letter-shell，一个功能强大的嵌入式 shell）腾讯云开发者社区

[未知]（smallqing/letter-shell 项目主页）Gitee 开源平台

【免责声明】

本文仅为 letter-shell 嵌入式开源项目的技术资讯与移植方案整理，项目实际运行效果取决于硬件平台、编译器配置与功能裁剪；本内容不构成商业项目选型的唯一依据，源码细节、版本更新以项目 GitHub 官方仓库为准。