src/hidapi/README.txt
author Ryan C. Gordon
Tue, 07 Apr 2020 14:03:13 -0400
changeset 13704 25edf3df6e51
parent 12958 b810b78d32cc
permissions -rw-r--r--
emscripten: support KaiOS's Left Soft Key and Right Soft Key (thanks, pelya!).

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