

%----------------------------------------------------------------
% AMS-LaTeX Paper ************************************************
%**** -----------------------------------------------------------
%\documentclass[12pt,twocolumn]{IEEEtran2e}%
%\documentclass[12pt,onecolumn,notitlepage]{report}
\documentclass[12pt,onecolumn,titlepage]{article}
\usepackage{graphicx,epsfig,amsmath,color,listings,tabularx,amsfonts,moreverb}
% ----------------------------------------------------------------
%\vfuzz2pt % Don't report over-full v-boxes if over-edge is small
%\hfuzz2pt % Don't report over-full h-boxes if over-edge is small
% ----------------------------------------------------------------
\newcommand{\code}[1] {\texttt{#1}}
\newcommand{\DB}   {\code{{MOOSDB}}}
\newcommand{\MA}   { \code{{MOOSApp}  }}
\newcommand{\MOOSLIB}   { \code{{MOOSLib}  }}
\newcommand{\New}[1]   {\textbf{\hspace{-15mm} \checkmark \hspace{10mm}#1 }}
\newcommand{\Ignore}[1]   { }
\setlength{\textheight}{230mm} \setlength{\columnsep}{4mm}
\setlength{\textwidth}{157mm} \setlength{\topmargin}{0.25in}
\setlength{\headheight}{0.0in} \setlength{\headsep}{0.0in}
\setlength{\oddsidemargin}{2mm} \setlength{\parskip}{0.03in}
%\pagestyle{empty}

\definecolor{comment}{rgb}{0,0.5,0}
\lstset{
 basicstyle = \small,
 frame = tb,
  language = [Visual]{c++},
  keywordstyle = \color{blue},
  %commentstyle = \color{comment}
  }

\begin{document}


% Produce the title page
\thispagestyle{empty} \vspace{4cm}
\begin{center}
\begin{Huge}
{ MOOS  - Mission Orientated Operating Suite\\ }
\end{Huge}
\vspace{7cm}

%\epsfig{file=moose6.eps,width = 0.2\linewidth} \\
%\epsfig{file=mit_logo_small.eps,width = 0.18\linewidth} \\
\epsfig{file=moose6.eps,width = 0.2\linewidth} \\

\vspace{5cm}
\begin{Large}
{Paul Michael Newman\\ } \vspace{1cm}
%
%
{Department of Ocean Engineering\\ Massachusetts Institute of
Technology\\\vspace{1cm}
Department of Engineering Science\\
Oxford University\\ }
\end{Large}
\vspace{0.5cm} Version 2.1 March 2006
\end{center}



\newpage
\begin{abstract}
This paper is about simple to use, extensible software for mobile
robotic research. It is concerned with a project called MOOS -- an
acronym for Mission Oriented Operating Suite. MOOS is an umbrella
term for a set of libraries and applications designed to
facilitate research in the mobile robotic domain. The spectrum of
functionality provided ranges over  low-level, multi-platform
communications,  dynamic control, high precision navigation and
path planning, concurrent mission task arbitration and execution,
mission logging and playback.

The first part of the paper describes the underlying philosophy of
MOOS and the resulting perceived benefits. The work then moves on
to describe the details of the design and implementations of core
system components. There then follows a set of high level
descriptions of principal mission-oriented MOOS processes.
Collectively these processes constitute a resilient, distributed
and coordinated suite of software suitable for in-the-field
deployment of sub-sea and land research robots.

\end{abstract}


\newpage
\section*{}

\vspace{3cm}
\begin{centering}
\epsfig{file=moose6.eps,width = 0.2\linewidth} \\
\end{centering}
\vspace{3cm}

\section*{Thanks}
First let me thank John for his trust and for believing in and
paying for the MOOS - I've had a ball. The Sea Grant crew made all
the difference, Rob for his advice and un-ending healthy cynicism,
Jim for his tenacity and book of spells , Sam for his skill and
amusing use of the ``pinger'', Joe for great help before, during,
and after trials and Justin for Florida and some great backing. I
very much appreciate their help, enthusiasm and support. Mike
Bosse was a superb client and colleague and always complained
about all the right things - cheers. Richard, thanks for your help
and being a great mate out here. Watch out for flat inert surfaces
- they can hurt a man.

Finally thanks to Sarah. For being great despite too many late
nights at MIT and the occasional ``lost'' weekend, for supplying
cookies and ridiculous MOOS paraphernalia. But most of all for
having made ``Boston'' sane and wonderful. Thank you.

For Version II of this document thanks to Mike Benjamin for excellent critisism
of the software and dedicated use of it. He's also an excellent cookie supplier. Thanks.





\newpage
\tableofcontents

\newpage
\part{Introduction}



\section{Philosophy and Background}
MOOS (pronounced ``moose'')  is an umbrella term applying to a set
of communicating applications. At its most general the ``MOOS''
refers to a suite of libraries and executables designed and proven
to run a field robot in sub-sea and land domains. Included in its
scope are a platform-independent, inter-process communication API,
sensor management such as DVL, LBL and SAS sonar, state of the art
navigation, vehicle dynamic control, concurrent mission task
execution, vehicle safety management, mission logging, mission
replay and reprocessing.

The heart of MOOS, its communications API and Library, was written
over a period of three days in late September 2001. It is the
fourth generation of communications software intended for mobile
robot systems written by the author.  The design of MOOS and the
functionality provided by its communications API was motivated by
experience and observations gained in using and developing several
software suites for mobile robots. In particular it was noted
that:
\begin{itemize}
\item Dependence on a particular operating system is bad news. The
development tools available in one choice may far out-perform
those available in another. Conversely the opposite may be true in
terms of real-time performance and networking. No one choice
satisfies all criteria.
\item Allowing source code dependencies to occur between
different applications can lead to project management problems and
slowed development. As the complexity of the project grows so does
the number of inter-dependencies and time spent coordinating
rebuilds etc.
\item Researchers often require a sense of ownership over an
element of a robotic system. It is desirable to be able to have an
individual write code in his or her own style and in isolation and
yet still have the resulting application interact with any number
of other applications/services running on the vehicle.
\end{itemize}

With these observations in mind the following design goals were
set:
\begin{itemize}
\item Platform independence - Code should run on Linux, NT, and
Win2000.
\item A collection of communicating processes should run the
vehicle - each process encapsulating a specialization or core
functionality.
\item The communications provided to these processes should be
utterly robust and tolerant of repeated stop/start cycling of any
process.
\item Processes should have no shared header file dependencies.
\end{itemize}

\section {Project Management in the Research Domain}
%
It is often the case that executables that need to interact with
each other have a clear 'owner', i.e have been developed on the
whole by a single researcher/engineer. Inevitably then, this work
carries the unique stylistic and architectural finger-prints of
the creator. This development model can be efficient until several
such projects are merged into a monolithic application. It is at
this point that code strain starts to show. Much effort can be
expended in fusing the projects with no overall change in
functionality. MOOS has been designed to allow projects to be
melded without blurring or dissolving process boundaries - the
number of processes remains the same. Instead each process joins a
``community'' of MOOS-enabled applications. Engineers can keep
coding their own application independently of all other source
code. This has ramifications when considering versioning and
source code control. The projects can live completely independent
lives - there is no compiled code dependency between them. A code
change in one domain cannot cause compilation  failures in
another.

\newpage
\part{Foundations}
\section{Overview}
It is useful to provide a brief description of a typical MOOS
driven system to provide a compelling motivation for the rest of
this document.

Consider the case of an single AUV (autonomous underwater vehicle)
operating within an LBL (long base-line) acoustic array
\footnote{MOOS can and has been equally well applied to land
robots however the AUV example is pretty interesting}. MOOS
provides all the software components and communications required
manage sensors, navigate, control actuators, plan trajectories,
monitor safety , log performance and both manual and automatic
control.
\begin{figure}[h!]\label{fig:Example}
\centering \epsfig{figure = Example.eps,width = 0.8\linewidth}
\caption{A complete MOOS configuration for AUV deployment. Taken
from the ``GOATS 2002'' experiment, Italy 2002}
\end{figure}
Figure \ref{fig:Example} shows a typical consortium of processes
used on a typical AUV research mission. In fact this setup was
used during the ``GOATS 2002'' experiment in Italy 2002. The AUV
was carrying a synthetic aperture sonar managed by a separate PC
in a payload section. MOOS enabled seem-less integration of this
payload with the processes running on the main vehicle computer
while providing real-time navigation and control of the vehicle
using a multitude of sensors. The details of these processes and
more importantly the underlying infrastructure will be discussed
in future sections of this document. At this juncture the most
important message to take home is that MOOS is a designed to
provide:
\begin{enumerate}
\item A standardized, multi-platform way for processes to share information
\item A set of key processes that fulfill ubiquitous roles in
mobile robotics
\end{enumerate}




\section{Topology}
MOOS has a star-like topology. Each application within a MOOS
community ( a \MA) has a connection to a single ``MOOS Database''
(called \DB) that lies at the heart of the software suite. All
communication happens via this central ``server'' application. The
network has the following properties:
\begin{itemize}
\item No Peer to Peer communication.
\item All communication  between the client and server is instigated by the
client. (ie the \DB {\textbf{never}} makes a unsolicited attempt
to contact a \MA.)
\item Each client has a unique name.
\item A given client need have no knowledge of what other clients exist.
\item A client has no way of transmitting data to a given client -
it can only be sent to  the \DB.
\item The network can be distributed over any number of machines
running any combination of supported operating systems.
\end{itemize}
This centralized topology is obviously vulnerable to
``bottle-necking'' at the server regardless of how well written
the server is. However the advantages of such a design are perhaps
greater than its disadvantages. Firstly the network remains simple
regardless of the number of participating clients. The server has
complete knowledge of all active connections and can take
responsibility for the allocation of communication resources. The
clients operate independently  with inter-connections. This
prevents rogue clients (badly written or hung) from directly
interfering with other clients.

\begin{figure}[ht!]
\centering  \epsfig{figure=Topology.eps,width=0.4\linewidth}
\caption{MOOS binds applications into a network with a star-shaped
topology. Each client has a single communications channel to a
server (\DB).} \label{fig:Topology}
\end{figure}

\section{MOOS Communities (and multiples
of)}\label{sec:Communities}

\New{} Post 2002 releases of MOOS have included explicit support
for multiple communities. The idea is that is is sometimes
advantageous to have groups of processes (bound together by mutual
connection to a MOOSDB hub) communicating with each other. To this
end, MOOSMsg's have been extended to included a ``Source
Community'' field which names the community from whence the
message came.

Under the ``one mission one mission file'' paradigm process
running on in community reads from the same mission file (see
section \ref{sec:ConfigFile}. The community name is specified by
the line \code{Community = <Name> } at the top of the mission
file. \footnote{Perhaps near the \code{ServerPort=} and
\code{ServerHost=} global definitions.}

The question remains --- how does this information get used? Well,
when the MOOSDB serving each community starts up (see Section
\ref{sec:DB}) the community name will be read and all messages
sent from the DB will be tagged with this community name (see
Section \ref{sec:Content}. However this tagging only happens if
the data content originated from the \DB's own local community
--- if it did not (i.e. it came from another community) then the
community name of the orginating community is preserved. To
understand how data from an external community could appear in one
particular \DB see section \ref{Sec:pMOOSBridge}.

\section{Message Content}\label{sec:Content}
The communications API in MOOS allows data to be transmitted
between \DB and a client. The meaning of that data is dependent on
the role of the client. However the form of that data is
constrained by MOOS. Somewhat unusually MOOS only allows for data
to be sent in string or double form. Data is packed into messages
(CMOOSMsg class) which contains other salient information shown in
Table \ref{tab:MOOSMsg}.
\begin{table*}
\centering
\begin{tabular}{l|l}\hline
  % after \\: \hline or \cline{col1-col2} \cline{col3-col4} ...
  {\textbf{Variable}} & {\textbf{Meaning}} \\ \hline
  Name  & The name of the data \\
  String Val & Data in string format \\
  Double Val & Numeric double float data \\
  Source & Name of client that sent this data to the \DB \\
  Time & Time at which the data was written \\
  Data Type & Type of data (STRING or DOUBLE)  \\
  Message Type & Type of Message (usually NOTIFICATION) \\
\New{Source Community} & The community to which the source process
belongs---see Sec \ref{sec:Communities}\\\hline
\end{tabular}\vspace{7mm}
  \caption{Contents of MOOS Message}\label{tab:MOOSMsg}
\end{table*}
The fact that data is commonly sent in string format is often seen
as a strange and inefficient aspect of MOOS. For example the
string \verb"Type=EST,Name=AUV,Pos=[3x1]{3.4,6.3,-0.23}" might
describe the position estimate of a vehicle called ``AUV'' as a
3x1 column vector\footnote{Typically string data in MOOS is a
concatenation of comma separated "name = value" pairs.}. It is
true that using custom binary data formats does decrease the
number of bytes sent. However binary data is unreadable to humans
and requires structure declarations to decode it and header file
dependencies are to be avoided where possible. The communications
efficiency argument is not as compelling as one may initially
think. The CPU cost invoked in sending a TCP/IP packet is largely
independent of size up to about one thousand bytes. So it is as
costly to send two bytes as it is one thousand. In this light
there is basically no penalty in using strings. There is however a
additional cost incurred in parsing string data which is far in
excess of that incurred when simply casting binary data.
Irrespective of this, experience has shown that the benefits of
using strings far outweighs the difficulties. In particular:
\begin{itemize}
\item Strings are human readable - debugging is trivial especially
using a tool like MOOSScope. (see Section \ref{sec:MOOSScope})
\item All data becomes the same type
\item Logging files are human readable (they can be compressed for
storage).
\item Replaying a log file is simply a case of reading strings from
a file and ``throwing'' them back at the \DB in time order.
\item The contents and internal order of strings transmitted by an application can be changed
without the need to recompile consumers (subscribers to that data)
- users simply would not understand new data fields but they would
not crash.
\end{itemize}
Of course, scalar data need not be transmitted in string format -
for example the depth of a sub-sea vehicle. In this case the data
would be sent while setting the data type to  \verb"MOOS_DOUBLE"
and writing the numeric value in the double data field of the
message.

\section{Threading and Process Models}
The choice of processes over threads was made on two counts,
firstly that of stability - a rogue process cannot corrupt the
program/data space of another process (in a sane OS that is).
Secondly on the basis of swift and pain-free development by
several programmers with diverse backgrounds. Building a single
monolithic executable by several people requires, at a minimum,
adherence to programming guidelines and styles that may not be
native to all those included - especially in an academic
environment. The use of small-footprint, independent processes
implies developers can use whatever means they see fit to
accomplish the job. Linking with the communications library
integrates them seamlessly with all other processes but denies a
process the means of interfering with others.



\section{Communications Mechanics}
%%%%%%%%%%%%%%%% FIGURE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{figure*}[ht!]
\centering \epsfig{figure = Comms.eps,width = 1.0\linewidth}
\caption{The mechanics of the client server interaction in MOOS.
The user code calls the \code{Notify} method to transmit data.
This method simply adds a message to the ``outbox''. Some time
later (1) the communications thread calls into the database. When
the database is not busy it accepts the client's call (2). The
client then packs the entire outbox into a single large
transmission which is sent to and read by the server (3). The
server unpacks the packet into its constituent messages and place
copies (according to subscriptions and timing ) in the mailboxes
of other connected clients. The server then compresses the mailbox
of the current client into a packet and sends it back to the
client (4). At this point the transaction is then complete and the
server terminates the conversation and looks to begin the same
process with a different client. Upon receiving the reply packet
the client communications thread unpacks it and places the
resulting messages in the ``inbox'' of the client. The user code
can retrieve this list of messages at {\it{any time}} by calling
the \code{Fetch} method.}
\end{figure*}

Each client has a connection to the DB. This connection is made on
the client side by instantiating a class provided in the core
\code{MOOSLIB} library called \code{CMOOSCommClient}. This class
manages a private thread that coordinates the communication with
the \DB. The \code{CMOOSCommClient} object completely hides the
intricacies and timings of the communications from the rest of the
application and provides a small, well defined set of methods to
handle data transfer. Using the \code{CMOOSCommClient} each
application can:
\begin{enumerate}
\item Publish data - issue a notification on named data.
\item Register for notifications on named data.
\item Collect notifications on named  data.
\end{enumerate}

\subsection{Publishing Data - notification} Assume as a result of
 some computation or input, a process \code{A} has a result that
is likely to be of use other undisclosed (remember MOOS
applications do not know about each other) processes \code{B} and
\code{C} - for example a position estimate. The simplest way in
which \code{A} can transmit its new data is to simply call the
\code{Notify} method on its local \code{CMOOSCommClient} object
specifying the data, its name and the time at which it is valid.
Behind the scenes this method then creates a suitable
\code{CMOOSMsg} filling in the relevant fields. The action of
publishing data in this way should be viewed as a
{\emph{notification}} on a named data variable. Crucially this
does not imply a change in the {\emph{value}} - the outcome of the
computations resulting in the need to publish data may remain not
change . For example two sequential estimates of location of a
vehicle may remain numerically the same but the {\it{time}} at
which they are valid changes - this constitutes a data
notification.

As far as the application-specific code in \code{A} is concerned
the invocation of the \code{Notify} method results in the data
being sent to the \DB. What is really happening however is that
the \code{CMOOSCommClient} object is placing the data in an
``outbox''  of \code{CMOOSMsg}s that need to be sent to the \DB at
the next available opportunity. The next obvious question is
``when does the  data reach the \DB?''. The \code{CMOOSCommClient}
object thread has a ``Comms Tick'' - essentially a timer that
contacts the \DB at a configurable rate (typically 10Hz but up to
50Hz ). All the messages in the outbox are packed into a single
packet or ``super message'' called a \code{CMOOSPkt}. Eventually
the \DB will accept the incoming call from the client \code{A} and
receive the packet. At this point the data flow is reversed and
the \DB replies with another \code{CMOOSPkt} containing
notifications (issued by other processes like \code{B} and
\code{C}) that are relevant to  \code{A}. How a process declares
what constitutes a relevant notification is discussed in section
\ref{sec:Registration}. If at the time the thread calls into the
\DB the outbox is empty (i.e there is nothing to notify) a NULL
message is created and sent. Similarly the \DB my reply with a
\code{CMOOSPkt} containing only a NULL message if  nothing of
interest to the client has happened since its last call in. This
policy preserves the strict symmetry of ``one packet sent, one
packet received'' for all occasions.


\subsection{Registration}\label{sec:Registration} Assume that a
list of names of data published has been provided by the author of
a particular MOOS application. For example, a application that
interfaces to a GPS sensor may publish data called \code{GPS\_X}
and \code{GPS\_Y}. A different application may register its
interest in this data by {\it{subscribing }} or {\it{registering}}
for it. An application can register for  notifications using a
single method \code{Register} specifying both the name of the data
and the maximum rate at which the client would like to be informed
that the data has been changed. The latter parameter is specified
in terms of the minimum possible time between notifications for a
named variable. For example setting it to zero would result in the
client receiving in the \code{CMOOSPkt} (that is the \DB's reply)
a collection of messages describing each and every change
notification issued on that variable.

\subsection{Collecting Notifications}\label{sec:CollectingNotifications}
At any time the owner of a \code{CMOOSCommClient} object can
enquire whether it has received any new notifications from the \DB
by invoking the \code{Fetch} method. The function fills in a list
of notification \code{CMOOSMsg}s describing what has changed, what
client made the change, when it was done and what the data type is
(see table \ref{tab:MOOSMsg} in section \ref{sec:Content}). Note
that a single call to \code{Fetch} may result in being presented
with several notifications corresponding to the same named data.
This implies that several changes were made to the data since the
last client-server conversation. However, the time difference
between these similar messages will never be less than that
specified in the \code{Register} function described in section
\ref{sec:Registration}.


\section{The MOOSDB}\label{sec:DB}
The \DB is the heart of the system. It serves as the hub through
which all communication occurs. It is tempting to think of the \DB
as simply a blackboard - an entity which stores the current state
(represented by values of named variables) of the system.
Typically a blackboard allows clients shared access to a
centralized repository of information. Although the \DB does
maintain the most recently set value of all variables and in that
way is similar to a blackboard, the way in which data is retrieved
is very different. The \DB records, on  behalf of its connected
clients, the {\it{history}} of changes to data. Assume a client
\code{A} has subscribed to variables called \code{p} and \code{q}
with a minimum notification period of $\tau_{p}$ and  $\tau_{q}$
seconds respectively. The time is now $t$ and the last call-in was
at time $t'$,$\Delta = t-t'$ seconds ago. When \code{A} calls in,
it is not simply presented with the most recent values of \code{p}
and \code{q} but rather all the {\it{changes}} that have occurred
to them between $t'$ and $t'$. Imagine that some other process
\code{B} is publishing changes (value and/or time-stamp) to $p$
and $q$ every $\tau_B$ seconds. The call in will result in $n_p$
and $n_q$ notification messages being returned to the client where
\begin{align*}
n_p &= \begin{cases}
    floor(\frac{\Delta}{\tau_{p}}) & \text{$\tau_{p} \geq \tau_B$}, \\
    floor(\frac{\Delta}{\tau_{B}}) & \text{otherwise}.
  \end{cases}\\
n_q &= \begin{cases}
    floor(\frac{\Delta}{\tau_{q}}) & \text{$\tau_{q} \geq \tau_B$}, \\
    floor(\frac{\Delta}{\tau_{B}}) & \text{otherwise}.
  \end{cases}
\end{align*}

If no clients have issued relevant notifications since $t'$ then
there will be no notification messages stored at the \DB for
collection by the client. The only exception to this rule is the
first time a client calls in after registering for a notification
on a variable. In this case the value of the variable is returned
in a notification message with a time-stamp specifying when the
data was last set.

\newpage
\part{Using The MOOS -- Libraries and Classes}


The combination of the \DB and the two libraries \code{MOOSLib}
and \code{MOOSGenLib} are all that is needed to build a MOOS
community. The role and operation of the \DB has already been
discussed in section \ref{sec:DB}. The contents and utilities
provided by the libraries are now described.

\section{MOOSLib}
The primary role of \code{MOOSLib} is to contain all the
communications components used both by the \DB itself and
\code{CMOOSCommClient} objects owned and used by client
applications.
\subsection{\code{CMOOSApp}}\label{sec:CMOOSApp}
 Perhaps the most important class exposed from the library is \code{CMOOSApp}. This class should be
used as  a base class for all MOOS applications. It provides along
with other things:
\begin{itemize}
\item Management and configurations of a \code{CMOOSCommClient} object
\item Tools for reading configuration parameters (using a file
reading tool exported from \code{MOOSGenLib}).
\item Timing control of the main thread of the application and an
additional communications thread.
\item Virtual functions that can be overloaded to perform specific
actions when:
\begin{enumerate}
\item New mail (notifications) arrives
\item The default work of the application should occur
\item The client connects to the \DB
\item The client disconnects from the server
\item The application is about to start
\end{enumerate}
\end{itemize}
Appendix A gives example code of a skeleton MOOS application using
the functionality provided by deriving from \code{CMOOSApp}.
Indeed this code could be used as the template from which to start
building all new MOOS applications. The timing of the application
is determined by two timer frequencies \code{AppTick} and
\code{CommsTick} which are set in the process configuration file
(see section \ref{sec:ConfigFile}). The \code{CMOOSApp} base class
does its best to call the virtual \code{Iterate} method at the
frequency specified by \code{AppTick}. It is within this method
that the bulk of the work of the application should be undertaken
- for example processing data or executing control loops. Just
before \code{Iterate} is called the \code{CMOOSApp} base class
calls \code{Fetch} (see section \ref{sec:CollectingNotifications}
on its \code{CMOOSCommClient}. If mail is present then the virtual
function \code{OnNewMail} is called. Here an overloaded version is
passed a list of \code{CMOOSMsg}s which can contains the relevant
notifications from the \DB and which can be acted upon as the
application sees fit. Only messages corresponding to variables
that have been registered for will be present. Typically an
application registers its interest in named data by calling
\code{CMOOSCommClient::Register()} during the virtual callback
\code{OnConnectToServer()}. This guarantees that the server has
been found, successfully connected to and subsequently any
registrations shall be successful. It should be noted that
attempting to register outside of this function (for example in
the overloaded \code{OnStartUp} method) may fail because the
communications thread with \code{CMOOSCommClient} has not yet
established a connection with the \DB.

\subsection{\code{CMOOSInstrument}} The class
\code{CMOOSInstrument} is another important base class. It is
intended to simplify the writing of applications interacting with
hardware via a single serial port. The class extends
\code{CMOOSApp} with utilities to manage and set up a
platform-independent serial port\footnote{The serial port classes
live in \code{MOOSGenLib} - see section \ref{sec:GenLib}.}. The
serial port can be configured to be asynchronous and receive
unsolicited streaming data or to be synchronous and perform
blocking read and writes. The choice  depends on the device the
application is intended to communicate with.

\section{MOOSGenLib}\label{sec:GenLib} The library
\code{MOOSGenLib} is a tool chest. It contains utilities and
classes used throughout MOOS. In particular it provides:
\begin{itemize}
\item Platform-independent serial ports (asynchronous and
synchronous).
\item Thread safe configuration reading tool
-- \code{CMOOSMissionFileReader}.
\item String manipulation/parsing tools.
\item Geodesy tools.
\item debug statement tools - MOOS equivalent of \code{printf}.
\end{itemize}
Of these assets the configuration file reader in particular
warrants more discussion.

\subsection{Configuration Files *.moos}\label{sec:ConfigFile}
Every MOOS process can read configuration parameters from a
``Mission file'' which by convention has a ``.moos'' extension.
For example the default mission file mentioned in the example code
given in Appendix A is {\it{Mission.moos}}. Traditionally MOOS
processes share  the same mission file to the maximum extent
possible. For example it is usual for there to be one common
mission file for all MOOS processes running on a given machine.
Every MOOS process has information contained in a configuration
block within a *.moos file. The block begins with the statement
\begin{center}
\code{ProcessConfig} = \code{ProcessName}
\end{center}
where {\code{ProcessName}} is the unique name the application will
use when connecting to the \DB. The configuration block is
delimited by braces. Within the braces there is a collection of
parameter statements - one per line.

Each statement is written as
\begin{center}
\code{ParameterName = Value}
\end{center}
where \code{Value} can be any string or numeric value. Typically
the format of the value string is a comma separated list of
strings or numbers. However some applications may require more
complicated syntax using a combination of delimiters other than
simple commas. Of course, the details of these settings is part of
the application documentation. Examples can be found on the MOOS
website ({\it{http://oceanai.mit.edu/pnewman}}). All applications
deriving from \code{CMOOSApp} and \code{CMOOSInstrument} inherit
several important configuration options. For example,
\code{CommTick} and \code{AppTick} (see section
\ref{sec:CMOOSApp}. The documentation on the MOOS webpage gives
details of these common parameters.

\begin{figure}\label{fig:ProcConfig}
\caption{A typical configuration block for a MOOS application. A
process called ``iDepth'' will search a mission file until a block
like this is found. It will then parse our configuration
parameters.}
\begin{lstlisting}[language = {matlab}]{}
/////////////////////////////
// depth sensor configuration
ProcessConfig = iDepth
{
    AppTick = 8
    CommsTick   = 4
    Port        = com1
    BaudRate    = 9600
    Streaming   = false
    Type        = ParaSci
    Resolution  = 0.1
}
\end{lstlisting}
\end{figure}
Figure \ref{fig:ProcConfig} gives an example of a typical
configuration block, in this case for a depth sensor. The
parameters \code{Type} and \code{Resolution} are specific to the
class defining the methods of a ``DepthSensor''. All the other
parameters are handled by its base classes (\code{CMOOSInstrument}
and \code{CMOOSApp}).

\subsection{Utility Functions}
\code{MOOSGenLib} contains a host of utility functions that are
described below. These functions are ubiquitous within MOOS and
should not be substituted with local version producing the same
functionality. The reason is the innards if these functions may be
built to accommodate subtleties in MOOS. A good example is that of
\code{MOOSTime} which returns the current process time
{\em{corrected}} by a constant term setup by the MOOS
communications when the server is contacted.

\begin{description}
  % after \\ : \hline or \cline{col1-col2} \cline{col3-col4} ...
%
\item[\code{MOOSFormat}]  The MOOS version of \code{sprintf}. It
  returns a formatted \code{std::string}  object.
%
\item[\code{MOOSTrace}]  The MOOS equivalent of \code{printf} printing
 a formatted string to the console. When run under win32 the
  function also writes to a debugger window if applicable. Note
  that   \code{MOOSTrace} does not use \code{cout} because on some
  Linux releases this is not thread safe.
%
\item[\code{MOOSChomp}]  A massively useful, simple string parsing
  function.   \code{MOOSChomp} is passed a string, S, to act on and a
  delimiter string, D, as parameters. It returns the substring
  occurring before D in S and removes everything up to
  the end of the D from the S. For example if S = ``X = 4, Y = 9''
  and D =``,'' then calling \code{MOOSChomp(S,D)} would return ``X =
  4'' and S would now be ``Y=9''.

\item[\code{MOOSTime}]  Returns the current time in decimal seconds (a
  double) for the current process. All connected processes will
  show the same time {\em{even}} if their respective machine clocks
  differ. This is achieved by deducing a client correction during initial handshaking with the
  \DB.
%

\item[\code{MOOSGetTimeStampString}] returns a time/date string formatted
in the MOOS convention - useful for naming temporary local files
for development purposes etc.
%
\item[\code{MOOS\_ANGLE\_WRAP}] Wraps all angles (in radians) to be
with $\pm \pi$ - forgetting to wrap angles can cause woe.
%
\item[\code{MOOSPause}] Pauses the current thread (not process) for
a specified number of milliseconds.
\item[\New{\code{MOOSGetValFromString}}]. Extracts named token=val
pairs from a string. For example: \newline
\code{name=AUV1,pose=[3x1]\{2,3,4\}}\\
Note the formatting of the vector - matrices can also be parsed in
this way. The function fills in a reference to
\code{std::vector<double>} and references to the rows and columns
that have been squeezed into this flatend form.
\end{description}


\subsection{Serial Ports}
The \code{CMOOSInstrument} class extends the \code{CMOOSApp} class
to offer non-blocking serial port functionality. The serial port
operations can be one of two modes - synchronous and asynchronous.

\begin{description}
\item[Synchronous] This mode is designed to be applied to
instruments that are synchronous - that is they only talk when
asked to. When in this mode the serial port owner is  responsible
for sending commands and listening (with a timeout) for replies as
required. It is the simplest mode and commonly employed.
\item[Asynchronous / Streaming] This mode is designed for use with instruments
that issue a stream of unsolicited transmissions. In this case the
serial port class manages a listen thread that parses incoming
bytes into a  series of telegrams, which are stored  along with a
time stamp in a list. The characters/bytes that delimit an end of
telegram in the input stream can be changed on the fly. At any
time the serial port user can query the store of telegrams to
retrieve a message or perhaps purge the list of its contents.
\end{description}

\newpage
\part{MOOS Conventions}

\section{Coordinate Conventions}
MOOS processes communicate using a defined coordinate system
illustrated in figure \ref{fig:coordinates}. The salient points to
note about this system are:
\begin{itemize}
\item The global (earth) frame is a conventional East-North-Up
frame.
\item The vehicle body frame  has been designed to align with the
global frame when the vehicle has zero yaw.
\item At zero heading the vehicle points north.
\item Zero heading is equivalent to zero yaw.
\item Yaw = -heading*$\pi/180$ (heading is in degrees).
\item Depth is in the opposite sense to Z
\end{itemize}
The fact that a coordinate system is defined that must be used
between processes {\it{does not mean}} this system is inflicted on
the internals of an application. Within the boundaries of a
process the developer is free to use whatever system he or she
feels comfortable with. All that is needed is a little patch work
to transform input and output data between coordinate frames.
However life can be made easier by using one coordinate frame
throughout.


\begin{figure*}[ht]\label{fig:coordinates}
\centering \epsfig{figure = coordinates.eps,width = 1.0\linewidth}
\caption{The MOOS coordinate system. Note that $\dot{yaw} =
-\dot{heading}$ and that the body and earth frames align at the
origin with the vehicle pointing north at zero yaw. Also the body
'y' axis is towards the front of the vehicle. (You may be used to
having the body x axis point towards the nose of the vehicle).
Note also that Z points up.}
\end{figure*}


\section{Geodesy} The geodetics with MOOS are refered to as
\code{MOOSGrid}. The geodesy tools within MOOS assume operation in
a local area - say a square with sides less than 20 km long. With
this assumption it is reasonable to superimpose a local cartesian
space over the work area and form a mapping from Lat/Long
coordinates to local \code{MOOSGrid}.
\begin{figure}
\centering \epsfig{figure = Geodesy.eps,width = 0.7\linewidth}
\caption{Defining a local cartesian \code{MOOSGrid} around a
lat/long origin}
\end{figure}
The class \code{CMOOSGeodesy} in \code{MOOSGenLib} performs all
the mapping required. It is primed  with the origin of the
\code{MOOSGrid} (in decimal lat/long). It can then convert
lat/long measurements to cartesian \code{MOOSGrid} coordinates
using a geodetic radius that is a function of the origin location.


\section{Units}
MOOS was designed and built by a European and so uses easy SI
units throughout. All distances are in meters and times in
seconds. Angles are always in radians and wrapped to lie with $\pm
\pi$. The only exception to this is ``heading'' variables, which
are in degrees. However  heading variables are never used
internally  - they are for human display alone. Instead their
``Yaw'' counterparts are used, which are always in radians.



\section{Naming Conventions}

\subsection{Process Naming}
MOOS developers are encouraged to adopt the naming convention for
applications given in table \ref{tab:Naming}. The basic idea is
that the prefix to the process gives some indication of its
function. Processes beginning with ``i'' are typically derived off
\code{CMOOSInstrument} and perform some kind of I/O via serial
port (often to a hardware sensor) or non-MOOS communications.
Processes beginning with ``p'' are pure and perform no I/O other
than via the MOOSDB. Finally ``u'' processes are utilities -
performing tasks not critical to vehicle operation but which are
perhaps useful at other times - for example \code{uGeodesy}
converts from ``Lat/Long'' to local-grid (\code{MOOSGrid})
coordinates.
\begin{table}[h!]
\label{tab:Naming} \caption{The naming convention for MOOS
applications} \centering
\begin{tabular}{p{1.0in}|p{2.8in}|p{1.65in}}
  % after \\ : \hline or \cline{col1-col2} \cline{col3-col4} ...
  \textbf{Name} & \textbf{Description} & \textbf{Example} \\
  \hline
  i[{\it{Name}}] &  Interface applications. Interacts (has I/O) with  an external device, for example via a keyboard or serial port & \code{iGPS, iCompass, iRemote}
  \\
  p[{\it{Name}}] & Pure applications. Only interacts with other MOOS applications & \code{pHelm, pLogger, pNav}
  \\
  u[{\it{Name}}] & Utility applications. Not used at run time but a useful at other times & \code{uPlayBack, uGeodesy} \\
\end{tabular}
\end{table}



\subsection{Variable Naming}
Data can take any string name. A developer could use any
combination of characters to name the data published by his or her
application. In practice though sticking to a convention makes
some things easier. A good example of this is the \code{pNav}
process that expects some kinds of sensor data to be named in a
standard format. Sensor data can be classified into at least the
following categories:
\begin{table}[h!]
\centering
\begin{tabularx}{\linewidth}{p{1.0in}|p{2.0in}|X}
\textbf{Quantity} & \textbf{Description} & \textbf{Example} \\
\hline
\code{X,Y,Z}& sensor measures vehicle position & GPS\\
 \code{DEPTH}& sensor gives depth & Pressure sensor  \\
\code{YAW} & sensor measures rotation around Z axis& Gyro\\
\code{BODY\_VEL} & sensor measures velocity in body frame & DVL,
Odometry
\end{tabularx}
\label{tab:SensorTypes} \caption{Sensor categories} \normalsize
\end{table}

If a sensor, managed by a process called \code{iSensor}, measures
one of these quantities then the name under which the data should
be published has the format \code{SENSOR\_\it{CATEGORY}}. This is
best highlighted with a few examples:
\begin{itemize}
\item iGPS measures X and Y position. It publishes \code{GPS\_X}
and \code{GPS\_Y}.
\item iDepth measures depth. It publishes \code{DEPTH\_DEPTH}.
\item iLBL measures range and depth. It publishes \code{LBL\_DEPTH}
and \code{LBL\_TOF} (time of flight).
\end{itemize}
This simple convention makes visual comprehension of the system
(when using a tool like MOOSScope \ref{sec:MOOSScope}) simple.
Additionally it avoids naming conflicts as the \DB  requires
unique process names and therefore basing data names on process
names will also result in unique data names.


\subsection{Actuator Naming } At the time of writing MOOS
applications are aware of three actuator types: \code{THRUST},
\code{ELEVATOR} and \code{RUDDER}. Clearly this illustrates the
early history of MOOS as software for autonomous underwater
vehicles (AUVs). On land the \code{ELEVATOR} actuator has no
meaning. The \code{THRUST} and \code{RUDDER} axes however map well
to throttle and steer angle.

Note that perhaps counter intuitively, but consistent with the
MOOS coordinate frame, a positive elevator angle will cause a
vehicle to make its pitch more negative. Similarly positive rudder
will make yaw decrease (but heading increase).




\newpage
\part{Key MOOS Processes}

This section describes some of the MOOS applications that have
been written using the MOOS API and libraries for use on mobile
robots. This section is not intended to provide definitive
documentation on these processes but rather to provide a good
summary of a field-tested installation of a MOOS community.


\section{ The Helm - \code{pHelm}}
Along with \code{pNav} the Helm process \code{Helm} is one of the
most important high-level processes that are typically run on a
given mission. The Helm's job is to take \code{NAV\_*} from the
navigator and, given a set of mission goals, decide on the most
suitable actuation commands. The multiple mission goals take the
form of prioritized tasks within the Helm. For example a
``snap-shot'' of the helm might reveal five active tasks: follow a
track line, stay at constant depth, limit depth, limit altitude
and limit mission length. The first two of these are conventional
trajectory control task that could be expected to be found in any
mobile robot lexicon. The last three tasks are safety tasks that
take some action if a limiting condition specified within them is
violated.

The Helm is designed to allow ``at sea'' reloading of missions. If
the mission file (specifying what tasks to run) is edited while
the Helm is runnning, the Helm can be commanded via a MOOS message
(\code{RESTART\_HELM}) to clean down and rebuild itself. This
makes for very rapid turnaround of missions in a research-oriented
field trip.

The Helm has two modes: online and off-line. When off-line no
tasks are run and the Helm make no attempt to control actuators.
In his mode the vehicle can be controlled via \code{iRemote} (see
\ref{sec:iRemote}. When on-line the vehicle's motor are under the
control of the Helm - autopilot is engaged. As would be expected
\code{iRemote} is used to send the signal that relinquishes the
manual control of the vehicle and puts the Helm online. Manual
control can be regained at any time by pressing ``space'' on the
iRemote console.

The details of tasks that can be run by the Helm and topics
relating to their management are now discussed.

\begin{figure}[h!]
\centering \epsfig{figure=mission.eps,width = 1.0\linewidth}
\caption{A typical mission plan. Traverse to (200,400), dive to
50m and perform a survey. Impose safety limits of 100m depth and
7m altitude. When the Survey is complete (or timed out) return to
the dive co-ordinate and surface. If something terrible has
happened and mission is still running after one hour - abort
immediately. The task priorities are written in triangles and
timeouts in boxes above the task descriptions.}
\end{figure}

\subsection{Tasks}
As might be expected, the Helm and its constituent tasks rely
heavily on the communications provided by the lower level MOOS
API. The tasks use the communications apparatus to coordinate
themselves. The parent Helm application is derived from
\code{CMOOSApp} and as such has access to the MOOS communications
system. The Helm application handles all communications on behalf
of its owned tasks. All received \code{CMOOSMsg}s are offered to
all active tasks. Each task is queried for any newly required
subscriptions that are subscribed for by the Helm. In a similar
fashion each task is queried for any messages that it requires to
be emitted. This mechanism gives each task the illusion that it
has its own \code{CMOOSCommClient} object even though it is in
fact sharing it with  other active tasks.



\begin{table}[h]\label{tab:TaskProps}
\caption{Base Task Properties}
 \centering
\begin{tabular}{p{0.2\columnwidth}|p{0.7\columnwidth} } %\hline
{\textbf{Property}} & {\textbf{Use}} \\ \hline %\hline
  \code{Name} & The name of the task - for example ``Leg7'' or
  ``InitialDelay''  \\ %\hline
  \code{StartFlags} & A list of  messages names that if received, will spur the tasks into action (turn it
  on).
  \\ %\hline
  \code{FinishFlags} & A list of messages that are emitted when the task
  completes or when it starves because it is not receiving
  notifications on one or more of its subscribed variables.
  \\ %\hline
  \code{EventFlags} & A list of messages that are emitted when some event happens but the task does not complete. A
  typical example of this would be a depth limit task emitting event messages when the vehicle exceeds a specified limit. The last
  thing you want to happen is the task quitting just when this has happened. Instead the event flags are sent and the task
  keeps running. \\ %\hline
  \code{TimeOut} & The maximum time the task should run for. If the task does not complete naturally before this
  timeout the FinishFlags are sent and the task retires itself automatically. The value of ``NEVER'' can be specified to
  indicated that a task should never timeout --- useful for safety tasks. \\ %\hline
  \code{InitialState} & A task can be on initially in which case it does not listen for start-flags. Or it can be off in which case it
  must receive a start-flag before it goes active. \\ %\hline
  \code{Priority} & Each task is assigned a priority from 1 to $\infty$ (0 is reserved for the special \code{EndMission} task). The lower
  the value the more important the task is.    \\ %\hline
\end{tabular}
\end{table}

All tasks are derived from a common base class that provides all
descendants with a shared heritage. In particular the ability to
specify in the mission file some key named properties which are
described in Table \ref{tab:TaskProps}. Perhaps the most important
thing to understand is that tasks use MOOS messages to synchronize
themselves. As one task finishes it emits one or more messages
which may be ``just the thing'' that other tasks were watching for
to signal that they should go active. Note that this has two
important consequences:
\begin{itemize}
\item One task can activate any number of other tasks.
\item A task can be activated by activity {\it{outside}} of the
helm. For example a command received by an acoustic modem could
start a task. This open architecture is a powerful concept within
MOOS.
\end{itemize}

\subsubsection{Task Completion}
A given task completes when any of the following conditions are
met:
\begin{itemize}
\item It has completed successfully - fulfilled its goal criteria.
For example it has steered the vehicle close (enough) to a way
point or has driven the vehicle to a specified depth.
\item It has timed out before achieving its goal.
\item It has starved. This occurs when it is does not receive the
data it needs at regular enough intervals. This is a crucial
safety feature. Say for example the navigation has failed -
\code{NAV\_*} will not be being emitted by the navigator and a
motion control task requiring navigation information to function
should not be allowed to continue to run with blithe disregard.
Starvation of tasks is a sure sign that something is wrong with
the system configuration or navigation.
\end{itemize}

\subsubsection{Task Arbitration}
The Helm employs the simplest of strategies in deciding which task
wins when two concurrent active tasks are both trying to control
the same actuator --- the one with highest priority (lowest
numerical value) wins. To illustrate this point envision the case
where a track-line task is running at priority level three. Then a
way-point task with priority level two goes active - perhaps after
reception of data via an acoustic modem. The way-point task will
take control of the rudder actuator until it completes. At this
point the original track-line task will resume. Throughout the
episode the track-line task is unaware that it does not have
control of the vehicle. In the case that one or more equal
priority tasks controlling the same actuator(s) are active the
Helm simply chooses to give the first task processed (in its list
of active tasks) control.

\subsection{Task Configuration and *.hoof Files}
Tasks are configured in a similar way to processes --- within a
named, brace delimited block of text. Any number of tasks can be
specified in this fashion. A task configuration block always
begins with \code{Task}={\it{TaskType}}, where {\it{TaskType}} is
one of the named types in Table \ref{tab:TaskSummaries} followed
by the opening brace of the block. Figure \ref{fig:TaskSpec} shows
typical task configuration blocks for two tasks.
%
\begin{figure}[ht]\label{fig:TaskSpec}
\begin{lstlisting}[]{}
Task = ConstantHeading
{
    Priority = 3
    Name = South
    Heading = 180
    TimeOut = 300
    InitialState = OFF
    StartFlag = MissionStart
    FinishFlag = GoNorth
    LOGPID = true
}

Task = ConstantHeading
{
    Priority = 3
    Name = North
    Heading = 0
    TimeOut = 120
    InitialState = OFF
    StartFlag = GoNorth
    FinishFlag = EndMission
    LOGPID = true
}
\end{lstlisting}
\end{figure}
%
In this case two task are being configured -- one to drive south
for 300 seconds and when this task completes another will drive
north for 120 seconds --- note the pairing of Start and Finish
flags. Each task derived from the base task class is likely to add
its own specialization parameters (like \code{Heading} in the case
of \code{ConstantHeading} Tasks). The semantics and specifications
of these additions are found in the task documentation (see the
MOOS web-pages http://oceanai.mit.edu/pnewman ).


\subsubsection{Task Specification Redirection} If the Helm
configuration block contains the line ``\code{TaskFile}=
{\it{filename.hoof}}'' then at startup the helm builds all the
tasks it finds in the specified \code{*.hoof} file. This
indirection is useful for building a library of missions that can
be loaded into the Helm at any time simply by changing a single
line in the Mission file.


\begin{table}[h!]\label{tab:TaskSummaries}
\caption{A summary of common task functionality} \centering
%
\begin{tabular}{p{0.3\columnwidth}|p{0.7\columnwidth}}
%\begin{tabularx}{0.9\linewidth}{|l|X|}
%\begin{tabularx}{0.9\linewidth}{|p{0.2\columnwidth}|p{0.8\columnwidth}|}

{\textbf{Task}}  &  {\textbf{Use}} \\ \hline
%
\code{TimeOut} & Issues \code{FinishFlags} after timeout. This is
useful for creating a pause between tasks - for example a delay at
mission start.
\\%\hline
%
\code{GoToWayPoint} & Go to a specified XY location. A tolerance
can be specified to stop un-ending hunting. Requires X,Y and Yaw
data.
\\%\hline
%
\code{ConstantDepth}  & Level Flight. Requires only depth data and
pitch data.
\\%\hline
%
\code{ConstantHeading} & Drives the vehicle at a constant heading.
Requires only yaw data.
\\%\hline
%
\code{XYPattern} & Repeats a pattern of way-points. Requires X,Y
and Yaw data. The number of repetitions required can be specified.
\\%\hline
%
\code{ZPattern} & Performs a series of depth set points. Requires
depth and pitch data. For example combining this with a orbit task
will execute a helical pattern.
\\%\hline
%
\code{GoToDepth} & Spiral to a given depth and exit. Requires
Pitch and Depth data.
\\%\hline
%
\code{LimitAltitude} & Fire event flags if too close to sea bed. A
Safety task requiring Altitude data. This has saved the vehicle
several times.
\\%\hline
%
\code{LimitDepth} & Fires event flag if the vehicle is too deep. A
Safety task that is usually run with timeout=NEVER
\\%\hline
%
\code{EndMission} & Abort Mission (highest priority). Set to be
the highest priority task (0). Locks out all other tasks. Usually
commands all actuation to zero.
\\%\hline
%
\code{DiveTask}  & Dive from surface (e.g reverse dive) \\%\hline
%
\code{Orbit} & Orbit a given location in XY plane. The direction, radius and number of orbits can be specified \\%\hline
%
\code{Survey} & Perform a survey (mow lawn) centered  on specified
position with given rotation and extent.\\%\hline
%
\code{TrackLine} & Execute a linear path between two points.
\\%\hline
%
\code{OverAllTimeOut} & Limit Total length of mission. Always use
this task - it is compulsory. Its FinishFlag should be the
StartFlag of an EndMission task.
\\%\hline
%
\code{LimitBox} & Fire event flags if 3D working volume of mission
is exceeded. A Safety task useful for trapping navigation failure.
\\%\hline
\end{tabular}
\end{table}


Table \ref{tab:TaskSummaries} gives a brief summary of the most
commonly used tasks found in the \code{MOOSTaskLib} library. This
list is not exhaustive but serves to illustrate the kind of
functionality provided. The configuration parameters for each task
can be found on the MOOS documentation web-pages.


\subsection{Third-party Task Execution}
An interesting component of the Helm is its ability to dynamically
launch a task on behalf of a another client -- ``a third-party
request''. Obviously some security needs to be in place to stop
wayward software requesting tasks to be performed that endanger
other aspects of the mission or even the vehicle itself. The issue
here is that third-party requests are simply MOOS messages with a
certain string format issued from the innards of some unknown
application. The third-party request security mechanism requires
that the human creating the mission file actively grants
permissions (by placing certain text in the Helm's configuration
block) for the Helm to launch a specified task on behalf of a
specified (named) client. Any third-party requests not mentioned
in the configuration block will be denied.

\subsubsection{Common Usage}
One may wonder why given the event-driven nature of the Helm such
a scheme is needed. The architecture was implemented by extending
the model of Navigator and Helm pair to include a 'Guest
Scientist' --- a client application which, on the fly, makes
requests to the Captain (Helm) to alter course to accommodate the
needs of some scientific mission. However,\begin{quote}``The
Captain reserves the right to deny the request on the grounds that
it may jeopardize the safety of the vessel or contradict more
important mission orders.''\end{quote} This clause summarizes the
interacting priorities of existing tasks and the extent of dynamic
task generation the Helm is allowed to grant to third-parties.


\subsubsection{Granting Permissions}
The format of the permission specification in the Helm
configuration block is as follows.\newline
%
\code{Allow}={\it{jobname}}@{\it{clientname}}:{\it{tasktype}}
$\mid$ \code{SessionTimeOut}={\it{Timeout}}\newline
%
The fields have the following meaning:
\begin{description}
\item[Jobname]  Describes the kind of work that the application requesting
the launch of a task wants to do. It can be any name, for example,
it might be ``Explore'' or ``Detect Mine'' -- something that is
meaningful to humans.
%
\item[Clientname] is the name of the application making the request, for example,
\code{iAcousticModem}. It is the name that is used by the client
when communicating with the DB.
%
\item[Tasktype] is the string name of a task supported by the Helm
application. For example \code{XYPattern}.
%
\item[SessionTime] is the time the client has after
completion of a requested third-party task during which it can
request another task and be guaranteed that it will be accepted
(provided it has the relevant permissions). This is a subtle
point: imagine a client has requested the vehicle traverse to a
distant way-point; having got there we do not want  a competing
client to request some other destination before the first task has
had a chance to perform whatever it wanted to do at the
``distant'' way-point. Typically this value is set to a few
seconds.
\end{description}


\subsubsection{Request Generation}
A client can generate a third-party request by using the
\code{CThirdPartyRequest} class provided in \code{MOOSGenLib}. The
class's methods allow specification of the task type, job name.
For every line that one would usually see in a Task configuration
block one call to \code{CThirdPartyRequest::AddProperty()} is made
specifying the property name and value. This done, a call to the
\code{ExecuteTask} function returns a string that can be
transmitted via the \code{CMOOSCommClient} or through a call to
\code{MOOSApp::Notify()} under the name of
\code{THIRDPARTY\_REQUEST}. The string returned by the
\code{ExecuteTask} function simply packs all relevant information
in a string in a manner that is understood by the Helm.

\subsection{Dynamic Controllers}
We shall now discuss how each task maps navigation data and task
goals to desired actuation settings.

Each task possesses two standard PID controllers (Proportional
Integral Differential)-- one for yaw control and one for depth
control. All tasks that use navigation data as feedback for motion
control use one or both of these controllers. The yaw axis
controller is simple and is encapsulated in the class
\code{CScalarPID} found in \code{MOOSGenLib}. The output of the
controller is the tasks ``vote'' on \code{DESIRED\_RUDDER}.

\subsubsection{Scalar PID}
The scalar PID has the structure shown in figure
\ref{fig:ScalarPID}. It has integral limits to prevent integral
wind up and is also output limited to bound the output values.
Hence three gains and two limits specify the characteristics of
the controller.

\begin{figure}[ht!]
\label{fig:ScalarPID}
 \centering
\epsfig{figure = ScalarPID.eps,width = 0.8\linewidth} \caption{The
structure of the scalar PID}
\end{figure}

It is important to note that the controller does not require that
it be run a precisely regular time intervals. Instead it uses the
sequence of time stamps on the input navigation data to perform
the differentiation and integration as required. The
differentiation is performed using a 5-tap FIR filter. This leads
to smooth performance. However no phase advance is performed -- a
point that could be improved upon.

\subsubsection{Vertical Control via Pitch Control}
The control of motion in the vertical direction is only applicable
to the subsea case. Here we choose to control depth via pitch. The
overall controller is fourth order and consists of an inner scalar
PID loop controlling vehicle pitch. This loop maps error in pitch
to desired elevator.  The set point for the pitch loop is derived
from the error in the vertical direction \footnote{note altitude
control and depth control have sign inversion between them. Depth
is in the negative Z direction}. This topology is shown in figure
\ref{fig:ZPID}.

\begin{figure}[ht!]
\label{fig:ZPID} \centering \epsfig{figure = ZPID.eps,width =
\linewidth} \caption{The structure of Z axis dynamic controller}
\end{figure}


\subsubsection{Track-line Control}
The \code{TrackLine} task is an interesting case study of the use
of the dynamic controllers. It is derived from the \code{WayPoint}
task which uses yaw control to drive in a straight line to a goal
position. The \code{TrackLine} is more sophisticated in that it
draws the vehicle onto a line defined between  a start and goal
point and then heads for the goal point along the track-line
direction. Beneath the hood the task is continually changing the
goal coordinates of the underlying way-point task -- a ``carrot
and donkey'' approach. At each time step the goal coordinate is
set to be the projection of the vehicle location onto the
track-line plus some ``lead distance'' along it.

\subsubsection{The Independence Assumption}
Implicit in all this is that the dynamics  in the XY plane and Z
axis are decoupled. Clearly this assumption may be too strong for
some vehicles\footnote{Although two AUV's have been succesfully
controller using this strategy.}.In this case XY controlling tasks
will also need to place a vote on elevator as well as rudder
commands. This is no big problem, but they will need to be
extended to control in the vertical plane at the same time. In
other words such a vehicle will not be able to tolerate the
division of tasks into XY and vertical control types as is
currently the case.

\newpage
\section{Navigation -- \code{pNav}}
The pNav process is perhaps the most complex of all the MOOS
processes. Its job requirement is simple -- \begin{quote}
{\it{``taking asynchronous, anachronistic and inconsistent input
from sensors, provide a single , up-to-date estimate of vehicle
pose and velocity.''}}. \end{quote} The most important output of
\code{pNav} is the \code{NAV\_*} (said ``Nav Star'') family where
the wild card is any one of {\it{X, Y, Z, DEPTH, PITCH, ROLL, YAW,
SPEED, X\_VEL, Y\_VEL, Z\_VEL or YAW\_VEL}}. Note that velocities
are in earth coordinates not body coordinates. The \code{NAV\_*}
family should be taken to be the best estimate of vehicle state.
Indeed the Helm application uses this family to deduce actuation
commands.

\subsection{Priority Queues}
pNav allows the route by which \code{NAV\_*} information is
derived to be specified in it control block. This is achieved by
the use of Priority Queues or Stacks. The idea is simple -- each
\code{NAV\_*} output has its own line in the configuration block.
Reading from left to right specifies the preferences for deriving
state estimation. For example, it might be preferable to have an
AUV use pure GPS fixes for X,Y navigation when on the surface. In
this case the GPS\_X and GPS\_Y sensor outputs are mapped straight
through to NAV\_X and NAV\_Y and the first entry on the RHS of the ``X'' line
in the pNav configuration block would be ``GPS@TIMEOUT''. Here the
value of ``TIMEOUT'' would be the maximum time between GPS fixes
that could be tolerated before assuming the sensor has stopped
publishing valid data. For example if no GPS\_X data arrived for
TIMEOUT seconds then the GPS sensor would no longer be fed through
to NAV\_X and the navigator would shift attention to the next
``SOURCE@TIMEOUT'' pair in the priority queue. A likely second
entry would be \code{DVL}. When the vehicle dives GPS fixes will
cease and it may be desirable to dead-reckon using a DVL in its
place. In this case the second entry would be ``DVL@TIMEOUT''. As
soon as the vehicle surfaces and GPS fixes resume the stack/queue
would ``pop'' and NAV\_X would once more derive itself from GPS
data. Figure \ref{fig:PriorityQueues} gives an example definition
of navigation priority queues.
\begin{figure}\label{fig:PriorityQueues}
\begin{lstlisting}[]{}
//////////////////////////////////////
//   routing priority stack
//////////////////////////////////////
X      = GPS @ 2.0, EKF @ 2.5 ,LSQ @ 5.0,
Y      = GPS @ 2.0, EKF @2.0 ,LSQ @ 5.0,
Z      = EKF @ 2.0 ,LSQ @ 5.0,
Depth  = EKF @ 2.0 ,LSQ @ 5.0,DEPTH @ 1.0
Yaw    = EKF @ 2.0 ,LSQ @ 5.0, INS @ 1.0
Pitch  = INS Speed  = EKF
\end{lstlisting}
\caption{Specifying NAV\_* derivations. Here for example NAV\_X is
derived preferentially from GPS (ie straight from GPS\_X) unless
no GPS data is received for 2 seconds. In this case EKF\_X is used
in its place. If the EKF (extended Kalman filter) fails to produce
any output for 2.5 seconds then as a last resort LSQ\_X is used
(non-linear least squares). However as soon as GPS data begins to
be delivered once more the system switches back to using GPS
-- popping the stack.}
\end{figure}

Of course this scenario  assumes that the DVL sensor can produce
DVL\_X/Y measurements. It is more likely to produce reliable body
velocity measurements. Now we must ask how to derive
position estimates from sensors that do not measure positions? The
\code{pNav} process solves this problem by providing two kinds of real
time navigation filters: a ten state non-linear Kalman filter and
a five state non-linear Least Squares filter. Collectively these
filters provide the following functionality:
\begin{itemize}
\item Derivation of rate from position sensors
\item Derivation of pose and rate from LBL ranges
\item Optimal fusion of rate and position measurements
\item Estimation of tide-height
\item Automatic robust rejection of outliers
\item Self diagnostics
\end{itemize}
These navigation filters reside in the MOOSNavLib library, which is
linked with pNav. They are discussed in greater detail in section
\ref{sec:NavFilters}.

\subsection{Stochastic Navigation Filters}\label{sec:NavFilters}

\begin{figure}
\centering \epsfig{figure = NavFrames.eps, width = 0.8\linewidth}
\caption{The relationship between tide, Z and depth. The navigation
filters understand  LBL time of flights as a function of two
vehicle positions (to be estimated) and the beacons location
(known).}
\end{figure}

The navigation filters are moderately complicated software
components and require a good understanding of stochastic
estimation - the full extent of which is beyond the remit of this
paper.

There are two kinds of navigation filters used for online
navigation: a non-linear Kalman Filter (EKF) and a non-linear Least
Squares Filter (LSQ). \footnote{The Top down calibration filter within MOOS is
used for automatic calibration of an LBL net using GPS and
acoustic ranges and is not considered to be online. }

\begin{description}
\item [Least Squares Filter(LSQ)] The LSQ filter is a conventional
non-linear least squares filter using the Newton-Raphson iteration
scheme. It can only produce estimates of pose (no rate states) and
process measurements that are proportional to pose (no velocity
measurements). Internally measurements are accrued (up to a certain
time span) until the state space becomes observable, at which point
a solution is found iteratively by successive linearizations. The
accumulation of observations then begins again until the next
estimate can be formed. Heuristically speaking the LSQ filter
``starts from scratch'' after every published estimate and has no
concept of the flow of time across successive estimates. This
implies that it is not easy to use measurements of rate  in
deriving pose estimates. On the other hand, it does mean the LSQ
filter is robust and immune to errors in previous estimates.

\item[Extended Kalman Filter (EKF)] The EKF is the most complex of the two filters and also
is the most versatile and accurate. It fuses predictions derived
from a simple vehicle model with measurements supplied by sensors.
Internally it use a fine discretization of time to faithfully
interpret and model sensor measurements. The filter is recursive
and so, heuristically speaking, possesses a concept of time. This
enables it to produce estimates of velocity in addition  to pose using pose only measurements.
\end{description}

The filters are designed to be fully configurable in an intuitive
way from text in the \code{pNav} configuration block in the
mission file. A typical \code{pNav} block is given in the
Appendix. This section will use this listing as an example and
discuss the meanings and use of some important constructs within it.


\subsubsection{Defining Sensors}
The filter needs to know what sensors are in use and their
geometry with respect to the vehicle's coordinate frame -- this is
achieved with the \code{SENSOR\_*} keyword where ``*'' is any of
XY, LBL, ORIENTATION, DEPTH, BODY\_VEL or ALTITUDE. The general
syntax is as follows:
\begin{center}
\code{SENSOR\_*} = {\it{iSource}} $\rightarrow$ {\it{sensorname}}
@ {\it{x,y,z,[twist]}} ~ {\it{noise}}\\
\end{center} Anthropomorphically the syntax can be read as:
\begin{quote}
Declare a sensor of type (*) which is managed by a process called
{\it{iSource}}. Call it {\it{sensorname}} and understand it to be
located at the vector $(x,y,z)$ in body coordinates with a twist
of {\it{twist}} about the body $z$ axis (useful for compass
offsets). Expect the sensor to produce data corrupted by noise
with standard deviation {\it{noise}}.
\end{quote}

Note there is no limit on the number of sensors that can be used.
For example you can have two GPS sensors (XY). In fact on a large
vessel this will allow estimation of yaw without an orientation
sensor - for ``free''.

\subsubsection{Mobile and Static Vehicles}
The EKF allows the vehicle to be defined as static or mobile. A
mobile vehicle includes velocity (x,y,z and yaw) estimates in its
state estimate. A static vehicle has only pose estimates. The LSQ
filter implicitly uses a static vehicle model as it has no concept
of prior history and recalculates fixes from scratch whenever
possible.


\subsubsection{Defining Vehicle Dynamics}
The EKF uses a linear, constant velocity dynamic model for the
vehicle. It assumes that the vehicle will continue to move in a
straight line with constant velocity across time steps. There is
however a noise model associated with this model that dilutes the
precision of the state estimate over time (in the absence of data
from sensors). The degree to which this happens is governed by the
\code{EKF\_*\_DYNAMICS} variables, which vary from 0 to 10. A
setting of zero implies the vehicle is immutable in that direction
and never changes. For example, a planet sized vehicle might have a setting of
zero for its yaw dynamics. A setting of 10 implies that the
vehicle is very mobile in a given degree of freedom and in the
absence of observations from sensors over a few seconds we expect
to have a large uncertainty in our state estimate. Essentially
these numbers are parameterizing the expected error in our
state model. Heuristically a larger number means that we are not
so sure the vehicle always obey a constant velocity model.

Note that we do {\em not} inflict the constraint that the vehicle
translates along the direction it is pointing (although when
moving at speed this may be the case). Intentionally the vehicle
model does not couple angular and cartesian degrees of freedom. Of
course that is not to say that models explaining sensor data do
the same - in particular the use of DVL body velocity observations
correlates yaw and position estimates.


\subsubsection{Start Conditions}
The LSQ filter can be used to initialize the EKF. If however the
EKF is being run in stand-alone mode it needs an initial guess to
start up. The initial state guess is provided in the mission file
via the \code{EKF\_*} and the uncertainty (1 standard deviation
bound) by the \code{EKF\_SIGMA\_*} variables. If the vehicle is
type ``mobile'', velocity estimates are internally initialized to zero with
a suitable uncertainty.


\subsubsection{Logging}
The performance of the navigation filters can be logged to file
for post-mission analysis\footnote{The \code{MOOSMat} matlab
script is designed to do this graphically.}. The location and stem
name of these log files can be specified using the
\code{NAV\_LOG\_*} variables. If time stamping is required the
file name includes the creation time of the log in standard MOOS
format. Two kinds of files are created: {\it{*.olog}} and
{\it{*.xlog}}. The former logs all  observations presented to the
filter and the outcome of their processing  - rejection/acceptance
 etc. The latter logs the evolution of the state estimate
and its covariance. Both files are in text format and intended for
 simple quick parsing in Matlab.

\subsubsection{Data Rejection}

Both the EKF and the LSQ filters possess moderately  sophisticated
machinery, which allows them to discriminate between good and out
of bound (outliers) sensor data.

The LSQ filter builds a temporal history of sensor data and
applies some robust statistics tests to it to identify outliers.
The underlying assumption here is that sensor noise is high
frequency whereas the vehicle motion and hence reliable sensor
data are low frequency processes. The \code{CSensorChannel} class
tries to find the best (in terms of consensus) linear relationship
between recent sensor data points. This done, it is able to
identify outliers and remove them from the input stream feeding
into the filter. The  \code{LSQ\_REJECTION} entries specify
sensors (and acoustic channel for the case of LBL) which should be
piped through this process. Each such statement declares the
number of data points to be analyzed (the extent of the temporal
history) and tolerable/expected deviation of point from the fitted
line. For the case of LBL sensors this is a time measured in
seconds.

The EKF filter is a little smarter and uses its current state
estimate and uncertainty to identify that the current crop of
observations are not mutually consistent either with themselves or
with the last state estimate (a common technique in Kalman
filtering). However having detected that at least one of the
current sensor measurement makes no sense it employs geometric
projective techniques to identify the true outlier.

\subsubsection{EKF Lag}

The EKF can be told to run ``behind time''. That is, only process
sensor data up until $\eta$ seconds ago. Having done this the EKF
then forward predicts to the current time to produce an external
navigation estimate (which is used to make dynamic control
decisions). The next iteration will use the ``un-altered''
internal estimate as a prior (ie the $\eta$ second old one). One
might ask ``why bother?''. The reason stems from the fact that
sensors cannot (should not) be relied upon to produce up to date
measurements. Typically they are always out of date by the time
they are processed. Things are exacerbated in the case of LBL data
processing. Envision the case where an LBL transceiver ranges to
two beacons, one of which is close, say 150 m away, with a reply
delay of 0.1 seconds, and the other one is distant, say 1.5km away
with a reply delay of 1 second. The reply from the first beacon
will come in 0.3 seconds after the interrogation but the remaining
beacon's reply will not be heard for three seconds. Only when all
replies are in (or the receive window has timed out) will the time
of flight be transmitted by the sensor hardware. This means that
by the time the data is processed it is at least 3 seconds old.
Now, to properly ``explain'' these time measurements the filter
must use the state estimates of the vehicle valid at the
time-stamp of the data - in this case three seconds ago. Hence the
filter needs to run behind time by an amount specified by the
\code{EKF\_LAG} parameter. The filter buffers all sensor data in a
queue (which is self-sorting on time stamp) and extracts data from
it valid at the current time minus whatever the lag is set to.


\subsubsection{Fixed Observations}

It is possible to force a constraint on the navigation by
declaring persistent observations. Every time the filter ``ticks''
these artificial observations are added to a list observations
stemming from real sensors. This for example would allow a surface
craft with no depth sensor to use LBL navigation by declaring a zero depth artificial
observation. Another case is when a heading measuring device is
not available but a constant heading observation can be added to take
its place. (Recall that the vehicle model does not correlate
heading and position so with a constant heading observation the
vehicle will simply translate).

\subsubsection{LSQ/EKF Interaction}
If both the LSQ and EKF filters are run at the same time the LSQ
filter can be used to initialize and monitor the performance of
the EKF. The fact that although they have lower precision LSQ
estimates have no dependency on prior estimates can be exploited.
This can be advantageous for several reasons:

\begin{description}
\item [Robustness] A poorly tuned/setup EKF can diverge - that is, produce a
state estimate so far from the truth and with sufficient confidence
that it rejects all incoming sensor data. There is no reason that
this should happen given the data rejection schemes employed,
however navigation is stochastic and unlikely things will happen
given time. A deployed system should be robust to such occurrences
and the checking of estimates against the LSQ filter offers one (of
several employed) way to do this. If the estimates emerging from
the LSQ differ significantly from those emerging from the EKF over
a sustained interval \code{pNav} takes the EKF off-line and
attempts to re-initialize it to the LSQ estimates. We require a
lack of consensus over several seconds/fixes to prevent spurious
LSQ fixes pulling the plug on the EKF prematurely. This also
accords with the observation that once the EKF has diverged it is
unlikely to recover and so waiting a few seconds is not going to
change anything.

\item[Observability] The LSQ estimate essentially solves a
nonlinear set of equations to derive state observation data. No
state estimate can be derived until the system of equations is
observable - ie enough of the right kind of measurements have been
accrued. If no LSQ solution can be produced for an extended period
it provides {\it{prima-facie}} evidence that the navigation
problem is or has become( via sensor failure) unobservable and
unsolvable. Note that the EKF does not require full observability
to operate - unobservable states just become more uncertain with
each iteration\footnote{Until specified limits are reached at
which point the filter is taken off-line.}. The navigation control
block allows a LSQ timeout to be specified. If no LSQ fixes are
derived for a time exceeding this an navigation failure is
declared and all filters are taken off-line. This mechanism has two
applications. Firstly it prevents an autonomous mission from being
started on a vehicle that cannot be navigated. Secondly, it serves
to monitor sensor failure and prevent motion control decisions
being taken on the basis of at least partially ``predict only''
EKF navigation estimates.

\item[Automatic Initialization] The LSQ does not need a prior to
produce a state estimate. Hence it does not need to be primed with
an initial guess. Hence once a stable/repeatable stream of solutions
begins to flow from the LSQ filter they can be used to initialize
the EKF removing the need  for  approximate starting
conditions to be specified.

\end{description}

\subsubsection{Hidden State Estimation}

Both the EKF and the LSQ estimate the tide height - the distance
between the XY navigation plane and the surface. The EKF can
optionally also estimate a bias term in an orientation sensor (one
bias is applied to all orientation sensors). Great care has to be
taken in ensuring that this term is in fact observable given the
system configuration - heading bias estimation should only be
enabled when operating with a body velocity sensor {\em{and}} a
position sensor.


\subsubsection{Navigation Failure}
Limits can be placed on the permissible navigation uncertainty. If
the one sigma bound of the estimates exceed these limits a
{\it{Navigation Failure}} is declared. All relevant filters are
taken off-line and the \code{EndMission} variable is published.
This is the last line of defence against navigation failure - if
this happens things have gone badly wrong and the mission should
be terminated. The EKF also watches the numerical value of the
pose derivative states. If they exceed sensible limits (~10m/s or
$\pi rads^{-1}$) the states are reset to zero. This is essentially
a coordinate shift and so is statistically consistent although
somewhat alarming. Accordingly a warning is issued. This condition
is often experienced at boot time when a large velocity is
inferred to explain the apparent shift in position from initial
guess to that of the first EKF derived estimate.


\subsection{Sensible Configuration and Commissioning}
This section is intended as a brief guide to actually using the
navigation filters and owning process \code{pNav}. It is not exhaustive and
cannot replace experience and understanding in the underlying
techniques.

\subsubsection{Defining the Navigation Frame}
Different groups of people like to define coordinate origins in
different places. In particular the $Z=0$ plane. In an area with
little or no tidal flux the use of an artificial tide observation
(tide = 0) can be used to fix the $Z=0$ plane to the sea surface.
All beacon locations will need to have negative Z
coordinates\footnote{ However depth will still be positive as
depth =tide-Z.}.

\subsubsection{Heuristic Hints}
The following  are a selection of heuristic statements that are
helpful to keep in mind during commissioning and verifying the
navigation component of MOOS.

\begin{itemize}

\item If rate states are often being reset something is wrong.
Poor data is being accepted when it should not be.

\item LSQ filter cannot use velocity sensors (it has no idea of
history).

\item The LSQ filter cannot be used underwater without an LBL net
-- there are no sensors that measure a quantity proportional to
position.

\item Increasing vehicle dynamics settings will cause more
observations to be accepted but reduce resilience to bad sensor
data.

\item Decreasing vehicle dynamics will lead to smoother (piece-wise)
trajectories but may cause sensor data to be erroneously rejected
during swift manoeuvres.

\item Increasing estimated sensor precision (in the sensor
declaration)  will tend to cause more data to be accepted and
increase its effect on state estimates. Accepting bad data will
increase the chances of the  state vector being corrupted to the
degree that no data is ever accepted again.

\item Try to keep the \code{EKF\_LAG} setting as small as
possible. If set too small LBL data will not be used. If set too
large the final prediction step used to bring the estimate forward
to the current time will be inaccurate - bad news for dynamic
control.

\item The \code{EKF\_LAG} can be very small if no LBL sensing is
used.

\item Tide estimation can only be accomplished if both depth
sensors and LBL data is used (with beacons on the sea bed).

\item Tide estimation cannot be used using only altitude and LBL
measurements as such a scheme would require a model of the sea-bed
to explain the altitude data.

\item \textbf{Always} analyze the navigation logs before
performing a long mission with a new sensor configuration or LBL
array. Do not launch unless everything seems fine. There are
numerous safety features built in but it could be several minutes
before problems are detected and the navigator pulls the plug and
emits the navigation failure flag (which should be monitored by
the \code{EndMission} task).


\item If the EKF is being run by itself (ie not booted from the
LSQ) make sure that its start coordinates and uncertainties are
suitable to allow it to start accepting data when it starts up --
ie close enough to its true position!

\item It is a good plan to set the initial uncertainty in heading to
be large. Otherwise orientation data may not be accepted.


\end{itemize}

\newpage
\section{Scheduling Communications --- \code{pScheduler}}\label{Sec:pScheduler}

\code{pScheduler} is a simple tool for generating and responding
to messages send to the \code{MOOSDB} by processes in a MOOS
community. It supports three competencies which will now be
described. Example configuration blocks will also be given.


\begin{description}
\item[SEQUENCES] A looping sequence of messages can be created and published by \code{pScheduler}. Each element of a
sequence is specified in the configuration block  with a line:
\code{SEQUENCE = PUBLISH\_NAME @ VALUE : TIME\_OFFSET }. For
example the configuration in figure \ref{Fig:Sequences} would
write the variable \code{LIGHT\_CONTROL} to the DB every 2 seconds
with its String value alternating between "ON" and "OFF". The
total sequence period is given by the maximum \code{TIME\_OFFSET}
parameter. Figure \ref{Fig:SchedulerExt} shows a more complicated
configuration block in which a sequence is constructed from
several different variables.
\begin{figure}[ht]
\label{Fig:Sequences}
\begin{lstlisting}[]{}
ProcessConfig  = pScheduler
{
    SEQUENCE   = LIGHT_CONTROL @ ON : 2
    SEQUENCE   = LIGHT_CONTROL @ OFF : 4
}
\end{lstlisting}\caption{Configuring a sequence with \code{pScheduler}}
\end{figure}
\item[TIMERS] A ``timer'' allows a variable to be written to the
data base repetitively. A timer can be started and stopped by
publication (by some other application) of user specified
variables. The scheduler can also be told  to derive the  value of
the periodic variable from another MOOS variable, which, if
arrives in the Scheduler's mail box overrides the initial value.
This sounds complicated but isn't. An example is useful. The
general syntax is as follows\\
\code{TIMER = PUBLISH\_NAME @ TIME , START\_VARIABLE,
STOP\_VARIABLE,VALUE\_VARIABLE -> VALUE}\\
Figure \ref{Fig:TIMER} shows a typical configuration block.
\begin{figure}[ht]
\label{Fig:TIMER}
\begin{lstlisting}[]{}
ProcessConfig  = pScheduler {
    TIMER   = CAMERA_CONTROL @ 4.0 , MISSION_START,  MISSION_END,...
                  DESIRED_CAMERA_ANGLE -> 0.0
    TIMER = CAMERA_GRAB @ 4.0, MISSION_START -> GRAB
    TIMER = CAMERA_GRAB @ 4.0,  -> GRAB
}
\end{lstlisting}\caption{Configuring a timer with \code{pScheduler}}
\end{figure}
In this case the variable \code{CAMERA\_CONTROL} will be published
every 4 seconds after some third party application writes
(publishes) the \code{MISSION\_START} variable. If, while the
timer is active, the variable \code{CAMERA\_ANGLE} is published
the value of \code{CAMERA\_CONTROL} will be copied from that
message. If \code{CAMERA\_ANGLE} is never published it will always
have its default value of $0.0$. The timer turns off if any
process publishes \code{MISSION\_END}. The second example is
simpler and writes \code{CAMERA\_GRAB} with value "GRAB" every 4
seconds as soon as \code{MISSION\_START} is written. The third
version starts immediately (note the comma is required...). Figure
\ref{Fig:SchedulerExt} shows a few more examples of the
configuration of timers in  \code{pScheduler}.
\item[RESPONSES] The last competency is one of responding to the
publication of one variable with the publication of one or more
different variables. The syntax is obvious: \code{RESPONSE =
STIMULUS\_VARIABLE : RESPONSE\_VARIABLE @
VALUE,RESPONSE\_VARIABLE2 @ VALUE,....  }. Here
\code{STIMULUS\_VARIABLE} is the name of the variable we wish
\code{pScheduler} to respond to and after the colon comes a
command separated list of response variables with the values they
should contain. Figure \ref{Fig:SchedulerExt} shows some clear
example configurations of "responses" in \code{pScheduler}
\end{description}

\begin{figure}
\label{Fig:SchedulerExt}
\begin{lstlisting}[]{}
ProcessConfig = pScheduler
{
    //generate a sequence 6 seconds long ....
    // VAR1 will fire after 1 second
    // VAR2 fire after 3 seconds
    // VAR3 fire after 6 seconds
    // one second later VAR1 will fire again..repeat...
    SEQUENCE = VAR1 : RED @ 1 SEQUENCE = VAR2 : ORANGE @ 3 SEQUENCE =
    VAR3 : GREEN @ 6

    //generate a timer that writes "VAR_T1" with value "TimerData"
    TIMER = VAR_T1 @ 3.0, -> TimerData

    // generate a timer that writes "VAR_T2" with a string version
    // of the current value of DB_TIME (published by the DB) TIMER =
    VAR_T2 @ 2.0 ,,,DB_TIME -> TimerData

    // generate a timer that writes "VAR_T3" with the current
    // value of DB_TIME (published by the DB)
    // which only starts when "GO_T3" is published and stops
    // when "STOP_T3" is published
    TIMER = VAR_T3 @ 4.0,GO_T3,STOP_T3,DB_TIME -> TimerData

    //generate a response to "SURPRISE_ME". The variable "BOO"
    // takes on string value "HOO" and variable R9 has value
    //"get_a_grip"
    RESPONSE = SURPRISE_ME : BOO @ HOO, R9 @ get_a_grip

    //generate a response to "DB_TIME".
    RESPONSE = DB_TIME : ACKNOWLEDGMENT @ I_GOT_THE_TIME

}
\end{lstlisting}\caption{An extended \code{pScheduler} configuration block}
\end{figure}

\newpage

\section{Bridging Communities --- \code{pMOOSBridge}}\label{Sec:pMOOSBridge}

\code{pMOOSBridge} is a powerful tool in building MOOS derived
systems. It allows messages to pass between communities and is
able to rename the messages as they are shuffled between
communities. Many of the sections in this document rely on
\code{pMOOSBridge} to set up different communications topologies. There is no correct topology --- choose one that
works for your own needs.
\begin{figure}[ht]
\centering \epsfig{file = pMOOSBridge.eps , width = 0.6\linewidth}
\caption{A possible MOOSBridge
configuration.One instance of \code{pMOOSBridge} can ``talk'' to a limitless
number of communities. The configuration block specifies what
should be mapped or ``shared'' between communities and how it
should be done. The \code{SHARE} command specifies precisely what
variables should be shared between which communities.}\label{fig:MOOSBridge1}
\end{figure}
One instance of \code{pMOOSBridge} can ``talk'' to a limitless
number of communities. The configuration block specifies what
should be mapped or ``shared'' between communities and how it
should be done. The \code{SHARE} command specifies precisely what
variables should be shared between which communities and the
syntax is intuitive:\\

\code{SHARE= {\it{Comm@Host:Port[V1[,V2...]] $->$ Comm@Host:port
[V1,V2...]}}}\\

The triplet Comm@Host:Port is a description of a community ---  name and hostname/port pair. The community
description can be omitted on the l.h.s of the arrow in which case the mission-file-scope defaults are assumed (see the example below).
Each variable (``V'') on the l.h.s (source) community will be inserted into the community on the r.h.s.
If no variables names are specified on the r.h.s (destination) community the original names are used, otherwise
there is a one to one mapping between variable names on the l.h.s and new variable names (aliases) on the r.h.s. If however
there are more named shared variables than aliases, the variables for which a alias is not specified retain there original names.


For example\\
\begin{verbatim}
SHARE= VehA@nym.robots.ox.ac.uk:9000 [GPS_X]->VehB@kayak.mit.edu:9000 [GPS_X]
\end{verbatim}\\
Here the variable \code{GPS\_X} is shared between a community called ``VehA'' running from a \DB on the machine called
``nym.robots.ox.ac.uk' listening on port 9000 is being inserted into a community called ``VehB'' using a \DB running on the machine called
``VehB@kayak.mit.edu'' also listening on port 9000. In both communities the variable is called ``GPS\_X''. However when viewed with
something like \code{uMS} (see Section \ref{sec:MOOSScope} it can be seen that the \code{m\_sOrginatingCommunity} member of the \code{MOOSMsg}
carrying this data in the ``VehB'' commmunity will be ``VehA''.

\begin{verbatim}
SHARE= VehA@nym.robots.ox.ac.uk:9000 [GPS_X]->VehB@kayak.mit.edu:9000 [GPS_X_A]
\end{verbatim}
This is similar to the above example only \code{pMOOSBridge} will rename ``GPS\_X'' to ``GPS\_X\_A'' in the
destination community. The next example shows how the source address need not be specified. When omitted the source community is
taken to be the community on which \code{pMOOSBridge} is running at the time. This example also shows how destination variable names may be ommitted in
which case the original (source community) variable name is preserved.
\begin{verbatim}
SHARE= [GPS_X]->VehB@kayak.mit.edu:9000
\end{verbatim}
Finally more that one mapping can be specified in one line:
\begin{verbatim}
SHARE= [GPS_X,OVEN_TEMP]->VehB@kayak.mit.edu:9000 [GPS_X_A]
\end{verbatim}
here GPS\_X is being mapped and renamed to \code{GPS\_X\_A} in community ``VehB'' but the variable \code{OVEN\_TEMP} is simply being shared without renaming.
It is important to realise that sharing is not bidirectional. In this case a process notifying change in \code{GPS\_X\_A} in community ``VehB'' \emph{would not}
result in pMOOSBridge notifying the \DB in community ``VehA'' that ``GPS\_X'' has changed.


\begin{figure}[ht]
\centering \epsfig{file = pMOOSBridge2.eps , width =
0.6\linewidth} \caption{An alternative MOOSBridge Configuration
--- one bridge per community. This maybe preferable it is undesirable to have one process manage all
the sharing of data. However it offers no \emph{functional} advantage of the topology shown in Figure
\ref{fig:MOOSBridge1}.}\label{fig:MOOSBridge2}
\end{figure}



\newpage


\section{Manual Control - \code{iRemote}}\label{sec:iRemote}
%
\code{iRemote} was designed to be a control terminal for a
deployed vehicle. It is really nothing more than a long
\code{switch} statement based on characters input from the
keyboard. One of its many functions is to allow remote control of
the actuators of the vehicle. This is an invaluable asset for land
and sub-sea vehicles alike. The application is multithreaded. The
primary thread blocks on a read of keyboard input. When a
character is pressed some action is taken - for example publishing
a new value for \code{DESIREDTHRUST}. The fact that \code{iRemote}
can take control of a real vehicle presents a safety problem. What
if the human controller walks away or even worse the vehicle moves
out of communication range (eg a submarine dives) and the console
is not available? To prevent the last issued actuator command
being carried out {\it{ad-infinitum }} a secondary in thread
\code{iRemote} prompts the user to hit an acknowledge key (') at
least every 15 seconds. If the human driver does not respond the
all actuators are set to the zero position.\footnote{The actuation
driver  in iActuation will also shut down all motors if it does
not receive control commands for an extended period of time. In
the Bluefin vehicle the driver class within iActuation sends a
message to the Janitor processes which resets a watchdog on the
power management board - keeping the tail cone powered.}

\subsection{Summary of Functionality}
The following (not exhaustive) list describes some of the online
functionality that \code{iRemote} provides:

\begin{tabularx}{\linewidth}{l|c|X}
\textbf{Function} & \textbf{Key} & \textbf{Comment} \\ \hline

 Reload Mission File & \textsc{R} & Tells \code{pHelm} to
rebuild its
tasks \\
%
Restart Navigation & \textsc{V} & Tells \code{pNav} to reboot all
navigation filters
\\
%
Restart Logger  & \textsc{G} & Tells \code{pLogger} to begin
recording to a new set of log files \\
%
Begin Mission & \textsc{O} & Instructs \code{pHelm} to go online\\
%
Halt Mission & \textsc{O} or {\it{space}} & \code{pHelm} goes
offline and \code{iRemote} takes control immediately. \\
%
Navigation Summary & \textsc{*} & Prints a summary of salient
navigation information \\
%
Rudder Left/Right & \textsc{n},\textsc{m} & Steer control \\
%
Elevator Up/Down & \textsc{p},\textsc{l} & Pitch control \\
%
Thrust Up/Down & \textsc{a},\textsc{z} & Throttle control (+ shift
gives 100 percent) \\
%
Stop        & {\it{space}} & Immediate zero of all degrees of
freedom \\
%
Fetch DB       & \textsc{F} & Prints a summary of the contents of the entire \DB \\
%
CustomKey & $[0 \rightarrow 9]$ & The numeric keys can be made
(via \code{iRemote}s configuration block) to publish any named
variable with a specified value. In the example configuration
block below (Figure \ref{fig:iRemoteBlock}), pressing  key ``2''
will cause \code{iRemote} to write the variable
\code{JANITOR\_SWITCH} with the string value (quotes)
ACTUATION::OFF \\
%
CustomSummary & \textsc{+} & The configuration block allows a
custom summary to be built consisting of any variable names used
within the system. \code{iRemote} subscribes to this data and
prints its current value when requested.\\
%
{\New{CustomJournal}} & $[0 \rightarrow 9]$ & Similar to
{\it{CustomSummary}} but instead of keeping the most recently
published variable it keeps a history of values. Each Journal can
be  bound to a numeric key. In the example below pressing key
``6'' will show the past 10 values of \code{DESIRED\_RUDDER} with
every delta captured as the
capture time is 0.\\
\end{tabularx}

\begin{figure}[h]
\begin{lstlisting}[ ]{}
///////////////////////////////////////////////
// iRemote config block
ProcessConfig = iRemote
{
    CustomJournal = Name = DESIRED_RUDDER,Key =6, History = 10,Period = 0
    CustomSummary = DESIRED_THRUST
    CustomKey = 2 : JANITOR_SWITCH @ "ACTUATION:OFF"
}
\end{lstlisting}
\caption{A small configuration block for iRemote showing typical
usage of the \code{CustomX} commands}\label{fig:iRemoteBlock}
\end{figure}


\subsection{Informing the Pilot}
In most missions \code{iRemote} is the only interface the vehicle
pilot has with the vehicle. Clearly then a method is needed by
which {\em{important}} information can be sent to the
\code{iRemote} console from any process. The \code{CMOOSApp}
member function \code{MOOSDebugWrite} achieves this by issuing a
notification on a variable watched by \code{iRemote}. Such
messages are displayed on the iRemote console at run time along
with the process making the announcement. Note that this  name is
somewhat unfortunate as this function should not be used for
debugging - it is a run-time thing. It is frustrating to have a
cornucopia of messages flashing on the screen during a mission the
content of which is meaningless to the pilot. Typical uses of this
functionality would be a very occasional summary of navigation
status and system level warning messages - for example
notification of unexpected mission task  termination.

%

\section{Logging - \code{pLogger}}
The \code{pLogger} process is intended to record the activities of
a MOOS session. It can be configured to record a fraction of or
every publication of any number of MOOS variables. It is an
essential MOOS tool and is worth its weight in gold in terms of
post-mission analysis, data gathering and post-mission replay.

The configuration of \code{pLogger} is trivial and consists of
multiple lines with the following syntax:
\begin{center}
\code{Log} =  {\it{varname}} @ {\it{period}} $[NOSYNC]$
\end{center}
where {\it{varname}} is any MOOS variable name and {\it{period}}
is the minimum interval between log entries that will be recorded
for the given variable. For example if
{\it{varname}}=\code{INS\_YAW} and {\it{period}} = 0.2 then even
if the variable is published at 20Hz it will only be recorded at
5Hz. The optional \code{NOSYNC} flag indicates that this variable
should not be recorded in the synchronous logs (see section
\ref{sec:LogTypes})

\subsection{Log File Types}\label{sec:LogTypes}
The logger records data in two file formats - synchronous
(``slog'' extensions) and asynchronous (``alog'' extensions). Both
formats are ASCII text -- they can always be compressed later and
usability is more important than disk space. The two formats are
now discussed.

\subsubsection{Synchronous Log Files}
Synchronous logging makes a table of {\em{numerical}} data. Each
line in the file corresponds to a single time interval. Each
column of the table represents the broad evolution of a given
variable over time. The time between lines (and whether
synchronous logging is even required) is specified with the line
\begin{center}
\code{SyncLog}= {\it{true/false @ period}}
\end{center}
where {\it{period}} is the interval time.

If there has been no change in the numeric variable between
successive time steps then its value is written as \code{NaN}. It
is important to note that synchronous logs do not capture all that
happens - they sample it. Synchronous logs are designed to be used
to swiftly appraise the behaviour of a MOOS community by examining
numeric data in a tool such as Matlab or a spreadsheet. The
\code{MOOSData} Matlab script reads in these files and with a
single mouse click can display the time evolution of any logged
variable.


\subsubsection{Asynchronous Log Files}
Asynchronous logging is thorough. The mechanism is designed to be
able to record {\em{every}} delta to the MOOSDB. The use of the
period variable allows the mission designer to back off from this
ultimate limit and record variables at a maximum frequency. The
key properties of asynchronous can be enumerated as follows:
\begin{enumerate}
\item Records both string and numeric data
\item Records data in a list format - one notification per line
\item Entries only made when variable is written
\end{enumerate}
Asynchronous log files are designed to be used with a playback
tool (for example \code{uPlayback} or other purpose-built
executable). Although the handling of strings and numeric data
adds a slight overhead to such a program's complexity the utility
gain from being able to slow, stop and accelerate time during a
post-mission replay/reprocessing session is simply massive.


\subsubsection{Mission Backup}
Simply having the {\it{alog}} and {\it{slog}} files is not enough
to evaluate the mission. One also needs the things that
{\em{caused}} the data to be recorded, namely the *.moos Mission
file and the *.hoof file (if Task redirection was used). To this
end the \code{pLogger} process takes a copy of these files and
places them (name appended with a time stamp if desired) within
the logging directory. The files extensions are renamed to
{\it{*.\_moos}} and {\it{*.\_hoof}} respectively.



\section{Startup - \code{pAntler}}
The process \code{pAntler} is used to launch/create a MOOS
community. It is very simple and very useful. It reads from its
configuration block a list of process names that will constitute
the MOOS community. Each process to be launched is specfied with a
line with the syntax
\begin{center}
{\code{Run}} = {\it{procname}} [ @ {\code{NewConsole}} =
{\it{true/false}}] [$\sim$ \code{MOOSName}]
\end{center}
The optional console parameter specifies whether the named process
should be launched in a new  window (an xterm in Unix or
cmd-prompt in NT derived platforms). Each process launched is
passed the mission file name  as a command line argument. When the
processes have been launched \code{pAntler} waits for all of the
community to exit and then quits itself.

\subsubsection{Running Multiple Instances of a Process}

The optional \code{MOOSName} parameter allows MOOSProcesses to
connect to the \DB under a specified name. For example a vehicle
may have two GPS instruments onboard. Now by default \code{iGPS}
may register it existence with the \DB under the name ``iGPS''. By
using this syntax multiple instances of the executable \code{iGPS}
can be run but each connects to a the \DB using a different name.

\begin{center}
\code{Run = iGPS @ NewConsole = true $\sim$ iGPSA}\\
\code{Run = iGPS @ NewConsole = true $\sim$ iGPSB}\\
\end{center}

would launch two instances of \code{iGPS} registering under
``iGPSA'' and ``iGPSB'' respectively. Note there would need to be
\emph{two} GPS configuration blocks in the mission file -- one for
each and the processnames would be ``iGPSA'' and ``iGPSB''


\subsection{Usage}
\code{pAntler} provides a simple and compact way to start a MOOS
session. For example if the desired mission file is
{\it{Mission.moos}} then executing
\begin{center}
\code{pAntler Mission.moos}
\end{center}
will launch the required processes for the  mission. Of course a
sensibly designed mission will not actually start to do anything
until a human (via \code{iRemote}) has confirmed a good working
status of the processes involved (eg \code{pNav}) and actively
hands control over to the Helm.

\subsubsection{I/O Redirection - Deployment} As already mentioned,
frequently \code{iRemote}, displayed on a remote machine, will be
the only interface a mission pilot has to the MOOS community.  We
must ask the question -  ``where does all the IO from other
processes go to prevent I/O blocking?''. One answer to this is I/O
redirection and backgrounding MOOS processes - a simple task in
unix derived systems \footnote{some OS are good for development
others for running...}/

Running \code{pAntler} in the following fashion followed by a
manual start up of \code{iRemote} is the recommended way of
running MOOS in the field using a serial port login.

\begin{enumerate}
\item \code{pAntler} {\it{mission.moos}} $>$ ptyZ0 $>$ /dev/null \&
\item \code{iRemote} {\it{mission.moos}}
\end{enumerate}

This redirection of \code{iRemote} is encapsulated in the
\code{moosbg} script included with the MOOS installations. In the
case of an AUV the interface can only be reached  through in-air
wireless communications, which will clearly disappear when the
vehicle submerges but will gracefully re-connect when surfacing(
not so easy to do with a PPP or similar link).

\newpage
\part{Utilities}

\section{MOOS meets Matlab ---\code{iMatlab}}

Not everyone want to program in C++. Many folks are happy using
matlab as their research tool. Whilst not advising the use of
matlab to control a real vehicle, it seemed a useful to build an
application that allows matlab to join a MOOS community - if only
for listening in and rendering sensor data. The project
\code{iMatlab} allows that to happen. In essence it ``mex''s up
some central MOOS code so it can be called from inside matlab. The
\code{CMake} build system supported by current releases of MOOS
will build the project for Linux or Windows version of matlab.


\subsection{Configuration}

\code{iMatlab} allows Matlab programmers to access some of the
benefits of MOOS. It allows connection to the MOOSDB and access to
local serial ports. Configuration for the most part is done via a
*.moos file which is either the default iMatlab.moos found locally
or at a location specified at initialisation. Figure
\ref{fig:iMatlab} shows a typical configuration block for
\code{iMatlab}.

\begin{figure}[h]
\begin{lstlisting}[ ]{}
    ProcessConfig = iMatlab
    {
        AppTick     = 10
        CommsTick   = 10
        Port        = COM6
        BaudRate    = 4800
        Verbose     = false
        Streaming   = false
        MOOSComms = true
        SerialComms = false
        SERIAL_TIMEOUT = 10.0
        SUBSCRIBE = DB_TIME @ 0.0
    }
\end{lstlisting}
\caption{A typical configuration block for \code{iMatlab}
}\label{fig:iMatlab}
\end{figure}

Most of the fields are understandable by reading the MOOS
documentation. The application specific fields are:
\begin{description}
\item [MOOSComms]: ``true'' or ``false'' - do you want to connect to a
community?
%
\item [SerialComms]: ``true'' or ``false''  - do you want to use serial
ports ?
%
\item [SUBSCRIBE]: {\it{VariableName @ Period}} - one entry for each
variable you want to subscribe to and the maximum update rate you
are interested in . You can have many SUBSCRIBE lines.
\end{description}

Importantly always call \code{iMatlab('init')} first --- an error
message is printed if you forget. By default iMatlab looks to read
configuration data from iMatlab.moos. Alternatively you can use
\code{iMatlab('init','CONFIG\_FILE','XYZ.moos')} to read from the
file ``XYZ.moos''  You can specify a process name other than the
default ``iMatlab'' by passing the \code{MOOSName} parameter at
initialisation:
\code{iMatlab('init','MOOSNAME','MyName',.......)}.



\subsection{Usage}

If \code{MOOSComms} is ``true''  in the configuration file  then
MOOS Comms functionality is enabled.

\subsubsection{Publishing}
To send data use the following syntax
\code{iMatlab(\'MOOS\_MAIL\_TX\',VARNAME,VARVAL)} e.g
\newline \code{iMatlab('MOOS\_MAIL\_TX','A\_DATA\_VALUE',10)}
or\\
\code{iMatlab('MOOS\_MAIL\_TX','MY\_NAME','PMN')}\\

\subsubsection{Receiving Notifications}

To receive data use the syntax \code{ D =
iMatlab('MOOS\_MAIL\_RX')}.    This will return a structure array
describing the data that has arrived  (because of a subscription)
since the last call \code{'MOOS\_MAIL\_RX'} call . Each element of
$D$ will be a structure with the following fields given in Table
\ref{Tab:iMatlabMail}.

\begin{table}[h!]
\centering
\begin{tabularx}{\linewidth}{p{2.5in}|p{1in}|X}
\textbf{Field} &  \textbf{type} &\textbf{Description}\\
\hline
KEY                    & string & the name of the variable\\
TYPE                   & string & the type of the variable
('DBL'/'STR')\\
TIME                    &double & the time the data was valid\\
STR                    & string & the string value of the data if TYPE=='STR'\\
DBL                     &double & the double value of the data if TYPE=='DBL'\\
SRC                    & string & the name of the process that issued the data\\
ORIGINATING\_COMMUNITY &  string & the name of the community which
SRC belongs to\\\hline
\end{tabularx}
\label{Tab:iMatlabMail} \caption{The contents of a MOOS mail
structure in iMatlab} \normalsize
\end{table}




\subsubsection{Registering for Notifications}

This is done either through the configuration file using
\code{SUBSCRIBE=...} or by calling
\code{iMatlab('MOOS\_REGISTER',VarName,MinTime)} For example
calling \code{iMatlab('MOOS\_REGISTER','DESIRED\_RUDDER',0.0)}
will subscribe to \emph{every} change in \code{'DESIRED\_RUDDER'}
while calling
\code{iMatlab('MOOS\_REGISTER','DESIRED\_RUDDER',0.2)} will
subscribe in a way that means we'll only be told about changes in
'DESIRED\_RUDDER' every 0.2 seconds.


\subsection{Serial Ports}

If "SerialComms = true"  in the configuration file then serial
port functionality is enabled.

\subsubsection{Sending Data}

Call \code{iMatlab('SERIAL\_TX',Data)} where \code{Data} is a
string or a vector of type uint8.

\subsubsection{Reading Data}

To receive data on a serial port call \code{ D =
iMatlab('SERIAL\_RX',Data)}.If "Streaming=false" in the
configuration file then the function will block until a timeout
occurs or a telegram is received (ASCII, carriage return
terminated only in the release). If  \code{"Streaming  = true"}
the function returns immediately with a structure array containing
all the telegrams received since the last call. Each element of
$D$ is a structure described by Table \ref{Tab:iMatlabSerial}.


\begin{table}[h!]
\centering
\begin{tabularx}{\linewidth}{p{2.5in}|X}
\textbf{Field} &  \textbf{Description}\\\hline
            STR   & the data Rx'd\\
            TIME  & the time it was received\\
\hline
\end{tabularx}
\label{Tab:iMatlabSerial} \caption{The contents of the data
structure pertaining to received serial data in \code{iMatlab}}
\normalsize
\end{table}



\subsection{Other Functionality}

\subsubsection{Pausing}
Calling \code{ iMatlab('MOOS\_PAUSE',T)}  suspends the calling
thread (matlab itself in this case) for T seconds. This is pretty
useful for a non-busy wait in contrast to the CPU loading when
calling Matlab's own \code{pause} function.



\section{Replay -- \code{uPB}}
There is a FLTK-based, cross platform GUI application that can
load in {\it{alog}} files and replay them into a MOOS community as
though the originators of the data were really running and issuing
notifications. A typical use of this application is to ``fake''
the presence of sensor processes when reprocessing sensor data and
tuning navigation filters. Alternatively it can be used in pure
replay mode perhaps to render a movie of the recorded mission. The
GUI allows the selection of which processes are ``faked''. Only
data recorded from those applications will be replayed from the
log files.  There is a single class that encapsulates all the
replay functionality - \code{CMOOSPlayback}. The GUI simply hooks
into the methods exported by this class. The GUI is almost self
documenting - start it up and hold the mouse over various buttons.

\begin{figure}
\center \epsfig{file=uPB.eps,width = 0.5\linewidth} \caption{A
screen shot of \code{uPB} - a cross platform ``alog'' playback
tool}
\end{figure}

A client process can control the replay of MOOS messages by
writing to the \code{PLAYBACK\_CHOKE} variable add writing a valid
time in the numeric message field. The Playback executable will
not play more than a few seconds past this value before waiting
for a new value to be written. In this way  it is possible to
debug (halt inspect and compile-in-place etc) at source level a
client application using replayed data without having the playback
rush on ahead during periods of thought or code-stepping.


\section{Visual Debugging - \code{uMS}}\label{sec:MOOSScope}
The \code{uMS} is another GUI application. It allows a user to
place a stethoscope on the MOOS network and watch what variables
are being written, which processes are writing them and how often
this is happening. After starting up the scope and specifying the
host name and port number of the \DB the user is presented with a
list of all MOOS variable in the server and their current state.
Several times a second \code{uMS} calls into the DB and uses a
special/unusual (and intentionally undocumented) message that
requests that the server inform the client about {\em{all}}
variables currently stored along with their update statistics.
\code{uMS} is a central tool in the MOOS suite. It is cross
platform and should be used to spy on and present visual feedback
on any MOOS community.

\begin{figure}
\center \epsfig{file=uMS.eps,width = 0.9\linewidth} \caption{A
screen shot of \code{uMS} - a cross platform, multi-community
viewer.}
\end{figure}

\subsection{Improvements over \code{MOOSScope}}
\New{Improvement} \code{uMS} replaces the old , win32 only,
\code{MOOSScope}. As well as being cross platform It offers new
functionality:

\begin{itemize}
    \item Support for multiple communities via tabbed GUI.
    \item Memory of last settings (persistence)
    \item String expansion (click on long data strings and ballon
    appears.
    \item Show hide unassigned variables
    \item Show hide messages from specific processes
    (shift-leftclick on the process list)
    \item Poke the moos via ctrl-leftclick on a variable or empty
    cell.
\end{itemize}

\subsection{Poking the MOOS}
\code{uMS} has one other valuable use : poking the MOOS. It allows
a user to double click on a variable name and alter its value
(string or double) interactively. This is akin to changing memory
contents in a source code debugging session. The difference here
is that this action is a notification and all clients that are
registered for it receive a message in their mail box and act on
it accordingly. The utility of this functionality should not be
underestimated. For example, during the commissioning of a new
sensor (say a DVL) it may be unclear what the best configuration
parameters are. For example by having the managing process
subscribe for notifications on a \code{PARAMETERS} variable the
\code{uMS} can be used to rapidly explore the
performance/parameter space by simply poking new configuration
describing strings into the \code{PARAMETERS} variable.


\newpage
\section{Simulation --- \code{uMVS}}

\subsection{Simulation Mode}\label{Sec:SimMode}

There is is mission-file-scope variable \code{Simulator}. For
normal operation (i.e deployment of a real vehicle this will be
set to be true). However setting it to \code{false} enters MOOS
into a different mode - one of simulation.

The idea is that to gain confidence in new code its a good plan to
be able to do dry runs of all the code that will be expected to
govern the in-life operation of the vehicle. The Simulator flag in
conjunction with the behaviour of the instrument applications can
achieve this.

Setting the \code{simulator} flag to true causes the iProcesses
(instruments) to subscribe to one or more \code{SIM\_*} variables
like \code{SIM\_X},\code{SIM\_Y},\code{SIM\_DEPTH}. These
variables are published by a vehicle simulator (see Section
\ref{sec:uMVS}) and encapsulate the state of simulated vehicle.
The instruments then simulate their output using these values.

So to summarise : running in simulation mode means all the
instruments, navigation, Helm applications behave as normal,
passing and feeding off the same variables between each other.
However at the lowest level the instrument classes are not talking
to hardware via their serial ports etc but are subscribing to data
from a simulated world which they use to generate their
measurements.

For example iGPS normally talks to a GPS sensor via a serial port
and outputs \code{GPS\_X} etc. In simulation mode it also
subscribes to \code{SIM\_X} and \code{SIM\_Y} which it converts
internally (very simply, it turns out, by using the CMOOSVariable
class) into \code{GPS\_X}.


\begin{figure}[ht]
\centering \epsfig{file = SimulationMode.eps , width =
0.8\linewidth} \caption{The variable subscription/publication
occurring  in simulation mode }\label{fig:SimulationMode}
\end{figure}

The final part of the story lies with \code{iActuation} - when in
simulation this process subscribes as usual to
\code{DESIRED\_RUDDER} etc but instead of sending bytes via a
serial port to a lump of hardware, it ``re-packages'' the commands
and bounces them back to the \DB as \code{SIM\_DESIRED\_RUDDER}
etc. It is these \code{SIM\_}-prefixed control  variables that are
subscribed to by the simulator and used to control the simulated
vehicle. This scenario is illustrated in Figure
\ref{fig:SimulationMode}. This shows how messages are bounced
around in the simulation mode - notice the additional \code{SIM\_}
prefixed subscriptions and publications made by \code{iGPS} and
\code{iActuation} respectively.

The details of the simulator is described in Section
\ref{sec:uMVS}.

\subsection{AUV and Acoustic Simulation  - \code{uMVS}}\label{sec:uMVS}
\code{uMVS} is a multi-vehicle AUV simulator. It is capable of
simulating any number of vehicles and acoustic ranging between
them and acoustic transponders. The vehicle simulation
incorporates a full 6D.O.F vehicle model replete with vehicle
dynamics, center of buoyancy/ center of gravity geometry, and
velocity dependent drag.

The acoustic simulation is also fairly smart. It simulates
acoustic packets propagating as spherical shells through the water
column. When they intersect with acoustic devices (either on
beacons or vehicles) the true time of intersection is calculated
by a refinement process. This design allows the real round trip to
be calculated when the vehicle is undertakes a trajectory that was
not known at the time the initial ``ping'' was launched.

A typical configuration block is given in \ref{fig:uMVSBlock}. The
syntax is simple --- consider the \code{ADD\_AUV} line in figure
\ref{fig:uMVSBlock}. The initial pose of the vehicle is specified
as an <X,Y,Z,Yaw> tuple. The AUV can also be named. The
\code{InputPrefix} and \code{OutputPrefix} terms are interesting.
They allow configuration of the names of the variables which are
used to control the actuators of the simulated vehicle and the
names of the variables used to describe the state of the vehicle.
As in reality, each vehicle is controlled by three actuator
settings : rudder,elevator and thrust. On a real vehicle these are
typically carried by the variables
\code{DESIRED\_THRUST},\code{DESIRED\_ELEVATOR} and
\code{DESIRED\_RUDDER}. Now say a particular simulated vehicle had
\code{InputPrefix = SIM\_}, \code{uMVS} would then subscribe to
\code{SIM\_DESIRED\_THRUST},\code{SIM\_DESIRED\_ELEVATOR} and
\code{SIM\_DESIRED\_RUDDER} and use these values as the control
parameters for the vehicle. Why might one like to do this? Well
see section \ref{Sec:SimMode}. An alternative use of the prefixes
is discussed in Section \ref{Sec:SimMinimal}.

\begin{figure}[h]
\begin{lstlisting}[ ]{}
ProcessConfig = uMVS
{
    //add an AUV, starting at Pose (X,Y,Z,Yaw), called AUV1.
    ADD_AUV=  pose=[4x1]{7,3,55,0},name = AUV1,InputPrefix=SIM_,OutputPrefix=SIM_
    ADD_TRANSPONDER=  name = B1, pose=[3x1]{0,0,0},Rx = CIF, Tx = Ch7,TAT = 0.125

    TideHeight = 60

    //a few variables for the simulator..
    LogFile = SimLog.txt
    InstantLogAcoustics = false

    //what is standard deviation of noise on
    //TOF measurements? 1ms = 1.5 meters
    TOFNoise = 0.00066
}

\end{lstlisting}
\caption{A small configuration block for \code{uMVS} showing a
typical configuration. This would be suitable for use with the
topology shown in Figure \ref{fig:SimulationMode}.
}\label{fig:uMVSBlock}
\end{figure}


\begin{figure}[h]
\begin{lstlisting}[ ]{}
ProcessConfig = uMVS
{
    ....
    ADD_AUV=  pose=[4x1]{7,3,55,0},name = AUV1,InputPrefix=,OutputPrefix=NAV_
    ....
}

\end{lstlisting}
\caption{Configuring the simulator to work for the scenario shown
in Figure \ref{fig:SimpleSim}. }\label{fig:SimpleuMVSBlock}
\end{figure}



\subsubsection{A more minimal simulation}\label{Sec:SimMinimal}

The ability to define the \code{InputPrefix} and
\code{OutputPrefix} terms for \code{uMVS} allows a more minimal
simulation to be constructed without using the global
\code{Simulation} flag discussed in Section \ref{Sec:SimMode}.
Infact one can eschew the need to use the instruments and
\code{iActuation} altogether. Why would anyone want to do this?
Well, the ``simulation mode'' of section \ref{Sec:SimMode} is
invaluable for gaining overall system/architecture confidence
however it can be inconvenient at times. For example if working on
the Helm or action planning process it may be inconvenient  to
have to launch the instrument processes and the Navigator at every
frequently during development. Figure \ref{fig:SimpleSim} shows an
alternative use of the simulator for exactly this case.  The
important configuration line (compared to \ref{fig:uMVSBlock}) is
shown in figure \ref{fig:SimpleuMVSBlock}. Note how the simulator
is told to publish \code{NAV\_*} data and subscribed to
\code{DESIRED\_THRUST},\code{DESIRED\_ELEVATOR},\code{DESIRED\_RUDDER}
by having an empty input prefix and \code{NAV\_} as an output
prefix. A typical topology using this set up is shown in Figure
\ref{fig:SimpleSim}.

\begin{figure}[ht]
\centering \epsfig{file = SimulationMode2.eps , width =
0.8\linewidth} \caption{A minimal simulation configuration for
example, Helm development. Here \code{uMVS} publishes vehicle
state as \code{NAV\_*} data and controls the internal simulated
vehicle by direct subscription to the standard Helm outputs.
}\label{fig:SimpleSim}
\end{figure}

\subsubsection{Logging}

\code{uMVS} can be configured (via the  \code{ LogFile} parameter)
to write a log file of the the simulation. This is a self
documenting file that records vehicle state and acoustic ranges
for perusal out of the MOOS environment.


\subsection{Multi-vehicle Simulation Scenarios}

So far we have considered the case of simulating a single vehicle
community (one community per vehicle). In the case there is one
mission file for the community, the simulator variable is set to
true and all process as run as though this were a real deployment
but behind the scenes the simulator is talking to the instruments
to fake reality. This was described in section \ref{Sec:SimMode}.

However what if it was desired to simulate (ie prepare for) and
experiment with multiple interacting vehicles, i.e lots of
communities how would this work? Several options are available to
the user here and they all involve the use of \code{pMOOSBridge}
which was described in section \ref{Sec:pMOOSBridge}.

One option is to run one simulator for each vehicle (each
simulator only running one vehicle) and use \code{pMOOSBridge} to
bridge whatever variables that need to be shared between
communities (it will most likely need to rename the variables
aswell). For example, consider Figure \ref{fig:MultiSim1}. Here a
possible two-vehicle simulation topology is shown. It is created
simply by linking two communities each with their own private
\code{uMVS} (here each in full simulation mode as described in
Section \ref{Sec:SimMode} but they could of course be in a reduced
form as described in Section \ref{Sec:SimMinimal}) with an
instance of \code{pMOOSBridge} described in Section
\ref{Sec:pMOOSBridge}.

\begin{figure}[ht]
\centering \epsfig{file = SimBridge0.eps , width = 0.8\linewidth}
\caption{A possible two-vehicle simulation created simply by
linking two communities each with a private \code{uMVS}(here each
in full simulation mode as described in Section \ref{Sec:SimMode}
but they could of course be in a reduced form as described in
Section \ref{Sec:SimMinimal}) with an instance of
\code{pMOOSBridge}.
 }\label{fig:MultiSim1}
\end{figure}


An alternative  approach would be to use the multi-vehicle
simulation capabilities of \code{uMVS} and adopt a topology
similar to Figure \ref{fig:MultiSim2}. Here each community has its
vehicle simulated in a common instance of \code{uMVS} which would
allow acoustic ranging between vehicles. Figure
\ref{fig:2AUVBlock} shows the possible configuration block for
\code{uMVS} in this scenario. Each vehicle community in Figure
\ref{fig:MultiSim2} runs its own instance of \code{pMOOSBridge} to
do the relevant data renaming between the ``simulating community''
and the rest of its own community. For example, with reference to
the configuration snippet in Figure \ref{fig:2AUVBlock} and the
topology of Figure \ref{fig:MultiSim2}, the bridge in ``Community
A'' would have to import \code{AUV\_A\_X} from the simulation
community and map it to \code{SIM\_X} while also export
\code{SIM\_DESIRED\_THRUST} as \code{AUV\_A\_DESIRED\_THRUST}
\footnote{And similarly for other relevant variables}.

\begin{figure}[ht]
\centering \epsfig{file = SimBridge.eps , width = 0.8\linewidth}
\caption{A possible two-vehicle simulation created simply by
linking two communities to a single ``simulation community'' via
private instances of \code{pMOOSBridge}. There is only one
\code{uMVS} running.
 }\label{fig:MultiSim2}
\end{figure}

\begin{figure}[h]
\begin{lstlisting}[ ]{}
ProcessConfig = uMVS {
    ....
    ADD_AUV=  pose=[4x1]{7,3,55,0},name = VehA,InputPrefix=AUV_A_,OutputPrefix=AUV_A_
    ADD_AUV=  pose=[4x1]{7,3,55,0},name = VehB,InputPrefix=AUV_A_,OutputPrefix=AUV_B_
    ....
}
\end{lstlisting}
\caption{Configuring the simulator to work for the scenario shown
in Figure \ref{fig:MultiSim2} with two vehicles. Note the values
of the input and output prefixes and the message renaming role
each \code{pMOOSBridge} has in Figure \ref{fig:MultiSim2} because
of them }\label{fig:2AUVBlock}
\end{figure}



\begin{figure}[ht]
\centering \epsfig{file = SimBridge2.eps , width = 0.8\linewidth}
\caption{A possible two-vehicle simulation created simply by
linking two communities to a single ``simulation community'' via a
{\emph{single}} instance of \code{pMOOSBridge}. Again, there is
only one \code{uMVS} running.
 }\label{fig:MultiSim3}
 \end{figure}

\begin{figure}[ht]
\centering \epsfig{file = SimBridge3.eps , width = 0.8\linewidth}
\caption{Similar to \ref{fig:MultiSim3} where a two-vehicle
simulation is created simply by linking two communities to a
single ``simulation community'' via a {\emph{single}} instance of
\code{pMOOSBridge}. Again, there is only one \code{uMVS} running.
The difference between this topology and that shown in Figure
\ref{fig:MultiSim3} is the individual vehicle comunities are
{\emph{not}} running in simulation mode (described in Section
\ref{Sec:SimMode}). Instead, in this case, the single instance of
\code{pMOOSBridge} is renaming and routing data such that the need
for instruments and the navigator is avoided.
 }\label{fig:MultiSim4}
 \end{figure}
Finally, another two alternatives are presented in Figures
\ref{fig:MultiSim3} and \ref{fig:MultiSim4}. Here a single bridge
is used to do all the required data routing and name mapping for
both communities. In \ref{fig:MultiSim4}, a visualisation
community has been added which uses the \code{iMatlab} interface
to render the simulation in a ``fancy fashion''. Note that in this
case a minimal simulation is being run and so the Bridge will be
mapping, for example, \code{AUV\_A\_SIM\_X} on the simulation
community to \code{NAV\_X} on community \code{A} as well as
\code{AUV\_B\_SIM\_X} to \code{NAV\_X} on community \code{B}.

\subsubsection{Inter Vehicle Ranging}
The ``ADD\_AUV'' string can also specify how the vehicle acoustic system
responds to acoustic interrogation. By adding something of the form ``{\it{ResponderChannel = Ch3,TAT = 0.125}}'' to the ``ADD\_AUV'' string,
the vehicles will act like acoustic beacons (only they move) and respond to ``CIF'' pulses
from other vehicle transceivers on the channel specified with the declared turnaround-time.
If the ``ResponderChannel'' is not specified it will be assumed that inter-vehicle ranging
is not wanted and the vehicle's acoustic responders will be turned off.

\newpage
\part{Other Matters}
\section{Building MOOS}

All of the latest MOOS code found on
{\it{www.robots.ox.ac.uk/~pnewman}} is cross platform. Built into
the source tree is a cross platform build system that relies on
\code{CMake} - a thirdparty executable available from
{\it{www.cmake.org}} or the MOOS website.

\subsection{The Source Tree Shape}

\begin{figure}[ht]\label{fig:MOOSTree}
\centering \epsfig{file = MOOSBuild.eps , width = \linewidth}
\caption{The MOOS source tree (as downloaded)}
\end{figure}

Figure \ref{fig:MOOSTree} shows the shape of the MOOS tree in
release packages. \footnote{you obviously don't have to stick with
this but it has some positives}. The ``core'' directory contains
code that has nothing per-se to do with robots. It is only
concerned with communications and logging communications. Of the
directories within ``core'' the most important three directories
are MOOSLib, MOOSGenLib and MOOSDB. These are the uber-core of
MOOS. The minimal conceivable build would be these three projects:
The base MOOS libraries and the MOOSDB server that binds processes
together.

The instruments subtree is pretty obvious - note it  includes
\code{iMatlab} which is peculiar instrument as it provides an
interface to Matlab not a device or human.

The \code{BasicApps} directory contains projects that are common
in mobile robotics apps --- \code{pNav} \code{pHelm} and
\code{iRemote}. \footnote{I would agree that there is a case to
put the latter in the instruments subfolder as it interfaces to a
``human instrument'' - but it seemed more robot centric rather
than sensor based - \it{sub-judice}}

The \code{Utils} directory is self explanatory and contains for
the most part cross platform GUIs and the a multi-vehicle AUV
simulator.

The Thirdparty directory contains cod that for the most past is
written by thirdparty authors. Newmat is linear algebra package
and FLTKVW is an extension to the FLTK functionality with a few
MOOS-Graphics additions.


\subsection{Cross platform Building using CMake}\label{Sec:CMake}

The use of \code{CMake} allows a code-author to describe in a high
level way what should be built in a project. The important point
from the is that it allows (via ``meta-make'' files called
\code{CMakeLists.txt} found in every directory) make files to be
written for unix and microsoft developer studio development alike.
This is a massive win in terms of cross platform development /
project management. \footnote{Of course if one only develops for
one OS it is hard to see the benefit.}

The instructions for building MOOS with \code{CMake} are as
follows:

\begin{enumerate}
\item  Download and install \code{CMake} for your platform (from
ww.cmake.org or the MOOS website)
%
\item ``cd'' into the MOOS root directory
%
\item Type \code{ccmake ./}  you should see
something like Figure \ref{fig:CMake1}.
\begin{figure}[ht]\label{fig:CMake1}
\centering \epsfig{file = CMake1.eps , width =  0.8\linewidth}
\caption{The initial CMake Screen - Win32 platforms have a
gui-dialog rather than an ncurses interface}
\end{figure}
%
\item press "c" to configure - the screen should look like
something like Figure \ref{fig:CMake2}.
\begin{figure}[ht]\label{fig:CMake2}
\centering \epsfig{file = CMake2.eps , width = 0.8\linewidth}
\caption{The initial CMake Screen after an initial configure -
note no option to generate makes files is present as yet. Build
directories and build options (ie what to build and what not) can
be selected at this stage. }
\end{figure}
*
\item press "c" to configure once more. the screen should now look
something like  Figure \ref{fig:CMake3}.
\begin{figure}[ht]\label{fig:CMake3}
\centering \epsfig{file = CMake3.eps , width = 0.8\linewidth}
\caption{The final CMake Screen before generating the build files
(``.dsp'' or Makefile --- depending on platform). Please note
``Configure'' may have been selected several times before this
final option is presented. }
\end{figure}
%
\item Notice an option "g" has appeared saying we are good to
go....Press "g" to generate the MOOS make files. If you have
followed the above steps CMake will exit and you'll see (along
with one or two other CMake generated files) a master Makefile in
the root directory. Typing make at the prompt will now cause the
MOOS core to be built. Check it does!
\end{enumerate}


By toggling the relevant fields in the ccmake curses-GUI you can
turn on/off Makefile generation for different part of the project.
Pressing "c" to configure then parses the newly included
CMakeLists.txt files and may present some new option for you to
select. Things should work simply by accepting the default values.

Note, the Utils directory includes massively useful GUI
applications which link against FLTK. You are expected to have the
library and include files in your system path (this should have
been done for you using the configure, make,make install paradigm
when building the FLTK library) Part III Adding your own projects
to the build tree

By entering a suitable directory or symbolic link in the
\code{ALSO\_BUILD} field causes CMake to recurse into tat
directory when creating make files. This way developers can
include their own projects in the build paradigm. For example, the
Oxford Mobile Robotics group has a directory called OXMOOS which
lives in a directory in MOOS (just like Core or Utils does).
Typing OXMOOS in the \code{ALSO\_BUILD} field causes CMake to
recurse into the OXMOOS directory and follow the instructions in
the CMakeLists.txt file therein (which causes it to recurse
further down into each of our individual application projects).
The advantage of this is it inherits all the build flags, library
settings of the parent MOOS project and so things like the library
paths (MOOSBin in the example above) are automatically passed to
the compiler.\\ \vspace{1cm}\\ \textbf{By default binaries and
libraries are placed in MOOS/MOOSBin} - this of course can be
changed simply by typing in your preferred destination during the
build system set up using CMake \footnote{Devstudio users will
find the binaries in debug/release/releasewithdebug directories
within MOOSBin depending on the active project configuration
selected in the IDE.} See Figure \ref{fig:CMake2}.


\subsection{Incorporating a Private Codebase/Subtree}

It is recommended to place a private subtree where the
``MOOSUSER'' label is in Figure \ref{fig:MOOSTree}. For example
the author has a private source tree called ``OXMOOS'' which can
normally be found in this location - a sibling of ``BasicApps''
and ``Core'' etc. The code{CMake} (See section \ref{Sec:CMake})
insfrastucture can be directed to descend into this subtree by
specifying the name of the subtree in the {\it{``ALSO\_BUILD''}}
field of the \code{CMake} configuration pages.


\subsection{I insist on my own Makefiles...}

Some MOOS users may not wish to use the CMake infrastructure  (a
CMakeLists.txt file in each directory) or tree provided in the
releases
--- preferring instead to use old trusted make files they have
written themselves for whatever platform they wish to
develop/deploy on. This of course will work --- the source in no
way depends upon the build system. The following tips maybe
useful:

\begin{itemize}
    \item The CMakeLists.txt files are a good way to see what
    needs to be built. The sources are listed and so are the
    linking dependencies.
    \item Don't assume all files in a directory should be compiled
    into an executable. Although this is generally true there are
    some applications that have OS dependent source-sets.
    \item To compile a MOOS applications it will need to have
    {\it{MOOS/Core}}in the include path and link against
    {\it{MOOSGen.a}} and {\it{MOOS.a}}. Where these are built depends on
    your own make files.
\end{itemize}

\newpage
\part{Summary and Further Work}

This paper provides a discussion of the MOOS software. It is
however, by no means exhaustive. Although the architecture of the
core communications are completely described many of the details
of the higher level processes building on this architecture have
been omitted. In some ways this is in the spirit of the MOOS -
knowledge of the innards of individual processes can be
administered on a ``need to know basis''. What is important is the
interactions between processes. In a similar vein the details of
of the workings navigation filters have also been omitted although
their broad functionality is described.

It is hoped that MOOS can provide a flexible research tool for
some time to come. It is an evolving project and under continual
improvement and expansion.

Most of all it should be fun to use -  despite its ridiculous
name.

\Ignore{
\section{StillToDo }

\begin{itemize}
  \item scheduler
  \item uMVS
  \item iMatlab
  \item SourceTree and Building
\end{itemize}
}






















%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\appendix
\section*{Appendix A - Skeleton Code}\label{app:A}

\begin{figure}[h!]
\begin{lstlisting}[]{}
#include "MOOSLib.h"
#include "MOOSGenLib.h"
#include "Skeleton.h"
int main(int argc ,char * argv[]) {
    // set default mission file
    char * sMissionFile="Mission.moos";

    if(argc>1)
    {
        sMissionFile = argv[1];
    }

    //make your application
    CSkeleton TheSkeleton;

    //run it//
    TheExample.Run("Skeleton",sMissionFile);

    return 0;
}
\end{lstlisting}
\caption{source code for a very minimal application that runs a
\code{CMOOSApp} derived object called \code{TheSkeleton} of type
\code{CSkeleton}.}
\end{figure}

\begin{figure}
\begin{lstlisting}[]{}
class CSkeleton : public CMOOSApp
{
 protected:
    //these are the virtual functions to overide
    bool OnNewMail(MOOSMSG_LIST &NewMail);
    bool Iterate();
    bool OnConnectToServer();
    bool OnStartUp();
};
\end{lstlisting}
\caption{source code for the declaration of the example
\code{CSkeleton} class}
\end{figure}
%
\begin{figure}

\begin{lstlisting}[ ]{}
#include "Skeleton.h"

bool CSkeleton::OnNewMail(MOOSMSG_LIST &NewMail)
{
    //parse mail here
    return true;
}

bool CSkeleton::OnConnectToServer()
{
    //register for variables here....
    return true;
}

bool CSkeleton::Iterate()
{
    //do standard work here
    return true;
}

bool CSkeleton::OnStartUp()
{
    //do start up things here...
    //for example read from mission file...
    return true;
}
\end{lstlisting} \caption{source code for the \code{CSkeleton}
\code{MOOSApp} derived class}
\end{figure}
\newpage
\section*{Appendix B - Navigation Configuration}
\begin{lstlisting}[ ]{}
/////////////////////////////////////////////
// pNav control block
ProcessConfig = pNav {

    ///////////////////////////////////////////
    //      routing priority stack
    ///////////////////////////////////////////
    X           = GPS @ 2.0,EKF @ 2.0 ,LSQ @ 5.0,
    Y           = GPS @ 2.0,EKF @ 2.0 ,LSQ @ 5.0,
    Z           = EKF @ 2.0 ,LSQ @ 5.0,
    Depth       = EKF @ 2.0 ,LSQ @ 5.0, DEPTH @ 1.0
    Altitude    = RANGE @ 1.0
    Yaw         = EKF @ 2.0 ,LSQ @ 5.0, INS @ 1.0
    Pitch       = INS
    Speed       = EKF

    ALWAYS_READ = INS_YAW,PARA_DEPTH,LBL_TOF,GPS_X,
                  GPS_Y,DVL_BODY_VEL_Y,DVL_BODY_VEL_X,DESIRED_THRUST

    /////////////////////
    //  FILTER CONTROL:
    /////////////////////

    //what filters to use......
    UseLSQ      = true
    UseEKF      = true
    LSQTimeOut  = 180

    MaxLSQEKFDeviation = 20
    MaxEKFPositionUncertainty = 30

    //how to log nav if required (development tool)
    NAV_LOG = true
    NAV_LOG_PATH = C:\codescratch\MOOSLOG\
    NAV_LOG_TIMESTAMP = false


    SV = 1500.0

    ///////////////////////////////
    // static observations
    // format is  [Value] @ [uncertainty]
    ///////////////////////////////

    FixedTide       = 0 @ 0.1

    ////////////////////////////////
    // map sensor outputs to sensors within filters
    // specifying geometry.....
    // Syntax is as follows
    // SensorType       =Source -> SensorName @ Location ~ Sensor Std
    //////////////////////////////

    SENSOR_XY       =   iGPS    ->  TheGPS    @ 0,0,0 ~ 0.3
    SENSOR_LBL      =   iLBL    ->  TheAvtrak @ 0,0,0 ~ 0.009
    SENSOR_ORIENTATION  =   iINS    ->  TheINS    @ 0,0,0 ~ 0.01
    SENSOR_DEPTH        =   iDepth  ->  TheDepth  @ 0,0,0 ~ 0.1
    SENSOR_BODY_VEL     =   iDVL  ->    TheDVL    @ 0,0,0 ~ 0.05


    ///////////////////////////////
    // Least Square filter set up
    LSQ_REJECTION = TheAvtrak[1] :  History = 6 ,FAIL = 0.005
    LSQ_REJECTION = TheAvtrak[2] :  History = 6 ,FAIL = 0.005
    //etc...
    //etc...

    ///////////////////////////////
    // Extended Kalman Filter set up

    EKF_LAG =3.0
    EKF_TIDE = 00

    //how fast/mobile is the vehicle?
    // 1=slow
    // 10 =fast
    EKF_XY_DYNAMICS = 0.1
    EKF_Z_DYNAMICS = 0.1
    EKF_YAW_DYNAMICS = 0.1
    EKF_VEHICLE_TYPE = MOBILE

    //initial uncertainty
    EKF_SIGMA_XX = 20.5
    EKF_SIGMA_YY = 20.5
    EKF_SIGMA_ZZ = 1
    EKF_SIGMA_HH = 180
    EKF_SIGMA_TIDE = 0.1

    //initial state
    EKF_X = 0
    EKF_Y = 0
    EKF_Z = 0
    EKF_H = 0
}
\end{lstlisting}
%\end{figure*}

\section*{Appendix C - Coding Style Guide}
This is the recommended coding style for c++ in MOOS. The author
has tried to follow such rules throughout - of course there will
be occasional slips and these should be corrected where found -
its all about entropy\footnote{Thanks to Greg Walker for this
list}. The author urges future ``MOOSies'' to use the same style.
It is not so much about one style being better than another but
keeping things unified  and having the same flavor whenever
possible.
\begin{itemize}
    \item  Use Hungarian notation prefixes for variables"
    \begin{itemize}
            \item doubles prefixed by "df" eg "dfMyLocalVal"
            \item ints prefixed by "n"
            \item strings prefixed by "s"
            \item member variables begin with "m\_" eg "m\_dfMyMemberVal"
    \end{itemize}
    \item  Variables should be long enough to be meaningful.  Where they are multi word use capital to denote first letter of each word.  e.g. m\_dfTurnAroundTime.
    \item  Use capital letters to identify defined constants (or the equivalent thereof)
    \item  Indent / tab stops in steps of 4
    \item  Opening and closing brackets at same tab stop as outer, enclosed lines to be indented.
    \item Minimize scope of local variables.
    \item Do not re-use a single local variable to express different concepts at different points in a routine.  There is a risk that somebody doesn't notice that when he comes to modify code at a later date.
    \item Be liberal in use of white space to separate logical steps - for clarity.
    \item Source text should not overrun 100 characters to a line.  You should be able to get that across a portrait style A4 paper page if you want to print it out.
    \item Keep to simple expressions in a statement.  It will be easier to understand later.
    \item Restrict the executable code of a procedure to about an A4 page.  If it stretches much beyond that you can probably find a block of code that expresses an identifiable concept to remove to a separate procedure.
    \item Avoid the use of multiple inheritance and friend classes.
    \item Never sit in an un-blocked loop waiting for an externally controlled condition to be met.  It eats up processor time with no benefit.
    \item Avoid use of explicit numeric values in code.  Assign symbolic name to the number so that the definition appears in one place only.
    \item Avoid "copy and paste" of anything more than tiny code fragments.  It's an indication that a common procedure can be created which will service multiple needs.  If there's less code in the application, there's less to go wrong.  If it needs a fix then one fix solves all associated problems - you don't have to seek out the other similar code which probably has the same fault.
    \item Where procedure calls have lots of parameters, don't be afraid to assign a line to each parameter - but do put the opening bracket in the same text column as the closing bracket.
    \item TRACE statements should start with class::method identifier, and end with a newline.  That makes it easy to find the source code that invoked the debug output.  e.g. TRACE("CMyClass::DoIt - That's done it $\backslash$ n");
\end{itemize}

\section*{Appendix D - Known Bugs and Inadequacies}
The following is an incomplete list of the known issues with MOOS
as of December 2002.

\begin{itemize}
\item Navigation filters do not take roll and pitch into account
when processing DVL data - easy to fix as all sensor data is
transformed into to a horizontal, rotated frame for processing.
\item In Windows \code{iRemote}sometimes does not quit when told
to. Strangely it does remove itself from the process table.
\item The dynamic controllers do not take in rate information but
rather infer it themselves which is a noise prone process and
incurs a phase lag - easy to fix.
\end{itemize}

\end{document}
