1. Introduction:
================

rwgps is a ncurses-based serial port driver/interface console
application for the Rockwell Microtracker LP(tm) GPS receiver module.
This module consists of the receiver module itself and a motherboard
which serves as a power supply and RS232 serial communication interface.
A power supply and antenna unit is also supplied, which plugs into the
receiver and may be of the active or passive type.

Rockwell supplied this module together with extensive and complete
documentation to facilitate both hardware and software design and
integration of this module in GPS receiver systems and other hardware.
A software package for the DOS operating system is also supplied for
running and testing the module.

rwgps is a software package released under the GNU General Public
License and in the form of source-code files in the C programming
language, developed on a UP1000 Alpha computer with SuSE Linux 7.0
installed. PLEASE NOTE that some parts of this source-code are platform
dependent as the GPS Receiver module uses the CAPS format for floating
point numbers and the conversion to IEEE754 format is endian-dependent.
This platform-specific code is in the convert.c file and there are some
comments in the affected functions on what to try, if the conversions
produce corrupt results.


2. Compilation:
===============

rwgps communicates with the GPS Receiver via an RS232 serial port. It
is necessary to specify the serial port device in the header file
rwgps.h before compilation. Currently the default is /dev/ttyS1.
Also the default geodetic position of the GPS receiver is specified
in this header for use with the Warm Start command, described later.

To compile just type make in the rwgps-01_beta directory. To test run,
connect the GPS Receiver module to the serial port and power up.
Type ./rwgps in the rwgps-01_beta directory to run the binary. Copy
the binary in whatever directory you want it installed (usually
/usr/bin or /usr/local/bin).


3. Usage:
=========

Before attempting to use rwgps, it is best to study the documentation
provided by Rockwell. This includes a lot of detailed information on
the GPS satellite navigation system, the mathematical background to
calculations involved in determining receiver location, the hardware
comprising the receiver module, modes of operation and the format of
'messages', or packets of data transmitted or accepted by the receiver.

Rockwell's Microtracker LP(tm) uses two basic formats for data packets,
or messages, the Binary format or NMEA format. rwgps is limited to the
Binary format messages for both receiving and sending, which is done
via the serial port at 9600 baud. Before rwgps can work properly, the
GPS Receiver must be plugged into the appropriate serial port and
powered up. Since some messages from the receiver may be delayed by
up to 10 sec (e.g. the BIT or Built-In-Test Results Message 101),
rwgps will wait for 12 sec for input data at the serial before it
produces an error message.

To run this application, just type rwgps at the console. rwgps is
a ncurses based application and takes no command line arguments.
As it displays a lot of information read from the receiver, the
full-screen root window (the 'main' screen) is divided into a
number of smaller units, each displaying a group of related data.
A color scheme is used to indicate the status of data on the screen:
Cyan is used for window labels, Magenta for data labels, green for
valid data and status flags, yellow for usable but not final data
and for transient status conditions, red for invalid data and fault
conditions.

