Libusb is a C library that provides generic access to USB devices. It is intended to be used by developers to facilitate the production of applications that communicate with USB hardware. It is portable: Using a single cross-platform API, it provides access to USB devices on Linux, OS X, Windows, Android, OpenBSD, etc. Libusb is a C library that provides generic access to USB devices. It is intended to be used by developers to facilitate the production of applications that communicate with USB hardware. It is portable: Using a single cross-platform API, it provides access to USB devices on Linux, macOS, Windows, etc. It is user-mode: No special privilege. TWAIN SANE Interface for MacOS X. This is a TWAIN datasource for MacOS X that aquires images using the SANE backend libraries. The SANE backend libraries provide access to a large range of scanners connected through SCSI or USB. Libusb is available for Windows 7 and up (but not Windows 10), as well as macOS 10.12 and up. There are also versions available for Linux distributions. Is there a better alternative? Libusb is extremely portable, unlike its main alternative libusbk, which is only available for Windows computers.

  1. Macos Libusb.h
  2. Macos Libusb_claim_interface
  3. Libusb Macos Catalina

<!-- -- coding: utf-8 -- -->

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.


Macos Libusb.h

{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 beused to communicate with the connected USB deviceby {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 whichconfiguration 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 groupperforming 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 andmaximum packet size.

See the documentation for a full API description.


  • Linux, MacOS or Windows system with Ruby MRI 1.9/2.x, JRuby or recent version of Rubinius
  • Optionally: libusb C-library version 1.0.8 or any newer version.The system libusb library can be installed like so:

    • Debian or Ubuntu:
    • MacOS: install with homebrew:

    or macports:

    • Windows: libusb.gem already comes with a precompiled libusb.dll, but you need to install a device driver (see below)


While gem install the system is checked for a usable libusb library installation.If none could be found, a bundled libusb version is built and used, instead.

Latest code can be used in this way:


In order to implement a driver for a USB device, it's essential to have a look at the packets that are send to and received back from the USB device. Wireshark has builtin capabilities to sniff USB traffic. On Linux you possibly need to load the usbmon kernel module before start:

Macos Libusb_claim_interface

On Windows it's possible to sniff USB, if the USB kernel driver was installed by the Wireshark setup.

[Wireshark](wireshark-usb-sniffer.png?raw=true 'Wireshark sniffing USB packets')

Device hotplug support

Support for device hotplugging can be used, if LIBUSB.has_capability?(:CAP_HAS_HOTPLUG) returns true.This requires libusb-1.0.16 or newer on Linux or MacOS. 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} todetect any events to handle.

Usage on Windows

Libusb Macos

In contrast to Linux, any access to an USB device by LIBUSB on Windows requires a proper driverinstalled in the system. Fortunately creating such a driver is quite easy withZadig. Select the interesting USB device,choose WinUSB driver and press 'Install Driver'. That's it. You may take the generated output directorywith it's INI-file and use it for driver installations on other 32 or 64 bit Windowssystems.

Cross compiling for Windows

Libusb-gem can be cross built for Windows and Linux operating systems, using the rake-compiler-dock .Just run:

If everything works, there are several platform specific gem files (like libusb-VERSION-x64-mingw32.gem) in the pkgdirectory.

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.


  • Project's home page:
  • API documentation:
  • Mailinglist:
  • Overall introduction to USB:


  • stabilize EventMachine interface

When my son got himself Buzz Quiz, it struck me that there was no way to create your own quiz.So that got me started on reading up on how I could use the Buzz Quiz controllers on my Mac.

Selecting a toolkit

All effort has gone to libusb. But i did not want to into C code again. This links sums up a list of related wrappers or bindings:

I've considered the following options:

  • libusbjava: java has javax.usb but nothing that works on Mac
  • jusb:
  • libusb: sorry but i did not want code C code again
  • apple I/O Kit: apple includes a toolkit for USB programming, but would make it more mac specific
  • python-usb: not so much for me, as I don't do much pythoin programming
  • ruby-usb: hey I like ruby, why not

Installing libUSB (using macports)

ruby-usb requires you to have libusb . This library has a current version of 1.0.3 , this version version not compatible with ruby-usb. Luckily macports still has the older versions available for us. The version we need is the libusb-compat . Note: that my macports where installed in /opt/local so you might need to change some paths.

Lets list the versions available by macports:

We install the libusb-compat version:

Getting ruby-usb

The most recent success with lib-usb I found was described on

Libusb Macos Catalina

downloaded the latest cvs snapshot from . This will install version 0.2-something. The rubygems is only the version 0.1 version. There were some bug fixes since then.

Solving the library and include paths

replace the extconf.rb as follows where /opt/local is the place where you installed libusb

Specify the correct build architecture

For some reason, the make mkmf decides to put both the ppc and the i386 as flags to the architecture. So we have to specify the i386 using the ARCHFLAGS variable:

Not specifying the architecture would result in a warning at compile time (file is not of required architecture)

At runtime this would result in an error

Even though we have the usb_init compiled in the dynamic library

The reason we only get an error at runtime is that ruby-usb dynamically load the library. In our case it will load the libusb.dylib which points to version 0.1.4 of the libusb.

Also check if old libraries exist in other places

Build the library with make

Patching the usb.rb

The last thing to get it working is to have usb.rb catch the error Errno::ERANGE . We do this by adding it to the corresponding line in usb.rb

If we don't patch it , it would result in the following error:

Finally installing ruby-usb

Example program

More on Ruby USB

  • Video explaining the use of ruby-usb :
  • Powerpoint on ruby-usb

Other projects using ruby-usb


  • Betabrite integration with ruby-usb :
  • RubyUSB - Buffaloblog:


USB Missile Launcher:

  • How To Control USB Missile Launcher on Linux :

  • AC Power Control through USB :