-------------------------------------------------------------------------------
Section 1.	Introduction.

	Date: August 29, 2006.

	Welcome,

	This is release 2.0.3 of the DarkGPS software distribution.

	This software allows you to control your GPS receiver.

	The software supports all 6, 8 and 12 Channel Motorola GPS
	receivers and the HPZ3801A GPS based frequency source.
	Connection can be made via a local serial port or via the net.

	The software can also generate data, of HP receiver parameters,
	which can be used to create graphs using the "gpschart" program.
	"gpschart" is included in this distribution.

	Please note that the software is only supported under Linux.

	The software is (c)Copyright of GS3 Technologies Inc. and is
	released under the GPL.
	
	All questions should be sent via the online forum for darkgps,
	on the http://www.gs3tech.com/ web site.
	
	Updates to this software will be posted at the GS3 Web Site as
	they become available.

	The following people have contributed greatly to the darkgps software:

	Mr. Sonny Mann
			Day to day support and suggestions have made this program
			possible. By far the greatest contribution.
			Sonny, thank you for everything.

	Mr. Carl R. Friend
			Thanks Carl for the many fixes, additions, general help
			and support.  I will take you up on that drink next
			time you are in NYC, I promise.

	Mr. George Kontakis
			A most valuable friend over the years and always
			there for support. Thanks G for everything.

	Mr. John Ackermann
			For giving me the initial idea on starting a
			program like this for Linux.

	Mr. Paul Burgess
			Thanks Paul for access to the M12 and beta testing.
			The Time Zone feature is all your idea.

	Mr. Glenn Powers
			The suggestion to add a maximum connection limit
			was perfect. Thank you!

	All the time-nuts members for their very helpful support
	on a variety of issues. Thank you everyone!

	I hope you enjoy the software as much as I enjoyed writing it.

	George Hrysanthopoulos, N2FGX
	
-------------------------------------------------------------------------------
Section 2.	Table of contents

	Section  1.	Introduction
	Section  2.	Table of Contents
	Section  3.	Quick start for a network connected receiver
	Section  4.	Quick start for a serial port connected HP Z3801A receiver
	Section  5.	Hardware supported
	Section  6.	Software Requirements
	Section  7.	Inventory
	Section  8.	Setup and Install
	Section  9.	Using the program with curses

	Section 10.	Connecting to a network attached GPS receiver

	Section 11.	Connecting to a Motorola Receiver attached
				to a serial port.

	Section 12.	Connecting to a HP Z3801A Receiver attached
				to a serial port.

	Section 13.	Using the gpsdisplay program as a daemon.
				HTML output for Motorola receivers.

	Section 14.	Using the program as a daemon.
				HTML and timelog output for HP receivers.

	Section 15.	Using the program as a daemon.
				For NTP shared memory receivers.

	Section 16.	Creating output in a non-curses, non-daemon, non-HTML system.

	Section 17.	Using a command file to initialize the receiver,
				for timing and navigation applications.

	Section 18.	Debug mode details

	Section 19.	Starting up the shared memory connector, "ntpscon".

	Section 20.	Creating charts for HP Receiver data.

	Section 21.	A complete example of connecting to an HP receiver and
				generating charts and HTML files.

	Section 22.	Complete curses command and key reference.

	Section 23.	Complete command line reference.

	Section 24.	Complete initialization file reference.

	Section 25.	The timesplit program
-------------------------------------------------------------------------------
Section 3.	Quick start for a network connected receiver

	Create a directory where the software will be installed.
	Copy "darkgps_2.0.tgz" there and do:

	tar -xzvf darkgps_2.0.tgz

	Make sure you have perl Curses installed. To install
	the module, as root do:

	# perl -MCPAN -eshell install Curses

	and then:

	./gpsdisplay www.darksmile.net

	You should see a screen of the data from the darksmile.net GPS receiver.

-------------------------------------------------------------------------------
Section 4.	Quick start for a serial port connected HP Z3801A receiver

	Create a directory where the software will be installed.
	Copy "darkgps_2.0.tgz" there and do:

	tar -xzvf darkgps_2.0.tgz

	Make sure you have perl Curses installed. Or as root do:

	perl -MCPAN -eshell install Curses

	Make sure you have perl Device::SerialPort installed. To install
	the module, as root do:

	# perl -MCPAN -eshell install Device::SerialPort

	and then:

	./gpsdisplay -s /dev/ttyS0 -r H

	You should see the data from your receiver connected to
	/dev/ttyS0. If you are connected to another port, just use that
	device instead.

-------------------------------------------------------------------------------
Section 5.	Hardware supported.

	The software has been tested with 6, 8 and 12 channel Motorola receivers.
	Some models tested are VT, UT and M12. In fact, all Motorola receivers
	should work fine with this software.

	Only HP Z3801A receivers have been tested. We hope to add more models
	in the future. It is possible that the software will work on the Z3816A
	receivers as well but we haven't tested it.

	If you have a receiver model that you would like supported, please
	get in touch with us in the forum page at http://www.gs3tech.com/
	
	We are always working to add functions to the system.

