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