Commit | Line | Data |
---|---|---|
c54ea491 AO |
1 | HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices |
2 | ================================================================== | |
3 | ||
4 | The hidraw driver provides a raw interface to USB and Bluetooth Human | |
5 | Interface Devices (HIDs). It differs from hiddev in that reports sent and | |
6 | received are not parsed by the HID parser, but are sent to and received from | |
7 | the device unmodified. | |
8 | ||
9 | Hidraw should be used if the userspace application knows exactly how to | |
10 | communicate with the hardware device, and is able to construct the HID | |
11 | reports manually. This is often the case when making userspace drivers for | |
12 | custom HID devices. | |
13 | ||
14 | Hidraw is also useful for communicating with non-conformant HID devices | |
15 | which send and receive data in a way that is inconsistent with their report | |
16 | descriptors. Because hiddev parses reports which are sent and received | |
17 | through it, checking them against the device's report descriptor, such | |
18 | communication with these non-conformant devices is impossible using hiddev. | |
19 | Hidraw is the only alternative, short of writing a custom kernel driver, for | |
20 | these non-conformant devices. | |
21 | ||
22 | A benefit of hidraw is that its use by userspace applications is independent | |
23 | of the underlying hardware type. Currently, Hidraw is implemented for USB | |
24 | and Bluetooth. In the future, as new hardware bus types are developed which | |
25 | use the HID specification, hidraw will be expanded to add support for these | |
26 | new bus types. | |
27 | ||
28 | Hidraw uses a dynamic major number, meaning that udev should be relied on to | |
29 | create hidraw device nodes. Udev will typically create the device nodes | |
30 | directly under /dev (eg: /dev/hidraw0). As this location is distribution- | |
31 | and udev rule-dependent, applications should use libudev to locate hidraw | |
32 | devices attached to the system. There is a tutorial on libudev with a | |
33 | working example at: | |
34 | http://www.signal11.us/oss/udev/ | |
35 | ||
36 | The HIDRAW API | |
37 | --------------- | |
38 | ||
39 | read() | |
40 | ------- | |
41 | read() will read a queued report received from the HID device. On USB | |
42 | devices, the reports read using read() are the reports sent from the device | |
43 | on the INTERRUPT IN endpoint. By default, read() will block until there is | |
44 | a report available to be read. read() can be made non-blocking, by passing | |
45 | the O_NONBLOCK flag to open(), or by setting the O_NONBLOCK flag using | |
46 | fcntl(). | |
47 | ||
48 | On a device which uses numbered reports, the first byte of the returned data | |
49 | will be the report number; the report data follows, beginning in the second | |
50 | byte. For devices which do not use numbered reports, the report data | |
51 | will begin at the first byte. | |
52 | ||
53 | write() | |
54 | -------- | |
55 | The write() function will write a report to the device. For USB devices, if | |
56 | the device has an INTERRUPT OUT endpoint, the report will be sent on that | |
57 | endpoint. If it does not, the report will be sent over the control endpoint, | |
58 | using a SET_REPORT transfer. | |
59 | ||
60 | The first byte of the buffer passed to write() should be set to the report | |
61 | number. If the device does not use numbered reports, the first byte should | |
62 | be set to 0. The report data itself should begin at the second byte. | |
63 | ||
64 | ioctl() | |
65 | -------- | |
66 | Hidraw supports the following ioctls: | |
67 | ||
68 | HIDIOCGRDESCSIZE: Get Report Descriptor Size | |
69 | This ioctl will get the size of the device's report descriptor. | |
70 | ||
71 | HIDIOCGRDESC: Get Report Descriptor | |
72 | This ioctl returns the device's report descriptor using a | |
73 | hidraw_report_descriptor struct. Make sure to set the size field of the | |
74 | hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE. | |
75 | ||
76 | HIDIOCGRAWINFO: Get Raw Info | |
77 | This ioctl will return a hidraw_devinfo struct containing the bus type, the | |
78 | vendor ID (VID), and product ID (PID) of the device. The bus type can be one | |
79 | of: | |
80 | BUS_USB | |
81 | BUS_HIL | |
82 | BUS_BLUETOOTH | |
83 | BUS_VIRTUAL | |
84 | which are defined in linux/input.h. | |
85 | ||
86 | HIDIOCGRAWNAME(len): Get Raw Name | |
87 | This ioctl returns a string containing the vendor and product strings of | |
88 | the device. The returned string is Unicode, UTF-8 encoded. | |
89 | ||
90 | HIDIOCGRAWPHYS(len): Get Physical Address | |
91 | This ioctl returns a string representing the physical address of the device. | |
92 | For USB devices, the string contains the physical path to the device (the | |
93 | USB controller, hubs, ports, etc). For Bluetooth devices, the string | |
94 | contains the hardware (MAC) address of the device. | |
95 | ||
96 | HIDIOCSFEATURE(len): Send a Feature Report | |
97 | This ioctl will send a feature report to the device. Per the HID | |
98 | specification, feature reports are always sent using the control endpoint. | |
99 | Set the first byte of the supplied buffer to the report number. For devices | |
100 | which do not use numbered reports, set the first byte to 0. The report data | |
101 | begins in the second byte. Make sure to set len accordingly, to one more | |
102 | than the length of the report (to account for the report number). | |
103 | ||
104 | HIDIOCGFEATURE(len): Get a Feature Report | |
105 | This ioctl will request a feature report from the device using the control | |
106 | endpoint. The first byte of the supplied buffer should be set to the report | |
107 | number of the requested report. For devices which do not use numbered | |
108 | reports, set the first byte to 0. The report will be returned starting at | |
109 | the first byte of the buffer (ie: the report number is not returned). | |
110 | ||
111 | Example | |
112 | --------- | |
113 | In samples/, find hid-example.c, which shows examples of read(), write(), | |
114 | and all the ioctls for hidraw. The code may be used by anyone for any | |
115 | purpose, and can serve as a starting point for developing applications using | |
116 | hidraw. | |
117 | ||
118 | Document by: | |
119 | Alan Ott <alan@signal11.us>, Signal 11 Software |