libhid

a user-space USB HID access library written in C

Introduction

libhid provides a generic and flexible way to access and interact with USB HID devices, much like libusb does for plain USB devices. It is based on libusb 0.1, thus it requires no special HID support in the kernel. Furthermore, it aims to support all operating system supported by libusb: Linux, BSD, OS X, and Windows (via libusb-win32).

libhid should be easy to use if you have some knowledge of C, and are willing to read someone else's code. Some API documentation has been generated using Doxygen, but it is far from complete (if you want to help, please contact us!).

For a simple example on how to use libhid, please check out test_libhid.c.

For more information, please consult the README.

Mailing lists

Development of libhid is currently coordinated with mailing lists and Subversion (see further down). The following three mailing lists exist (click on the list name to go to the list information page):

We realise that the documentation and instructions we provide with the library are far from usable. Thus, please do not hesitate to write to us on the discussion list!

Getting libhid

libhid is available through various ways. In the following, we list the possibilities in decreasing order of preference/currency:

Subversion (svn)

The Subversion tree is the most current development repository. The CVS version history has been imported into in the Subversion repository as well.

Update (2006-06-29): The SVN repository has moved again. We are now back at Alioth. (Many thanks to Martin Krafft for hosting libhid for these past two years.) If you have a checked out copy, please relocate it. If you have read-only access, use the first command. With write access, use the second:

svn sw --relocate svn://svn.{ailab.ch,debian.org}/svn/libhid/trunk
svn sw --relocate svn+ssh://svn.{ailab.ch/home/svn/external,debian.org/svn}/libhid/trunk

To check out the latest version of libhid into the directory libhid-svn, ensure that Subversion is installed, and use the following command:

svn co svn://svn.debian.org/libhid/trunk libhid-svn

Instructions on how to compile the code are available in the README file. Please do not hesitate to write to the mailing list if you have questions, comments, or problems.

The Subversion tree can also be viewed online via websvn. The latest version is available at the trunk.

If you want to contribute, please send a patch or two to the libhid-discuss mailing list (please keep patches under 20KB, or gzip them before attaching them). After a few patches have been accepted, it would not be unreasonable for you to ask for SVN write access. For that, you would need an account on Alioth. You can sign up for free (and need not be affiliated with Debian).

Debian

libhid is in Debian, and was included in sarge (3.1). To install:

# apt-get install libhid-dev python-hid

Tarball

You may download a tarball of libhid from Alioth at the download page for libhid by selecting the link for the latest libhid-*.tar.gz file. Unpack it, then run:

$ ./configure && make
$ su
# make install

to install it into /usr/local.

A note about languages

At time of writing, libhid can be used directly from C/C++, or from Python. It is possible for us to provide further language bindings, thanks to Swig. Thus, if you need to use HID devices from any other of the languages supported by Swig, it should be trivial to add support. Just echo your desires to the discussion list, but bear in mind that the libhid developers cannot guarantee support for any given language.

For a simple example on how to use libhid from Python, please check out this script.

Licence

libhid is released under the terms of the GPL version 2.

We realise that this is a serious impediment. The GPL is a "viral" licence, and you will only be able to use libhid in other GPL projects. We would like to change the licence, but libhid uses the MGE UPS SYSTEMS HID Parser, which is GPL, and thus we cannot. Our solution is to rewrite the HID parser. One of these days. We are also in contact with MGE, trying to convince them to loosen their licence. If the licencing issues are solved, we are likely to re-release libhid under the Artistic Licence.

About

libhid grew out of libHID and is being developed by

It is used in a rewrite of the Network UPS Tools USB driver (newhidups/usbhid-ups) and as a basis for libphidgets.

Links

Valid XHTML 1.1!

$Id: index.html 362 2008-04-27 18:00:10Z clepple-guest $