HID 报告描述

1. 报告描述简介

Report Description，即上报事件的描述，描述所支持事件的格式及取值意义，比如鼠标按键上报格式、左键右键中间键分别对应的值等；报告描述类似，都是结构数据，格式类似

{usage:1, {id:0,usage:1.1,size:1,count:1,min:0,max:5,format:xx}}

2. 描述符结构

几个主要的名词解释一下：

• Collection，集合，相当于{}，用来包含一组描述；Collection有Application和Physical之分，Application表示大项，里有可以有很多Physical子项
• Report，报告，在上图中只是一个ID号，来区分不同report。
• Main Item,主项，例出来哪些项
• Report Size，每一项有多少位。
• Report Count, 总共有多少项
• Logical Minimum，每个项的取值范围中的最小值，即最小只能取的值。
• Logical Maximum，每个项的取值范围中的最大值，即最大只能取的值。
• Usage，用途，表示有哪些功能，一个Usage代表一个功能。

项描述基本上是由两个字节构成，第一个字节表示名称，第二个字节表示值，
如Report Size,8
Report Size 是名称，8是它的值。
Report Size 对应的16制数据是0x75，在代码里上面的表现是0x75,0x08。

项描述基本上是由两个字节构成，第一个字节表示名称，第二个字节表示值，
如Report Size,8
Report Size 是名称，8是它的值。
Report Size 对应的16制数据是0x75，在代码里上面的表现是0x75,0x08。
有些名称不需要带值，如Collection的结束符( ) )为0xC0，就没有第二个字节。有些名称不需要带值，如Collection的结束符( ) )为0xC0，就没有第二个字节。

3. 名称

名称有分长字和短字，这里只介绍短字，短字是由一个字节构成，结构如下：

第3 ~ 2位表示类型，有如下几种：

• 0 = Main
• 1 = Global
• 2 = Local
• 3 = Reserved

第1 ~ 0位表示名称的值由多少个字节构成，具体意义如下：

• 0 = 0 bytes，名称后面不带值
• 1 = 1 bytes，名称后面带1个值
• 2 = 2 bytes，名称后面带2个值
• 3 = 4 bytes，名称后面带4个值

第7 ~ 4位表示Tag，Tag与类型对应，每种类型有很多不同的Tag。

3.1 Main类对应的Tag

在上面表格中，可以看到，第3 ~ 2位是00，这两位是bType值，00表示类型为Main；nn是第1 ~ 0位，是bSize，表示数值的字节数；第7 ~ 4位是bTag，如
1000(0x8?)表示Input；Valid Data表示值的意义，如Input项，Bit 0 {Data(0) | Constant(1)}，意思是说，如果值的第0位的是0，即表示Data，如果是
Constant，如下语句：

• 0x81, 0x02, // Input: (Data,Variable, Absolute)
• 它的值是2，第0位是0对应的是Data，第1位是1 对应的是Variable，第二位是0对应的是Absolute，所以它是一个Data、Variable、 Absolute的类型。

下面对Data、Variable等的意思作一下解释。

• Data 表示是一个可写的数据。
• Constant 表示是一个只读的数据。
• Aarray 表示数据里的值代表一个Usage，Report Size表示位数，即Report Size的存储单元里的值是Usage的Index。Report Count一般为1，如果大以同时出现多个Usage.
• Variable 则是一个Report Size存储单元表示一个Usage,其值表示Usage的状态；Report Size表示位数，Report Count表示长度。
• Absolute 表示绝对数据，如触模屏数据，便使用Absolute。
• Relative 表示相对数据，如鼠标数据，便使用Relative。
• 其也用的少就不多说了，详细参看《HID协议》。

3.2 Global类对应的Tag

在上面表格中，可以看到，第3 ~ 2位是01，这两位是bType值，01表示类型为Global；nn是第1 ~ 0位，是bSize，表示数值的字节数；第7 ~ 4位是bTag，
0000(0x0?)表示Usage Page。

3.3 Local类对应的Tag

在上面表格中，可以看到，第3 ~ 2位是10，这两位是bType值，10表示类型为Local；nn是第1 ~ 0位，是bSize，表示数值的字节数；第7 ~ 4位是bTag，
0000(0x0?)表示Usage。

