Module: Toybox.SensorHistory

Overview

The SensorHistory module contains the interface for SensorHistory.

SensorHistory provides access to historical information recorded by the on-board sensors of device hardware. The amount of information that is available is device dependent. This means that one device may provide more information than another. This class provides an ORDER_* enum which is used to select the data order of the sample iterator.

Since:

API Level 2.1.0

Supported Devices:

Requires Permission:

SensorHistory

Classes Under Namespace

Classes: SensorHistoryIterator, SensorSample

Constant Summary

Order

Name	Value	Since	Description	See Also
ORDER_NEWEST_FIRST	0	API Level 2.1.0	Request iterator with newest data first
ORDER_OLDEST_FIRST	1	API Level 2.1.0	Request iterator with oldest data first

Instance Method Summary collapse

getBodyBatteryHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the body battery history for the given period.
getElevationHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the elevation history for the given period, up to the last power cycle.
getHeartRateHistory(options as { :period as Lang.Number or Time.Duration, :order as SensorHistory.Order or Null } or Null) as SensorHistory.SensorHistoryIterator

Get the heart rate history for the given period, up to the last power cycle.
getOxygenSaturationHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the oxygen saturation history for the given period This function always returns the most recent sensor history samples.
getPressureHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the pressure history for the given period, up to the last power cycle.
getStressHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get stress history data for the given period This function always returns the most recent sensor history samples.
getTemperatureHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the temperature history for the given period, up to the last power cycle.

Instance Method Details

getBodyBatteryHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the body battery history for the given period.

This function always returns the most recent sensor history samples. The time between each `SensorSample` in the iterator may be device dependent.

Parameters:

options — (Lang.Dictionary) —

Dictionary of options. Can be null.
- :period — (Lang.Number, Time.Duration) —
  The period of time from which to retrieve the samples:
  - If null, the entire available history is retrieved
  - If a Duration, then the history for the given Duration is retrieved
  - If a Number, then the last specified Number of entries are retrieved
- :order — (Lang.Boolean) —
  The order in which to retrieve the samples:
  - If null, the samples will be ORDER_NEWEST_FIRST
  - Use the ORDER_* enumeration to explicitly select ORDER_NEWEST_FIRST or ORDER_OLDEST_FIRST

Example:

Shows the use of BodyBatteryIterator

using Toybox.SensorHistory;
using Toybox.System;

  // Create a method to get the SensorHistoryIterator object
  function getIterator() {
      // Check device for SensorHistory compatibility
      if ((Toybox has :SensorHistory) && (Toybox.SensorHistory has :getBodyBatteryHistory)) {
          // Set up the method with parameters
          return Toybox.SensorHistory.getBodyBatteryHistory({});
      }
      return null;
  }
  // get the body battery iterator object
  var bbIterator = getIterator();
  var sample = bbIterator.next();                         // get the body battery data

  while (sample != null) {
      System.println("Sample: " + sample.data);           // print the current sample
      sample = bbIterator.next();
  }

Supported Devices:

Returns:

SensorHistory.SensorHistoryIterator —

An iterator for the body battery history for the given period. Samples returned by this iterator are ranges from 0-100. A 0 indicates that the body is drained and a 100 indicates the body is rested and charged.

See Also:

Since:

API Level 3.3.0

getElevationHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the elevation history for the given period, up to the last power cycle.

This function always returns the most recent pressure samples. The time between each SensorSample in the iterator may be device dependent.

Parameters:

options — (Lang.Dictionary) —

Dictionary of options. Can be null.
- :period — (Lang.Number, Time.Duration) —
  The period of time from which to retrieve the samples:
  - If null, the entire available history is retrieved
  - If a Duration, then the history for the given Duration is retrieved
  - If a Number, then the last specified Number of entries are retrieved
- :order — (Lang.Boolean) —
  The order in which to retrieve the samples:
  - If null, the samples will be ORDER_NEWEST_FIRST
  - Use the ORDER_* enumeration to explicitly select ORDER_NEWEST_FIRST or ORDER_OLDEST_FIRST

Example:

Gets a SensoryHistoryIterator and prints out the elevation value from the most recent SensorSample

using Toybox.SensorHistory;
using Toybox.Lang;
using Toybox.System;

// Create a method to get the SensorHistoryIterator object
function getIterator() {
    // Check device for SensorHistory compatibility
    if ((Toybox has :SensorHistory) && (Toybox.SensorHistory has :getElevationHistory)) {
        return Toybox.SensorHistory.getElevationHistory({});
    }
    return null;
}

// Store the iterator info in a variable. The options are 'null' in
// this case so the entire available history is returned with the
// newest samples returned first.
var sensorIter = getIterator();

// Print out the next entry in the iterator
if (sensorIter != null) {
    System.println(sensorIter.next().data);
}

