am 588300cb: am 2e929658: Merge "docs: Added new sensor types. Bug: 10674725" into klp-docs

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">

      <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>

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

    <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>

    <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>

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

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() {

    @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>

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>

  <div id="qv">

  <h2>In this document</h2>

  <ol>

    <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>

    <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>

    <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>

<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

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>