MARLAB DECK UNIT

SOFTWARE DOCUMENTATION

Table of Contents

1 Introduction	4

1.1 Overview	4

1.2 Scope	4

1.3 Related documents	4

2 Using the software	4

2.1 Overview	4

2.2 Switching between operating modes	5

2.3 Settings	6

2.4 Running stalk in Engineer mode	6

2.5 Monitoring in Deck mode	6

3 Installation and configuration	7

3.1 Installation	7

3.2 Configure the operating modes	7

3.2.1 Set up the operating modes:	7

3.2.2 Scripts used in setting up the operating modes	8

3.3 Configure the Public Key Authentication for file transfer	9

3.4 Configure the GPRS network connection	10

3.5 Configure the firewall	12

3.6 Build and Install the software	12

3.7 Running deckunit and stalk	13

4 Source code	13

4.1 Overview	13

4.2 The deckunitC module	14

4.3 The deckunitJ module	16

4.4 The stalk utility	16

4.5 Notes on building and installation	17

Preface

Documentation Conventions

The following documentation conventions are used within this document:

Text Convention	Usage
Constant width text	Command, parameters, directives and command output, file locations, domain names.
Italic constant width text	Arguments to a command for which appropriate substitution should be made in any command input.
Underlined text	Names of documents or references to other sources.

Introduction

Overview

This document describes the software developed for the Marlab Deck Unit project.

Scope

The following items are addressed :

Use of the software

Installation and configuration

Documentation of software components

This document should be read in conjunction with all relevant product and project documentation.

Related documents

Marlab Deck Unit Software Design specification 2020-002-DS Issue A

Marlab Deck Unit Design Specification2020-001-DS Issue A

Telit GM862-GPRS Software User Guide

GARMIN GPS 25 LP SERIES GPS SENSOR BOARDS GPS25-LVC, GPS25-LVS, GPS25-HVS Technical Specification

Using the software

Overview

The software consists of two components, the component to be installed on the offshore machine 'deckunit', and the engineer utility 'stalk'.

These components operate in different modes, 'Deck mode', and 'Engineer mode', and they both operate in 'Development mode', but not simultaneously.

The deckunit component and an X server are automatically started in run level 2 when the offshore machine is booted – this run level is referred to as 'Deck mode'.

Run level 5 is intended for Engineer mode. It is configured to run an X server, but not deckunit. Run level 5 also starts pppd so that a GPRS internet connection is available when deckunit is not running. Switching between run levels 2 and 5 will cause a temporary break in the connection.

Run level 3 is intended for 'Development mode' , editing, compiling etc..

The sections below provide details of using the software:

Switching between operating modes

Settings

Running stalk in Engineer mode

Monitoring in Deck mode

Switching between operating modes

Switching modes varies a little depending on the start and end modes, and the login user. Follow the sequence of commands below, omitting the ones specific to a mode or login user.

If start is Development mode, first kill the x server running in this mode: the x server in Deck mode, (which is shared by Engineer mode) is set up differently to the 'normal' set up for the x server that runs in Development mode. This will also switch to a virtual terminal:

Ctrl-Alt-Backspace	: Kill the x server

If not already in a virtual terminal (start is Deck mode), switch to one (any Function key in the range F1-F6 that is not in use):

Ctrl-Alt-F1	: Switch to virtual terminal

If not logged in as root, type exit until get a login prompt:

$ exit
login: root	: Login as root

Switch modes (change runlevels) to one of the following:

(init 5 : Engineer mode	: Stops deckunit, restarts pppd
init 2 : Deck mode	: starts deckunit, an x server, pppd
init 3 : Development mode	: stops pppd and deckunit)

# init N	: Change mode

If end is Deck mode, switch to the desk top running it:

Ctrl-Alt-F7	: Change to desk top

