Skip to content
mcuee edited this page Jul 24, 2024 · 22 revisions

Table of Contents

libusb-win32

The installer from libusb-win32 does not work under Windows 7/8/8.1/10/11, please use the GUI installer from libusbK or Zadig.
libusb-win32 is a port of the USB library libusb 0.1 (http://sourceforge.net/projects/libusb) to the Microsoft Windows operating systems (Windows 2000, Windows XP, Windows Vista and Windows 7, 8, 8.1, 10, 11). The library allows user space applications to access many USB device on Windows in a generic way without writing any line of kernel driver code.

libusb-win32 1.2.6.0 version will be the last version to support Windows 2000/XP/Vista. libusb-win32 1.2.7.3 vevrsion and will be the last version to support Windows 7 because of Microsoft kernel driver signing policy change. Windows 10/11 will be the main supported platforms from libusb-1.3.0.0 version onwards.

Features

Can be used as a filter driver for existing, already installed devices. This feature allows libusb-win32 to communicate with many installed USB device.

A GUI (filter wizard) is provided and it is only to attach the filter driver to particular USB device of interests. So this should be safer to use than the older behavior which tries to attach the filter to all USB device (acting as class filters to all possible device class). It is still possible to do that by using the console version of install-filter.exe but this is only recommended to be used by developers and power users since this could potentially cause BSODs.

When you use the device filter mode using the Filter Wizard GUI, you may have to repeat the process if you unplug the device and plug it back in a different port. Please take note that the device filter driver (upper filter) may not work with all USB devices.

Can be used as a normal device driver for devices for which no driver exists (self build/developed USB hardware, etc). You can also replace the existing device driver with libusb-win32 device driver if desired. This is the preferred way to use libusb-win32.

When you use Zadig or libusbk-inf-wizard GUI to replace a device with inbox driver (like HID or USB Mass Storage Device), you may need to repeat the process if you plug in a same device but with different serial number. This is because Windows prefers inbox driver (signed) and ranks it higher than the libusb-win32 driver package.

The two methods described above can be used in parallel. However, the device driver mode is the preferred way to use libusb-win32 followed by using device filter driver mode. The class filter driver is not recommended to be used.

100% API and functional compatible with the libusb 0.1 project.

Supports all USB transfer: Control, Bulk, Interrupt and Isochronous transfers. Take note the libusb 0.1 under other OS (Linux, Mac OS X, BSDs, etc) does not support Isochronous Transfer. libusb-win32 also has its own asynchronous API which is not available to libusb-0.1 under Linux or other OS.

Supports all Standard Device Requests (control messages) described in chapter 9 of the USB specification.

Supports vendor specific control messages.

License

The library (DLL and import lib, examples, installers) is distributed under the terms of the GNU Lesser General Public License (LGPL http://www.gnu.org/licenses/licenses.html#LGPL). Take note the installers in the older versions of libusb-win32 (before 1.2.0.0) is distributed under GPL, not LGPL.

The driver portion (libusb0.sys) is distributed under the terms of the GNU General Public License (GPL http://www.gnu.org/licenses/licenses.html#GPL).

This license combination explicitly allows the use of this library in commercial, non-Open-Source applications. Read the licenses carefully and apply all of their requirements before including this library in a commercial application!

Support

If something isn't working as expected, make sure that you have installed the the latest version of libusb-win32 and the latest service packs for your OS before requesting for any support.

Available Support Options: A mailing list (https://sourceforge.net/mail/?group_id=78138) is available for discussions, questions, bug reports, feature request, and other issues. It is the preferred support channel. Please subscribe (http://lists.sourceforge.net/lists/listinfo/libusb-win32-devel) to the list first before posting.

The project page offers different forms which can be filled out to get support, to report bugs, or to request new features. Please describe your problems and your system as precise as possible (OS, service packs, version of libusb-win32, type of device, output of "testlibusb-win.exe", etc.). This will make solving problems a lot easier. Debug version of the libusb-win32 are provided from libusb-1.2.3.0 onwards. Together with Microsoft DebugView http://technet.microsoft.com/en-us/sysinternals/bb896647), detailed debug information can be printed out to facilitate easier debugging process.

You should also read the FAQ (Frequently Asked Questions) at https://github.com/mcuee/libusb-win32/wiki/FAQ.

Download

Source code and binary package release can be downloaded from this github repo.

Installation

Installation

Filter Driver Installation

Please use the latest release version. 1.2.6.0 is widely used but the latest release version is recommended. As of April 2024, the latest relese version is 1.4.0.

The filters driver is installed by a user friendly GUI installer which makes the install and uninstall process easier and more secure.

Download the latest filter driver installer (libusb-win32-devel-filter-x.x.x.x.zip and then unzip, or libusb-win32-devel-filter-x.x.x.x.exe ).

Close all applications which use USB devices before installing.

Run the test program (testlibusb-win.exe) from the system's start menu. This program will verify the correct installation and print the descriptors of the USB devices accessible by the library.

A reboot may not be necessary but is recommended.

Note: libusb-win32 GUI installer is missing from 1.4.0.0 release for now. Filter GUI is available though as part of the binary package.

Device Driver Installation

Please use Zadig or libusbK-inf-wizard to install libusb-win32 device driver 1.2.6.0 version. Please use Zadig 2.9 version to install libusb-win32 device driver 1.4.0.0 release. Custom version of Zadig may be included in the release sometimes since Zadig will lag behind libusb-win32 release for some time.

Zadig is part of libwdi project. Latest version is Zadig 2.9 which supports libusb-win32 1.4.0.0 release. https://github.com/pbatard/libwdi/releases/tag/v1.5.1

Removing

Removing the Filter Driver

To remove device filter driver, run the GUI filter driver wizard to remove it.

Removing the Device Driver

The device driver can not be easily removed from the system. You can however try to use usbdeview http://www.nirsoft.net/utils/usb_devices_view.html to remove the entries. Under Vista and Windows 7, you can use pnputil (http://msdn.microsoft.com/en-us/library/ff550419%28v=vs.85%29.aspx) to remove the driver package.

Updating

Updating the Filter Driver

Remove the old version first (see above). This is the recommended method even though it is not strictly necessary. Install the new version as described above.

Updating the Device Driver

Please use Zadig or libusbK-inf-wizard to install libusb-win32 device driver 1.2.6.0 version. Please use the customized Zadig version to install libusb-win32 1.2.7.3 version.

Development

Requirements to build libusb-win32 from source package

Windows 10 or later system.

VS 2019/VS2022 or later Windows WDK for Windows 11 or EWDK WIN11 version

MinGW and MinGW-w64 will not be supported as the driver building tool. Even if they can build the driver from the source codes, the resultant libusb0.sys will not be supported.

Inno Setup 6 or above (http://www.jrsoftware.org/isinfo.php) install system is required if you want to build the installer.

For developers who want to use libusb-win32

To use libusb-win32 in your own programs include the supplied header file lusb0_usb.h, and link against the import library or DLL.

If you are porting a libusb 0.1.x based program from Unix style systems to Windows, please take note that libusb-win32 differentiates IN Endpoints and OUT Endpoints. So IN Endpoint 1 is 0x81 and OUT Endpoint 1 is 0x01. One more difference is that you need to call usb_set_configuration() before usb_claim_interface(). This is especially for the filter drive. Take note this is not really necessary under Linux libusb-0.1.

Please also refer to the following section on documentation and examples.

Documentation and Examples

This is the detailed libusb-win32 Documentation https://sourceforge.net/p/libusb-win32/wiki/Documentation/. The excellent libusb-1.0 documentation (http://libusb.sourceforge.net/api-1.0/) can also serve as a good reference even though the API is not compatible.

The source codes can also serve as some kind of documentation for the libusb-win32 developers. However, examples are often the best documentations for Open Source Projects like libusb and libusb-win32, especially for the users of the library. Here are some links to https://sourceforge.net/p/libusb-win32/wiki/Examples/ using libusb-0.1 and libusb-win32. Language wrappers (DotNet, Python, Perl, Ruby, Java, etc) are also listed.

Portability

libusb-0.1 is widely supported by operating systems like Linux, FreeBSD, NetBSD, OpenBSD, Darwin/MacOS X and Solaris. libusb-win32 is API compatible with libusb 0.1. So it will greatly help you porting your libusb-0.1 based application to Windows.

FreeBSD 8/9 includes a new FreeBSD-specific reimplementation of the libusb-0.1 API, so your applications will probably work there too. The source code for this library can be found here (http://svn.freebsd.org/viewvc/base/head/lib/libusb/).

Mailing list

The libusb-win32-devel mailing list exists for both users of the library and developers interested in contributing to the library itself.

Links

libusb(http://sourceforge.net/projects/libusb): The main libusb project from which libusb-win32 is derived.

libusb(http://www.libusb.info): The new libusb website.

libusbdotnet(http://sourceforge.net/projects/libusbdotnet): .Net and Mono wrapper for libusb, libusb-win32 and more.

pyusb(http://sourceforge.net/projects/pyusb): Python wrapper for libusb, libusb-win32 and more.

usb.org(http://www.usb.org): The place to get USB specifications and other general information about USB.

USB Made Simple (http://www.usbmadesimple.co.uk): Introduction to the ABCs of USB.

Microsoft MSDN (http://msdn.microsoft.com): You can find Windows specific information about USB Driver development from MSDN.

libwdi (https://github.com/pbatard/libwdi): Related project -- Windows Driver Installer library libwdi