-------------------------------------------------------------------------------
Section 6.	Software Requirements

	The software should be running on a Linux system.
	For our development, we use Slackware Linux 10.x.
	Other distros that work well are: Red Hat (all versions).
	Debian, SUSE and Ubuntu. As a matter of fact, any Linux
	distribution should work well.

	In order to fully utilize the software, the following
	components should be installed in your system.

	perl
		Required

	perl Module Curses
		Required

	perl Module Device::SerialPort
		If you need to connect to your GPS receiver via
		a serial port, then this module is required.
		If a "network connection only" is needed, then this
		module can be skipped.
										
	perl Modules GD and GD::Graph
		If you need to create charts of the HP receiver values
		then these modules are required. Otherwise they can be skipped.
	
-------------------------------------------------------------------------------
Section 7.	Inventory

		The software consists of the following components:

		Makefile		-	ntpscon Makefile
		gpsdisplay		-	The program that connects with the GPS
							receiver, controls it and generates data.

		ntpscon.c		-	The program that connects with
							the NTP shared memory segment
							and allows the viewing of data via the net.
		ntpscon.h		-	Header file with receiver defs

		sockhelp.c		-	socket helper routines.
		sockhelp.h		-	socket helper include file.

		gpschart		-	The program that generates graphs of HP receiver data,
							like EFC and Holdover Uncertainty.

		README			-	This file.
		CHANGES			-	Change log for all the files here.

		gpsdisplay.ini	-	The referense initialization file. All
							initialization file keywords are detailed there.
		*.ini			-	Some sample initialization files

		timing_setup	-	If this file is read in by the gpsdisplay
							program, it will initialize a Motorola receiver
							to be used for timing applications.
							Use the "read" command to do this.

		nav_setup		-	If this file is read in by the gpsdisplay
							program, it will initialize a Motorola receiver
							to be used for navigation applications.
							Use the "read" command to do this.

		timesplit		-	Takes a log file formatted for the Z3801
							and creates two files with a split along
							an input date.

		WeeklyMaint		-	Example script which uses "timesplit" to breakup
							log files for weekly archiving.

		G1				-	Sample bash script to generate charts for a single
							HP receiver.
		GA				-	Sample bash script to generate charts for a two
							HP receivers.

		darkgps/index.shtml
						-	HTML file which shows the combined
							charts for the two HP receivers in
							the darksmile.net site.

		darkgps/indexsingle.shtml
						-	HTML file which shows the extended
							charts for the two HP receivers in
							the darksmile.net site.
-------------------------------------------------------------------------------
Section 8.	Setup and Install

		In order to setup the software for your system do:

		1.	Create a directory that will contain the software.

		2.	Copy the darkgps_2.0.tgz file there.

		3.	Untar the file:
				tar -xzvf darkgps_2.0.tgz

		4.	Install the perl modules that you need, according
	 		to the "Software Requirements" section above. For each module do:

			perl -MCPAN -eshell install module_name

			or download each module from CPAN, compile and install.

		5.	Execute "make" if you will be using the shared memory connector.
			Just do:

				make

			and the Shared Memory Connector program, "ntpscon",
			will be generated.

		6.	That's it. You now ready to use the program.

			For a quick test do:

			gpsdisplay darksmile.net

			You should now see the darksmile.net GPS receiver data.

-------------------------------------------------------------------------------
Section  9.	Using the program with curses

		The Curses(Full Screen), interface allows for a real-time
		display of receiver data using color and highlighting
		to enhance viewing.

		---------------------------------
		Color sub-section

		Color is used if your terminal supports it.
		It is highly recommended that you use color-xterm
		rxvt, gnome-terminal, Konsole or Eterm.
		
		If you use a color terminal make sure you do:

		# export TERM=term-type

		Where term-type is: "gnome" for gnome-terminal,
		"rxvt" for rxvt, or "Eterm" for Eterm.
		Make sure this is correct.
		---------------------------------

		Now, do:

		Open a xterm, as discussed above, and resize it so it can be
		as big as possible. gpsdisplay will take full advantage of
		a big screen.

		By default, the Curses display is enabled and the screen is divided
		to the following sections:

			+-------------------------------------------+
			+   1. Top Data Section                     +
			+-------------------------------------------+
			+                                           +
			+   2. Live Satellite status section        +
			+                                           +
			+-------------------------------------------+
			+   3. Live receiver data scrolling section +
			+-------------------------------------------+
			+   4. Receiver version data section        +
			+-------------------------------------------+
			+   5. Output and message section           +
			+-------------------------------------------+
			+   6. Command line                         +
			+-------------------------------------------+
			+   7. gpsdisplay version and setup section +
			+-------------------------------------------+

		Certain screens, like help, combine sections 1,2 and 3 into one.
		The main data screen shows all 7 sections.

		The "Top data section" displays time, date, receiver
		health, 1PPS status and other vital stats.

		The "Live Satellite status section" shows how many satellites
		are being tracked by the receiver and the status of each.
		To the right of each satellite line, is the signal strength meter.

		The "Live receiver data scrolling section" shows the raw
		data as it is received from the receiver.

		The "Receiver version data" section is one line of info
		on the version of the Receiver software.

		The "Output and message section" displays command replies and
		systems messages.

		The "Command line" is where all user input is entered.

		The "gpsdisplay version and setup section" shows program version
		and configuration info.

		In Curses mode, the following Function keys are enabled.

		F1	-	Go to main screen

		F2	-	Extended Information Window. Maybe blank.

		F3	-	Display receiver commands which we are not currently
				processing. This screen is only relevant for Motorola
				receivers since we are not parsing all "@@" commands.
				Maybe blank.

		F7	-	System Log window. All system messages and output are shown here.

		F8	-	Terminal Mode Window. This allows the user to send commands to
				a receiver that is connected via the serial port.

		F9	-	Display the help screen.

		F11	-	Lock/Unlock. This is useful when we need to make sure
				that commands are not sent to the program, or receiver, by accident.
				The F11 key is a toggle, so hit once and the system is locked,
				hit again and the system is unlocked.

		F12	-	Quits the program. The program will not exit if it is in "locked"
				mode.

