1 page.title=Android Open Accessory Protocol 2.0 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 <ol> 8 <li><a href="#detecting">Detecting Android Open Accessory 2.0 Support</a></li> 9 <li><a href="#audio-support">Audio Support</a></li> 10 <li><a href="#hid">HID Support</a></li> 11 <li><a href="#interop-aoa">Interoperability with AOA 1.0 Features</a></li> 12 <li><a href="#no-app-conn">Connecting AOA 2.0 without an Android App</a></li> 13 </ol> 14 15 <h2>See also</h2> 16 <ol> 17 <li><a href="aoa.html">Android Open Accessory Protocol</a></li> 18 </ol> 19 </div> 20 </div> 21 22 <p>This document describes the changes to the Android Open Accessory (AOA) protocol since its 23 initial release, and is a supplement to the documentation of the <a href="aoa.html">first 24 release of AOA</a>.</p> 25 26 <p>The Android Open Accessory Protocol 2.0 adds two new features: audio output (from the Android 27 device to the accessory) and support for the accessory acting as one or more human interface devices 28 (HID) to the Android device. The Android SDK APIs available to Android application developers 29 remain unchanged.</p> 30 31 <h2 id="detecting">Detecting Android Open Accessory 2.0 Support</h2> 32 33 <p>In order for an accessory to determine if a connected Android device supports accessories and at 34 what protocol level, the accessory must send a {@code getProtocol()} command and check the result. 35 Android devices supporting the initial version of the Android Open Accessory protocol return a 36 {@code 1}, representing the protocol version number. Devices that support the new features described 37 in this document must return {@code 2} for the protocol version. Version 2.0 of the protocol is 38 upwardly compatible, so accessories designed for the original accessory protocol still work 39 with newer Android devices. The following code from the <a href="adk.html">Android Development Kit 40 2011</a> {@code AndroidAccessory} library demonstrates this protocol check:</p> 41 42 <pre> 43 bool AndroidAccessory::switchDevice(byte addr) 44 { 45 int protocol = getProtocol(addr); 46 if (protocol >= 1) { 47 Serial.print("device supports protocol 1 or higher\n"); 48 } else { 49 Serial.print("could not read device protocol version\n"); 50 return false; 51 } 52 53 sendString(addr, ACCESSORY_STRING_MANUFACTURER, manufacturer); 54 sendString(addr, ACCESSORY_STRING_MODEL, model); 55 sendString(addr, ACCESSORY_STRING_DESCRIPTION, description); 56 sendString(addr, ACCESSORY_STRING_VERSION, version); 57 sendString(addr, ACCESSORY_STRING_URI, uri); 58 sendString(addr, ACCESSORY_STRING_SERIAL, serial); 59 60 usb.ctrlReq(addr, 0, USB_SETUP_HOST_TO_DEVICE | USB_SETUP_TYPE_VENDOR | 61 USB_SETUP_RECIPIENT_DEVICE, 62 ACCESSORY_START, 0, 0, 0, 0, NULL); 63 return true; 64 } 65 </pre> 66 67 <p>AOA 2.0 includes new USB product IDs, one for each combination of USB interfaces available when 68 in accessory mode. The possible USB interfaces are:</p> 69 70 <ul> 71 <li><strong>accessory</strong> - An interface providing 2 bulk endpoints for communicating with an 72 Android application.</li> 73 <li><strong>audio</strong> -A new standard USB audio class interface for streaming audio 74 from an Android device to an accessory.</li> 75 <li><strong>adb</strong> - An interface intended only for debugging purposes while developing an 76 accessory. Only enabled if the user has USB Debugging enabled in Settings on the Android device. 77 </li> 78 </ul> 79 80 <p>In AOA 1.0, there are only two USB product IDs:</p> 81 82 <ul> 83 <li>{@code 0x2D00} - accessory</li> 84 <li>{@code 0x2D01} - accessory + adb</li> 85 </ul> 86 87 <p>AOA 2.0 adds an optional USB audio interface and, therefore, includes product IDs for the new 88 combinations of USB interfaces:</p> 89 90 <ul> 91 <li>{@code 0x2D02} - audio</li> 92 <li>{@code 0x2D03} - audio + adb</li> 93 <li>{@code 0x2D04} - accessory + audio</li> 94 <li>{@code 0x2D05} - accessory + audio + adb</li> 95 </ul> 96 97 <h2 id="audio-support">Audio Support</h2> 98 99 <p>AOA 2.0 includes optional support for audio output from an Android device to an accessory. This 100 version of the protocol supports a standard USB audio class interface that is capable of 2 channel 101 16-bit PCM audio with a bit rate of 44100 Khz. AOA 2.0 is currently limited to this output mode, but 102 additional audio modes may be added in the future.</p> 103 104 <p>To enable the audio support, the accessory must send a new USB control request:</p> 105 106 <pre> 107 <strong>SET_AUDIO_MODE</strong> 108 requestType: USB_DIR_OUT | USB_TYPE_VENDOR 109 request: 58 110 value: 0 for no audio (default), 111 1 for 2 channel, 16-bit PCM at 44100 KHz 112 index: 0 113 data none 114 </pre> 115 116 <p>This command must be sent <em>before</em> sending the {@code ACCESSORY_START} command for 117 entering accessory mode.</p> 118 119 <h2 id="hid">HID Support</h2> 120 121 <p>AOA 2.0 allows the accessory to register one or more HID devices with 122 an Android device. This approach reverses the direction of communication for typical USB HID 123 devices like USB mice and keyboards. Normally, the HID device is a peripheral connected to a USB 124 host like a personal computer. But in the case of the AOA protocol, the USB host acts as one or more 125 input devices to a USB peripheral.</p> 126 127 <p>HID support in AOA 2.0 is simply a proxy for standard HID events. The implementation makes no 128 assumptions about the content or type of events and merely passes it through to the input system, 129 so an AOA 2.0 accessory can act as any HID device (mouse, keyboard, game controller, etc.). It 130 can be used for something as simple as the play/pause button on a media dock, or something as 131 complicated as a docking station with a mouse and full QWERTY keyboard.</p> 132 133 <p>The AOA 2.0 protocol adds four new USB control requests to allow the accessory to act as one or 134 more HID input devices to the Android device. Since HID support is done entirely through 135 control requests on endpoint zero, no new USB interface is needed to provide this support. The 136 control requests are as follows:</p> 137 138 <ul> 139 <li><strong>ACCESSORY_REGISTER_HID</strong> registers a new HID device with the Android device. 140 The accessory provides an ID number that is used to identify the HID device for the other three 141 calls. This ID is valid until USB is disconnected or until the accessory sends 142 ACCESSORY_UNREGISTER_HID to unregister the HID device.</li> 143 <li><strong>ACCESSORY_UNREGISTER_HID</strong> unregisters a HID device that was previously 144 registered with ACCESSORY_REGISTER_HID.</li> 145 <li><strong>ACCESSORY_SET_HID_REPORT_DESC</strong> sends a report descriptor for a HID device to 146 the Android device. This request is used to describe the capabilities of the HID device, and must 147 be sent before reporting any HID events to the Android device. If the report descriptor is larger 148 than the maximum packet size for endpoint zero, multiple ACCESSORY_SET_HID_REPORT_DESC commands are 149 sent in order to transfer the entire descriptor.</li> 150 <li><strong>ACCESSORY_SEND_HID_EVENT</strong> sends input events from the accessory to the Android 151 device.</li> 152 </ul> 153 154 <p>The code definitions for these new control requests are as follows:</p> 155 156 <pre> 157 /* Control request for registering a HID device. 158 * Upon registering, a unique ID is sent by the accessory in the 159 * value parameter. This ID will be used for future commands for 160 * the device 161 * 162 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 163 * request: ACCESSORY_REGISTER_HID_DEVICE 164 * value: Accessory assigned ID for the HID device 165 * index: total length of the HID report descriptor 166 * data none 167 */ 168 #define ACCESSORY_REGISTER_HID 54 169 170 /* Control request for unregistering a HID device. 171 * 172 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 173 * request: ACCESSORY_REGISTER_HID 174 * value: Accessory assigned ID for the HID device 175 * index: 0 176 * data none 177 */ 178 #define ACCESSORY_UNREGISTER_HID 55 179 180 /* Control request for sending the HID report descriptor. 181 * If the HID descriptor is longer than the endpoint zero max packet size, 182 * the descriptor will be sent in multiple ACCESSORY_SET_HID_REPORT_DESC 183 * commands. The data for the descriptor must be sent sequentially 184 * if multiple packets are needed. 185 * 186 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 187 * request: ACCESSORY_SET_HID_REPORT_DESC 188 * value: Accessory assigned ID for the HID device 189 * index: offset of data in descriptor 190 * (needed when HID descriptor is too big for one packet) 191 * data the HID report descriptor 192 */ 193 #define ACCESSORY_SET_HID_REPORT_DESC 56 194 195 /* Control request for sending HID events. 196 * 197 * requestType: USB_DIR_OUT | USB_TYPE_VENDOR 198 * request: ACCESSORY_SEND_HID_EVENT 199 * value: Accessory assigned ID for the HID device 200 * index: 0 201 * data the HID report for the event 202 */ 203 #define ACCESSORY_SEND_HID_EVENT 57 204 </pre> 205 206 <h2 id="interop-aoa">Interoperability with AOA 1.0 Features</h2> 207 208 <p>The original <a href="aoa.html">AOA protocol</a> provided support for an Android application to 209 communicate directly with a USB host (accessory) over USB. AOA 2.0 keeps that support, but adds new 210 features to allow the accessory to communicate with the Android operating system itself 211 (specifically the audio and input systems). The design of the AOA 2.0 makes it is possible to build 212 an accessory that also makes use of the new audio and/or HID support in addition to the original 213 feature set. Simply use the new features described in this document in addition to the original AOA 214 protocol features.</p> 215 216 <h2 id="no-app-conn">Connecting AOA 2.0 without an Android App</h2> 217 218 <p>It is possible to design an accessory (for example, an audio dock) that uses the new audio and 219 HID support, but does not need to communicate with an application on the Android device. In that 220 case, the user would not want to see the dialog prompts related to finding and associating the newly 221 attached accessory with an Android application that can communicate with it. To prevent these 222 dialogs from appearing after the device and accessory are connected, the accessory can simply not 223 send the manufacturer and model names to the Android device. If these strings are not provided to 224 the Android device, then the accessory is able to make use of the new audio and HID support in AOA 225 2.0 without the system attempting to find an application to communicate with the accessory. Also, 226 if these strings are not provided, the accessory USB interface is not present in the Android 227 device USB configuration after the device enters accessory mode.</p>
