Zephyr USB HID设备驱动开发完整示例分享

手把手教你用 Zephyr 实现 USB HID 设备：从零开始的完整实战

你有没有试过把一块 STM32 或 nRF52 开发板插到电脑上，让它像键盘一样自动输入“Hello World”？或者做一个自定义游戏手柄，不装驱动就能即插即用？这背后靠的就是USB HID 协议和嵌入式系统的完美配合。

在物联网和智能硬件快速发展的今天，人机交互（HMI）不再是大厂专属。借助像Zephyr这样的开源实时操作系统，我们完全可以用几千行代码，在资源受限的小设备上实现专业级的 USB 输入功能。

本文将带你从工程创建到实际运行，一步步搭建一个基于 Zephyr 的 USB HID 设备，重点解决新手最容易踩坑的几个关键问题：
- 如何正确配置 Kconfig 让 USB 功能真正启用？
- 报告描述符到底怎么写才不会被 macOS 拒之门外？
- 为什么连续发送数据会丢包？该怎么避免？

全程无死角拆解，连最底层的端点传输机制也会讲清楚。准备好了吗？让我们开始吧。

先搞明白：HID 到底是个啥？

很多人以为“HID 就是键盘鼠标”，其实它比你想得更灵活。HID 的全称是Human Interface Device，但它并不仅限于传统外设——只要你能定义清楚“数据代表什么”，任何传感器、控制器都可以通过 HID 协议传给主机。

它的核心优势在于：

✅免驱支持：Windows/Linux/macOS/Android 都内置了标准 HID 驱动
✅低延迟通信：使用中断传输，最快每 1ms 发送一次数据
✅结构可定制：通过报告描述符自由定义数据格式

比如你可以让一个温湿度传感器伪装成“系统控制类设备”，上报环境异常事件；也可以让工业按钮面板模拟成多媒体快捷键。这就是 HID 的魔力。

而这一切的关键，就是那个看起来像天书一样的——报告描述符（Report Descriptor）。

⚠️ 注意：如果主机识别不了你的设备，90% 的问题是出在报告描述符语法错误或逻辑不合理。

Zephyr 怎么玩转 USB？三层架构一图看懂

Zephyr 对 USB 的支持不是简单封装一堆函数，而是有一套清晰的分层设计。理解这个结构，才能避免“改了配置没生效”这类低级失误。

+------------------------+ | Application | ← 你的业务逻辑（按键扫描、状态更新） +------------------------+ ↓ +------------------------+ | Class Driver (HID) | ← 构造 HID 描述符，处理报告收发 +------------------------+ ↓ | USB Device Stack | ← 协议栈核心：枚举、SETUP 包解析、端点管理 +------------------------+ ↓ | SoC USB Controller | ← 芯片级驱动（如 stm32_usbd, nrfx_usbd） +------------------------+

每一层各司其职：
- 最下层对接硬件寄存器
- 中间层处理 USB 协议细节
- 上层提供类设备接口（HID/CDC/MSC）
- 应用层只关心“我要发什么”

这种抽象让你换平台时几乎不用改代码。STM32 上跑通的 HID 驱动，移植到 nRF52840 只需调整 devicetree 配置即可。

关键配置一步不能少：Kconfig 是启动钥匙

很多开发者第一步就卡住了：明明写了代码，dmesg却看不到设备插入日志。原因往往是USB 子系统根本没打开。

Zephyr 使用 Kconfig 系统进行编译时裁剪，以下这几个选项必须显式启用：

CONFIG_USB_DEVICE_STACK=y CONFIG_USB_HID=y CONFIG_USB_HID_DEVICE=y CONFIG_USB_COMPOSITE_DEVICE=n # 单一功能先关掉复合模式 CONFIG_USB_REQUEST_BUFFER_SIZE=64 CONFIG_USB_REQUEST_DATA_SIZE=64

如果你打算做键盘或鼠标，还可以直接启用预设模板简化开发：

CONFIG_USB_HID_KEYBOARD=y # 自动生成键盘描述符 # 或 CONFIG_USB_HID_MOUSE=y # 自动生成鼠标描述符

但如果你想做自定义设备（比如带旋钮的控制台），就必须自己写报告描述符——这才是真正的硬核部分。

自定义报告描述符实战：让电脑认识你的“新设备”

假设我们要做一个“多功能控制面板”，包含：
- 6 个可编程按键
- 1 个编码器（旋钮）
- 3 个状态指示灯（由主机控制）

我们需要构造一段二进制描述符，告诉主机：“我有这些数据，它们长这样”。

下面是手写的 HID 报告描述符（以 C 数组形式嵌入代码）：

