Accessory Development Kit 2012 Guide

The Android Accessory Development Kit (ADK) for 2012 is the latest reference implementation of an Android Open Accessory device, designed to help Android hardware accessory builders and software developers create accessories for Android. The ADK 2012 is based on the Arduino open source electronics prototyping platform, with some hardware and software extensions that allow it to communicate with Android devices.

A limited number of these kits were produced and distributed at the Google I/O 2012 developer conference. If you did not receive one of these kits, fear not! The specifications and design files for the hardware were also released for use by manufacturers and hobbyists. You should expect to see kits with similar features available for purchase, or you can build one yourself!

One of the important new features demonstrated by this ADK is the ability to play audio over a USB connection. Be sure to check out the reference implementation of a USB audio dock in this ADK if you are interested in making audio-related USB accessories for Android.

Components

The ADK 2012 is based on the Arduino open source electronics prototyping platform and is an open hardware design. The hardware design files and firmware source code are included with the ADK software download. The ADK contains two main physical hardware components:

  1. Main processing board containing the microprocessor, USB connections, power connector and input/output pins. This board can be removed and used separately from the rest of the hardware.
  2. Shield containing sensors, LEDs, input controls, audio amplifier and speaker output, contained in a custom, polygon box enclosure.

The main hardware features of the ADK are as follows:

  • An ARM 32-bit Cortex M3 micro-processor
  • Separate USB connections for an Android device and computer connection for programming and debugging
  • Sensors for light, color, proximity, temperature, humidity, barometric pressure, and acceleration
  • Micro SD Card slot
  • Bluetooth support

The ADK comes preloaded with an alarm clock firmware program that you can use immediately. A companion Android application, ADK 2012, is available on Google Play. The source code for both the Android application and the ADK firmware (an Arduino sketch) can be downloaded from this page.

The ADK 2012 also comes with additional parts to help you develop accessories with it, including:

  • AC power adapter
  • USB A to Micro USB B connector cable
  • Micro USB B to Micro USB AB connector (small, rectangular plug)
  • Micro SD Card, preinstalled in the ADK SD Card socket

Using the Alarm Clock

An alarm clock program comes preloaded on the ADK. This firmware program allows you to use the ADK as an alarm clock.

To use the ADK as an alarm clock:

  1. Open up the ADK by gently squeezing the two widest faces of the enclosure.
  2. Attach the provided AC power adapter (round connector) to the main ADK board, or attach a USB cable to the port marked Computer and a USB port on your computer.
  3. Place and hold your fingertip over the clock symbol on the control face.

    Note: You may need to hold your finger in place for 1-2 seconds.

  4. Use the plus (+) and minus (-) symbols inside the clock digits to set the correct time.
  5. Place your fingertip over the alarm clock symbol to activate alarm setting.
  6. Use the plus (+) and minus (-) symbols inside the clock digits to set the alarm time.
  7. Use the plus (+) and minus (-) symbols inside the last two clock digits to turn the alarm on (on) or off (oF).
  8. To set the alarm tone, place and hold your fingertip over the alarm clock symbol, then tap the slider control on top of the enclosure.

