Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit e3eeeb6d authored by Joe Fernandez's avatar Joe Fernandez Committed by Android (Google) Code Review
Browse files

Merge "docs: Remove Android Open Accessory docs, which are now on... 

Merge "docs: Remove Android Open Accessory docs, which are now on source.android.com" into jb-dev-docs
parents 688447e5 069bc4a3

docs/html/tools/adk/adk2.jd

+13 −10
Original line number Diff line number Diff line
@@ -28,19 +28,22 @@ page.title=Accessory Development Kit 2012 Guide 
    <ol>

      <li><a href="https://developers.google.com/events/io/sessions/gooio2012/128/">

        Google I/O Session Video</a></li>

      <li><a href="aoa.html">Android Open Accessory Protocol</a></li>

      <li><a href="aoa2.html">Android Open Accessory Protocol 2.0</a></li>

      <li><a href="http://source.android.com/tech/accessories/aoap/aoa.html">

        Android Open Accessory Protocol</a></li>

      <li><a href="http://source.android.com/tech/accessories/aoap/aoa2.html">

        Android Open Accessory Protocol 2.0</a></li>

      <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html">

        USB Accessory Dev Guide</a></li>

    </ol>

  </div>

</div>



<p>The Android Accessory Development Kit (ADK) for 2012 is the latest reference implementation of

an <a href="aoa.html">Android Open Accessory</a> device, designed to help Android hardware accessory

builders and software developers create accessories for Android. The ADK 2012 is based on the <a

href="http://arduino.cc">Arduino</a> open source electronics prototyping platform, with some

hardware and software extensions that allow it to communicate with Android devices.</p>

<p>The Android Accessory Development Kit (ADK) for 2012 is the latest reference implementation of an

<a href="http://source.android.com/tech/accessories/index.html">Android Open Accessory</a> device,

designed to help Android hardware accessory builders and software developers create accessories

for Android. The ADK 2012 is based on the <a href="http://arduino.cc">Arduino</a> open source

electronics prototyping platform, with some hardware and software extensions that allow it to

communicate with Android devices.</p>



<p>A limited number of these kits were produced and distributed at the Google I/O 2012 developer

conference. If you did not receive one of these kits, fear not! The specifications and design files
@@ -604,8 +607,8 @@ implementation details.</p> 


<p>One of the important new features introduced with the ADK 2012 is the ability to play audio over

a USB connection. This innovation was introduced as an update to Android Open Accessory (AOA)

<a href="aoa2.html">protocol 2.0</a> and is available on devices running Android 4.1 (API Level 16)

and higher.</p>

<a href="http://source.android.com/tech/accessories/aoap/aoa2.html">protocol 2.0</a> and is

available on devices running Android 4.1 (API Level 16) and higher.</p>



<p>The ADK 2012 provides a reference implementation of this functionality for accessory developers.

No software application is required to be installed on the connected Android device, accessory

docs/html/tools/adk/aoa.jd

deleted100644 → 0
+0 −186
Original line number Diff line number Diff line 
page.title=Android Open Accessory Protocol

@jd:body



<div id="qv-wrapper">

    <div id="qv">

      <h2>In this document</h2>

      <ol>

        <li><a href="#accessory-protocol">Implementing the Android Accessory Protocol</a>

          <ol>

            <li><a href="#wait">Wait for and detect connected devices</a></li>

            <li><a href="#determine">Determine the device's accessory mode support</a></li>

            <li><a href="#start">Attempt to start the device in accessory mode</a></li>

            <li><a href="#establish">Establish communication with the device</a></li>

        </li>

      </ol>

      

      <h2>See also</h2>

      <ol>

        <li><a href="aoa2.html">Android Open Accessory Protocol 2.0</a></li>

        <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html">USB Accessory Dev

