README.txt
1
2There are two implementations of HIDAPI for Linux. One (linux/hid.c) uses the
3Linux hidraw driver, and the other (libusb/hid.c) uses libusb. Which one you
4use depends on your application. Complete functionality of the hidraw
5version depends on patches to the Linux kernel which are not currently in
6the mainline. These patches have to do with sending and receiving feature
7reports. The libusb implementation uses libusb to talk directly to the
8device, bypassing any Linux HID driver. The disadvantage of the libusb
9version is that it will only work with USB devices, while the hidraw
10implementation will work with Bluetooth devices as well.
11
12To use HIDAPI, simply drop either linux/hid.c or libusb/hid.c into your
13application and build using the build parameters in the Makefile.
14
15
16Libusb Implementation notes
17----------------------------
18For the libusb implementation, libusb-1.0 must be installed. Libusb 1.0 is
19different than the legacy libusb 0.1 which is installed on many systems. To
20install libusb-1.0 on Ubuntu and other Debian-based systems, run:
21 sudo apt-get install libusb-1.0-0-dev
22
23
24Hidraw Implementation notes
25----------------------------
26For the hidraw implementation, libudev headers and libraries are required to
27build hidapi programs. To install libudev libraries on Ubuntu,
28and other Debian-based systems, run:
29 sudo apt-get install libudev-dev
30
31On Redhat-based systems, run the following as root:
32 yum install libudev-devel
33
34Unfortunately, the hidraw driver, which the linux version of hidapi is based
35on, contains bugs in kernel versions < 2.6.36, which the client application
36should be aware of.
37
38Bugs (hidraw implementation only):
39-----------------------------------
40On Kernel versions < 2.6.34, if your device uses numbered reports, an extra
41byte will be returned at the beginning of all reports returned from read()
42for hidraw devices. This is worked around in the libary. No action should be
43necessary in the client library.
44
45On Kernel versions < 2.6.35, reports will only be sent using a Set_Report
46transfer on the CONTROL endpoint. No data will ever be sent on an Interrupt
47Out endpoint if one exists. This is fixed in 2.6.35. In 2.6.35, OUTPUT
48reports will be sent to the device on the first INTERRUPT OUT endpoint if it
49exists; If it does not exist, OUTPUT reports will be sent on the CONTROL
50endpoint.
51
52On Kernel versions < 2.6.36, add an extra byte containing the report number
53to sent reports if numbered reports are used, and the device does not
54contain an INTERRPUT OUT endpoint for OUTPUT transfers. For example, if
55your device uses numbered reports and wants to send {0x2 0xff 0xff 0xff} to
56the device (0x2 is the report number), you must send {0x2 0x2 0xff 0xff
570xff}. If your device has the optional Interrupt OUT endpoint, this does not
58apply (but really on 2.6.35 only, because 2.6.34 won't use the interrupt
59out endpoint).
60