\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=MCA.Lab02IntroMOOS}
\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.png}
\labdate{June 15-26 2026}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Dept of Mechanical Engineering, 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:

\vspace{0.1in}
\noindent
\urlxx{http://oceanai.mit.edu/minicourse-pisa/labs/lab01}

%-------------------------------------------------------------------------
\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 this lab: \newline
 \urlx{http://oceanai.mit.edu/minicourse-pisa/pdfs/lecture_pisa_02.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}


\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.45\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}

\noindent
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.

\vspace{0.1in}
\noindent
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.

\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 = <MOOSVar>                                   
   incoming_var = <MOOSVar>                                      
 }                        
\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{Augmenting the Control Options in the Alpha Mission}
\label{sec_aqua_alpha}
%======================================================================

In this section, we will work with the Alpha mission, and add a couple
commands to the control interface, and also add another MOOS App to
the MOOS community.

\vspace{0.1in}
\noindent
You will experience:

\begin{packed_itemize}
\item How to create your own mission folder (by copying an existing mission)
\item How to add command buttons and command pull-down menu options to the
  \app{pMarineViewer} interface.
\item How to add an additional MOOS App to a mission configuration file.
\item How to use the \app{iSay} MOOS App to add audio confirmation when
  issuing commands.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The first step is to make a copy of the \var{alpha} mission, naming it
\var{alpha\_mod1}. In the steps below, after copying the folder, run
the mission from within the \var{alpha\_mod1} folder and verify that it
runs exactly as in the \var{alpha} folder.

\vspace{0.1in}
\begin{consoleverb}
$ cd moos-ivp/ivp/missions
$ cp -rp s1_alpha alpha_mod1
$ cd aphpa_mod1 
$ ./launch.sh 10
\end{consoleverb}
\vspace{0.1in}

%======================================================================
\subsection{Adding Button Commands to the Control Interface}
\label{sec_pmv_buttons}

In the next step, the goal is to add two command buttons to the \app{pMarineViewer}
interface. You will notice that the Alpha mission has four buttons to start with:

\begin{packed_itemize}
\item \var{DEPLOY}: Begins the mission
\item \var{RETURN}: Sends the vehicle home
\item \var{SLOWER}: Changes the speed to a slower speed (1.5m/sec)
\item \var{FASTER}: Changes the speed to a faster speed (3.5m/sec)
\end{packed_itemize}

\noindent
These buttons are configured in \app{pMarineViewer} configuration block of the
\var{alpha.moos} file. If you open an editor of this file and search for the
expression {\em button}, the buttons for the above four configurations can be
found. To read more on button configuration in \app{pMarineViewer}, see the
documentation:

\urlx{https://oceanai.mit.edu/ivpman/apps/pMarineViewer}

\vspace{0.1in}
\noindent
Section 2.3 discusses button configuration. The documentation does not yet
convey that up to 20 buttons (not 4) may be used. Your goal is to add two
additional buttons:

\begin{packed_itemize}
\item One button, labeled \var{REVERSE} which will send the vehicle around
  the waypoints in a counter-clockwise direction, instead of the initially
  configured clockwise directions.

\item Another button, labeled \var{TOGGLE} which will send the vehicle
  around the waypoints in the direction opposite of what it is currently
  traversing.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Each button is configured with a label and one or more MOOS pokes. Use the two
label suggestions above. As for the MOOS poke, for now take it on faith that
they will be:

\begin{packed_itemize}
\item \var{WPT\_UPDATE=order=reverse}, and 
\item \var{WPT\_UPDATE=order=toggle}
\end{packed_itemize}

\vspace{0.1in}
\noindent
The meaning will be discussed later, but a quick explanation is that
\var{WPT\_UPDATE} is the variable that the Waypoint behavior is
listening for parameter updates, and \var{order=reverse} and
\var{order=toggle} are two parameter options for the Waypoint behavior
that we're setting up to be changed dynamically on button pushes.


\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figures/alpha_toggle.png}
  \caption{The Aquaticus Alpha mission is modified to add two additional
    command buttons, \var{REVERSE}, and \var{TOGGLE}, for changing
    the direction of the vehicle traversal.}
  \label{fig_alpha_toggle}
  \gif{figures/alpha_toggle.gif}
  %  \urlvideo{https://vimeo.com/484934380}{0:17}
\end{figure}

%======================================================================
\subsection{Adding the iSay Application for Audio Feedback of Commands}
\label{sec_isay}

In this section, the \app{iSay} application is added to the Alpha mission. This
app will convert posted phrases like "returning home" to computer generated audio.
Any English utterance is fair game. It will also post sounds, like bells or buzzers,
to indicate that a certain event has occurred. This app is described on its own page:

\urlx{https://oceanai.mit.edu/ivpman/apps/iSay}

\vspace{0.1in}
\noindent
The \app{iSay} app uses the native system commands found on the Mac
(\cmd{say}), and Linux (\cmd{espeak}). You can try this separately now by just
opening a terminal window and typing:

\vspace{0.1in}
\begin{consoleverb}
  $ say "Hello, how are you?"     (on the Mac), or
  $ espeak "Hello, how are you?"  (in Linux)
\end{consoleverb}

\vspace{0.1in}
\noindent
The first step is to add \app{iSay} to the Antler configuration block at the top of
the \var{alpha.moos} file:

\vspace{0.1in}
\begin{fileverb}
  Run = iSay    @ NewConsole = false
\end{fileverb}
\vspace{0.1in}

\noindent
Then add \app{iSay} configuration block to the end of the
\var{alpha.moos} file. (Actually any order in the file is fine.) To
get an example of the \app{iSay} configuration parameters and an
example configuration block, type \var{iSay -e} on the command line,
and you will be presented with an example configuration block. Most
MOOS-IvP apps are implemented to support the \var{-e} command line
argument to provide this information. Once you have copied this block
into the \var{alpha.moos} file, re-launch the mission, to confirm that
\app{iSay} is seen in the list of processes in the upper blue panel of
\app{pMarineViewer}, as in the figure below.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/isay_present.png}
  \caption{The iSay app is running and appears in the list of processes.} 
  \label{fig_isay_present}
\end{figure}

\vspace{0.1in}
\noindent
The \app{iSay} registers for the MOOS mail messgage
\mvar{SAY\_MOOS}. Try things out by configuring a seventh button, with
the label \var{"TESTING"}, and have it poke
\msvar{SAY\_MOOS=testing}. Re-launch the mission and click this button
any time to see if you hear something. Make sure you set the
\var{linux/mac} configuration parameter properly to suit your system.

%======================================================================
\subsection{Adding Audio Feedback to Reverse and Toggle Commands}
\label{sec_isay_toggle}

As a final exercise, re-configure the \var{REVERSE} and \var{TOGGLE} buttons
to make {\em two} pokes with each button click. Keep what you have already and
add a posting to \var{SAY\_MOOS} to say "reversing" or "toggling" when the
button is clicked. Re-run your mission and see if the single button clicks
have the intended effect: both a change in traversal and an audio confirmation.


\end{document}