4 样例解读

下面是一个伪代码描述的样例
其中涉及到的页码可查看第5段用途表：

Usage Page (Generic Desktop), //定位到Generic Desktop页，这个相当于指针跳转一样的东西
Usage (Mouse), //指定Generic Desktop里的mouse，表示这是一个鼠标
Collection (Application), // Collection Application，是对Mouse的解释
Usage(Pointer), //表示指针形式
Collection (Physical), // CollectionPhysical，是对Pointer的解释
ReportID (0A), //id为0x0A的报告
Usage(X), Usage (Y), //上报X,Y两个数据
LogicalMinimum (-127), ;Report data values range from -127
LogicalMaximum (127), ;to 127 //X,Y的取值范围是-127~127
ReportSize (8), Report Count (2), //总共要上报2个字节，即x一个字节,y一个字节
Input(Data, Variable, Relative), //将X,Y这两个字节添加到0x0A的报告里，且这两个值是可写并且是相对的
LogicalMinimum (0), ;
LogicalMaximum (1), ;//下面Button的取值范围是0~1
ReportSize (1), Report Count (3), //3个1位的数据
UsagePage (Button Page),//是一个BUTTON
UsageMinimum (1),
Usage Maximum (3),//共有BUTTON1~BUTTON3，即总共有3个BUTTON
Input(Data, Variable, Absolute),//将3个分别代表的BUTTON1,BUTTON2,BUTTON3的位添加到0x0A的报告
ReportSize (5),
Input(Constant), //增加5个无效的位与上面3位凑成一个字节
EndCollection,
End Collection

综上所示，上面样例所表达的意思就是下图所示的：

再举一个实际的例子进行解读，下面是摘自TI CC2540/CC2541 SDK里的BLE-CC254x_v1.4.0\Projects\ble\Profiles\HIDDevKbM\hidkbmservice.c

