光
最近用 ESP32-S3 的 USB OTG 做一个 HID 自定义键盘,调通之后回头看,枚举阶段的坑比想象中多,分享一下排查经验。
先说结论:大部分枚举失败不是代码写错,而是描述符和端点配置对不上,主机一读描述符就放弃了。
一、描述符先对齐
HID 设备至少要配齐三层描述符:设备描述符、配置描述符、HID 报告描述符。常见错误有三个:bMaxPacketSize0 写成 64 但实际端点只配了 8;报告描述符里的 Usage Page 和 Usage 写错,主机认不出这是键盘还是鼠标;配置描述符的 wTotalLength 算错,主机读到的长度和实际发送的不一致。我的做法是先用 USB 协议分析仪或者系统自带的 usbmon 抓一遍枚举过程,看主机在哪一步停下,再对着那一步的描述符改。
二、端点配置别想当然
ESP32-S3 的 OTG 外设中断端点默认轮询间隔是 10ms,HID 报告如果设了 1ms 的 bInterval,实际达不到也没关系,但描述符里写 1ms 而固件里按 10ms 回,主机不会报错,只是延迟变大。真正会出问题的是端点号冲突:CDC 和 HID 共存时,CDC 占了 EP1 IN/OUT,HID 再用 EP1 就会枚举失败。建议 HID 固定用 EP2,CDC 用 EP1,写死在代码里别留给默认配置。
三、枚举失败的定位顺序
1)先看供电:USB 枚举瞬间电流有个小尖峰,3.3V 轨如果被拉低超过 100mV,部分主机直接判定设备异常。
2)再看 D+/D- 上拉:全速设备 D+ 上拉 1.5k,高速设备靠 chirp 协商,电阻焊错成 10k 会导致主机识别成低速。
3)最后看固件:用逻辑分析仪抓 D+/D- 波形,确认 SET_ADDRESS 之后设备有没有正确回 ACK。
一个小经验:开发阶段先用最简单的 HID 报告描述符(一个按键、一个字节)跑通枚举,再往上加功能。一次加太多,出问题根本不知道是哪一层。
你们在 ESP32-S3 上做 USB 设备时,遇到过哪些枚举失败的情况?最后定位到的是硬件还是描述符问题?
先说结论:大部分枚举失败不是代码写错,而是描述符和端点配置对不上,主机一读描述符就放弃了。
一、描述符先对齐
HID 设备至少要配齐三层描述符:设备描述符、配置描述符、HID 报告描述符。常见错误有三个:bMaxPacketSize0 写成 64 但实际端点只配了 8;报告描述符里的 Usage Page 和 Usage 写错,主机认不出这是键盘还是鼠标;配置描述符的 wTotalLength 算错,主机读到的长度和实际发送的不一致。我的做法是先用 USB 协议分析仪或者系统自带的 usbmon 抓一遍枚举过程,看主机在哪一步停下,再对着那一步的描述符改。
二、端点配置别想当然
ESP32-S3 的 OTG 外设中断端点默认轮询间隔是 10ms,HID 报告如果设了 1ms 的 bInterval,实际达不到也没关系,但描述符里写 1ms 而固件里按 10ms 回,主机不会报错,只是延迟变大。真正会出问题的是端点号冲突:CDC 和 HID 共存时,CDC 占了 EP1 IN/OUT,HID 再用 EP1 就会枚举失败。建议 HID 固定用 EP2,CDC 用 EP1,写死在代码里别留给默认配置。
三、枚举失败的定位顺序
1)先看供电:USB 枚举瞬间电流有个小尖峰,3.3V 轨如果被拉低超过 100mV,部分主机直接判定设备异常。
2)再看 D+/D- 上拉:全速设备 D+ 上拉 1.5k,高速设备靠 chirp 协商,电阻焊错成 10k 会导致主机识别成低速。
3)最后看固件:用逻辑分析仪抓 D+/D- 波形,确认 SET_ADDRESS 之后设备有没有正确回 ACK。
一个小经验:开发阶段先用最简单的 HID 报告描述符(一个按键、一个字节)跑通枚举,再往上加功能。一次加太多,出问题根本不知道是哪一层。
你们在 ESP32-S3 上做 USB 设备时,遇到过哪些枚举失败的情况?最后定位到的是硬件还是描述符问题?

