$Id: README,v 1.3 2000/05/29 18:08:35 decouto Exp $
29 May 2000
Douglas S. J. De Couto
decouto@lcs.mit.edu
README -- Garble v1.0.1
http://www.pdos.lcs.mit.edu/~decouto/garble
NOTE: (5 jan 2001) etrex support, thanks to a kind Danilo Beuche , download http://www.pdos.lcs.mit.edu/~decouto/garble/etrex.tar.gz.
NOTE: (12 nov 2001) a preliminary java version of this library is available at java-garble.tar.gz.
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
, , and
7. Mailing Lists / Contact
There are three lists:
garble-announce@lists.sourceforge.net -- for announcements about Garble.
garble-users@lists.sourceforge.net -- for discussions about using Garble.
garble-devel@lists.sourceforge.net -- 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 decouto@lcs.mit.edu
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).