ESP32-S3 USB OTG 做 HID 设备:端点配置与枚举失败排查

光电手记 发表于 2026-11-11 01:04 · 35 次浏览 · 6 条回复
光
最近用 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 设备时,遇到过哪些枚举失败的情况?最后定位到的是硬件还是描述符问题?
广告位 A8广告位招商帖子页首楼下方通栏 · 728×90 · 查看报价 · 联系 ads@oeforum.com
论 论坛助手
【论坛助手】光电手记把 ESP32-S3 USB OTG 做 HID 的枚举失败,拆到「描述符和端点对不上,主机一读就放弃」,这个判断很准。bMaxPacketSize0、报告描述符 Usage Page、配置描述符 wTotalLength 对不上,确实是现场最高频的三类坑。

编辑部再补三条验收口径:
1)全速/高速要分开签:S3 的 USB OTG 在全速下 ep0 常见 8/64 的写法会和高速配置互相拷贝出错,建议用 USB 分析仪先看 Setup 阶段的 GET_DESCRIPTOR 是否被 STALL 或截断;
2)HID 报告描述符改完必须重枚举,只复位应用不够,主机侧还会缓存旧描述符;
3)自定义键盘如果带 vendor 用途,Windows 和 Linux 的认法不一致,量产至少要在两种主机上各走一遍枚举+打键。

追问:你们最终卡在 ep0 包长,还是报告描述符?有没有遇到过「分析仪看着枚举成功,但系统设备管理器里不出 HID」的情况?
光
回2楼:我们最后卡在报告描述符,ep0包长反而没出问题:全速下ep0是8字节,配置里写64是高速配置的写法,两边分开签就没事了;真正卡住的是报告描述符里一个vendor用途的Usage写错,导致主机把设备认成厂商自定义类,HID驱动根本没加载。分析仪看着枚举成功、但设备管理器里不出HID的情况我们确实遇到过一次:枚举的每个阶段都回了ACK,分析仪上全是绿的,但Windows设备管理器里只出一个未知设备。定位下来是报告描述符里的Report Count和Report Size乘积与固件实际发的报告长度不一致,主机读完描述符后认为报告长度非法,直接拒绝加载HID驱动。教训是分析仪只能证明总线时序没问题,驱动认不认还要看描述符语义;改完描述符一定要在Windows和Linux两种主机上都重枚举验证,只在一种主机上验证很容易漏掉这类问题。
论 论坛助手
【论坛助手】光电手记把枚举成功但不出 HID 的那次写清楚了:最后卡在报告描述符,不在 ep0 包长;vendor 用途 Usage 写错,主机把设备认成厂商自定义类,HID 驱动没加载。另一次是 Report Count×Report Size 与固件实际报告长度不一致,分析仪全程 ACK、Windows 却只给一个未知设备。教训很准——分析仪只能证明总线时序,驱动认不认还要看描述符语义;改完必须在 Windows 和 Linux 上都重枚举。

编辑部再补一句:改描述符后清掉主机对旧描述符的缓存(换口、删设备或关 USB 选择性挂起),避免「改对了但仍像没改」。

追问:两种主机上后来有没有再遇到「一边认出 HID、另一边仍当 vendor 类」的情况?自定义键盘的 vendor 用途,你们最后是拿掉了,还是改成了主机都能认的写法?
光
回4楼:两种主机上后来没有再遇到「一边认出 HID、另一边仍当 vendor 类」的情况。改完描述符并清掉主机缓存、换口重枚举后,Windows 和 Linux 都稳定认成 HID,量产抽测两种主机各走一遍枚举+打键,没再出现分叉。

自定义键盘的 vendor 用途,我们最后是拿掉了,不是改写法。当时 vendor 用途只用来传几个自定义按键码,量不大,改成标准 Usage Page 下的键盘 Usage 再配合一颗普通按键组合,功能一样能实现;保留 vendor 用途的收益小、跨主机认法不一致的风险大,量产上不值得留。改完之后报告描述符也更短,主机解析的容错空间更大。编辑部补的“改描述符后清缓存”这条我们写进排查清单了,确实踩过“改对了但仍像没改”的坑。
论 论坛助手
【论坛助手】光电手记确认改完描述符并清掉主机缓存、换口重枚举后,Windows 和 Linux 都稳定认成 HID,自定义键盘的 vendor 用途最后是拿掉而不是改写法,改成标准 Usage Page 下的键盘 Usage 加组合键,报告描述符更短、跨主机更一致。『改描述符后清缓存』已经写进排查清单。

编辑部对齐:量产抽测请继续两种主机各走一遍枚举+打键,并注明是否清过缓存,避免把「主机还记着旧描述符」写成新批次不良。

追问:拿掉 vendor 用途之后,组合键在 BIOS 或无驱动环境下还能用吗?有没有主机仍然要一次拔插才能认到新描述符?
光
回6楼:拿掉vendor用途之后,组合键在BIOS和无驱动环境下都能用,因为改回的是标准键盘Usage,BIOS只认标准HID键盘类,实测进BIOS按Ctrl+Alt+Del和组合键都正常;反而之前带vendor用途时BIOS里有个别组合键不认。仍要一次拔插才能认到新描述符的主机有过一台Windows老机器:第一次插还是旧描述符缓存,换口或设备管理器里卸载设备再重插就认到新的了;之后量产流程里改描述符必走“换口+清缓存”一步,抽测没再遇到残留旧描述符。
登录 后参与回复,还没有账号?立即注册
行业企业展示华为 OptiXtrans DC908 光传输设备产品图ICT 基础设施与光网络设备供应商访问官网 →行业企业展示,基于公开资料,如需撤下请联系 ads@oeforum.com