A simple and useful parser for decoding/encoding FIT files.
· Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Overview
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

A simple and useful Node.js tool written in C++/JS using Node-API for decoding/encoding FIT files.

Getting Started

To compile the add-on you need a toolchain that compile C and C++ code into binaries.

Prerequisites

Node.js

The NodeJS ecosystem is mandatory and can be installed downloading the binaries for your architecture, here.

node-gyp

After developing process, to correctly deploying the addon, you need node-gyp build system installed. You can find all the information needed, here.

---

Linux

For Linux, a proper C/C++ compiler toolchain, like GCC.

---

macOS

For macOS, install XCode Command Line Tools which will install clang, clang++, and make:

xcode-select --install

---

Windows

For Windows the build tools system is now shipped with Node.js.

Installation

To install the others development packages, simply type into the terminal:

npm install

(back to top)

Project structure

The core of the addon resides within the src folder and it is structured like below:

• configuration - utility functions and defines.
• decode - C++ class to decode FIT file.
• encode - C++ class to encode FIT file.
• fit - source code of the FIT SDK.
• nlohmann a wonderful C++ class for handle JSON objects. More information at nlohmann/json.
• worker - the async N-API C++ class for schedule the parsing process to the background avoiding Node's main loop.
• fit_parser.cpp/fit_parser.hpp - N-API wrapper class that expose all the addon functionalities.
• main.cpp - The entry point of the module.

Note: Files in the fit folder are sourced from the FIT SDK. If you have custom generated messages, you'll need to replace the files within this folder with your own.

Build

After the installation step you can build the addon module with the following command:

npm run build

The command will produce the binary file for the current platform inside binary folder.

Other commands

• To build and then run the test, use:

  npm run build+
  

• To rebuild(clean + build):

  npm run rebuild
  

• To rebuild and then run the test:

  npm run rebuild+
  

• To simply clean:

  npm run clean
  

(back to top)

Pre/Post Scritps

Contents of the scripts folder:

• post.js - for moving the compiled module in the convenient folder binary.

Usage

Include the module

const fitModule = require("<your path>/FITParser.node");

Decode from file path

fitModule.decodeFile("filepath", [options], (err, result) => ...)

Params:

Name	Mandatory	Type	Descriptions
filepath		String	filepath of the FIT file to decode
options		JSON array	see decode options
callback		Function	the callback function

Callback params:

Name	Type	Descriptions
err	JSON string	the JSON string representing error. Is composed by a message and a code
result	JSON string	the JSON string representing the FIT file

Decode from buffer

fitModule.decodeBuffer(buffer, [options], (err, result) => ...)

Params:

Name	Mandatory	Type	Descriptions
buffer		Buffer	buffer object of the FIT file to decode
options		JSON array	see decode options
callback		Function	the callback function

Callback params:

Name	Type	Descriptions
err	JSON string	the JSON string representing error. Is composed by a message and a code
result	JSON string	the JSON string representing the FIT file

---

Decode options

All the available decode options are listed below:

Option name	Type	Default	Description
skipHeaders	bool	false	if true, messages's header is skipped
force	bool	false	if true, the decode process continue even if an incomplete stream is found
rawValues	bool	false	if true, all fields will be produced with the .FIT internal representation: {value:..., offset:..., scale:...,}
include	Array of numbers	undefined	An array of message's id1 representing only the messages that will be included in the decoded result
exclude	Array of numbers	undefined	An array of message's id1 representing the messages to be excluded from decoded result
version	int	2	Protocol version of the FIT library

id¹: All message ids can be retrieved from property defines of fitModule object like below:

fitModule.defines.FILE_ID; // = 0
fitModule.defines.FILE_CREATOR; // = 1
...

The complete list is visible in the header fit_profile.hpp.

Async/Await

All the decode/encode functions above, have the corresponding awaitable version using the suffix Async:

try {
  const result = await fitModule.decodeBufferAsync(...);
  const fit = JSON.parse(result);
  ...
} catch (err) {
  ...
}

In folder example there are different types of FIT files you can choose to test the module.

Encode JSON string

fitModule.encodeJsonToFile("filepath", jsonString, [options], (err, result) => ...)

Params:

Name	Mandatory	Type	Descriptions
filepath		String	representing the path where the file will be saved
jsonString		String	stringified JSON object represent the .FIT file to be written
options		JSON array	see encode options
callback		Function	the callback function

Callback params:

Name	Type	Descriptions
err	JSON string	the JSON string representing error. Is composed by a message and a code
info	JSON array	a JSON array containing warnings1(JSON object composed by message/code)

Warnings¹: array not empty, means there is something in fitObj that is not ok but the .fit file will still be produced.

Encode buffer

fitModule.encodeBuffer("filepath", buffer, [options], (err, result) => ...)

Params:

Name	Mandatory	Type	Descriptions
filepath		String	representing the path where the file will be saved
buffer		Buffer	the Buffer object of the FIT file to encode
options		JSON array	see encode options
callback		Function	the callback function

