Composite sensors

In this document

Composite sensor type summary

The following table lists the composite sensor types and their categories, underlying base sensors, and trigger modes. Certain base sensors are required of each sensor for accuracy. Using other tools to approximate results should be avoided as they will invariably provide a poor user experience.

When there is no gyroscope on the device, and only when there is no gyroscope, you may implement the rotation vector and other composite sensors without using the gyroscope.

Sensor type Category Underlying base sensor Trigger mode
Game rotation vector Attitude Accelerometer, Gyroscope MUST NOT USE Magnetometer Continuous
Geomagnetic rotation vector (Magnetometer) Low power sensor Attitude Accelerometer, Magnetometer NOT Gyroscope Continuous
Gravity Attitude Accelerometer, Gyroscope Continuous
Gyroscope uncalibrated Uncalibrated Gyroscope Continuous
Linear acceleration Activity Accelerometer, Gyroscope AND Magnetometer Continuous
Magnetic field uncalibrated Uncalibrated Magnetometer Continuous
Orientation Attitude Accelerometer, Magnetometer PREFERRED Gyroscope Continuous
Rotation vector Attitude Accelerometer, Gyroscope AND Magnetometer Continuous
Significant motion Low power sensor Activity Accelerometer (or another as long as very low power) One-shot
Step counter Low power sensor Activity Accelerometer On- change
Step detector Low power sensor Activity Accelerometer Special

low power icon = Low power sensor

Activity sensors

Linear acceleration

Underlying base sensor(s): Accelerometer, Gyroscope AND Magnetometer
Trigger-mode: Continuous
Wake-up sensor: No

Indicates the linear acceleration of the device in device coordinates, not including gravity. The output is conceptually:
output of TYPE_ACCELERATION minus output of TYPE_GRAVITY.

Readings on all axes should be close to 0 when the device is immobile. Units are m/s^2. The coordinate system is the same as is used for the acceleration sensor.

Significant motion

Underlying base sensor(s): Accelerometer (or another as long as low power)
Trigger-mode: One-shot
Wake-up sensor: Yes

Significant motion allows a device to stay in suspend and idle modes longer and save power. It does this by relying upon last known location until the device experiences "significant motion." Such a movement would trigger on mode and a call to retrieve new location.

Here is an example on how the platform can use significant motion to save power. When users are moving, their locations are updated frequently. After some period of inactivity, significant motion presumes the device is static and stops seeking location updates. It instead registers the last known location as valid. The device is then allowed to go into idle and then suspend mode.

This sensor exists to save power by keeping the SoC in suspend mode when the device is at rest. A sensor of this type triggers an event each time significant motion is detected and automatically disables itself. The only allowed value to return is 1.0.

A significant motion is a motion that might lead to a change in the user location. Examples of such significant motions are:

  • walking or biking
  • sitting in a moving car, coach or train

Examples of situations that should not trigger significant motion:

  • phone in pocket and person is not moving
  • phone is on a table and the table shakes a bit due to nearby traffic or washing machine

This sensor makes a tradeoff for power consumption that may result in a small amount of false negatives. This is done for a few reasons:

  1. The goal of this sensor is to save power.
  2. Triggering an event when the user is not moving (false positive) is costly in terms of power, so it should be avoided.
  3. Not triggering an event when the user is moving (false negative) is acceptable as long as it is not done repeatedly. If the user has been walking for 10 seconds, not triggering an event within those 10 seconds is not acceptable.

To ensure the applications have the time to receive the significant motion event before the application processor goes back to sleep, the driver must hold a "timeout wake lock" for 200 milliseconds for every wake-up sensor. That is, the application processor should not be allowed to go back to sleep in the 200 milliseconds following a wake-up interrupt.

Important: This sensor is very different from the other types in that it must work when the screen is off without the need for holding a partial wake lock (other than the timeout wake lock) and MUST allow the SoC to go into suspend. When significant motion is detected, the sensor must awaken the SoC and the event be reported.

If a particular device cannot support this mode of operation, then this sensor type must not be reported by the HAL. ie: it is not acceptable to "emulate" this sensor in the HAL.

When the sensor is not activated, it must also be deactivated in the hardware; it must not wake up the SoC anymore, even in case of significant motion.

setDelay() has no effect and is ignored.

Once a "significant motion" event is returned, a sensor of this type must disable itself automatically, as if activate(..., 0) had been called.

Step detector

Underlying base sensor(s): Accelerometer
Trigger-mode: Special
Wake-up sensor: No

A sensor of this type triggers an event each time a step is taken by the user. The only allowed value to return is 1.0 and an event is generated for each step. Like with any other event, the timestamp indicates when the event (here the step) occurred. This corresponds to when the foot hit the ground, generating a high variation in acceleration.

Compared to the step counter, the step detector should have a lower latency (less than 2 seconds). Both the step detector and the step counter detect when the user is walking, running and walking up the stairs. They should not trigger when the user is biking, driving or in other vehicles.

While this sensor operates, it shall not disrupt any other sensors, in particular, the accelerometer; it might very well be in use.

