Download the PHP package adriangibbons/php-fit-file-analysis without Composer

phpFITFileAnalysis

A PHP (>= v5.4) class for analysing FIT files created by Garmin GPS devices.

Live demonstration (Right-click and Open in new tab)

Demo Screenshots

Please read this page in its entirety and the FAQ first if you have any questions or need support.

What is a FIT file?

FIT or Flexible and Interoperable Data Transfer is a file format used for GPS tracks and routes. It is used by newer Garmin fitness GPS devices, including the Edge and Forerunner series, which are popular with cyclists and runners.

Visit the FAQ page within the Wiki for more information.

How do I use phpFITFileAnalysis with my PHP-driven website?

A couple of choices here:

The more modern way: Add the package adriangibbons/php-fit-file-analysis in a composer.json file:

Run from the command line.

The composer.json file should autoload the class, so as long as you include the autoload file in your PHP file, you should be able to instantiate the class with:

The more manual way: Download the ZIP from GitHub and put PHP class file from the /src directory somewhere appropriate (e.g. classes/). A conscious effort has been made to keep everything in a single file.

Then include the file on the PHP page where you want to use it and instantiate an object of the class:

Note that the only mandatory parameter required when creating an instance is the path to the FIT file that you want to load.

There are more Optional Parameters that can be supplied. These are described in more detail further down this page.

The object will automatically load the FIT file and iterate through its contents. It will store any data it finds in arrays, which are accessible via the public data variable.

Accessing the Data

Data read by the class are stored in associative arrays, which are accessible via the public data variable:

The array indexes are the names of the messages and fields that they contain. For example:

OK, but how do I know what messages and fields are in my file? You could either iterate through the $pFFA->data_mesgs array, or take a look at the debug information you can dump to a webpage:

How about some real-world examples?

Enumerated Data The FIT protocol makes use of enumerated data types. Where these values have been identified in the FIT SDK, they have been included in the class as a private variable: $enum_data.

A public function is available, which will return the enumerated value for a given message type. For example:

In addition, public functions provide a short-hand way to access commonly used enumerated data:

• manufacturer()
• product()
• sport()

Optional Parameters

There are five optional parameters that can be passed as an associative array when the phpFITFileAnalysis object is instantiated. These are:

• fix_data
• data_every_second
• units
• pace
• garmin_timestamps
• overwrite_with_dev_data

For example:

The optional parameters are described in more detail below.

"Fix" the Data

FIT files have been observed where some data points are missing for one sensor (e.g. cadence/foot pod), where information has been collected for other sensors (e.g. heart rate) at the same instant. The cause is unknown and typically only a relatively small number of data points are missing. Fixing the issue is probably unnecessary, as each datum is indexed using a timestamp. However, it may be important for your project to have the exact same number of data points for each type of data.

Recognised values: 'all', 'cadence', 'distance', 'heart_rate', 'lat_lon', 'power', 'speed'

Examples:

If the fix_data array is not supplied, then no "fixing" of the data is performed.

A FIT file might contain the following:

As illustrated above, the types of data most susceptible to missing data points are: position_lat, position_long, altitude, heart_rate, cadence, distance, speed, and power.

With the exception of cadence information, missing data points are "fixed" by inserting interpolated values.

For cadence, zeroes are inserted as it is thought that it is likely no data has been collected due to a lack of movement at that point in time.

Interpolation of missing data points

As you can see from the trivial example above, temperature data have been recorded for each of five timestamps (100, 101, 102, 103, and 104). However, distance information has not been recorded for timestamps 102 and 103.

If fix_data includes 'distance', then the class will attempt to insert data into the distance array with the indexes 102 and 103. Values are determined using a linear interpolation between indexes 101(4.01) and 104(10.88).

The result would be:

Data Every Second

Some of Garmin's Fitness devices offer the choice of Smart Recording or Every Second Recording.

