树莓派模拟USB键盘无法发送F13及更高按键的技术求助

核心问题分析 #

原HID报告描述符将扫描码最大值限制为0x65（对应F12），要支持F13-F24（扫描码0x66至0x73），需调整描述符的Usage Minimum和Usage Maximum字段。直接改值后出现BlockingIOError，是因为报告描述符的结构或长度不符合USB HID规范，导致系统无法正确识别HID设备。

正确的HID报告描述符配置 #

替换Key Mime Pi启用脚本中的报告描述符为以下内容（适配标准USB键盘的扩展按键支持）：

0x05, 0x01,        // Usage Page (Generic Desktop)
0x09, 0x06,        // Usage (Keyboard)
0xA1, 0x01,        // Collection (Application)
0x05, 0x07,        // Usage Page (Key Codes)
0x19, 0x00,        // Usage Minimum (0x00)
0x29, 0x73,        // Usage Maximum (0x73, 覆盖F13-F24)
0x15, 0x00,        // Logical Minimum (0)
0x25, 0x73,        // Logical Maximum (0x73)
0x75, 0x08,        // Report Size (8 bits)
0x95, 0x06,        // Report Count (6)
0x81, 0x00,        // Input (Data, Array, Absolute)
0x05, 0x08,        // Usage Page (LEDs)
0x19, 0x01,        // Usage Minimum (Num Lock)
0x29, 0x05,        // Usage Maximum (Kana)
0x15, 0x00,        // Logical Minimum (0)
0x25, 0x01,        // Logical Maximum (1)
0x75, 0x01,        // Report Size (1 bit)
0x95, 0x05,        // Report Count (5)
0x91, 0x02,        // Output (Data, Variable, Absolute)
0x75, 0x03,        // Report Size (3 bits)
0x95, 0x01,        // Report Count (1)
0x91, 0x01,        // Output (Constant)
0xC0,              // End Collection

关键调整说明 #

• 将Usage Maximum和Logical Maximum从0x65改为0x73，覆盖F13（0x66）到F24（0x73）的扫描码范围
• 保持Input字段的Report Count为6（标准键盘支持同时按下6个按键），修改这个值会破坏HID报告结构
• 保留LED输出部分原有配置，避免影响键盘指示灯功能

配置后的验证步骤 #

1. 替换脚本中的报告描述符后，重新运行Key Mime Pi启用脚本
2. 在目标电脑的设备管理器中，确认USB HID设备被正常识别为键盘
3. 发送F13-F24的UDP测试数据包，验证按键响应
4. 若仍出现BlockingIOError，检查：
   • 报告描述符字节数是否正确（上述描述符共34字节）
   • 树莓派的USB gadget驱动是否加载，执行lsmod | grep libcomposite确认
   • 确保无其他程序占用USB gadget设备节点

额外注意事项 #

• F13-F24的扫描码需严格对应：F13=0x66，F14=0x67，…，F24=0x73，发送数据包时不要填错
• 若需支持更多特殊按键，可进一步扩展Usage Maximum，但不能超出USB HID键盘规范范围

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