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 = 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.
- 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://github.com/larskanis/libusb.git
$ bundle
$ rake install_gem
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.
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.
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.
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.
- 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
- stabilize EventMachine interface