FIT SDK
When a person uses their wearable device or cycling computer to record their activities, chances are that data is stored in a FIT Activity file. FIT Activity files are also a common format used by web APIs to transfer activity data between fitness platforms. This makes FIT Activity files the most common of all FIT file types.
Activity files are used to record date & time, sport type, lap & split data, GPS track, sensor data, and events for an active session. Many fitness devices and apps record Activity files in real time while others may export data stored in a proprietary format to a FIT file after the activity recording is complete.
See the Decoding Activity Files and Encoding Activity Files recipes for example programs for working with Activity files.
There is a set of required message types that are expected to be included in every Activity file. There are also message types that are commonly found in Activity files but not required; as with all FIT files, any valid messages may be included in Activity files as needed.
The following are the required messages for an Activity file.
| Message | Purpose |
|---|---|
| File Id | The File Id message is required by all FIT file types and is expected to be the first message in the file. For Activity files, the Type property should be set to 4. The order of the File Id message in the file and the Type property help to quickly identify the file type before fully decoding the file. The File Id message also contains the Manufacturer Id and Product Id of the device or platform that created the file. Manufacturers Ids are assigned by Garmin and each manufacturer defines their own list of Product Ids. The FIT SDK includes a list of Manufacturer Ids and a list of Garmin Product Ids. |
| Activity | A single Activity message is required in a FIT Activity file. Included in the Activity message are the Local Timestamp and Session Count properties. The Local Timestamp is used to determine the time zone offset that can be applied to all timestamps in the file. Most devices record FIT files in real time and the session count will be unknown until the end of the recording. Because of this, the Activity message will often be the last message in the file. It is possible that the Activity message will be missing if the file is truncated or corrupted, so dependencies on the Activity message in post processing of Activity files should be keep to a minimum. |
| Session | Activity files will contain one or more Session messages. A Session message is a Summary message type. Start Time, Total Elapsed Time, Total Timer Time, and Timestamp are required fields for all summary messages. Session messages define almost 150 fields that can provide information related to the activity. This includes the start time; sport & sub sport type; summary values such as total duration, distance, and elevation gain; pool length; starting location; and GPS bounding box. Session messages will typically contain a subset of these fields based on whether a specific feature of the device was used, sport type, and what sensors were in use during the recording of the activity. When a user is engaged in a multi-sport activity, the summary data for each leg of the activity, including transitions, will be stored in separate Session messages within the same Activity file. |
| Lap | Lap messages represent laps or intervals within the session. A Lap message is a Summary message type. Start Time, Total Elapsed Time, Total Timer Time, and Timestamp are required fields for all summary messages. An Activity file should contain at least one Lap message for every Session message, but will likely contain multiple Lap messages per Session message representing various time or distance based splits. Laps may be marked manually by the user or automatically by the recording device. Lap messages should be sequential and non-overlapping, and the sum of the total elapsed time and distance values for all Lap messages should equal the total elapsed time and distance for the corresponding Session message. |
| Record | Record messages are where the moment-by-moment GPS coordinate, speed, distance, heart rate, power, etc. values are stored within Activity files. Records contain timestamps with a one-second resolution, although devices may store data at a lower rate. Devices may also use the Smart Recording technique resulting in Record messages being recorded at irregular time intervals. The data found in Record messages is commonly displayed to users in the form of charts and as tracks on a map. Timestamp and at least one other value are required for each Record message. |
Activity files may contain additional messages other than the required messages. Optional messages may depend on whether a specific feature of a device was used, whether the user was performing a workout or following a course, or what sensors were in use during the recording of the activity.
These are optional message types commonly found in Activity files. Activity files may contain additional messages not listed here.
| Message | Purpose |
|---|---|
| Device Info | Device Info messages are used in Activity files to store information about the device or platform that created the activity and other hardware accessories or sensors that may have been used. Device Info messages may include the manufacturer ID, name, description, serial number, software version, and battery status of the accessory. Not all properties will be reported for all accessories. It is a best practice to include a Device Info message in a FIT Activity file, with additional information describing the device or platform that created the Activity file. This is in addition to the Manufacturer Id and Product Id values in the File Id message. For this Device Info message the device index property should be set to 0 (Creator), the Manufacturer Id should be given, and a display friendly product name should provided. Software version is optional but recommended. |
| Event | Event messages are used to indicate that something notable occurred at a point in time during the recording of an activity. Events can indicate when the timer was started or stopped, when a workout step was completed, if the users deviated from a course they were following, gear changes for electronic shifting systems, or Cycling Dynamics events like the rider standing or sitting. The complete list of Event Types is defined in the Event enum. |
| Length | Length messages are used with track and pool workouts to provide summary information for each lap of a track completed or length of a pool swam. A Length message is a Summary message type. Start Time, Total Elapsed Time, Total Timer Time, and Timestamp are required fields for all summary messages. The Length Type field is also required for all Length messages. |
| Segment Lap | Segment Lap messages are used to mark sections of the route corresponding to predetermined GPS tracks and are typically created by the community for virtual racing. See the Garmin Support Center for more information on segments. Segment Lap is a Summary message type. Start Time, Total Elapsed Time, Total Timer Time, and Timestamp are required fields for all summary messages. |
| User Profile | The User Profile message provides information about the user at the time the activity was recorded. This may include age, gender, weight, height, and resting heart rate. An Activity file should contain a maximum of one User Profile message. The User Profile message does not have a timestamp and can occur at any point in the file. |
| Zone Target | Some sport zone target values are calculated according to user parameters such as maximum or threshold heart rate or power values. Zone Target messages are used to store the current values at the time the activity was recorded. An Activity file should contain a maximum of one Zone Target message. The Zone Target message does not have a timestamp and can occur at any point in the file. |
| Workout | An Activity file may contain Workout and Workout Step messages describing the structured training associated with the activity. An Activity file should contain a maximum of one Workout message. The Workout message does not have a timestamp and can occur at any point in the file. See the Workout File description for more information on Workout messages. |
| Workout Step | When a Workout message is included in an Activity file, one or more Workout Step messages should also be included. The Workout Step messages describe the individual steps that make up the workout. The Workout Step message does not have a timestamp and can occur at any point in the file, however they should be in sequential order. When performing a workout during an activity, the device will typically include a Lap message for each workout step completed, and the Lap message’s Workout Step Index field will contain the index in to the list of Workout Step messages associated with the lap. See the Workout File description for more information on Workout Step messages. |
| HR | HR messages contain compressed heart rate samples. HR messages are commonly used by heart rate monitors that use a “store and forward” data recording method. See Decoding Activity Files for an example of how to expand compressed HR data. |
| HRV | HRV messages are used to record heart rate variability data. The HRV messages contain an array of RR intervals and are interleaved with record and event messages in chronological order. Note that HRV data is not timestamped, and shall be synchronized by checking successive RR intervals as they occur between other timestamped messages. |
Refer to the FIT Profile for a complete list of messages and message properties.
An Activity file is expected to adhere to the following guidelines:
The sequence of messages in an Activity file typically follows one of two patterns: summary first or summary last.
With the summary first message pattern, all of the summary messages are grouped together at the beginning of the file, followed by the moment-by-moment messages like Records and Events.
Whereas with the summary last sequence pattern, the summary messages are written to the file as they occur during the recording of the activity. With this pattern, the summary messages are written to the file at the end of the time interval that they represent.
With summary first message sequencing, the order of messages is the same for both single-sport and multi-sport activities. The file begins with the required File Id and and the optional Device Info messages. The summary messages are grouped by type, starting with Sessions and then Laps, and ordered by the message start times. After the summary messages the moment-by-moment messages are written to the file in ascending chronological order.
The following is the typical sequence of messages for the summary first message pattern:
File Id [1]
Device Info [1…n]
Activity [1]
Session [1…n]
Lap [1…n]
Lengths [1…n]
Records and Event messages interleaved by time stamp [1…n]
In the use case of someone participating in a multi-sport event, the file may contain a session representing each leg of the event and the transitions.
The following is the typical sequence of messages for a single-sport activity using the summary last message pattern:
The message sequence is similar to a single session activity with the File Id and Device Info messages at the beginning of the file, followed by Event, Record, and Lap messages. At the end of each leg of the event, the current lap and session are closed and the corresponding messages are saved to the file. This pattern continues until the final leg of the event is completed. The file concludes with the final Lap and Session messages, and then Activity message.
The following is the typical sequence of messages for an Olympic distance triathlon using the summary last message pattern: