基于CherryUSB的HID设备开发：键盘鼠标实例教程

【免费下载链接】CherryUSB CherryUSB is a tiny and portable USB Stack (device & host) for embedded system with USB IP 项目地址: https://gitcode.com/gh_mirrors/ch/CherryUSB

CherryUSB是一个适用于嵌入式系统的轻量级USB协议栈，支持设备和主机模式。本教程将以键盘和鼠标为例，详细介绍如何使用CherryUSB开发HID（人机接口设备）应用，帮助新手快速掌握嵌入式USB设备开发技巧。

HID设备开发基础

HID设备是计算机与用户交互的重要桥梁，常见的键盘、鼠标、游戏手柄等都属于HID设备范畴。CherryUSB提供了完善的HID类协议支持，通过简单的API调用即可实现标准HID设备功能。

在CherryUSB中，HID设备开发主要涉及以下核心文件：

• HID类驱动：class/hid/usbd_hid.c
• HID设备描述符：class/hid/usb_hid.h
• 示例模板：demo/hid_keyboard_template.c 和 demo/hid_mouse_template.c

HID报告描述符

HID设备通过报告描述符定义数据格式，这是HID设备开发的关键。CherryUSB提供了标准的键盘和鼠标报告描述符宏定义，位于usb_hid.h中，开发者无需手动编写复杂的描述符结构。

开发环境准备

在开始开发前，请确保已完成以下准备工作：

1. 获取源码

git clone https://gitcode.com/gh_mirrors/ch/CherryUSB

2. 选择硬件平台 CherryUSB支持多种嵌入式平台，包括STM32、ESP32、CH32等。不同平台的USB控制器驱动位于port/目录下，例如：

• STM32平台：port/dwc2/
• ESP32平台：port/dwc2/usb_glue_esp.c

3. 配置工具链 根据目标平台配置相应的交叉编译工具链，具体可参考官方文档：docs/en/quick_start/start.rst

图：CherryUSB开发环境配置界面

键盘设备开发实例

1. 基本结构

键盘示例代码位于demo/hid_keyboard_template.c，主要包含以下几个部分：

• 设备描述符：定义USB设备基本信息（厂商ID、产品ID等）
• 配置描述符：定义HID接口和端点信息
• 报告描述符：定义键盘数据格式
• 初始化函数：注册USB设备和HID接口
• 数据发送函数：模拟键盘按键发送

2. 关键代码解析

设备初始化

void hid_keyboard_init(uint8_t busid, uintptr_t reg_base)
{
    usbd_desc_register(busid, &hid_descriptor);
    usbd_add_interface(busid, usbd_hid_init_intf(busid, &intf0, hid_keyboard_report_desc, HID_KEYBOARD_REPORT_DESC_SIZE));
    usbd_add_endpoint(busid, &hid_in_ep);
    usbd_initialize(busid, reg_base, usbd_event_handler);
}

发送按键数据

void hid_keyboard_test(uint8_t busid)
{
    const uint8_t sendbuffer[8] = {0x00, 0x00, HID_KBD_USAGE_A, 0x00, 0x00, 0x00, 0x00, 0x00};
    if(usb_device_is_configured(busid) == false) return;
    
    memcpy(write_buffer, sendbuffer, 8);
    hid_state = HID_STATE_BUSY;
    usbd_ep_start_write(busid, HID_INT_EP, write_buffer, 8);
    while (hid_state == HID_STATE_BUSY);
}

3. 报告描述符

键盘报告描述符定义了按键数据的格式，CherryUSB已内置标准键盘报告描述符：

static const uint8_t hid_keyboard_report_desc[HID_KEYBOARD_REPORT_DESC_SIZE] = {
    0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
    0x09, 0x06,                    // USAGE (Keyboard)
    0xa1, 0x01,                    // COLLECTION (Application)
    // ... 省略中间部分 ...
    0xc0                           // END_COLLECTION
};

鼠标设备开发实例

1. 基本结构

鼠标示例代码位于demo/hid_mouse_template.c，与键盘类似，但报告描述符和数据格式有所不同。

2. 鼠标数据结构

struct hid_mouse {
    uint8_t buttons;  // 鼠标按键状态
    int8_t x;         // X轴位移
    int8_t y;         // Y轴位移
    int8_t wheel;     // 滚轮位移
};

3. 移动控制示例

void draw_circle(uint8_t *buf)
{
    static int32_t move_cnt = 0;
    static uint8_t step_x_y = 0;
    static int8_t x = 0, y = 0;

    move_cnt++;
    if (move_cnt > CURSOR_WIDTH) {
        step_x_y++;
        step_x_y = step_x_y % 4;
        move_cnt = 0;
    }
    // ... 根据不同step设置x和y的值 ...
    buf[0] = 0;       // 按键状态
    buf[1] = x;       // X轴位移
    buf[2] = y;       // Y轴位移
    buf[3] = 0;       // 滚轮
}

图：CherryUSB HID设备测试界面

测试与调试

1. 编译下载

根据目标平台，使用相应的构建系统编译项目。以ESP32为例：

cd tests/espressif/device
idf.py build flash monitor

2. 功能测试

• 键盘测试：连接USB后，程序会自动发送按键数据，可在文本编辑器中观察输入结果
• 鼠标测试：鼠标指针会自动画圆，可通过在线鼠标速率测试工具验证性能

3. 常见问题

• 设备无法识别：检查USB硬件连接和设备描述符配置
• 数据发送失败：确认端点地址和报告大小是否正确
• 兼容性问题：参考docs/en/support/index.rst中的兼容列表

高级应用

CherryUSB还支持更复杂的HID设备开发，例如：

• 复合设备：同时实现键盘和鼠标功能
• 自定义HID设备：通过自定义报告描述符实现特定功能
• 远程唤醒：支持USB远程唤醒功能，参考demo/hid_remote_wakeup_template.c

总结

通过本教程，你已经了解了如何使用CherryUSB开发HID设备。CherryUSB提供了简洁的API和丰富的示例，极大降低了嵌入式USB开发的门槛。无论是简单的键盘鼠标，还是复杂的自定义HID设备，CherryUSB都能满足你的需求。

想要深入学习，可以参考以下资源：

• 官方文档：docs/en/index.rst
• 示例代码：demo/目录下的各种HID示例
• API参考：docs/en/api/api_device.rst

【免费下载链接】CherryUSB CherryUSB is a tiny and portable USB Stack (device & host) for embedded system with USB IP 项目地址: https://gitcode.com/gh_mirrors/ch/CherryUSB