src/hidapi/README.txt
author Sam Lantinga <slouken@libsdl.org>
Tue, 16 Oct 2018 08:29:27 -0700
changeset 12332 c80f702e4b8b
parent 12098 8eb14aba4e87
child 12958 b810b78d32cc
permissions -rw-r--r--
Support vibration magnitude on Android 8.0 (thanks Rachel!)
     1          HIDAPI library for Windows, Linux, FreeBSD and Mac OS X
     2         =========================================================
     3 
     4 About
     5 ======
     6 
     7 HIDAPI is a multi-platform library which allows an application to interface
     8 with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and Mac
     9 OS X.  HIDAPI can be either built as a shared library (.so or .dll) or
    10 can be embedded directly into a target application by adding a single source
    11 file (per platform) and a single header.
    12 
    13 HIDAPI has four back-ends:
    14 	* Windows (using hid.dll)
    15 	* Linux/hidraw (using the Kernel's hidraw driver)
    16 	* Linux/libusb (using libusb-1.0)
    17 	* FreeBSD (using libusb-1.0)
    18 	* Mac (using IOHidManager)
    19 
    20 On Linux, either the hidraw or the libusb back-end can be used. There are
    21 tradeoffs, and the functionality supported is slightly different.
    22 
    23 Linux/hidraw (linux/hid.c):
    24 This back-end uses the hidraw interface in the Linux kernel.  While this
    25 back-end will support both USB and Bluetooth, it has some limitations on
    26 kernels prior to 2.6.39, including the inability to send or receive feature
    27 reports.  In addition, it will only communicate with devices which have
    28 hidraw nodes associated with them.  Keyboards, mice, and some other devices
    29 which are blacklisted from having hidraw nodes will not work. Fortunately,
    30 for nearly all the uses of hidraw, this is not a problem.
    31 
    32 Linux/FreeBSD/libusb (libusb/hid.c):
    33 This back-end uses libusb-1.0 to communicate directly to a USB device. This
    34 back-end will of course not work with Bluetooth devices.
    35 
    36 HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses
    37 Fox Toolkit (http://www.fox-toolkit.org).  It will build on every platform
    38 which HIDAPI supports.  Since it relies on a 3rd party library, building it
    39 is optional but recommended because it is so useful when debugging hardware.
    40 
    41 What Does the API Look Like?
    42 =============================
    43 The API provides the the most commonly used HID functions including sending
    44 and receiving of input, output, and feature reports.  The sample program,
    45 which communicates with a heavily hacked up version of the Microchip USB
    46 Generic HID sample looks like this (with error checking removed for
    47 simplicity):
    48 
    49 #ifdef WIN32
    50 #include <windows.h>
    51 #endif
    52 #include <stdio.h>
    53 #include <stdlib.h>
    54 #include "hidapi.h"
    55 
    56 #define MAX_STR 255
    57 
    58 int main(int argc, char* argv[])
    59 {
    60 	int res;
    61 	unsigned char buf[65];
    62 	wchar_t wstr[MAX_STR];
    63 	hid_device *handle;
    64 	int i;
    65 
    66 	// Initialize the hidapi library
    67 	res = hid_init();
    68 
    69 	// Open the device using the VID, PID,
    70 	// and optionally the Serial number.
    71 	handle = hid_open(0x4d8, 0x3f, NULL);
    72 
    73 	// Read the Manufacturer String
    74 	res = hid_get_manufacturer_string(handle, wstr, MAX_STR);
    75 	wprintf(L"Manufacturer String: %s\n", wstr);
    76 
    77 	// Read the Product String
    78 	res = hid_get_product_string(handle, wstr, MAX_STR);
    79 	wprintf(L"Product String: %s\n", wstr);
    80 
    81 	// Read the Serial Number String
    82 	res = hid_get_serial_number_string(handle, wstr, MAX_STR);
    83 	wprintf(L"Serial Number String: (%d) %s\n", wstr[0], wstr);
    84 
    85 	// Read Indexed String 1
    86 	res = hid_get_indexed_string(handle, 1, wstr, MAX_STR);
    87 	wprintf(L"Indexed String 1: %s\n", wstr);
    88 
    89 	// Toggle LED (cmd 0x80). The first byte is the report number (0x0).
    90 	buf[0] = 0x0;
    91 	buf[1] = 0x80;
    92 	res = hid_write(handle, buf, 65);
    93 
    94 	// Request state (cmd 0x81). The first byte is the report number (0x0).
    95 	buf[0] = 0x0;
    96 	buf[1] = 0x81;
    97 	res = hid_write(handle, buf, 65);
    98 
    99 	// Read requested state
   100 	res = hid_read(handle, buf, 65);
   101 
   102 	// Print out the returned buffer.
   103 	for (i = 0; i < 4; i++)
   104 		printf("buf[%d]: %d\n", i, buf[i]);
   105 
   106 	// Finalize the hidapi library
   107 	res = hid_exit();
   108 
   109 	return 0;
   110 }
   111 
   112 If you have your own simple test programs which communicate with standard
   113 hardware development boards (such as those from Microchip, TI, Atmel,
   114 FreeScale and others), please consider sending me something like the above
   115 for inclusion into the HIDAPI source.  This will help others who have the
   116 same hardware as you do.
   117 
   118 License
   119 ========
   120 HIDAPI may be used by one of three licenses as outlined in LICENSE.txt.
   121 
   122 Download
   123 =========
   124 HIDAPI can be downloaded from github
   125 	git clone git://github.com/signal11/hidapi.git
   126 
   127 Build Instructions
   128 ===================
   129 
   130 This section is long. Don't be put off by this. It's not long because it's
   131 complicated to build HIDAPI; it's quite the opposite.  This section is long
   132 because of the flexibility of HIDAPI and the large number of ways in which
   133 it can be built and used.  You will likely pick a single build method.
   134 
   135 HIDAPI can be built in several different ways. If you elect to build a
   136 shared library, you will need to build it from the HIDAPI source
   137 distribution.  If you choose instead to embed HIDAPI directly into your
   138 application, you can skip the building and look at the provided platform
   139 Makefiles for guidance.  These platform Makefiles are located in linux/
   140 libusb/ mac/ and windows/ and are called Makefile-manual.  In addition,
   141 Visual Studio projects are provided.  Even if you're going to embed HIDAPI
   142 into your project, it is still beneficial to build the example programs.
   143 
   144 
   145 Prerequisites:
   146 ---------------
   147 
   148 	Linux:
   149 	-------
   150 	On Linux, you will need to install development packages for libudev,
   151 	libusb and optionally Fox-toolkit (for the test GUI). On
   152 	Debian/Ubuntu systems these can be installed by running:
   153 	    sudo apt-get install libudev-dev libusb-1.0-0-dev libfox-1.6-dev
   154 
   155 	If you downloaded the source directly from the git repository (using
   156 	git clone), you'll need Autotools:
   157 	    sudo apt-get install autotools-dev autoconf automake libtool
   158 
   159 	FreeBSD:
   160 	---------
   161 	On FreeBSD you will need to install GNU make, libiconv, and
   162 	optionally Fox-Toolkit (for the test GUI). This is done by running
   163 	the following:
   164 	    pkg_add -r gmake libiconv fox16
   165 
   166 	If you downloaded the source directly from the git repository (using
   167 	git clone), you'll need Autotools:
   168 	    pkg_add -r autotools
   169 
   170 	Mac:
   171 	-----
   172 	On Mac, you will need to install Fox-Toolkit if you wish to build
   173 	the Test GUI. There are two ways to do this, and each has a slight
   174 	complication. Which method you use depends on your use case.
   175 
   176 	If you wish to build the Test GUI just for your own testing on your
   177 	own computer, then the easiest method is to install Fox-Toolkit
   178 	using ports:
   179 		sudo port install fox
   180 
   181 	If you wish to build the TestGUI app bundle to redistribute to
   182 	others, you will need to install Fox-toolkit from source.  This is
   183 	because the version of fox that gets installed using ports uses the
   184 	ports X11 libraries which are not compatible with the Apple X11
   185 	libraries.  If you install Fox with ports and then try to distribute
   186 	your built app bundle, it will simply fail to run on other systems.
   187 	To install Fox-Toolkit manually, download the source package from
   188 	http://www.fox-toolkit.org, extract it, and run the following from
   189 	within the extracted source:
   190 		./configure && make && make install
   191 
   192 	Windows:
   193 	---------
   194 	On Windows, if you want to build the test GUI, you will need to get
   195 	the hidapi-externals.zip package from the download site.  This
   196 	contains pre-built binaries for Fox-toolkit.  Extract
   197 	hidapi-externals.zip just outside of hidapi, so that
   198 	hidapi-externals and hidapi are on the same level, as shown:
   199 
   200 	     Parent_Folder
   201 	       |
   202 	       +hidapi
   203 	       +hidapi-externals
   204 
   205 	Again, this step is not required if you do not wish to build the
   206 	test GUI.
   207 
   208 
   209 Building HIDAPI into a shared library on Unix Platforms:
   210 ---------------------------------------------------------
   211 
   212 On Unix-like systems such as Linux, FreeBSD, Mac, and even Windows, using
   213 Mingw or Cygwin, the easiest way to build a standard system-installed shared
   214 library is to use the GNU Autotools build system.  If you checked out the
   215 source from the git repository, run the following:
   216 
   217 	./bootstrap
   218 	./configure
   219 	make
   220 	make install     <----- as root, or using sudo
   221 
   222 If you downloaded a source package (ie: if you did not run git clone), you
   223 can skip the ./bootstrap step.
   224 
   225 ./configure can take several arguments which control the build. The two most
   226 likely to be used are:
   227 	--enable-testgui
   228 		Enable build of the Test GUI. This requires Fox toolkit to
   229 		be installed.  Instructions for installing Fox-Toolkit on
   230 		each platform are in the Prerequisites section above.
   231 
   232 	--prefix=/usr
   233 		Specify where you want the output headers and libraries to
   234 		be installed. The example above will put the headers in
   235 		/usr/include and the binaries in /usr/lib. The default is to
   236 		install into /usr/local which is fine on most systems.
   237 
   238 Building the manual way on Unix platforms:
   239 -------------------------------------------
   240 
   241 Manual Makefiles are provided mostly to give the user and idea what it takes
   242 to build a program which embeds HIDAPI directly inside of it. These should
   243 really be used as examples only. If you want to build a system-wide shared
   244 library, use the Autotools method described above.
   245 
   246 	To build HIDAPI using the manual makefiles, change to the directory
   247 	of your platform and run make. For example, on Linux run:
   248 		cd linux/
   249 		make -f Makefile-manual
   250 
   251 	To build the Test GUI using the manual makefiles:
   252 		cd testgui/
   253 		make -f Makefile-manual
   254 
   255 Building on Windows:
   256 ---------------------
   257 
   258 To build the HIDAPI DLL on Windows using Visual Studio, build the .sln file
   259 in the windows/ directory.
   260 
   261 To build the Test GUI on windows using Visual Studio, build the .sln file in
   262 the testgui/ directory.
   263 
   264 To build HIDAPI using MinGW or Cygwin using Autotools, use the instructions
   265 in the section titled "Building HIDAPI into a shared library on Unix
   266 Platforms" above.  Note that building the Test GUI with MinGW or Cygwin will
   267 require the Windows procedure in the Prerequisites section above (ie:
   268 hidapi-externals.zip).
   269 
   270 To build HIDAPI using MinGW using the Manual Makefiles, see the section
   271 "Building the manual way on Unix platforms" above.
   272 
   273 HIDAPI can also be built using the Windows DDK (now also called the Windows
   274 Driver Kit or WDK). This method was originally required for the HIDAPI build
   275 but not anymore. However, some users still prefer this method. It is not as
   276 well supported anymore but should still work. Patches are welcome if it does
   277 not. To build using the DDK:
   278 
   279    1. Install the Windows Driver Kit (WDK) from Microsoft.
   280    2. From the Start menu, in the Windows Driver Kits folder, select Build
   281       Environments, then your operating system, then the x86 Free Build
   282       Environment (or one that is appropriate for your system).
   283    3. From the console, change directory to the windows/ddk_build/ directory,
   284       which is part of the HIDAPI distribution.
   285    4. Type build.
   286    5. You can find the output files (DLL and LIB) in a subdirectory created
   287       by the build system which is appropriate for your environment. On
   288       Windows XP, this directory is objfre_wxp_x86/i386.
   289 
   290 Cross Compiling
   291 ================
   292 
   293 This section talks about cross compiling HIDAPI for Linux using autotools.
   294 This is useful for using HIDAPI on embedded Linux targets.  These
   295 instructions assume the most raw kind of embedded Linux build, where all
   296 prerequisites will need to be built first.  This process will of course vary
   297 based on your embedded Linux build system if you are using one, such as
   298 OpenEmbedded or Buildroot.
   299 
   300 For the purpose of this section, it will be assumed that the following
   301 environment variables are exported.
   302 
   303 	$ export STAGING=$HOME/out
   304 	$ export HOST=arm-linux
   305 
   306 STAGING and HOST can be modified to suit your setup.
   307 
   308 Prerequisites
   309 --------------
   310 
   311 Note that the build of libudev is the very basic configuration.
   312 
   313 Build Libusb. From the libusb source directory, run:
   314 	./configure --host=$HOST --prefix=$STAGING
   315 	make
   316 	make install
   317 
   318 Build libudev. From the libudev source directory, run:
   319 	./configure --disable-gudev --disable-introspection --disable-hwdb \
   320 		 --host=$HOST --prefix=$STAGING
   321 	make
   322 	make install
   323 
   324 Building HIDAPI
   325 ----------------
   326 
   327 Build HIDAPI:
   328 
   329 	PKG_CONFIG_DIR= \
   330 	PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \
   331 	PKG_CONFIG_SYSROOT_DIR=$STAGING \
   332 	./configure --host=$HOST --prefix=$STAGING
   333 
   334 
   335 Signal 11 Software - 2010-04-11
   336                      2010-07-28
   337                      2011-09-10
   338                      2012-05-01
   339                      2012-07-03