From 069bc4a3b69a45b13bc23e7e01cd514b5ac49aa1 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Thu, 4 Oct 2012 11:43:09 -0700 Subject: docs: Remove Android Open Accessory docs, which are now on source.android.com Change-Id: I5346de7e575304523d33a94329792fb1a37db89b --- docs/html/tools/adk/adk2.jd | 23 +++-- docs/html/tools/adk/aoa.jd | 186 ----------------------------------- docs/html/tools/adk/aoa2.jd | 227 ------------------------------------------- docs/html/tools/adk/index.jd | 15 +-- docs/html/tools/tools_toc.cs | 8 -- 5 files changed, 18 insertions(+), 441 deletions(-) delete mode 100644 docs/html/tools/adk/aoa.jd delete mode 100644 docs/html/tools/adk/aoa2.jd (limited to 'docs/html/tools') diff --git a/docs/html/tools/adk/adk2.jd b/docs/html/tools/adk/adk2.jd index d5be8ab..0b18583 100644 --- a/docs/html/tools/adk/adk2.jd +++ b/docs/html/tools/adk/adk2.jd @@ -28,19 +28,22 @@ page.title=Accessory Development Kit 2012 Guide
  1. Google I/O Session Video
    2. -
  2. Android Open Accessory Protocol
    3. -
  3. Android Open Accessory Protocol 2.0
    4. +
  4. + Android Open Accessory Protocol
    5. +
  5. + Android Open Accessory Protocol 2.0
  6. USB Accessory Dev Guide
-

The Android Accessory Development Kit (ADK) for 2012 is the latest reference implementation of -an Android Open Accessory device, designed to help Android hardware accessory -builders and software developers create accessories for Android. The ADK 2012 is based on the Arduino open source electronics prototyping platform, with some -hardware and software extensions that allow it to communicate with Android devices.

+

The Android Accessory Development Kit (ADK) for 2012 is the latest reference implementation of an +Android Open Accessory device, +designed to help Android hardware accessory builders and software developers create accessories +for Android. The ADK 2012 is based on the Arduino open source +electronics prototyping platform, with some hardware and software extensions that allow it to +communicate with Android devices.

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 @@ -537,7 +540,7 @@ void loop() { L.accessorySend(outmsg, outmsgLen); } L.adkEventProcess(); -} +}

For more details, review the implementations of these methods in the {@code clock.ino} @@ -604,8 +607,8 @@ implementation details.

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) -protocol 2.0 and is available on devices running Android 4.1 (API Level 16) -and higher.

+protocol 2.0 and is +available on devices running Android 4.1 (API Level 16) and higher.

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 diff --git a/docs/html/tools/adk/aoa.jd b/docs/html/tools/adk/aoa.jd deleted file mode 100644 index 7884d6e..0000000 --- a/docs/html/tools/adk/aoa.jd +++ /dev/null @@ -1,186 +0,0 @@ -page.title=Android Open Accessory Protocol -@jd:body - -

- -
- -

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.

- -

Note: 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 <uses-feature> element in your corresponding application's - Android manifest. For more information, see the USB Accessory developer -guide.

- -

Implementing the Android Accessory Protocol

- -

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:

- -
    -
  1. Wait for and detect connected devices
    2. - -
  2. Determine the device's accessory mode support
    3. - -
  3. Attempt to start the device in accessory mode if needed
    4. - -
  4. Establish communication with the device if it supports the Android accessory protocol
    5. -
- -

The following sections go into depth about how to implement these steps.

- -

Wait for and detect connected devices

- -

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.

- -

Determine the device's accessory mode support

- - -

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

- -
    -
  1. The attached device supports Android accessory mode and is already in accessory mode.
    2. - -
  2. The attached device supports Android accessory mode, but it is not in accessory mode.
    3. - -
  3. The attached device does not support Android accessory mode.
    4. -
- -

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 establish communication with the device through - bulk transfer endpoints with its own communication protocol. There is no need to start the device - in accessory mode.

- -

Note: 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.

- -

If the vendor and product ID do not match, there is no way to distinguish between states b and - c, so the accessory attempts to start the device in accessory mode to figure - out if the device is supported.

- -

Attempt to start the device in accessory mode

- -

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:

- -
    -
  1. 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: - 
    -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)
-
    -
    2. - -
  2. 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: - 
    -requestType:    USB_DIR_OUT | USB_TYPE_VENDOR
-request:        52
-value:          0
-index:          string ID
-data            zero terminated UTF8 string sent from accessory to device
-
    - -

    The following string IDs are supported, with a maximum size of 256 bytes for each string - (must be zero terminated with \0).

    - 
    -manufacturer name:  0
-model name:         1
-description:        2
-version:            3
-URI:                4
-serial number:      5
-
    -
    3. - -
  3. 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: - 
    -requestType:    USB_DIR_OUT | USB_TYPE_VENDOR
-request:        53
-value:          0
-index:          0
-data:           none
-
    -
    4. -
- -

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 determining the device's accessory mode support - 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 - establish communication with the device.

- -

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.

- -

Establish communication with the device

- -

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.

- diff --git a/docs/html/tools/adk/aoa2.jd b/docs/html/tools/adk/aoa2.jd deleted file mode 100644 index bbccfc3..0000000 --- a/docs/html/tools/adk/aoa2.jd +++ /dev/null @@ -1,227 +0,0 @@ -page.title=Android Open Accessory Protocol 2.0 -@jd:body - -
- -
- -

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 first -release of AOA.

- -

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.

- -

Detecting Android Open Accessory 2.0 Support

- -

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 Android Development Kit -2011 {@code AndroidAccessory} library demonstrates this protocol check:

- -
-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;
-}
-
- -

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:

- - - -

In AOA 1.0, there are only two USB product IDs:

- - - -

AOA 2.0 adds an optional USB audio interface and, therefore, includes product IDs for the new -combinations of USB interfaces:

- - - -

Audio Support

- -

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.

- -

To enable the audio support, the accessory must send a new USB control request:

- -
-SET_AUDIO_MODE
-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
-
- -

This command must be sent before sending the {@code ACCESSORY_START} command for -entering accessory mode.

- -

HID Support

- -

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.

- -

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.

- -

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:

- - - -

The code definitions for these new control requests are as follows:

- -
-/* 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
-
- -

Interoperability with AOA 1.0 Features

- -

The original AOA protocol 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.

- -

Connecting AOA 2.0 without an Android App

- -

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.

\ No newline at end of file diff --git a/docs/html/tools/adk/index.jd b/docs/html/tools/adk/index.jd index 4b9b042..d492e96 100644 --- a/docs/html/tools/adk/index.jd +++ b/docs/html/tools/adk/index.jd @@ -11,9 +11,11 @@ devices, weather stations, or any other external hardware device that adds to th Android.

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.

+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 +Android Open Acessory protocol. +

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.

@@ -24,11 +26,4 @@ to use them, and how to get started building your own accessories for Android.ADK 2011 Guide
Guide to getting started with the original ADK, released at Google I/O 2011.
- -
Android Open Accessory Protocol
-
Guide to implementing the Android Open Accessory Protocol.
- -
Android Open Accessory Protocol 2.0
-
A description and guide to implementing the extended Android Open Accessory Protocol which - supports audio dock accessories.
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 5e2b9f7..cca9433 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -213,14 +213,6 @@ class="en">USB Drivers -- cgit v1.1