This sensor must be low power. That is, if the step detection cannot be done in hardware, this sensor should not be defined. Also, when the step detector is activated and the accelerometer is not, only steps should trigger interrupts (not accelerometer data).

setDelay() has no impact on this sensor type.

Step counter

Underlying base sensor(s): Accelerometer
Trigger-mode: On-change
Wake-up sensor: No

A sensor of this type returns the number of steps taken by the user since the last reboot while activated. The value is returned as a uint64_t and is reset to zero only on a system reboot.

The timestamp of the event is set to the time when the last step for that event was taken.
See the Step detector sensor type for the signification of the time of a step.

Compared to the step detector, the step counter can have a higher latency (less than 10 seconds). Thanks to this latency, this sensor has a high accuracy; the step count after a full day of measures should be within 10% of the real step count. Both the step detector and the step counter detect when the user is walking, running and walking up the stairs. They should not trigger when the user is biking, driving or in other vehicles.

Important note: This sensor is different from other types in that it must work when the screen is off without the need of holding a partial wake-lock and MUST allow the SoC to go into suspend.

While in suspend mode this sensor must stay active. No events are reported during that time but steps continue to be accounted for; an event will be reported as soon as the SoC resumes if the timeout has expired.

In other words, when the screen is off and the device is allowed to go into suspend mode, it should not be woken up, regardless of the setDelay() value. But the steps shall continue to be counted.

The driver must however ensure the internal step count never overflows. The minimum size of the hardware's internal counter shall be 16 bits. (This restriction is here to avoid too frequent wake-ups when the delay is very large.) It is allowed in this situation to wake the SoC up so the driver can do the counter maintenance.

While this sensor operates, it shall not disrupt any other sensors, in particular, the accelerometer; it might very well be in use.

If a particular device cannot support these modes of operation, then this sensor type must not be reported by the HAL. ie: it is not acceptable to "emulate" this sensor in the HAL.

This sensor must be low power. That is, if the step detection cannot be done in hardware, this sensor should not be defined. Also, when the step counter is activated and the accelerometer is not, only steps should trigger interrupts (not accelerometer data).

Attitude sensors

Rotation vector

Underlying base sensor(s): Accelerometer, Gyroscope AND Magnetometer
Trigger-mode: Continuous
Wake-up sensor: No

The rotation vector symbolizes the orientation of the device relative to the East-North-Up coordinates frame. It is usually obtained by integration of accelerometer, gyroscope and magnetometer readings.

The East-North-Up coordinate system is defined as a direct orthonormal basis where:

  • X points east and is tangential to the ground.
  • Y points north and is tangential to the ground.
  • Z points towards the sky and is perpendicular to the ground.

The orientation of the phone is represented by the rotation necessary to align the East-North-Up coordinates with the phone's coordinates. That is, applying the rotation to the world frame (X,Y,Z) would align them with the phone coordinates (x,y,z).

The rotation can be seen as rotating the phone by an angle theta around an axis rot_axis to go from the reference (East-North-Up aligned) device orientation to the current device orientation.

The rotation is encoded as the four (reordered) components of a unit quaternion:

  • sensors_event_t.data[0] = rot_axis.x*sin(theta/2)
  • sensors_event_t.data[1] = rot_axis.y*sin(theta/2)
  • sensors_event_t.data[2] = rot_axis.z*sin(theta/2)
  • sensors_event_t.data[3] = cos(theta/2)

Where:

  • rot_axis.x,y,z are the North-East-Up coordinates of a unit length vector representing the rotation axis
  • theta is the rotation angle

The quaternion must be of norm 1. (It is a unit quaternion.) Failure to ensure this will cause erratic client behaviour.

In addition, this sensor reports an estimated heading accuracy:
sensors_event_t.data[4] = estimated_accuracy (in radians)

The heading error must be less than estimated_accuracy 95% of the time. This sensor must use a gyroscope and an accelerometer as main orientation change input.

This sensor should also include magnetometer input to make up for gyro drift, but it cannot be implemented using only a magnetometer.

Game rotation vector

Underlying base sensor(s): Accelerometer, Gyroscope NOT Magnetometer
Trigger-mode: Continuous
Wake-up sensor: No

Similar to the rotation vector sensor but not using the geomagnetic field. Therefore the Y axis doesn't 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.

This sensor does not report an estimated heading accuracy:
sensors_event_t.data[4] is reserved and should be set to 0

