keii.dev
1## HIDAPI library for Windows, Linux, FreeBSD and macOS
2
3| CI instance | Status |
4|----------------------|--------|
5| `Linux/macOS/Windows (master)` | [](https://github.com/libusb/hidapi/actions/workflows/builds.yml?query=branch%3Amaster) |
6| `Windows (master)` | [](https://ci.appveyor.com/project/libusb/hidapi/branch/master) |
7| `BSD, last build (branch/PR)` | [](https://builds.sr.ht/~z3ntu/hidapi) |
8| `Coverity Scan (last)` |  |
9
10HIDAPI is a multi-platform library which allows an application to interface
11with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and macOS.
12HIDAPI can be either built as a shared library (`.so`, `.dll` or `.dylib`) or
13can be embedded directly into a target application by adding a _single source_
14file (per platform) and a single header.<br>
15See [remarks](BUILD.md#embedding-hidapi-directly-into-your-source-tree) on embedding _directly_ into your build system.
16
17HIDAPI library was originally developed by Alan Ott ([signal11](https://github.com/signal11)).
18
19It was moved to [libusb/hidapi](https://github.com/libusb/hidapi) on June 4th, 2019, in order to merge important bugfixes and continue development of the library.
20
21## Table of Contents
22
23* [About](#about)
24 * [Test GUI](#test-gui)
25 * [Console Test App](#console-test-app)
26* [What Does the API Look Like?](#what-does-the-api-look-like)
27* [License](#license)
28* [Installing HIDAPI](#installing-hidapi)
29* [Build from Source](#build-from-source)
30
31
32## About
33
34### HIDAPI has four back-ends:
35* Windows (using `hid.dll`)
36* Linux/hidraw (using the Kernel's hidraw driver)
37* libusb (using libusb-1.0 - Linux/BSD/other UNIX-like systems)
38* macOS (using IOHidManager)
39
40On Linux, either the hidraw or the libusb back-end can be used. There are
41tradeoffs, and the functionality supported is slightly different. Both are
42built by default. It is up to the application linking to hidapi to choose
43the backend at link time by linking to either `libhidapi-libusb` or
44`libhidapi-hidraw`.
45
46Note that you will need to install an udev rule file with your application
47for unprivileged users to be able to access HID devices with hidapi. Refer
48to the [69-hid.rules](udev/69-hid.rules) file in the `udev` directory
49for an example.
50
51#### __Linux/hidraw__ (`linux/hid.c`):
52
53This back-end uses the hidraw interface in the Linux kernel, and supports
54both USB and Bluetooth HID devices. It requires kernel version at least 2.6.39
55to build. In addition, it will only communicate with devices which have hidraw
56nodes associated with them.
57Keyboards, mice, and some other devices which are blacklisted from having
58hidraw nodes will not work. Fortunately, for nearly all the uses of hidraw,
59this is not a problem.
60
61#### __Linux/FreeBSD/libusb__ (`libusb/hid.c`):
62
63This back-end uses libusb-1.0 to communicate directly to a USB device. This
64back-end will of course not work with Bluetooth devices.
65
66### Test GUI
67
68HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses
69Fox Toolkit <http://www.fox-toolkit.org>. It will build on every platform
70which HIDAPI supports. Since it relies on a 3rd party library, building it
71is optional but it is useful when debugging hardware.
72
73NOTE: Test GUI based on Fox Toolkit is not actively developed nor supported
74by HIDAPI team. It is kept as a historical artifact. It may even work sometime
75or on some platforms, but it is not going to get any new features or bugfixes.
76
77Instructions for installing Fox-Toolkit on each platform is not provided.
78Make sure to use Fox-Toolkit v1.6 if you choose to use it.
79
80### Console Test App
81
82If you want to play around with your HID device before starting
83any development with HIDAPI and using a GUI app is not an option for you, you may try [`hidapitester`](https://github.com/todbot/hidapitester).
84
85This app has a console interface for most of the features supported
86by HIDAPI library.
87
88## What Does the API Look Like?
89
90The API provides the most commonly used HID functions including sending
91and receiving of input, output, and feature reports. The sample program,
92which communicates with a heavily hacked up version of the Microchip USB
93Generic HID sample looks like this (with error checking removed for
94simplicity):
95
96**Warning: Only run the code you understand, and only when it conforms to the
97device spec. Writing data (`hid_write`) at random to your HID devices can break them.**
98
99```c
100#include <stdio.h> // printf
101#include <wchar.h> // wchar_t
102
103#include <hidapi.h>
104
105#define MAX_STR 255
106
107int main(int argc, char* argv[])
108{
109 int res;
110 unsigned char buf[65];
111 wchar_t wstr[MAX_STR];
112 hid_device *handle;
113 int i;
114
115 // Initialize the hidapi library
116 res = hid_init();
117
118 // Open the device using the VID, PID,
119 // and optionally the Serial number.
120 handle = hid_open(0x4d8, 0x3f, NULL);
121 if (!handle) {
122 printf("Unable to open device\n");
123 hid_exit();
124 return 1;
125 }
126
127 // Read the Manufacturer String
128 res = hid_get_manufacturer_string(handle, wstr, MAX_STR);
129 printf("Manufacturer String: %ls\n", wstr);
130
131 // Read the Product String
132 res = hid_get_product_string(handle, wstr, MAX_STR);
133 printf("Product String: %ls\n", wstr);
134
135 // Read the Serial Number String
136 res = hid_get_serial_number_string(handle, wstr, MAX_STR);
137 printf("Serial Number String: (%d) %ls\n", wstr[0], wstr);
138
139 // Read Indexed String 1
140 res = hid_get_indexed_string(handle, 1, wstr, MAX_STR);
141 printf("Indexed String 1: %ls\n", wstr);
142
143 // Toggle LED (cmd 0x80). The first byte is the report number (0x0).
144 buf[0] = 0x0;
145 buf[1] = 0x80;
146 res = hid_write(handle, buf, 65);
147
148 // Request state (cmd 0x81). The first byte is the report number (0x0).
149 buf[0] = 0x0;
150 buf[1] = 0x81;
151 res = hid_write(handle, buf, 65);
152
153 // Read requested state
154 res = hid_read(handle, buf, 65);
155
156 // Print out the returned buffer.
157 for (i = 0; i < 4; i++)
158 printf("buf[%d]: %d\n", i, buf[i]);
159
160 // Close the device
161 hid_close(handle);
162
163 // Finalize the hidapi library
164 res = hid_exit();
165
166 return 0;
167}
168```
169
170You can also use [hidtest/test.c](hidtest/test.c)
171as a starting point for your applications.
172
173
174## License
175
176HIDAPI may be used by one of three licenses as outlined in [LICENSE.txt](LICENSE.txt).
177
178## Installing HIDAPI
179
180If you want to build your own application that uses HID devices with HIDAPI,
181you need to get HIDAPI development package.
182
183Depending on what your development environment is, HIDAPI likely to be provided
184by your package manager.
185
186For instance on Ubuntu, HIDAPI is available via APT:
187```sh
188sudo apt install libhidapi-dev
189```
190
191HIDAPI package name for other systems/package managers may differ.
192Check the documentation/package list of your package manager.
193
194## Build from Source
195
196Check [BUILD.md](BUILD.md) for details.