Position sensors

The Android platform provides two sensors that let you determine the position
of a device: the geomagnetic field sensor and the accelerometer. The Android
platform also provides a sensor that lets you determine how close the face of
a device is to an object (known as the proximity sensor). The
geomagnetic field sensor and the proximity sensor are hardware-based. Most
handset and tablet manufacturers include a geomagnetic field sensor. Likewise,
handset manufacturers usually include a proximity sensor to determine when a
handset is being held close to a user's face (for example, during a phone
call). For determining a device's orientation, you can use the readings from
the device's accelerometer and the geomagnetic field sensor.

Position sensors are useful for determining a device's physical position in
the world's frame of reference. For example, you can use the geomagnetic field
sensor in combination with the accelerometer to determine a device's position
relative to the magnetic north pole. You can also use these sensors to
determine a device's orientation in your application's frame of reference.
Position sensors are not typically used to monitor device movement or motion,
such as shake, tilt, or thrust (for more information, see Motion sensors).

The geomagnetic field sensor and accelerometer return multi-dimensional arrays
of sensor values for each SensorEvent. For example,
the geomagnetic field sensor provides geomagnetic field strength values for
each of the three coordinate axes during a single sensor event. Likewise, the
accelerometer sensor measures the acceleration applied to the device during a
sensor event. For more information about the coordinate systems that are used
by sensors, see
Sensor coordinate systems. The proximity sensor provides a single value
for each sensor event. Table 1 summarizes the position sensors that are
supported on the Android platform.

1This sensor was deprecated in Android 2.2 (API
level 8), and this sensor type was deprecated in Android 4.4W (API level 20).
The sensor framework provides alternate methods for acquiring device
orientation, which are discussed in Compute
the device's orientation.

2 Some proximity sensors provide only binary values
representing near and far.

Use the game rotation vector sensor

The game rotation vector sensor is identical to the
Rotation
vector sensor, 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.

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.

The following code shows you how to get an instance of the default game rotation vector
sensor:

Use the geomagnetic rotation vector sensor

The geomagnetic rotation vector sensor is similar to the
Rotation
vector sensor, 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.

The following code shows you how to get an instance of the default geomagnetic rotation
vector sensor:

Compute the device's orientation

By computing a device's orientation, you can monitor the position of the
device relative to the earth's frame of reference (specifically, the magnetic
north pole). The following code shows you how to compute a device's
orientation:

The system computes the orientation angles by using a device's geomagnetic
field sensor in combination with the device's accelerometer. Using these two
hardware sensors, the system provides data for the following three
orientation angles:

Azimuth (degrees of rotation about the -z axis). This is
the angle between the device's current compass direction and magnetic north.
If the top edge of the device faces magnetic north, the azimuth is 0
degrees; if the top edge faces south, the azimuth is 180 degrees. Similarly,
if the top edge faces east, the azimuth is 90 degrees, and if the top edge
faces west, the azimuth is 270 degrees.

Pitch (degrees of rotation about the x axis). This is the
angle between a plane parallel to the device's screen and a plane parallel
to the ground. If you hold the device parallel to the ground with the bottom
edge closest to you and tilt the top edge of the device toward the ground,
the pitch angle becomes positive. Tilting in the opposite direction—
moving the top edge of the device away from the ground—causes
the pitch angle to become negative. The range of values is -180 degrees to
180 degrees.

Roll (degrees of rotation about the y axis). This is the
angle between a plane perpendicular to the device's screen and a plane
perpendicular to the ground. If you hold the device parallel to the ground
with the bottom edge closest to you and tilt the left edge of the device
toward the ground, the roll angle becomes positive. Tilting in the opposite
direction—moving the right edge of the device toward the ground—
causes the roll angle to become negative. The range of values is -90 degrees
to 90 degrees.

Note:The sensor's roll definition has changed to reflect the
vast majority of implementations in the geosensor ecosystem.

Note that these angles work off of a different coordinate system than the
one used in aviation (for yaw, pitch, and roll). In the aviation system, the
x axis is along the long side of the plane, from tail to nose.

The orientation sensor derives its data by processing the raw sensor data
from the accelerometer and the geomagnetic field sensor. Because of the heavy
processing that is involved, the accuracy and precision of the orientation
sensor is diminished. Specifically, this sensor is reliable only when the roll
angle is 0. As a result, the orientation sensor was deprecated in Android
2.2 (API level 8), and the orientation sensor type was deprecated in Android
4.4W (API level 20).
Instead of using raw data from the orientation sensor, we recommend that you
use the getRotationMatrix()
method in conjunction with the
getOrientation() method
to compute orientation values, as shown in the following code sample. As part
of this process, you can use the
remapCoordinateSystem()
method to translate the orientation values to your application's frame of
reference.

You don't usually need to perform any data processing or filtering of the
device's raw orientation angles other than translating the sensor's
coordinate system to your application's frame of reference.

Use the geomagnetic field sensor

The geomagnetic field sensor lets you monitor changes in the earth's magnetic field. The
following code shows you how to get an instance of the default geomagnetic field sensor:

This sensor provides raw field strength data (in μT) for each of the three coordinate axes.
Usually, you do not need to use this sensor directly. Instead, you can use the rotation vector
sensor to determine raw rotational movement or you can use the accelerometer and geomagnetic field
sensor in conjunction with the getRotationMatrix() method to obtain the rotation matrix and the inclination matrix. You can then
use these matrices with the getOrientation()
and getInclination() methods to obtain azimuth
and geomagnetic inclination data.

Note: When testing your app, you can improve
the sensor's accuracy by waving the device in a figure-8 pattern.

Use the uncalibrated magnetometer

The uncalibrated magnetometer is similar to the geomagnetic field
sensor, 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, geomagneticsensor_event.values[0]
will be close to uncalibrated_magnetometer_event.values[0] -
uncalibrated_magnetometer_event.values[3]. That is,

calibrated_x ~= uncalibrated_x - bias_estimate_x

Note: 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.

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:

The proximity sensor is usually used to determine how far away a person's head is from the face
of a handset device (for example, when a user is making or receiving a phone call). Most
proximity sensors return the absolute distance, in cm, but some return only near and
far values. The following code shows you how to use the proximity sensor:

Note: Some proximity sensors return binary values that represent
"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 getMaximumRange() method.