README.txt (12193B)
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/libusb/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