Guide</a></li>

      </ol>

    </div>

  </div>



  <p>With Android 3.1, the platform introduces Android Open Accessory

  support, which allows external USB hardware (an Android USB accessory) to interact with an

  Android-powered device in a special accessory mode. When an Android-powered powered device is

  in accessory mode, the connected accessory acts as the USB host (powers the bus and enumerates

  devices) and the Android-powered device acts as the USB device. Android USB accessories are

  specifically designed to attach to Android-powered devices and adhere to a simple protocol

  (Android accessory protocol) that allows them to detect Android-powered devices that support

  accessory mode. Accessories must also provide 500mA at 5V for charging power. Many previously

  released Android-powered devices are only capable of acting as a USB device and cannot initiate

  connections with external USB devices. Android Open Accessory support overcomes this limitation

  and allows you to build accessories that can interact with an assortment of Android-powered

  devices by allowing the accessory to initiate the connection.</p>



  <p class="note"><strong>Note:</strong> Accessory mode is ultimately dependent on the device's

  hardware and not all devices support accessory mode. Devices that support accessory mode can

  be filtered using a <code>&lt;uses-feature&gt;</code> element in your corresponding application's

  Android manifest. For more information, see the <a href=

  "{@docRoot}guide/topics/connectivity/usb/accessory.html#manifest">USB Accessory</a> developer

guide.</p>



  <h2 id="accessory-protocol">Implementing the Android Accessory Protocol</h2>



  <p>An Android USB accessory must adhere to Android Accessory Protocol, which defines how

  an accessory detects and sets up communication with an Android-powered device. In general, an

  accessory should carry out the following steps:</p>



  <ol>

    <li>Wait for and detect connected devices</li>



    <li>Determine the device's accessory mode support</li>



    <li>Attempt to start the device in accessory mode if needed</li>



    <li>Establish communication with the device if it supports the Android accessory protocol</li>

  </ol>



  <p>The following sections go into depth about how to implement these steps.</p>



  <h3 id="wait">Wait for and detect connected devices</h3>



  <p>Your accessory should have logic to continuously check

  for connected Android-powered devices. When a device is connected, your accessory should

  determine if the device supports accessory mode.</p>



  <h3 id="determine">Determine the device's accessory mode support</h3>





  <p>When an Android-powered device is connected, it can be in one of three states:</p>



  <ol type="a">

    <li>The attached device supports Android accessory mode and is already in accessory mode.</li>



    <li>The attached device supports Android accessory mode, but it is not in accessory mode.</li>



    <li>The attached device does not support Android accessory mode.</li>

  </ol>



  <p>During the initial connection, the accessory should check the vendor and product IDs of the

  connected device's USB device descriptor. The vendor ID should match Google's ID (0x18D1) and the

  product ID should be 0x2D00 or 0x2D01 if the device is already in accessory mode (case A). If so,

  the accessory can now <a href="#establish">establish communication with the device</a> through

  bulk transfer endpoints with its own communication protocol. There is no need to start the device

  in accessory mode.</p>



  <p class="note"><strong>Note:</strong> 0x2D00 is reserved for Android-powered devices that

  support accessory mode. 0x2D01 is reserved for devices that support accessory mode as well as the

  ADB (Android Debug Bridge) protocol, which exposes a second interface with two bulk endpoints for

  ADB. You can use these endpoints for debugging the accessory application if you are simulating

  the accessory on a computer. In general, do not use this interface unless your accessory is

  implementing a passthrough to ADB on the device.</p>



  <p>If the vendor and product ID do not match, there is no way to distinguish between states b and

  c, so the accessory <a href="#start">attempts to start the device in accessory mode</a> to figure

  out if the device is supported.</p>



  <h3 id="start">Attempt to start the device in accessory mode</h3>



  <p>If the vendor and product IDs do not correspond to an Android-powered device in accessory

  mode, the accessory cannot discern whether the device supports accessory mode and is not in that

  state, or if the device does not support accessory mode at all. This is because devices that

  support accessory mode but aren't in it initially report the device's manufacturer vendor ID and

  product ID, and not the special Android Open Accessory ones. In either case, the accessory should

