Fitreader is a small gem used for read and decoding FIT files generated by various sports devices. Currently it has only been designed specifically to read files produced by a Garmin Edge 1000. It will probably mostly work out of the box with other file sources, but will probably not work 100% perfectly unless it's a Garmin cycling computer.

Add this line to your application's Gemfile:

gem 'fitreader'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fitreader

To use this gem in a ruby or rails application, simply add

gem 'fitreader'

to the Gemfile and then

require 'fitreader'

to the class you wish to call it from. After that, it's a simple matter of calling

fit_file = Fit.new(path_to_fit_file)

All of the interface and convenience functions can be found in lib/fitreader.rb.

After reading a FIT file, the file header can be inspected by calling

fit_file.header

A digest of the records found in the file is shown with

fit_file.digest

which will return a list similar to the following, showing respectively the name of the record type (as defined in the FIT SDK), and the number of records parsed

{:file_id=>1,
 :file_creator=>1,
 :device_settings=>1,
 :user_profile=>1,
 :sensor_info=>5,
 :sport=>1,
 :zones_target=>1,
 :record=>4988,
 :event=>120,
 :device_info=>30,
 :source=>43,
 :segment_lap=>2,
 :lap=>1,
 :session=>1,
 :activity=>1,
 :battery_info=>20}

Armed with this information, we can call

fit_file.type <name>

where is the name supplied by the previous command, for example

fit_file.type :session

will fetch the session record(s) in the form of a Message object. This object contains three fields: a name, a global_num (as defined by the FIT SDK), and an array of records.

The records array contains a list of hashes, with key-value pairs of field name (also according to the message-type definition) and value, for example timestamp, or coordinates, etc.

For example:

{:timestamp=>2016-04-09 11:19:51 UTC,
 :position_lat=>57.711100755259395,
 :position_long=>11.992837116122246,
 :distance=>78.94,
 :altitude=>14.200000000000045,
 :speed=>3.835,
 :heart_rate=>103,
 :cadence=>0,
 :temperature=>12,
 :fractional_cadence=>0.0},

Some things to watch out for:

• speed is recorded as m/s, rather than kph as one might expect.

After checking out the repo, run bin/setup to install dependencies. Then, run rspec spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine from a clone of the repo, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/samsari/fitreader.

The gem is available as open source under the terms of the MIT License.