diff options
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 1 | ||||
| -rw-r--r-- | docs/html/tools/adk/adk.jd (renamed from docs/html/guide/topics/connectivity/usb/adk.jd) | 250 | ||||
| -rw-r--r-- | docs/html/tools/adk/adk2.jd | 617 | ||||
| -rw-r--r-- | docs/html/tools/adk/aoa.jd | 186 | ||||
| -rw-r--r-- | docs/html/tools/adk/aoa2.jd | 227 | ||||
| -rw-r--r-- | docs/html/tools/adk/index.jd | 34 | ||||
| -rw-r--r-- | docs/html/tools/tools_toc.cs | 20 |
7 files changed, 1108 insertions, 227 deletions
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 44b977e..0b677c9 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -407,7 +407,6 @@ <ul> <li><a href="<?cs var:toroot ?>guide/topics/connectivity/usb/accessory.html">Accessory</a></li> <li><a href="<?cs var:toroot ?>guide/topics/connectivity/usb/host.html">Host</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/connectivity/usb/adk.html">Open Accessory Dev Kit</a></li> </ul> </li> <li><a href="<?cs var:toroot?>guide/topics/connectivity/sip.html"> diff --git a/docs/html/guide/topics/connectivity/usb/adk.jd b/docs/html/tools/adk/adk.jd index 034728c..2a0c717 100644 --- a/docs/html/guide/topics/connectivity/usb/adk.jd +++ b/docs/html/tools/adk/adk.jd @@ -1,4 +1,4 @@ -page.title=Android Open Accessory Development Kit +page.title=Accessory Development Kit 2011 Guide @jd:body <div id="qv-wrapper"> @@ -24,21 +24,6 @@ page.title=Android Open Accessory Development Kit </li> <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 connected 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> - </ol> - </li> - - <li> <a href="#firmware">How the ADK board implements the Android Accessory Protocol</a> <ol> @@ -66,72 +51,26 @@ page.title=Android Open Accessory Development Kit <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html">USB Accessory Dev Guide</a></li> </ol> - <h2>Where to buy</h2> - - <ol> - - <li><a href="http://store.arduino.cc/"> - Arduino Store</a></li> - - <li><a href="https://store.diydrones.com/ProductDetails.asp?ProductCode=BR-PhoneDrone"> - DIY Drones</a></li> - - <li><a href= - "http://mbed.org/order/"> - mbed</a></li> - - <li><a href= - "http://www.microchip.com/android"> - Microchip</a></li> - - <li><a href="http://shop.moderndevice.com/products/freeduino-usb-host-board"> - Modern Device</a></li> - - <li><a href= - "http://www.rt-net.jp/shop/index.php?main_page=product_info&cPath=3_4&products_id=1"> - RT Corp</a></li> - - <li><a href="http://www.seeedstudio.com/depot/seeeduino-adk-main-board-p-846.html"> - Seeed Studio</a></li> - - <li><a href="http://www.sparkfun.com/products/10748"> - SparkFun</a></li> - - <li><a href="http://troido.de/de/shoplsmallgbuy-android-stufflsmallg"> - Troido</a></li> - - </ol> </div> </div> - <p>The Android 3.1 platform (also backported to Android 2.3.4) 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 will support accessory mode. Devices that support accessory mode can - be filtered using a <code><uses-feature></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> - - <p>The following list of distributers are currently producing Android Open Accessory compatible - development boards:</p> + <p>The Android Open Accessory Development Kit (ADK) is a reference implementation of an Android + Open Accessory, based on the <a href="http://www.arduino.cc/">Arduino open source electronics + prototyping platform</a>. The accessory's hardware design files, code that implements the + accessory's firmware, and the Android application that interacts with the accessory are provided + as part of the kit to help hardware builders and software developers get started building their + own accessories. The hardware design files and firmware code are contained in the <a href= + "https://dl-ssl.google.com/android/adk/adk_release_20120606.zip">ADK package download</a>.</p> - <ul> + <p>A limited number of kits were produced and distributed at the Google I/O 2011 developer + conference. However, many hardware builders have reproduced and enhanced the original design and + these boards are available for purchase. The following list of distributors are currently + producing Android Open Accessory compatible development boards:</p> - <li>The <a href="http://store.arduino.cc/">Arduino Store</a> provides the Arduino Mega ADK - (in <a href="http://store.arduino.cc/eu/index.php?main_page=product_info&cPath=11_12&products_id=144">EU nations</a> - or <a href="http://store.arduino.cc/ww/index.php?main_page=product_info&cPath=11_12&products_id=144">non-EU nations</a>) - that is based on the ATmega2560 and supports the ADK firmware.</li> + <ul> + <li>The <a href="http://store.arduino.cc/">Arduino Store</a> provides the <a +href="http://arduino.cc/en/Main/ArduinoBoardADK">Arduino Mega ADK</a> (for EU nations or non- + EU nations) that is based on the ATmega2560 and supports the ADK firmware.</li> <li><a href="https://store.diydrones.com/ProductDetails.asp?ProductCode=BR-PhoneDrone">DIY Drones</a> provides an Arduino-compatible board geared towards RC (radio controlled) and UAV @@ -157,18 +96,16 @@ page.title=Android Open Accessory Development Kit <li><a href="http://www.sparkfun.com/products/10748"> SparkFun</a>'s IOIO board now has beta support for the ADK firmware.</li> + <li><a href="http://troido.de/de/shoplsmallgbuy-android-stufflsmallg">Troido</a> has produced an + Arduino-compatible version of the ADK hardware.</li> + </ul> <p>We expect more hardware distributers to create a variety of kits, so please stay tuned for further developments.</p> <h2 id="components">ADK Components</h2> - <p>The Android Open Accessory Development Kit (ADK) provides an implementation of an Android USB - accessory that is based on the <a href="http://www.arduino.cc/">Arduino open source electronics - prototyping platform</a>, the accessory's hardware design files, code that implements the - accessory's firmware, and the Android application that interacts with the accessory. The hardware - design files and firmware code are contained in the <a href= - "https://dl-ssl.google.com/android/adk/adk_release_20120606.zip">ADK package download</a>.</p> + <p>The main hardware and software components of the ADK include:</p> <ul> @@ -421,145 +358,6 @@ page.title=Android Open Accessory Development Kit accessories communicate with Android-powered devices describe much of what you should be doing in your own accessory.</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> - <h2 id="firmware">How the ADK board implements the Android Accessory protocol</h2> <p>If you have access to the ADK board and shield, the following sections describe the firmware @@ -667,8 +465,10 @@ bool AndroidAccessory::isConnected(void) <p>If the device is not already in accessory mode, then the ADK board must determine whether or not it supports it by sending control request 51 to check the version of the USB accessory protocol that the device supports (see <code>AndroidAccessory::getProtocol()</code>). Protocol - version 1 is the only version for now, but this can be an integer greater than zero in the - future. If the appropriate protocol version is returned, the board sends control request 52 (one + version 1 is supported by Android 2.3.4 (API Level 10) and higher. Protocol version 2 is + supported by Android 4.1 (API Level 16) and higher. Versions greater than 2 may supported in + the future. + If the appropriate protocol version is returned, the board sends control request 52 (one for each string with <code>AndroidAcessory:sendString()</code>) to send it's identifying information, and tries to start the device in accessory mode with control request 53. The <code>AndroidAccessory::switchDevice()</code> method takes care of this:</p> @@ -676,7 +476,7 @@ bool AndroidAccessory::isConnected(void) bool AndroidAccessory::switchDevice(byte addr) { int protocol = getProtocol(addr); - if (protocol == 1) { + if (protocol >= 1) { Serial.print("device supports protocol 1\n"); } else { Serial.print("could not read device protocol version\n"); diff --git a/docs/html/tools/adk/adk2.jd b/docs/html/tools/adk/adk2.jd new file mode 100644 index 0000000..d3fed30 --- /dev/null +++ b/docs/html/tools/adk/adk2.jd @@ -0,0 +1,617 @@ +page.title=Accessory Development Kit 2012 Guide +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#components">Components</a></li> + <li><a href="#clock">Using the Alarm Clock</a></li> + <li><a href="#play-audio">Playing Audio</a></li> + <li><a href="#dev">Developing Accessories with ADK 2012</a> + <ol> + <li><a href="#src-download">Downloading the ADK Source</a></li> + <li><a href="#dev-setup">Setting Up the Development Environment</a></li> + <li><a href="#alt-build">Using the ADK Alternative Build System</a></li> + </ol> + </li> + <li><a href="#adk-conn">How the ADK Connects with Android Devices</a> + <ol> + <li><a href="#adk-conn-bt">ADK Connection over Bluetooth</a></li> + <li><a href="#adk-conn-usb">ADK Connection over USB</a></li> + </ol> + </li> + <li><a href="#audio-dock">USB Audio Dock Implementation</a></li> + </ol> + + <h2>See also</h2> + <ol> + <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="{@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>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 +for the hardware were also released for use by manufacturers and hobbyists. You should expect to see +kits with similar features available for purchase, or you can build one yourself!</p> + +<p>One of the important new features demonstrated by this ADK is the ability to play audio over a +USB connection. Be sure to check out the <a href="#audio-dock">reference implementation</a> of a USB +audio dock in this ADK if you are interested in making audio-related USB accessories for +Android.</p> + +<h2 id="components">Components</h2> + +<p>The ADK 2012 is based on the Arduino open source electronics prototyping platform and is an open +hardware design. The hardware design files and firmware source code are included with the ADK +software download. The ADK contains two main physical hardware components:</p> + +<ol> + <li>Main processing board containing the microprocessor, USB connections, power connector and +input/output pins. This board can be removed and used separately from the rest of the hardware.</li> + <li>Shield containing sensors, LEDs, input controls, audio amplifier and speaker output, contained +in a custom, polygon box enclosure.</li> +</ol> + +<p>The main hardware features of the ADK are as follows:</p> + +<ul> + <li>An ARM 32-bit Cortex M3 micro-processor</li> + <li>Separate USB connections for an Android device and computer connection for programming and +debugging</li> + <li>Sensors for light, color, proximity, temperature, humidity, barometric pressure, and +acceleration</li> + <li>Micro SD Card slot</li> + <li>Bluetooth support</li> +</ul> + +<p>The ADK comes preloaded with an alarm clock firmware program that you can use immediately. A +companion Android application, <a +href="https://play.google.com/store/apps/details?id=com.google.android.apps.adk2">ADK 2012</a>, is +available on Google Play. The source code for both the Android application and the ADK firmware (an +Arduino sketch) can be downloaded from this page.</p> + +<p>The ADK 2012 also comes with additional parts to help you develop accessories with it, +including:</p> + +<ul> + <li>AC power adapter</li> + <li>USB A to Micro USB B connector cable</li> + <li>Micro USB B to Micro USB AB connector (small, rectangular plug)</li> + <li>Micro SD Card, preinstalled in the ADK SD Card socket</li> +</ul> + +<h2 id="clock">Using the Alarm Clock</h2> + +<p>An alarm clock program comes preloaded on the ADK. This firmware program allows you to use the +ADK as an alarm clock.</p> + +<p>To use the ADK as an alarm clock:</p> + +<ol> + <li>Open up the ADK by gently squeezing the two widest faces of the enclosure.</li> + <li>Attach the provided AC power adapter (round connector) to the main ADK board, or attach a USB +cable to the port marked <strong>Computer</strong> and a USB port on your computer.</li> + <li>Place and hold your fingertip over the clock symbol on the control face. + <p class="note"><strong>Note:</strong> You may need to hold your finger in place for 1-2 +seconds.</p> + </li> + <li>Use the plus (+) and minus (-) symbols inside the clock digits to set the correct time.</li> + <li>Place your fingertip over the alarm clock symbol to activate alarm setting.</li> + <li>Use the plus (+) and minus (-) symbols inside the clock digits to set the alarm time.</li> + <li>Use the plus (+) and minus (-) symbols inside the last two clock digits to turn the alarm on +({@code on}) or off ({@code oF}).</li> + <li>To set the alarm tone, place and hold your fingertip over the alarm clock symbol, then tap the +slider control on top of the enclosure.</li> +</ol> + +<p>To use the <strong>ADK 2012</strong> companion application for the alarm clock:</p> + +<ol> + <li>Load the companion application on your Android device running Android 3.1 (API Level 12) or +higher: + <ul> + <li>Using an NFC-enabled Android device, unlock and hold the device against the left side of +the ADK enclosure. Follow the prompts to install the app. + <br>- or -</li> + <li>Start Google Play on your device, search for the <strong>ADK 2012</strong> application and +install it. If you cannot find the app, your device is not compatible. Try installing on another +device.</li> + </ul> + </li> + <li>Connect your Android device to the ADK using one of the following methods: + <ul> + <li id="conn-bt">To connect using Bluetooth: + <ol> + <li>Plug the AC power adapter into the ADK.</li> + <li>On your Android device, turn Bluetooth On (<strong>Settings > +Bluetooth</strong>).</li> + <li>In the <strong>Settings</strong> page, press the <strong>Bluetooth</strong> option to +view paired devices.</li> + <li>Select <strong>Search for Devices</strong> to locate the ADK 2012 accessory and follow +the on screen instructions to connect.</li> + <li>After pairing is complete, start the <strong>ADK 2012</strong> app on your Android +device.</li> + <li>On the start screen, select the <strong>Use Bluetooth</strong> button.</li> + <li>In the list of paired devices, select the <strong>ADK 2012</strong> device.</li> + <li>The <strong>ADK 2012</strong> app should switch to the menu screen and you can start +interacting with the ADK accessory.</li> + </ol> + </li> + + <li id="conn-usb">To connect using USB: + <ol> + <li>Plug the AC power adapter into the ADK.</li> + <li>Connect the Micro USB AB connector (small, rectangular plug) to the port labeled +<strong>Phone</strong> on the ADK board.</li> + <li>Unlock your Android device and connect the Micro USB B connector to your device. + <p class="note"><strong>Note:</strong> Your device must support Android USB accessory +mode. Devices that support this mode include Google Nexus devices.</p> + </li> + <li>On the Android device, you should see a prompt to connect to the <strong>ADK DemoKit +2012</strong>, select <strong>OK</strong>.</li> + <li>The <strong>ADK 2012</strong> app should start automatically and you can start +interacting with the ADK.</li> + </ol> + </li> + </ul> + </li> +</ol> + +<p class="note"><strong>Note:</strong> When using the ADK with a USB connection to an Android +device, make sure the AC power adapter is plugged in. A USB connection to a computer does not +provide sufficient voltage to power both the ADK and a USB connection to a device.</p> + + +<h2 id="play-audio">Playing Audio</h2> + +<p>The ADK 2012 comes with audio output capabilities, including an amplifier and speaker. You can +use it to play audio from your Android device using either a Bluetooth or USB connection.</p> + +<p>To play audio over Bluetooth:</p> + +<ol> + <li>Follow the instructions in the <a href="#conn-bt">previous section</a> to connect your Android +device to the ADK over Bluetooth.</li> + <li>On your Android device, navigate to the <strong>Settings > Bluetooth</strong> page to view the +list of paired devices, and make sure the ADK is connected.</li> + <li>Select the settings icon next to the <strong>ADK 2012</strong> item.</li> + <li>Make sure the <strong>Media Audio</strong> option is enabled.</li> + <li>Navigate to an application that plays music or other audio.</li> + <li>Play a song or sound and listen to it on the ADK speaker!</li> +</ol> + +<p>To play audio over USB, you must use a device running Android 4.1 (API Level 16) or higher:</p> + +<ol> + <li>Plug the AC power adapter into the ADK.</li> + <li>Connect the Micro USB AB connector (small, rectangular plug) to the Phone port on the ADK +board.</li> + <li>Unlock your Android device and connect the Micro USB B connector to your device. + <p class="note"><strong>Note:</strong> Your device must support Android USB accessory +mode. Devices that support this mode include Google Nexus devices.</p> + </li> + <li>On the Android device, you should see a prompt to connect to the <strong>ADK DemoKit +2012</strong>, select <strong>Cancel</strong> and allow the ADK to connect as a media device +only.</li> + <li>Navigate to an application that plays music or other audio.</li> + <li>Play a song or sound and listen to it on the ADK speaker!</li> +</ol> + +<p class="note"><strong>Note:</strong> When using the ADK with a USB connection to an Android +device, make sure the AC power adapter is plugged in. A USB connection to a computer does not +provide sufficient voltage to power both the ADK and a USB connection to a device.</p> + + +<h2 id="dev">Developing Accessories with ADK 2012</h2> + +<p>The ADK 2012 is a hardware platform and a set of software libraries for prototyping Android +accessories. This section discusses how to set up a development environment for programming the ADK +to make it do what you want and to test software for building your own Android accessories.</p> + +<h3 id="src-download">Downloading the ADK Source</h3> + +<p>The support software and hardware specifications for the ADK 2012 are available from the Android +source repository. Follow the instructions below to obtain the source material for the ADK.</p> + +<p>To download the ADK 2012 software, source code and hardware design specifications.</p> + +<ol> + <li>Download and install <a href="http://git-scm.com/download">Git</a> for your development +system.</li> + <li>Download and setup the {@code repo} tool, as described on the <a +href="http://source.android.com/source/downloading.html#installing-repo">Android open source +project</a> site.</li> + <li>In a terminal window, create a new directory for the downloaded source files, initialize and +synchronize a local repository: +<pre> +$> mkdir android-accessories +$> cd android-accessories +$> repo -init -u https://android.googlesource.com/platform/manifest -b android-accessories +$> repo sync +</pre> + </li> +</ol> + +<p>After successfully completing this process, you should have the source code and tools for +working with the ADK 2012:</p> + +<ul> + <li>{@code adk2012/board} - Source code and hardware design files for the ADK 2012</li> + <li>{@code adk2012/app} - Source code for the ADK 2012 Android companion application</li> + <li>{@code external/ide} - Source code for the ADK 2012 Integrated Development Environment +(IDE)</li> + <li>{@code external/toolchain} - The toolchain used by the ADK 2012 IDE</li> +</ul> + + +<h3 id="dev-setup">Setting Up the Development Environment</h3> + +<p>The ADK 2012 source code repository includes an integrated development environment (IDE) that you +can use to develop software for and program the ADK 2012 accessory. The following instructions +explain how to build and run the ADK 2012 IDE.</p> + +<p>To set up, build and run the ADK 2012 IDE:</p> + +<ol> + <li><a href="#src-download">Download</a> the ADK 2012 source code files.</li> + <li>Download and install the Java Development Kit 6 or higher from <a +href="http://java.oracle.com">java.oracle.com</a>.</li> + <li>Download and install <a href="http://ant.apache.org/">Apache Ant</a>.</li> + <li>In a terminal window, navigate to {@code <adk-source-download>/external/ide/build} +and execute the following command to build the ADK 2012 IDE: +<pre>$> ant</pre> + </li> + <li>After the build successfully completes, execute the following command to run the ADK 2012 +IDE: +<pre>$> ant run</pre></li> +</ol> + +<p>After you have successfully built and run the ADK 2012 IDE, you must configure it to use the +ADK 2012 library.</p> + +<p>To configure the ADK 2012 IDE for use with the ADK libraries:</p> + +<ol> + <li>Start the ADK 2012 IDE and choose <strong>File > Preferences</strong>.</li> + <li>In the <strong>Preferences</strong> dialog, make a note of the <strong>Sketchbook +location</strong> directory.</li> + <li>Copy the {@code <adk-source-download>/adk2012/board/library/ADK2} directory and its +contents into your {@code sketchbook/libraries/} directory, so that you create a {@code +sketchbook/libraries/ADK2} directory.</li> + <li>Stop and restart the <strong>ADK 2012 IDE</strong>.</li> + <li>In the IDE, choose <strong>File > Examples > ADK2</strong> and then choose one of the example +sketches: + <ul> + <li><strong>clock</strong> - The sketch that is preloaded onto the ADK 2012.</li> + <li><strong>BluetoothScan</strong> - An example sketch demonstrating code that connects an +accessory to an Android device over Bluetooth.</li> + <li><strong>usbaccessory</strong> - An example sketch demonstrating code that connects an +accessory to an Android device through a USB cable.</li> + </ul> + </li> + <li>Connect a Micro USB cable from the <strong>Computer</strong> port on the ADK board to your +development computer.</li> + <li>In the <strong>ADK 2012 IDE</strong>, establish a serial port connection with the ADK by +selecting <strong>Tools > Serial Port</strong> and selecting the serial port for the ADK.</li> + <li>In the <strong>ADK 2012 IDE</strong>, choose the ADK by selecting<strong>Tools > Board > +Google ADK2</strong>.</li> + <li>Modify an example sketch or create your own.</li> + <li>Upload the sketch to the ADK by choosing <strong>File > Upload</strong>. When the <strong>ADK +2012 IDE</strong> reports <strong>Done uploading</strong>, the sketch is uploaded and the ADK is +ready to communicate with your Android device.</li> +</ol> + +<h3 id="alt-build">Using the ADK Alternative Build System</h3> + +<p>An alternative build and load system is also available for the ADK 2012. This system is command +line based and intended for production environments where using an IDE environment to load software +onto accessory hardware may be inconvenient or undesirable.</p> + +<p>To use the command line based build system:</p> +<ol> + <li><a href="#src-download">Download</a> the ADK 2012 source code files.</li> + <li>Download and install the <a href="http://www.gnu.org/software/make/">make</a> tool on your +development system.</li> + <li>Update your system’s PATH to include {@code +<adk-source-download>/external/toolchain/bin}.</li> + <li>Open a terminal window, navigate to {@code +<adk-source-download>/external/toolchain/app} and execute the following command: + <pre>$> make</pre></li> +</ol> + +<h2 id="adk-conn">How the ADK Connects with Android Devices</h2> + +<p>The essential feature of any Android accessory is its ability to connect and communicate with an +Android device. Creating a fast and reliable connection between your accessory and Android devices +is the first order of business when building software for an accessory. This section describes the +connection and communication essentials used in the ADK 2012 so that you can apply them to +developing your own Android accessories.</p> + +<h3 id="adk-conn-bt">ADK Connection over Bluetooth</h3> + +<p>The ADK 2012 app and hardware accessory use a Bluetooth Serial Port Profile (SPP) connection to +communicate. This connection allows two way communication between the ADK accessory and Android +devices.</p> + +<p class="note"><strong>Note:</strong> The implementation of the ADK hardware allows the use of +other profiles and multiple connections. However, the basic communication between the ADK 2012 +accessory and the Android application uses SPP.</p> + +<h4 id="acc-bt-code">Accessory Bluetooth Code</h4> + +<p>In order to enable Bluetooth communications, the {@code clock.ino} sketch for the ADK 2012 +accessory calls a {@code btStart()} method during the {@code setup()} method to enable radio +frequency communications and start listening for Bluetooth connections:</p> + +<pre> +ADK L; +void setup() { + L.adkInit(); + L.btStart(); +} +... +void btStart(){ + uint8_t i, dlci; + int f; + + L.btEnable(adkBtConnectionRequest, adkBtLinkKeyRequest, adkBtLinkKeyCreated, + adkBtPinRequest, NULL); + + dlci = L.btRfcommReserveDlci(RFCOMM_DLCI_NEED_EVEN); + + if(!dlci) dbgPrintf("BTADK: failed to allocate DLCI\n"); + else{ + + //change descriptor to be valid... + for(i = 0, f = -1; i < sizeof(sdpDescrADK); i++){ + + if(sdpDescrADK[i] == MAGIX){ + if(f == -1) f = i; + else break; + } + } + + if(i != sizeof(sdpDescrADK) || f == -1){ + + dbgPrintf("BTADK: failed to find a single marker in descriptor\n"); + L.btRfcommReleaseDlci(dlci); + return; + } + + sdpDescrADK[f] = dlci >> 1; + + dbgPrintf("BTADK has DLCI %u\n", dlci); + + L.btRfcommRegisterPort(dlci, btAdkPortOpen, btAdkPortClose, btAdkPortRx); + L.btSdpServiceDescriptorAdd(sdpDescrADK, sizeof(sdpDescrADK)); + } +} +</pre> + +<p>Notice that the {@code sdpDescrADK} object contains a Universally Unique Identifier (UUID) in the +variable {@code BT_ADK_UUID}. This identifier <em>must match</em> the device UUID provided in the +{@link android.bluetooth.BluetoothSocket} connection request in the Android application code.</p> + +<p>Once Bluetooth is enabled with the code shown above, the accessory listens for connection +requests. The ADK library handles listening and connection details, so the accessory calls +{@code ADK::adkEventProcess()} once during each loop execution:</p> + +<pre> +void loop(void) +{ + ... + L.adkEventProcess(); //let the adk framework do its thing + ... +} +</pre> + +<p>If a Bluetooth connection has been established, any commands are routed to the +{@code btAdkPortRx()} callback method (which was registered with the ADK library as part of the +{@code btStart()} method) and processed accordingly. The ADK accessory sends messages back through +the Bluetooth connection using the {@code ADK::btRfcommPortTx()} method. +For more details, review the implementations of these methods in the {@code clock.ino} sketch.</p> + +<h4 id="app-bt-code">Android App Bluetooth Code</h4> + +<p>In the ADK 2012 Android app, the code for handling Bluetooth connections is encapsulated in in a +{@code BTConnection} class. In this class, the application requests access to the Bluetooth adapter +and negotiates a connection with the ADK 2012 accessory. Here is a summary of the relevant code:</p> + +<pre> +mAdapter = BluetoothAdapter.getDefaultAdapter(); +BluetoothDevice device = mAdapter.getRemoteDevice(address); +mSocket = device.createInsecureRfcommSocketToServiceRecord(ADK_UUID); +mSocket.connect(); +</pre> + +<p>Note the {@code ADK_UUID} parameter in the second line. This identifier must match the identifier +output by the accessory (the {@code BT_ADK_UUID} variable mentioned earlier), otherwise the protocol +negotiation fails and the {@link android.bluetooth.BluetoothSocket} is not created. Once a +connection is established, you obtain {@link java.io.InputStream} and {@link java.io.OutputStream} +objects from the socket to communicate with the accessory:</p> + +<pre> +mInStream = mSocket.getInputStream(); +mOutStream = mSocket.getOutputStream(); +</pre> + +<p>Review the {@code BTConnection.java} file provided in the ADK 2012 software download for more +implementation details.</p> + +<h3 id="adk-conn-usb">ADK Connection over USB</h3> + +<p>The ADK 2012 app and hardware accessory can also use a USB connection to communicate, similar to +the original ADK.</p> + +<h4 id="acc-usb-code">Accessory USB Code</h4> + +<p>The ADK library takes care of most of the implementation details for a USB connection, the +accessory code must make a few calls to initialize USB connectivity, including setting the accessory +identification strings:</p> + +<pre> +ADK L; +void setup() { + L.adkInit(); + L.usbSetAccessoryStringVendor(...); + L.usbSetAccessoryStringName(...); + L.usbSetAccessoryStringLongname(...); + L.usbSetAccessoryStringVersion(...); + L.usbSetAccessoryStringUrl(...); + L.usbSetAccessoryStringSerial(...); + + L.usbStart(); +} +</pre> + +<p class="note"><strong>Note:</strong> The identification strings must match the USB accessory +filter settings specified in the connecting Android application,otherwise the application cannot +connect with the accessory.</p> + +<p>Once USB is enabled with code shown above, the accessory listens for connection requests. The ADK +library handles listening and connection details, so the accessory calls {@code +ADK::adkEventProcess()} once during each loop execution:</p> + +<pre> +void loop(void) +{ + ... + L.adkEventProcess(); //let the adk framework do its thing + ... +} +</pre> + +<p>The accessory must then check for a live USB connection to process commands and send +messages. Here is a summary of the relevant code:</p> + +<pre> +void loop() { + if (L.accessoryConnected()) { + int recvLen = L.accessoryReceive(msg, sizeof(msg)); + if (recvLen > 0) { + ... // process message + } + + L.accessorySend(outmsg, outmsgLen); + } + L.adkEventProcess(); +} +</pre> + +<p>For more details, review the implementations of these methods in the {@code clock.ino} +sketch.</p> + +<h4 id="app-usb-code">Android App USB Code</h4> + +<p>In the ADK 2012 Android app, the code for handling USB connections is encapsulated in a +{@code UsbConnection} class. This class sets up a {@link android.content.BroadcastReceiver} to +listen for USB events and then attempts to connect when a matching connection event is received. +Here is a summary of the relevant code:</p> + +<pre> +import com.android.future.usb.UsbAccessory; +import com.android.future.usb.UsbManager; + +mUSBManager = UsbManager.getInstance(this); +UsbAccessory acc = mUSBManager.getAccessoryList()[0]; + +if (!mUSBManager.hasPermission(acc)) return; +</pre> + +<p>The ADK 2012 app uses the support library to implement the USB accessory connections, in order to +support devices running Android 2.3.4 (API Level 10). If you only need to support Android +3.1 (API Level 12) and higher devices, you can replace the first 4 lines the following code:</p> + +<pre> +import android.hardware.usb.UsbAccessory +import android.hardware.usb.UsbManager + +mUSBManager = (UsbManager) getSystemService(Context.USB_SERVICE); +UsbAccessory acc = (UsbAccessory) + intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); +</pre> + +<p>Note that the app only receives events when the USB accessory identification information matches +the information in the {@code res/xml/usb_accessory_filter.xml} file, referenced by the +application’s manifest statement:</p> + +<pre> +<meta-data + android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" + android:resource="@xml/usb_accessory_filter" /> +</pre> + +<p>Connections from other USB devices are not received by the ADK 2012 accessory.</p> + +<p>Once the connection is established, the app can communicate with the accessory through file input +and output streams, as shown in the following example code:</p> + +<pre> +ParcelFileDescriptor mFD = mUSBManager.openAccessory(acc); +if (mFD != null) { + FileDescripter fd = mFD.getFileDescriptor(); + mIS = new FileInputStream(fd); // use this to receive messages + mOS = new FileOutputStream(fd); // use this to send commands +} +</pre> + +<p>Review the {@code UsbConnection.java} file provided in the ADK 2012 source code for more +implementation details.</p> + +<h2 id="audio-dock">USB Audio Dock Implementation</h2> + +<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> + +<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 +developers only need to support AOA v2. This implementation demonstrates audio output of 16bit, +44.1kHz stereo PCM source data compressed into a single channel due to the audio hardware available +on the accessory.</p> + +<p>Using the audio output features provided by the ADK library requires only a few function calls. +The first few calls are in the accessory {@code setup()} routine, which prepare the accessory for +USB connections and audio output, as summarized in the code example below:</p> + +<pre> +ADK L; +void setup() { + L.audioInit(); + L.usbh_init() + L.usbStart(); +} +</pre> + +<p>For more information about the {@code ADK::audioInit()} function, see the {@code +libraries/ADK/Audio.c} library file. For more information about the {@code ADK::usbh_init()} +function, see the {@code libraries/ADK/Usbh.c} library file.</p> + +<p>After completing this setup, the {@code loop()} function calls {@code ADK::adkEventProcess()} to +handle audio output and other ADK functions:</p> + +<pre> +void loop(void) +{ + ... + L.adkEventProcess(); //let the adk framework do its thing + ... +} +</pre> + +<p>This call executes task queuing for the ADK and as part of the execution process, the task queue +executes {@code usbh_work()} in {@code libraries/ADK/Usbh.c}, which handles audio output requests. +Review the implementation of this function for details. For additional implementation details on +audio output, see the {@code libraries/ADK/accessory.c} library file.</p> diff --git a/docs/html/tools/adk/aoa.jd b/docs/html/tools/adk/aoa.jd new file mode 100644 index 0000000..7884d6e --- /dev/null +++ b/docs/html/tools/adk/aoa.jd @@ -0,0 +1,186 @@ +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><uses-feature></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> + diff --git a/docs/html/tools/adk/aoa2.jd b/docs/html/tools/adk/aoa2.jd new file mode 100644 index 0000000..2a3b2f0 --- /dev/null +++ b/docs/html/tools/adk/aoa2.jd @@ -0,0 +1,227 @@ +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="oap.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 diff --git a/docs/html/tools/adk/index.jd b/docs/html/tools/adk/index.jd new file mode 100644 index 0000000..4b9b042 --- /dev/null +++ b/docs/html/tools/adk/index.jd @@ -0,0 +1,34 @@ +page.title=Accessory Development Kit +@jd:body + +<p>The Accessory Development Kit (ADK) is a reference implementation for hardware manufacturers and +hobbyists to use as a starting point for building accessories for Android. Each ADK release is +provided with source code and hardware specifications to make the process of developing your own +accessories easier. Creating new and alternative hardware based on the ADK is encouraged!</p> + +<p>Android accessories can be audio docking stations, exercise machines, personal medical testing +devices, weather stations, or any other external hardware device that adds to the functionality of +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> + +<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> + +<dl> + <dt><a href="adk2.html">ADK 2012 Guide</a></dt> + <dd>Guide to getting started with the ADK released at Google I/O 2012.</dd> + + <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> diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 27fbd2d..21d45fa 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -197,12 +197,30 @@ class="en">USB Drivers</span></a> </li> - <li class="nav-section"> <div class="nav-section-header empty"><a href="<?cs var:toroot ?>tools/samples/index.html"><span class="en">Samples</span></a></div> </li> + + <li class="nav-section"> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>tools/adk/index.html"> + <span class="en">ADK</span></a> + </div> + <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> </ul><!-- nav --> |