[![Build Status](https://travis-ci.org/larskanis/libusb.svg)](https://travis-ci.org/larskanis/libusb) Access USB devices from Ruby ============================ LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices. * [libusb](http://libusb.info) is a library that gives full access to devices connected via the USB bus. No special kernel driver is thus necessary for accessing USB devices. * This Ruby binding supports the API version 1.0 of [libusb](http://libusb.info). Note that the old "legacy" version 0.1.x of libusb uses a completely different API that is covered by the ruby extension [ruby-usb](http://www.a-k-r.org/ruby-usb/) . LIBUSB for Ruby is covered by the GNU Lesser General Public License version 3. Features -------- * Access to descriptors of devices, configurations, interfaces, settings and endpoints * Synchronous and asynchronous communication for bulk, control, interrupt and isochronous transfers * Support for USB-3.0 descriptors and bulk streams * Compatibility layer for [ruby-usb](http://www.a-k-r.org/ruby-usb/) (API based on libusb-0.1). See {::USB} for description. Synopsis -------- See [the documentation](http://rubydoc.info/gems/libusb/frames) for a full API description. ```ruby require "libusb" usb = LIBUSB::Context.new device = usb.devices(:idVendor => 0x04b4, :idProduct => 0x8613).first device.open_interface(0) do |handle| handle.control_transfer(:bmRequestType => 0x40, :bRequest => 0xa0, :wValue => 0xe600, :wIndex => 0x0000, :dataOut => 1.chr) end ``` {LIBUSB::Context#devices} is used to get all or only particular devices. After {LIBUSB::Device#open_interface opening and claiming} the {LIBUSB::Device} the resulting {LIBUSB::DevHandle} can be used to communicate with the connected USB device by {LIBUSB::DevHandle#control_transfer}, {LIBUSB::DevHandle#bulk_transfer}, {LIBUSB::DevHandle#interrupt_transfer} or by using the {LIBUSB::Transfer} classes. A {LIBUSB::Device} can also be used to retrieve information about it, by using the device descriptor attributes. A {LIBUSB::Device} could have several configurations. You can then decide of which configuration to enable. You can only enable one configuration at a time. Each {LIBUSB::Configuration} has one or more interfaces. These can be seen as functional group performing a single feature of the device. Each {LIBUSB::Interface} has at least one {LIBUSB::Setting}. The first setting is always default. An alternate setting can be used independent on each interface. Each {LIBUSB::Setting} specifies it's own set of communication endpoints. Each {LIBUSB::Endpoint} specifies the type of transfer, direction, polling interval and maximum packet size. Prerequisites ------------- * Linux, MacOSX or Windows system with Ruby MRI 1.8.7/1.9/2.0, JRuby or recent version of Rubinius * Optionally: [libusb](http://libusb.info) or [libusbx](http://libusbx.org) library version 1.0.8+ : * Debian or Ubuntu: ``` $ sudo apt-get install libusb-1.0-0-dev ``` * OS-X: install with homebrew: ``` $ brew install libusb ``` or macports: ``` $ port install libusb ``` * Windows: libusb.gem already comes with a precompiled `libusb.dll`, but you need to install a device driver (see [below](#usage-on-windows)) Install ------- $ gem install libusb While ```gem install``` the system is checked for a usable libusb(x) library installation. If none could be found, a bundled libusb version is built and used, instead. Latest code can be used in this way: $ git clone git://github.com/larskanis/libusb.git $ bundle $ rake install_gem Device hotplug support ---------------------- Support for device hotplugging can be used, if ```LIBUSB.has_capability?(:CAP_HAS_HOTPLUG)``` returns ```true```. This requires libusb(x)-1.0.16 or newer on Linux or OS-X. Windows support is [still on the way](https://github.com/libusbx/libusbx/issues/9). A hotplug event handler can be registered with {LIBUSB::Context#on_hotplug_event}. You then need to call {LIBUSB::Context#handle_events} in order to receive any events. This can be done as blocking calls (possibly in it's own thread) or by using {LIBUSB::Context#pollfds} to detect any events to handle. Usage on Windows ---------------- In contrast to Linux, any access to an USB device by LIBUSB on Windows requires a proper driver installed in the system. Fortunately creating such a driver is quite easy with [Zadig](http://sourceforge.net/projects/libwdi/files/zadig/). Select the interesting USB device, choose WinUSB driver and press "Install Driver". That's it. You may take the generated output directory with it's INI-file and use it for driver installation on other 32 or 64 bit Windows systems. Cross compiling for Windows --------------------------- Libusb-gem can be cross built for the win32 platform, using the [rake-compiler-dock](https://github.com/larskanis/rake-compiler-dock) . Just run: $ rake gem:windows If everything works, there should be `libusb-VERSION-x86-mingw32.gem` in the pkg directory. EventMachine integration ------------------------ Libusb for Ruby comes with an experimental integration to [EventMachine](http://rubyeventmachine.com/). That API is currently proof of concept - see {LIBUSB::Context#eventmachine_register}. If you're experienced with EventMachine, please leave a comment. Resources --------- * Project's home page: http://github.com/larskanis/libusb * API documentation: http://rubydoc.info/gems/libusb/frames * Mailinglist: http://rubyforge.org/mailman/listinfo/libusb-hackers * Overall introduction to USB: http://www.usbmadesimple.co.uk Todo ---- * stabilize EventMachine interface