USB HID STM32

好的！在 STM32 上实现 USB HID (Human Interface Device) 功能，通常用于创建键盘、鼠标、游戏手柄、自定义控制面板等与主机（PC）交互的设备。以下是关键步骤和中文说明：

核心概念：

1. USB HID 协议： 一种标准化的 USB 设备类协议，定义了设备如何描述自身（报告描述符）以及如何传输数据（报告）。
2. 报告描述符： 一个复杂的二进制数据结构，精确描述设备发送和接收的数据格式（报告）。它定义了报告 ID、数据项（输入、输出、特性）、用途、逻辑/物理范围等。这是 HID 开发中最关键也最容易出错的部分。
3. 报告： 实际传输的数据包。分为：
   • 输入报告 (Input Report): 设备 -> 主机 (例如：按键状态、鼠标移动、传感器数据)。
   • 输出报告 (Output Report): 主机 -> 设备 (例如：LED 状态、电机控制、配置参数)。
   • 特性报告 (Feature Report): 双向传输，用于配置或获取设备特定信息。
4. STM32 USB 外设： STM32 微控制器通常内置 USB FS (Full Speed, 12 Mbps) 或 USB HS (High Speed, 480 Mbps，需要外部 PHY) 外设。
5. STM32CubeMX / HAL 库： ST 官方提供的图形化配置工具和硬件抽象层库，极大简化了 USB 和其他外设的初始化配置。

在 STM32 上实现 USB HID 的步骤：

1. 硬件准备：

   • 选择支持 USB 的 STM32 开发板 (如 STM32F103/4, STM32F0, STM32L4, STM32F7, STM32H7 等)。
   • 确保 USB 连接线（通常是 Micro-USB 或 USB-C）连接正确（DP/DM 引脚）。
   • 检查 VBUS 供电（自供电或总线供电）。

2. 软件环境：

   • 安装 STM32CubeMX。
   • 安装你选择的 IDE (如 Keil MDK-ARM, IAR Embedded Workbench, STM32CubeIDE)。
   • 安装对应的 STM32Cube 固件包 (例如 STM32CubeF4)。

