企业官网建设流程全解析

ESP32-S3 USB HID LED 不亮？3 个临时方案

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32

按键输入正常，但 Caps Lock / Num Lock 指示灯不亮：ESP32-S3 Arduino 核心的 USB HID 键盘 LED 状态反馈自3.0.0-RC2起失效（2.0.13正常，3.1.0-RC1复现）。本文给出 3 个临时方案，并说明断在哪一环。

版本对照表

问题自3.0.0-RC2引入且至今未解决，2.0.13与3.0.0-RC1两条线均可用。

注意输入方向在所有版本都正常，断的只有主机到设备的 LED 回传这一路。

协议层发生了什么

你的按键发得出去，LED 状态却回不来：USB HID 有两条数据流——输入报告（设备→主机，承载按键状态）与输出报告（主机→设备，承载 LED 状态）。

问题出在 TinyUSB（Arduino 核心内置的 USB 协议栈），两个变更点直接命中 LED 链路：

• ① 输出报告回调不触发：主机写入 LED 状态，设备侧tud_hid_set_report_cb却不应答，LED 位到不了_onOutput——新版处理流程变更，OUT 端点数据不再进回调。
• ②tud_hid_n_ready()（检查主机是否已连接的函数）误判连接状态：设备初始化后立即调用它返回 false，物理上明明已连接——检测逻辑被调整，重插后状态才正确。可直接用它做重连检查：

if (!Keyboard.ready()) { // 内部即 tud_hid_n_ready(0) Serial.println("HID not ready, replug"); }

LED 状态链路可对照 libraries/USB/src/USBHIDKeyboard.cpp 的_onOutput：事件只在回调触发时才发出。

现在能做什么

官方补丁落地前，你有 3 个临时方案可选：

• 把 Arduino 核心降到2.0.13，适用于不依赖 3.x 新特性的存量项目，代价是用不上新增功能。
• 改用3.0.0-RC1，适用于想提前体验 3.x 核心的场景，代价是上电后可能要重插一次 USB 才识别连接。
• 等官方补丁，适用于能排期等待的项目，代价是等待期内 LED 反馈不可用，需自行实现 LED 状态兜底。

官方修复方向

修复涉及 USB HID 键盘驱动的输出报告处理逻辑与设备初始化的连接状态检测两个模块；该版本还会支持即将发布的 ESP32-P4。

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32