static CONST uint8 hidReportMap[] =
{
// 鼠标
0x05, 0x01, // UsagePage (Generic Desktop)
 0x09, 0x02, // Usage (Mouse)
 0xA1, 0x01, // Collection (Application)
 0x85, 0x01, // Report Id (1)
 0x09, 0x01, // Usage (Pointer)
 0xA1, 0x00, // Collection (Physical)
 0x05, 0x09, // Usage Page (Buttons)
 0x19, 0x01, // Usage Minimum (01) -Button 1
 0x29, 0x03, // Usage Maximum (03) -Button 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) - Button states
 0x75, 0x05, // Report Size (5)
 0x95, 0x01, // Report Count (1)
 0x81, 0x01, // Input (Constant) - Paddingor Reserved bits
 0x05, 0x01, // Usage Page (GenericDesktop)
 0x09, 0x30, // Usage (X)
 0x09, 0x31, // Usage (Y)
 0x09, 0x38, // Usage (Wheel)
 0x15, 0x81, // Logical Minimum (-127)
 0x25, 0x7F, // Logical Maximum (127)
 0x75, 0x08, // Report Size (8)
 0x95, 0x03, // Report Count (3)
 0x81, 0x06, // Input (Data, Variable,Relative) - X & Y coordinate
 0xC0, // End Collection
 0xC0, // End Collection
// 键盘
0x05, 0x01, // UsagePg (Generic Desktop)
 0x09, 0x06, // Usage (Keyboard)
 0xA1, 0x01, // Collection: (Application)
 0x85, 0x02, // Report Id (2)
 //
 0x05, 0x07, // Usage Pg (Key Codes)
 0x19, 0xE0, // Usage Min (224)
 0x29, 0xE7, // Usage Max (231)
 0x15, 0x00, // Log Min (0)
 0x25, 0x01, // Log Max (1)
 // Modifier byte
 0x75, 0x01, // Report Size (1)
 0x95, 0x08, // Report Count (8)
 0x81, 0x02, // Input: (Data, Variable,Absolute)
 // Reserved byte
 0x95, 0x01, // Report Count (1)
 0x75, 0x08, // Report Size (8)
 0x81, 0x01, // Input: (Constant)
 // LED report
 0x95, 0x05, // Report Count (5)
 0x75, 0x01, // Report Size (1)
 0x05, 0x08, // Usage Pg (LEDs)
 0x19, 0x01, // Usage Min (1)
 0x29, 0x05, // Usage Max (5)
 0x91, 0x02, // Output: (Data, Variable,Absolute)
 // LED report padding
 0x95, 0x01, // Report Count (1)
 0x75, 0x03, // Report Size (3)
 0x91, 0x01, // Output: (Constant)
 // Key arrays (6 bytes)
 0x95, 0x06, // Report Count (6)
 0x75, 0x08, // Report Size (8)
 0x15, 0x00, // Log Min (0)
 0x25, 0x65, // Log Max (101)
 0x05, 0x07, // Usage Pg (Key Codes)
 0x19, 0x00, // Usage Min (0)
 0x29, 0x65, // Usage Max (101)
 0x81, 0x00, // Input: (Data, Array)
 0xC0, // End Collection
// Consumer
0x05, 0x0C, // Usage Pg (Consumer Devices)
 0x09, 0x01, // Usage (Consumer Control)
 0xA1, 0x01, // Collection (Application)
 0x85, 0x03, // Report Id (3)
 0x09, 0x02, // Usage (Numeric KeyPad)
 0xA1, 0x02, // Collection (Logical)
 0x05, 0x09, // Usage Pg (Button)
 0x19, 0x01, // Usage Min (Button1)
 0x29, 0x0A, // Usage Max (Button10)
 0x15, 0x01, // Logical Min (1)
 0x25, 0x0A, // Logical Max (10)
 0x75, 0x04, // Report Size (4)
 0x95, 0x01, // Report Count (1)
 0x81, 0x00, // Input (Data, Ary,Abs)
 0xC0, // End Collection
 0x05, 0x0C, // Usage Pg (ConsumerDevices)
 0x09, 0x86, // Usage (Channel)
 0x15, 0xFF, // Logical Min (-1)
 0x25, 0x01, // Logical Max (1)
 0x75, 0x02, // Report Size (2)
 0x95, 0x01, // Report Count (1)
 0x81, 0x46, // Input (Data, Var,Rel, Null)
 0x09, 0xE9, // Usage (Volume Up)
 0x09, 0xEA, // Usage (Volume Down)
 0x15, 0x00, // Logical Min (0)
 0x75, 0x01, // Report Size (1)
 0x95, 0x02, // Report Count (2)
 0x81, 0x02, // Input (Data, Var,Abs)
 0x09, 0xE2, // Usage (Mute)
 0x09, 0x30, // Usage (Power)
 0x09, 0x40, // Usage (Menu)
 0x09, 0xB1, // Usage (Pause)
 0x09, 0xB2, // Usage (Record)
 0x0a, 0x23, 0x02, // Usage (Home)
 0x0a, 0x24, 0x02, // Usage (Back)
 0x09, 0xB3, // Usage (Fast Forward)
 0x09, 0xB4, // Usage (Rewind)
 0x09, 0xB5, // Usage (Scan Next)
 0x09, 0xB6, // Usage (Scan Prev)
 0x09, 0xB7, // Usage (Stop)
 0x15, 0x01, // Logical Min (1)
 0x25, 0x0C, // Logical Max (12)
 0x75, 0x04, // Report Size (4)
 0x95, 0x01, // Report Count (1)
 0x81, 0x00, // Input (Data, Ary,Abs)
 0x09, 0x80, // Usage (Selection)
 0xA1, 0x02, // Collection (Logical)
 0x05, 0x09, // Usage Pg (Button)
 0x19, 0x01, // Usage Min (Button1)
 0x29, 0x03, // Usage Max (Button3)
 0x15, 0x01, // Logical Min (1)
 0x25, 0x03, // Logical Max (3)
 0x75, 0x02, // Report Size (2)
 0x81, 0x00, // Input (Data, Ary,Abs)
 0xC0, // End Collection
 0x81, 0x03, // Input (Const, Var,Abs)
 0xC0 // End Collection
};