At the top of the root window is the main Navigational data display,
consisting of the three windows, NAVIGATION, POSITION and VELOCITY.
These indicate receiver position in geodetic units (degrees latitude
and longitude and altitude in meters, Cartesian position x, y, z in
meters and velocity in meters/sec. UTC date and time is also indicated
together with a UTC validity flag, which indicates when UTC data from
the GPS receiver is valid. This data is normally renewed at 1 sec
intervals unless power saving mode is selected, whereby data is
renewed at up to a maximum of 5 sec intervals.

Below these windows at the left is the satellite information window
labeled SATELLITES. In this the satellite PRN (identity), elevation
and azimuth in degrees is shown. The data in this window is renewed
at 2 minute intervals and this window may not appear in the main
screen until data from the receiver arrives.

Next are two windows displaying precision dilution estimates and
expected errors in the navigational and time data. Please see the
Rockwell Microtracker LP manual for details if this information is
of interest to you.

Following these is the receiver channel activity display. The GPS
receiver has five receiving channels, of which four are used for
tracking satellites with good signal strengths and one for searching
for new satellites to be used, as they move into reception. The
columns in this window indicate channel number, satellite PRN,
activity and signal/noise ratio.

At the right side of the root window below the Velocity display is
the GPS date and time display window. Data displayed is UTC date,
UTC time, Week number, set time and the UTC validity flag. This
indicates the validity status of the time data from the GPS receiver.

At the bottom right of the root window is the GPS Receiver engine
status indications window. The most useful of these is the Navigation
Mode status display which indicates whether the receiver is in Cold
Start mode, Acquisition mode and 2-d or 3-d Navigation mode. Please
see the Rockwell manual for details if needed.

Finally, at the bottom left of the root window is the program mode
and errors display window:

The PR MODE box indicates which 'mode' rwgps is in as follows:

MAIN SCRN: rwgps is running normally and the main screen is refreshed
with data from the GPS Receiver. Note that this does not mean the
displayed data are valid, as the receiver may not be in tracking mode.

WARM STRT: A 'warm start' command has been sent to the receiver. This
is done to initialize the receiver and is explained further below.

BIT RESLT: A Built-In-Test command has been sent to the receiver and
rwgps is waiting for data. Note that this takes about 10 sec to complete.

PROG HALT: rwgps has been halted with the 'H' keystroke. The main screen
is displayed but reading and display of data is suspended.

POWER MAN: A Power Management command was sent to the receiver.

SET CLOCK: The user has initiated the hardware clock setting process by
keying 'C'. rwgps will close the main screen and display a confirmation
dialog box before setting the computer's hardware clock to GPS time.

The MSGID box indicate the Message ID number of the last 'Message'
(data packet) received from or sent to the GPS receiver. Messages
commonly  received and displayed are Message 101: Built-In-Test
results, Message 102 Visible Satellite Information, Message 103:
Receiver position, velocity, status and GPS date and time. Messages
commonly sent to the receiver are Message 201: Initialization
command (Warm start data), Message 212: Built-In-Test command and
Message 211: Power Management control. Please see the Rockwell
manual for details of these commands.

The PROTO box indicates the Message protocol flag: ACK signifies
a request to acknowledge a sent Message or acknowledgment of
reception of a valid Message. NACK signifies no acknowledgment
of a Message is needed or the a sent message is invalid. NULL
signifies that ACK/NACK flags are not relevant to the Message.
These protocol flags refer to the Message ID in the MSGID box.

The ERRORS box gives some indication on the function that failed,
e.g. read(), write() or popen() with the '!' indicating an error
condition.

Below these boxes is one line of verbose information on errors
returned by system calls or relating to the status of rwgps.
Sometimes error codes returned by the system can produce an unclear
error report.

At the bottom of the main screen is a keystroke commands display bar.
'B' initiates a BIT (Built-In-Test), 'W' opens a form for entering
Warm start (initialization) data, 'M' opens the Main screen, 'C'
opens the set hardware clock confirmation dialog box, 'P' opens the
Power Management data form, 'H' halts rwgps until some keystroke
command is issued and 'Q' quits rwgps. Keystrokes are case
insensitive.


4. Keystroke Commands:
======================

'T' (Built-In-Test): Sends a self-test request to the receiver.
Data transmission stops while a built-in test is carried out by the
receiver, which takes about 10 sec. A Message 101 data packet is
sent by the receiver with the results of the BIT. rwgps will close
the main screen and open the BIT test results windows where details
of an extensive self-test are displayed. Please see the Rockwell
manual for details of these tests.

'W' (Warm start parameters): Opens the warm start parameters form
where the receiver's current position (Lat and Long in deg and min,
Altitude in meters), UTC time and date, and the static navigation
enable flag are entered. A '1' in this entry allows the GPS receiver
to average the position/velocity data so the wonder in their value
can be reduced, if the receiver detects that it is static. Receiver
position need only be specified to about 100 km accuracy and  UTC
to within 5 minutes. Default values for the receiver's position
can be specified in the rwgps.h header file if needed. UTC will
also be read and entered from the computer's hardware clock. If
this is not set to UTC, time and date should be entered manually.

'M' (Main screen): Opens the main rwgps screen and starts reading
and display of data from the receiver.

'C' (Clock set): Opens a confirmation dialog box where the user can
either cancel or confirm the setting of the computer's hardware
(cmos) clock to GPS (UTC) time and date.

'P' (Power Management command): Opens a form where the user can
enter some parameters for the Power Management command as follows:

Command/Status flag: If 1, the Power Management (Message 211) command
is a request for the receiver to go to a power management state
according to the Solution Update Rate. If 2, it is a request for a
Power Management Status message (not normally used). If 3, then
Message 211 is both a Power Management command and status request.
(Again not normally used). Default value is 1.