-------------------------------------------------------------------------------
Section 10.	Connecting to a network attached GPS receiver

			In this mode, the only thing you can do is display data.
			However, this can be useful if the status of a receiver
			is needed. By running in this mode you can display what the
			remote receiver "sees".

			To see this system in action, connect to the darksmile.net
			site like this:

				gpsdisplay darksmile.net

			This will show you the GPS receiver data from our site.
			See Section 16 on starting the ntpscon program and sharing your own
			data

-------------------------------------------------------------------------------
Section 11.	Connecting to a Motorola Receiver attached to a serial port.

			In this mode, you have two display options.
			In Default mode, you will see the "Top Data Section", the
			"Live Satellite status section" and the
			"Live receiver data scrolling section".

			In terminal mode you should see any data from the receiver
			and responses to your commands.

			For now, let's go though an example of connecting to UT+
			receiver connected to the /dev/ttyS0 port in terminal mode.
			Let's start the gpsdisplay program:

				$ gpsdisplay -r M -s /dev/ttyS0 -t

			-r M			- The receiver is a Motorola type
			-s /dev/ttyS0	- The serial port is in /dev/ttyS0
			-t				- Start in terminal mode

			You will see the following screen:

			+-------------------------------------------+
			+                                           +
			+   1. Terminal Section                     +
			+                                           +
			+-------------------------------------------+
			+   2. Receiver version data section        +
			+-------------------------------------------+
			+   3. Output and message section           +
			+-------------------------------------------+
			+   4. Command line                         +
			+-------------------------------------------+
			+   5. gpsdisplay version and setup section +
			+-------------------------------------------+

			Let's type a command to send to the receiver:

				@@Aw#ff<Enter>

			The program will compute the checksum and send it to
			the receiver. You will see the response on the
			"Output Data Section" in about 2 seconds.

			The "#" after the "@@Aw" command string, instructs
			the program that the following hex characters should
			be translated to binary before being sent.

			We could've sent the same command as:

				Aw#ff

			The program knows that since we are dealing with a
			Motorola receiver, the starting "@@" is required
			and will be provided.
			
			We could've sent the same command as:

				Aw#  ff

			Spaces will be deleted from the data stream. So a command
			like "Az" could be sent as:

				@@Az# ff ff ff ff
			or:
				Az# ff ff ff ff
			or:
				Az#ffffffff
			It is all the same command.

			If you plan to leave the program unattended for a while,
			you might want to enable lock mode by hitting the F11
			key. This will disable the keyboard until F11 is hit again.
			It should prevent accidental data being entered.
			This feature is not really there for security just
			accident prevention.

			To go back to the main screen just hit F1.
			To see the system log, hit F7.
			To go back to terminal mode hit F8.
			To get help hit F9.
			
