RPCS3/hidapi
1
0
Fork 0
mirror of https://github.com/RPCS3/hidapi.git synced 2026-07-19 13:34:37 -04:00
Code Issues Packages Projects Releases Wiki Activity

README: convert to markdown

Browse Source
This commit is contained in:
Luca Weiss
2019-06-09 11:53:20 +02:00
committed by Ihor Dutchak
parent 121567d64a
commit fdae95dcd7
1 changed files with 125 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.txt → README.md
+125 -114
View File
@@ -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 <windows.h>
#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