<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=MiniCourse.IntroMultiVehicle}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 5 - Simulation of Multi-Vehicle Deployments}
\vspace{0.1in}
%\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.15in}
\labpng{0.7}{figs_common/header.png}
\vspace{0.15in}
\labdate{August 14-15, 2024}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Dept of Mechanical Engineering, 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 this lab we shift focus to autonomy configurations involving
multiple vehicles.  Ultimately the inter-\app{MOOSDB} or inter-vehicle
communication may come over a 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 Converting the Alpha Mission to use a Shoreside / Vehicle Topology
\item Converting the Alpha Mission to a Two-Vehicle Mission with pShare
\item Using the uField Toolbox to Ease pShare Configuration
\end{packed_itemize}
\end{labinfo}

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

%=======================================================================
\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}.
\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 See the slides from the accompanying lecture which give a bit more
  background into marine autonomy and the IvP Helm: 
  \urlx{http://oceanai.mit.edu/pavlab/pdfs_txt/lecture_05.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}

%==========================================================================
\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 workshop.

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

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

In the first exercise in today's 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 .moos files. In later missions, we will be
using components of the uField Toolbox to automatically configure the 
share configurations.

%=======================================================================
\subsection{Exercise 1 - 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 .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 directory. 

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


%---------------------------------------------------------------------
\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\_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 by
hovering your mouse over the button.) Make sure those variables are
being properly shared to the alpha vehicle community.

\pskip
\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 scope in the destination (alpha) community.
\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 \var{s1\_alpha} mission, 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]{figures/Alpha.png}
  \caption{The Alpha mission.}
  \label{fig_alpha_video}
  \gif{educlips/gifs/Alpha.gif}
%  \urlvideo{https://vimeo.com/84549446}{0:19}
\end{figure}
\vspace{0.1in}


%=============================================================================
\subsection{Exercise 2 - The Alpha Bravo pShare Mission}

In this part we will:
\begin{packed_itemize}[2]
  \item Prepare a copy of the previous modified alpha mission for experimenting.
  \item Create a third .moos file, bravo.moos, to launch another simulated vehicle.
  \item Launch the three communities and confirm that sharing works, and deploy
    and return commands work for both vehicles with a single \app{pMarineViewer} button
    click.
\end{packed_itemize}

%-----------------------------------------------------------------------------
\subsubsection{Make a Copy of the Previous Two-MOOS-Community Alpha mission}

The first step is to copy the alpha example mission from the previous
exercise in Section \ref{sec_one_alpha}.  The file structure should
be, calling it \var{s16\_alpha\_bravo\_pshare}.

%-------------------------------------------------------------------------
\subsubsection{Create a New bravo.moos File for Simulating a Second Vehicle}

In this step you will create a third mission file, \var{bravo.moos},
for simulating a second vehicle. In the \var{bravo.moos} file, you
will need to configure it with a distinct community name, e.g.,
bravo, distinct port number, and distinct port number for UDPListen in the
\app{pShare} configuration block. 

\pskip
A \var{bravo.bhv} file will also need to be created for this
vehicle. The behavior mission is not the point of focus here, so just
create a waypoint survey mission similar to alpha's with the vertices
shifted 50 meters to the east, and 20 meters to the south. Shift the
bravo vehicle's starting position 50 meters to the east (in the
\app{uSimMarine} configuration block).  The \var{shoreside.moos} will
also need to be altered to share the \msvar{DEPLOY} and \msvar{RETURN}
commands out to both vehicles with a single button click.


%------------------------------------------------------------------------
\subsubsection{Launch the Three Communities and Confirm Things Work}

YYour final mission configuration should meet the following criteria:

\begin{packed_enumerate}[2]
  \item You should be able to launch both vehicles and the shoreside
    community with a single shell script.
  \item You should be able to deploy and return both vehicles with a
    single button click in \app{pMarineViewer}.
  \item The vehicles and the mission waypoints for both vehicles
    should be viewable in \app{pMarineViewer}.
  \item Your \app{pMarineViewer} should also be configured to deploy
    or return a single chosen vehicle in isolation. Hint: use the
    \psvar{actions} parameter in \app{pMarineViewer} to add
    deploy-alpha, return-bravo etc. capability in the Action pull-down
    menu.
