Commit | Line | Data |
---|---|---|
cca47861 MCC |
1 | ================================================================ |
2 | HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices | |
3 | ================================================================ | |
c54ea491 AO |
4 | |
5 | The hidraw driver provides a raw interface to USB and Bluetooth Human | |
6 | Interface Devices (HIDs). It differs from hiddev in that reports sent and | |
7 | received are not parsed by the HID parser, but are sent to and received from | |
8 | the device unmodified. | |
9 | ||
10 | Hidraw should be used if the userspace application knows exactly how to | |
11 | communicate with the hardware device, and is able to construct the HID | |
12 | reports manually. This is often the case when making userspace drivers for | |
13 | custom HID devices. | |
14 | ||
15 | Hidraw is also useful for communicating with non-conformant HID devices | |
16 | which send and receive data in a way that is inconsistent with their report | |
17 | descriptors. Because hiddev parses reports which are sent and received | |
18 | through it, checking them against the device's report descriptor, such | |
19 | communication with these non-conformant devices is impossible using hiddev. | |
20 | Hidraw is the only alternative, short of writing a custom kernel driver, for | |
21 | these non-conformant devices. | |
22 | ||
23 | A benefit of hidraw is that its use by userspace applications is independent | |
1c900363 | 24 | of the underlying hardware type. Currently, hidraw is implemented for USB |
c54ea491 AO |
25 | and Bluetooth. In the future, as new hardware bus types are developed which |
26 | use the HID specification, hidraw will be expanded to add support for these | |
27 | new bus types. | |
28 | ||
29 | Hidraw uses a dynamic major number, meaning that udev should be relied on to | |
30 | create hidraw device nodes. Udev will typically create the device nodes | |
31 | directly under /dev (eg: /dev/hidraw0). As this location is distribution- | |
32 | and udev rule-dependent, applications should use libudev to locate hidraw | |
33 | devices attached to the system. There is a tutorial on libudev with a | |
1c900363 | 34 | working example at:: |
cca47861 | 35 | |
c54ea491 | 36 | http://www.signal11.us/oss/udev/ |
1c900363 | 37 | https://web.archive.org/web/2019*/www.signal11.us |
c54ea491 AO |
38 | |
39 | The HIDRAW API | |
40 | --------------- | |
41 | ||
42 | read() | |
43 | ------- | |
44 | read() will read a queued report received from the HID device. On USB | |
45 | devices, the reports read using read() are the reports sent from the device | |
46 | on the INTERRUPT IN endpoint. By default, read() will block until there is | |
47 | a report available to be read. read() can be made non-blocking, by passing | |
48 | the O_NONBLOCK flag to open(), or by setting the O_NONBLOCK flag using | |
49 | fcntl(). | |
50 | ||
51 | On a device which uses numbered reports, the first byte of the returned data | |
52 | will be the report number; the report data follows, beginning in the second | |
53 | byte. For devices which do not use numbered reports, the report data | |
54 | will begin at the first byte. | |
55 | ||
56 | write() | |
cca47861 | 57 | ------- |
c54ea491 AO |
58 | The write() function will write a report to the device. For USB devices, if |
59 | the device has an INTERRUPT OUT endpoint, the report will be sent on that | |
60 | endpoint. If it does not, the report will be sent over the control endpoint, | |
61 | using a SET_REPORT transfer. | |
62 | ||
63 | The first byte of the buffer passed to write() should be set to the report | |
64 | number. If the device does not use numbered reports, the first byte should | |
65 | be set to 0. The report data itself should begin at the second byte. | |
66 | ||
67 | ioctl() | |
cca47861 | 68 | ------- |
c54ea491 AO |
69 | Hidraw supports the following ioctls: |
70 | ||
cca47861 MCC |
71 | HIDIOCGRDESCSIZE: |
72 | Get Report Descriptor Size | |
73 | ||
c54ea491 AO |
74 | This ioctl will get the size of the device's report descriptor. |
75 | ||
cca47861 MCC |
76 | HIDIOCGRDESC: |
77 | Get Report Descriptor | |
78 | ||
c54ea491 AO |
79 | This ioctl returns the device's report descriptor using a |
80 | hidraw_report_descriptor struct. Make sure to set the size field of the | |
81 | hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE. | |
82 | ||
cca47861 MCC |
83 | HIDIOCGRAWINFO: |
84 | Get Raw Info | |
85 | ||
c54ea491 AO |
86 | This ioctl will return a hidraw_devinfo struct containing the bus type, the |
87 | vendor ID (VID), and product ID (PID) of the device. The bus type can be one | |
cca47861 MCC |
88 | of:: |
89 | ||
90 | - BUS_USB | |
91 | - BUS_HIL | |
92 | - BUS_BLUETOOTH | |
93 | - BUS_VIRTUAL | |
94 | ||
1e1f780f | 95 | which are defined in uapi/linux/input.h. |
c54ea491 | 96 | |
cca47861 MCC |
97 | HIDIOCGRAWNAME(len): |
98 | Get Raw Name | |
99 | ||
c54ea491 AO |
100 | This ioctl returns a string containing the vendor and product strings of |
101 | the device. The returned string is Unicode, UTF-8 encoded. | |
102 | ||
cca47861 MCC |
103 | HIDIOCGRAWPHYS(len): |
104 | Get Physical Address | |
105 | ||
c54ea491 AO |
106 | This ioctl returns a string representing the physical address of the device. |
107 | For USB devices, the string contains the physical path to the device (the | |
108 | USB controller, hubs, ports, etc). For Bluetooth devices, the string | |
109 | contains the hardware (MAC) address of the device. | |
110 | ||
cca47861 MCC |
111 | HIDIOCSFEATURE(len): |
112 | Send a Feature Report | |
113 | ||
c54ea491 AO |
114 | This ioctl will send a feature report to the device. Per the HID |
115 | specification, feature reports are always sent using the control endpoint. | |
116 | Set the first byte of the supplied buffer to the report number. For devices | |
117 | which do not use numbered reports, set the first byte to 0. The report data | |
118 | begins in the second byte. Make sure to set len accordingly, to one more | |
119 | than the length of the report (to account for the report number). | |
120 | ||
cca47861 MCC |
121 | HIDIOCGFEATURE(len): |
122 | Get a Feature Report | |
123 | ||
c54ea491 AO |
124 | This ioctl will request a feature report from the device using the control |
125 | endpoint. The first byte of the supplied buffer should be set to the report | |
126 | number of the requested report. For devices which do not use numbered | |
f43d3870 DC |
127 | reports, set the first byte to 0. The returned report buffer will contain the |
128 | report number in the first byte, followed by the report data read from the | |
129 | device. For devices which do not use numbered reports, the report data will | |
130 | begin at the first byte of the returned buffer. | |
131 | ||
132 | HIDIOCSINPUT(len): | |
133 | Send an Input Report | |
134 | ||
135 | This ioctl will send an input report to the device, using the control endpoint. | |
136 | In most cases, setting an input HID report on a device is meaningless and has | |
137 | no effect, but some devices may choose to use this to set or reset an initial | |
138 | state of a report. The format of the buffer issued with this report is identical | |
139 | to that of HIDIOCSFEATURE. | |
140 | ||
141 | HIDIOCGINPUT(len): | |
142 | Get an Input Report | |
143 | ||
144 | This ioctl will request an input report from the device using the control | |
145 | endpoint. This is slower on most devices where a dedicated In endpoint exists | |
146 | for regular input reports, but allows the host to request the value of a | |
147 | specific report number. Typically, this is used to request the initial states of | |
148 | an input report of a device, before an application listens for normal reports via | |
149 | the regular device read() interface. The format of the buffer issued with this report | |
150 | is identical to that of HIDIOCGFEATURE. | |
151 | ||
152 | HIDIOCSOUTPUT(len): | |
153 | Send an Output Report | |
154 | ||
155 | This ioctl will send an output report to the device, using the control endpoint. | |
156 | This is slower on most devices where a dedicated Out endpoint exists for regular | |
157 | output reports, but is added for completeness. Typically, this is used to set | |
158 | the initial states of an output report of a device, before an application sends | |
159 | updates via the regular device write() interface. The format of the buffer issued | |
160 | with this report is identical to that of HIDIOCSFEATURE. | |
161 | ||
162 | HIDIOCGOUTPUT(len): | |
163 | Get an Output Report | |
164 | ||
165 | This ioctl will request an output report from the device using the control | |
2f7f4efb | 166 | endpoint. Typically, this is used to retrieve the initial state of |
f43d3870 DC |
167 | an output report of a device, before an application updates it as necessary either |
168 | via a HIDIOCSOUTPUT request, or the regular device write() interface. The format | |
169 | of the buffer issued with this report is identical to that of HIDIOCGFEATURE. | |
c54ea491 AO |
170 | |
171 | Example | |
cca47861 | 172 | ------- |
c54ea491 AO |
173 | In samples/, find hid-example.c, which shows examples of read(), write(), |
174 | and all the ioctls for hidraw. The code may be used by anyone for any | |
175 | purpose, and can serve as a starting point for developing applications using | |
176 | hidraw. | |
177 | ||
178 | Document by: | |
cca47861 | 179 | |
c54ea491 | 180 | Alan Ott <alan@signal11.us>, Signal 11 Software |