Package: pygarmin
PyGarminThePygarmindistribution provides aPythonmodule and a command line application that implement the protocol used byGarminGPS devices. It is based on the officialprotocol specification.DocumentationFor API documentation, usage and examples see the files in thedocsdirectory. The documentation is also hosted onRead the Docs.InstallingYou can install Pygarmin withpipas follows:$pipinstallpygarminOr to upgrade to the most recent version:$pipinstallpygarmin--upgradeTo follow or contribute to pygarmin development, you can browse or clone the Git
repositoryon Github:$gitclonehttps://github.com/quentinsf/pygarmin.gitAnd install the requirements using the below command:$pipinstall-rrequirements.txtPygarmin applicationDescriptionPygarminis 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 thegarmin_gpskernel 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, likepygarmin infoto return a product description,pygarminget-waypointsto download the
waypoints, andpygarminput-mapto upload a new map.ExamplesShow help message:pygarmin --helpShow help on theget-almanaccommand:pygarmin get-almanac -hShow product description with debugging enabled:pygarmin --debug infoShow information on the currently installed maps, use the serial port and be very verbose:pygarmin -p /dev/ttyUSB0 -vv mapDownload all waypoints in gpx format to the file waypoints.gpx:pygarmin get-waypoints waypoints.gpx -t gpxPrint real-time position, velocity, and time (PVT) to stdout:pygarmin pvt -t tpvList the images types:pygarmin get-image-typesList all images:pygarmin get-image-listDownload all images and save them according to the given filename pattern:pygarmin get-image ~/icons/waypoint%03d.pngDownload 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 3Upload 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 1Download the currently installed map from the device and save it as “gmapsupp.img” to the current directory:pygarmin get-mapUpload the map “gmapsupp.img”:pygarmin put-map gmapsupp.imgGarmin moduleThegarmin moduleis a set ofPythonclasses which
implement the protocol used byGarminGPS
receivers to talk to each other and to other machines. It is based on the
officialprotocol specification. The project was started
byQuentin Stafford-Fraserbut
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.BasicsAlmost every model of Garmin receiver implements a slightly different protocol.
They have many things in common, but there are minor differences. The classgarmin.Garminwill 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 likeget_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 thegarmin.Wptclass.Example CodeHere’s a simple Python program:#!/usr/bin/env python3importloggingfromgarminimportgarminlog=logging.getLogger('garmin')log.addHandler(logging.StreamHandler())log.setLevel(logging.INFO)# Create a 'physical layer' connection using serial portphys=garmin.SerialLink('/dev/ttyUSB0')# ...or using USBphys=garmin.USBLink()# Create a Garmin object using this connectiongps=garmin.Garmin(phys)# Get the waypoints from the GPSwaypoints=gps.get_waypoints()# Get the tracks from the GPStracks=gps.get_tracks()# Print the waypointsprint("Waypoints:")forwaypointinwaypoints:posn=waypoint.get_posn()degrees=posn.as_degrees()lat=degrees.latlon=degrees.lonprint(waypoint.ident,lat,lon,waypoint.cmnt)# Print the tracksprint("Tracks:")fortrackintracks:print(track)# Put a new waypointprint("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 methodPosition.to_degrees()converts a semicircle integer into a degree float and
theas_degrees()method converts a Position into a DegreePosition data type.LicenseThis 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.AcknowledgementsThanks are due to, amongst others:Quentin Stafford-FraserJames SkillenBjorn TilleniusHyrum K. WrightCedric DutoitFolkert van der Beek (for a major rewrite in Dec 2022)and probably others, to whom our apologies!The logo was designed byQuentin
Stafford-FraserChangelog[1.1.2] 2023-12-27Fix GPX export of Garmin Forerunner 305 tracks[1.1.1] 2023-12-26Use the same license (GPLv2 or later) for the package as the source[1.1.0] 2023-12-26Support Garmin Forerunner 305Support images of different color depthsVarious bugfixes[1.0.5] 2023-11-22Fix relative package import (PR #7)[1.0.4] 2022-12-23Improve documentationAdd usage of pygarmin application to project description[1.0.3] 2022-12-23Fix project description[1.0.2] 2022-12-22Host documentation on Read the Docs[1.0.1] 2022-12-21Made the pygarmin script a submoduleImproved docstringsSwitched from Markdown to ReStructuredTextAdded documentation using Sphinx[1.0]Improved coding style to conform to the PEP8 style guideImproved loggingImproved docstringsUsed a factory method to create objectsUsed the new PyUSB 1.0 APIUsed f-strings instead of %-formattingUsed the rawutil module instead of a customized structImplemented unit ID requestAdded support for baudrate changeAdded support for proximity waypoints transferAdded support for waypoint category transferAdded support for position initializationAdded support for mapsAdded support for image transfer (screenshots and waypoint symbols)Added support for screenshotsRemoved test code (because I believe this belongs outside the main
module)Rewritten pygarmin to a fairly complete command-line program[0.8]Used pyserial for serial communicationAdded debian package supportAdded support for flightbookAdded support for lapsAdded support for runsAdded support for USB devicesMigrated to python3[0.7]Fixed various bugsBrought up to date with CVS (the tarball had become very dated)Patches for recent pythons on Win32JAHS’s mods - callback, debug etcSee CVS logs for more details[0.6]Fixed various bugsTidier SerialLink codeRuns under Python 1.5.2More debugging available if wanted[0.5]Added a datum-conversion module.Added Raymond Penners’ Win32SerialLink stuff and timeout stuffA900 supportA800 support (for real-time data)Waypoints now haverepr,strand getDict methodsThe ‘pygarmin’ app has some facilities to output XML, using the new
xmlwriter module[0.4]Various bug fixes and minor changes. See CVS logs for details[0.3]Some changes to newstruct to fix bugs and make it work with Python
1.5.1Added TrackHdr class to fix protocol D310[0.2]Incorporated James Skillen’s improvements to support protocol A001
for newer Garmin unitsUpdated the tables based on new spec[0.1]Initial release