4.4 KiB
工厂 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。
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线速。
逐行发送，每行以回车或换行结束：
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不改变认证协议。
日志入口：
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任务栈配置。
验证
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枚举及实机收发测试。