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

Requires Permission:

  • Sensor

Classes Under Namespace

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

Constant Summary

RemoteSensorType

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

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

typedef SensorType as Sensor.RemoteSensorType or Sensor.OnboardSensorType

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

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

Example:

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

Supported Devices:

Returns:

Since:

API Level 2.3.0

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 }, :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;
using Toybox.ActivityRecording;
// Set up a fit session to record the data
var mSession = ActivityRecording.createSession(
    {
        :name=>"PitchCounter",
        :sport=>ActivityRecording.SPORT_GENERIC,
        :sensorLogger => mLogger
    }
);
// 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);
mSession.start();                           // Start Activity Recording

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

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 Nov 29, 2021 1:34:36 PM