hidapi-master.zip_HIDApi_QT HIDAPI_Quick

HIDAPI library for Windows, Linux, FreeBSD and Mac OS X ========================================================= About ====== HIDAPI is a multi-platform library which allows an application to interface with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and Mac OS X. HIDAPI can be either built as a shared library (.so or .dll) or can be embedded directly into a target application by adding a single source file (per platform) and a single header. HIDAPI has four 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. While this back-end will support both USB and Bluetooth, it has some limitations on kernels prior to 2.6.39, including the inability to send or receive feature reports. 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-libusb.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 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): #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]); // Finalize the hidapi library res = hid_exit(); return 0; } If you have your own simple test programs which communicate with standard hardware development boards (such as those from Microchip, TI, Atmel, FreeScale and others), please consider sending me something like the above for inclusion into the HIDAPI source. This will help others who have the same hardware as you do. License ======== HIDAPI may be used by one of three licenses as outlined in LICENSE.txt. Download ========= HIDAPI can be downloaded from github git clone git://github.com/signal11/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: 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: 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: pkg_add -r gmake libiconv fox16 If you downloaded the source directly from the git repository (using git clone), you'll need Autotools: 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: 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 installed using ports uses the ports X11 libraries which are not compatible with the Apple X11 libraries. If you install Fox with ports and then try to distribute your built app bundle, it will simply fail to run on other systems. To install Fox-Toolkit manually, download the source package from http://www.fox-toolkit.org, extract it, and run the following from within the extracted source: ./configure && make && make install Windows: --------- On Windows, if you want to build the test GUI, you will need to get the hidapi-externals.zip package from the download site. This contains pre-built binaries for Fox-toolkit. Extract hidapi-externals.zip just outside of hidapi, so that hidapi-externals and hidapi are on the same level, as shown: Parent_Folder | +hidapi +hidapi-externals Again, this step is not required if you do not wish to build the test GUI. Building HIDAPI into a shared library on Unix Platforms: --------------------------------------------------------- On Unix-like systems such as Linux, FreeBSD, Mac, and even Windows, using Mingw or Cygwin, the easiest way to build a standard system-installed shared library is to use the GNU Autotools build system. If you checked out the source from the git repository, run the following: ./bootstrap ./configure make make install <----- as root, or using sudo If you downloaded a source package (ie: if you did not run git clone), you can skip the ./bootstrap step. ./configure can take several argum