diff --git a/README.txt b/README.txt index 4dc0e1a..b971d78 100644 --- a/README.txt +++ b/README.txt @@ -1,13 +1,14 @@ -HID API for Windows, Linux, FreeBSD and Mac OS X + 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. On Windows, a DLL is built. On other platforms (and optionally on -Windows), the single source file can simply be dropped into a target -application. +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) @@ -32,15 +33,18 @@ 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 modified version the USB Generic HID -sample which is part of the Microchip 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): +which communicates with a heavily hacked up version of the Microchip USB +Generic HID sample looks like this (with error checking removed for +simplicity): #include #include @@ -97,51 +101,174 @@ int main(int argc, char* argv[]) 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 ---------- -It can be downloaded from github +========= +HIDAPI can be downloaded from github git clone git://github.com/signal11/hidapi.git Build Instructions -------------------- -To build the console test program: - Windows: - Build the .sln file in the windows/ directory. - Linux: - For the hidraw implementation, cd to the linux/ directory and run make. - For the libusb implementation, cd to the libusb/ directory and run make. - FreeBSD: - cd to the libusb/ directory and run gmake. - Mac OS X: - cd to the mac/ directory and run make. +=================== -To build the Test GUI: - The test GUI uses Fox toolkit, available from www.fox-toolkit.org. - On Debian-based systems such as Ubuntu, install Fox using the following: - sudo apt-get install libfox-1.6-dev - On FreeBSD, install iconv and Fox as root: - pkg_add -r gmake libiconv fox16 - On Mac OSX, install Fox from ports: - sudo port install fox - On Windows, download the hidapi-externals.zip file from the main download - site and extract it just outside of hidapi, so that hidapi-externals and - hidapi are on the same level, as shown: +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. - Parent_Folder - | - +hidapi - +hidapi-externals +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.PLATFORM where PLATFORM is +the name of the platform (eg: Makefile.linux or Makefile.mac). +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. - Then to build: - On Windows, build the .sln file in the testgui/ directory. - On Linux and Mac, run make from the testgui/ directory. - On FreeBSD, run gmake from the testgui/ directory. -To build using the DDK (old method): +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 + + 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 arguments which control the build. The two most +likely to be used are: + --enable-testgui + Enable build of the Test GUI. This requires Fox toolkit to + be installed. Instructions for installing Fox-Toolkit on + each platform are in the Prerequisites section above. + + --prefix=/usr + Specify where you want the output headers and libraries to + be installed. The example above will put the headers in + /usr/include and the binaries in /usr/lib. The default is to + install into /usr/local which is fine on most systems. + +Building the manual way on Unix platforms: +------------------------------------------- + +Manual Makefiles are provided mostly to give the user and idea what it takes +to build a program which embeds HIDAPI directly inside of it. These should +really be used as examples only. If you want to build a system-wide shared +library, use the Autotools method described above. + + To build HIDAPI using the manual makefiles, change to the directory + of your platform and run make: + cd linux/ make -F Makefile-manual + + To build the Test GUI using the manual makefiles: + cd testgui/ + make -F Makefile-manual + + +Building on Windows: +--------------------- + +To build the HIDAPI DLL on Windows using Visual Studio, build the .sln file +in the windows/ directory. + +To build the Test GUI on windows using Visual Studio, build the .sln file in +the testgui/ directory. + +To build HIDAPI using MinGW or Cygwin using Autotools, use the instructions +in the section titled "Building HIDAPI into a shared library on Unix +Platforms" above. Note that building the Test GUI with MinGW or Cygwin will +require the Windows procedure in the Prerequisites section above (ie: +hidapi-externals.zip). + +To build HIDAPI using MinGW using the Manual Makefiles, see the section +"Building the manual way on Unix platforms" above. + +HIDAPI can also be built using the Windows DDK (now also called the Windows +Driver Kit or WDK). This method was originally required for the HIDAPI build +but not anymore. However, some users still prefer this method. It is not as +well supported anymore but should still work. Patches are welcome if it does +not. To build using the DDK: 1. Install the Windows Driver Kit (WDK) from Microsoft. 2. From the Start menu, in the Windows Driver Kits folder, select Build @@ -154,9 +281,9 @@ To build using the DDK (old method): by the build system which is appropriate for your environment. On Windows XP, this directory is objfre_wxp_x86/i386. --------------------------------- Signal 11 Software - 2010-04-11 2010-07-28 2011-09-10 2012-05-01 + 2012-07-03