__aligned(4) static const uint8_t hid_report_desc[] = { 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x05, // Usage (Joystick) 0xA1, 0x01, // Collection (Application) // --- Input Report --- 0x85, 0x01, // Report ID (1) 0x75, 0x01, // Report Size: 1 bit 0x95, 0x18, // Report Count: 24 bits = 3 bytes 0x15, 0x00, // Logical Minimum: 0 0x25, 0x01, // Logical Maximum: 1 0x05, 0x09, // Usage Page: Buttons 0x19, 0x01, // Usage Minimum: Button 1 0x29, 0x18, // Usage Maximum: Button 24 0x81, 0x02, // Input (Data, Variable, Absolute) // 编码器增量（signed byte） 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x30, // Usage (X) 0x15, 0x81, // Logical Min (-127) 0x25, 0x7F, // Logical Max (127) 0x75, 0x08, // Report Size: 8 0x95, 0x01, // Report Count: 1 0x81, 0x06, // Input (Data, Variable, Relative) // --- Output Report (LEDs) --- 0x85, 0x02, // Report ID (2) 0x75, 0x01, // Report Size: 1 0x95, 0x03, // Report Count: 3 LEDs 0x15, 0x00, 0x25, 0x01, 0x05, 0x08, // Usage Page (LEDs) 0x19, 0x01, // Usage Minimum: Num Lock 0x29, 0x03, // Usage Maximum: Scroll Lock 0x91, 0x02, // Output (Data, Variable, Absolute) // 填充位 0x95, 0x05, 0x91, 0x01, 0xC0 // End Collection };

📌 解读要点：
-0x85, 0x01表示接下来的数据属于Report ID 1
- 按钮用了Input (Variable)，每个 bit 代表一个按键状态
- 编码器是相对值输入，用Relative标记
- LED 控制走Output Report，主机下发，设备接收

💡 小技巧：可以用 HID Descriptor Tool 反向验证生成的描述符是否合法。

驱动初始化三步走：注册 → 绑定 → 启动

Zephyr 提供了一套简洁的 API 来操作 HID 设备。整个流程就像“挂号看病”：先登记身份，再约好回调，最后开机营业。

第一步：定义设备实例

static struct usb_hid hid_dev;

第二步：设置回调函数

当数据成功发出或收到主机命令时，系统会调用这些函数：

static void report_sent_cb(const struct device *dev, struct usb_hid *hid, int status) { if (status) { LOG_ERR("Send failed: %d", status); } atomic_set(&can_send, 1); // 允许下次发送 } static void report_received_cb(const struct device *dev, struct usb_hid *hid, uint8_t report_id, uint8_t *data, uint32_t len) { LOG_INF("Got output report ID %u, len=%u", report_id, len); if (report_id == 2 && len >= 1) { update_leds(data[0] & 0x07); // 控制前3个LED } }

第三步：绑定并启动

static struct hid_ops ops = { .sent_cb = report_sent_cb, .received_cb = report_received_cb, }; void usb_hid_init(void) { usb_hid_register_device(&hid_dev, hid_report_desc, sizeof(hid_report_desc), &ops); usb_hid_init(&hid_dev); // 等待连接 while (!device_is_ready(hid_dev.dev)) { k_msleep(100); } LOG_INF("HID device ready"); }

注意：usb_hid_init()不会阻塞，设备是否上线取决于主机是否完成枚举。

数据发送别踩坑：中断端点不是你想发就能发

这是新手最常见的问题：连续按几次按钮，电脑只响应一次。原因是USB 中断端点在同一时刻只能挂一个传输请求。

如果你前一条还没发完就急着发下一条，hid_int_ep_write()会返回-EBUSY，数据直接被丢弃。

正确的做法是在回调中释放“发送许可”：

static atomic_t can_send = 1; int send_input_report(uint8_t *buf, size_t len) { if (!atomic_get(&can_send)) { return -EAGAIN; // 正忙，稍后再试 } int ret = hid_int_ep_write(&hid_dev, buf, len, NULL); if (ret == 0) { atomic_set(&can_send, 0); // 锁定，等待回调解锁 } return ret; }

这样就能保证每次发送都落地生效。

复合设备进阶玩法：HID + CDC 二合一

有些场景需要同时具备“输入能力”和“调试通道”。比如一个工业面板既要模拟快捷键，又要输出日志供维护人员查看。

Zephyr 支持复合设备（Composite Device），只需开启：

CONFIG_USB_COMPOSITE_DEVICE=y CONFIG_UART_CONSOLE=y CONFIG_CDC_ACM=y

然后在应用中同时注册两个类设备：

usb_hid_register_device(...); cdc_acm_register(); usb_hid_init(&hid_dev);

烧录后你会发现设备在电脑上显示为两个接口：
- 一个是 HID Joystick
- 一个是 CDC Serial Port

串口可用于调试输出，HID 负责主功能，互不干扰。

调试秘籍：Linux 下快速验证 HID 设备

别总盯着串口打印，直接看主机侧反应才是王道。推荐几个实用工具：

1. 查看设备枚举信息

dmesg | tail -20

正常应看到类似：

usb 1-2: new full-speed USB device number 4 using xhci_hcd hid-generic 0003:1234:0002.0004: input,hidraw3: USB HID v1.11 Device [My Custom HID Panel] on usb-0000:00:14.0-2/input0

2. 抓取原始 HID 报告

sudo hexdump -C /dev/hidraw3

按下按键时应该能看到数据变化。

3. 查看描述符内容

sudo usbhid-dump -d 1234:0002 -e

输出的是完整的描述符十六进制流，可用于对比预期值。

结尾彩蛋：如何让设备休眠省电？

电池供电设备不能一直狂刷中断。可以结合 USB 挂起（Suspend）机制降低功耗：

#if defined(CONFIG_USB_SUSPEND_RESUME) static void usb_status_cb(struct usb_cfg_data *cfg, enum usb_dc_status_code status, const uint8_t *param) { switch (status) { case USB_DC_SUSPEND: LOG_INF("USB suspended, entering low power mode"); enter_low_power_mode(); break; case USB_DC_RESUME: LOG_INF("USB resumed"); exit_low_power_mode(); break; } } #endif

记得在DEVICE_CONFIG中注册这个回调。设备进入 Suspend 后电流可降至微安级，非常适合穿戴设备。

掌握了这套方法论，你已经具备开发专业 HID 设备的能力。无论是做个复古游戏手柄、自动化测试脚本触发器，还是工业级控制终端，都不再是难题。

如果你也在用 Zephyr 做 USB 开发，欢迎留言交流遇到的奇葩问题。下期我们可以聊聊如何用 ZMK 框架打造自己的蓝牙机械键盘固件—— 同样基于 Zephyr，同样精彩。