Metadata-Version: 2.1
Name: pygarmin
Version: 1.0.3
Summary: A Python interface to older Garmin GPS equipment
Home-page: http://github.com/quentinsf/pygarmin
Author: Folkert van der Beek
License: GNU General Public License version 3
Project-URL: Homepage, https://github.com/quentinsf/pygarmin
Project-URL: Bug Tracker, https://github.com/quentinsf/pygarmin/issues
Keywords: garmin,gps
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Utilities
Requires-Python: >=3.8
License-File: LICENSE

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 emacs-zotero 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

Background
----------

PyGarmin 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
   # (This may take a little while)
   waypoints = gps.get_waypoints()

   # Get the tracks from the GPS
   # (This may take a little while)
   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, waypoint.get_smbl())

   # 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],
               'smbl': 8236}
   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.

More details
------------

There are 3 levels of protocol documented:

============= =========
 Layer         Level
============= =========
 Application   highest
 Link
 Physical      lowest
============= =========

The specification documents the various different versions of these
under labels of Pxxx, Lxxx, Axxx etc, where xxx is a number, and this
convention is followed in the code. There are also various data types,
named Dxxx. Roughly speaking, the Physical protocols specify RS232, the
Link protocols specify a packet structure for sending messages to and
fro, and the Application protocols specify what can actually go in those
packets.

For example, a Garmin GPS 38 will talk to your computer over physical
layer P000 (RS232) using a packet structure defined by link layer L001.
If you want to transfer waypoints to and from it, they will be sent
using application layer A100 (a waypoint transfer protocol), and the
actual waypoints transferred will be of type D100.

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