Merge "docs: Added new sensor types. Bug: 10674725" into klp-docs

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 @@ page.tags="sensorevent","accelerometer","gyroscope","gravity","rotation"
       <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 @@ sensors can be either hardware-based or software-based (the gravity, linear acce
 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
@@ -120,6 +123,32 @@ parameters. Table 1 summarizes the motion sensors that are available on the Andr
     <td><code>SensorEvent.values[2]</code></td>
     <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>
@@ -152,6 +181,25 @@ parameters. Table 1 summarizes the motion sensors that are available on the Andr
     <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 @@ drift (bias). In practice, gyroscope noise and drift will introduce errors that
 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
@@ -451,3 +529,63 @@ North Pole.</li>
 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>
+
+
+<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() {
+    &#64;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>

docs/html/guide/topics/sensors/sensors_overview.jd

@@ -710,7 +710,7 @@ have negative Z values. This coordinate system is used by the following sensors:
 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>

docs/html/guide/topics/sensors/sensors_position.jd

@@ -6,7 +6,9 @@ page.tags="sensorevent","orientation","proximity"
   <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>
@@ -82,6 +84,34 @@ the position sensors that are supported on the Android platform.</p>
     <th scope="col" style="white-space:nowrap">Description</th>
     <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>
@@ -96,6 +126,32 @@ the position sensors that are supported on the Android platform.</p>
     <td><code>SensorEvent.values[2]</code></td>
     <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">&mu;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>
@@ -125,11 +181,58 @@ discussed in <a href="#sensors-pos-orient">Using the Orientation Sensor</a>.</p>
 <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 @@ use these matrices with the {@link android.hardware.SensorManager#getOrientation
 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>