-------------------------------------------------------------------------------
Section 12. Connecting to a HP Z3801A Receiver attached to a serial port.

			In this mode, you have two display options.
			In Default mode, you will see the "Top Data Section", the
			"Live Satellite status section" and the
			"Live receiver data scrolling section".

			In terminal mode you should see any data from the receiver
			and responses to your commands.

			For now, let's go though an example of connecting to the HP
			receiver connected to the /dev/ttyS0 port in terminal mode.
			Let's start the gpsdisplay program:

				$ gpsdisplay -r H -s /dev/ttyS0 -t

			-r H			- The receiver is a HP type
			-s /dev/ttyS0	- The serial port is in /dev/ttyS0
			-t				- Start in terminal mode

			You will see the following screen:

			+-------------------------------------------+
			+                                           +
			+   1. Terminal Section                     +
			+                                           +
			+-------------------------------------------+
			+   2. Receiver version data section        +
			+-------------------------------------------+
			+   3. Output and message section           +
			+-------------------------------------------+
			+   4. Command line                         +
			+-------------------------------------------+
			+   5. gpsdisplay version and setup section +
			+-------------------------------------------+

			Let's type a command to send to the receiver:

				:SYSTEM:STATUS?<Enter>

			The program will send this command to the HP
			receiver. You will see the response on the
			"Output Data Section" in about 2 seconds.
			You should see:

			[06/15/06 15:23:38] 15 Jun 2006,19:23:36 -- Lat: N 40:46:18.886, Lon: W 73:54:41.593, Height: +41.92 m (MSL), Sats: 6/2
			
			Hey, what happened to my extended HP display?
			Well, by default it is compressed so save space.
			To see the extended command response, hit Ctrl-V
			which will enable the more "Verbose" display.
			Then try the ":SYSTEM:STATUS?" command again.

			You are now ready communicate with the receiver by entering
			Z3801A commands.

			If you plan to leave the program unattended for a while,
			you might want to enable lock mode by hitting the F11
			key. This will disable the keyboard until F11 is hit again.
			It should prevent accidental data being entered.
			This feature is not really there for security just
			accident prevention.

			To go back to the main screen just hit F1.
			To see the system log, hit F7.
			To go back to terminal mode hit F8.
			To get help hit F9.
			
-------------------------------------------------------------------------------
Section 13. Using the gpsdisplay program as a daemon.
			HTML output for Motorola receivers.
			
			To do this we suggest creating a .ini file with the proper commands
			to setup the receiver.
			
			This is an example of such .ini file. Let's go over the file called:
			"gpsdisplayMoto_ttyS7_daemon.ini" included in this distribution.

				#
				# Hash marks are comments and will be ignored.
				#
				# Timelog does nothing if the receiver type is Motorola
				Timelog				/opt/gpsdata/timelogmoto.log
				#
				# This is the file that will have the HTML formatted receiver
				# status.
				HTTPFile            /opt/http/htdocs/darkgps/motobasic.html
				#
				# Specific colors for different parts of the HTMP data.
				HTMLColors          #66ffff,Blue,#99ff99,Blue,RED
				#
				# Serial port where the receiver is connected.
				SerialPort          /dev/ttyS7
				#
				# Receiver type
				ReceiverType        Motorola
				#
				# We are interested in daemon mode not full screen mode
				FullScreenEnable    Off
				#
				# We will start in main mode
				TerminalMode        Off
				#
				# We will start in daemon mode
				DaemonMode          On
				#
				# The string that will be used in the HTML file
				HTMLTitle           "Motorola Receiver on ttyS7"
				#
				# Set debug mode to "on" and set the debug file name.
				Debug               /opt/gpsdata/gpsdisplayMoto_daemon_ttyS7.log
				#
				# Set verbose mode to 0
				Verbose             0

			Now, let's start the program:

				$ gpsdisplay -i gpsdisplayMoto_ttyS7_daemon.ini

			You will get a prompt but the program will be running in the background
			and generating an HTML file with all receiver data.

			To see this in action have your browser point to:

				http://www.darksmile.net/darkgps/motobasic.html

			We also have the data for all ur receivers at:

				http://www.darksmile.net/darkgps

-------------------------------------------------------------------------------
Section 14. Using the program as a daemon.
			HTML and timelog output for HP receivers.

			To do this we suggest creating a .ini file with the proper commands
			to setup the receiver.
			
			This is an example of such .ini file. Let's go over the file called:
			"gpsdisplayHP_ttyS0_daemon.ini" included in this distribution.

				#
				# Hash marks are comments and will be ignored.
				#
				# Timelog is the file that will contain Receiver values
				# such as EFC, Holdover Uncertainty etc.
				Timelog                 /opt/gpsdata/timelogS0.log
				#
				# This is the file that will have the HTML formatted receiver
				# status.
				HTTPFile            /opt/http/htdocs/darkgps/motobasic.html
				#
				# Specific colors for different parts of the HTMP data.
				HTMLColors          #66ffff,Blue,#99ff99,Blue,RED
				#
				# Serial port where the receiver is connected.
				SerialPort              /dev/ttyS0
				#
				# Receiver type
				ReceiverType            HP
				#
				# We are interested in daemon mode not full screen mode
				FullScreenEnable        Off
				#
				# We will start in daemon mode
				DaemonMode              On
				#
				# The string that will be used in the HTML file
				HTMLTitle               "HP Receiver on ttyS0"
				#
				# Set debug mode to "on" and set the debug file name.
				Debug                   /opt/gpsdata/gpsdisplayHP_ttyS0.log
				#
				# Set verbose mode to 0
				Verbose                 1
				#
				# The "SysInit" Keyword should be the last one in this file.
				# All lines after the "SysInit", will be processed as if they
				# were entered from the keyboard, including comment lines and blanks!
				SysInit
				#
				# Blink the "Alarm" LED
				Blink Alarm
				#
				# Blink the "Enable" LED
				Blink Enable

			Now, let's start the program:

				$ gpsdisplay -i gpsdisplayHP_ttyS0_daemon.ini

			You will get a prompt but the program will be running in the background
			and generating an HTML file with all receiver data.

			To see this in action have your browser point to:

				http://www.darksmile.net/darkgps/hps0.html

			We also have the data from all our receivers at:

				http://www.darksmile.net/darkgps
			