try to start

  the device into accessory mode to figure out if the device supports it. The following steps

  explain how to do this:</p>



  <ol>

    <li>Send a 51 control request ("Get Protocol") to figure out if the device supports the Android

    accessory protocol. A non-zero number is returned if the protocol is supported, which

    represents the version of the protocol that the device supports (currently, only version 1

    exists). This request is a control request on endpoint 0 with the following characteristics:

      <pre>

requestType:    USB_DIR_IN | USB_TYPE_VENDOR

request:        51

value:          0

index:          0

data:           protocol version number (16 bits little endian sent from the device to the

accessory)

</pre>

    </li>



    <li>If the device returns a proper protocol version, send identifying string information to the

    device. This information allows the device to figure out an appropriate application for this

    accessory and also present the user with a URL if an appropriate application does not exist.

    These requests are control requests on endpoint 0 (for each string ID) with the following

    characteristics:

      <pre>

requestType:    USB_DIR_OUT | USB_TYPE_VENDOR

request:        52

value:          0

index:          string ID

data            zero terminated UTF8 string sent from accessory to device

</pre>



      <p>The following string IDs are supported, with a maximum size of 256 bytes for each string

      (must be zero terminated with \0).</p>

      <pre>

manufacturer name:  0

model name:         1

description:        2

version:            3

URI:                4

serial number:      5

</pre>

    </li>



    <li>When the identifying strings are sent, request the device start up in accessory mode. This

    request is a control request on endpoint 0 with the following characteristics:

      <pre>

requestType:    USB_DIR_OUT | USB_TYPE_VENDOR

request:        53

value:          0

index:          0

data:           none

</pre>

    </li>

  </ol>



  <p>After sending the final control request, the connected USB device should re-introduce itself

  on the bus in accessory mode and the accessory can re-enumerate the connected devices. The

  algorithm jumps back to <a href="#determine">determining the device's accessory mode support</a>

  to check for the vendor and product ID. The vendor ID and product ID of the device will be

  different if the device successfully switched to accessory mode and will now correspond to

  Google's vendor and product IDs instead of the device manufacturer's IDs. The accessory can now

  <a href="#establish">establish communication with the device</a>.</p>



  <p>If at any point these steps fail, the device does not support Android accessory mode and the

  accessory should wait for the next device to be connected.</p>



  <h3 id="establish">Establish communication with the device</h3>



  <p>If an Android-powered device in accessory mode is detected, the accessory can query the

  device's interface and endpoint descriptors to obtain the bulk endpoints to communicate with the

  device. An Android-powered device that has a product ID of 0x2D00 has one interface with two bulk

  endpoints for input and output communication. A device with product ID of 0x2D01 has two

  interfaces with two bulk endpoints each for input and output communication. The first interface

  is for standard communication while the second interface is for ADB communication. To communicate

  on an interface, all you need to do is find the first bulk input and output endpoints, set the

  device's configuration to a value of 1 with a SET_CONFIGURATION (0x09) device request, then

  communicate using the endpoints.</p>

docs/html/tools/adk/aoa2.jd

deleted100644 → 0
+0 −227
Original line number Diff line number Diff line 
page.title=Android Open Accessory Protocol 2.0

@jd:body



<div id="qv-wrapper">

  <div id="qv">

    <h2>In this document</h2>

    <ol>

      <li><a href="#detecting">Detecting Android Open Accessory 2.0 Support</a></li>

      <li><a href="#audio-support">Audio Support</a></li>

      <li><a href="#hid">HID Support</a></li>

      <li><a href="#interop-aoa">Interoperability with AOA 1.0 Features</a></li>

      <li><a href="#no-app-conn">Connecting AOA 2.0 without an Android App</a></li>

    </ol>



    <h2>See also</h2>

    <ol>

      <li><a href="aoa.html">Android Open Accessory Protocol</a></li>

    </ol>

  </div>

