File System Guide

Overview

The File System API allows developers to read and write files on the Fitbit device. Each application has its own private area of the device file system, so files cannot be shared amongst different applications.

In order to read or write to a file within your application's /resources folder, you need to specify the full path /mnt/assets/resources/. Files which have been transferred using File Transfer are held within /private/data/.

All of the methods within the File System API are synchronous, meaning that the each call prevents subsequent code from executing until it has finished. You can read more about synchronous JavaScript here.

File Types

The API is capable of working with the following types of files:

  • ASCII - A text file in which each byte represents one character according to the ASCII code.
  • UTF-8 - A text file where character encoding is capable of encoding all possible Unicode code points.
  • JSON - A text file, written with JavaScript object notation.
  • CBOR - A binary file, containing the Concise Binary Object Representation (CBOR) data format.
  • Binary - A binary file

Writing Files

In order to write data to a file, we can use the writeFileSync() method, which accepts a filename, the file data, and the type of encoding.

Writing an ASCII File

Create a string, then write that into the specified filename with ASCII encoding.

import * as fs from "fs";
let ascii_data = "Lorem ipsum dolor sit amet, sodales morbi, vestibulum vel.";
fs.writeFileSync("ascii.txt", ascii_data, "ascii");

Writing a UTF-8 File

Create a string, then write that into the specified filename with UTF-8 encoding.

import * as fs from "fs";
let utf8_data = "JavaScript is da best 😍";
fs.writeFileSync("utf8.txt", utf8_data, "utf-8");

Writing a JSON File

Create a JavaScript object, then write that into the specified filename as a JSON string.

import * as fs from "fs";
let json_data = {
  "_id": "58fe4408726f862be04fa0f2",
  "guid": "189fbd1a-968e-48f3-9311-247ca188e907",
  "registered": "2017-08-21T20:00:00 GMT-07:00",
  "latitude": -2.932463,
  "longitude": 151.797305,
};
fs.writeFileSync("json.txt", json_data, "json");

Writing a CBOR File

Create a JavaScript object, then write that into the specified filename using CBOR encoding. When using CBOR encoding, the resulting file size will be smaller than a JSON file.

import * as fs from "fs";
let json_data = {
  "_id": "58fe4408726f862be04fa0f2",
  "guid": "189fbd1a-968e-48f3-9311-247ca188e907",
  "registered": "2017-08-21T20:00:00 GMT-07:00",
  "latitude": -2.932463,
  "longitude": 151.797305,
};
fs.writeFileSync("cbor.txt", json_data, "cbor");

Writing a Binary File

In the following example, the openSync() method is used to open a file for writing (w+), then an ArrayBuffer containing a Uint8Array of 3 bytes is written to the file using the writeFileSync() method.

A file with the specified name is either created if it does not exist, or truncated if it does.

import * as fs from "fs";
file = fs.openSync("filename.bin", "w+");
buffer = new ArrayBuffer(3);
bytes = new Uint8Array(buffer);
bytes[0] = 1;
bytes[1] = 2;
bytes[2] = 3;
fs.writeSync(file, buffer);
fs.closeSync(file);

Reading Files

In order to read data from a file, we can use the readFileSync() method, which accepts a filename, and the type of encoding, then returns the file data.

Reading an ASCII File

Read the contents of the specified ASCII encoded file.

import * as fs from "fs";
let ascii_read = fs.readFileSync("ascii.txt", "ascii");
console.log("ASCII Data: " + ascii_read);

Reading a UTF-8 File

Read the contents of the specified UTF-8 encoded file.

import * as fs from "fs";
let utf8_read = fs.readFileSync("utf8.txt", "utf-8");
console.log("UTF-8 Data: " + utf8_read);

Reading a JSON File

Read the contents of the specified JSON file into a JavaScript object.

When reading a valid JSON file, the string is automatically parsed into an object, so the object"s properties can be accessed directly.

import * as fs from "fs";
let json_object  = fs.readFileSync("json.txt", "json");
console.log("JSON guid: " + json_object.guid);

Reading a CBOR File

Read the contents of the specified CBOR encoded file into a JavaScript object.

When reading a valid CBOR file, the string is automatically parsed into an object, so the object"s properties can be accessed directly.

import * as fs from "fs";
let json_object  = fs.readFileSync("cbor.txt", "cbor");
console.log("Object guid: " + json_object.guid);

Reading a Binary File

In the following example, the openSync() method is used to open a file for reading (r), then the readSync() method is used to read 3 bytes from the file into an ArrayBuffer. The buffer is then used to construct a Uint8Array of the 3 bytes. After the bytes have been printed to the log, the file is closed using closeSync().

import * as fs from "fs";
let file = fs.openSync("filename.bin", "r");
let buffer = new ArrayBuffer(3);
fs.readSync(file, buffer, 0, 3, 0);
let bytes = new Uint8Array(buffer);
console.log("bytes:", bytes[0], bytes[1], bytes[2]);
fs.closeSync(file);

File Details

The File System API provides the statSync() method to allow developers to query the file size and last modified date for each file.

import * as fs from "fs";
let stats = fs.statSync("filename.txt");
if (stats) {
  console.log("File size: " + stats.size + " bytes");
  console.log("Last modified: " + stats.mtime);
}

Deleting Files

In order to delete a file from the file system, we use the unlinkSync() method, passing the filename to delete.

import * as fs from "fs";
fs.unlinkSync("filename.txt");

Renaming Files

In order to rename a file in the file system, we use the renameSync() method, passing the current filename, and the desired new filename.

import * as fs from "fs";
fs.renameSync("filename.txt", "newfilename.txt");