Blame | Last modification | View Log | RSS feed
===========================================================================
GARMINTOOLS
===========================================================================
This software provides Linux users with the ability to communicate with the
Garmin Forerunner 305 via the USB interface. While this is the only Garmin
unit that I own, I did implement all of the documented Garmin protocols
(http://www.garmin.com/support/pdf/IOSDK.zip) as of Rev C (May 19, 2006)
over the USB physical link. This means that if you have a Garmin with a
USB connection to a PC, you ought to be able to use this software to
communicate with it.
==> You will need to make sure that the 'garmin_gps' kernel module is not
loaded or compiled into your kernel. This module conflicts with the
garmintools software.
If you're looking for a complete solution to all of your Linux Garmin GPS
needs, this is not it. I own a Garmin Forerunner 305 and wrote this code
specifically so I could download and save data from that particular GPS
unit to my Linux machine. I tried gpsbabel (http://www.gpsbabel.org), but
found that it did not have command line options specific to the Forerunner
run and lap data - all I could do was get the tracklog. That's how all of
this got started. I also wanted a few other things, like the ability to
convert a track log into a Google maps encoded polyline, and (eventually)
the ability to generate PNG images of heart rate and elevation data.
You need to have the libusb library (http://libusb.sf.net) installed. You
must also have read and write permissions to the device file through which
the Garmin unit is accessed. The easiest thing to do is run the programs
as root. Alternatively, you can write a hotplug script. I haven't tried
this yet.
As of version 0.01, this software gives you the ability to do the following:
1) Get basic information from the Garmin unit, such as its software version
and supported protocols. To do this, use 'garmin_get_info'.
2) Save runs and associated track logs from the Garmin unit to disk. To do
this, use 'garmin_save_runs'. Files are saved with the extension ".gmn"
and are named by the run start time (e.g. '20070121T151814.gmn'). The
.gmn file format is a binary file format that can be unpacked with the
same functions that unpack the raw data from the Garmin unit itself. It
is substantially more efficient than the bloated XML format that Garmin
uses.
IMPORTANT NOTE: The output of garmin_save_runs will tell you where on
your filesystem the actual .gmn files were saved. The default is to
save them in a directory tree (by year and month) under the current
directory. You can override this by setting the environment variable
GARMIN_SAVE_RUNS to whatever directory you like.
ANOTHER IMPORTANT NOTE: Old workouts are not deleted from the watch,
and their laps hang around for a long time. This once led me to
clobber half a dozen saved runs with truncated files containing
only the lap data (because the associated track logs had long since
been overwritten in the Forerunner's memory). Therefore, if a file
with the same name already exists, it is *not* overwritten.
FINAL NOTE: As a result of that rather unpleasant experience, I wrote
a Perl script 'fore2gmn.pl' (included in the 'extras' directory) that
can convert a .hst file (the XML format exported from Garmin Training
Center) to a set of .gmn files. These .gmn files are saved in the
current working directory without any of the year/month hierarchy
business. Using this script, I was able to restore the six files
that I had lost.
3) Dump the contents of a .gmn file. To do this, use 'garmin_dump'. The
output of garmin_dump is XML-like, and is mainly meant to be used for
debugging.
4) Print, in an XML-like format, the encoded polyline representation of a
.gmn file (for Google maps) along with other information such as the
start and center latitude/longitude, and the lat/lon bounding box.
To do this, use 'garmin_gmap' on a .gmn file.
In addition, the garmintools API in src/garmin.h gives you the ability to
read a .gmn file and do pretty much anything you want to it.
I chose to write this software in C. C++ programmers (and I am one of
them) might have a look at the code and ask, "Why not do this in C++ and
spare yourself all of the switch statements?" I don't have a good answer,
just a bunch of half-answers, and I may end up changing my mind. The
bottom line is that even after years of C++ programming, I still like to
stick with C when I can. If you've ever had to deal with aCC on HP-UX,
you understand.
CAVEAT: I have only tested this software with the Forerunner 305 that I
own. I don't know if it works with the Edge 205/305 or the Forerunner 205.
In principle, it should at least save the files successfully.
ONE MORE CAVEAT: The 'garmin_gmap' utility expects a .gmn file with a
D304 track point data type. This is the data type used by the Forerunner
305. I WILL FIX THIS SOON. Also, the output of garmin_gmap is not for
the faint of heart. You will need to have your own website where you
can put this encoded polyline in an HTML file, following the instructions
on the Google maps API reference pages:
http://www.google.com/apis/maps/documentation/
I may make this easier some day. For now, this is how it is.
Dave Bailey
Truckee, CA
22 February 2007