-------------------------------------------------------------------------------
Section 15. Using the gpsdisplay program as a daemon.
			HTML output for NTP shared memory receivers.
			
			To do this we suggest creating a .ini file with the proper commands
			to setup the receiver.
			
			This is an example of such .ini file. Let's go over the file called:
			"gpsdisplayTimelordDaemon.ini" included in this distribution.

				#
				# Hash marks are comments and will be ignored.
				#
				# Hostname is the host that we will be connecting to
				Hostname			Timelord
				#
				# Port is the remote port on hostname that we will be connecting to
				Port				12321
				#
				# This is the file that will have the HTML formatted receiver
				# status.
				HTTPFile            /opt/http/htdocs/GPS/GPStable.html
				#
				# Specific colors for different parts of the HTMP data.
				HTMLColors          #66ffff,Blue,#99ff99,Blue,RED
				#
				# Receiver type
				ReceiverType        Motorola
				#
				# We will start in daemon mode
				DaemonMode          On
				#
				# The string that will be used in the HTML file
				HTMLTitle           "darksmile.net"
				#
				# Set debug mode to "off"
				Debug               Off
				#
				# Set verbose mode to 0
				Verbose             0

			Now, let's start the program:

				$ gpsdisplay -i gpsdisplayTimelordDaemon.ini

			You will get a prompt but the program will be running in the background
			and generating an HTML file with all receiver data.

			To see this in action have your browser point to:

				http://www.darksmile.net/GPS/GPStable.html

			We also have the data at the end of the main page:

				http://www.darksmile.net/

-------------------------------------------------------------------------------
Section 16. Creating output in a non-curses, non-daemon, non-HTML system

			Running gpsdisplay in this mode allows for a quick check of a receiver
			connection. For example connecting to a Motorola receiver
			using the shared memory connector do:

				gpsdisplay ./gpsdisplay -d junk -v 5 -o timelord

			You should see the data from the receiver. You will not go to
			a curses full screen mode.

			For a serial port connected receiver do:

				gpsdisplay ./gpsdisplay -d junk -v 5 -r M -s /dev/ttyS0 -o
			
-------------------------------------------------------------------------------
Section 17.	Using a command file to initialize the receiver,
			for timing and navigation applications.

			In this distribution we have included two files which
			can initialize a Motorola receiver (any model) for
			timing or navigation modes.

			To initialize a receiver using these files, use the internal
			read command.

			From the curses command line, or after the "SysInit" section
			in a .ini file, do:

				read timing_setup

			You will see the program go to terminal mode and run each line
			in the file. This file will setup the receiver for timing
			applications. For a navigation application do:

				read nav_setup

			The read command can be executed even when the program is in
			daemon mode.
			
-------------------------------------------------------------------------------
Section 18. Debug mode details

			Debug mode can be enabled even when the program is started in
			non-debug mode. This can be useful when in daemon mode.

			To enable debug when the program is already running, just
			send a USR2 signal to the gpsdisplay process and
			the debug output will be sent to /tmp/gpsdebug.

			The verbose level will be set to maximum.

			To disable debug mode send a USR3 signal.

-------------------------------------------------------------------------------
Section 19.	Starting up the shared memory connector, "ntpscon".

			The shared memory connector is a facility, provided by the ntpscon
			program, to display data from a Motorola receiver controlled
			by the NTP daemon.

			The connection diagram is as follows:

				GPS Satellites
					|
				GPS Antenna
					|
				Motorola GPS receiver
					|
				Motorola receiver interface board. This allows level
				translation from TTL to RS232 and puts the 1PPS signal
				in the DCD pin.
					|
				Serial Cable with timing from the GPS receiver in the DCD pin
					|
				Computer running Linux with the Nanokernel patches
					|
				NTP Daemon running on the Linux system
					|
				ntpscon program, provided in the darkgps software
					|
				Network/Intranet/Internet
					|
				gpsdisplay program

			To use ntpscon, you must first compile the source. See section 8
			for these instructions. ntpscon is provided with full source code
			and released under the GPL.

			Next, make sure that you have ntpd running on the same system that
			you will be running ntpscon. Also, make sure that ntpd is connected
			to a Motorola GPS receiver.

			ntpscon can now be started. Afterwards, you can use "gpsdisplay"
			to see the data.

			ntpscon has a few command line switches. Here is a list of their
			function.

			-d or --debug		-	Enable debug output when running in
									non-daemon mode
			-h or --help		-	Display a quick usage menu
			-m n or --maxconn n	-	Allow a maximum number of network
									connections.
									This should help prevent any DoS attacks.
									By default, this is set to 25.
			-n or --nofork		-	Don't start in the background. Together
									with debug, this option will allow
									debugging network connections.
			-p n or --port n	-	Port to use when listening for connections.
									Default is 12321.
			-v or --verbose		-	Increase the verbosity level of debug output.

			Normally, you just start ntpscon like this:

				$ ntpscon

			As ntpscon is running, it creates system log entries for events such
			as new connections, connection limit reached etc.

			IMPORTANT:

			ntpscon should have a specific userid for itself, although this is
			not a requirement. The ID should have a password that does not
			allow login, and no privileges whatsoever!

			In other words: Don't run as root!

			We start it like this:
	
				su - ntpscon -c "(cd /export/opt/ntp/timelord/shm; ./ntpscon)"

			After you start ntpscon, you can test it by using the gpsdisplay
			program.

				$ gpsdisplay localhost

			You should now see the data from the local receiver.

			Now, if you'd like, you can open a connection to this port from the
			Internet and allow others to see your data.

			To see our data do:

				gpsdisplay darksmile.net

