Garmin Mapsource installer

From OpenStreetMap Wiki
Jump to navigation Jump to search
The Garmin MapSource installer program about to install a map

Garmin Mapsource installer is a Microsoft Windows program for installing Garmin .img files so that Garmin's Mapsource program can use them.

It's aimed at distributors of Garmin maps who can easily add support for MapSource by bundling the stand-alone executable up with a configuration file telling it what to install. The program itself is around 200 KB. See Garmin map of Iceland (direct link to installer) for an example of a map distribution that uses this installer.

I wrote it because the alternatives were asking end-users to edit their Registry, using proprietary programs like MapSetToolkit which depend on cGPSmapper, or running unfriendly .bat scripts.

Using this program for your map distribution

To use this program to distribute maps you generate you should:

   svn co

This will give you a directory with two files: Setup.exe and garmin-mapsource-installer.ini. The .ini file contains a section like this:

Family = OpenStreetMap Iceland
ID = 7F02
BMAP = 13314530.img
TDB = 13314530.tdb
other = 13314531.img

All the values except "other" will be written to the registry during installation. This is what the registry will look like afterwards:

The registry after installation

The "other" value is the actual map file (not metadata) that will be copied to the install location:

The installed files

If you generate your map with mkgmap it won't work in MapSource (it'll refuse to start due to a corrupted map) unless you supply a few required options on the command-line. These are:

Option Affect
Each map family must have an --overview-map with a TDB file and an associated map (specified with --mapname) that has a different 8 character ID. If any of these are missing your installation won't work.

Given these options the [Map] section in the .ini file would have to contain:

BMAP = 40000001.img
TDB = 40000001.tdb
other = 40000002.img
--family-id=639 Required. FIXME: Does this correspond to the ID value in the registry or can anything be specified?

ID defined in Map section of garmin-mapsource-installer.ini should be the "machine" hex representation of --family-id=x used with mkgmap. Example: for


the hex code of 639 is 02 7F but you have to use it in form how computers store it - least significant byte first - 7F02

ID = 7F02 

Required. FIXME: The installer needs to check that no other map already installed uses the same FID. see Talk:Garmin_Mapsource_installer#Check_for_FID_already_existing

--series-name="OSM Iceland" The name your map will have in the MapSource interface e.g. when switching between maps or browsing installed map packages. see screenshot
--family-name="OSM Iceland" This name is used in the map selection window (switch maps on/off) of the GPS.

You will need to modify the .ini file to match the values you specify to mkgmap.

Once you've generated your Garmin image files just place them in a directory with the installer and ini file:

avar@aoeu:~/src/osm/applications/utils/garmin-mapsource-installer/dist$ ls -l
total 3276
-rw-r--r-- 1 avar avar    5120 2009-09-19 03:02 13314530.img
-rw-r--r-- 1 avar avar     545 2009-09-19 03:02 13314530.tdb
-rw-r--r-- 1 avar avar 3134464 2009-09-19 03:02 13314531.img
-rw-r--r-- 1 avar avar     667 2009-09-19 02:18 garmin-mapsource-installer.ini
-rwxr-xr-x 1 avar avar  189177 2009-09-19 02:18 Setup.exe

Then zip them up into a map package:

avar@aoeu:~/src/osm/applications/utils/garmin-mapsource-installer/dist$ zip -j *
  adding: 13314530.img (deflated 88%)
  adding: 13314530.tdb (deflated 31%)
  adding: 13314531.img (deflated 20%)
  adding: garmin-mapsource-installer.ini (deflated 50%)
  adding: Setup.exe (deflated 16%)

Then put the ZIP on your website and point Windows users at it.


See /Development

Bugs & caveats

  • This is in early development. Things may break, particularly the format of the .ini file will probably be changed in the future
  • Installation of multiple maps isn't supported yet. The workaround is to have multiple installers.