Docs: Adding sensors HAL content to source.android
Bug: 10134622
Change-Id: I742b5db03822fdba8e55d2dbb4796f508cfb1c57
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 9240852..963a6a1 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -119,6 +119,30 @@
</ul>
</li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/sensors/index.html">
+ <span class="en">Sensors</span>
+ </a>
+ </div>
+ <ul>
+ <li>
+ <a href="<?cs var:toroot ?>devices/sensors/base_triggers.html">
+ <span class="en">Base sensors</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>devices/sensors/composite_sensors.html">
+ <span class="en">Composite sensors</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>devices/sensors/batching.html">
+ <span class="en">Batching results</span>
+ </a>
+ </li>
+ </ul>
+ </li>
</ul>
</li>
<!-- End Porting Android -->
diff --git a/src/devices/sensors/base_triggers.jd b/src/devices/sensors/base_triggers.jd
new file mode 100644
index 0000000..1d2bd78
--- /dev/null
+++ b/src/devices/sensors/base_triggers.jd
@@ -0,0 +1,143 @@
+page.title=Base sensors and trigger modes
+@jd:body
+
+<!--
+ Copyright 2013 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="triggers">Trigger modes</h2>
+<p>Sensors can report events in different ways called trigger modes; each sensor
+ type has one and only one trigger mode associated to it. Four trigger modes
+ exist:</p>
+<h3 id="continuous">Continuous</h3>
+<p>Events are reported at a constant rate defined by setDelay(). Example sensors
+ using the continuous trigger mode are accelerometers and gyroscopes.</p>
+<h3 id="on-change">On-change</h3>
+<p>Events are reported only if the sensor's value has changed. setDelay() is used
+ to set a lower limit to the reporting period, meaning the minimum time between
+ consecutive events. Activating the sensor also triggers an event. The HAL must
+ return an event immediately when an on-change sensor is activated. Example
+ sensors using the on-change trigger mode are the step counter and proximity
+ sensor types.</p>
+<h3 id="one-shot">One-shot</h3>
+<p>Upon detection of an event, the sensor deactivates itself and then sends a
+ single event. Order matters to avoid race conditions. No other event is sent
+ until the sensor is reactivated. setDelay() is ignored.
+<a
+href="{@docRoot}devices/sensors/composite_sensors.html#Significant">Significant
+motion</a> is an example of this kind of sensor.</p>
+<h3 id="special">Special</h3>
+<p>See the individual sensor type descriptions for details.</p>
+<h2 id="categories">Categories</h2>
+<p>Sensors fall into four primary categories:</p>
+<blockquote>
+ <p><em>Base</em> - records core measurements from which all other sensors are derived <br/>
+ <em>Activity</em> - detects user or device movement<br/>
+ <em>Attitude</em> - measures the orientation of the device<br/>
+ <em>Uncalibrated</em> - is identical to the corresponding base sensor except the
+ dynamic calibration is reported separately rather than applied to the results</p>
+</blockquote>
+<h2 id="base">Base sensors</h2>
+<p>These sensor types are listed first because they are the fundamental sensors
+ upon which all other sensor types are based.</p>
+<h3 id="Accelerometer">Accelerometer</h3>
+<p><em>Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+<p>All values are in SI units (m/s^2) and measure the acceleration of the device
+ minus the force of gravity.</p>
+<p>Acceleration sensors return sensor events for all three axes at a constant rate
+ defined by setDelay().</p>
+<ul>
+ <li>x: Acceleration on the x-axis</li>
+ <li>y: Acceleration on the y-axis</li>
+ <li>z: Acceleration on the z-axis</li>
+</ul>
+<p>Note the readings from the accelerometer include the acceleration due to gravity
+ (which is opposite the direction of the gravity vector).</p>
+<p>Here are examples:</p>
+<ul>
+ <li>The norm of (x, y, z) should be close to 0 when in free fall.</li>
+ <li>When the device lies flat on a table and is pushed on its left side toward the
+ right, the x acceleration value is positive.</li>
+ <li>When the device lies flat on a table, the acceleration value is +9.81, which
+ corresponds to the acceleration of the device (0 m/s^2) minus the force of
+ gravity (-9.81 m/s^2).</li>
+ <li>When the device lies flat on a table and is pushed toward the sky, the
+ acceleration value is greater than +9.81, which corresponds to the
+ acceleration of the device (+A m/s^2) minus the force of gravity (-9.81
+ m/s^2).</li>
+</ul>
+<h3 id="Ambient">Ambient temperature</h3>
+<p><em>Trigger-mode: On-change<br/>
+Wake-up sensor: No</em></p>
+<p>This sensor provides the ambient (room) temperature in degrees Celsius.</p>
+<h3 id="Geomagnetic">Geomagnetic field</h3>
+<p><em>Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+<p>All values are in micro-Tesla (uT) and measure the geomagnetic field in the X, Y
+ and Z axis.</p>
+<p>Returned values include calibration mechanisms so the vector is aligned with the
+ magnetic declination and heading of the earth's geomagnetic field.</p>
+<p>Magnetic field sensors return sensor events for all three axes at a constant
+ rate defined by setDelay().</p>
+<h3 id="Gyroscope">Gyroscope</h3>
+<p><em>Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+<p>All values are in radians/second and measure the rate of rotation around the X,
+ Y and Z axis. The coordinate system is the same as is used for the acceleration
+ sensor. Rotation is positive in the counter-clockwise direction (right-hand
+ rule).</p>
+<p>That is, an observer looking from some positive location on the x, y or z axis
+ at a device positioned on the origin would report positive rotation if the
+ device appeared to be rotating counter clockwise. Note that this is the standard
+ mathematical definition of positive rotation and does not agree with the
+ definition of roll given elsewhere.</p>
+<p>The range should at least be 17.45 rad/s (ie: ~1000 deg/s).</p>
+<p>Automatic gyro-drift compensation is required.</p>
+<h3 id="Light">Light</h3>
+<p><em>Trigger-mode: On-change<br/>
+Wake-up sensor: No</em></p>
+<p>The light sensor value is returned in SI lux units.</p>
+<h3 id="Proximity">Proximity</h3>
+<p><em>Trigger-mode: On-change<br/>
+Wake-up sensor: Yes</em></p>
+<p>Measures the distance from the sensor to the closest visible surface. As this is
+ a wake-up sensor, it should wake up the SoC when it is running and detects a
+ change in proximity. The distance value is measured in centimeters. Note that
+ some proximity sensors only support a binary "near" or "far" measurement. In
+ this case, the sensor should report its maxRange value in the "far" state and a
+ value less than maxRange in the "near" state.</p>
+<p>To ensure the applications have the time to receive the event before the
+ application processor goes back to sleep, the driver must hold a "timeout wake
+ lock" for 200 milliseconds for every wake-up sensor. That is, the application
+ processor should not be allowed to go back to sleep in the 200 milliseconds
+ following a wake-up interrupt.</p>
+<h3 id="Pressure">Pressure</h3>
+<p><em>Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+<p>The pressure sensor uses a barometer to return the atmospheric pressure in
+ hectopascal (hPa).</p>
+<h3 id="humidity">Relative humidity</h3>
+<p><em>Trigger-mode: On-change<br/>
+Wake-up sensor: No</em></p>
+<p>A relative humidity sensor measures relative ambient air humidity and returns a
+ value in percent.</p>
diff --git a/src/devices/sensors/batching.jd b/src/devices/sensors/batching.jd
new file mode 100644
index 0000000..972e002
--- /dev/null
+++ b/src/devices/sensors/batching.jd
@@ -0,0 +1,184 @@
+page.title=Batching sensor results
+@jd:body
+
+<!--
+ Copyright 2013 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="Why">Why batch?</h2>
+<p>Batching can enable significant power savings by preventing the application
+ processor from waking up to receive each notification. Instead, these
+ notifications can be grouped and processed together.</p>
+<p>Enabling batch mode for a given sensor sets the delay between events. A timeout
+ value of zero disables batch mode for the given sensor. The period_ns parameter is equivalent to calling setDelay() -- this function both enables or disables the batch mode AND sets the event's period in nanoseconds. See setDelay() for a detailed explanation of the period_ns parameter.</p>
+<p>In non-batch mode, all sensor events must be reported as soon as they are
+ detected. For example, an accelerometer activated at 50Hz will trigger
+ interrupts 50 times per second.<br/>
+ While in batch mode, sensor events do not need to be reported as soon as they
+ are detected. They can be temporarily stored and reported in batches, as long as
+ no event is delayed by more than "timeout" nanoseconds. That is, all events
+ since the previous batch are recorded and returned at once. This reduces the
+ amount of interrupts sent to the SoC and allows the SoC to switch to a lower
+ power mode (idle) while the sensor is capturing and batching data.</p>
+<p>setDelay() is not affected and it behaves as usual. <br/>
+ <br/>
+ Each event has a timestamp associated with it. The timestamp must be accurate
+ and correspond to the time in which the event physically happened.</p>
+<p>Batching does not modify the behavior of poll(): batches from different sensors
+ can be interleaved and split. As usual, all events from the same sensor are
+ time-ordered.</p>
+<h2 id="Suspend">Suspend mode</h2>
+<p>These are the power modes of the application processor: on, idle, and suspend.
+ The sensors behave differently in each of these modes. As you would imagine, on
+ mode is when the application processor is running. Idle mode is low-power use
+ waiting for activity before going into suspension. Suspend mode is when the
+ application processor is not running.</p>
+<p>When the SoC is awake (not in suspend mode), events must be reported in batches
+ at least every "timeout." No event shall be dropped or lost. If internal
+ hardware FIFOs fill up before the timeout, then events are reported at that
+ point to ensure no event is lost.</p>
+<h2 id="Normal">Normal behavior in suspend mode</h2>
+<p>By default, batch mode doesn't significantly change the interaction with suspend
+ mode. That is, sensors must continue to allow the SoC to go into suspend mode
+ and sensors must stay active to fill their internal FIFO. In this mode, when the
+ FIFO fills up, it shall wrap around and behave like a circular buffer,
+ overwriting older events.<br/>
+ <br/>
+ As soon as the SoC comes out of suspend mode, a batch is produced with as much
+as the recent history as possible, and batch operation resumes as usual.</p>
+<p>The behavior described above allows applications to record the recent history of
+ a set of sensor types while keeping the SoC in suspend. It also allows the
+ hardware to not have to rely on a wake-up interrupt line.</p>
+<h2 id="WAKE_UPON_FIFO_FULL">WAKE_UPON_FIFO_FULL behavior in suspend mode</h2>
+<p>There are cases, however, where an application cannot afford to lose any events,
+ even when the device goes into suspend mode.</p>
+<p>For a given rate, if a sensor has the capability to store at least 10 seconds
+ worth of events in its FIFO and is able to wake up the SoC, it can implement an
+ optional secondary mode: the WAKE_UPON_FIFO_FULL mode.</p>
+<p>The caller will set the SENSORS_BATCH_WAKE_UPON_FIFO_FULL flag to activate this
+ mode. If the sensor does not support this mode, batch() will fail when the flag
+ is set.</p>
+<p>When running with the WAKE_UPON_FIFO_FULL flag set, no events can be lost. When
+ the FIFO is getting full, the sensor must wake up the SoC from suspend and
+ return a batch before the FIFO fills-up.</p>
+<p>Depending on the device, it might take a few milliseconds for the SoC to
+ entirely come out of suspend and start flushing the FIFO. Enough head room must
+ be allocated in the FIFO to allow the device to entirely come out of suspend
+ without the FIFO overflowing (no events shall be lost).</p>
+<p>Implementing the WAKE_UPON_FIFO_FULL mode is optional. If the hardware cannot
+ support this mode, or if the physical FIFO is so small that the device would
+ never be allowed to go into suspend for at least 10 seconds, then this function <strong>must</strong> fail when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set, regardless
+ of the value of the timeout parameter.</p>
+<h2 id="Implementing">Implementing batching</h2>
+<p>Batch mode, if supported, should happen at the hardware level, typically using
+ hardware FIFOs. In particular, it SHALL NOT be implemented in the HAL, as this
+ would be counter productive. The goal here is to save significant amounts of
+ power. Batching should be implemented without the aid of the SoC, which should
+ be allowed to be in suspend mode during batching.</p>
+<p>In some implementations, events from several sensors can share the same physical
+ FIFO. In that case, all events in the FIFO can be sent and processed by the HAL
+ as soon as one batch must be reported.</p>
+<p>For example, if the following sensors are activated:</p>
+<ul>
+ <li>accelerometer batched with timeout = 20s</li>
+ <li>gyroscope batched with timeout = 5s</li>
+</ul>
+<p>Then the accelerometer batches can be reported at the same time the gyroscope
+ batches are reported (every 5 seconds).<br/>
+ <br/>
+ Batch mode can be enabled or disabled at any time, in particular while the
+ specified sensor is already enabled; and this shall not result in the loss of
+ events.</p>
+<h2 id="different-sensors">Batching different sensors</h2>
+<p>On platforms in which hardware FIFO size is limited, the system designers may
+ have to choose how much FIFO to reserve for each sensor. To help with this
+ choice, here is a list of applications made possible when batching is
+ implemented on the different sensors.</p>
+<p><strong>High value: Low power pedestrian dead reckoning</strong><br/>
+ Target batching time: 20 seconds to 1 minute<br/>
+ Sensors to batch:<br/>
+ - Step detector<br/>
+ - Rotation vector or game rotation vector at 5Hz<br/>
+ Gives us step and heading while letting the SoC go to Suspend.<br/>
+ <br/>
+ <strong>High value: Medium power activity/gesture recognition</strong><br/>
+ Target batching time: 3 seconds<br/>
+ Sensors to batch: accelerometer between 20Hz and 50Hz<br/>
+ Allows recognizing arbitrary activities and gestures without having<br/>
+ to keep the SoC fully awake while the data is collected.<br/>
+ <br/>
+ <strong>Medium-high value: Interrupt load reduction</strong><br/>
+ Target batching time: < 1 second<br/>
+ Sensors to batch: any high frequency sensor.<br/>
+ If the gyroscope is set at 240Hz, even batching just 10 gyro events can<br/>
+ reduce the number of interrupts from 240/second to 24/second.<br/>
+ <br/>
+ <strong>Medium value: Continuous low frequency data collection</strong><br/>
+ Target batching time: > 1 minute<br/>
+ Sensors to batch: barometer, humidity sensor, other low frequency<br/>
+ sensors.<br/>
+ Allows creating monitoring applications at low power.<br/>
+ <br/>
+ <strong>Medium value: Continuous full-sensors collection</strong><br/>
+ Target batching time: > 1 minute<br/>
+ Sensors to batch: all, at high frequencies<br/>
+ Allows full collection of sensor data while leaving the SoC in<br/>
+ suspend mode. Only to consider if fifo space is not an issue.<br/>
+ <br/>
+ In each of the cases above, if WAKE_UPON_FIFO_FULL is implemented, the<br/>
+ applications might decide to let the SoC go to suspend, allowing for even<br/>
+ more power savings.</p>
+<h2 id="Dry-run">Dry run</h2>
+<p>If the flag SENSORS_BATCH_DRY_RUN is set, this function returns without
+ modifying the batch mode or the event period and has no side effects, but
+ returns errors as usual (as it would if this flag was not set). This flag is
+ used to check if batch mode is available for a given configuration, in
+ particular for a given sensor at a given rate.</p>
+<h2 id="Return-values">Return values</h2>
+<p>Because sensors must be independent, the return value must not depend on the
+ state of the system (whether another sensor is on or not), nor on whether the
+ flag SENSORS_BATCH_DRY_RUN is set (in other words, if a batch call with
+ SENSORS_BATCH_DRY_RUN is successful, the same call without SENSORS_BATCH_DRY_RUN
+ must succeed as well).</p>
+<p>If successful, 0 is returned.</p>
+<p>If the specified sensor doesn't support batch mode, -EINVAL is returned.<br/>
+ If the specified sensor's trigger-mode is one-shot, -EINVAL is returned.</p>
+<p>If WAKE UPON FIFO_FULL is specified and the specified sensor's internal FIFO is
+ too small to store at least 10 seconds worth of data at the given rate, -EINVAL
+ is returned. Note that as stated above, this has to be determined at compile
+ time and not based on the state of the system.</p>
+<p>If some other constraints above cannot be satisfied, -EINVAL is returned.<br/>
+ <br/>
+ Note: the timeout parameter when > 0 has no impact on whether this function
+ succeeds or fails.<br/>
+ <br/>
+ If timeout is set to 0, this function must succeed.</p>
+<h2 id="Supporting-docs">Supporting documentation</h2>
+<p><a href="http://developer.android.com/guide/topics/sensors/index.html">Developer - Location and Sensors
+ APIs</a></p>
+<p><a href="http://developer.android.com/guide/topics/sensors/sensors_overview.html">Developer - Sensors
+ Overview</a></p>
+<p><a href="http://developer.android.com/reference/android/hardware/Sensor.html">Sensors SDK API
+ reference</a></p>
+<p><a href="{@docRoot}devices/reference/sensors_8h_source.html">Android
+ Hardware Abstraction Layer - sensors.h</a></p>
+<p><a href="http://developer.android.com/reference/android/hardware/SensorManager.html">SensorManager</a></p>
diff --git a/src/devices/sensors/composite_sensors.jd b/src/devices/sensors/composite_sensors.jd
new file mode 100644
index 0000000..7ede9ee
--- /dev/null
+++ b/src/devices/sensors/composite_sensors.jd
@@ -0,0 +1,527 @@
+page.title=Composite sensors
+@jd:body
+
+<!--
+ Copyright 2013 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="summary">Composite sensor type summary</h2>
+
+<p>The following table lists the composite sensor types and their categories,
+underlying base sensors, and trigger modes. Certain base sensors are required of
+each sensor for accuracy. Using other tools to approximate results should be
+avoided as they will invariably provide a poor user experience.</p>
+<table>
+ <tr>
+<th>Sensor type</th>
+<th>Category</th>
+<th>Underlying base sensor</th>
+<th>Trigger mode</th>
+</tr>
+<tr>
+<td>Game rotation vector</td>
+<td>Attitude</td>
+<td>Accelerometer, Gyroscope
+MUST NOT USE Magnetometer</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Geomagnetic rotation vector (Magnetometer) <img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /></td>
+<td>Attitude</td>
+<td>Accelerometer, Magnetometer
+NOT Gyroscope</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Gravity</td>
+<td>Attitude</td>
+<td>Accelerometer, Gyroscope</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Gyroscope uncalibrated</td>
+<td>Uncalibrated</td>
+<td>Gyroscope</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Linear acceleration</td>
+<td>Activity</td>
+<td>Accelerometer, Gyroscope
+AND Magnetometer</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Magnetic field uncalibrated</td>
+<td>Uncalibrated</td>
+<td>Magnetometer</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Orientation</td>
+<td>Attitude</td>
+<td>Accelerometer, Magnetometer
+PREFERRED Gyroscope</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Rotation vector</td>
+<td>Attitude</td>
+<td>Accelerometer, Gyroscope
+AND Magnetometer</td>
+<td>Continuous</td>
+</tr>
+<tr>
+<td>Significant motion
+ <img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /></td>
+<td>Activity</td>
+<td>Accelerometer (or another as long as very low power)</td>
+<td>One-shot</td>
+</tr>
+<tr>
+<td>Step counter
+ <img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /></td>
+<td>Activity</td>
+<td>Accelerometer</td>
+<td>On-
+change</td>
+</tr>
+<tr>
+<td>Step detector
+ <img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /></td>
+<td>Activity</td>
+<td>Accelerometer</td>
+<td>Special</td>
+</tr>
+</table>
+
+<p><img src="images/battery_icon.png" alt="low power icon"/> =
+Low power sensor</p>
+
+<h2 id="Activity">Activity sensors</h2>
+
+<h3 id="acceleration">Linear acceleration</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer, Gyroscope AND Magnetometer<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p>Indicates the linear acceleration of the device in device coordinates, not
+including gravity. The output is conceptually:<br/>
+output of TYPE_ACCELERATION minus output of TYPE_GRAVITY.</p>
+
+<p>Readings on all axes should be close to 0 when the device is immobile. Units are
+m/s^2. The coordinate system is the same as is used for the acceleration sensor.</p>
+
+<h3 id="Significant">Significant motion</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer (or another as long as low power)<br/>
+Trigger-mode: One-shot<br/>
+Wake-up sensor: Yes</em></p>
+
+<p>Significant motion allows a device to stay in suspend and idle modes longer and
+save power. It does this by relying upon last known location until the device
+experiences "significant motion." Such a movement would trigger on mode and a
+call to retrieve new location.</p>
+
+<p>Here is an example on how the platform can use significant motion to save
+power. When users are moving, their locations are updated frequently. After some period
+of inactivity, significant motion presumes the device is static and stops
+seeking location updates. It instead registers the last known location as valid.
+The device is then allowed to go into idle and then suspend mode.</p>
+
+<p>This sensor exists to save power by keeping the SoC in suspend mode when the
+device is at rest. A sensor of this type triggers an event each time significant
+motion is detected and automatically disables itself. The only allowed value to
+return is 1.0.</p>
+
+<p>A significant motion is a motion that might lead to a change in the user
+location. Examples of such significant motions are:</p>
+
+<ul>
+<li>walking or biking</li>
+<li>sitting in a moving car, coach or train</li>
+</ul>
+
+<p>Examples of situations that should not trigger significant motion:</p>
+
+<ul>
+<li>phone in pocket and person is not moving</li>
+<li>phone is on a table and the table shakes a bit due to nearby traffic or
+washing machine</li>
+</ul>
+
+<p>This sensor makes a tradeoff for power consumption that may result in a small
+amount of false negatives. This is done for a few reasons:</p>
+
+<ol>
+<li>The goal of this sensor is to save power.</li>
+<li>Triggering an event when the user is not moving (false positive) is costly in
+terms of power, so it should be avoided.</li>
+<li>Not triggering an event when the user is moving (false negative) is
+acceptable as long as it is not done repeatedly. If the user has been walking
+for 10 seconds, not triggering an event within those 10 seconds is not
+acceptable.</li>
+</ol>
+
+<p>To ensure the applications have the time to receive the significant motion event
+before the application processor goes back to sleep, the driver must hold a
+"timeout wake lock" for 200 milliseconds for every wake-up sensor. That is, the
+application processor should not be allowed to go back to sleep in the 200
+milliseconds following a wake-up interrupt.</p>
+
+<p>IMPORTANT NOTE: This sensor is very different from the other types in that it
+must work when the screen is off without the need for holding a partial wake
+lock (other than the timeout wake lock) and MUST allow the SoC to go into
+suspend. When significant motion is detected, the sensor must awaken the SoC and
+the event be reported.</p>
+
+<p>If a particular device cannot support this mode of operation, then this sensor
+type <strong>must not</strong> be reported by the HAL. ie: it is not acceptable to "emulate"
+this sensor in the HAL.</p>
+
+<p>When the sensor is not activated, it must also be deactivated in the hardware;
+it must not wake up the SoC anymore, even in case of significant motion.</p>
+
+<p>setDelay() has no effect and is ignored.</p>
+
+<p>Once a "significant motion" event is returned, a sensor of this type must
+disable itself automatically, as if activate(..., 0) had been called.</p>
+
+<h3 id="detector">Step detector</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer<br/>
+Trigger-mode: Special<br/>
+Wake-up sensor: No</em></p>
+
+<p>A sensor of this type triggers an event each time a step is taken by the user.
+The only allowed value to return is 1.0 and an event is generated for each step.
+Like with any other event, the timestamp indicates when the event (here the
+step) occurred. This corresponds to when the foot hit the ground, generating a
+high variation in acceleration.</p>
+
+<p>Compared to the step counter, the step detector should have a lower latency
+(less than 2 seconds). Both the step detector and the step counter detect when
+the user is walking, running and walking up the stairs. They should not trigger
+when the user is biking, driving or in other vehicles.</p>
+
+<p>While this sensor operates, it shall not disrupt any other sensors, in
+particular, the accelerometer; it might very well be in use.</p>
+
+<p>This sensor must be low power. That is, if the step detection cannot be done in
+hardware, this sensor should not be defined. Also, when the step detector is
+activated and the accelerometer is not, only steps should trigger interrupts
+(not accelerometer data).</p>
+
+<p>setDelay() has no impact on this sensor type.</p>
+
+<h3 id="counter">Step counter</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer<br/>
+Trigger-mode: On-change<br/>
+Wake-up sensor: No</em></p>
+
+<p>A sensor of this type returns the number of steps taken by the user since the
+last reboot while activated. The value is returned as a uint64_t and is reset to
+zero only on a system reboot.</p>
+
+<p>The timestamp of the event is set to the time when the last step for that event
+was taken.<br/>
+See the <a href="#detector">Step detector</a>
+sensor type for the signification of the time of a step.</p>
+
+<p>Compared to the step detector, the step counter can have a higher latency (less
+than 10 seconds). Thanks to this latency, this sensor has a high accuracy; the
+step count after a full day of measures should be within 10% of the real step
+count. Both the step detector and the step counter detect when the user is
+walking, running and walking up the stairs. They should not trigger when the
+user is biking, driving or in other vehicles.</p>
+
+<p><strong>Important note</strong>: This sensor is different from other types in that it must work
+when the screen is off without the need of holding a partial wake-lock and MUST
+allow the SoC to go into suspend.</p>
+
+<p>While in suspend mode this sensor must stay active. No events are reported
+during that time but steps continue to be accounted for; an event will be
+reported as soon as the SoC resumes if the timeout has expired.</p>
+
+<p>In other words, when the screen is off and the device is allowed to go into
+suspend mode, it should not be woken up, regardless of the setDelay() value. But
+the steps shall continue to be counted.</p>
+
+<p>The driver must however ensure the internal step count never overflows. The
+minimum size of the hardware's internal counter shall be 16 bits. (This
+restriction is here to avoid too frequent wake-ups when the delay is very
+large.) It is allowed in this situation to wake the SoC up so the driver can do
+the counter maintenance.</p>
+
+<p>While this sensor operates, it shall not disrupt any other sensors, in
+particular, the accelerometer; it might very well be in use.</p>
+
+<p>If a particular device cannot support these modes of operation, then this sensor
+type <strong>must not</strong> be reported by the HAL. ie: it is not acceptable to "emulate"
+this sensor in the HAL.</p>
+
+<p>This sensor must be low power. That is, if the step detection cannot be done in
+hardware, this sensor should not be defined. Also, when the step counter is
+activated and the accelerometer is not, only steps should trigger interrupts
+(not accelerometer data).</p>
+
+<h2 id="Attitude">Attitude sensors</h2>
+
+<h3 id="Rotation-vector">Rotation vector</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer, Gyroscope AND Magnetometer<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p>The rotation vector symbolizes the orientation of the device relative to the
+East-North-Up coordinates frame. It is usually obtained by integration of
+accelerometer, gyroscope and magnetometer readings.</p>
+
+<p>The East-North-Up coordinate system is defined as a direct orthonormal basis
+where:</p>
+
+<ul>
+<li>X points east and is tangential to the ground.</li>
+<li>Y points north and is tangential to the ground.</li>
+<li>Z points towards the sky and is perpendicular to the ground.</li>
+</ul>
+
+<p>The orientation of the phone is represented by the rotation necessary to align
+the East-North-Up coordinates with the phone's coordinates. That is, applying
+the rotation to the world frame (X,Y,Z) would align them with the phone
+coordinates (x,y,z).</p>
+
+<p>The rotation can be seen as rotating the phone by an angle theta around an axis
+rot_axis to go from the reference (East-North-Up aligned) device orientation to
+the current device orientation.</p>
+
+<p>The rotation is encoded as the four (reordered) components of a unit quaternion:</p>
+
+<ul>
+<li>sensors_event_t.data[0] = rot_axis.x*sin(theta/2)</li>
+<li>sensors_event_t.data[1] = rot_axis.y*sin(theta/2)</li>
+<li>sensors_event_t.data[2] = rot_axis.z*sin(theta/2)</li>
+<li>sensors_event_t.data[3] = cos(theta/2)</li>
+</ul>
+
+<p>Where:</p>
+
+<ul>
+<li>rot_axis.x,y,z are the North-East-Up coordinates of a unit length vector
+representing the rotation axis</li>
+<li>theta is the rotation angle</li>
+</ul>
+
+<p>The quaternion must be of norm 1. (It is a unit quaternion.) Failure to ensure
+this will cause erratic client behaviour.</p>
+
+<p>In addition, this sensor reports an estimated heading accuracy:<br/>
+sensors_event_t.data[4] = estimated_accuracy (in radians)</p>
+
+<p>The heading error must be less than estimated_accuracy 95% of the time. This
+sensor must use a gyroscope and an accelerometer as main orientation change
+input.</p>
+
+<p>This sensor should also include magnetometer input to make up for gyro drift,
+but it cannot be implemented using only a magnetometer.</p>
+
+<h3 id="Game-rotation">Game rotation vector</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer, Gyroscope NOT Magnetometer<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p>Similar to the <a href="#Rotation-vector">rotation vector</a> sensor but not using
+the geomagnetic field. Therefore the Y axis doesn't point north but instead to
+some other reference. That reference is allowed to drift by the same order of
+magnitude as the gyroscope drifts around the Z axis.</p>
+
+<p>This sensor does not report an estimated heading accuracy:<br/>
+sensors_event_t.data[4] is reserved and should be set to 0</p>
+
+<p>In an ideal case, a phone rotated and returned to the same real-world
+orientation should report the same game rotation vector (without using the
+earth's geomagnetic field).</p>
+
+<p>This sensor must be based on a gyroscope. It cannot be implemented using a
+magnetometer.</p>
+
+<h3 id="Gravity">Gravity</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer, Gyroscope NOT Magnetometer<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p>The gravity output of this sensor indicates the direction and magnitude of
+gravity in the device's coordinates. Units are m/s^2. On Earth, the magnitude is
+9.8 m/s^2. The coordinate system is the same as is used for the acceleration
+sensor. When the device is at rest, the output of the gravity sensor should be
+identical to that of the accelerometer.</p>
+
+<h3 id="Magnetometer">Geomagnetic rotation vector (Magnetometer)</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer, Magnetometer NOT Gyroscope<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p>This sensor is similar to the <a href="#Rotation-vector">rotation vector</a> sensor
+but using a magnetometer instead of a gyroscope.</p>
+
+<p>This sensor must be based on a magnetometer. It cannot be implemented using a
+gyroscope, and gyroscope input cannot be used by this sensor.</p>
+
+<p>Just like the rotation vector sensor, this sensor reports an estimated heading
+accuracy:<br/>
+sensors_event_t.data[4] = estimated_accuracy (in radians)</p>
+
+<p>The heading error must be less than estimated_accuracy 95% of the time.</p>
+
+<p>See the <a href="#Rotation-vector">rotation vector</a> sensor description for more
+details.</p>
+
+<h3 id="Orientation">Orientation</h3>
+
+<p><em>Underlying base sensor(s): Accelerometer, Magnetometer PREFERRED Gyroscope<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p><strong>Note</strong>: This is an older sensor type that has been
+deprecated in the Android SDK although not yet in the HAL. It has been replaced
+by the rotation vector sensor, which is more clearly defined, requires a
+gyroscope, and therefore provides more accurate results. Use the rotation vector
+sensor over the orientation sensor whenever possible.</p>
+
+<p>The orientation sensor tracks the attitude of the device. All values are angles
+in degrees. Orientation sensors return sensor events for all three axes at a
+constant rate defined by setDelay().</p>
+
+<ul>
+<li>azimuth: angle between the magnetic north direction and the Y axis, around <br />
+the Z axis (0<=azimuth<360). 0=North, 90=East, 180=South, 270=West</li>
+<li>pitch: Rotation around X axis (-180<=pitch<=180), with positive values when
+the z-axis moves toward the y-axis.</li>
+<li>roll: Rotation around Y axis (-90<=roll<=90), with positive values when the
+x-axis moves towards the z-axis.</li>
+</ul>
+
+<p>Please note, for historical reasons the roll angle is positive in the clockwise
+direction. (Mathematically speaking, it should be positive in the
+counter-clockwise direction):</p>
+
+<div class="figure" style="width:264px">
+ <img src="images/axis_positive_roll.png" alt="Depiction of orientation relative to a device" height="253" />
+ <p class="img-caption">
+ <strong>Figure 2.</strong> Orientation relative to a device.
+ </p>
+</div>
+
+<p>This definition is different from yaw, pitch and roll used in aviation where the
+X axis is along the long side of the plane (tail to nose).</p>
+
+<h2 id="Uncalibrated">Uncalibrated sensors</h2>
+
+<p>Uncalibrated sensors provide more raw results and may include some bias but also
+contain fewer "jumps" from corrections applied through calibration. Some
+applications may prefer these uncalibrated results as smoother and more
+reliable. For instance, if an application is attempting to conduct its own
+sensor fusion, introducing calibrations can actually distort results.</p>
+
+<h3 id="Gyroscope-uncalibrated">Gyroscope uncalibrated</h3>
+
+<p><em>Underlying base sensor(s): Gyroscope<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p>The uncalibrated gyroscope is useful for post-processing and melding orientation
+data. All values are in radians/second and measure the rate of rotation around
+the X, Y and Z axis. An estimation of the drift on each axis is reported as
+well.</p>
+
+<p>No gyro-drift compensation shall be performed. Factory calibration and
+temperature compensation should still be applied to the rate of rotation
+(angular speeds).</p>
+
+<p>The coordinate system is the same as is used for the acceleration sensor.
+Rotation is positive in the counter-clockwise direction (right-hand rule). That
+is, an observer looking from some positive location on the x, y or z axis at a
+device positioned on the origin would report positive rotation if the device
+appeared to be rotating counter clockwise. Note that this is the standard
+mathematical definition of positive rotation and does not agree with the
+definition of roll given elsewhere.</p>
+
+<p>The range should at least be 17.45 rad/s (ie: ~1000 deg/s).</p>
+
+<p>Content of an uncalibrated_gyro event (units are rad/sec):</p>
+
+<ul>
+<li>x_uncalib : angular speed (w/o drift compensation) around the X axis</li>
+<li>y_uncalib : angular speed (w/o drift compensation) around the Y axis</li>
+<li>z_uncalib : angular speed (w/o drift compensation) around the Z axis</li>
+<li>x_bias : estimated drift around X axis in rad/s</li>
+<li>y_bias : estimated drift around Y axis in rad/s</li>
+<li>z_bias : estimated drift around Z axis in rad/s</li>
+</ul>
+
+<p>If the implementation is not able to estimate the drift, then this sensor <strong>must
+not</strong> be reported by this HAL. Instead, the regular
+<a href="{@docRoot}devices/sensors/base_triggers.html#Gyroscope">Gyroscope</a> sensor is used without drift compensation.</p>
+
+<p>If this sensor is present, then the corresponding Gyroscope sensor must be
+present and both must return the same sensor_t::name and sensor_t::vendor.</p>
+
+<h3 id="Magnetic-field-uncalibrated">Magnetic field uncalibrated</h3>
+
+<p><em>Underlying base sensor(s): Magnetometer<br/>
+Trigger-mode: Continuous<br/>
+Wake-up sensor: No</em></p>
+
+<p>Similar to <a href="{@docRoot}devices/sensors/base_triggers.html#Geomagnetic">Geomagnetic field</a> sensor, but the hard
+iron calibration is reported separately instead of being included in the
+measurement. The uncalibrated magnetometer allows the system to handle bad hard
+iron estimation.</p>
+
+<p>Factory calibration and temperature compensation should still be applied to the
+"uncalibrated" measurement. Separating away the hard iron calibration estimation
+allows the system to better recover from bad hard iron estimation.</p>
+
+<p>All values are in micro-Tesla (uT) and measure the ambient magnetic field in the
+X, Y and Z axis. Assumptions that the magnetic field is due to the Earth's poles
+should be avoided.</p>
+
+<p>The uncalibrated_magnetic event contains three fields for uncalibrated measurement: x_uncalib, y_uncalib, z_uncalib. Each is a component of the
+measured magnetic field, with soft iron and temperature compensation applied,
+but not hard iron calibration. These values should be continuous (no
+re-calibration should cause a jump).</p>
+
+<p>The uncalibrated_magnetic event contains three fields for hard iron bias estimates: x_bias, y_bias, z_bias. Each field is a component of the estimated
+hard iron calibration. They represent the offsets to apply to the calibrated
+readings to obtain uncalibrated readings (x_uncalib ~= x_calibrated + x_bias).
+These values are expected to jump as soon as the estimate of the hard iron
+changes, and they should be stable the rest of the time.</p>
+
+<p>If this sensor is present, then the corresponding Geomagnetic field sensor must
+be present and both must return the same sensor_t::name and sensor_t::vendor.</p>
+
+<p>See the <a href="{@docRoot}devices/sensors/base_triggers.html#Geomagnetic">geomagnetic field</a> sensor description for more
+information.<br/></p>
diff --git a/src/devices/sensors/images/axis_positive_roll.png b/src/devices/sensors/images/axis_positive_roll.png
new file mode 100644
index 0000000..c2bf6ba
--- /dev/null
+++ b/src/devices/sensors/images/axis_positive_roll.png
Binary files differ
diff --git a/src/devices/sensors/images/battery_icon.png b/src/devices/sensors/images/battery_icon.png
new file mode 100644
index 0000000..4cd15b8
--- /dev/null
+++ b/src/devices/sensors/images/battery_icon.png
Binary files differ
diff --git a/src/devices/sensors/index.jd b/src/devices/sensors/index.jd
new file mode 100644
index 0000000..32f3ee1
--- /dev/null
+++ b/src/devices/sensors/index.jd
@@ -0,0 +1,262 @@
+page.title=Sensors HAL overview
+@jd:body
+
+<!--
+ Copyright 2013 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="intro">Introduction</h2>
+<p><a href="http://developer.android.com/guide/topics/sensors/sensors_overview.html">Android
+ sensors</a> give applications access to a mobile device's underlying base sensor(s):
+ accelerometer, gyroscope, and magnetometer. Manufacturers develop the drivers
+ that define additional composite sensor types from those base sensors. For
+ instance, Android offers both calibrated and uncalibrated gyroscopes, a
+ geomagnetic rotation vector and a game rotation vector. This variety gives
+ developers some flexibility in tuning applications for battery life optimization
+ and accuracy.</p>
+<p>The <a href="{@docRoot}devices/reference/sensors_8h_source.html">Sensors
+Hardware Abstraction Layer (HAL) API</a> is the interface between the hardware drivers
+and the Android framework; the <a href="http://developer.android.com/reference/android/hardware/Sensor.html">Sensors Software Development Kit (SDK)
+ API</a> is the interface between the Android framework and the Java applications. Please note,
+ the Sensors HAL API described in this documentation is not identical to the
+ Sensors SDK API described on <a href="http://developer.android.com/reference/android/hardware/Sensor.html">developer.android.com</a>.
+ For example, some sensors that are deprecated in the SDK may still exist in the
+ HAL, and vice versa.</p>
+<p>Similarly, audio recorders, Global Positioning System (GPS) devices, and
+ accessory (pluggable) sensors are not supported by the Android Sensors HAL API
+ described here. This API covers sensors that are physically part of the device
+ only. Please see the <a href="{@docRoot}devices/audio.html">Audio</a>, <a href="{@docRoot}devices/reference/gps_8h.html">Location </a><a href="{@docRoot}devices/reference/gps_8h.html">Strategies</a>,
+ and the <a href="{@docRoot}accessories/index.html">Accessories</a> section
+ for information on those devices.</p>
+<p>Application framework<br/>
+ At the application framework level is the app code, which utilizes the <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> APIs to interact with the sensors hardware. Internally, this code calls
+ corresponding JNI glue classes to access the native code that interacts with the
+ sensors hardware.</p>
+<p>JNI<br/>
+ The JNI code associated with <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> is located in the frameworks/base/core/jni/ directory. This code calls the lower
+ level native code to obtain access to the sensor hardware.</p>
+<p>Native framework<br/>
+ The native framework is defined in frameworks/native/ and provides a native
+ equivalent to the <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> package. The native framework calls the Binder IPC proxies to obtain access to
+ sensor-specific services.</p>
+<p>Binder IPC<br/>
+ The Binder IPC proxies facilitate communication over process boundaries.</p>
+<p>HAL<br/>
+ The Hardware Abstraction Layer (HAL) defines the standard interface that sensor
+ services call into and that you must implement to have your sensor hardware
+ function correctly. The sensor HAL interfaces are located in
+ hardware/libhardware/include/hardware.</p>
+<p>Kernel Driver<br/>
+ The sensors driver interacts with the hardware and your implementation of the
+ HAL. The HAL is driver-agnostic.</p>
+<h3 id="axis-def">Sensor axis definition</h3>
+<p>The sensor event values are expressed in a specific frame that is static
+ relative to the phone. This API is relative only to the NATURAL orientation of
+ the screen. In other words:</p>
+<ul>
+ <li>the axes are not swapped when the device's screen orientation changes.</li>
+ <li>higher level services <em>may</em> perform this transformation.</li>
+</ul>
+<div class="figure" style="width:269px"> <img src="http://developer.android.com/images/axis_device.png" alt="Coordinate system relative to device for Sensor
+ API" height="225" />
+ <p class="img-caption"> <strong>Figure 1.</strong> Coordinate system (relative to a device) that's used by the Sensor
+ API. </p>
+</div>
+<h3 id="accuracy">Accuracy</h3>
+<p>The sensors included by the manufacturer must be accurate and precise to meet
+the expectations of application developers. The sensors included in Android devices are
+ tested for sensor interaction and accuracy as part of the <a href="{@docRoot}compatibility/index.html">Android Compatibility
+ program</a> starting in the
+ Android 4.4 release. Testing will continue to be improved in future releases.
+ See the <em>Sensors</em> section of the Android Compatibility Definition Document (CDD)
+ for the exact requirements.</p>
+<h3 id="power">Power consumption</h3>
+<p>Some defined sensor are higher power than others. Others are lower power by
+ design and should be implemented as such with their processing done in the
+ hardware. This means they should not require the application processor to be
+ running. Here are the low-power sensors:</p>
+<ul>
+ <li><a href="{@docRoot}devices/sensors/composite_sensors.html#Magnetometer">Geomagnetic rotation vector</a></li>
+ <li><a href="{@docRoot}devices/sensors/composite_sensors.html#Significant">Significant motion</a></li>
+ <li><a href="{@docRoot}devices/sensors/composite_sensors.html#counter">Step counter</a></li>
+ <li><a href="{@docRoot}devices/sensors/composite_sensors.html#detector">Step detector</a></li>
+</ul>
+<p>They are accompanied by a low-power <img src="images/battery_icon.png"
+alt="low-power sensors"/>
+ icon in the <a href="{@docRoot}devices/sensors/composite_sensors.html#summary">Sensor summary</a> table. </p>
+<p>These sensor types cannot be implemented at high power as their primary benefit
+ is low battery use. It is better to not implement a low-power sensor at all
+ rather than implement it as high power.</p>
+<p>Composite low-power sensor types, such as the step detector, must have their
+ processing conducted in the hardware; power use is much lower than if done in
+ the software. Power use is low on small microprocessors and even lower still on
+ application-specific integrated circuits (ASICs). A hardware implementation of
+ composite sensor types can also make use of more raw sensor data and a better
+ synchronization between sensors.</p>
+<h3 id="release">HAL release cycle</h3>
+<p>Functionality is tied to versions of the API. Android maintains two versions of
+ the Sensors HAL API per release. For instance, if version 1 was the latest and
+ version 1.1 is released, the version prior to 1 will no longer be supported upon
+ that release. Only the two latest versions of the Sensors HAL API are supported.</p>
+<h2 id="interaction">Interaction</h2>
+<h3 id="concurrent">Concurrent running</h3>
+<p>Android sensors must work independently of one another. Activating one sensor
+ shall not deactivate another sensor. Activating one shall not reduce the rate of
+ another. This is a key element of compatibility testing.</p>
+<h3 id="suspend">Interaction with suspend mode</h3>
+<p>Unless otherwise noted, an enabled sensor shall not prevent the system on a chip
+ (SoC) from going into suspend mode. See the <a
+href="{@docRoot}devices/sensors/batching.html#Suspend">Suspend
+ mode</a> section for a full description of the expected
+ behavior in this mode. It is the responsibility of applications to keep a
+ partial <a href="http://developer.android.com/reference/android/os/PowerManager.WakeLock.html">wake
+ lock</a> should they wish to receive sensor events while the screen is off. While in
+ suspend mode, and unless otherwise noted (<a
+href="{@docRoot}devices/sensors/batching.html">batch</a> mode
+ and sensor particularities), enabled sensors' events are lost.</p>
+<p>Note that conceptually, the sensor itself is not deactivated while in suspend
+ mode. Instead, the data it returns is missing. The oldest data is dropped to
+ accommodate the latest data. As soon as the SoC gets out of suspend mode,
+ operations resume as normal.</p>
+<p>Most applications should either hold a wake lock to ensure the system doesn't go
+ to suspend, or unregister from the sensors when they do not need them, unless
+ batch mode is active. When batching, sensors must continue to fill their
+ internal FIFO. (See the documentation of <a
+href="{@docRoot}devices/sensors/batching.html">batch</a> mode
+ to learn how suspend interacts with batch mode.)</p>
+<p>In batch mode, and only when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set
+ and supported, the specified sensor must be able to wake-up the SoC and be able
+ to buffer at least 10 seconds worth of the requested sensor events.</p>
+<p>There are notable exceptions to this behavior, which are sensor-dependent. (See
+ the sensor types descriptions below.)</p>
+<p>The individual sensor references specify the wake-up behavior of each sensor:</p>
+<ul>
+ <li>wake-up: yes - this sensor must wake-up the SoC to deliver events</li>
+ <li>wake-up: no - this sensor shall not wake-up the SoC; events are dropped</li>
+</ul>
+<h3 id="fusion">Sensor fusion and virtual sensors</h3>
+<p>Many composite sensor types are or can be implemented as virtual sensors from
+ underlying base sensors on the device. Examples of composite sensors types
+ include the rotation vector sensor, orientation sensor, step detector and step
+ counter.</p>
+<p>From the point of view of this API, these virtual sensors <strong>must</strong> appear as
+ real, individual sensors. It is the responsibility of the driver and HAL to make
+ sure this is the case.</p>
+<p>In particular, all sensors must be able to function concurrently. For example,
+ if defining both an accelerometer and a step counter, then both must be able to
+ work concurrently.</p>
+<h3 id="hal">HAL interface</h3>
+<p>These are the common sensor calls expected at the HAL level:</p>
+<ol>
+ <li><em>getSensorList()</em> - Gets the list of all sensors.</li>
+ <li><em>activate()</em> - Starts the specified sensor.</li>
+ <li><em>batch</em> - Sets parameters to group event data collection and optimize power use.</li>
+ <li><em>setDelay()</em> - Sets the event's period in
+ nanoseconds for a given sensor.</li>
+ <li><em>flush()</em> - Flush adds an event to the end of the
+ "batch mode" FIFO for the specified sensor and flushes the FIFO.</li>
+ <li><em>poll()</em> - Returns an array of sensor data. </li>
+</ol>
+<p>Please note, the implementation must be thread safe and allow these values to be
+ called from different threads.</p>
+<h4 id="getSensorList">getSensorList(sensor_type)</h4>
+<p>Provide the list of sensors implemented by the HAL for the given sensor type. </p>
+<p>Developers may then make multiple calls to get sensors of different types or use
+ Sensor.TYPE_ALL to get all the sensors. See getSensorList() defined on
+ developer.android.com for more details.</p>
+<h4 id="activate">activate(sensor, true/false)</h4>
+<pre>
+ int (*activate)(struct sensors_poll_device_t *dev,
+ int handle, int enabled);</pre>
+<p>Activates or deactivates the sensor with the specified handle. Handles must be
+ higher than SENSORS_HANDLE_BASE and must be unique. A handle identifies a given
+ sensor. The handle is used to activate and/or deactivate sensors. In this
+ version of the API, there can only be 256 handles.</p>
+<p>The handle is the handle of the sensor to change. The enabled argument is set to
+ 1 to enable or 0 to disable the sensor.</p>
+<p>Unless otherwise noted in the individual sensor type descriptions, an activated
+ sensor never prevents the SoC from going into suspend mode; that is, the HAL
+ shall not hold a partial wake lock on behalf of applications.<br/>
+ <br/>
+ One-shot sensors deactivate themselves automatically upon receiving an event,
+ and they must still accept to be deactivated through a call to activate(...,
+ ..., 0).<br/>
+ <br/>
+ If "enabled" is 1 and the sensor is already activated, this function is a no-op
+ and succeeds. If "enabled" is 0 and the sensor is already deactivated, this
+ function is a no-op and succeeds. This returns 0 on success and a negative errno
+ code otherwise.</p>
+<h4 id="batch">batch(sensor, batching parameters)</h4>
+<pre>
+ int (*batch)(struct sensors_poll_device_1* dev,
+ int handle, int flags, int64_t period_ns, int64_t timeout);
+</pre>
+<p>Sets parameters to group event data collection and reduce power use. Batching
+ can enable significant power savings by allowing the application processor to
+ sleep rather than awake for each notification. Instead, these notifications can
+ be grouped and processed together. See the <a
+href="{@docRoot}devices/sensors/batching.html">Batching</a> section for details.</p>
+<h4 id="setDelay">setDelay(sensor, delay)</h4>
+<pre>
+ int (*setDelay)(struct sensors_poll_device_t *dev,
+ int handle, int64_t period_ns);
+</pre>
+<p>Sets the event's period in nanoseconds for a given sensor. What the period_ns
+ parameter means depends on the specified sensor's trigger mode:</p>
+<ul>
+ <li>Continuous: setDelay() sets the sampling rate.</li>
+ <li>On-change: setDelay() limits the delivery rate of events.</li>
+ <li>One-shot: setDelay() is ignored. It has no effect.</li>
+ <li>Special: See specific sensor type descriptions.</li>
+</ul>
+<p>For continuous and on-change sensors, if the requested value is less than sensor_t::minDelay, then it's silently clamped to sensor_t::minDelay unless
+ sensor_t::minDelay is 0, in which case it is clamped to >= 1ms:<br/>
+ @return 0 if successful, < 0 on error</p>
+<h4 id="flush">flush()</h4>
+<pre>
+ int (*flush)(struct sensors_poll_device_1* dev, int handle);
+</pre>
+<p>Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t) to the
+ end of the "batch mode" FIFO for the specified sensor and flushes the FIFO;
+ those events are delivered as usual (i.e.: as if the batch timeout had expired)
+ and removed from the FIFO.<br/>
+ <br/>
+ The flush happens asynchronously (i.e.: this function must return immediately).
+ If the implementation uses a single FIFO for several sensors, that FIFO is
+ flushed and the META_DATA_FLUSH_COMPLETE event is added only for the specified
+ sensor.<br/>
+ <br/>
+ If the specified sensor wasn't in batch mode, flush succeeds and promptly sends
+ a META_DATA_FLUSH_COMPLETE event for that sensor.</p>
+<p>If the FIFO was empty at the time of the call, flush returns 0 (success) and
+ promptly sends a META_DATA_FLUSH_COMPLETE event for that sensor.<br/>
+ <br/>
+ If the specified sensor wasn't enabled, flush returns -EINVAL. return 0 on
+ success, negative errno code otherwise.</p>
+<h4 id="poll">poll()</h4>
+<pre> int (*poll)(struct sensors_poll_device_t *dev,
+ sensors_event_t* data, int count);</pre>
+<p>Returns an array of sensor data. This function must block until events are
+ available. It will return the number of events read on success, or -errno in
+ case of an error.</p>
+<p>The number of events returned in data must be less or equal to the "count"
+ argument. This function shall never return 0 (no event).</p>
