
		Tgps by Tero Kivinen <kivinen@iki.fi>
		www-site: http://www.acr.fi/tgps/

Description
-----------

Tgps is a program that allows you to retrieve and send data to Garmin
GPS receiver(s). It is also intended to be a Garmin protocol
simulator, that allows you to generate NMEA and Garmin output for
multiple destinations from a single GPS device.


Compilation
-----------

Unpack the distribution by saying

	tar zxvf tgps-x.x.tar.gz

or

	gzip -cd | tar xvf -

After the distribution has been unpacked cd to the directory created
and run the configure script:

	cd tgps-x.x
	./configure

After that just say make, and if that compiles ok, then install the
tgps package by make install.


How to use tgps
---------------

To test the tgps program connect your Garmin device to your computer.
Turn the Garmin device on and make sure that it is configure to talk
garmin protocol (see your garmin manual to get instructions how to
verify that). The run the tgps program with -v option like this:

	tgps -v -f /dev/tty00

where the /dev/tty00 is the device name where the gps is connected
(other names can be /dev/ttyS0, /dev/cua0, /dev/com1). 

It should print something like this (long lines ware splitted to
multiple lines to make it easier to read):

	V1      D
	Product id = GPS III Plus (119), software version = 2.04
	description = GPS III+ Software Version  2.04 
	Supported protocols: L001 A010 A100 A200 A300 A500 A600 A700
		D104 D201 D300 D501 D600 D700 
	Additional strings: 
	VERBMAP Atlantic Highway Land Data 1.00
	Supported protocols: P000 L001 A010 A100 A200 A300 A500 A600
		A700 A800 A900 D104 D201 D300 D501 D600 D700 D800

The first line means that output is version 1, and the latitude and
longitudes are given out as degrees. The second line means that the
tgps was able to request a product id from the gps device, and the
product id for the device is "GPS III Plus" and it has a number of
119.

If the tgps does not recognize your device (i.e it prints out "Unknown
(xxx)") you need to add new entry to the tgps_garmin_products table in
garmin.c. Send me a note saying the type of the device, the product id
number (number printed in parenthesis in after the product id text),
and the "Supported protocols" line, so I can add that device to the
next version of tgps.

The next line gives the product description and list of supported
protocols based by the internal database. After the "Additional
strings" there can be multiple lines telling some other information
about the device. The last "Supported protocols" line is received from
the gps using the product data protocol supported by the newer garmin
devices.

After that the tgps waits for input from the gps device. Now you can
go to the menus and request gps to send for example the waypoints to
the host and you will see lines like this (long lines ware splitted to
multiple lines to make it easier to read):

	W1	WALLAC	CRTD 18:44 12-JUL-00	47.0709658
		12.8389782	Smbl=lodging, Dspl=S+N

Just press Ctrl-C TWICE to exit the tgps. The first one will abort all
operations to the gps and it will exit after the gps device
acknowledges those abort operations (about after a second). The second
Ctrl-C will exit immediately and it will work even if the gps is
turned off or if the cable has been disconnected.

Next you can back up your gps device in case you make some mistakes
while testing the tgps. You can do that by saying:

	tgps -r -f /dev/tty00 -o routes-%F
	tgps -w -f /dev/tty00 -o waypoints-%F

That will store the routes and waypoints to files named
routes-yyyy-mm-dd and waypoints-yyyy-mm-dd. Check those files and
verify that the coordinates and the amount of data in those are
correct. Then you can start playing with the upload feature. First try
uploading the example track included by the tgps:

	tgps -u -f /dev/tty00 -i track-example

You should see few lines of dots appearing to the screen. A dot is
printed after one entry has been uploaded to the gps. The example
track might be too long for the older garmin units, but it should
still work fine also in those device. They will just see the end of
the track log.

After the upload is ready go the gps map page and zoom out. After that
scroll to the coordinates N 47.16 and E 12.81 and zoom in. You
should now see a road called Grossglockner Hochalpenstrae in the
middle of Austria between Fusch and Heiligenblut.

If you upload also the waypoint-example and route-example it will give
one waypoint for each "kehre" (hairpin curve) named "KEHxx" where the
xx is the number of curve. It will also give some other curves (KVHxx:
curves going up to the Kaiser-Franz-Josefs-Hhe and EDELKx: curves
going up to the Edelweisshtte). The waypoint file will also contain
few other places in the road. The route is the tracback route for the
full road.

Remember that when you upload any track logs to the gps device it will
automatically turn off the track log recording, so remember to turn
that on after you stop playing around with the example tracks.

If you want to remove the routes and waypoints uploaded from the
example files, remove all routes and waypoints and restore the
waypoints and routes you backuped up earlier by using

	tgps -u -f /dev/tty00 -i waypoints-yyyy-mm-dd

and

	tgps -u -f /dev/tty00 -i routes-yyyy-mm-dd

For easier use of the tgps make a symbolic link from the serial line
to the /dev/gps0, so you don't need to give the -f option all the
time. If you cannot make the symlink you can set the GPSDEV
environment variable to point to the serial line. 

For instructions how to use the tgps program refer to the manual page
of the tgps. 


Reporting bugs
--------------

If you find a bug or have a feature request send them to
tgps-support@acr.fi.



					Tero Kivinen
					kivinen@iki.fi
					http://www.iki.fi/kivinen/
