Garmin API

class pygarmin.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, link
>>> port = '/dev/ttyUSB0'
>>> phys = link.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, link
>>> phys = link.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

property command

Device Command Protocol.

property transmission

Transmission Protocol.

property waypoint_transfer

Waypoint Transfer Protocol.

property waypoint_category_transfer

Waypoint Category Transfer Protocol.

property route_transfer

Route Transfer Protocol.

property track_log_transfer

Track Log Transfer Protocol.

property proximity_waypoint_transfer

Proximity Waypoint Transfer Protocol.

property almanac_transfer

Almanac Transfer Protocol.

property date_and_time_initialization

Date And Time Initialization Protocol.

property flightbook_transfer

Flightbook Transfer Protocol.

property position_initialization

Position Initialization Protocol.

property pvt

PVT Protocol.

property map_transfer

Map Transfer Protocol.

property map_unlock

Map Unlock Protocol.

property lap_transfer

Lap Transfer Protocol.

property run_transfer

Run Transfer Protocol.

property workout_transfer

Workout Transfer Protocol.

property workout_occurrence_transfer

Workout Occurrence Transfer Protocol.

property fitness_user_profile_transfer

Fitness User Profile Transfer Protocol.

property workout_limits_transfer

Workout Limits Transfer Protocol.

property course_transfer

Course Transfer Protocol.

property course_lap_transfer

Course Lap Transfer Protocol.

property course_point_transfer

Course Point Transfer Protocol.

property course_limits_transfer

Course Limits Transfer Protocol.

property course_track_transfer

Course Track Transfer Protocol.

property screenshot_transfer

Screenshot Transfer Protocol.

property image_transfer

Image Transfer Protocol.

property 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_waypoint_categories(callback=None)

Download waypoint categories.

Parameters

callback (function or None) – optional callback function

Returns

list of waypoint category datatypes

Return type

list

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 or list of lists of dicts) – 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 or list of lists of dicts) – 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_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

get_memory_properties()

Return memory info.

get_map_properties()

Return map info.

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

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

error.GarminError – if the map_transfer_protocol is not supported.

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_workouts(callback=None)

Download workouts.

Parameters

callback (function or None) – optional callback function

Returns

list of workout datatypes

Return type

list

get_workout_occurrences(callback=None)

Download workout occurrences.

Parameters

callback (function or None) – optional callback function

Returns

list of workout occurrence datatypes

Return type

list

get_fitness_user_profile(callback=None)

Download fitness user profile.

Parameters

callback (function or None) – optional callback function

Returns

list of workout occurrence datatypes

Return type

list

get_workout_limits(callback=None)

Download workout limits.

Parameters

callback (function or None) – optional callback function

Returns

list of workout limits datatypes

Return type

list

get_courses(callback=None)

Download workout occurrences.

Parameters

callback (function or None) – optional callback function

Returns

list of workout occurrence datatypes

Return type

list

get_course_laps(callback=None)

Download workout occurrences.

Parameters

callback (function or None) – optional callback function

Returns

list of workout occurrence datatypes

Return type

list

get_course_points(callback=None)

Download workout occurrences.

Parameters

callback (function or None) – optional callback function

Returns

list of workout occurrence datatypes

Return type

list

get_course_limits(callback=None)

Download course limits.

Parameters

callback (function or None) – optional callback function

Returns

list of course limits datatypes

Return type

list

get_course_tracks(callback=None)

Download workout occurrences.

Parameters

callback (function or None) – optional callback function

Returns

list of workout occurrence datatypes

Return type

list

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

MicroBMP

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

MicroBMP

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 (MicroBMP or str or io.BufferedReader) – image data to upload

  • callback (function or None) – optional callback function

abort_transfer()

Abort transfer

turn_power_off()

Turn power off