Skip to content

Home

Jump to bottom
Ingvar Stepanyan edited this page Jun 26, 2022 · 70 revisions
Clone this wiki locally

A cross-platform user-mode library, for generic access to USB devices

Table of Contents

Description

About

libusb is a cross-platform user-mode library that provides access to USB devices. The project website is at libusb.info. The old project site libusb.org should not be used.

The current API is of 1.0 version (libusb-1.0 API). You can still use the legacy API (libusb-0.1 API) with the libusb-compat-0.1 wrapper.

Take note libusb-win32 is a separate project and it is in bug-fix-only mode. New project should migrate to use libusb Windows backend.

Features

  • Supports all the major platforms: Linux, OS X, Windows, OpenBSD/NetBSD, Solaris and Haiku
  • Supports all versions of USB, from 1.0 to 3.1
  • Unified modern API, that provides both synchronous and asynchronous access
  • User-mode: no need for kernel access

Downloads

libusb releases can be accessed from the releases directory.

Documentation

  • The libusb-1.0 API Reference can be accessed HERE
  • A FAQ is also available.

Support

The preferred way to get support is to use the mailing list. The libusb mailing-list is hosted on Sourceforge. You can subscribe and check the archive HERE.

For your convenience, marc.info may provide a more user-friendly version of the mailing list archives.

For historical reasons, the libusbx mailing list archive can be found here.

You are also encouraged to check the Wiki Pages for topics of interest.

Development

Supported Environments

  • Linux [status: Stable]
    • Any modern Linux system with usbfs.
  • Mac OS X [status: Stable]
    • Any modern version of Mac OS X (PowerPC or x86 either in 32 and 64 bits or Apple Silicon)
    • Note: for USB 3.0 port,please use Mac OS X Mountain Lion 10.8.2 or later.
    • Note: the device should not be bound to a kernel driver. You can use a codeless kext to achieve that if there is a kernel driver (eg: HID or USB Mass Storage) which already binds to the device.
  • Windows [status: Stable]
    • MinGW-w64 32bit/64bit GCC under Windows. MSYS2 is a good MinGW-w64 distribution for Windows. To compile a library that is both 32 and 64 bit compatible, you should use a version of MinGW-w64 that supports both -m32 and -m64 (a.k.a. "multilib"). A pre-built multilib version can be downloaded with TDM64.
    • Microsoft Visual C++ (Visual Studio).
    • Windows DDK build environment (dropped in 1.0.24)
    • Device driver support: WinUSB, HID, libusb-win32 (libusb0.sys, not recommended), libusbK, usbdk.
  • OpenBSD and NetBSD [status: EXPERIMENTAL]
    • Only device with ugen driver are supported
  • Android -- [status: EXPERIMENTAL]
  • Solaris support was added in libusb-1.0.21
  • Haiku support was added in libusb-1.0.20
  • WebAssembly + WebUSB support [status: EXPERIMENTAL]
    • Note: WebAssembly support requires custom toolchain (Emscripten) and linker flags to be used for building your application and has some limitations compared to other platforms. For more details, see the accompanying blog post.
More information on the Windows implementation can be obtained from the Windows Backend page.

Note: FreeBSD 8 and above include a FreeBSD-specific reimplementation of the libusb API, so your applications will probably work there too. The source code for this library can be found here.

IBM has a partial port of libusb for AIX as well. Please refer to the IBM website here.

If you are interested in porting to other platforms, the PORTING file tells you where to start. We are more than happy to help out here, please write to the mailing list with your questions and feedback.

Accessing the Source

The latest development tree is always available from git.

For those not familiar with git, here are the commands one can use to retrieve libusb: 

# retrieve development branch (this only needs to be done once)
git clone git://github.com/libusb/libusb.git
cd libusb

# for further updates, once the clone has been done
git pull

You can also browse the git development tree from https://github.com/libusb/libusb.

When compiling from git, remember that you may have to run ./autogen.sh, ./bootstrap.sh or run the autotools creation utilities, in order to have configure and Makefile created for you. The difference between autogen.sh and bootstrap.sh is that the former will invoke configure with a set of default options, whereas the latter will not.

To create projects relying on libusb, please refer to the samples in the examples/ subdirectory.

Contributing

Please submit a pull request (PR) at https://github.com/libusb/libusb/pulls. If you don't have any ready code yet, but want to suggest a new feature, you can file an issue at https://github.com/libusb/libusb/issues.

Once all feedback has been addressed and it is a change we want to include, we'll add your commit to libusb. Note that the pull request status will show up as “Closed” instead of “Merged” because of the way we merge contributions. Don't worry: you will still get author credit in the actual merged commit.

Open Source projects using libusb

  • OpenOCD and other libFTDI based projects
  • UrJTAG - Universal JTAG Library
  • CUPS - An Open Source printing system
  • SANE - Scanner Access Now Easy
  • usbutils - USB utilities for Linux
  • sigrok - A signal analysis software suite for a very large range of devices
  • airspy host AirSpy's usemode driver and associated tools
  • OpenKinect - Library and appplications for the Microsoft Xbox Kinect device
  • OpenNI - An Open Source SDK for 3D sensing
  • BTstack - A Portable User-Space Bluetooth Stack
  • UsbPicProg - An Open Source PIC programmer
  • fprint - A fingerprint scanning application and library
  • IIDC Camera Control Library libdc1394 - Capture and control API for IIDC compliant cameras
  • Microdia - A Microdial webcam capture application
  • usbmuxd - A socket daemon to multiplex connections from and to iOS devices
  • coldsync - Palm OS synchronization utility
  • SUB-20 - Software for the Dimax SUB-20 Multi Interface USB Adapter
  • libnifalcon - A driver for the Novint Falcon Haptic Device
  • XPIOCARDS - A flight simulator interface
  • Exodriver - Open Source drivers for Labjack data acquisition devices
  • madWiMAX - A Linux driver for mobile WiMAX devices
  • Yubikey Personalization - Library and command line tool used to personalize YubiKeys.
  • USRP Hardware Driver (UHD) - A cross-platform driver for USRP Software Defined Radios
  • libuvc - Library for webcams and other USB Video Class devices
  • dfu-util - Device Firmware Upgrade Utilities
  • Dolphin Emulator - Emulator for Nintendo video game consoles: GameCube and Wii
  • libIIO - a library that provides generic access to Linux IIO devices.
  • And many more!...

Language Bindings

Other Resources