Hid API for Linux, Mac OS X, and Windows

ArticleDirectory

• About
• What does the API look like?
• License
• Download
• Build instructions
• Contact

About

 

Hidapi is a multi-platform library which allows an application to interface with USB and Bluetooth hid-class devices on Windows, Linux, and Mac OS X. while it can be used to communicate with standard hid devices like keyboards, mice, and joysticks, it is most useful when used with venm (vendor-defined) hid devices. using devices do this in order to not require a custom driver to be written for each platform. hidapi is easy to integrate with the client application, just requiring a single source file to be dropped into the application. on Windows, hidapi can optionally be built into a DLL.

Programs which use hidapi are driverless, meaning they do not require the use of a custom driver for each device on each platform.

Hidapi provides a clean and consistent interface for each platform, making it easier to develop applications which communicate with USB hid devices without having to know the details of the hid libraries and interfaces on each platform.

The hidapi source also provides a GUI test application which can enumerate and communicate with any HID device attached to the system. The test GUI compiles and runs on all platforms supported by hidapi.

 

What does the API look like?

Doxygen HTML documentation can be found here.

The API provides an easy method to enumerate hid devices attached to the system, and easy access toFunctionality of the most commonly used hid functions including transfer of input, output, and feature reports. The sample program, which communicates with a modified version ofUSB generic hidSample which is part ofMicrochip application library(In folder"Microchip solutions \ USB device-hid-custom demos \ Generic hid-firmware"When the microchip application framework is installed), looks like this (with error checking removed for simplicity ):

 

# Include   <Stdio. h> # Include  <Stdlib. h> # Include   "Hidapi. H"  Int   Main ( Int Argc, Char * Argv []) { Int Res; Unsigned   Char Buf [65]; # define max_str 255wchar_t wstr [max_str]; hid_device * handle; Int I; // Enumerate and print the hid devices on the System  Struct Hid_device_info * devs, * cur_dev; Devs = hid_enumerate (0x0, 0x0); cur_dev = Devs; While (Cur_dev) {printf ( "Device found \ n type: % 04hx % 04hx \ n path: % s \ n serial_number: % ls" , Cur_dev-> vendor_id, cur_dev-> product_id, cur_dev-> path, cur_dev-> serial_number); printf ( "\ N" ); Printf ( "Manufacturer: % ls \ n" , Cur_dev-> manufacturer_string); printf ( "Product: % ls \ n" , Cur_dev-> product_string); printf ( "\ N" ); Cur_dev = cur_dev-> next;} hid_free_enumeration (Devs ); // 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); printf ( "Manufacturer string: % ls \ n" , Wstr ); // Read the product string Res = hid_get_product_string (handle, wstr, max_str); printf ( "Product string: % ls \ n" , Wstr );// Read the serial number string Res = hid_get_serial_number_string (handle, wstr, max_str); printf ( "Serial number string: % ls" , Wstr); printf ( "\ N" ); // Send a feature report to the device Buf [0] = 0x2; // First byte is Report Number Buf [1] = 0xa0; Buf [2] = 0x0a; Res = hid_send_feature_report (handle, Buf, 17 ); // Read a feature report from the device Buf [0] = 0x2; Res = hid_get_feature_report (handle, Buf, Sizeof (BUF ));// Print out the returned buffer. Printf ( "Feature report \ n" ); For (I = 0; I <res; I ++) printf ( "% 02hhx" , Buf [I]); printf ( "\ N" ); // Set the hid_read () function to be non-blocking. Hid_set_nonblocking (handle, 1 ); // Send an output report to toggle the LED (CMD 0x80) Buf [0] = 1; // First byte is Report Number Buf [1] = 0x80; Res = hid_write (handle, Buf, 65 );// Send an output report to request the State (CMD 0x81) Buf [1] = 0x81; hid_write (handle, Buf, 65 ); // Read requested State Res = hid_read (handle, Buf, 65 ); If (RES <0) printf ( "Unable to read () \ n" ); // Print out the returned buffer.  For (I = 0; I <res; I ++) printf ( "Buf [% d]: % d \ n" , I, Buf [I]); Return 0 ;}

 

 

License

Hidapi may be used by one of three licenses as outlined in license.txt. These licenses are:

• GPL V3 (see LICENSE-gpl3.txt ),
• BSD (see LICENSE-bsd.txt ),
• The more liberal original hidapi license (see LICENSE-orig.txt ).

The user of hidapi (the developer who uses hidapi in their code) can choose to use hidapi under any of the three licenses at their discretion. For example:

1. An author of GPL software wowould likely use hidapi under the terms of the GPL.
2. An author of specified cial, closed-source software wowould likely use hidapi under the terms of either the BSD-style license or the original hidapi license.

The idea is to make hidapi accessable to as your users as possible for both open-and closed-source applications, and to give users the flexibility to link with the code in any way they see fit.

 

 

Download

Hidapi can be downloaded fromGitHub.A zip file is available fromDownload Page.To get the latest trunk revision (if you have git installed, run the following:

 
Git clone git: // github.com/signal11/hidapi.git
 

 

 

Build instructions

 

Windows: 
Build. SlnFile inWindows/Directory using Visual Studio.

Linux: 
Change toLinux/Directory and runMake.

Mac OS X: 
Change toMAC/Directory and runMake.

To build the test Gui: 

• On Windows, build. SlnFile inHidtest/Directory. Make sure to first set up the externals (Fox Toolkit) as described in readme.txt.
• On Linux and Mac, runMakeFromHidtest/Directory. Make sure to first install fox-Toolkit as described in readme.txt

 

 

Contact

 

A mailing list is to be set up soon. For the time being, please direct inquiries and questions to alan@signal11.us.