A Workout file contains instructions for performing a structured activity. Workout files can be used to describe endurance training, strength training, and even yoga and Pilates practices. The instructions contained in Workout files can used by cycling computers, wearable devices, and third-party applications to guide users through their activities.
See the Encoding Workout Files recipe for an example program for creating Workout files.
There is a set of required message types that are expected to be included in every Workout file. These messages include information about the creator of the file and the individual steps that make up the workout.
The following are the required messages for a Workout 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 Workout files, the Type property should be set to 5. Since a device may contain multiple workout files it is important that the combination of type, manufacturer, product, and serial number is unique. |
| Workout | The Workout message provides a summary of the workout and the number of workout steps contained in the file. |
| Workout Step | The Workout Step message is used to define the instructions for each step of the workout. |
A Workout file must contain a File Id message, a Workout message, and one or more Workout Step messages. The File Id message should be the first message in the file followed by the Workout message and then one or more Workout Step messages.
The following is the required sequence of messages for a Workout file.
The Workout message provides a summary of the workout information contained in the file.
| FIT Fields | Required | Type | Description |
|---|---|---|---|
| sport | N | sport (enum) | Indicates the sport type of the workout. |
| capabilities | N | workout_capabilities | Bitfield describing workout capabilities. |
| num_valid_steps | Y | UINT16 | Indicates the number of valid steps. |
| wkt_name | N | string | User-friendly string identifying name of workout. |
| sub_sport | N | sub_sport (enum) | Indicates the sub sport type of the workout. |
| pool_length | N | UINT16 | Total length of the pool in meters, eg. for a 25 yard pool the pool_length value would be would be 22.86 meters. |
| pool_length_unit | N | display_measure (enum) | Unit used to display the pool length to the user. |
The Workout Step message is used to define each step of the workout. A Workout Step message includes information about the duration of the step, the target intensity for the step, if a block of steps should be repeated, and specific equipment that is required for the step.
| Workout Step Field | Required | Type | Description |
|---|---|---|---|
| message_index | Y | message_index | Provides an index for each step such that a repeat step can refer back to a specific workout step. |
| wkt_step_name | N | string | Display-friendly string identifying name of the workout step. |
| duration_type | Y | wkt_step_duration (enum) | Indicates the type of parameter that will define the workout. |
| duration_value | Y | UINT32 | Dynamic field representing the value of the duration. The value in this field depends on the duration_type. |
| target_type | Y | wkt_step_target (enum) | Indicates the type of parameter that will define the workout step’s target range/zone. |
| target_value | N | UINT32 | Dynamic field representing the value of the target. The value in this field depends on either duration_type or target type. |
| custom_target_value_low | N | UINT32 | If the workout target uses a custom range, rather than a defined zone, this field is used to specify the lower boundary. Dynamic field dependent on target_type. |
| custom_target_value_high | N | UINT32 | If the workout target uses a custom range, rather than a defined zone, this field is used to specify the upper boundary. Dynamic field dependent on target_type. |
| intensity | N | intensity (enum) | Represents the workout steps intensity level. |
| notes | N | string | Display-friendly string with additional instructions for the step to display to the user. |
| equipment | N | workout_equipment (enum) | Represents the equipment that should be used when performing the step. |
The message_index provides a 0 based index for each workout step. The message_index may be used by repeat steps to reference a specific workout step. The message index must be unique for each workout step and be in the range [0, workout.num_valid_steps-1].
The duration_value and target_value fields are dynamic fields that are dependent on the value of the duration_type field as described in the following table.
| duration_type | duration_value | target_value |
|---|---|---|
| Time | duration_time | |
| Distance | duration_distance | |
| hr_less_than | duration_hr | |
| hr_greater_than | duration_hr | |
| calories | duration_calories | |
| open | duration_value | |
| repeat_until_steps_cmplt | duration_step | repeat_steps |
| repeat_until_time | duration_step | repeat_time |
| repeat_until_distance | duration_step | repeat_distance |
| repeat_until_calories | duration_step | repeat_calories |
| repeat_until_hr_less_than | duration_step | repeat_hr |
| repeat_until_hr_greater_than | duration_step | repeat_hr |
| repeat_until_power_less_than | duration_step | repeat_power |
| repeat_until_power_greater_than | duration_step | repeat_power |
| power_less_than | duration_power | |
| power_greater_than | duration_power | |
| repetition_time | duration_time |
When not dependent on the duration_type, the target_value, custom_target_value_low, and custom_target_value_high fields are dynamic fields that are dependent on the value of the target_type field as described in the following table.
| target_type | target_value | customtargetvalue_low | customtargetvalue_high |
|---|---|---|---|
| speed | target_speed_zone | custom_target_speed_low | custom_target_speed_high |
| heart_rate | target_hr_zone | custom_target_heart_rate_low | custom_target_heart_rate_high |
| open | target_value | custom_target_value_low | custom_target_value_high |
| cadence | target_cadence_zone | custom_target_cadence_low | custom_target_cadence_high |
| power | target_power_zone | custom_target_power_low | custom_target_power_high |
| stroke_type | target_swim_stroke | 0 | 0 |
The workout_steps intensity field provides a way to differentiate between workout steps that are designated for warm up, intervals (active), recovery (rest), and cool down. The intensity field does not affect target or duration values, but tracking the intensity field allows the program designer to calculate the total amount of active time within a workout.
| Intensity Value | Intensity Description |
|---|---|
| 0 | Active |
| 1 | Rest |
| 2 | Warmup |
| 3 | Cooldown |
| 4 | Recovery |
| 5 | Interval |
| 6 | Other |
Unless defining repeat steps, the target_value dynamic field typically refers to setting a target zone. These target zones represent target limits that have already been established through other means, such as in a settings file, through a user interface, or predefined on fitness equipment. If zones are predefined their numbering should start at 1 (since 0 is reserved to indicate a custom zone). The workout_step can then be used to set a target heart rate, power, or other zone value. In this case, the custom_target_value_high and custom_target_value_low fields should be set to 0.
If a specific target range is desired, the custom_target_low and custom_target_high fields may be used to set the upper and lower boundaries of the desired target range, and the target_value would be set to 0. Refer to the FIT SDK for specific field/zone values. When creating swim workouts, the target is used to indicate the swim stroke for the step.
Power and heart rate values can be set as absolute or relative values. Absolute values represent beats per minute (bpm) for heart rate, or watts for power. Relative values are percentages ranging from 0 to 100% of the user’s maximum heart rate or 0 to 1000% of the user’s functional threshold power (FTP).
The integer range 0 to 100 (heart rate) and 0 to 1000 (power) are reserved for relative values, absolute heart rate and power values must be offset by 100 bpm or 1000 watts respectively. Examples are provided below.
| Desired Heart Rate | Value in HR Field |
|---|---|
| 125 bpm | 225 |
| 85% user’s max HR | 85 |
| Desired Power | Value in Power Field |
|---|---|
| 325 watts | 1325 |
| 275% FTP | 275 |
A Workout Step message can be used to indicate that a block of steps should be repeated within the workout a specified number of times. The Workout Step message defining the repetition block should immediately follow the block of steps to be repeated. As with all Workout Step messages, this message should have a valid message_index.
The following are the fields and values used to describe a repeat block within a workout.
| Workout Step Field | Value |
|---|---|
| message_index | The valid message index for this step |
| duration_type | repeat_until_steps_cmplt (6) |
| duration_value | message_index to repeat from |
| target_type | open (2) |
| target_value | # of repetitions |
A Workout Step message can be used to indicate that a block of steps should be repeated within the workout until a minimum target value can no longer be maintained, or should be repeated until a maximum target value has been reached.
A typical application of a repeat-until block is when a trainer with a bicycle power meter prescribes that the athlete should continue repeating the intervals until the average power value for the block of steps drops below a specified wattage. A typical block of repeat-until steps will include an active step and a rest step, as defined by the intensity field. In a repeat-until block only the workout steps with an Intensity type Active are part of the criteria to stop or continue.
The following are the fields and values used to describe a repeat-until block within a workout.
| Workout Step Field | Value |
|---|---|
| message_index | The valid message index for this step |
| duration_type | repeat_until_power_last_lap_less_than (17) |
| duration_value | message_index to repeat from |
| target_type | No-set, it is implied from the duration type |
| target_value | Minimum target power to maintain. |