上面用三大应用功能，分别鼠标、键盘和Consumer，每个应用功能都是用Collection Application括起来的。

我们先来解析鼠标的报告描述：

// 0x04代表是Global类的Usage Page功能，最位2位表示带多少个字节的数据，因为只带1个数据，所以是1，跟0x04组合起来就是0x05了。其他名称的不多，数值可以参照上面的《3名称》
0x05,0x01, // Usage Page (Generic Desktop)
// 表示这是一个鼠标， Usage是为了给对方解析数据时有个参照
0x09, 0x02, // Usage (Mouse)
// 0xA1, 0x01 表示Collection Application ; 0xA1,0x00表示CollectionPhysical.表示下面所包含的是对Mouse的解释
0xA1, 0x01, // Collection (Application)
// 该报告对应的ID是1
0x85, 0x01, // Report Id (1)
// 这是个指针形式
0x09, 0x01, // Usage (Pointer)
// 下面所包含的是对指针的解释
0xA1, 0x00, // Collection (Physical)
// 下面定义的是按键
0x05, 0x09, // Usage Page (Buttons)
// 总共有3个按键
0x19, 0x01, // Usage Minimum (01) -Button 1
0x29, 0x03, // Usage Maximum (03) -Button 3
// 按键的值是0和1，表示放开和按下
0x15, 0x00, // Logical Minimum (0)
0x25, 0x01, // Logical Maximum (1)
// 有3个1位，即用3bits分别对应三个按键
0x75, 0x01, // Report Size (1)
0x95, 0x03, // Report Count (3)
// 将这三个位加入本报告的数据中，这三位是可读写的绝对值
0x81, 0x02, // Input (Data, Variable,Absolute) - Button states
// 定义1个5位的数据
0x75, 0x05, // Report Size (5)
0x95, 0x01, // Report Count (1)
// 将这个数据添加到本报告的数据中，主要是与前面3位组成一个字节，这5位是Constant数据
0x81, 0x01, // Input (Constant) - Paddingor Reserved bits
// 下面定义的是X,Y,Wheel三个功能
0x05, 0x01, // Usage Page (Generic Desktop)
0x09, 0x30, // Usage (X)
0x09, 0x31, // Usage (Y)
0x09, 0x38, // Usage (Wheel)
// X,Y,Wheel的取值范围是-127~127
0x15, 0x81, // Logical Minimum (-127)
0x25, 0x7F, // Logical Maximum (127)
// 用三个字节来表示x,y,wheel
0x75, 0x08, // Report Size (8)
0x95, 0x03, // Report Count (3)
// 将这三个字节添加到本报告中
0x81, 0x06, // Input (Data, Variable,Relative) - X & Y coordinate
0xC0, // End Collection

上面解析出来的数据格式如下:

我们来看一下，如果要发一个鼠标的坐标，该如何发：

static void hidEmuKbdSendMouseReport( uint8buttons )
{
    uint8 buf[HID_MOUSE_IN_RPT_LEN];
    buf[0] = buttons; // Buttons
    buf[1] = 0; // X
    buf[2] = 0; // Y
    buf[3] = 0; // Wheel
    HidDev_Report( HID_RPT_ID_MOUSE_IN, HID_REPORT_TYPE_INPUT, HID_MOUSE_IN_RPT_LEN, buf );
}

从上面函数可以看到，X,Y在第2、3个字节，结合上面的数据格式图可以看出，正好是对应的。

我们接着解析键盘的报告描述：

