= Windows backend = == About == The aim of this project is to bring a Windows backend to the mainline libusb 1.0 branch, so that libusb 1.0 can easily be used on Windows platforms. == Status == The Windows backend is now in pre-release stages. As of 2010.07.29, it is now included into the official libusb v1.0 tree (MinGW and cygwin only for the time being, with Visual C++ and WDK/DDK coming soon). It supports both HID and WinUSB driven devices, with libusb0.sys driver support (from libusb-win32) planned in a future release.[[BR]] Supported systems are all Windows platforms, starting with Windows XP, and including 64 bit versions, with the following untested exceptions: * Windows 2003 * Windows XP 64 bit == Supported development environments == The following development environments are currently supported for libusb 1.0 on Windows: * [http://www.mingw.org MinGW] (32 bit) or [http://mingw-w64.sourceforge.net/ MinGW-w64]. If using MinGW-w64, make sure you use a recent version (> 2010.03), as earlier ones had a [http://sourceforge.net/tracker/index.php?func=detail&aid=2904747&group_id=202880&atid=983354 bug] preventing libusb from working. * [http://msdn.microsoft.com/en-us/visualc/default.aspx Microsoft Visual C++ (Visual Studio)], either Express or full version, from version 6.0. You should be able to produce both win32 and x64 binaries with Visual C++. Take note the free Express version of Visual C++ can not produce 64bit binaries. Also note that Microsoft crippled the 2010 version of Visual C++ Express, so that it chokes on importing project files that have 64 bit builds. If you plan on using Express 2010, you'll have to recreate the project files from scratch. * [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=36a2630f-5d56-43b5-b996-7633f2ec14ff Windows DDK build environment], which is '''freely available''', through the use of the 'ddk_build.cmd' file. This will also produce both 32 and 64 bits binaries. * [http://www.cygwin.com/ Cygwin]. Take note that Cygwin currently can not produce 64bit binaries. == Source == The current development Windows backend is available in the [http://git.libusb.org/ libusb main git repository] under [http://git.libusb.org/?p=libusb-pbatard.git libusb-pbatard.git]. For those not familiar with git, here are the git commands you can use retrieve and compile the Windows branch: {{{ git clone git://git.libusb.org/libusb-pbatard.git ; retrieve development branch (this only needs to be done once) git pull ; keep in sync with the remote tree }}} On Windows, if you don't want to use git on the commandline, you can use [http://code.google.com/p/tortoisegit/ TortoiseGit] to access and keep in sync with the git repository.[[BR]] Note that before you can install [http://code.google.com/p/tortoisegit/ TortoiseGit] you need to install [http://code.google.com/p/msysgit/ MSysGit] and make sure that, during the installation of MSysGit, when prompted to adjust the PATH environment, you select "Run Git from the Windows Command Prompt" (2nd option). Also, in the general settings of [http://code.google.com/p/tortoisegit/ TortoiseGit], the MSysGit path must point to the MSysGit bin directory (eg: C:\Program Files (x86)\Git\bin") Also note that, for MinGW and cygwin, as with the original libusb 1.0 development tree, '''you need to run './autogen.sh' in order to have configure and Makefile created for you'''. == Creating applications using libusb == To create projects relying on libusb 1.0, please refer to how the example executables (lusb, xusb) are compiled.[[BR]] Please note that, on Windows, libusb depends on the SetupAPI, OLE32 and AdvAPI32 libraries, so you must either add "-lsetupapi -lole32 -ladvapi32" in your Makefile (if using MinGW/Cygwin) or add SetupAPI.lib, OLE32.lib and AdvAPI32.lib as linker dependencies in your project files (MS). == .NET support == A .NET version of libusb, called [http://libusbdotnet.sourceforge.net/V2/Index.html LibUsbDotNet], based on libusb 1.0 and the Windows backend has also been developed by Travis Robinson.[[BR]] If you plan to use libusb in a .NET project, please make sure you check [http://libusbdotnet.sourceforge.net] or [http://sourceforge.net/projects/libusbdotnet/] == Driver Installation == To access your USB devices with the Windows backend, if the device is not HID compliant, you will need to install the relevant driver. Two options are available: * The easiest option is to use the most recent version of our Automated Driver Installer GUI: "zadig.exe", which is part of the Windows Driver Installer library, [wiki:libwdi libwdi].[[BR]] The current version, which is compatible with both 32 and 64 bit Windows platforms, starting with Windows 2000, should be able to install a WinUSB driver for any USB device.[[BR]] Note that because the installer needs to run with administrative privileges, it is recommended to check the md5 checksum after download (or recompile your own version from [http://git.libusb.org/?p=libwdi.git;a=shortlog the source])[[BR]] * [http://libusb-winusb-wip.googlecode.com/files/zadig.exe zadig.exe]: 5.7 MB, md5sum: 606199bc8b4ce36f15b590b5ddc1c61e, compiled with MinGW-w64 from libwdi v1.0.1.[[BR]] NB: When ran in advanced mode, Zadig also allows the selection and installation of the signed libusb0.sys driver from [http://sourceforge.net/apps/trac/libusb-win32/wiki libusb-win32] (v.1.2.1.0).[[BR]] * Or you can download the [http://libusb-winusb-wip.googlecode.com/files/winusb%20driver.zip WinUSB driver files], then customize the .inf for your device and install the driver by following the instructions that are either provided [wiki:winusb_driver_installation here] or in the README file that comes with the driver archive. == Latest Binary Snapshots == The following pre-built binary snapshots 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 Cygwin users should be able to use the MinGW (32 bit) library with the option -mno-cygwin[[BR]]Note that these archives are provided in the 7z format. If you need a decompressor, you can install [http://www.7-zip.org/ 7-zip]. * '''[http://libusb-winusb-wip.googlecode.com/files/libusb_2010.09.06.7z 2010.09.06 (pbr301)]''' * '''[http://libusb-winusb-wip.googlecode.com/files/libusb_2010.08.19.7z 2010.08.19 (pbr299)]''' * '''[http://libusb-winusb-wip.googlecode.com/files/libusb_2010.08.18.7z 2010.08.18 (pbr298)]''' * '''[http://libusb-winusb-wip.googlecode.com/files/libusb_2010.08.16.7z 2010.08.16 (pbr295)]''' * '''[http://libusb-winusb-wip.googlecode.com/files/libusb_2010.08.10.7z 2010.08.10 (pbr294)]''' * '''[http://libusb-winusb-wip.googlecode.com/files/libusb_2010.08.05.7z 2010.08.05 (pbr293)]''' == Development Considerations == * For the first release, only [http://msdn.microsoft.com/en-us/library/aa476426.aspx WinUSB] and HID access will be supported, with provisions for other access modes to be included later. This should cover most devices however. * Windows' handling of composite devices is done with multiple drivers (VID_####&PID_####&MI_##), descendants of the usbccgp.sys driver (Composite Generic Parent), as this is Windows' default. For more info, see "2. How Windows handles a composite device" at [http://www.cygnal.org/ubb/Forum9/HTML/001050.html]. It is however possible to replace the composite parent driver with WinUSB 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. We should provide native Windows events, to use with WaitForSingleObject/WaitForMultipleObjects, in a future version of libusb. == Known Restrictions == * Neither WinUSB or HID can be used to send an actual reset command to an USB device. This is a limitation of the Microsoft drivers. * Neither WinUSB or HID can be used to set a device configuration that is different from the default one. This is a limitation of the Microsoft drivers. * WinUSB does not support multiple concurrent applications (as per the [http://download.microsoft.com/download/9/C/5/9C5B2167-8017-4BAE-9FDE-D599BAC8184A/WinUsb_HowTo.docx WinUSB Howto whitepaper]). * WinUSB does not support isochronous transfers. * HID keyboards and mice will not have read or write access. This is because Windows requires an exclusive access to them, and uses a driver that prevent generic access. * Likewise, HID devices or interfaces for which the OS has a specific Windows driver different from the generic HID one cannot be accessed (eg. HID audio devices). * Multiple HID top level collections are currently not supported (only the first top level collection will be used). * HID vendor requests are not implemented. * Because there is no native poll on Windows, the ability to return externally pollable file descriptors on Windows (libusb_pollfd) has been disabled. == To Do == * libusb0.sys integration * multithread sample application * hotplug detection == Done == * automated driver installation ([http://libusb.org/wiki/libwdi libwdi]) * full pthread-win32 dependency removal * multithreading/concurrent access * HID * device enumeration * descriptors retrieval * composite devices & interface selection * poll and pipe * control transfers * bulk/interrupt transfers * device reset * transfer cancellation * MSVC compatibility == Development's status log == Please consult the '''[http://git.libusb.org/?p=libusb-pbatard.git;a=log git log]''' or the '''raw''' [wiki:windows_backend_activity_log Activity Log].[[BR]] NB: Previous development occurred on the [http://code.google.com/p/libusb-winusb-wip/source/list Google Code SVN Repository] but this is '''no longer maintained'''. == Development Links == * [http://www.microsoft.com/whdc/connect/usb/winusb_howto.mspx How to Use WinUSB to Communicate with a USB Device].[[BR]]Note that the inf file given in the howto has a typo. If you don't change SourceDisksFiles.'''NT'''amd64 to SourceDisksFiles.amd64, the driver installation will fail to copy the required DLLs on 64 bit systems... * [http://209.85.229.132/search?q=cache:3tk2Nqp0wfoJ:www.osronline.com/article.cfm%3Farticle%3D532+selecting+configuration+descriptor+winusb Using WinUSB for User-Mode to USB Device Communication] * [http://msdn.microsoft.com/en-us/library/ff540046.aspx#winusb WinUSB User-Mode Client Support Routines] * [http://msdn.microsoft.com/en-us/library/ff538865.aspx HID Class Support Routines] * [http://msdn.microsoft.com/en-us/library/ff539849.aspx HID Class Driver IOCTLs] * [http://blogs.msdn.com/usbcoreblog/ Microsoft's USB Core Team Blog] (including resources on instrumenting the USB stack in Windows 7) * [http://blogs.msdn.com/iliast/archive/2008/03/10/why-do-we-need-wdf-coinstallers.aspx additional] [http://blogs.msdn.com/iliast/archive/2009/08/13/wdf-logo-requirements-regarding-coinstallers.aspx information] about Windows Co-Installers * [http://msdn.microsoft.com/en-us/library/e5ewb1h3%28v=vs.71%29.aspx Enabling Memory Leak Detection in Visual C++] * [http://y-a-terminal.svn.sourceforge.net/viewvc/y-a-terminal/trunk/MKY.IO.Usb/ HID implementation example (C#)] == Mailing list == The libusb-devel mailing list exists for the users of the library, plus developers interested in contributing to the library itself. * [http://lists.sourceforge.net/mailman/listinfo/libusb-devel Subscribe] * [http://sourceforge.net/mailarchive/forum.php?forum_name=libusb-devel Archives at SourceForge] * [http://news.gmane.org/gmane.comp.lib.libusb.devel.general Archives at GMANE] * [http://www.nabble.com/LibUSB-f14231.html Archives at Nabble]