This is a brief description about the new process concept of cumulus
introduced by me (Axel Pauli, axel@kflog.org). It isolates the GPS
receiver part from cumulus and put it in a separate process.

Last update: 07 Apr 04 11:07:52 Axel Pauli

======================================================================
Remarks to the current design of cumulus and motivations to change it:
======================================================================

The current run-time design of cumulus is based on a single threaded
process. The main task of the process is to get NMEA data records from
the serial device and to process them. Most of the other actions are
derived from this task. The main problem which we do have with this
approach is the load sharing between the different modules of
cumulus. GPS data will come continuous in and must be processed to
avoid buffer overruns and data loss. On the other hand the map
loading/drawing needs a lot of time in dependency of the scale factor
and the underlaying terrain. This time excceds often the buffer
capacity (4KB) of the serial driver. Normally we could bridge ca. 10s
by 4800 bps device speed. To avoid GPS data loss we will call
processEvents on different places in our code. But this caused a lot
of side effects due to recursive calling of the same functions which
we tried to block with different methods. Therefore I decided me to
outhouse the GPS receiver module into a separate process.

==================================
Design details for the new concept:
==================================

-Aproach is using a client-server model. The cumulus program is the
server, the GPS subprocess the client.

-GPS subprocess will only read or write data from/to the serial
device. Received NMEA data will be queued internally until the server
is fetching it or queue is full. If queue is full, oldest message will
be removed. More will not be done to get a high stable running
process.

-Communication between server-client is transacted via sockets over
the loopback device lo. This device has the IP address 127.0.0.1 and
is default on every UNIX system. A free port is gotten by the server
from the kernel and passed to the client as command option during exec
call. Two socket channels will be introduced. One channel for command
and data transfer a second channel as notification line.

-Server starts always with the command handling via command/data
channel to avoid dead locks in the communication. The client has only
to response to the requests from the server. It will never send
unsolicited messages.

-Client can send a notification via the notification line to the
server if new data are available and server has requested this. This
is useful, if client polling should be avoided by the server.

-Client process is created via fork/exec. The port number of the
server listening end point socket is passed during startup via command
line option.

-Client will open two socket channels to the server during its
initialization phase. Channel 0 for command/data transfer, Channel 1
for notification signalisation.

-Server supervises client via a timer routine. Every 10 seconds is
checked, if client is alive. If not, the zombie process is effaced and
a new client process is startup.

-Client checks periodically, if server is alive. If not more (e.g. due
to crash), it terminates too to avoid unwanted zombies.

-The server module provides the following public methods:

     a) sendSentence()      transmits a message to the GPS device
     b) startGpsReceiving() starts receiving of GPS data
     c) stopGpsReceiving()  stops receiving of GPS data

-The server module emits the following signals:

     a) newSentence()       new GPS NMEA message avialable
     b) gpsConnectionLost() connection to GPS is going lost

===========================
Realization of server side:
===========================

The GPSCon module has been adapted to the new needs. It covers all the
new functionality, like client process startup, client process
supervision, client connection handling and interprocess
communication. There are a few little changes in other modules
(gpsnmea, cumulusapp, main) too. Additionally there are two new
modules like SignalHandler, Ipc and one definition protocol file.

===========================
Realization of client side:
===========================

I have introduced a new process with the name gpsClient. It has to lay
in the same directory like the cumulus process. The process comprises
4 modules (gpsmain, gpsclient, ipc, signalhandler) and the definition
protocol file. It is a simple console process written in C++ with an
own managed main loop on base of the unix select function. Some useful
QT classes are also included. It can queue up to 500 NMEA records at
the moment. That can be changed via define statement if desired. There
has been introduced one additionally message ConnectionLost beside the
NMEA records. This message describes a timeout for the server occurred
if more than 10s no new data came in on client side.

================
Message Protocol
================

The used message protocol for the interprocess communication is pure
ascii 8 bits. It is defined in the file protocol.h, so that single
terms could be changed very easy. Space is used as separator between
the command key words and the single arguments of the message. The
messages are transmitted in tow parts via the socket. As first the
message length as unsigned integer and then the rest of the message as
unsigned characters. That has the advantage, that the other side will
know how long a single message is and where the next message will
begin, if more as one is sent. All communications starts always from
server side. The client has only to response to the requests.

=======================================================
Server request				Client response
=======================================================

MSG_GM					MSG_NEG | MSG_RM ' ' <message>

MSG_MAGIC ' ' MSG_PROTOCOL		MSG_POS | MSG_NEG

MSG_OPEN ' ' <device> ' ' <speed>	MSG_POS | MSG_NEG

MSG_CLOSE				MSG_POS

MSG_NTY					MSG_POS

MSG_SM ' ' <message>			MSG_POS | MSG_NEG

MSG_SHD					no response expected

If notification signaling is requested by the server, the client sends
only the message MSG_DA in the notification channel.

======================
Build and integration:
======================

The appended tar file contains all changed modules of cumulus and the
new ones. You can extract it in the cumulus build directory.

The file gpsclient.pro describes all dependencies for tmake to build
the new subprocess. To generate a makefile call:

tmake -o MakefileGpsClient gpsclient.pro

Afterwards call:

make -f MakefileGpsClient

to build the new process. The process must be installed in the same
directory as cumulus on the Z!

===================
First test results:
===================

I tried a couple of tests with the new process design. Killing of
gpsClient process during run will be answered by cumulus with a
startup of a new client. That seems to be stable. Killing of cumulus
is also recognized by the client and answered with its
termination. Data transfer server-client with notitication works also
very good. Stress tests displayed too a good behaviour.

