Orientation Sensor Guide

Overview

An Orientation sensor measures the orientation of a device relative to an orthogonal coordinate frame.

Note: Only the Fitbit Versa and Fitbit Sense contain the orientation sensor.

The coordinate frame's axes, X, Y and Z are such that:

The X and Y axes are perpendicular to each other, but do not point in a particular direction relative to the earth. The orientation of X and Y relative to the earth can drift over time.
The Z axis is perpendicular to the ground and points towards the sky.

The sensor reading is a four-element array containing the components of the unit quaternion (a.k.a versor) representing the device's orientation.

The first element of the array is the scalar part of the quaternion, and the last 3 elements form the i, j and k factors of the vector part.

So if q is a quaternion reading, the quaternion can be written mathematically as:

q[0] + q[1]i + q[2]j + q[3]k

Reading Sensor Data

import { OrientationSensor } from "orientation";

if (OrientationSensor) {
  const orientation = new OrientationSensor({ frequency: 60 });
  orientation.addEventListener("reading", () => {
    console.log(
      `Orientation Reading: \
      timestamp=${orientation.timestamp}, \
      [${orientation.quaternion[0]}, \
      ${orientation.quaternion[1]}, \
      ${orientation.quaternion[2]}, \
      ${orientation.quaternion[3]}]`
    );
  });
  orientation.start();
}

Batched Readings

The OrientationSensor 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 (scalar, i, j, k, 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 { OrientationSensor } from "orientation";

if (OrientationSensor) {
  // 30 readings per second, 60 readings per batch
  const orientation = new OrientationSensor({ frequency: 30, batch: 60 });
  orientation.addEventListener("reading", () => {
    for (let index = 0; index < orientation.readings.timestamp.length; index++) {
      console.log(
        `Orientation Reading: \
        timestamp=${orientation.readings.timestamp[index]}, \
        [${orientation.readings.scalar[index]}, \
        ${orientation.readings.i[index]}, \
        ${orientation.readings.j[index]}, \
        ${orientation.readings.k[index]}]`
      );
    }
  });
  orientation.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 { Orientation } from "orientation";
import { display } from "display";

if (Orientation) {
  const orientation = new Orientation({ frequency: 1 });
  orientation.addEventListener("reading", () => {
    console.log(
      `Orientation Reading: \
      timestamp=${orientation.timestamp}, \
      [${orientation.quaternion[0]}, \
      ${orientation.quaternion[1]}, \
      ${orientation.quaternion[2]}, \
      ${orientation.quaternion[3]}]`
    );
  });
  display.addEventListener("change", () => {
    // Automatically stop the sensor when the screen is off to conserve battery
    display.on ? orientation.start() : orientation.stop();
  });
  orientation.start();
}

Orientation Best Practices

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

Don't forget to call orientation.stop() when you've finished using it.
Check if the sensor exists before using it.

Orientation in Action

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

Heart Rate Sensor Guide