To use the ADK 2012 companion application for the alarm clock:

  1. Load the companion application on your Android device running Android 3.1 (API Level 12) or higher:
    • Using an NFC-enabled Android device, unlock and hold the device against the left side of the ADK enclosure. Follow the prompts to install the app.
      - or -
    • Start Google Play on your device, search for the ADK 2012 application and install it. If you cannot find the app, your device is not compatible. Try installing on another device.
  2. Connect your Android device to the ADK using one of the following methods:
    • To connect using Bluetooth:
      1. Plug the AC power adapter into the ADK.
      2. On your Android device, turn Bluetooth On (Settings > Bluetooth).
      3. In the Settings page, press the Bluetooth option to view paired devices.
      4. Select Search for Devices to locate the ADK 2012 accessory and follow the on screen instructions to connect.
      5. After pairing is complete, start the ADK 2012 app on your Android device.
      6. On the start screen, select the Use Bluetooth button.
      7. In the list of paired devices, select the ADK 2012 device.
      8. The ADK 2012 app should switch to the menu screen and you can start interacting with the ADK accessory.
    • To connect using USB:
      1. Plug the AC power adapter into the ADK.
      2. Connect the Micro USB AB connector (small, rectangular plug) to the port labeled Phone on the ADK board.
      3. Unlock your Android device and connect the Micro USB B connector to your device.

        Note: Your device must support Android USB accessory mode. Devices that support this mode include Google Nexus devices.

      4. On the Android device, you should see a prompt to connect to the ADK DemoKit 2012, select OK.
      5. The ADK 2012 app should start automatically and you can start interacting with the ADK.

Note: When using the ADK with a USB connection to an Android device, make sure the AC power adapter is plugged in. A USB connection to a computer does not provide sufficient voltage to power both the ADK and a USB connection to a device.

Playing Audio

The ADK 2012 comes with audio output capabilities, including an amplifier and speaker. You can use it to play audio from your Android device using either a Bluetooth or USB connection.

To play audio over Bluetooth:

  1. Follow the instructions in the previous section to connect your Android device to the ADK over Bluetooth.
  2. On your Android device, navigate to the Settings > Bluetooth page to view the list of paired devices, and make sure the ADK is connected.
  3. Select the settings icon next to the ADK 2012 item.
  4. Make sure the Media Audio option is enabled.
  5. Navigate to an application that plays music or other audio.
  6. Play a song or sound and listen to it on the ADK speaker!

To play audio over USB, you must use a device running Android 4.1 (API Level 16) or higher:

  1. Plug the AC power adapter into the ADK.
  2. Connect the Micro USB AB connector (small, rectangular plug) to the Phone port on the ADK board.
  3. Unlock your Android device and connect the Micro USB B connector to your device.

    Note: Your device must support Android USB accessory mode. Devices that support this mode include Google Nexus devices.

  4. On the Android device, you should see a prompt to connect to the ADK DemoKit 2012, select Cancel and allow the ADK to connect as a media device only.
  5. Navigate to an application that plays music or other audio.
  6. Play a song or sound and listen to it on the ADK speaker!

Note: When using the ADK with a USB connection to an Android device, make sure the AC power adapter is plugged in. A USB connection to a computer does not provide sufficient voltage to power both the ADK and a USB connection to a device.

Developing Accessories with ADK 2012

The ADK 2012 is a hardware platform and a set of software libraries for prototyping Android accessories. This section discusses how to set up a development environment for programming the ADK to make it do what you want and to test software for building your own Android accessories.

Downloading the ADK Source

The support software and hardware specifications for the ADK 2012 are available from the Android source repository. Follow the instructions below to obtain the source material for the ADK.

To download the ADK 2012 software, source code and hardware design specifications.

  1. Download and install Git for your development system.
  2. Download and setup the repo tool, as described on the Android open source project site.
  3. In a terminal window, create a new directory for the downloaded source files, initialize and synchronize a local repository: 
    $> mkdir android-accessories
$> cd android-accessories
$> repo init -u https://android.googlesource.com/accessories/manifest
$> repo sync

After successfully completing this process, you should have the source code and tools for working with the ADK 2012:

  • adk2012/board - Source code and hardware design files for the ADK 2012
  • adk2012/app - Source code for the ADK 2012 Android companion application
  • external/ide - Source code for the ADK 2012 Integrated Development Environment (IDE)
  • external/toolchain - The toolchain used by the ADK 2012 IDE

Setting Up the Development Environment

The ADK 2012 comes with an integrated development environment (IDE) that you use to develop software and program the ADK 2012 accessory. The following instructions explain how to setup and run the ADK 2012 IDE.

