## HIDAPI library for Windows, Linux, FreeBSD and macOS
| CI instance | Status |
|----------------------|--------|
| `macOS master` | [![Build Status](https://travis-ci.org/libusb/hidapi.svg?branch=master)](https://travis-ci.org/libusb/hidapi) |
| `Windows master` | [![Build status](https://ci.appveyor.com/api/projects/status/r482aevuigmi86rk/branch/master?svg=true)](https://ci.appveyor.com/project/Youw/hidapi/branch/master) |
| `Linux/BSD, last build (branch/PR)` | [![builds.sr.ht status](https://builds.sr.ht/~qbicz/hidapi.svg)](https://builds.sr.ht/~qbicz/hidapi?) |
HIDAPI is a multi-platform library which allows an application to interface
with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and macOS.
HIDAPI can be either built as a shared library (`.so`, `.dll` or `.dylib`) or
can be embedded directly into a target application by adding a single source
file (per platform) and a single header.
HIDAPI library was originally developed by Alan Ott ([signal11](https://github.com/signal11)).
It 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.
## Table of Contents
* [About](#about)
* [What Does the API Look Like?](#what-does-the-api-look-like)
* [License](#license)
* [Download](#download)
* [Build Instructions](#build-instructions)
* [Prerequisites](#prerequisites)
* [Linux](#linux)
* [FreeBSD](#freebsd)
* [Mac](#mac)
* [Windows](#windows)
* [Building HIDAPI into a shared library on Unix Platforms](#building-hidapi-into-a-shared-library-on-unix-platforms)
* [Building the manual way on Unix platforms](#building-the-manual-way-on-unix-platforms)
* [Building on Windows](#building-on-windows)
* [Cross Compiling](#cross-compiling)
* [Prerequisites](#prerequisites-1)
* [Building HIDAPI](#building-hidapi)
## About
HIDAPI has five back-ends:
* Windows (using `hid.dll`)
* Linux/hidraw (using the Kernel's hidraw driver)
* Linux/libusb (using libusb-1.0)
* FreeBSD (using libusb-1.0)
* Mac (using IOHidManager)
On Linux, either the hidraw or the libusb back-end can be used. There are
tradeoffs, and the functionality supported is slightly different.
__Linux/hidraw__ (`linux/hid.c`):
This back-end uses the hidraw interface in the Linux kernel, and supports
both USB and Bluetooth HID devices. It requires kernel version at least 2.6.39
to build. In addition, it will only communicate with devices which have hidraw
nodes associated with them.
Keyboards, mice, and some other devices which are blacklisted from having
hidraw nodes will not work. Fortunately, for nearly all the uses of hidraw,
this is not a problem.
__Linux/FreeBSD/libusb__ (`libusb/hid.c`):
This back-end uses libusb-1.0 to communicate directly to a USB device. This
back-end will of course not work with Bluetooth devices.
HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses
Fox Toolkit <http://www.fox-toolkit.org>. It will build on every platform
which HIDAPI supports. Since it relies on a 3rd party library, building it
is optional but recommended because it is so useful when debugging hardware.
## What Does the API Look Like?
The API provides the most commonly used HID functions including sending
and receiving of input, output, and feature reports. The sample program,
which communicates with a heavily hacked up version of the Microchip USB
Generic HID sample looks like this (with error checking removed for
simplicity):
**Warning: Only run the code you understand, and only when it conforms to the
device spec. Writing data at random to your HID devices can break them.**
```c
#ifdef WIN32
#include <windows.h>
#endif
#include <stdio.h>
#include <stdlib.h>
#include "hidapi.h"
#define MAX_STR 255
int main(int argc, char* argv[])
{
int res;
unsigned char buf[65];
wchar_t wstr[MAX_STR];
hid_device *handle;
int i;
// Initialize the hidapi library
res = hid_init();
// Open the device using the VID, PID,
// and optionally the Serial number.
handle = hid_open(0x4d8, 0x3f, NULL);
// Read the Manufacturer String
res = hid_get_manufacturer_string(handle, wstr, MAX_STR);
wprintf(L"Manufacturer String: %s\n", wstr);
// Read the Product String
res = hid_get_product_string(handle, wstr, MAX_STR);
wprintf(L"Product String: %s\n", wstr);
// Read the Serial Number String
res = hid_get_serial_number_string(handle, wstr, MAX_STR);
wprintf(L"Serial Number String: (%d) %s\n", wstr[0], wstr);
// Read Indexed String 1
res = hid_get_indexed_string(handle, 1, wstr, MAX_STR);
wprintf(L"Indexed String 1: %s\n", wstr);
// Toggle LED (cmd 0x80). The first byte is the report number (0x0).
buf[0] = 0x0;
buf[1] = 0x80;
res = hid_write(handle, buf, 65);
// Request state (cmd 0x81). The first byte is the report number (0x0).
buf[0] = 0x0;
buf[1] = 0x81;
res = hid_write(handle, buf, 65);
// Read requested state
res = hid_read(handle, buf, 65);
// Print out the returned buffer.
for (i = 0; i < 4; i++)
printf("buf[%d]: %d\n", i, buf[i]);
// Close the device
hid_close(handle);
// Finalize the hidapi library
res = hid_exit();
return 0;
}
```
You can also use [hidtest/test.c](hidtest/test.c)
as a starting point for your applications.
## License
HIDAPI may be used by one of three licenses as outlined in [LICENSE.txt](LICENSE.txt).
## Download
HIDAPI can be downloaded from GitHub
```sh
git clone git://github.com/libusb/hidapi.git
```
## Build Instructions
This section is long. Don't be put off by this. It's not long because it's
complicated to build HIDAPI; it's quite the opposite. This section is long
because of the flexibility of HIDAPI and the large number of ways in which
it can be built and used. You will likely pick a single build method.
HIDAPI can be built in several different ways. If you elect to build a
shared library, you will need to build it from the HIDAPI source
distribution. If you choose instead to embed HIDAPI directly into your
application, you can skip the building and look at the provided platform
Makefiles for guidance. These platform Makefiles are located in `linux/`,
`libusb/`, `mac/` and `windows/` and are called `Makefile-manual`. In addition,
Visual Studio projects are provided. Even if you're going to embed HIDAPI
into your project, it is still beneficial to build the example programs.
### Prerequisites:
#### Linux:
On Linux, you will need to install development packages for libudev,
libusb and optionally Fox-toolkit (for the test GUI). On
Debian/Ubuntu systems these can be installed by running:
```sh
sudo apt-get install libudev-dev libusb-1.0-0-dev libfox-1.6-dev
```
If you downloaded the source directly from the git repository (using
git clone), you'll need Autotools:
```sh
sudo apt-get install autotools-dev autoconf automake libtool
```
#### FreeBSD:
On FreeBSD you will need to install GNU make, libiconv, and
optionally Fox-Toolkit (for the test GUI). This is done by running
the following:
```sh
pkg_add -r gmake libiconv fox16
```
If you downloaded the source directly from the git repository (using
git clone), you'll need Autotools:
```sh
pkg_add -r autotools
```
#### Mac:
On Mac, you will need to install Fox-Toolkit if you wish to build
the Test GUI. There are two ways to do this, and each has a slight
complication. Which method you use depends on your use case.
If you wish to build the Test GUI just for your own testing on your
own computer, then the easiest method is to install Fox-Toolkit
using ports:
```sh
sudo port install fox
```
If you wish to build the TestGUI app bundle to redistribute to
others, you will need to install Fox-toolkit from source. This is
because the version of fox that gets install
评论0