Package usb.core

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

See:
Description

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:

• Open Source. The libraries are under the "Lesser" GPL (LGPL), which means you can use them in proprietary products as well as in Free Software projects.
• Provides multi-threaded access to multiple physical USB Devices.
• Supports access to native or remote devices.
• Devices with multiple interface can support multiple drivers; each claims a different interface.
• Synchronous control and bulk messaging are well supported; interrupt messaging is in development.
• You can enumerate devices, and receive notifications when devices (or USB controllers) are added or removed.

Simple example programs are available, and a more substantial and useful application is available at jphoto.sourceforge.net. 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):
   • You can address devices at specific hub ports using the PortIdentifier class. Such port IDs won't change unless you recable.
   • To find out about devices which are currently connected, ask the host about its Busses.
   • Ask the Host to notify you about them as they connect, using a USBListener.
   • Walk up or down a USB tree from a device you have.
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:

• Some applications may may get substantial work done without claiming any interface. They may only be visible except to the extent that they use control messaging.
• Some drivers may provide standard USB Class functionality such as a hub, keyboard, or still imaging device.
• Other drivers may support some vendor-specific functionality. Device characteristics such as vendor number and product number help determine what drivers might talk to the device. These drivers are typically associated with a lists of devices they handle, which evolves over time.

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".)

• Control messaging (no endpoint type) is used in request/response messages to devices, and are used for device management. They can be used to access the device's identification information (identifying device type, manufacturer, product, perhaps a serial number, and more). Drivers share access to such "command style" communications to the device, and there may be extended periods where they must exclude access from other drivers.

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:

• Bulk endpoints are reliable. They have some reserved bandwidth, and also take up what's left at the end of a USB frame, after periodic transfers. They are used in storage units such as high-capacity removable disks, flash memory readers, in still imaging devices (scanners, cameras), in MP3 players to transfer data to or from the USB device, in network interfaces, and in other kinds of devices.
• Interrupt endpoints preallocate a certain amount of bandwidth for periodic (every N frames of USB traffic) use in communicating events from the device to the USB host (or sometimes vice versa, as in a force feedback joystick). Examples include mouse movements and key presses; at most 64 bytes of data can be transferred each interrupt. (Note that these are not real interrupts. The USB host polls each device for interrupt data, with a period chosen by the endpoint.)
• Isochronous endpoints (iso for short) are not currently supported in this package. These are used for media data such as sound (to speakers or a headset; from a microphone) and video (most of the USB "webcams" use this). These are periodic unreliable transfers, typically larger than interrupt data. Such media often have OS support that is automatically used by the Java Media APIs, and need little user mode support.

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 java.io.InputStream which you can read and write as you need. If you have a bulk output endpoint, it provides you with a java.io.OutputStream. 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.)