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

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 RemoteSensorType or OnboardSensorType

Instance Method Summary collapse

Instance Method Details

disableSensorType(sensorType as SensorType) as Boolean

Disable the given sensor type for use.

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

Returns:

  • Boolean

    true on success, otherwise false.

Since:

API Level 3.2.0

enableSensorEvents(listener as Null or Method(info as 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.

Parameters:

  • listener(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 SensorType) as Boolean

Enable the given sensor type for use.

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

Returns:

  • Boolean

    true on success, otherwise false.

Since:

API Level 3.2.0

getInfo() as Info

Get the current Sensor Sensor.Info.

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

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 Number

Get the maximum sample rate supported by the system.

Example:

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

Supported Devices:

Returns:

  • Number

    The max sample rate as a number

Since:

API Level 2.3.0

getRegisteredSensors(sensorType as SensorType or Null) as 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(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 Method(data as SensorData) as Void, options as { :period as Number, :accelerometer as { :enabled as Boolean, :sampleRate as Number, :includePower as Boolean, :includePitch as Boolean, :includeRoll as Boolean }, :heartBeatIntervals as { :enabled as 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.

Parameters:

  • listener(Method)

    A method that takes a single SensorData object as a parameter that will contain the requested data.

  • options(Dictionary)

    A Dictionary of options. The allowed values depend on sensor type.

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 Array<SensorType>) as Array<SensorType>

Enable sensors for use.

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

Parameters:

  • sensors(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:

  • Array

    An Array of requested sensors that are available

Since:

API Level 1.0.0

unregisterSensorDataListener() as Void

Unregister a previously registered data listener.

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 Apr 22, 2021 10:10:32 AM