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