</div>



<p>This document describes the changes to the Android Open Accessory (AOA) protocol since its

initial release, and is a supplement to the documentation of the <a href="aoa.html">first

release of AOA</a>.</p>



<p>The Android Open Accessory Protocol 2.0 adds two new features: audio output (from the Android

device to the accessory) and support for the accessory acting as one or more human interface devices

(HID) to the Android device. The Android SDK APIs available to Android application developers

remain unchanged.</p>



<h2 id="detecting">Detecting Android Open Accessory 2.0 Support</h2>



<p>In order for an accessory to determine if a connected Android device supports accessories and at

what protocol level, the accessory must send a {@code getProtocol()} command and check the result.

Android devices supporting the initial version of the Android Open Accessory protocol return a

{@code 1}, representing the protocol version number. Devices that support the new features described

in this document must return {@code 2} for the protocol version. Version 2.0 of the protocol is

upwardly compatible, so accessories designed for the original accessory protocol still work

with newer Android devices. The following code from the <a href="adk.html">Android Development Kit

2011</a> {@code AndroidAccessory} library demonstrates this protocol check:</p>



<pre>

bool AndroidAccessory::switchDevice(byte addr)

{

    int protocol = getProtocol(addr);

    if (protocol >= 1) {

        Serial.print("device supports protocol 1 or higher\n");

    } else {

        Serial.print("could not read device protocol version\n");

        return false;

    }



    sendString(addr, ACCESSORY_STRING_MANUFACTURER, manufacturer);

    sendString(addr, ACCESSORY_STRING_MODEL, model);

    sendString(addr, ACCESSORY_STRING_DESCRIPTION, description);

    sendString(addr, ACCESSORY_STRING_VERSION, version);

    sendString(addr, ACCESSORY_STRING_URI, uri);

    sendString(addr, ACCESSORY_STRING_SERIAL, serial);



    usb.ctrlReq(addr, 0, USB_SETUP_HOST_TO_DEVICE | USB_SETUP_TYPE_VENDOR |

USB_SETUP_RECIPIENT_DEVICE,

                ACCESSORY_START, 0, 0, 0, 0, NULL);

    return true;

}

</pre>



<p>AOA 2.0 includes new USB product IDs, one for each combination of USB interfaces available when

in accessory mode. The possible USB interfaces are:</p>



<ul>

  <li><strong>accessory</strong> - An interface providing 2 bulk endpoints for communicating with an

Android application.</li>

  <li><strong>audio</strong> -A new standard USB audio class interface for streaming audio

from an Android device to an accessory.</li>

  <li><strong>adb</strong> - An interface intended only for debugging purposes while developing an

accessory. Only enabled if the user has USB Debugging enabled in Settings on the Android device.

  </li>

</ul>



<p>In AOA 1.0, there are only two USB product IDs:</p>



<ul>

  <li>{@code 0x2D00} - accessory</li>

  <li>{@code 0x2D01} - accessory + adb</li>

</ul>



<p>AOA 2.0 adds an optional USB audio interface and, therefore, includes product IDs for the new

combinations of USB interfaces:</p>



<ul>

  <li>{@code 0x2D02} - audio</li>

  <li>{@code 0x2D03} - audio + adb</li>

  <li>{@code 0x2D04} - accessory + audio</li>

  <li>{@code 0x2D05} - accessory + audio + adb</li>

</ul>



<h2 id="audio-support">Audio Support</h2>



<p>AOA 2.0 includes optional support for audio output from an Android device to an accessory. This

version of the protocol supports a standard USB audio class interface that is capable of 2 channel

16-bit PCM audio with a bit rate of 44100 Khz. AOA 2.0 is currently limited to this output mode, but

additional audio modes may be added in the future.</p>



<p>To enable the audio support, the accessory must send a new USB control request:</p>



<pre>

<strong>SET_AUDIO_MODE</strong>

