Module: Toybox.Sensor

Overview

The Sensor module provides access to sensor data.

Sensor allows Apps to register for updates to the current sensor data. It also enables apps to control the ANT+ sensors supported natively by the device, which are described by the provided SENSOR_* constants.

Example:

Using heart rate sensors to display current heart rate

using Toybox.Sensor;
function initialize() {
    Sensor.setEnabledSensors([Sensor.SENSOR_HEARTRATE]);
    Sensor.enableSensorEvents(method(:onSensor));
}

function onSensor(sensorInfo) {
    System.println("Heart Rate: " + sensorInfo.heartRate);
}

Since:

API Level 1.0.0

App Types:

Watch App
Audio Content Provider
Background
Data Field
Widget

Supported Devices:

Requires Permission:

Sensor

Classes Under Namespace

Classes: AccelerometerData, GyroscopeData, HeartRateData, Info, MagnetometerData, SensorData, SensorInfo, SensorInfoIterator, TooManySensorDataListenersException

Constant Summary

RemoteSensorType
OnboardSensorType
SensorTechnology

Name	Value	Since
SENSOR_BIKESPEED	0	API Level 1.0.0
SENSOR_BIKECADENCE	1	API Level 1.0.0
SENSOR_BIKEPOWER	2	API Level 1.0.0
SENSOR_FOOTPOD	3	API Level 1.0.0
SENSOR_HEARTRATE	4	API Level 1.0.0
SENSOR_TEMPERATURE	5	API Level 1.0.0

Name	Value	Since
SENSOR_PULSE_OXIMETRY	6	API Level 3.2.0
SENSOR_ONBOARD_PULSE_OXIMETRY	7	API Level 3.2.0
SENSOR_ONBOARD_HEARTRATE	8	API Level 3.2.0

Name	Value	Since	Description
SENSOR_TECHNOLOGY_ANT	0	API Level 3.2.0	ANT Sensor
SENSOR_TECHNOLOGY_BLE	1	API Level 3.2.0	Bluetooth Low Energy Sensor
SENSOR_TECHNOLOGY_ONBOARD	2	API Level 3.2.0	Onboard Sensor

Typedef Summary collapse

SensorType as Sensor.RemoteSensorType or Sensor.OnboardSensorType

Instance Method Summary collapse

disableSensorType(sensorType as Sensor.SensorType) as Lang.Boolean

Disable the given sensor type for use.
enableSensorEvents(listener as Null or Lang.Method(info as Sensor.Info) as Void) as Void

Request sensor events from enabled sensors.
enableSensorType(sensorType as Sensor.SensorType) as Lang.Boolean

Enable the given sensor type for use.
getInfo() as Sensor.Info

Get the current Sensor Sensor.Info.
getMaxSampleRate() as Lang.Number

Get the maximum sample rate supported by the system.
getMaxSampleRateForSensorType(sensorDataType as Lang.Symbol) as Lang.Number

Get the maximum sample rate supported for given sensor data type.
getRegisteredSensors(sensorType as Sensor.SensorType or Null) as Sensor.SensorInfoIterator

Retrieve the sensors that are currently registered.
registerSensorDataListener(listener as Lang.Method(data as Sensor.SensorData) as Void, options as { :period as Lang.Number, :accelerometer as { :enabled as Lang.Boolean, :sampleRate as Lang.Number, :includePower as Lang.Boolean, :includePitch as Lang.Boolean, :includeRoll as Lang.Boolean }, :gyroscope as { :enabled as Lang.Boolean, :sampleRate as Lang.Number }, :magnetometer as { :enabled as Lang.Boolean, :sampleRate as Lang.Number }, :heartBeatIntervals as { :enabled as Lang.Boolean } }) as Void

Register a callback to fetch high-frequency data from various sensors.
setEnabledSensors(sensors as Lang.Array<Sensor.SensorType>) as Lang.Array<Sensor.SensorType>

Enable sensors for use.
unregisterSensorDataListener() as Void

Unregister a previously registered data listener.

Typedef Details

SensorType as Sensor.RemoteSensorType or Sensor.OnboardSensorType

Since:

API Level 1.0.0

Instance Method Details

disableSensorType(sensorType as Sensor.SensorType) as Lang.Boolean

Disable the given sensor type for use.

Unlike the existing setEnabledSensors() function, this will not enable/disable other sensor types.

Note:

Will cause an app crash if called from a data field app

Returns:

Lang.Boolean —

true on success, otherwise false.

Since:

