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