// 这是一个键盘
0x05,0x01, // Usage Pg (Generic Desktop)
0x09, 0x06, // Usage (Keyboard)
// 本报告的ID是2
0xA1, 0x01, // Collection: (Application)
0x85, 0x02, // Report Id (2)
// 下面定义的是按键码
0x05, 0x07, // Usage Pg (Key Codes)
// 按键码分别是224~231，共总有8个按键码
0x19, 0xE0, // Usage Min (224)
0x29, 0xE7, // Usage Max (231)
// 按键码的值是0和1，分别代表放开和按下
0x15, 0x00, // Log Min (0)
0x25, 0x01, // Log Max (1)
// 用8个bit分别表示8个按键的状态
// Modifier byte
0x75, 0x01, // Report Size (1)
0x95, 0x08, // Report Count (8)
// 将这8个bit添加到本报告中
0x81, 0x02, // Input: (Data, Variable,Absolute)
// 另外再预留8个bit备用，暂时没用
// Reserved byte
0x95, 0x01, // Report Count (1)
0x75, 0x08, // Report Size (8)
0x81, 0x01, // Input: (Constant)
// 定义5个1bit
// LED report
0x95, 0x05, // Report Count (5)
0x75, 0x01, // Report Size (1)
// 这是LED
0x05, 0x08, // Usage Pg (LEDs)
// 5个bit分别对应LED1~LED5
0x19, 0x01, // Usage Min (1)
0x29, 0x05, // Usage Max (5)
// 将这5个bit添加到本报告中，LED需要作为OUT
0x91, 0x02, // Output: (Data, Variable,Absolute)
// 再增加3个bit，与上面5个bit组成一个字节
// LED report padding
0x95, 0x01, // Report Count (1)
0x75, 0x03, // Report Size (3)
0x91, 0x01, // Output: (Constant)
// 定义6个字节
// Key arrays (6 bytes)
0x95, 0x06, // Report Count (6)
0x75, 0x08, // Report Size (8)
// 每个字节的取值范围是0~101
0x15, 0x00, // Log Min (0)
0x25, 0x65, // Log Max (101)
// 这个也是键盘码
0x05, 0x07, // Usage Pg (Key Codes)
// 分别是键盘码0~键盘码101
0x19, 0x00, // Usage Min (0)
0x29, 0x65, // Usage Max (101)
// 将这6个字节添加到本报告中,表示同时可产生6个键值。
0x81, 0x00, // Input: (Data, Array)
0xC0, // End Collection

上面解析出来的数据格式如下:

Input和Out是不同的两条通道。现在我们来看一下，如果要发一个按键K0~K101，需要怎么发，如下：

static void hidEmuKbdSendReport( uint8keycode )
{
    uint8 buf[HID_KEYBOARD_IN_RPT_LEN];
    buf[0] = 0; // Modifierkeys
    buf[1] = 0; // Reserved
    buf[2] = keycode; // Keycode 1
    buf[3] = 0; // Keycode 2
    buf[4] = 0; // Keycode 3
    buf[5] = 0; // Keycode 4
    buf[6] = 0; // Keycode 5
    buf[7] = 0; // Keycode 6
    HidDev_Report( HID_RPT_ID_KEY_IN, HID_REPORT_TYPE_INPUT, HID_KEYBOARD_IN_RPT_LEN, buf );
}

上面函数可以看到，它是放在第3个字节，结合数据格式图可以看出，第3个字节开始，刚好是在K0~K101的按键区。

我们最后来解析Consumer的报告描述：

