Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
libusb.org was the original home for libusb project. Now it still exists but the information and code are quite outdated.
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.
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.
libusb Windows backend can support device using libusbK.sys (and libusb0.sys driver -- not recommended due to issues) 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. If libusbK.dll is not present, then it will directly talk to device using WinUSB using WinUSB API. libusb Windows also supports device using generic HID driver or usbdk driver.
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.
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.
You have to subscribe to the mailing list in order to post.
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?
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.
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
Please refer to the following Wiki page:
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 than libusb 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 switch to libusbK driver.
- If your device uses libusb-win32 filter driver, please uninstall the filter driver and try usbdk instead.
- If your device uses other driver, and you do want to keep using the existing driver, then try usbdk.
- If your device uses other driver and you are okay with switching drivers, then switch to WinUSB (preferred) or libusbK driver.
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.
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
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 USB 3.0 too).
If you encounter such an issue, you should report it to the libusb mailing-list.
But please note that USB 3.0 is fairly new, so some Operating Systems are still catching up.
For instance, USB 3.0 support for Windows 7 and earlier is very 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. As of now (27-Dec-2016), things should be much better. Please try to upgrade to later version of the kernel whenever possible to have better support.
For Mac OS X, xHCI support has only been introduced recently with Mac OS X Mountain Lion, so USB 3.0 support may not be that mature either. Things should be better now (27-Dec-2016). Whenever possible, please upgrade to later version of Mac OS X for better support.
We will try to help you sort issues related to USB 3.0 usage where possible. But before you contact us, if on Windows 7, please make sure you test with the latest USB 3.0 drivers available from your xHCI provider, or, if on Linux, please make sure you test with the latest kernel, as the xHCI driver is regularly being updated there.
If your application will revolve around HID access, you are strongly encouraged to try to use the HIDAPI library by Signal 11 Software, which is also cross-platform. It uses native HID API under Windows and Mac OS X. 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 Mac OS X, you must install a codeless kext kernel driver and then reboot, before you will be able communicate with the device. This may not be easy with the release of later Mac OS X versions. So it is not recommended. 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 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.
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.
Please refer to the Windows CE related information in the following file.
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.