Build Status

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.


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


See the documentation for a full API description.

require "libusb"

usb =
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)

LIBUSB::Context#devices is used to get all or only particular devices. After 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.


  • 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)


$ 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://
$ 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.



  • stabilize EventMachine interface