FIT SDK for Go

The Flexible and Interoperable Data Transfer (FIT) protocol is a protocol developed by Garmin for storing and sharing data originating from sports, fitness, and health devices. When recording an activity using devices such as cycling computer, smartwatch, and similar devices, chances are the resulting file is often in FIT file format (*.fit).

More about FIT: developer.garmin.com/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 raw protocol messages; instead, they decode directly into predefined message structs grouped by common file types. 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):

Type	Local Number	Message	Field 1	Value 1	Units 1	Field 2	Value 2	Units 2	Field 3	Value 3	Units 3	Field 4	Value 4	Units 4	Field 5	Value 5	Units 5	Field 6	Value 6	Units 6
Definition	0	developer_data_id	developer_data_index	1		application_id	16		application_version	1
Data	0	developer_data_id	developer_data_index	1		application_id	<omitted>		application_version	40113
Definition	0	field_description	fit_base_type_id	1		developer_data_index	1		field_definition_number	1		field_name	13
Data	0	field_description	fit_base_type_id	7		developer_data_index	1		field_definition_number	5		field_name	device_model
Definition	0	field_description	fit_base_type_id	1		developer_data_index	1		field_definition_number	1		field_name	20
Data	0	field_description	fit_base_type_id	7		developer_data_index	1		field_definition_number	4		field_name	device_manufacturer
Data	0	field_description	fit_base_type_id	7		developer_data_index	1		field_definition_number	6		field_name	device_os_version
Data	0	field_description	fit_base_type_id	7		developer_data_index	1		field_definition_number	7		field_name	mobile_app_version
Definition	0	device_info	manufacturer	1		product	1		device_model	11		device_manufacturer	6		device_os_version	5		mobile_app_version	8
Data	0	device_info	manufacturer	265		product	101		device_model	iPhone14,4		device_manufacturer	apple		device_os_version	16.6		mobile_app_version	332.0.0

CLIs

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

1. fitactivity: Combines multiple FIT activity files into one continuous FIT activity (and conceal the start and end GPS positions for privacy). README.md
2. 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
3. fitprint: Generates comprehensive human-readable *.txt file containing details extracted from FIT files. README.md
4. 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:

1. Register Manufacturer Specific Messages at Runtime

   For those who prefer using this SDK as it is without need to generate their own custom SDK, we provide factory package as an abstraction to hold the profile messages. See Register at Runtime.

2. Generate Custom FIT SDK

   Please see Generate Custom FIT SDK

Benchmark

We do not aim to compete with anyone; rather, we have created this FIT SDK with the intention of providing an alternative. However, having a benchmark can show us how relevant we are to the world.

Here is a benchmark for decoding and encoding big_activity.fit using this FIT SDK in comparison to github.com/tormoder/fit, the long-standing Go library for decoding and encoding FIT files. See internal/cmd/benchfit/benchfit_test.go

cd internal/cmd/benchfit
go test -bench=. -benchmem

goos: darwin
goarch: amd64
pkg: benchfit
cpu: Intel(R) Core(TM) i5-5257U CPU @ 2.70GHz
BenchmarkDecode/muktihari/fit_raw-4  12    95655408 ns/op   77092784 B/op    100047 allocs/op
BenchmarkDecode/muktihari/fit-4      13    87700988 ns/op   52699547 B/op    101064 allocs/op
BenchmarkDecode/tormoder/fit-4       10   106331934 ns/op   84108932 B/op    700051 allocs/op
BenchmarkEncode/muktihari/fit_raw-4  15    75523944 ns/op     131522 B/op        14 allocs/op
BenchmarkEncode/muktihari/fit-4       8   147434340 ns/op   44139516 B/op    100018 allocs/op
BenchmarkEncode/tormoder/fit-4        1  1301732705 ns/op  101992544 B/op  12100312 allocs/op
PASS
ok      benchfit        10.958s

NOTE: The 1st on the list, "raw", means we decode the file into the original FIT protocol message structure (similar to the Official FIT SDK implementation in other languages). While the 2nd decodes messages to Activity File struct, which should be equivalent to what the 3rd does.

We decode slightly faster and encode significantly faster. We allocate far fewer objects on the heap and have a smaller memory footprint for both decoding and encoding.

Contributing

Please see CONTRIBUTING.md. Thank you, contributors!