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. 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.