Windows - leiajay/libusb GitHub Wiki

IMPORTANT: NEC/Renesas uPD720200/uPD720200A USB 3.0 users, please upgrade your drivers to version 2.1.16.0 or later. uPD720201/uPD720202 users should use version 3.x (3.0.23 or later preferred). Older versions of the driver have a bug that prevents libusb from accessing devices.

Table of Contents

Overview

About

This project adds Windows platform support to the libusb Open Source library, in order to help developers easily communicate with USB devices on Windows. Currently it supports the WinUSB and HID drivers for generic USB device access as well as the libusb-win32 and libusbK drivers.

Take note libusb-win32 and libusbK are separated projects. libusb-win32 is a Windows only project which provide libusb-0.1 API compatible library for Windows and the kernel driver libusb0.sys. libusbK is a Windows only project which provides a new set of API for Windows and kernel driver libusbK.sys.

Binary Snapshots

Pre-built binary snapshots are provided in the release directory under /<current-version>/Windows/.
These are provided AS IS for your convenience, generated for the following environments:

  • Microsoft Visual Studio and DDK/WDK → MS32(32 bit) and MS64 (64 bit) directories
  • MinGW -> MinGW32 (32 bit) and MinGW64 (64 bit) directories
Note that these archives are provided in the 7z format so you may have to install ​7-zip.

Supported Environments

Supported systems are all Windows platforms, starting with Windows XP, and including 64 bit versions, with the following exceptions:

  • Windows 2003 (Microsoft does not support WinUSB on 32bit/64bit Windows 2003)
  • Windows XP 64 bit (Microsoft does not officially support WinUSB on 64bit Windows XP)

USB 3.0 Support

libusb supports USB 3.0 controllers and devices on Windows. Proprietary vendor controller drivers for Windows 7 and earlier as well as the Microsoft controller xHCI driver for Windows 8 are supported. If you are not using Windows 8 or later, you will be using vendor driver. Make sure you upgrade to the latest version of the driver if you encounter problems.

If you are using a NEC/Renesas USB 3.0 controller, such as the fairly widespread uPD720200/uPD720200A, remember to make sure that your controller drivers are version 2.1.16.0 or later. Older versions of the drivers are known to have a bug that prevents access to USB devices.

Windows 8.x Support

libusb was tested under Windows 8 and Windows 8.1, for both 32 and 64 bit, and no issues were found.

.NET support

A .NET version of libusb, called LibUsbDotNet, based on libusb 1.0, has been developed by Travis Robinson. If you plan to use libusb in a .NET project, make sure you check http://libusbdotnet.sourceforge.net or http://sourceforge.net/projects/libusbdotnet/

How to use libusb on Windows

Driver Installation

If your target device is not HID, you must install a driver before you can communicate with it using libusb. Currently, this means installing one of Microsoft's WinUSB, libusb-win32 or libusbK drivers. Two options are available:

  • Recommended: Use the most recent version of Zadig, an Automated Driver Installer GUI application for WinUSB, libusb-win32 and libusbK...
  • Alternatively, if you are only interested in WinUSB, you can download the WinUSB driver files and customize the inf file for your device.
Note that if you install the libusb-win32 driver manually, you will also need to install the libusbK DLL, as all libusb-win32 accesses are done through it. One way to install/update libusbK.dll is to install libusbk development kit (libusbK-x.x.x.x-setup.exe from Sourceforge site and choose to update the system files during the installation.

Development Considerations

The handling of composite devices under Windows is done with multiple drivers, that are children of the usbccgp.sys driver (Composite Generic Parent), as this is the default for the OS. For more info, see "2. How Windows handles a composite device" at http://forum.silabs.com/ubbthreads.php?ubb=showflat&Number=39797. If needed, it is also possible to replace the composite parent driver to access the device.

Because Windows does not provide a native poll() function, and cygwin is the only development environment that provides such a call, the use of libusb file descriptors with poll() on cygwin is NOT supported. In a future version of libusb, we should provide better handling of native Windows events, but this will require a redesign of the libusb API, so it probably won't occur before libusb 2.0.

Known Restrictions

  • WinUSB cannot be used to send an actual reset command to an USB device. This is a limitation of WinUSB.
  • WinUSB and libusbK cannot be used to set a device configuration that is different from the first one. This is a limitation of KMDF USB I/O Target.
  • WinUSB does not support multiple concurrent applications (as per the MSDN documentation).
  • WinUSB does not support isochronous transfers.
  • With WinUSB, when LIBUSB_RECIPIENT_INTERFACE is used for the transfer, the WinUSB DLL forces the low byte of wIndex to the interface number, regardless of what you set it to. See http://www.lvr.com/forum/index.php?topic=331 for more details.
  • HID keyboards and mice cannot be accessed using the native HID driver as Windows reserves exclusive access to them.
  • Multiple HID top level collections are currently not supported (only the first top level collection will be used).
  • The HID Report Descriptors provided by libusb are recomposed and may present minor differences from the actual ones, as the Windows HID API does not allow to read them directly from the device.
  • Because there is no native poll() on Windows, the ability to return externally pollable file descriptors on Windows libusb_get_pollfd() returns an error.
  • If you use a composite device, and plan to install a libusb compatible driver for any of the interfaces, you should ensure that your driver package adds a Device Interface GUID in the registry, as proper enumeration of composite devices in libusb depends on it. This is typically achieved by adding something like the following in your inf:
    HKR,,DeviceInterfaceGUIDs,0x00010000,{12345678-1234-1234-1234-123456789ABC}
    This is in particular a problem with libusb-win32's inf-wizard which will be deprecated by libusb-win32 project. Please use Zadig instead.
  • libusb0.sys access is done through the libusbK DLL, therefore, if you plan to use the libusb-win32/libusb0.sys driver in libusb, you must have that library installed. If using a recent version of Zadig, you should not have to do anything, at it will install the library for you.

Development Links

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️