feat(factory): support USB CDC alongside UART CLI
This commit is contained in:
chenjintao
@@ -100,3 +100,11 @@ bounded lock failure, cleanup and retry (`tools/test_battery_adc_init.py`).
|
||||
Config/default consistency and enabled-pin uniqueness checks passed.
|
||||
No device was flashed; touch polarity, ADC2 sampling with Wi-Fi, charger/wake,
|
||||
motor direction and concurrent operation still require hardware validation.
|
||||
|
||||
## Factory CLI UART and CDC
|
||||
|
||||
`CONFIG_TQ_FACTORY_CLI_USB_CDC_ENABLE=y` enables native USB Serial/JTAG CDC input
|
||||
on GPIO19/20 alongside UART0 (GPIO43 TX / GPIO44 RX). Logs may already appear on
|
||||
CDC through the secondary console; this option additionally enables command input
|
||||
and routes replies back to the requesting port. UART and CDC line buffers and
|
||||
pending identity values are separate. See [the CLI guide](工厂CLI串口与CDC使用说明.zh-CN.md).
|
||||
|
||||
@@ -130,7 +130,10 @@ CONFIG_TQ_FACTORY_CLI_ENABLE=y
|
||||
control_plane_factory_cli_start();
|
||||
```
|
||||
|
||||
它创建名为 `factory_cli` 的 FreeRTOS 任务，通过 Console UART 读取以 `\r` 或 `\n` 结束的命令。
|
||||
它创建单个名为 `factory_cli` 的 FreeRTOS 任务，同时轮询 UART0 与原生 USB Serial/JTAG CDC，
|
||||
读取以 `\r` 或 `\n` 结束的命令。新增 `CONFIG_TQ_FACTORY_CLI_USB_CDC_ENABLE=y` 默认启用CDC，
|
||||
两路各自维护行缓冲、工厂模式和待保存身份字段，回复只发给命令来源。
|
||||
详见 [工厂CLI串口与CDC使用说明](../工厂CLI串口与CDC使用说明.zh-CN.md)。
|
||||
|
||||
关键参数：
|
||||
|
||||
@@ -138,8 +141,8 @@ control_plane_factory_cli_start();
|
||||
| --- | ---: |
|
||||
| 最大命令行长度 | 512 B |
|
||||
| 最大参数数量 | 8 |
|
||||
| 串口读取超时 | 100 ms |
|
||||
| 任务栈 | 12 KiB |
|
||||
| 接收调度 | 两路非阻塞读取，每路每轮最多64字节，每轮让出1 tick |
|
||||
| 任务栈 | 默认7 KiB（`CONFIG_TQ_FACTORY_CLI_TASK_STACK_BYTES`） |
|
||||
| 任务优先级 | 4 |
|
||||
| 运行核心 | `CONFIG_TQ_LOCAL_TASK_CORE` |
|
||||
|
||||
@@ -186,8 +189,8 @@ get_device_info
|
||||
`set_device_id` 和 `set_serial_number` 只将值暂存在 RAM：
|
||||
|
||||
```c
|
||||
s_pending_device_id
|
||||
s_pending_serial_number
|
||||
s_current_session->pending_device_id
|
||||
s_current_session->pending_serial_number
|
||||
```
|
||||
|
||||
只有执行 `save_config` 后，才会调用：
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# 工厂 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枚举及实机收发测试。
|
||||
Reference in New Issue
Block a user