Gyroscope Sensor Guide
chevron down
back search icon cancel search
 
 

Gyroscope Sensor Guide

Overview

The Gyroscope sensor measures the device's angular velocity along 3 orthogonal axes (X, Y and Z).

Note: Only the Fitbit Versa and Fitbit Sense contain a gyroscope sensor.

A Brief Introduction to Axes

The X axis is parallel with the device's screen, aligned with the left and right edges, in the top-bottom direction. The Y axis is parallel with the device's screen, aligned with the top and bottom edges, in the left-right direction. The Z axis is perpendicular to the device's screen, pointing up.

The sign (+/-) of angular velocities follows the right-hand rule. A positive angular velocity along an axis corresponds to the curling direction of the fingers of a right hand, with the thumb pointing in the direction of the axis.

Peeking the Current Gyroscope Reading

If you need to check the latest reading from the gyroscope, you can access the properties directly from the gyroscope object using the reading event.

import { Gyroscope } from "gyroscope";

if (Gyroscope) {
  const gyro = new Gyroscope({ frequency: 1 });
  gyro.addEventListener("reading", () => {
    console.log(
      `ts: ${gyro.timestamp}, \
       x: ${gyro.x}, \
       y: ${gyro.y}, \
       z: ${gyro.z}`
    );
  });
  gyro.start();
}

Batched Readings

The Gyroscope 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 (x, y, z, 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 { Gyroscope } from "gyroscope";

if (Gyroscope) {
  // 30 readings per second, 60 readings per batch
  const gyro = new Gyroscope({ frequency: 30, batch: 60 });
  gyro.addEventListener("reading", () => {
    for (let index = 0; index < gyro.readings.timestamp.length; index++) {
      console.log(
        `Gyroscope Reading: \
          timestamp=${gyro.readings.timestamp[index]}, \
          [${gyro.readings.x[index]}, \
          ${gyro.readings.y[index]}, \
          ${gyro.readings.z[index]}]`
      );
    }
  });
  gyro.start();
}

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 { Gyroscope } from "gyroscope";
import { display } from "display";

if (Gyroscope) {
  const gyro = new Gyroscope({ frequency: 1 });
  gyro.addEventListener("reading", () => {
    console.log(
      `ts: ${gyro.timestamp}, \
       x: ${gyro.x}, \
       y: ${gyro.y}, \
       z: ${gyro.z}`
    );
  });
  display.addEventListener("change", () => {
    // Automatically stop the sensor when the screen is off to conserve battery
    display.on ? gyro.start() : gyro.stop();
  });
  gyro.start();
}

Gyroscope Best Practices

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

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

The Gyroscope in Action

If you're interested in using the Gyroscope API within your application, please review the Gyroscope API reference documentation.

previous
Barometer Sensor Guide
Heart Rate Sensor Guide
next