串口 Shell 命令表 — TWS 耳机 (杰理 AC7002)¶

调试 & 产测用 UART 串口命令集硬件平台：杰理 AC7002 (BT 5.3, RISC-V) 串口参数：115200 baud, 8N1, 3.3V TTL

1. 通用命令¶

命令	参数	说明	返回值示例
`help`	-	显示所有命令列表	`=== TWS Shell Commands ===`
`ver`	-	显示固件版本	`FW v0.1.0 (2026-05)`
`reset`	-	软复位 MCU	`Resetting...`
`uptime`	-	系统运行时间	`Up 0d 0h 12m 34s`
`heap`	-	堆内存使用	`Heap: used 8.2KB / 32KB (26%)`
`log`	N=0~4	设置日志级别	`Log level set to 3 (INFO)`

2. LED 测试命令¶

命令	参数	说明	返回值示例
`led test`	-	LED 轮流点亮测试	`LED_R ON → LED_G ON → LED_B ON → OFF`
`led r on/off`	-	单独控制红色 LED	`LED_R ON`
`led g on/off`	-	单独控制绿色 LED	`LED_G ON`
`led b on/off`	-	单独控制蓝色 LED	`LED_B ON`
`led pat`	N=0~6	设置闪烁模式	`Pattern set to 2 (FAST_BLINK)`

LED 模式表：

编号	模式	含义
0	OFF	灭
1	SLOW_BLINK	慢闪 1Hz — 待机未配对
2	FAST_BLINK	快闪 4Hz — 配对中
3	SOLID	常亮 — 已连接
4	BREATHING	呼吸 — 播放中
5	RED_FAST	红灯快闪 — 低电量
6	RED_SOLID	红灯常亮 — 充电中

3. 触控/按键测试命令¶

命令	参数	说明	返回值示例
`touch test`	-	进入触控测试模式	`等待触控操作...`
`touch status`	-	读取触控状态	`Touch: IDLE`
`btn read`	-	读取按键（如有点击）	`Btn: SINGLE_CLICK`

触控测试模式下，单击/双击/长按/滑动会实时打印：

[TOUCH] 👆 单击 detected
[TOUCH] 👆👆 双击 detected
[TOUCH] ✊ 长按 detected (1000ms)
[TOUCH] 📶 滑动 UP

4. BLE 测试命令¶

命令	参数	说明	返回值示例
`ble init`	-	初始化 BLE 协议栈	`BLE init OK, MAC: AA:BB:CC:DD:EE:FF`
`ble adv on/off`	-	开启/停止广播	`Advertising: ON`
`ble status`	-	BLE 状态	`State: IDLE, Connected: NO`
`ble rssi`	-	读取当前 RSSI	`RSSI: -45 dBm`
`ble name`	name	设置广播名称	`Name set to TWS-Earbuds`
`ble name`	-	读取广播名称	`Name: TWS-Earbuds`
`ble scan`	-	扫描周边设备	`Found 3 devices: ...`
`ble conn`	-	手动建立连接	`Connecting... OK`
`ble disc`	-	断开连接	`Disconnected`

5. 音频测试命令¶

命令	参数	说明	返回值示例
`audio play`	-	播放测试音 (1kHz)	`Playing 1kHz test tone...`
`audio stop`	-	停止播放	`Audio stopped`
`audio vol`	N=0~100	设置音量	`Volume set to 70`
`audio vol`	-	读取当前音量	`Volume: 70`
`audio status`	-	音频状态	`State: PLAYING, SR: 48kHz, Vol: 70`
`audio loop`	-	音频回环测试	`Loopback test: OK, delay: 15ms`

6. ANC 测试命令¶

命令	参数	说明	返回值示例
`anc on/off/toggle`	-	控制 ANC 模式	`ANC: ON`
`anc status`	-	ANC 状态	`Mode: ON, Gain: 0dB \| Status: OK`
`anc gain`	N=-12~12	设置 ANC 增益 (dB)	`ANC Gain set to 0dB`
`anc mode`	N=0~3	切换 ANC 模式	`ANC Mode: FEEDFORWARD`
`anc calib`	-	ANC 校准	`Calibration OK`

