QLandkarte - use your Garmin GPS with Linux

Garmin's MapSource software is hardly the only reason for me to boot into Windows and it does not look like Garmin ever wants to address Linux users by writing a portable piece of software. So I started to help myself. I found several tools like GPSBabel or sendmap to handle data for my GPS receiver but no tool to visualize and manage this data in a decent way. On my quest I found a specification of the used IMG format for maps at Sourceforge. After some reading and toying around I considered this specification good enough to start a GUI project to visualize such files. QLandkarte is the result of this effort.

Implemented features are:

• Supporting:
  • eMap (serial, experimental)
  • eTrex Legend (serial, experimental)
  • eTrex Legend C (usb)
  • eTrex Venture Cx (usb, untested)
  • GPSmap 60CS (usb)
  • GPSmap 60Cx (usb, untested)
  • GPSmap 60CSx (usb)
  • For other USB units you have to get involved.
• Import map collections (needs *.tdb file, basemap and map tiles)
• Load single *.img tiles
• Display maps and object information
• Search for places via Google Map API
• Search for geo caches via opencaching.de
• Save workspace to *.gpx
• Maps
  • Upload maps to device
  • Download map information
• Waypoints
  • upload / download waypoints
  • create waypoints
  • move / edit waypoints
  • load waypoints from *.gpx
  • save waypoints to *.gpx
• Tracks
  • download tracks
  • combine / split tracks
  • purge / remove trackpoints
  • view track information and profile
  • load tracks from *.gpx
  • save tracks to *.gpx
• Print maps to PDF or paper.

Requirements:

• > Qt 4.2.x (Qt 4.1.x will not work!)
• > proj4 4.4.x
• > libusb 0.1.x

---

Garmin, MapSource and Linux are registered trademarks.

Howto create a device driver for QLandkarte?

As prerequisite get yourself a copy of the Garmin protocol specification. This is a moving target on the Garmin website. Use Google to find it. Not necessary, but of great help will be a USB or serial protocol sniffer for Microsoft Windows.

Next get the latest version of QLandkarte:

      svn export https://qlandkarte.svn.sourceforge.net/svnroot/qlandkarte/trunk qlandkarte
      

Change path to:

      cd qlandkarte/src/device
      

You will see something like:

        device
          |-- CUSB.cpp
          |-- CUSB.h
          |-- EtrexLegendC
          |   |-- CDevice.cpp
          |   |-- CDevice.h
          |   |-- EtrexLegendC.pro
          |   |-- Makefile
          |   `-- loader.cpp
          |-- GPSMap60CSx
          |   |-- CDevice.cpp
          |   |-- CDevice.h
          |   |-- GPSMap60CSx.pro
          |   |-- Makefile
          |   `-- loader.cpp
          |-- Garmin.cpp
          |-- Garmin.h
          |-- IDevice.h
          |-- IDeviceDefault.cpp
          |-- IDeviceDefault.h
          |-- ILink.cpp
          |-- ILink.h
          |-- device.pro
          `-- template
              |-- CDevice.cpp
              |-- CDevice.h
              |-- loader.cpp
              `-- template.pro
      

The subdirectory 'template' contains a template project setup for you. Make a copy of it, by using your device's full name. Let's assume your device is named MyGarmin:

      cp -r template MyGarmin
      cd MyGarmin
      mv template.pro MyGarmin.pro
      

Open all files and replace every single occurance of the string '<template>' into 'MyGarmin'. Go back to the project's root and add your subproject to 'QLandkarte.pro'. The project should build without errors. The makefiles will copy all drivers to 'bin/plugins'. QLandkarte will search for them in '/usr/lib/qlandkarte'. To skip 'make install' during development simply link the local plugin directory to '/usr/lib/qlandkarte'. As a first test open QLandkarte and go to menu 'Copyright->Driver'. The copyright notice should open. If another driver is in place you have to edit '~/.config/QLandkarte/QLandkarte.conf' at this stage.

Time to get accustomed to the files in 'device'.

IDevice.h This is the base class definition of your driver as it is seen by the application. There is quite some documentation to read in the header file. If you add anything to IDevice you must increment INTERFACE_VERSION

IDeviceDefault.* This will be the base class of your driver implementation. Your driver has to implement all methods with a leading '_'. The CDevice template should have method stubs already.

Garmin.* That is where all the data structures and enumerations from the Garmin protocol specificaton go. Most likely you will have to add some data structure. Don't forget to define the shift operators to exchange data between QLandkarte's and Garmin's data structures. If you do it in Garmin.cpp others can use it, too.

CUSB.* That is the implementation of the USB lowlevel commands like open(), close(), read()and write(). CUSB aims to support as many devices as possible. However if your device has a special USB quirk, subclass CUSB and fix it there. If you are not sure, ask the list.

CSerial.* Same as USB for serial port devices.

Let's start to implement. First you want to edit all copyright notices. Kudos who deserves it. After that you will change '#undef DBG' in CUSB.cpp to '#define DBG', recompile and start QLandkarte from console. Try a simple waypoint download. This should dump the initial sync. up sequence.

      ...
      14 00 00 00 ff 00 00 00 6c 00 00 00 24 01 36 01  ........l...$.6.
      47 50 53 4d 61 70 36 30 43 53 58 20 53 6f 66 74  GPSMap60CSX Soft
      77 61 72 65 20 56 65 72 73 69 6f 6e 20 33 2e 31  ware Version 3.1
      30 00 56 45 52 42 4d 41 50 20 52 65 63 20 52 6f  0.VERBMAP Rec Ro
      75 74 61 62 6c 65 20 48 77 79 20 42 61 73 65 6d  utable Hwy Basem
      61 70 2c 20 41 54 4c 20 76 32 20 32 2e 30 30 00  ap, ATL v2 2.00.
      56 45 52 53 4d 41 50 20 51 4c 61 6e 64 6b 61 72  VERSMAP QLandkar
      74 65 20 30 2e 30 30 00                          te 0.00.
 124 310 GPSMap60CSX Software Version 3.10
      ...
      

The line '124 310 GPSMap60CSX Software Version 3.10' tells you the product ID as hex. value, the software version as decimal and the device string. Now you can uncomment the code in _acquire() and change it accordingly. Try to evaluate as much data as possible to avoid false use by an unsupported device.

This will be the next section of interest:

      ...
      Protocol: P0
      Protocol: L1
      Protocol: A10
      Protocol: T1
      Protocol: A100
      Protocol: D110
      Protocol: A201
      Protocol: D202
      ...
      

It tell's you the exchange and data protocols used by your device. For details please refer to Garmin's specification.

This brings us to the end of this tutorial. From this point on you have to find the way on your own. I recommend to have a look at other device drivers. Especially the GPSMap60CSX driver is from the author of QLandkarte. Copy the parts you need, skip the bugs.

And why did you recommend a USB/serial port sniffer? You can trust Garmin's specification, or not. I decided to have a look on what MapSource is doing with the device, while I developed QLandkarte. Especially uploading maps is not documented at all.