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.
- -After the application is installed, you can 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.
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.
- -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:
- -The main hardware features of the ADK are as follows:
- -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:
- -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:
- -Note: You may need to hold your finger in place for 1-2 -seconds.
-To use the ADK 2012 companion application for the alarm clock:
- -Note: Your device must support Android USB accessory -mode. Devices that support this mode include Google Nexus devices.
-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.
- - -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:
- -To play audio over USB, you must use a device running Android 4.1 (API Level 16) or higher:
- -Note: Your device must support Android USB accessory -mode. Devices that support this mode include Google Nexus devices.
-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.
- - -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.
- -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.
- -Note: Developers using Windows must use a Linux compatibility -package, such as cygwin, to install and run {@code repo}. -Within your compatibility environment, you must install {@code curl}, {@code git} and {@code -python} to be able to download and use the {@code repo} tool.
--$> 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:
- -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:
- -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:
- -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:
-$> ./setup-
To build a program for your accessory:
-$> ./build-
To load the program on your accessory hardware:
-$> ./flash
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.
- -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.
- -In order to enable Bluetooth communications, the {@code clock.ino} sketch for the ADK 2012 -accessory calls a {@code btStart()} method during the {@code 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 {@code sdpDescrADK} object contains a Universally Unique Identifier (UUID) in the -variable {@code BT_ADK_UUID}. This identifier must match the device UUID provided in the -{@link android.bluetooth.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 -{@code 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 -{@code btAdkPortRx()} callback method (which was registered with the ADK library as part of the -{@code btStart()} method) and processed accordingly. The ADK accessory sends messages back through -the Bluetooth connection using the {@code ADK::btRfcommPortTx()} method. -For more details, review the implementations of these methods in the {@code clock.ino} sketch.
- -In the ADK 2012 Android app, the code for handling Bluetooth connections is encapsulated in in a -{@code 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 {@code ADK_UUID} parameter in the second line. This identifier must match the identifier -output by the accessory (the {@code BT_ADK_UUID} variable mentioned earlier), otherwise the protocol -negotiation fails and the {@link android.bluetooth.BluetoothSocket} is not created. Once a -connection is established, you obtain {@link java.io.InputStream} and {@link java.io.OutputStream} -objects from the socket to communicate with the accessory:
- --mInStream = mSocket.getInputStream(); -mOutStream = mSocket.getOutputStream(); -- -
Review the {@code BTConnection.java} file provided in the ADK 2012 software download for more -implementation details.
- -The ADK 2012 app and hardware accessory can also use a USB connection to communicate, similar to -the original ADK.
- -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 {@code -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 {@code clock.ino} -sketch.
- -In the ADK 2012 Android app, the code for handling USB connections is encapsulated in a -{@code UsbConnection} class. This class sets up a {@link android.content.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 {@code 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 {@code UsbConnection.java} file provided in the ADK 2012 source code for more -implementation details.
- -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 {@code 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 {@code ADK::audioInit()} function, see the {@code -libraries/ADK/Audio.c} library file. For more information about the {@code ADK::usbh_init()} -function, see the {@code libraries/ADK/Usbh.c} library file.
- -After completing this setup, the {@code loop()} function calls {@code 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 {@code usbh_work()} in {@code 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 {@code libraries/ADK/accessory.c} library file.
diff --git a/docs/html/adk/index.jd b/docs/html/adk/index.jd deleted file mode 100644 index e08748fc3b42f..0000000000000 --- a/docs/html/adk/index.jd +++ /dev/null @@ -1,30 +0,0 @@ -page.title=Accessory Development Kit -page.tags=adk -@jd:body - -The Accessory Development Kit (ADK) is a reference implementation for hardware manufacturers and -hobbyists to use as a starting point for building accessories for Android. Each ADK release is -provided with source code and hardware specifications to make the process of developing your own -accessories easier. Creating new and alternative hardware based on the ADK is encouraged!
- -Android accessories can be audio docking stations, exercise machines, personal medical testing -devices, weather stations, or any other external hardware device that adds to the functionality of -Android.
- -Accessories use the Android Open Accessory (AOA) protocol to communicate with Android -devices, over a USB cable or through a Bluetooth connection. If you are building an accessory that -uses USB, make sure you understand how to implement the AOA protocol to establish communication -between your accessory hardware and Android. For more information, see the -Android Open Acessory protocol. -
- -The following sections provide more information about the Android Accessory Development Kits, how -to use them, and how to get started building your own accessories for Android.
- -