3. 使用 STM32CubeMX 配置 USB HID：

   • 打开 CubeMX，创建新工程，选择你的 STM32 型号。
   • 在 Connectivity 或 USB 类别下启用 USB (OTG_FS 或 OTG_HS)。
   • 将 Mode 设置为 Device_Only。
   • 在 Middleware 部分，启用 USB_DEVICE。
   • 在 Class For FS IP 或 Class For HS IP 下拉菜单中，选择 Human Interface Device Class (HID)。
   • 配置描述符 (关键步骤！):
     • 在 Device Descriptor 标签页，填写厂商 ID (idVendor)、产品 ID (idProduct)、设备版本 (bcdDevice)、制造商字符串、产品字符串、序列号字符串等。这些信息会在设备管理器中显示。
     • 切换到 Configuration Descriptor 标签页。
     • 在 HID 子标签页下：
       • 设置 HID 设备类 (bDeviceSubClass 和 bDeviceProtocol)，通常 Boot 设备（如键盘鼠标）需要特定值，非 Boot 设备设为 0`。
       • 设置 HID 报告描述符大小 (HID_ReportDesc_Size)。这是下一步要定义的结构大小。
       • 设置 轮询间隔 (Polling Interval)，即主机查询设备请求数据的频率（毫秒）。
     • 在 HID_Mouse 或 HID_Keyboard 等预设模板标签页下（如果使用模板），可以快速生成标准设备的报告描述符。对于自定义 HID，通常需要手动编写报告描述符。
   • 配置时钟： 确保 USB 时钟 (48 MHz for FS) 正确配置。CubeMX 通常会自动处理，但需检查 RCC 设置。
   • 生成代码： 点击 GENERATE CODE，选择你的 IDE。

4. 编写/修改报告描述符 (自定义 HID 核心)：

   • CubeMX 生成的代码中，报告描述符通常定义在一个数组里，如 usbd_hid.c 文件中的 HID_MOUSE_ReportDesc 或 HID_CUSTOM_ReportDesc。
   • 如果你需要自定义 HID 设备（非标准鼠标键盘），必须修改这个数组。
   • 学习 HID 描述符语法： 参考官方文档 "Device Class Definition for HID 1.11" 和 "HID Usage Tables"。理解 USAGE_PAGE, USAGE, COLLECTION, INPUT, OUTPUT, FEATURE, REPORT_SIZE, REPORT_COUNT, LOGICAL_MINIMUM, LOGICAL_MAXIMUM 等关键项。
   • 使用工具： 在线 HID 描述符工具 (如 usb.org 的 HID Descriptor Tool) 或桌面工具可以帮助可视化和生成描述符代码。
   • 示例 (一个简单的自定义 HID，发送 4 字节输入报告)：

     /* 自定义 HID 报告描述符 */
     __ALIGN_BEGIN static uint8_t HID_CUSTOM_ReportDesc[23] __ALIGN_END = {
       0x06, 0x00, 0xFF,  // USAGE_PAGE (Vendor Defined 0xFF00)
       0x09, 0x01,        // USAGE (Vendor Usage 0x01)
       0xA1, 0x01,        // COLLECTION (Application)
       // 4 个 8 位的输入报告 (Data, Var, Abs)
       0x09, 0x02,        //   USAGE (Vendor Usage 0x02)
       0x15, 0x00,        //   LOGICAL_MINIMUM (0)
       0x26, 0xFF, 0x00,  //   LOGICAL_MAXIMUM (255)
       0x75, 0x08,        //   REPORT_SIZE (8)
       0x95, 0x04,        //   REPORT_COUNT (4)
       0x81, 0x02,        //   INPUT (Data,Var,Abs)
       0xC0               // END_COLLECTION
     };

     • 这个描述符定义了一个 Vendor 定义的设备，有一个包含 4 个字节的输入报告。每个字节范围是 0-255。
   • 更新大小： 确保在 CubeMX 配置中设置的 HID_ReportDesc_Size 与你实际定义的描述符数组大小一致。

5. 发送数据 (设备 -> 主机 - 输入报告)：

   • 在应用程序中，当你需要向主机发送数据（如按键按下、传感器读数）时，调用 HAL 库提供的发送函数。
   • 关键函数：USBD_HID_SendReport(USBD_HandleTypeDef *pdev, uint8_t *report, uint16_t len)
   • 参数：
     • pdev: USB 设备句柄 (通常在 usbd_conf.c 中定义为 hUsbDeviceFS 或 hUsbDeviceHS)。
     • report: 指向包含你要发送的报告数据的缓冲区指针。数据的格式必须严格匹配你在报告描述符中定义的结构！ 第一个字节通常是报告 ID (如果描述符中定义了 Report ID)。
     • len: 报告的长度（字节数），必须与描述符定义的长度一致。
   • 示例 (发送 4 字节数据):

     uint8_t my_report[4] = {0x01, 0xAA, 0x55, 0xF0}; // 示例数据
     if (USBD_HID_SendReport(&hUsbDeviceFS, my_report, sizeof(my_report)) != USBD_OK) {
       // 处理发送错误
     }

   • 注意： 这个函数是非阻塞的。它把数据放入 USB 发送缓冲区并立即返回。实际发送由 USB 中断在后台完成。确保不要过快地连续调用，需等待上一次发送完成（通过检查状态或使用回调）。

6. 接收数据 (主机 -> 设备 - 输出报告/特性报告)：

   • 主机发送的数据（如控制 LED、设置参数）通过 USB 中断到达。
   • HAL 库会在接收到数据后，调用你在 usbd_hid.c 中定义的弱函数 HID_OutEvent_FS (对于 FS) 或 HID_OutEvent_HS (对于 HS)。
   • 你需要重写这个函数：

     // 在 main.c 或你的应用文件中
     extern USBD_HandleTypeDef hUsbDeviceFS; // 声明外部变量
     void HID_OutEvent_FS(uint8_t event_idx, uint8_t state) {
       // 这个函数通常用于处理 SET_PROTOCOL, 可以忽略
     }
     // 真正处理输出报告的函数 (HAL 调用的弱函数)
     void HID_OutEvent_FS(uint8_t *report, uint16_t len) {
       // report: 指向接收到的输出报告数据的指针
       // len: 接收到的数据长度
       // 在这里解析和处理主机发来的数据 (report 数组)
       // 例如，根据 report[0] (报告ID) 和 report[1]... 控制 LED 或设置变量
       if (len > 0 && report[0] == REPORT_ID_LED_CONTROL) { // 假设报告ID为1
         GPIO_PinState led_state = (report[1] > 0) ? GPIO_PIN_SET : GPIO_PIN_RESET;
         HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, led_state);
       }
     }

     • 确保在 usbd_hid.c 中对应的 HID_OutEvent_FS 函数是 __weak 定义的，这样你的实现才会被链接。

7. 处理特性报告 (可选)：

   • 特性报告是双向的，用于配置或获取设备信息。
   • 发送特性报告使用 USBD_HID_SendReport（和输入报告一样，但报告 ID 需对应特性报告）。
   • 接收特性报告也是通过 HID_OutEvent_FS，需要根据报告 ID 区分是输出报告还是特性报告。
   • 处理主机通过控制传输 (GET_REPORT, SET_REPORT) 对特性报告的请求，通常在 usbd_hid.c 中的 USBD_HID_Setup 函数里实现。CubeMX 生成的代码通常有框架，你需要填充处理特定请求的逻辑。

8. 编译、下载与调试：

   • 编译 CubeMX 生成的工程代码。
   • 将程序下载到 STM32 开发板。
   • 将开发板通过 USB 连接到 PC。
   • 调试关键点：
     • 枚举： PC 是否能识别到设备？检查设备管理器（Windows）或 lsusb/dmesg (Linux)。如果枚举失败，检查：
       • USB 线缆和连接。
       • STM32 USB 时钟配置 (必须是精确的 48MHz for FS)。
       • USB DP (D+) 引脚是否需要外部 1.5K 上拉电阻（有些 STM32 内部集成，需在 CubeMX 中配置 Soft disconnect 和 Pull-up 选项）。
       • 描述符是否正确（尤其是报告描述符长度和内容）。这是最常见的问题！使用 USBlyzer 或 Wireshark (配合 USBPcap) 抓取 USB 枚举过程的数据包，查看设备返回的描述符内容。
     • 发送数据： 主机是否能收到数据？使用 HIDAPI (跨平台库), Bus Hound (Windows)，或编写简单的测试程序读取 HID 设备数据。
     • 接收数据： 设备是否能正确解析和执行主机发送的命令？在 HID_OutEvent_FS 中设置断点或打印调试信息。使用 HIDAPI 或测试程序向设备发送数据。
     • 报告描述符验证： 使用在线或离线工具验证你的报告描述符是否符合规范。

总结与建议：

1. CubeMX 是起点： 利用它完成底层 USB 和时钟的复杂初始化。
2. 报告描述符是核心： 花时间理解并正确编写报告描述符。这是定义设备行为和数据格式的关键。从简单示例开始，逐步完善。
3. 善用 HAL 函数： USBD_HID_SendReport 用于发送，HID_OutEvent_FS/HS 用于接收处理。
4. 调试工具必不可少： USB 协议分析器 (Bus Hound, Wireshark+USBPcap) 和 HID 测试工具 (HIDAPI) 是解决问题的利器。
5. 参考例程： STM32Cube 固件包中包含丰富的 USB HID 示例 (如 HID_Standalone)。仔细研究这些例程是快速上手的好方法。
6. 查阅文档： STM32 参考手册 (RM)、应用笔记 (AN)、以及 USB-IF 的 HID 规范文档是权威参考。

希望这份详细的中文指南能帮助你在 STM32 上成功开发 USB HID 设备！如果你有具体的 STM32 型号、遇到特定的问题或需要更详细的代码片段，请随时提问。