FAQ

mcuee edited this page Dec 27, 2016 · 11 revisions
Clone this wiki locally

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 may not exist for very long.

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

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

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. 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 HID devices?

libusb does try to support HID devices where possible. 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.

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.

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, as they are system reserved, as well as getting a direct read of HID report descriptors. Apart from that, you should be communicate with an HID device as you would with any other USB device.

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. It also covers FreeBSD.

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.

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.