wiki:libusb-win32
Last modified 3 years ago Last modified on 02/14/12 14:13:03

libusb-win32

Take note the latest version can be found in the libusb-win32 Sourceforge Trac Wiki.

libusb-win32 is a port of the USB library libusb-0.1 to the Microsoft Windows operating systems (Windows 98 SE, Windows ME, Windows 2000, Windows XP, Windows Vista and Windows 7. Starting from version 1.1.14.0, libusb-win32 support of Win98SE and WinME is dropped due to the age of these Operating systems.

Vista/7 64 bit are supported from version 1.2.0.0 since a Microsoft KMCS accepted digital signature is embedded in the kernel driver libusb0.sys.

Features:

  • Can be used as a filter driver for existing, already installed devices. This feature allows libusb-win32 to communicate with almost any installed USB device. The filter driver may cause problems for certain device. Therefore it should not be used by normal users. Rather it should be considered more as a development tool for developers or power users of Windows.

Starting with v1.2.2.0, 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.

  • 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.
  • The two methods described above can used in parallel.
  • 100% API and functional compatible with the libusb 0.1 project.
  • Supports all USB transfer: Control, Bulk, Interrupt and Isochronous transfers. Take note libusb 0.1 does not support Isochronous Transfer under other Operating Systems like Linux.
  • Supports all Standard Device Requests (control messages) described in chapter 9 of the USB specification.
  • Supports vendor specific control messages.

License

  • The library (including DLL, import libraries, examples and installers) is distributed under the terms of the GNU Lesser General Public License (LGPL).
  • The driver is distributed under the terms of the GNU General Public License (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 latest service packs for your OS and the latest version of libusb-win32 before requesting for any support.

Available Support Options:

  • A mailing list is available for discussions, questions, bug reports, feature request, and other issues. It is the preferred support channel. Please subscribe 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, detailed debug information can be printed out to facilitate easier debugging process.

Download

Source code and binary packages can be downloaded from the project download site. Source code is also available via anonymous Subversion.

Installation

Installation

Filter Driver Installation

  • Please use the latest release version.
  • Versions up until 0.1.12.2 have serious bugs related to the filter drivers under Vista and Windows 7 and some XP installations. Please use later versions (1.1.14.0 or newer). For 64bit Windows Vista/7/2008/2008R2, the version should be 1.2.0.0 or later.
  • The filters driver is installed by a user friendly GUI installer which makes the install and uninstall process easier and more secure. Starting with 1.2.2.0, a GUI for installing the filter driver (Filter Wizard) is the preferred way to use the filter. It only tries to attach the filter driver to a particular USB device. You can still use the command line install-filter.exe application to install class filter. But it is not recommended.
  • Log in as a user with administrator privileges.
  • Download the latest filter driver installer (libusb-win32-devel-filter-x.x.x.x.zip) and then unzip).
  • Close all applications which use USB devices before installing.
  • Run the installer, and follow its instructions. Do not run the installer from an USB storage device!
  • At the end of the installation process the installer will offer to run a test program. This program will verify the correct installation and print the descriptors of all USB devices accessible by the library. The test program can also be run later from the system's start menu.
  • A reboot isn't necessary but is recommended.

Device Driver Installation

  • Please use the latest release version.
  • The device driver is distributed as a separate package which includes everything to use libusb-win32 for single devices as a normal device driver. The installation of the filter driver is not necessary any more!
  • Log in as a user with administrator privileges.
  • Download the latest device driver binary package (libusb-win32-device-bin-x.x.x.x.zip or tar.gz).
  • Extract it to a temporary directory.
  • Use the INFWizard program to generate the INF file (modify the vendor and product IDs, strings etc). Create different inf-files to install different types of devices (devices with different IDs).
  • Unplug the device(s) from the system.
  • Open the Windows Device Manager and remove all incorrectly installed USB devices (device entries with a yellow exclamation mark).
  • Reconnect the device(s) to the system.
  • When Windows asks for a driver, choose the inf-file(s) created above. When Windows asks for a driver, choose the inf-file(s) created above. Windows will warn that the driver is is not 'digitally signed'. Ignore this message and continue with the installation. As of version V1.2.0.0, a valid digital signature is embedded inside libusb0.sys for AMD/Intel x86_64 version of Windows so that the users can install the driver as well under 64bit x86_64 version of Windows Vista/7/2008/2008R2. Please read more about the Microsoft Kernel Mode Code Signing (KMCS) policy for more information.
  • Open the Windows Device Manager to verify that the device is installed correctly. Run the test program (testlibusb-win.exe) from the 'bin directory'. It should print out the descriptors of your device(s).
  • A reboot isn't necessary.
  • Starting from version 1.2.1.0, the inf-wizard.exe has embedded driver binaries and provide an option to install the driver at the end of the process.

Removing

Removing the Filter Driver

  • To remove the filter driver open the Control Panel, open 'Software', choose the 'LibUsb?-Win32-x.x.x.x' entry, and remove it.
  • A reboot isn't necessary.
  • If the above failed, you can manually run "install-filer -u" as admin. After that you can remove the other relevant files.

Removing the Device Driver

  • To remove device filter driver, run the GUI filter driver wizard to remove it.
  • The device driver can not be easily removed from the system. You can however try to use usbdeview to remove the entries. Under Vista and Windows 7, you can use pnputil to remove the driver package.

Updating

Updating the Filter Driver

  • Remove the old version first (see above). This is the recommended method.
  • Install the new version as described above.

Updating the Device Driver

  • Download the latest device driver binary package (libusb-win32-bin-x.x.x.x.zip).
  • Modify the inf-file as described in the Installation section.
  • Open the Device Manager and select the device you want to update.
  • Choose 'Properties->Driver->Update'. Disable the automatic installation and select the new inf-file manually.
  • Since 1.2.1.0, inf-wizard.exe GUI program can be used to automatically install/update the device driver.

Development

Requirements to build libusb-win32 from source package

  • A WinXP or later system.
  • The Windows WDK 6001.18002 or later. You can get WDK from Microsoft . From 1.1.14.0 onwards, WDK will be the official tools to build the kernel driver files since it is the primary tools Windows driver developers use. It will be the official tools to build the release packages as well.
  • MinGW/Msys is required to build the MinGW GCC import library.
  • Cygwin is not officially supported but there is a port of libusb-win32 for Cygwin.
  • Borland C++ 5.5 or above is required to build the import library file for Borland C++.
  • Inno Setup 5 or above install system is required if you want to build the installer.

Build Process

Until 0.1.12.2 (including 0.1.12.2), the package is built with a standard Makefile under MinGW/MSys or Cygwin. Starting from version 1.1.4.0, MinGW/MSys can only be used to to build 32bit library and test programs.

  • Download the latest source code.
  • From a Msys shell run the command "make" to build the library and test programs.

Starting from version 1.1.4.0, batch files in the DDK_MAKE directory will be the main tools to build the driver, library, and distribution packages.

  • Download the latest source code.
  • Edit make.cfg according to your particular setup (WDK directory, locations of MinGW, Borland C++, Inno Setup, etc).
  • Use the provided batch files to the build the 32bit/64bit drivers, library and test programs. Please refer to the output of "make.cmd" for more build options.
  • To build the distribution archives and the installer run "make.cmd dist". Please refer to the output of "make.cmd" for more build options.

For developers who want to use libusb-wi32

  • To use libusb-win32 in your own programs include the supplied header file usb.h, and link against the import library (libraries for GCC, BCC, and MSVC 32bit/64bit are available).
  • To avoid any version conflicts, DO NOT include the DLL libusb0.dll in your application's directory. The DLL is part of the driver and installed automatically to the Windows system directory.
  • If you are porting a libusb 0.1.x based program from Unix style systems to Windows, remove all references to the library's global variable usb_busses. Use the function usb_get_busses() instead to get this variable. Global variables in shared libraries (DLLs) do not work well on Windows systems across different compilers. Please also take note that libusb-win32 differentiate IN Endpoints and OUT Endpoints. So IN Endpoint 1 is 0x81 and OUT Endpoint 1 is 0x01.
  • Please also refer to the following section on documentation and examples.

Documentation and Examples

This is the detailed libusb-win32 Documentation.

The excellent libusb-1.0 documentation can also serve as a good reference even though the API is not compatible.

The 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 projects and code 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.

Mailing list

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

  • libusb-0.1: The original libusb-0.1 project from which libusb-win32 is derived.
  • libusb.org: The new libusb website.
  • libusbdotnet: .Net and Mono wrapper for libusb, libusb-win32 and more.
  • pyusb: Python wrapper for libusb, libusb-win32 and more.
  • usb.org: The place to get USB specifications and other general information about USB.
  • www.lvr.com: A lot of information about USB hardware and software development.
  • Beyondlogic.org: Another site with information about USB hardware and software development.
  • USB Made Simple: Introduction to the ABCs of USB.
  • MCCI: Sells commercial generic USB drivers for Windows.
  • Jungo: Another vendor of generic USB drivers.
  • Thesycon: Another vendor of generic USB drivers.
  • Microsoft MSDN: You can find Windows specific information about USB Driver development from MSDN.
  • libusb-1.0 Windows Backend: Related project -- libusb-1.0 Windows backend
  • libwdi: Related project -- Windows Driver Installer library libwdi