Ruby USB

Michael Hewner

rubyusb.technofetish.net

rubyusb ‘at’ hewner.com

What’s Cool About USB?

• Everywhere & well specified

• You can build your own (but not in ruby)

• Self-describing (especially HID devices)

USB Human Interface Devices

For the complete HID spec details check out

Device Class Definition for HID 1.11

http://www.usb.org/developers/devclass_docs/HID1_11.pdf

The Goal: Annotated Data

10000000011111011

1 0 0 nothing -5

Left mouse button

Distinct but logically grouped

Annotated with the string

“security stuff”

Measures in °CMinimum Value -36

Implicitly *10^3

A Partial Mouse HID DescriptorUSAGE_PAGE (Generic Desktop)

USAGE (Mouse)

COLLECTION (Application)

USAGE (Pointer)

COLLECTION (Physical)

USAGE_PAGE (Button)

USAGE_MINIMUM (Button 1)

USAGE_MAXIMUM (Button 3)

LOGICAL_MINIMUM (0)

LOGICAL_MAXIMUM (1)

REPORT_COUNT (3)

REPORT_SIZE (1)

INPUT (Data,Var,Abs)

REPORT_COUNT (1)

REPORT_SIZE (5)

INPUT (Cnst,Var,Abs)

…and more follows

05 01

09 02

A1 01

09 01

A1 00

05 09

19 01

29 03

15 00

25 01

95 03

75 01

81 02

95 01

75 05

81 03

1 0 0 XXXXX

3 1 Bit “Button” Fields

1 5 Bit Empty Space

Examples of RubyUSB

How Does it Work? Part 1 of 3: libUSB

LibUSB

Cross -PlatformC USB Library

C Structs&

Raw USB Descriptions

• Provides basic C access to all key USB fuctionality

• Supposedly cross-platform (OS X and BSD) but I’ve only tested on Linux

• The version in the Debian package repository doesn’t work – you need to get the latest from CVS

• You must disconnect devices from the kernel

How Does it Work? Part 2 of 3: HIDParser

HIDParser

C++ OO ParserFor HID Reports

ReportDescriptor

Objects

• Parses the HID into “Report Descriptor Objects” that describe a particular kind of communication

• Vast majority of HID constructs are supported

• Suite of unit tests

• Needs more testing on interesting HID devices

How Does it Work? Part 3 of 3: RubyUSB

RubyUSB

HandyDocumentedUSB Library

• Tries to implictly do the right thing

• Produces annotated Objects

• Needs more work for Output and some other stuff

The Big Picture

LibUSB

Cross-PlatformC USBLibrary

RawUSB

Descriptions

HIDParse

C++ OOParser

For HIDReports

ReportDescriptor

Objects

RubyUSB

HandyDocumentedUSB Library

Raw USB Reports

FancyReportObjects

YourRock’n

App

YourRock’nUSB

CDevice

AVRUSB

SimpleCommands

USB

AVRUSB: So Very Cool

So easy to build your own custom USB devices anybody can do it. As long as anybody has a soldering iron and an avr microcontroller programmer.

http://www.obdev.at/products/avrusb/hidkeys.html

Future Stuff

• Improved packaging building and installation

• Improved ruby objects

• More testing with a variety of usb devices

• Evdev for even easier but less cool fun