Garmin API

class garmin.Garmin(physicalLayer)

Bases: object

Garmin GPS device object.

The class provides methods to communicate with the hardware.

Most GNU/Linux distributions use a kernel module called garmin_gps to make a USB Garmin device accessible via a serial port. In order to communicate with a Windows computer via a serial link, Garmin USB drivers need to be installed. To communicate with a Garmin device connected to the serial port /dev/ttyUSB0, you could try this:

>>> from garmin import garmin
>>> port = '/dev/ttyUSB0'
>>> phys = garmin.SerialLink(port)
>>> gps = garmin.Garmin(phys)
>>> print(gps.product_data)

Alternatively, internal USB support can be used. For this to work on GNU/Linux, you probably should remove and blacklist the garmin_gps kernel module.

>>> from garmin import garmin
>>> phys = garmin.USBLink()
>>> gps = garmin.Garmin(phys)
>>> print(gps.product_data)
product_data_protocol

Product Data Protocol

product_id

Product ID

software_version

Software version

product_description

Product description

supported_protocols

Protocol capabilities and device-specific data types

Link Protocol

command

Device Command Protocol

transmission

Transmission Protocol

waypoint_transfer

Waypoint Transfer Protocol

waypoint_category_transfer

Waypoint Category Transfer Protocol

route_transfer

Route Transfer Protocol

track_log_transfer

Track Log Transfer Protocol

proximity_waypoint_transfer

Proximity Waypoint Transfer Protocol

almanac_transfer

Almanac Transfer Protocol

date_and_time_initialization

Date And Time Initialization Protocol

flightbook_transfer

Flightbook Transfer Protocol

position_initialization

Position Initialization Protocol

pvt

PVT Protocol

map_transfer

Map Transfer Protocol

map_unlock

Map Unlock Protocol

lap_transfer

Lap Transfer Protocol

run_transfer

Run Transfer Protocol

screenshot_transfer

Screenshot Transfer Protocol

image_transfer

Image Transfer Protocol

get_unit_id()

Return the device’s unit ID.

This feature is undocumented in the spec. The implementation is derived from capturing raw USB traffic from Garmin’s proprietary MapSource application version 6.16.3 (https://www8.garmin.com/support/download_details.jsp?id=209).

get_waypoints(callback=None)

Download waypoints.

Parameters

callback (function or None) – optional callback function

Returns

list of waypoint datatypes

Return type

list

put_waypoints(data, callback=None)

Upload waypoints.

Parameters

  • data (list of waypoint datatypes) – data

  • callback (function or None) – optional callback function

Returns

None

get_routes(callback=None)

Download routes.

Parameters

callback (function or None) – optional callback function

Returns

list of route datatypes

Return type

list

put_routes(data, callback=None)

Upload routes.

Parameters

  • data (list of route datatypes) – data

  • callback (function or None) – optional callback function

Returns

None

get_tracks(callback=None)

Download tracks.

Parameters

callback (function or None) – optional callback function

Returns

list of track datatypes

Return type

list

put_tracks(data, callback=None)

Upload tracks.

Parameters

  • data (list of track datatypes) – data

  • callback (function or None) – optional callback function

Returns

None

get_proximities(callback=None)

Download proximities.

Parameters

callback (function or None) – optional callback function

Returns

list of proximity datatypes

Return type

list

put_proximities(data, callback=None)

Upload proximities.

Parameters

  • data (list of proximity datatypes) – data

  • callback (function or None) – optional callback function

Returns

None

get_laps(callback=None)

Download laps.

Parameters

callback (function or None) – optional callback function

Returns

list of lap datatypes

Return type

list

get_runs(callback=None)

Download runs.

Parameters

callback (function or None) – optional callback function

Returns

list of run datatypes

Return type

list

get_flightbook(callback=None)

Download flightbooks.

Parameters

callback (function or None) – optional callback function

Returns

list of flightbook datatypes

Return type

list

pvt_on()

Turn on PVT mode.

In PVT mode the device will transmit packets approximately once per second

pvt_off()

Turn off PVT mode.

get_pvt(callback=None)

Get real-time position, velocity, and time (PVT).

Parameters

callback (function or None) – optional callback function

Returns

PVT datatype

Return type

garmin.PVT

del_map()

Delete map.

get_map(callback=None)

Download map.

The map is received as raw data and is in Garmin IMG format.

Parameters

callback (function or None) – optional callback function

Raises

GarminError – if the map_transfer_protocol is not supported.

Returns

map

Return type

bytes

put_map(data, key=None, callback=None)

Upload map.

The map is sent as raw data and should be in Garmin IMG format. Multiple IMG files should be merged into one file called "gmapsupp.img". To upload a locked map, the encryption key has to be specified.

Parameters

  • data (str or io.BufferedReader or bytes) – Garmin IMG

  • key (str or None) – optional encryption key

  • callback (function or None) – optional callback function

Raises

GarminError – if the map_transfer_protocol is not supported.

Returns

None

get_screenshot(callback=None)

Capture screenshot.

The map is received as raw data and is in Garmin IMG format.

Parameters

callback (function or None) – optional callback function

Returns

image file of the device’s display

Return type

PIL.Image

get_image_types()

Get image types.

Return a list of image types that are allowed to be retrieved or updated. Each image type is represented as a dict of the index and name of the image type.

Returns

supported image types

Return type

list[dict]

get_image_list()

Get image list.

Return a list of images that are allowed to be retrieved or updated. Each image is represented as a dict of the image type index, image index, writable status, and image name. The image type name the image belongs to can be looked up with Garmin.get_image_types().

Returns

supported images

Return type

list[dict]

get_image(idx, callback=None)

Download image.

It is possible to get a screenshot from most GPS models. Certain newer models also allow you to get other image types, like the splash screen or waypoint symbols.

The index of the image can be looked up with Garmin.get_image_list().

Parameters

  • idx (int) – index of image to download

  • callback (function or None) – optional callback function

Returns

image file of the device’s display

Return type

PIL.Image

put_image(idx, data, callback=None)

Upload image.

The index of the image can be looked up with Garmin.get_image_list().

Parameters

  • idx (int) – index of image to upload

  • data (PIL.Image) – image data to upload

  • callback (function or None) – optional callback function

abort_transfer()

Abort transfer

turn_power_off()

Turn power off