0.10 -> 0.11
0.09 -> 0.10
0.08 -> 0.09
0.07 -> 0.08
0.06 -> 0.07
0.05 -> 0.06
0.04 -> 0.05
0.03 -> 0.04
0.02 -> 0.03
0.01 -> 0.02

NAME

Garmin::FIT - A Perl class to decode Garmin .FIT files

SYNOPSIS

  use Garmin::FIT;
  Garmin::FIT->version_string;
  $fit = new Garmin::FIT;
  $fit->unit_table(<unit> => <unit conversion table>);
  $fit->semicircles_to_degree(<boolean>);
  $fit->mps_to_kph(<boolean>);
  $fit->use_gmtime(<boolean>);
  $fit->file(<file name>)
  $fit->open;
  $fit->fetch_header;
  $fit->fetch;
  $fit->protocol_version_string;
  $fit->protocol_version_string(<version number>);
  $fit->profile_version_string;
  $fit->profile_version_string(<version number>);
  $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->switched(<data message descriptor>, <array of values>, <data type table>);
  $fit->string_value(<array of values>, <offset in the array>, <counts>);
  $fit->value_cooked(<type name>, <field attributes table>, <invalid data>, <value>);
  $fit->error;
  $fit->crc_expected;
  $fit->crc;
  $fit->trailing_garbages;
  $fit->close;
  ...

DESCRIPTION

Garmin::FIT is a Perl class to provide interfaces to decode Garmin .FIT files.

The latest version is obtained via

GarminFIT-0.11.tar.gz (21KB, 2012-09-17 13:59:45).

There are three applications

fitdump,

fitsed,

and

fit2tcx

using this class.

Constants

Following constants are automatically exported.

FIT_ENUM
FIT_SINT8
FIT_UINT8
FIT_SINT16
FIT_UINT16
FIT_SINT32
FIT_UINT32
FIT_STRING
FIT_FLOAT16
FIT_FLOAT32
FIT_UINT8Z
FIT_UINT16Z
FIT_UINT32Z
FIT_BYTE: numbers representing types of field values in data messages.
FIT_HEADER_LENGTH: length of a .FIT file header.

Class methods

Garmin::FIT->version_string: returns a string representing the version of this class.
new Garmin::FIT: creates a new object and returns it.
Garmin::FIT->message_name(<message spec>): returns the message name for <message spec> or undef.
Garmin::FIT->message_number(<message spec>): returns the message number for <message spec> or undef.
Garmin::FIT->field_name(<message spec>, <field spec>): returns the field name for <field spec> in <message spec> or undef.
Garmin::FIT->field_number(<message spec>, <field spec>): returns the field index for <field spec> in <message spec> or undef.
Garmin::FIT->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.
Garmin::FIT->crc_of_string(<old CRC>, <reference to a scalar>, <offset in scalar>, <counts>): calculate CRC-16 of the specified part of the scalar.
Garmin::FIT->my_endian: returns the endian (0 for little endian and 1 for big endian) of the machine on which this program is running.

Object methods

<object>->unit_table(<unit> => <unit conversion table>): sets <unit conversion table> for <unit>.
<object>->semicircles_to_degree(<boolean>): a wrapper method of unit_table() method.
<object>->mps_to_kph(<boolean>): ditto.
<object>->use_gmtime(<boolean>): sets the flag which of GMT or local timezone is used for date_time type value conversion.
<object>->file(<file name>): sets the name <file name> of a .FIT file.
<object>->open: opens the .FIT file.
<object>->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.
<object>->fetch: reads a message in the .FIT file, and returns 1 on success, or undef on failure or EOF.
<object>->protocol_version_string: returns a string representing the .FIT protocol version on which this class based.
<object>->protocol_version_string(<version number>): returns a string representing the .FIT protocol version <version number>.
<object>->profile_version_string: returns a string representing the .FIT protocol version on which this class based.
<object>->profile_version_string(<version number>): returns a string representing the .FIT profile version <version number>.
<object>->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.
<object>->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.
<object>->switched(<data message descriptor>, <array of values>, <data type table>): returns real data type attributes for a C's union like field.
<object>->string_value(<array of values>, <offset in the array>, <counts>): converts an array of character codes to a Perl string.
<object>->value_cooked(<type name>, <field attributes table>, <invalid>, <value>): converts <value> to a (hopefully) human readable form.
<object>->value_uncooked(<type name>, <field attributes table>, <invalid>, <value representation>): converts a human readable representation of a datum to an original form.
<object>->error: returns an error message recorded by a method.
<object>->crc_expected: CRC-16 attached to the end of a .FIT file. Only available after all contents of the file has been read.
<object>->crc: CRC-16 calculated from the contents of a .FIT file.
<object>->trailing_garbages: number of octets after CRC-16, 0 usually.
<object>->close: closes opened file handles.
<object>->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.
<object>->endian_convert(<endian converter>, <reference to a scalar>, <offset in the scalar>): apply <endian converter> to the specified part of the scalar.

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 I<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.

