1 page.title=Accessory Development Kit 2012 Guide 2 page.tags="adk" 3 @jd:body 4 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>In this document</h2> 8 <ol> 9 <li><a href="#components">Components</a></li> 10 <li><a href="#clock">Using the Alarm Clock</a></li> 11 <li><a href="#play-audio">Playing Audio</a></li> 12 <li><a href="#dev">Developing Accessories with ADK 2012</a> 13 <ol> 14 <li><a href="#src-download">Downloading the ADK Source</a></li> 15 <li><a href="#dev-setup">Setting Up the Development Environment</a></li> 16 <li><a href="#alt-build">Using the ADK Alternative Build System</a></li> 17 </ol> 18 </li> 19 <li><a href="#adk-conn">How the ADK Connects with Android Devices</a> 20 <ol> 21 <li><a href="#adk-conn-bt">ADK Connection over Bluetooth</a></li> 22 <li><a href="#adk-conn-usb">ADK Connection over USB</a></li> 23 </ol> 24 </li> 25 <li><a href="#audio-dock">USB Audio Dock Implementation</a></li> 26 </ol> 27 28 <h2>See also</h2> 29 <ol> 30 <li><a href="https://developers.google.com/events/io/sessions/gooio2012/128/"> 31 Google I/O Session Video</a></li> 32 <li><a href="http://source.android.com/tech/accessories/aoap/aoa.html"> 33 Android Open Accessory Protocol</a></li> 34 <li><a href="http://source.android.com/tech/accessories/aoap/aoa2.html"> 35 Android Open Accessory Protocol 2.0</a></li> 36 <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html"> 37 USB Accessory Dev Guide</a></li> 38 </ol> 39 </div> 40 </div> 41 42 <p>The Android Accessory Development Kit (ADK) for 2012 is the latest reference implementation of an 43 <a href="http://source.android.com/tech/accessories/index.html">Android Open Accessory</a> device, 44 designed to help Android hardware accessory builders and software developers create accessories 45 for Android. The ADK 2012 is based on the <a href="http://arduino.cc">Arduino</a> open source 46 electronics prototyping platform, with some hardware and software extensions that allow it to 47 communicate with Android devices.</p> 48 49 <p>A limited number of these kits were produced and distributed at the Google I/O 2012 developer 50 conference. If you did not receive one of these kits, fear not! The specifications and design files 51 for the hardware were also released for use by manufacturers and hobbyists. You should expect to see 52 kits with similar features available for purchase, or you can build one yourself!</p> 53 54 <p>One of the important new features demonstrated by this ADK is the ability to play audio over a 55 USB connection. Be sure to check out the <a href="#audio-dock">reference implementation</a> of a USB 56 audio dock in this ADK if you are interested in making audio-related USB accessories for 57 Android.</p> 58 59 <h2 id="components">Components</h2> 60 61 <p>The ADK 2012 is based on the Arduino open source electronics prototyping platform and is an open 62 hardware design. The hardware design files and firmware source code are included with the ADK 63 software download. The ADK contains two main physical hardware components:</p> 64 65 <ol> 66 <li>Main processing board containing the microprocessor, USB connections, power connector and 67 input/output pins. This board can be removed and used separately from the rest of the hardware.</li> 68 <li>Shield containing sensors, LEDs, input controls, audio amplifier and speaker output, contained 69 in a custom, polygon box enclosure.</li> 70 </ol> 71 72 <p>The main hardware features of the ADK are as follows:</p> 73 74 <ul> 75 <li>An ARM 32-bit Cortex M3 micro-processor</li> 76 <li>Separate USB connections for an Android device and computer connection for programming and 77 debugging</li> 78 <li>Sensors for light, color, proximity, temperature, humidity, barometric pressure, and 79 acceleration</li> 80 <li>Micro SD Card slot</li> 81 <li>Bluetooth support</li> 82 </ul> 83 84 <p>The ADK comes preloaded with an alarm clock firmware program that you can use immediately. A 85 companion Android application, <a 86 href="https://play.google.com/store/apps/details?id=com.google.android.apps.adk2">ADK 2012</a>, is 87 available on Google Play. The source code for both the Android application and the ADK firmware (an 88 Arduino sketch) can be downloaded from this page.</p> 89 90 <p>The ADK 2012 also comes with additional parts to help you develop accessories with it, 91 including:</p> 92 93 <ul> 94 <li>AC power adapter</li> 95 <li>USB A to Micro USB B connector cable</li> 96 <li>Micro USB B to Micro USB AB connector (small, rectangular plug)</li> 97 <li>Micro SD Card, preinstalled in the ADK SD Card socket</li> 98 </ul> 99 100 <h2 id="clock">Using the Alarm Clock</h2> 101 102 <p>An alarm clock program comes preloaded on the ADK. This firmware program allows you to use the 103 ADK as an alarm clock.</p> 104 105 <p>To use the ADK as an alarm clock:</p> 106 107 <ol> 108 <li>Open up the ADK by gently squeezing the two widest faces of the enclosure.</li> 109 <li>Attach the provided AC power adapter (round connector) to the main ADK board, or attach a USB 110 cable to the port marked <strong>Computer</strong> and a USB port on your computer.</li> 111 <li>Place and hold your fingertip over the clock symbol on the control face. 112 <p class="note"><strong>Note:</strong> You may need to hold your finger in place for 1-2 113 seconds.</p> 114 </li> 115 <li>Use the plus (+) and minus (-) symbols inside the clock digits to set the correct time.</li> 116 <li>Place your fingertip over the alarm clock symbol to activate alarm setting.</li> 117 <li>Use the plus (+) and minus (-) symbols inside the clock digits to set the alarm time.</li> 118 <li>Use the plus (+) and minus (-) symbols inside the last two clock digits to turn the alarm on 119 ({@code on}) or off ({@code oF}).</li> 120 <li>To set the alarm tone, place and hold your fingertip over the alarm clock symbol, then tap the 121 slider control on top of the enclosure.</li> 122 </ol> 123 124 <p>To use the <strong>ADK 2012</strong> companion application for the alarm clock:</p> 125 126 <ol> 127 <li>Load the companion application on your Android device running Android 3.1 (API Level 12) or 128 higher: 129 <ul> 130 <li>Using an NFC-enabled Android device, unlock and hold the device against the left side of 131 the ADK enclosure. Follow the prompts to install the app. 132 <br>- or -</li> 133 <li>Start Google Play on your device, search for the <strong>ADK 2012</strong> application and 134 install it. If you cannot find the app, your device is not compatible. Try installing on another 135 device.</li> 136 </ul> 137 </li> 138 <li>Connect your Android device to the ADK using one of the following methods: 139 <ul> 140 <li id="conn-bt">To connect using Bluetooth: 141 <ol> 142 <li>Plug the AC power adapter into the ADK.</li> 143 <li>On your Android device, turn Bluetooth On (<strong>Settings > 144 Bluetooth</strong>).</li> 145 <li>In the <strong>Settings</strong> page, press the <strong>Bluetooth</strong> option to 146 view paired devices.</li> 147 <li>Select <strong>Search for Devices</strong> to locate the ADK 2012 accessory and follow 148 the on screen instructions to connect.</li> 149 <li>After pairing is complete, start the <strong>ADK 2012</strong> app on your Android 150 device.</li> 151 <li>On the start screen, select the <strong>Use Bluetooth</strong> button.</li> 152 <li>In the list of paired devices, select the <strong>ADK 2012</strong> device.</li> 153 <li>The <strong>ADK 2012</strong> app should switch to the menu screen and you can start 154 interacting with the ADK accessory.</li> 155 </ol> 156 </li> 157 158 <li id="conn-usb">To connect using USB: 159 <ol> 160 <li>Plug the AC power adapter into the ADK.</li> 161 <li>Connect the Micro USB AB connector (small, rectangular plug) to the port labeled 162 <strong>Phone</strong> on the ADK board.</li> 163 <li>Unlock your Android device and connect the Micro USB B connector to your device. 164 <p class="note"><strong>Note:</strong> Your device must support Android USB accessory 165 mode. Devices that support this mode include Google Nexus devices.</p> 166 </li> 167 <li>On the Android device, you should see a prompt to connect to the <strong>ADK DemoKit 168 2012</strong>, select <strong>OK</strong>.</li> 169 <li>The <strong>ADK 2012</strong> app should start automatically and you can start 170 interacting with the ADK.</li> 171 </ol> 172 </li> 173 </ul> 174 </li> 175 </ol> 176 177 <p class="note"><strong>Note:</strong> When using the ADK with a USB connection to an Android 178 device, make sure the AC power adapter is plugged in. A USB connection to a computer does not 179 provide sufficient voltage to power both the ADK and a USB connection to a device.</p> 180 181 182 <h2 id="play-audio">Playing Audio</h2> 183 184 <p>The ADK 2012 comes with audio output capabilities, including an amplifier and speaker. You can 185 use it to play audio from your Android device using either a Bluetooth or USB connection.</p> 186 187 <p>To play audio over Bluetooth:</p> 188 189 <ol> 190 <li>Follow the instructions in the <a href="#conn-bt">previous section</a> to connect your Android 191 device to the ADK over Bluetooth.</li> 192 <li>On your Android device, navigate to the <strong>Settings > Bluetooth</strong> page to view the 193 list of paired devices, and make sure the ADK is connected.</li> 194 <li>Select the settings icon next to the <strong>ADK 2012</strong> item.</li> 195 <li>Make sure the <strong>Media Audio</strong> option is enabled.</li> 196 <li>Navigate to an application that plays music or other audio.</li> 197 <li>Play a song or sound and listen to it on the ADK speaker!</li> 198 </ol> 199 200 <p>To play audio over USB, you must use a device running Android 4.1 (API Level 16) or higher:</p> 201 202 <ol> 203 <li>Plug the AC power adapter into the ADK.</li> 204 <li>Connect the Micro USB AB connector (small, rectangular plug) to the Phone port on the ADK 205 board.</li> 206 <li>Unlock your Android device and connect the Micro USB B connector to your device. 207 <p class="note"><strong>Note:</strong> Your device must support Android USB accessory 208 mode. Devices that support this mode include Google Nexus devices.</p> 209 </li> 210 <li>On the Android device, you should see a prompt to connect to the <strong>ADK DemoKit 211 2012</strong>, select <strong>Cancel</strong> and allow the ADK to connect as a media device 212 only.</li> 213 <li>Navigate to an application that plays music or other audio.</li> 214 <li>Play a song or sound and listen to it on the ADK speaker!</li> 215 </ol> 216 217 <p class="note"><strong>Note:</strong> When using the ADK with a USB connection to an Android 218 device, make sure the AC power adapter is plugged in. A USB connection to a computer does not 219 provide sufficient voltage to power both the ADK and a USB connection to a device.</p> 220 221 222 <h2 id="dev">Developing Accessories with ADK 2012</h2> 223 224 <p>The ADK 2012 is a hardware platform and a set of software libraries for prototyping Android 225 accessories. This section discusses how to set up a development environment for programming the ADK 226 to make it do what you want and to test software for building your own Android accessories.</p> 227 228 <h3 id="src-download">Downloading the ADK Source</h3> 229 230 <p>The support software and hardware specifications for the ADK 2012 are available from the Android 231 source repository. Follow the instructions below to obtain the source material for the ADK.</p> 232 233 <p>To download the ADK 2012 software, source code and hardware design specifications.</p> 234 235 <ol> 236 <li>Download and install <a href="http://git-scm.com/download">Git</a> for your development 237 system.</li> 238 <li>Download and setup the {@code repo} tool, as described on the <a 239 href="http://source.android.com/source/downloading.html#installing-repo">Android open source 240 project</a> site. 241 <p class="note"><strong>Note:</strong> Developers using Windows must use a Linux compatibility 242 package, such as <a href="http://www.cygwin.com/">cygwin</a>, to install and run {@code repo}. 243 Within your compatibility environment, you must install {@code curl}, {@code git} and {@code 244 python} to be able to download and use the {@code repo} tool.</p> 245 </li> 246 <li>In a terminal window, create a new directory for the downloaded source files, initialize and 247 synchronize a local repository: 248 <pre> 249 $> mkdir android-accessories 250 $> cd android-accessories 251 $> repo init -u https://android.googlesource.com/accessories/manifest 252 $> repo sync 253 </pre> 254 </li> 255 </ol> 256 257 <p>After successfully completing this process, you should have the source code and tools for 258 working with the ADK 2012:</p> 259 260 <ul> 261 <li>{@code adk2012/board} - Source code and hardware design files for the ADK 2012</li> 262 <li>{@code adk2012/app} - Source code for the ADK 2012 Android companion application</li> 263 <li>{@code external/ide} - Source code for the ADK 2012 Integrated Development Environment 264 (IDE)</li> 265 <li>{@code external/toolchain} - The toolchain used by the ADK 2012 IDE</li> 266 </ul> 267 268 269 <h3 id="dev-setup">Setting Up the Development Environment</h3> 270 271 <p>The ADK 2012 comes with an integrated development environment (IDE) that you use to develop 272 software and program the ADK 2012 accessory. The following instructions explain how to setup and run 273 the ADK 2012 IDE.</p> 274 275 <p>To set up and run the ADK 2012 IDE:</p> 276 277 <ol> 278 <li>Download and install the Java Development Kit 6 or higher from <a 279 href="http://java.oracle.com">java.oracle.com</a>.</li> 280 <li>Download the ADK 2012 IDE for your development platform: 281 <ul> 282 <li><a href="https://dl-ssl.google.com/android/adk/adk2012_ide-win32-20120629.zip"> 283 Windows</a></li> 284 <li><a href="https://dl-ssl.google.com/android/adk/adk2012_ide-macosx-20120626.zip"> 285 Mac</a></li> 286 <li>Linux 287 <a href="https://dl-ssl.google.com/android/adk/adk2012_ide-linux32-20120626.tgz">32bit</a>, 288 <a href="https://dl-ssl.google.com/android/adk/adk2012_ide-linux64-20120626.tgz">64bit</a> 289 </li> 290 </ul> 291 </li> 292 <li>Unpack the downloaded archive.</li> 293 <li>Run the application by navigating to the unpacked {@code ADK2012_IDE/} folder and execute 294 the {@code arduino} file.</li> 295 </ol> 296 297 <p>After you have successfully installed and run the ADK 2012 IDE, you must configure it to use 298 the ADK 2012 library.</p> 299 300 <p>To configure the ADK 2012 IDE for use with the ADK libraries:</p> 301 302 <ol> 303 <li>Start the ADK 2012 IDE and choose <strong>File > Preferences</strong>.</li> 304 <li>In the <strong>Preferences</strong> dialog, make a note of the <strong>Sketchbook 305 location</strong> directory.</li> 306 <li>Copy the {@code <adk-source-download>/adk2012/board/library/ADK2} directory and its 307 contents into your {@code sketchbook/libraries/} directory, so that you create a {@code 308 sketchbook/libraries/ADK2} directory.</li> 309 <li>Stop and restart the <strong>ADK 2012 IDE</strong>.</li> 310 <li>In the IDE, choose <strong>File > Examples > ADK2</strong> and then choose one of the example 311 sketches: 312 <ul> 313 <li><strong>clock</strong> - The sketch that is preloaded onto the ADK 2012.</li> 314 <li><strong>BluetoothScan</strong> - An example sketch demonstrating code that connects an 315 accessory to an Android device over Bluetooth.</li> 316 <li><strong>usbaccessory</strong> - An example sketch demonstrating code that connects an 317 accessory to an Android device through a USB cable.</li> 318 </ul> 319 </li> 320 <li>Connect a Micro USB cable from the <strong>Computer</strong> port on the ADK board to your 321 development computer.</li> 322 <li>In the <strong>ADK 2012 IDE</strong>, establish a serial port connection with the ADK by 323 selecting <strong>Tools > Serial Port</strong> and selecting the serial port for the ADK.</li> 324 <li>In the <strong>ADK 2012 IDE</strong>, choose the ADK by selecting<strong>Tools > Board > 325 Google ADK2</strong>.</li> 326 <li>Modify an example sketch or create your own.</li> 327 <li>Upload the sketch to the ADK by choosing <strong>File > Upload</strong>. When the <strong>ADK 328 2012 IDE</strong> reports <strong>Done uploading</strong>, the sketch is uploaded and the ADK is 329 ready to communicate with your Android device.</li> 330 </ol> 331 332 <h3 id="alt-build">Using the ADK Alternative Build System</h3> 333 334 <p>An alternative, make file-based build and upload system is also available for the ADK 2012. This 335 system is command line based and intended for production environments where using an IDE environment 336 to load software onto accessory hardware may be inconvenient or undesirable.</p> 337 338 <p>To setup the environment:</p> 339 <ol> 340 <li><a href="#src-download">Download</a> the ADK 2012 source code files.</li> 341 <li>In a terminal window, navigate to {@code 342 <adk-source-download>/adk2012/board/MakefileBasedBuild}.</li> 343 <li>Execute the following command and follow the instructions: 344 <pre>$> ./setup</pre> 345 </li> 346 </ol> 347 348 <p>To build a program for your accessory:</p> 349 <ol> 350 <li>Place your accessory code in the {@code MakefileBasedBuild/app} directory, including all 351 required library files. See the {@code app/main.c} file for an example of the program format.</li> 352 <li>Execute the following command and follow the instructions: 353 <pre>$> ./build</pre> 354 </li> 355 </ol> 356 357 <p>To load the program on your accessory hardware:</p> 358 <ol> 359 <li>Run the build process above and make sure your program compiled successfully.</li> 360 <li>Attach the accessory via USB cable to your development computer.</li> 361 <li>Check which port the accessory is attached to and modify the {@code UART} variable in the 362 {@code flash} script to the correct port address. On linux machines, the port address is typically 363 {@code /dev/ttyUSB0}.</li> 364 <li>Execute the following command to load the program on the accessory: 365 <pre>$> ./flash</pre></li> 366 </ol> 367 368 <h2 id="adk-conn">How the ADK Connects with Android Devices</h2> 369 370 <p>The essential feature of any Android accessory is its ability to connect and communicate with an 371 Android device. Creating a fast and reliable connection between your accessory and Android devices 372 is the first order of business when building software for an accessory. This section describes the 373 connection and communication essentials used in the ADK 2012 so that you can apply them to 374 developing your own Android accessories.</p> 375 376 <h3 id="adk-conn-bt">ADK Connection over Bluetooth</h3> 377 378 <p>The ADK 2012 app and hardware accessory use a Bluetooth Serial Port Profile (SPP) connection to 379 communicate. This connection allows two way communication between the ADK accessory and Android 380 devices.</p> 381 382 <p class="note"><strong>Note:</strong> The implementation of the ADK hardware allows the use of 383 other profiles and multiple connections. However, the basic communication between the ADK 2012 384 accessory and the Android application uses SPP.</p> 385 386 <h4 id="acc-bt-code">Accessory Bluetooth Code</h4> 387 388 <p>In order to enable Bluetooth communications, the {@code clock.ino} sketch for the ADK 2012 389 accessory calls a {@code btStart()} method during the {@code setup()} method to enable radio 390 frequency communications and start listening for Bluetooth connections:</p> 391 392 <pre> 393 ADK L; 394 void setup() { 395 L.adkInit(); 396 L.btStart(); 397 } 398 ... 399 void btStart(){ 400 uint8_t i, dlci; 401 int f; 402 403 L.btEnable(adkBtConnectionRequest, adkBtLinkKeyRequest, adkBtLinkKeyCreated, 404 adkBtPinRequest, NULL); 405 406 dlci = L.btRfcommReserveDlci(RFCOMM_DLCI_NEED_EVEN); 407 408 if(!dlci) dbgPrintf("BTADK: failed to allocate DLCI\n"); 409 else{ 410 411 //change descriptor to be valid... 412 for(i = 0, f = -1; i < sizeof(sdpDescrADK); i++){ 413 414 if(sdpDescrADK[i] == MAGIX){ 415 if(f == -1) f = i; 416 else break; 417 } 418 } 419 420 if(i != sizeof(sdpDescrADK) || f == -1){ 421 422 dbgPrintf("BTADK: failed to find a single marker in descriptor\n"); 423 L.btRfcommReleaseDlci(dlci); 424 return; 425 } 426 427 sdpDescrADK[f] = dlci >> 1; 428 429 dbgPrintf("BTADK has DLCI %u\n", dlci); 430 431 L.btRfcommRegisterPort(dlci, btAdkPortOpen, btAdkPortClose, btAdkPortRx); 432 L.btSdpServiceDescriptorAdd(sdpDescrADK, sizeof(sdpDescrADK)); 433 } 434 } 435 </pre> 436 437 <p>Notice that the {@code sdpDescrADK} object contains a Universally Unique Identifier (UUID) in the 438 variable {@code BT_ADK_UUID}. This identifier <em>must match</em> the device UUID provided in the 439 {@link android.bluetooth.BluetoothSocket} connection request in the Android application code.</p> 440 441 <p>Once Bluetooth is enabled with the code shown above, the accessory listens for connection 442 requests. The ADK library handles listening and connection details, so the accessory calls 443 {@code ADK::adkEventProcess()} once during each loop execution:</p> 444 445 <pre> 446 void loop(void) 447 { 448 ... 449 L.adkEventProcess(); //let the adk framework do its thing 450 ... 451 } 452 </pre> 453 454 <p>If a Bluetooth connection has been established, any commands are routed to the 455 {@code btAdkPortRx()} callback method (which was registered with the ADK library as part of the 456 {@code btStart()} method) and processed accordingly. The ADK accessory sends messages back through 457 the Bluetooth connection using the {@code ADK::btRfcommPortTx()} method. 458 For more details, review the implementations of these methods in the {@code clock.ino} sketch.</p> 459 460 <h4 id="app-bt-code">Android App Bluetooth Code</h4> 461 462 <p>In the ADK 2012 Android app, the code for handling Bluetooth connections is encapsulated in in a 463 {@code BTConnection} class. In this class, the application requests access to the Bluetooth adapter 464 and negotiates a connection with the ADK 2012 accessory. Here is a summary of the relevant code:</p> 465 466 <pre> 467 mAdapter = BluetoothAdapter.getDefaultAdapter(); 468 BluetoothDevice device = mAdapter.getRemoteDevice(address); 469 mSocket = device.createInsecureRfcommSocketToServiceRecord(ADK_UUID); 470 mSocket.connect(); 471 </pre> 472 473 <p>Note the {@code ADK_UUID} parameter in the second line. This identifier must match the identifier 474 output by the accessory (the {@code BT_ADK_UUID} variable mentioned earlier), otherwise the protocol 475 negotiation fails and the {@link android.bluetooth.BluetoothSocket} is not created. Once a 476 connection is established, you obtain {@link java.io.InputStream} and {@link java.io.OutputStream} 477 objects from the socket to communicate with the accessory:</p> 478 479 <pre> 480 mInStream = mSocket.getInputStream(); 481 mOutStream = mSocket.getOutputStream(); 482 </pre> 483 484 <p>Review the {@code BTConnection.java} file provided in the ADK 2012 software download for more 485 implementation details.</p> 486 487 <h3 id="adk-conn-usb">ADK Connection over USB</h3> 488 489 <p>The ADK 2012 app and hardware accessory can also use a USB connection to communicate, similar to 490 the original ADK.</p> 491 492 <h4 id="acc-usb-code">Accessory USB Code</h4> 493 494 <p>The ADK library takes care of most of the implementation details for a USB connection, the 495 accessory code must make a few calls to initialize USB connectivity, including setting the accessory 496 identification strings:</p> 497 498 <pre> 499 ADK L; 500 void setup() { 501 L.adkInit(); 502 L.usbSetAccessoryStringVendor(...); 503 L.usbSetAccessoryStringName(...); 504 L.usbSetAccessoryStringLongname(...); 505 L.usbSetAccessoryStringVersion(...); 506 L.usbSetAccessoryStringUrl(...); 507 L.usbSetAccessoryStringSerial(...); 508 509 L.usbStart(); 510 } 511 </pre> 512 513 <p class="note"><strong>Note:</strong> The identification strings must match the USB accessory 514 filter settings specified in the connecting Android application,otherwise the application cannot 515 connect with the accessory.</p> 516 517 <p>Once USB is enabled with code shown above, the accessory listens for connection requests. The ADK 518 library handles listening and connection details, so the accessory calls {@code 519 ADK::adkEventProcess()} once during each loop execution:</p> 520 521 <pre> 522 void loop(void) 523 { 524 ... 525 L.adkEventProcess(); //let the adk framework do its thing 526 ... 527 } 528 </pre> 529 530 <p>The accessory must then check for a live USB connection to process commands and send 531 messages. Here is a summary of the relevant code:</p> 532 533 <pre> 534 void loop() { 535 if (L.accessoryConnected()) { 536 int recvLen = L.accessoryReceive(msg, sizeof(msg)); 537 if (recvLen > 0) { 538 ... // process message 539 } 540 541 L.accessorySend(outmsg, outmsgLen); 542 } 543 L.adkEventProcess(); 544 } 545 </pre> 546 547 <p>For more details, review the implementations of these methods in the {@code clock.ino} 548 sketch.</p> 549 550 <h4 id="app-usb-code">Android App USB Code</h4> 551 552 <p>In the ADK 2012 Android app, the code for handling USB connections is encapsulated in a 553 {@code UsbConnection} class. This class sets up a {@link android.content.BroadcastReceiver} to 554 listen for USB events and then attempts to connect when a matching connection event is received. 555 Here is a summary of the relevant code:</p> 556 557 <pre> 558 import com.android.future.usb.UsbAccessory; 559 import com.android.future.usb.UsbManager; 560 561 mUSBManager = UsbManager.getInstance(this); 562 UsbAccessory acc = mUSBManager.getAccessoryList()[0]; 563 564 if (!mUSBManager.hasPermission(acc)) return; 565 </pre> 566 567 <p>The ADK 2012 app uses the support library to implement the USB accessory connections, in order to 568 support devices running Android 2.3.4 (API Level 10). If you only need to support Android 569 3.1 (API Level 12) and higher devices, you can replace the first 4 lines the following code:</p> 570 571 <pre> 572 import android.hardware.usb.UsbAccessory 573 import android.hardware.usb.UsbManager 574 575 mUSBManager = (UsbManager) getSystemService(Context.USB_SERVICE); 576 UsbAccessory acc = (UsbAccessory) 577 intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); 578 </pre> 579 580 <p>Note that the app only receives events when the USB accessory identification information matches 581 the information in the {@code res/xml/usb_accessory_filter.xml} file, referenced by the 582 applications manifest statement:</p> 583 584 <pre> 585 <meta-data 586 android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" 587 android:resource="@xml/usb_accessory_filter" /> 588 </pre> 589 590 <p>Connections from other USB devices are not received by the ADK 2012 accessory.</p> 591 592 <p>Once the connection is established, the app can communicate with the accessory through file input 593 and output streams, as shown in the following example code:</p> 594 595 <pre> 596 ParcelFileDescriptor mFD = mUSBManager.openAccessory(acc); 597 if (mFD != null) { 598 FileDescripter fd = mFD.getFileDescriptor(); 599 mIS = new FileInputStream(fd); // use this to receive messages 600 mOS = new FileOutputStream(fd); // use this to send commands 601 } 602 </pre> 603 604 <p>Review the {@code UsbConnection.java} file provided in the ADK 2012 source code for more 605 implementation details.</p> 606 607 <h2 id="audio-dock">USB Audio Dock Implementation</h2> 608 609 <p>One of the important new features introduced with the ADK 2012 is the ability to play audio over 610 a USB connection. This innovation was introduced as an update to Android Open Accessory (AOA) 611 <a href="http://source.android.com/tech/accessories/aoap/aoa2.html">protocol 2.0</a> and is 612 available on devices running Android 4.1 (API Level 16) and higher.</p> 613 614 <p>The ADK 2012 provides a reference implementation of this functionality for accessory developers. 615 No software application is required to be installed on the connected Android device, accessory 616 developers only need to support AOA v2. This implementation demonstrates audio output of 16bit, 617 44.1kHz stereo PCM source data compressed into a single channel due to the audio hardware available 618 on the accessory.</p> 619 620 <p>Using the audio output features provided by the ADK library requires only a few function calls. 621 The first few calls are in the accessory {@code setup()} routine, which prepare the accessory for 622 USB connections and audio output, as summarized in the code example below:</p> 623 624 <pre> 625 ADK L; 626 void setup() { 627 L.audioInit(); 628 L.usbh_init() 629 L.usbStart(); 630 } 631 </pre> 632 633 <p>For more information about the {@code ADK::audioInit()} function, see the {@code 634 libraries/ADK/Audio.c} library file. For more information about the {@code ADK::usbh_init()} 635 function, see the {@code libraries/ADK/Usbh.c} library file.</p> 636 637 <p>After completing this setup, the {@code loop()} function calls {@code ADK::adkEventProcess()} to 638 handle audio output and other ADK functions:</p> 639 640 <pre> 641 void loop(void) 642 { 643 ... 644 L.adkEventProcess(); //let the adk framework do its thing 645 ... 646 } 647 </pre> 648 649 <p>This call executes task queuing for the ADK and as part of the execution process, the task queue 650 executes {@code usbh_work()} in {@code libraries/ADK/Usbh.c}, which handles audio output requests. 651 Review the implementation of this function for details. For additional implementation details on 652 audio output, see the {@code libraries/ADK/accessory.c} library file.</p> 653