Rust USB HID设备开发宏库usbd-hid-macros使用指南

usbd-hid-macros是一个简化Rust中USB HID(Human Interface Device)设备开发的宏库，特别专注于简化报告描述符(Report Descriptor)的生成过程。

主要功能

• 提供声明式宏来定义HID报告描述符
• 自动生成符合USB HID规范的描述符结构
• 简化常见HID设备类型的实现
• 与usbd-hid库无缝集成

使用方法

基本安装

首先在Cargo.toml中添加依赖：

[dependencies]
usbd-hid-macros = "0.3"
usbd-hid = "0.6"

定义HID设备

使用gen_hid_descriptor!宏来定义你的HID设备描述符：

use usbd_hid_macros::gen_hid_descriptor;

#[gen_hid_descriptor(
    (collection = APPLICATION, usage_page = GENERIC_DESKTOP, usage = KEYBOARD) = {
        (usage_page = KEYBOARD, usage_min = 0xE0, usage_max = 0xE7) = {
            #[packed_bits 8] #[item_settings data,variable,absolute] modifier=input;
        };
        (usage_min = 0x00, usage_max = 0x65) = {
            #[item_settings data,array,absolute] keycodes=input;
        };
    }
)]
#[allow(dead_code)]
pub struct KeyboardReport {
    pub modifier: u8,      // 修饰键状态(如Ctrl, Alt等)
    pub _reserved: u8,     // 保留字段
    pub keycodes: [u8; 6], // 当前按下的普通键
}

鼠标设备示例

#[gen_hid_descriptor(
    (collection = APPLICATION, usage_page = GENERIC_DESKTOP, usage = MOUSE) = {
        (usage_page = GENERIC_DESKTOP, usage = POINTER) = {
            (collection = PHYSICAL, usage = POINTER) = {
                (usage_page = BUTTON, usage_min = 0x01, usage_max = 0x03) = {
                    #[packed_bits 3] #[item_settings data,variable,absolute] buttons=input;
                    #[padding 5] padding=input;
                };
                (usage_page = GENERIC_DESKTOP,) = {
                    (usage = X,) = {
                        #[item_settings data,variable,relative] x=input;
                    };
                    (usage = Y,) = {
                        #[item_settings data,variable,relative] y=input;
                    };
                };
            };
        };
    }
)]
#[allow(dead_code)]
pub struct MouseReport {
    pub buttons: u8, // 鼠标按钮状态(左键、右键等)
    pub x: i8,       // X轴相对移动量
    pub y: i8,       // Y轴相对移动量
}

游戏手柄示例

#[gen_hid_descriptor(
    (collection = APPLICATION, usage_page = GENERIC_DESKTOP, usage = JOYSTICK) = {
        (usage_page = GENERIC_DESKTOP,) = {
            (usage = X,) = {
                #[item_settings data,variable,absolute] x=input;
            };
            (usage = Y,) = {
                #[item_settings data,variable,absolute] y=input;
            };
            (usage = Z,) = {
                #[item_settings data,variable,absolute] z=input;
            };
            (usage = RX,) = {
                #[item_settings data,variable,absolute] rx=input;
            };
            (usage = RY,) = {
                #[item_settings data,variable,absolute] ry=input;
            };
            (usage = RZ,) = {
                #[item_settings data,variable,absolute] rz=input;
            };
        };
        (usage_page = BUTTON, usage_min = 0x01, usage_max = 0x10) = {
            #[packed_bits 16] #[item_settings data,variable,absolute] buttons=input;
        };
    }
)]
#[allow(dead_code)]
pub struct JoystickReport {
    pub x: u8,        // X轴位置
    pub y: u8,        // Y轴位置
    pub z: u8,        // Z轴位置
    pub rx: u8,       // X轴旋转
    pub ry: u8,       // Y轴旋转
    pub rz: u8,       // Z轴旋转
    pub buttons: u16, // 16个按钮状态
}

使用生成的描述符

定义好报告结构后，可以这样使用：

use usbd_hid::descriptor::SerializedDescriptor;
use usbd_hid_macros::gen_hid_descriptor;

// 定义你的报告描述符...

let report_desc = KeyboardReport::desc();

// 然后可以将report_desc传递给usbd-hid的配置

高级用法

组合设备

你可以定义包含多个顶级集合的组合设备：

#[gen_hid_descriptor(
    (collection = APPLICATION, usage_page = GENERIC_DESKTOP, usage = KEYBOARD) = {
        // 键盘部分...
    };
    (collection = APPLICATION, usage_page = GENERIC_DESKTOP, usage = MOUSE) = {
        // 鼠标部分...
    }
)]
pub struct KeyboardMouseReport {
    // 字段...
}

自定义用法页

你可以定义自己的用法页(Usage Page)：

const MY_CUSTOM_USAGE_PAGE: u16 = 0xFF00;

#[gen_hid_descriptor(
    (collection = APPLICATION, usage_page = MY_CUSTOM_USAGE_PAGE, usage = 0x01) = {
        // 自定义设备...
    }
)]
pub struct CustomDeviceReport {
    // 字段...
}

完整示例

下面是一个完整的键盘HID设备实现示例：

use usb_device::prelude::*;
use usbd_hid::hid_class::HIDClass;
use usbd_hid_macros::gen_hid_descriptor;

// 定义键盘报告描述符
#[gen_hid_descriptor(
    (collection = APPLICATION, usage_page = GENERIC_DESKTOP, usage = KEYBOARD) = {
        (usage_page = KEYBOARD, usage_min = 0xE0, usage_max = 0xE7) = {
            #[packed_bits 8] #[item_settings data,variable,absolute] modifier=input;
        };
        (usage_min = 0x00, usage_max = 0x65) = {
            #[item_settings data,array,absolute] keycodes=input;
        };
    }
)]
#[allow(dead_code)]
pub struct KeyboardReport {
    pub modifier: u8,
    pub _reserved: u8,
    pub keycodes: [u8; 6],
}

fn main() {
    // 初始化USB设备
    let usb_bus = UsbBus::new(peripherals.USB);
    
    // 创建HID类实例
    let hid = HIDClass::new(&usb_bus, KeyboardReport::desc(), 60);
    
    // 创建USB设备
    let mut usb_dev = UsbDeviceBuilder::new(&usb_bus, UsbVidPid(0x16c0, 0x27dd))
        .manufacturer("My Company")
        .product("HID Keyboard")
        .serial_number("123456")
        .device_class(0)
        .build();
    
    // 主循环
    loop {
        // 处理USB事件
        usb_dev.poll(&mut [&mut hid]);
        
        // 创建键盘报告
        let report = KeyboardReport {
            modifier: 0,       // 无修饰键
            _reserved: 0,      // 保留字段
            keycodes: [0; 6],  // 无按键按下
        };
        
        // 发送报告
        hid.push_input(&report).ok();
    }
}

注意事项

1. 报告描述符必须符合USB HID规范
2. 结构体字段必须与描述符定义匹配
3. 使用#[allow(dead_code)]可以避免编译器警告
4. 确保你的设备实现了正确的报告ID（如果需要）

usbd-hid-macros大大简化了HID设备开发中最复杂的部分——报告描述符的生成，让开发者可以更专注于设备功能的实现。