/** @file frontpage.dox * @brief libhid HTML front page */ /** @mainpage libhid - a portable HID API @section sec_intro Introduction

For a more up-to-date version of this page, please consult http://libhid.alioth.debian.org.

libhid is a user-space HID access library written in C. It 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, thus it requires no HID support in the kernel. Furthermore, it aims to support all operating system supported by libusb: Linux, BSD, OS X, and Windows.

libhid is still under development and it does not have a proper homepage (if you want to write one, please contact us!). Until one is ready, you are welcome to download the software and try it out, it should be easy to use if you have some knowledge of C and are willing to read someone else 's code. Documentation does not yet exist, but we are working to provide it using Doxygen (again, if you want to help, please contact us!).

For more information, please consult the README.

@section sec_lists Mailing lists

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

libhid-announce [ archives ] -- a moderated list with very low volume for announcements. Everyone should subscribe here.
libhid-discuss [ archives ] -- a subscriber-only list for general discussion. Everyone is cordially invited to join and participate.
libhid-cvs [ archives ] -- a mailing list receiving CVS commit mails. This list is being superceded by libhid-commits (below).
libhid-commits [ archived via websvn ] -- a mailing list receiving Subversion (svn) commit mails. If you want to closely track libhid development, you probably want to subscribe to this list.

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!

@section sec_getting Getting libhid

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

@subsection ssec_svn Subversion (SVN)

The Subversion tree will be the preferred development repository from here forward. The CVS version history is available in the Subversion repository as well.

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.ailab.ch/libhid/trunk libhid-svn

To retrieve a particular released (or otherwise tagged) version of libhid, simply modify the checkout URL. You may have to browse with viewcvs to find the exact tag name. As an example, let's retrieve version 0.2.8-1:



svn co svn://svn.ailab.ch/libhid/tags/0.2.8-1 libhid-0.2.8-1

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 viewcvs. The latest version is available at the trunk.

If you want to contribute, please send a patch or two. We cannot give out write access to the Subversion tree just like that, but if you show us a patch, we'll conclude that you are serious about developing libhid, and give you permission.

@subsection ssec_debian Debian

libhid has entered Debian, but the versions may be a little behind. You can use my (madduck) repository to always get the latest versions. Simply add the following to your /etc/apt/sources.list file:


deb     http://debian.madduck.net ~madduck/packages/stage/libhid/


deb-src http://debian.madduck.net ~madduck/packages/stage/libhid/

and then install it. You may leave out python-hid if you do not want the Python bindings:


# apt-get install libhid-dev python-hid

@subsection ssec_tarball Tarball

Of course, libhid is available as a tarball from the Debian repository. Simply find the latest file with the extension .orig.tar.gz, download it, unpack it, and then do the standard


$ ./configure && make


$ su


# make install

to install it into /usr/local.

@section sec_lang 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, we will make it available. Just echo your desires to the discussion list.

@section sec_licence Licence

libhid is released under the GPL.

@section sec_abount About

libhid grew out of libHID and is actively being developed by

Martin F. Krafft <libhid@pobox.madduck.net>
Arnaud Quette <arnaud.quette@mgeups.com>
Charles Lepple <clepple@ghz.cc>

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

@section sec_links Links

libHID -- the previous version of a HID access library. libhid officially subsumes this project.
libphidgets -- a library to access Phidget devices. It uses libhid to communicate with the devices.
Network UPS Tools -- a toolkit for reliable monitoring of UPS hardware and ensure safe shutdowns of the systems which are connected. It was the reason why libHID started, and is currently being ported from libHID to libhid.
Swig -- a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. libhid uses it to provide the Python bindings (and other languages on request).
MGE UPS SYSTEMS HID Parser -- a library to enumerate and parse the HID namespace. libhid uses it to find the device to talk to.
MGE UPS SYSTEMS -- the company behind the HID parser. They also employ one of the libhid developers (Arnaud) and fund his development on libhid. In addition, MGE UPS SYSTEMS have made UPS devices available to Charles and Martin, for testing, and to express their gratitude.

$Id: frontpage.dox 269 2005-11-11 03:16:51Z clepple $

*/ /* COPYRIGHT: This file is part of libhid, a user-space HID access library. libhid is (c) 2003-2005 Martin F. Krafft Charles Lepple Arnaud Quette && and distributed under the terms of the GNU General Public License. See the ./COPYING file in the source tree root for more information. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. */