If end in Development mode, need to start up a new x server but first kill the x server that was running in Deck or Engineer mode. (This is not necessary if end is the other modes: when start is Development mode, the x server is killed while still in Development mode, and, when swapping between Deck and Engineer mode, the x server is shared). To kill the x server, first get the process id:

# ps ax | grep -w X	: To find the PID of x server

# kill -SIGTERM <pidno>	: To kill the x server with that pidno
# exit	: Exit until get login prompt
login: marlab	: Login as ordinary user
$ startx	: Run a normal x server

Settings

Aside from the settings on the Initialization screen, some additional settings are configurable in the text file /marlab/Sys/marlabsys.ini.

The mean sea level and antenna height are required by deckunit to calculate the altitude to send to GPS as part of the Initialization phase.

There is also a file number setting at which to start numbering files, this is for use by deckunit to update to keep track of the file number to use when it resumes logging after the system shuts down.

Running stalk in Engineer mode

Usage: stalk <device> [<speed>]

where <device> is GPS, GPRS, Minipack, or /dev/ttyXX

<speed> is 4800, 9600, ...

Start stalk by typing on the command line:

$ /marlab/bin/stalk <arg>

A command prompt is displayed at the bottom of the window to send commands to the device. Lines read from the device are scrolled up the screen above the command line.

To exit stalk press :

Ctrl-C

Monitoring in Deck mode

To monitor events whilst deckunit is running, switch to a virtual terminal and login as an ordinary user:

Ctrl-Alt-F1
login: marlab

Then to monitor data being logged live to a file, in the /marlab/Data directory find the file, if any, (since it may already be compressed, copied and archived), with the current date and the most recent file number. If the ferry is at sea and currently updating the file, then running tail with that file name will show the logged lines being updated as they are received.

$ tail -f <logfilename>

Installation and configuration

Installation

The input and output files are contained in the directory tree /marlab and the source code, configuration files and documentation in ~/marlabsoftware, so to reinstall these they need to be copied to those directories.

As root, copy the marlab directory tree to /marlab.

# cp -r marlab /marlab/

As an ordinary user copy the marlabsoftware directory tree to ~/ . This will be owned by the name of the login user.

$ cp -r marlabsoftware/ ~/marlabsoftware/

The other installation tasks are:

Setting up the automatic start up of deckunit, and alternative run levels for Engineer mode and Development mode.

Setting up the public and private keys for the secure shell ssh that the scp copying utility relies on.

Setting up the configuration files for the pppd utility

Setting up the firewall

Building and Installing the software

Running deckunit and stalk.

These are dealt with in the sections that follow.

Configure the operating modes

As indicated in section 2.1., three operating modes ('run levels') are used on the offshore machine: Deck mode, Engineer mode and Development mode.

The following subsections describe the changes made to the inittab file and other scripts that the init process, and the processes it runs, rely on, and how and where they should be installed.

Set up the operating modes:

The ~/marlabsoftware/config/init directory contains the configuration files to set up operating modes.

Copy the following files to the specified directories (these files are described below in section 3.2.2):

$ cd ~/marlabsoftware/config/init
$ su	(need to be root)

# cp rc.deckunit /etc/rc.d/

# cp rc.xserver /etc/rc.d/

# cp rc.pppd /etc/rc.d/

# cp .xinitrc /root/

# cp .fvwm2rc /root/

Check that the files /etc/rc.d/rc.deckunit, /etc/rc.d/rc.xserver and

/etc/rc.d/rc.pppd have execute permission:

# ls -l /etc/rc.d

Edit /etc/inittab:

Change line:	id:3:initdefault:

to	:	id:2:initdefault:

Add lines	:	xx:25:respawn:/etc/rc.d/rc.xserver

du:2:respawn:/etc/rc.d/rc.deckunit

pp:5:respawn:/etc/rc.d/rc.pppd

Scripts used in setting up the operating modes

Inittab The /etc/inittab edits change the default run level from 3 to 2, and tell init to execute the scripts rc.xserver and rc.deckunit in run level 2. These scripts start an X server and deckunit respectively.