-------------------------------------------------------------------------------
Section 20. Creating charts for HP Receiver data.

			If the Timelog option is enabled, in the .ini file, or if
			you specify -g timelog_file from the command line,
			then time, EFC, "Holdover Uncertainty" and "Time Interval Offset"
			data will be written to a log file which can then be processed by the
			gpschart program.

			For help on the gpschart program invoke it with the --help option.

			gpschart can create charts for a single receiver or for two
			receivers and put the charts on the same file.

			NOTE:
				
				gpschart is a very CPU and RAM intensive job. On our system,
				to crunch 653000 points takes almost 3 minutes, for a dual
				receiver chart.

				All this is running on a dual processor Xeon 1188MHz
				machine with 1GB RAM.

-------------------------------------------------------------------------------
Section 21.	A complete example of connecting to an HP receiver and
			generating charts and HTML files.

			In the darksmile.net system we run gpsdisplay in daemon
			mode and we create the charts once every ten minutes
			from a cron job that executes gpschart.

			These are the details:

			First start gpsdisplay in daemon mode using a .ini file:

				gpsdisplay -i gpsdisplayHP_ttyS0_daemon.ini

			This .ini file is included with this distribution.

			Then once every ten minutes, from cron, we run the "GA"
			script (also included in this distribution).

			However, the charts can be generated like this:

				./gpschart -i timelogS0.log -e EFC_Chart -u Holdover_uncertainty_chart -t "title"

			Where:

				timelogS0.log is the name of the timelog file generated from
				the gpsdisplay program

			The charts will have the extension .gif appended to them.

			To see this in action point your browser to:

			http://www.darksmile.net/darkgps/

