Use OpenStreetMap to create your own Garmin device

OpenStreetMap (OSM) is the easiest place to look for up-to-date, high quality maps for a Garmin navigational device (Figure 1). If necessary, you can also create a map that includes information you yourself have specially selected.

Figure 1: Garmin devices can be loaded with custom images and maps.

This is actually fairly easy. Loading a ready-made map onto a GPS device gives you all of the data you need along with relevant settings for your next hike or bike tour. Table 1 contains suitable sources (Figure 2). Some of the websites provide updated maps for Garmin devices on a weekly basis, others on a daily basis. Most of the time, all you need to do is load the compressed images and then unpack them in the Garmin/ directory on the device memory card. The device itself has a directory of the same name, but this is not where the images belong.

Table 1

Sources for OSM Maps

Source URL Type
OSM Garmin maps http://garmin.openstreetmap.nl/ Free worldwide Garmin maps
Navmaps http://www.navmaps.eu Individual maps of Europe
OpenFietsmap http://www.openfietsmap.nl Individual maps of Europe
Thkukuk http://osm.thkukuk.de Individual maps of Europe
Free alternatives http://mapas.alternativaslibres.es Complete set of maps for Europe
Spatial reference http://www.raumbezug.eu/osm-garmin.htm Complete set of maps for Europe
Maps for hiking and horseback riding http://www.wanderreitkarte.de Hiking and horseback riding
Figure 2: There a plenty of online resources for OSM maps for Garmin devices.

This approach works in most situations. However, OSM does not always have every feature you desire. Prepared maps represent just a portion of the data that is actually available. On the other hand, flooding a map with data would make it unreadable. As a result, the data you would like to have is frequently not there. In addition, device manufacturers often use a variety of different formats for the maps, trails, routes, and other features on their devices, thus making it difficult to use the features.

Mkgmap

A very special tool called Mkgmap [1] provides the foundation with which you can create Garmin compatible maps. You will find this Java command-line program in the repositories of numerous distributions. The software works by generating Garmin-compatible images that are suitable for direct use on the corresponding devices. Mkgmap does not deliver a preview as part of the results as is clear from a problem that occurs in developing styles. Essentially then, previews are only possible directly on the hardware. There is a small workaround that can help out with this issue.

Since it takes some time to create images and copy them to the hardware, you should definitely start working with a small file of about the same size as a map for an individual county within a state. If the device displays these data in the desired way, then you can try out the next larger unit, such as a map the size of a state. In order to reduce the copy time required for larger and larger files, it is a good idea to avoid using a USB cable when copying the files directly onto the device. Instead, you should use the memory card in the computer. The processors for most GPS devices tend to be feeble, something that becomes apparent when trails and routes get loaded.

You will need an image file called gmapsupp.img for old Garmin compatible devices. You can create this kind of file via the Mkgmap option --gmapsupp . Modern devices differ in that they read image files independently of the way they are named. The decisive factor is whether they are saved to the Garmin/ directory. Newer devices also make it possible to save different details of the map in different images and then use them simultaneously. The newer devices frequently use a file named gmapdem.img for contour lines (DEM stands for Digital Elevation Model) and gmapgc.img for geocoding information. The latter matches locations to addresses and coordinates. The names involve conventions that you can choose as desired.

Basically, it is very easy to create a Garmin device map. First, you should load the required OSM data and convert them using Mkgmap, paying careful attention to the styles. As part of this process, you could potentially create several image files, each of which contains a particular feature of the map like contour lines, bike routes, POIs (see the "POIs" box) ,and other similar things. Then you should copy the images that have been created to the device's Garmin/ folder. Currently, this is pretty much the only procedure available for Linux users. See the "Proprietary Images" box for more information.

Proprietary Images

Garmin uses a form of VFAT-based disc images for the image file format. The filesystem displayed by the file contains a series of partial maps as well as some additional data. Each zoom level is displayed on a set of tiles with the images for this resolution. Garmin does not provide the actual specifications [2]. The format has yet to be completely decrypted [3]. In addition, mounting the disk images is not straightforward. As a result, numerous problems are more difficult to resolve than they might otherwise be.