Since the default run level is 2, the X server and deckunit are automatically started when the offshore machine is booted in Deck mode.

Run level 5 (Engineer mode) is configured to run an X server but not deckunit. So to terminate deckunit switch to run level 5, and to restart it, switch to run level 2 . Switching between runlevels 2 and 5 will leave the X server running. Run level 5 also starts pppd so that a GPRS Internet connection is available when deckunit is not running. Switching between run levels 2 and 5 will cause a temporary break in the connection.

Runlevel 3 is for development use (editing, compiling).

rc.xserver The rc.xserver script sets up a few environment variables, and then does 'exec startx' to start the X server. startx starts the X server, and looks for a file called .xinitrc in the user's home directory, and executes it if it exists. We are running as root at this point, so startx will look in root's home directory (i.e. /root).

.xinitrc The .xinitrc script does some standard set up, and then 'xhost +' to allow any user to connect to the X server. This is to allow deckunit, which is running as an ordinary user, to connect to the X server, which is being run by root. The .xinitrc script next does 'xset s off' to turn off the screen-saver – to prevent the screen going blank. Finally, .xinitrc does 'exec fvwm2' to start the window manager.

.fvwm2rc The fvwm2 window manager started by .xinitrc looks for a configuration file called .fvwm2rc in the user's home directory. The .fvwm2rc file has the task bar and menus commented out, so windows are displayed on a plain background.

rc.deckunitThe rc.deckunit script sets up a few environment variables, sleeps for a few seconds to allow the X server to start, and then does 'exec deckunit' to start deckunit. Any output from deckunit (e.g. If debug printing is enabled) is redirected to the file /marlab/error/output.txt so that it doesn't interfere with the "console" screen, and is available for later examination.

rc.pppd The rc.pppd script sets up a few environment variables, and then starts pppd. If pppd returns (which means that the connection has been lost), the scripts sleeps for 60 seconds before returning. This is to prevent init restarting the script too rapidly.

Configure the Public Key Authentication for file transfer

The 'Public key Authentication' enables the use of ssh and scp without being prompted for a password. The scp utility, which relies on ssh, is used by deckunit for the automatic copying of log files from the ferry PC (the 'client' machine) to the onshore PC (the 'server' machine).

The Public Key Authentication could additionally be configured the other way round (with the ferry PC as 'server' and onshore PC as 'client') to allow ssh login from the onshore PC to the ferry PC without a password.

On the client machine, login as the user that deckunit will run as, and

type the command:

$ ssh-keygen -t dsa

to generate a public/private key pair. Just press Enter when it prompts for a pass phrase.

This creates the files id_dsa and id_dsa.pub in the ~/.ssh directory. The id_dsa.pub file contains the public key, and the id_dsa file contains the private key.

On the server machine, login as the user that will be receiving the log files.

If it doesn't already exist, create a file:

~/.ssh/authorized_keys2

Append the contents of id_dsa.pub to it. Be careful not to introduce any extra characters (e.g. spaces).

Don't do this set-up (i.e. Public Key Authentication without a pass-phrase) on an insecure or public client machine - it allows access to the server machine by anyone who has access to the id_dsa file!

Edit the value of the <tohost> variable in ~/marlabsoftware/src/deckunit/deck.c with the address of the shore machine and a username which the file transfer utility scp also requires. After the username and hostname enter a pathname for the directory in which the files are to be stored – in this example, in /marlab/Data/

username@hostname:/marlab/Data/

If you enter a relative pathname, this will be relative to the home directory of the user. For example, if you enter:

username@hostname:marlab/Data/

then files will be copied to the directory ~/marlab/Data.

On the shore-based PC - set up the corresponding user and directory tree:

$ mkdir ~/marlab/Data

Configure the GPRS network connection

The /marlabsoftware/config/ppp directory contains the configuration files for use with pppd to make a connection with GPRS . These need to be copied to the /etc/ppp directory, and then edited to match the connection details provided by the ISP.

