FAQ
libusb.org was the original home for libusb project. Now the website is offline.
libusb.info is the current home page for libusb project.
libusbx was a fork of libusb and libusbx.org is its website. As of 2014.01.26, libusbx project has been fully merged back into libusb and is being discontinued. libusbx.org is no longer related to libusb project.
libusb project now concentrates on developing the libusb-1.0 API. To be compatible with the legacy libusb-0.1 API, libusb-compat-0.1 was created to provide the compatible layer.
Take note libusb-win32 and libusbK projects are separate projects and both of them use libusb-win32 mailing list for technical support. Unlike libusb which is a cross-platform project, libusb-win32 and libusbK project are both Windows only project.
libusb-win32 project includes libusb0.sys (Windows WDM kernel driver in device driver mode or filter driver mode) and libusb0.dll (libusb-win32 API, library). libusb-win32 API is a superset of the libusb-0.1 API supported by libusb-compat. libusb0.dll supports device using libusb0.sys and libusbK.sys.
libusbK projects includes libusbK.sys (Windows KMDF kernel driver) and libusbK.dll (libusbK API, library). libusbK API is Windows only and libusbK.dll supports device using libusbK.sys, libusb0.sys and WinUSB.
openusb is a project similar to libusb (started as a fork of the libusb-1.0 API) but it is mostly dead other than on Solaris.
libusb Windows backend can support device using libusbK.sys through libusbK.dll provided by libusbK project. If libusbK.dll is present, it will use libusbK.dll as the intermediate library to support device using WinUSB driver, and not directly using WinUSB API. If libusbK.dll is not present, then it will directly talk to device using WinUSB driver (winusb.sys) through WinUSB API (winusb.dll).
libusb Windows also supports device using generic HID driver or usbdk driver.
In summary, there is no Windows kernel driver involved in the libusb project. It is purely a user space library. It supports multiple kernel drivers.
1) WinUSB.sys kernel driver from Microsoft, through WinUSB.dll from Microsoft
- libusb-1.0.dll --> WinUSB.dll --> WinUSB.sys (if libusbK.dll is not present, or after commit https://github.com/libusb/libusb/commit/9c28ad219b654011783a42ec888ca87dbda704a even if libusbK.dll is present)
- libusb-1.0.dll --> libusbK.dll --> WinUSB.dll --> WinUSB.sys (before https://github.com/libusb/libusb/commit/9c28ad219b654011783a42ec888ca87dbda704a6, no longer true after the commit)
- libusb-1.0.dll --> libusbK.dll --> libusbK.sys
- libusb-1.0.dll --> libusbK.dll --> libusb0.sys
Warning: use of the HID backend is highly discouraged. libusb project recommends the user to switch to hidapi.
5) usbdk driver from usbdk project
In terms of support, WinUSB is first class supported driver for libusb project, followed by libusbK.sys, then libusb0.sys. usbdk/HID/libusb0.sys are also supported but they may have more issues compared to the other three.
usbdk is another open-source generic USB driver. usbdk is a new backend added in libusb-1.0.21 release. The major benefit is that you can keep the existing driver. It supports isochronous transfer as well. The support is less mature than the WinUSB/libusbK.sys/libusb0.sys. usbdk is known to have some staibilty issues. Therfore the use of usbdk is discouraged.
libusb is released under version 2.1 of the GNU Lesser General Public License (LGPL).
You can, as long as you don't modify its source code.
If you modify the source, then you must make any changes you applied to libusb public, and grant others the right to use these changes in their own applications, under the LGPL v2.1 license terms.
Please read the libusb Troubleshooting page and use the mailing list for support.
Please also read the Wiki pages including this FAQ page as well as libusb caveats.
You have to subscribe to the mailing list in order to post.
You can help in many ways.
- You can help testing the git head or RC release using the test matrix (eg: https://github.com/libusb/libusb/issues/1099)
- You can help testing using the downstream projects like libusb language bindings or projects using libusb
- You can help testing the pull requests.
- You can help contributing tests and examples to libusb projects.
Yes, you can use many devices to test libusb (ref: https://github.com/libusb/libusb/issues/1052).
- Highly recommended -- Cypress FX3 SuperSpeed Explorer Kit or other FX3 based boards https://www.cypress.com/documentation/development-kitsboards/cyusb3kit-003-ez-usb-fx3-superspeed-explorer-kit
- Cypress FX2LP
- Arm Cortex M MCU based development board like ST STM32 (eg: Bluepill and Blackpill, Discovery or Nucleo boards), Microchip SAM MCU, Raspberry Pi Pico, etc
- Other USB MCU like Microhip PIC or AVR, TI MSP 430, etc
- Linux USB Gadget devices (eg: using Raspberry Pi Zero or Raspberry Pi 4B/400)
- libusb-1.0.26 has the umockdev based testing under Linux
- tinyusb - https://github.com/hathach/tinyusb
- cherryusb - https://github.com/sakumisu/CherryUSB
- lufa - https://github.com/abcminiuser/lufa
- m-stack for PIC16/18/24/32 - https://github.com/signal11/m-stack.git
- libopencm3 for ARM Cortex-M3 - http://libopencm3.org/
- libusb_stm32 - https://github.com/dmitrystu/libusb_stm32.git
- PIC16/18 USB stack - https://github.com/johnnydrazzi/USB-Stack
- fx2lib for EZUSB FX2LP - https://github.com/djmuhlestein/fx2lib
Yes you can. Please detach the kernel driver by calling libusb_detach_kernel_driver() so that you can use libusb. Please take note you need to have the correct privilege to do that. Take note this function is only available for Linux. Better way is to use udev rules to unbind the kernel driver.
Can I run libusb application on Linux when there is already another application which has already claimed the interface?
You have to exit the other application. If not and libusb_set_configuration() and libusb_claim_interface() will fail. Take note if the other application is the kernel driver, you have to detach the kernel driver.
Yes.
The standard solution is to use udev rules. Here are some links to udev related websites.
- udev homepage
- Debian's udev overview
- Writing udev rules
- Proper place to ask questions about udev rules
How can I run libusb applications under Mac OS X if there is already a kernel extension installed for the device and claim exclusive access?
If there is no existing kernel extension installed for the device, libusb will run out of the box, you do not even need to have root privilege and there is no need to set up udev rules like Linux. However, if there is an existing kernel extension installed for the device, then it is more troublesome. There are ways to get libusb working and they all require some interventions as root.
1) You can use kextunload to unload the kernel extension. You need to run the command as root. Take note this may not be possible for drivers like USB HID since it may be used by other USB HID device. Take note that the kextunload command will lose its effect in the next boot.
sudo kextunload -b com.apple.driver.AppleUSBFTDI
The above command will unload the Apple provided FTDI driver (Mac OS X Mavericks or later).
sudo kextunload FTDIUSBSerialDriver.kext
The above command will unload the FTDI provided VCP driver.
2) You can use a codeless kext to prevent the kernel driver from attaching to the device. Take note that OS X Mavericks and later require that the kext be signed using a special Developer ID.
Please read the following two Apple technical notes for more details about writing a codeless kext.
- Technical Note TN2315: Introducing the Apple AppleUSBFTDI kernel driver
- Technical Q&A QA1076: Tips on USB driver matching for Mac OS X
For example, in the case of Apple provided FTDI driver, you can edit the following file to comment out the key/dict sections of the desired VID/PID combination.
/System/Library/Extensions/IOUSBFamily.kext/Contents/PlugIns/AppleUSBFTDI.kext/Contents/Info.plist
Once you finish the editing, you can issue the following two commands and everything should work after that.
sudo kextunload -bundle com.apple.driver.AppleUSBFTDI
sudo kextload -bundle com.apple.driver.AppleUSBFTDI
Reference:
- http://alvarop.com/2014/01/using-busblaster-openocd-on-osx-mavericks/ (Dead link now).
- https://embeddedartistry.com/blog/2017/06/26/osx-getting-pesky-ftdi-debugging-devices-to-work/
For macOS Catalina(10.15) and later, Apple FTDI driver is now a Driverkit extension named com.apple.DriverKit-AppleUSBFTDI. (Note: it seems to work with libusb out of the box under Mac Mini M1 Big Sur even though the driver and the serial port are present).
Updates in Feb 2022: with the merging of pull request #911, support for detaching kernel drivers with authorization has been added. This has been included in the upcoming 1.0.25 release. Take note the underlying macOS capture APIs only work on the whole device and not on individual interfaces. So this will force all the kernel extensions (drivers) bound to all the interfaces of a USB Composite devices to be released (Issue #920). You will need to get the entitlement from Apple Developer support, create a provisioning profile with that entitlement, and build your app with that profile.
Please take note that command line apps cannot use provisioning profiles and therefore cannot hold this entitlement so you have to run as root. As for the GUI application, as of now APple support is saying that `com.apple.vm.device-access` entitlement is not the right entitlement. So basically there is no solution as of now. This means libusb (and libraries like libuvc which uses libusb) may not be the right library to use if you hit this issue (Issue #972 and Issue #1014).
Specifically for UVC device, there is a way to override the default USB video class extension by creating a simple DriverKit extension to override the default driver-matching behavior for USB devices. https://developer.apple.com/documentation/coremediaio/overriding_the_default_usb_video_class_extension?language=objc
Please refer to the following Wiki page:
https://github.com/libusb/libusb/wiki/Windows#How_to_use_libusb_on_Windows
Basically you will need to install a supported driver.
- If your device is a generic HID device, no extra driver is needed since it is supported. But HIDAPI is recommended for HID device rather than libusb on Windows.
- If your device uses WinUSB driver, no extra driver is needed since it is supported natively.
- If your device uses libusbK driver, you should be set as well (libusbK.dll should have been installed).
- If your device uses libusb-win32 (libusb0.sys) device driver, please try it to see if it works well. If not, try to switch to libusbK driver.
- If your device uses libusb-win32 filter driver, please switch to device driver mode.
No.
libusb only provides an API for writing software on the host. Of course, if the device also acts as a USB host then libusb could still be useful, but only for the host part of the device.
Yes.
libusb can be used for low-level communication with USB Mass Storage Class devices. But in order to access a file on such a device you must first implement Mass Storage Class, SCSI and the particular file system used on the device, most commonly FAT32.
However, libusb will not do this part for you. In a word, do not use libusb for USB mass storage device.
But you can find a limited example of how to read a data block through Mass Storage using libusb in the mass_storage test from the xusb.c sample of the the libusb distribution.
Yes (as long as the underlying OS supports the corresponding USB version too).
If you encounter such an issue, you should report it to the libusb mailing-list.
But please take note of the OS support of USB 3.x/USB4.
For instance, USB 3.0 support for Windows 7 and earlier is very much dependent on individual drivers, which are provided by the USB controller manufacturer, and not Microsoft. Some of these have been known to have bugs. Only Windows 8/8.1/10 and later have an official USB 3.0 stack that originates from Microsoft.
For Linux, the xHCI driver may also not be as mature as the other host controller driver if you use older kernel versions. Please try to upgrade to later version of the kernel whenever possible to have better support.
For Mac OS X, xHCI support may not be so good in older versions like Mac OS X Mountain Lion. Whenever possible, please upgrade to later version of Mac OS X for better support.
Warning: use of the HID backend is highly discouraged. libusb project recommends the user to switch to hidapi.
If your application will revolve around HID access, you are strongly encouraged to try to use the HIDAPI library, which is also cross-platform. It uses native HID API under Windows and macOS. It use either hidraw or libusb as the backend under Linux.
libusb was widely used to access USB HID device under Linux for historical reasons so there may be use cases to use libusb for HID device due to existing code base or for platforms without HIDAPI support. However, the level of support as well as the ease of access of HID devices, depends on the platform you will be running libusb on.
On Linux, you must detach the kernel HID driver for libusb to communicate with the device, but the libusb API can do this for you. If you have a relevant udev rule, you should also be able to perform that operation without requiring root privileges. Still HIDAPI is recommended for new development.
On old version of macOS, you could install a codeless kext kernel driver extension (obsolete under newer version of macOS) and then reboot, before you will be able communicate with the device. This has become impossible with newer version of macOS (even with the newer DriverKit extensions as Apple will not allow it). So please do not use libusb with HID device under macOS as it will not work . HIDAPI should be the library of choices if you need Mac OS X support.
On Windows, the native Windows HID driver is supported by libusb, but there are quite some limitations, such as not being able to access HID mice and keyboards since they are system reserved, as well as getting a direct read of HID report descriptors.
Under NetBSD/OpenBSD, you may have to rebuild the kernel in order to use libusb with the HID device. Please refer to the apcupsd page.
In general, you may find HIDAPI a better library for HID device.
No.
Windows RT is locked by Microsoft, which means that users cannot install the applications or library of their choice. As such, libusb has no plans to support Windows RT.
No.
Yes.
One way to build libusb binary for both x86_64 in addition to arm64 is as following if you do not use homebrew.
1. Install Xcode Ver12.2 or later
2. Clone the newest libusb from git
3. Open the Xcode project from /libusb/Xcode/libusb.xcodeproj
4. Choose the build option to "Any Mac" which means both ARM64 and X86_64
5. Edit the Run Scheme to Release and then build the project.
6. Show the "libusb-1.0.0.dylib" in Finder then copy it to /usr/local/lib
7. Copy the "libusb.h" to /usr/local/include/libusb-1.0
If you use Homebrew, you can use x86_64 and arm64 homebrew at the same time using different directories . Please follow the official Homebrew instructions.
Not officially supported. If you encounter issues, please check if the issues are present in official Apple Macs or not.
Yes.
Please refer to the Windows CE related information in the following file.
https://github.com/libusb/libusb/blob/master/INSTALL_WIN.txt
Note: Windows CE support has been removed in 1.0.24.
Yes. However, this will only work if your device has USB host support (also known as USB On-The-Go) and if you have sufficient privileges to run in host mode (which usually requires a "rooted" device). Please check the android directory for more info.
Currently there are also multiple issues reported by the user. Please check the existing tickets as well to see if you can sort out the issues from the hints in the tickets. Version 1.0.24 has made quite some improvements on Android side and you should use version 1.0.24 or later.
An important tip of using the API libusb_wrap_sys_device under Android is mentionedhere. It is also mentioned in Issue #717.
Yes. However, VMs, especially VirtualBox, may have not very good implementation of the USB stack. If you encounter issues with libusb on VMs, run it under non-VMs first to see if that works or not. It it works under non-VMs but not under VMs, you may have to get help from the VM vendor or community.
What USB class should I choose for my USB device (I am developing the firmware) if I want to use it with libusb?
You should use custom class and the use Windows OS descriptor for USB devices so that Windows will automatically use WinUSB driver for your device.
Please refer to the following web sites for more info:
- https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/microsoft-defined-usb-descriptors
- https://github.com/pbatard/libwdi/wiki/WCID-Devices
Please do not use device class like USB HID, Mass Storage or Audio where the OS will have default driver bound to them.
Please read libusb-1.0 API documentation here. https://libusb.sourceforge.io/api-1.0/libusb_io.html
Please take note that ALL transfers MUST be freed before libusb_exit() is called.
Please take note that ALL libusb objects MUST be released before libusb_exit() is called.
Please also take note that there is no way to cancel Synchronous transfer after the request has been submitted.
What are the extra considerations to be applied to applications which interact with libusb from multiple threads?
Please read libusb-1.0 API documentation here. https://libusb.sourceforge.io/api-1.0/libusb_caveats.html (first section)
https://libusb.sourceforge.io/api-1.0/libusb_mtasync.html
For non-hotplug platforms (like Windows), it is recommended that all device discovery should be running in the same thread. If the device discovery runs in several threads, the application should make sure that only one is running at a time through some synchronization mechanism, because device discovery may not be thread-safe within a single context for these platforms. This is not an issue with hotplug capable platforms (Linux and macOS).
Please read libusb-1.0 API documentation here. https://libusb.sourceforge.io/api-1.0/libusb_caveats.html
- usb_resetep(), a previously deprecated function, is implemented as equivalent to calling usb_clear_halt().
- libusb-0.1 allowed you to open a device which you did not have permission to do anything useful with (all I/O requests would immediately fail). libusb-compat-0.1 does not allow you to open such devices. You can still read descriptor info without opening a device.
- usb_device's "num_children" attribute is hardcoded to 0, and "children" is hardcoded to NULL. Do you need this information in your software? Let us know on the mailing list, and we'll add it.
- Some libusb-0.1 users may have implemented I/O cancellation by running transfers in their own threads and simply killing the thread when they don't want to do the transfer any more. This is bad programming practice for obvious reasons, and this lack of functionality was one of the primary drivers for libusb-1.0 development. With libusb-1.0 or libusb-compat-0.1 backed by libusb-1.0, forcefully killing threads in this way is likely to cause all libusb I/O to halt. Instead, port your application to use libusb-1.0's asynchronous transfer API, which supports transfer cancellation.
- Error codes returned on certain events may not exactly match the error codes returned by libusb-0.1. Patches accepted to bring us closer to the behaviour of libusb-0.1 on Linux.
- The internal structure of usb_dev_handle is different from libusb-0.1. Of course, since this is a purely internal structure, that shouldn't cause any problems. In reality, some libusb-0.1 users make assumptions about what is inside (bad programming practice) and those assumptions are no longer true, resulting in broken software.
- libusb-1.0 and libusb-0.1-compat may be slower in listing the devices under Linux compared to libusb-0.1. Please refer to ticket https://github.com/libusb/libusb/issues/237. libusb 0.1 finds devices through devtmpfs by scanning /dev/bus/usb. These device nodes are likely to show up quite soon after the device is enumerated. libusb 1.0 listens for uevents from the kernel through a netlink socket. There are quite a few uevents that the kernel sends out while setting up a new device, only one of which tells libusb that a new device has arrived. This also happens in a dedicated thread, so there may be scheduling latencies at play. One potential workaround is to build libusb with netlink and not udev.
