Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 1 | page.title=Accessory Development Kit 2012 Guide |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 2 | page.tags=adk |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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> |
Joe Fernandez | d2d6c09 | 2012-07-11 15:26:09 -0700 | [diff] [blame] | 30 | <li><a href="https://developers.google.com/events/io/sessions/gooio2012/128/"> |
| 31 | Google I/O Session Video</a></li> |
Joe Fernandez | 069bc4a | 2012-10-04 11:43:09 -0700 | [diff] [blame] | 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> |
Joe Fernandez | d2d6c09 | 2012-07-11 15:26:09 -0700 | [diff] [blame] | 36 | <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html"> |
| 37 | USB Accessory Dev Guide</a></li> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 38 | </ol> |
| 39 | </div> |
| 40 | </div> |
| 41 | |
Joe Fernandez | 069bc4a | 2012-10-04 11:43:09 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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 |
Joe Fernandez | d2d6c09 | 2012-07-11 15:26:09 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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 |
Joe Fernandez | 79dee59 | 2012-06-29 14:39:00 -0700 | [diff] [blame] | 251 | $> repo init -u https://android.googlesource.com/accessories/manifest |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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 | |
Joe Fernandez | caa008f | 2012-06-27 23:33:20 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 274 | |
Joe Fernandez | caa008f | 2012-06-27 23:33:20 -0700 | [diff] [blame] | 275 | <p>To set up and run the ADK 2012 IDE:</p> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 276 | |
| 277 | <ol> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 278 | <li>Download and install the Java Development Kit 6 or higher from <a |
Joe Fernandez | caa008f | 2012-06-27 23:33:20 -0700 | [diff] [blame] | 279 | href="http://java.oracle.com">java.oracle.com</a>.</li> |
| 280 | <li>Download the ADK 2012 IDE for your development platform: |
| 281 | <ul> |
Joe Fernandez | d2d6c09 | 2012-07-11 15:26:09 -0700 | [diff] [blame] | 282 | <li><a href="https://dl-ssl.google.com/android/adk/adk2012_ide-win32-20120629.zip"> |
Joe Fernandez | caa008f | 2012-06-27 23:33:20 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 291 | </li> |
Joe Fernandez | caa008f | 2012-06-27 23:33:20 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 295 | </ol> |
| 296 | |
Joe Fernandez | caa008f | 2012-06-27 23:33:20 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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 | |
Joe Fernandez | d9435b3 | 2012-06-26 23:32:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 337 | |
Joe Fernandez | d9435b3 | 2012-06-26 23:32:03 -0700 | [diff] [blame] | 338 | <p>To setup the environment:</p> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 339 | <ol> |
| 340 | <li><a href="#src-download">Download</a> the ADK 2012 source code files.</li> |
Joe Fernandez | d9435b3 | 2012-06-26 23:32:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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(); |
Joe Fernandez | 069bc4a | 2012-10-04 11:43:09 -0700 | [diff] [blame] | 544 | } |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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 | application’s 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) |
Joe Fernandez | 069bc4a | 2012-10-04 11:43:09 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 3a77ccc | 2012-06-24 23:58:25 -0700 | [diff] [blame] | 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> |