Heart Rate Sensor Guide
chevron down
back search icon cancel search
 
 

Heart Rate Sensor Guide

Overview

The Heart Rate sensor measures a person’s heartRate in 'Beats per minute'.

Peeking the Current Heart Rate

If you need to check the latest reading from the heart rate sensor, you can access the properties directly from the HeartRateSensor object using the reading event.

import { HeartRateSensor } from "heart-rate";

if (HeartRateSensor) {
  const hrm = new HeartRateSensor({ frequency: 1 });
  hrm.addEventListener("reading", () => {
    console.log(`Current heart rate: ${hrm.heartRate}`);
  });
  hrm.start();
}

Detecting Off-Wrist

The readings from the HeartRateSensor contain a timestamp which can be used to determine if the current reading is stale, but we recommend using the Body Presence API to detect the off/on wrist events.

import { BodyPresenceSensor } from "body-presence";

if (BodyPresenceSensor) {
  const body = new BodyPresenceSensor();
  body.addEventListener("reading", () => {
    if (!body.present) {
      hrm.stop();
    } else {
      hrm.start();
    }
  });
  body.start();
}

Batched Readings

The HeartRateSensor API can also generate batches of data at a specified sample rate. This allows a developer to control the frequency that their application receives and processes sensor data.

The onreading event is emitted when a batch of readings is available, and the .readings property contains the sensor readings, with each data channel (bpm, and timestamp) as its own array.

By reducing the sample rate (frequency), or by increasing the batch size, developers will benefit from reduced CPU usage, and minimize their application's impact on battery life.

In order to use batched readings, the batch property must be specified during the initialization of the sensor.

import { HeartRateSensor } from "heart-rate";

if (HeartRateSensor) {
  // 1 reading per second, 60 readings per batch
  let hrm = new HeartRateSensor({ frequency: 1, batch: 60 });
  hrm.addEventListener("reading", () => {
    for (let index = 0; index < hrm.readings.timestamp.length; index++) {
      console.log(
        `HeartRateSensor Reading: \
          timestamp=${hrm.readings.timestamp[index]}, \
          [${hrm.readings.heartRate[index]}]`
      );
    }
  });
  hrm.start();
}

Permissions

In order to access data from the HeartRateSensor, you must request the access_heart_rate permission within the package.json file, and check that the permission has been granted within your code.

import { me as appbit } from "appbit";
import { HeartRateSensor } from "heart-rate";

if (HeartRateSensor && appbit.permissions.granted("access_heart_rate")) {
  const hrm = new HeartRateSensor();
  hrm.start();
}

Read the Permissions Guide for further information.

Automatically Stopping and Starting

One of the best ways to conserve battery life is to stop the sensor when the display is off. You can use the Display API to respond to changes in the screen's power state.

import { HeartRateSensor } from "heart-rate";
import { display } from "display";

if (HeartRateSensor) {
  const hrm = new HeartRateSensor();
  hrm.addEventListener("reading", () => {
    console.log(`Current heart rate: ${hrm.heartRate}`);
  });
  display.addEventListener("change", () => {
    // Automatically stop the sensor when the screen is off to conserve battery
    display.on ? hrm.start() : hrm.stop();
  });
  hrm.start();
}

Heart Rate Sensor Best Practices

Here's a simple list of best practices to follow when using the Heart Rate Sensor API:

  1. Always use the most optimal frequency for your specific needs.
  2. Don't forget to call hrm.stop(); when you've finished using it.
  3. Check if the sensor exists before using it.

The Heart Rate Sensor in Action

If you're interested in using the Heart Rate Sensor API within your application, why not check out the "HR Meter" example app or review the Heart-rate API reference documentation.

previous
Gyroscope Sensor Guide
Orientation Sensor Guide
next