Some notes on storing waypoints in Garmin Nüvi receivers

This document grew out of my attempts to understand the various ways of storing waypoints on my nüvi receiver. I'm publishing them here in the hope they'll be useful to someone else. I'm eager to accept corrections or improvements to this text, within the bounds of the overall shape of the file. Don't hesitate to email me if you think you can help improve it. If you have questions about the Nüvi or waypoints in general, however, you might like to know about http://www.nuvipassion.com which features a lively support group for users of the nüvi.

Simon Slavin, email thread@bigfraud.org


Summary

.gpx files.gpi files
location/Garmin/gpx/Garmin/POI
file handlingabsorbed into current.hpx when readleft where they are
max number of pointslow (50 ?)limited only by memory
fields (others ignored)name, comment, phone numbername, comment, description, link,
proximity, speed, address, contact info
editing in unitwill lose ignored tagsnot possible
iconindicate one of the built-in symbols.bmp image data incorporated into file
ampersandmust be entered as &HTML form preferred, '&' sometimes works
accented charactersUTF-8 works, some HTML special characters workUTF-8 does not work, HTML special characters don't
styled text markupcause parsing problemsmarkup language
alertsignoredproximity and speed alerts

The above table does not include details on things that are handled the same in both types of file. For instance, although GPX has an element type for elevation, all Garmin units seem to ignore all elevation information in .gpi files.


Overall handling

This section describes the most significant difference between how .gpx and .gpi files are handled. Once you understand this difference, many other aspects of how the nüvi handles these files fall into place.

Think of the .gpx file (and there is only one, once the device has booted) as the working memory of the device. Points in this file are constantly referred to by the device: they all appear every time a map appears on its display and they must all appear quickly in a sorted list when you hit the 'favourites' button. Consequently, when the device boots, it's needs to all the points in one place where it can find them when it needs them. That's why all other .gpx files disappear when the device is booted.

There's a limit of 50 items in the Favourites file you can make up yourself using the unit. This is because the unit has to consult the entire file every time it draws the map so a big file would slow down map-drawing.

The points in .gpi files, by contrast, are more normally consulted one at a time and only when the user specially requests it. The user is expected to use a special menu to access these points, select one from the list, then ignore them again. The points don't have to be consulted every time a map is drawn (unless you're at very high zoom levels), and if the user is just navigating normally there's no reason to consult these files at all. Consequently it's possible to keep the points in many different files and consult them only when needed.


Other Matters

Tags

The following example includes exactly the tags that the nüvi understands in .gpx files.

  <wpt lat ="54" lon ="42.7">
    <name>a test point</name>
    <cmt>This is a comment.</cmt>
    <sym>Residence</sym>
    <extensions>
      <gpxx:WaypointExtension>
        <gpxx:PhoneNumber>+44 1234 567890</gpxx:PhoneNumber>
      </gpxx:WaypointExtension>
    </extensions>
  </wpt>

If a tag isn't in the above example it will be ignored when the .gpx file is parsed.

Symbols

The unit includes a number of pre-defined symbols which can be selected using the user interface. When selecting a symbol in a .gpx file you specify it by name. The unit also knows about some symbols which don't appear in the grid it shows to allow you to select them. A table of names vs. symbols can be found in this thread:

http://www.gpspassion.com/forumsen/topic.asp?TOPIC_ID=71684

Although some effort has been made by different manufacturers to standardise on symbol names and appearances, this has not been completely achieved. In addition to this, models which don't have colour displays have to use simpler symbols on the display so that they're clear when only black and white are available for display. For these reasons you can expect some variation on the appearance of symbols used in different units.

XML-like markup language

Actually, I have no idea if this markup language is XML or not. Comment fields in .gpi formats can hold a maximum of 159 characters, but description fields don't seem to have a small limit. Certain XML-like markup tags work including

It's possible that you're meant to surround marked-up text with <HTML></HTML> tags but from what I can see it just seems to waste space. Many other tags may work but the above are all the ones I have examples of. If you want some examples of markup that works, look at the .gml files in the /Garmin/Help directory.

Alerts

nüvi receivers are capable of two kinds of alert: proximity alerts and speed alerts:

alert typehow to specify onewhen you're notified
proximity alertspecify a proximity and no speedwhen you're closer than that distance to the point
speed alertspecify a proximity and a speedwhen you're closer than that distance to the point and travelling faster than that speed

By assigning a link to a sound file to a waypoint you can replace the normal 'alert' sound with your own sound. (I'm confused here as to whether this is meant to work only for TourGuide files.)


History of this file

2007/08/23 Version 1.2.1 Wrong folder for .gpi files, pointed out by Thom Kalta. Thanks, Thom.

2007/01/03 Version 1.2 Updated for inclusion with MacGarminTools rather than MakeGPI.

2006/12/12 Version 1.1 Updated for address and contact information in .gpi file.