Android’s USB port has in the past been curiously inaccessible to programmers. Last week at Google I/O we announced the Android Open Accessory APIs for Android. These APIs allow USB accessories to connect to Android devices running Android 3.1 or Android 2.3.4 without special licensing or fees. The new “accessory mode” does not require the Android device to support USB Host mode. This post will concentrate on accessory mode, but we also announced USB Host mode APIs for devices with hardware capable of supporting it.
To understand why having a USB port is not sufficient to support accessories let’s quickly look at how USB works. USB is an asymmetric protocol in that one participant acts as a USB Host and all other participants are USB Devices. In the PC world, a laptop or desktop acts as Host and your printer, mouse, webcam, etc., is the USB Device. The USB Host has two important tasks. The first is to be the bus master and control which device sends data at what times. The second key task is to provide power, since USB is a powered bus.
The problem with supporting accessories on Android in the traditional way is that relatively few devices support Host mode. Android’s answer is to turn the normal USB relationship on its head. In accessory mode the Android phone or tablet acts as the USB Device and the accessory acts as the USB Host. This means that the accessory is the bus master and provides power.
Establishing the Connection
Building an Open Accessory is simple as long as you include a USB host and can provide power to the Android device. The accessory needs to implement a simple handshake to establish a bi-directional connection with an app running on the Android device.
The handshake starts when the accessory detects that a device has been connected to it. The Android device will identify itself with the VID/PID that is appropriate based on the manufacturer and model of the device. The accessory then sends a control transaction to the Android device asking if it supports accessory mode.
Once the accessory confirms the Android device supports accessory mode, it sends a series of strings to the Android device using control transactions. These strings allow the Android device to identify compatible applications as well as provide a URL that Android will use if a suitable app is not found. Next the accessory sends a control transaction to the Android device telling it to enter accessory mode.
The Android device then drops off the bus and reappears with a new VID/PID combination. The new VID/PID corresponds to a device in accessory mode, which is Google’s VID 0x18D1, and PID 0x2D01 or 0x2D00. Once an appropriate application is started on the Android side, the accessory can now communicate with it using the first Bulk IN and Bulk OUT endpoints.
The protocol is easy to implement on your accessory. If you’re using the ADK or other USB Host Shield compatible Arduino you can use the AndroidAccessory library to implement the protocol. The ADK is one easy way to get started with accessory mode, but any accessory that has the required hardware and speaks the protocol described here and laid out in detail in the documentation can function as an Android Open Accessory.
Communicating with the Accessory
After the low-level USB connection is negotiated between the Android device and the accessory, control is handed over to an Android application. Any Android application can register to handle communication with any USB accessory. Here is how that would be declared in your AndroidManifest.xml:
<activity android:name=".UsbAccessoryActivity" android:label="@string/app_name"> <intent-filter> <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" /> </intent-filter>
<meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" android:resource="@xml/accessory_filter" /> </activity>
Here's how you define the accessories the Activity supports:
<resources> <usb-accessory manufacturer="Acme, Inc" model="Whiz Banger" version="7.0" /> </resources>
The Android system signals that an accessory is available by issuing an Intent and then the user is presented with a dialog asking what application should be opened. The accessory-mode protocol allows the accessory to specify a URL to present to the user if no application is found which knows how communicate with it. This URL could point to an application in Android Market designed for use with the accessory.
After the application opens it uses the Android Open Accessory APIs in the SDK to communicate with the accessory. This allows the opening of a single FileInputStream and single FileOutputStream to send and receive arbitrary data. The protocol that the application and accessory use is then up to them to define.
Here’s some basic example code you could use to open streams connected to the accessory:
public class UsbAccessoryActivity extends Activity { private FileInputStream mInput; private FileOutputStream mOutput;
private void openAccessory() { UsbManager manager = UsbManager.getInstance(this); UsbAccessory accessory = UsbManager.getAccessory(getIntent());
ParcelFileDescriptor fd = manager.openAccessory(accessory);
if (fd != null) { mInput = new FileInputStream(fd); mOutput = new FileOutputStream(fd); } else { // Oh noes, the accessory didn’t open! } } }
Future Directions
There are a few ideas we have for the future. One issue we would like to address is the “power problem”. It’s a bit odd for something like a pedometer to provide power to your Nexus S while it’s downloading today’s walking data. We’re investigating ways that we could have the USB Host provide just the bus mastering capabilities, but not power. Storing and listening to music on a phone seems like a popular thing to do so naturally we’d like to support audio over USB. Finally, figuring out a way for phones to support common input devices would allow for users to be more productive. All of these features are exciting and we hope will be supported by a future version of Android.
Accessory mode opens up Android to a world of new possibilities filled with lots of new friends to talk to. We can’t wait to see what people come up with. The docs and samples are online; have at it!
