README
¶
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 similiar devices, chances are the resulting file is often in FIT file format (*.fit). The FIT file is a binary file format known for its compact size, making it the preferred choice for manufacturers to use in their embedded devices. However, despite having gained widespread adoption, Garmin has not yet released an official SDK for Go, this is where this SDK comes in to bridge the gap, enabling Go developers to be able to interact with FIT file format.
More about FIT: developer.garmin.com/fit
This SDK is designed with efficiency in mind, but it places a higher priority on clarity, simplicity and extensibility.
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 provides some CLI programs to interact with FIT files that can be found in cmd folder.
fitactivity: Combines multiple FIT activity files into one continuous FIT activity (and conceal the start and end GPS positions for privacy). README.mdfitconv: Converts FIT file to a CSV file, allowing us to read the FIT file in a human-readable format. README.md
The 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 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:
-
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
factorypackage as an abstraction to hold the profile messages. For example, please see Register Manufacturer Specific Types & Messages at Runtime. -
Generate custom FIT SDK
Please see Generate Custom FIT SDK
Contributing
Please see CONTRIBUTING.md. Thank you, contributors!
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd provides CLI programs to work with FIT files.
|
Package cmd provides CLI programs to work with FIT files. |
|
fitconv/fitcsv
Package fitcsv provides the implementations of fit listener's interfaces that can listen to the events emitted by the decoder.
|
Package fitcsv provides the implementations of fit listener's interfaces that can listen to the events emitted by the decoder. |
|
Package decoder provides a handler to decode fit files.
|
Package decoder provides a handler to decode fit files. |
|
Package encoder provides a handler to encode data into fit file binary form.
|
Package encoder provides a handler to encode data into fit file binary form. |
|
Package factory contains predefined messages based on messages in [Profile.xlsx] provided in the Official Fit SDK.
|
Package factory contains predefined messages based on messages in [Profile.xlsx] provided in the Official Fit SDK. |
|
internal
|
|
|
cmd/fitgen/pkg/strutil
Package strutil is used only for naming package, variable, etc inside the go template.
|
Package strutil is used only for naming package, variable, etc inside the go template. |
|
Package kit provides helpers for decoding and encoding as well as type conversion.
|
Package kit provides helpers for decoding and encoding as well as type conversion. |
|
hash
Package hash provides interface for hash16 functions as an additional interface to the existing Go stdlib's Hash32 and Hash64.
|
Package hash provides interface for hash16 functions as an additional interface to the existing Go stdlib's Hash32 and Hash64. |
|
hash/crc16
Package crc16 implements the 16-bit cyclic redundancy check, or CRC-16, checksum.
|
Package crc16 implements the 16-bit cyclic redundancy check, or CRC-16, checksum. |
|
Package listener defines interface contracts that can be added on a decoder to receive message and message definition as soon as it is decoded.
|
Package listener defines interface contracts that can be added on a decoder to receive message and message definition as soon as it is decoded. |
|
Package profile defines an abstraction layer of types used in the Fit file above the base types (primitive-types) such as sint, uint, etc.
|
Package profile defines an abstraction layer of types used in the Fit file above the base types (primitive-types) such as sint, uint, etc. |
|
basetype
Package basetype defines the base of all types used in Fit.
|
Package basetype defines the base of all types used in Fit. |
|
filedef
Package filedef contains the implementation of known common file types and its listener to convert decoded FIT file into the desired common file type as soon as the message is decoded.
|
Package filedef contains the implementation of known common file types and its listener to convert decoded FIT file into the desired common file type as soon as the message is decoded. |
|
untyped/fieldnum
Package fieldnum contains untyped constants for greater flexibility, intended to simplify code typing when creating messages and fields using the factory and reduce human error.
|
Package fieldnum contains untyped constants for greater flexibility, intended to simplify code typing when creating messages and fields using the factory and reduce human error. |
|
untyped/mesgnum
Package mesgnum contains untyped constants for greater flexibility, intended to simplify code typing when creating messages and fields using the factory and reduce human error.
|
Package mesgnum contains untyped constants for greater flexibility, intended to simplify code typing when creating messages and fields using the factory and reduce human error. |
|
Package proto defines the abstraction for Fit Protocol.
|
Package proto defines the abstraction for Fit Protocol. |