|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
|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.|
|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.|
|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.|
|USBException||USBException objects indicate USB errors.|
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.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.
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!
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.
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).
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.
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.
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
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.)
In most places the USB specification defines values to be
unsigned eight or sixteen bit units, they are exposed in this
API using (signed)
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.)
|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|