Solution Update Rate: The rate in seconds/update of navigation data.
If 1, the Receiver is in normal FULL mode updating navigational data
once a second. If any other value, in the range 2-5, the the Receiver
is in power management (CYCLED) low p0power mode, updating results at
the specified intervals. Default value is 1.

Acquisition Timeout: The time in seconds before the Receiver switches
from Acquisition mode to Cold Start mode if no satellites are tracked.
Default value is 90 sec. Please see Rockwell's manual for details.

Low Power Timeout: The value entered here controls the way the Receiver
comes out of the low power mode. Please see the Rockwell manual for
more details. Default value is -1 (no timeout).

'H' (HALT): Keying H halts rwgps and freezes the main screen displayed.
This is useful for studying displayed information.

'Q' (Quit): Quits rwgps.


5. Bugs and annoyances:
=======================

I have fixed all bugs I have found. However rwgps is not easy to test,
since the calculations it carries out on the raw data read from the GPS
receiver may produce incorrect results depending on the location of the
receiver. This is mainly true of longitude since it may be negative or
positive depending on location relative to 0 longitude.

The main screen is probably too large and overloaded with displayed
information. This is because rwgps was written to test the Microtracker
GPS receiver and all relevant information was put on the main screen.

There is a delay in the response to command keystrokes which depends on
the Power Management mode of the receiver. Normally this is 1 sec or
less so it is not very noticeable, but if the receiver is in low power
mode, the delay can be up to 5 sec.

The SATELLITES window displaying GPS visible satellite information
appears only when data (Message 102) is sent by the receiver. This is
done once every two minutes so this window may be blank for that period
of time.

The color scheme used in the displays my not be agreeable to all users.
Some of the colors can be changed in the rwgps.h header file. Color pair
definitions are in the main.c file. All ncurses screen display functions
are in the ncscreen.c file.

6. Files:
=========

rwgps is built from six C source files, a header file and a simple
Makefile. Each file is written, as far as I could, so as to be reusable
and limited to functions of similar or related functionality. All New
Curses display functions are in ncscreen.c. All functions related to
opening and reading/writing to the serial port are in serial.c.
Functions carrying out communication tasks with the Receiver are in
comms.c. Functions reading or formatting Messages from or for the
Receiver are in messages.c. Functions carrying out numerical format
conversions are in convert.c. Please note that some conversions are
endian-depended and therefore platform-specific. This application
was developed on a UP1000 computer with an Alpha EV67 processor. On
other platforms it may be necessary to modify some functions in
convert.c and some comments are included for this purpose. The main()
function and some utility functions relating to flow control are in
main.c. Many definitions of constants and colors are in the header
file rwgps.h.

7. Change-log:
=============

Version 0.1_beta is the first public beta release of rwgps after
bug-fixing and testing locally.

Version 0.2_beta: Added cursor control in the Warm Start and Power
Management forms.

Version 0.3_beta: Changed the Keystroke commands bar to brace keystroke
characters with <>. Removed a few lines of redundant code from ncscreen.c

Version 0.4_beta: Changed the program flow ('mode') control scheme to
streamline the code that acts on the various mode flags. Flow control
flags are now single-bit.

Version 0.5_beta: Modified the command that sets the hardware clock of
the host computer from GPS time and date so that the --utc rather than
the --localtime option is used in the hwclock --set command.

Version 0.6_beta: Changed the type of two functions from 'bool' to 'int'
to stop rwgps from going into an endless loop on startup. This problem
was not evident when I was developing rwgps on a UP1000 Alpha-processor
machine - another one of a number of 'bugs' that just did not show on
the AlphaLinux platform.

Version 0.7: After a bug report from Juha Vierinen regarding seg
faulting of xnec2c, my graphical adaptation of NEC2, I changed all
"sprintf" commands to "snprintf" to avoid buffer overruns. Following
on the above changes, I revised all similar situations in rwgps
source code and changed all "sprintf" commands to "snprintf" just
in case. While going through the rwgps source code, I also fixed
some minor bugs like typos and tidied error messages.

Version 0.8: Made minor changes to the source code to improve style,
after checking with cppcheck and clang analyzer. 

Version 0.9: After a bug report by Steve Platt I edited the
open_serial() function in serial.c to properly enable "raw" mode
and parity settings.

8. Copying:
===========

This software package is released under the GNU Public License. Please
see the COPYING file for more details.

Neoklis Kyriazis  April 22  2001.
