\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 = incoming_var = } \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}