Merge "CDD: Make Verified Boot mandatory for devices w/ adquate AES performance" into mnc-dev
diff --git a/src/accessories/accessories_toc.cs b/src/accessories/accessories_toc.cs
index 654ff7b..616cc5e 100644
--- a/src/accessories/accessories_toc.cs
+++ b/src/accessories/accessories_toc.cs
@@ -1,5 +1,5 @@
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -30,9 +30,20 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>accessories/headset-spec.html">Headset specification</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>accessories/headset/index.html">
+ <span class="en">Headset</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>accessories/headset/specification.html">Specification</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/headset/requirements.html">Requirements</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/headset/testing.html">Testing</a></li>
</ul>
- </li>
+ </li>
+ </ul>
+ </li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>accessories/custom.html">
@@ -45,8 +56,8 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>accessories/aoa2.html">Version 2.0</a></li>
- <li><a href="<?cs var:toroot ?>accessories/aoa.html">Version 1.0</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/aoa2.html">AOA 2.0</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/aoa.html">AOA 1.0</a></li>
</ul>
</li>
</ul>
diff --git a/src/accessories/aoa.jd b/src/accessories/aoa.jd
index 7388d54..7c728fe 100644
--- a/src/accessories/aoa.jd
+++ b/src/accessories/aoa.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -16,55 +16,81 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<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>
+<p>Android USB accessories must adhere to the Android Open Accessory (AOA)
+protocol, which defines how an accessory detects and sets up communication with
+an Android-powered device. Accessories should carry out the following steps:</p>
+
<ul>
-<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>
+<li>Wait for and detect a connected device.</li>
+<li>Determine the device's accessory mode support.</li>
+<li>Attempt to start the device in accessory mode (if needed).</li>
+<li>If the device supports AOA, establish communication with the device.</li>
</ul>
+
<p>The following sections explain how to implement these steps.</p>
-<h2 id="wait-for-and-detect-connected-devices">Wait for and Detect Connected Devices</h2>
-<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>
-<h2 id="determine-accessory-mode-support">Determine Accessory Mode Support</h2>
-<p>When an Android-powered device is connected, it can be in one of three states:</p>
+
+<p class="note">When developing a new accessory that connects to an Android
+device over USB, use <a href="{@docRoot}accessories/aoa2.html">AOAv2</a>.</p>
+
+<h2 id="wait-for-and-detect-connected-devices">Wait for and detect connected
+devices</h2>
+
+<p>Accessories should continuously check for connected Android-powered devices.
+When a device is connected, the accessory should determine if the device
+supports accessory mode.</p>
+
+<h2 id="determine-accessory-mode-support">Determine accessory mode support</h2>
+
+<p>When an Android-powered device connects, it can be in one of three states:
+</p>
+
<ul>
-<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>
+<li>Supports Android accessory mode and is already in accessory mode.</li>
+<li>Supports Android accessory mode but it is not in accessory mode.</li>
+<li>Does not support Android accessory mode.</li>
</ul>
-<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 (<code>0x18D1</code>) and the
-product ID should be <code>0x2D00</code> or <code>0x2D01</code> if the device is already in accessory mode (case A). If
-so, the accessory can now
-<a href="#establish-communication-with-the-device">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><strong>Note:</strong> <code>0x2D00</code> is reserved for Android-powered devices that
-support accessory mode. <code>0x2D01</code> 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="#attempt-to-start-in-accessory-mode">attempts to start the device in accessory mode</a>
-to determine if the device is supported.</p>
-<h2 id="attempt-to-start-in-accessory-mode">Attempt to Start in Accessory Mode</h2>
-<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>
+
+<p>During the initial connection, the accessory should check the vendor ID and
+product ID of the connected device's USB device descriptor. The vendor ID
+should match Google's ID (<code>0x18D1</code>). If the device is already in
+accessory mode, the product ID should be <code>0x2D00</code> or
+<code>0x2D01</code> and the accessory can
+<a href="#establish-communication-with-the-device">establish communication with
+the device</a> through bulk transfer endpoints using its own communication
+protocol (the device does not need to be started in accessory mode).</p>
+
+<p class="note"><strong>Note:</strong> <code>0x2D00</code> is reserved for
+Android-powered devices that support accessory mode. <code>0x2D01</code> is
+reserved for devices that support accessory mode as well as the Android Debug
+Bridge (ADB) 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 the accessory implements a passthrough to ADB on the device.
+</p>
+
+<p>If the vendor ID or the product ID found in USB device descriptor do not
+match expected values, the accessory cannot determine if the device supports
+Android accessory mode. The accessory should attempt to start the device in
+accessory mode (detailed below) to determine device support.</p>
+
+<h2 id="attempt-to-start-in-accessory-mode">Attempt to start in accessory
+mode</h2>
+
+<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 (but
+is not in) accessory mode or if the device does not support accessory mode. This
+can occur because devices that support accessory mode (but are not in that mode)
+initially report the <em>device</em> manufacturer vendor and product IDs instead
+of the <em>AOA</em> vendor and product IDs.</p>
+
+<p>The accessory should try to start the device in accessory mode to determine
+if the device supports that mode:</p>
+
<ul>
- <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:
+ <li>Send a 51 control request ("Get Protocol") to determine if the device
+ supports the Android accessory protocol. If the device supports the protocol,
+ it returns a non-zero number that represents the supported protocol version.
+ The control request is on endpoint 0 with the following characteristics:
<pre>
requestType: USB_DIR_IN | USB_TYPE_VENDOR
@@ -75,10 +101,12 @@
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
+
+ <li>If the device returns a supported protocol version, send a control request
+ with identifying string information to the device. This information allows the
+ device to determine an appropriate application for the accessory (or present a
+ URL to the user if an appropriate application does not exist). The control
+ request is on endpoint 0 (for each string ID) with the following
characteristics:
<pre>
@@ -89,8 +117,8 @@
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>
+ <p>The following string IDs are supported, with a maximum size of 256 bytes
+ for each string (must be zero-terminated with <code>\0</code>).</p>
<pre>
manufacturer name: 0
@@ -101,8 +129,9 @@
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:
+
+ <li>Send a control request to ask the device to start in accessory mode. The
+ control request is on endpoint 0 with the following characteristics:
<pre>
requestType: USB_DIR_OUT | USB_TYPE_VENDOR
@@ -114,25 +143,37 @@
</li>
</ul>
-<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-accessory-mode-support">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-communication-with-the-device">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>
-<h2 id="establish-communication-with-the-device">Establish Communication with the Device</h2>
-<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 <code>0x2D00</code> has one interface with two bulk
-endpoints for input and output communication. A device with product ID of <code>0x2D01</code> 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 <code>SET_CONFIGURATION</code> (<code>0x09</code>) device request, then
-communicate using the endpoints.</p>
+<p>After completing these steps, the accessory should wait for the connected USB
+device to re-introduce itself on the bus in accessory mode, then re-enumerate
+connected devices. The algorithm returns to
+<a href="#determine-accessory-mode-support">determine accessory mode support</a>
+to check the vendor and product IDs, which should be correct (e.g. correspond to
+Google's vendor and product IDs instead of the device manufacturer's IDs) if the
+device successfully switched to accessory mode. If IDs are correct, the
+accessory moves to <a href="#establish-communication-with-the-device">establish
+communication with the device</a>.</p>
+
+<p>If any step fails, the accessory determines the device does not support
+Android accessory mode and waits for the next device to connect.</p>
+<h2 id="establish-communication-with-the-device">Establish communication with
+the device</h2>
+
+<p>If the accessory detects an Android-powered device in accessory mode, the
+accessory can query the device interface and endpoint descriptors to obtain the
+bulk endpoints for communicating with the device.</p>
+
+<p>The number of interfaces and bulk endpoints depends on the product ID. An
+Android-powered device with a product ID of:</p>
+
+<ul>
+<li><code>0x2D00</code> has one interface with two bulk endpoints for input and
+output communication.</li>
+<li><code>0x2D01</code> has two interfaces with two bulk endpoints each for
+input and output communication. The first interface handles standard
+communication and the second interface handles ADB communication. To use an
+interface, locate the first bulk input and output endpoints, set the
+device configuration to a value of 1 with a <code>SET_CONFIGURATION</code>
+(<code>0x09</code>) device request, then communicate using the endpoints.</li>
+</ul>
\ No newline at end of file
diff --git a/src/accessories/aoa2.jd b/src/accessories/aoa2.jd
index c48bf25..2cbdc47 100644
--- a/src/accessories/aoa2.jd
+++ b/src/accessories/aoa2.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -16,24 +16,37 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<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="{@docRoot}accessories/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-android-open-accessory-20-support">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()</code> command and check the result.
-Android devices supporting the initial version of the Android Open Accessory protocol return a
-<code>1</code>, representing the protocol version number. Devices that support the new features described
-in this document must return <code>2</code> 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 example from the Accessory Development Kit 2011
+<p>This document describes changes in the Android Open Accessory (AOA) protocol
+since its initial release and supplements
+<a href="{@docRoot}accessories/aoa.html">AOA 1.0 documentation</a>. AOAv2
+adds the following features:</p>
+
+<ul>
+<li>Audio output (from the Android device to the accessory).</li>
+<li>Support for the accessory acting as one or more Human Interface Devices
+(HID) to the Android device.</li>
+</ul>
+
+<p>Android SDK APIs available to Android application developers are unchanged.
+</p>
+
+
+<h2 id="detecting-android-open-accessory-20-support">Detecting AOAv2 support</h2>
+
+<p>To determine if a connected Android device supports accessories and the
+supported protocol version, an accessory must send a <code>getProtocol()</code>
+command and check the result. Android devices that support only the feautures
+in AOAv1 must return <code>1</code> as the protocol version; devices that
+support the additional feautres in AOAv2 must return <code>2</code> as the
+protocol version. AOAv2 is backward-compatible with AOAv1, so accessories
+designed for the original accessory protocol continue to work with newer Android
+devices.</p>
+
+<p>The following example from the Accessory Development Kit 2011
<a href="http://developer.android.com/tools/adk/adk2.html#src-download">source code</a>
-(<code><adk-src>/adk1/board/AndroidAccessory/AndroidAccessory.cpp</code>) library demonstrates this protocol
-check:</p>
+(<code><adk-src>/adk1/board/AndroidAccessory/AndroidAccessory.cpp</code>)
+library demonstrates this protocol check:</p>
+
<pre><code>bool AndroidAccessory::switchDevice(byte addr)
{
int protocol = getProtocol(addr);
@@ -56,35 +69,77 @@
return true;
}
</code></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</code> - accessory</li>
-<li><code>0x2D01</code> - 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</code> - audio</li>
-<li><code>0x2D03</code> - audio + adb</li>
-<li><code>0x2D04</code> - accessory + audio</li>
-<li><code>0x2D05</code> - 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>
+
+<p>AOAv2 includes new USB product IDs for each combination of USB interfaces
+available in accessory mode:</p>
+
+<table id="AOA-version-comparison">
+<tbody>
+
+<tr>
+<th>Version</th>
+<th>Product ID</th>
+<th>Communication</th>
+<th>Description</th>
+</tr>
+
+<tr>
+<td rowspan="2">AOAv1</td>
+<td><code>0x2D00</code></td>
+<td>accessory</td>
+<td>Provides two bulk endpoints for communicating with an Android
+application.</td>
+</tr>
+
+<tr>
+<td><code>0x2D01</code></td>
+<td>accessory + adb</td>
+<td>For debugging purposes during accessory development. Available only if the
+user has enabled <em>USB Debugging</em> in the Android device settings.</td>
+</tr>
+
+<tr>
+<td rowspan="4">AOAv2</td>
+<td><code>0x2D02</code></td>
+<td>audio</td>
+<td>For streaming audio from an Android device to an accessory.</td>
+</tr>
+
+<tr>
+<td><code>0x2D03</code></td>
+<td>audio + adb</td>
+<td></td>
+</tr>
+
+<tr>
+<td><code>0x2D04</code></td>
+<td>accessory + audio</td>
+<td></td>
+</tr>
+
+<tr>
+<td><code>0x2D05</code></td>
+<td>accessory + audio + adb</td>
+<td></td>
+</tr>
+
+</tbody>
+</table>
+
+
+<p>Product IDs used in AOAv1 (<code>0x2D00</code> and <code>0x2D01</code>)
+continue to be supported in AOAv2.</p>
+
+<h2 id="audio-support">Audio support</h2>
+
+<p>AOAv2 includes support for audio output from an Android device to an
+accessory via a standard USB audio class interface capable of 2 channel, 16-bit
+PCM audio with a bit rate of 44100 Khz (additional audio modes may be added in
+the future).</p>
+
+<p>To enable audio support, the accessory must send a new USB control request:
+</p>
+
<pre><code>**SET_AUDIO_MODE**
requestType: USB_DIR_OUT | USB_TYPE_VENDOR
request: 58
@@ -93,39 +148,53 @@
index: 0
data none
</code></pre>
-<p>This command must be sent <em>before</em> sending the <code>ACCESSORY_START</code> command for
-entering accessory mode.</p>
-<h2 id="hid-support">HID Support</h2>
-<p>AOA 2.0 allows the accessory to register one or more USB Human Interface Devices (HID) 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>
+
+<p>This command must be sent <em>before</em> sending the
+<code>ACCESSORY_START</code> command for entering accessory mode.</p>
+
+<h2 id="hid-support">HID support</h2>
+
+<p>AOAv2 allows accessories to register one or more USB Human Interface
+Devices (HID) with an Android device. This approach reverses the direction of
+communication for typical USB HID devices such as USB mice and keyboards.
+Normally, the HID device is a peripheral connected to a USB host (i.e. a
+personal computer), but in AOA the USB host can act as one or more input
+devices to a USB peripheral.</p>
+
+<p>HID support is a proxy for standard HID events; the
+implementation makes no assumptions about the content or type of events and
+simply passes it through to the input system, enabling an AOAv2 accessory to
+act as any HID device (mouse, keyboard, game controller, etc.). You can use HID
+support to provide basic functionality, such as a play/pause button on a media
+dock, or for advanced functionality such as a docking station with a mouse and
+full QWERTY keyboard.</p>
+
+<p>AOAv2 adds new USB control requests that allow the accessory to act as
+one or more HID input devices to the Android device. HID support is handled
+entirely through control requests on endpoint zero, so no new USB interface is
+needed. The four new control requests are:</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
-<code>ACCESSORY_UNREGISTER_HID</code> to unregister the HID device.</li>
-<li><strong>ACCESSORY_UNREGISTER_HID</strong> unregisters a HID device that was previously
-registered with <code>ACCESSORY_REGISTER_HID</code>.</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 <code>ACCESSORY_SET_HID_REPORT_DESC</code> 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
+<li><strong>ACCESSORY_REGISTER_HID</strong> registers a new HID device with the
+Android device. The accessory provides an ID used to identify the HID device for
+the other three calls. This ID is valid until USB disconnects or until the
+accessory sends <code>ACCESSORY_UNREGISTER_HID</code> to unregister the HID
device.</li>
+<li><strong>ACCESSORY_UNREGISTER_HID</strong> unregisters a HID device
+previously registered with <code>ACCESSORY_REGISTER_HID</code>.</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
+<code>ACCESSORY_SET_HID_REPORT_DESC</code> commands are sent 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>
+
+<p>The code definitions for the new control requests are:</p>
+
<pre><code>/* 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
@@ -174,23 +243,34 @@
*/
#define ACCESSORY_SEND_HID_EVENT 57
</code></pre>
-<h2 id="interoperability-with-aoa-10-features">Interoperability with AOA 1.0 Features</h2>
-<p>The original <a href="{@docRoot}accessories/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="connecting-aoa-20-without-an-android-app">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>
+<h2 id="interoperability-with-aoa-10-features">Interoperability with AOAv1</h2>
+
+<p>The original protocol (<a href="{@docRoot}accessories/aoa.html">AOAv1</a>)
+provides support for an Android application to communicate directly with a USB
+host (accessory) over USB. AOAv2 continues this support and adds new features
+to allow the accessory to communicate with the Android operating system itself
+(specifically the audio and input systems). The design of AOAv2 makes it
+possible to build an accessory that uses the new audio and HID support
+in addition to the original feature set. Simply use the new features along with
+the original features.</p>
+
+<h2 id="connecting-aoa-20-without-an-android-app">Connecting AOAv2 without an
+Android app</h2>
+
+<p>You can design an accessory (such as an audio dock) that uses audio and HID
+support but does not communicate with an application on the Android device. For
+these accessories, users do not need to receive dialog prompts for finding and
+associating the newly attached accessory with an Android application that can
+communicate with it.</p>
+
+<p>To suppress such dialogs after an accessory connects, the
+accessory can choose not to send the manufacturer and model names to the Android
+device. When these strings are not provided to the Android device:</p>
+
+<ul>
+<li>The system does not attempt to find an application to communicate with the
+accessory.</li>
+<li>The accessory USB interface is not present in the Android device USB
+configuration after the device enters accessory mode.</li>
+</ul>
\ No newline at end of file
diff --git a/src/accessories/audio.jd b/src/accessories/audio.jd
index 92ce6fe..72c5e1d 100644
--- a/src/accessories/audio.jd
+++ b/src/accessories/audio.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -24,53 +24,67 @@
</div>
</div>
-<p>In implementing an audio accessory, such as a headset, headphone amplifier,
-microphone, DAC/ADC, or dock, you should consider how your accessory will
-connect with Android devices. In particular, you should decide
-if your accessory will use wired a 3.5 mm headset connector, Universal Serial
-Bus (USB), or a Bluetooth connection to stream music or other audio content.</p>
+<p>When implementing an audio accessory such as a headset, headphone amplifier,
+microphone, DAC/ADC, or dock, consider how the accessory connects to Android
+devices. The following sections describe wired 3.5 mm headset connections,
+Universal Serial Bus (USB) connections, and Bluetooth connections for streaming
+music or other audio content.</p>
+
<h2 id="audio-over-35mm">Audio over 3.5 mm headset connector</h2>
-<p>Many Android-based devices include a 3.5 mm (“mini”) headset connector. In
-addition to the traditional stereo output and mono input features, the <a
-href="headset-spec.html">Wired audio headset specification</a> defines standard
-impedances and functions so a range of Android devices and headsets can inter-operate.</p>
+<p>Many Android devices include a 3.5 mm (“mini”) headset connector.
+In addition to traditional stereo output and mono input features, the
+<a href="headset/specification.html">Wired audio headset specification</a>
+defines standard impedances and functions that enable interoperability between
+a range of Android devices and headsets.</p>
<h2 id="audio-over-usb">Audio over USB</h2>
<p>Android can use USB in several modes:</p>
<ul>
- <li>development
- <li>accessory
- <li>host
+ <li><strong>Development</strong>. Does not support audio. </li>
+ <li><strong>Accessory</strong>. Provided by Android Open Accessory (AOA) 2.0
+ and provides limited audio capability, as described in
+ <a href="custom.html#audio-over-usb">Connecting custom audio over USB</a>.
+ </li>
+ <li><strong>Host</strong>. Enables the Android device to drive the USB bus
+ and operate with a wide range of USB-based peripherals, including audio
+ interfaces. Host mode audio is described in
+ <a href="{@docRoot}devices/audio/usb.html">USB Digital Audio</a>.</li>
</ul>
-<p>In the development mode, there is no audio capability.</p>
-<p>Accessory mode is provided by the Open Accessory (AOA) protocol version 2.0.
-There is limited audio capability in accessory mode, as described in <a
-href="custom.html#audio-over-usb">Connecting custom audio over USB</a>.</p>
-<p>Host mode enables the Android device to drive the USB bus and operate with a
-wide range of USB-based peripherals, including audio interfaces. Host mode
-audio is described in <a href="{@docRoot}devices/audio/usb.html">USB Digital Audio</a>
<h2 id="audio-over-bluetooth">Audio over Bluetooth</h2>
-<p>An accessory that connects with Android over Bluetooth can use an Advanced Audio Distribution
-Profile (A2DP) connection stream music for playback. Playing audio over a Bluetooth with A2DP is
-supported on Android 1.5 (API Level 3) and higher. An Android user can connect to an accessory
-that supports this profile using the system Settings > Bluetooth and play music directly to the
-accessory without the need for a secondary application.</p>
-<p><strong>Note:</strong> If you want to provide a custom application for output to your audio
-accessory, note that the Android 3.0 (API Level 11) allows applications to operate an A2DP
-connection using the
-<a href="http://developer.android.com/reference/android/bluetooth/BluetoothA2dp.html"><code>BluetoothA2dp</code></a>
-class.</p>
+<p>An accessory that connects with Android over Bluetooth can use an Advanced
+Audio Distribution Profile (A2DP) connection stream music for playback. Playing
+audio over a Bluetooth with A2DP is supported on Android 1.5 (API Level 3) and
+higher. An Android user can connect to an accessory that supports this profile
+using the system Settings > Bluetooth and play music directly to the
+accessory without a secondary application.</p>
+
+<p>As of Android 3.0 (API Level 11), applications can operate an A2DP connection
+using the
+<a href="http://developer.android.com/reference/android/bluetooth/BluetoothA2dp.html">
+<code>BluetoothA2dp</code></a> class. To provide a custom application for
+output to an audio accessory, you must use Android 3.0 or higher.
+</p>
+
<h3 id="next-steps_1">Next steps</h3>
-<p>To get started on building an audio accessory that uses a Bluetooth connection:</p>
+<p>To get started building an audio accessory that uses a Bluetooth connection:
+</p>
<ul>
-<li>Select a hardware platform or build an hardware device that can support Bluetooth
- communications and the A2DP connection profile.</li>
+<li>Select a hardware platform or build an hardware device that can support
+Bluetooth communications and the A2DP connection profile.</li>
<li>Review the ADK 2012
- <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
- of an audio playback accessory using a Bluetooth connection.</li>
+ <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware
+ source code</a> (<code><adk-src>/adk2012/board/library/ADK2/</code>),
+ which includes an example implementation of an audio playback accessory using
+ a Bluetooth connection.</li>
</ul>
-<p><strong>Note:</strong> The ADK 2012 source code includes an open source Bluetooth stack that
-is built for the Texas Instruments CC2564 chip, but can work with any Bluetooth chip that
-implements a standard Host/Controller Interface (HCI).</p>
+
+<p class="note"><strong>Note:</strong> The ADK 2012 source code includes an open
+source Bluetooth stack built for the Texas Instruments CC2564 chip, but is
+designed to work with any Bluetooth chip that implements a standard
+Host/Controller Interface (HCI).</p>
+
+<h2 id="midi-over-usb">MIDI over USB and Bluetooth LE</h2>
+<p>Both USB and Bluetooth Low Energy can be used as transports for the
+<a href="http://en.wikipedia.org/wiki/MIDI">MIDI</a> protocol. For details, see
+<a href="{@docRoot}devices/audio/midi.html">MIDI</a>.</p>
\ No newline at end of file
diff --git a/src/accessories/custom.jd b/src/accessories/custom.jd
index 560f182..c4ff0f6 100644
--- a/src/accessories/custom.jd
+++ b/src/accessories/custom.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -24,88 +24,109 @@
</div>
</div>
-<p>An accessory for Android can be anything: keyboard, thermometer, robot, lighting control or
-anything else you can imagine. Accessories for Android all have one thing in common; they all
-connect to an Android device in some way. When starting out to build an accessory, you should
-decide how your accessory will connect to Android devices. This page gives you quick overview of
-your options for connecting your Android accessory and resources to help you get started.</p>
+<p>An accessory for Android can be anything: keyboard, thermometer, robot,
+lighting control, or anything else you can imagine. All Android accessories
+connect to an Android device in some way, so when building an accessory you must
+consider the type of connections your accessory will use. This page provides a
+quick overview of your options for connecting your Android accessory and
+a list of resources to help you get started.</p>
+
<h2 id="connecting-over-usb">Connecting over USB</h2>
-<p>An accessory that connects to an Android device through a USB cable must support the Android
-Open Accessory (AOA) protocol, which specifies how an accessory can establish communication with
-an Android device over a USB cable. Due to the low power output of Android devices, the AOA
-protocol requires the accessory act as a USB host, which means that the connecting accessory must
-power the bus.</p>
-<p>The AOA protocol has two versions which support different types of communication. Version
-1.0 supports a generic accessory communication and adb debugging. This version of the protocol is
-supported by the platform in Android 3.1 (API Level 12) and higher, and supported through an
-<a href="https://developers.google.com/android/add-ons/google-apis/">Add-On Library</a> in Android
-2.3.4 (API Level 10) and higher. Version 2.0 of the protocol is available in Android 4.1 (API Level
-16) and adds audio streaming and human interface device (HID) capabilities.</p>
-<p>If you use the general accessory protocol to communicate with your accessory (rather than the
-adb or audio protocol), you must provide an Android application that can detect the connection of
-your USB accessory and establish communication.</p>
-<h3 id="next-steps">Next steps</h3>
-<p>To get started on building an Android accessory that uses a USB connection:</p>
+<p>An accessory that connects to an Android device through a USB cable must
+support the Android Open Accessory (AOA) protocol, which specifies how an
+accessory can establish communication with an Android device via USB.
+Due to the low power output of Android devices, AOA requires the accessory to
+act as a USB host, meaning the connecting accessory must power the bus.</p>
+
+<p>AOA has two versions that support different types of communication:</p>
<ul>
-<li>Select a hardware platform or build a hardware device that can support USB host mode.</li>
-<li>Review the <a href="{@docRoot}accessories/index.html">AOA protocol</a> specifications to understand
- how to implement this protocol on your accessory hardware. Implementing the
- <a href="{@docRoot}accessories/aoa2.html">AOA 2.0 protocol</a> is recommended for all new Android USB
- accessories.</li>
-<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which demonstrates an implementation of an accessory
- using a USB connection for general data communications and audio streaming.</li>
-<li>If you are planning to build an Android application that communicates with your accessory
- via USB, review the ADK 2012 Android
- <a href="http://developer.android.com/tools/adk/adk2.html#src-download">application source code</a>
- (<code><adk-src>/adk2012/app/</code>).</li>
+<li><strong>AOAv1</strong>. Supports generic accessory communication and adb
+debugging. Available in Android 3.1 (API Level 12) and higher and supported
+through an
+<a href="https://developers.google.com/android/add-ons/google-apis/">Add-On
+Library</a> in Android 2.3.4 (API Level 10) and higher.</li>
+<li><strong>AOAv2</strong>. Supports audio streaming and human interface
+device (HID) capabilities. Available in Android 4.1 (API Level 16).</li>
</ul>
+
+<p>If you use the general accessory protocol to communicate with your accessory
+(rather than the adb or audio protocol), you must provide an Android application
+that can detect the connection of your USB accessory and establish communication.
+</p>
+
+<h3 id="next-steps_0">Next steps</h3>
+<p>To get started building an Android accessory that uses a USB connection:
+</p>
+<ul>
+<li>Select a hardware platform or build a hardware device that can support USB
+host mode.</li>
+<li>Review <a href="{@docRoot}accessories/protocol.html">AOA</a> specifications to
+understand how to implement this protocol on your accessory hardware.
+Implementing <a href="{@docRoot}accessories/aoa2.html">AOAv2</a> is
+recommended for all new Android USB accessories.</li>
+<li>Review the ADK 2012
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware
+source code</a> (<code><adk-src>/adk2012/board/library/ADK2/</code>),
+which demonstrates an implementation of an accessory using a USB connection for
+general data communications and audio streaming.</li>
+<li>When planning to build an Android application that communicates with your
+accessory via USB, review the ADK 2012 Android
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">application
+source code</a> (<code><adk-src>/adk2012/app/</code>).</li>
+</ul>
+
<h2 id="connecting-over-bluetooth">Connecting over Bluetooth</h2>
-<p>An accessory that connects with Android devices over a Bluetooth connection can use the
-various connection profiles supported by Android, including the Simple Serial Protocol (SSP) and
-Advanced Audio Distribution Profile (A2DP) profile. An accessory that uses Bluetooth to connect to
-Android devices must support Bluetooth communications and at least one of the supported connection
-profiles.</p>
-<p>Users must enable Bluetooth on their Android device and pair with your accessory in order to
-use it. You can also provide a secondary Android application that handles any specialized
-communication, such as data input or control outputs, to interface with your accessory.</p>
+<p>An accessory that connects with Android devices over a Bluetooth connection
+can use connection profiles supported by Android, including the Simple Serial
+Protocol (SSP) and Advanced Audio Distribution Profile (A2DP) profile. An
+accessory that uses Bluetooth to connect to Android devices must support
+Bluetooth communications and at least one of the supported connection profiles.
+</p>
+<p>Users must enable Bluetooth on their Android device and pair with your
+accessory to use the accessory. You can also provide a secondary Android
+application that handles specialized communication such as data input or control
+outputs to interface with your accessory.</p>
+
<h3 id="next-steps_1">Next steps</h3>
-<p>To get started on building an Android accessory that uses a Bluetooth connection:</p>
+<p>To get started building an Android accessory that uses a Bluetooth connection:
+</p>
<ul>
-<li>Select a hardware platform or build an hardware device that can support Bluetooth
- communications and an Android supported connection profile, such as SSP or A2DP.</li>
-<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
- of general data communications and audio streaming using a Bluetooth connection.</li>
-<li>If you are planning to build an Android application that communicates with your accessory
- via Bluetooth, review the ADK 2012 Android
- <a href="http://developer.android.com/tools/adk/adk2.html#src-download">application source code</a>
- (<code><adk-src>/adk2012/app/</code>).</li>
+<li>Select a hardware platform or build an hardware device that can support
+Bluetooth communications and an Android supported connection profile, such as
+SSP or A2DP.</li>
+<li>Review the ADK 2012
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware
+source code</a> (<code><adk-src>/adk2012/board/library/ADK2/</code>),
+which includes an example implementation of general data communications and
+audio streaming using a Bluetooth connection.</li>
+<li>When planning to build an Android application that communicates with your
+accessory via Bluetooth, review the ADK 2012 Android
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">application
+source code</a> (<code><adk-src>/adk2012/app/</code>).</li>
</ul>
-<p><strong>Note:</strong> The ADK 2012 source code includes an open source Bluetooth stack which
-is built for the Texas Instruments CC2564 chip, but can work with any Bluetooth chip that
-supports a standard Host/Controller Interface (HCI).</p>
+
+<p class="note"><strong>Note:</strong> The ADK 2012 source code includes an open
+source Bluetooth stack built for the Texas Instruments CC2564 chip but is
+designed to work with any Bluetooth chip that supports a standard
+Host/Controller Interface (HCI).</p>
<h2 id="audio-over-usb">Connecting audio over USB</h2>
-<p>An accessory that connects with Android over USB connection may use the Android Open
-Accessory (AOA) protocol version 2.0. This version of the AOA protocol is supported on Android 4.1
-(API Level 16) and higher. Once an Android device connects to an accessory that supports this
-protocol, the Android system treats it as a standard audio output device and routes all audio to
-that accessory. No secondary software application is required on the Android device.</p>
-<p><strong>Note:</strong> Due to the low power output of Android devices, the Android Open Accessory
-Protocol requires that accessories act as a USB host, which means that the connecting accessory
-must power the bus.</p>
-<h3 id="next-steps">Next steps</h3>
-<p>To get started on building an audio accessory that uses a USB connection:</p>
-<ul>
-<li>Select a hardware platform or build a hardware device that can support USB host mode.</li>
-<li>Review the <a href="{@docRoot}accessories/aoa2.html">AOA 2.0 protocol</a> specification to understand
- how to implement this protocol on your accessory hardware.</li>
-<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
- of an audio playback accessory using a USB connection.</li>
-</ul>
-<p><strong>Note:</strong> The AOA 2.0 protocol also supports the
-<a href="{@docRoot}accessories/aoa2.html#hid-support">human interface device</a> (HID) protocol through a USB
-connection, enabling accessories such as audio docks to provide hardware play back controls such
-as pause, fast-forward or volume buttons.</p>
+<p>An accessory that connects with Android over USB can use AOAv2 (supported on
+Android 4.1 (API Level 16) and higher. After an Android device connects to an
+accessory that supports this protocol, the Android system treats it as a
+standard audio output device and routes all audio to that accessory. No
+secondary software application is required on the Android device.</p>
+
+<p class="note"><strong>Note:</strong> Due to the low power output of Android
+devices, AOA requires accessories to act as a USB host, meaning the connecting
+accessory must power the bus.</p>
+
+<h3 id="next-steps_2">Next steps</h3>
+<p>To get started building an audio accessory that uses a USB connection, see
+<a href="#next-steps_0">next steps for USB connections.</a></p>
+
+<p>AOAv2 also supports the
+<a href="{@docRoot}accessories/aoa2.html#hid-support">human interface device</a>
+(HID) protocol through a USB connection, enabling accessories such as audio
+docks to provide hardware play back controls such as pause, fast-forward or
+volume buttons.</p>
\ No newline at end of file
diff --git a/src/accessories/headset-spec.jd b/src/accessories/headset-spec.jd
deleted file mode 100644
index c9a749e..0000000
--- a/src/accessories/headset-spec.jd
+++ /dev/null
@@ -1,697 +0,0 @@
-page.title=Wired audio headset specification
-@jd:body
-
-<!--
- Copyright 2014 The Android Open Source Project
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-<div id="qv-wrapper">
- <div id="qv">
- <h2>In this document</h2>
- <ol id="auto-toc">
- </ol>
- </div>
-</div>
-
-<p><em>Version 1.1</em></p>
-
-<p>This document specifies the requirements for headsets and mobile devices to
-function uniformly across the Android ecosystem. It is separated into two
-sections beginning with the specifications for the headset
-accessory followed by the specifications for the mobile device.</p>
-
-<h2 id=headset_accessory_plug_specifications>Headset Accessory (Plug) Specifications</h2>
-
-<p>The requirements in the following section apply to the headset accessory.</p>
-
-<h3 id=functions>Functions</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Stereo Audio Out</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Audio in (Mic)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Ground</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
-</table>
-
-<h3 id=control-function_mapping>Control-Function Mapping</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Control Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Function A</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Play/pause/hook (Short Press), Trigger Assist (Long Press), Next (double press)</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function B</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td>
-<p>Vol+</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function C</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td>
-<p>Vol-</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function D</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td>
-<p>Reserved (Nexus devices will use this reserved function to launch Google
-voice search)</p>
-</td>
- </tr>
-</table>
-
-<p><strong>Assign functions to buttons as follows</strong>:</p>
-
-<ul>
- <li> All one-button headsets must implement Function A.
- <li> Headsets with multiple buttons must implement functions according to the
-following pattern:
- <ul>
- <li> 2 functions: A and D
- <li> 3 functions: A, B, C
- <li> 4 functions: A, B, C, D
- </ul>
-</ul>
-
-<h3 id=mechanical>Mechanical</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- <th>
-<p><strong>Notes</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>4 conductor 3.5mm plug</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Ref: EIAJ-RC5325A standard</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>CTIA pinout order (LRGM)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Except in regions with legal requirements for OMTP pinout</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>OMTP pinout order (LRMG)</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>Microphone</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Must not be obstructed when operating headset controls</p>
-</td>
- </tr>
-</table>
-
-<h3 id=electrical>Electrical</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Ear speaker impedance</p>
-</td>
- <td>
-<p><strong>16 ohms or higher</strong></p>
-</td>
- <td>
-<p>Recommend 32 - 300 ohms</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Mic DC resistance</p>
-</td>
- <td>
-<p><strong>1000 ohms or higher</strong></p>
-</td>
- <td>
-<p>Mic characteristics must be compliant with section 5.4 “Audio Recording” of
-current Android Compatibility Definition Document (CDD)</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Control Function Equivalent impedance*</p>
-
-<p>*Total impedance from positive mic terminal to GND when button is pressed with
-2.2 V mic bias applied through 2.2 kOhm resistor</p>
-</td>
- <td>
-<p><strong>0 ohm</strong></p>
-</td>
- <td>
-<p>[Function A] Play/Pause/Hook</p>
-</td>
- </tr>
- <tr>
- <td></td>
- <td>
-<p><strong>240 ohm</strong> +/- 1% resistance</p>
-</td>
- <td>
-<p>[Function B]</p>
-</td>
- </tr>
- <tr>
- <td></td>
- <td>
-<p><strong>470 ohm</strong> +/- 1% resistance</p>
-</td>
- <td>
-<p>[Function C] </p>
-</td>
- </tr>
- <tr>
- <td></td>
- <td>
-<p><strong>135 ohm</strong> +/- 1% resistance</p>
-</td>
- <td>
-<p>[Function D]</p>
-</td>
- </tr>
-</table>
-
-<p>In the following diagrams, Button A is mapped to Function A, Button B to
-Function B, and so on.</p>
-
-<h3 id=reference_headset_test_circuit_1>Reference Headset Test Circuit 1</h3>
-
-<img src="images/headset-circuit1.png" alt="Reference Headset Test Circuit 1" />
-<p class="img-caption"><strong>Figure 1.</strong> Reference headset test circuit 1</p>
-
-<p class="note"><strong>Note:</strong> The above diagram shows the CTIA pinout
-for a 4-segment plug. For the OMTP pinout, switch the positions of the MIC and
-GND segments.</p>
-
-<h3 id=reference_headset_test_circuit_2>Reference Headset Test Circuit 2</h3>
-
-<p>The second reference circuit shows how the actual resistor values (R1 - R4)
-are altered to meet this specification.</p>
-
-<img src="images/headset-circuit2.png" alt="Reference Headset Test Circuit 2" />
-<p class="img-caption"><strong>Figure 2.</strong> Reference headset test circuit 2</p>
-
-<p>The actual resistance of the buttons parallel with the microphone (R1-R4) is
-based on the microphone capsule resistance (Rmic) and the equivalent impedance
-values (ReqA-ReqD). Use the following formula:</p>
-
-<p><em>Rn=(Rmic*ReqN) / (ReqN-Rmic)</em></p>
-
-<p>Where R<em>n</em> is the actual resistance of a button, Req<em>N</em> is the
-equivalent impedance value of that button (provided), and Rmic is the
-microphone impedance value.</p>
-
-<p>The example above assumes a 5 kohm microphone impedance (Rmic). Therefore, to
-achieve an equivalent R4 impedance of 135 ohm (ReqD), the actual resistor value
-(R4) needs to be 139 ohms.</p>
-
-
-<h2 id=mobile_device_jack_specifications>Mobile Device (Jack) Specifications</h2>
-
-<p class="caution"><strong>Caution:</strong> To achieve compatibility with the
-headset specification above, devices that include a 4 conductor 3.5mm audio
-jack must meet the following specifications. Please see the <em>Analog audio
-ports</em> section of the <a
-href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition
-Document (CDD)</a> for Android compatibility requirements.</p>
-
-<p><strong>Headset Jack Functions</strong></p>
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Stereo Audio Out</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Audio in (Mic)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Ground</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
-</table>
-
-<h3 id=software_mapping>Software mapping</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Function A control event </p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_MEDIA</p>
-
-<p>Android key KEYCODE_HEADSETHOOK</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function D control event</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_VOICECOMMAND</p>
-
-<p>Android key KEYCODE_VOICE_ASSIST</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function B control event</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_VOLUMEUP</p>
-
-<p>Android key VOLUME_UP</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function C control event</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_VOLUMEDOWN</p>
-
-<p>Android key VOLUME_DOWN</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset insertion detection</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event SW_JACK_PHYSICAL_INSERT 7</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset type detection</p>
-</td>
- <td>
-<p><strong>Mic</strong></p>
-</td>
- <td>
-<p>input event SW_MICROPHONE_INSERT 4</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset type detection</p>
-</td>
- <td>
-<p><strong>No Mic</strong></p>
-</td>
- <td>
-<p>input event SW_HEADPHONE_INSERT 2</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset speaker impedance</p>
-</td>
- <td>
-<p><strong>Required Headphone (low)</strong></p>
-</td>
- <td>
-<p>Failure mode is to indicate headphones so that limitation would be on</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset speaker impedance</p>
-</td>
- <td>
-<p><strong>Required Line In (high)</strong></p>
-</td>
- <td>
-<p>input event SW_LINEOUT_INSERT 6</p>
-</td>
- </tr>
-</table>
-
-<h3 id=mechanical11>Mechanical</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>4 conductor 3.5mm jack</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>CTIA pinout order (LRGM)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>3 Pin & Mono Plug Compatible</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>OMTP pinout order (LRMG)</p>
-</td>
- <td>
-<p>Optional but <strong>Strongly Recommended</strong></p>
-</td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>Headset detect sequence</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Plug insert notification must only be triggered after all contacts on plug are
-touching their relevant segments. This will prevent unreliable headset
-detection due to slow insertion. </p>
-</td>
- </tr>
-</table>
-
-<h3 id=electrical12>Electrical</h3>
-
-<h4 id=general>General</h4>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Notes</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Maximum output voltage drive</p>
-</td>
- <td>
-<p>150mV </p>
-</td>
- <td>
-<p>>= 150mV on 32 ohm</p>
-
-<p>Test conditions: EN50332-2</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Mic bias resistance </p>
-</td>
- <td>
-<p>Required</p>
-</td>
- <td>
-<p>Flexible on detection method used and microphone bias resistor selection.
-Require that all button resistance value ranges specified below be detected and
-related to their respective function</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Mic bias voltage</p>
-</td>
- <td>
-<p>1.8V - 2.9V</p>
-</td>
- <td>
-<p>To guarantee compatibility to common microphone capsules.</p>
-</td>
- </tr>
-</table>
-
-<h4 id=function_impedance_and_threshold_detection>Function Impedance and Threshold Detection</h4>
-
-<p>Devices must detect the following resistor ladder on the accessories. The
-accessories will be tested to the standardized circuit diagram in the diagram
-illustrated earlier (Reference Headset Test Circuit) where the total impedance
-is measured from MIC terminal to GND when a button is pressed with 2.2V mic
-bias applied through 2.2 kOhm resistor. This is the same effective resistance
-as the button detection circuit with the microphone in parallel with the button
-resistor.</p>
-<table>
- <tr>
- <th>
-<p><strong>Button Impedance Level</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Notes</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p><strong>70 ohm or less</strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function A]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>110 - 180 ohm </strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function D]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>210 - 290 ohm</strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function B]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>360 - 680 ohm </strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function C]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>Headset speaker impedance level</strong></p>
-</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>Low Threshold Detection</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Headphone (low) < 1 Kohm</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>High Threshold Detection</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Line In (high) > 5 Kohm</p>
-</td>
- </tr>
-</table>
diff --git a/src/accessories/headset/images/button_configuration.png b/src/accessories/headset/images/button_configuration.png
new file mode 100644
index 0000000..52a0750
--- /dev/null
+++ b/src/accessories/headset/images/button_configuration.png
Binary files differ
diff --git a/src/accessories/headset/images/button_icons.png b/src/accessories/headset/images/button_icons.png
new file mode 100644
index 0000000..e7b695a
--- /dev/null
+++ b/src/accessories/headset/images/button_icons.png
Binary files differ
diff --git a/src/accessories/headset/images/button_spacing.png b/src/accessories/headset/images/button_spacing.png
new file mode 100644
index 0000000..2bc6cdf
--- /dev/null
+++ b/src/accessories/headset/images/button_spacing.png
Binary files differ
diff --git a/src/accessories/images/headset-circuit1.png b/src/accessories/headset/images/headset-circuit1.png
similarity index 100%
rename from src/accessories/images/headset-circuit1.png
rename to src/accessories/headset/images/headset-circuit1.png
Binary files differ
diff --git a/src/accessories/images/headset-circuit2.png b/src/accessories/headset/images/headset-circuit2.png
similarity index 100%
rename from src/accessories/images/headset-circuit2.png
rename to src/accessories/headset/images/headset-circuit2.png
Binary files differ
diff --git a/src/accessories/headset/images/icon_sizing.png b/src/accessories/headset/images/icon_sizing.png
new file mode 100644
index 0000000..8bfd128
--- /dev/null
+++ b/src/accessories/headset/images/icon_sizing.png
Binary files differ
diff --git a/src/accessories/headset/images/media_four.png b/src/accessories/headset/images/media_four.png
new file mode 100644
index 0000000..128dba0
--- /dev/null
+++ b/src/accessories/headset/images/media_four.png
Binary files differ
diff --git a/src/accessories/headset/images/media_one.png b/src/accessories/headset/images/media_one.png
new file mode 100644
index 0000000..3f9d4db
--- /dev/null
+++ b/src/accessories/headset/images/media_one.png
Binary files differ
diff --git a/src/accessories/headset/images/media_three.png b/src/accessories/headset/images/media_three.png
new file mode 100644
index 0000000..5f1105c
--- /dev/null
+++ b/src/accessories/headset/images/media_three.png
Binary files differ
diff --git a/src/accessories/headset/images/media_two.png b/src/accessories/headset/images/media_two.png
new file mode 100644
index 0000000..3b1e26c
--- /dev/null
+++ b/src/accessories/headset/images/media_two.png
Binary files differ
diff --git a/src/accessories/headset/images/microphone.png b/src/accessories/headset/images/microphone.png
new file mode 100644
index 0000000..1b19015
--- /dev/null
+++ b/src/accessories/headset/images/microphone.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_four.png b/src/accessories/headset/images/telephony_four.png
new file mode 100644
index 0000000..bea091e
--- /dev/null
+++ b/src/accessories/headset/images/telephony_four.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_one.png b/src/accessories/headset/images/telephony_one.png
new file mode 100644
index 0000000..0760f25
--- /dev/null
+++ b/src/accessories/headset/images/telephony_one.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_three.png b/src/accessories/headset/images/telephony_three.png
new file mode 100644
index 0000000..b2c8e29
--- /dev/null
+++ b/src/accessories/headset/images/telephony_three.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_two.png b/src/accessories/headset/images/telephony_two.png
new file mode 100644
index 0000000..1ba31e2
--- /dev/null
+++ b/src/accessories/headset/images/telephony_two.png
Binary files differ
diff --git a/src/accessories/headset/index.jd b/src/accessories/headset/index.jd
new file mode 100644
index 0000000..d66c6ac
--- /dev/null
+++ b/src/accessories/headset/index.jd
@@ -0,0 +1,29 @@
+page.title=Android Audio Headset
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<p>This section describes the development and testing of the Android headset
+accessory interface. This documentation presents the interface guidelines for the
+Android headset inline remote.</p>
+
+<p>The goal is to maintain certain standards for consistency and design while
+allowing for freedom in design expression. If you choose to implement a
+dedicated Android headset accessory, please follow these guidelines to ensure
+your headset is compatible with devices following the recommendations in the <a
+href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition
+Document (CDD)</a>.</p>
diff --git a/src/accessories/headset/requirements.jd b/src/accessories/headset/requirements.jd
new file mode 100644
index 0000000..1f5c0d0
--- /dev/null
+++ b/src/accessories/headset/requirements.jd
@@ -0,0 +1,189 @@
+page.title=Headset Requirements
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id=media>Media</h2>
+
+<p>If a user connects a headset to the device while playing media, the audio
+output (sound) should be heard only via the headset.</p>
+
+<p>For example, while playing media with the <a
+href="https://github.com/googlesamples/android-UniversalMusicPlayer">open
+source</a> <a
+href="https://android-developers.blogspot.com/2015/03/a-new-reference-app-for-multi-device.html">Universal
+Music Player</a>, pressing the play/pause button should pause playback.
+Pressing the same button when media is paused should resume playback.</p>
+
+<p>If the headset has volume control buttons: </p>
+
+<ul>
+ <li> Pressing the volume-up button should increase the volume incrementally each
+time the button is pressed until maximum volume is reached. If the volume-up
+button is pressed and held, the volume should gradually increase to maximum
+volume setting.
+ <li> Pressing the volume-down button should decrease the volume incrementally each
+time the button is pressed until entirely muted. If the volume-down button is
+pressed and held, the volume should gradually decrease to silent.
+ <li> Pressing the volume-up button when in a muted state should increase the volume
+one notch at a time starting from silent.
+</ul>
+
+<p><strong>Recommended for Apps</strong>: On disconnecting the headset, sound output should stop and playback should
+pause. On reconnecting, playback should not start again unless the user presses
+the play button. Upon pressing play, sound output should again be limited to
+the headset.</p>
+
+<h3 id=one_button>One button</h3>
+
+<img src="images/media_one.png" alt="Button functions for one-button headsets handling a media stream.">
+</span>
+
+<p class="img-caption"><strong>Figure 1.</strong> Button functions for one-button headsets handling a media stream.</p>
+
+<h3 id=two_buttons>Two buttons</h3>
+
+<img src="images/media_two.png" alt="Button functions for two-button headsets handling a media stream.">
+
+<p class="img-caption"><strong>Figure 2.</strong> Button functions for two-button headsets handling a media stream.</p>
+
+<h3 id=three_buttons>Three buttons</h3>
+
+<img src="images/media_three.png" alt="Button functions for three-button headsets handling a media stream.">
+
+<p class="img-caption"><strong>Figure 3.</strong> Button functions for three-button headsets handling a media stream.</p>
+
+<h3 id=four_buttons>Four buttons</h3>
+
+<img src="images/media_four.png" alt="Button functions for four-button headsets handling a media stream.">
+
+<p class="img-caption"><strong>Figure 4.</strong> Button functions for four-button headsets handling a media stream.</p>
+
+<h2 id=telephony>Telephony</h2>
+
+
+<p>If a user connects a headset to the device while a call is in progress, the
+conversation should continue on the headset. The call should not get
+disconnected, and the microphone should not be muted. If present, volume
+buttons should behave identically to media playback.</p>
+
+<p>Pressing the play/pause button while a phone call is in progress should toggle
+the microphone state between muted and unmuted. If a user receives calls while
+using the headset, the voice assistance button should allow handling of those
+calls:</p>
+
+<ul>
+ <li> While in a phone call, pressing quickly on the play/pause button should mute
+the microphone. And if pressed quickly again, the microphone should un-mute.
+ <li> While in a phone call, a long press on the play/pause button should end the
+telephone call.
+ <li> While receiving a phone call, pressing quickly on the play/pause button should
+accept the call.
+ <li> While receiving a phone call, a long press on the play/pause button should
+reject the call.
+</ul>
+
+<h3 id=one_button>One button</h3>
+
+<img src="images/telephony_one.png" alt="Button functions for one-button headsets handling a phone call.">
+
+<p class="img-caption"><strong>Figure 5.</strong> Button functions for one-button headsets handling a phone call. </p>
+
+<h3 id=two_buttons>Two buttons</h3>
+
+<img src="images/telephony_two.png" alt="Button functions for two-button headsets handling a phone call.">
+
+<p class="img-caption"><strong>Figure 6.</strong> Button functions for two-button headsets handling a phone call. </p>
+
+<h3 id=three_buttons>Three buttons</h3>
+
+<img src="images/telephony_three.png" alt="Button functions for three-button headsets handling a phone call.">
+
+<p class="img-caption"><strong>Figure 7.</strong> Button functions for three-button headsets handling a phone call. </p>
+
+<h3 id=four_buttons>Four buttons</h3>
+
+<img src="images/telephony_four.png" alt="Button functions for four-button headsets handling a phone call.">
+<p class="img-caption"><strong>Figure 8.</strong> Button functions for four-button headsets handling a phone call. </p>
+
+<h2 id=voice_assistance>Voice assistance</h2>
+
+<p>The voice assistance button is a new inline control standard for consistently
+and conveniently accessing a voice search feature from any approved wearable
+audio device. By pressing the button defined here, users will hear the two-tone
+signature <a href="http://en.wikipedia.org/wiki/Earcon">earcon</a> indicating that the device is listening and ready to receive the query.</p>
+
+<p>Whether embedded into a multi-function button or highlighted as a single
+button, it should always be quickly accessible, ergonomically correct, and
+placed intuitively as described in the following section.</p>
+
+<h2 id=buttons_and_function_mapping>Buttons and function mapping recommendations</h2>
+
+<p>The following diagrams depict the acceptable configuration of the Android voice
+assistance button.</p>
+
+<h3 id=options>Options</h3>
+
+<img src="images/button_configuration.png" alt="Button configuration options.">
+
+<p class="img-caption"><strong>Figure 9.</strong> Button configuration options. </p>
+
+<p>Buttons should always be front facing and spaced out so they can be easily
+located by touch only.</p>
+
+<h3 id=spacing>Spacing</h3>
+
+<p>Buttons must be more than 5mm and must have at least 5mm distance between
+buttons. For four-button headsets, there must be at least 9mm of space between
+button D and the cluster of other buttons. </p>
+
+<img src="images/button_spacing.png" alt="Button spacing requirements">
+
+<p class="img-caption"><strong>Figure 10.</strong> Button spacing requirements.</p>
+
+<h3 id=icon>Icon</h3>
+
+<p>In the following diagram, A is unlabeled or labeled with a dot. B is labeled
+with a + or an arrow pointing up. C is labeled with a - or an arrow pointing
+down. D is labeled with the selected button icon.</p>
+
+<img src="images/button_icons.png" alt="Button icon requirements">
+<p class="img-caption"><strong>Figure 11.</strong> Button icon requirements. </p>
+
+<h3 id=sizing>Sizing</h3>
+
+<p>The following diagram shows the ratio of button icon to the space around it.</p>
+
+<img src="images/icon_sizing.png" alt="Voice search button icon sizing requirements">
+
+<p class="img-caption"><strong>Figure 12.</strong> Voice search button icon sizing requirements. </p>
+
+<h3 id=microphone_port>Microphone port</h3>
+
+<p>The microphone should never be obstructed when operating the buttons. Place the
+port away from finger interface area.</p>
+
+<img src="images/microphone.png" alt="Microphone placement">
+
+<p class="img-caption"><strong>Figure 13.</strong> Microphone placement. </p>
diff --git a/src/accessories/headset/specification.jd b/src/accessories/headset/specification.jd
new file mode 100644
index 0000000..d1616b1
--- /dev/null
+++ b/src/accessories/headset/specification.jd
@@ -0,0 +1,410 @@
+page.title=Wired Audio Headset Specification (v1.1)
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>This section specifies requirements for headsets and mobile devices to
+function uniformly across the Android ecosystem.</p>
+
+<h2 id="headset_accessory_plug_specifications">Headset accessory (plug)
+specifications</h2>
+
+<p>The following requirements apply to headset accessories.</p>
+
+<h3 id="functions">Functions</h3>
+
+<table style="width:50%">
+ <tr>
+ <th>Function</th>
+ <th>Accessory Support</th>
+ </tr>
+ <tr>
+ <td>Stereo Audio Out</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Audio in (Mic)</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Ground</td>
+ <td>Required</td>
+ </tr>
+</table>
+
+<h3 id="control-function_mapping">Control-function mapping</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Control Function</th>
+ <th style="width:33%">Accessory Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>Function A</td>
+ <td>Required</td>
+ <td>Play/pause/hook (Short Press), Trigger Assist (Long Press), Next
+ (Double Press)</td>
+ </tr>
+ <tr>
+ <td>Function B</td>
+ <td>Optional</td>
+ <td>Vol+</td>
+ </tr>
+ <tr>
+ <td>Function C</td>
+ <td>Optional</td>
+ <td>Vol-</td>
+ </tr>
+ <tr>
+ <td>Function D</td>
+ <td>Optional</td>
+ <td>Reserved (Nexus devices use this to launch Voice Assist)
+</td>
+ </tr>
+</table>
+
+<p>Assign functions to buttons as follows:</p>
+
+<ul>
+ <li> All one-button headsets must implement Function A.
+ <li> Headsets with multiple buttons must implement functions according to the
+following pattern:
+ <ul>
+ <li> 2 functions: A and D
+ <li> 3 functions: A, B, C
+ <li> 4 functions: A, B, C, D
+ </ul>
+</ul>
+
+<h3 id="mechanical">Mechanical</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Accessory Support</th>
+ <th style="width:33%">Notes</th>
+ </tr>
+ <tr>
+ <td>4 conductor 3.5mm plug</td>
+ <td>Required</td>
+ <td>Ref: EIAJ-RC5325A standard</td>
+ </tr>
+ <tr>
+ <td>CTIA pinout order (LRGM)</td>
+ <td>Required</td>
+ <td>Except in regions with legal requirements for OMTP pinout</td>
+ </tr>
+ <tr>
+ <td>OMTP pinout order (LRMG)</td>
+ <td>Optional</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>Microphone</td>
+ <td>Required</td>
+ <td>Must not be obstructed when operating headset controls</td>
+ </tr>
+</table>
+
+<h3 id="electrical">Electrical</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Accessory Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>Ear speaker impedance</td>
+ <td>16 ohms or higher</td>
+ <td>Recommend 32 - 300 ohms</td>
+ </tr>
+ <tr>
+ <td>Mic DC resistance</td>
+ <td>1000 ohms or higher
+</td>
+ <td>Mic characteristics must be compliant with section 5.4 “Audio
+ Recording” of the current
+ <a href="{@docRoot}compatibility/android-cdd.pdf">Android CDD</a></td>
+ </tr>
+ <tr>
+ <td rowspan="4">Control Function Equivalent impedance*</td>
+ <td>0 ohm</td>
+ <td>[Function A] Play/Pause/Hook</td>
+ </tr>
+ <tr>
+ <td>240 ohm +/- 1% resistance</td>
+ <td>[Function B]</td>
+ </tr>
+ <tr>
+ <td>470 ohm +/- 1% resistance</td>
+ <td>[Function C]</td>
+ </tr>
+ <tr>
+ <td>135 ohm +/- 1% resistance</td>
+ <td>[Function D]</td>
+ </tr>
+</table>
+
+<p><em>*Total impedance from positive mic terminal to GND when button is
+pressed with 2.2 V mic bias applied through 2.2 kOhm resistor</em></p>
+
+<p>In the following diagrams, Button A maps to Function A, Button B to
+Function B, and so on.</p>
+
+<h3 id="reference_headsets">Reference headset test circuits</h3>
+
+<p>The following diagram for Reference Headset Test Circuit 1 shows the CTIA
+pinout for a 4-segment plug. For the OMTP pinout, switch the positions of the
+MIC and GND segments.</p>
+
+<img src="images/headset-circuit1.png" alt="Reference Headset Test Circuit 1" />
+<p class="img-caption"><strong>Figure 1.</strong> Reference headset test circuit 1</p>
+
+<p>The following diagram for Reference Headset Test Circuit 2 shows how the
+actual resistor values (R1 - R4) are altered to meet this specification.</p>
+
+<img src="images/headset-circuit2.png" alt="Reference Headset Test Circuit 2" />
+<p class="img-caption"><strong>Figure 2.</strong> Reference headset test circuit 2</p>
+
+<p>The actual resistance of the buttons parallel with the microphone (R1-R4) is
+based on the microphone capsule resistance (Rmic) and the equivalent impedance
+values (ReqA-ReqD). Use the following formula:</p>
+
+<p><em>Rn=(Rmic*ReqN) / (ReqN-Rmic)</em></p>
+
+<p>Where R<em>n</em> is the actual resistance of a button, Req<em>N</em> is the
+equivalent impedance value of that button (provided), and Rmic is the
+microphone impedance value.</p>
+
+<p>The example above assumes a 5 kohm microphone impedance (Rmic); to achieve
+an equivalent R4 impedance of 135 ohm (ReqD), the actual resistor value (R4)
+must be 139 ohms.</p>
+
+<h2 id="mobile_device_jack_specifications">Mobile device (jack) specifications</h2>
+
+<p class="caution"><strong>Caution:</strong> To achieve compatibility with the
+headset specification, devices that include a 4 conductor 3.5mm audio jack
+must meet the following specifications. For Android compatibility requirements,
+refer to the <em>Analog audio ports</em> section of the <a
+href="{@docRoot}compatibility/android-cdd.pdf">Android CDD</a>.</p>
+
+<h3 id="headset_jack_functions">Functions</h3>
+
+<table>
+ <tr>
+ <th>Function</th>
+ <th>Device Support</th>
+ </tr>
+ <tr>
+ <td>Stereo Audio Out</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Audio in (Mic)</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Ground</td>
+ <td>Required</td>
+ </tr>
+</table>
+
+<h3 id="software_mapping">Software mapping</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Device Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>Function A control event</td>
+ <td>Required</td>
+ <td>input event KEY_MEDIA
+<p>Android key KEYCODE_HEADSETHOOK</p></td>
+ </tr>
+ <tr>
+ <td>Function D control event</td>
+ <td>Required</td>
+ <td>input event KEY_VOICECOMMAND
+<p>Android key KEYCODE_VOICE_ASSIST</p></td>
+ </tr>
+ <tr>
+ <td>Function B control event</td>
+ <td>Required
+</td>
+ <td>input event KEY_VOLUMEUP
+<p>Android key VOLUME_UP</p></td>
+ </tr>
+ <tr>
+ <td>Function C control event</td>
+ <td>Required</td>
+ <td>input event KEY_VOLUMEDOWN
+<p>Android key VOLUME_DOWN</p></td>
+ </tr>
+ <tr>
+ <td>Headset insertion detection</td>
+ <td>Required</td>
+ <td>input event SW_JACK_PHYSICAL_INSERT 7</td>
+ </tr>
+ <tr>
+ <td rowspan="2">Headset type detection</td>
+ <td>Mic</td>
+ <td>input event SW_MICROPHONE_INSERT 4</td>
+ </tr>
+ <tr>
+ <td>No Mic</td>
+ <td>input event SW_HEADPHONE_INSERT 2</td>
+ </tr>
+ <tr>
+ <td rowspan="2">Headset speaker impedance</td>
+ <td>Required Headphone (low)</td>
+ <td>Failure mode is to indicate headphones so limitation would be on</td>
+ </tr>
+ <tr>
+ <td>Required Line In (high)</td>
+ <td>input event SW_LINEOUT_INSERT 6</td>
+ </tr>
+</table>
+
+<h3 id="mechanical11">Mechanical</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Device Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>4 conductor 3.5mm jack</td>
+ <td>Required</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>CTIA pinout order (LRGM)</td>
+ <td>Required</td>
+ <td>3 Pin & Mono Plug Compatible</td>
+ </tr>
+ <tr>
+ <td>OMTP pinout order (LRMG)</td>
+ <td>Optional but strongly recommended</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>Headset detect sequence</td>
+ <td>Required</td>
+ <td>Plug insert notification must be triggered only after all contacts on
+ plug are touching their relevant segments (this prevents unreliable headset
+ detection due to slow insertion.</td>
+ </tr>
+</table>
+
+<h3 id="electrical12">Electrical</h3>
+
+<h4 id="general">General</h4>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Device Support</th>
+ <th style="width:33%">Notes</th>
+ </tr>
+ <tr>
+ <td>Maximum output voltage drive</td>
+ <td>150mV</td>
+ <td>>= 150mV on 32 ohm
+<p>Test conditions: EN50332-2</p></td>
+ </tr>
+ <tr>
+ <td>Mic bias resistance</td>
+ <td>Required</td>
+ <td>Flexible on detection method used and microphone bias resistor
+ selection. Require that all button resistance value ranges specified below
+ be detected and related to their respective function</td>
+ </tr>
+ <tr>
+ <td>Mic bias voltage</td>
+ <td>1.8V - 2.9V</td>
+ <td>To guarantee compatibility to common microphone capsules.</td>
+ </tr>
+</table>
+
+<h4 id="function_impedance_and_threshold_detection">Function impedance and
+threshold detection</h4>
+
+<p>Devices must detect the following resistor ladder on the accessories. The
+accessories will be tested to the standardized circuit diagram in the diagram
+illustrated earlier (Reference Headset Test Circuit) where the total impedance
+is measured from MIC terminal to GND when a button is pressed with 2.2V mic
+bias applied through 2.2 kOhm resistor. This is the same effective resistance
+as the button detection circuit with the microphone in parallel with the button
+resistor.</p>
+
+<table>
+ <tr>
+ <th style="width:40%">Button Impedance Level</th>
+ <th style="width:20%">Device Support</th>
+ <th style="width:40%">Notes</th>
+ </tr>
+ <tr>
+ <td>70 ohm or less</td>
+ <td>Required</td>
+ <td>[Function A]</td>
+ </tr>
+ <tr>
+ <td>110 - 180 ohm</td>
+ <td>Required</td>
+ <td>[Function D]</td>
+ </tr>
+ <tr>
+ <td>210 - 290 ohm</td>
+ <td>Required</td>
+ <td>[Function B]</td>
+ </tr>
+ <tr>
+ <td>360 - 680 ohm</td>
+ <td>Required</td>
+ <td>[Function C]</td>
+ </tr>
+ </table>
+
+ <table>
+ <tr>
+ <th style="width:40%">Headset Speaker Impedance Level</th>
+ <th style="width:20%">Device Support</th>
+ <th style="width:40%">Notes</th>
+ </tr>
+ <tr>
+ <td>Low Threshold Detection</td>
+ <td>Required</td>
+ <td>Headphone (low) < 1 Kohm</td>
+ </tr>
+ <tr>
+ <td>High Threshold Detection</td>
+ <td>Required</td>
+ <td>Line In (high) > 5 Kohm</td>
+ </tr>
+</table>
diff --git a/src/accessories/headset/testing.jd b/src/accessories/headset/testing.jd
new file mode 100644
index 0000000..c66d4f0
--- /dev/null
+++ b/src/accessories/headset/testing.jd
@@ -0,0 +1,112 @@
+page.title=Testing
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id=headset_insertion>Headset insertion</h2>
+
+<ol>
+ <li> Start with the Android device turned off.
+ <li> Plug in the headset.
+ <li> Turn the device on.
+ <li> Unlock.
+ <li> Open the <a
+ href="https://github.com/googlesamples/android-UniversalMusicPlayer">open
+ source</a> <a
+ href="https://android-developers.blogspot.com/2015/03/a-new-reference-app-for-multi-device.html">Universal
+ Music Player</a>.
+ <li> Press the DUT volume buttons to maximize media volume.
+ <li> Start playing music and verify audio comes out of the headset.
+ <li> While Music is playing, disconnect the headset and verify music stops.
+ <li> Reconnect the headset, start playing music again, and verify audio comes out of
+the headset.
+</ol>
+
+<h2 id=volume_buttons>Volume buttons</h2>
+
+<ol>
+ <li> Play music and ensure it is coming out of the headset.
+ <li> Press (“short press”) on the volume-down button. Then verify the volume panel
+displays the media volume decrease by one notch and the volume output is
+reduced as expected.
+ <li> Long press on the volume-down button. Then verify the volume panel shows media
+volume going all the way down and volume output is reduced gradually to muted.
+ <li> Press on the volume-up button. Then verify the volume panel displays the media
+volume go up one notch and the volume output is increased as expected.
+ <li> Long press on the volume-up button. Then verify the volume panel shows the
+media volume go all the way up to maximum and the volume output is increased as
+expected.
+</ol>
+
+<h2 id=play_pause_for_music>Play/pause for music</h2>
+
+<p>Press quickly on the play/pause button and verify music stops playing out of
+the headset. If music was not already playing, then it should start playing out
+of the headset.</p>
+
+<h2 id=play_pause_for_telephony>Play/pause for telephony</h2>
+
+<ol>
+ <li> Make a phone call.
+ <li> Press quickly on the play/pause button while in the call.
+ <li> Verify the microphone mutes. And if you press quickly again, the microphone
+should un-mute.
+ <li> While still in the call, long press on the play/pause button.
+ <li> Verify the long press ends the telephone call
+ <li> Receive a phone call on the Android device.
+ <li> Press quickly on the play/pause button while the phone is ringing and verify
+the call is accepted.
+ <li> Receive another phone call on the Android device.
+ <li> Long press on the play/pause button while the phone is ringing and verify the
+call is rejected.
+</ol>
+
+<h2 id=play_pause_for_voice_actions_microphone>Play/pause for voice actions + microphone</h2>
+
+<ol>
+ <li> Open the screen on your Android device, unlock it, and go to the home screen.
+ <li> Long press on the play/pause button.
+ <li> Verify:
+ <ol>
+ <li> you hear a beep after which you should be able to make a voice search query,
+such as “What time is it?”
+ <li> you hear a response, such as “The time is ...”
+ </ol>
+ </ol>
+
+<h2 id=voice_button_for_voice_actions_microphone>Voice button for voice actions + microphone</h2>
+
+<ol>
+ <li> Open the screen on your Android device, unlock it, and go to the home screen.
+ <li> Short press on the voice button.
+ <li> Verify:
+ <ol>
+ <li> you hear a beep after which you should be able to make a search query, such as
+“What time is it?”
+ <li> you hear a response, such as “The time is ...”
+ </ol>
+ </ol>
+
+<p><strong>Important</strong>: A press on the voice button can launch launch any search app, for example
+Google search.</p>
diff --git a/src/accessories/index.jd b/src/accessories/index.jd
index d30c0ce..709b26a 100644
--- a/src/accessories/index.jd
+++ b/src/accessories/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -16,10 +16,8 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>Implement compelling accessories to extend the capabilities of your users'
-Android-powered devices. Android relies on a suite of standard protocols you
-can implement in your accessories to be compatible with a wide range of
-Android-powered devices.
+<p>Using a suite of standard protocols, you can implement compelling accessories
+that extend Android capabilities in a wide range of Android-powered devices.
</p>
<div class="layout-content-row">
@@ -29,8 +27,8 @@
<p>Android supports local on-device audio and remote off-device audio
over a wired 3.5 mm headset jack, USB connection, or Bluetooth.
Manufacturers should see the <a
- href="{@docRoot}accessories/headset-spec.html">wired audio headset
- specification</a>, while users may learn how to <a
+ href="{@docRoot}accessories/headset/specification.html">wired audio headset
+ specification</a>, while users can learn how to <a
href="https://support.google.com/nexus/answer/6127700">record and play
back audio using USB host mode</a>.</p>
<p><a href="{@docRoot}accessories/audio.html">» Audio Accessories</a></p>
@@ -38,9 +36,10 @@
<div class="layout-content-col span-6">
<h4 id="custom-accessories">Custom Accessories</h4>
- <p>What do you want to connect to your Android device? Alarm clock? Keyboard? Thermostat? Robot?
- Learn how to connect existing equipment or your own unique hardware to
- Android using the Android Open Accessory Protocol.</p>
+ <p>What do you want to connect to your Android device? Alarm clock?
+ Keyboard? Thermostat? Robot? Learn how to connect existing equipment or
+ your own unique hardware to Android using the Android Open Accessory
+ (AOA) protocol.</p>
<p><a href="{@docRoot}accessories/custom.html">» Custom Accessories</a></p>
</div>
diff --git a/src/accessories/protocol.jd b/src/accessories/protocol.jd
index 7ce3bb4..b04e634 100644
--- a/src/accessories/protocol.jd
+++ b/src/accessories/protocol.jd
@@ -1,44 +1,52 @@
-page.title=Android Open Accessory Protocol
+page.title=Android Open Accessory (AOA)
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
-->
-<p> Android Open Accessory support 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 in the USB accessory role. Android USB accessories are
-specifically designed to attach to Android-powered devices and adhere to the Android Open 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>Android Open Accessory (AOA) support allows external USB hardware
+(Android USB accessories) to interact with Android-powered devices in
+<em>accessory mode</em>. 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 accessory.
+</p>
+<p>Android USB accessories are designed to attach to Android-powered devices.
+Such accessories adhere to AOA, enabling them to detect Android-powered devices
+that support accessory mode, and must provide 500mA at 5V for charging power.
+Some previously-released Android-powered devices are capable of acting only
+as a USB device and cannot initiate connections with external USB devices. AOA
+support overcomes this limitation, enabling you to build accessories that can
+initiate connections and interact with an assortment of Android-powered devices.
+</p>
-<p><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="http://developer.android.com/guide/topics/connectivity/usb/accessory.html#manifest">USB Accessory</a>
-developer guide.</p>
-
+<p class="note"><strong>Note:</strong> Accessory mode is dependent on device
+hardware; not all devices support accessory mode. Devices that support accessory
+mode can be filtered using a <code><uses-feature></code> element in the
+corresponding application's Android manifest. For details, see the
+<a href="http://developer.android.com/guide/topics/connectivity/usb/accessory.html#manifest">USB
+Accessory</a> developer guide.</p>
-<p>Android Open Accessory support is included in Android 3.1 (API Level 12) and higher, and supported
-through an <a href="https://developers.google.com/android/add-ons/google-apis/">Add-On Library</a> in Android
-2.3.4 (API Level 10) and higher.</p>
-
-
+<p>AOA has two versions that support different types of communication:</p>
+<ul>
+<li><strong>AOAv1</strong>. Supports generic accessory communication and adb
+debugging. Available in Android 3.1 (API Level 12) and higher and supported
+through an
+<a href="https://developers.google.com/android/add-ons/google-apis/">Add-On
+Library</a> in Android 2.3.4 (API Level 10) and higher.</li>
+<li><strong>AOAv2</strong>. Supports audio streaming and human interface
+device (HID) capabilities. Available in Android 4.1 (API Level 16).</li>
+</ul>
\ No newline at end of file
diff --git a/src/compatibility/android-cdd.html b/src/compatibility/android-cdd.html
index f055171..a3a3587 100644
--- a/src/compatibility/android-cdd.html
+++ b/src/compatibility/android-cdd.html
@@ -96,6 +96,12 @@
<p class="toc_h2"><a href="#3_9_device_administration">3.9. Device Administration</a></p>
+<p class="toc_h3"><a href="#3_9_1_device_provisioning">3.9.1 Device Provisioning</a></p>
+
+<p class="toc_h4"><a href="#3_9_1_2_device_owner_provisioning">3.9.1.1 Device Owner provisioning</a></p>
+
+<p class="toc_h4"><a href="#3_9_1_2_managed_profile_provisioning">3.9.1.2 Managed profile provisioning</a></p>
+
<p class="toc_h2"><a href="#3_10_accessibility">3.10. Accessibility</a></p>
<p class="toc_h2"><a href="#3_11_text-to-speech">3.11. Text-to-Speech</a></p>
@@ -710,7 +716,8 @@
</tr>
<tr>
<td>SERIAL</td>
- <td>A hardware serial number, which MUST be available. The value of this field MUST
+ <td>A hardware serial number, which MUST be available and unique across
+devices with the same MODEL and MANUFACTURER. The value of this field MUST
be encodable as 7-bit ASCII and match the regular expression “^([a-zA-Z0-9]{6,20})$”.</td>
</tr>
<tr>
@@ -864,9 +871,13 @@
android.os.Build.SUPPORTED_32_BIT_ABIS, and
android.os.Build.SUPPORTED_64_BIT_ABIS parameters, each a comma separated list
of ABIs ordered from the most to the least preferred one</li>
- <li>MUST report, via the above parameters, only those ABIs documented in the latest
-version of the Android NDK, “NDK Programmer’s Guide | ABI Management” in docs/
-directory</li>
+ <li>MUST report, via the above parameters, only those ABIs documented and
+described in the latest version of the Android NDK ABI Management documentation
+[<a href="https://developer.android.com/ndk/guides/abis.html">Resources, XX</a>],
+and MUST include support for the Advanced SIMD (a.k.a. NEON)
+[<a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html">Resources,XX</a>]
+extension
+ </li>
<li>SHOULD be built using the source code and header files available in the
upstream Android Open Source Project</li>
</ul>
@@ -1482,7 +1493,6 @@
<h2 id="3_9_device_administration">3.9. Device Administration</h2>
-
<p>Android includes features that allow security-aware applications to perform
device administration functions at the system level, such as enforcing password
policies or performing remote wipe, through the Android Device Administration
@@ -1495,9 +1505,40 @@
[<a href="http://developer.android.com/guide/topics/admin/device-admin.html">Resources, 39</a>]
and report the platform feature android.software.device_admin.</p>
-<p>Device implementations MAY have a preinstalled application performing device
-administration functions but this application MUST NOT be set out-of-the box as
-the default Device Owner app [<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)">Resources, 41</a>].</p>
+<h3 id="3_9_1_device_provisioning">3.9.1 Device Provisioning</h3>
+<h4 id="3_9_1_1_device_owner_provisioning">3.9.1.1 Device owner provisioning</h4>
+<p>If a device implementation declares the android.software.device_admin feature,
+the out of box setup flow MUST make it possible to enroll a Device Policy
+Controller (DPC) application as the Device Owner app
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)">
+Resources, XX</a>]. Device implementations MAY have a preinstalled application
+performing device administration functions but this application MUST NOT be set
+as the Device Owner app without explicit consent or action from the user or the
+administrator of the device.</p>
+
+<p>The device owner provisioning process (the flow initiated by
+android.app.action.PROVISION_MANAGED_DEVICE
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE">
+Resources, XX</a>]) user experience MUST align with the AOSP implementation</p>
+
+<p>If the device implementation reports android.hardware.nfc, it MUST have NFC
+enabled, even during the out-of-box setup flow, in order to allow for NFC
+provisioning of Device owners
+<a href="https://source.android.com/devices/tech/admin/provision.html#device_owner_provisioning_via_nfc">[Resources, XX]</a>.
+</p>
+
+<h4 id="3_9_1_2_managed_profile_provisioning">3.9.1.2 Managed profile provisioning</h4>
+<p>If a device implementation declares the android.software.managed_users,
+it MUST be possible to enroll a Device Policy Controller (DPC) application
+as the owner of a new Managed Profile
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProfileOwnerApp(java.lang.String)">
+Resources, XX</a>]</p>
+
+<p>The managed profile provisioning process (the flow initiated by
+android.app.action.PROVISION_MANAGED_PROFILE
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">
+Resources, XX</a>]) user experience MUST align with the AOSP implementation
+</p>
<h2 id="3_10_accessibility">3.10. Accessibility</h2>
@@ -3493,23 +3534,24 @@
<ul>
<li>NfcA (ISO14443-3A)</li>
<li>NfcB (ISO14443-3B)</li>
- <li>NfcF (JIS 6319-4)</li>
+ <li>NfcF (JIS X 6319-4)</li>
<li>IsoDep (ISO 14443-4)</li>
<li>NFC Forum Tag Types 1, 2, 3, 4 (defined by the NFC Forum)</li>
</ul>
- <li>SHOULD be capable of reading and writing NDEF messages via the following NFC
-standards. Note that while the NFC standards below are stated as SHOULD, the
-Compatibility Definition for a future version is planned to change these to
-MUST. These standards are optional in this version but will be required in
-future versions. Existing and new devices that run this version of Android are <strong>very strongly encouraged</strong> to meet these requirements now so they will be able to upgrade to the future platform releases.</li>
+ <li>MUST be capable of reading and writing NDEF messages as well as raw
+ data via the following NFC standards:</li>
<ul>
<li>NfcV (ISO 15693)</li>
</ul></li>
+ <li>SHOULD be capable of reading the barcode and URL (if encoded) of
+ Thinfilm NFC Barcode
+ [<a href="http://developer.android.com/reference/android/nfc/tech/NfcBarcode.html">Resources, XX</a>] products.
+ </li>
<li>MUST be capable of transmitting and receiving data via the following
peer-to-peer standards and protocols:
<ul>
<li>ISO 18092</li>
- <li>LLCP 1.0 (defined by the NFC Forum)</li>
+ <li>LLCP 1.2 (defined by the NFC Forum)</li>
<li>SDP 1.0 (defined by the NFC Forum)</li>
<li>NDEF Push Protocol [<a href="http://static.googleusercontent.com/media/source.android.com/en/us/compatibility/ndef-push-protocol.pdf">Resources, 84</a>]</li>
<li>SNEP 1.0 (defined by the NFC Forum)</li>
@@ -3580,8 +3622,8 @@
<ul>
<li>MUST implement the corresponding Android APIs as documented by the Android SDK.</li>
<li>MUST report the feature com.nxp.mifare from the
-android.content.pm.PackageManager.hasSystemFeature() meth<a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">od [Resources, 53]</a>. Note that this is not a standard Android feature and as such does not appear
-as a constant on the PackageManager class.</li>
+android.content.pm.PackageManager.hasSystemFeature() method <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">[Resources, 53]</a>. Note that this is not a standard Android feature and as such does not appear
+as a constant in the android.content.pm.PackageManager class.</li>
<li>MUST NOT implement the corresponding Android APIs nor report the com.nxp.mifare
feature unless it also implements general NFC support as described in this
section.</li>
@@ -4129,6 +4171,13 @@
ignored. Implementations MAY add additional permissions, provided the new
permission ID strings are not in the android.* namespace.</p>
+<p>Permissions with a protection level of dangerous are runtime permissions. Applications
+with targetSdkVersion > 22 request them at runtime. The system MUST show a dedicated UI for the
+user to decide whether to grant the requested runtime permissions and also provide a UI for the
+user to manage runtime permissions. On the system there MUST be one and only one
+implementation of both the UI for the user to accept runtime permissions and the UI for
+the user to manage runtime permissions.</p>
+
<h2 id="9_2_uid_and_process_isolation">9.2. UID and Process Isolation</h2>
@@ -4697,6 +4746,19 @@
<p>41. Android Device Owner App:</p>
<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)</a></p>
+<p>XX. Android Device Owner Provisioning Flow:</p>
+
+<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE</a></p>
+<p>XX. Device Owner Provisioning via NFC:</p>
+
+<p><a href="https://source.android.com/devices/tech/admin/provision.html#device_owner_provisioning_via_nfc">https://source.android.com/devices/tech/admin/provision.html#device_owner_provisioning_via_nfc</a></p>
+<p>XX. Android Managed Profile Provisioning flow:</p>
+
+<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE</a></p>
+
+<p>XX. Android Profile Owner App:</p>
+
+<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProfileOwnerApp(java.lang.String)">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProfileOwnerApp(java.lang.String)</a></p>
<p>42. Android Accessibility Service APIs: <a href="http://developer.android.com/reference/android/accessibilityservice/AccessibilityService.html">http://developer.android.com/reference/android/accessibilityservice/AccessibilityService.html</a></p>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index de70dd0..8a730cb 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -196,6 +196,8 @@
<li><a href="<?cs var:toroot ?>devices/tech/config/kernel.html">Kernel</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/low-ram.html">Low RAM</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/renderer.html">OpenGLRenderer</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/config/runtime_perms.html">Runtime Permissions</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/config/uicc.html">UICC</a></li>
</ul>
</li>
@@ -257,7 +259,12 @@
<a href="<?cs var:toroot ?>devices/tech/power/index.html"><span class="en">Power</span></a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/power/batterystats.html">Battery Use</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/power/component.html">Component Power</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/power/device.html">Device Power</a>
+ </li>
+ <li><a href="<?cs var:toroot ?>devices/tech/power/values.html">Power Values</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/power/batterystats.html">Battery Use</a>
+ </li>
</ul>
</li>
@@ -302,7 +309,21 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/security/encryption/index.html">Encryption</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/authentication/index.html">Authentication</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/encryption/index.html">Full Disk Encryption</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/selinux/index.html">
+ <span class="en">SELinux</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/concepts.html">Concepts</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/implement.html">Implementation</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/customize.html">Customization</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/validate.html">Validation</a></li>
+ </ul>
+ </li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/index.html">
@@ -314,19 +335,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/dm-verity.html">Implementing dm-verity</a></li>
</ul>
</li>
- <li class="nav-section">
- <div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/security/selinux/index.html">
- <span class="en">Security-Enhanced Linux</span>
- </a>
- </div>
- <ul>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/concepts.html">Concepts</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/implement.html">Implementation</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/customize.html">Customization</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/validate.html">Validation</a></li>
- </ul>
- </li>
+
</ul>
</li>
</ul>
diff --git a/src/devices/tech/config/runtime_perms.jd b/src/devices/tech/config/runtime_perms.jd
new file mode 100644
index 0000000..ef54b78
--- /dev/null
+++ b/src/devices/tech/config/runtime_perms.jd
@@ -0,0 +1,107 @@
+page.title=Runtime Permissions
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The Android 6.0 release presents a new application permission model aimed at making permissions more understandable, useful, and secure for users. The model moves Android applications that require dangerous permissions (see <a href="#affected-permissions">Affected permissions</a>) from an <i>install</i> time permission model to <i>runtime</i> permission model:</p>
+
+<ul>
+<li><strong>Install Time Permissions</strong> (<i>Android 5.1 and earlier</i>). Users grant dangerous permissions to an app when installing or updating the app. OEMs/carriers can pre-install apps with pre-granted permissions without notifying the user. </li>
+<li><strong>Runtime Permissions</strong> (Android <i>6.0 and later</i>). Users grant dangerous permissions to an app when the app is running. Applications decide when to request permissions (such as when the app launches or the user accesses a specific feature), but must allow the user to grant/deny application access to specific permission groups. OEMs/carriers can pre-install apps but cannot pre-grant permissions (see <a href="#creating-exceptions">Creating exceptions</a>). </li>
+</ul>
+
+<p>The move to runtime permissions provides users additional context and visibility into the permissions that applications are seeking or have been granted. The new model also encourages developers to help users understand why applications require the requested permissions and to provide greater transparency about the benefits and hazards of granting or denying permissions. Users can revoke application permissions using the Apps menu in Settings.</p>
+
+<h2 id="affected-permissions">Affected permissions</h2>
+
+<p>The Android 6.0 release requires only dangerous permissions to use a runtime permissions model. Dangerous permissions are higher-risk permissions (such as <code>READ_CALENDAR</code>) that grant requesting applications access to private user data or control over the device that can negatively impact the user. To view a list of dangerous permissions, run the command: <code>adb shell pm list permissions -g -d</code> .</p>
+
+<p>This release does not change the behavior of normal permissions (all non-dangerous permissions including normal, system, and signature permissions). Normal permissions are lower-risk permissions (such as <code>SET_WALLPAPER</code>) that grant requesting applications access to isolated application-level features with minimal risk to other applications, the system, or the user. As in Android 5.1 and earlier releases, the system automatically grants normal permissions to a requesting application at installation and does not prompt the user for approval. For details on permissions, refer to <a href="http://developer.android.com/guide/topics/manifest/permission-element.html"><permission> element documentation</a>.</p>
+
+<h2 id="requirements">Requirements</h2>
+
+<p>The runtime permission model applies to all applications, including pre-installed apps and apps delivered to the device as part of the setup process. Application software requirements include: </p>
+<ul>
+<li>Runtime permission model must be consistent across all devices running Android 6.0. Enforced by Android Compatibility Test Suite (CTS) tests.</li>
+<li>Apps must prompt users to grant application permissions at runtime. For details, see Updating Applications.Limited exceptions may be granted to default applications and handlers that provide basic device functionality determined to be fundamental to the expected operation of the device (i.e. the device's default Dialer app for handling ACTION_CALL may have Phone permission access). For details, see <a href="#creating-exceptions">Creating exceptions</a>.</li>
+<li>Pre-loaded apps with "dangerous permission" MUST target API level 23 and the AOSP permission model of Android 6.0 should be maintained (i.e. the UI flow during an app installation should not deviate from the AOSP implementation of PackageInstaller, users can even revoke the dangerous permissions of pre-installed apps etc.).</li>
+<li>Headless applications must use an activity to request permissions or share a UID with another application that has the necessary permissions. For details, see <a href="#headless-apps">Headless applications</a>.</li>
+</ul>
+
+<h2 id="permissions-migration">Permissions migration</h2>
+
+<p>Permissions granted to applications on Android 5.x remain granted after updating to Android 6.0, but users can revoke those permissions at any time.</p>
+
+<h2 id="integration">Integration</h2>
+
+<p>When integrating the Android 6.0 application runtime permissions model, you must update pre-installed applications to work with the new model. You can also define exceptions for apps that are the default handlers/providers for core functionality, define custom permissions, and customize the theme used in the PackageInstaller.</p>
+
+<h3 id="updating-apps">Updating applications</h3>
+
+<p>Applications on the system image and pre-installed applications are not automatically pre-granted permissions. We encourage you to work with pre-installed app developers (OEM, Carrier, and third party) to make the required app modifications using the <a href="https://developer.android.com/preview/features/runtime-permissions.html">guidelines</a> posted on the developer portal. Specifically, you must ensure that pre-installed applications are modified to avoid crashes and other issues when users revoke permissions.</p>
+
+<h4 id="preloaded-apps">Pre-loaded applications</h4>
+<p>Pre-loaded apps that use dangerous permissions MUST target API level 23 and maintain the Android 6.0 AOSP permission model (i.e. the UI flow during an app installation should not deviate from the AOSP implementation of PackageInstaller, users can even revoke the dangerous permissions of pre-installed apps etc.).</p>
+
+<h4 id="headless-apps">Headless applications</h4>
+<p>Only activities can request permissions; services cannot directly request permissions. </p>
+<ul>
+<li>In Android 5.1 and earlier releases, headless applications can request permissions when installed or pre-installed without the use of an activity.</li>
+<li>In Android 6.0, headless applications must use one of the following methods to request permissions:<ul>
+<li>Add an activity to request permissions (preferred method).</li>
+<li>Share a UID with another application that has the necessary permissions. Use this method only when you need the platform to handle multiple APKs as a single application.</li>
+</ul></li>
+</ul>
+<p>The goal is to avoid confusing users with permission requests that appear out of context.</p>
+
+<h3 id="customizing-package-install">Customizing PackageInstaller</h3>
+<p>If desired, you can customize the Permissions UI <b>theme</b> by updating the default device themes (<code>Theme.DeviceDefault.Settings</code> and <code>Theme.DeviceDefault.Light.Dialog.NoActionBar</code>) used by PackageInstaller. However, because consistency is critical for app developers, you cannot customize the placement, position, and rules of when the Permissions UI appears.</p>
+<p>To include <b>strings</b> for additional languages, contribute the strings to AOSP.</p>
+
+<h3 id="creating-exceptions">Creating exceptions</h3>
+<p>You can pre-grant permissions to applications that are default handlers or providers for core OS functionality using the <code>DefaultPermissionGrantPolicy.java</code> in PackageManager. Examples:</p>
+
+<code>
+<p>ACTION_CALL (Dialer) Default</p>
+<ul>
+<li>Phone, Contacts, SMS, Microphone</li>
+</ul>
+<p>SMS_DELIVER_ACTION (SMS/MMS) Default</p>
+<ul>
+<li>Phone, Contacts, SMS</li>
+</ul>
+</code>
+
+<h3 id="defining-custom-perms">Defining custom permissions</h3>
+<p>You can define custom permissions and groups as <i>normal</i> or <i>dangerous</i> and add OEM/Carrier-specific permissions to existing permissions groups, just as you could in Android 5.x and earlier releases.</p>
+
+<p>In the Android 6.0 release, if you add a new dangerous permission, it must be handled in the same way as other dangerous permissions (requested during app runtime and revocable by users). Specifically: </p>
+
+<ul>
+<li>You can add new permissions to a current group, but you cannot modify the AOSP mapping of dangerous permissions and dangerous permissions group (e.g. you cannot remove a permission from a group and assign to other group).</li>
+<li>You can add new permission groups in applications installed on the device, but you cannot add new permissions groups in the platform manifest.</li>
+</ul>
+
+<h2 id="testing-perms">Testing permissions</h2>
+<p>The Android 6.0 release includes new Compatibility Test Suite (CTS) tests that verify individual permissions are mapped to the correct Groups. Passing these tests is a requirement for Android 6.0 CTS compatibility.</p>
\ No newline at end of file
diff --git a/src/devices/tech/config/uicc.jd b/src/devices/tech/config/uicc.jd
new file mode 100644
index 0000000..762e25d
--- /dev/null
+++ b/src/devices/tech/config/uicc.jd
@@ -0,0 +1,310 @@
+page.title=UICC Carrier Privileges
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Android 5.1 introduced a new mechanism to grant special privileges for APIs relevant
+to the Universal Integrated Circuit Card (UICC) owner’s apps. The Android platform will load
+certificates stored on a UICC and grant
+permission to apps signed by these certificates to make calls to a handful of
+special APIs. Since carriers have full control of the UICC, this mechanism
+provides a secure and flexible way to manage apps from the Mobile Network
+Operator (MNO) hosted on generic application distribution channels such as
+Google Play but still have special privileges on devices without the need for
+the apps to be signed by the per-device platform certificate or be
+pre-installed as a system app.</p>
+
+<h2 id=rules_on_uicc>Rules on UICC</h2>
+
+<p>Storage on the UICC is compatible with the <a
+href="http://www.globalplatform.org/specificationsdevice.asp">GlobalPlatform
+Secure Element Access Control specification</a>. The application identifier
+(AID) on card is A00000015141434C00, and the standard GET DATA command is used
+to fetch rules stored on the card. You may update these rules via card
+over-the-air (OTA) update. Data hierarchy is as follows (noting the
+two-character letter and number combination in parentheses is the object tag).
+(An extension to spec is under review.)</p>
+
+<p>Each rule is a REF-AR-DO (E2) and consists of a concatenation of a REF-DO and
+an AR-DO:</p>
+
+<ul>
+ <li>REF-DO (E1) contains a DeviceAppID-REF-DO or a concatenation of a
+DeviceAppID-REF-DO and a PKG-REF-DO.
+ <ul>
+ <li>DeviceAppID-REF-DO (C1) stores the SHA1 (20 bytes) or SHA256 (32 bytes)
+signature of the certificate.
+ <li>PKG-REF-DO (CA) is the full package name string defined in manifest, ASCII
+encoded, max length 127 bytes.
+ </ul>
+ <li>AR-DO (E3) is extended to include PERM-AR-DO (DB), which is an 8-byte bit mask
+representing 64 separate permissions.
+</ul>
+
+<p>If PKG-REF-DO is not present, any app signed by the certificate will be granted
+access; otherwise both certificate and package name need to match.</p>
+
+<h3 id=example>Example</h3>
+
+<p>App name: com.google.android.apps.myapp<br>
+Sha1 of certificate in hex string:</p>
+<pre>
+AB:CD:92:CB:B1:56:B2:80:FA:4E:14:29:A6:EC:EE:B6:E5:C1:BF:E4</pre>
+
+<p>Rule on UICC in hex string:</p>
+<pre>
+E243 <= 43 is value length in hex
+ E135
+ C114 ABCD92CBB156B280FA4E1429A6ECEEB6E5C1BFE4
+ CA1D 636F6D2E676F6F676C652E616E64726F69642E617070732E6D79617070
+ E30A
+ DB08 0000000000000001
+</pre>
+
+<h2 id=enabled_apis>Enabled APIs</h2>
+
+<p>Currently we support the following APIs, listed below (refer to
+developer.android.com for more details).</p>
+
+<h3 id=telephonymanager>TelephonyManager</h3>
+
+<p>API to check whether calling application has been granted carrier privileges:</p>
+
+<pre>
+<a
+href="http://developer.android.com/reference/android/telephony/TelephonyManager.html#hasCarrierPrivileges()">hasCarrierPrivileges</a>
+</pre>
+
+<p>APIs for brand and number override:</p>
+
+<pre>
+setOperatorBrandOverride
+setLine1NumberForDisplay
+setVoiceMailNumber
+</pre>
+
+<p>APIs for direct UICC communication:</p>
+
+<pre>
+iccOpenLogicalChannel
+iccCloseLogicalChannel
+iccExchangeSimIO
+iccTransmitApduLogicalChannel
+iccTransmitApduBasicChannel
+sendEnvelopeWithStatus
+</pre>
+
+<p>API to set device mode to global:</p>
+
+<pre>
+setPreferredNetworkTypeToGlobal
+</pre>
+
+<h3 id=smsmanager>SmsManager</h3>
+
+<p>API allows caller to create new incoming SMS messages:</p>
+
+<pre>
+injectSmsPdu
+</pre>
+
+<h4 id=carriermessagingservice>CarrierMessagingService</h4>
+
+<p>A service that receives calls from the system when new SMS and MMS are
+sent or
+received. To extend this class, you must declare the service in your manifest
+file with the android.Manifest.permission#BIND_CARRIER_MESSAGING_SERVICE
+permission and include an intent filter with the #SERVICE_INTERFACE action.</p>
+
+<pre>
+onFilterSms
+onSendTextSms
+onSendDataSms
+onSendMultipartTextSms
+onSendMms
+onDownloadMms
+</pre>
+
+<h4 id=telephonyprovider>TelephonyProvider</h4>
+
+<p>Content provider APIs that allow modification to the telephony database, value
+fields are defined at Telephony.Carriers:</p>
+
+<pre>
+insert, delete, update, query
+</pre>
+
+<p>See the <a
+href="https://developer.android.com/reference/android/provider/Telephony.html">Telephony
+reference on developer.android.com</a> for additional information.</p>
+
+<h2 id=android_platform>Android platform</h2>
+
+<p>On a detected UICC, the platform will construct internal UICC objects that
+include carrier privilege rules as part of the UICC. <a
+href="https://android.googlesource.com/platform/frameworks/opt/telephony/+/master/src/java/com/android/internal/telephony/uicc/UiccCarrierPrivilegeRules.java">UiccCarrierPrivilegeRules.java</a>
+will load rules, parse them from the UICC card, and cache them in memory. When
+a privilege check is needed, UiccCarrierPrivilegeRules will compare the caller
+certificate with its own rules one by one. If the UICC is removed, rules will
+be destroyed along with the UICC object.</p>
+
+<h2 id=faq>FAQ</h2>
+
+<p><strong>How can certificates be updated on the UICC?
+</strong></p>
+
+<p><em>A: Use existing card OTA update mechanism.
+</em></p>
+
+<p><strong>Can it co-exist with other rules?
+</strong></p>
+
+<p><em>A: It’s fine to have other security rules on the UICC under same AID; the
+platform will filter them out automatically.
+</em></p>
+
+<p><strong>What happens when the UICC is removed for an app that relies on the
+certificates on it?
+</strong></p>
+
+<p><em>A: The app will lose its privileges because the rules associated with the UICC
+are destroyed on UICC removal.
+</em></p>
+
+<p><strong>Is there a limit on the number of certificates on the UICC?
+</strong></p>
+
+<p><em>A: The platform doesn’t limit the number of certificates; but because the check
+is linear, too many rules may incur a latency for check.
+</em></p>
+
+<p><strong>Is there a limit to number of APIs we can support via this method?
+</strong></p>
+
+<p><em>A: No, but we limit the scope of APIs to carrier related.
+</em></p>
+
+<p><strong>Are there some APIs prohibited from using this method? If so, how do you
+enforce them? (ie. Will you have tests to validate which APIs are supported via
+this method?)
+</strong></p>
+
+<p><em>A: Please refer to the "API Behavioral Compatibility" section of the <a
+href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition
+Document CDD)</a>. We have some CTS tests to make sure the permission model of
+the APIs is not changed.
+</em></p>
+
+<p><strong>How does this work with the multi-SIM feature?
+</strong></p>
+
+<p><em>A: The default SIM that gets set by the user will be used.</em></p>
+
+<p><strong>Does this in any way interact or overlap with other SE access technologies e.g.
+SEEK?
+<em>A: As an example, SEEK uses the same AID as on the UICC. So the rules co-exist
+and are filtered by either SEEK or UiccCarrierPrivileges.</em>
+</strong></p>
+
+<p><strong>When is it a good time to check carrier privileges?
+<em>A: After the SIM state loaded broadcast.</em>
+</strong></p>
+
+<p><strong>Can OEMs disable part of carrier APIs?
+</strong></p>
+
+<p><em>A: No. We believe current APIs are the minimal set, and we plan to use the bit
+mask for finer granularity control in the future.
+</em></p>
+
+<p><strong>Does setOperatorBrandOverride override ALL other forms of operator name
+strings? For example, SE13, UICC SPN, network based NITZ, etc.?
+</strong></p>
+
+<p><em>A: See the SPN entry within TelephonyManager:
+<a
+href="http://developer.android.com/reference/android/telephony/TelephonyManager.html">http://developer.android.com/reference/android/telephony/TelephonyManager.html</a>
+</em></p>
+
+<p><strong>What does the injectSmsPdu method call do?
+</strong></p>
+
+<p><em>A: This facilitates SMS backup/restore in the cloud. The injectSmsPdu call
+enables the restore function.
+</em></p>
+
+<p><strong>For SMS filtering, is the onFilterSms call based on SMS UDH port filtering? Or
+would carrier apps have access to ALL incoming SMS?
+</strong></p>
+
+<p><em>A: Carriers have access to all SMS data.</em></p>
+
+<p><strong>Since the extension of DeviceAppID-REF-DO to support 32 bytes appears
+incompatible with the current GP spec (which allows 0 or 20 bytes only) why are
+you introducing this change? Do you not consider SHA-1 to be good enough to
+avoid collisions? Have you proposed this change to GP already, as this could
+be backwards incompatible with existing ARA-M / ARF?
+</strong></p>
+
+<p><em>A: For providing future proof security this extension introduces SHA-256 for
+DeviceAppID-REF-DO in addition to SHA-1 which is currently the only option in
+the GP SEAC standard. It is highly recommended to use SHA-256.</em></p>
+
+<p><strong>If DeviceAppID is 0 (empty), would you really apply the rule to all device
+applications not covered by a specific rule?
+</strong></p>
+
+<p><em>A: Carrier apis require deviceappid-ref-do be non-empty. Being empty is
+intended for test purpose and is not recommended for operational deployments.</em></p>
+
+<p><strong>According to your spec, PKG-REF-DO used just by itself, without
+DeviceAppID-REF-DO, should not be accepted. But it is still described in Table
+6-4 as extending the definition of REF-DO. Is this on purpose? What will be the
+behavior of the code when only a PKG-REF-DO is used in a REF-DO?
+</strong></p>
+
+<p><em>A: The option of having PKG-REF-DO as a single value item in REF-DO was removed
+in the latest version. PKG-REF-DO should only occur in combination with
+DeviceAppID-REF-DO.
+</em></p>
+
+<p><strong>We assume we can grant access to all carrier-based permissions or have a
+finer-grained control. What will define the mapping between the bit mask and
+the actual permissions then? One permission per class? One permission per
+method specifically? Will 64 separate permissions be enough in the long run?
+</strong></p>
+
+<p><em>A: This is reserved for the future, and we welcome suggestions.</em></p>
+
+<p><strong>Can you further define the DeviceAppID for Android specifically? Since this is
+the SHA-1 (20 bytes) hash value of the Publisher certificate used to signed the
+given app, shouldn't the name reflect that purpose? (The name could be
+confusing to many readers as the rule will be applicable then to all apps
+signed with that same Publisher certificate.)
+</strong></p>
+
+<p><em>A: See the <a
+href="#rules_on_uicc">Rules on UICC</a> section for details. The deviceAppID storing
+certificates is already supported by the existing spec. We tried to minimize
+spec changes to lower barrier for adoption. </em></p>
diff --git a/src/devices/tech/power/batterystats.jd b/src/devices/tech/power/batterystats.jd
index 92aeb04..11b0b48 100644
--- a/src/devices/tech/power/batterystats.jd
+++ b/src/devices/tech/power/batterystats.jd
@@ -1,4 +1,4 @@
-page.title=Viewing Battery Usage Data
+page.title=Viewing Battery Use Data
@jd:body
<!--
diff --git a/src/devices/tech/power/component.jd b/src/devices/tech/power/component.jd
new file mode 100644
index 0000000..cb38615
--- /dev/null
+++ b/src/devices/tech/power/component.jd
@@ -0,0 +1,259 @@
+page.title=Measuring Component Power
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+
+<p>You can determine individual component power consumption by comparing the current drawn by the
+device when the component is in the desired state (on, active, scanning, etc.) and when the
+component is off. Measure the average instantaneous current drawn on the device at a
+nominal voltage using an external power monitor, such as a bench power supply or specialized
+battery-monitoring tools (such as Monsoon Solution Inc. Power Monitor and Power Tool software).</p>
+
+<p>Manufacturers often supply information about the current consumed by an individual component.
+Use this information if it accurately represents the current drawn from the device battery in
+practice. However, validate manufacturer-provided values before using those values in your device
+power profile.</p>
+
+<h2 id="control-consumption">Controlling power consumption</h2>
+
+<p>When measuring, ensure the device does not have a connection to an external charge source, such
+as a USB connection to a development host used when running Android Debug Bridge (adb). The device
+under test might draw current from the host, thus lowering measurements at the battery. Avoid USB
+On-The-Go (OTG) connections, as the OTG device might draw current from the device under test.</p>
+
+<p>Excluding the component being measured, the system should run at a constant level of power
+consumption to avoid inaccurate measurements caused by changes in other components. System
+activities that can introduce unwanted changes to power measurements include:</p>
+
+<ul>
+<li><strong>Cellular, Wi-Fi, and Bluetooth receive, transmit, or scanning activity</strong>. When
+not measuring cell radio power, set the device to airplane mode and enable Wi-Fi or Bluetooth as
+appropriate.</li>
+<li><strong>Screen on/off</strong>. Colors displayed while the screen is on can affect power draw
+on some screen technologies. Turn the screen off when measuring values for non-screen components.</li>
+<li><strong>System suspend/resume</strong>. A screen off state can trigger a system suspension,
+placing parts of the device in a low-power or off state. This can affect power consumption of the
+component being measured and introduce large variances in power readings as the system periodically
+resumes to send alarms, etc. For details, see <a href="#control-suspend">Controlling system
+suspend</a>.</li>
+<li><strong>CPUs changing speed and entering/exiting low-power scheduler idle state</strong>.
+During normal operation, the system makes frequent adjustments to CPU speeds, the number of online
+CPU cores, and other system core states such as memory bus speed and voltages of power rails
+associated with CPUs and memory. During testing, these adjustments affect power measurements:
+<ul>
+<li>CPU speed scaling operations can reduce the amount of clock and voltage scaling of memory buses
+and other system core components.</li>
+<li>Scheduling activity can affect the percentage of the time CPUs spend in low-power idle states.
+For details on preventing these adjustments from occurring during testing, see
+<a href="#control-cpu">Controlling CPU speeds</a>.</li>
+</ul>
+
+</li>
+</ul>
+
+<p>For example, Joe Droid wants to compute the <code>screen.on</code> value for a device. He
+enables airplane mode on the device, runs the device at a stable current state, holds the CPU
+speed constant, and uses a partial wakelock to prevent system suspend. Joe then turns the device
+screen off and takes a measurement (200mA). Next, Joe turns the device screen on at minimum
+brightness and takes another measurement (300mA). The <code>screen.on</code> value is 100mA (300 -
+200).</p>
+
+<p class="note">
+<strong>Note</strong>: For components that don’t have a flat waveform of current consumption when
+active (such as cellular radio or Wi-Fi), measure the average current over time using a power
+monitoring tool.</p>
+
+<p>When using an external power source in place of the device battery, the system might experience
+problems due to an unconnected battery thermistor or integrated fuel gauge pins (i.e. an invalid
+reading for battery temperature or remaining battery capacity could shut down the kernel or Android
+system). Fake batteries can provide signals on thermistor or fuel gauge pins that mimic temperature
+and state of charge readings for a normal system, and may also provide convenient leads for
+connecting to external power supplies. Alternatively, you can modify the system to ignore the
+invalid data from the missing battery.</p>
+
+<h2 id="control-suspend">Controlling system suspend</h2>
+
+<p>This section describes how to avoid system suspend state when you don’t want it to interfere
+with other measurements, and how to measure the power draw of system suspend state when you do
+want to measure it.</p>
+
+<h3 id="prevent-suspend">Preventing system suspend</h3>
+
+<p>System suspend can introduce unwanted variance in power measurements and place system components
+in low-power states inappropriate for measuring active power use. To prevent the system from
+suspending while the screen is off, use a temporary partial wakelock. Using a USB cable, connect
+the device to a development host, then issue the following command:</p>
+
+<pre>
+$ adb shell "echo temporary > /sys/power/wake_lock"
+</pre>
+
+<p>While in <code>wake_lock</code>, the screen off state does not trigger a system suspend.
+(Remember to disconnect the USB cable from the device before measuring power consumption.)</p>
+
+<p>To remove the wakelock:</p>
+
+<pre>
+$ adb shell "echo temporary > /sys/power/wake_unlock"
+</pre>
+
+<h3 id="measure-suspend">Measuring system suspend</h3>
+
+<p>To measure the power draw during the system suspend state, measure the value of
+<code>cpu.idle</code> in the power profile. Before measuring:
+
+<ul>
+<li>Remove existing wakelocks (as described above).</li>
+<li>Place the device in airplane mode to avoid concurrent activity by the cellular radio, which
+might run on a processor separate from the SoC portions controlled by the system suspend.</li>
+<li>Ensure the system is in suspend state by:
+<ul>
+<li>Confirming current readings settle to a steady value. Readings should be within the expected
+range for the power consumption of the SoC suspend state plus the power consumption of system
+components that remain powered (such as the USB PHY).</li>
+<li>Checking the system console output.</li>
+<li>Watching for external indications of system status (such as an LED turning off when not in
+suspend).</li>
+</ul>
+</li>
+</ul>
+
+<h2 id="control-cpu">Controlling CPU speeds</h2>
+
+<p>Active CPUs can be brought online or put offline, have their clock speeds and associated
+voltages changed (possibly also affecting memory bus speeds and other system core power states),
+and can enter lower power idle states while in the kernel idle loop. When measuring different CPU
+power states for the power profile, avoid the power draw variance when measuring other parameters.
+The power profile assumes all CPUs have the same available speeds and power characteristics.</p>
+
+<p>While measuring CPU power, or while holding CPU power constant to make other measurements, keep
+the number of CPUs brought online constant (such as having one CPU online and the rest
+offline/hotplugged out). Keeping all CPUs except one in scheduling idle may product acceptable
+results. Stopping the Android framework with <code>adb shell stop</code> can reduce system
+scheduling activity.</p>
+
+<p>You must specify the available CPU speeds for your device in the power profile <code>cpu.speeds</code> entry. To get a list of available CPU speeds, run:</p>
+
+<pre>
+adb shell cat /sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state
+</pre>
+
+<p>These speeds match the corresponding power measurements in value <code>cpu.active</code>.</p>
+
+<p>For platforms where number of cores brought online significantly affects power consumption, you
+might need to modify the cpufreq driver or governor for the platform. Most platforms support
+controlling CPU speed using the userspace cpufreq governor and using sysfs interfaces to set the
+speed. For example, to set speed for 200MHz on a system with only 1 CPU or all CPUs sharing a
+common cpufreq policy, use the system console or adb shell to run the following commands:</p>
+
+<pre>
+echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
+echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq
+echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_min_freq
+echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed
+cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
+</pre>
+
+<p class="note">
+<strong>Note</strong>: The exact commands differ depending on the platform cpufreq implementation.
+</p>
+
+<p>These commands ensure the new speed is not outside the allowed bounds, set the new speed, then
+print the speed at which the CPU is actually running (for verification). If the current
+minimum speed prior to execution is higher than 200000, you might need to reverse the order
+of the first two lines, or execute the first line again to drop the minimum speed prior to
+setting the maximum speed.</p>
+
+<p>To measure current consumed by a CPU running at various speeds, use the system console to place
+the CPU in a CPU-bound loop using the command:</p>
+<pre>
+# while true; do true; done
+</pre>
+
+<p>Take the measurement while the loop executes.</p>
+
+<p>Some devices can limit maximum CPU speed while performing thermal throttling due to a high
+temperature measurement (i.e. after running CPUs at high speeds for sustained periods). Watch for
+such limiting, either using the system console output when taking measurements or by checking the
+kernel log after measuring.</p>
+
+<p>For the <code>cpu.awake</code> value, measure the power consumed when the system is not in
+suspend and not executing tasks. The CPU should be in a low-power scheduler <em>idle loop
+</em>, possibly executing an ARM Wait For Event instruction or in an SoC-specific low-power state
+with a fast-exit latency suitable for idle use.</p>
+
+<p>For the <code>cpu.active</code> value, measure power when the system is not in suspend mode and not executing tasks. One CPU (usually the primary CPU) should run the task while all other CPUs
+should be in an idle state.</p>
+
+<h2 id="screen-power">Measuring screen power</h2>
+
+<p>When measuring screen on power, ensure that other devices normally turned on when the screen is
+enabled are also on. For example, if the touchscreen and display backlight would normally be on
+when the screen is on, ensure these devices are on when you measure to get a realistic example of
+screen on power usage.</p>
+
+<p>Some display technologies vary in power consumption according to the colors displayed, causing
+power measurements to vary considerably depending on what is displayed on the screen at the time of
+measurement. When measuring, ensure the screen is displaying something that has power
+characteristics of a realistic screen. Aim between the extremes of an all-black screen (which
+consumes the lowest power for some technologies) and an all-white screen. A common choice is a view
+of a schedule in the calendar app, which has a mix of white background and non-white elements.</p>
+
+<p>Measure screen on power at <em>minimum</em> and <em>maximum</em> display/backlight brightness.
+To set minimum brightness:</p>
+
+<ul>
+<li><strong>Use the Android UI</strong> (not recommended). Set the Settings > Display Brightness
+slider to the minimum display brightness. However, the Android UI allows setting brightness only to
+a minimum of 10-20% of the possible panel/backlight brightness, and does not allow setting
+brightness so low that the screen might not be visible without great effort.</li>
+<li><strong>Use a sysfs file</strong> (recommended). If available, use a sysfs file to control
+panel brightness all the way down to the minimum brightness supported by the hardware.</li>
+</ul>
+
+<p>Additionally, if the platform sysfs file enables turning the LCD panel, backlight, and
+touchscreen on and off, use the file to take measurements with the screen on and off. Otherwise,
+set a partial wakelock so the system does not suspend, then turn on and off the
+screen with the power button.</p>
+
+<h2 id="wifi-power">Measuring Wi-Fi power</h2>
+
+<p>Perform Wi-Fi measurements on a relatively quiet network. Avoid introducing additional work
+processing high volumes of broadcast traffic that is unrelated to the activity being measured.</p>
+
+<p>The <code>wifi.on</code> value measures the power consumed when Wi-Fi is enabled but not
+actively transmitting or receiving. This is often measured as the delta between the current draw in
+system suspend (sleep) state with Wi-Fi enabled vs. disabled.</p>
+
+<p>The <code>wifi.scan</code> value measures the power consumed during a Wi-Fi scan for access
+points. Applications can trigger Wi-Fi scans using the WifiManager class
+<a href ="http://developer.android.com/reference/android/net/wifi/WifiManager.html">
+<code>startScan()</code>API</a>. You can also open Settings > Wi-Fi, which performs access point
+scans every few seconds with an apparent jump in power consumption, but you must subtract screen
+power from these measurements.</p>
+
+<p class="note">
+<strong>Note</strong>: Use a controlled setup (such as
+<a href="http://en.wikipedia.org/wiki/Iperf">iperf</a>) to generate network receive and transmit
+traffic.</p>
\ No newline at end of file
diff --git a/src/devices/tech/power/device.jd b/src/devices/tech/power/device.jd
new file mode 100644
index 0000000..985b9c0
--- /dev/null
+++ b/src/devices/tech/power/device.jd
@@ -0,0 +1,250 @@
+page.title=Measuring Device Power
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<p>You can determine device power consumption for Android devices that include a battery fuel gauge
+such as a Summit SMB347 or Maxim MAX17050 (available on many Nexus devices). Use the in-system
+gauge when external measurement equipment is not available or is inconvenient to
+connect to a device (such as in mobile usage).</p>
+
+<p>Measurements can include instantaneous current, remaining charge, battery capacity at test start
+and end, and more depending on the supported properties of the device (see below). For best
+results, perform device power measurements during long-running A/B tests that use the same device
+type with the same fuel gauge and same current sense resistor. Ensure the starting battery charge
+is the same for each device to avoid differing fuel gauge behavior at different points in the
+battery discharge curve.</p>
+
+<p>Even with identical test environments, measurements are not guaranteed to be of high absolute
+accuracy. However, most inaccuracies specific to the fuel gauge and sense resistor are consistent
+between test runs, making comparisons between identical devices useful. We recommend running
+multiple tests in different configurations to identify significant differences and relative power
+consumption between configurations.</p>
+
+<h2 id="power-consumption">Reading power consumption</h2>
+
+<p>To read power consumption data, insert calls to the API in your testing code.</p>
+
+<pre>
+import android.os.BatteryManager;
+import android.os.ServiceManager;
+import android.content.Context;
+BatteryManager mBatteryManager =
+(BatteryManager)Context.getSystemService(Context.BATTERY_SERVICE);
+Long energy =
+mBatteryManager.getLongProperty(BatteryManager.BATTERY_PROPERTY_ENERGY_COUNTER);
+Slog.i(TAG, "Remaining energy = " + energy + "nWh");
+</pre>
+
+<h2 id="avail-props">Available properties</h2>
+
+<p>Android supports the following battery fuel gauge properties:</p>
+
+<pre>
+BATTERY_PROPERTY_CHARGE_COUNTER Remaining battery capacity in microampere-hours
+BATTERY_PROPERTY_CURRENT_NOW Instantaneous battery current in microamperes
+BATTERY_PROPERTY_CURRENT_AVERAGE Average battery current in microamperes
+BATTERY_PROPERTY_CAPACITY Remaining battery capacity as an integer percentage
+BATTERY_PROPERTY_ENERGY_COUNTER Remaining energy in nanowatt-hours
+</pre>
+
+<p>Most properties are read from kernel power_supply subsystem attributes of similar names.
+However, the exact properties, resolution of property values, and update frequency
+available for a specific device depend on:</p>
+
+<ul>
+<li>Fuel gauge hardware, such as a Summit SMB347 or Maxim MAX17050.</li>
+<li>Fuel gauge-to-system connection, such as the value of external current sense resistors.</li>
+<li>Fuel gauge chip software configuration, such as values chosen for average current computation
+intervals in the kernel driver.</li>
+</ul>
+
+<p>For details, see the properties available for <a href="#nexus-devices">Nexus devices</a>.</p>
+
+<h2 id="maxim-fuel">Maxim fuel gauge</h2>
+
+<p>When determining battery state-of-charge over a long period of time, the Maxim fuel gauge
+(MAX17050, BC15) corrects for coulomb-counter offset measurements. For measurements made over a
+short period of time (such as power consumption metering tests), the fuel gauge does not make
+corrections, making the offset the primary source of error when current measurements are too small
+(although no amount of time can eliminate the offset error completely).</p>
+
+<p>For a typical 10mOhm sense resistor design, the offset current should be better than 1.5mA,
+meaning any measurement is +/-1.5mA (PCBoard layout can also affect this variation). For example,
+when measuring a large current (200mA) you can expect the following:</p>
+
+<ul>
+<li>2mA (1% gain error of 200mA due to fuel gauge gain error)</li>
+<li>+2mA (1% gain error of 200mA due to sense resistor error)</li>
+<li>+1.5mA (current sense offset error from fuel gauge)</li>
+</ul>
+
+<p>The total error is 5.5mA (2.75%). Compare this to a medium current (50mA) where the same error
+percentages give a total error of 7% or to a small current (15mA) where +/-1.5mA gives a total
+error of 10%.</p>
+
+<p>For best results, we recommend measuring greater than 20mA. Gain measurement errors are
+systematic and repeatable, enabling you to test a device in multiple modes and get clean relative
+measurements (with exceptions for the 1.5mA offset).</p>
+
+<p>For +/-100uA relative measurements, required measurement time depends on:</p>
+
+<ul>
+<li><b>ADC sampling noise</b>. The MAX17050 with its normal factory configuration produces +/-1.5mA
+sample-to-sample variation due to noise, with each sample delivered at 175.8ms. You can expect a
+rough +/-100uA for a 1 minute test window and a clean 3-sigma noise less than 100uA (or 1-sigma
+noise at 33uA) for a 6 minute test window.</li>
+<li><b>Sample Aliasing because of load variation</b>. Variation exaggerates errors, so for samples
+with variation inherent in the loading, consider using a longer test window.</li>
+</ul>
+
+<h2 id="nexus-devices">Supported Nexus devices</h2>
+
+<h5 id="nexus-5">Nexus 5</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 5</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17048 fuel gauge (ModelGauge™, no coulomb counter)</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>The fuel gauge does not support any measurements other than battery State Of Charge to a
+resolution of %/256 (1/256th of a percent of full battery capacity).</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5 id="nexus-6">Nexus 6</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 6</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
+current sense resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
+CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh (raw coulomb
+counter read, not adjusted by fuel gauge for coulomb counter offset, plus inputs from the ModelGauge
+m3 algorithm including empty compensation).<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5 id="nexus-9">Nexus 9</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 9</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
+current sense resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
+CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh.<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
+Accumulated current update period 175.8ms.<br>
+ADC sampled at 175ms quantization with a 4ms sample period. Can adjust duty cycle.</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5 id="nexus-10">Nexus 10</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 10</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Dallas Semiconductor DS2784 fuel gauge (a coulomb counter), with a 10mohm current sense
+resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>Current measurement (instantaneous and average) resolution is 156.3uA.<br>
+CURRENT_NOW instantaneous current update period is 3.5 seconds.<br>
+CURRENT_AVERAGE update period is 28 seconds (not configurable).<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 625uAh.<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution is 144nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
+Update period for all is 3.5 seconds.</td>
+</tr>
+</tbody>
+</table>
\ No newline at end of file
diff --git a/src/devices/tech/power/index.jd b/src/devices/tech/power/index.jd
index c3a6a9a..0876ae7 100644
--- a/src/devices/tech/power/index.jd
+++ b/src/devices/tech/power/index.jd
@@ -23,15 +23,15 @@
</div>
</div>
-<p>Battery usage information is derived from battery usage statistics and power profile values.</p>
+<p>Battery use information is derived from battery use statistics and power profile values.</p>
-<h2 id="usage-statistics">Battery Usage Statistics</h2>
+<h2 id="usage-statistics">Battery use statistics</h2>
-<p>The framework automatically determines battery usage statistics by tracking how long device
+<p>The framework automatically determines battery use statistics by tracking how long device
components spend in different states. As components (Wi-Fi chipset, cellular radio, Bluetooth, GPS,
display, CPU) change states (OFF/ON, idle/full power, low/high brightness, etc.), the controlling
-service reports to the framework BatteryStats service. BatteryStats collects information over time and
-stores it for use across reboots. The service doesn’t track battery current draw directly,
+service reports to the framework BatteryStats service. BatteryStats collects information over time
+and stores it for use across reboots. The service doesn’t track battery current draw directly,
but instead collects timing information that can be used to approximate battery
consumption by different components.</p>
@@ -40,9 +40,9 @@
<ul>
<li><strong>Push</strong>. Services aware of component changes push state changes to the
BatteryStats service.</li>
-<li><strong>Pull</strong>. For components such as the CPU usage by apps, the framework automatically
-pulls the data at transition points (such as starting or stopping an activity) to take a
-snapshot.</li>
+<li><strong>Pull</strong>. For components such as the CPU use by apps, the framework
+automatically pulls the data at transition points (such as starting or stopping an activity) to
+take a snapshot.</li>
</ul>
<p>Resource consumption is associated with the application using the resource. When multiple
@@ -50,27 +50,25 @@
suspending), the framework spreads consumption across those applications, although not necessarily
equally.</p>
-<p>To avoid losing usage statistics for a shutdown event, which may indicate battery power
-consumption problems (i.e. shutdown occurs because the battery reached zero remaining capacity), the
-framework flashes statistics approximately every 30 minutes.</p>
+<p>To avoid losing use statistics for a shutdown event, which may indicate battery power
+consumption problems (i.e. shutdown occurs because the battery reached zero remaining capacity),
+the framework flashes statistics approximately every 30 minutes.</p>
-<p>Battery usage statistics are handled entirely by the framework and do not require OEM
+<p>Battery use statistics are handled entirely by the framework and do not require OEM
modifications.</p>
-<h2 id="profile-values">Power Profile Values</h2>
+<h2 id="profile-values">Power profile values</h2>
-<p class="caution"><strong>Caution:</strong> Device manufacturers must
-provide a component power profile that defines the current consumption value
-for the component and the approximate battery drain caused by the component
-over time. This profile is defined in <a
-href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">platform/frameworks/base/core/res/res/xml/power_profile.xml</a>.
-See the <a href="#power-values">Power Values</a> table for guidance on these
-settings.</p>
+<p class="caution"><strong>Caution:</strong> Device manufacturers must provide a component power
+profile that defines the current consumption value for the component and the approximate battery
+drain caused by the component over time. This profile is defined in
+<a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">platform/frameworks/base/core/res/res/xml/power_profile.xml</a>.
+For guidance on these settings, see <a href="{@docRoot}devices/tech/power/values.html">Power Values</a>.</p>
-<p>Within a power profile, power consumption is specified in milliamps (mA) of
-current draw at a nominal voltage and can be a fractional value specified in microamps (uA). The
-value should be the mA consumed at the battery and not a value applicable to a power rail that does
-not correspond to current consumed from the battery.</p>
+<p>Within a power profile, power consumption is specified in milliamps (mA) of current draw at a
+nominal voltage and can be a fractional value specified in microamps (uA). The value should be the
+mA consumed at the battery and not a value applicable to a power rail that does not correspond to
+current consumed from the battery.</p>
<p>For example, a display power profile specifies the mA of current required to keep the display on
at minimum brightness and at maximum brightness. To determine the power cost (i.e the battery
@@ -78,689 +76,7 @@
each brightness level, then multiplies those time intervals by an interpolated display brightness
cost.</p>
-<p>The framework also multiplies the CPU time for each application by the mA required to run the CPU
-at a specific speed. This calculation establishes a comparative ranking of how much battery an
+<p>The framework also multiplies the CPU time for each application by the mA required to run the
+CPU at a specific speed. This calculation establishes a comparative ranking of how much battery an
application consumes by executing CPU code (time as the foreground app and total time including
background activity are reported separately).</p>
-
-<h2 id="component-power">Measuring Component Power</h2>
-
-<p>You can determine individual component power consumption by comparing the current drawn by the
-device when the component is in the desired state (on, active, scanning, etc.) and when the
-component is off. Measure the average instantaneous current drawn on the device at a
-nominal voltage using an external power monitor, such as a bench power supply or specialized
-battery-monitoring tools (such as Monsoon Solution Inc. Power Monitor and Power Tool software).</p>
-
-<p class="note">
-<strong>Note:</strong> Manufacturers often supply information about the current consumed by an
-individual component. Use this information if it accurately represents the current drawn from the
-device battery in practice. However, validate manufacturer-provided values before
-using those values in your device power profile.</p>
-
-<p>When measuring, ensure the device does not have a connection to an external charge source, such
-as a USB connection to a development host used when running Android Debug Bridge (adb). The device
-under test might draw current from the host, thus lowering measurements at the battery. Avoid USB
-On-The-Go (OTG) connections, as the OTG device might draw current from the device under test.</p>
-
-<p>Excluding the component being measured, the system should run at a constant level of power
-consumption to avoid inaccurate measurements caused by changes in other components. System
-activities that can introduce unwanted changes to power measurements include:</p>
-
-<ul>
-<li><strong>Cellular, Wi-Fi, and Bluetooth receive, transmit, or scanning activity</strong>. When
-not measuring cell radio power, set the device to airplane mode and enable Wi-Fi or Bluetooth as
-appropriate.</li>
-<li><strong>Screen on/off</strong>. Colors displayed while the screen is on can affect power draw on
-some screen technologies. Turn the screen off when measuring values for non-screen components.</li>
-<li><strong>System suspend/resume</strong>. A screen off state can trigger a system suspension,
-placing parts of the device in a low-power or off state. This can affect power consumption of the
-component being measured and introduce large variances in power readings as the system periodically
-resumes to send alarms, etc. For details, see <a href="#control-suspend">Controlling System
-Suspend</a>.</li>
-<li><strong>CPUs changing speed and entering/exiting low-power scheduler idle state</strong>. During
-normal operation, the system makes frequent adjustments to CPU speeds, the number of online CPU
-cores, and other system core states such as memory bus speed and voltages of power rails associated
-with CPUs and memory. During testing, these adjustments affect power measurements:
-
-<ul>
-<li>CPU speed scaling operations can reduce the amount of clock and voltage scaling of memory buses
-and other system core components.</li>
-<li>Scheduling activity can affect the percentage of the time CPUs spend in low-power idle states.
-For details on preventing these adjustments from occurring during testing, see
-<a href="#control-cpu">Controlling CPU Speeds</a>.</li>
-</ul>
-
-</li>
-</ul>
-
-<p>For example, Joe Droid wants to compute the <code>screen.on</code> value for a device. He enables
-airplane mode on the device, runs the device at a stable current state, holds the CPU speed constant
-, and uses a partial wakelock to prevent system suspend. Joe then turns the device screen off and
-takes a measurement (200mA). Next, Joe turns the device screen on at minimum brightness and takes
-another measurement (300mA). The <code>screen.on</code> value is 100mA (300 - 200).</p>
-
-<p>For components that don’t have a flat waveform of current consumption when active (such as
-cellular radio or Wi-Fi), measure the average current over time using a power monitoring tool.</p>
-
-<p>When using an external power source in place of the device battery, the system might experience
-problems due to an unconnected battery thermistor or integrated fuel gauge pins (i.e. an invalid
-reading for battery temperature or remaining battery capacity could shut down the kernel or Android
-system). Fake batteries can provide signals on thermistor or fuel gauge pins that mimic temperature
-and state of charge readings for a normal system, and may also provide convenient leads for
-connecting to external power supplies. Alternatively, you can modify the system to ignore the
-invalid data from the missing battery.</p>
-
-<h3 id="control-suspend">Controlling System Suspend</h3>
-
-<p>This section describes how to avoid system suspend state when you don’t want it to interfere with
-other measurements, and how to measure the power draw of system suspend state when you do want to
-measure it.</p>
-
-<h4>Preventing System Suspend</h4>
-
-<p>System suspend can introduce unwanted variance in power measurements and place system components
-in low-power states inappropriate for measuring active power use. To prevent the system from
-suspending while the screen is off, use a temporary partial wakelock. Using a USB cable, connect the
-device to a development host, then issue the following command:</p>
-
-<pre>
-$ adb shell "echo temporary > /sys/power/wake_lock"
-</pre>
-
-<p>While in wake_lock, the screen off state does not trigger a system suspend. (Remember to
-disconnect the USB cable from the device before measuring power consumption.)</p>
-
-<p>To remove the wakelock:</p>
-
-<pre>
-$ adb shell "echo temporary > /sys/power/wake_unlock"
-</pre>
-
-<h4>Measuring System Suspend</h4>
-
-<p>To measure the power draw during the system suspend state, measure the value of cpu.idle in the
-power profile. Before measuring:
-
-<ul>
-<li>Remove existing wakelocks (as described above).</li>
-<li>Place the device in airplane mode to avoid concurrent activity by the cellular radio, which
-might run on a processor separate from the SoC portions controlled by the system suspend.</li>
-<li>Ensure the system is in suspend state by:
-<ul>
-<li>Confirming current readings settle to a steady value. Readings should be within the expected
-range for the power consumption of the SoC suspend state plus the power consumption of system
-components that remain powered (such as the USB PHY).</li>
-<li>Checking the system console output.</li>
-<li>Watching for external indications of system status (such as an LED turning off when not in
-suspend).</li>
-</ul>
-</li>
-</ul>
-
-<h3 id="control-cpu">Controlling CPU Speeds</h3>
-
-<p>Active CPUs can be brought online or put offline, have their clock speeds and associated voltages
-changed (possibly also affecting memory bus speeds and other system core power states), and
-can enter lower power idle states while in the kernel idle loop. When measuring different CPU power
-states for the power profile, avoid the power draw variance when measuring other parameters. The
-power profile assumes all CPUs have the same available speeds and power characteristics.</p>
-
-<p>While measuring CPU power, or while holding CPU power constant to make other measurements, keep
-the number of CPUs brought online constant (such as having one CPU online and the rest
-offline/hotplugged out). Keeping all CPUs except one in scheduling idle may product acceptable
-results. Stopping the Android framework with <code>adb shell stop</code> can reduce system
-scheduling activity.</p>
-
-<p>You must specify the available CPU speeds for your device in the power profile cpu.speeds
-entry. To get a list of available CPU speeds, run:</p>
-
-<pre>
-adb shell cat /sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state
-</pre>
-
-<p>These speeds match the corresponding power measurements in value <code>cpu.active</code>.</p>
-
-<p>For platforms where number of cores brought online significantly affects power consumption, you
-might need to modify the cpufreq driver or governor for the platform. Most platforms support
-controlling CPU speed using the “userspace” cpufreq governor and using sysfs interfaces to
-set the speed. For example, to set speed for 200MHz on a system with only 1 CPU or all CPUs sharing
-a common cpufreq policy, use the system console or adb shell to run the following commands:</p>
-
-<pre>
-echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
-echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq
-echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_min_freq
-echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed
-cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
-</pre>
-
-<p class="note">
-<strong>Note</strong>: The exact commands differ depending on the platform cpufreq implementation.
-</p>
-
-<p>These commands ensure the new speed is not outside the allowed bounds, set the new speed, then
-print the speed at which the CPU is actually running (for verification). If the current
-minimum speed prior to execution is higher than 200000, you might need to reverse the order
-of the first two lines, or execute the first line again to drop the minimum speed prior to
-setting the maximum speed.</p>
-
-<p>To measure current consumed by a CPU running at various speeds, use the system console place the
-CPU in a CPU-bound loop using the command:</p>
-<pre>
-# while true; do true; done
-</pre>
-
-<p>Take the measurement while the loop executes.</p>
-
-<p>Some devices can limit maximum CPU speed while performing thermal throttling due to a high
-temperature measurement (i.e. after running CPUs at high speeds for sustained periods). Watch for
-such limiting, either using the system console output when taking measurements or by checking the
-kernel log after measuring.</p>
-
-<p>For the <code>cpu.awake</code> value, measure the power consumed when the system is not in
-suspend and not executing tasks. The CPU should be in a low-power scheduler <em>idle loop
-</em>, possibly executing an ARM Wait For Event instruction or in an SoC-specific low-power state
-with a fast-exit latency suitable for idle use.</p>
-
-<p>For the <code>cpu.active</code> value, power needs to be measured when the
-system is not in suspend mode and not executing tasks. One of the CPU (usually
-the primary CPU) should be running the task, and all the other CPUs should be in
-an idle state.</p>
-
-<h3 id="screen-power">Measuring Screen Power</h3>
-
-<p>When measuring screen on power, ensure that other devices normally turned on when the screen is
-enabled are also on. For example, if the touchscreen and display backlight would normally be on when
-the screen is on, ensure these devices are on when you measure to get a realistic example of screen
-on power usage.</p>
-
-<p>Some display technologies vary in power consumption according to the colors displayed, causing
-power measurements to vary considerably depending on what is displayed on the screen at the time of
-measurement. When measuring, ensure the screen is displaying something that has power
-characteristics of a realistic screen. Aim between the extremes of an all-black screen (which
-consumes the lowest power for some technologies) and an all-white screen. A common choice is a view
-of a schedule in the calendar app, which has a mix of white background and non-white elements.</p>
-
-<p>Measure screen on power at <em>minimum</em> and <em>maximum</em> display/backlight brightness.
-To set minimum brightness:</p>
-
-<ul>
-<li><strong>Use the Android UI</strong> (not recommended). Set the Settings > Display Brightness
-slider to the minimum display brightness. However, the Android UI allows setting brightness only to
-a minimum of 10-20% of the possible panel/backlight brightness, and does not allow setting
-brightness so low that the screen might not be visible without great effort.</li>
-<li><strong>Use a sysfs file</strong> (recommended). If available, use a sysfs file to control panel
-brightness all the way down to the minimum brightness supported by the hardware.</li>
-</ul>
-
-<p>Additionally, if the platform sysfs file enables turning the LCD panel, backlight, and
-touchscreen on and off, use the file to take measurements with the screen on and off. Otherwise,
-set a partial wakelock so the system does not suspend, then turn on and off the
-screen with the power button.</p>
-
-<h3 id="wifi-power">Measuring Wi-Fi Power</h3>
-
-<p>Perform Wi-Fi measurements on a relatively quiet network. Avoid introducing additional work
-processing high volumes of broadcast traffic that is unrelated to the activity being measured.</p>
-
-<p>The <code>wifi.on</code> value measures the power consumed when Wi-Fi is enabled but not actively
-transmitting or receiving. This is often measured as the delta between the current draw in
-system suspend (sleep) state with Wi-Fi enabled vs. disabled.</p>
-
-<p>The <code>wifi.scan</code> value measures the power consumed during a Wi-Fi scan for access
-points. Applications can trigger Wi-Fi scans using the WifiManager class
-<a href ="http://developer.android.com/reference/android/net/wifi/WifiManager.html">
-<code>startScan()</code>API</a>. You can also open Settings > Wi-Fi, which performs access point
-scans every few seconds with an apparent jump in power consumption, but you must subtract screen
-power from these measurements.</p>
-
-<p class="note">
-<strong>Note</strong>: Use a controlled setup (such as
-<a href="http://en.wikipedia.org/wiki/Iperf">iperf</a>) to generate network receive and transmit
-traffic.</p>
-
-<h2 id="device-power">Measuring Device Power</h2>
-
-<p>You can determine device power consumption for Android devices that include a battery fuel gauge
-such as a Summit SMB347 or Maxim MAX17050 (available on many Nexus devices). Use the in-system
-battery fuel gauge when external measurement equipment is not available or is inconvenient to
-connect to a device (such as in mobile usage).</p>
-
-<p>Measurements can include instantaneous current, remaining charge, battery capacity at test start
-and end, and more depending on the supported properties of the device (see below). For best results,
-perform device power measurements during long-running A/B tests that use the same device type with
-the same fuel gauge and same current sense resistor. Ensure the starting battery charge is the same
-for each device to avoid differing fuel gauge behavior at different points in the battery discharge
-curve.</p>
-
-<p>Even with identical test environments, measurements are not guaranteed to be of high absolute
-accuracy. However, most inaccuracies specific to the fuel gauge and sense resistor are consistent
-between test runs, making comparisons between identical devices useful. We recommend running
-multiple tests in different configurations to identify significant differences and relative power
-consumption between configurations.</p>
-
-<h3 id="power-consumption">Reading Power Consumption</h3>
-
-<p>To read power consumption data, insert calls to the API in your testing code.</p>
-
-<pre>
-import android.os.BatteryManager;
-import android.os.ServiceManager;
-import android.content.Context;
-BatteryManager mBatteryManager =
-(BatteryManager)Context.getSystemService(Context.BATTERY_SERVICE);
-Long energy =
-mBatteryManager.getLongProperty(BatteryManager.BATTERY_PROPERTY_ENERGY_COUNTER);
-Slog.i(TAG, "Remaining energy = " + energy + "nWh");
-</pre>
-
-<h3 id="avail-props">Available Properties</h3>
-
-<p>Android supports the following battery fuel gauge properties:</p>
-
-<pre>
-BATTERY_PROPERTY_CHARGE_COUNTER Remaining battery capacity in microampere-hours
-BATTERY_PROPERTY_CURRENT_NOW Instantaneous battery current in microamperes
-BATTERY_PROPERTY_CURRENT_AVERAGE Average battery current in microamperes
-BATTERY_PROPERTY_CAPACITY Remaining battery capacity as an integer percentage
-BATTERY_PROPERTY_ENERGY_COUNTER Remaining energy in nanowatt-hours
-</pre>
-
-<p>Most properties are read from kernel power_supply subsystem attributes of similar names.
-However, the exact properties, resolution of property values, and update frequency
-available for a specific device depend on:</p>
-
-<ul>
-<li>Fuel gauge hardware, such as a Summit SMB347 or Maxim MAX17050.</li>
-<li>Fuel gauge-to-system connection, such as the value of external current sense resistors.</li>
-<li>Fuel gauge chip software configuration, such as values chosen for average current computation
-intervals in the kernel driver.</li>
-</ul>
-
-<p>For details, see the properties available for <a href="#nexus-devices">Nexus devices</a>.</p>
-
-<h3 id="maxim-fuel">Maxim Fuel Gauge</h3>
-
-<p>When determining battery state-of-charge over a long period of time, the Maxim fuel gauge
-(MAX17050, BC15) corrects for coulomb-counter offset measurements. For measurements made over a
-short period of time (such as power consumption metering tests), the fuel gauge does not make
-corrections, making the offset the primary source of error when current measurements are too small
-(although no amount of time can eliminate the offset error completely).</p>
-
-<p>For a typical 10mOhm sense resistor design, the offset current should be better than 1.5mA,
-meaning any measurement is +/-1.5mA (PCBoard layout can also affect this variation). For example,
-when measuring a large current (200mA) you can expect the following:</p>
-
-<ul>
-<li>2mA (1% gain error of 200mA due to fuel gauge gain error)</li>
-<li>+2mA (1% gain error of 200mA due to sense resistor error)</li>
-<li>+1.5mA (current sense offset error from fuel gauge)</li>
-</ul>
-
-<p>The total error is 5.5mA (2.75%). Compare this to a medium current (50mA) where the same error
-percentages give a total error of 7% or to a small current (15mA) where +/-1.5mA gives a total error
-of 10%.</p>
-
-<p>For best results, we recommend measuring greater than 20mA. Gain measurement errors are
-systematic and repeatable, enabling you to test a device in multiple modes and get clean relative
-measurements (with exceptions for the 1.5mA offset).</p>
-
-<p>For +/-100uA relative measurements, required measurement time depends on:</p>
-
-<ul>
-<li><b>ADC sampling noise</b>. The MAX17050 with its normal factory configuration produces +/-1.5mA
-sample-to-sample variation due to noise, with each sample delivered at 175.8ms. You can expect a
-rough +/-100uA for a 1 minute test window and a clean 3-sigma noise less than 100uA (or 1-sigma
-noise at 33uA) for a 6 minute test window.</li>
-<li><b>Sample Aliasing because of load variation</b>. Variation exaggerates errors, so for samples
-with variation inherent in the loading, consider using a longer test window.</li>
-</ul>
-
-<h3 id="nexus-devices">Supported Nexus Devices</h3>
-
-<h5 id="nexus-5">Nexus 5</h5>
-
-<table>
-<tbody>
-<tr>
-<th>Model</th>
-<td>Nexus 5</td>
-</tr>
-<tr>
-<th>Fuel Gauge</th>
-<td>Maxim MAX17048 fuel gauge (ModelGauge™, no coulomb counter)</td>
-</tr>
-<tr>
-<th>Properties</th>
-<td>BATTERY_PROPERTY_CAPACITY</td>
-</tr>
-<tr>
-<th>Measurements</th>
-<td>The fuel gauge does not support any measurements other than battery State Of Charge to a
-resolution of %/256 (1/256th of a percent of full battery capacity).</td>
-</tr>
-</tbody>
-</table>
-
-
-<h5 id="nexus-6">Nexus 6</h5>
-
-<table>
-<tbody>
-<tr>
-<th>Model</th>
-<td>Nexus 6</td>
-</tr>
-<tr>
-<th>Fuel Gauge</th>
-<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
-current sense resistor.</td>
-</tr>
-<tr>
-<th>Properties</th>
-<td>BATTERY_PROPERTY_CAPACITY<br>
-BATTERY_PROPERTY_CURRENT_NOW<br>
-BATTERY_PROPERTY_CURRENT_AVERAGE<br>
-BATTERY_PROPERTY_CHARGE_COUNTER<br>
-BATTERY_PROPERTY_ENERGY_COUNTER</td>
-</tr>
-<tr>
-<th>Measurements</th>
-<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
-CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
-CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh (raw coulomb
-counter read, not adjusted by fuel gauge for coulomb counter offset, plus inputs from the ModelGauge
-m3 algorithm including empty compensation).<br>
-CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
-ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.</td>
-</tr>
-</tbody>
-</table>
-
-
-<h5 id="nexus-9">Nexus 9</h5>
-
-<table>
-<tbody>
-<tr>
-<th>Model</th>
-<td>Nexus 9</td>
-</tr>
-<tr>
-<th>Fuel Gauge</th>
-<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
-current sense resistor.</td>
-</tr>
-<tr>
-<th>Properties</th>
-<td>BATTERY_PROPERTY_CAPACITY<br>
-BATTERY_PROPERTY_CURRENT_NOW<br>
-BATTERY_PROPERTY_CURRENT_AVERAGE<br>
-BATTERY_PROPERTY_CHARGE_COUNTER<br>
-BATTERY_PROPERTY_ENERGY_COUNTER</td>
-</tr>
-<tr>
-<th>Measurements</th>
-<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
-CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
-CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh.<br>
-CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
-ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
-Accumulated current update period 175.8ms.<br>
-ADC sampled at 175ms quantization with a 4ms sample period. Can adjust duty cycle.</td>
-</tr>
-</tbody>
-</table>
-
-
-<h5 id="nexus-10">Nexus 10</h5>
-
-<table>
-<tbody>
-<tr>
-<th>Model</th>
-<td>Nexus 10</td>
-</tr>
-<tr>
-<th>Fuel Gauge</th>
-<td>Dallas Semiconductor DS2784 fuel gauge (a coulomb counter), with a 10mohm current sense
-resistor.</td>
-</tr>
-<tr>
-<th>Properties</th>
-<td>BATTERY_PROPERTY_CAPACITY<br>
-BATTERY_PROPERTY_CURRENT_NOW<br>
-BATTERY_PROPERTY_CURRENT_AVERAGE<br>
-BATTERY_PROPERTY_CHARGE_COUNTER<br>
-BATTERY_PROPERTY_ENERGY_COUNTER</td>
-</tr>
-<tr>
-<th>Measurements</th>
-<td>Current measurement (instantaneous and average) resolution is 156.3uA.<br>
-CURRENT_NOW instantaneous current update period is 3.5 seconds.<br>
-CURRENT_AVERAGE update period is 28 seconds (not configurable).<br>
-CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 625uAh.<br>
-CHARGE_COUNTER_EXT (extended precision in kernel) resolution is 144nAh.<br>
-ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
-Update period for all is 3.5 seconds.</td>
-</tr>
-</tbody>
-</table>
-
-
-<h2 id="viewing-usage">Viewing Battery Usage Data</h2>
-
-See <a href="{@docRoot}devices/tech/power/batterystats.html">Viewing Battery Usage Data</a>.
-
-<h2 id="power-values">Power Values</h2>
-
-<p>Device manufacturers must provide a component power profile defined in
-<em><device></em>/frameworks/base/core/res/res/xml/power_profile.xml. To
-determine these values, use hardware that measures the power being used by
-the device and perform the various operations for which information is needed.
-Measure the power use during those operations and compute the values (deriving
-differences from other base-line power uses as appropriate).</p>
-
-<table>
-<tr>
- <th>Name</th>
- <th>Description</th>
- <th>Example Value</th>
- <th>Notes</th>
-</tr>
-<tr>
- <td>none</td>
- <td>Nothing</td>
- <td>0</td>
- <td></td>
-</tr>
-
-<tr>
- <td>screen.on</td>
- <td>Additional power used when screen is turned on at minimum brightness.</td>
- <td>200mA</td>
- <td>Includes touch controller and display backlight. At 0 brightness, not the Android minimum which tends to be 10 or 20%.</td>
-</tr>
-
-<tr>
- <td>screen.full</td>
- <td>Additional power used when screen is at maximum brightness, compared to screen at minimum brightness.</td>
- <td>100mA-300mA</td>
- <td>A fraction of this value (based on screen brightness) is added to the screen.on value to compute the power usage of the screen.</td>
-</tr>
-
-<tr>
- <td>bluetooth.active</td>
- <td>Additional power used when playing audio through bluetooth A2DP.</td>
- <td>14mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>bluetooth.on</td>
- <td>Additional power used when bluetooth is turned on but idle.</td>
- <td>1.4mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>wifi.on</td>
- <td>Additional power used when Wi-Fi is turned on but not receiving, transmitting, or scanning.</td>
- <td>2mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>wifi.active</td>
- <td>Additional power used when transmitting or receiving over Wi-Fi.</td>
- <td>31mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>wifi.scan</td>
- <td>Additional power used when Wi-Fi is scanning for access points.</td>
- <td>100mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>dsp.audio</td>
- <td>Additional power used when audio decoding/encoding via DSP.</td>
- <td>14.1mA</td>
- <td>Reserved for future use.</td>
-</tr>
-
-
-<tr>
- <td>dsp.video</td>
- <td>Additional power used when video decoding via DSP.</td>
- <td>54mA</td>
- <td>Reserved for future use.</td>
-</tr>
-
-<tr>
- <td>gps.on</td>
- <td>Additional power used when GPS is acquiring a signal.</td>
- <td>50mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>radio.active</td>
- <td>Additional power used when cellular radio is transmitting/receiving.</td>
- <td>100mA-300mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>radio.scanning</td>
- <td>Additional power used when cellular radio is paging the tower.</td>
- <td>1.2mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>radio.on</td>
- <td>Additional power used when the cellular radio is on. Multi-value entry, one per signal strength (no signal, weak, moderate, strong).</td>
- <td>1.2mA</td>
- <td>Some radios boost power when they search for a cell tower and do not detect a signal. These
- numbers could all be the same or decreasing with increasing signal strength. If you provide only
- one value, the same value will be used for all strengths. If you provide 2 values, the first will
- be for no-signal and the second for all other strengths, and so on.</td>
-</tr>
-
-<tr>
- <td>cpu.speeds</td>
- <td>Multi-value entry that lists each possible CPU speed in KHz.</td>
- <td>125000KHz, 250000KHz, 500000KHz, 1000000KHz, 1500000KHz</td>
- <td>The number and order of entries must correspond to the mA entries in cpu.active.</td>
-</tr>
-
-<tr>
- <td>cpu.idle</td>
- <td>Total power drawn by the system when CPUs (and the SoC) are in system suspend state.</td>
- <td>3mA</td>
- <td></td>
-</tr>
-
-<tr>
- <td>cpu.awake</td>
- <td>Additional power used when CPUs are in scheduling idle state (kernel idle loop); system is not
- in system suspend state.</td>
- <td>50mA</td>
- <td>Your platform might have more than one idle state in use with differing
-levels of power consumption; choose a representative idle state for longer
-periods of scheduler idle (several milliseconds). Examine the power graph on
-your measurement equipment and choose samples where the CPU is at its lowest
-consumption, discarding higher samples where the CPU exited idle.</td>
-</tr>
-
-<tr>
- <td>cpu.active</td>
- <td>Additional power used by CPUs when running at different speeds.</td>
- <td>100mA, 120mA, 140mA, 160mA, 200mA</td>
- <td>Set the max speed in the kernel to each of the allowed speeds and peg the CPU at that
-speed. The number of entries here correspond to the number of entries in cpu.speeds, in the
-same order.</td>
-</tr>
-
-<tr>
- <td>battery.capacity</td>
- <td>The total battery capacity in mAh.</td>
- <td>3000mAh</td>
- <td></td>
-</tr>
-
-</table>
-
-<h3 id="sample">Sample file</h3>
-
-<pre>
-<!-- Most values are the incremental current used by a feature, in mA (measured at
-nominal voltage). OEMs must measure and provide actual values before shipping a device.
-Example real-world values are given, but are dependent on the platform
-and can vary significantly, so should be measured on the shipping platform with a power meter.
--->
-0
-200
-160
-10
-<!-- Bluetooth stereo audio playback 10.0 mA -->
-1.3
-0.5
-30
-100
-12
-50
-50
-75
-1.1
-<!-- Strength 0 to BINS-1 (4) -->
-1.1
-
-<!-- Different CPU speeds as reported in
-/sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state -->
-
-250000 <!-- 250 MHz -->
-500000 <!-- 500 MHz -->
-750000 <!-- 750 MHz -->
-1000000 <!-- 1 GHz -->
-1200000 <!-- 1.2 GHz -->
-
-<!-- Power consumption when CPU is idle -->
-3.0
-50.1
-<!-- Power consumption at different speeds -->
-
-100 <!-- 250 MHz -->
-120 <!-- 500 MHz -->
-140 <!-- 750 MHz -->
-155 <!-- 1 GHz -->
-175 <!-- 1.2 GHz -->
-
-<!-- This is the battery capacity in mAh -->
-3000
-<!-- Battery capacity is 3000 mAH (at 3.6 Volts) -->
-
-</pre>
diff --git a/src/devices/tech/power/values.jd b/src/devices/tech/power/values.jd
new file mode 100644
index 0000000..e88900a
--- /dev/null
+++ b/src/devices/tech/power/values.jd
@@ -0,0 +1,264 @@
+page.title=Measuring Power Values
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+
+<p>Device manufacturers must provide a component power profile in
+<code>/frameworks/base/core/res/res/xml/power_profile.xml</code>.</p>
+
+<p>To determine values for power profiles, use hardware that measures the power
+being used by the device and perform the various operations for which
+information is needed. Measure the power use during those operations and compute
+the values (deriving differences from other baseline power uses as appropriate).
+</p>
+
+<h2 id="values">Power values</h2>
+
+<table>
+<tr>
+ <th>Name</th>
+ <th>Description</th>
+ <th>Example Value</th>
+ <th>Notes</th>
+</tr>
+<tr>
+ <td>none</td>
+ <td>Nothing</td>
+ <td>0</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>screen.on</td>
+ <td>Additional power used when screen is turned on at minimum brightness.</td>
+ <td>200mA</td>
+ <td>Includes touch controller and display backlight. At 0 brightness, not the
+ Android minimum which tends to be 10 or 20%.</td>
+</tr>
+
+<tr>
+ <td>screen.full</td>
+ <td>Additional power used when screen is at maximum brightness, compared to
+ screen at minimum brightness.</td>
+ <td>100mA-300mA</td>
+ <td>A fraction of this value (based on screen brightness) is added to the
+ screen.on value to compute the power usage of the screen.</td>
+</tr>
+
+<tr>
+ <td>bluetooth.active</td>
+ <td>Additional power used when playing audio through Bluetooth A2DP.</td>
+ <td>14mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>bluetooth.on</td>
+ <td>Additional power used when Bluetooth is turned on but idle.</td>
+ <td>1.4mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>wifi.on</td>
+ <td>Additional power used when Wi-Fi is turned on but not receiving,
+ transmitting, or scanning.</td>
+ <td>2mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>wifi.active</td>
+ <td>Additional power used when transmitting or receiving over Wi-Fi.</td>
+ <td>31mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>wifi.scan</td>
+ <td>Additional power used when Wi-Fi is scanning for access points.</td>
+ <td>100mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>dsp.audio</td>
+ <td>Additional power used when audio decoding/encoding via DSP.</td>
+ <td>14.1mA</td>
+ <td>Reserved for future use.</td>
+</tr>
+
+
+<tr>
+ <td>dsp.video</td>
+ <td>Additional power used when video decoding via DSP.</td>
+ <td>54mA</td>
+ <td>Reserved for future use.</td>
+</tr>
+
+<tr>
+ <td>camera.avg</td>
+ <td>Average power use by the camera subsystem for a typical camera
+ application.</td>
+ <td>600mA</td>
+ <td>Intended as a rough estimate for an application running a preview
+ and capturing approximately 10 full-resolution pictures per minute.</td>
+</tr>
+
+<tr>
+ <td>camera.flashlight</td>
+ <td>Average power used by the camera flash module when on.</td>
+ <td>200mA</td>
+ <td></td>
+</tr>
+
+
+<tr>
+ <td>gps.on</td>
+ <td>Additional power used when GPS is acquiring a signal.</td>
+ <td>50mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>radio.active</td>
+ <td>Additional power used when cellular radio is transmitting/receiving.</td>
+ <td>100mA-300mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>radio.scanning</td>
+ <td>Additional power used when cellular radio is paging the tower.</td>
+ <td>1.2mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>radio.on</td>
+ <td>Additional power used when the cellular radio is on. Multi-value entry,
+ one per signal strength (no signal, weak, moderate, strong).</td>
+ <td>1.2mA</td>
+ <td>Some radios boost power when they search for a cell tower and do not
+ detect a signal. Values can be the same or decrease with increasing signal
+ strength. If you provide only one value, the same value is used for all
+ strengths. If you provide two values, the first is used for no-signal, the
+ second value is used for all other strengths, and so on.</td>
+</tr>
+
+<tr>
+ <td>cpu.speeds</td>
+ <td>Multi-value entry that lists each possible CPU speed in KHz.</td>
+ <td>125000KHz, 250000KHz, 500000KHz, 1000000KHz, 1500000KHz</td>
+ <td>The number and order of entries must correspond to the mA entries in
+ cpu.active.</td>
+</tr>
+
+<tr>
+ <td>cpu.idle</td>
+ <td>Total power drawn by the system when CPUs (and the SoC) are in system
+ suspend state.</td>
+ <td>3mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>cpu.awake</td>
+ <td>Additional power used when CPUs are in scheduling idle state
+ (kernel idle loop); system is not in system suspend state.</td>
+ <td>50mA</td>
+ <td>Your platform might have more than one idle state in use with differing
+ levels of power consumption; choose a representative idle state for longer
+ periods of scheduler idle (several milliseconds). Examine the power graph on
+ your measurement equipment and choose samples where the CPU is at its lowest
+ consumption, discarding higher samples where the CPU exited idle.</td>
+</tr>
+
+<tr>
+ <td>cpu.active</td>
+ <td>Additional power used by CPUs when running at different speeds.</td>
+ <td>100mA, 120mA, 140mA, 160mA, 200mA</td>
+ <td>Set the max speed in the kernel to each of the allowed speeds and peg the
+ CPU at that speed. The number of entries here correspond to the number of
+ entries in cpu.speeds, in the same order.</td>
+</tr>
+
+<tr>
+ <td>battery.capacity</td>
+ <td>Total battery capacity in mAh.</td>
+ <td>3000mAh</td>
+ <td></td>
+</tr>
+</table>
+
+<h2 id="sample">Sample file</h2>
+
+<pre>
+<!-- Most values are the incremental current used by a feature, in mA (measured at
+nominal voltage). OEMs must measure and provide actual values before shipping a device.
+Example real-world values are given, but are dependent on the platform
+and can vary significantly, so should be measured on the shipping platform with a power meter.
+-->
+0
+200
+160
+10
+<!-- Bluetooth stereo audio playback 10.0 mA -->
+1.3
+0.5
+30
+100
+12
+50
+50
+75
+1.1
+<!-- Strength 0 to BINS-1 (4) -->
+1.1
+
+<!-- Different CPU speeds as reported in
+/sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state -->
+
+250000 <!-- 250 MHz -->
+500000 <!-- 500 MHz -->
+750000 <!-- 750 MHz -->
+1000000 <!-- 1 GHz -->
+1200000 <!-- 1.2 GHz -->
+
+<!-- Power consumption when CPU is idle -->
+3.0
+50.1
+<!-- Power consumption at different speeds -->
+
+100 <!-- 250 MHz -->
+120 <!-- 500 MHz -->
+140 <!-- 750 MHz -->
+155 <!-- 1 GHz -->
+175 <!-- 1.2 GHz -->
+
+<!-- This is the battery capacity in mAh -->
+3000
+<!-- Battery capacity is 3000 mAH (at 3.6 Volts) -->
+
+</pre>
\ No newline at end of file
diff --git a/src/devices/tech/security/authentication/index.jd b/src/devices/tech/security/authentication/index.jd
new file mode 100644
index 0000000..66560a7
--- /dev/null
+++ b/src/devices/tech/security/authentication/index.jd
@@ -0,0 +1,250 @@
+page.title=Authentication
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id=overview>Overview</h2>
+
+<p>Android 6.0 introduces the concept of user-authentication-gated cryptographic
+keys. To achieve this, two key components need to work together.
+First is the cryptographic key storage and service provider, which stores
+cryptographic keys and provides standard crypto routines on top of them. Second
+is any number of user authenticators that may attest to the user's presence
+and/or successful authentication.</p>
+
+<p>The cryptographic key storage in Android is provided by the keystore service and Keymaster.
+(Also see information about
+the <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore system</a>,
+at the framework level, which is backed by the keystore service.) For Android 6.0,
+the two supported authentication components are Gatekeeper (for
+PIN/pattern/password authentication) and Fingerprint (for fingerprint
+authentication). These components communicate their authentication
+state with the keystore service via an authenticated channel.</p>
+
+<ul>
+ <li><strong>The keystore service and Keymaster.</strong> Cryptographic services,
+ including hardware-backed cryptography for key storage,
+ which might include a Trusted Execution Environment (TEE).</li>
+ <li><strong>Gatekeeper</strong>. Components for PIN, pattern, and password authentication.</li>
+ <li><strong>Fingerprint.</strong> Components for fingerprint authentication.</li>
+</ul>
+
+<h2 id=architecture>Architecture</h2>
+
+<p>The Gatekeeper and Fingerprint components work with Keymaster and other
+components to support the use of hardware-backed <a href="#authentication_token_format">authentication tokens</a> (referred to below as "AuthTokens").</p>
+
+<h3 id=enrollment>Enrollment</h3>
+
+<p>Upon first boot of the device after a factory reset, all authenticators are prepared to receive
+credential enrollments from the user.</p>
+
+<p>The user must initially enroll a PIN/pattern/password with Gatekeeper. This
+initial enrollment creates a randomly generated, 64-bit User SID (user secure
+identifier, described further below) that serves as an identifier for the user
+and as a binding token for the user's cryptographic material.
+This User SID is cryptographically bound to the user's password.
+As detailed below, successful authentications to Gatekeeper result in AuthTokens that contain the User SID
+for that password.</p>
+
+<p>When a user wants to change their credential, they must present their existing
+credential. If the existing credential is verified successfully, the User SID
+associated with the existing credential is transferred to the new credential.
+This allows the user to keep accessing their keys after changing their
+credential. If a user does not present their existing credential, the new one
+is enrolled with a fully random User SID. The user can access the device but
+keys created under the old User SID are permanently lost. This is known as an
+"untrusted enroll."</p>
+
+<p>Note that an untrusted enroll will not be allowed under normal circumstances by
+the Android framework, so most users won't ever see this functionality.
+However, forcible password resets either by a device administrator or an
+attacker may cause this to occur.</p>
+
+<h3 id=authentication>Authentication</h3>
+
+<p>Now that the user has set up a credential and received a User SID, they may
+proceed to start authentication.</p>
+
+<p>In the diagram below, authentication starts when a user provides a PIN,
+pattern, password, or fingerprint. All TEE components share a secret key which
+they use to authenticate each other's messages.</p>
+
+<img src="../images/authentication-flow.png" alt="Authentication flow" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> Authentication flow</p>
+
+<p>The numbers in the following steps correspond to the numbers in the diagram
+above, and include reference to both the Android OS and the TEE OS: </p>
+
+<ol>
+ <li>A user provides a PIN, pattern, password, or fingerprint. The
+<code>LockSettingsService</code> or <code>FingerprintService</code> make a request via Binder to the
+Gatekeeperd or fingerprintd daemon in the Android OS. Note that fingerprint
+authentication occurs asynchronously after the fingerprint request is sent.
+ <li>This step involves <strong>either</strong> Gatekeeperd (option 1 below)
+ <strong>or</strong> fingerprintd (option 2 below),
+ depending on whether a pin/pattern/password, or fingerprint, is provided.
+ <ul>
+ <li>The Gatekeeperd daemon sends a pin, pattern, or password hash (received in step
+1) to its counterpart (Gatekeeper) in the TEE. If authentication in the TEE is
+successful, Gatekeeper in the TEE sends an AuthToken containing the
+corresponding User SID, signed with the AuthToken HMAC key, to its
+counterpart in the Android OS.
+ <li>Alternatively, the fingerprintd daemon, which listens for fingerprint events,
+sends the data (received in step 1) to its counterpart (Fingerprint) in the
+TEE. If authentication in the TEE is successful, Fingerprint in the TEE sends
+an AuthToken, signed with the AuthToken HMAC key, to its counterpart in the Android OS.
+ </ul>
+ <li>The Gatekeeperd or fingerprintd daemon receives a signed AuthToken and passes
+the AuthToken to the keystore service via an extension to
+the keystore service's Binder interface. Additionally, Gatekeeperd notifies the keystore service when
+the device is re-locked and when the device password changes.
+ <li>The keystore service passes to Keymaster the AuthTokens received from Gatekeeperd and
+fingerprintd, verifying the AuthTokens with the key shared with the Gatekeeper
+and Fingerprint trustlets. Keymaster trusts the timestamp in the token as the
+last authentication time and bases a key release decision (to allow an app to
+use the key) on the timestamp.
+</ol>
+
+<p class="note"><strong>Note:</strong> AuthTokens are invalidated whenever a device reboots.</p>
+
+<h2 id=authentication_token_format>Authentication token format</h2>
+
+<p>The AuthToken format described in the
+<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/hw_auth_token.h"><code>hw_auth_token.h</code></a> file is
+necessary for token sharing and compatibility across languages and
+components. See the following file:</p>
+<pre>
+hardware/libhardware/include/hardware/hw_auth_token.h
+</pre>
+
+<p>A simple serialization protocol with the required fields is defined in the
+table below. The fields are fixed size.</p>
+
+<p>Field descriptions are below the table.</p>
+<table>
+ <tr>
+ <th><strong>Field</strong></th>
+ <th><strong>Type</strong></th>
+ <th><strong>Required or Optional</strong></th>
+ </tr>
+ <tr>
+ <td>AuthToken Version</td>
+ <td>1 byte</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Challenge</td>
+ <td>64-bit unsigned integer</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>User SID</td>
+ <td>64-bit unsigned integer</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Authenticator ID</td>
+ <td>64-bit unsigned integer in network order</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>Authenticator type</td>
+ <td>32-bit unsigned integer in network order</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Timestamp</td>
+ <td>64-bit unsigned integer in network order</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>AuthToken HMAC key (SHA-256)</td>
+ <td>256-bit blob</td>
+ <td>Required</td>
+ </tr>
+</table>
+
+<h3 id=field_descriptions>Field descriptions </h3>
+
+<p>This section describes the fields of the AuthToken table above.</p>
+
+<p><strong>AuthToken Version:</strong> Group tag for all fields below.</p>
+
+<p><strong>Challenge:</strong> A random integer to prevent replay attacks. Usually the ID of a requested
+crypto operation. Currently used by transactional fingerprint authorizations.
+If present, the AuthToken is valid only for crypto operations containing the
+same challenge.</p>
+
+<p><strong>User SID</strong>: Non-repeating user identifier tied cryptographically to all keys associated
+with device authentication. For more information, see the Gatekeeper page.</p>
+
+<p><strong>Authenticator ID (ASID)</strong>: Identifier used to bind to a specific authenticator policy. All
+authenticators have their own value of ASID that they can change according to
+their own requirements.</p>
+
+<p><strong>Authenticator Type</strong>: Either Gatekeeper or Fingerprint, as follows:</p>
+<table>
+ <tr>
+ <th><strong>Authenticator Type</strong></th>
+ <th><strong>Authenticator Name</strong></th>
+ </tr>
+ <tr>
+ <td>0x00</td>
+ <td>Gatekeeper</td>
+ </tr>
+ <tr>
+ <td>0x01</td>
+ <td>Fingerprint</td>
+ </tr>
+</table>
+
+<p><strong>Timestamp</strong>: Time (in milliseconds) since the most recent system boot.</p>
+
+<p><strong>AuthToken HMAC key</strong>: Keyed SHA-256 MAC of all fields except the HMAC field.</p>
+
+<h2 id=device_boot_flow>Device boot flow</h2>
+
+<p>On every boot of a device, the AuthToken HMAC key must be generated and shared
+with all TEE components (Gatekeeper, Fingerprint, and Keymaster). Thus, the HMAC key
+must be randomly generated every time the device reboots, for added protection against replay attacks.</p>
+
+<p>The protocol for sharing this HMAC key with all components is a
+platform-dependent implementation feature. The key must <strong>never</strong>
+be made available outside the TEE. Thus, if a TEE OS lacks an
+internal inter-process communication (IPC) mechanism,
+and the TEE needs to transfer the data through the untrusted OS, the transfer
+must be done via a secure key exchange protocol.</p>
+
+<p>The Trusty operating system, which runs next to Android, is an example of a
+TEE, but other TEEs can be used instead. Trusty uses an internal IPC system to
+communicate directly between Keymaster and Fingerprint or Gatekeeper. The HMAC
+key is kept solely in Keymaster. Fingerprint and Gatekeeper request the key
+from Keymaster for each use, and do not persist or cache the value.</p>
+
+<p>Note that no communication happens between applets in the TEE because some TEEs
+are lacking in IPC infrastructure. This also
+permits the keystore service to quickly deny requests that are bound to fail as it has
+knowledge of the authentication table in the system, saving a potentially
+costly IPC into the TEE.</p>
diff --git a/src/devices/tech/security/images/authentication-flow.png b/src/devices/tech/security/images/authentication-flow.png
new file mode 100644
index 0000000..1c136e4
--- /dev/null
+++ b/src/devices/tech/security/images/authentication-flow.png
Binary files differ
