Pygarmin application

Synopsis

pygarmin [arguments] <sub-command> [arguments]

The arguments before the sub-command configure pygarmins behaviour, the sub-command indicates which operation should be performed, and the arguments after the sub-command configure the sub-commands behaviour.

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.

Options

Command line application to communicate with a Garmin GPS device.

Pygarmin can retrieve information from the device, such as the product description including the unit ID, the supported protocols, memory properties, and information on the installed maps. supports bi-directional transfer of waypoints, routes, track logs, proximity waypoints, maps and images such as custom waypoint icons. It is able to receive laps, runs, satellite almanac, current time, current position, and screenshots. It can continuously receive real-time position, velocity, and time (PVT).

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.

usage: pygarmin [-h] [-v] [-D] [--version] [--progress | --no-progress]
                [-p PORT]
                {info,protocols,memory,map,get-waypoints,put-waypoints,get-routes,put-routes,get-tracks,put-tracks,get-proximities,put-proximities,get-almanac,time,position,pvt,get-laps,get-runs,get-map,put-map,del-map,get-screenshot,get-image-types,get-image-list,get-image,put-image}
                ...

Named Arguments

-v, --verbosity

Increase output verbosity

Default: 0

-D, --debug

Enable debugging

Default: 0

--version

Dump version and exit

Default: False

--progress, --no-progress

Show progress bar (default: True)

Default: True

-p, --port

Set the device name (default: usb:)

Default: “usb:”

Sub-commands

info

Return product description

pygarmin info [-h] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

protocols

Return protocol capabilities

pygarmin protocols [-h] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

memory

Return memory info

pygarmin memory [-h] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

map

Return map info

pygarmin map [-h] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

get-waypoints

Download waypoints

pygarmin get-waypoints [-h] [-t {txt,garmin,gpx}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin, gpx

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

put-waypoints

Upload waypoints

pygarmin put-waypoints [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set input file

Default: <_io.TextIOWrapper name=’<stdin>’ mode=’r’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set input format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

get-routes

Download routes

pygarmin get-routes [-h] [-t {txt,garmin,gpx}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin, gpx

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

put-routes

Upload routes

pygarmin put-routes [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set input file

Default: <_io.TextIOWrapper name=’<stdin>’ mode=’r’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set input format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

get-tracks

Download tracks

pygarmin get-tracks [-h] [-t {txt,garmin,gpx}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin, gpx

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

put-tracks

Upload tracks

pygarmin put-tracks [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set input file

Default: <_io.TextIOWrapper name=’<stdin>’ mode=’r’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set input format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

get-proximities

Download proximities

pygarmin get-proximities [-h] [-t {txt,garmin,gpx}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin, gpx

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

put-proximities

Upload proximities

pygarmin put-proximities [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set input file

Default: <_io.TextIOWrapper name=’<stdin>’ mode=’r’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set input format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

get-almanac

Download almanac

pygarmin get-almanac [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

time

Download current date and time

pygarmin time [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

position

Download current position

pygarmin position [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

pvt

Download pvt

pygarmin pvt [-h] [-t {txt,garmin,tpv}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin, tpv

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. tpv returns a TPV object based on the GPSD JSON protocol.

Default: “garmin”

get-laps

Download laps

pygarmin get-laps [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

get-runs

Download runs

pygarmin get-runs [-h] [-t {txt,garmin}] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

Named Arguments

-t, --format

Possible choices: txt, garmin

Set output format. txt returns a JSON string that consists of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype.

Default: “garmin”

get-map

Download map

pygarmin get-map [-h] filename

Positional Arguments

filename

Set output file

Default: “gmapsupp.img”

put-map

Upload map

pygarmin put-map [-h] filename

Positional Arguments

filename: Set input file

del-map

Delete map

pygarmin del-map [-h]

get-screenshot

Capture screenshot

pygarmin get-screenshot [-h] [-t FORMAT] filename

Positional Arguments

filename

Set image file name

Default: “Screenshot.bmp”

Named Arguments

-t, --format: Set image file format

get-image-types

List image types

pygarmin get-image-types [-h] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

get-image-list

List images

pygarmin get-image-list [-h] [filename]

Positional Arguments

filename

Set output file

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

get-image

Download image

pygarmin get-image [-h] [-t FORMAT] [-i [INDEX ...]] [filename]

Positional Arguments

filename: Filename or directory to save images. A filename pattern can contain %d (or any formatting string using the % operator), since %d is replaced by the image index. Example: waypoint%03d.png

Named Arguments

-t, --format: Set image file format
-i, --index: Indices of the image list to get

put-image

Upload image

pygarmin put-image [-h] [-i [INDEX ...]] filename [filename ...]

Positional Arguments

filename: Set input file

Named Arguments

-i, --index: Indices of the image list to put

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