Note: This page describes the development version of GPSBabel. It may substantially differ from the latest released GPSBabel.

Garmin Points of Interest (.gpi) (garmin_gpi)

This format can...

  • read and write waypoints

This format has the following options: alerts, bitmap, category, hide, descr, notes, position, proximity, sleep, speed, unique, units, writecodec, languagecode .

The format garmin_gpi supports the binary POI (.gpi) files that are usable on newer Garmin GPS receivers. See garmin_poi for additional information about Garmin's own Poiloader program. Garmin POI-Loader is the standard application that creates GPI files with all possible features.

Some of the third party and commercial GPI files are using some kind of encryption or compression that makes the file contents completely unreadable to us. If you get an error "Unsupported code page NNN. File is likely encrypted." means we could basically recognize it as a Garmin GPI file, but it's mangled beyond what we're likely to successfully read.

If a waypoint name is annotated with a trailing '@'NNN where NNN is a number, that number will be used as the speed for POI alerts, just as with Garmin's POI Loader program. The units default to metric kilometers per hour, but this can be changed to statute via the units argument. A speed associated with a specific POI will get precedence over any 'speed' argument provided. For example, a waypoint named "Point@30" will associate a speed of 30 km/h with that specific point even if 'speed=40m' is present in the output arguments.

The layout of GPI files isn't documented and our module was created via reverse engineering. If you get a problem on reading or writing a GPI file, please provide that file (mailto:gpsbabel-misc@lists.sourceforge.net).

At this time we don't support special features as "Tour-Guide" or links to sounds and pictures.

Important

Creation timestamp issue: See the option sleep !!!

This module does not support direct transfer of .GPI files to receivers in Garmin protocol mode. For units like Nuvi, Zumo, or Streetpilot, just choose a file that's on the drive where your GPS is mounted. For units like the X series (GPSMap 60CSx, GPSMap 60Cx, Legend Hcx, etc.) you must explicitly put the unit in mass storage mode or mount the memory chip in an external reader and transfer the file directly.

Example 3.7. Command showing garmin_gpi output example

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,category="Nice Restaurants",bitmap=restaurant.bmp,notes -F "My Points.gpi"


alerts option

Enable alerts on speed or proximity distance.

Because speed isn't a real member of a normal waypoint, you can put the speed values into the waypoint names. "Point@30" will result in a speed value of 30. By default we assume these values are in kilometers per hour.

Proximity distance is also supported by GPX, Garmin GDB, OZI Explorer, and Universal CSV.

gpsbabel -i gpx -f "warnings.gpx" -o garmin_gpi,alerts=1 -F "warnings.gpi"

bitmap option

Use specified bitmap on output.

The bitmap (BMP) should be 24x24 (or smaller) and can be in RGB-colors (24- and 32-bit) or 8-bit indexed color format.

If you're starting from images in another format, you may need to use another tool like Gimp or ImageMagick's convert to get the image into one of the above formats to avoid errors about "Unsupported color depth".

Not all devices can support all color depths. GPSBabel (and its developers) have no way of knowing what is supported on any given model so some experimentation may be necessary on your part. It was reported that a Nuvi 3790, for example, will read the POIs only if they use 8BPP.

A color value of 0xFF00FF (blue=255, green=0, red=255), also called "Magenta", can be used for transparent areas.

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,bitmap="tux.bmp" -F "My Points.gpi"

category option

Default category on output.

With this option you can specify the category which is primary visible on the device (default is "My points").

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,category="Best Restaurants" -F "My Points.gpi"

hide option

Don't show gpi bitmap on device.

For a large list of points (or whyever) it can be useful when no bitmaps are displayed on device. With this option no bitmap is stored and displayed.

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,hide -F "My Points.gpi"

descr option

Write description to address field.

The GPI address field is often visible in lists on the device. Use this option if you want to see the waypoint description (which can be an address too) in this lists.

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,descr -F "My Points.gpi"

notes option

Write notes to address field.

The GPI address field is often visible in lists on the device. Use this option if you want to see the waypoint notes (which can be an address too) in this lists.

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,notes -F "My Points.gpi"

position option

Write position to address field.

