# -*- coding: utf-8 -*-

Access USB devices from Ruby via libusb.

DESCRIPTION:

RibUSB is a Ruby extension that gives a Ruby programmer access to all functionality of libusb, version 1.0.

  • libusb is a library that gives full access to devices connected via the USB bus. No kernel driver is thus necessary for accessing USB devices. Linux and OSX support is ready, Windows support is under development, ports to other systems are bound to appear with time.

  • This Ruby extension supports the API version 1.0 of libusb. Note that the old “legacy” version 0.1.x of libusb uses a completely different API and is thus not supported.

  • The API is currently work-in-progress. Do not rely on it being stable just yet.

This project is being developed by András G. Major and Lars Kanis, is hosted on RubyForge and Github.

RibUSB is covered by the GNU Public License version 2.

FEATURES:

  • Access to descriptors of devices, configurations, interfaces, settings and endpoints

  • Synchronous and asynchronous communication for bulk, control and interrupt transfers

  • Compatibility layer for ruby-usb (API based on libusb-0.1)

  • Download as source or precompiled win32 gems

SYNOPSIS:

require "ribusb"

usb = RibUSB::Context.new
device = usb.find(:idVendor => 0x04b4, :idProduct => 0x8613).first
device.claim_interface(0)
device.control_transfer(:bmRequestType => 0x40, :bRequest => 0xa0, :wValue => 0xe600, :wIndex => 0x0000, :dataOut => 1.chr)
device.release_interface(0)

RibUSB::Context#find is used to get all or only particular devices. A RibUSB::Device can be used to communicate with the USB device by RibUSB::Device#control_transfer, RibUSB::Device#bulk_transfer or RibUSB::Device#interrupt_transfer.

RibUSB is compatible to ruby-usb. See ::USB for description of ruby-usb compatibility layer.

REQUIREMENTS:

  • libusb version 1.0 or greater

  • Ruby MRI 1.8, 1.9 or Rubinius

  • Linux, MacOSX or Windows system

INSTALL:

In order to install RibUSB from source code, you need a working Ruby installation, including its header files and build utilities (on Debian and Ubuntu systems, part the ruby-dev package). Also, you need a C compiler (usually gcc), and make. The libusb-1.0 library along with its header files must naturally be present (on Debian and Ubuntu system, install the libusb-1.0-0-dev package).

To install from gem, execute this command to download RibUSB and to build it. On Windows a binary gem is installed automatically:

gem install ribusb

To install from source, execute this command to configure RibUSB and to build it:

git clone git://github.com/larskanis/ribusb.git
rake install_gem

From now on, you can use the RibUSB extension from any instance of Ruby on that computer by “requiring” it from within your Ruby program:

require "ribusb"

Please browse the documentation on the website for example uses of RibUSB. Have fun.

Usage on Windows

In contrast to Linux, any access to an USB device by RibUSB 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 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.

RibUSB can be used as precompiled Windows gem, so there should be no need for a compiler.

Cross compiling for mswin32

Using rake-compiler a cross compiled ribusb-gem can be build on a linux or darwin host for the win32 platform. Libusb is downloaded from source git repo and cross compiled. The generated gem is statically linked against libusb-1.0. There are no runtime dependencies to any but the standard Windows DLLs.

Install mingw32. On a debian based system this should work:

apt-get install mingw32

On MacOS X, if you have MacPorts installed:

port install i386-mingw32-gcc

Install the rake-compiler:

gem install rake-compiler

Download and cross compile ruby 1.8 and 1.9 for win32:

rake-compiler cross-ruby VERSION=1.8.6-p398
rake-compiler cross-ruby VERSION=1.9.2-p180

Download and cross compile ribusb for win32:

rake cross native gem

or with custom versions:

rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.2 LIBUSB_VERSION=295c9d1

If everything works, there should be ribusb-VERSION-x86-mswin32.gem in the pkg directory.

Todo