<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}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

\begin{document}
\wikidoc{file=Lab.ClassMultivAutonomyPreLab}
\wikidoc{auth=mikerb@mit.edu}
\helplevelsubsec

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 6 - Pre-Lab for Multi-Vehicle Operations}
\vspace{0.1in}
\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.15in}
\labpng{0.65}{figures/multibots.png}
\vspace{0.15in}
\labdate{Feb 25th, 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

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

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

In Lab 6 we begin shifting our focus to autonomy configurations
involving multiple vehicles. This pre-lab covers a few initial steps
of Lab 6 for those who wish to get a jump on Lab 6.  Our first focus
will be on communications between two independently running
\app{MOOSDB} processes, where typically a single \app{MOOSDB}, or
"MOOS Community" is associate with a single vehicle.  Ultimately the
inter-\app{MOOSDB} or inter-vehicle communication may come over an
acoustic modem link or a satellite link, our primary initial focus is
on communications over an Internet connection, even if the multiple
"nodes" are all running on your one laptop.

\vspace{0.1in}
\noindent
Gaining familiarity with this mode of operation will be essential for later
labs and operation of vehicles on the water. 

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item The Shoreside and Vehicle(s) Topology
\item Introduction to pShare via the xrelay mission
\item Converting the Alpha Mission to use a Shoreside / Vehicle Topology
\end{packed_itemize}
\end{labinfo}

%=======================================================================
\section{Preliminaries}
\label{prelims}
%=======================================================================

%=======================================================================
\subsection*{Make Sure You Have the Latest Updates}

It is possible we will be making changes to the MOOS-IvP tree during
the semester.  Always make sure you have the latest code:

\begin{consoleverb}
 $ cd moos-ivp
 $ git pull
\end{consoleverb}

\vspace{0.1in}
\noindent
If you see see a response similar to the below, indicating that no
updates were pulled in from the server, then you shouldn't need to
re-build the software.

\begin{consoleverb}
Already up to date.
\end{consoleverb}

\vspace{0.1in}
\noindent
Otherwise you will need to rebuild:

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

%=======================================================================
\subsection*{Make Sure Key Executables are Built and In Your Path}

This lab does assume that you have a working MOOS-IvP tree checked out
and installed 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}

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

