The FIT SDK documentation is available at https://developer.garmin.com/fit
Share your knowledge, ask questions, and get the latest FIT SDK news in the FIT SDK Developer Forum
FitGen is a command line tool that can be used to generate, optimize, and customize the FIT SDK. The C SDK can be generated by running FitGen. For windows systems, download and run FitGen.exe. For linux systems, download and run fitgen-linux-x64. Run the following commands to generate the C SDK.
Windows
FitGen.exe -cLinux
fitgen-linux-x64 -cFitGen can be used to optimize the C SDK for use in embedded applications and customize the SDK.
In order to maintain interoperability of FIT files, existing messages and fields in the FIT Profile should not be redefined or modified. When required, Developer Data Fields should be used to add new data fields to existing messages.
This following information will cover:
- Optimizing the FIT C SDK for embedded applications.
- Adding custom messages to the FIT SDK.
- FitGen command line arguments.
The C SDK can be optimized to reduce the code size, reduce the amount of memory used at runtime, or to reduce the size of FIT files that are created. Multiple techniques can be combined to optimize the footprint of the C SDK.
The steps to optimizing the C SDK are:
- Modify the compile options in fit_config.h to suit the application requirements.
- Modify config.csv to customize the FIT Profile and reduce code size.
- Run FitGen.exe to generate the C SDK with the new configuration.
The following modifications can be made in fit_config.h to change the compile time behavior of the FIT SDK:
- Set the max number of local message definitions to reduce RAM requirements.
- Define the required endianness, the default is little endian.
- Choose between using data types defined in fit.h or stdint.h.
- Select the product configuration that should be used. See Generating Code for Multiple Products for more information on using multiple product configurations.
The config.csv file is used to select which messages and fields are included in the C SDK. FitGen creates a default config.csv that selects the most common messages and fields to be included in the C SDK. The default config.csv file can be edited to add or remove messages from the C SDK.
The code size of the C SDK can be optimized by excluding message and fields that are not used for a given application. The length of array and string fields can be optimized to further reduce the code size of the C SDK and the file size of encoded FIT files.
Messages and fields are selected by specifying the number of field elements in the product column of config.csv. A field is not included if the cell is 0 or blank. If no fields are included then the message is not included in the C SDK.
For example, the following configuration includes a user profile message with a friendly name with maximum length of 16 characters, gender, age and weight. Language is not included in the message because it is set to 0.
user_profile,,,""
,friendly_name,,"16"
,gender,,"1"
,age,,"1"
,height,,"1"
,weight,,"1"
,language,,"0"
A message can be configured to have multiple definitions with different fields selected. Alternate definitions must first be named by adding the following option to the message row of config.csv:
d=<alt-def 1 name>,<alt-def 2 name>,<alt-def 3 name>,...
If n names are specified, then n alternate message definitions are created in addition to the main message definition. Names can only include letters, numbers and the underscore character. To specify the number of elements for a particular field, the field row of config.csv must be formatted as follows:
<main-def # elements> d=<alt-def 1 # elements>,<alt-def 2 # elements>,<alt-def 3 # elements>,...
For example, the following configuration includes three "my_custom_message" message definitions in the C SDK. The main definition includes all the fields, a name with a maximum length of 64, and an array of 16 values. The "compact version" reduces the length of the name and array fields by half, and the "super compact version" removes the name and array fields from the message entirely. Note that the alternate message definitions are in the same column and grouped together with quotes.
my_custom_message,,,"d=compact_version,super_compact_version"
,timestamp,,"1 d=1,1"
,local_timestamp,,"1 d=1,1"
,field0,,"1 d=1,1"
,field1,,"1 d=1,1"
,field2,,"1 d=1,1"
,field3,,"1 d=1,1"
,name,,"64 d=32,0"
,custom_options,,"1 d=1,1"
,bitmask_options,,"1 d=1,1"
,position_lat,,"1 d=1,1"
,position_long,,"1 d=1,1"
,enhanced_altitude,,"1 d=1,1"
,array_of_values,,"16 d=8,0"
When executing FitGen using a custom config.csv file, the -norewrite option should be used to prevent FitGen from overwriting config.csv with default values.
> fitgen -norewrite -config config.csv
After running FitGen, fit_example.h shows the message and message definition sizes for each version of the message.
#define FIT_MY_CUSTOM_MESSAGE_MESG_SIZE 164
#define FIT_MY_CUSTOM_MESSAGE_MESG_DEF_SIZE 44
#define FIT_MY_CUSTOM_MESSAGE_COMPACT_VERSION_MESG_SIZE 100
#define FIT_MY_CUSTOM_MESSAGE_COMPACT_VERSION_MESG_DEF_SIZE 44
#define FIT_MY_CUSTOM_MESSAGE_SUPER_COMPACT_VERSION_MESG_SIZE 36
#define FIT_MY_CUSTOM_MESSAGE_SUPER_COMPACT_VERSION_MESG_DEF_SIZE 38
fit_example.h also shows that the array and name fields are not included in the super compact version of the message.
typedef struct
{
FIT_DATE_TIME timestamp; // 1 * s + 0, UTC time of message
FIT_LOCAL_DATE_TIME local_timestamp; // 1 * s + 0, Local time of message
FIT_UINT32 field2; // uint32 field
FIT_FLOAT32 field3; // float32 field
FIT_MY_CUSTOM_BITFIELD_OPTIONS bitmask_options; // custom bitfields field
FIT_SINT32 position_lat; // 1 * semicircles + 0, latitude field
FIT_SINT32 position_long; // 1 * semicircles + 0, longitude field
FIT_UINT32 enhanced_altitude; // 5 * m + 500, enhanced altitude field
FIT_UINT16 field1; // uint16 field
FIT_UINT8 field0; // uint8 field
FIT_MY_CUSTOM_OPTIONS custom_options; // custom options field
} FIT_MY_CUSTOM_MESSAGE_SUPER_COMPACT_VERSION_MESG;
If products have different features, it may be beneficial to create different product configurations that include only the messages and features used by each product. This can be done using a single config.csv file.
The default product in config.csv is "EXAMPLE" which includes the most common messages and fields. Additional product configurations can be defined by adding columns to the "Message" header, and then selecting the messages and fields to be included in each product configuration. The following config.csv file creates a second product configuration named "OTHER", sets its data structure alignment to 4, add a device file, and selects the messages and fields that should be included.
Data Structure Alignment [bytes]:,,,4,4
File:,device,,"1 n=device ","1 n=device "
Message Name,Field Name,Products:,EXAMPLE,OTHER
file_id,,,"f=all,1,, ","f=all,1,, "
,type,,"1","1"
,manufacturer,,"1","1"
,product,,"1","1"
,serial_number,,"1","1"
,time_created,,"1","0"
,number,,"1","0"
,product_name,,"20","0"
FitGen creates a header and source file for each product configuration using the naming scheme fit_<product_name>.[c,h]. These header and source files are included by other source files created by FitGen. Preprocessor directives make sure that only one product configuration will be used at compile time.
#include "fit_config.h"
#if defined(FIT_PRODUCT_OTHER)
#include "fit_other.h"
#else
#include "fit_example.h"
#endif
By default the "EXAMPLE" product configuration is used. A different product configuration can be selected at compile time by defining FIT_PRODUCT_<PRODUCT_NAME> in fit_config.h. To use the product configuration "OTHER", define "FIT_PRODUCT_OTHER" in fit_config.h.
#define FIT_PRODUCT_OTHER
In the C SDK, message data is accessed directly through auto generated C structures. See FIT_*_MESG type definitions in fit_example.h for examples. The order of fields is optimized to minimize the structure padding requirements. The default alignment is 4 bytes and can be configured in config.csv for each product.
In the previous example, the alignment for both the EXAMPLE and OTHER product configurations is set to 4.
Data Structure Alignment [bytes]:,,,4,4
FIT files that have a predetermined number of messages can be setup as a fixed structure of message definitions and message data. Defining a fixed file structure allows for efficient random access of message data. File Structures are commonly used for settings files that have a fixed number of messages and fields.
File Structures are defined at the top of the config.csv file, and messages can be included in a file by adding the following option to the message row in the config.csv file:
f=<file type>,<number of messages in file>
If file type is "all", then the message is included in all file types. The file_id message is required in every file so it must be configured as f=all,1.
For example, the config.csv below defines a settings file that includes a file_id message and 3 user profile messages. Each of these 3 messages includes the fields: friendly name, gender, age, height and weight.
Data Structure Alignment [bytes]:,,,4
File:,settings,,"1 n=settings"
Message Name,Field Name,Products:,EXAMPLE
file_id,,,"f=all,1,,"
,type,,"1"
,manufacturer,,"1"
,product,,"1"
,serial_number,,"1"
,time_created,,"1"
,number,,"1"
,product_name,,"20"
user_profile,,,"f=settings,3"
,friendly_name,,"16"
,gender,,"1"
,age,,"1"
,height,,"1"
,weight,,"1"
,language,,"0"
fit_example.h shows the definition of the settings file structure. The structure contains members for the file header, message definitions, messages, and 2 byte CRC. The structure allocates the space for the file header and CRC,
#define FIT_SETTINGS_FILE_FILE_ID_MESGS 1
#define FIT_SETTINGS_FILE_USER_PROFILE_MESGS 3
#define FIT_SETTINGS_FILE_DATA_SIZE ((FIT_UINT32)297)
#define FIT_SETTINGS_FILE_SIZE (FIT_FILE_HDR_SIZE + FIT_SETTINGS_FILE_DATA_SIZE + sizeof(FIT_UINT16))
#define FIT_SETTINGS_FILE_MESG_COUNT 2
#define FIT_SETTINGS_FILE_COUNT 1
#define FIT_SETTINGS_FILE_CRC_PAD_SIZE ((FIT_ALIGNMENT - FIT_FILE_CRC_SIZE) % FIT_ALIGNMENT)
typedef struct
{
FIT_UINT8 hdr[FIT_FILE_HDR_SIZE];
FIT_UINT8 file_id_mesg_def[FIT_HDR_SIZE + FIT_FILE_ID_MESG_DEF_SIZE];
FIT_UINT8 file_id_mesg[FIT_SETTINGS_FILE_FILE_ID_MESGS][FIT_HDR_SIZE + FIT_FILE_ID_MESG_SIZE];
FIT_UINT8 user_profile_mesg_def[FIT_HDR_SIZE + FIT_USER_PROFILE_MESG_DEF_SIZE];
FIT_UINT8 user_profile_mesg[FIT_SETTINGS_FILE_USER_PROFILE_MESGS][FIT_HDR_SIZE + FIT_USER_PROFILE_MESG_SIZE];
FIT_UINT8 crc[2];
} FIT_SETTINGS_FILE;
extern const FIT_SETTINGS_FILE fit_settings_file;
A fit_settings_file structure can be created on the heap or stack, and the contents can be written to or read from the local file system. Note that it is up to the user to fill in the header, CRC, and message definitions.
struct FIT_SETTINGS_FILE settings;
struct FIT_SETTINGS_FILE *pSettings = malloc(FIT_SETTINGS_FILE_SIZE);
Alternate messages can be selected when setting up files and RAM. To set up a file with an alternate message, add the following option to the message row of config.csv:
f=<file_type>,<number of messages in file>,<alt-def name>
To set up a static copy of a message in RAM, add the following option to the message row of config.csv:
r=<number of messages in RAM>, <alt-def name>
If the alternate definition name is not specified, the main definition is used. For example, the following configuration selects the "long_name" definition for the settings file but the main definition in the device file.
user_profile,,,"d=long_name,language_only f=settings,3,long_name f=device,3"
,friendly_name,,"16 d=32,0"
,gender,,"1 d=0,0"
,age,,"1 d=0,0"
,height,,"1 d=0,0"
,weight,,"1 d=0,0"
,language,,"0 d=0,1"
Message and field capabilities can be auto generated. A capability is configured by adding the following option to the message or field row of config.csv:
c=<file type>,<capability type>,<number of messages>
The options for capability type are: num_per_file, max_per_file, or max_per_file_type. Each message and field can have multiple capability options (for different file types).
Fields can be configured to set initial values or retrieve data from RAM. To setup fields to use a constant initialization value add the following option to the field row of config.csv:
f=<file_type>,<count>,<init_value>
When fields should be pulled from a variable available in RAM add the following option to the field row of config.csv:
f=<file_type>,<count>,<init_value>,<ram_variable>
If there is a constant pointer to the RAM data instead of an accessible variable add the following option to the field row of config.csv:
f=<file_type>,<count>,<init_value>,<ram_pointer>,p
The steps to add custom messages to the FIT SDK are:
- Define custom messages and custom types in messages.csv and types.csv files.
- Execute FitGen, passing the messages.csv and types.csv files as arguments.
messages.csv and types.csv should be saved to /path/to/fit/sdk. This should be the same location as FitGen.exe or fitgen-linux-x64. For each custom message, a corresponding message number should be added to the "mesg_num" type. Custom message numbers should be in the range [0xFF00,0xFFFE].
Copy and paste the following text into a text editor and save it as /path/to/fit/sdk/types.csv. The example types.csv file contains an entry in the mesg_num enum for the "my_custom_message" message, and definitions for two custom types that show how to define enums and bitfields.
Type Name,Base Type,Value Name,Value,Comment
mesg_num,uint16,,,
,,my_custom_message,0xFF01,"Message number for my custom message"
,,,,,,,,
my_custom_options,enum,,,"Custom Options"
,,option_a,0,"Option A"
,,option_b,1,"Option B"
,,option_c,2,"Option C"
,,,,,,,,
my_custom_bitfield_options,uint32z,,,"Custom Bitfield Options"
,,bit1,0x00000001,"Bit 0"
,,bit2,0x00000002,"Bit 1"
,,bit3,0x00000004,"Bit 2"
,,bit4,0x00000008,"Bit 3"
,,bit5,0x00000010,"Bit 4"
Copy and paste the following text into a text editor and save it as /path/to/fit/sdk/messages.csv. The example messages.csv file provides an example message definition with fields that use both the standard data types defined in the FIT Protocol and the custom types defined in types.csv.
Message Name,Field Def #,Field Name,Field Type,Array,Components,Scale,Offset,Units,Bits,Accumulate,Ref Field Name,Ref Field Value,Comment,Products:,EXAMPLE
my_custom_message,,,,,,,,,,,,,,,
,253,timestamp,date_time,,,,,s,,,,,"UTC time of message as seconds since 1989-12-31T00:00:00Z",,
,0,local_timestamp,local_date_time,,,,,s,,,,,"Local time of message as seconds since 1989-12-31T00:00:00",,
,1,field0,uint8,,,,,,,,,,"uint8 field",,
,2,field1,uint16,,,,,,,,,,"uint16 field",,
,3,field2,uint32,,,,,,,,,,"uint32 field",,
,4,field3,float32,,,,,,,,,,"float32 field",,
,5,name,string,,,,,,,,,,"name field",,
,6,custom_options,my_custom_options,,,,,,,,,,"custom options field",,
,7,bitmask_options,my_custom_bitfield_options,,,,,,,,,,"custom bitfields field",,
,8,position_lat,sint32,,,,,semicircles,,,,,"latitude field",,
,9,position_long,sint32,,,,,semicircles,,,,,"longitude field",,
,10,enhanced_altitude,uint32,,,5,500,m,,,,,"enhanced altitude field",,
,11,array_of_values,uint32,[N],,,,,,,,,"array field",,
To use FitGen to create a custom SDK using the definitions in messages.csv and types.csv files, from a command prompt navigate to the location where the FIT SDK is installed and execute the following command:
> fitgen -messages messages.csv -types types.csv
All of the SDKs located at /path/to/fit/sdk will now include the custom messages and types defined in the messages.csv and types.csv files.
Generating the C SDK with the custom messages requires FitGen to be executed a second time. The first time FitGen is executed a new config.csv file is generated that contains the custom messages. This can be seen in line 4 of the output above. The config.csv file needs to be updated to specify that the custom messages and fields should be included in the C SDK. After editing config.csv, run FitGen a second time providing the modified config.csv file as an argument.
To edit config.csv, open the file in a text editor then scroll to the bottom and locate the custom messages. You should see something similar to this:
my_custom_message,,,""
,timestamp,,"0"
,local_timestamp,,"0"
,field0,,"0"
,field1,,"0"
,field2,,"0"
,field3,,"0"
,name,,"0"
,custom_options,,"0"
,bitmask_options,,"0"
,position_lat,,"0"
,position_long,,"0"
,enhanced_altitude,,"0"
,array_of_values,,"0"
Fields with a "0" in their row will not be included in the C SDK and should be changed to a "1". Any message with a field marked as "1" will be included in the C SDK. If the field is an array or a string, the value should be changed to the desired array or string length. See Optimizing the FIT C SDK for more information on editing config.csv.
my_custom_message,,,""
,timestamp,,"1"
,local_timestamp,,"1"
,field0,,"1"
,field1,,"1"
,field2,,"1"
,field3,,"1"
,name,,"64"
,custom_options,,"1"
,bitmask_options,,"1"
,position_lat,,"1"
,position_long,,"1"
,enhanced_altitude,,"1"
,array_of_values,,"16"
Save config.csv and execute FitGen a second time, passing the messages.csv, types.csv, and config.csv files as arguments. The nowrite argument prevents FitGen from overwriting the edited config.csv file. See FitGen Command Line Arguments for additional command line options.
> fitgen -norewrite -messages messages.csv -types types.csv -config config.csv
The C SDK will now include the custom messages and types as defined in the messages.csv, types.csv files, and config.csv files. Inspecting the file /path/to/fit/sdk/c/fit_example.h will show the custom message and types.
// my_custom_message message
#define FIT_MY_CUSTOM_MESSAGE_MESG_SIZE 164
#define FIT_MY_CUSTOM_MESSAGE_MESG_DEF_SIZE 44
#define FIT_MY_CUSTOM_MESSAGE_MESG_NAME_COUNT 64
#define FIT_MY_CUSTOM_MESSAGE_MESG_ARRAY_OF_VALUES_COUNT 16
typedef struct
{
FIT_DATE_TIME timestamp; // 1 * s + 0, UTC time of message
FIT_LOCAL_DATE_TIME local_timestamp; // 1 * s + 0, Local time of message
FIT_UINT32 field2; // uint32 field
FIT_FLOAT32 field3; // float32 field
FIT_STRING name[FIT_MY_CUSTOM_MESSAGE_MESG_NAME_COUNT]; // name field
FIT_MY_CUSTOM_BITFIELD_OPTIONS bitmask_options; // custom bitfields field
FIT_SINT32 position_lat; // 1 * semicircles + 0, latitude field
FIT_SINT32 position_long; // 1 * semicircles + 0, longitude field
FIT_UINT32 enhanced_altitude; // 5 * m + 500, enhanced altitude field
FIT_UINT32 array_of_values[FIT_MY_CUSTOM_MESSAGE_MESG_ARRAY_OF_VALUES_COUNT]; // array field
FIT_UINT16 field1; // uint16 field
FIT_UINT8 field0; // uint8 field
FIT_MY_CUSTOM_OPTIONS custom_options; // custom options field
} FIT_MY_CUSTOM_MESSAGE_MESG;
typedef FIT_UINT8 FIT_MY_CUSTOM_MESSAGE_FIELD_NUM;
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_TIMESTAMP ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)253)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_LOCAL_TIMESTAMP ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)0)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_FIELD2 ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)3)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_FIELD3 ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)4)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_NAME ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)5)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_BITMASK_OPTIONS ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)7)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_POSITION_LAT ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)8)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_POSITION_LONG ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)9)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_ENHANCED_ALTITUDE ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)10)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_ARRAY_OF_VALUES ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)11)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_FIELD1 ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)2)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_FIELD0 ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)1)
#define FIT_MY_CUSTOM_MESSAGE_FIELD_NUM_CUSTOM_OPTIONS ((FIT_MY_CUSTOM_MESSAGE_FIELD_NUM)6)
Refer to Profile.xlsx for examples of how messages and types in the FIT Profile are defined. If needed, the "Messages" worksheet may be exported as messages.csv and the "Types" worksheet may be exported as types.csv. These files can be used as templates for creating custom messages and types.
For help using FitGen, use the -help or /? to see a list of options.
> fitgen /?
FIT Code Generator - Protocol 2.00 Profile 21.xxRelease+Custom
Usage: FitGen.exe [options]
Options:
-o <directory> Specify the root output directory. defaults to "."
-c [directory] Write C code into specified directory. defaults to "c"
-cpp [directory] Write C++ code into specified directory. defaults to "cpp"
-objcpp [directory] Write Objective-C code into specified directory. defaults to "objcpp"
-cs [directory] Write C# code into specified directory. defaults to "cs"
-java [directory] Write Java code into specified directory. defaults to "java"
-js [directory] Write JavaScript code into specified directory. defaults to "js"
-py [directory] Write Python code into specified directory. defaults to "py"
-swift [directory] Write Swift code into specified directory. defaults to "swift"
-norewrite Do not rewrite the used config.csv to include missing messages.
-config config.csv to use, default is current directory if not specified.
-types <file name>.csv Add types to profile. types.csv is added by default if the file exists.
-messages <file name>.csv Add messages to profile. messages.csv is added by default if the file exists.
-v Show Fitgen/Profile version.FitGen automatically looks for input files named "messages.csv", "types.csv", and "config.csv" in the working directory. If found, these files will automatically be used.
The following two commands are equivalent:
> fitgen -messages messages.csv -types types.csv -config config.csv
> fitgen
By default FitGen generates the code for the all of the SDKs. Use the -c, -cpp, -objcpp, -cs, -java, -js, -py, or -swift options to generate the SDK for a specific SDK. More than one language option can be provided. Optionally, the output directory can be specified for each SDK.
The following command generates just the Java SDK in the directory ./myjavasdk.
> fitgen -java myjavasdk
The following output should be displayed to the console. Note that none of the other SDKs were generated.
FIT Code Generator - Protocol 2.00 Profile 21.188Release+Custom
SDK Version: production/akw/21.xx.00
Parsing existing config.csv...
Writing new config.csv...
Generating Java code...
When executing FitGen using a custom config.csv file, the -norewrite option should be used to prevent FitGen from overwriting config.csv with default values.
> fitgen -norewrite -config config.csv -c
The following output should be displayed to the console, note that the existing config.csv was not overwritten.
FIT Code Generator - Protocol 2.00 Profile 21.32Release+Custom
SDK Version: production/akw/21.32.00-0-g756ff70
Adding custom types profile "types.csv".
Adding custom message profile "messages.csv".
Parsing existing config.csv...
Rewrite disabled! Keeping existing config.csv
Generating C code...
Generating C code for EXAMPLE...
Generating C code for OTHER...