The Android Open Accessory Development Kit (ADK) is a reference implementation of an Android Open Accessory, based on the Arduino open source electronics prototyping platform. The accessory's hardware design files, code that implements the accessory's firmware, and the Android application that interacts with the accessory are provided as part of the kit to help hardware builders and software developers get started building their own accessories. The hardware design files and firmware code are contained in the ADK package download.
A limited number of kits were produced and distributed at the Google I/O 2011 developer conference. However, many hardware builders have reproduced and enhanced the original design and these boards are available for purchase. The following list of distributors are currently producing Android Open Accessory compatible development boards:
We expect more hardware distributers to create a variety of kits, so please stay tuned for further developments.
The main hardware and software components of the ADK include:
hardware/ directory.hardware/.arduino_libs/USB_Host_Shield directory.arduino_libs/AndroidAccessory/examples/demokit/demokit.pde,
defines the firmware that
runs on the ADK board and is written in C++. The sketch calls the Android accessory protocol
library to interact with the Android-powered device. It also sends data from the ADK board and
shield to the Android application and receives data from the Android application and outputs it
to the ADK board and shield.arduino_libs/AndroidAccessory directory. This library defines how to
enumerate the bus, find a connected Android-powered device that supports accessory mode, and
how to setup communication with the device.app/ directory.The following sections describe how to install the Arduino software on your computer, use the Arduino IDE to install the ADK board's firmware, and install and run the accompanying Android application for the ADK board. Before you begin, download the following items to set up your development environment:
To install the Arduino software:
Note: If you are on a Mac, install the FTDI USB Serial Driver that is included in the Arduino package, even though the installation instructions say otherwise.
app,
arduino_libs, and hardware directories.On Windows:
arduino_libs/AndroidAccessory and
arduino_libs/USB_Host_Shield directories (the complete directories,
not just the files within) to the <arduino_installation_root>/libraries/
directory.CapSense/ library directory and its contents to the
<arduino_installation_root>/libraries/ directory.On Mac:
Arduino
directory inside your user account's Documents directory, and within
that, a libraries directory.arduino_libs/AndroidAccessory and
arduino_libs/USB_Host_Shield directories (the
complete directories, not just the files within) to your
Documents/Arduino/libraries/ directory.CapSense/ library directory and its contents to the
Documents/Arduino/libraries/ directory.
On Linux (Ubuntu):
firmware/arduino_libs/AndroidAccessory and
firmware/arduino_libs/USB_Host_Shield directories (the complete directories,
not just the files within) to the <arduino_installation_root>/libraries/
directory.CapSense/ library directory and its contents to the
<arduino_installation_root>/libraries/ directory.sudo apt-get install avr-libc
from a shell prompt.You should now have three new directories in the Arduino libraries/ directory:
AndroidAccessory, USB_Host_Shield, and CapSense.
To install the firmware to the ADK board:
The DemoKit Android application runs on your Android-powered device and communicates with the ADK board. The ADK board receives commands such as lighting up the board's LEDs or sends data from the board such as joystick movement and temperature readings.
To install and run the application in Eclipse:
app directory, click Open to close that dialog and then
click Finish.Note: Even though the add-on is labeled as 2.3.3, the newest Google API add-on library for API level 10 adds USB Open Accessory API support for 2.3.4 devices.
You can now interact with the ADK board by moving the color LED or servo sliders (make sure the servos are connected) or by pressing the relay buttons in the application. On the ADK shield, you can press the buttons and move the joystick to see their outputs displayed in the application.
The ADK firmware consists of a few files that you should be looking at if you want to build
your own accessory. The files in the arduino_libs/AndroidAccessory
directory are the most important files and have the logic to detect and connect to
Android-powered devices that support accessory mode. Feel free to add debug statements (Arduino
Serial.println() statements) to the code located in the
<arduino_installation_root>/libraries/AndroidAccessory directory and
demokit.pde sketch and re-upload the sketch to the ADK board to
discover more about how the firmware works.
You can view the debug statements in the Arduino Serial Monitor by clicking Tools > Serial Monitor and setting the baud to 115200. The following sections about how accessories communicate with Android-powered devices describe much of what you should be doing in your own accessory.
If you have access to the ADK board and shield, the following sections describe the firmware code that you installed onto the ADK board. The firmware demonstrates a practical example of how to implement the Android Accessory protocol. Even if you do not have the ADK board and shield, reading through how the hardware detects and interacts with devices in accessory mode is still useful if you want to port the code over for your own accessories.
The important pieces of the firmware are the
arduino_libs/AndroidAccessory/examples/demokit/demokit/demokit.pde sketch, which is
the code that receives and sends data to the DemoKit application running on the Android-powered
device. The code to detect and set up communication with the Android-powered device is contained
in the arduino_libs/AndroidAccessory/AndroidAccessory.h and
arduino_libs/AndroidAccessory/AndroidAccessory.cpp files. This code
includes most of the logic that will help you implement your own accessory's firmware. It might
be useful to have all three of these files open in a text editor as you read through these next
sections.
The following sections describe the firmware code in the context of the algorithm described in Implementing the Android Accessory Protocol.
In the firmware code (demokit.pde), the loop() function runs
repeatedly and calls AndroidAccessory::isConnected() to check for any connected
devices. If there is a connected device, it continuously updates the input and output streams
going to and from the board and application. If nothing is connected, it continuously checks for
a device to be connected:
...
AndroidAccessory acc("Google, Inc.",
"DemoKit",
"DemoKit Arduino Board",
"1.0",
"http://www.android.com",
"0000000012345678");
...
void loop()
{
...
if (acc.isConnected()) {
//communicate with Android application
}
else{
//set the accessory to its default state
}
...
}
When a device is connected to the ADK board, it can already be in accessory mode, support
accessory mode and is not in that mode, or does not support accessory mode. The
AndroidAccessory::isConnected() method checks for these cases and responds
accordingly when the loop() function calls it. This function first checks to see if
the device that is connected hasn't already been handled. If not, it gets the connected device's
device descriptor to figure out if the device is already in accessory mode by calling
AndroidAccessory::isAccessoryDevice(). This method checks the vendor and product ID
of the device descriptor. A device in accessory mode has a vendor ID of 0x18D1 and a product ID
of 0x2D00 or 0x2D01. If the device is in accessory mode, then the ADK board can establish communication with the device. If not, the board attempts to start the device in accessory mode.
bool AndroidAccessory::isConnected(void)
{
USB_DEVICE_DESCRIPTOR *devDesc = (USB_DEVICE_DESCRIPTOR *) descBuff;
byte err;
max.Task();
usb.Task();
if (!connected &&
usb.getUsbTaskState() >= USB_STATE_CONFIGURING &&
usb.getUsbTaskState() != USB_STATE_RUNNING) {
Serial.print("\nDevice addressed... ");
Serial.print("Requesting device descriptor.");
err = usb.getDevDescr(1, 0, 0x12, (char *) devDesc);
if (err) {
Serial.print("\nDevice descriptor cannot be retrieved. Program Halted\n");
while(1);
}
if (isAccessoryDevice(devDesc)) {
Serial.print("found android accessory device\n");
connected = configureAndroid();
} else {
Serial.print("found possible device. switching to serial mode\n");
switchDevice(1);
}
} else if (usb.getUsbTaskState() == USB_DETACHED_SUBSTATE_WAIT_FOR_DEVICE) {
connected = false;
}
return connected;
}
If the device is not already in accessory mode, then the ADK board must determine whether or
not it supports it by sending control request 51 to check the version of the USB accessory
protocol that the device supports (see AndroidAccessory::getProtocol()). Protocol
version 1 is supported by Android 2.3.4 (API Level 10) and higher. Protocol version 2 is
supported by Android 4.1 (API Level 16) and higher. Versions greater than 2 may supported in
the future.
If the appropriate protocol version is returned, the board sends control request 52 (one
for each string with AndroidAcessory:sendString()) to send it's identifying
information, and tries to start the device in accessory mode with control request 53. The
AndroidAccessory::switchDevice() method takes care of this:
bool AndroidAccessory::switchDevice(byte addr)
{
int protocol = getProtocol(addr);
if (protocol >= 1) {
Serial.print("device supports protocol 1\n");
} else {
Serial.print("could not read device protocol version\n");
return false;
}
sendString(addr, ACCESSORY_STRING_MANUFACTURER, manufacturer);
sendString(addr, ACCESSORY_STRING_MODEL, model);
sendString(addr, ACCESSORY_STRING_DESCRIPTION, description);
sendString(addr, ACCESSORY_STRING_VERSION, version);
sendString(addr, ACCESSORY_STRING_URI, uri);
sendString(addr, ACCESSORY_STRING_SERIAL, serial);
usb.ctrlReq(addr, 0, USB_SETUP_HOST_TO_DEVICE | USB_SETUP_TYPE_VENDOR | USB_SETUP_RECIPIENT_DEVICE,
ACCESSORY_START, 0, 0, 0, 0, NULL);
return true;
}
If this method returns false, the board waits until a new device is connected. If it is
successful, the device displays itself on the USB bus as being in accessory mode when the ADK board
re-enumerates the bus. When the device is in accessory mode, the accessory then establishes communication with the device.
If a device is detected as being in accessory mode, the accessory must find the proper bulk
endpoints and set up communication with the device. When the ADK board detects an Android-powered
device in accessory mode, it calls the AndroidAccessory::configureAndroid()
function:
...
if (isAccessoryDevice(devDesc)) {
Serial.print("found android acessory device\n");
connected = configureAndroid();
}
...
which in turn calls the findEndpoints() function:
...
bool AndroidAccessory::configureAndroid(void)
{
byte err;
EP_RECORD inEp, outEp;
if (!findEndpoints(1, &inEp, &outEp))
return false;
...
The AndroidAccessory::findEndpoints() function queries the Android-powered
device's configuration descriptor and finds the bulk data endpoints in which to communicate with
the USB device. To do this, it first gets the device's first four bytes of the configuration
descriptor (only need descBuff[2] and descBuff[3]), which contains the information about the
total length of data returned by getting the descriptor. This data is used to determine whether
or not the descriptor can fit in the descriptor buffer. This descriptor also contains information
about all the interfaces and endpoint descriptors. If the descriptor is of appropriate size, the
method reads the entire configuration descriptor and fills the entire descriptor buffer with this
device's configuration descriptor. If for some reason the descriptor is no longer attainable, an
error is returned.
...
bool AndroidAccessory::findEndpoints(byte addr, EP_RECORD *inEp, EP_RECORD *outEp)
{
int len;
byte err;
uint8_t *p;
err = usb.getConfDescr(addr, 0, 4, 0, (char *)descBuff);
if (err) {
Serial.print("Can't get config descriptor length\n");
return false;
}
len = descBuff[2] | ((int)descBuff[3] << 8);
if (len > sizeof(descBuff)) {
Serial.print("config descriptor too large\n");
/* might want to truncate here */
return false;
}
err = usb.getConfDescr(addr, 0, len, 0, (char *)descBuff);
if (err) {
Serial.print("Can't get config descriptor\n");
return false;
}
...
Once the descriptor is in memory, a pointer is assigned to the first position of the buffer
and is used to index the buffer for reading. There are two endpoint pointers (input and output)
that are passed into AndroidAccessory::findEndpoints() and their addresses are set
to 0, because the code hasn't found any suitable bulk endpoints yet. A loop reads the buffer,
parsing each configuration, interface, or endpoint descriptor. For each descriptor, Position 0
always contains the size of the descriptor in bytes and position 1 always contains the descriptor
type. Using these two values, the loop skips any configuration and interface descriptors and
increments the buffer with the descLen variable to get to the next descriptor.
Note: An Android-powered device in accessory mode can
potentially have two interfaces, one for the default communication to the device and the other
for ADB communication. The default communication interface is always indexed first, so finding
the first input and output bulk endpoints will return the default communication endpoints, which
is what the demokit.pde sketch does. If you are writing your own firmware, the logic
to find the appropriate endpoints for your accessory might be different.
When it finds the first input and output endpoint descriptors, it sets the endpoint pointers to those addresses. If the findEndpoints() function finds both an input and output endpoint, it returns true. It ignores any other endpoints that it finds (the endpoints for the ADB interface, if present).
...
p = descBuff;
inEp->epAddr = 0;
outEp->epAddr = 0;
while (p < (descBuff + len)){
uint8_t descLen = p[0];
uint8_t descType = p[1];
USB_ENDPOINT_DESCRIPTOR *epDesc;
EP_RECORD *ep;
switch (descType) {
case USB_DESCRIPTOR_CONFIGURATION:
Serial.print("config desc\n");
break;
case USB_DESCRIPTOR_INTERFACE:
Serial.print("interface desc\n");
break;
case USB_DESCRIPTOR_ENDPOINT:
epDesc = (USB_ENDPOINT_DESCRIPTOR *)p;
if (!inEp->epAddr && (epDesc->bEndpointAddress & 0x80))
ep = inEp;
else if (!outEp->epAddr)
ep = outEp;
else
ep = NULL;
if (ep) {
ep->epAddr = epDesc->bEndpointAddress & 0x7f;
ep->Attr = epDesc->bmAttributes;
ep->MaxPktSize = epDesc->wMaxPacketSize;
ep->sndToggle = bmSNDTOG0;
ep->rcvToggle = bmRCVTOG0;
}
break;
default:
Serial.print("unkown desc type ");
Serial.println( descType, HEX);
break;
}
p += descLen;
}
if (!(inEp->epAddr && outEp->epAddr))
Serial.println("can't find accessory endpoints");
return inEp->epAddr && outEp->epAddr;
}
...
Back in the configureAndroid() function, if there were endpoints found, they are
appropriately set up for communication. The device's configuration is set to 1 and the state of
the device is set to "running", which signifies that the device is properly set up to communicate
with your USB accessory. Setting this status prevents the device from being re-detected and
re-configured in the AndroidAccessory::isConnected() function.
bool AndroidAccessory::configureAndroid(void)
{
byte err;
EP_RECORD inEp, outEp;
if (!findEndpoints(1, &inEp, &outEp))
return false;
memset(&epRecord, 0x0, sizeof(epRecord));
epRecord[inEp.epAddr] = inEp;
if (outEp.epAddr != inEp.epAddr)
epRecord[outEp.epAddr] = outEp;
in = inEp.epAddr;
out = outEp.epAddr;
Serial.print("inEp: ");
Serial.println(inEp.epAddr, HEX);
Serial.print("outEp: ");
Serial.println(outEp.epAddr, HEX);
epRecord[0] = *(usb.getDevTableEntry(0,0));
usb.setDevTableEntry(1, epRecord);
err = usb.setConf( 1, 0, 1 );
if (err) {
Serial.print("Can't set config to 1\n");
return false;
}
usb.setUsbTaskState( USB_STATE_RUNNING );
return true;
}
Lastly, methods to read and write to the appropriate endpoints are needed. The
demokit.pde sketch calls these methods depending on the data that is read from the
Android-powered device or sent by the ADK board. For instance, moving the joystick on the ADK
shield writes data that is read by the DemoKit application running on the Android-powered device.
Moving sliders on the DemoKit application is read by the demokit.pde sketch and
changes the state of the accessory, such as lighting up or changing the color of the LED
lights.
int AndroidAccessory::read(void *buff, int len, unsigned int nakLimit) {
return usb.newInTransfer(1, in, len, (char *)buff, nakLimit); }
int AndroidAccessory::write(void *buff, int len) {
usb.outTransfer(1, out, len, (char *)buff);
return len; }
See the demokit.pde sketch for information about how the ADK board
reads and writes data.