POIs

POIs refers to Points of Interest. POIs can include buildings, gas stations, museums etc. These might also be significant scenic points of interest.

Mkgmap has a --help=options option that provides basic information about the program. The --help=<Topic> option displays additional details for each keyword. The option names cannot be abbreviated in Mkgmap. Equal signs are required between the option and value. You will only need to use a few of the numerous options available in order to perform most tasks (See Table 2).

Table 2

Getting a Handle on Mkgmap

Option Function
-c <file> Reads the relevant file and interprets the contents line by line as <Option>=<value>
--output-dir=<folder> Writes to the relevant directory
--gmapsupp Creates and reads a Garmin-compatible file
-n <Name> Defines the map name
--description=<Text> Describes the map and its features
--country-name=<country> Defines the country name
--country-abbr=<abbreviation> Defines the country name abbreviation
--region-name=<Region> Defines the region name
--region-abbr=<abbreviation> Defines the region name abbreviation
--style-file=<file> Reads styles from the relevant file
--list-styles Displays available styles
--check-styles Checks the available styles
--route Creates a routing-capable map
--cycle-map Creates a bike route map
--transparent Creates a transparent overlay
--verbose Delivers comprehensive output

Maps and Styles

Styles are an important aspect to the creation of the maps. As with Maperitive [4], the software uses features to classify the display for objects and then draws them accordingly. The objects include such things as points, lines, and surfaces. The styles determine the manner in which this occurs. In particular, a style defines the relationship between the form in which an object appears and the magnification level of the object.

Garmin compatible navigational devices work with a scale of 24 resolution levels. The scale correlates the levels with distance. In practice, only levels 16 through 24 are actually relevant (see Table 3). In addition, the mapping for these levels can vary depending on the device. The zoom levels for the maps are different. In principle, there are 17 levels; these include 0 to 16. However, only the values from 0 (maximum detail) to 10 (overview) are typically used.

Table 3

Resolution

Factor Distance
16 30-12km
18 8-3km
20 2000-800m
22 500-200m
23 300-80m
24 120-50m

An internal table gives the relationship between the zoom level and the resolution. For example, the zoom level 0 corresponds to resolution 24. When calling Mkgmap, you can define which level the map should take into account via the --levels= option. A Garmin navigational map contains a maximum of eight levels. In addition, there are up to eight so-called overview levels. A large number of levels improves the display, but it also eats up storage space for the image files.

A gmapsupp.img file contains its own set of precalculated tiles for each zoom level. You will see the level when navigating. This explains the file size, which often reaches into the gigabytes. Since the filesystem for the image is based on VFAT, problems may occur. The maximum size for VFAT files is 4GB. This becomes an issue primarily when you try to create very large MBTiles files [5] that you then use for an SQLite database. By the way, you can use Maperitive as needed to create the displayed tiles and then embed them in a disk image.

Another problem to consider also involves file size and contents. Mkgmap has restrictions with respect to the size of the datasets that it processes. Therefore, you will need to split large OSM and protocolbuffer binary format (PBF) files. Splitting is accomplished with the second program in the Mkgmap suite, aptly known as splitter [6]. You install this program separately, either by hand or under Arch Linux. Otherwise, the program usually comes in the mkgmap package. You will find the program options via --help . However, the packages in Arch Linux do not come with documentation and examples. As a result, you may have to resort to the original files.

Splitter divides OSM files into smaller files. In the process, it tries to keep neighboring regions together. In addition, the program also attempts to transfer Ways and Polygons as completely as possible to a new file. It does this by creating files of various sizes.

Full of Style

Both Mkgmap and Maperitive have a set of rules that defines how a device displays point and line objects. These rules describe particular details line by line in the same way that the software processes them. If the tool uses a rule, it will process the next object. The entire ensemble of rules is divided up among several files and is referred to as the style.

