readme

Garble is a C++ program for transferring data to and from Garmin GPS

$Id: README,v 1.3 2000/05/29 18:08:35 decouto Exp $

29 May 2000
Douglas S. J. De Couto
[e-mail]

README -- Garble v1.0.1
http://www.pdos.lcs.mit.edu/~decouto/garble

Contents:
0. License
1. Introduction
2. Compatibility and Features
3. Using Garble
4. Output Formats
5. Building and Installing
6. The Insides
7. Mailing Lists / Contact
8. Source Code
9. Changes in New Version 


0. License

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA.


1. Introduction

Garble is a C++ program for transferring data to and from Garmin GPS
receivers.  It is based on a set of library routines that implement
the the Garmin protocol specification (available in the support
section at http://www.garmin.com).  The core routines are portable,
and were originally developed under MacOS --- this distribution
compiles and runs under Linux i386.


2. Compatibility and Feature

Garble v1.0.1 supports downloading waypoints, proximity waypoints,
routes, and track data from most Garmin GPS units.  The underlying
library supports uploading waypoints, proximity waypoints, and routes
to GPS 12, GPS 12 XL, GPS 48, GPS II Plus, GPS 128 models, although
the current version of the program does not implement those functions.
Garble can also transfer date, time, and position data from most
Garmin receivers.  Garble can command GPS receivers to turn off.
Garble has been tested using a GPS 12 XL with firmware version 3.53,
and a GPS III+.


3. Using Garble

Here is the program's help output, obtained by running it with the
--help option:

All data is sent to standard out.  Only the last GPS action option is used.
-d, --device dev-name             use device specified by dev-name, defaults to /dev/gps
-m, --timeout t                   wait up to t milliseconds to receive data, defaults to 1500
-r, --get-routes                  download routes
-w, --get-waypoints               download waypoints
-x, --get-proximity-waypoints     download proximity waypoints
-t, --get-tracks                  download tracks
-i, --get-gps-info                get GPS product info
-o, --turn-off                    turn off GPS
-z, --get-time                    get time from the GPS
-p, --get-pos                     get the current position
-v, --version                     current version of Garble
-e, --echo                        echo parameters and quit
-l, --verbose                     use verbose error messages
-h, --help                        print this message

You must have read and write access to your serial ports -- either run
as root, or add your user to the tty group in /etc/group.  /dev/ttyS0
is COM1, ttyS1 is COM2, etc.  See the Linux Serial HOWTO for more
information.

For example, the following command will list the waypoints on standard
out:

garble -d /dev/ttyS0 --get-waypoints


4. Output formats:

4.1 Waypoints are listed in the following format:

Waypoint-id / lat, lon / comment

Latitude and longitude are in degrees, + is North, East.

4.3 Proximity waypoints are listed in the following format:

Waypoint-id / distance / lat, lon / comment

Distance is in meters.

4.4 Routes are listed as a series of waypoints, with blank lines
between routes.

4.5 Tracks are listed as series of trackpoints, with blank lines
between separate tracks.  The trackpoint format is:

lat, lon / time

Time is in the C library format, in the following format (from the
ctime manpage):

"Wed Jun 30 21:49:08 1993\n"


5. Building and Installing:

untar and gunzip the archive, e.g. 

gzip -d garble-1.0.1.tar.gz
tar xf garble-1.0.1.tar

If you are running Linux on an i386, it is very simple:

Type "make dep; make" in the garble-1.0.1 directory, it should give you
an executable named garble in that directory.  That's it!

If you are running on a different architecture, e.g. PowerPC, change
the CPPFLAGS line in the Makefile to have -DDO_BYTE_SWAP instead of
-UDO_BYTE_SWAP.  If anyone is a configure whiz and wants to hook this
up for Garble, let me know!


6. The Insides:

The Garble core is a set of 3 classes in namesace garmin, which
implement the Garmin physical layer (serial line), link layer (packet
transfer), and application layer (data transfer protocols).  Each
layer depends upon the previous layer:

garmin::application_layer
-------------------------
garmin::link_layer
-------------------------
garmin::physical_layer

The physical_layer class is an abstract base class; I have included an 
implementation that uses the serial ports on Linux:
garmin_serial_unix. 

This code was written to swap bytes when neccesary in multibyte values
when transferring data to and from the GPS and the computer.  For
instance, Macintosh and Garmin use different byte orderings; Macintosh
is big-endian, and Garmin is little-endian.  

Garble requires the standard C++ libraries to compile, notable
<string>, <vector>, and <list>


7. Mailing Lists / Contact

There are three lists:

[e-mail] -- for announcements about Garble.
[e-mail] -- for discussions about using Garble.
[e-mail] -- about development of Garble.

See:

 http://lists.sourceforge.net/mailman/listinfo/garble-announce
 http://lists.sourceforge.net/mailman/listinfo/garble-users
 http://lists.sourceforge.net/mailman/listinfo/garble-devel

for information on the lists, or email garble-devel-request,
garble-users-request, or garble-announce-requests, all
@lists.sourceforge.net for information.

I can be contacted personally at [e-mail]

Please let me know if you have any comments!


8. This project is hosted by SourceForge (http://www.sourceforge.net);
the sources are available for anonymous CVS from
cvs.garble.sourceforge.net with CVSROOT /cvsroot/garble, check out
module garble/garble-src; see
http://sfdocs.sourceforge.net/sfdocs/site/cvs.php for more
information.


9. Changes in New Version 

Version 1.0.1 is a bug fix from version 1.0, which makes Garble work
even with serial port devices which are normally ``cooked'' -- that
is, they perform some form of processing on serial port data.  One
work around is to use raw devies (e.g. /dev/cua0), or to ``stty -f
/dev/gps raw'' (or the appropriate device if you are not using
/dev/gps).