Command Line Arguments

By default FitToCSV.bat creates a .csv file containing all the message definitions and data messages found in the original FIT file. This creates a .csv file with rows that have varying numbers of columns, and messages of similar types on nonconsecutive rows. Using the optional command line arguments, the output can be filtered so only the messages of interest will be written to the .csv file with each row having a fixed number of columns.

FitCSVTool Usage

The FitCSVTool is a Java command line utility that converts binary FIT files to and from readable text files. The command line usage is:

FIT CSV Tool - Protocol 2.0
Usage: java -jar FitCSVTool.jar <options> <file>
      -b <FIT FILE> <CSV FILE>  FIT binary to CSV.
      -c <CSV FILE> <FIT FILE>  CSV to FIT binary.
      -t Enable file verification tests.
      -d Enable debug output.
      -i Check the integrity of the FIT file before decoding.
      -s Show invalid fields in the CSV file.
      -se Show invalid fields in the CSV file as empty cells.
      -u Hide unknown data and report statistics on how much is hidden.
      -x Print byte values as hexadecimal.
      -deg Print semicircle values as degrees.
      -iso8601 Print date-time values as ISO 8601 formatted strings.
      -pN Encode file using Protocol Version <N>. Default: 2
      -ex Changes the behaviour of the --defn and --data options to
          filter out the messages listed. The default behaviour without
          this flag is to exclude all messages except those listed
          after the --defn and the --data options.
      -e Print enum values as their corresponding string labels when
          possible. Note: CSV files generated with this option will not
          be able to be converted back into .FIT files.
      -re Remove expanded fields from CSV output. This removes fields
          that have been generated through component expansion and
          which do not exist in the source .FIT file.
      --defn <MESSAGE_STRING_0,MESSAGE_STRING_1,...> Narrows down the
          definitions output to CSV. Use 'none' for no definitions.
          When this option is used, only the message definitions
          in the comma separated list will be written to the CSV.
          eg. --defn file_capabilities,record,file_creator
          Note: This option is only compatible with the -b option.
      --data <MESSAGE_STRING_0,MESSAGE_STRING_1,...> Narrows down the
          data output to CSV. When this option is used, only the data
          in the comma separated list will be written to the csv. Use 'none' for no
          records. eg. --data file_capabilities,record,file_creator
          Note: This option is only compatible with the -b option.

Message Filtering

Message filtering in the output text file may be accomplished using the –defn or –data arguments and passing in a list of message names. In this way, only messages of interest will be written to the .csv file, simplifying analysis.

To suppress the generation of ALL data messages, the special argument ‘none’ may be used with the –data argument. To suppress the generation of ALL definition messages, the special arguments ‘none’ may be used with the –defn argument.

In addition to the usual .csv output, when these arguments are used, a ‘data’ file is created (*_data.csv). The header row of the data file contains a column for each message/field combination encountered in the file. Messages that have been filtered are not included. When a missing field value is encountered the last known value will be used, so care should be taken to differentiate values that are repeated in the CSV files from values missing in the input file.

A common example of message filtering can be found in the FitToCSV-record.bat file included with the FIT SDK. FitToCSV-record.bat uses the –defn none option to exclude message definitions and –data record to only include Record messages.

java -jar FitCSVTool.jar --defn none --data record <file>

The resulting _data.csv file contains Record messages with a single header row at the top and with each row having a fixed number of columns, which is a desired format for additional analysis.

Invalid Fields

The FitCSVTool defaults to excluding invalid fields from the resulting CSV. The default behavior can be modified to show invalid fields with their corresponding invalid values by using –s. To show invalid fields in the CSV but substitute an empty cell for the invalid value use –se. These options can be helpful for maintaining consistent formatting when analyzing .csv output. The following are the differences in output when a field is invalid (in this case, the battery_status field):