To set up and run the ADK 2012 IDE:

  1. Download and install the Java Development Kit 6 or higher from java.oracle.com.
  2. Download the ADK 2012 IDE for your development platform:
  3. Unpack the downloaded archive.
  4. Run the application by navigating to the unpacked ADK2012_IDE/ folder and execute the arduino file.

After you have successfully installed and run the ADK 2012 IDE, you must configure it to use the ADK 2012 library.

To configure the ADK 2012 IDE for use with the ADK libraries:

  1. Start the ADK 2012 IDE and choose File > Preferences.
  2. In the Preferences dialog, make a note of the Sketchbook location directory.
  3. Copy the <adk-source-download>/adk2012/board/library/ADK2 directory and its contents into your sketchbook/libraries/ directory, so that you create a sketchbook/libraries/ADK2 directory.
  4. Stop and restart the ADK 2012 IDE.
  5. In the IDE, choose File > Examples > ADK2 and then choose one of the example sketches:
    • clock - The sketch that is preloaded onto the ADK 2012.
    • BluetoothScan - An example sketch demonstrating code that connects an accessory to an Android device over Bluetooth.
    • usbaccessory - An example sketch demonstrating code that connects an accessory to an Android device through a USB cable.
  6. Connect a Micro USB cable from the Computer port on the ADK board to your development computer.
  7. In the ADK 2012 IDE, establish a serial port connection with the ADK by selecting Tools > Serial Port and selecting the serial port for the ADK.
  8. In the ADK 2012 IDE, choose the ADK by selectingTools > Board > Google ADK2.
  9. Modify an example sketch or create your own.
  10. Upload the sketch to the ADK by choosing File > Upload. When the ADK 2012 IDE reports Done uploading, the sketch is uploaded and the ADK is ready to communicate with your Android device.

Using the ADK Alternative Build System

An alternative, make file-based build and upload system is also available for the ADK 2012. This system is command line based and intended for production environments where using an IDE environment to load software onto accessory hardware may be inconvenient or undesirable.

To setup the environment:

  1. Download the ADK 2012 source code files.
  2. In a terminal window, navigate to <adk-source-download>/adk2012/board/MakefileBasedBuild.
  3. Execute the following command and follow the instructions: 
    $> ./setup

To build a program for your accessory:

  1. Place your accessory code in the MakefileBasedBuild/app directory, including all required library files. See the app/main.c file for an example of the program format.
  2. Execute the following command and follow the instructions: 
    $> ./build

To load the program on your accessory hardware:

  1. Run the build process above and make sure your program compiled successfully.
  2. Attach the accessory via USB cable to your development computer.
  3. Check which port the accessory is attached to and modify the UART variable in the flash script to the correct port address. On linux machines, the port address is typically /dev/ttyUSB0.
  4. Execute the following command to load the program on the accessory: 
    $> ./flash

How the ADK Connects with Android Devices

The essential feature of any Android accessory is its ability to connect and communicate with an Android device. Creating a fast and reliable connection between your accessory and Android devices is the first order of business when building software for an accessory. This section describes the connection and communication essentials used in the ADK 2012 so that you can apply them to developing your own Android accessories.

ADK Connection over Bluetooth

The ADK 2012 app and hardware accessory use a Bluetooth Serial Port Profile (SPP) connection to communicate. This connection allows two way communication between the ADK accessory and Android devices.

Note: The implementation of the ADK hardware allows the use of other profiles and multiple connections. However, the basic communication between the ADK 2012 accessory and the Android application uses SPP.

Accessory Bluetooth Code

In order to enable Bluetooth communications, the clock.ino sketch for the ADK 2012 accessory calls a btStart() method during the setup() method to enable radio frequency communications and start listening for Bluetooth connections:

