

\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 Meets Matlab --- \code{iMatlab} }
\author{Paul Newman}


\begin{document}
\maketitle

\begin{center}
\epsfig{file=images/moose6.eps,width = 0.2\linewidth}
\end{center}

\section{Introduction}

Not everyone wants 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 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\
footnote{Compiles into a binary form Matlab can call directly.} 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 the 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}[ht]
\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  \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}[ht]
\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}
 \caption{The contents of a MOOS mail
structure in iMatlab} \normalsize
\label{Tab:iMatlabMail}
\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}[ht]
\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}
\caption{The contents of the data
structure pertaining to received serial data in \code{iMatlab}}
\normalsize
\label{Tab:iMatlabSerial} 
\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.


\end{document} 