In an ideal case, a phone rotated and returned to the same real-world orientation should report the same game rotation vector (without using the earth's geomagnetic field).

This sensor must be based on a gyroscope. It cannot be implemented using a magnetometer.

Gravity

Underlying base sensor(s): Accelerometer, Gyroscope NOT Magnetometer
Trigger-mode: Continuous
Wake-up sensor: No

The gravity output of this sensor indicates the direction and magnitude of gravity in the device's coordinates. Units are m/s^2. On Earth, the magnitude is 9.8 m/s^2. The coordinate system is the same as is used for the acceleration sensor. When the device is at rest, the output of the gravity sensor should be identical to that of the accelerometer.

Geomagnetic rotation vector (Magnetometer)

Underlying base sensor(s): Accelerometer, Magnetometer NOT Gyroscope
Trigger-mode: Continuous
Wake-up sensor: No

This sensor is similar to the rotation vector sensor but using a magnetometer instead of a gyroscope.

This sensor must be based on a magnetometer. It cannot be implemented using a gyroscope, and gyroscope input cannot be used by this sensor.

Just like the rotation vector sensor, this sensor reports an estimated heading accuracy:
sensors_event_t.data[4] = estimated_accuracy (in radians)

The heading error must be less than estimated_accuracy 95% of the time.

See the rotation vector sensor description for more details.

Orientation

Underlying base sensor(s): Accelerometer, Magnetometer PREFERRED Gyroscope
Trigger-mode: Continuous
Wake-up sensor: No

Note: This is an older sensor type that has been deprecated in the Android SDK although not yet in the HAL. It has been replaced by the rotation vector sensor, which is more clearly defined, requires a gyroscope, and therefore provides more accurate results. Use the rotation vector sensor over the orientation sensor whenever possible.

The orientation sensor tracks the attitude of the device. All values are angles in degrees. Orientation sensors return sensor events for all three axes at a constant rate defined by setDelay().

  • azimuth: angle between the magnetic north direction and the Y axis, around
    the Z axis (0<=azimuth<360). 0=North, 90=East, 180=South, 270=West
  • pitch: Rotation around X axis (-180<=pitch<=180), with positive values when the z-axis moves toward the y-axis.
  • roll: Rotation around Y axis (-90<=roll<=90), with positive values when the x-axis moves towards the z-axis.

Please note, for historical reasons the roll angle is positive in the clockwise direction. (Mathematically speaking, it should be positive in the counter-clockwise direction):

Depiction of orientation relative to a device

Figure 2. Orientation relative to a device.

This definition is different from yaw, pitch and roll used in aviation where the X axis is along the long side of the plane (tail to nose).

Uncalibrated sensors

Uncalibrated sensors provide more raw results and may include some bias but also 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.

Gyroscope uncalibrated

Underlying base sensor(s): Gyroscope
Trigger-mode: Continuous
Wake-up sensor: No

The uncalibrated gyroscope is useful for post-processing and melding orientation data. All values are in radians/second and measure the rate of rotation around the X, Y and Z axis. An estimation of the drift on each axis is reported as well.

No gyro-drift compensation shall be performed. Factory calibration and temperature compensation should still be applied to the rate of rotation (angular speeds).

The coordinate system is the same as is used for the acceleration sensor. Rotation is positive in the counter-clockwise direction (right-hand rule). That is, an observer looking from some positive location on the x, y or z axis at a device positioned on the origin would report positive rotation if the device appeared to be rotating counter clockwise. Note that this is the standard mathematical definition of positive rotation and does not agree with the definition of roll given elsewhere.

The range should at least be 17.45 rad/s (ie: ~1000 deg/s).

Content of an uncalibrated_gyro event (units are rad/sec):

  • x_uncalib : angular speed (w/o drift compensation) around the X axis
  • y_uncalib : angular speed (w/o drift compensation) around the Y axis
  • z_uncalib : angular speed (w/o drift compensation) around the Z axis
  • x_bias : estimated drift around X axis in rad/s
  • y_bias : estimated drift around Y axis in rad/s
  • z_bias : estimated drift around Z axis in rad/s

If the implementation is not able to estimate the drift, then this sensor must not be reported by this HAL. Instead, the regular Gyroscope sensor is used without drift compensation.

If this sensor is present, then the corresponding Gyroscope sensor must be present and both must return the same sensor_t::name and sensor_t::vendor.

Magnetic field uncalibrated

Underlying base sensor(s): Magnetometer
Trigger-mode: Continuous
Wake-up sensor: No

Similar to Geomagnetic field sensor, but the hard iron calibration is reported separately instead of being included in the measurement. The uncalibrated magnetometer allows the system to handle bad hard iron estimation.

Factory calibration and temperature compensation should still be applied to the "uncalibrated" measurement. Separating away the hard iron calibration estimation allows the system to better recover from bad hard iron estimation.

All values are in micro-Tesla (uT) and measure the ambient magnetic field in the X, Y and Z axis. Assumptions that the magnetic field is due to the Earth's poles should be avoided.

The uncalibrated_magnetic event contains three fields for uncalibrated measurement: x_uncalib, y_uncalib, z_uncalib. Each is a component of the measured magnetic field, with soft iron and temperature compensation applied, but not hard iron calibration. These values should be continuous (no re-calibration should cause a jump).

The uncalibrated_magnetic event contains three fields for hard iron bias estimates: x_bias, y_bias, z_bias. Each field is a component of the estimated hard iron calibration. They represent the offsets to apply to the calibrated readings to obtain uncalibrated readings (x_uncalib ~= x_calibrated + x_bias). These values are expected to jump as soon as the estimate of the hard iron changes, and they should be stable the rest of the time.

If this sensor is present, then the corresponding Geomagnetic field sensor must be present and both must return the same sensor_t::name and sensor_t::vendor.

See the geomagnetic field sensor description for more information.