从零打造一个“免驱”自定义设备：HID协议实战全解析
你有没有遇到过这样的场景？
调试一块嵌入式板子，插上USB线后电脑弹出提示：“发现新硬件，正在安装驱动……” 然后等几十秒甚至更久，最后还失败了。或者你的工业控制器在客户现场无法识别，只因为对方用的是Linux系统，而你开发时只测试了Windows。
如果你厌倦了这些麻烦，HID协议或许就是你要找的答案。
为什么选择HID？一个键盘教会我们的事
想象一下：你买了一个机械键盘，插到一台从未见过的电脑上——无论是Windows、macOS、Linux还是Android平板，它几乎立刻就能打字。不需要装驱动，也不需要管理员权限。
这背后靠的不是魔法，而是HID（Human Interface Device）协议。
HID原本是为鼠标、键盘这类标准输入设备设计的USB子类规范，但它有一个被严重低估的能力：你可以用它来传输任意自定义数据。换句话说，哪怕你的设备根本不是“人机接口”，只要“长得像HID”，操作系统就会乖乖认它。
这意味着：
- ✅ 插上即用，无需安装驱动；
- ✅ 跨平台兼容性拉满；
- ✅ 可以直接用Python、C#、JavaScript读取数据；
- ✅ 还能用Wireshark抓包分析通信过程。
所以今天我们要做的，就是亲手做一个“伪装成键盘”的非键盘设备——但它上报的不是按键，而是按钮状态、旋钮位置、甚至是传感器数值。
HID是怎么工作的？拆开来看
USB枚举：设备的“自我介绍”
当一个USB设备插入主机时，并不会马上开始传数据。它首先要经历一个叫枚举（Enumeration）的流程：
- 主机问：“你是谁？” → 请求设备描述符；
- 设备答：“我是一个HID设备。” → 返回
bDeviceClass = 0x03； - 主机再问：“你的功能是什么？” → 读取HID描述符；
- 主机接着问：“你发的数据长什么样？” → 获取并解析报告描述符（Report Descriptor）；
- 最后，驱动加载完成，进入正常通信。
这个过程中最关键的一步，就是报告描述符。它是整个HID协议中最核心也最容易踩坑的部分。
💡 类比理解：如果把HID通信比作寄快递，那么报告描述符就是“打包说明书”——告诉收件方每个包裹里有什么、多大、怎么拆。
报告描述符：HID的灵魂所在
很多人学HID学到一半放弃，就是因为卡在了这一关：一堆十六进制数，看起来像天书。
比如这段代码：
0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x06, // Usage (Keyboard) 0xA1, 0x01, // Collection (Application) ...别慌，我们来把它“翻译”成人话。
报告描述符的本质
它是一串紧凑编码的“元数据”，用来定义你的设备会发送哪些数据、每项占多少位、代表什么意思。主机靠它来自动解析后续收到的每一个字节。
它的结构由三种类型的“项目项”组成：
| 类型 | 作用 |
|---|---|
| Global Items | 全局设定，如字段大小、数量、数值范围 |
| Local Items | 局部属性，如用途（Usage）、标签 |
| Main Items | 数据声明，如Input、Output、Feature |
关键字段详解
| 字段 | 含义 | 示例说明 |
|---|---|---|
Report Size | 每个数据字段的位宽（bit） | 0x75, 0x08表示8位（1字节） |
Report Count | 字段的数量 | 0x95, 0x06表示有6个这样的字段 |
Logical Minimum/Maximum | 数据的逻辑取值范围 | 如0~255表示无符号字节 |
Usage Page和Usage | 定义用途类别 | 0x01是通用桌面设备，0x06是键盘 |
Input,Output,Feature | 声明数据流向和属性 | 0x81, 0x02表示可变输入 |
⚠️常见陷阱：
如果你设置了Report Size = 1,Report Count = 10，总共是10 bit，不能被8整除。这样会导致最后一个字节“跨包”，主机可能解析错位，造成数据混乱。
✅解决方法：补足到最近的字节边界。例如加一个Report Size=6, Report Count=1作为填充。
动手写一个自定义按钮设备的描述符
假设我们想做一个设备，能上报两个按钮的状态（按下/释放），并且接收主机指令点亮一个LED。
我们可以这样设计输入报告：
- 第1字节：按钮1状态（0或1）
- 第2字节：按钮2状态（0或1）
输出报告：
- 第1字节：LED控制（bit0 控制红灯）
对应的描述符如下：
const uint8_t hid_report_descriptor[] = { 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x00, // Usage (Undefined) 0xA1, 0x01, // Collection (Application) // 输入：两个按钮状态 0x75, 0x08, // Report Size = 8 bits 0x95, 0x02, // Report Count = 2 0x15, 0x00, // Logical Minimum = 0 0x25, 0x01, // Logical Maximum = 1 0x05, 0x09, // Usage Page (Button) 0x19, 0x01, // Usage Minimum = Button 1 0x29, 0x02, // Usage Maximum = Button 2 0x81, 0x02, // Input (Data, Variable, Absolute) // 输出：LED控制 0x75, 0x08, // Report Size = 8 0x95, 0x01, // Report Count = 1 0x15, 0x00, 0x25, 0x01, 0x05, 0x08, // LED Page 0x19, 0x01, 0x29, 0x01, 0x91, 0x02, // Output (Data, Var, Abs) 0xC0 // End Collection };这段描述符告诉主机：“我会发两个字节的输入数据，每个代表一个按钮；你也随时可以给我发一个字节来控制LED。”
🛠 小贴士：可以用 USB.org 提供的 HID 工具 或在线生成器验证语法是否正确。
在STM32上跑起来：HAL库实战
我们以STM32F4 + STM32CubeMX + HAL库为例，展示如何快速搭建一个HID设备。
步骤一：配置USB外设
- 打开STM32CubeMX，选择芯片型号；
- 启用
USB_OTG_FS，工作模式选为Device Only； - 在Middleware中添加
USB_DEVICE，类别选为Custom HID； - 生成代码。
此时，HAL已经为你准备好了基本框架，包括：
- USB中断处理
- 控制端点0的基础响应
-USBD_CUSTOM_HID_SendReport()发送函数
步骤二：替换默认描述符
找到文件usbd_custom_hid.c，修改宏定义：
__ALIGN_BEGIN static uint8_t CUSTOM_HID_ReportDesc_FS[USBD_CUSTOM_HID_REPORT_DESC_SIZE] __ALIGN_END = { // 替换为我们上面写的那个描述符 0x05, 0x01, 0x09, 0x00, 0xA1, 0x01, 0x75, 0x08, 0x95, 0x02, 0x15, 0x00, 0x25, 0x01, 0x05, 0x09, 0x19, 0x01, 0x29, 0x02, 0x81, 0x02, 0x75, 0x08, 0x95, 0x01, 0x15, 0x00, 0x25, 0x01, 0x05, 0x08, 0x19, 0x01, 0x29, 0x01, 0x91, 0x02, 0xC0 };步骤三：发送数据
编写一个函数，定期上报按钮状态：
void send_button_states(uint8_t btn1, uint8_t btn2) { uint8_t report[2]; report[0] = btn1; report[1] = btn2; if (USBD_OK == USBD_CUSTOM_HID_SendReport(&hUsbDeviceFS, report, 2)) { // 发送成功 } }主循环中检测GPIO变化即可：
while (1) { uint8_t b1 = HAL_GPIO_ReadPin(BTN1_GPIO_Port, BTN1_Pin); uint8_t b2 = HAL_GPIO_ReadPin(BTN2_GPIO_Port, BTN2_Pin); static uint8_t last_b1 = 1, last_b2 = 1; if (b1 != last_b1 || b2 != last_b2) { send_button_states(!b1, !b2); // 注意电平反转 last_b1 = b1; last_b2 = b2; } HAL_Delay(10); // 防抖+限频 }接收主机命令（LED反馈）
你需要重写回调函数来处理Output Report：
int8_t USBD_CUSTOM_HID_OutEvent_FS(uint8_t event_idx, uint8_t state) { // event_idx: Report ID（本例为0） // state: 收到的数据（即LED状态） if (state & 0x01) { HAL_GPIO_WritePin(LED_RED_GPIO_Port, LED_RED_Pin, GPIO_PIN_SET); } else { HAL_GPIO_WritePin(LED_RED_GPIO_Port, LED_RED_Pin, GPIO_PIN_RESET); } return 0; }现在，主机只要下发一个字节（如0x01），你的MCU就会点亮红灯！
实际应用场景：工业面板也能“即插即用”
设想一个工厂里的操作台，上面有一堆按钮、旋钮、指示灯。传统做法是通过RS485或CAN总线连接PLC，协议私有，调试困难。
换成HID方案后：
[按钮/编码器] ↓ [STM32采集] ↓ 封装为HID Input Report ↓ USB → PC/HMI软件（Python/C#） ↓ 触发动作 / 更新UI ↑ ← 下发Output Report ←优势非常明显：
- 上位机程序可以直接用hidapi库读取设备状态；
- 不需要管理员权限，适合部署在工控机；
- 更换设备无需重新安装驱动；
- 可热插拔，支持多设备动态识别；
- 数据格式清晰，便于日志记录与故障回溯。
避坑指南：那些年我们掉过的“坑”
❌ 枚举失败？检查这几个地方
描述符长度不匹配
确保CUSTOM_HID_ReportDesc_FS数组大小与USBD_CUSTOM_HID_REPORT_DESC_SIZE一致。电源问题
USB只能提供500mA电流。如果你接了多个LED或传感器，记得计算功耗，必要时外接供电。差分信号走线不良
D+ 和 D− 必须走90Ω差分阻抗，尽量等长，远离高频噪声源。频繁发送导致拥堵
USB中断传输有带宽限制。建议轮询间隔不低于1ms，避免连续调用SendReport。
✅ 最佳实践建议
| 项目 | 建议 |
|---|---|
bInterval | 设置为1~10ms，平衡实时性与负载 |
| VID/PID | 使用自定义唯一值（如VID=0x1234, PID=0x5678） |
| 多功能设备 | 使用Report ID区分不同类型报告 |
| 固件升级 | 预留DFU模式切换入口（如长按按钮进入Bootloader） |
| 安全性 | 避免模拟键盘输入打开命令行，防止被防病毒软件拦截 |
能不能不用STM32？当然可以！
虽然本文以STM32为例，但HID并不依赖特定平台。以下方案同样可行：
- ESP32-S2/S3：内置USB OTG，支持TinyUSB栈，可用Arduino或ESP-IDF开发；
- RP2040（树莓派Pico）：官方提供完整的TinyUSB示例，几分钟就能跑起HID；
- nRF52系列（Nordic）：支持USB和Bluetooth HID双模，适合无线场景；
- Linux单板机（如树莓派Zero）：可通过gadgetfs模拟HID设备。
特别是TinyUSB开源协议栈，已经成为轻量级HID实现的事实标准，支持数十种MCU，文档完善，社区活跃。
写在最后：HID不只是“键盘鼠标”
HID的强大之处在于它的“伪装能力”。只要你能让设备“看起来像个标准输入设备”，操作系统就会对你敞开大门。
它可以是：
- 一个自定义游戏手柄
- 一台医疗仪器的操作面板
- 一个智能家居控制旋钮
- 甚至是一个艺术装置的交互接口
掌握HID，你就掌握了通往“免驱世界”的钥匙。
下次当你又要搞串口通信的时候，不妨停下来想想：能不能改成HID？
也许答案是——完全可以，而且更好用。
如果你正在做类似的项目，欢迎留言交流经验。也可以分享你在实际开发中遇到的奇葩问题，我们一起排雷。