ADK L;
void setup() {
 L.adkInit();
 L.btStart();
}
...
void btStart(){
    uint8_t i, dlci;
    int f;

    L.btEnable(adkBtConnectionRequest, adkBtLinkKeyRequest, adkBtLinkKeyCreated,
               adkBtPinRequest, NULL);

    dlci = L.btRfcommReserveDlci(RFCOMM_DLCI_NEED_EVEN);

    if(!dlci) dbgPrintf("BTADK: failed to allocate DLCI\n");
    else{

        //change descriptor to be valid...
        for(i = 0, f = -1; i < sizeof(sdpDescrADK); i++){

            if(sdpDescrADK[i] == MAGIX){
                if(f == -1) f = i;
                else break;
            }
        }

        if(i != sizeof(sdpDescrADK) || f == -1){

            dbgPrintf("BTADK: failed to find a single marker in descriptor\n");
            L.btRfcommReleaseDlci(dlci);
            return;
        }

        sdpDescrADK[f] = dlci >> 1;

        dbgPrintf("BTADK has DLCI %u\n", dlci);

        L.btRfcommRegisterPort(dlci, btAdkPortOpen, btAdkPortClose, btAdkPortRx);
        L.btSdpServiceDescriptorAdd(sdpDescrADK, sizeof(sdpDescrADK));
    }
}

Notice that the sdpDescrADK object contains a Universally Unique Identifier (UUID) in the variable BT_ADK_UUID. This identifier must match the device UUID provided in the BluetoothSocket connection request in the Android application code.

Once Bluetooth is enabled with the code shown above, the accessory listens for connection requests. The ADK library handles listening and connection details, so the accessory calls ADK::adkEventProcess() once during each loop execution:

void loop(void)
{
  ...
  L.adkEventProcess(); //let the adk framework do its thing
  ...
}

If a Bluetooth connection has been established, any commands are routed to the btAdkPortRx() callback method (which was registered with the ADK library as part of the btStart() method) and processed accordingly. The ADK accessory sends messages back through the Bluetooth connection using the ADK::btRfcommPortTx() method. For more details, review the implementations of these methods in the clock.ino sketch.

Android App Bluetooth Code

In the ADK 2012 Android app, the code for handling Bluetooth connections is encapsulated in in a BTConnection class. In this class, the application requests access to the Bluetooth adapter and negotiates a connection with the ADK 2012 accessory. Here is a summary of the relevant code:

mAdapter = BluetoothAdapter.getDefaultAdapter();
BluetoothDevice device = mAdapter.getRemoteDevice(address);
mSocket = device.createInsecureRfcommSocketToServiceRecord(ADK_UUID);
mSocket.connect();

Note the ADK_UUID parameter in the second line. This identifier must match the identifier output by the accessory (the BT_ADK_UUID variable mentioned earlier), otherwise the protocol negotiation fails and the BluetoothSocket is not created. Once a connection is established, you obtain InputStream and OutputStream objects from the socket to communicate with the accessory:

mInStream = mSocket.getInputStream();
mOutStream = mSocket.getOutputStream();

Review the BTConnection.java file provided in the ADK 2012 software download for more implementation details.

ADK Connection over USB

The ADK 2012 app and hardware accessory can also use a USB connection to communicate, similar to the original ADK.

Accessory USB Code

The ADK library takes care of most of the implementation details for a USB connection, the accessory code must make a few calls to initialize USB connectivity, including setting the accessory identification strings:

ADK L;
void setup() {
  L.adkInit();
  L.usbSetAccessoryStringVendor(...);
  L.usbSetAccessoryStringName(...);
  L.usbSetAccessoryStringLongname(...);
  L.usbSetAccessoryStringVersion(...);
  L.usbSetAccessoryStringUrl(...);
  L.usbSetAccessoryStringSerial(...);

  L.usbStart();
}

Note: The identification strings must match the USB accessory filter settings specified in the connecting Android application,otherwise the application cannot connect with the accessory.

Once USB is enabled with code shown above, the accessory listens for connection requests. The ADK library handles listening and connection details, so the accessory calls ADK::adkEventProcess() once during each loop execution:

