Announcing Fitbit OS 2.2 - The Versioning!
chevron down

Announcing Fitbit OS 2.2 - The Versioning!

Fitbit OS 2.2 for Developers

The latest firmware update for the Fitbit Ionic and Versa smartwatches continues the evolution of Fitbit OS, and provides some great new developer functionality. Welcome to SDK 2.0!

What's New

We couldn't resist highlighting these general firmware updates which positively affect developers:

  • Improved BLE connection reliability
  • WiFi performance improvement
  • Site synchronization won't interrupt mobile communications

While everyone benefits from the general updates, this release also contains the following new features and updates especially for developers:

  • SDK Versioning
  • App Timeout API
  • Body Presence API
  • Sensor Batching
  • File Directory Listings
  • Cryptographic Digest

We've updated the reference documentation to incorporate these updates, but let's take a look at each of the new features and enhancements in more detail.

SDK Versioning

We've now reached a critical point in the evolution of the Fitbit OS platform where we needed to prevent any changes to the SDK from breaking existing applications and clock faces. To meet this important goal, we've implemented versioning within the SDK. We're now officially at SDK 2.0.

Versioning allows us to introduce new APIs, alter existing APIs, and (if necessary) deprecate old APIs, all without worrying about breaking API compatibility for existing applications.

All existing applications and clock faces are now considered SDK version 1.0, and moving forward developers will be able to target specific versions of the SDK when building their projects in order to access new APIs.

We've already updated the Fitbit App Gallery so that application installations and updates will only be installed on devices with a firmware compatible with the targeted SDK version. Because the Fitbit Gallery App Manager allows you to have multiple published builds, devices with firmware that is only compatible with SDK 1.0 will continue to work with the existing builds, and updated devices will be able to utilize the latest and greatest updates.

Developers can still publish an update to an existing SDK 1.0 app, provided it correctly targets that version of the SDK. If you have never published an SDK version 1.0 version of your app, users on old firmware will still see your SDK 2.0 version, but they will be informed to update their firmware before the app can be installed. Pretty neat, eh?

Fitbit Studio has been updated to allow developers to select the SDK version number within the package.json settings. Users of the new Fitbit Command Line Tools can already update their projects to SDK version 2.0 by incrementing the sdk major version number manually in their package.json file, then running npm install within their project folder.

App Timeout API

All apps targeting SDK 2.0 will now automatically terminate after 2 minutes of inactivity (after the display turns off). Users will now see their clock after waking the device again. This change was added to improve usability, and potentially reduce battery usage of unwanted apps.

For applications which need to override this new default behavior, we have provided the App Timeout API. This new API allows developers to query the current state of the timeout, and also disable it, or enable it again. Please consider user's battery life and use this API sparingly.

// Disable app timeout
import { me } from "appbit";

if (me.appTimeoutEnabled) {
 console.log("Timeout is enabled");

me.appTimeoutEnabled = false; // Disable timeout

Body Presence API

While its name may sound a bit unusual at first, the new Body Presence API can be used to detect if a human body is touching the device. A simpler analogy is "off-wrist" detection. This API essentially provides an event which occurs when user puts on, or takes off their Fitbit OS device.

It's the same underlying functionality which is used to disable Fitbit Pay when the user removes the device from their wrist, and should only take a matter of seconds to trigger.

Common use cases for this API would be stopping sensor readings, or even simulating a low power mode by reducing screen updates to preserve battery when the device is unused.

// Basic On/Off Wrist Detection
import { BodyPresenceSensor } from "body-presence";

let body = new BodyPresenceSensor();
body.onreading = () => {
 console.log(`The watch is ${body.present ? "" : "not"} on the user's body.`);

Sensor Batching!

SDK 2.0 heralds the proud return of batched sensor readings! This new implementation provides each property as its own array within the batch, it's more efficient than the original implementation, and is just as simple to work with.

To utilize batching, developers just need to specify the batch size when initializing the sensor, then access each sensor property array within the batch.

// Accelerometer, with batching

let acc = new Accelerometer({ frequency: 30, batch: 60 });
acc.onreading = () => {
 for (let i = 0; i < acc.readings.timestamp.length; i++) {
     `Accelerometer Reading: timestamp=${acc.readings.timestamp[i]},
       [${acc.readings.x[i]}, ${acc.readings.y[i]},

File Directory Listings

Have you ever wondered which files exist within your private/data folder? Have you transferred some files with the File Transfer API and forgotten to persist the filenames? Well thanks to the new listDirSync() method added to the File System API in SDK 2.0, developers can now get a listing of the folder contents.

// Directory file listing
import { listDirSync } from "fs";

const listDir = listDirSync("/private/data");
while((dirIter = && !dirIter.done) {

Cryptographic Digest

Without delving deep diving into the realm of cryptography here, SDK 2.0 now provides a SHA-256 digest() method. This will generate an irreversible and unique fixed size hash from source data. It has specifically been optimized for performance on Fitbit OS, and will be substantially faster than the JavaScript based solutions that some developers were previously struggling to use.

// SHA-256 hash example
import * as Crypto from "crypto";

const buffer = new ArrayBuffer(3);
const bytes = new Uint8Array(buffer);
bytes[0] = 1;
bytes[1] = 2;
bytes[2] = 3;

Crypto.subtle.digest("SHA-256", buffer).then(hash => {

But Wait, There's More

As if all this wasn't enough, we've got even more greatness for you:

  • JavaScript bundle minification - with working sourcemapping in Fitbit Studio and the Command Line Interface in SDK 1.0 and 2.0.
  • Transparent images are now 25% smaller due to RGBA6666 encoding.
  • The Geolocation API on Fitbit Versa now automatically falls back to Connected GPS mode.
  • The JPEG module now correctly throws an error when an image decode fails.
  • Vertical text alignment has been fixed, you may need to adjust any vertically aligned textarea and text elements when switching to SDK version 2.0.

Until Next Time

Follow @fitbitdev on Twitter, and join our Fitbit Community Forum to keep in touch, 24/7. Curious to see the amazing work Fitbit Developers have done so far? Keep tabs on the #Made4Fitbit Twitter hashtag.