API Level 3.2.0

enableSensorEvents(listener as Null or Lang.Method(info as Sensor.Info) as Void) as Void

Request sensor events from enabled sensors.

Sensor events are retrieved from any enabled sensors at a rate of 1 Hz. The data retrieved from enabled sensors is passed to the listener Method provided as a parameter to this method.

Note:

Will cause an app crash if called from a data field app

Parameters:

listener — (Lang.Method) —
A reference to a listener Method:
- Called when sensor updates are received
- Receives a Sensor.info object
- Use null to specify no listener

Example:

using Toybox.Sensor;
// Given an onSensor listener method is defined
Sensor.enableSensorEvents(method(:onSensor));

Since:

API Level 1.0.0

enableSensorType(sensorType as Sensor.SensorType) as Lang.Boolean

Enable the given sensor type for use.

Unlike the existing setEnabledSensors() function, this will not enable/disable other sensor types.

Note:

Will cause an app crash if called from a data field app

Note:

Multitasking: Sensor states can not be changed while in inacitve mode and sensor enabled during active mode will be disabled when app becomes inactive, and re-enabled automatically when is active again. These state changes are denoted by calls to AppBase.onActive() and AppBase.onInactive().

Returns:

Lang.Boolean —

true on success, otherwise false.

Since:

API Level 3.2.0

getInfo() as Sensor.Info

Get the current Sensor Sensor.Info.

This is useful for retrieving the current sensor info either on demand or periodically within a Timer.

Note:

Will cause an app crash if called from a data field app

Example:

Get accelerometer data once per second

using Toybox.Sensor;
using Toybox.System;
using Toybox.Timer;
var dataTimer = new Timer.Timer();
dataTimer.start(method(:timerCallback), 1000, true); // A one-second timer
function timerCallback() {
    var sensorInfo = Sensor.getInfo();
    if (sensorInfo has :accel && sensorInfo.accel != null) {
        var accel = sensorInfo.accel;
        var xAccel = accel[0];
        var yAccel = accel[1];
        System.println("x: " + xAccel + ", y: " + yAccel);
    }
}

Returns:

Sensor.Info

getMaxSampleRate() as Lang.Number

Get the maximum sample rate supported by the system.

Note:

Will cause an app crash if called from a data field app

Note:

This function can produce different results after the app transitions to the active state after being inactive. These state changes are denoted by calls to AppBase.onActive() and AppBase.onInactive().

Example:

using Toybox.Sensor;
var maxSample = Sensor.getMaxSampleRate();

Supported Devices:

Returns:

Lang.Number —

The max sample rate as a number

Since:

API Level 2.3.0

getMaxSampleRateForSensorType(sensorDataType as Lang.Symbol) as Lang.Number

Get the maximum sample rate supported for given sensor data type.

Note:

Will cause an app crash if called from a data field app

Note:

Parameters:

sensorDataType — (Lang.Symbol) —

Symbol of the sensor data type to get the max rate for, allowed symbols are accelerometer, gyroscope, and magnetometer.

Example:

using Toybox.Sensor;
var maxSample = Sensor.getMaxSampleRateForSensorType(:accelerometer);

Supported Devices:

Returns:

Lang.Number —

The max sample rate as a Number

Since:

API Level 3.4.5

getRegisteredSensors(sensorType as Sensor.SensorType or Null) as Sensor.SensorInfoIterator

Retrieve the sensors that are currently registered.

This function returns an iterator for the sensors that are considered to be `registered` if pairing information has been provided for it in Sensor settings.

Parameters:

sensorType — (Lang.Number, null) —

A SENSOR_* value that describes the sensor type to enumerate, or null to get all sensors.

Returns:

Sensor.SensorInfoIterator —

An iterator of the sensors that are currently registered.

Since:

API Level 3.2.0

registerSensorDataListener(listener as Lang.Method(data as Sensor.SensorData) as Void, options as { :period as Lang.Number, :accelerometer as { :enabled as Lang.Boolean, :sampleRate as Lang.Number, :includePower as Lang.Boolean, :includePitch as Lang.Boolean, :includeRoll as Lang.Boolean }, :gyroscope as { :enabled as Lang.Boolean, :sampleRate as Lang.Number }, :magnetometer as { :enabled as Lang.Boolean, :sampleRate as Lang.Number }, :heartBeatIntervals as { :enabled as Lang.Boolean } }) as Void

The callback will get invoked each time a new set of sensor data over the length of time specified in the period option is available.

Note:

Only one data request is allowed to be registered at a time. Subsequent calls to this function for the same sensor type will override previously registered requests.

Note:

Will cause an app crash if called from a data field app

Parameters:

listener — (Lang.Method) —

A method that takes a single SensorData object as a parameter that will contain the requested data.
options — (Lang.Dictionary) —

A Dictionary of options. The allowed values depend on sensor type.
- :period — (Lang.Number) —
  
  Period of time to request samples in seconds. Maximum is 4 seconds.
- :accelerometer — (Lang.Dictionary) —
  Options for accelerometer data.
  - :enabled (Toybox::Lang::Boolean) Set to true to fetch data from the accelerometer.
  - :sampleRate (Toybox::Lang::Number) Samples per second to request in Hz.
  - :includePower (Toybox::Lang::Boolean) Valid only when :accelerometer=>:enabled is set to true. Requests that the power Array be computed.
  - :includePitch (Toybox::Lang::Boolean) Valid only when :accelerometer=>:enabled is set to true. Requests that the pitch Array be computed.
  - :includeRoll (Toybox::Lang::Boolean) Valid only when :accelerometer=>:enabled is set to true. Requests that the roll Array be computed.
- :heartBeatIntervals — (Lang.Dictionary) —
  Options for Heart Beat Interval data.
  - :enabled (Toybox::Lang::Boolean) Set to true to fetch heart beat interval data.
- :gyroscope — (Lang.Dictionary) —
  Options for gyroscope data.
  - :enabled (Toybox::Lang::Boolean) Set to true to fetch data from the gyroscope.
  - :sampleRate (Toybox::Lang::Number) Samples per second to request in Hz.
- :magnetometer — (Lang.Dictionary) —
  Options for magnetometer data.
  - :enabled (Toybox::Lang::Boolean) Set to true to fetch data from the magnetometer.
  - :sampleRate (Toybox::Lang::Number) Samples per second to request in Hz.

Example:

using Toybox.Sensor;
// initialize accelerometer
var options = {
    :period => 1,               // 1 second sample time
    :accelerometer => {
        :enabled => true,       // Enable the accelerometer
        :sampleRate => 25       // 25 samples
    },
    :heartBeatIntervals => {
        :enabled => true
    }
};
// Using the callback setup in Toybox.SensorHistory.SensorData
Sensor.registerSensorDataListener(method(:accelCallback), options);

Supported Devices:

setEnabledSensors(sensors as Lang.Array<Sensor.SensorType>) as Lang.Array<Sensor.SensorType>

Enable sensors for use.

This will enable both connected ANT+ sensors and system sensors if possible.

Note:

Will cause an app crash if called from a data field app

Note:

Parameters:

sensors — (Lang.Array) —
The sensors to enable:
- An Array of SENSOR_* types to enable
- An empty array ([]) to disable all sensors

Example:

Enable a heart rate sensor

using Toybox.Sensor;
Sensor.setEnabledSensors([Sensor.SENSOR_HEARTRATE]);

Returns:

Lang.Array —

An Array of requested sensors that are available

Since:

API Level 1.0.0

unregisterSensorDataListener() as Void

Unregister a previously registered data listener.

Note:

Will cause an app crash if called from a data field app

Example:

// Assuming use of registerSensorDataListener() example and mSession
using Toybox.Sensor;

Sensor.unregisterSensorDataListener(); // Unregister Listener
mSession.stop();                       // Stop Activity Recording

Supported Devices:

Module: Toybox.Sensor

Overview

Classes Under Namespace

Constant Summary

RemoteSensorType

OnboardSensorType

SensorTechnology

Typedef Summary collapse

Instance Method Summary collapse

Typedef Details

SensorType as Sensor.RemoteSensorType or Sensor.OnboardSensorType

Instance Method Details

disableSensorType(sensorType as Sensor.SensorType) as Lang.Boolean

enableSensorEvents(listener as Null or Lang.Method(info as Sensor.Info) as Void) as Void

enableSensorType(sensorType as Sensor.SensorType) as Lang.Boolean

getInfo() as Sensor.Info

getMaxSampleRate() as Lang.Number

getMaxSampleRateForSensorType(sensorDataType as Lang.Symbol) as Lang.Number

getRegisteredSensors(sensorType as Sensor.SensorType or Null) as Sensor.SensorInfoIterator

setEnabledSensors(sensors as Lang.Array<Sensor.SensorType>) as Lang.Array<Sensor.SensorType>

unregisterSensorDataListener() as Void