ANC 模式表：

编号	模式	说明
0	OFF	关闭降噪
1	ON	ANC 开启
2	AMBIENT	环境音模式
3	WINDFL	抗风噪模式

7. 电池/电源命令¶

命令	参数	说明	返回值示例
`batt`	-	读取电池电压和电量	`Battery: 3.85V (85%), Charging: NO`
`batt raw`	-	ADC 原始值	`ADC raw: 2845 (Vref: 1.2V)`
`batt status`	-	充电状态	`Charging: NO, Full: NO, USB: 5.0V`

8. GPIO/I2C 调试命令¶

命令	参数	说明	返回值示例
`gpio get`	pin	读取引脚电平	`GPIO23: HIGH (3.3V)`
`gpio set`	pin 0/1	设置引脚输出	`GPIO23 set to LOW`
`i2c scan`	-	扫描 I2C 总线	`Found: 0x68(MPU), 0x77(BMP)`
`i2c read`	addr reg len	读取 I2C 寄存器	`0x68[0x0F] = 0xAB`

9. 产测命令¶

命令	参数	说明	返回值示例
`prod test`	-	生产全流程测试	`=== PASS/FAIL ===`
`prod sn`	sn	写入序列号	`SN: TWS-20260517-001 written`
`prod mac`	-	读取 MAC 地址	`MAC: AA:BB:CC:DD:EE:FF`
`prod pass`	-	标记 PASS	`PASS`
`prod fail`	reason	标记 FAIL	`FAIL - BLE no response`

产测输出示例：

=== TWS 产测 ===
SN: TWS-20260517-001
LED Test              [PASS]
Touch Test            [PASS]
BLE Init              [PASS]
BLE Advertising       [PASS]
Audio Playback        [PASS]
ANC Mode Toggle       [PASS]
Battery Voltage       [PASS]  3.85V
I2C Scan              [PASS]  No I2C devices needed
Flash R/W             [PASS]
=== 结果: ALL PASS ✓ (耗时 45s) ===

10. 综合诊断命令¶

命令	参数	说明	返回值示例
`diag quick`	-	快速诊断 (15s)	关键指标概览
`diag full`	-	全面诊断 (2min)	所有模块详细测试
`diag sensor`	-	传感器专项	触控/ANC
`diag comm`	-	通信专项	BLE 全面测试

快速诊断输出示例：

=== TWS 快速诊断 ===
FW: v0.1.0             [OK]
Heap: 8.2KB/32KB       [OK]
BLE: IDLE              [OK]
Battery: 3.85V 85%     [OK]
LED: OK                [OK]
Touch: IDLE            [OK]
ANC: OFF               [OK]
Uptime: 0d 0h 12m      [OK]
=== 诊断完成 (8s) ===

11. 错误码¶

错误码	含义	说明
`E_OK`	成功	操作完成
`E_PARAM`	参数错误	参数数量或格式不对
`E_HW`	硬件错误	模块无响应
`E_TIMEOUT`	超时	操作未按时完成
`E_BUSY`	忙	正在处理其他任务
`E_NOMEM`	内存不足	堆分配失败
`E_INVAL`	无效命令	未知命令

12. 实现位置¶

在固件中实现 Shell 的模块：

firmware/src/
├── main.c          // shell_init() 在 main() 入口调用
├── cmd_led.c       // led 命令处理 (文件待创建)
├── cmd_touch.c     // touch 命令处理 (文件待创建)
├── cmd_ble.c       // ble 命令处理 (文件待创建)
├── cmd_audio.c     // audio 命令处理 (文件待创建)
├── cmd_anc.c       // anc 命令处理 (文件待创建)
├── cmd_batt.c      // batt 命令处理 (文件待创建)
├── cmd_prod.c      // prod 命令处理 (产测专用, 文件待创建)
└── cmd_shell.c     // Shell 核心 (命令解析/分发, 文件待创建)

文档版本：v0.1
最后更新：2026-05-17
适用固件：TWS FW ≥ v0.1.0