[转]Tutorial about USB HID Report Descriptors
Tutorial about USB HID Report Descriptors
This page is from my old website, and it is sort of popular, so I’ve moved it here.
A USB HID report descriptor is one of the descriptors that a USB host can request from a USB device. HID devices send data to the host using reports, and the descriptor tells the host how to interpret the data. I will try to show you how to write one of these descriptors.
First, go to this page http://www.usb.org/developers/hidpage/ and find the document titled “Device Class Definition for HID”. What I will be talking about is essentially paraphrasing the important sections of that document.
Second, go get the HID descriptor tool from the same page. You’ll want to play with it as you go through this tutorial. It is an absolute headache to write the HID report descriptors manually (converting between binary and hex and looking up the meanings of the numbers) so this tool is essential.
What is a USB HID report descriptor?
The HID protocol makes implementation of devices very simple. Devices define their data packets and then present a “HID descriptor” to the host. The HID descriptor is a hard coded array of bytes that describe the device’s data packets. This includes: how many packets the device supports, how large are the packets, and the purpose of each byte and bit in the packet. For example, a keyboard with a calculator program button can tell the host that the button’s pressed/released state is stored as the 2nd bit in the 6th byte in data packet number 4 (note: these locations are only illustrative and are device specific). The device typically stores the HID descriptor in ROM and does not need to intrinsically understand or parse the HID descriptor. Some mouse and keyboard hardware in the market today are implemented using only an 8-bit CPU.
– Wikipedia on Human Interface Device
I’m going to try teaching you about USB HID report descriptors by walking you through writing a few.
For a simple starting point, let us make a standard mouse. Just three buttons, and movement on the X and Y axis. So we want to send data regarding the buttons and movement. It takes one bit to represent each button, and one byte to represent the movement on one axis as a signed integer. So we can say that we want the data structure to look something like this
| Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0 | |
| Byte 0 | Useless | Useless | Useless | Useless | Useless | Left Button | Middle Button | Right Button |
| Byte 1 | X Axis Relative Movement as Signed Integer | |||||||
| Byte 2 | Y Axis Relative Movement as Signed Integer |
And then we can say our data structure in C looks like
|
1
2
3
4
5
6
|
structmouse_report_t
{
uint8_t buttons;
int8_t x;
int8_t y;
}
|
So now in our descriptor, our first item must describe buttons, three of them
|
1
2
3
|
USAGE_PAGE (Button)
USAGE_MINIMUM (Button 1)
USAGE_MAXIMUM (Button 3)
|
each button status is represented by a bit, 0 or 1
|
1
2
|
LOGICAL_MINIMUM (0)
LOGICAL_MAXIMUM (1)
|
there are three of these bits
|
1
2
|
REPORT_COUNT (3)
REPORT_SIZE (1)
|
send this variable data to the computer
|
1
|
INPUT (Data,Var,Abs)
|
and the final result looks like
|
1
2
3
4
5
6
7
8
|
USAGE_PAGE (Button)
USAGE_MINIMUM (Button 1)
USAGE_MAXIMUM (Button 3)
LOGICAL_MINIMUM (0)
LOGICAL_MAXIMUM (1)
REPORT_COUNT (3)
REPORT_SIZE (1)
INPUT (Data,Var,Abs)
|
that will represent the buttons
but what about the five useless padding bits?
|
1
2
3
|
REPORT_COUNT (1)
REPORT_SIZE (5)
INPUT (Cnst,Var,Abs)
|
now we make the X axis movement
|
1
2
|
USAGE_PAGE (Generic Desktop)
USAGE (X)
|
we want it to be a signed integer that takes one byte, so it has a value between -127 and +127 (actually -128 and +127, but I want to keep things even)
|
1
2
|
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
|
we want it to take an entire byte which is 8 bits
|
1
2
|
REPORT_SIZE (8)
REPORT_COUNT (1)
|
and send it to the computer as a variable relative coordinate
|
1
|
INPUT (Data,Var,Rel)
|
you end up with something like this to represent the X axis movement
|
1
2
3
4
5
6
7
|
USAGE_PAGE (Generic Desktop)
USAGE (X)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (1)
INPUT (Data,Var,Rel)
|
How about Y axis? You can try
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
USAGE_PAGE (Generic Desktop)
USAGE (X)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (1)
INPUT (Data,Var,Rel)
USAGE_PAGE (Generic Desktop)
USAGE (Y)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (1)
INPUT (Data,Var,Rel)
|
Which will work, but to save memory, we can do this instead
|
1
2
3
4
5
6
7
8
|
USAGE_PAGE (Generic Desktop)
USAGE (X)
USAGE (Y)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (2)
INPUT (Data,Var,Rel)
|
So all your data will end up looking like
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
USAGE_PAGE (Button)
USAGE_MINIMUM (Button 1)
USAGE_MAXIMUM (Button 3)
LOGICAL_MINIMUM (0)
LOGICAL_MAXIMUM (1)
REPORT_COUNT (3)
REPORT_SIZE (1)
INPUT (Data,Var,Abs)
REPORT_COUNT (1)
REPORT_SIZE (5)
INPUT (Cnst,Var,Abs)
USAGE_PAGE (Generic Desktop)
USAGE (X)
USAGE (Y)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (2)
INPUT (Data,Var,Rel)
|
Ah but we are not done, in order to make the computer know that this is a mouse, we do
|
1
2
3
4
5
6
7
8
9
10
|
USAGE_PAGE (Generic Desktop)
USAGE (Mouse)
COLLECTION (Application)
USAGE (Pointer)
COLLECTION (Physical)
... What we wrote already goes here
END COLLECTION
END COLLECTION
|
So in the end, this is the USB HID report descriptor for a standard mouse
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
0x05, 0x01, // USAGE_PAGE (Generic Desktop)
0x09, 0x02, // USAGE (Mouse)
0xa1, 0x01, // COLLECTION (Application)
0x09, 0x01, // USAGE (Pointer)
0xa1, 0x00, // COLLECTION (Physical)
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,Var,Abs)
0x95, 0x01, // REPORT_COUNT (1)
0x75, 0x05, // REPORT_SIZE (5)
0x81, 0x03, // INPUT (Cnst,Var,Abs)
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,Var,Rel)
0xc0, // END_COLLECTION
0xc0 // END_COLLECTION
|
This is actually the example descriptor provided with the USB HID documentation, and you can also find this as an example provided with the HID tool.
Cool, at this point, you will have encountered some concepts that you may have questions about, you should research the following:
Usage Pages
There’s one thing that I think isn’t explained well in the documentation, USAGE, USAGE_PAGE, USAGE_MINIMUM and USAGE_MAXIMUM. In a descriptor, you first set a USAGE_PAGE, and certain USAGEs are available. In the mouse example, USAGE_PAGE (Generic Desktop) allowed you to use USAGE (Mouse), and when the usage page was changed to USAGE_PAGE (Button), then the USAGE_MINIMUM and USAGE_MAXIMUM allowed you to specify the buttons, and before you can use USAGE (X) and USAGE (Y), the usage page was changed back to USAGE_PAGE (Generic Desktop). The usage page is like a namespace, changing the usage page affects what “usages” are available. Read the documentation called ” HID Usage Tables” for more info.
Collections
Read the documentation about the official proper use of collections. In my own words, collections can be used to organize your data, for example, a keyboard may have a built-in touchpad, then the data for the keyboard should be kept in one application collection while the touchpad data is kept in another. We can assign an “Report ID” to each collection, which I will show you later.
Hey here’s something you can do, by turning “USAGE (Mouse)” into “USAGE (Gamepad)”, you make the computer think that it’s a game pad with one joystick and 3 buttons. How about converting a Playstation 2 controller into a USB gamepad? The controller has 16 buttons and two thumb sticks, so we want the data to look like
| Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0 | |
| Byte 0 | Button | Button | Button | Button | Button | Button | Button | Button |
| Byte 1 | Button | Button | Button | Button | Button | Button | Button | Button |
| Byte 2 | Left X Axis as Signed Integer | |||||||
| Byte 3 | Left Y Axis as Signed Integer | |||||||
| Byte 4 | Right X Axis as Signed Integer | |||||||
| Byte 5 | Right Y Axis as Signed Integer |
So our data structure looks like
|
1
2
3
4
5
6
7
8
|
structgamepad_report_t
{
uint16_t buttons;
int8_t left_x;
int8_t left_y;
int8_t right_x;
int8_t right_y;
}
|
We make the computer understand that it’s a game pad
|
1
2
3
4
5
6
7
8
9
|
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
...
END COLLECTION
END COLLECTION
|
for the buttons
|
1
2
3
4
5
6
7
8
|
USAGE_PAGE (Button)
USAGE_MINIMUM (Button 1)
USAGE_MAXIMUM (Button 16)
LOGICAL_MINIMUM (0)
LOGICAL_MAXIMUM (1)
REPORT_COUNT (16)
REPORT_SIZE (1)
INPUT (Data,Var,Abs)
|
for the four thumb stick axis
|
1
2
3
4
5
6
7
8
9
10
|
USAGE_PAGE (Generic Desktop)
USAGE (X)
USAGE (Y)
USAGE (Z)
USAGE (Rx)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (4)
INPUT (Data,Var,Abs)
|
NOTE: Z is used to represent the right stick’s X axis, Rx is used to represent the right stick’s Y axis. This doesn’t make sense but this is how most existing USB game pads work. I have tested this using Battlefield Bad Company 2, it works.
NOTE: Use “absolute” for something like joysticks, but “relative” for things like mouse.
So now you end up with
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
USAGE_PAGE (Button)
USAGE_MINIMUM (Button 1)
USAGE_MAXIMUM (Button 16)
LOGICAL_MINIMUM (0)
LOGICAL_MAXIMUM (1)
REPORT_COUNT (16)
REPORT_SIZE (1)
INPUT (Data,Var,Abs)
USAGE_PAGE (Generic Desktop)
USAGE (X)
USAGE (Y)
USAGE (Z)
USAGE (Rx)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (4)
INPUT (Data,Var,Abs)
END COLLECTION
END COLLECTION
|
Hey how about two players? Here’s where collections get handy
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
REPORT_ID (1)
...
END COLLECTION
END COLLECTION
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
REPORT_ID (2)
...
END COLLECTION
END COLLECTION
|
fill in the data areas and you end up with
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
|
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
REPORT_ID (1)
USAGE_PAGE (Button)
USAGE_MINIMUM (Button 1)
USAGE_MAXIMUM (Button 16)
LOGICAL_MINIMUM (0)
LOGICAL_MAXIMUM (1)
REPORT_COUNT (16)
REPORT_SIZE (1)
INPUT (Data,Var,Abs)
USAGE_PAGE (Generic Desktop)
USAGE (X)
USAGE (Y)
USAGE (Z)
USAGE (Rx)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (4)
INPUT (Data,Var,Abs)
END COLLECTION
END COLLECTION
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
REPORT_ID (2)
USAGE_PAGE (Button)
USAGE_MINIMUM (Button 1)
USAGE_MAXIMUM (Button 16)
LOGICAL_MINIMUM (0)
LOGICAL_MAXIMUM (1)
REPORT_COUNT (16)
REPORT_SIZE (1)
INPUT (Data,Var,Abs)
USAGE_PAGE (Generic Desktop)
USAGE (X)
USAGE (Y)
USAGE (Z)
USAGE (Rx)
LOGICAL_MINIMUM (-127)
LOGICAL_MAXIMUM (127)
REPORT_SIZE (8)
REPORT_COUNT (4)
INPUT (Data,Var,Abs)
END COLLECTION
END COLLECTION
|
This is really important: You must change your data structure to include the report ID
| Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0 | |
| Byte 0 | Report ID | |||||||
| Byte 1 | Button | Button | Button | Button | Button | Button | Button | Button |
| Byte 2 | Button | Button | Button | Button | Button | Button | Button | Button |
| Byte 3 | Left X Axis as Signed Integer | |||||||
| Byte 4 | Left Y Axis as Signed Integer | |||||||
| Byte 5 | Right X Axis as Signed Integer | |||||||
| Byte 6 | Right Y Axis as Signed Integer |
|
1
2
3
4
5
6
7
8
9
|
structmultiplayer_gamepad_report_t
{
uint8_t report_id;
uint16_t buttons;
int8_t left_x;
int8_t left_y;
int8_t right_x;
int8_t right_y;
}
|
You must manually set the report ID before you send the data to the computer in order for the computer to understand which player the data belongs to.
|
1
2
3
4
|
multiplayer_gamepad_report_t player1_report;
multiplayer_gamepad_report_t player2_report;
player1_report.report_id = 1;
player2_report.report_id = 2;
|
You can also use collections and report IDs to make composite devices. So far I’ve shown you the keyboard, mouse, and gamepad. Here’s something that describes a composite device that is a keyboard, mouse, and two player game pad.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
USAGE_PAGE (Generic Desktop)
USAGE (Keyboard)
COLLECTION (Application)
REPORT_ID (1)
...
END COLLECTION
USAGE_PAGE (Generic Desktop)
USAGE (Mouse)
COLLECTION (Application)
USAGE (Pointer)
COLLECTION (Physical)
REPORT_ID (2)
...
END COLLECTION
END COLLECTION
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
REPORT_ID (3)
...
END COLLECTION
END COLLECTION
USAGE_PAGE (Generic Desktop)
USAGE (Game Pad)
COLLECTION (Application)
COLLECTION (Physical)
REPORT_ID (4)
...
END COLLECTION
END COLLECTION
|
and of course, your data structures with the added report ID.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
structkeyboard_report_t
{
uint8_t report_id;
uint8_t modifier;
uint8_t reserved;
uint8_t keycode[6];
}
structmouse_report_t
{
uint8_t report_id;
uint8_t buttons;
int8_t x;
int8_t y;
}
structgamepad_report_t
{
uint8_t report_id;
uint16_t buttons;
int8_t left_x;
int8_t left_y;
int8_t right_x;
int8_t right_y;
}
|
But since we changed the data structure, your device no-longer supports boot protocol, and hence you will not need to define a protocol. So make sure you change usbconfig.h accordingly.
Want to see this in action? Load up this example project into USnooBie and let Windows’s “Devices and Printers” show you!
Example Project Files
![hid_tutorial_1_ss[1]](http://img.e-com-net.com/image/info2/e2d23a43d8a648b497b9e9781d3e73fe.png)