Repository files navigation

This repository is a collection of Garmin FIT Perl library and scripts forconverting Garmin FIT files to other formats.
Currently the following conversions are supported:

Source		Destination		Extension
	Garmin FIT		GPX v1.1	.gpx
	Garmin FIT		SigmaSport log file	.slf
	Garmin FIT		JavaScript Object Notation	.json
	Garmin FIT		Text dump of all data records	.txt

Main library for reading and parsing Garmin FIT file is a modified/updatedversion ofGarmin::FIT library by Kiyokazu Suto. If you want to updateGarmin::FIT library to the latest protocol/profile, use documentation fromthe officialFIT SDK fromthisisant.com Web site.

Currently supported FIT protocol and profile in this version of library is:

Some of the messages and fields used in this implementation are not describedin the latest officialFIT SDK documentation and are thereforeexperimental/unsupported. This implementation was tested on FIT files fromGarmin Edge device only. Other devices might produce FIT files which don'thave all required fields. Scripts work in both Windows and Unix environments.Support for 64-bit integers is not tested at all.

Conversion scripts need to be run from the command line (there's no GUI).

You'll need the following Perl prerequisites:

• POSIX::strftime::GNU
• Data::UUID
• Config::Simple

You can install them withppm on Windows (if you are using ActivePerl) orwithcpan:

$ cpan install POSIX::strftime::GNU  $ cpan install Data::UUID  $ cpan install Config::Simple

You have to copy FIT files from your Garmin (or other) device to your computer.You'll need theactivity FIT files only. On Garmin Edge devices thesefiles are stored in \Garmin\Activity subdirectory. You can also do it viaGarmin Connect Export option.

All conversion scripts can optionaly use config file inWindowsini format,which must be named as the script name with extension.ini and mustreside in the current working directory. If the config file is not found, somereasonable defaults are applied.

Config file example (fit2slf.ini):

[default];SigmaSport: cycling, mountainbike, racing_bycicle (road bike), running, ...sport = mountainbiketraining_type = Ridingbike = bike1[personal]name = John Smithgender = maleage = 40height = 183weight = 75[bike1]name = Ibis Ripley 29 LStype = MTBweight = 12.3wheel_size = 2326

Units used in config file and in scripts are metric (kg, cm, mm, ...).

Detailed syntax and parameters used inini file is described inConfig (ini) File Syntax.

Usefit2gpx.pl with optional config filefit2gpx.ini:

$ fit2gpx.pl input.fit

This produces fileinput.gpx in the current directory. If the fileinput.gpx already exists, it will not be overwritten. To force overwrite,use:

$ fit2gpx.pl -y input.fit

By default a GPX file compatible withGarmin's Track Point Extension Format v1is produced. If you want to produce a GPX file compatible with aCluetrust GPX Extension Format, use the following:

$ fit2gpx.pl -c input.fit

Difference between them is in the syntax how heart rate, cadence, temperature &power data is stored in the file. In both cases a Cluetrust extension<gpxdata:lap> (one for each lap) will be added to the end of file,where the following average/min/max values are stored:

startPoint, endPoint, startTime, elapsedTime, calories, distance, avg_speed,max_speed, min_altitude, avg_altitude, max_altitude, total_ascent, total_descent,distance_uphill, distance_downhill, avg_incline_uphill, avg_incline_downhill,avg_rise_rate_uphill, avg_rise_rate_downhill, min_heart_rate, max_heart_rate,min_percent_hrmax, avg_percent_hrmax, max_percent_hrmax, time_under_target_zone,time_in_target_zone, time_over_target_zone, avg_power, avg_power_KJ,avg_power_W_per_Kg, max_power, avg_cadence, max_cadence, min_temperature,avg_temperature, max_temperature, total_cycles, total_records

Ifinput.fit contains power data from power meter, the real poweraverage will be used instead of calculated one.

Usefit2slf.pl with optional config filefit2slf.ini:

$ fit2slf.pl input.fit

This produces fileinput.slf in the current directory. If the fileinput.slf already exists, it will not be overwritten. To force overwrite,use:

$ fit2slf.pl -y input.fit

A lot of calculation of average/min/max values is done in addition to thedata found in FIT file. Specifically, power is calculated according to theformulas described in J.C. Martin's paperValidation of a Mathematical Model for Road Cycling Powerfrom 1998. You can change some of the parameters used for power calculationinini file (seeConfig (ini) File Syntax). Ifinput.fit containspower data from power meter, the real power measurements will be used insteadof calculated ones.

Resultinginput.slf can be directly imported inSigmaSport Data Center,which is a perfect software foroffline evaluation of cycling statisticsand training sessions.

Usefitdump.pl:

$ fitdump.pl -print_json=1 input.fit > input.json

If you want to include the units, which are switched off by default for JSON,add command line switch-without_unit=0.

fitdump.pl reads the contents for Garmin .FIT files given on command line(or standard input if no file is specified), and prints them in human readableform. Usage:

$ fitdump.pl input.fit > input.txtor$ cat input.fit | fitdump.pl > input.txt

The following command line switches are available (see example for JSON above):

-semicircles_to_deg=(0|1)       default: 1-mps_to_kph=(0|1)               default: 1-use_gmtime=(0|1)               default: 0-maybe_chained=(0|1)            default: 0-print_json=(0|1)               default: 0-without_unit=(0|1)             default: 0 (1 for print_json)-skip_invalid=(0|1)             default: 0 (1 for print_json)-numeric_date_time=(0|1)        default: 0-show_version=(0|1)             default: 0

Fields in .FIT files, which are not documented inFIT SDK, are named asunknown<field_number>. New fields, which typically appear in newerversions of FIT Profiles andGarmin::FIT library doesn't know them yet,are named asxxx<field_number>.

fitdump.pl is written in a generic way and will read all versions of.FIT files (past and future).