<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
% Include common packages, environments, counters etc
%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_lab_format}
\input{common_latex/common_latex_definitions}
%===================================================================
\begin{document}
\wikidoc{file=SDR.LabIntroMOOS}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 2 - Introduction to MOOS}
\vspace{0.1in}
%\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.1in}
\labpng{0.75}{figs_common/header_sdr.png}
\labdate{Fall 2017}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Henrik Schmidt, henrik@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{footnotesize}
\end{labcover}

%===================================================================
% Add a blank page so first body page is on the right when doubleside
\blankpage

%===================================================================
% Begin the body of the text
%===================================================================
\section{Overview and Objectives}
\label{sec_overview}
%===================================================================

This lab will introduce MOOS to new users. It assumes nothing
regarding MOOS background. The goals of this lab are to (a) understand
the publish-subscribe architecture, (b) get comfortable launching and
interacting with the MOOSDB, (c) understand how to generate scripted
interactions with the MOOSDB, (d) understand how the logger operates
and basic tools for examining log files

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item MOOS Preliminaries: MOOS vs. MOOS-IvP, the MOOS Architecture
\item Launching, Scoping, and Poking the MOOSDB
\item Launching a Mission with pAntler
\item Scripted Pokes the to the MOOSDB
\item A Simple Example with pXRelayTest
\item Modify the pXRelayTest Code
\end{packed_itemize}
\end{labinfo}


\subsection{Preliminaries}
\label{prelims}

This lab assumes you have a working MOOS-IvP tree checked out and
built on your computer. To verify this make sure that the following
executables are built and findable in your shell path:

\begin{consoleverb}
 $ which MOOSDB
 /Users/you/moos-ivp/bin/MOOSDB
 $ which pHelmIvP
 /Users/you/moos-ivp/bin/pHelmIvP
\end{consoleverb}
\postverb

\noindent
If unsuccessful with the above, return to the steps in Lab 1:

\pskip
\noindent
\urlxx{http://oceanai.mit.edu/pavlab/pmwiki/pmwiki.php?n=SDR.LabIntro}

%-------------------------------------------------------------------------
\subsection{MOOS vs. MOOS-IvP}

What is the relationship between MOOS and MOOS-IvP? MOOS-IvP is a
superset of MOOS. The additional components include another
architecture, the IvP Helm behavior-based architecture, and several
additional MOOS applications.  This is the nested repository concept
depicted in Figure \ref{fig_nested_archs}.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/nested_moos.png}
  \caption{{\bf Nested Repositories:} The MOOS-IvP tree contains the
    Oxford MOOS tree and additional modules from MIT including the
    Helm architecture, Helm behaviors and further MOOS applications.}
\label{fig_nested_archs}
\end{figure}


%==========================================================================
\subsection{More MOOS / MOOS-IvP Resources}

We will only just touch the MOOS basics today. A few further resources are worth 
mentioning for following up this lab with your own exploration.