-------------------------------------------------------------------------------
Section 22. Complete curses command and key reference

		In Curses (Full Screen Mode) the user has the capability to
		interact directly with a GPS receiver. In addition to receiver specific
		commands, gpsdisplay also has a set of commands to control the
		software.
			
		Note:	If the program is in Terminal Mode, these commands must be
				prefixed by a "!" in order to be processed. Otherwise they will
				be passed on to the receiver with possibly unpredictable
				results.

		Note:	Commands are not case sensitive, although parameters such
				as file names are.

		Here is a complete list:

		Help
			Brings up the Help screen

		blink A[ctive]|E[nabled]
			HP Receiver only. Blinks the LED specified. Note that the
			blink rate is dependent on command scheduling to the
			HP receiver and will not be a steady rate.
			
			This is to be used for a system check rather than any timing
			application.

		w1
			Display the main program screen.

		w3
			Display the unprocessed commands screen.

		term[inalMode]
			Start "Terminal Mode" and display the terminal window.

			NOTE:	If the program is already in terminal mode,
					this command will do nothing. Also, if the program
					is in terminal mode and this command is entered without
					the initial "!" then it will, again, be ignored.

					The intended action here is that if this command
					is the first in a command file, that is to be read
					in via the "read" command, it will insure that the
					program always go to terminal mode.
			NOTE:	If the receiver is network connected, "Terminal Mode"
					is used only for display purposes.

		sleep n
			Sleep for a specified 1/100 of a second. Sleep 100 would
			sleep for 1 second.
			
			During this time, input from the receiver will be processed
			normally but input from the user will be ignored.

		read
			Read in a file and process it as if each line was entered
			from the command line. This is useful if many commands are
			to be processed at the same time.

			Two examples of this are: time_setup and nav_setup.
			The files will initialize a Motorola receiver for
			timing applications or Navigation respectively.

		log
			Bring up the log screen

		lock
			Lock the keyboard and ignore further keystrokes
			except F11(unlock) or the unlock command.

			Note that once the lock command is given via the
			keyboard only F11 will be able to unlock the system.

			If the lock command is given via a command file
			an unlock command can also be given via the same file.

			This can be used to intentionally lock the keyboard during
			sensitinve command processing.

		unlock
			Unlocks the keyboard.

		hpv
			HP Receiver only. Increase verbosity of HP receiver output.

		!{string}
			If in terminal mode, processes the command as a gpsdisplay
			internal command.

			If in normal mode, sends the command to the receiver.
			All receiver specific options apply.

			Normal mode example:

				!@@Aw#ff

			Will send the command: @@Awff to the Motorola receiver.

			Terminal mode example:

				!w1

			Will return the system to normal mode. This can also be
			accomplished via the F1 key.

		#[string]
			This is a comment. It will be ignored.

		----------------------------------------------------------------------
		Function Key Commands and command line equivalents:

		Note: In "Terminal Mode", prefix the commands with a "!":

		F1/"w1"    - Display main window          F2/"w2"     - Extended Information Window
		F3/"w3"    - Unprocessed Commands Window
		F7/"log"   - System Log Window            F8/"term"   - Terminal Mode Window
		F9/"help"  - Help(This Screen)

		F11/Lock/Unlock  - Toggle System Lock     F12/"Quit"  - Quit
		----------------------------------------------------------------------
		Sending GPS Receiver commands in "Terminal Mode":

		In "Normal Mode", prefix the commands with a "!":
		to send a command to the receiver.

		Motorola commands can be prefixed with @@ but they don't have to be.
		The checksum will be computed automatically before the command is sent to
		the receiver.

		So a @@Cj and Cj are the same.

		To send a hex code to the receiver put a '#' after the command.
		e.x. @@Az#ffffffff will send the proper command to get the antenna delay.

		Note: HP Receiver commands do not require a checksum.
		----------------------------------------------------------------------
		Other Commands:

		 unlock/Ctrl-L - Unlock keyboard
		 Ctrl-W        - Suspend Data display
		 Ctrl-V        - Toggles "Show more receiver data". In HP Mode, the
						 terminal screen will be very busy!
		----------------------------------------------------------------------
		Command line movement uses Standard Keys and "Emacs Mode" keys

		Standard Keys:

			Home      - Beginning of line, End        - End of line
			LeftArrow - Move to the left,  RightArrow - Move to the right
			UpArrow   - Previous Command,  DownArrow  - Next Command

			Ctrl-D    - Delete Char Right, Bksp       - Delete Char Left
			Ctrl-U    - Delete line,       Ctrl-K     - Delete to EOL

		"Emacs Mode" key combinations:

			Ctrl-A - Beginning of line, Ctrl-E - End of line
			Ctrl-B - Move to the left,  Ctrl-F - Move to the right
			Ctrl-P - Previous Command,  Ctrl-N - Next Command

-------------------------------------------------------------------------------
Section 23. Complete command line reference.

		gpsdisplay has many options here is the complete list.
			
        ./gpsdisplay [-d] [-v[v[v...]]] [-ckotm]
                        [-f time_format] [-i Configuration_file]
                        [-s serial_port_device] [-B baud]
                        [-p port] [-l html_output_file] [-[-]h]
                        [-C n,n,n,n,n] [-e HTML_Title] [-g timelog]
                        [-r receiver_model] hostname

        Where:

        -d debug_file|off -- Debug file must be specified in order
           for debug to be enabled
        -v[v[v...]]] verbose. Specify verbosity level of debug output
        -c Run in full screen mode(curses). This is the default.
        -k fork (run in the background)
        -o Generate simple screen output (no curses).
        -t Start terminal mode.
        -f time_format -- USA1,USA2,USA3,EUR1,EUR2,EUR3,ISO1,ISO2
           The format used to display the time and date
        -i Configuration_file -- System configuration file
           Note: Command line options override any configuration file settings
        -s serial_port -- Serial port to use. e.x. /dev/ttyS0
        -B baud -- Specify BAUD rate when using the serial port. e.x. 9600-8-N-1
		-m Limit the Output and LiveData windows to 1 line. Only applies if we are in curses mode.
        -p port -- port number to use for connecting to
           the NTP shared memory connector. Default is 12321
        -C TitleBackground,TitleFont,TextBackground,TextLabels,Textdata
           Color selection for HTML page
        -e HTML_Title_String -- The string that will define the <TITLE> tag
           in the HTML output file
        -g timelog -- The name of the Time Log file
        -l html_output_file -- The output destination of HTML code
        -h Help (this screen)
        -r receiver_model -- As of 4/2006, two types
           are supported: M(Motorola) and H(Hewlett Packard)

        hostname -- Well you know...

        For a quick display do: ./gpsdisplay www.darksmile.net

