Reporting modes

Sensors can generate events in different ways called reporting modes; each sensor type has one and only one reporting mode associated with it. Four reporting modes exist.

Continuous

Events are generated at a constant rate defined by the sampling_period_ns parameter passed to the batch function. Example sensors using the continuous reporting mode are accelerometers and gyroscopes.

On-change

Events are generated only if the measured values have changed. Activating the sensor at the HAL level (calling activate(..., enable=1) on it) 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 reporting mode are the step counter, proximity, and heart rate sensor types.

The sampling_period_ns parameter passed to the batch function is used to set the minimum time between consecutive events, meaning an event shouldn't be generated until sampling_period_ns nanoseconds elapsed since the last event, even if the value changed since then. If the value changed, an event must be generated as soon as sampling_period_ns has elapsed since the last event.

For example, suppose:

  • We activate the step counter with sampling_period_ns = 10 * 10^9 (10 seconds).
  • We walk for 55 seconds, then stand still for one minute.
  • The events are generated about every 10 seconds during the first minute (including at time t=0 because of the activation of the sensor, and t=60 seconds), for a total of seven events. No event is generated in the second minute because the value of the step count didn’t change after t=60 seconds.

One-shot

Upon detection of an event, the sensor deactivates itself and then sends a single event through the HAL. Order matters to avoid race conditions. (The sensor must be deactivated before the event is reported through the HAL). No other event is sent until the sensor is reactivated. Significant motion is an example of this kind of sensor.

One-shot sensors are sometimes referred to as trigger sensors.

The sampling_period_ns and max_report_latency_ns parameters passed to the batch function are ignored. Events from one-shot events cannot be stored in hardware FIFOs; the events must be reported as soon as they are generated.

Special

See the individual sensor type descriptions for details on when the events are generated.