\end{packed_enumerate}

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{figures/lab_07_alpha_bravo_pshare.png}
  \caption{AS simple two-vehicle mission connecting to vehicle communities, and a 
    shoreside community, using pShare.}
  \label{fig_alpha_bravo_pshare}
  \gif{figures/lab_07_alpha_bravo_pshare.gif}
  %  \urlvideo{https://vimeo.com/87900172}{0:21}
\end{figure}


%========================================================================
\newpage 
\section{Using the uField Toolbox to Facilitate Multi-Vehicle Simulations}
%========================================================================

In the next exercise, the goal is to create an autonomy mission that
uses a few modules in the uField Toolbox to replace some of the
\app{pShare} configuration steps used in the previous exercise. Our
end goal is a two vehicle simulation that should be easily scalable to
a larger number of vehicles.

\pskip

Once we have the multi-vehicle simulation established, our goal in the
next section will be to build a mission where two simulated vehicles
are receiving points in the x-y plane, from the shoreside community,
and traversing those points in a shortest-path trajectory.

%========================================================================
\subsection{Exercise 3 - The Henry Gilda Baseline Mission}

In this part we will:
\begin{packed_itemize}
  \item Copy the baseline mission from the moos-ivp/ivp/missions-minicourse folder.
  \item Note the structure of the launch script and the nsplug setup.
  \item Note the roles of \app{uFldShoreBroker}, \app{uFldNodeBroker},
    and \app{pHostInfo}.
\end{packed_itemize}


%------------------------------------------------------------------------
\subsubsection*{Copy the baseline mission from the moos-ivp tree}

Start by copying a baseline version of the mission from the moos-ivp MIT
2.680 mission tree:

\vspace{0.1in}
\begin{consoleverb}
 $ cp -rp moos-ivp/ivp/missions-minicourse/lab_henry_gilda_baseline s_17_henry_gilda_baseline
\end{consoleverb}
\vspace{0.1in}

\noindent
If you don't see the \var{lab\_07\_henry\_gilda\_baseline} folder, or
even the \var{missions-2680}, try doing and svn update. Confirm that
the mission launches properly by typing \var{./launch.sh 10} from the
command line in your newly created folder. You should see two vehicles
appear on the screen.  Deploy them with the \var{DEPLOY} button, and
return them with the \var{RETURN} button.  At any time you can
station-keep them by hitting the \var{STATION} button. The vehicle
should automatically enter the station keeping mode upon returning.

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{figures/lab_07_henry_gilda_baseline.png}
  \caption{A simple two-vehicle mission connecting two loitering
    vehicle communities, and a shoreside community, using the uField
    Toolbox utilities for coordinating the pShare connections.
    \url{https://vimeo.com/87907093}{0:20}}
  \label{fig_henry_gilda_baseline}
  \gif{educlips/gifs/lab_07_henry_gilda_baseline.gif}
%  \urlvideo{https://vimeo.com/87907093}{0:20}
\end{figure}


%--------------------------------------------------------------------
\subsubsection*{Understand the Launch Structure}

Before moving on, take a look at how things are launched. See if you
can understand what is going on inside the launch script. Note that
the script is building the target \var{.moos} files by invoking an
application called \cmd{nsplug}. This tool is a bit like the \cmd{cpp}
pre-processor. It takes as an argument a file which can be thought of
as a template of sorts, and produces another file with components of
the template filled in. We use it so we can have just {\em one}
mission and behavior file for both vehicles, with just a few of the
details such as vehicle name, start position and MOOS community values
filled in at launch time.  You can learn a bit more about \cmd{nsplug}
by:

\vspace{0.1in}
\begin{consoleverb}
 $ nsplug -h
 $ nsplug -m | less
\end{consoleverb}
\vspace{0.1in}

\noindent
Note that the \var{targ\_*} files are generated automatically each time the 
launch script is invoked. If you edit these files, the changes will be lost 
the next time you launch!

\pskip
\noindent
Note that the launch script defines certain variables such as the
vehicle name, \app{MOOSDB} port etc., and passes this info into
\cmd{nsplug} for expansion.

%-------------------------------------------------------------------
\subsubsection*{Understand the uField Toolbox Operations}

Before moving on, take a look at the relationship between
\app{pHostInfo}, \app{uFldNodeBroker} and \app{uFldShoreBroker}. Note
how they handle the \app{pShare} configuration for you on both ends. From
this point forward, using these tools, your configuration of share
variables should be handled in this way. Please read the sections on
these three applications in the uField Toolbox documentation on the
course website.

\pskip

For now, beginning with this baseline mission, share configuration
will just work. But you {\em will} want to augment what is being
shared for later steps in this lab, so try to understand how share
configuration is handled in the \app{uFldNodeBroker} and
\app{uFldShoreBroker} modules.

%======================================================================
\subsection{Exercise 4 - The Henry Gilda Refuel Mission}

Copy your "Henry Gilda Baseline" mission from the previous exercise to
create a new mission folder:

\vspace{0.1in}
\begin{consoleverb}
 $ cp -rp s17_henry_gilda_baseline  s18_henry_gilda_refuel
\end{consoleverb}
\vspace{0.1in}

\noindent
Augment this mission to accept a shoreside "refuel" command from a new
\app{pMarineViewer} button. When the refuel command is given, the
vehicle returns to its launch point, but automatically enters a new
"refueling" mission mode while station keeping, for 60 seconds, and
then automatically resumes loitering. 

\pskip
\noindent
To accomplish this mission you will need to:

\vspace{0.1in}
\begin{packed_itemize}[1]
\item Add a new refuel button to the \app{pMarineViewer} configuration
  that accepts a refueling command by posting
  \msvar{REFUEL\_NEEDED\_ALL=true}.

\item Make sure this variable is shared out to all vehicles by
  augmenting the \app{uFldShoreBroker} configuration block in the
  \var{meta\_shoreside.moos} file.

\item (Remember - don't edit the \var{targ\_*} files since these are
  auto-generated in the launch process and will be overwritten each
  time the mission is launched!)

\item Add a new Timer behavior in the vehicle behavior configuration
  file that begins each time the vehicle returns for refueling, waits
  60 seconds, and then posts endflags that result in the vehicle
  resuming its loiter missions. The vehicle should {\em automatically}
  go back to loitering after the timer ends.

\item Station keeping should still work at any time, if commanded by
  the user.

\item The vehicle may still be returned with the \var{RETURN} button,
  but when returned in this way, it acts as it did in the baseline
  mission - it station keeps and remains station keeping indefinitely
  until re-deployed.
\end{packed_itemize}

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{figures/lab_07_henry_gilda_baseline.png}
  \caption{The Henry Gilda Refuel mission has two loitering vehicles. When the
    user commands the vehicles to return, they return to their starting point 
    and station keep for 60 seconds and automatically re-deploy afterwards.
    As with the baseline mission, both vehicles have their own MOOS community, 
    connected to a shoreside community, with the connections coordinated 
    using the uField Toolbox utilities. \url{https://vimeo.com/87950212}}
  \label{fig_henry_gilda_refuel}
  \gif{educlips/gifs/lab_07_henry_gilda_refuel.gif}
  %\urlvideo{https://vimeo.com/87950212}{0:40}
\end{figure}


%======================================================================
\subsection{Exercise 5 - The Henry Gilda Auto Refuel Mission}

Copy your "Henry Gilda Refuel" mission from the previous assignment to
create a new mission folder:

\vspace{0.1in}
\begin{consoleverb}
 $ cp -rp s18_henry_gilda_refuel  s19_henry_gilda_auto_refuel
\end{consoleverb}
\vspace{0.1in}

Augment this mission such that (a) the vehicles automatically initiate
the refueling after a fixed time "no-refuel-needed" interval (use 300
seconds for testing), (b) the so-called "no-refuel-needed" time
duration is paused whenever the vehicle is in the station keeping
mode. Presumably because no fuel is being expended. (c) the
hierarchical mode structure has an explicit "refueling" mode while
refueling.

\pskip
\noindent
To accomplish this mission you will need to:

\vspace{0.1in}
\begin{packed_itemize}[1]
\item Add a new Timer behavior in vehicle behavior configuration file
  that begins when the mission begins and counts down until re-fueling
  is needed. It should post end-flags that trigger a mode change and
  the process of returning for re-fueling.  It should be re-set after
  re-fueling is complete (it will need to have the \bvar{perpetual}
  parameter set to true).

\item As before, station keeping should still work at any time, if commanded
  by the user. The need-to-refuel timer should also be paused when or if the
  vehicle is station-keeping.

\item (Remember - don't edit the \var{targ\_*} files since these are
  auto-generated in the launch process and will be overwritten each
  time the mission is launched!)
\end{packed_itemize}

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering
  \includegraphics[width=0.99\textwidth]{figures/lab_07_henry_gilda_baseline.png}
  \caption{The Henry Gilda Refuel mission has two loitering
    vehicles. When the user commands the vehicles to return, they
    return to their starting point and station keep for 60 seconds and
    automatically re-deploy afterwards.  As with the baseline mission,
    both vehicles have their own MOOS community, connected to a
    shoreside community, with the connections coordinated using the
    uField Toolbox utilities. \url{https://vimeo.com/87958055}}
  \label{fig_henry_gilda_auto_refuel}
  \gif{educlips/gifs/lab_07_henry_gilda_auto_refuel.gif}
%  \urlvideo{https://vimeo.com/87958055}{0:47}
\end{figure}


%======================================================================
\newpage
\section{Where to Find the Solutions}
%======================================================================

All solutions can be downloaded from the MIT OceanAI server as below. Two
utilities are needed for retrieving solution tar files. The \cmd{wget}
and \cmd{tar} commands.

\vspace{0.1in}
\noindent
The \cmd{wget} utility is a readily available in package in both
GNU/Linux and MacOS:

\begin{consoleverb}
 $ sudo apt-get install wget  (GNU/Linux)
 $ sudo port install wget     (MacOS)
\end{consoleverb}

\vspace{0.1in}
\noindent
The \cmd{tar} utility is very likely native to your machine. To {\em untar}
a tar file into a folder:

\begin{consoleverb}
 $ tar xvf example_folder.tar
 $ ls
 $ example_folder.tar  example_folder/
\end{consoleverb}


%======================================================================
\subsection{Solutions to Exercise: Alpha pShare}

Get the whole folder with:

\begin{consoleverb}
 $ wget http://oceanai.mit.edu/mc/s15_alpha_pshare.tar
\end{consoleverb}

%======================================================================
\subsection{Solutions to Exercise: Alpha Bravo pShare}

Get the whole folder with:

\begin{consoleverb}
 $ wget http://oceanai.mit.edu/mc/s16_alpha_bravo_pshare.tar
\end{consoleverb}


%======================================================================
\subsection{Solutions to Exercise: Henry Gilda Baseline}

Get the whole folder with:

\begin{consoleverb}
 $ wget http://oceanai.mit.edu/mc/s17_henry_gilda_baseline.tar
\end{consoleverb}

%======================================================================
\subsection{Solutions to Exercise: Henry Gilda Refuel}

Get the whole folder with:

\begin{consoleverb}
 $ wget http://oceanai.mit.edu/mc/s18_henry_gilda_refuel.tar
\end{consoleverb}

%======================================================================
\subsection{Solutions to Exercise: Henry Gilda Auto Refuel}

Get the whole folder with:

\begin{consoleverb}
 $ wget http://oceanai.mit.edu/mc/s19_henry_gilda_auto_refuel.tar
\end{consoleverb}





\end{document}


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