# Garmin - FIT Python SDK
## FIT SDK Documentation
The FIT SDK documentation is available at [https://developer.garmin.com/fit](https://developer.garmin.com/fit).
## FIT SDK Developer Forum
Share your knowledge, ask questions, and get the latest FIT SDK news in the [FIT SDK Developer Forum](https://forums.garmin.com/developer/).
## FIT Python SDK Requirements
* [Python](https:##www.python.org/downloads/) Version 3.6 or greater is required to run the FIT Python SDK
## Install
```sh
pip install garmin-fit-sdk
```
## Usage
```py
from garmin_fit_sdk import Decoder, Stream
stream = Stream.from_file("Activity.fit")
decoder = Decoder(stream)
messages, errors = decoder.read()
print(errors)
print(messages)
```
## Decoder
### Constructor
Creating Decoder objects requires an input Stream representing the binary FIT file data to be decoded. See [Creating Streams](#creatingstreams) for more information on constructing Stream objects.
Once a Decoder object is created it can be used to check that the Stream is a FIT file, that the FIT file is valid, and to read the contents of the FIT file.
### is_fit Method
All valid FIT files should include a 12 or 14 byte file header. The 14 byte header is the preferred header size and the most common size used. Bytes 8-11 of the header contain the ASCII values ".FIT". This string can easily be spotted when opening a binary FIT file in a text or hex editor.
```
Offset: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00000000: 0E 10 43 08 78 06 09 00 2E 46 49 54 96 85 40 00 ..C.x....FIT..@.
00000010: 00 00 00 07 03 04 8C 04 04 86 07 04 86 01 02 84 ................
00000020: 02 02 84 05 02 84 00 01 00 00 19 28 7E C5 95 B0 ...........(~E.0
```
### check_integrity Method
The checkIntegrity method performs three checks on a FIT file:
1. Checks that bytes 8-11 of the header contain the ASCII values ".FIT".
2. Checks that the total file size is equal to Header Size + Data Size + CRC Size.
3. Reads the contents of the file, computes the CRC, and then checks that the computed CRC matches the file CRC.
A file must pass all three of these tests to be considered a valid FIT file. See the [IsFIT(), CheckIntegrity(), and Read() Methods recipe](/fit/cookbook/isfit-checkintegrity-read/) for use-cases where the checkIntegrity method should be used and cases when it might be better to avoid it.
#### Read Method
The Read method decodes all messages from the input stream and returns an object containing a list of errors encountered during the decoding and a dictionary of decoded messages grouped by message type. Any exceptions encountered during decoding will be caught by the Read method and added to the list of errors.
The Read method accepts an optional options object that can be used to customize how field data is represented in the decoded messages. All options are enabled by default. Disabling options may speed up file decoding. Options may also be enabled or disable based on how the decoded data will be used.
```py
messages, errors = read(
apply_scale_and_offset = True,
convert_datetimes_to_dates = True,
convert_types_to_strings = True,
enable_crc_check = True,
expand_sub_fields = True,
expand_components = True,
merge_heart_rates = True,
mesg_listener = None)
```
#### mesg_listener
Optional callback function that can be used to inspect or manipulate messages after they are fully decoded and all the options have been applied. The message is mutable and we be returned from the Read method in the messages dictionary.
Example mesg_listener callback that tracks the field names across all Record messages.
```py
from garmin_fit_sdk import Decoder, Stream, Profile
stream = Stream.from_file("Activity.fit")
decoder = Decoder(stream)
record_fields = set()
def mesg_listener(mesg_num, message):
if mesg_num == Profile['mesg_num']['RECORD']:
for field in message:
record_fields.add(field)
messages, errors = decoder.read(mesg_listener = mesg_listener)
if len(errors) > 0:
print(f"Something went wrong decoding the file: {errors}")
return
print(record_fields)
```
#### apply_scale_and_offset: true | false
When true the scale and offset values as defined in the FIT Profile are applied to the raw field values.
```py
{
'altitude': 1587 ## with a scale of 5 and offset of 500 applied
}
```
When false the raw field value is used.
```py
{
'altitude': 10435 ## raw value store in file
}
```
#### enable_crc_check: true | false
When true the CRC of the file is calculated when decoding a FIT file and then validated with the CRC found in the file. Disabling the CRC calculation will improve the performance of the read method.
#### expand_sub_fields: true | false
When true subfields are created for fields as defined in the FIT Profile.
```py
{
'event': 'rear_gear_change',
'data': 16717829,
'gear_change_data':16717829 ## Sub Field of data when event == 'rear_gear_change'
}
```
When false subfields are omitted.
```py
{
'event': 'rearGearChange',
'data': 16717829
}
```
#### expand_components: true | false
When true field components as defined in the FIT Profile are expanded into new fields. expand_sub_fields must be set to true in order for subfields to be expanded
```py
{
'event': 'rear_gear_change'
'data': 16717829,
'gear_change_data':16717829, ## Sub Field of data when event == 'rear_gear_change'
'front_gear': 2, ## Expanded field of gear_change_data, bits 0-7
'front_gear_num': 53, ## Expanded field of gear_change_data, bits 8-15
'rear_gear': 11, ## Expanded field of gear_change_data, bits 16-23
'rear_gear_num': 1, ## Expanded field of gear_change_data, bits 24-31
}
```
When false field components are not expanded.
```py
{
'event': 'rear_gear_change',
'data': 16717829,
'gear_change_data': 16717829 ### Sub Field of data when event == 'rear_gear_change'
}
```
#### convert_types_to_strings: true | false
When true field values are converted from raw integer values to the corresponding string values as defined in the FIT Profile.
```py
{ 'type':'activity'}
```
When false the raw integer value is used.
```py
{ 'type': 4 }
```
#### convert_datetimes_to_dates: true | false
When true FIT Epoch values are converted to Python datetime objects.
```py
{ 'time_created': {Python datetime object} }
```
When false the FIT Epoch value is used.
```py
{ 'time_created': 995749880 }
```
When false the Util.convert_timestamp_to_datetime method may be used to convert FIT Epoch values to Python datetime objects.
#### merge_heart_rates: true | false
When true automatically merge heart rate values from HR messages into the Record messages. This option requires the apply_scale_and_offset and expand_components options to be enabled. This option has no effect on the Record messages when no HR messages are present in the decoded messages.
## Creating Streams
Stream objects contain the binary FIT data to be decoded. Streams objects can be created from bytearrays, BufferedReaders, and BytesIO objects. Internally the Stream class uses a BufferedReader to manage the byte stream.
#### From a file
```py
stream = Stream.from_file("activity.fit")
print(f"is_fit: {Decoder.is_fit(stream)}")
```
#### From a bytearray
```py
fit_byte_array = bytearray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00])
stream = Stream.from_byte_array(fit_byte_array)
print(f"is_fit: {Decoder.is_fit(stream)}")
```
#### From a BytesIO Object
```py
fit_byte_bytes_io = io.BytesIO(bytearray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]))
stream = Stream.from_byte_io(fit_byte_bytes_io)
print(f"is_fit: {Decoder.is_fit(stream)}")
```
#### From a buffered_reader
```py
fit_buffered_reader = io.BufferedReader(io.BytesIO(bytearray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00])))
stream = Stream.from_buffered_reader(fit_buffered_reader)
print(f"is_fit: {Decoder.is_fit(stream)}")
```
## Util
The Util object contains both constants and methods for working with decoded messages and fields.
### FIT_EPOCH_S Constant
The FIT_EPOCH_S constant represents the number of seconds between the Unix Epoch and the FIT Epoch.
```py
FIT_EPOCH_S = 631065600
```
The FIT_EPOCH_S value can be used to convert FIT Epoch values to Python datetime objects.
```py
python_date = datetime.datetime.utcfromtimestamp(fitDateTime + FIT_EPOCH_S)
```
### convert_timestamp_to_datetime Method
A convenience method for converting FIT Epoch values to Python Datetime objects.
```py
python_date = convert_timestamp_to_datetime(fit_datetime)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/garmin/fit-python-sdk",
"name": "garmin-fit-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "garmin, fit sdk, fit",
"author": "Garmin International, Inc.",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cb/03/fd100c98bf8255471d1209d60900c2f097266924e26c9cd11ff3494ab54d/garmin-fit-sdk-21.141.0.tar.gz",
"platform": null,
"description": "# Garmin - FIT Python SDK\n\n## FIT SDK Documentation\nThe FIT SDK documentation is available at [https://developer.garmin.com/fit](https://developer.garmin.com/fit).\n## FIT SDK Developer Forum\nShare your knowledge, ask questions, and get the latest FIT SDK news in the [FIT SDK Developer Forum](https://forums.garmin.com/developer/).\n\n## FIT Python SDK Requirements\n* [Python](https:##www.python.org/downloads/) Version 3.6 or greater is required to run the FIT Python SDK\n\n## Install\n```sh\npip install garmin-fit-sdk\n```\n\n## Usage\n```py\nfrom garmin_fit_sdk import Decoder, Stream\n\nstream = Stream.from_file(\"Activity.fit\")\ndecoder = Decoder(stream)\nmessages, errors = decoder.read()\n\nprint(errors)\nprint(messages)\n```\n\n## Decoder\n\n### Constructor\n\nCreating Decoder objects requires an input Stream representing the binary FIT file data to be decoded. See [Creating Streams](#creatingstreams) for more information on constructing Stream objects.\n\nOnce a Decoder object is created it can be used to check that the Stream is a FIT file, that the FIT file is valid, and to read the contents of the FIT file.\n\n### is_fit Method\n\nAll valid FIT files should include a 12 or 14 byte file header. The 14 byte header is the preferred header size and the most common size used. Bytes 8-11 of the header contain the ASCII values \".FIT\". This string can easily be spotted when opening a binary FIT file in a text or hex editor.\n\n```\n Offset: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F\n00000000: 0E 10 43 08 78 06 09 00 2E 46 49 54 96 85 40 00 ..C.x....FIT..@.\n00000010: 00 00 00 07 03 04 8C 04 04 86 07 04 86 01 02 84 ................\n00000020: 02 02 84 05 02 84 00 01 00 00 19 28 7E C5 95 B0 ...........(~E.0\n```\n\n### check_integrity Method\n\nThe checkIntegrity method performs three checks on a FIT file:\n\n1. Checks that bytes 8-11 of the header contain the ASCII values \".FIT\".\n2. Checks that the total file size is equal to Header Size + Data Size + CRC Size.\n3. Reads the contents of the file, computes the CRC, and then checks that the computed CRC matches the file CRC.\n\nA file must pass all three of these tests to be considered a valid FIT file. See the [IsFIT(), CheckIntegrity(), and Read() Methods recipe](/fit/cookbook/isfit-checkintegrity-read/) for use-cases where the checkIntegrity method should be used and cases when it might be better to avoid it.\n\n#### Read Method\nThe Read method decodes all messages from the input stream and returns an object containing a list of errors encountered during the decoding and a dictionary of decoded messages grouped by message type. Any exceptions encountered during decoding will be caught by the Read method and added to the list of errors.\n\nThe Read method accepts an optional options object that can be used to customize how field data is represented in the decoded messages. All options are enabled by default. Disabling options may speed up file decoding. Options may also be enabled or disable based on how the decoded data will be used.\n\n```py\nmessages, errors = read(\n apply_scale_and_offset = True,\n convert_datetimes_to_dates = True,\n convert_types_to_strings = True,\n enable_crc_check = True,\n expand_sub_fields = True,\n expand_components = True,\n merge_heart_rates = True,\n mesg_listener = None)\n```\n#### mesg_listener\nOptional callback function that can be used to inspect or manipulate messages after they are fully decoded and all the options have been applied. The message is mutable and we be returned from the Read method in the messages dictionary.\n\nExample mesg_listener callback that tracks the field names across all Record messages.\n\n```py\nfrom garmin_fit_sdk import Decoder, Stream, Profile\n\nstream = Stream.from_file(\"Activity.fit\")\ndecoder = Decoder(stream)\n\nrecord_fields = set()\ndef mesg_listener(mesg_num, message):\n if mesg_num == Profile['mesg_num']['RECORD']:\n for field in message:\n record_fields.add(field)\n\nmessages, errors = decoder.read(mesg_listener = mesg_listener)\n\nif len(errors) > 0:\n print(f\"Something went wrong decoding the file: {errors}\")\n return\n\nprint(record_fields)\n```\n\n#### apply_scale_and_offset: true | false\nWhen true the scale and offset values as defined in the FIT Profile are applied to the raw field values.\n```py\n{\n 'altitude': 1587 ## with a scale of 5 and offset of 500 applied\n}\n```\nWhen false the raw field value is used.\n```py\n{\n 'altitude': 10435 ## raw value store in file\n}\n```\n#### enable_crc_check: true | false\nWhen true the CRC of the file is calculated when decoding a FIT file and then validated with the CRC found in the file. Disabling the CRC calculation will improve the performance of the read method.\n#### expand_sub_fields: true | false\nWhen true subfields are created for fields as defined in the FIT Profile.\n```py\n{\n 'event': 'rear_gear_change',\n 'data': 16717829,\n 'gear_change_data':16717829 ## Sub Field of data when event == 'rear_gear_change'\n}\n```\nWhen false subfields are omitted.\n```py\n{\n 'event': 'rearGearChange',\n 'data': 16717829\n}\n```\n#### expand_components: true | false\nWhen true field components as defined in the FIT Profile are expanded into new fields. expand_sub_fields must be set to true in order for subfields to be expanded\n\n```py\n{\n 'event': 'rear_gear_change'\n 'data': 16717829,\n 'gear_change_data':16717829, ## Sub Field of data when event == 'rear_gear_change'\n 'front_gear': 2, ## Expanded field of gear_change_data, bits 0-7\n 'front_gear_num': 53, ## Expanded field of gear_change_data, bits 8-15\n 'rear_gear': 11, ## Expanded field of gear_change_data, bits 16-23\n 'rear_gear_num': 1, ## Expanded field of gear_change_data, bits 24-31\n}\n```\nWhen false field components are not expanded.\n```py\n{\n 'event': 'rear_gear_change',\n 'data': 16717829,\n 'gear_change_data': 16717829 ### Sub Field of data when event == 'rear_gear_change'\n}\n```\n#### convert_types_to_strings: true | false\nWhen true field values are converted from raw integer values to the corresponding string values as defined in the FIT Profile.\n```py\n{ 'type':'activity'}\n```\nWhen false the raw integer value is used.\n```py\n{ 'type': 4 }\n```\n#### convert_datetimes_to_dates: true | false\nWhen true FIT Epoch values are converted to Python datetime objects.\n```py\n{ 'time_created': {Python datetime object} }\n```\nWhen false the FIT Epoch value is used.\n```py\n{ 'time_created': 995749880 }\n```\nWhen false the Util.convert_timestamp_to_datetime method may be used to convert FIT Epoch values to Python datetime objects.\n#### merge_heart_rates: true | false\nWhen true automatically merge heart rate values from HR messages into the Record messages. This option requires the apply_scale_and_offset and expand_components options to be enabled. This option has no effect on the Record messages when no HR messages are present in the decoded messages.\n\n## Creating Streams\nStream objects contain the binary FIT data to be decoded. Streams objects can be created from bytearrays, BufferedReaders, and BytesIO objects. Internally the Stream class uses a BufferedReader to manage the byte stream.\n\n#### From a file\n```py\nstream = Stream.from_file(\"activity.fit\")\nprint(f\"is_fit: {Decoder.is_fit(stream)}\")\n```\n#### From a bytearray\n```py\nfit_byte_array = bytearray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00])\nstream = Stream.from_byte_array(fit_byte_array)\nprint(f\"is_fit: {Decoder.is_fit(stream)}\")\n```\n#### From a BytesIO Object\n```py\nfit_byte_bytes_io = io.BytesIO(bytearray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]))\nstream = Stream.from_byte_io(fit_byte_bytes_io)\nprint(f\"is_fit: {Decoder.is_fit(stream)}\")\n```\n#### From a buffered_reader\n```py\nfit_buffered_reader = io.BufferedReader(io.BytesIO(bytearray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00])))\nstream = Stream.from_buffered_reader(fit_buffered_reader)\nprint(f\"is_fit: {Decoder.is_fit(stream)}\")\n```\n\n## Util\nThe Util object contains both constants and methods for working with decoded messages and fields.\n### FIT_EPOCH_S Constant\nThe FIT_EPOCH_S constant represents the number of seconds between the Unix Epoch and the FIT Epoch.\n```py\nFIT_EPOCH_S = 631065600\n```\nThe FIT_EPOCH_S value can be used to convert FIT Epoch values to Python datetime objects.\n```py\npython_date = datetime.datetime.utcfromtimestamp(fitDateTime + FIT_EPOCH_S)\n```\n### convert_timestamp_to_datetime Method\nA convenience method for converting FIT Epoch values to Python Datetime objects.\n```py\npython_date = convert_timestamp_to_datetime(fit_datetime)\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Garmin FIT Python SDK",
"version": "21.141.0",
"project_urls": {
"Homepage": "https://github.com/garmin/fit-python-sdk"
},
"split_keywords": [
"garmin",
" fit sdk",
" fit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b29a7be64037ccf525d7f9116da9da4b5966929c8543104d49cb0d52aa5842f6",
"md5": "f713d8187baa09e3daf1f48e701efd94",
"sha256": "19e7c134f85bbcc9ca55013b6410cd9620ababed9944459e787a04f0f5be8f09"
},
"downloads": -1,
"filename": "garmin_fit_sdk-21.141.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f713d8187baa09e3daf1f48e701efd94",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 233730,
"upload_time": "2024-05-13T20:33:31",
"upload_time_iso_8601": "2024-05-13T20:33:31.083839Z",
"url": "https://files.pythonhosted.org/packages/b2/9a/7be64037ccf525d7f9116da9da4b5966929c8543104d49cb0d52aa5842f6/garmin_fit_sdk-21.141.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb03fd100c98bf8255471d1209d60900c2f097266924e26c9cd11ff3494ab54d",
"md5": "fd1fc544a8f830da84f65ac63bff86f1",
"sha256": "0c536c4852aaaadf7a6bd87def8960597679bd31371dbbbd27a5930a14cde78b"
},
"downloads": -1,
"filename": "garmin-fit-sdk-21.141.0.tar.gz",
"has_sig": false,
"md5_digest": "fd1fc544a8f830da84f65ac63bff86f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 228765,
"upload_time": "2024-05-13T20:33:33",
"upload_time_iso_8601": "2024-05-13T20:33:33.049604Z",
"url": "https://files.pythonhosted.org/packages/cb/03/fd100c98bf8255471d1209d60900c2f097266924e26c9cd11ff3494ab54d/garmin-fit-sdk-21.141.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-13 20:33:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "garmin",
"github_project": "fit-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": [
[
"~=",
"7.0.1"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"~=",
"3.0.0"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
"~=",
"3.6.1"
]
]
}
],
"lcname": "garmin-fit-sdk"
}
JSON
