.\" $snafu: garload.1,v 2.0 2003/10/06 19:14:06 marc Exp $
.\"
.\" Public Domain, 2001, Marco S Hyman <marc@snafu.org>
.\"
.Dd May 7, 1998
.Dt GARLOAD 1
.Os SNAFU\ Software
.Sh NAME
.Nm garload
.Nd load waypoints, routes, and tracks to a Garmin GPS unit
.Sh SYNOPSIS
.Nm
.Op Fl v
.Op Fl d Ar debug-level
.Op Fl p Ar port
.Sh DESCRIPTION
.Nm
will load waypoint, route, and/or tracking information to a Garmin GPS unit
from standard input.  The data is expected to be in the format dumped
by
.Xr gardump 1 .
The input can be re-directed from a file, loading data that was
dumped using gardump.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl v
Display the software version on stderr and exit with a return code of 1.
.It Fl d Ar debug-level
Enable various levels of debugging output.  Without this option
debugging is disabled and only critical errors are written to
stderr.  Additional debug output at the various levels are:
.Bl -tag -width Ds
.It 1
Write all error messages to stderr.
.It 2
Write status messages to stderr.
.It 3
Write Garmin application protocol status to stderr.
.It 4
Perform a dump of all data going in and out of the Garmin
layer 2 protocol machine.  Data sent to the
.Tn GPS
is prefixed by the symbol
.Li } .
Data received from the
.Tn GPS
is prefixed by the symbol
.Li { .
Data is written to stderr.
.It 5
Perform a dump of all data read from/written to the GPS unit.
Data sent to the
.Tn GPS
is prefixed by the symbol
.Li > .
Data received from the
.Tn GPS
is prefixed by the symbol
.Li < .
Data is written to stderr.
.El
.It Fl p Ar port
Use
.Ar port
as the device connected to the GPS unit.  The default port is a
compile time option that is typically set to
.Pa /dev/tty00 .
.El
.Pp
.Nm
reads stdin and determines what to do based upon the data read.
Data is assumed to be in the format created by
.Xr gardump 1 .
That program outputs waypoints, routes, and track logs, preceding
each section by a ``comment'' in square brackets.
.Nm
uses the ``comment' to determine what data to upload.  The ``comments''
acted upon are:
.Bl -tag -width Ds
.It [waypoints, n records]
Begin upload of waypoints.  The number of records is ignored.
.It [routes, n records]
Begin upload of routes.  The number of records is ignored.  Routes are
composed of a route header followed by route waypoints.
.It [tracks, n records]
Begin upload of a track log.  The number of records is ignored.
The time/date field in track log entries, if present, is ignored
on upload.
.It [end transfer, n/m records]
Terminate any existing upload.
.El
.Pp
Each tranfer should be terminated by an `[end transfer...] record before
the next transfer is started.
.Nm
will ignore any line where the first non-blank character is ``#''. This
allows comments to be added to files that will be processed by
.Nm garload .
A brief description of the record format for waypoints, routes, and tracks
is output by
.Xr gardump 1
in the form of a comment as part of each download.
.\".SH ENVIRONMENT
.\".SH FILES
.\".SH EXAMPLES
.\".SH DIAGNOSTICS
.Sh SEE ALSO
.Xr gardump 1
.\".Sh HISTORY
.Sh AUTHORS
Marco S. Hyman using information from the published GARMIN GPS Interface
Specification, dated December 6, 1999 and the note OBSERVATIONS OF THE
GARMIN-GARMIN PROTOCOL by william.soley@sun.com and werme@zk3.dec.com.
.Sh BUGS
Tested with a Garmin GPS III+ and GPS V using OpenBSD versions
2.3 through 3.3 running on SPARC and i386.  May not work with other
GPS units or operating systems