Fitreader
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.
Installation
Add this line to your application's Gemfile:
gem 'fitreader'
And then execute:
$ bundle
Or install it yourself as:
$ gem install fitreader
Usage
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
Fitreader.read(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
Fitreader.header
A digest of the records found in the file is shown with
Fitreader.available_records
which will return a list similar to the following, showing respectively the global_message_number (as defined in the FIT SDK), the name of the record type, and the number of records parsed
[[0, :file_id, 1],
[3, :user_profile, 1],
[7, :zones_target, 1],
[18, :session, 1],
[19, :lap, 1],
[20, :record, 2899],
[21, :event, 73],
[22, :source, 58],
[23, :device_info, 14],
[34, :activity, 1],
[49, :file_creator, 1],
[72, :training_file, 1],
[104, :battery_info, 40],
[147, :sensor_info, 3]]
Armed with this information, we can call
Fitreader. filter
where filter is either the global_number or the name supplied by the previous command, for example
Fitreader. 18
Fitreader. :session
will both fetch the session record(s) in the form of a MessageType object. This object contains three fields: a definition, an array of records and an array of undefined_records.
The definition contains metadata from a combination of the FIT file itself and the SKD. I will write more detailed information, but basically this information tells us how to interpret the actual data. Of most relevance, it tells us the name and datatype of each field we will find in records of this type.
The records array contains a list or Record objects. A Record object contains a fields array and an error_fields array. The fields array is a list of the actual data contined within this record, for example timestamp, or coordinated, etc. The particular FieldData object includes the name of the field (also found in the definition), along with the raw_value and the processed value which may differ in the case of, for example, a coordinate.
The error_fields array contains any fields defined in the FIT file itself that aren't defined within the SDK. Without the SKD we can most likely never know what the field represents or whether the raw value would need further processing to make sense to us. These are included mostly for debugging and future convenience sake.
The results of this function are probably a lot more data that we generally need, so a convenience function is included that distills the results of the previous call into a more efficient dataset
Fitreader.record_values 20
Fitreader.record_values :record
This will return an array of hashes, one hash for each record of the specified type. The hashes contain only the field name and value, 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 in my files, rather than kph as one might expect.
Development
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.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/samsari/fitreader.
License
The gem is available as open source under the terms of the MIT License.