Merge "docs: Added new sensor types. Bug: 10674725" into klp-docs
This commit is contained in:
Ricardo Cervera
committed by
Android (Google) Code Review
Android (Google) Code Review
commit
2e92965820
@@ -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
|
||||
@@ -450,4 +528,64 @@ North Pole.</li>
|
||||
<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>
|
||||
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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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">μ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>
|
||||
@@ -313,4 +445,4 @@ public class SensorActivity extends Activity implements SensorEventListener {
|
||||
"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>
|
||||
android.hardware.Sensor#getMaximumRange} method.</p>
|
||||
|
||||
Reference in New Issue
Block a user