The GPI address field is often visible in lists on the device. Use this option if you want to see the waypoint position (coordinates) in this lists.

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,position -F "My Points.gpi"

proximity option

Default proximity.

When no proximity data is available in the source input, GPSBabel uses this as the default proximity value. The parameter has to be in meters, or, when units=s specified, in miles. alerts are automatically enabled.

Example 3.8. Read GPX file, create GPI to alert when you're 1/2 mile from a speed camera.

gpsbabel -i gpx -f "SpeedCameras.gpx" -o garmin_gpi,units=s,proximity=0.5 -F "SpeedCameras.gpi"


Its also possible to append a specific distance unit to the parameter.

gpsbabel -i gpx -f "SpeedCameras.gpx" -o garmin_gpi,proximity=500m -F "SpeedCameras.gpi"

Table 3.2. Supported distance units (garmin_gpi)

UnitDescription
faFathoms
feetFeet
ftFeet
kmKilometers
mMeters
miMiles
nmNautical miles


sleep option

After output job done sleep n second(s).

The Garmin units seem to use the creation timestamp of GPI files for internal purposes. In other words, if you load GPI files with same creation timestamp on your device, strange things will happen, such as having missing or repeated POIs. With the sleep option, GPSBabel waits a given number of seconds after the GPI file was written.

In the normal case of using GPSBabel from the command line or from the GUI, the chance of creating files with the same timestamp is in the nearly ZERO. In scripts or batch files where you are writing multiple files - even from different GPSBabel instances - the odds of this happening is rather good. The sleep option forces GPSBabel to wait after creating a file to ensure the timestamps are unique. Values are specified in seconds and can be 1 or more.

gpsbabel -i gpx -f "SpeedCameras.gpx" -o garmin_gpi,sleep=1 -F "SpeedCameras.gpi"

speed option

Default speed.

When no speed data is available in the source input, GPSBabel uses this as the default speed value. The parameter has to be in kilometers per hour, or, when units=s specified, in miles per hour. alerts are automatically enabled.

gpsbabel -i gpx -f "SpeedCameras.gpx" -o garmin_gpi,units=s,speed=30 -F "SpeedCameras.gpi"

Its also possible to append a specific speed unit to the parameter.

gpsbabel -i gpx -f "SpeedCameras.gpx" -o garmin_gpi,speed=30mph -F "SpeedCameras.gpi"

Table 3.3. Supported speed units (garmin_gpi)

UnitDescription
km/hKilometers per hour
kmhKilometers per hour
kphKilometers per hour
ktKnots
knotKnots
m/sMeters per second
mpsMeters per second
mi/hMiles per hour


unique option

Create unique waypoint names (default = yes).

Don't create unique names sample:

gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,unique=0 -F "My Points.gpi"

units option

Units used for names with @speed ('s'tatute or 'm'etric).

Sample command tells GPSBabel to handle speed values in miles per hour: gpsbabel -i gpx -f "My Points.gpx" -o garmin_gpi,units=s -F "My Points.gpi"

writecodec option

codec to use for writing strings.

This lets you override the default codec of 'windows-1252' when writing strings in Garmin GPI files. This option may be removed in future versions of GPSBabel as it's not known which Garmin devices support which character sets.

languagecode option

language code to use for reading dual language files.

Garmin points of interest files may contain data in two languages. If you attempt to read a dual language Garmin points of interest file without specifiying which language to use GPSBabel will print an error message containing the language codes used in the file. Subsequently you may use one of these codes with the languagecode option to specify which language to use.

Example 3.9. Example with unspecified language and a garmin points of interest dual language file.

gpsbabel -i garmin_gpi -f reference/spb_metro_norm.gpi could produce the following output:

garmin_gpi: Must select language code, RU and EN found.


Example 3.10. Example for specifying language with a garmin points of interest dual language file.

gpsbabel -i garmin_gpi,languagecode=EN -f reference/spb_metro_norm.gpi could produce the following output:

59.944070N 30.306680E About Saint-Petersburg Metro - 2016.05/This file represents information about metro stations in aint-Petersburg. Published by NAVICOM, 2016. http://navicom.ru
59.830660N 30.500100E RYBACKOE/Subway
59.934430N 30.329950E NEVSKII PROSPEKT/Subway
...