requestType:    USB_DIR_OUT | USB_TYPE_VENDOR

request:        58

value:          0 for no audio (default),

                1 for 2 channel, 16-bit PCM at 44100 KHz

index:          0

data            none

</pre>



<p>This command must be sent <em>before</em> sending the {@code ACCESSORY_START} command for

entering accessory mode.</p>



<h2 id="hid">HID Support</h2>



<p>AOA 2.0 allows the accessory to register one or more HID devices with

an Android device. This approach reverses the direction of communication for typical USB HID

devices like USB mice and keyboards. Normally, the HID device is a peripheral connected to a USB

host like a personal computer. But in the case of the AOA protocol, the USB host acts as one or more

input devices to a USB peripheral.</p>



<p>HID support in AOA 2.0 is simply a proxy for standard HID events. The implementation makes no

assumptions about the content or type of events and merely passes it through to the input system, 

so an AOA 2.0 accessory can act as any HID device (mouse, keyboard, game controller, etc.). It

can be used for something as simple as the play/pause button on a media dock, or something as

complicated as a docking station with a mouse and full QWERTY keyboard.</p>



<p>The AOA 2.0 protocol adds four new USB control requests to allow the accessory to act as one or

more HID input devices to the Android device.  Since HID support is done entirely through

control requests on endpoint zero, no new USB interface is needed to provide this support. The

control requests are as follows:</p>



<ul>

  <li><strong>ACCESSORY_REGISTER_HID</strong> registers a new HID device with the Android device.

The accessory provides an ID number that is used to identify the HID device for the other three

calls. This ID is valid until USB is disconnected or until the accessory sends

ACCESSORY_UNREGISTER_HID to unregister the HID device.</li>

  <li><strong>ACCESSORY_UNREGISTER_HID</strong> unregisters a HID device that was previously

registered with ACCESSORY_REGISTER_HID.</li>

  <li><strong>ACCESSORY_SET_HID_REPORT_DESC</strong> sends a report descriptor for a HID device to

the Android device. This request is used to describe the capabilities of the HID device, and must

be sent before reporting any HID events to the Android device. If the report descriptor is larger

than the maximum packet size for endpoint zero, multiple ACCESSORY_SET_HID_REPORT_DESC commands are

sent in order to transfer the entire descriptor.</li>

  <li><strong>ACCESSORY_SEND_HID_EVENT</strong> sends input events from the accessory to the Android

device.</li>

</ul>



<p>The code definitions for these new control requests are as follows:</p>



<pre>

/* Control request for registering a HID device.

 * Upon registering, a unique ID is sent by the accessory in the

 * value parameter. This ID will be used for future commands for

 * the device

 *

 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR

 *  request:        ACCESSORY_REGISTER_HID_DEVICE

 *  value:          Accessory assigned ID for the HID device

 *  index:          total length of the HID report descriptor

 *  data            none

 */

#define ACCESSORY_REGISTER_HID         54



/* Control request for unregistering a HID device.

 *

 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR

 *  request:        ACCESSORY_REGISTER_HID

 *  value:          Accessory assigned ID for the HID device

 *  index:          0

 *  data            none

 */

#define ACCESSORY_UNREGISTER_HID         55



/* Control request for sending the HID report descriptor.

 * If the HID descriptor is longer than the endpoint zero max packet size,

 * the descriptor will be sent in multiple ACCESSORY_SET_HID_REPORT_DESC

 * commands. The data for the descriptor must be sent sequentially

 * if multiple packets are needed.

 *

 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR

 *  request:        ACCESSORY_SET_HID_REPORT_DESC

 *  value:          Accessory assigned ID for the HID device

 *  index:          offset of data in descriptor

 *                      (needed when HID descriptor is too big for one packet)

 *  data            the HID report descriptor

 */

#define ACCESSORY_SET_HID_REPORT_DESC         56



