File System Guide
chevron down
back search icon cancel search
 
 

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.

File system operations are relative to your app's private data directory, /private/data/. For example the path file.txt refers to /private/data/file.txt. This private directory is also where files transferred using File Transfer are held once received by your application. This is the only location your app can write to; all locations outside of /private/data/ are read-only.

Files within your application's resources/ folder can be read by specifying the absolute path /mnt/assets/resources/.

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.

Note: PNG images files which are contained in your application's resources folder are automatically converted into a hardware optimized TXI format. The files are renamed during the build process to your-filename.png.txi.

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, written in raw bytes.

Listing Files

If you want to list the contents of the /private/data/ folder, you can use the listDirSync() method.

import { listDirSync } from "fs";
const listDir = listDirSync("/private/data");
while((dirIter = listDir.next()) && !dirIter.done) {
  console.log(dirIter.value);
}

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 Exists

The File System API provides the existsSync() method to check if a file exists before accessing it.

import * as fs from "fs";
if (fs.existsSync("/private/data/my-file.txt")) {
  console.log("file exists!");
}

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");
previous
Design Guidelines
Geolocation Guide
next