$Id: README,v 1.3 2000/05/29 18:08:35 decouto Exp $29 May 2000Douglas S. J. De Coutodecouto@lcs.mit.eduREADME -- Garble v1.0.1http://www.pdos.lcs.mit.edu/~decouto/garbleContents:0. License1. Introduction2. Compatibility and Features3. Using Garble4. Output Formats5. Building and Installing6. The Insides7. Mailing Lists / Contact8. Source Code9. Changes in New Version 0. LicenseThis program is free software; you can redistribute it and/ormodify it under the terms of the GNU General Public Licenseas published by the Free Software Foundation; either version 2of 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 ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See theGNU General Public License for more details.You should have received a copy of the GNU General Public Licensealong with this program; if not, write to the Free SoftwareFoundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,USA.1. IntroductionGarble is a C++ program for transferring data to and from Garmin GPSreceivers.  It is based on a set of library routines that implementthe the Garmin protocol specification (available in the supportsection at http://www.garmin.com).  The core routines are portable,and were originally developed under MacOS --- this distributioncompiles and runs under Linux i386.2. Compatibility and FeatureGarble v1.0.1 supports downloading waypoints, proximity waypoints,routes, and track data from most Garmin GPS units.  The underlyinglibrary supports uploading waypoints, proximity waypoints, and routesto GPS 12, GPS 12 XL, GPS 48, GPS II Plus, GPS 128 models, althoughthe current version of the program does not implement those functions.Garble can also transfer date, time, and position data from mostGarmin 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 GarbleHere 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 messageYou must have read and write access to your serial ports -- either runas root, or add your user to the tty group in /etc/group.  /dev/ttyS0is COM1, ttyS1 is COM2, etc.  See the Linux Serial HOWTO for moreinformation.For example, the following command will list the waypoints on standardout:garble -d /dev/ttyS0 --get-waypoints4. Output formats:4.1 Waypoints are listed in the following format:Waypoint-id / lat, lon / commentLatitude and longitude are in degrees, + is North, East.4.3 Proximity waypoints are listed in the following format:Waypoint-id / distance / lat, lon / commentDistance is in meters.4.4 Routes are listed as a series of waypoints, with blank linesbetween routes.4.5 Tracks are listed as series of trackpoints, with blank linesbetween separate tracks.  The trackpoint format is:lat, lon / timeTime is in the C library format, in the following format (from thectime 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.gztar xf garble-1.0.1.tarIf 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 youan executable named garble in that directory.  That's it!If you are running on a different architecture, e.g. PowerPC, changethe 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 thisup for Garble, let me know!6. The Insides:The Garble core is a set of 3 classes in namesace garmin, whichimplement the Garmin physical layer (serial line), link layer (packettransfer), and application layer (data transfer protocols).  Eachlayer depends upon the previous layer:garmin::application_layer-------------------------garmin::link_layer-------------------------garmin::physical_layerThe 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 valueswhen transferring data to and from the GPS and the computer.  Forinstance, Macintosh and Garmin use different byte orderings; Macintoshis big-endian, and Garmin is little-endian.  Garble requires the standard C++ libraries to compile, notable<string>, <vector>, and <list>7. Mailing Lists / ContactThere 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-develfor 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.eduPlease 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 fromcvs.garble.sourceforge.net with CVSROOT /cvsroot/garble, check outmodule garble/garble-src; seehttp://sfdocs.sourceforge.net/sfdocs/site/cvs.php for moreinformation.9. Changes in New Version Version 1.0.1 is a bug fix from version 1.0, which makes Garble workeven with serial port devices which are normally ``cooked'' -- thatis, they perform some form of processing on serial port data.  Onework 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).