FIT SDK for Go

This project hosts the Go implementation for The Flexible and Interoperable Data Transfer (FIT) Protocol, which is a protocol developed by Garmin for storing and sharing data originating from sports, fitness, and health devices. Activities recorded using devices such as smartwatch and cycling computer are now mostly in a FIT file format (*.fit).

Motivation

The FIT protocol, known for its compact size as a binary file format, is the preferred choice for manufacturers to use in their embedded devices. However, despite its widespread adoption, Garmin has not yet released an official SDK for Go, and existing third-party libraries for decoding and encoding the FIT protocol lack the semantics of the official SDK.

One of the key semantics they are missing is the ability for users to retrieve protocol messages. Instead, these messages are unmarshalled directly into predefined structures based on common file types. This results in the loss of the message arrival order, inability to handle 'unknown messages', and limits the ability to extend certain functionalities. Furthermore, existing third-party libraries do not seem to fully support FIT Protocol V2, and their ability to produce variant options of the FIT protocol is limited. For instance, creating FIT files with compressed timestamps or FIT files with multiple local message types, which significantly reduces the resulting FIT files' size, is missing.

Without diminishing respect for the existing libraries created nearly a decade ago, at a time when the capabilities of Go were limited, we believe a new approach is necessary. This is where this SDK comes in, bridging the gap and enabling Go developers to seamlessly interact with the FIT protocol.

Usage

Please see Usage.

Protocol Version 2.0 is supported

Version 2.0 introduced Developer Fields as a way to add custom data fields to existing messages. We strives to support Developer Fields and carefully thought about how to implement it since the inception of the SDK. While this may still need to be battle-tested to ensure correctness, this is generally work and usable.

Here is the sample of what Developer Fields would look like in a .fit that have been converted to .csv by fitconv. The device_info message has some Developer Fields defined in field_description (the ones that are being bold):

<table class="table table-bordered table-hover table-condensed"> <thead> <tr> <th>Type</th> <th>Local Number</th> <th>Message</th> <th>Field 1</th> <th>Value 1</th> <th>Units 1</th> <th>Field 2</th> <th>Value 2</th> <th>Units 2</th> <th>Field 3</th> <th>Value 3</th> <th>Units 3</th> <th>Field 4</th> <th>Value 4</th> <th>Units 4</th> <th>Field 5</th> <th>Value 5</th> <th>Units 5</th> <th>Field 6</th> <th>Value 6</th> <th>Units 6</th> </tr> </thead> <tbody> <tr> <td>Definition</td> <td>0</td> <td>developer_data_id</td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>application_id</td> <td>16</td> <td> </td> <td>application_version</td> <td>1</td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Data</td> <td>0</td> <td>developer_data_id</td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>application_id</td> <td><omitted></td> <td> </td> <td>application_version</td> <td>40113</td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Definition</td> <td>0</td> <td>field_description</td> <td>fit_base_type_id</td> <td>1</td> <td> </td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>field_definition_number</td> <td>1</td> <td></td> <td>field_name</td> <td>13</td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Data</td> <td>0</td> <td>field_description</td> <td>fit_base_type_id</td> <td>7</td> <td> </td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>field_definition_number</td> <td>5</td> <td></td> <td>field_name</td> <td><strong>device_model</strong></td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Definition</td> <td>0</td> <td>field_description</td> <td>fit_base_type_id</td> <td>1</td> <td> </td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>field_definition_number</td> <td>1</td> <td></td> <td>field_name</td> <td>20</td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Data</td> <td>0</td> <td>field_description</td> <td>fit_base_type_id</td> <td>7</td> <td> </td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>field_definition_number</td> <td>4</td> <td></td> <td>field_name</td> <td><strong>device_manufacturer</strong></td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Data</td> <td>0</td> <td>field_description</td> <td>fit_base_type_id</td> <td>7</td> <td> </td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>field_definition_number</td> <td>6</td> <td></td> <td>field_name</td> <td><strong>device_os_version</strong></td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Data</td> <td>0</td> <td>field_description</td> <td>fit_base_type_id</td> <td>7</td> <td> </td> <td>developer_data_index</td> <td>1</td> <td> </td> <td>field_definition_number</td> <td>7</td> <td></td> <td>field_name</td> <td><strong>mobile_app_version</strong></td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <td>Definition</td> <td>0</td> <td>device_info</td> <td>manufacturer</td> <td>1</td> <td> </td> <td>product</td> <td>1</td> <td> </td> <td>device_model</td> <td>11</td> <td></td> <td>device_manufacturer</td> <td>6</td> <td> </td> <td>device_os_version</td> <td>5</td> <td></td> <td>mobile_app_version</td> <td>8</td> <td> </td> </tr> <tr> <td>Data</td> <td>0</td> <td>device_info</td> <td>manufacturer</td> <td>265</td> <td> </td> <td>product</td> <td>101</td> <td> </td> <td><strong>device_model</strong></td> <td><strong>iPhone14,4</strong></td> <td> </td> <td><strong>device_manufacturer</strong></td> <td><strong>apple</strong></td> <td> </td> <td><strong>device_os_version</strong></td> <td><strong>16</strong>.6</td> <td> </td> <td><strong>mobile_app_version</strong></td> <td><strong>332.0.0</strong></td> <td> </td> </tr> </tbody> </table>

CLIs

We provide some CLI programs to interact with FIT files that can be found in cmd folder.

fitactivity: A program to manage FIT activity files, including combining multiple FIT activity files into a single continuous activity, concealing start and end GPS positions for privacy, and reducing or removing messages. README.md
fitconv: Converts FIT files to CSV format, enabling us to read the FIT data in a human-readable format. Conversely, it also converts CSV files back to FIT format, enabling us to create or edit FIT files in CSV form. The programs is designed to work seamlessly with CSVs produced by the Official FIT SDK's FitCSVTool.jar. README.md
fitprint: Generates comprehensive human-readable *.txt file containing details extracted from FIT files. README.md
fitdump: Dumps the FIT file(s) into segmented bytes in a *.txt file format. README.md

Some programs are automatically built during release; for Linux, Windows, and macOS platforms. They are available for download in Release's Assets.

Custom FIT SDK

A FIT file may contain manufacturer specific messages (Product Profile) that are not defined in Global Profile (Profile.xlsx) since it's specific to a manufacturer (other manufacturers may have different meaning for that messages)

To be able to decode or create the manufacturer specific messages, we provide options to pick based on your need:

Fit

Install / Use