/* Control request for sending HID events.

 *

 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR

 *  request:        ACCESSORY_SEND_HID_EVENT

 *  value:          Accessory assigned ID for the HID device

 *  index:          0

 *  data            the HID report for the event

 */

#define ACCESSORY_SEND_HID_EVENT         57

</pre>



<h2 id="interop-aoa">Interoperability with AOA 1.0 Features</h2>



<p>The original <a href="aoa.html">AOA protocol</a> provided support for an Android application to

communicate directly with a USB host (accessory) over USB. AOA 2.0 keeps that support, but adds new

features to allow the accessory to communicate with the Android operating system itself

(specifically the audio and input systems). The design of the AOA 2.0 makes it is possible to build

an accessory that also makes use of the new audio and/or HID support in addition to the original

feature set. Simply use the new features described in this document in addition to the original AOA

protocol features.</p>



<h2 id="no-app-conn">Connecting AOA 2.0 without an Android App</h2>



<p>It is possible to design an accessory (for example, an audio dock) that uses the new audio and

HID support, but does not need to communicate with an application on the Android device. In that

case, the user would not want to see the dialog prompts related to finding and associating the newly

attached accessory with an Android application that can communicate with it. To prevent these

dialogs from appearing after the device and accessory are connected, the accessory can simply not

send the manufacturer and model names to the Android device. If these strings are not provided to

the Android device, then the accessory is able to make use of the new audio and HID support in AOA

2.0 without the system attempting to find an application to communicate with the accessory. Also,

if these strings are not provided, the accessory USB interface is not present in the Android

device USB configuration after the device enters accessory mode.</p>
 
 No newline at end of file

docs/html/tools/adk/index.jd

+5 −10
Original line number Diff line number Diff line
@@ -11,9 +11,11 @@ devices, weather stations, or any other external hardware device that adds to th 
Android.</p>



<p>Accessories use the Android Open Accessory (AOA) protocol to communicate with Android

devices, over USB cable or through a Bluetooth connection. If you are building an accessory for

Android devices, make sure you review the information below to understand about how to implement the

AOA protocol.</p>

devices, over a USB cable or through a Bluetooth connection. If you are building an accessory that

uses USB, make sure you understand how to implement the AOA protocol to establish  communication

between your accessory hardware and Android. For more information, see the

<a href="http://source.android.com/tech/accessories/index.html">Android Open Acessory protocol</a>.

</p>



<p>The following sections provide more information about the Android Accessory Development Kits, how

to use them, and how to get started building your own accessories for Android.</p>
@@ -24,11 +26,4 @@ to use them, and how to get started building your own accessories for Android.</ 


  <dt><a href="adk.html">ADK 2011 Guide</a></dt>

  <dd>Guide to getting started with the original ADK, released at Google I/O 2011.</dd>



  <dt><a href="aoa.html">Android Open Accessory Protocol</a></dt>

  <dd>Guide to implementing the Android Open Accessory Protocol.</dd>



  <dt><a href="aoa2.html">Android Open Accessory Protocol 2.0</a></dt>

  <dd>A description and guide to implementing the extended Android Open Accessory Protocol which

  supports audio dock accessories.</dd>

</dl>

docs/html/tools/tools_toc.cs

+0 −8
Original line number Diff line number Diff line
@@ -213,14 +213,6 @@ class="en">USB Drivers</span></a> 
    <ul>

      <li><a href="<?cs var:toroot ?>tools/adk/adk2.html">ADK 2012 Guide</a></li>

      <li><a href="<?cs var:toroot ?>tools/adk/adk.html">ADK 2011 Guide</a></li>

      <li class="nav-section">

        <div class="nav-section-header">

        <a href="<?cs var:toroot ?>tools/adk/aoa.html">Android Open Accessory Protocol</a>

        </div>

        <ul>

          <li><a href="<?cs var:toroot ?>tools/adk/aoa2.html">AOA 2.0</a></li>

        </ul>

      </li>

    </ul>

  </li>