hidapi

A Simple library for communicating with USB and Bluetooth HID devices on Linux, Mac and Windows.

Showing:

Popularity

Downloads/wk

0

GitHub Stars

607

Maintenance

Last Commit

3d ago

Contributors

93

Package

Dependencies

0

License

GNU GPLv3 or BSD or HIDAPI original

Categories

Readme

HIDAPI library for Windows, Linux, FreeBSD and macOS

CI instanceStatus
Linux/macOS/Windows masterGitHub Builds
Windows masterBuild status
Linux/BSD, last build (branch/PR)builds.sr.ht status

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).

It was moved to libusb/hidapi on June 4th, 2019, in order to merge important bugfixes and continue development of the library.

Table of Contents

About

HIDAPI has four back-ends:

  • Windows (using hid.dll)
  • Linux/hidraw (using the Kernel's hidraw driver)
  • libusb (using libusb-1.0 - Linux/BSD/other UNIX-like systems)
  • macOS (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. Both are built by default. It is up to the application linking to hidapi to choose the backend at link time by linking to either libhidapi-libusb or libhidapi-hidraw.

Note that you will need to install an udev rule file with your application for unprivileged users to be able to access HID devices with hidapi. Refer to the 69-hid.rules file in the udev directory for an example.

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.

Test GUI

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.

NOTE: Test GUI based on Fox Toolkit is not actively developed nor supported by HIDAPI team. It is kept as a historical artifact. It may even work sometime or on some platforms, but it is not going to get any new features or bugfixes.

Instructions for installing Fox-Toolkit on each platform is not provided. Make sure to use Fox-Toolkit v1.6 if you choose to use it.

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 (hid_write) at random to your HID devices can break them.

#include <stdio.h> // printf
#include <wchar.h> // wprintf

#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 as a starting point for your applications.

License

HIDAPI may be used by one of three licenses as outlined in LICENSE.txt.

Installing HIDAPI

If you want to build your own application that uses HID devices with HIDAPI, you need to get HIDAPI development package.

Depending on what your development environment is, HIDAPI likely to be provided by your package manager.

For instance on Ubuntu, HIDAPI is available via APT:

sudo apt install libhidapi-dev

HIDAPI package name for other systems/package managers may differ. Check the documentation/package list of your package manager.

Build from Source

Check BUILD.md for details.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial