91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# 工厂 CLI：UART0 与原生 USB CDC
|
||
|
||
2026-10-23：工厂CLI新增原生USB Serial/JTAG CDC收发，保留UART0。
|
||
此前CDC可看到第二控制台日志，但工厂CLI只读取UART0；“能看到日志”不代表能输入命令。
|
||
|
||
## 配置与接线
|
||
|
||
`menuconfig`位置：`TQ Cat Configuration -> Voice, Authentication & Multimodal ->
|
||
Credentials & Device Authentication`。
|
||
|
||
```text
|
||
CONFIG_TQ_FACTORY_CLI_ENABLE=y
|
||
CONFIG_TQ_FACTORY_CLI_USB_CDC_ENABLE=y
|
||
```
|
||
|
||
第二项默认开启，要求芯片支持USB Serial/JTAG，且没有选择USB-OTG控制台。
|
||
这里的CDC是ESP32-S3自带的USB Serial/JTAG设备，不是TinyUSB/USB-OTG CDC实现。
|
||
关闭第二项仍能使用UART0。
|
||
|
||
- 原生USB：GPIO19 D-、GPIO20 D+，使用板上的原生USB接口和数据线。
|
||
- UART0：GPIO43 TX、GPIO44 RX，使用3.3V USB转串口，交叉连接TX/RX并共地。
|
||
- 当前日志主控制台仍为UART0，USB Serial/JTAG仍为第二日志输出；不改变刷机方式。
|
||
|
||
## 发送命令
|
||
|
||
刷入新固件后，打开原生USB枚举出来的串口。macOS通常为`/dev/cu.usbmodem…`，
|
||
应使用本机实际枚举的端口。UART当前波特率115200；原生USB CDC的速率不代表UART线速。
|
||
|
||
逐行发送，每行以回车或换行结束：
|
||
|
||
```text
|
||
get_device_info
|
||
factory_mode
|
||
set_device_id <后台登记的设备UUID>
|
||
set_serial_number <同一台设备的实际序列号>
|
||
save_config
|
||
get_device_info
|
||
get_auth_material
|
||
```
|
||
|
||
普通设置成功返回`OK`；读取命令返回JSON和`OK`；失败返回`ERROR <reason>`。
|
||
`save_config`成功才表示写入Flash。JSON和`OK`应作为独立完整行读取，工具应允许穿插日志行。
|
||
关于注册服务和工位签名，继续按设备认证文档操作；CDC不改变认证协议。
|
||
|
||
日志入口：
|
||
|
||
```text
|
||
platform_console: Factory USB Serial/JTAG CDC ready (GPIO19 D-, GPIO20 D+)
|
||
cp_factory_cli: Factory serial CLI ready (UART0 and enabled USB Serial/JTAG CDC)
|
||
```
|
||
|
||
平台日志确认实际CDC驱动安装；CLI通用就绪日志只表示至少有一路可用。
|
||
如果某一路初始化失败，会打印对应警告，另一路仍可工作，后续install可重试失败一路。
|
||
|
||
## 隔离、超时和生命周期
|
||
|
||
只有一个CLI任务。每轮先后读取两路，各最多64字节，非阻塞读取后让出一个tick。
|
||
两路命令串行执行，不新增第二个worker。每路独立保存行缓冲、工厂模式及待提交身份，
|
||
回复只发回来源端口。持久化的设备身份仍是整台设备共享，不能把两路当成两台设备操作。
|
||
|
||
超长行丢弃至下一个行尾，不把尾部重新当作命令。半行连续2秒没有新字节也会丢弃至行尾；
|
||
USB拔插后建议先发送一个空行，再发完整命令。CDC读取报错也会清理当前半行。
|
||
|
||
USB发送使用小块、零等待驱动入队，一条回复共用250ms预算（含获取stdout锁），
|
||
并按整行保护，避免普通ESP_LOG插进JSON。USB未打开或拔出时不会无限等待。
|
||
超时可能已有部分数据入队；250ms是软件入队预算，不保证主机已收到。
|
||
工具必须检查完整应答，超时后可先换行并查询设备状态，不能仅凭部分输出认定保存成功。
|
||
UART沿用原有发送路径。驱动是平台常驻共享资源，CLI停止/重启不卸载驱动，
|
||
启动可重复调用；CLI仍按原有协作取消、有界等待和强制兜底策略停止。
|
||
|
||
新增USB RX/TX缓冲请求分别为2048/1024字节，另有驱动/队列/ISR开销；
|
||
两路行数组共1024字节，待提交身份数组共256字节，另有会话元数据。
|
||
它们不是图像或DMA缓存；没有新增CLI任务，也未增加CLI任务栈配置。
|
||
|
||
## 验证
|
||
|
||
```sh
|
||
python3 tools/test_factory_cli_console.py
|
||
python3 tools/test_provisioning_recovery.py
|
||
```
|
||
|
||
第一项编译实际平台驱动及CLI组帧、命令解析、身份保存函数，分别验证CDC开/关、
|
||
驱动重复初始化、单端失败与回退、双端来源路由、身份暂存隔离、USB发送超时、超长行
|
||
与半行恢复；使用ASan/UBSan。第二项回归身份保存通知和配网恢复。
|
||
|
||
本次CDC开启/关闭的主机测试和配网恢复测试均通过，ESP-IDF 5.5.4新板配置构建通过；
|
||
未烧录，尚未完成本次实现的USB枚举与实机收发验证。
|
||
|
||
实机验收需分别通过UART、CDC发送`get_device_info`，再验证CDC身份保存、公钥读取、
|
||
USB拔插及双端交错命令。主机故障桩和构建不能代替USB枚举及实机收发测试。
|