Sensors API
chevron down

Sensors API

Interface: Sensor

A sensor measures different physical quantities and provides corresponding sensor readings which are a source of information about the device and its environment.

Each reading is composed of the values of the different physical quantities measured by the sensor at a certain time.

Readings are reported either one by one (default mode) or in a batch of multiple readings (batch mode).

  • In default mode, a Sensor object includes properties that represent the last available reading. The names and types of those properties depend on the specific sensor type represented by subclasses of this base interface.

  • In batch mode, the Sensor object's readings property contains arrays of readings. The number of readings in the array depends on the batch property of the options passed to the constructor.

Read the Sensor Guides for further information.

Implemented by accelerometer.IAccelerometer, barometer.IBarometer, body-presence.IBodyPresenceSensor, gyroscope.IGyroscope, heart-rate.IHeartRateSensor, orientation.IOrientationSensor


readonly activated


Flag that indicates if the sensor is activated or not. When a sensor is created, the sensor is not activated, thus the initial value of this property equals false.


((this: Sensor, event: Event) => any) or undefined

Event handler that is called when the sensor is activated.


((this: Sensor, event: SensorErrorEvent) => any) or undefined

Event handler that is called when an error occurs. When an error occurs, the sensor is automatically stopped, and the activated property equals false.


((this: Sensor, event: Event) => any) or undefined

Event handler that is called whenever a new reading is available.



setOptions(options: SensorOptions)

Returns: void

New in SDK 4.0

Update the sensor parameters. This can be called both when the sensor is active (started) and when it's not.

Parameter: options Dictionary containing attributes (e.g. frequency, batch_size) to set and their values. See SensorOptions.

Throws: Throws an Error in case arguments are invalid, or there was a failure when interacting with the internal sensor object.


Returns: void

Start the sensor. This will cause the sensor to start and become activated.


Returns: void

Stop the sensor. This will cause the sensor to stop and become deactivated. The onreading event handler will no longer be called when the sensor is deactivated.

Interface: SensorErrorEvent

Event that is emitted when an asynchronous error occurs.


readonly defaultPrevented


Set to true when the default handling was prevented

readonly error


The error that occurred

readonly target

EventTarget or undefined

Target of the event

readonly type


Type of the event

Interface: BatchedSensorReading

New in SDK 6.0

Implemented by accelerometer.BatchedAccelerometerReading, barometer.BatchedBarometerReading, gyroscope.BatchedGyroscopeReading, heart-rate.BatchedHeartRateSensorReading, orientation.BatchedOrientationSensorReading


readonly timestamp


Interface: SensorReading

Base type for sensor readings.

Specific subtypes add named properties to convey the data measured by the sensor. Those properties may be null when no reading is available for the sensor (when the sensor is not yet activated and there are no valid cached values that can be used).

Implemented by accelerometer.AccelerometerReading, barometer.BarometerReading, gyroscope.GyroscopeReading, heart-rate.HeartRateSensorReading, orientation.OrientationSensorReading


readonly timestamp

number or null

Timestamp of the reading in milliseconds.

NOTE: this is relative to an unspecified arbitrary 0 time, or null if no reading is available (when the sensor is not yet activated and there are no valid cached values that can be used).

Interface: SensorOptions

Options used when instantiating a sensor.


readonly batch

number or undefined

New in SDK 2.0

Desired batch size.

Requesting a batch size is an indication to the sensor that readings should be reported by batches of batch count.

Batching allows a less frequent invocation of the sensor's onreading event handler. When batching is requested, the sensor's onreading event handler is called when a batch of readings is available. The readings are presented as contiguous arrays through the readings property.

NOTE: when operating in batch mode, the frequency still represents the sensor's sampling frequency, not the batch reporting frequency. So, for example, with a frequency of 30 and a batch size of 60, the 'reading' event can be expected to be emitted about every 2 seconds, with 60 readings each time, which gives an average of 30 readings per second.

readonly frequency

number or undefined

Desired sampling frequency in Hz.

The actual sampling frequency of the sensor may be different from the desired frequency, depending on various constraints from the driver and/or hardware capabilities.

NOTE: the timestamp property of sensor readings may be used to determine the actual sampling frequency in effect when the sensor is running.