如何配置ESP32-IDF HID为BLE鼠标或摇杆，解决连接后功能失效问题

1. 核心错误点 #

• 报告ID未正确携带：你在鼠标报告描述符中定义了Report ID (0x01)，HID规范要求带Report ID的报文第一个字节必须为对应的ID值，你当前发送函数中Mouse_Buffer[0] = 0，主机无法匹配到对应报告定义，直接忽略报文。
• 鼠标报告描述符结构错误：鼠标属于通用桌面的应用级设备，顶层Collection类型应为Application而非Physical，且按钮部分未声明Usage范围，主机无法识别按键定义。
• 报文长度与定义不匹配：你当前定义的鼠标输入报告总长度为 1字节Report ID + 1字节按钮 + 3字节(X/Y/滚轮) = 5字节，你调用esp_hidd_dev_input_set仅发送4字节，报文截断。
• 注释中的摇杆描述符语法错误：摇杆部分的Logical Maximum (4095)和Physical Maximum (4095)属于双字节值，你将其二进制拆分后单独作为一个字节写入，导致描述符结构错乱，无法解析。

2. 修正代码 #

修正后的鼠标报告描述符 #

const unsigned char mediaReportMap[] = {
    0x05, 0x01,     // Usage Page(Generic Desktop)
    0x09, 0x02,     // Usage(Mouse)
    0xA1, 0x01,     // Collection(Application) <-- 修正为Application类型
    0x85, 0x01,     // Report ID (0x01)
    0x09, 0x01,     // Usage(Pointer)
    0xA1, 0x00,     // Collection(Physical) <-- 嵌套Pointer的Physical集合
    0x05, 0x09,     // Usage Page(Buttons)
    0x19, 0x01,     // Usage Minimum (Button 1)
    0x29, 0x08,     // Usage Maximum (Button 8)
    0x15, 0x00,     // Logical Minimum (0)
    0x25, 0x01,     // Logical Maximum (1)
    0x75, 0x01,     // Report Size (1) <-- 每个按钮占1位
    0x95, 0x08,     // Report Count (8) <-- 共8个按钮
    0x81, 0x02,     // Input(Data,Var,Abs)
    0x05, 0x01,     // Usage Page(Generic Desktop)
    0x09, 0x30,     // Usage(X)
    0x09, 0x31,     // Usage(Y)
    0x09, 0x38,     // Usage(Wheel)
    0x75, 0x08,     // Report Size(8)
    0x95, 0x03,     // Report Count(3)
    0x15, 0x81,     // Logical Minimum(-127)
    0x25, 0x7F,     // Logical Maximum(127)
    0x81, 0x06,     // Input(Variable, Relative)
    0xC0,           // End Collection (Physical)
    0xC0            // End Collection (Application)
};

修正后的发送函数 #

void esp_hidd_send_axis(int xVal, int yVal)
{
   uint8_t Mouse_Buffer[5] = {0};
   Mouse_Buffer[0] = 0x01; // 携带Report ID 0x01
   Mouse_Buffer[1] = 0; // 按钮状态，无按键则为0
   Mouse_Buffer[2] = xVal & 0xFF; // X偏移，范围-127~127
   Mouse_Buffer[3] = yVal & 0xFF; // Y偏移，范围-127~127
   Mouse_Buffer[4] = 0; // 滚轮状态
   esp_hidd_dev_input_set(hid_dev, 1, 1, Mouse_Buffer, 5); // 发送完整5字节报文
}

3. 额外注意事项 #

• 若需要切换为摇杆功能，需将双字节的最值写为连续的两个字节：0x26, 0xFF, 0x0F（对应4095），不要拆分为单独的0x0F字节。
• 蓝牙HID注册时需确保使用的报告描述符是修改后的mediaReportMap，而非默认的消费类控制描述符。

内容的提问来源于stack exchange，提问作者YIJEN Lu