AUTHOR

Kiyokazu SUTO <suto@ks-and-ks.ne.jp>

DISCLAIMER etc.

This program is distributed with ABSOLUTELY NO WARRANTY.

Anyone can use, modify, and re-distibute this program without any restriction.

ACKNOWLEDGEMENT

The author is very grateful to Garmin for supplying us free software programers with .FIT SDK which includes detailed documetation about its proprietary file format.

CHANGES

0.10 --> 0.11

profile_version
%named_type
%msgtype_by_name: follow global profile version 4.10.

0.09 --> 0.10

profile_version
%named_type
%msgtype_by_name: follow global profile version 2.00.

0.08 --> 0.09

profile_version: was calculated from wrong string expression.
profile_version_from_string(): should use profile_version_scale instead of profile_version_major_shift.
fetch_header(): calculate and return header CRCs only for proper protocol version.
cat_header(): support header CRCs and extra data in a file header.
msgtype_by_name->{session}->{35}: scale attribute was missing.
msgtype_by_name->{session}->{36}: ditto.

0.07 --> 0.08

protocol_version
profile_version
fetch_header()
%named_type
%msgtype_by_name
%msgtype_by_num: follow protocol version 1.2 and global profile version 1.50.

0.06 --> 0.07

profile_version: major and minor parts should be computed by division with scale 100, not bit shift.
error(): .FIT file name is included in each error message.
fetch_header(): header length of .FIT files of newer profile version, may differ from 12. Thanks to report from Nils Knieling.

0.05 --> 0.06

initialize(): the member buffer of an object must be initialzied with a reference to a scalar, not the scalar itself. Thanks to report from Nils Knieling.

0.04 --> 0.05

$version
$version_major_scale
@version
$my_endian
$protocol_version_major_shift
$protocol_version_minor_mask
$protocol_version
@protocol_version
$profile_version_major_shift
$profile_version_minor_mask
$profile_version
@profile_version
@crc_table
$header_template
$header_length
$FIT_signature_string
$FIT_signature
$rechd_offset_compressed_timestamp_header
$rechd_mask_compressed_timestamp_header
$rechd_offset_cth_local_message_type
$rechd_length_cth_local_message_type
$rechd_mask_cth_local_message_type
$rechd_length_cth_timestamp
$rechd_mask_cth_timestamp
$rechd_offset_definition_message
$rechd_mask_definition_message
$rechd_length_local_message_type
$rechd_mask_local_message_type
$cthd_offset_local_message_type
$cthd_length_local_message_type
$cthd_mask_local_message_type
$cthd_length_time_offset
$cthd_mask_time_offset
$defmsg_min_template
$defmsg_min_length
$deffld_template
$deffld_length
$deffld_mask_endian_p
$deffld_mask_type
@invalid
@size
@template
%named_type
$use_gmtime
%msgtype_by_name
$mesg_name_vs_num
%msgtype_by_num
$msgnum_anon
$msgname_anon
@type_name: must be global scope, otherwise they can be collected as garbages after long time run. Thanks to reports and tests by Nils Knieling.
fetch_header(): backslashs in error messages should be quoted.

0.03 --> 0.04

use_gmtime(): works as a class method too.
msgtype_by_name->{file_id}->{2}: new member type_name with value garmin_product.
msgtype_by_name->{device_info}->{4}: ditto.
msgtype_by_name->{schedule}->{1}: ditto.
msgtype_by_name->{event}->{data16}->{2}->{switch}->{course_point}: fix wrong member name when --> name.
msgtype_by_name->{event}->{data}->{2}->{switch}->{course_point}: ditto.
data_message_callback_by_num(): save callback data in the form of new array reference instead of reference to @_.
data_message_callback_by_name(): ditto.
open(): make $FH binary mode. Thanks to reports and tests on Windows platform by Nils Knieling.