-------------------------------------------------------------------------------
Section 24. Complete initialization file reference

	#
	#	Hash marks are comments and will be ignored
	#	Keywords are not case sensitive but parameters
	#	such as logfile names are.
	#
	# Hostname followed by an IP address or remote host name
	# specifies the machine that we will be connecting via TCP/IP
	Hostname	Timelord
	#
	# Port is the port that we will be connecting to on the
	# remote host
	Port	12321
	#
	# Timelog specifies the log file which will hold
	# the timing data, such as: Sats, PRN, Time, EFC etc.
	# If the name of the log file is: "none" then no logging
	# of data will occur.
	# NOTE: If you go to daemon mode make sure that the path here is absolute!
	#
	Timelog /tmp/timelog.log
	#
	# HTTPFile specifies where the HTTP data will be output
	# If the name of the HTTP file is: "none" then no
	# file will be written. Setting this option to a filename
	# implies that the HTML Generation will be on.
	# NOTE: If you go to daemon mode make sure that the path here is absolute!
	HTTPFile	/tmp/http.html
	#
	# Select the colors for the html code
	#HTMLColors TitleBackground,TitleFont,TextBackground,TextLabels,Textdata
	HTMLColors #0099cc,White,White,Blue,Red
	#
	# HTMLTitle specifies the title that will be within the <TITLE></TITLE> Tags
	# but only if the HTML file is produced.
	HTMLTitle	Hello There
	#
	# OutputWinLimit, when specified, limits the Output and LiveData windows to 1 line.
	OutputWinLimit
	#
	# Serial port definition
	# If the name of the SerialPort is: "none" then
	# the serial port input method will not be used.
	# e.x. SerialPort	/dev/ttyS7
	SerialPort	none
	#
	# Receiver type. Motorola or HP
	ReceiverType	Motorola
	#
	# Baud rate. If ReceiverType is Motorola then BaudRate
	# defaults to 9600-8-n-1. If ReceiverType is HP then
	# BaudRate defaults 19200-7-o-1
	BaudRate	9600-8-n-1
	#
	# FullScreenEnable sets the output mode.
	# Curses = "on" or "off"
	FullScreenEnable	On
	#
	# TimeFormat allows a user to display the time in several different formats
	# USA1 		Default - Would display Date as mm/dd/yyyy, Time as: hh:mm:ss.frac {UTC|GPS}
	# USA2		Would display Date as mm/dd/yyyy, Time as: ddd-hh:mm:ss.frac {UT|GPS}
	# USA3		Would display Date as mm/dd/yyyy, Time as: yyyy.ddd.hh:mm:ss {UT|GPS}
	#
	# EUR1		Would display Date as dd/mm/yyyy, Time as: hh:mm:ss.frac {UTC|GPS}
	# EUR2		Would display Date as dd/mm/yyyy, Time as: ddd-hh:mm:ss.frac {UT|GPS}
	# EUR3		Would display Date as dd/mm/yyyy, Time as: yyyy.ddd.hh:mm:ss.frac {UT|GPS}
	# ISO1		Display Date as yyyy-mm-<DD>, Time as: hh:mm:ss.frac {UTC|GPS}
	# ISO2		Display Date as yyyy-mm-<DD>, Time as: yyyy-mm-ddThh:mm:ss.frac {UTC|GPS}
	TimeFormat	USA1
	#
	# TerminalMode on|of sets the way that the program
	# is presented to the user. If the connection is via TCP/IP
	# then this mode has no effect. If the connection
	# is via the serial port then the user will be presented
	# with a terminal program view where all input from the keyboard
	# is passed on to the serial port.
	TerminalMode	Off
	#
	# DeamonMode on|off If "on" then the program runs as a daemon.
	# If set to on and FullScreenEnable is also on then this will
	# setting will not be used.
	DaemonMode	Off
	#
	# Debug sets debug mode filename
	# Specifiying a filename sets enables the option.
	# Note that the debug option must specify an output file
	# in order to be enabled. Debug and verbose data will no longer
	# go to stderr.(5/2006)
	# NOTE: If you go to daemon mode make sure that the path here is absolute!
	Debug	filename|off
	#
	# Verbose takes a numeric parameter to set the verbosity level
	# of the debug output.
	# Maximum is 5 minimum is 0
	Verbose	0
	#
	# The "SysInit" Keyword should be the last one in this file.
	# All lines after the "SysInit", will be processed as if they
	# were entered from the keyboard, including comment lines and blanks!
	# Note that setting the "TerminalMode" option to "on" above,
	# will start the system in terminal mode and the commands below
	# should reflect that.
	#
	# The commands here will also be entered in the retrieve buffer
	# and can be recalled.
	#
	# Special note to HP users:
	# Some HP commands do not return a scpi prompt.
	# For proper processing of those commands, add a blank line
	# right below them.
	SysInit

-------------------------------------------------------------------------------
Section 25.	The timesplit program

	The timesplit program can be used to perform maintenance on the
	time logs from the Z3801 receiver.

	The function of the program can be explained as follows:

	Given a timelog with data for x number of days, by specifying:
	
	timesplit 7 logname

	Two files will be created:

	logname.SPLIT1		- All data prior to 7 days ago
	logname.SPLIT2		- All data from 7 days ago to the last entry in the log file

	"logname.SPLIT1" can be gzipped and saved and "logname.SPLIT2" can replace the
	original "logname".

	WARNING: Make sure you check for the semaphore from the "gpsdisplay" program before
	you attempt to override the original log file.

	For an example see the included program: WeeklyMaint
