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.