The styles used in Mkgmap are very special and also different from those in Maperitive. They consist of at least four files in a directory where specialized information is kept. Often there are more of these files. You can select names for the files as desired. Alternatively, Mkgmap accepts compressed directories or all of the information in a single file.

One file by the name of version is a must have. This file describes the version of the description language for the style rather than the version of the style itself. Currently, there are only versions 0 and 1. An empty space should follow the line with the version number.

The optional file info contains information about the style as <key>=<value> . You can indicate multiple line values between the two curved brackets. Possible keywords include version (style version), summary (short description of the style), and description (detailed description of the style).

You can provide options in the options file similar to those in the command line (see Table 2). However, the software will only pay attention to options that refer to the style, such as levels , overview-levels , and extra-used-tags . The latter entry makes it possible to indicate additional tags that you would like to use in the style. Most of the time this will not be required.

The points file contains rules that the software uses to display point objects. Normally these include POIs. They will not appear on the map without the points file. You can enter the corresponding objects as follows:

<key>=<value> [
  <character number> resolution <resolution>]

The combination of key and value indicates the POI that you want to have displayed. The < character number> refers to the internal number of the character you would like to use. <Resolution> refers to the resolution at which it will appear. This is illustrated by the following example:

amenity=
  hospital [0x3002 resolution 14]

The points file normally ends with a clause, which provides that the software will have an icon or text for each object displayed (Listing 1). The inc/address file contains clauses as shown in Listing 2. These clauses make sure that all of the elements appear with the names they have been given. However, this can lead to numerous additional entries in some areas.

Listing 1

points

