

\documentclass[a4paper,10pt]{article}
\usepackage{listings,color,epsfig,amsmath,url,tabularx}
\definecolor{codecolor}{rgb}{0.99,0.97,0.94} % color values Red, Green, Blue
\definecolor{commentcolor}{rgb}{0.1,0.5,0.1} % color values Red, Green, Blue
\definecolor{stringcolor}{rgb}{0.3,0.1,0.1} % color values Red, Green, Blue
\newcommand{\Code}[1]{\texttt{#1} }
\newcommand{\code}[1]{\Code{#1} }
\newcommand{\DB}   {\code{{MOOSDB}}}
\newcommand{\MA}   {\code{{MOOSApp}}}
\newcommand{\Ignore}[1]   {}



% Title Page
\title{MOOS Conventions}
\author{Paul Newman}


\begin{document}
\maketitle

\begin{center}
\epsfig{file=images/moose6.eps,width = 0.2\linewidth}
\end{center}
\begin{abstract}
This document states the conventions used by MOOS. This covers coordinate frames as well as processes and variable naming policies.
\end{abstract}


\section{Coordinate Conventions}
MOOS processes communicate using a defined coordinate system as
illustrated in Figure \ref{fig:coordinates}. The salient points to
note about this system are as follows.
\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 = images/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} MOOS defines a geodetic called
\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 = images/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'' typically make use of \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 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 \code{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).

\end{document}
