ozpos/libusb

Access USB devices from Ruby via libusb-1.x

Access USB devices from Ruby

LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices.

• libusb 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. 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 .

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 (API based on libusb-0.1). See {::USB} for description.

Synopsis

See the documentation for a full API description.

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 or libusbx 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)

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.

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. 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 . 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. 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