Base sensors and trigger modes

In this document

Trigger modes

Sensors can report events in different ways called trigger modes; each sensor type has one and only one trigger mode associated to it. Four trigger modes exist:

Continuous

Events are reported at a constant rate defined by setDelay(). Example sensors using the continuous trigger mode are accelerometers and gyroscopes.

On-change

Events are reported only if the sensor's value has changed. Activating the sensor also triggers an event, meaning the HAL must return an event immediately when an on-change sensor is activated. Example sensors using the on-change trigger mode are the step counter and proximity sensor types.

Here is how the period_ns parameter affects setDelay(...) and batch(...). The period_ns parameter is used to set a lower limit to the reporting period, meaning the minimum time between consecutive events. Here is an example: If activating the step counter with period_ns = 10 seconds, walking for 1 minute, and then not walking for 1 minute, the events will be generated every 10 seconds during the first minute, and no event will be generated in the second minute.

One-shot

Upon detection of an event, the sensor deactivates itself and then sends a single event. Order matters to avoid race conditions. No other event is sent until the sensor is reactivated. setDelay() is ignored. Significant motion is an example of this kind of sensor.

Special

See the individual sensor type descriptions for details.

Categories

Sensors fall into four primary categories:

Base - records core measurements from which all other sensors are derived
Activity - detects user or device movement
Attitude - measures the orientation of the device
Uncalibrated - is identical to the corresponding base sensor except the dynamic calibration is reported separately rather than applied to the results

Base sensors

These sensor types are listed first because they are the fundamental sensors upon which all other sensor types are based.

Accelerometer

Trigger-mode: Continuous
Wake-up sensor: No

All values are in SI units (m/s^2) and measure the acceleration of the device minus the force of gravity.

Acceleration sensors return sensor events for all three axes at a constant rate defined by setDelay().

  • x: Acceleration on the x-axis
  • y: Acceleration on the y-axis
  • z: Acceleration on the z-axis

Note the readings from the accelerometer include the acceleration due to gravity (which is opposite the direction of the gravity vector).

Here are examples:

  • The norm of (x, y, z) should be close to 0 when in free fall.
  • When the device lies flat on a table and is pushed on its left side toward the right, the x acceleration value is positive.
  • When the device lies flat on a table, the acceleration value is +9.81, which corresponds to the acceleration of the device (0 m/s^2) minus the force of gravity (-9.81 m/s^2).
  • When the device lies flat on a table and is pushed toward the sky, the acceleration value is greater than +9.81, which corresponds to the acceleration of the device (+A m/s^2) minus the force of gravity (-9.81 m/s^2).

Ambient temperature

Trigger-mode: On-change
Wake-up sensor: No

This sensor provides the ambient (room) temperature in degrees Celsius.

Geomagnetic field

Trigger-mode: Continuous
Wake-up sensor: No

All values are in micro-Tesla (uT) and measure the geomagnetic field in the X, Y and Z axis.

Returned values include calibration mechanisms so the vector is aligned with the magnetic declination and heading of the earth's geomagnetic field.

Magnetic field sensors return sensor events for all three axes at a constant rate defined by setDelay().

Gyroscope

Trigger-mode: Continuous
Wake-up sensor: No

All values are in radians/second and measure the rate of rotation around the X, Y and Z axis. 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).

Automatic gyro-drift compensation is required.

Light

Trigger-mode: On-change
Wake-up sensor: No

The light sensor value is returned in SI lux units.

Proximity

Trigger-mode: On-change
Wake-up sensor: Yes

Measures the distance from the sensor to the closest visible surface. As this is a wake-up sensor, it should wake up the SoC when it is running and detects a change in proximity. The distance value is measured in centimeters. Note that some proximity sensors only support a binary "near" or "far" measurement. In this case, the sensor should report its maxRange value in the "far" state and a value less than maxRange in the "near" state.

To ensure the applications have the time to receive the 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.

Pressure

Trigger-mode: Continuous
Wake-up sensor: No

The pressure sensor uses a barometer to return the atmospheric pressure in hectopascal (hPa).

Relative humidity

Trigger-mode: On-change
Wake-up sensor: No

A relative humidity sensor measures relative ambient air humidity and returns a value in percent.