Package usb.core

This package provides a USB Host Driver Interface, letting Java programs access USB Devices from USB Hosts.


Interface Summary
Bus A Universal Serial Bus connects a set of (USB) devices to a Host.
DeviceSPI This is not an Application Programming Interface.
Host Represents a host with one or more Universal Serial Busses.
USBListener Interface implemented by objects that want to monitor USB structure.

Class Summary
Configuration Provides access to a USB configuration supported by a device, and to the interfaces associated with that configuration.
ControlMessage This class supports control messaging with convenience methods for common calls, and encapsulates data for all control requests.
Descriptor This is a base class for entities with USB typed descriptors.
Device Provides access to a USB device.
DeviceDescriptor Provides access to a USB device descriptor.
Endpoint Provides access to a USB endpoint descriptor, structuring device data input or output in a given device configuration.
HostFactory Bootstrapping methods.
Hub Bundles access to a USB Hub descriptor and some hub operations.
Interface USB interfaces describe sets of endpoints, and are associated with a particular device configuration.
PortIdentifier This class provides "stable" string identifiers for USB devices, appropriate for use in operations and troubleshooting.
USBListenerAdapter Subclassable USBListener adapter, which ignores all calls.

Exception Summary
USBException USBException objects indicate USB errors.

Package usb.core Description

This package provides a USB Host Driver Interface, letting Java programs access USB Devices from USB Hosts. The initial implementation is of course for the GNU/Linux OS, but alternative operating systems (such as Win32) could also be supported through an appropriate server implementation. Some currently notable aspects of this API include:

Simple example programs are available, and a more substantial and useful application is available at JPhoto exposes USB "class driver" functionality as an API and tool, for "Digital Still Imaging" devices (cameras and more).

At this writing, two implementations of this interface are available. One uses the Linux 2.4 kernel; the other uses RMI. That should reduces the number of porting problems, as well as enabling application development on any platform that has sufficient Java support. The relevant Service Provider Interface (SPI) is not for applications use, and is subject to change.

Overview of Device Selection, Setup, and Use

To use a device, you first need to find it. In this API, the file system is not used to discover or identify devices. If you're using the Java API, you'll likely need to use one or more Endpoints to do your I/O; but you need to get them first!

  1. Bootstrap by getting a USB Host from the HostFactory.
  2. Then get a Device. Given a host, you have several choices here, all of which can give you access to a device in "operational" mode (no further setup is required):
  3. Look at the Device and its current Configuration to see if it's one that you want to deal with; there might be many similar devices to use.

Once you have such a device, interact directly with it using control messaging, or use Endpoints to transport data in various ways. To get an endpoint, claim an Interface, from its Configuration, and then you may use its endpoints. Get interfaces from the current configuration, and keep track of whether you've claimed them.

In the "interface claiming" process, other drivers may be able to claim the interface before your Java code. As yet there's no way to ask another module to release its claim on an interface, much less to do so in your favor. You can tell which driver claimed an interface. Note: you don't claim devices, only interfaces. Devices can be shared between drivers, with interfaces as the nonsharable unit.

Device Driver Modes

USB offers a lot of flexibility in how functionality is structured in different devices. At this writing, two of those mechanisms should be avoided in this API: multiple configurations, and alternate settings for interfaces. (Most devices don't use these, so temporarily avoiding that USB functionality should be no real hardship.)

Some interesting driver modes include:

You may find that a driver you have written for one type of device can work with another one. Often new models retain protocol compatibility with older ones. So, manage the lists of devices supported by your driver carefully, and try to make it so that end users can update the lists easily (use some text config file, perhaps XML).

USB Communication Types

Each USB device supports four types of communication. One of them can be used with every device, and is implicitly available with every interface. (Called the "default control pipe" or "endpoint zero".)

Other types of communication are grouped in "interfaces". Interfaces have at least one "endpoint", used to describe one of the other three types of communication:

It's likely that features using isochronous endpoints could leverage the real time extensions to Java, or be exposed through higher level APIs such as the Java Media Framework (JMF). Such support has not been the top priority for this package thus far.

Bulk Messaging

If you have a bulk input endpoint, it is associated with a which you can read and write as you need. If you have a bulk output endpoint, it provides you with a Only high speed devices use bulk messaging.

Note that there are no limits to the amount of data you can send or receive through a bulk endpoint, other than elapsed time it takes to send the data. Unlike TCP, there are packet boundaries; you can send packets of up to a per-endpoint maximum (such as 64 bytes, the biggest) and you can detect "short" reads (less than the maximum, including zero bytes) through the API.

USB 1.1 is nominally at 12 Megabit/second speed, and USB 2.0 is nominally at 480 Megabit/second, but your host controller or OS may limit your throughput. You can help the USB Host Controller Driver (HCD) get top throughput by using larger writes.

Interrupt Endpoints

You may send interrupt data to a device at any time using Endpoint.sendInterrupt, sending data to the device (maximum of 64 bytes, but check the specific endpoint size limit).

To receive interrupts from a device, dedicate a thread to issue Endpoint.recvInterrupt, and do at least partial processing of the interrupt data provided by device. (This threading model and API is highly subject to change. It's not debugged yet, for one thing; likely a user mode timer should just do the polling, to simplify the kernel interaction.)

Other API Notes

In most places the USB specification defines values to be unsigned eight or sixteen bit units, they are exposed in this API using (signed) int values. In places where values are defined as BCD encoded release numbers, they are exposed as strings.

USB numbers things starting at one. This means that this API uses one-based ranges for things such as port numbers and USB addresses.

In places where the USB specification defines values to be string index descriptor numbers, they are exposed here as strings. Device strings may of course be cached at various levels of the system. You can facilitate this by asking to use a default language; just pass zero where language codes are required. (The Linux implementation uses its system locale when choosing among a selection of languages; other native implementations might consider other factors.)

Associated source code is licenced under the LGPL.
This documentation was derived from that source code on 24-Jul-2002.