Supported Devices:

Returns:

SensorHistory.SensorHistoryIterator —

An iterator for the elevation history for the given period. Samples returned by this iterator are in meters (m).

See Also:

Since:

API Level 2.1.0

getHeartRateHistory(options as { :period as Lang.Number or Time.Duration, :order as SensorHistory.Order or Null } or Null) as SensorHistory.SensorHistoryIterator

Get the heart rate history for the given period, up to the last power cycle.

This function always returns the most recent heart rate samples. The time between each SensorSample in the iterator may be device dependent.

Parameters:

options — (Lang.Dictionary) —

Dictionary of options. Can be null.
- :period — (Lang.Number, Time.Duration) —
  The period of time from which to retrieve the samples:
  - If null, the entire available history is retrieved
  - If a Duration, then the history for the given Duration is retrieved
  - If a Number, then the last specified Number of entries are retrieved
- :order — (Lang.Boolean) —
  The order in which to retrieve the samples:
  - If null, the samples will be listed ORDER_NEWEST_FIRST
  - Use the ORDER_* enumeration to explicitly select ORDER_NEWEST_FIRST or ORDER_OLDEST_FIRST

Example:

Gets a SensoryHistoryIterator and prints out the heart rate value from the most recent SensorSample

using Toybox.SensorHistory;
using Toybox.Lang;
using Toybox.System;

// Create a method to get the SensorHistoryIterator object
function getIterator() {
    // Check device for SensorHistory compatibility
    if ((Toybox has :SensorHistory) && (Toybox.SensorHistory has :getHeartRateHistory)) {
        return Toybox.SensorHistory.getHeartRateHistory({});
    }
    return null;
}

// Store the iterator info in a variable. The options are 'null' in
// this case so the entire available history is returned with the
// newest samples returned first.
var sensorIter = getIterator();

// Print out the next entry in the iterator
if (sensorIter != null) {
    System.println(sensorIter.next().data);
}

Returns:

SensorHistory.SensorHistoryIterator —

An iterator for the heart rate history for the given period. Samples returned by this iterator are in beats per minute (bpm).

See Also:

Since:

API Level 2.1.0

getOxygenSaturationHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the oxygen saturation history for the given period

This function always returns the most recent sensor history samples. The time between each `SensorSample` in the iterator may be device dependent.

Parameters:

options — (Lang.Dictionary) —

Dictionary of options. Can be null.
- :period — (Lang.Number, Time.Duration) —
  The period of time from which to retrieve the samples:
  - If null, the entire available history is retrieved
  - If a Duration, then the history for the given Duration is retrieved
  - If a Number, then the last specified Number of entries are retrieved
- :order — (Lang.Boolean) —
  The order in which to retrieve the samples:
  - If null, the samples will be ORDER_NEWEST_FIRST
  - Use the ORDER_* enumeration to explicitly select ORDER_NEWEST_FIRST or ORDER_OLDEST_FIRST

Example:

Gets a SensoryHistoryIterator and prints out the Muscle Oxygen Saturation value from the most recent SensorSample

using Toybox.SensorHistory;
using Toybox.Lang;
using Toybox.System;

// Create a method to get the SensorHistoryIterator object
function getIterator() {
    // Check device for SensorHistory compatibility
    if ((Toybox has :SensorHistory) && (Toybox.SensorHistory has :getOxygenSaturationHistory)) {
        // Set up the method with parameters
        return Toybox.SensorHistory.getOxygenSaturationHistory({});
    }
    return null;
}

// Store the iterator info in a variable. The options are 'null' in
// this case so the entire available history is returned with the
// newest samples returned first.
var sensorIter = getIterator();

// Print out the next entry in the iterator
if (sensorIter != null) {
    System.println(sensorIter.next().data);
}

Supported Devices:

Returns:

SensorHistory.SensorHistoryIterator —

An iterator for the oxygen saturation history for the given period. Samples returned by this iterator are in percent (%).

See Also:

Since:

API Level 3.2.0

getPressureHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the pressure history for the given period, up to the last power cycle.

This function always returns the most recent pressure samples. The time between each SensorSample in the iterator may be device dependent.

Parameters:

options — (Lang.Dictionary) —

Dictionary of options. Can be null.
- :period — (Lang.Number, Time.Duration) —
  The period of time from which to retrieve the samples.
  - If period is null, the entire available history is retrieved
  - If period is a Duration, then the history for the given Duration is retrieved
  - If period is a Number, then the last specified Number of entries are retrieved
- :order — (Lang.Boolean) —
  The order in which to retrieve the samples.
  - If order is null, the samples will be ORDER_NEWEST_FIRST
  - Use the ORDER enumeration to explicitly select ORDER_NEWEST_FIRST or ORDER_OLDEST_FIRST

