Fitbit

Simulator on Linux

https://appdb.winehq.org/objectManager.php?sClass=version&iId=36675

https://github.com/bingtimren/fitbit-sim-starter

Developer Bridge

Wifi will not connect if device has less than 25% battery

Folders

/app/

/common/

/companion/

/resources/ (gui, css, images, etc.)

/settings/ (jsx, tsx)

Size

application <= 10m

file space <= 15m

Use Clock API and tick events instead of setInterval() to reduce battery impact

Messaging API

• synchronous, socket based (subset of WebSocket API)
• while app is running on device
• identical in device and companion API
• CBOR encoded
• message <= 1027 bytes (MAX_MESSAGE_SIZE)
• do not overflow buffer

File Transfer

• asynchronous
• companion <=> device (even app not running)
• automatic handshake & retry, transparent to developer
• outbox queue - can queue one or more files, if queue a file with same filename, will overwrite
• device receiving
  • process files upon start (may receive file when app not running)
  • listen for incoming file transfers, mvoe files from staging folder to application folder by calling nextFile() on index
• companion receiving
  • process files upon start
  • listen for incoming file transfers
  • call pop() on inbox

Lifecycle

• device launch => companion launch (peerAppLaunched)
• subscribed events => companion woken (with reason)
  • periodical (not implemented in simulator)
  • location change (5km)
  • setting change (settingsStorage)

Each app has own private area

/private/data is only place writable & default dir

/mnt/assets/resources - application's resources/ are mounted readonly (PNG converted to TXI)

All methods are synchronous

Recommended approach:

• Detect capability, rather than code for specific device model name
• Use file naming convention in resources folder to target different device; when referencing in code just use the base filename

Some APIs needs to request permission first before usage

Interface: JSX with restricted tags

• Link
• Text
• TextInput
• TextImageRow - to be used in Select
• Button
• Toggle
• ColorSelect
• Select - single / multiple select
• Additive List - handles add/re-order/delete of items
• Section
• List(Until June 2, 2020 still not implemented)
• Slider
• OAuth Button
• Strava Login Button
• Image Picker

Persistence

• settingsStorage of type LiveStorage
• read/writable by companion & settings view
• use "settingsKey" to link UI input with setting key
• companion should listen to setting change event & examine awoke reason to handle setting change and send setting to device

Settings API (used by JSX)

• storage management
  • automatic - use settingKey
  • manually -
    • value={props.settings.color}
    • onChange={value => props.settingsStorage.setItem('color', value)}

Currently seems there's no "official" way but https://github.com/SergioMorchon/fitbit-sdk-types

Coordination:

• pixels, percentage, combined (30%+15) [no space in combined expression]
• some elements (<svg>) creates new coordination context for elements encapsulated inside

Elements:

• line
• rect
• circle
• image
• text
• textarea
• dynamic-textarea
• arc
• defs : to include <symbol> and stylesheet definitions
• section - like <svg> establishes a new coordination system, but lighter (has less attributes), only position and size)
• g - be used to translate (move), rotate, scale all elements inside
• gradientRect - gradient, lineral, radial, bilinear
• mask - creates a mask for visual effects
• symbol - define reuseable elements (use id in symbol and children to identify symbol & child)
  • use - use a symbol, (href to refer the id)
  • set - to modify any attribute (use href & attributeName to identify)

API Reference: https://dev.fitbit.com/build/reference/device-api/document/

CSS

Multi-view SVG

import document from "document";

document.replaceSync("./resources/another-view.gui");

This has performance benefits as well as better code organisation.

See https://dev.fitbit.com/blog/2019-10-29-announcing-fitbit-os-sdk-4.0/

Physical Buttons

https://dev.fitbit.com/build/guides/user-interface/javascript/#using-the-physical-buttons

Prevent default action of physical buttons

https://community.fitbit.com/t5/SDK-Development/Physical-Button-Exit-App/td-p/2375320

import document from "document";

import { me } from "appbit";

document.onkeypress = function(e) {

  console.log("Key pressed: " + e.key);

  e.preventDefault();

    if (e.key==="up") {

      console.log("trapped");

      me.exit();

  }

Event

See https://dev.fitbit.com/build/guides/user-interface/javascript/#events

Note: when one component (rect etc.) is covered by another, click event is not passed to the under laying component, if the covering component is merely hidden (.style.visibility = "hidden"; // hidden). To expose the under laying component, set the covering component's display attribute (.style.display = "none";)

API Reference

https://dev.fitbit.com/build/reference/device-api/

Cryptography API

App Cluster Storage

All apps by same developer can share app cluster storage by same ID.