NAME

Geo::FIT - Decode Garmin FIT files

SYNOPSIS

use Geo::FIT;
$fit = Geo::FIT->new();
$fit->file( $fname )
$fit->open;
$fit->fetch_header;
$fit->fetch;
$fit->data_message_callback_by_name( $message name,   \&callback_function [, \%callback_data, ... ] );
$fit->data_message_callback_by_num(  $message number, \&callback_function [, \%callback_data, ... ] );
$fit->close;

DESCRIPTION

Geo::FIT is a Perl class to provide interfaces to decode Garmin FIT files (*.fit).

The module also provides a script to read and print the contents for FIT files (fitdump.pl), as well as a script to convert FIT files to TCX files (fit2tcx.pl).

Constructor

• new()

  creates a new object and returns it.

Class methods

• version_string()

  returns a string representing the version of this class.

• message_name(message spec)

  returns the message name for message spec or undef.

• message_number(message spec)

  returns the message number for message spec or undef.

• field_name(message spec, field spec)

  returns the field name for field spec in message spec or undef.

• field_number(message spec, field spec)

  returns the field index for field spec in message spec or undef.

• cat_header(protocol version, profile version, file length[, refrencne to a scalar])

  composes the binary form of a .FIT file header, concatenates the scalar and it, and returns the reference to the scalar. If the 4th argument is omitted, it returns the reference to the binary form. file length is assumed not to include the file header and trailing CRC.

• crc_of_string(old CRC, reference to a scalar, offset in scalar, counts)

  calculate CRC-16 of the specified part of the scalar.

• my_endian

  returns the endian (0 for little endian and 1 for big endian) of the current system.

Object methods

• file(file name)

  sets the name file name of a .FIT file.

• open()

  opens the .FIT file.

• fetch_header()

  reads .FIT file header, and returns an array of the file size (excluding the trailing CRC-16), the protocol version, the profile version, extra octets in the header other than documented 4 values, the header CRC-16 recorded in the header, and the calculated header CRC-16.

• fetch()

  reads a message in the .FIT file, and returns 1 on success, or undef on failure or EOF.

• unit_table(unit => unit conversion table)

  sets unit conversion table for unit.

• semicircles_to_degree(boolean)

• mps_to_kph(boolean)

  wrapper methods of unit_table() method.

• use_gmtime(boolean)

  sets the flag which of GMT or local timezone is used for date_time type value conversion.

• protocol_version_string()

  returns a string representing the .FIT protocol version on which this class based.

• protocol_version_string(version number)

  returns a string representing the .FIT protocol version version number.

• profile_version_string()

  returns a string representing the .FIT protocol version on which this class based.

• profile_version_string(version number)()

  returns a string representing the .FIT profile version version number.

• data_message_callback_by_name(message name, callback function[, callback data, ...])

  register a function callback function which is called when a data message with the name message name is fetched.

• data_message_callback_by_num(message number, callback function[, callback data, ...])

  register a function callback function which is called when a data message with the messag number message number is fetched.

• switched(data message descriptor, array of values, data type table)

  returns real data type attributes for a C's union like field.

• string_value(array of values, offset in the array, counts)

  converts an array of character codes to a Perl string.

• value_cooked(type name, field attributes table, invalid, value)

  converts value to a (hopefully) human readable form.

• value_uncooked(type name, field attributes table, invalid, value representation)

  converts a human readable representation of a datum to an original form.

• error()

  returns an error message recorded by a method.

• crc_expected()

  CRC-16 attached to the end of a .FIT file. Only available after all contents of the file has been read.

• crc()

  CRC-16 calculated from the contents of a .FIT file.

• trailing_garbages()

  number of octets after CRC-16, 0 usually.

• close()

  closes opened file handles.

• cat_definition_message(data message descriptor[, reference to a scalar])

  composes the binary form of a definition message after data message descriptor, concatenates the scalar and it, and returns the reference to the scalar. If the 2nd argument is omitted, returns the reference to the binary form.

• endian_convert(endian converter, reference to a scalar, offset in the scalar)

  apply endian converter to the specified part of the scalar.

Constants

Following constants are exported: FIT_ENUM, FIT_SINT8, FIT_UINT8, FIT_SINT16, FIT_UINT16, FIT_SINT32, FIT_UINT32, FIT_SINT64, FIT_UINT64, FIT_STRING, FIT_FLOAT16, FIT_FLOAT32, FIT_UINT8Z, FIT_UINT16Z, FIT_UINT32Z, FIT_UINT64Z.

Also exported are:

• FIT_BYTE

  numbers representing base types of field values in data messages.

• FIT_BASE_TYPE_MAX

  the maximal number representing base types of field values in data messages.

• FIT_HEADER_LENGTH

  length of a .FIT file header.

Data message descriptor

When fetch method meets a definition message, it creates a hash which includes various information about the corresponding data message. We call the hash a data message descriptor. It includes the following key value pairs.

• field index => field name

  in a global .FIT profile.

• local_message_type => local message type

  necessarily.

• message_number => message number

  necessarily.

• message_name => message name

  only if the message is documented.

• callback => reference to an array

  of a callback function and callback data, only if a callback is registered.

• endian => endian

  of multi-octets data in this message, where 0 for littel-endian and 1 for big-endian.

• template => template for unpack

  used to convert the binary data to an array of Perl representations.

• i_field name => offset in data array

  of the value(s) of the field named field name.

• o_field_name => offset in binary data

  of the value(s) of the field named field name.

• c_field_name => the number of values

  of the field named field name.

• s_field_name => size in octets

  of whole the field named field name in binary data.

• a_field name => reference to a hash

  of attributes of the field named field name.

• t_field name => type name

  only if the type of the value of the field named field name has a name.

• T_field name => a number

  representing base type of the value of the field named field name.

• N_field name => a number

  representing index of the filed named field name in the global .FIT profile.

• I_field name => a number

  representing the invalid value of the field named field name, that is, if the value of the field in a binary datum equals to this number, the field must be treated as though it does not exist in the datum.

• endian_converter => reference to an array

  used for endian conversion.

• message_length => length of binary data

  in octets.

• array_length => length of data array

  of Perl representations.

Callback function

When fetch method meets a data message, it calls a callback function registered with data_message_callback_by_name or data_message_callback_by_num, in the form

• callback function->(object, data message descriptor, array of field values, callback data, ...).

  The return value of the function becomes the return value of fetch. It is expected to be 1 on success, or undef on failure status.

Developer data

Fields in devloper data are given names of the form developer data index_field definition number_converted field name, and related informations are included data message descriptors in the same way as the fields defined in the global .FIT profile.

Each converted field name is made from the value of field_name field in the corresponding field description message, after the following conversion rules:

• (1) Each sequence of space characters is converted to single _.
• (2) Each of remaining non-word-constituend characters is converted to _ + 2 column hex representation of ord() of the character + _.

64bit data

If your perl lacks 64bit integer support, you need the module Math::BigInt.

DEPENDENCIES

Nothing in particular so far.

SEE ALSO

Geo::TCX

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-geo-gpx@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Originally written by Kiyokazu Suto suto@ks-and-ks.ne.jp with contributions by Matjaz Rihtar.

This version is maintained by Patrick Joly <patjol@cpan.org>.

Please visit the project page at: https://github.com/patjoly/geo-fit.

VERSION

1.05

LICENSE AND COPYRIGHT

Copyright 2022, Patrick Joly patjol@cpan.org. All rights reserved.

Copyright 2016-2022, Kiyokazu Suto suto@ks-and-ks.ne.jp. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.