wiki:APIs
Last modified 9 months ago Last modified on 01/05/14 19:10:06

API version overview

There are two libusb API versions:

  • libusb-1.0 is the current API version under active development
    • libusb-1.0 API symbols begin with libusb_ or LIBUSB_.
  • libusb-0.1 is the original version which is deprecated and unmaintained since many years
    • libusb-0.1 API symbols begin with usb_ or USB_.

API implementation overview

There are many different implementations of the two libusb APIs, each developed by a different community. This is unfortunately a frequent cause of confusion for libusb users.

There are three libusb-1.0 API implementations:

  • libusb is the implementation developed here on libusb.org by successors of the original libusb authors.
  • libusbx describes itself as a hostile fork of libusb and uses the same SONAMEs and filenames as libusb. Many Linux distributions currently ship libusbx. It was created by developers who disagree with libusb's high quality standards and the resulting moderate development pace. libusbx development takes place outside of libusb.org.
  • FreeBSD ships their own implementation of the libusb-1.0 API as part of their system libraries.

There are several libusb-0.1 API implementations:

  • libusb-0.1 is the very first libusb implementation.
  • libusb-compat-0.1 is a compatibility library which provides the libusb-0.1 API by using the libusb-1.0 API.
  • libusb-win32 is a Windows-only implementation of the libusb-0.1 API. The libusb-win32 project has also created the open source libusb0.sys Windows kernel driver, which exposes a userspace API that allows USB devices to be accessed outside of the Windows kernel.
  • FreeBSD ships their own implementation of the libusb-0.1 API as part of their system libraries.

Because the 0.1 and 1.0 APIs use different prefixes they are compatible with each other. It is common that both are installed in parallel on a system. We strongly recommend using libusb-1.0 together with libusb-compat-0.1 instead of the ancient libusb-0.1 code, so that programs which use both the 0.1 API and the 1.0 API in different parts of the program, or in different libraries used by the program, will all use libusb-1.0 for the actual device access. This is important to avoid potential conflicts between libusb-1.0 and libusb-0.1 being used in the same process.

libusb-1.0 (current API and implementation)

Daniel Drake adopted the project in January 2008 and worked on the libusb-1.0 API and implementation, which adds several features missing from the 0.1 API. libusb-1.0 is recommended for all new development. Developers are encouraged to port existing applications which use libusb-0.1 to use the new API.

  • Download sources
  • See the libusb-1.0 page for more detailed information about libusb-1.0
  • libusb-1.0 API documentation
  • Linux, Mac OS X, Windows, OpenBSD and NetBSD are currently supported.
  • FreeBSD includes a separate implementation of the libusb-0.1 and libusb-1.0 APIs in the system libc.
  • The Windows backend currently uses the generic USB device driver WinUSB.sys by Microsoft, which is included with all Windows versions starting with Windows Vista. There is a ticket about supporting the libusb0.sys kernel driver created by the libusb-win32 project.

A kernel driver which supports using libusb in userspace is always required, on every operating system. Each operating system has different rules for device drivers. On Mac OS X, if an interface driver included with the OS matches the characteristics of a USB device's interface then that driver seizes the interface and the driver cannot be detached by libusb, so libusb can not access that interface. In the case of OpenBSD and NetBSD libusb-1.0 can be used only for devices with the ugen driver. For Windows currently only the WinUSB driver is supported.

libusb is not suited for HID class devices. While it is possible to use libusb with HID class devices it requires the original HID class driver to be replaced by a driver which supports libusb, and this leads to a quite poor user experience on any platform other than Linux. It is recommended to use HIDAPI instead. HIDAPI provides convenient cross-platform access to HID class devices and can do so without any kernel driver concerns across all supported platforms.

libusb-0.1 (legacy API)

Johannes Erdfelt founded the libusb project and lead development through 2007. By then, libusb-0.1 had stabilized, and was adopted by a wide range of projects.

  • Download sources
  • Supported operating systems: Linux, FreeBSD, NetBSD, OpenBSD, Darwin, MacOS X (and Windows, through the libusb-win32 project). Solaris has a wrapper for libusb-0.1 as well. There are also independent implementation efforts for other OS like BeOS and OS/2 which may not be mature enough.
  • Development status: libusb-0.1 is deprecated and will have no further changes or releases
  • Note that libusb-win32 is a separate project which still sees active development. The next generation libusb-win32 kernel driver (libusbk.sys) is based on KMDF. The libusbk library will support the existing libusb-win32 API, libusb-1.0 API and WinUSB-like API. libusb-win32 users who are fine with the libusb-win32 API are recommended to keep using it since it will be supported by the libusb-win32 project. libusb-win32 users who are interested in libusb-1.0 will also be supported once the libusbk backend is integrated. Future enhancement of the libusb-1.0 API (say libusb-1.1) may be required to be more suitable for Windows users.
  • Download libusb-0.1 releases here
  • libusb-0.1 API documentation
  • Unofficial bindings at the libusb-win32 site
  • Projects and Examples using libusb-win32