Clone this wiki locally
This page details the specifics of the Windows backend part of libusb, which helps 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.
Please note that libusb-win32 and libusbK are separate projects. libusb-win32 is a Windows-only project which provides a libusb-0.1 API compatible library for Windows and the associated kernel driver libusb0.sys. libusbK is a Windows only project which provides a new set of API for Windows (supporting WinUSB, libusb0.sys and libusbk.sys) and kernel driver libusbK.sys.
The pre-built Windows binaries are provided AS IS for your convenience, generated for the following environments:
- Microsoft Visual Studio; MS32 (32 bit) and MS64 (64 bit) directories
- MinGW -> MinGW32 (32 bit) and MinGW64 (64 bit) directories.
7zformat so you may have to install 7-zip.
Installing and building libusb via vcpkg:
You can download and install libusb using the vcpkg dependency manager:
git clone https://github.com/Microsoft/vcpkg.git cd vcpkg .\bootstrap-vcpkg.bat .\vcpkg integrate install .\vcpkg install libusb
The libusb port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.
msys2 has a libusb package. Please contact the msys2 project if you encountered issues with the msys2 package. It is recommended to use pkg-config (libusb-1.0.pc) on MSYS2 or other MinGW-w64 distributions.
Reference: how to use libusb under MinGW-w64?
You may want to build from source if you encounter compatibility issues with the pre-built binaries. We recommend either Visual Studio or a MinGW-w64 based toolchain like MSYS2.
Note that the MinGW.org toolchain is not supported. clang support patches are welcome. Patches to add support for other toolchains (including MinGW.org) may be accepted after review even though these toolchains are not officially supported.
Supported systems are all Windows platforms, starting with Windows Vista, and including 64 bit versions. Windows XP support was dropped in libusb 1.0.24.
libusb supports USB 3.x 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/8.1/10 are supported. If you are are using Windows 7 or earlier version, you will be using vendor driver. Make sure you upgrade to the latest version of the driver if you encounter problems.
If your target device is not HID, and your device is not using WinUSB driver, 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
libusb-win32 (please use device driver mode if you really need to use it as the filter driver mode is not well supported)and
libusbK (only if you hit WinUSB limitations).
- For version 1.0.21 or later, you can also use the usbdk backend. usbdk provides another driver option for libusb Windows backend. For 1.0.21, usbdk is a compile-time option, but it becomes a runtime option from version 1.0.22 onwards, so you need to specify the usbdk backend using something like the following.
libusb_context * ctx = NULL; libusb_init(&ctx); libusb_set_option(ctx, LIBUSB_OPTION_USE_USBDK);
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. If needed, it is also possible to replace the composite parent driver to access the device. Zadig can be used for this purpose.
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.
WinUSBcannot be used to send an actual reset command to an USB device. This is a limitation of WinUSB.
libusbKcannot be used to set a device configuration that is different from the first one. This is a limitation of KMDF USB I/O Target.
WinUSBdoes not support multiple concurrent applications (as per the Microsoft Windows Hardware Drivers documentation).
libusbkdriver allows this but it may have the limitation that you can claim the interface multiple times (https://github.com/libusb/libusb/issues/807).
libusb-win32driver will also allow this but it is not recommended to be used due to multiple issues reported.
WinUSBdoes not support isochronous transfers under Windows XP/Vista/7/8. WinUSB under Windows 8.1 or later supports isochronous transfer. libusb Windows supports isochronous transfer using the usbdk backend from version 1.0.21. libusb-1.0.22 adds isochronous support using libsubK driver. libusb-1.0.23 adds isochronous transfer support for WinUSB (Windows 8.1/10 or later) but the support may not be that mature.
WinUSBallows setting up different pipe policy and RAW_IO can be useful in some use cases. Unfortunately it will make the WinUSB backend pretty complicated so this is not supported. why not WinUSB RAW_IO pipe policy?
LIBUSB_RECIPIENT_INTERFACEis used for the transfer, the
WinUSBDLL forces the low byte of
wIndexto the interface number, regardless of what you set it to.
- This is not a real limitation though, please refer to the OSR threads. From Tim Roberts answer in that thread:
- One can also argue that this is a security measure. The USB spec requires that the low byte of wIndex be set to the interface number when the recipient is set to "interface". Devices that use that field for other purposes are broken.
- 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.
- Windows HID API does not support custom Control Transfer, everything needs to be done through report. Please check out the discussion here.
- 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:
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 and libusbk.sysaccess is done through the libusbK DLL, therefore, if you plan to use the libusb-win32/libusb0.sys or libusbK/libusbk.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.
- libusb0.sys: the support of libusb0.sys filter driver has quite some issues, you should use the device driver mode if you really need to use libusb0.sys.
- libusb0.sys: cannot send libusb_control_transfer with zero wLength with libusb0.sys 22.214.171.124 version. Please use libusb0.sys 126.96.36.199 snapshot release or later.
- uhubctl will not work under Windows. Please refer to Issue #391 due to limitation of the underlying drivers (libusb0.sys, libusbk.sys, usbdk and WinUSB) with regard to USB Hubs.
How to Use WinUSB to Communicate with a USB Device & WinUSB (Winusb.sys) Installation.
Note that the inf file given in the howto has a typo. If you don't change
SourceDisksFiles.amd64, the driver installation will fail to copy the required DLLs on 64 bit systems...
- Using WinUSB for User-Mode to USB Device Communication
- WinUSB User-Mode Client Support Routines
- Microsoft's USB Core Team Blog
- Microsoft HW Development Center -- USB
- additional information about Windows Co-Installers
- Finding Memory Leaks Using the CRT Library
- libusbK documentation
- libwdi/Zadig Wiki
- Microsoft Devcon source code
- Microsoft USBView source code