Callback params:

Name	Type	Descriptions
err	JSON string	the JSON string representing error. Is composed by a message and a code
info	JSON array	a JSON array containing warnings1 object(JSON object composed by message/code)

Warnings¹: array not empty, means there is something in fitObj that is not ok but the .fit file will still be produced.

Encode options

All the available decode options are listed below:

Option name	Type	Default	Description
exclude	Array of numbers	undefined	An array of message's id1 representing the messages to be skipped from encoding
version	int	2	Protocol version of the FIT library

id¹: All message ids can be retrieved from property defines of fitModule object like below:

fitModule.defines.FILE_ID; // = 0
fitModule.defines.FILE_CREATOR; // = 1
...

The complete list is visible in the header fit_profile.hpp.

Exported Defines

To access the defines

fitModule.defines.VERSION;
fitModule.defines.FIT_BASE_TYPES;
fitModule.defines.FIT_FILE_TYPES;
fitModule.defines.FIT_MESG_NUM;
fitModule.defines.SYSTEM_TIME_OFFSET_SEC;

  #define VERSION <current version>
  #define SYSTEM_TIME_OFFSET_SEC 631065600
  #define LEFT_RIGHT_BALANCE_100 100.0

  #define FIT_ENUM_INVALID            ((FIT_ENUM)0xFF)
  #define FIT_SINT8_INVALID           ((FIT_SINT8)0x7F)
  #define FIT_UINT8_INVALID           ((FIT_UINT8)0xFF)
  #define FIT_SINT16_INVALID          ((FIT_SINT16)0x7FFF)
  #define FIT_UINT16_INVALID   ((FIT_UINT16)0xFFFF)
  #define FIT_SINT32_INVALID   ((FIT_SINT32)0x7FFFFFFF)
  #define FIT_UINT32_INVALID   ((FIT_UINT32)0xFFFFFFFF)
  #define FIT_STRING_INVALID   ((FIT_STRING)0x00)
  #define FIT_FLOAT32_INVALID   ((FIT_FLOAT32)*((FIT_FLOAT32*)::fit::baseTypeInvalids[FIT_BASE_TYPE_FLOAT32 & FIT_BASE_TYPE_NUM_MASK]))
  #define FIT_FLOAT64_INVALID   ((FIT_FLOAT64)*((FIT_FLOAT64*)::fit::baseTypeInvalids[FIT_BASE_TYPE_FLOAT64 & FIT_BASE_TYPE_NUM_MASK]))
  #define FIT_UINT8Z_INVALID   ((FIT_UINT8Z)0x00)
  #define FIT_UINT16Z_INVALID   ((FIT_UINT16Z)0x0000)
  #define FIT_UINT32Z_INVALID   ((FIT_UINT32Z)0x00000000)
  #define FIT_BYTE_INVALID   ((FIT_BYTE)0xFF)
  #define FIT_SINT64_INVALID   ((FIT_SINT64)0x7FFFFFFFFFFFFFFFL)
  #define FIT_UINT64_INVALID   ((FIT_UINT64)0xFFFFFFFFFFFFFFFFL)
  #define FIT_UINT64Z_INVALID   ((FIT_UINT64Z)0x0000000000000000L)

  #define FIT_FILE_INVALID     0xFF
  #define FIT_FILE_DEVICE      ((FIT_FILE)1)
  #define FIT_FILE_SETTINGS    ((FIT_FILE)2)
  #define FIT_FILE_SPORT       ((FIT_FILE)3)
  #define FIT_FILE_ACTIVITY    ((FIT_FILE)4)
  #define FIT_FILE_WORKOUT     ((FIT_FILE)5)
  #define FIT_FILE_COURSE      ((FIT_FILE)6)
  #define FIT_FILE_SCHEDULES   ((FIT_FILE)7)
  #define FIT_FILE_WEIGHT      ((FIT_FILE)9)
  #define FIT_FILE_TOTALS      ((FIT_FILE)10)
  #define FIT_FILE_GOALS       ((FIT_FILE)11)
  #define FIT_FILE_BLOOD_PRESSURE ((FIT_FILE)14)
  #define FIT_FILE_MONITORING_A   ((FIT_FILE)15)
  #define FIT_FILE_ACTIVITY_SUMMARY   ((FIT_FILE)20)
  #define FIT_FILE_MONITORING_DAILY   ((FIT_FILE)28)
  #define FIT_FILE_MONITORING_B       ((FIT_FILE)32)
  #define FIT_FILE_SEGMENT            ((FIT_FILE)34)
  #define FIT_FILE_SEGMENT_LIST       ((FIT_FILE)35)
  #define FIT_FILE_EXD_CONFIGURATION  ((FIT_FILE)40)
  #define FIT_FILE_MFG_RANGE_MIN      ((FIT_FILE)0xF7)
  #define FIT_FILE_MFG_RANGE_MAX      ((FIT_FILE)0xFE)

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Attributions

All logo/icons of the project are provided by Icon8.