mcuee edited this page Aug 4, 2018 · 24 revisions

Table of Contents

Frequently Asked Questions

libusb.org, libusbx.org and libusb.info

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.

libusb-win32, libusbK and 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.

What about usbdk?

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.

Licensing

What is the libusb license?

libusb is released under version 2.1 of the GNU Lesser General Public License (LGPL).

Can I use libusb in a proprietary application?

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.

Getting help

How can I get help? What is the best practice to describe my issues?

Please read the libusb Troubleshooting page and use the mailing list for support.

I tried to post to the libusb mailing list but it failed. Why?

You have to subscribe to the mailing list in order to post.

Running libusb

Can I run libusb applications on Linux without root privilege?

Yes.
The standard solution is to use udev rules. Here are some links to udev related websites.

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.

3) In certain cases, you can manually edit the Info.plist configuration file of a kernel extension to prevent it from loading for certain VID/PID combination.

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:

How to use libusb under Windows?

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 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.

Can libusb be used on the USB device side, e.g. Linux Gadget Device?

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.

Can I use libusb to open a file on an USB storage 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.

Does libusb support USB 3.0?

Yes (as long as the underlying OS supports USB 3.0 too).

My device works when plugged on an USB 2.0 port but not on an USB 3.0 one

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.

Does libusb support USB HID devices?

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.

Platform Support

Does libusb support Windows RT?

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.

Does libusb support Apple iOS device?

No.

Does libusb support Windows CE based device?

Yes.

Please refer to the Windows CE related information in the following file.
https://github.com/libusb/libusb/blob/master/INSTALL_WIN.txt

Does libusb support Android

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.


Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.