1 <html devsite> 2 <head> 3 <title>Android Open Accessory Protocol 2.0</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 <p>This document describes changes in the Android Open Accessory (AOA) protocol 26 since its initial release and supplements 27 <a href="aoa.html">AOA 1.0 documentation</a>. AOAv2 28 adds the following features:</p> 29 30 <ul> 31 <li>Audio output (from the Android device to the accessory).</li> 32 <li>Support for the accessory acting as one or more Human Interface Devices 33 (HID) to the Android device.</li> 34 </ul> 35 36 <p>Android SDK APIs available to Android application developers are unchanged. 37 </p> 38 39 40 <h2 id="detecting-android-open-accessory-20-support">Detecting AOAv2 support</h2> 41 42 <p>To determine if a connected Android device supports accessories and the 43 supported protocol version, an accessory must send a <code>getProtocol()</code> 44 command and check the result. Android devices that support only the feautures 45 in AOAv1 must return <code>1</code> as the protocol version; devices that 46 support the additional feautres in AOAv2 must return <code>2</code> as the 47 protocol version. AOAv2 is backward-compatible with AOAv1, so accessories 48 designed for the original accessory protocol continue to work with newer Android 49 devices.</p> 50 51 <p>The following example from the Accessory Development Kit 2011 52 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">source code</a> 53 (<code><adk-src>/adk1/board/AndroidAccessory/AndroidAccessory.cpp</code>) 54 library demonstrates this protocol check:</p> 55 56 <pre class="devsite-click-to-copy"> 57 bool AndroidAccessory::switchDevice(byte addr) 58 { 59 int protocol = getProtocol(addr); 60 if (protocol >= 1) { 61 Serial.print("device supports protocol 1 or higher\n"); 62 } else { 63 Serial.print("could not read device protocol version\n"); 64 return false; 65 } 66 67 sendString(addr, ACCESSORY_STRING_MANUFACTURER, manufacturer); 68 sendString(addr, ACCESSORY_STRING_MODEL, model); 69 sendString(addr, ACCESSORY_STRING_DESCRIPTION, description); 70 sendString(addr, ACCESSORY_STRING_VERSION, version); 71 sendString(addr, ACCESSORY_STRING_URI, uri); 72 sendString(addr, ACCESSORY_STRING_SERIAL, serial); 73 74 usb.ctrlReq(addr, 0, USB_SETUP_HOST_TO_DEVICE | USB_SETUP_TYPE_VENDOR | 75 USB_SETUP_RECIPIENT_DEVICE, ACCESSORY_START, 0, 0, 0, 0, NULL); 76 return true; 77 } 78 </pre> 79 80 <p>AOAv2 includes new USB product IDs for each combination of USB interfaces 81 available in accessory mode:</p> 82 83 <table id="AOA-version-comparison"> 84 <tbody> 85 86 <tr> 87 <th>Version</th> 88 <th>Product ID</th> 89 <th>Communication</th> 90 <th>Description</th> 91 </tr> 92 93 <tr> 94 <td rowspan="2">AOAv1</td> 95 <td><code>0x2D00</code></td> 96 <td>accessory</td> 97 <td>Provides two bulk endpoints for communicating with an Android 98 application.</td> 99 </tr> 100 101 <tr> 102 <td><code>0x2D01</code></td> 103 <td>accessory + adb</td> 104 <td>For debugging purposes during accessory development. Available only if the 105 user has enabled <em>USB Debugging</em> in the Android device settings.</td> 106 </tr> 107 108 <tr> 109 <td rowspan="4">AOAv2</td> 110 <td><code>0x2D02</code></td> 111 <td>audio</td> 112 <td>For streaming audio from an Android device to an accessory.</td> 113 </tr> 114 115 <tr> 116 <td><code>0x2D03</code></td> 117 <td>audio + adb</td> 118 <td></td> 119 </tr> 120 121 <tr> 122 <td><code>0x2D04</code></td> 123 <td>accessory + audio</td> 124 <td></td> 125 </tr> 126 127 <tr> 128 <td><code>0x2D05</code></td> 129 <td>accessory + audio + adb</td> 130 <td></td> 131 </tr> 132 133 </tbody> 134 </table> 135 136 137 <p>Product IDs used in AOAv1 (<code>0x2D00</code> and <code>0x2D01</code>) 138 continue to be supported in AOAv2.</p> 139 140 <h2 id="audio-support">Audio support</h2> 141 142 <p>AOAv2 includes support for audio output from an Android device to an 143 accessory via a standard USB audio class interface capable of 2 channel, 16-bit 144 PCM audio with a bit rate of 44100 Khz (additional audio modes may be added in 145 the future).</p> 146 147 <p>To enable audio support, the accessory must send a new USB control request: 148 </p> 149 150 <pre class="devsite-click-to-copy"> 151 **SET_AUDIO_MODE** 152 requestType: USB_DIR_OUT | USB_TYPE_VENDOR 153 request: 58 154 value: 0 for no audio (default), 155 1 for 2 channel, 16-bit PCM at 44100 KHz 156 index: 0 157 data none 158 </pre> 159 160 <p>This command must be sent <em>before</em> sending the 161 <code>ACCESSORY_START</code> command for entering accessory mode.</p> 162 163 <h2 id="hid-support">HID support</h2> 164 165 <p>AOAv2 allows accessories to register one or more USB Human Interface 166 Devices (HID) with an Android device. This approach reverses the direction of 167 communication for typical USB HID devices such as USB mice and keyboards. 168 Normally, the HID device is a peripheral connected to a USB host (i.e. a 169 personal computer), but in AOA the USB host can act as one or more input 170 devices to a USB peripheral.</p> 171 172 <p>HID support is a proxy for standard HID events; the 173 implementation makes no assumptions about the content or type of events and 174 simply passes it through to the input system, enabling an AOAv2 accessory to 175 act as any HID device (mouse, keyboard, game controller, etc.). You can use HID 176 support to provide basic functionality, such as a play/pause button on a media 177 dock, or for advanced functionality such as a docking station with a mouse and 178 full QWERTY keyboard.</p> 179 180 <p>AOAv2 adds new USB control requests that allow the accessory to act as 181 one or more HID input devices to the Android device. HID support is handled 182 entirely through control requests on endpoint zero, so no new USB interface is 183 needed. The four new control requests are:</p> 184 185 <ul> 186 <li><strong>ACCESSORY_REGISTER_HID</strong> registers a new HID device with the 187 Android device. The accessory provides an ID used to identify the HID device for 188 the other three calls. This ID is valid until USB disconnects or until the 189 accessory sends <code>ACCESSORY_UNREGISTER_HID</code> to unregister the HID 190 device.</li> 191 <li><strong>ACCESSORY_UNREGISTER_HID</strong> unregisters a HID device 192 previously registered with <code>ACCESSORY_REGISTER_HID</code>.</li> 193 <li><strong>ACCESSORY_SET_HID_REPORT_DESC</strong> sends a report descriptor for 194 a HID device to the Android device. This request is used to describe the 195 capabilities of the HID device and must be sent before reporting any HID events 196 to the Android device. If the report descriptor is larger than the maximum 197 packet size for endpoint zero, multiple 198 <code>ACCESSORY_SET_HID_REPORT_DESC</code> commands are sent to transfer the 199 entire descriptor.</li> 200 <li><strong>ACCESSORY_SEND_HID_EVENT</strong> sends input events from the 201 accessory to the Android device.</li> 202 </ul> 203 204 <p>The code definitions for the new control requests are:</p> 205 206 <pre class="devsite-click-to-copy"> 207 /* Control request for registering a HID device. 208 * Upon registering, a unique ID is sent by the accessory in the 209 * value parameter. This ID will be used for future commands for 210 * the device 211 * 212 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 213 * request: ACCESSORY_REGISTER_HID_DEVICE 214 * value: Accessory assigned ID for the HID device 215 * index: total length of the HID report descriptor 216 * data none 217 */ 218 #define ACCESSORY_REGISTER_HID 54 219 220 /* Control request for unregistering a HID device. 221 * 222 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 223 * request: ACCESSORY_REGISTER_HID 224 * value: Accessory assigned ID for the HID device 225 * index: 0 226 * data none 227 */ 228 #define ACCESSORY_UNREGISTER_HID 55 229 230 /* Control request for sending the HID report descriptor. 231 * If the HID descriptor is longer than the endpoint zero max packet size, 232 * the descriptor will be sent in multiple ACCESSORY_SET_HID_REPORT_DESC 233 * commands. The data for the descriptor must be sent sequentially 234 * if multiple packets are needed. 235 * 236 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 237 * request: ACCESSORY_SET_HID_REPORT_DESC 238 * value: Accessory assigned ID for the HID device 239 * index: offset of data in descriptor 240 * (needed when HID descriptor is too big for one packet) 241 * data the HID report descriptor 242 */ 243 #define ACCESSORY_SET_HID_REPORT_DESC 56 244 245 /* Control request for sending HID events. 246 * 247 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 248 * request: ACCESSORY_SEND_HID_EVENT 249 * value: Accessory assigned ID for the HID device 250 * index: 0 251 * data the HID report for the event 252 */ 253 #define ACCESSORY_SEND_HID_EVENT 57 254 </pre> 255 256 <h2 id="interoperability-with-aoa-10-features">Interoperability with AOAv1</h2> 257 258 <p>The original protocol (<a href="aoa.html">AOAv1</a>) 259 provides support for an Android application to communicate directly with a USB 260 host (accessory) over USB. AOAv2 continues this support and adds new features 261 to allow the accessory to communicate with the Android operating system itself 262 (specifically the audio and input systems). The design of AOAv2 makes it 263 possible to build an accessory that uses the new audio and HID support 264 in addition to the original feature set. Simply use the new features along with 265 the original features.</p> 266 267 <h2 id="connecting-aoa-20-without-an-android-app">Connecting AOAv2 without an 268 Android app</h2> 269 270 <p>You can design an accessory (such as an audio dock) that uses audio and HID 271 support but does not communicate with an application on the Android device. For 272 these accessories, users do not need to receive dialog prompts for finding and 273 associating the newly attached accessory with an Android application that can 274 communicate with it.</p> 275 276 <p>To suppress such dialogs after an accessory connects, the 277 accessory can choose not to send the manufacturer and model names to the Android 278 device. When these strings are not provided to the Android device:</p> 279 280 <ul> 281 <li>The system does not attempt to find an application to communicate with the 282 accessory.</li> 283 <li>The accessory USB interface is not present in the Android device USB 284 configuration after the device enters accessory mode.</li> 285 </ul> 286 287 </body> 288 </html> 289