void loop(void)
{
  ...
  L.adkEventProcess(); //let the adk framework do its thing
  ...
}

The accessory must then check for a live USB connection to process commands and send messages. Here is a summary of the relevant code:

void loop() {
  if (L.accessoryConnected()) {
    int recvLen = L.accessoryReceive(msg, sizeof(msg));
    if (recvLen > 0) {
      ... // process message
    }

    L.accessorySend(outmsg, outmsgLen);
  }
  L.adkEventProcess();
}

For more details, review the implementations of these methods in the clock.ino sketch.

Android App USB Code

In the ADK 2012 Android app, the code for handling USB connections is encapsulated in a UsbConnection class. This class sets up a BroadcastReceiver to listen for USB events and then attempts to connect when a matching connection event is received. Here is a summary of the relevant code:

import com.android.future.usb.UsbAccessory;
import com.android.future.usb.UsbManager;

mUSBManager = UsbManager.getInstance(this);
UsbAccessory acc = mUSBManager.getAccessoryList()[0];

if (!mUSBManager.hasPermission(acc)) return;

The ADK 2012 app uses the support library to implement the USB accessory connections, in order to support devices running Android 2.3.4 (API Level 10). If you only need to support Android 3.1 (API Level 12) and higher devices, you can replace the first 4 lines the following code:

import android.hardware.usb.UsbAccessory
import android.hardware.usb.UsbManager

mUSBManager = (UsbManager) getSystemService(Context.USB_SERVICE);
UsbAccessory acc = (UsbAccessory)
                   intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);

Note that the app only receives events when the USB accessory identification information matches the information in the res/xml/usb_accessory_filter.xml file, referenced by the application’s manifest statement:

<meta-data
    android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED"
    android:resource="@xml/usb_accessory_filter" />

Connections from other USB devices are not received by the ADK 2012 accessory.

Once the connection is established, the app can communicate with the accessory through file input and output streams, as shown in the following example code:

ParcelFileDescriptor mFD = mUSBManager.openAccessory(acc);
if (mFD != null) {
  FileDescripter fd = mFD.getFileDescriptor();
  mIS = new FileInputStream(fd);  // use this to receive messages
  mOS = new FileOutputStream(fd); // use this to send commands
}

Review the UsbConnection.java file provided in the ADK 2012 source code for more implementation details.

USB Audio Dock Implementation

One of the important new features introduced with the ADK 2012 is the ability to play audio over a USB connection. This innovation was introduced as an update to Android Open Accessory (AOA) protocol 2.0 and is available on devices running Android 4.1 (API Level 16) and higher.

The ADK 2012 provides a reference implementation of this functionality for accessory developers. No software application is required to be installed on the connected Android device, accessory developers only need to support AOA v2. This implementation demonstrates audio output of 16bit, 44.1kHz stereo PCM source data compressed into a single channel due to the audio hardware available on the accessory.

Using the audio output features provided by the ADK library requires only a few function calls. The first few calls are in the accessory setup() routine, which prepare the accessory for USB connections and audio output, as summarized in the code example below:

ADK L;
void setup() {
  L.audioInit();
  L.usbh_init()
  L.usbStart();
}

For more information about the ADK::audioInit() function, see the libraries/ADK/Audio.c library file. For more information about the ADK::usbh_init() function, see the libraries/ADK/Usbh.c library file.

After completing this setup, the loop() function calls ADK::adkEventProcess() to handle audio output and other ADK functions:

void loop(void)
{
  ...
  L.adkEventProcess(); //let the adk framework do its thing
  ...
}

This call executes task queuing for the ADK and as part of the execution process, the task queue executes usbh_work() in libraries/ADK/Usbh.c, which handles audio output requests. Review the implementation of this function for details. For additional implementation details on audio output, see the libraries/ADK/accessory.c library file.