Introduction: The Challenge of Undocumented FIT File Data
Decoding all the data within Garmin’s FIT files can be a challenge due to the presence of undocumented messages, fields, and values. Garmin developed the FIT file format to store data on its devices, including activity data, courses, workouts, monitoring data, goals, and more. While much of this data is viewable in the Garmin Connect app or website, and activities can often be exported to FIT format by other brands and imported into apps like Strava, there are reasons to develop custom applications. These reasons include accessing data not shown in standard apps, creating personalized data visualizations, or performing more in-depth analysis.
The Garmin FIT SDK: An Incomplete Resource
To aid developers, Garmin provides an SDK (available on their developer website) with tools to extract information from FIT files in various programming languages. However, this SDK isn’t exhaustive, meaning not all information within FIT files can be accessed through it.
FIT Files: Messages, Fields, and the Profile Spreadsheet
A FIT file is a compact, binary format organizing information into messages and fields. For example, a “lap” message contains summary information for each lap, and a “device info” message details the devices and sensors used. Each message comprises several fields, such as start time and total elapsed time in a lap message.
Messages and fields are identified by numerical codes. Also the value of a field may be a numerical code. For example, an “event” field may have value 0 for a timer event, 9 for a lap event, 22 for a battery low alert, etc.
The SDK includes a spreadsheet, profile.xlsx, which documents the meaning of many of these numbers.
The Problem: Undocumented Elements
When working with FIT files, you’ll quickly encounter undocumented numbers. You might decode a message but not know its purpose, or find undocumented fields within documented messages, leaving their meaning unclear. Even when a field’s purpose is known, it can contain undocumented values. For instance, an “event” field might have an undocumented value like 39, so you don’t know what type of event it is.
Strategies for Deciphering Undocumented Data
Several methods can be used to decipher these undocumented elements. One crucial tool is an application like FIT File Viewer, which displays all messages, fields, and values within a FIT file, including those not officially documented (accessible via developer mode in FIT File Viewer).
A practical approach is to record an activity and then compare the values in the FIT file with the information presented in the Connect app/website or your device’s app. If you find a match in a field labeled like “field {number}” (where {number} is the specific field’s numerical identifier), it suggests this is the corresponding data point. Repeating this process with different activities can help confirm your findings.
Another useful technique is to change settings on your device one at a time and observe the resulting changes in the FIT file. This helps isolate the impact of each setting modification.
Good to know: if you go to https://www.fitfileviewer.com/develop, you have some extra features: you will see the fields for which I have already figured out the type, but not the meaning yet, and there is a button to log the undocumented fields (if any) in the debugger console: the field definition number, base type, size and value in the first row.
A Community-Driven Resource: Undocumented Data for FIT File Viewer
Through these investigations and the shared knowledge of others, I have compiled a list of undocumented messages, fields, and values specifically for use in FIT File Viewer. This list follows the same format as the profile.xlsx file in the FIT SDK.
I am now sharing this document to benefit others developing their own FIT file decoders. Simultaneously, I encourage them to share any undocumented values they discover, so I can incorporate them into this resource.
You can find the list of undocumented values in this Google Sheet.
Call for Contribution
If you discover other undocumented messages, fields, or values, or identify any errors in this sheet, please contribute!
You can do so by opening a FIT file demonstrating the value in FIT File Viewer, clicking the “Contact Me” link at the bottom, and completing the form.