Copy (as root) ppp configuration files in the ~/marlabsoftware/config/ppp directory to /etc/ppp, which is where the pppd utility expects to find them:

$ su

# cp chap-secrets /etc/ppp

# cp connect-chat /etc/ppp

# cp ip-up /etc/ppp

# cp ip-down /etc/ppp

# cp options /etc/ppp

# cp pap-secrets /etc/ppp

Ensure that permissions are set correctly on these files (IMPORTANT):

# ls -l /etc/ppp

-rw------- chap-secrets

-rw-r--r-- connect-chat

-rwxr-xr-x ip-down

-rwxr-xr-x ip-up

-rw-r--r-- options

-rw------- pap-secrets

If necessary, set the file permissions:

# chmod 600 chap-secrets

# chmod 644 connect-chat

# chmod 755 ip-down

# chmod 755 ip-up

# chmod 644 options

# chmod 600 pap-secrets

Set the setuid bit on pppd to enable it to be run by the ordinary user that runs deckunit:

# chmod u+s /usr/sbin/pppd

Change to the /etc/ppp directory to edit the configuration files:

# cd /etc/ppp

Edit the options file:

Enter the correct user name (from the ISP , e.g. “rlnet”).

Enter the correct serial device (e.g. /dev/ttyS0).

Edit the chap-secrets or pap-secrets file:

Enter the password for the user name entered in the options file above, in chap-secrets or pap-secrets, depending on the authentication method used by the ISP. Iit won't harm to put it in both, if it's not clear which authentication method is used. (Format: '<name> * <pword>'.)

Edit the connect-chat script:

Put in the correct APN (e.g."internet", "o2.co.uk")

Configure DNS addresses : Do one of the following, depending on whether the ISP provides DNS IP addresses dynamically or statically.

ISP provides DNS IP addresses dynamically:

Ensure the following line is in the options file and uncommented:

usepeerdns

pppd will create a file resolv.conf, which the ip-up script copies to /etc/resolv.conf. The ip-up script is run by pppd after establishing a successful connection.

ISP provides static DNS IP addresses :

Comment out usepeerdns in the options file:

# usepeerdns

Comment out the following line in ip-up so that it doesn't do the copy:

# /bin/cp /etc/ppp/resolv.conf /etc/resolv.conf

Change to /etc directory and enter the IP addresses provided by the ISP in the /etc/resolv.conf file, which may need to be created. Each IP address should be entered on a separate line, preceded by the word nameserver. For example:

nameserver 159.2.56.3

nameserver 159.2.56.4

Configure the firewall

