Mac Garmin Tools: gpx2gpi

(This is part of the documentation for Mac Garmin Tools. If you don't know what those are or how you got here, see the homepage.)

gpx2gpi

This droplet converts .gpx files to .gpi files which are the files you can move directly onto your Garmin unit. Drop six .gpx files on it and you'll get six .gpi files. It does not ask for any user input: all the details it needs should be supplied in the .gpx file and all you'll see is a progress window like the one shown on the right.

The .gpi files will by created in the same directory as the .gpx files you dropped on it. Although you can view the resulting files using a text editor they will probably look like gibberish: they're in a special format used by Garmin units.

You will normally use this droplet on the results of using another application to make up a .gpx file. If that's all you need, go ahead: that's all you need to know. The rest of this page is for people who want to make up .gpx files themselves, or to understand what the various parts of the format mean.

If you're trying to make up a file in GPX format from scratch, it's best to start with a GPX file sourced from elsewhere. This will give you the correct structure and somewhat complicated top two lines. You can use a file produced by csv2gpx as an example. Alternatively, you could start with a copy of the file that the unit itself uses to keep track of the waypoints you've set. You'll find it here

/Garmin/gpx/current.gpx

on the device.


Elements used

The GPX format is very rich, allowing you to supply not only a great deal of information about your points but also track and route information. The application pays attention only to certain elements of the .gpx file since the Garmin units will only hold certain types of information about the waypoints.

Metadata information

Name

After some initial specifications in the .gpx file you'll find the metadata information – information about the file as a whole. The application only pays attention to one element that appears in this metadata: the name. The name is used as the Category to put the points in (unless you override this by specifying a category in for the point yourself).

  <metadata>
    <name>Shopping</name>
  </metadata>

A semi-colon can be used to separate the category from the subcategory. If the 'name' element is missing from the metadata the application will make up a name based on the name of the file.

Bounds and time

Many .gpx files contain bounds information: a rectagle which is as small as possible while containing all points mentioned in the file. Although this information is needed for the .gpi file this application ignores anything it sees in the metadata element and calculates it own information by inspecting the points. Similarly, the application ignores the time element of the header, and puts the time it's run into the .gpi file. You can safely leave these elements out.

Point information

After the metadata information comes the list of waypoints. The absolute minimum you can specify about a point is this:

  <wpt lat ="44.39874" lon ="2.730013">
    <name>Eddie's House</name>
  </wpt>

The absolute most you can specify is this: an unrealistic, but fully specified example of waypoint information. It has every element that the application can understand.

  <wpt lat ="44.39874" lon ="2.730013">
    <name>Eddie&apos;s House</name>
    <cmt>Snooker !</cmt>
    <desc>Light green, about half way down the street.</desc>
    <link href="filename.ext"/>
    <extensions>
      <gpxx:WaypointExtension>
        <gpxx:Proximity SpeedLimit="13.91">1000</gpxx:Proximity>
        <gpxx:Categories>
          <gpxx:Category>Friend;Near home</gpxx:Category>
        </gpxx:Categories>
        <gpxx:Address>
          <gpxx:StreetAddress>14 Short Street</gpxx:StreetAddress>
          <gpxx:City>Finecaster</gpxx:City>
          <gpxx:State>Rorkshire</gpxx:State>
          <gpxx:Country>England</gpxx:Country>
          <gpxx:PostalCode>RK4 4AW</gpxx:PostalCode>
        </gpxx:Address>
        <gpxx:PhoneNumber Category="Phone">+44 1245 123456</gpxx:PhoneNumber>
        <gpxx:PhoneNumber Category="Phone2">123-4568</gpxx:PhoneNumber>
        <gpxx:PhoneNumber Category="Fax">611-1635</gpxx:PhoneNumber>
        <gpxx:PhoneNumber Category="Email">eddie@example.com</gpxx:PhoneNumber>
      </gpxx:WaypointExtension>
    </extensions>
  </wpt>

It's unlikely that you'd ever need to take advantage of all these elements in any one point. And if you don't care whether the unit understands the information you could put it all in as text. There are advantages to using the correct elements, however: see the notes on the phone number for an example.

Comment

Some data-providers to use this field for long pieces of text. Many units limit the display of this field to a certain number of characters (I've seen 128 and 100) or a certain number of lines of the display (I've seen one and four lines of a 16 character display). It's probably better to use the Description field if your text is long.

Description

There don't seem to be many limits to how many characters you can fit in this field. Garmin units which display it at all can display many paragraphs of text here. Some XML-style markup items work in some units, especially Garmin nüvi units. The following tags seem to work:

Using these tags together you can make some quite professional-looking text, with headings and lists. 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.

gpxx:Proximity

The '<gpxx:Proximity>' element is used to set up the unit's alert capabilities. Most Garmin units have the ability to set a proximity alert: when you get closer than a certain distance to the point, the unit will beep, or flash a message on the display or something like that. nüvi units can also handle a speed alert: you add a SpeedLimit attribute to the Proximity element and the unit will beep only if you exceed that speed within that distance of the point. The units for the proximity value are metres. The units for the 'SpeedLimit' are meters per second. My use of the 'SpeedLimit' attribute for this purpose is not a standard part of the GPX definition. It will change if I find a better way to define the alert limits.

gpxx:Categories

There are three problems involved in taking category information from a GPX file to a Garmin receiver:

The first two problems are handled by the program as best it can. The third is handled by treating semicolons in category names as a splitter between category and subcategory: 'Food' would not be assigned a subcategory, 'Food;Chinese' would.

Warning: at the time of writing (March 2007) there appears to be a serious bug in the firmware in Garmin's units where it deals with subcategories. The points work correctly on maps and as alerts but they're shown in the wrong places in the category hierarchy menu. If you want your points to look neat in the menu, don't assign any subcategories.

gpxx:PhoneNumber

If a Category attribute is not supplied for a contact detail, 'Phone' is assumed. This 'Phone' category of PhoneNumber makes any Garmin unit twinned to a BlueTooth phone show a 'dial' button on the display which lets you make the phone dial that number by pressing the button. Although you can also enter other details (phone2, fax and email) the unit just displays them; it won't let you dial them.


Links to images and sounds

Garmin units vary. I think that the nüvi range currently handles more types of linked files than any others. These units handle four types of link:

extensionfile typeuse
.bmpbitmap imageUsed as an icon for the point.
.jpeg or .jpgJPEG imageAppears on the page for the point. You can scroll and zoom in on it.
.wavWAV audio fileA button appears on the page for the point. Press the button to play the sound.
.mp3MP3 audio fileA button appears on the page for the point. Press the button to play the sound.

The application uses the file extension to figure out what to do with the file. Although the format used to specify each link in a .gpx file is the same, the application treats each kind of link very differently, so don't play about with the filename: an bitmap image should definitely have a '.bmp' extension, for example. All files should be put in the same folder as the .gpx file you're processing.

You can use many links for the same point, but as far as I can tell, the unit only pays attention to one item of any kind. For instance, one point may have a bitmap icon, a JPEG image, and a sound associated with it, but if you link both a WAV and an MP3 file — two sounds — to the same point the unit will ignore one of them.

Bitmaps

The units seem to be especially finicky with regard to bitmaps for use as icons. The .bmp file format is rather complicated and allows for many different image formats and different heights and widths of image. I have never seen any icon with a bigger size than 24 pixels work, and many smaller sizes don't seem to work. If your chosen bitmap doesn't work try using the Preview application to resave it as a bitmap. This will convert it to a 24-bit bitmap and those seem slightly more likely to work than 1-bit, 4-bit or 8-bit bitmaps.

For transparency, make sure your icon uses either 4 or 8 bits per pixel, and use magenta (100% red, 0% green, 100% blue) where you want it to be transparent. If you use 4-bit deep icons, you may notice that some other colours, besides magenta, are also interpreted as transparent.


Multilanguage capabilities

The following fields of the file contain information which is marked for language:

The information for these fields can be supplied in more than one language. When the unit needs to display this information it will automatically pick the version in language that the user selected for user-interface display (or the language they selected for spoken feedback for sound files). The format used to define the text in different languages is the xml:lang standard for XML files, with examples as follows:

    <name>Bobby&apos;s House</name>
    <name xml:lang="FR">Chez Bobby</name>
    <name xml:lang="DE">Haus Bobby</name>
    <name xml:lang="IT">Casa del Bobby</name>
    <name xml:lang="SP">Casa de Roberto</name>
    <Category>Food;Speciality</Category>
    <Category xml:lang="FR">Nourriture;Spécialité</Category>

For each field you can supply as many or few languages as you like, in any order, independently of any other field. The default language for the file can be set by supplying an xml:lang attribute in the <gpx> element at the top of the file. The language codes used conform to ISO 639. I have only ever seen two-character codes used.

Technically, the way I've used xml:lang to indicate language violates the XML definition used for GPX files, so if you do this your file will probably not pass XML validation.


TourGuide / Tour Guide / Travel Guide

The nüvi range has a 'Tour Guide' facility. This can include proximity alerts, text, images and sound files: when you get closer to a certain distance to a point the unit automatically plays the sound file instead of beeping. You can also read text and see a picture associated with a point. This is intended for 'scenic points' tours or displays in a museum. To make the .gpi file take advantage of this feature set both a proximity distance and a sound file for the same point.

Warning: using this feature for any one point effects the entire .gpi file in a way which is not compatible with the normal kind of beeping alarms. Don't try to combine the two features in the same .gpx file. Normally you'd have an entire .gpx file devoted to a tour guide, with every point having its own sound file and a proximity set.