From fdae95dcd785cc138dcc7564d2ac737405fa6cf3 Mon Sep 17 00:00:00 2001 From: Luca Weiss Date: Sun, 9 Jun 2019 11:53:20 +0200 Subject: [PATCH] README: convert to markdown --- README.txt => README.md | 239 +++++++++++++++++++++------------------- 1 file changed, 125 insertions(+), 114 deletions(-) rename README.txt => README.md (67%) diff --git a/README.txt b/README.md similarity index 67% rename from README.txt rename to README.md index c5e790d..566444b 100644 --- a/README.txt +++ b/README.md @@ -1,8 +1,6 @@ - HIDAPI library for Windows, Linux, FreeBSD and Mac OS X - ========================================================= +# HIDAPI library for Windows, Linux, FreeBSD and Mac OS X -About -====== +## 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 @@ -11,11 +9,11 @@ can be embedded directly into a target application by adding a single source file (per platform) and a single header. HIDAPI has five 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) +* 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. @@ -38,14 +36,14 @@ 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? -============================= +## 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): +```c #ifdef WIN32 #include #endif @@ -108,6 +106,7 @@ 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, @@ -115,17 +114,16 @@ 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 -======== +## License HIDAPI may be used by one of three licenses as outlined in LICENSE.txt. -Download -========= +## Download HIDAPI can be downloaded from github - git clone git://github.com/signal11/hidapi.git +```sh +git clone git://github.com/signal11/hidapi.git +``` -Build Instructions -=================== +## 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 @@ -142,88 +140,97 @@ 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: ---------------- +### 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 +#### 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: +```sh +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 +If you downloaded the source directly from the git repository (using +git clone), you'll need Autotools: +```sh +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 +#### 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: +```sh +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 +If you downloaded the source directly from the git repository (using +git clone), you'll need Autotools: +```sh +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. +#### 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 Test GUI just for your own testing on your +own computer, then the easiest method is to install Fox-Toolkit +using ports: +```sh +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 +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: +```sh +./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. +#### 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: ---------------------------------------------------------- +### 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 +```sh +./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. +can skip the `./bootstrap` step. ./configure can take several arguments which control the build. The two most likely to be used are: +```sh --enable-testgui Enable build of the Test GUI. This requires Fox toolkit to be installed. Instructions for installing Fox-Toolkit on @@ -234,26 +241,28 @@ likely to be used are: 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: -------------------------------------------- +``` +### 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. For example, on Linux run: - cd linux/ - make -f Makefile-manual +To build HIDAPI using the manual makefiles, change to the directory +of your platform and run make. For example, on Linux run: +```sh +cd linux/ +make -f Makefile-manual +``` - To build the Test GUI using the manual makefiles: - cd testgui/ - make -f Makefile-manual +To build the Test GUI using the manual makefiles: +```sh +cd testgui/ +make -f Makefile-manual +``` -Building on Windows: ---------------------- +### Building on Windows: To build the HIDAPI DLL on Windows using Visual Studio, build the .sln file in the windows/ directory. @@ -287,8 +296,7 @@ not. To build using the DDK: by the build system which is appropriate for your environment. On Windows XP, this directory is objfre_wxp_x86/i386. -Cross Compiling -================ +## Cross Compiling This section talks about cross compiling HIDAPI for Linux using autotools. This is useful for using HIDAPI on embedded Linux targets. These @@ -299,38 +307,41 @@ OpenEmbedded or Buildroot. For the purpose of this section, it will be assumed that the following environment variables are exported. +```sh +$ export STAGING=$HOME/out +$ export HOST=arm-linux +``` - $ export STAGING=$HOME/out - $ export HOST=arm-linux +`STAGING` and `HOST` can be modified to suit your setup. -STAGING and HOST can be modified to suit your setup. - -Prerequisites --------------- +### Prerequisites Note that the build of libudev is the very basic configuration. Build Libusb. From the libusb source directory, run: - ./configure --host=$HOST --prefix=$STAGING - make - make install +```sh +./configure --host=$HOST --prefix=$STAGING +make +make install +``` Build libudev. From the libudev source directory, run: - ./configure --disable-gudev --disable-introspection --disable-hwdb \ - --host=$HOST --prefix=$STAGING - make - make install +```sh +./configure --disable-gudev --disable-introspection --disable-hwdb \ + --host=$HOST --prefix=$STAGING +make +make install +``` -Building HIDAPI ----------------- +### Building HIDAPI Build HIDAPI: - - PKG_CONFIG_DIR= \ - PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \ - PKG_CONFIG_SYSROOT_DIR=$STAGING \ - ./configure --host=$HOST --prefix=$STAGING - +``` +PKG_CONFIG_DIR= \ +PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \ +PKG_CONFIG_SYSROOT_DIR=$STAGING \ +./configure --host=$HOST --prefix=$STAGING +``` Signal 11 Software - 2010-04-11 2010-07-28