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