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
Properties
readonly activated
boolean
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.
onactivate
((this: Sensor, event: Event) => any) or undefined
Event handler that is called when the sensor is activated.
onerror
((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.
onreading
((this: Sensor, event: Event) => any) or undefined
Event handler that is called whenever a new reading is available.
Methods
setOptions()
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.
start()
Returns: void
Start the sensor. This will cause the sensor to start and become activated.
stop()
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.
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly error
Error
The error that occurred
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
Interface: BatchedSensorReading
New in SDK 6.0
Implemented by accelerometer.BatchedAccelerometerReading, barometer.BatchedBarometerReading, gyroscope.BatchedGyroscopeReading, heart-rate.BatchedHeartRateSensorReading, orientation.BatchedOrientationSensorReading
Properties
readonly timestamp
Uint32Array
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
Properties
readonly timestamp
number or null
Timestamp of the reading in milliseconds.
NOTE: this is relative to an unspecified arbitrary
0time, ornullif 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.
Properties
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
30and a batch size of60, the 'reading' event can be expected to be emitted about every2seconds, with60readings each time, which gives an average of30readings 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.