// 这是个Consumer控制
0x05,0x0C, // Usage Pg (Consumer Devices)
0x09, 0x01, // Usage (Consumer Control)
// 本报告ID为3
0xA1, 0x01, // Collection (Application)
0x85, 0x03, // Report Id (3)
// 下面定义的是数字键盘
0x09, 0x02, // Usage (Numeric KeyPad)
// 下面定义的是按键
0xA1, 0x02, // Collection (Logical)
0x05, 0x09, // Usage Pg (Button)
// 分别是Button1~Button10
0x19, 0x01, // Usage Min (Button1)
0x29, 0x0A, // Usage Max (Button10)
// 每个按键的取值范围为1~10
0x15, 0x01, // Logical Min (1)
0x25, 0x0A, // Logical Max (10)
// 1个4bit的值，来表示键值1~10，这个值是哪个就表示哪个键按下。
0x75, 0x04, // Report Size (4)
0x95, 0x01, // Report Count (1)
// 将这4bit添加到本报告中
0x81, 0x00, // Input (Data, Ary, Abs)
0xC0, // End Collection
// 这里定义的是频道
0x05, 0x0C, // Usage Pg (ConsumerDevices)
0x09, 0x86, // Usage (Channel)
// 频道值范围是-1~1，这里应该只用到-1和1，表示频道+和-
0x15, 0xFF, // Logical Min (-1)
0x25, 0x01, // Logical Max (1)
// 用一个2bit来表示，第1个bit表示频道+，第二个表示频道-
0x75, 0x02, // Report Size (2)
0x95, 0x01, // Report Count (1)
// 将这个2bit加到本报告中
0x81, 0x46, // Input (Data, Var,Rel, Null)
// 定义两个按键，音量加和音量减
0x09, 0xE9, // Usage (Volume Up)
0x09, 0xEA, // Usage (Volume Down)
// 按键值为0~1，这里少了LogicalMax,继承上面的LogicalMax=1
0x15, 0x00, // Logical Min (0)
0x75, 0x01, // Report Size (1)
// 定义2个1bit，每个bit代表一个键
0x95, 0x02, // Report Count (2)
// 将2个1bit添加到本报告中
0x81, 0x02, // Input (Data, Var,Abs)
// 定义12个按键
0x09, 0xE2, // Usage (Mute)
0x09, 0x30, // Usage (Power)
0x09, 0x40, // Usage (Menu)
0x09, 0xB1, // Usage (Pause)
0x09, 0xB2, // Usage (Record)
0x0a, 0x23, 0x02, // Usage (Home)
0x0a, 0x24, 0x02, // Usage (Back)
0x09, 0xB3, // Usage (Fast Forward)
0x09, 0xB4, // Usage (Rewind)
0x09, 0xB5, // Usage (Scan Next)
0x09, 0xB6, // Usage (Scan Prev)
0x09, 0xB7, // Usage (Stop)
// 用一个4位来存储1~12，1表示Mute … 12表示Stop
0x15, 0x01, // Logical Min (1)
0x25, 0x0C, // Logical Max (12)
0x75, 0x04, // Report Size (4)
0x95, 0x01, // Report Count (1)
// 将这个4bit添加到报告中
0x81, 0x00, // Input (Data, Ary,Abs)
0x09, 0x80, // Usage (Selection)
// 这是按键
0xA1, 0x02, // Collection (Logical)
0x05, 0x09, // Usage Pg (Button)
// 分别是Button1~Button3
0x19, 0x01, // Usage Min (Button1)
0x29, 0x03, // Usage Max (Button3)
// 每个按键取值范围是1~3
0x15, 0x01, // Logical Min (1)
0x25, 0x03, // Logical Max (3)
// 这里缺少了Report Count，继承上面的Report Count =1，也就是用1个2bit来存储1~3
0x75, 0x02, // Report Size (2)
// 将1个字节添加到本报告中
0x81, 0x00, // Input (Data, Ary,Abs)
0xC0, // End Collection
// 再补充2个bit将上面的凑成一个字节，ReportSize=2和Report Count=1继承上面的。
0x81, 0x03, // Input (Const, Var,Abs)
0xC0 // End Collection

修改后，解析出来的数据格式如下:

我们来看一下，如果要发音量+/-键该怎么发：

static void hidCCSendReport( uint8 cmd,bool keyPressed )
{
    //Only send the report if something meaningful to report
    uint8 buf[HID_CC_IN_RPT_LEN] = { 0, 0 };
    //No need to include Report Id
    if( keyPressed )
    {
        hidCCBuildReport( buf, cmd );
    }
    HidDev_Report( HID_RPT_ID_CC_IN, HID_REPORT_TYPE_INPUT, HID_CC_IN_RPT_LEN, buf );
}

在hidCCBuildReport对音量加减解析出来是：
音量加是：buf[0] =0x40, buf[1] = 0x00
音量减是：buf[0] =0x80, buf[1] = 0x00
正好与数据格式图中第一个字节的第6位和第7位相对应。

5 用途表

下面用途表中列了几个常用的表，其他详细请参看《HID用途表》
Usage Page

Generic Desktop Page（0x01）

Keyboard/Keypad Page(0x07)

LED Usage Page(0x08)

Button Usage Page(0x09)

Consumer Usage Page(0x0C)