\begin{itemize}
\item The 2.680 lecture covers much of the material for today's lab: \newline
 \urlx{http://oceanai.mit.edu/2.680/lectures/2.680-03-moos-intro.pdf}

\item The "Very Brief Overview of MOOS" page on the course documentation page: \newline 
 \urlx{http://oceanai.mit.edu/ivpman/pmwiki/pmwiki.php?n=Helm.MOOSOverview}

\item Follow the links to the documentation on the Oxford MOOS website. \newline 
 \urlx{http://themoos.org} 


\end{itemize}

%==========================================================================
\subsection{The MOOS Architecture}

The main idea explored today is that MOOS is a publish-subscribe
architecture.  A single \app{MOOSDB} serves multiple MOOS applications
by essentially handling the mail published and subscribed for by each
app. A MOOS {\em community} is a collection of applications connected
to a single \app{MOOSDB}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.55\textwidth]{figures/moos_pub_sub.png}
  \caption{{\bf The MOOS Architecture:} MOOS is a publish-subscribe
    architecture.  The \aapp{MOOSDB} serves a number of clients,
    handling mail for each client as new information is posted. A
    MOOSDB with connected clients constitutes a {\em MOOS
      community}. There may be multiple MOOS communities on a single
    machine, and a single MOOS community may be distributed over more
    than one machine.}
\label{fig_moos_arch}
\end{figure}

For typical autonomous vehicle implementations, there is a MOOS
community on board each vehicle. When simulating multiple vehicles on
a single machine, there is also a single community associated with
each vehicle. A {\em MOOS community} consists of a single \app{MOOSDB}
with one or more connected clients.  The communications discussed in
today's lab concern how a single app communicates with another app via
the \app{MOOSDB} in the publish-subscribe architecture. Later labs
will address how vehicles communicate with each other, essentially
bridging two or more MOOS communities with one another.

\pskip

For today, the focus is on the \app{MOOSDB} and connected
applications. The \app{MOOSDB}, unlike an actual database, does not
contain a full history of information that has passed through it. At
most, it stores the latest value for any given MOOS variable published
to the \app{MOOSDB}. When a new app connects to the \app{MOOSDB} it
must register for the mail it needs. On startup, an app can expect to
get a mail message containing the latest value for any variable it
registers for, even if that mail reflects a posting to the
\app{MOOSDB} long ago. Anything happening prior to that will be
unknown to the newly connected app.


%======================================================================
\newpage
\input{./help_mip_launch_moos}

%======================================================================
\newpage
\input{./help_mip_scoping}

%======================================================================
\newpage
\input{./help_mip_poking_the_db}

%======================================================================
\newpage
\input{./help_mip_pantler.tex}

%======================================================================
\newpage
\input{./help_mip_scripted_pokes.tex}


%======================================================================
\newpage
\section{A Simple Example with pXRelay}
\label{sec_pxrelay}
%======================================================================

\app{pXRelay} is a simple MOOS app designed solely to illustrate basic
functions of a MOOS app. It registers for a single variable, and upon
receiving mail for that variable, it publishes another variable
incremented by 1. It provides a framework for illustrating a few other
introductory topics.

\pskip

\subsection{Basic pXRelay Usage}

\app{pXRelay} is configured with its own block in the MOOS
configuration file. It is configured with (a) an incoming variable,
the variable it will register for incoming mail, and (b) an outgoing
variable, a variable it will post an incremented integer each time it
receives mail on the incoming variable. The basic form is:

\vspace{0.15in}
\begin{fileverb}
 ProcessConfig = pXRelay                                         
 {                                                               
   outgoing_var = &lt;MOOSVar&gt;                                   
   incoming_var = &lt;MOOSVar&gt;                                      
 }                        
\end{fileverb}
\vspace{0.15in}

%=======================================================================
\subsection{A Simple Example with pXRelay}

The below mission file contains a configuration for two instances of
the \app{pXRelay} application. All MOOS apps must have a unique name
to connect to the MOOSDB, so we launch them with an alias with
\app{pAntler} using the \var{~pXRelay\_PEARS} alias for example. The
two apps each register for what the other produces, and each produces
what the other registers for.

\vspace{0.1in}
\begin{listing}{Example Code}
\label{block_pxrelay}
\footnotesize
\begin{Verbatim}[frame=single]
  0   // (wget http://oceanai.mit.edu/2.680/examples/xrelay.moos)
  1   ServerHost = localhost
  2   ServerPort = 9000
  3   Community  = alpha
  4  
  5   ProcessConfig = ANTLER
  6   {
  7     MSBetweenLaunches = 200
  8   
  9     Run = MOOSDB       @ NewConsole = false
 10     Run = pXRelay      @ NewConsole = false ~pXRelay_PEARS
 11     Run = pXRelay      @ NewConsole = false ~pXRelay_APPLES
 12   }
 13  
 14   ProcessConfig = pXRelay_APPLES
 15   {
 16     AppTick       = 10
 17     CommsTick     = 10
 18     incoming_var  = APPLES
 19     outgoing_var  = PEARS
 20   }
 21  
 22   ProcessConfig = pXRelay_PEARS
 23   {
 24     AppTick       = 10
 25     CommsTick     = 10
 26     incoming_var  = PEARS
 27     outgoing_var  = APPLES
 28   }
\end{Verbatim}
\normalsize
\end{listing}
\vspace{0.15in}

\noindent
Upon launch, the two pXRelay apps are in a stalemate, each waiting for
the other to make the first posting. We can break this stalemate with
\app{uPokeDB}:

\vspace{0.1in}
\begin{consoleverb}
 $ uPokeDB xrelay.moos PEARS=1
\end{consoleverb}
\vspace{0.1in}

\noindent
This should get things going. Now it would be good to see it all
running by launching a scope:

\vspace{0.1in}
\begin{consoleverb}
 $ uXMS xrelay.moos --all --show=time
\end{consoleverb}
\vspace{0.1in}


\noindent
Your goals in this part are:

\begin{packed_enumerate}[2]

\item Create a copy of the example mission file shown in Listing
  \ref{block_pxrelay} above and save it locally as
  \var{pxrelay.moos}. (hint: use wget!)

\item Launch the mission. Open up \app{uXMS} in another Terminal window with the
  parameters of your choosing. I recommend

\begin{consoleverb}
 $ uXMS pxrelay.moos --colorany=APPLES,PEARS --all
\end{consoleverb}

\item Kick off the activity by poking one of the \mvar{APPLES} or
  \mvar{PEARS} variables with an initial value. Confirm that things
  are working as they should.

\item Add \app{uTimerScript} to your mission file, with a simple
  script to kick off the \app{pXRelay} handshaking at some point after
  launch (say 10 secs), as an alternative way to kicking off the
  active instead of \app{uPokeDB}. You'll need to add
  \app{uTimerScript} to your \var{ANTLER} configuration block, and add
  a simple script (a \app{uTimerScript} configuration block) to your
  .moos file.

\item Change your \app{uTimerScript} script to be the ascending
  counter script from Section \ref{sec_scripted_pokes}, incrementing
  \mvar{COUNTER\_A} 1 to 10.  Configure it with \psvar{paused=false}, but
add a condition to your script
  (\psvar{condition = APPLES == \$(PEARS)}.  Re-launch the revised mission. Since
  \mvar{APPLES} is equal to \mvar{PEARS} periodically, the condition
  will periodically be met.

\item Try changing the \pvar{AppTick} in one of the \app{pXRelay}
  configurations to 0.1. You should note that the script is now mostly 
  in the state where its conditions are not met. Can you explain why?

\end{packed_enumerate}

%+++++++++++++++++++++++++++++++++++

%======================================================================
\newpage
\section{Modify the pXRelay Code}
\label{sec_pxrelay_mod}
%======================================================================

[Note - this step is great to try if you have time. It's not essential
  in terms of continuity to the next lab. The most useful part of this
  step is to pull down the \var{moos-ivp-extend} tree and verify that
  you can build the tree with the \app{pXRelayTest} in your shell
  path.]

\vspace{0.1in}
\noindent
Next we will take the first steps toward extending the MOOS-IvP
code. This is done by creating your own "third-party" tree, with your
own MOOS apps.  A template for this is available on the
\urlx{moos-ivp.org} website: Go to \urlx{www.moos-ivp.org} and click
on the \var{moos-ivp-extend} link in the lefthand menu. Download the
\var{moos-ivp-extend} tree, in the same directory where the
\var{moos-ivp} tree resides:

\begin{consoleverb}
$ svn co https://oceanai.mit.edu/svn/moos-ivp-extend/trunk moos-ivp-extend
\end{consoleverb}

\noindent
Verify that you can build this tree by:

\begin{consoleverb}
 $ cd moos-ivp-extend
 $ ./build.sh
\end{consoleverb}

\noindent
It should add the executable, \app{pXRelayTest}, in \var{moos-ivp-extend/bin/}. 

\vspace{0.1in}
\noindent
Add the above directory to your shell path.

\vspace{0.1in}
\noindent
The moos-ivp-extend tree contains an app very similar to \app{pXRelay}
from the moos-ivp tree. This app is call \app{pXRelayTest}. We will
attempt to modify some of the behavior of the \app{pXRelay}
application while putting our modifications in the new moos-ivp-extend
tree, in \app{pXRelayTest}.


\begin{enumerate}
\item Take a look at the \app{pXRelayTest} source code.  Look inside
  \var{Relayer.cpp}. Check out the \var{OnNewMail()} and
  \var{Iterate()} loops.
\item Can you modify this code to make it increment by ten instead of
  one?
\item Can you modify this code such that it takes {\em two} incoming variables, 
  and does its thing if {\em either} of the two variables is written to?
\end{enumerate}



\end{document}

</pre></body></html>