从零到实战：基于CH582和CherryUSB打造一个自定义HID设备（键盘/鼠标）
从零到实战：基于CH582和CherryUSB打造自定义HID设备
在创客和嵌入式开发领域，自定义HID（人机接口设备）的需求日益增长。无论是打造一款带有宏功能的机械键盘，还是开发一个基于手势识别的空气鼠标，CH582微控制器配合CherryUSB协议栈的组合，为开发者提供了快速实现创意的可能。本文将带你从零开始，完成一个完整HID设备的开发流程。
1. 开发环境搭建与硬件准备
CH582是沁恒微电子推出的一款集成USB功能的ARM Cortex-M0微控制器，内置蓝牙5.3和丰富的外设资源。要开始我们的HID设备开发之旅，首先需要准备好以下硬件和软件环境：
硬件清单：
- CH582开发板（如CH582F评估板）
- USB Type-C或Micro USB连接线
- 按键模块（用于键盘功能测试）
- 加速度传感器模块（可选，用于鼠标功能）
软件工具准备：
- Keil MDK或IAR Embedded Workbench开发环境
- WCH官方提供的CH582 SDK包
- CherryUSB协议栈（可从GitHub获取最新版本）
- USB分析工具（如Wireshark或USBlyzer）
安装完开发环境后，我们需要在项目中集成CherryUSB协议栈。这里有一个简单的目录结构示例：
project_root/ ├── CH582_SDK/ # WCH官方SDK ├── CherryUSB/ # 协议栈核心代码 ├── Drivers/ # 硬件驱动 ├── Inc/ # 项目头文件 └── Src/ # 项目源文件提示：确保在项目设置中正确包含所有必要的头文件路径，特别是CherryUSB的核心头文件和CH582的USB驱动头文件。
2. CherryUSB协议栈基础配置
CherryUSB是一个轻量级的USB协议栈，特别适合资源有限的嵌入式设备。要将其适配到CH582平台，需要进行一些基础配置。
首先，我们需要修改usb_config.h文件，启用HID类支持：
#define CONFIG_USB_DEVICE_HID #define CONFIG_USB_DEVICE_HID_NUM 1 // 我们只需要一个HID接口接下来，配置USB设备描述符。在usbd_desc.c中定义设备的基本信息：
const uint8_t usbd_device_descriptor[] = { 0x12, // bLength 0x01, // bDescriptorType (Device) 0x0110, // bcdUSB (USB 1.1) 0x00, // bDeviceClass 0x00, // bDeviceSubClass 0x00, // bDeviceProtocol 0x40, // bMaxPacketSize0 (64 bytes) 0x0483, // idVendor (示例VID) 0x5750, // idProduct (示例PID) 0x0100, // bcdDevice 0x01, // iManufacturer 0x02, // iProduct 0x03, // iSerialNumber 0x01 // bNumConfigurations };对于HID设备，最关键的是HID描述符和报告描述符的配置。下面是一个简单的键盘HID描述符示例：
const uint8_t hid_keyboard_descriptor[] = { // HID描述符 0x09, // bLength 0x21, // bDescriptorType (HID) 0x0110, // bcdHID 0x00, // bCountryCode 0x01, // bNumDescriptors 0x22, // bDescriptorType (Report) sizeof(hid_keyboard_report_descriptor), 0x00, // wDescriptorLength // 报告描述符 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x06, // Usage (Keyboard) 0xA1, 0x01, // Collection (Application) // ... 更多报告描述符内容 };3. HID报告描述符深度解析
报告描述符是HID设备与主机通信的核心，它定义了设备能够发送和接收的数据格式。让我们深入解析一个完整的键盘报告描述符：
const uint8_t hid_keyboard_report_descriptor[] = { 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x06, // Usage (Keyboard) 0xA1, 0x01, // Collection (Application) // 修饰键 (Ctrl, Shift, Alt等) 0x05, 0x07, // Usage Page (Key Codes) 0x19, 0xE0, // Usage Minimum (Left Control) 0x29, 0xE7, // Usage Maximum (Right GUI) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x01, // Logical Maximum (1) 0x75, 0x01, // Report Size (1) 0x95, 0x08, // Report Count (8) 0x81, 0x02, // Input (Data, Variable, Absolute) // 保留字节 0x95, 0x01, // Report Count (1) 0x75, 0x08, // Report Size (8) 0x81, 0x01, // Input (Constant) // 按键码 0x95, 0x06, // Report Count (6) 0x75, 0x08, // Report Size (8) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x65, // Logical Maximum (101) 0x05, 0x07, // Usage Page (Key Codes) 0x19, 0x00, // Usage Minimum (0) 0x29, 0x65, // Usage Maximum (101) 0x81, 0x00, // Input (Data, Array) 0xC0 // End Collection };这个描述符定义了一个标准的键盘报告格式，包含：
- 8个1位的修饰键（Ctrl、Shift、Alt等）
- 1个8位的保留字段
- 6个8位的按键码（最多可同时报告6个按键）
对于鼠标设备，报告描述符会有所不同。下面是一个简单的鼠标报告描述符示例：
const uint8_t hid_mouse_report_descriptor[] = { 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x02, // Usage (Mouse) 0xA1, 0x01, // Collection (Application) // 按键 0x05, 0x09, // Usage Page (Button) 0x19, 0x01, // Usage Minimum (Button 1) 0x29, 0x03, // Usage Maximum (Button 3) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x01, // Logical Maximum (1) 0x95, 0x03, // Report Count (3) 0x75, 0x01, // Report Size (1) 0x81, 0x02, // Input (Data, Variable, Absolute) // 填充5位 0x95, 0x01, // Report Count (1) 0x75, 0x05, // Report Size (5) 0x81, 0x01, // Input (Constant) // X/Y轴移动 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x30, // Usage (X) 0x09, 0x31, // Usage (Y) 0x15, 0x81, // Logical Minimum (-127) 0x25, 0x7F, // Logical Maximum (127) 0x75, 0x08, // Report Size (8) 0x95, 0x02, // Report Count (2) 0x81, 0x06, // Input (Data, Variable, Relative) 0xC0 // End Collection };4. CH582 USB硬件层配置
CH582的USB外设需要正确初始化才能与CherryUSB协议栈协同工作。以下是关键的初始化步骤：
- 时钟配置：
void USB_Clock_Init(void) { R8_USB_CTRL = RB_UC_CLR_ALL; R8_USB_CTRL = RB_UC_RESET_SIE | RB_UC_CLR_ALL; DelayMs(10); R8_USB_CTRL = 0; // 配置USB时钟 R8_CK32K_CONFIG |= RB_CLK_USB_EN | RB_CLK_OSC32K_EN; R8_USB_CTRL |= RB_UC_DEV_PU_EN; }- 端点配置：
void USB_EP_Init(void) { // 配置端点0（控制端点） R8_UEP0_CTRL = UEP_R_RES_ACK | UEP_T_RES_NAK; R16_UEP0_DMA = (uint16_t)(uint32_t)Ep0Buffer; R8_UEP0_T_LEN = 0; // 配置HID中断端点（端点1输入） R8_UEP1_CTRL = UEP_R_RES_ACK | UEP_T_RES_NAK; R16_UEP1_DMA = (uint16_t)(uint32_t)HIDReportBuffer; R8_UEP1_T_LEN = sizeof(HIDReportBuffer); // 启用端点中断 R8_USB_INT_EN |= RB_UIE_SETUP_ACT | RB_UIE_TRANSFER; }- 中断处理：
void USB_IRQHandler(void) { uint8_t int_status = R8_USB_INT_ST; if(int_status & RB_UIS_SETUP_ACT) { // 处理SETUP包 USB_HandleSetupPacket(); R8_USB_INT_FG = RB_UIS_SETUP_ACT; } if(int_status & RB_UIS_TRANSFER) { uint8_t ep_status = R8_USB_INT_ST & MASK_UIS_TOKEN; switch(ep_status) { case UIS_TOKEN_IN: // 处理IN令牌 if(R8_USB_INT_ST & RB_UIS_TOG_OK) { USB_HandleInToken(); } break; case UIS_TOKEN_OUT: // 处理OUT令牌 if(R8_USB_INT_ST & RB_UIS_TOG_OK) { USB_HandleOutToken(); } break; } R8_USB_INT_FG = RB_UIS_TRANSFER; } }5. 自定义HID设备实现
现在，我们将实现一个具体的HID设备示例——一个带有额外功能键的宏键盘。这个键盘除了标准按键外，还有三个可编程的宏键。
键盘功能实现步骤：
- 定义报告数据结构：
typedef struct { uint8_t modifiers; // 修饰键 uint8_t reserved; // 保留字节 uint8_t keys[6]; // 按键码 uint8_t macro_keys; // 我们的自定义宏键（3位） } KeyboardReport;- 修改报告描述符以包含宏键：
const uint8_t hid_keyboard_report_descriptor[] = { // ... 标准键盘描述符部分 // 添加宏键 0x05, 0x0C, // Usage Page (Consumer) 0x19, 0x01, // Usage Minimum (Consumer Control) 0x29, 0x03, // Usage Maximum (3个自定义功能) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x01, // Logical Maximum (1) 0x75, 0x01, // Report Size (1) 0x95, 0x03, // Report Count (3) 0x81, 0x02, // Input (Data, Variable, Absolute) // 填充5位 0x95, 0x01, // Report Count (1) 0x75, 0x05, // Report Size (5) 0x81, 0x01, // Input (Constant) // ... 其余部分 };- 实现按键扫描和报告生成：
void GenerateKeyboardReport(void) { static KeyboardReport report = {0}; // 扫描物理按键 report.modifiers = ScanModifierKeys(); ScanNormalKeys(report.keys); // 扫描宏键 report.macro_keys = 0; if(IsMacroKey1Pressed()) report.macro_keys |= 0x01; if(IsMacroKey2Pressed()) report.macro_keys |= 0x02; if(IsMacroKey3Pressed()) report.macro_keys |= 0x04; // 发送报告 USBD_HID_SendReport(&report, sizeof(report)); }对于空气鼠标的实现，我们可以使用CH582内置的ADC读取加速度传感器数据：
void GenerateMouseReport(void) { int8_t x_movement = 0, y_movement = 0; uint8_t buttons = 0; // 读取加速度传感器数据 int16_t x_accel = ReadAccelerometerX(); int16_t y_accel = ReadAccelerometerY(); // 转换为鼠标移动量 x_movement = (int8_t)(x_accel / 64); // 适当缩放 y_movement = (int8_t)(y_accel / 64); // 限制范围 x_movement = (x_movement < -127) ? -127 : (x_movement > 127) ? 127 : x_movement; y_movement = (y_movement < -127) ? -127 : (y_movement > 127) ? 127 : y_movement; // 读取按键状态 if(IsLeftButtonPressed()) buttons |= 0x01; if(IsRightButtonPressed()) buttons |= 0x02; // 构造报告 uint8_t report[4] = {buttons, x_movement, y_movement, 0}; // 发送报告 USBD_HID_SendReport(report, sizeof(report)); }6. 调试与优化技巧
开发HID设备时，调试是一个重要环节。以下是一些实用的调试技巧：
常见问题排查表：
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 设备无法被识别 | 描述符错误 | 使用USB分析工具检查描述符 |
| 按键无响应 | 报告格式不匹配 | 检查报告描述符与实际发送的数据 |
| 设备频繁断开 | 电源不足 | 检查供电，必要时使用外部电源 |
| 移动不流畅 | 采样率太低 | 提高报告发送频率 |
性能优化建议：
- 报告频率优化：
// 设置10ms的报告间隔 #define HID_REPORT_INTERVAL 10 void TIM2_IRQHandler(void) { static uint32_t tick = 0; if(++tick >= HID_REPORT_INTERVAL) { tick = 0; GenerateInputReport(); } }- 电源管理：
void EnterLowPowerMode(void) { // 当无用户交互时进入低功耗模式 if(!AnyKeyPressed()) { R8_SLP_POWER_CTRL |= RB_SLP_USB_SUSPEND; R8_POWER_CTRL |= RB_PWR_USB_SUSPEND; } }- 使用DMA提高效率：
void USB_DMA_Config(void) { // 配置USB端点DMA R16_UEP1_DMA = (uint16_t)(uint32_t)HIDReportBuffer; R8_UEP1_T_LEN = sizeof(HIDReportBuffer); R8_UEP1_CTRL = UEP_R_RES_ACK | UEP_T_RES_NAK | UEP_T_TOG; // 启用DMA完成中断 R8_USB_INT_EN |= RB_UIE_DMA_END; }在实际项目中，我发现合理设置报告间隔对用户体验影响很大。对于键盘设备，20-30ms的报告间隔通常足够；而对于鼠标或游戏手柄，建议将报告间隔缩短到10ms以内以获得更流畅的操作体验。