Example:

Gets a SensoryHistoryIterator and prints out the pressure value from the most recent SensorSample

using Toybox.SensorHistory;
using Toybox.Lang;
using Toybox.System;

// Create a method to get the SensorHistoryIterator object
function getIterator() {
    // Check device for SensorHistory compatibility
    if ((Toybox has :SensorHistory) && (Toybox.SensorHistory has :getPressureHistory)) {
        return Toybox.SensorHistory.getPressureHistory({});
    }
    return null;
}

// Store the iterator info in a variable. The options are 'null' in
// this case so the entire available history is returned with the
// newest samples returned first.
var sensorIter = getIterator();

// Print out the next entry in the iterator
if (sensorIter != null) {
    System.println(sensorIter.next().data);
}

Supported Devices:

Returns:

SensorHistory.SensorHistoryIterator —

An iterator for the pressure history for the given period. Samples returned by this iterator are in Pascals (Pa).

See Also:

Since:

API Level 2.1.0

getStressHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get stress history data for the given period

This function always returns the most recent sensor history samples. The time between each `SensorSample` in the iterator may be device dependent.

Parameters:

options — (Lang.Dictionary) —

Dictionary of options. Can be null.
- :period — (Lang.Number, Time.Duration) —
  The period of time from which to retrieve the samples:
  - If null, the entire available history is retrieved
  - If a Duration, then the history for the given Duration is retrieved
  - If a Number, then the last specified Number of entries are retrieved
- :order — (Lang.Boolean) —
  The order in which to retrieve the samples:
  - If null, the samples will be ORDER_NEWEST_FIRST
  - Use the ORDER_* enumeration to explicitly select ORDER_NEWEST_FIRST or ORDER_OLDEST_FIRST

Example:

Shows the use of StressHistoryIterator

using Toybox.ActivityMonitor;
using Toybox.System;

  // Create a method to get the SensorHistoryIterator object
  function getIterator() {
      // Check device for SensorHistory compatibility
      if ((Toybox has :SensorHistory) && (Toybox.SensorHistory has :getStressHistory)) {
          // Set up the method with parameters
          return Toybox.SensorHistory.getStressHistory({});
      }
      return null;
  }

// get stress history iterator object
var stressIterator = getIterator();
var sample = stressIterator.next();                        // get the stress data

while (sample != null) {
    System.println("Sample: " + sample.data);        // print the current sample
    sample = stressIterator.next();
}

Supported Devices:

Returns:

SensorHistory.SensorHistoryIterator —

An iterator for the stress history for the given period. Samples returned by this iterator are ranges from 0-100. Higher value indicate higher stress and lower value indicate lower stress. and a 100 indicates the body is rested and charged.

See Also:

Since:

API Level 3.3.0

getTemperatureHistory(options as { :period as Lang.Number or Time.Duration or Null, :order as SensorHistory.Order } or Null) as SensorHistory.SensorHistoryIterator

Get the temperature history for the given period, up to the last power cycle.

This function always returns the most recent temperature samples. The time between each SensorSample in the iterator may be device dependent.

Parameters:

options — (Lang.Dictionary) —

Dictionary of options. Can be null.
- :period — (Lang.Number, Time.Duration) —
  The period of time from which to retrieve the samples:
  - If null, the entire available history is retrieved
  - If a Duration, then the history for the given Duration is retrieved
  - If a Number, then the last specified Number of entries are retrieved
- :order — (Lang.Boolean) —
  The order in which to retrieve the samples.
  - If null, the samples will be listed ORDER_NEWEST_FIRST
  - Use the ORDER_* enumeration to explicitly select ORDER_NEWEST_FIRST or ORDER_OLDEST_FIRST

Example:

Gets a SensoryHistoryIterator and prints out the temperature value from the most recent SensorSample

using Toybox.SensorHistory;
using Toybox.Lang;
using Toybox.System;

// Create a method to get the SensorHistoryIterator object
function getIterator() {
    // Check device for SensorHistory compatibility
    if ((Toybox has :SensorHistory) && (Toybox.SensorHistory has :getTemperatureHistory)) {
        // Set up the method with parameters
        return Toybox.SensorHistory.getTemperatureHistory({});
    }
    return null;
}

// Store the iterator info in a variable. The options are 'null' in
// this case so the entire available history is returned with the
// newest samples returned first.
var sensorIter = getIterator();

// Print out the next entry in the iterator
if (sensorIter != null) {
    System.println(sensorIter.next().data);
}

Supported Devices:

Returns:

SensorHistory.SensorHistoryIterator —

An iterator for the temperature history for the given period. Samples returned by this iterator are in degrees Celsius (C).

See Also:

Since:

API Level 2.1.0

Generated Apr 1, 2024 11:04:32 AM