The file rc.firewall (downloaded from http://projectfiles.com/firewall/) implements a firewall. The standard /etc/rc.d/rc.inet2 script supplied with Slackware looks for and executes a /etc/rc.d/rc.firewall file when Linux is booted. So just copying the file is the only installation that is needed:

Copy firewall script to /etc/rc.d and ensure that it is executable:

$ cd ~/marlabsoftware/config/firewall

$ su	: As root
# cp rc.firewall /etc/rc.d/rc.firewall

# chmod +x /etc/rc.d/rc.firewall

The rc.firewall script has some configuration options in it (near the beginning), but these should not need changing. It is configured for ppp0 as the interface to the internet, and blocks all incoming connections except ssh.

The firewall script should be usable on both the deck PC and the shore PC.

Build and Install the software

In section 3.1. the directory containing the source code subdirectory was copied to ~/marlabsoftware. Below specifies how to build and install the two software components deckunit and stalk.

Compile and link deckunit.

deckunit consists of two modules, deckunitC and deckunitJ,which are written in C and Java , respectively, and are built and installed separately.

Compile deckunitC

First change to the directory containing the Makefile then type make and make install:

$ cd ~/marlabsoftware/src/deckunit

$ make
$ make install	:Copy the executable file to /marlab/bin

Compile deckunitJ

First change to the directory containing the script file myscript,then run it:

$ cd ~/marlabsoftware/src/deckunitgui
$ ./myscript	: compile,jar and copy the jar file to /marlab/bin	(where deckunitC expects to find it)

Compile and link stalk.

First change to the directory containing the Makefile then type make and make install:

$ cd ~/marlabsoftware/src/stalk
$ make
$ make install

Running deckunit and stalk

To start deckunit manually in Development mode, at the command prompt, type:

$ /marlab/bin/deckunit

To start stalk, at the command prompt, type:

$ /marlab/bin/stalk

Source code

Overview

This section encompasses the documentation of the Marlab Deck Unit Software components deckunit and stalk and notes on building and installation.

The deckunit component consists of two modules, the back end deckunitC, written in C, and a Java module, deckunitJ, which controls the GUI.

Source code for deckunit is in the following directories:

~/marlabsoftware/src/deckunit/	: deckunitC source code
~/marlabsoftware/src/deckunitgui/frontend	: deckunitJ source code

Source code for the stalk component is in the directory:

~/marlabsoftware/src/stalk	: stalk source code

The sections below cover the following:

The deckunitC module

The deckunitJ module

The stalk utility

Notes on building and installation of the software components comprising the Marlab Deck Unit software.

The deckunitC module

deckunitC is divided into several threads, the main control thread, hardware-specific threads to carry out tasks for GPS, Minipack and GPRS, and a thread to interface to GpsDrive.

Control thread

The control thread in main.c sets up signal handling, opens all files, and reads in settings. This thread starts the main processes - the GUI - deckunitJ- and the GpsDrive. It also starts up all the threads.

When the control thread waits for the results of hardware tests, the hardware threads communicate via thread 'condition' variables. At other times, they communicate via global variables, which, when necessary, are locked by thread mutexes.

Post initialization, when the control thread starts up the GpsDrive process, the <startDeck> routine controls the tasks to do at port and at sea. Distance from the port (calculated by <atAPort>) is used to assess when the vessel is at sea.

When at port, a gzip process is run to compress files and an scp process is run to transfer them to the base station. The scp utility was chosen both for the security it provides when copying files, since it relies on ssh (see installation), and for the ability to run it from deckunit in non-interactive mode.

The following file is used by this thread in deckunitC to tell the deckunitJ process when to switch between the GpsDrive display and the deckunit data display, and when to stop displaying the deckunit data screen if at port.

/marlab/comm/switch.txt

It is also used by deckunitJ at initialization to tell deckunitC when the user has pressed F9.

Hardware Threads

The files initgps.c initminipack.c and initgprs.c contain the source code specific to each bit of hardware, GPS, Minipack and GPRS respectively.

Each hardware thread tests and configures its own hardware.

The GPS and Minipack threads also log the data received over their serial ports. They check a global variable, which is set by the control thread, periodically to see when they should abort or re-commence logging. They each set a global variable to tell the Control thread when they are idle (i.e. have aborted as instructed).

The GPRS thread establishes and maintains the GPRS connection. It does all the network checking itself, but runs pppd to try to connect. It checks the exit status of pppd periodically and if pppd has exited (i.e. the connection is lost), it runs pppd again.

Data being logged by any of these threads is written to the following file to be displayed by deckunitJ:

/marlab/comm/disp.txt

This is a FIFO so that data that is read by deckunitJ is removed immediately.

If an error occurs and the program shuts down, the error is written to the file:

/marlab/error/error.txt

Data Logging by GPS and Minipack threads

Lines received from Minipack and GPS are logged to a data file in the following format:

G : <GPS line>
M : OT,<Minipack line>

The letter 'G' is for GPS and 'M' for Minipack to mark the line being logged. This is followed by space-colon-space.

For GPS lines this is followed by the GPS sentence received. For Minipack lines, the sentence received is preceded by a comma-separated field in which to store the labels for out-of-range data – as above – where just temperature is out of range. If there is no data out of range, then an empty field is written:

M : ,<Minipack line>

The GpsDrive Thread

The files gpsd.c and gpsd.h contain the source code to interface to the GpsDrive program.

The GpsDrive thread is used instead of the gpsd server that is supplied with the GpsDrive program. It listens for TCP socket connections on port 2947, which is the port that GpsDrive expects to connect to. Once GpsDrive has connected, the GPS thread copies each sentence that it receives from the GPS hardware to the GpsDrive program via the socket connection.

Shutting down

When a signal is received a flag <sigarrived> is set by the signal handler, which each thread checks regularly. The first thread to notice the signal calls the <shutdownAll> routine and locks it, other threads that try to lock it will exit. <shutdownAll> kills off any processes that have been started, closes ports & files, and stores the file number used for the last log file name with the label value FILENUMBER in the settings file:

/marlab/Sys/marlabsys.ini

This is to ensure the last file will not be overwritten when data logging resumes.

Common code

The file deck.c Contains a collection of common global variable initializations for file pointers, process Ids, process exit values, base station IP address, inter-thread communication variables and mutexes, some data structures used to log to files and to the display, and a data structure for settings.

It also contains general routines to update the log and display, and to lock log files while one thread is reading or writing. Other routines here lock thread variables, release memory, clean-up and shut down.

The file general.c contains a collection of general routines to clear buffers, open and close files, and read and write to files, and allocate memory.

The file serial.c contains the code to set up a serial port with settings appropriate to the port for each bit of hardware.

Common declarations are contained in deck.h and general.h.

The deckunitJ module

The deckunitJ module consists of two threads, one that creates the display, and listens for events, the 'GUI thread', (DataScreen.java, InitScreen.java) and one that performs control and background tasks, the 'Control thread' (ControlThread.java).

The Control thread is started from FrontEnd.java and it starts the GUI thread with the display of the Initialization screen. It also controls the display of the data screen, in response deckunitC which tells it when the vessel is at port or at sea, and when to switch screens while at sea. It reads the information supplied by deckunitC:

/marlab/comm/switch.txt

The initialization and data screens are updated by the Control thread by reading data from the FIFO that deckunitC writes to:

/marlab/comm/disp.txt

The source code for the layout of the displays, the methods to update the data displayed and the event handlers is contained in the files DataScreen.java and InitScreen.java. InitScreen.java contains the event handler that tells the deckunitC process when the user has requested a Save and Exit from the Initialization screen ( F9 ). It does this by writing to the file:

/marlab/comm/switch.txt

This event handler also writes the new settings that the user has entered in the settings file:

/marlab/Sys/marlabsys.ini

The stalk utility

The source of stalk is in the file ~/marlabsoftware/src/stalk/stalk.c.

The functions in deckunit/general.c are used for managing the serial port, and the GNU readline library is used for the user interface.

Notes on building and installation

Below are details of the tasks carried out when the C and Java modules of deckunit, deckunitC and deckunitJ, and the C utility stalk, are built and installed See section 3.6. above for the commands to build and install.

deckunitJ is compiled using the script file myscript in ~/marlabsoftware/src/deckunitgui. This file compiles the source, puts it into a jar file, then copies it to /marlab/bin. An additional file wheretostart.txt in the ~/marlabsoftware/src/deckunitgui directory is required by the jar utility, (run from myscript),when it builds the jar file containing the compiled class files.

deckunitC and stalk are compiled and linked using the Makefiles in the subdirectories, ~/marlabsoftware/src/deckunit and ~/marlabsoftware/src/stalk respectively. Each Makefile contains the commands to copy the executable file to /marlab/bin. The Makefile also sets the 'setuid' and 'setgid' permission bits and changes the owner to an ordinary user. This is so that whether the software is started by root or an ordinary user, it is always run as an ordinary user.

16/03/05 Marlab Deck Unit Software Documentation 17

2005-03-12T09:45:29