Smart Recording records key points where the fitness device changes direction, speed, heart rate or elevation. This recording type records less track points and will potentially have gaps between timestamps of greater than one second.

You can force timestamps to be regular one second intervals by setting the option:

Missing timestamps will have data interpolated as per the option above.

If the option is not specified in conjunction with then is assumed.

Note that you may experience degraded performance using the option. Improving the performance will be explored - it is likely the function is sub-optimal.

Set Units

By default, metric units (identified in the table below) are assumed.

You can request statute or raw units instead of metric. Raw units are those were used by the device that created the FIT file and are native to the FIT standard (i.e. no transformation of values read from the file will occur).

To select the units you require, use one of the following:

Pace

If required by the user, pace can be provided instead of speed. Depending on the units requested, pace will either be in minutes per kilometre (min/km) for metric units; or minutes per mile (min/mi) for statute.

To select pace, use the following option:

Pace values will be decimal minutes. To get the seconds, you may wish to do something like:

Note that if 'raw' units are requested then this parameter has no effect on the speed data, as it is left untouched from what was read-in from the file.

Timestamps

Unix time is the number of seconds since UTC 00:00:00 Jan 01 1970, however the FIT standard specifies that timestamps (i.e. fields of type date_time and local_date_time) represent seconds since UTC 00:00:00 Dec 31 1989.

The difference (in seconds) between FIT and Unix timestamps is 631,065,600:

By default, fields of type date_time and local_date_time read from FIT files will have this delta added to them so that they can be treated as Unix time. If the FIT timestamp is required, the 'garmin_timestamps' option can be set to true.

Overwrite with Developer Data

The FIT standard allows developers to define the meaning of data without requiring changes to the FIT profile being used. They may define data that is already incorporated in the standard - e.g. HR, cadence, power, etc. By default, if developers do this, the data will overwrite anything in the regular array. If you do not want this occur, set the 'overwrite_with_dev_data' option to false. The data will still be available in .

Analysis

The following functions return arrays of data that could be used to create tables/charts:

For advanced control over these functions, or use with other sensor data (e.g. cadence or speed), use the underlying functions:

Functions exist to determine thresholds based on percentages of user-supplied data:

Heart Rate

A function exists for analysing heart rate data:

Heart Rate metrics:

• TRIMP (TRaining IMPulse)
• Intensity Factor

Power

Three functions exist for analysing power data:

Power metrics:

• Average Power
• Kilojoules
• Normalised Power (estimate had your power output been constant)
• Variability Index (ratio of Normalised Power / Average Power)
• Intensity Factor (ratio of Normalised Power / Functional Threshold Power)
• Training Stress Score (effort based on relative intensity and duration)

Critical Power (or Best Effort) is the highest average power sustained for a specified period of time within the activity. You can supply a single time period (in seconds), or an array or time periods.

Quadrant Analysis provides insight into the neuromuscular demands of a bike ride through comparing pedal velocity with force by looking at cadence and power.

Note that and some power metrics (Normalised Power, Variability Index, Intensity Factor, Training Stress Score) will use the PHP Trader extension if it is loaded on the server. If the extension is not loaded then it will use the built-in Simple Moving Average algorithm, which is far less performant particularly for larger files!

A demo of power analysis is available here.

Other methods

Returns array of booleans using timestamp as key. true == timer paused (e.g. autopause):

Returns a JSON object with requested ride data:

Returns array of gear change information (if present, e.g. using Shimano D-Fly Wireless Di2 Transmitter):

Acknowledgement

This class has been created using information available in a Software Development Kit (SDK) made available by ANT (thisisant.com).

As a minimum, I'd recommend reading the three PDFs included in the SDK:

1. FIT File Types Description
2. FIT SDK Introductory Guide
3. Flexible & Interoperable Data Transfer (FIT) Protocol

Following these, the 'Profile.xls' spreadsheet and then the Java/C/C++ examples.