\urlxx{http://oceanai.mit.edu/ivpman/labs/machine_setup}{Lab.ClassSetup}

%=======================================================================
\subsection*{Where to Build and Store Lab Missions}

As with previous labs, we will use your version of the
\var{moos-ivp-extend} tree. In this tree, there is a missions folder:

\begin{consoleverb}
 $ cd moos-ivp-extend
 $ ls
 CMakeLists.txt  bin/          build.sh*      docs/        missions/       src/
 README          build/        data/          lib/         scripts/
\end{consoleverb}

\noindent
For each distinct assignment in this lab, there should be a
corresponding subdirectory in a \var{lab\_06} sub-directory of the
\var{missions} folder, typically with both a \var{.moos} and
\var{.bhv} configuration file. See Section \ref{sec_hand_in} for the 
full requested file structure.

%=======================================================================
\subsection*{Documentation Conventions}

To help distinguish between MOOS variables, MOOS configuration
parameters, and behavior configuration parameters, we will use the
following conventions:

\begin{packed_itemize}[3]
\item MOOS variables are rendered in \mvar{green}, such as
  \mvar{IVPHELM\_STATE}, as well as postings to the \app{MOOSDB}, such
  as \mvar{DEPLOY=true}.
\item MOOS configuration parameters are rendered in \pvar{blue}, such
  as \pvar{AppTick=10} and \pvar{verbose=true}.
\item Behavior  parameters are rendered in \bvar{brown},
  such as \bvar{priority=100} and \bvar{endflag=RETURN=true}.
\item MOOS-IvP applications are rendered in \app{magenta}, such as
  \app{MOOSDB}, or \app{pHelmIvP}.
\item General GNU/Linux commands are represented in \cmd{dark purple},
  such as \cmd{wget}, \cmd{ls}, or \cmd{cd}.
\end{packed_itemize}

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

A few further resources are worth mentioning for following up this lab
with your own exploration.

\begin{packed_itemize}[2]

\item The \app{pShare} documentation
  
\urlx{http://oceanai.mit.edu/2.680/oxmoos/pshare.html}

\item The slides from class which give a bit more background into
  marine autonomy and the IvP Helm.

  \urlx{http://oceanai.mit.edu/2.680/docs/2.680-07-multiple\_vehicles\_2024.pdf}

\item The IvP Helm and Utilities documentation:
  \urlx{http://oceanai.mit.edu/ivpman}
\item The moos-ivp.org website:
  \urlx{http://www.moos-ivp.org}
\end{packed_itemize}

%==========================================================================
\newpage
\section{The Shoreside (Topside) / Vehicle Topology}
%==========================================================================

The layout of interconnected MOOS communities used in this lab is
depicted in the figure below. This layout will be used for the
remainder of the course, including during operations on the river.
You will experience different versions of this arrangement. In the
simplest arrangement, in the lab, the Shoreside and vehicle
communities will all be running on your computer. As we mentioned
previously, A MOOS community is a collection of MOOS apps, each
connected to a single MOOSDB for that community. The Shoreside
topology is sometimes also referred to as the {\em uField} topology
since the uField Toolbox is a set of utility applications for
facilitating the Shoreside arrangement.

\vspace{0.15in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.75\textwidth]{figures/ufield_overview_v2.png}
  \caption{{\bf Shoreside to Multi-Vehicle Topology:} A number of
    vehicles are deployed with each vehicle maintaining some level of
    connectivity to a shoreside command and control computer. Each
    node (vehicles and the shoreside) are comprised of a dedicated
    MOOS community. Modes and limits of communication may vary.}
\label{ufld_overview}
\end{figure}
\vspace{0.1in}

\noindent
Communications between apps {\em within} a single MOOS community are
typically high bandwidth with little or negligible latency. This is all handled
over TCP communications between the app and the MOOSDB through the
publish-subscribe protocol described thus far in class. Communications
{\em between MOOS communities} will typically be much lower in bandwidth
with higher latency. Communication modalities may also vary, but include
WiFi, underwater acoustic modems, satellite networks like Iridium, and
others. In these cases there can also be messages that are simply lost.

\vspace{0.1in}
\noindent
Because of these limitations, communications are also typically more
deliberately arranged ahead of time. Communications {\em within} a
MOOS community can be quite dynamic in the sense that any app can
publish anything at any time, and any app can Register for information
at any time. In autonomy systems where there are communications {\em
  between MOOS communities}, the allowed inter-node messages are usually
declared beforehand, and there may also be message priorities and upper
limits on message frequency for certain variables.

\vspace{0.1in}
\noindent
In our class, both in simulation and on the water, the app \app{pShare} is
used for inter-node communications (comms between MOOS
communities). Each MOOS community runs an instance of \app{pShare} as
shown in Figure \ref{fig_ufield_pshare} below. 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.7\textwidth]{figures/ufield_pshare.png}
  \caption{{\bf Inter MOOS Community Communications}: Apps within a single
    MOOS community communicate over TCP, while communication between communities
    is assumed to be lossy. The \app{pShare} app is use in simulations in some
    field test environments to share a small configurable set of information
  between platforms.}
  \label{fig_ufield_pshare}
\end{figure}
\vspace{0.1in}

\noindent
Each instance of \app{pShare} is configured to listen on a unique channel. The
channel is defined by its IP address and port number. Therefore, when multiple
MOOS communities are simulated on a single machine (same IP address), the port
numbers need to be different. When the multiple MOOS communities are on different
platforms, each with its own unique IP address, then each \app{pShare} app may
have the same port number. 

\vspace{0.1in}
\noindent
In addition to specifying the channel for {\em incoming} messages,
\app{pShare} needs to be configured to specify {\em outgoing}
messages. An outgoing message configuration consists of specifying a
MOOS variable in the local (source) community, and the destination of
the message in terms of the IP address and port number of the
receiving \app{pShare} app in the {\em destination} community. It is
also possible to change the name of MOOS variable as it arrives in the
destination community. So each \app{pShare} configuration will consist
of two parts:

\begin{packed_itemize}
\item The incoming listen port
\item One or more MOOS variables mapped to a destination community.
\end{packed_itemize}

\vspace{0.1in}
\noindent
When finally configured, a publication to a local MOOS variable
involved in a \app{pShare}, will result in a near instantaneous
similar publication in the destination community. Note that
\app{pShare} works over UDP, and messages do not have the same
guarantee of arrival as they do with TCP. Messages can and will
drop. You are unlikely to experience a dropped message when simulating
inter-node comms on a single computer, or even over reasonably strong
WiFi connection. But there will be dropped messages when working on
the Charles River when the robots have lossy comms to the shore.
There are no mechanisms built into \app{pShare} to detect a dropped
message. If a message is critical, the user will have to implement
their own acknowledgment and re-send protocol.

\vspace{0.1in}
\noindent
Note: In an separate development branch, a new 2023 app called
\app{pMediator} has been developed to such an ack and re-send
protocol. Ask if you're interested, but we won't need it in our labs
in simulation.


\vspace{0.1in}
\noindent
Normally in our setups, the \app{pShare} communications are solely
between the shoreside MOOS community and the one or more vehicle MOOS
communities. We typically don't share information directly between
vehicles, although there is nothing about \app{pShare} that would
disallow this. While inter-vehicle communication is certainly desired,
and part of our future labs, we implement all inter-vehicle
communications to be routed through the Shoreside community.  For
reasons further explained in later labs, we use this "comms routed
through the shoreside" arrangement so that we can simulate comms
limitations often experienced in the field. We can drop comms based on
inter-vehicle range, or we can limit the bandwidth between vehicles to
simulate communications with similar limits, like satellite or
underwater acoustic comms.


%====================================================================== 
\newpage
\section{Experimenting with pShare}
%======================================================================

In the first exercise in the  pre-lab, the goal is to become familiar
with \app{pShare}. In these first couple of missions, we will be
configuring \app{pShare} explicitly in our \var{.moos} files. In later
missions, we will be using components of the uField Toolbox to
automatically configure the share configurations.

%========================================================================
\subsection{Assignment 1 (self check-off) - Configure pXRelay with pShare}

In this part we will:
\begin{packed_itemize}
  \item Prepare a copy of the xrelay mission for experimenting.
  \item Create two .moos files to launch two \app{MOOSDB} processes.
  \item Launch the two communities and confirm that sharing between
    two MOOS communities works with \app{pShare}.
\end{packed_itemize}

%-------------------------------------------------------------------------
\subsubsection{Make a Copy of the pXRelay Mission}

The first step is to copy the xrelay example mission from your
\var{moos-ivp} tree in your own \var{moos-ivp-extend} tree.

\vspace{0.1in}
\begin{consoleverb}
 $ cp -rp moos-ivp/ivp/missions/xrelay  moos-ivp-extend/missions/lab_06/xrelay_pshare
\end{consoleverb}
\vspace{0.1in}

\noindent
The original xrelay mission had a single \var{.moos} mission
configuration file, with a single \app{MOOSDB} and two \app{pXRelay}
apps.

\begin{figure}[H]
  \centering
  \includegraphics[width=0.45\textwidth]{figures/xrelay_single.png}
  \caption{The original xrelay mission contained a single
    \aapp{MOOSDB} with two \aapp{pXRelay} applications uniquely
    named.}
\label{fig_xrelay_single}
\end{figure}

\vspace{0.1in}
\noindent
This will be transformed by you into two mission files, each launching a 
single \app{MOOSDB}, each with a unique community name:

\begin{figure}[H]
  \centering
  \includegraphics[width=0.55\textwidth]{figures/xrelay_double.png}
  \caption{The new xrelay mission contains two \app{MOOSDBs} each with
    their own \aapp{pXRelay} application. The \aapp{pXRelay}
    application does not need to be uniquely named, but the MOOS
    communities are uniquely named.}
\label{fig_xrelay_double}
\end{figure}

\vspace{0.1in}
\noindent
Recall in the earlier XRelay mission, where two versions of
\app{pXRelay} were launched and connected to the same \app{MOOSDB},
each version had to be launched with a unique name, like
\app{pXRelay\_apples}. Since we now will be launching two MOOS
Communities, with one instance of \app{pXRelay} in each community,
each \app{pXRelay} instance can simply remain named \app{pXRelay}.


%------------------------------------------------------------------------
\subsubsection{Split the xrelay Mission up into Two Separate MOOS Communities}

The xrelay mission, as originally configured, has three essential apps
launched.  The \app{MOOSDB}, and two \app{pXRelay} apps. In this
experiment, you will create two \var{.moos} files, each launching a
\app{MOOSDB} and one \app{pXRelay} app. You will also need the \app{pShare}
app launched in each community.

\vspace{0.1in}
\noindent
Note: You will need to configure each \var{.moos} file with a unique
community name (with the \psvar{Community} parameter), and port number
(with the \psvar{ServerPort} parameter).  The \psvar{ServerHost}
parameter can remain \psvar{"localhost"} for now.  Note each of those
pieces of information since you will need it in the configuration of
\app{pShare} in both files.

\vspace{0.1in}
\noindent
Some quick documentation on \app{pShare} can be found by just typing
\var{"pShare --help"} on the command line. Or you can find more
complete documentation here:

\vspace{0.1in}

\urlx{http://oceanai.mit.edu/2.680/oxmoos/pshare.html}

\vspace{0.1in}

\noindent 
Your \app{pShare} configuration block will look something like
(removing the comments of course):

\vspace{0.15in}
\footnotesize
\begin{fileverb}
ServerHost = localhost
ServerPort = 9000                   &lt;-- needs to be unique between files
Community  = apples                 &lt;-- needs to be unique between files

ProcessConfig = pShare
{
  AppTick    = 4
  CommsTick  = 4

  input  = route = localhost:9200    &lt;-- needs to be unique between files

  output = src_name=APPLES, route=localhost:9201
}
\end{fileverb}
\normalsize
\vspace{0.1in}

\noindent
Note that the port on which \app{pShare} is listening is not the same
port on which the \app{MOOSDB} is serving. And remember that the same
share configuration will not work for both sides. They must complement
each other, in terms of the variable name being shared, the share
input route, the destination host IP and port number. The following
figure may help:

\vspace{0.15in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.99\textwidth]{figures/xrelay_share.png}
  \caption{The new xrelay mission needs to have \aapp{pShare}
    configured to share the \vvar{APPLES} and \vvar{PEARS} messages
    with complementary configurations.}
\label{fig_xrelay_share}
\end{figure}

%--------------------------------------------------------------------------
\subsubsection{Launch the two communities and confirm that sharing works}

Using perhaps two separate terminal windows, launch both MOOS
communities and confirm that the modified xrelay mission works as
before. You will still need to poke one of the communities to get
things going. Confirm things are working by opening a scope in one of
the communities. Enable the "Community" field on scoped items, either
by launching \app{uXMS} with the \var{--show=community} parameter, or
just toggling this field on with the \var{'c'} key after \app{uXMS} is
launched. You should see postings from both the local community, and
the second remote community.

\vspace{0.1in}
\noindent
If things are not working, consider the following trouble-shooting points:

\begin{packed_itemize}
\item Make sure the port specified in the share input route on each
  side matches the destination port on the other, and vice versa.

\item Make sure the port numbers used are not the same as the
  \app{MOOSDB} port numbers.

\item Make sure the \app{MOOSDB} port numbers are unique, like
  \var{9000} and \var{9001}.  This is the \var{ServerPort} parameter
  in the \var{.moos} file.

\item Try just poking with \app{uPokeDB} to test the sharing. For
  example, poking \msvar{APPLES=99} in the community that is
  configured to export the the \msvar{APPLES} variable, and opening a
  scope in the destination community.
\end{packed_itemize}

%=======================================================================
\subsection{Assignment 2 (self check off) - The Alpha pShare Mission}
\label{sec_one_alpha}

In this part we will:
\begin{packed_itemize}
  \item Prepare a copy of the alpha mission for experimenting.
  \item Create two \var{.moos} files to launch two \app{MOOSDB}
    processes.
  \item Implement the Alpha mission with two MOOS communities using \app{pShare}.
  \item Launch the two communities and confirm that sharing works.
\end{packed_itemize}

%--------------------------------------------------------------------
\subsubsection{Make a Copy of the Alpha Mission}

The first step is to copy the alpha example mission from the moos-ivp
class tree into your own \var{moos-ivp-extend} tree.

\begin{consoleverb}
 $ cp -rp moos-ivp/ivp/missions/s1_alpha  moos-ivp-janedoe/missions/lab_06/alpha_pshare
\end{consoleverb}
\postverb

\noindent
You won't be handing this in, but it's not a bad idea to check it in
under your version control system.


%---------------------------------------------------------------------
\subsubsection{Split the Alpha Mission Into Two Separate MOOS Communities}

In this step you will create two separate MOOS communities: a {\em
  shoreside} community and an {\em alpha} vehicle community, by
creating two separate .moos files.  In the shoreside community there
will be a \app{MOOSDB} and \app{pMarineViewer}. In the alpha community
will be a \app{MOOSDB} and everything but \app{pMarineViewer}. In both
communities you will also need to add a \app{pShare} configuration
block and add \app{pShare} to the \app{Antler} configuration block.

\vspace{0.1in}
\noindent
The primary challenge here is to consider which variables to configure
for sharing in each direction. One hint is that, from the vehicle to
the shoreside you will need to share the \msvar{NODE\_REPORT}. This is
the message generated from \app{pNodeReporter} containing much of the
vehicle state, and used by \app{pMarineViewer} to render the
vehicle. It is generated locally on the vehicle as
\msvar{NODE\_REPORT\_LOCAL} and should arrive in the shoreside as
\msvar{NODE\_REPORT}.  The configuration in alpha's \app{pShare}
config block will look something like:

\prevblue
\begin{verbatim}
  output = src_name=NODE_REPORT_LOCAL, dest_name=NODE_REPORT, route=localhost:9200
\end{verbatim}
\postverb

\noindent
You will also want to share the \msvar{VIEW\_POLYGON}, \msvar{VIEW\_SEGLIST} and
\msvar{VIEW\_POINT} variables to enable \app{pMarineViewer} on the
shoreside to have the visual feedback of the vehicle waypoints. What
variables do you need to share from the shoreside to the vehicle?

%-----------------------------------------------------------------------------
\subsubsection{Launch the Two Communities and Confirm that Sharing Works}

Using perhaps two separate terminal windows, launch both MOOS
communities and confirm that the modified Alpha mission works as
before. You still should be able to deploy and return the vehicle with
the buttons in \app{pMarineViewer}.  Consider what is being poked when
hitting those buttons. You can always find this out by looking at the
\app{pMarineViewer} configuration block in the mission file. Or,
recent versions of \app{pMarineViewer}, you can hover your mouse over
each button, and after a second a small pop-up window will appear
showing which variables are being poked with that button.  Make sure
those variables are being properly shared to the alpha vehicle
community.

\vspace{0.1in}
\noindent
If things are not working, consider the following trouble-shooting points:

\begin{packed_itemize}[2]
\item Make sure the port specified in the share input route on each
  side matches the destination port on the other, and vice versa.
\item Make sure the port numbers used are not the same as the
  \app{MOOSDB} port numbers.
\item Try just poking with \app{uPokeDB} to test the sharing. For
  example, poking \msvar{DEPLOY=true} in the shoreside community, and
  opening a \app{uXMS} scope in the destination (alpha) community.
  Even easier: use the realmcasting interface built into
  \app{pMarineViewer} as of 2022, to verify that messages like
  \mvar{DEPLOY} are being shared from shore to the vehicle. Ask a TA
  for help if haven't used the realmcasting utility yet.
  
\item You should see a vehicle in the \app{pMarineViewer} window even
  before deploying the vehicle. If you don't check the \app{pShare}
  configuration on the vehicle side.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The result should look just like the basic alpha mission from Lab 1,
but, under the hood, things are just running in two separate MOOS
communities:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/Alpha.png}
  \caption{The Alpha mission.}
  \label{fig_alpha_video}
  \urlvideo{https://vimeo.com/84549446}{0:19}
\end{figure}
\vspace{0.1in}


%=======================================================================
\section{Instructions for Handing In Assignments}
%=======================================================================

%=======================================================================
\subsection{Requested File Structure}
\label{sec_hand_in}

You are encouraged to continue to upload all mission files.  Here is
the requested file structure:

\vspace{0.1in}
\begin{consoleverb}
  moos-ivp-extend/
    missions/
      lab_06/
        xrelay_pshare/              // Assignment 1 - self check off
        alpha_pshare/               // Assignment 2 - self check off
        alpha_bravo_pshare/         // Assignment 3 - check off
        henry_gilda_baseline/       // Assignment 4 - self check off
        henry_gilda_refuel/         // Assignment 5 - self check off
        henry_gilda_auto_refuel/    // Assignment 6 - check off
\end{consoleverb}
\vspace{0.1in}

\end{document}



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