/*-------------------------------------------------------------------------
|   garmin_gps is a linux kernel driver to access garmin gps devices
|   connected to a linux box by usb.
|
|   Copyright 2006 by Hermann Kneissel herkne@users.sourceforge.net
|
|   This code is free software; you can redistribute it and/or
|   modify it under the terms of the GNU Library General Public
|   License as published by the Free Software Foundation; either
|   version 2 of the License, or (at your option) any later version.
|
|   This code 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
|   Library General Public License for more details.
|
|   You should have received a copy of the GNU Library General Public
|   License along with this library; if not, write to the Free
|   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
--------------------------------------------------------------------------*/
This is README for version 0.32


This is my first linux kernel driver, so expect some glitches.
I have tested this driver with a GPSmap60C in a 2.6.7 kernel, it 
also seems to work with a GPS-18. Since both devices show the
same usb product id i assume that garmin uses a common usb
interface in all its devices, so i expect other models to be
working too.

Applications i successfully used with this driver are 
gpsman version 6.1.2 and the latest gpsbabel (although gpsbabel
sometimes produces segmentation faults, it seems some
fields are not set correctly when using this driver but i have
not yet checked if this also happens when using a gps
connected via the serial bus).

Hermann Kneissel






URL
	http://sourceforge.net/projects/garmin-gps/



FILES

	This release consists of the following files:

	README		you are reading it now
	compile.sh	shell script to compile the kernel module
	garmin_gps.c	the kernel driver



CHANGES

	0.32		Continue reading from bulk-in even after the gps indicated
			end-of-data.

	0.31a		Added missing #ifdefs for older kernel versions.

	0.31		Added a patch from Ondrej Palkovsky <ondrap@penguin.cz>
			- the 'ACK' packet is sent after the transfer of the USB packet is 
			completed, i.e. in the write_callback function. Because the close 
			function sends the 'abort' command, a parameter is added that allows 
			the caller of garmin_write_bulk to specify, if the 'ack' should be 
			propagated to the serial link or dimissed.
			This fixes the problem with gpsbabel, it has sent several packets that 
			were acknowledged before they were sent to the GPS and GpsBabel closed 
			the device - thus effectively cancelled all outstanding requests in the 
			queue.
			- removed the APP_RESP_SEEN and APP_REQ_SEEN flags and changed 
			them into counters. It evades USB reset of the gps on every device close.

			This version requires at least kernel version 2.6.16

	0.28		Updated to work with the x-Series of gps receivers
			(eg. GPSmap60Cx)

	0.22		Updated to compile with 2.6.10-rc1. Restructured
			the code according to suggestions from Greg KH.
			Note: this driver will NOT compile with kernels
			2.6.9 or below.

	0.19		In native mode replies for a start-session request
			send by a client will now be answered by the driver.
			First version of a regression test.
			Most unused code removed.
		




INSTALLATION

The driver requires 'USB Serial Convert support' to be configured.

To compile it put all the files into a directory and and use the 
supplied shell script to compile/install the module:

	/bin/sh compile.sh <kernel-source-dir>
	




USAGE

If you are using hotplugging the driver should be loaded automatically
as soon as you plug your gps in. Configure your favourite gps program
to use the tty port assigned to the driver (eg. /dev/usb/tts/0). If it
does not get a connection on the first try, close and restart the program.

The driver supports the following parameters:

debug=x		enables debug output. x=1/0

initial_mode=x	sets the mode of operation. At the moment two modes
		are defined:

	0	is a raw-mode, where all data written to the tty-port
		is send directly the the device and all data send
		by the device is written to the usb bus. Please note
		that at the moment in this mode no checking for package
		boundaries is done. Each write operation must contain
		a complete package structure as described in [2].

	1	(this is the default) In this mode all data read from
		the tty is assumed to be in the garmin serial protocol
		format described in [1]. Data read from the gps will
		be converted into this format before being sent to the
		tty port. Please not that at the moment the checksum
		will be ignored and all handshake packages are assumed
		to contain ACKs.


I also provided a small test program which allows to change mode
and debug settings without haveing to reload the module. The tty-port
is currently hardcoded, so if you are using a port other than
/dev/usb/tts/0 you must change the port in the source code.

At the moment garmin_gps_ctl knows the followin commands:

	garmin_gps_ctl reset	causes a reset of the usb device.
	garmin_gps_ctl debug x	changes the debug settings to x
	garmin_gps_ctl defmode x changes the default mode to x

Compile it using
	gcc -o garmin_gps_ctl garmin_gps_ctl.c


If you are interested in nmea-output, have a look at garminusb2nmea,
a program contributed by Manuel Kasper which converts the data read 
from the gps into nmea sentences. This program can also be downloaded 
from the sourceforge page.





REFERENCES

[1] GARMIN GPS Interface Specification
    http://www.garmin.com/support/pdf/iop_spec.pdf

[2] GARMIN GPS Interface Specification
    USB Addendum (Rev.1)
    http://www.garmin.com/support/pdf/USBAddendum.pdf


TRADEMARKS

Garmin and GPSmap are registered trademarks of Garmin Ltd (www.garmin.com)