[...]
<finalize>
# The finalizer section is executed for each element when a rule with an element type matches
name=* { name ,${name}' }
include ,inc/address';

Listing 2

inc/address

[...]
mkgmap:phone!=* & phone=* { set mkgmap:phone='${phone}' }
mkgmap:phone!=* & contact:phone=* { add
mkgmap:phone='${contact:phone}' }
mkgmap:is_in!=* & is_in=* { set mkgmap:is_in='${is_in}' }

Similarly, lines defines the display for ways, and polygons defines the display for surfaces. The relations file provides relations for borders, routes, and other things. You will find examples of these file types in the sources [7], documentation [8], and style manual [9] for Mkgmap. Additional examples for style files that have some interesting features can be found on Github under the keyword "mkgmap." You will find a truly interesting version of an OSM map online [10] together with accompanying text that explains how to create the map [11].

Some options such as name-tag-list="name:mkgmap,name:de,int_name,name:en,name" no longer work in the options file of Mkgmap's current version. Instead they only work on the command line. When called, Mkgmap comments on the modified behavior of default options. The online information about about various options [12] is very good, although not entirely current.

Mkgmap style rules follow a predetermined pattern. They consist of two to three parts, which you divide with empty spaces or line breaks. The simplest tests consist of equal or relational operators. There is just a small number of operators that can be used for the tests (see Table 4).

Table 4

Operators for the Test

Abbreviation Meaning
<Tag>=<value> Equal
<Tag>=* True, if tag exists, independent of value
<Tag>!=<value> Unequal
<Tag>!=* True, if tag does not exist
<Tag><<value> Smaller
<Tag><=<value> Smaller-equal
<Tag>~<Regexp> Value corresponds to a regular expression
!(<Regexp>) Negates the expression in brackets

You can connect several tests together with an ampersand (& ). A vertical bar (| ) indicates the logical "or." Tags containing empty spaces are expressed with single or double quotation marks. Functions used to influence the appearance of objects are put between curvy brackets. You can separate the statements using a semicolon (; ). The number of statements is restricted in size. Table 5 shows the most important statements.

Table 5

Statements

Statement Function Example
name Sets the name (preset: Tag-Names) name=* { name '${name}' }
add Adds a tag highway=path {add access = no; add bicycle = yes; add foot = yes}
addlabel Sets a Label highway=* & ref=* { addlabel '${ref}' }
set Overwrites existing tags {set highway=bridleway; set horse=yes}
delete Removes Tags highway=no | highway=none {delete highway}
deletealltags Removes all Tags (highway=razed | highway=dismantled) {deletealltags}
apply For relations, sets Tags type=route & ( route=hiking | route=foot ) { apply { set route=hiking; }}

Garmin devices have a built-in set of icons for marking POIs and ways. A special version of OSM maps, which has been created by the user Computerteddy [13], makes many features available for older navigational devices. For newer devices, you can define additional icons via a so-called TYP file [14]. For some time now, Mkgmap has been able to automatically create these files from special source texts. As soon as you indicate an appropriate TXT file to create an image file when you are calling the program, Mkgmap will also translate this:

$ mkgmap [...] map.osm <TYP-File>.TXT [...]

The call automatically creates the file <TYP-File>.TYP . If you copy it together with the image files to the navigational device's Garmin/ folder, then the device will use the new icons.

Mkgmap is able to quickly test some of the style features (--check-styles ). Before trying this out, you should first determine via --list-styles which styles the application can find. You can select the desired style using --style-file=<Stil> . If no selection is made, the program will test all of the styles found. Ideally, both commands report on Number of MapFailedExceptions: 0 and Number of ExitExceptions: 0 .

After implementing an OSM file with Mkgmap, you should use QLandkarte to test the file that has just been created, even if only in a limited way. This program does not load the image files directly. Instead, it takes a detour consisting of a TDB file. Mkgmap also creates this file when requested. For example, tdbfile=yes activates this process from the options file. Otherwise you should use the following command:

$ mkgmap --tdbfile gmapsupp.img

Two options support the accurate representation of borders and coastlines. You can get exact information about borders [15] via --bounds=bounds.zip , and about coastlines [16] via --precom-sea=sea.zip . You can mount both options on the command line when you create the image files.

Creating Maps

The process of getting the best raw data will depend in part on your requirements and the available possibilities. In most cases, the prepared Geofabrik [17] raw data will suffice. You can load these either as an XML file with the extension .osm or as a compressed version, normally in the PBF format [18].

Depending on the region, these files can be hundreds of megabytes to several gigabytes in size. You should divide the files in such a way that parts of structures that belong together persist (Listing 3, Line 1). The result will be a file by the name of template.args for which you should specify a family-id and map name (Listing 4). You should use this file later when calling Mkgmap in order to set important default settings.

Listing 3

Dividing Files

01 $ java -Xmx1024m -jar splitter.jar --output=pbf --output-dir=splitter --max-nodes=1400000 --mapid=10010001 --poly-file=germany.poly europe.osm.pbf
02 $ java -Xmx2048M -jar mkgmap --name-tag-list="name:de,name,int_name" --tdbfile --style-file=<Style-Datei> --remove-short-arcs --route --net -c template.args *.pbf *.osm *.TYP

Listing 4

template.args

# This file can be given to mkgmap using the -c option
# Please edit it first to add a description of each map.
#
# You can set the family id for the map
family-id: 7777
product-id: 1
# Following is a list of map tiles. Add a suitable description
# for each one.
mapname: 63240001
# description: OSM Map
input-file: 63240001.osm.pbf
[...]

Afterwards you should use Mkgmap to compile the divided PBF and OSM files as shown above. If you have source texts for a text file (*.TXT ), then you should add these to the list of the files that have been entered. The family and product IDs need to match with one another so that the Garmin device recognizes the text files as belonging to the maps. This requires that you indicate the data in the --family-ID=<Number> option when compiling the source texts for the TYP files and map.

When creating maps from OSM files that have been split, you will find that the template.args file already exists. You should incorporate this file together with -c template.args into the command line (Listing 3, Line 2).

Conclusion

Theere are several ways to use Linux to create maps for Garmin devices. The programs that Garmin offers can be used with Wine. However, this does not work very well. With its splitter and a text file compiler, Mkgmap offers a high performance platform for creating your own maps.

There are two main issues that with Mkgmap. There are practically no error messages, and there is no preview. Given that the navigational devices themselves crash in lieu of issuing error messages, it becomes even more difficult to fix errors.