PyGarmin
========
.. figure:: pygarmin.png
:alt: PyGarmin
The **Pygarmin** distribution provides a `Python <https://www.python.org/>`_
module and a command line application that implement the protocol used by
`Garmin <https://www.garmin.com/>`_ GPS devices. It is based on the official
`protocol specification <https://www8.garmin.com/support/commProtocol.html>`_.
Documentation
-------------
For API documentation, usage and examples see the files in the ``docs``
directory. The documentation is also hosted on `Read the Docs
<https://pygarmin.readthedocs.io/en/latest/>`_.
Installing
----------
You can install Pygarmin with ``pip`` as follows:
.. code-block:: console
$ pip install pygarmin
Or to upgrade to the most recent version:
.. code-block:: console
$ pip install pygarmin --upgrade
To follow or contribute to pygarmin development, you can browse or clone the Git
repository `on Github <https://github.com/quentinsf/pygarmin>`_:
.. code-block:: console
$ git clone https://github.com/quentinsf/pygarmin.git
And install the requirements using the below command:
.. code-block:: console
$ pip install -r requirements.txt
Pygarmin application
====================
Description
-----------
*Pygarmin* is a command line application that can retrieve data from and
transfer data to a Garmin GPS device connected by a serial or USB port.
The port is specified with the -p PORT option. To communicate with a Garmin GPS
serially, use the name of that serial port such as /dev/ttyUSB0, /dev/cu.serial,
or COM1. To communicate via USB use usb: as the port on all OSes. For this to
work on GNU/Linux, you probably should remove and blacklist the ``garmin_gps``
kernel module. Some protocols won't work at all with a serial connection, like
the transfer of images and maps. So your best bet is to use the internal USB
support.
The functionality is split into a number of sub-commands, like ``pygarmin info``
to return a product description, ``pygarmin get-waypoints`` to download the
waypoints, and ``pygarmin put-map`` to upload a new map.
Examples
--------
Show help message::
pygarmin --help
Show help on the ``get-almanac`` command::
pygarmin get-almanac -h
Show product description with debugging enabled::
pygarmin --debug info
Show information on the currently installed maps, use the serial port and be very verbose::
pygarmin -p /dev/ttyUSB0 -vv map
Download all waypoints in gpx format to the file waypoints.gpx::
pygarmin get-waypoints waypoints.gpx -t gpx
Print real-time position, velocity, and time (PVT) to stdout::
pygarmin pvt -t tpv
List the images types::
pygarmin get-image-types
List all images::
pygarmin get-image-list
Download all images and save them according to the given filename pattern::
pygarmin get-image ~/icons/waypoint%03d.png
Download the images with index 1, 2, and 3 and save them as PNG files with the default filenames to the current directory::
pygarmin get-image -t png -i 1 2 3
Upload an image as a custom waypoint symbol with index 1, and don't show the progress bar::
pygarmin --no-progress put-image Waypoint\ Symbol\ 000.bmp -i 1
Download the currently installed map from the device and save it as "*gmapsupp.img*" to the current directory::
pygarmin get-map
Upload the map "*gmapsupp.img*"::
pygarmin put-map gmapsupp.img
Garmin module
=============
The *garmin module* is a set of `Python <https://www.python.org/>`__ classes which
implement the protocol used by `Garmin <https://www.garmin.com/>`__ GPS
receivers to talk to each other and to other machines. It is based on the
official `protocol specification
<https://www8.garmin.com/support/commProtocol.html>`__. The project was started
by `Quentin Stafford-Fraser <https://quentinsf.com/software/pygarmin/>`__ but
several others have helped to make it what it is today.
PyGarmin has been used to transfer information to and from several different
Garmin receivers, mostly under Linux, though there is some Windows support now
and people have used it on Mac OS X as well. If you use PyGarmin, it will
probably be much quicker than writing your own software from scratch.
Basics
------
Almost every model of Garmin receiver implements a slightly different protocol.
They have many things in common, but there are minor differences. The class
``garmin.Garmin`` will create instances of the appropriate protocol classes and
notes the datatype classes for each type of data used in the transmissions. It
also has some friendly methods like ``get_waypoints()``, which do what you would
expect. What you get back when you call this is a list of objects, each of which
is a child the ``garmin.Wpt`` class.
Example Code
------------
Here’s a simple Python program:
.. code-block:: python
#!/usr/bin/env python3
import logging
from garmin import garmin
log = logging.getLogger('garmin')
log.addHandler(logging.StreamHandler())
log.setLevel(logging.INFO)
# Create a 'physical layer' connection using serial port
phys = garmin.SerialLink('/dev/ttyUSB0')
# ...or using USB
phys = garmin.USBLink()
# Create a Garmin object using this connection
gps = garmin.Garmin(phys)
# Get the waypoints from the GPS
waypoints = gps.get_waypoints()
# Get the tracks from the GPS
tracks = gps.get_tracks()
# Print the waypoints
print("Waypoints:")
for waypoint in waypoints:
posn = waypoint.get_posn()
degrees = posn.as_degrees()
lat = degrees.lat
lon = degrees.lon
print(waypoint.ident, lat, lon, waypoint.cmnt)
# Print the tracks
print("Tracks:")
for track in tracks:
print(track)
# Put a new waypoint
print("Upload a new waypoint:")
waypoint = {'ident': 'CHURCH',
'cmnt': 'LA SAGRADA FAMILIA',
'posn': [493961671, 25937164]}
gps.put_waypoints(waypoint)
This should work for most models, because all waypoints will have an identity, a
position (latitude and longitude), and a comment field. The latitude and
longitude are transferred as ‘semicircle’ coordinates (basically degrees, but
scaled to fill a signed long integer). The static method
``Position.to_degrees()`` converts a semicircle integer into a degree float and
the ``as_degrees()`` method converts a Position into a DegreePosition data type.
License
=======
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, version 3.
In the past, it has been released under the GNU General Public License
version 2, and some contributions have been made under that license. You
may use it under the terms of the GPLv2 if you prefer.
Acknowledgements
================
Thanks are due to, amongst others:
- `Quentin Stafford-Fraser <https://quentinsf.com/>`__
- James Skillen
- `Bjorn Tillenius <http://tillenius.me/>`__
- Hyrum K. Wright
- Cedric Dutoit
- Folkert van der Beek (for a major rewrite in Dec 2022)
and probably others, to whom our apologies!
The logo was designed by `Quentin
Stafford-Fraser <https://quentinsf.com/>`__
Changelog
=========
[1.1.2] 2023-12-27
------------------
- Fix GPX export of Garmin Forerunner 305 tracks
[1.1.1] 2023-12-26
------------------
- Use the same license (GPLv2 or later) for the package as the source
[1.1.0] 2023-12-26
------------------
- Support Garmin Forerunner 305
- Support images of different color depths
- Various bugfixes
[1.0.5] 2023-11-22
------------------
- Fix relative package import (PR #7)
[1.0.4] 2022-12-23
------------------
- Improve documentation
- Add usage of pygarmin application to project description
[1.0.3] 2022-12-23
------------------
- Fix project description
[1.0.2] 2022-12-22
------------------
- Host documentation on Read the Docs
.. _section-1:
[1.0.1] 2022-12-21
------------------
- Made the pygarmin script a submodule
- Improved docstrings
- Switched from Markdown to ReStructuredText
- Added documentation using Sphinx
.. _section-2:
[1.0]
-----
- Improved coding style to conform to the PEP8 style guide
- Improved logging
- Improved docstrings
- Used a factory method to create objects
- Used the new PyUSB 1.0 API
- Used f-strings instead of %-formatting
- Used the rawutil module instead of a customized struct
- Implemented unit ID request
- Added support for baudrate change
- Added support for proximity waypoints transfer
- Added support for waypoint category transfer
- Added support for position initialization
- Added support for maps
- Added support for image transfer (screenshots and waypoint symbols)
- Added support for screenshots
- Removed test code (because I believe this belongs outside the main
module)
- Rewritten pygarmin to a fairly complete command-line program
.. _section-3:
[0.8]
-----
- Used pyserial for serial communication
- Added debian package support
- Added support for flightbook
- Added support for laps
- Added support for runs
- Added support for USB devices
- Migrated to python3
.. _section-4:
[0.7]
-----
- Fixed various bugs
- Brought up to date with CVS (the tarball had become very dated)
- Patches for recent pythons on Win32
- JAHS’s mods - callback, debug etc
- See CVS logs for more details
.. _section-5:
[0.6]
-----
- Fixed various bugs
- Tidier SerialLink code
- Runs under Python 1.5.2
- More debugging available if wanted
.. _section-6:
[0.5]
-----
- Added a datum-conversion module.
- Added Raymond Penners’ Win32SerialLink stuff and timeout stuff
- A900 support
- A800 support (for real-time data)
- Waypoints now have **repr**, **str** and getDict methods
- The ‘pygarmin’ app has some facilities to output XML, using the new
xmlwriter module
.. _section-7:
[0.4]
-----
- Various bug fixes and minor changes. See CVS logs for details
.. _section-8:
[0.3]
-----
- Some changes to newstruct to fix bugs and make it work with Python
1.5.1
- Added TrackHdr class to fix protocol D310
.. _section-9:
[0.2]
-----
- Incorporated James Skillen’s improvements to support protocol A001
for newer Garmin units
- Updated the tables based on new spec
.. _section-10:
[0.1]
-----
- Initial release
Raw data
{
"_id": null,
"home_page": "http://github.com/quentinsf/pygarmin",
"name": "pygarmin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "garmin,gps",
"author": "Folkert van der Beek",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/85/a7/17a19fa987049179f5d48fd7e20d4cee25f97c347a59209087eba63e9f44/pygarmin-1.1.2.tar.gz",
"platform": null,
"description": "PyGarmin\n========\n\n.. figure:: pygarmin.png\n :alt: PyGarmin\n\nThe **Pygarmin** distribution provides a `Python <https://www.python.org/>`_\nmodule and a command line application that implement the protocol used by\n`Garmin <https://www.garmin.com/>`_ GPS devices. It is based on the official\n`protocol specification <https://www8.garmin.com/support/commProtocol.html>`_.\n\nDocumentation\n-------------\n\nFor API documentation, usage and examples see the files in the ``docs``\ndirectory. The documentation is also hosted on `Read the Docs\n<https://pygarmin.readthedocs.io/en/latest/>`_.\n\nInstalling\n----------\n\nYou can install Pygarmin with ``pip`` as follows:\n\n.. code-block:: console\n\n $ pip install pygarmin\n\nOr to upgrade to the most recent version:\n\n.. code-block:: console\n\n $ pip install pygarmin --upgrade\n\nTo follow or contribute to pygarmin development, you can browse or clone the Git\nrepository `on Github <https://github.com/quentinsf/pygarmin>`_:\n\n.. code-block:: console\n\n $ git clone https://github.com/quentinsf/pygarmin.git\n\nAnd install the requirements using the below command:\n\n.. code-block:: console\n\n $ pip install -r requirements.txt\n\nPygarmin application\n====================\n\nDescription\n-----------\n\n*Pygarmin* is a command line application that can retrieve data from and\ntransfer data to a Garmin GPS device connected by a serial or USB port.\n\nThe port is specified with the -p PORT option. To communicate with a Garmin GPS\nserially, use the name of that serial port such as /dev/ttyUSB0, /dev/cu.serial,\nor COM1. To communicate via USB use usb: as the port on all OSes. For this to\nwork on GNU/Linux, you probably should remove and blacklist the ``garmin_gps``\nkernel module. Some protocols won't work at all with a serial connection, like\nthe transfer of images and maps. So your best bet is to use the internal USB\nsupport.\n\nThe functionality is split into a number of sub-commands, like ``pygarmin info``\nto return a product description, ``pygarmin get-waypoints`` to download the\nwaypoints, and ``pygarmin put-map`` to upload a new map.\n\nExamples\n--------\n\nShow help message::\n\n pygarmin --help\n\nShow help on the ``get-almanac`` command::\n\n pygarmin get-almanac -h\n\nShow product description with debugging enabled::\n\n pygarmin --debug info\n\nShow information on the currently installed maps, use the serial port and be very verbose::\n\n pygarmin -p /dev/ttyUSB0 -vv map\n\nDownload all waypoints in gpx format to the file waypoints.gpx::\n\n pygarmin get-waypoints waypoints.gpx -t gpx\n\nPrint real-time position, velocity, and time (PVT) to stdout::\n\n pygarmin pvt -t tpv\n\nList the images types::\n\n pygarmin get-image-types\n\nList all images::\n\n pygarmin get-image-list\n\nDownload all images and save them according to the given filename pattern::\n\n pygarmin get-image ~/icons/waypoint%03d.png\n\nDownload the images with index 1, 2, and 3 and save them as PNG files with the default filenames to the current directory::\n\n pygarmin get-image -t png -i 1 2 3\n\nUpload an image as a custom waypoint symbol with index 1, and don't show the progress bar::\n\n pygarmin --no-progress put-image Waypoint\\ Symbol\\ 000.bmp -i 1\n\nDownload the currently installed map from the device and save it as \"*gmapsupp.img*\" to the current directory::\n\n pygarmin get-map\n\nUpload the map \"*gmapsupp.img*\"::\n\n pygarmin put-map gmapsupp.img\n\n\nGarmin module\n=============\n\nThe *garmin module* is a set of `Python <https://www.python.org/>`__ classes which\nimplement the protocol used by `Garmin <https://www.garmin.com/>`__ GPS\nreceivers to talk to each other and to other machines. It is based on the\nofficial `protocol specification\n<https://www8.garmin.com/support/commProtocol.html>`__. The project was started\nby `Quentin Stafford-Fraser <https://quentinsf.com/software/pygarmin/>`__ but\nseveral others have helped to make it what it is today.\n\nPyGarmin has been used to transfer information to and from several different\nGarmin receivers, mostly under Linux, though there is some Windows support now\nand people have used it on Mac OS X as well. If you use PyGarmin, it will\nprobably be much quicker than writing your own software from scratch.\n\nBasics\n------\n\nAlmost every model of Garmin receiver implements a slightly different protocol.\nThey have many things in common, but there are minor differences. The class\n``garmin.Garmin`` will create instances of the appropriate protocol classes and\nnotes the datatype classes for each type of data used in the transmissions. It\nalso has some friendly methods like ``get_waypoints()``, which do what you would\nexpect. What you get back when you call this is a list of objects, each of which\nis a child the ``garmin.Wpt`` class.\n\nExample Code\n------------\n\nHere\u2019s a simple Python program:\n\n.. code-block:: python\n\n #!/usr/bin/env python3\n import logging\n from garmin import garmin\n\n log = logging.getLogger('garmin')\n log.addHandler(logging.StreamHandler())\n log.setLevel(logging.INFO)\n\n # Create a 'physical layer' connection using serial port\n phys = garmin.SerialLink('/dev/ttyUSB0')\n\n # ...or using USB\n phys = garmin.USBLink()\n\n # Create a Garmin object using this connection\n gps = garmin.Garmin(phys)\n\n # Get the waypoints from the GPS\n waypoints = gps.get_waypoints()\n\n # Get the tracks from the GPS\n tracks = gps.get_tracks()\n\n # Print the waypoints\n print(\"Waypoints:\")\n for waypoint in waypoints:\n posn = waypoint.get_posn()\n degrees = posn.as_degrees()\n lat = degrees.lat\n lon = degrees.lon\n print(waypoint.ident, lat, lon, waypoint.cmnt)\n\n # Print the tracks\n print(\"Tracks:\")\n for track in tracks:\n print(track)\n\n # Put a new waypoint\n print(\"Upload a new waypoint:\")\n waypoint = {'ident': 'CHURCH',\n 'cmnt': 'LA SAGRADA FAMILIA',\n 'posn': [493961671, 25937164]}\n gps.put_waypoints(waypoint)\n\nThis should work for most models, because all waypoints will have an identity, a\nposition (latitude and longitude), and a comment field. The latitude and\nlongitude are transferred as \u2018semicircle\u2019 coordinates (basically degrees, but\nscaled to fill a signed long integer). The static method\n``Position.to_degrees()`` converts a semicircle integer into a degree float and\nthe ``as_degrees()`` method converts a Position into a DegreePosition data type.\n\nLicense\n=======\n\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, version 3.\n\nIn the past, it has been released under the GNU General Public License\nversion 2, and some contributions have been made under that license. You\nmay use it under the terms of the GPLv2 if you prefer.\n\nAcknowledgements\n================\n\nThanks are due to, amongst others:\n\n- `Quentin Stafford-Fraser <https://quentinsf.com/>`__\n- James Skillen\n- `Bjorn Tillenius <http://tillenius.me/>`__\n- Hyrum K. Wright\n- Cedric Dutoit\n- Folkert van der Beek (for a major rewrite in Dec 2022)\n\nand probably others, to whom our apologies!\n\nThe logo was designed by `Quentin\nStafford-Fraser <https://quentinsf.com/>`__\n\nChangelog\n=========\n\n[1.1.2] 2023-12-27\n------------------\n\n- Fix GPX export of Garmin Forerunner 305 tracks\n\n[1.1.1] 2023-12-26\n------------------\n\n- Use the same license (GPLv2 or later) for the package as the source\n\n[1.1.0] 2023-12-26\n------------------\n\n- Support Garmin Forerunner 305\n- Support images of different color depths\n- Various bugfixes\n\n[1.0.5] 2023-11-22\n------------------\n\n- Fix relative package import (PR #7)\n\n[1.0.4] 2022-12-23\n------------------\n\n- Improve documentation\n- Add usage of pygarmin application to project description\n\n[1.0.3] 2022-12-23\n------------------\n\n- Fix project description\n\n[1.0.2] 2022-12-22\n------------------\n\n- Host documentation on Read the Docs\n\n.. _section-1:\n\n[1.0.1] 2022-12-21\n------------------\n\n- Made the pygarmin script a submodule\n- Improved docstrings\n- Switched from Markdown to ReStructuredText\n- Added documentation using Sphinx\n\n.. _section-2:\n\n[1.0]\n-----\n\n- Improved coding style to conform to the PEP8 style guide\n- Improved logging\n- Improved docstrings\n- Used a factory method to create objects\n- Used the new PyUSB 1.0 API\n- Used f-strings instead of %-formatting\n- Used the rawutil module instead of a customized struct\n- Implemented unit ID request\n- Added support for baudrate change\n- Added support for proximity waypoints transfer\n- Added support for waypoint category transfer\n- Added support for position initialization\n- Added support for maps\n- Added support for image transfer (screenshots and waypoint symbols)\n- Added support for screenshots\n- Removed test code (because I believe this belongs outside the main\n module)\n- Rewritten pygarmin to a fairly complete command-line program\n\n.. _section-3:\n\n[0.8]\n-----\n\n- Used pyserial for serial communication\n- Added debian package support\n- Added support for flightbook\n- Added support for laps\n- Added support for runs\n- Added support for USB devices\n- Migrated to python3\n\n.. _section-4:\n\n[0.7]\n-----\n\n- Fixed various bugs\n- Brought up to date with CVS (the tarball had become very dated)\n- Patches for recent pythons on Win32\n- JAHS\u2019s mods - callback, debug etc\n- See CVS logs for more details\n\n.. _section-5:\n\n[0.6]\n-----\n\n- Fixed various bugs\n- Tidier SerialLink code\n- Runs under Python 1.5.2\n- More debugging available if wanted\n\n.. _section-6:\n\n[0.5]\n-----\n\n- Added a datum-conversion module.\n- Added Raymond Penners\u2019 Win32SerialLink stuff and timeout stuff\n- A900 support\n- A800 support (for real-time data)\n- Waypoints now have **repr**, **str** and getDict methods\n- The \u2018pygarmin\u2019 app has some facilities to output XML, using the new\n xmlwriter module\n\n.. _section-7:\n\n[0.4]\n-----\n\n- Various bug fixes and minor changes. See CVS logs for details\n\n.. _section-8:\n\n[0.3]\n-----\n\n- Some changes to newstruct to fix bugs and make it work with Python\n 1.5.1\n- Added TrackHdr class to fix protocol D310\n\n.. _section-9:\n\n[0.2]\n-----\n\n- Incorporated James Skillen\u2019s improvements to support protocol A001\n for newer Garmin units\n- Updated the tables based on new spec\n\n.. _section-10:\n\n[0.1]\n-----\n\n- Initial release\n",
"bugtrack_url": null,
"license": "GNU General Public License version 2 or any later version",
"summary": "A Python interface to older Garmin GPS equipment",
"version": "1.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/quentinsf/pygarmin/issues",
"Homepage": "https://github.com/quentinsf/pygarmin"
},
"split_keywords": [
"garmin",
"gps"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "499e59a4696aa164b230fae3fee2de922257cb12dffe590f81ec6f1d91c9f209",
"md5": "97d16d80812f751610149e420fd43be4",
"sha256": "47f030ea0fc6a2836ff0f3a7e06a8d270054353e6d16751059bb6fbeb78e0038"
},
"downloads": -1,
"filename": "pygarmin-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "97d16d80812f751610149e420fd43be4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 79329,
"upload_time": "2023-12-27T10:34:44",
"upload_time_iso_8601": "2023-12-27T10:34:44.824877Z",
"url": "https://files.pythonhosted.org/packages/49/9e/59a4696aa164b230fae3fee2de922257cb12dffe590f81ec6f1d91c9f209/pygarmin-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "85a717a19fa987049179f5d48fd7e20d4cee25f97c347a59209087eba63e9f44",
"md5": "adf7575510c75ea31a47d4a187f07fd6",
"sha256": "805470942a76033095fa04800a02066daf59dc92a8b19ff842a3031b9364b9f1"
},
"downloads": -1,
"filename": "pygarmin-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "adf7575510c75ea31a47d4a187f07fd6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 83351,
"upload_time": "2023-12-27T10:34:48",
"upload_time_iso_8601": "2023-12-27T10:34:48.759095Z",
"url": "https://files.pythonhosted.org/packages/85/a7/17a19fa987049179f5d48fd7e20d4cee25f97c347a59209087eba63e9f44/pygarmin-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-27 10:34:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quentinsf",
"github_project": "pygarmin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pygarmin"
}
JSON
