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

Since:

API Level 1.0.0

Name Value Since Description See Also
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

OnboardSensorType

Since:

API Level 1.0.0

Name Value Since Description See Also
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

SensorTechnology

The sensor technology

Describes the technology used to communicate with the sensor.

Since:

API Level 3.2.0

Name Value Since Description See Also
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

Instance Method Summary collapse

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:

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:

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:

See Also:

Since:

API Level 1.0.0

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:

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:

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().

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:

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:

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

Register a callback to fetch high-frequency data from various sensors.

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:

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:

See Also:

Since:

API Level 2.3.0

Throws:

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:

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().

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:

See Also:

Since:

API Level 2.3.0


Generated Jun 6, 2024 10:31:53 AM