-
Notifications
You must be signed in to change notification settings - Fork 138
The story on libusb for Windows
Note: some of the info here about libusb under Windows may be outdated. However, there is no intention to change the offical avrdude Windows MSVC binaries to use the avrdude-libusb and avrdude-libftdi.
As AVRDUDE was originally written for Unix-like operating systems, the USB support is based on libusb. libusb is a library that provides access to generic USB devices, such as USB-based AVR programmers.
The libusb API has two major revisions: There is the old version libusb-0.1, and there is the current version libusb-1.0. AVRDUDE uses both the libusb-0.1 and the libusb-1.0 API.
In order to support Windows, the libusb API had been ported to Windows by the libusb team. Additionally, a Windows kernel-mode driver libusb0.sys had been developed, which can be used to access USB devices. Some years later, the Windows kernel-mode driver libusbK.sys had been developed, which provided similar capabilities as libusb0.sys.
Somewhere in 2005, Microsoft realized that, in addition to the well known USB class drivers, there was a need for a generic USB driver. Microsoft created a driver called WinUSB, which was released as a built-in system component for Windows XP and Windows Vista. The driver can be used by device vendors via a signed driver INF file. Since Windows 8.1, vendors can add a special Microsoft OS descriptor to their devices firmware, which causes the WinUSB driver to load automatically.
On Linux (or other Unix-like systems supporting libusb), you need to install the package libusb-dev. Then, you are pretty much done. You will get support for both libusb-0.1 and libusb-1.0 API, with the respective headers and libraries installed, and you can simply build and use AVRDUDE.
On Windows, the situation is a little more complicated:
- There is a Windows only project called libusb-win32, which provides a Windows library for the libusb-0.1 API. The USB kernel-mode driver libusb0.sys is also part of this project. The library supports the libusb0.sys driver and libusbk.sys.
- There is a Windows only project called libusbK, which provides a library for its own libusbK API. The USB kernel-mode driver libusbK.sys is also part of this project. The library supports the libusb0.sys, libusbK.sys, and WinUSB driver. libusbK API is not widely used as it is a Windows only API.
- There is a cross-platform project called libusb, which supports the libusb-1.0 API. The libusb-0.1 API is supported via the library libusb-compat-0.1. The support for libusb0.sys has quite some issues and the project does not recommend to use with libusb0.sys. However, it does support the driver libusbK.sys, as well as the WinUSB driver.
- The libusbK.sys driver (3.0.7.0 from 27APR2014) receive little maintenance. Due to the need for an EV Code Signing certificate, it is unlikely that we will see much community driven support for libusbK.sys.
- The Windows SDK ships with a header file called usb.h, which conflicts with the libusb-0.1 header with the same name. On Windows, the libusb-0.1 header file is typically renamed to lusb0_usb.h.
- Some vendors, including Atmel/Microchip, provide proper driver installation packages for their USB devices, which make use of the WinUSB driver.
- Some vendors provide driver installation packages, which make use of the libusb-win32 API and the kernel-mode driver libusb0.sys.
- Some vendors do not provide a proper driver installation package for their devices. They rely on hacks, such as the Zadig driver installation tool in order to load a USB driver for their devices.
- Due to the lack of WinUSB support, or support for the vendor device drivers, some tools require you to swap the device vendors driver for the libusb0.sys driver.
To summarize:
| Library | libusb-0.1 API | libusb-1.0 API | winusb.sys | libusb0.sys | libusbK.sys | header | library |
|---|---|---|---|---|---|---|---|
| libusb-win32 (1) | x | - | - | x | x | lusb0_usb.h | libusb.lib |
| libusb (2) | - | x | x | x | x | libusb.h | libusb-1.0.lib |
| libusb-compat (2) | x | - | x | x | x | usb.h | libusb.lib |
| libusbK | - | - | x | x | x | libusbk.h | libusbK.lib |
| avrdude-libusb (3) | x | - | x | x | x | lusb0_usb.h | libusb.lib |
- Can be enabled via CMake option
USE_LIBUSBWIN32, this is not recommended. - Used for Cygwin/MSYS2 builds. Its support of libusb0.sys may have some issues, especially the older 1.0.24 version.
- Used for Visual Studio builds. This is what the official avrdude Windows binary release will use. It also uses avrdude-libftdi so that you do not need to switch from FTDI vendor driver to WinUSB, which is a great advantage to the avrdude user under Windows.
- For AVRDUDE, we have USB devices that use both WinUSB and libusb0.sys.
- There is no one-fits-all library that supports the required libusb APIs and both libusb0.sys and WinUSB drivers: libusb-win32 supports libusb0.sys and libusbK only, and libusb supports WinUSB and libusbK.sys only.
- Requiring users to swap the vendor supplied driver to libusb0.sys is not desired. Forcing a non-standard driver upon a device would require users to swap drivers back and forth depending on the tools used.
- The library libusb-win32 should no longer be used, because it does not support WinUSB. If your USB devices uses the WinUSB driver, you should use the libusb library. If your USB devices use the Windows HID class driver, you should use libhidapi library.
Provide your Windows user with a proper driver installation package for your USB devices. If you require a generic USB driver (i.e. not a class driver, such as HID or CDC), choose WinUSB on Windows. If you choose to use the WinUSB driver, consider adding a Microsoft OS descriptor to your device firmware, so that the WinUSB driver is loaded automatically. You should not require your users to use tools such as Zadig.