1.引言开发自定义游戏控制器时不能只向电脑发送几个按键字节。电脑还需要知道这些字节分别表示什么。USB HID设备通过报告描述符声明数据格式例如X/Y方向各占多少位、有哪些按键以及整份报告有多长。本文以CH572的USB/Device/CompoundDev例程为基础使用HIDDescBuilder设计Gamepad报告描述符再让固件按该格式发送数据最后验证Windows是否将原鼠标接口识别为游戏控制器。2.原始例程键盘鼠标CompoundDev是一个USB复合设备原版包含键盘和鼠标两个HID接口。烧录原始程序后WCHUSBList能清晰的看到这两个功能这次改造我们保留键盘接口只将鼠标接口改成Gamepad便于观察修改前后的差异。3.反向解析原鼠标报告描述符在动手修改前我们可以先用HIDDescBuilder的“解析HEX”功能逆向分析原鼠标的数据结构。将原鼠标的HEX数组粘贴到底部输入框点击“解析HEX”结合左侧树状图和右侧Property面板核心信息一目了然数据特性X/Y轴逻辑范围Logical Range为-127 ~ 127且被定义为Relative相对位移。位对齐设计包含Button 1-33bit与Padding[5b]5bit常量填充刚好凑齐1字节符合USB协议规范。报告格式Report ID为0总输入报告长度为4字节1字节按键 3字节坐标。对比思考通过解析可以看出鼠标的“相对位移”与Gamepad的“绝对位置”截然不同。此外原鼠标没有独立ID而在复合设备中改造为Gamepad时我们通常需要引入Report ID如0x01以便主机精准区分数据。3.用HIDDescBuilder设计Gamepad拖动左侧组件库中的模板与数据项组成GamePad结构包括X/Y方向和Button16。X、Y轴各占2 bitLogical Minimum/Maximum设为-1和1适合方向键Button16各占1 bit生成的HEX还包含6 bitConstant填充用于将数据补齐至2字节工具生成的报告描述符为48字节。输入报告由1字节Report ID2字节数据组成。设计完成后可直接复制C数组减少手工编写HID HEX 的工作。复制结果如下#include stdint.h static const uint8_t hidReportDescriptor[] { 0x05, 0x01, 0x09, 0x05, 0xA1, 0x01, 0x85, 0x01, 0x09, 0x01, 0xA1, 0x00, 0x09, 0x30, 0x09, 0x31, 0x15, 0xFF, 0x25, 0x01, 0x95, 0x02, 0x75, 0x02, 0x81, 0x02, 0xC0, 0x05, 0x09, 0x19, 0x01, 0x29, 0x06, 0x15, 0x00, 0x95, 0x06, 0x75, 0x01, 0x81, 0x02, 0x95, 0x01, 0x75, 0x06, 0x81, 0x03, 0xC0 }; static const unsigned int hidReportDescriptorSize sizeof(hidReportDescriptor);4.将生成结果接入固件首先修改接口描述符将原鼠标接口用途改为游戏手柄将其报告描述符长度wDescriptorLength更新为0x30即48字节再把工具导出的内容写入GamePad[]并准备3字节的 HIDGamepad[]发送缓冲区。键盘接口保持原样。接着在主机请求接口1的报告描述符时返回GamePad[]及其实际长度。这样电脑读取到的是新的Gamepad描述符。最后停用原鼠标报告函数新增DevHIDGamepadReport()将X/Y和六个按键状态打包到两个数据字节连同Report ID 0x01通过原接口的EP2 IN端点发送。5.无硬件环境下的实测验证当前使用的是一块CH572芯片板没有外接方向键和按钮。因此在主循环中定时调用DevHIDGamepadReport()让设备自动循环发送居中→左→居中→右→居中→上→居中→下等方向状态并模拟Button 1按下、释放。每个状态停留约0.8秒便于观察。重新编译、烧录并连接电脑后WCHUSBList显示键盘仍在原鼠标功能已被识别为HID游戏控制器HID-compliant game controller。接着打开Windows自带的joy.cpl游戏控制器测试工具进行验证观察到方向指示和按键指示灯按程序设定的顺序周期性变化完美验证了HID报告描述符与固件上报逻辑的正确性。6.总结通过这个案例我们完整体验了HIDDescBuilder从“反向解析HEX”到可视化设计描述符、导出C数组再到接入固件并通过joy.cpl验证设备识别的全过程。对于没有外设硬件的开发者使用软件模拟循环发送是快速验证USB通信和HID协议的绝佳方法。下一步你只需在此基础上接入实体的GPIO按键和ADC摇杆就能快速制作出一个专属的USB游戏控制器。 
长河君 · 2026/10/30 9:58:10 · 阅读 1.2k 实测：用HIDDescBuilder将USB鼠标接口改为Gamepad
1.引言开发自定义游戏控制器时不能只向电脑发送几个按键字节。电脑还需要知道这些字节分别表示什么。USB HID设备通过报告描述符声明数据格式例如X/Y方向各占多少位、有哪些按键以及整份报告有多长。本文以CH572的USB/Device/CompoundDev例程为基础使用HIDDescBuilder设计Gamepad报告描述符再让固件按该格式发送数据最后验证Windows是否将原鼠标接口识别为游戏控制器。2.原始例程键盘鼠标CompoundDev是一个USB复合设备原版包含键盘和鼠标两个HID接口。烧录原始程序后WCHUSBList能清晰的看到这两个功能这次改造我们保留键盘接口只将鼠标接口改成Gamepad便于观察修改前后的差异。3.反向解析原鼠标报告描述符在动手修改前我们可以先用HIDDescBuilder的“解析HEX”功能逆向分析原鼠标的数据结构。将原鼠标的HEX数组粘贴到底部输入框点击“解析HEX”结合左侧树状图和右侧Property面板核心信息一目了然数据特性X/Y轴逻辑范围Logical Range为-127 ~ 127且被定义为Relative相对位移。位对齐设计包含Button 1-33bit与Padding[5b]5bit常量填充刚好凑齐1字节符合USB协议规范。报告格式Report ID为0总输入报告长度为4字节1字节按键 3字节坐标。对比思考通过解析可以看出鼠标的“相对位移”与Gamepad的“绝对位置”截然不同。此外原鼠标没有独立ID而在复合设备中改造为Gamepad时我们通常需要引入Report ID如0x01以便主机精准区分数据。3.用HIDDescBuilder设计Gamepad拖动左侧组件库中的模板与数据项组成GamePad结构包括X/Y方向和Button16。X、Y轴各占2 bitLogical Minimum/Maximum设为-1和1适合方向键Button16各占1 bit生成的HEX还包含6 bitConstant填充用于将数据补齐至2字节工具生成的报告描述符为48字节。输入报告由1字节Report ID2字节数据组成。设计完成后可直接复制C数组减少手工编写HID HEX 的工作。复制结果如下#include stdint.h static const uint8_t hidReportDescriptor[] { 0x05, 0x01, 0x09, 0x05, 0xA1, 0x01, 0x85, 0x01, 0x09, 0x01, 0xA1, 0x00, 0x09, 0x30, 0x09, 0x31, 0x15, 0xFF, 0x25, 0x01, 0x95, 0x02, 0x75, 0x02, 0x81, 0x02, 0xC0, 0x05, 0x09, 0x19, 0x01, 0x29, 0x06, 0x15, 0x00, 0x95, 0x06, 0x75, 0x01, 0x81, 0x02, 0x95, 0x01, 0x75, 0x06, 0x81, 0x03, 0xC0 }; static const unsigned int hidReportDescriptorSize sizeof(hidReportDescriptor);4.将生成结果接入固件首先修改接口描述符将原鼠标接口用途改为游戏手柄将其报告描述符长度wDescriptorLength更新为0x30即48字节再把工具导出的内容写入GamePad[]并准备3字节的 HIDGamepad[]发送缓冲区。键盘接口保持原样。接着在主机请求接口1的报告描述符时返回GamePad[]及其实际长度。这样电脑读取到的是新的Gamepad描述符。最后停用原鼠标报告函数新增DevHIDGamepadReport()将X/Y和六个按键状态打包到两个数据字节连同Report ID 0x01通过原接口的EP2 IN端点发送。5.无硬件环境下的实测验证当前使用的是一块CH572芯片板没有外接方向键和按钮。因此在主循环中定时调用DevHIDGamepadReport()让设备自动循环发送居中→左→居中→右→居中→上→居中→下等方向状态并模拟Button 1按下、释放。每个状态停留约0.8秒便于观察。重新编译、烧录并连接电脑后WCHUSBList显示键盘仍在原鼠标功能已被识别为HID游戏控制器HID-compliant game controller。接着打开Windows自带的joy.cpl游戏控制器测试工具进行验证观察到方向指示和按键指示灯按程序设定的顺序周期性变化完美验证了HID报告描述符与固件上报逻辑的正确性。6.总结通过这个案例我们完整体验了HIDDescBuilder从“反向解析HEX”到可视化设计描述符、导出C数组再到接入固件并通过joy.cpl验证设备识别的全过程。对于没有外设硬件的开发者使用软件模拟循环发送是快速验证USB通信和HID协议的绝佳方法。下一步你只需在此基础上接入实体的GPIO按键和ADC摇杆就能快速制作出一个专属的USB游戏控制器。