am 1d77a874: am 588300cb: am 2e929658: Merge "docs: Added new sensor types. Bug: 10674725" into klp-docs
* commit '1d77a8741c8b08c2b911e714c56521483e23bdac':
docs: Added new sensor types. Bug: 10674725
diff --git a/docs/html/guide/topics/sensors/sensors_motion.jd b/docs/html/guide/topics/sensors/sensors_motion.jd
index 289c639..945f8a6 100644
--- a/docs/html/guide/topics/sensors/sensors_motion.jd
+++ b/docs/html/guide/topics/sensors/sensors_motion.jd
@@ -1,5 +1,5 @@
page.title=Motion Sensors
-page.tags="sensorevent","accelerometer","gyroscope","gravity","rotation"
+page.tags="sensorevent","accelerometer","gyroscope","gravity","rotation","stepcounter"
@jd:body
<div id="qv-wrapper">
@@ -11,6 +11,9 @@
<li><a href="#sensors-motion-gyro">Using the Gyroscope</a></li>
<li><a href="#sensors-motion-linear">Using the Linear Accelerometer</a></li>
<li><a href="#sensors-motion-rotate">Using the Rotation Vector Sensor</a></li>
+ <li><a href="#sensors-motion-significant">Using the Significant Motion Sensor</a></li>
+ <li><a href="#sensors-motion-stepcounter">Using the Step Counter Sensor</a></li>
+ <li><a href="#sensors-motion-stepdetector">Using the Step Detector Sensor</a></li>
</ol>
<h2>Key classes and interfaces</h2>
<ol>
@@ -47,7 +50,7 @@
rotation vector sensors). For example, on some devices the software-based sensors derive their data
from the accelerometer and magnetometer, but on other devices they may also use the gyroscope to
derive their data. Most Android-powered devices have an accelerometer, and many now
-include a gyroscope. The availability of the softare-based sensors is more variable because they
+include a gyroscope. The availability of the software-based sensors is more variable because they
often rely on one or more hardware sensors to derive their data.</p>
<p>Motion sensors are useful for monitoring device movement, such as tilt, shake, rotation, or
@@ -121,6 +124,32 @@
<td>Rate of rotation around the z axis.</td>
</tr>
<tr>
+ <td rowspan="6">{@link android.hardware.Sensor#TYPE_GYROSCOPE_UNCALIBRATED}</td>
+ <td><code>SensorEvent.values[0]</code></td>
+ <td>Rate of rotation (without drift compensation) around the x axis.</td>
+ <td rowspan="6">rad/s</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[1]</code></td>
+ <td>Rate of rotation (without drift compensation) around the y axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[2]</code></td>
+ <td>Rate of rotation (without drift compensation) around the z axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[3]</code></td>
+ <td>Estimated drift around the x axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[4]</code></td>
+ <td>Estimated drift around the y axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[5]</code></td>
+ <td>Estimated drift around the z axis.</td>
+ </tr>
+ <tr>
<td rowspan="3">{@link android.hardware.Sensor#TYPE_LINEAR_ACCELERATION}</td>
<td><code>SensorEvent.values[0]</code></td>
<td>Acceleration force along the x axis (excluding gravity).</td>
@@ -152,6 +181,25 @@
<td><code>SensorEvent.values[3]</code></td>
<td>Scalar component of the rotation vector ((cos(θ/2)).<sup>1</sup></td>
</tr>
+ <tr>
+ <td>{@link android.hardware.Sensor#TYPE_SIGNIFICANT_MOTION}</td>
+ <td>N/A</td>
+ <td>N/A</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>{@link android.hardware.Sensor#TYPE_STEP_COUNTER}</td>
+ <td><code>SensorEvent.values[0]</code></td>
+ <td>Number of steps taken by the user since the last reboot while the sensor
+ was activated.</td>
+ <td>Steps</td>
+ </tr>
+ <tr>
+ <td>{@link android.hardware.Sensor#TYPE_STEP_DETECTOR}</td>
+ <td>N/A</td>
+ <td>N/A</td>
+ <td>N/A</td>
+ </tr>
</table>
<p class="note"><strong><sup>1</sup></strong> The scalar component is an optional value.</p>
@@ -366,6 +414,36 @@
compensated for. You usually determine the drift (bias) and noise by monitoring other sensors, such
as the gravity sensor or accelerometer.</p>
+<h2 id="sensors-motion-gyrounc">Using the Uncalibrated Gyroscope</h2>
+
+<p>The uncalibrated gyroscope is similar to the <a href="#sensors-motion-gyro">gyroscope</a>,
+except that no gyro-drift compensation is applied to the rate of rotation. Factory calibration
+and temperature compensation are still applied to the rate of rotation. The uncalibrated
+gyroscope is useful for post-processing and melding orientation data. In general,
+<code>gyroscope_event.values[0]</code> will be close to
+<code>uncalibrated_gyroscope_event.values[0] - uncalibrated_gyroscope_event.values[3]</code>.
+That is,</p>
+
+<p><code>calibrated_x ~= uncalibrated_x - bias_estimate_x</code></p>
+
+<p class="note"><strong>Note:</strong> Uncalibrated sensors provide more raw results and may
+include some bias, but their measurements 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>
+
+<p>In addition to the rates of rotation, the uncalibrated gyroscope also provides the estimated
+drift around each axis. The following code shows you how to get an instance of the default
+uncalibrated gyroscope:</p>
+
+<pre>
+private SensorManager mSensorManager;
+private Sensor mSensor;
+...
+mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_GYROSCOPE_UNCALIBRATED);
+</pre>
+
<h2 id="sensors-motion-linear">Using the Linear Accelerometer</h2>
<p>The linear acceleration sensor provides you with a three-dimensional vector representing
@@ -450,4 +528,64 @@
<p>The Android SDK provides a sample application that shows how to use the rotation vector sensor.
The sample application is located in the API Demos code (<a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html">
-OS - RotationVectorDemo</a>).</p>
\ No newline at end of file
+OS - RotationVectorDemo</a>).</p>
+
+
+<h2 id="sensors-motion-significant">Using the Significant Motion Sensor</h2>
+
+<p>The significant motion sensor triggers an event each time significant motion is detected and
+then it disables itself. A significant motion is a motion that might lead to a change in the
+user's location; for example walking, biking, or sitting in a moving car. The following code shows you
+how to get an instance of the default significant motion sensor and how to register an event
+listener:</p>
+
+<pre>
+private SensorManager mSensorManager;
+private Sensor mSensor;
+private TriggerEventListener mTriggerEventListener;
+...
+mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_SIGNIFICANT_MOTION);
+
+mTriggerEventListener = new TriggerEventListener() {
+ @Override
+ public void onTrigger(TriggerEvent event) {
+ // Do work
+ }
+};
+
+mSensorManager.requestTriggerSensor(mTriggerEventListener, mSensor);
+</pre>
+
+<p>For more information, see {@link android.hardware.TriggerEventListener}.</p>
+
+
+<h2 id="sensors-motion-stepcounter">Using the Step Counter Sensor</h2>
+
+<p>The step counter sensor provides the number of steps taken by the user since the last reboot
+while the sensor was activated. The step counter has more latency (up to 10 seconds) but more
+accuracy than the step detector sensor. The following code shows you how to get an instance of
+the default step counter sensor:</p>
+
+<pre>
+private SensorManager mSensorManager;
+private Sensor mSensor;
+...
+mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_STEP_COUNTER);
+</pre>
+
+
+<h2 id="sensors-motion-stepdetector">Using the Step Detector Sensor</h2>
+
+<p>The step detector sensor triggers an event each time the user takes a step. The latency is
+expected to be below 2 seconds. The following code shows you how to get an instance of the
+default step detector sensor:</p>
+
+<pre>
+private SensorManager mSensorManager;
+private Sensor mSensor;
+...
+mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_STEP_DETECTOR);
+</pre>
diff --git a/docs/html/guide/topics/sensors/sensors_overview.jd b/docs/html/guide/topics/sensors/sensors_overview.jd
index a162ccf..0b3cb2b 100644
--- a/docs/html/guide/topics/sensors/sensors_overview.jd
+++ b/docs/html/guide/topics/sensors/sensors_overview.jd
@@ -710,7 +710,7 @@
href="{@docRoot}guide/topics/sensors/sensors_motion.html#sensors-motion-accel">Acceleration
sensor</a></li>
<li><a
-href="{@docRoot}guide/topics/sensors/sensors_motion.html#sensors-motion-gravity">Gravity
+href="{@docRoot}guide/topics/sensors/sensors_motion.html#sensors-motion-grav">Gravity
sensor</a></li>
<li><a
href="{@docRoot}guide/topics/sensors/sensors_motion.html#sensors-motion-gyro">Gyroscope</a></li>
diff --git a/docs/html/guide/topics/sensors/sensors_position.jd b/docs/html/guide/topics/sensors/sensors_position.jd
index 55b282b..f021afe 100644
--- a/docs/html/guide/topics/sensors/sensors_position.jd
+++ b/docs/html/guide/topics/sensors/sensors_position.jd
@@ -6,7 +6,9 @@
<div id="qv">
<h2>In this document</h2>
<ol>
- <li><a href="#sensors-pos-orient">Using the Orientation Sensor</a></li>
+ <li><a href="#sensors-pos-gamerot">Using the Game Rotation Vector Sensor</a></li>
+ <li><a href="#sensors-pos-geomrot">Using the Geomagnetic Rotation Vector Sensor</a></li>
+ <li><a href="#sensors-pos-orient">Using the Orientation Sensor</a></li>
<li><a href="#sensors-pos-mag">Using the Geomagnetic Field Sensor</a></li>
<li><a href="#sensors-pos-prox">Using the Proximity Sensor</a></li>
</ol>
@@ -83,6 +85,34 @@
<th scope="col" style="white-space:nowrap">Units of measure</th>
</tr>
<tr>
+ <td rowspan="3">{@link android.hardware.Sensor#TYPE_GAME_ROTATION_VECTOR}</td>
+ <td><code>SensorEvent.values[0]</code></td>
+ <td>Rotation vector component along the x axis (x * sin(θ/2)).</td>
+ <td rowspan="3">Unitless</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[1]</code></td>
+ <td>Rotation vector component along the y axis (y * sin(θ/2)).</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[2]</code></td>
+ <td>Rotation vector component along the z axis (z * sin(θ/2)).</td>
+ </tr>
+ <tr>
+ <td rowspan="3">{@link android.hardware.Sensor#TYPE_GEOMAGNETIC_ROTATION_VECTOR}</td>
+ <td><code>SensorEvent.values[0]</code></td>
+ <td>Rotation vector component along the x axis (x * sin(θ/2)).</td>
+ <td rowspan="3">Unitless</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[1]</code></td>
+ <td>Rotation vector component along the y axis (y * sin(θ/2)).</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[2]</code></td>
+ <td>Rotation vector component along the z axis (z * sin(θ/2)).</td>
+ </tr>
+ <tr>
<td rowspan="3">{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD}</td>
<td><code>SensorEvent.values[0]</code></td>
<td>Geomagnetic field strength along the x axis.</td>
@@ -97,6 +127,32 @@
<td>Geomagnetic field strength along the z axis.</td>
</tr>
<tr>
+ <td rowspan="6">{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD_UNCALIBRATED}</td>
+ <td><code>SensorEvent.values[0]</code></td>
+ <td>Geomagnetic field strength (without hard iron calibration) along the x axis.</td>
+ <td rowspan="6">μT</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[1]</code></td>
+ <td>Geomagnetic field strength (without hard iron calibration) along the y axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[2]</code></td>
+ <td>Geomagnetic field strength (without hard iron calibration) along the z axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[3]</code></td>
+ <td>Iron bias estimation along the x axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[4]</code></td>
+ <td>Iron bias estimation along the y axis.</td>
+ </tr>
+ <tr>
+ <td><code>SensorEvent.values[5]</code></td>
+ <td>Iron bias estimation along the z axis.</td>
+ </tr>
+ <tr>
<td rowspan="3">{@link android.hardware.Sensor#TYPE_ORIENTATION}<sup>1</sup></td>
<td><code>SensorEvent.values[0]</code></td>
<td>Azimuth (angle around the z-axis).</td>
@@ -125,11 +181,58 @@
<p class="note"><sup><strong>2</strong></sup> Some proximity sensors provide only binary values
representing near and far.</p>
+
+<h2 id="sensors-pos-gamerot">Using the Game Rotation Vector Sensor</h2>
+
+<p>The game rotation vector sensor is identical to the
+<a href="{@docRoot}guide/topics/sensors/sensors_motion.html#sensors-motion-rotate">Rotation
+Vector Sensor</a>, except it does not use the geomagnetic field. Therefore the Y axis does not
+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>Because the game rotation vector sensor does not use the magnetic field, relative rotations
+are more accurate, and not impacted by magnetic field changes. Use this sensor in a game if
+you do not care about where north is, and the normal rotation vector does not fit your needs
+because of its reliance on the magnetic field.</p>
+
+<p>The following code shows you how to get an instance of the default game rotation vector
+sensor:</p>
+
+<pre>
+private SensorManager mSensorManager;
+private Sensor mSensor;
+...
+mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_GAME_ROTATION_VECTOR);
+</pre>
+
+
+<h2 id="sensors-pos-geomrot">Using the Geomagnetic Rotation Vector Sensor</h2>
+
+<p>The geomagnetic rotation vector sensor is similar to the
+<a href="{@docRoot}guide/topics/sensors/sensors_motion.html#sensors-motion-rotate">Rotation
+Vector Sensor</a>, but it uses a magnetometer instead of a gyroscope. The accuracy of this
+sensor is lower than the normal rotation vector sensor, but the power consumption is reduced.
+Only use this sensor if you want to collect some rotation information in the background without
+draining too much battery. This sensor is most useful when used in conjunction with batching.</p>
+
+<p>The following code shows you how to get an instance of the default geomagnetic rotation
+vector sensor:</p>
+
+<pre>
+private SensorManager mSensorManager;
+private Sensor mSensor;
+...
+mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_GEOMAGNETIC_ROTATION_VECTOR);
+</pre>
+
+
<h2 id="sensors-pos-orient">Using the Orientation Sensor</h2>
<p>The orientation sensor lets you monitor the position of a device relative to the earth's frame of
reference (specifically, magnetic north). The following code shows you how to get an instance of the
-default orientation sensor :</p>
+default orientation sensor:</p>
<pre>
private SensorManager mSensorManager;
@@ -249,6 +352,35 @@
and {@link android.hardware.SensorManager#getInclination getInclination()} methods to obtain azimuth
and geomagnetic inclination data.</p>
+<h2 id="sensors-pos-magunc">Using the Uncalibrated Magnetometer</h2>
+
+<p>The uncalibrated magnetometer is similar to the <a href="#sensors-pos-mag">geomagnetic field
+sensor</a>, except that no hard iron calibration is applied to the magnetic field. Factory calibration
+and temperature compensation are still applied to the magnetic field. The uncalibrated magnetometer
+is useful to handle bad hard iron estimations. In general, <code>geomagneticsensor_event.values[0]</code>
+will be close to <code>uncalibrated_magnetometer_event.values[0] -
+uncalibrated_magnetometer_event.values[3]</code>. That is,</p>
+
+<p><code>calibrated_x ~= uncalibrated_x - bias_estimate_x</code></p></p>
+
+<p class="note"><strong>Note:</strong> Uncalibrated sensors provide more raw results and may
+include some bias, but their measurements 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>
+
+<p>In addition to the magnetic field, the uncalibrated magnetometer also provides the
+estimated hard iron bias in each axis. The following code shows you how to get an instance of the
+default uncalibrated magnetometer:</p>
+
+<pre>
+private SensorManager mSensorManager;
+private Sensor mSensor;
+...
+mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_MAGNETIC_FIELD_UNCALIBRATED);
+</pre>
+
<h2 id="sensors-pos-prox">Using the Proximity Sensor</h2>
<p>The proximity sensor lets you determine how far away an object is from a device. The following
code shows you how to get an instance of the default proximity sensor:</p>
@@ -313,4 +445,4 @@
"near" or "far." In this case, the sensor usually reports its maximum range value in the far state
and a lesser value in the near state. Typically, the far value is a value > 5 cm, but this can vary
from sensor to sensor. You can determine a sensor's maximum range by using the {@link
-android.hardware.Sensor#getMaximumRange} method.</p>
\ No newline at end of file
+android.hardware.Sensor#getMaximumRange} method.</p>