| page.title=Accessory Development Kit 2012 Guide |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#components">Components</a></li> |
| <li><a href="#clock">Using the Alarm Clock</a></li> |
| <li><a href="#play-audio">Playing Audio</a></li> |
| <li><a href="#dev">Developing Accessories with ADK 2012</a> |
| <ol> |
| <li><a href="#src-download">Downloading the ADK Source</a></li> |
| <li><a href="#dev-setup">Setting Up the Development Environment</a></li> |
| <li><a href="#alt-build">Using the ADK Alternative Build System</a></li> |
| </ol> |
| </li> |
| <li><a href="#adk-conn">How the ADK Connects with Android Devices</a> |
| <ol> |
| <li><a href="#adk-conn-bt">ADK Connection over Bluetooth</a></li> |
| <li><a href="#adk-conn-usb">ADK Connection over USB</a></li> |
| </ol> |
| </li> |
| <li><a href="#audio-dock">USB Audio Dock Implementation</a></li> |
| </ol> |
| |
| <h2>See also</h2> |
| <ol> |
| <li><a href="https://developers.google.com/events/io/sessions/gooio2012/128/"> |
| Google I/O Session Video</a></li> |
| <li><a href="aoa.html">Android Open Accessory Protocol</a></li> |
| <li><a href="aoa2.html">Android Open Accessory Protocol 2.0</a></li> |
| <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html"> |
| USB Accessory Dev Guide</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>The Android Accessory Development Kit (ADK) for 2012 is the latest reference implementation of |
| an <a href="aoa.html">Android Open Accessory</a> device, designed to help Android hardware accessory |
| builders and software developers create accessories for Android. The ADK 2012 is based on the <a |
| href="http://arduino.cc">Arduino</a> open source electronics prototyping platform, with some |
| hardware and software extensions that allow it to communicate with Android devices.</p> |
| |
| <p>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!</p> |
| |
| <p>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 <a href="#audio-dock">reference implementation</a> of a USB |
| audio dock in this ADK if you are interested in making audio-related USB accessories for |
| Android.</p> |
| |
| <h2 id="components">Components</h2> |
| |
| <p>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:</p> |
| |
| <ol> |
| <li>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.</li> |
| <li>Shield containing sensors, LEDs, input controls, audio amplifier and speaker output, contained |
| in a custom, polygon box enclosure.</li> |
| </ol> |
| |
| <p>The main hardware features of the ADK are as follows:</p> |
| |
| <ul> |
| <li>An ARM 32-bit Cortex M3 micro-processor</li> |
| <li>Separate USB connections for an Android device and computer connection for programming and |
| debugging</li> |
| <li>Sensors for light, color, proximity, temperature, humidity, barometric pressure, and |
| acceleration</li> |
| <li>Micro SD Card slot</li> |
| <li>Bluetooth support</li> |
| </ul> |
| |
| <p>The ADK comes preloaded with an alarm clock firmware program that you can use immediately. A |
| companion Android application, <a |
| href="https://play.google.com/store/apps/details?id=com.google.android.apps.adk2">ADK 2012</a>, 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.</p> |
| |
| <p>The ADK 2012 also comes with additional parts to help you develop accessories with it, |
| including:</p> |
| |
| <ul> |
| <li>AC power adapter</li> |
| <li>USB A to Micro USB B connector cable</li> |
| <li>Micro USB B to Micro USB AB connector (small, rectangular plug)</li> |
| <li>Micro SD Card, preinstalled in the ADK SD Card socket</li> |
| </ul> |
| |
| <h2 id="clock">Using the Alarm Clock</h2> |
| |
| <p>An alarm clock program comes preloaded on the ADK. This firmware program allows you to use the |
| ADK as an alarm clock.</p> |
| |
| <p>To use the ADK as an alarm clock:</p> |
| |
| <ol> |
| <li>Open up the ADK by gently squeezing the two widest faces of the enclosure.</li> |
| <li>Attach the provided AC power adapter (round connector) to the main ADK board, or attach a USB |
| cable to the port marked <strong>Computer</strong> and a USB port on your computer.</li> |
| <li>Place and hold your fingertip over the clock symbol on the control face. |
| <p class="note"><strong>Note:</strong> You may need to hold your finger in place for 1-2 |
| seconds.</p> |
| </li> |
| <li>Use the plus (+) and minus (-) symbols inside the clock digits to set the correct time.</li> |
| <li>Place your fingertip over the alarm clock symbol to activate alarm setting.</li> |
| <li>Use the plus (+) and minus (-) symbols inside the clock digits to set the alarm time.</li> |
| <li>Use the plus (+) and minus (-) symbols inside the last two clock digits to turn the alarm on |
| ({@code on}) or off ({@code oF}).</li> |
| <li>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.</li> |
| </ol> |
| |
| <p>To use the <strong>ADK 2012</strong> companion application for the alarm clock:</p> |
| |
| <ol> |
| <li>Load the companion application on your Android device running Android 3.1 (API Level 12) or |
| higher: |
| <ul> |
| <li>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. |
| <br>- or -</li> |
| <li>Start Google Play on your device, search for the <strong>ADK 2012</strong> application and |
| install it. If you cannot find the app, your device is not compatible. Try installing on another |
| device.</li> |
| </ul> |
| </li> |
| <li>Connect your Android device to the ADK using one of the following methods: |
| <ul> |
| <li id="conn-bt">To connect using Bluetooth: |
| <ol> |
| <li>Plug the AC power adapter into the ADK.</li> |
| <li>On your Android device, turn Bluetooth On (<strong>Settings > |
| Bluetooth</strong>).</li> |
| <li>In the <strong>Settings</strong> page, press the <strong>Bluetooth</strong> option to |
| view paired devices.</li> |
| <li>Select <strong>Search for Devices</strong> to locate the ADK 2012 accessory and follow |
| the on screen instructions to connect.</li> |
| <li>After pairing is complete, start the <strong>ADK 2012</strong> app on your Android |
| device.</li> |
| <li>On the start screen, select the <strong>Use Bluetooth</strong> button.</li> |
| <li>In the list of paired devices, select the <strong>ADK 2012</strong> device.</li> |
| <li>The <strong>ADK 2012</strong> app should switch to the menu screen and you can start |
| interacting with the ADK accessory.</li> |
| </ol> |
| </li> |
| |
| <li id="conn-usb">To connect using USB: |
| <ol> |
| <li>Plug the AC power adapter into the ADK.</li> |
| <li>Connect the Micro USB AB connector (small, rectangular plug) to the port labeled |
| <strong>Phone</strong> on the ADK board.</li> |
| <li>Unlock your Android device and connect the Micro USB B connector to your device. |
| <p class="note"><strong>Note:</strong> Your device must support Android USB accessory |
| mode. Devices that support this mode include Google Nexus devices.</p> |
| </li> |
| <li>On the Android device, you should see a prompt to connect to the <strong>ADK DemoKit |
| 2012</strong>, select <strong>OK</strong>.</li> |
| <li>The <strong>ADK 2012</strong> app should start automatically and you can start |
| interacting with the ADK.</li> |
| </ol> |
| </li> |
| </ul> |
| </li> |
| </ol> |
| |
| <p class="note"><strong>Note:</strong> 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.</p> |
| |
| |
| <h2 id="play-audio">Playing Audio</h2> |
| |
| <p>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.</p> |
| |
| <p>To play audio over Bluetooth:</p> |
| |
| <ol> |
| <li>Follow the instructions in the <a href="#conn-bt">previous section</a> to connect your Android |
| device to the ADK over Bluetooth.</li> |
| <li>On your Android device, navigate to the <strong>Settings > Bluetooth</strong> page to view the |
| list of paired devices, and make sure the ADK is connected.</li> |
| <li>Select the settings icon next to the <strong>ADK 2012</strong> item.</li> |
| <li>Make sure the <strong>Media Audio</strong> option is enabled.</li> |
| <li>Navigate to an application that plays music or other audio.</li> |
| <li>Play a song or sound and listen to it on the ADK speaker!</li> |
| </ol> |
| |
| <p>To play audio over USB, you must use a device running Android 4.1 (API Level 16) or higher:</p> |
| |
| <ol> |
| <li>Plug the AC power adapter into the ADK.</li> |
| <li>Connect the Micro USB AB connector (small, rectangular plug) to the Phone port on the ADK |
| board.</li> |
| <li>Unlock your Android device and connect the Micro USB B connector to your device. |
| <p class="note"><strong>Note:</strong> Your device must support Android USB accessory |
| mode. Devices that support this mode include Google Nexus devices.</p> |
| </li> |
| <li>On the Android device, you should see a prompt to connect to the <strong>ADK DemoKit |
| 2012</strong>, select <strong>Cancel</strong> and allow the ADK to connect as a media device |
| only.</li> |
| <li>Navigate to an application that plays music or other audio.</li> |
| <li>Play a song or sound and listen to it on the ADK speaker!</li> |
| </ol> |
| |
| <p class="note"><strong>Note:</strong> 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.</p> |
| |
| |
| <h2 id="dev">Developing Accessories with ADK 2012</h2> |
| |
| <p>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.</p> |
| |
| <h3 id="src-download">Downloading the ADK Source</h3> |
| |
| <p>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.</p> |
| |
| <p>To download the ADK 2012 software, source code and hardware design specifications.</p> |
| |
| <ol> |
| <li>Download and install <a href="http://git-scm.com/download">Git</a> for your development |
| system.</li> |
| <li>Download and setup the {@code repo} tool, as described on the <a |
| href="http://source.android.com/source/downloading.html#installing-repo">Android open source |
| project</a> site. |
| <p class="note"><strong>Note:</strong> Developers using Windows must use a Linux compatibility |
| package, such as <a href="http://www.cygwin.com/">cygwin</a>, 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.</p> |
| </li> |
| <li>In a terminal window, create a new directory for the downloaded source files, initialize and |
| synchronize a local repository: |
| <pre> |
| $> mkdir android-accessories |
| $> cd android-accessories |
| $> repo init -u https://android.googlesource.com/accessories/manifest |
| $> repo sync |
| </pre> |
| </li> |
| </ol> |
| |
| <p>After successfully completing this process, you should have the source code and tools for |
| working with the ADK 2012:</p> |
| |
| <ul> |
| <li>{@code adk2012/board} - Source code and hardware design files for the ADK 2012</li> |
| <li>{@code adk2012/app} - Source code for the ADK 2012 Android companion application</li> |
| <li>{@code external/ide} - Source code for the ADK 2012 Integrated Development Environment |
| (IDE)</li> |
| <li>{@code external/toolchain} - The toolchain used by the ADK 2012 IDE</li> |
| </ul> |
| |
| |
| <h3 id="dev-setup">Setting Up the Development Environment</h3> |
| |
| <p>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.</p> |
| |
| <p>To set up and run the ADK 2012 IDE:</p> |
| |
| <ol> |
| <li>Download and install the Java Development Kit 6 or higher from <a |
| href="http://java.oracle.com">java.oracle.com</a>.</li> |
| <li>Download the ADK 2012 IDE for your development platform: |
| <ul> |
| <li><a href="https://dl-ssl.google.com/android/adk/adk2012_ide-win32-20120629.zip"> |
| Windows</a></li> |
| <li><a href="https://dl-ssl.google.com/android/adk/adk2012_ide-macosx-20120626.zip"> |
| Mac</a></li> |
| <li>Linux |
| <a href="https://dl-ssl.google.com/android/adk/adk2012_ide-linux32-20120626.tgz">32bit</a>, |
| <a href="https://dl-ssl.google.com/android/adk/adk2012_ide-linux64-20120626.tgz">64bit</a> |
| </li> |
| </ul> |
| </li> |
| <li>Unpack the downloaded archive.</li> |
| <li>Run the application by navigating to the unpacked {@code ADK2012_IDE/} folder and execute |
| the {@code arduino} file.</li> |
| </ol> |
| |
| <p>After you have successfully installed and run the ADK 2012 IDE, you must configure it to use |
| the ADK 2012 library.</p> |
| |
| <p>To configure the ADK 2012 IDE for use with the ADK libraries:</p> |
| |
| <ol> |
| <li>Start the ADK 2012 IDE and choose <strong>File > Preferences</strong>.</li> |
| <li>In the <strong>Preferences</strong> dialog, make a note of the <strong>Sketchbook |
| location</strong> directory.</li> |
| <li>Copy the {@code <adk-source-download>/adk2012/board/library/ADK2} directory and its |
| contents into your {@code sketchbook/libraries/} directory, so that you create a {@code |
| sketchbook/libraries/ADK2} directory.</li> |
| <li>Stop and restart the <strong>ADK 2012 IDE</strong>.</li> |
| <li>In the IDE, choose <strong>File > Examples > ADK2</strong> and then choose one of the example |
| sketches: |
| <ul> |
| <li><strong>clock</strong> - The sketch that is preloaded onto the ADK 2012.</li> |
| <li><strong>BluetoothScan</strong> - An example sketch demonstrating code that connects an |
| accessory to an Android device over Bluetooth.</li> |
| <li><strong>usbaccessory</strong> - An example sketch demonstrating code that connects an |
| accessory to an Android device through a USB cable.</li> |
| </ul> |
| </li> |
| <li>Connect a Micro USB cable from the <strong>Computer</strong> port on the ADK board to your |
| development computer.</li> |
| <li>In the <strong>ADK 2012 IDE</strong>, establish a serial port connection with the ADK by |
| selecting <strong>Tools > Serial Port</strong> and selecting the serial port for the ADK.</li> |
| <li>In the <strong>ADK 2012 IDE</strong>, choose the ADK by selecting<strong>Tools > Board > |
| Google ADK2</strong>.</li> |
| <li>Modify an example sketch or create your own.</li> |
| <li>Upload the sketch to the ADK by choosing <strong>File > Upload</strong>. When the <strong>ADK |
| 2012 IDE</strong> reports <strong>Done uploading</strong>, the sketch is uploaded and the ADK is |
| ready to communicate with your Android device.</li> |
| </ol> |
| |
| <h3 id="alt-build">Using the ADK Alternative Build System</h3> |
| |
| <p>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.</p> |
| |
| <p>To setup the environment:</p> |
| <ol> |
| <li><a href="#src-download">Download</a> the ADK 2012 source code files.</li> |
| <li>In a terminal window, navigate to {@code |
| <adk-source-download>/adk2012/board/MakefileBasedBuild}.</li> |
| <li>Execute the following command and follow the instructions: |
| <pre>$> ./setup</pre> |
| </li> |
| </ol> |
| |
| <p>To build a program for your accessory:</p> |
| <ol> |
| <li>Place your accessory code in the {@code MakefileBasedBuild/app} directory, including all |
| required library files. See the {@code app/main.c} file for an example of the program format.</li> |
| <li>Execute the following command and follow the instructions: |
| <pre>$> ./build</pre> |
| </li> |
| </ol> |
| |
| <p>To load the program on your accessory hardware:</p> |
| <ol> |
| <li>Run the build process above and make sure your program compiled successfully.</li> |
| <li>Attach the accessory via USB cable to your development computer.</li> |
| <li>Check which port the accessory is attached to and modify the {@code UART} variable in the |
| {@code flash} script to the correct port address. On linux machines, the port address is typically |
| {@code /dev/ttyUSB0}.</li> |
| <li>Execute the following command to load the program on the accessory: |
| <pre>$> ./flash</pre></li> |
| </ol> |
| |
| <h2 id="adk-conn">How the ADK Connects with Android Devices</h2> |
| |
| <p>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.</p> |
| |
| <h3 id="adk-conn-bt">ADK Connection over Bluetooth</h3> |
| |
| <p>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.</p> |
| |
| <p class="note"><strong>Note:</strong> 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.</p> |
| |
| <h4 id="acc-bt-code">Accessory Bluetooth Code</h4> |
| |
| <p>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:</p> |
| |
| <pre> |
| 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)); |
| } |
| } |
| </pre> |
| |
| <p>Notice that the {@code sdpDescrADK} object contains a Universally Unique Identifier (UUID) in the |
| variable {@code BT_ADK_UUID}. This identifier <em>must match</em> the device UUID provided in the |
| {@link android.bluetooth.BluetoothSocket} connection request in the Android application code.</p> |
| |
| <p>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:</p> |
| |
| <pre> |
| void loop(void) |
| { |
| ... |
| L.adkEventProcess(); //let the adk framework do its thing |
| ... |
| } |
| </pre> |
| |
| <p>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.</p> |
| |
| <h4 id="app-bt-code">Android App Bluetooth Code</h4> |
| |
| <p>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:</p> |
| |
| <pre> |
| mAdapter = BluetoothAdapter.getDefaultAdapter(); |
| BluetoothDevice device = mAdapter.getRemoteDevice(address); |
| mSocket = device.createInsecureRfcommSocketToServiceRecord(ADK_UUID); |
| mSocket.connect(); |
| </pre> |
| |
| <p>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:</p> |
| |
| <pre> |
| mInStream = mSocket.getInputStream(); |
| mOutStream = mSocket.getOutputStream(); |
| </pre> |
| |
| <p>Review the {@code BTConnection.java} file provided in the ADK 2012 software download for more |
| implementation details.</p> |
| |
| <h3 id="adk-conn-usb">ADK Connection over USB</h3> |
| |
| <p>The ADK 2012 app and hardware accessory can also use a USB connection to communicate, similar to |
| the original ADK.</p> |
| |
| <h4 id="acc-usb-code">Accessory USB Code</h4> |
| |
| <p>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:</p> |
| |
| <pre> |
| ADK L; |
| void setup() { |
| L.adkInit(); |
| L.usbSetAccessoryStringVendor(...); |
| L.usbSetAccessoryStringName(...); |
| L.usbSetAccessoryStringLongname(...); |
| L.usbSetAccessoryStringVersion(...); |
| L.usbSetAccessoryStringUrl(...); |
| L.usbSetAccessoryStringSerial(...); |
| |
| L.usbStart(); |
| } |
| </pre> |
| |
| <p class="note"><strong>Note:</strong> The identification strings must match the USB accessory |
| filter settings specified in the connecting Android application,otherwise the application cannot |
| connect with the accessory.</p> |
| |
| <p>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:</p> |
| |
| <pre> |
| void loop(void) |
| { |
| ... |
| L.adkEventProcess(); //let the adk framework do its thing |
| ... |
| } |
| </pre> |
| |
| <p>The accessory must then check for a live USB connection to process commands and send |
| messages. Here is a summary of the relevant code:</p> |
| |
| <pre> |
| void loop() { |
| if (L.accessoryConnected()) { |
| int recvLen = L.accessoryReceive(msg, sizeof(msg)); |
| if (recvLen > 0) { |
| ... // process message |
| } |
| |
| L.accessorySend(outmsg, outmsgLen); |
| } |
| L.adkEventProcess(); |
| } |
| </pre> |
| |
| <p>For more details, review the implementations of these methods in the {@code clock.ino} |
| sketch.</p> |
| |
| <h4 id="app-usb-code">Android App USB Code</h4> |
| |
| <p>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:</p> |
| |
| <pre> |
| 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; |
| </pre> |
| |
| <p>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:</p> |
| |
| <pre> |
| import android.hardware.usb.UsbAccessory |
| import android.hardware.usb.UsbManager |
| |
| mUSBManager = (UsbManager) getSystemService(Context.USB_SERVICE); |
| UsbAccessory acc = (UsbAccessory) |
| intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); |
| </pre> |
| |
| <p>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:</p> |
| |
| <pre> |
| <meta-data |
| android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" |
| android:resource="@xml/usb_accessory_filter" /> |
| </pre> |
| |
| <p>Connections from other USB devices are not received by the ADK 2012 accessory.</p> |
| |
| <p>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:</p> |
| |
| <pre> |
| 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 |
| } |
| </pre> |
| |
| <p>Review the {@code UsbConnection.java} file provided in the ADK 2012 source code for more |
| implementation details.</p> |
| |
| <h2 id="audio-dock">USB Audio Dock Implementation</h2> |
| |
| <p>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) |
| <a href="aoa2.html">protocol 2.0</a> and is available on devices running Android 4.1 (API Level 16) |
| and higher.</p> |
| |
| <p>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.</p> |
| |
| <p>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:</p> |
| |
| <pre> |
| ADK L; |
| void setup() { |
| L.audioInit(); |
| L.usbh_init() |
| L.usbStart(); |
| } |
| </pre> |
| |
| <p>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.</p> |
| |
| <p>After completing this setup, the {@code loop()} function calls {@code ADK::adkEventProcess()} to |
| handle audio output and other ADK functions:</p> |
| |
| <pre> |
| void loop(void) |
| { |
| ... |
| L.adkEventProcess(); //let the adk framework do its thing |
| ... |
| } |
| </pre> |
| |
| <p>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.</p> |