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,get-time,get-position,pvt,get-laps,get-runs,get-workouts,get-courses,get-fitness-user-profile,get-activities,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,json,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, json, gpx

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

Default: “garmin”

put-waypoints

Upload waypoints

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

Positional Arguments

filename

Set input file

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

Named Arguments

-t, --format

Possible choices: garmin, json, gpx

Set input format. garmin returns a string that can be executed and will yield the same value as the datatype. json returns a JSON string of the datatypes. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

get-routes

Download routes

pygarmin get-routes [-h] [-t {txt,garmin,json,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, json, gpx

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

Default: “garmin”

put-routes

Upload routes

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

Positional Arguments

filename

Set input file

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

Named Arguments

-t, --format

Possible choices: garmin, json, gpx

Set input format. garmin returns a string that can be executed and will yield the same value as the datatype. json returns a JSON string of the datatypes. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

get-tracks

Download tracks

pygarmin get-tracks [-h] [-t {txt,garmin,json,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, json, gpx

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

Default: “garmin”

put-tracks

Upload tracks

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

Positional Arguments

filename

Set input file

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

Named Arguments

-t, --format

Possible choices: garmin, json, gpx

Set input format. garmin returns a string that can be executed and will yield the same value as the datatype. json returns a JSON string of the datatypes. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

get-proximities

Download proximities

pygarmin get-proximities [-h] [-t {txt,garmin,json,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, json, gpx

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

Default: “garmin”

put-proximities

Upload proximities

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

Positional Arguments

filename

Set input file

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

Named Arguments

-t, --format

Possible choices: garmin, json, gpx

Set input format. garmin returns a string that can be executed and will yield the same value as the datatype. json returns a JSON string of the datatypes. gpx returns a string in GPS Exchange Format (GPX).

Default: “garmin”

get-almanac

Download almanac

pygarmin get-almanac [-h] [-t {txt,garmin,json}] [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, json

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

Default: “garmin”

get-time

Download current date and time

pygarmin get-time [-h] [-t {txt,garmin,json}] [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, json

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

Default: “garmin”

get-position

Download current position

pygarmin get-position [-h] [-t {txt,garmin,json}] [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, json

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

Default: “garmin”

pvt

Download pvt

pygarmin pvt [-h] [-t {txt,garmin,gpsd}] [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, gpsd

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

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 human readable string 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,fit}] [filename]

Positional Arguments

filename

Filename or directory to save runs (default is stdout). A filename pattern can contain %d (or any formatting string using the % operator), since %d is replaced by the image index. Example: run%03d.fit. By default, runs are written to filenames named by the start date and time.

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

Named Arguments

-t, --format

Possible choices: txt, garmin, fit

Set output format. txt returns a human readable string of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. fit returns the binary FIT file format.

Default: “garmin”

get-workouts

Download workouts

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

Positional Arguments

filename

Filename or directory to save workouts (default is stdout). A filename pattern can contain %d (or any formatting string using the % operator), since %d is replaced by the image index. Example: workout%03d.fit. By default, the workout name is used as filename.

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

Named Arguments

-t, --format

Possible choices: txt, garmin, fit

Set output format. txt returns a human readable string of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. fit returns the binary FIT file format.

Default: “garmin”

get-courses

Download courses

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

Positional Arguments

filename

Filename or directory to save courses (default is stdout). A filename pattern can contain %d (or any formatting string using the % operator), since %d is replaced by the image index. Example: course%03d.fit. By default, the course name is used as filename.

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

Named Arguments

-t, --format

Possible choices: txt, garmin, fit

Set output format. txt returns a human readable string of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. fit returns the binary FIT file format.

Default: “garmin”

get-fitness-user-profile

Download fitness user profile

pygarmin get-fitness-user-profile [-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 human readable string 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-activities

Download activities. Activities are runs that are grouped by multisport session.

pygarmin get-activities [-h] [-t {fit}] [filename]

Positional Arguments

filename

Filename or directory to save activities (default is stdout). A filename pattern can contain %d (or any formatting string using the % operator), since %d is replaced by the image index. Example: activity%03d.fit. By default, activities are written to filenames named by the start date and time.

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

Named Arguments

-t, --format

Possible choices: fit

Set output format. txt returns a human readable string of a dictionary with the datatypes attributes. garmin returns a string that can be executed and will yield the same value as the datatype. fit returns the binary FIT file format.

Default: “fit”

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 filename or directory

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

Upload all waypoints in the file waypoints.gpx:

pygarmin put-waypoints waypoints.gpx -t gpx

Download all activities in FIT format to the files activity001.fit to activityNNN.fit in the current directory:

pygarmin get-activities -t fit activity%03d.fit

Print real-time position, velocity, and time (PVT) in GPSD JSON format to stdout:

pygarmin pvt -t gpsd

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