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

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 6 - 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 27th, 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}
%=======================================================================

This lab assumes the completion of the Lab 6 Pre-Lab Assignment ending
with the self checkoff \var{"Alpha pShare"} mission.

\vspace{0.1in}
\noindent
In this lab we will continue shifting our focus to autonomy
configurations involving multiple vehicles. The first focus, in the
pre-lab, was 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.

\pskip

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

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

%=======================================================================
\subsection*{The MOOS-IvP-2680 Tree}

Starting with this lab, we begin using the additional
\pvar{moos-ivp-2680} tree. In total you will now work with three
trees:

\begin{packed_itemize}
\item \pvar{moos-ivp}: Public autonomy codebase (provided to you)
\item \pvar{moos-ivp-2680}: 2.680 autonomy codebase and baseline
  missions (provided to you)
\item \pvar{moos-ivp-extend}: Student codebase and lab solution
  missions (created by you)
\end{packed_itemize}

\vspace{0.1in}
\noindent
Download this tree onto your computer in the same folder, side-by-side
with \pvar{moos-ivp} and \pvar{moos-ivp-extend}. To download:

\vspace{0.1in}
\begin{consoleverb}
$ git clone git@github.com:mit2680/moos-ivp-2680.git
\end{consoleverb}
\vspace{0.1in}

\noindent
The \pvar{moos-ivp-2680} tree contains both MOOS apps and MOOS
missions useful to 2.680.  In today's lab, content from the
\pvar{moos-ivp-2680/missions} folder will be needed. We don't yet need
any apps, but if you want to add \pvar{moos-ivp-2680/bin} to your
shell path in your \var{.bashrc} file, this is a good move you will
need for later.


%=======================================================================
\subsection*{Make Sure You Have the Latest MOOS-IvP 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{pShare}, or \app{pHelmIvP}.
\item General GNU/Linux commands are represented in \cmd{dark purple},
  such as \cmd{wget}, \cmd{mkdir}, 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 See the slides from class related to multiple vehicles and inter-vehicle
  sharing of information:
  \urlx{http://oceanai.mit.edu/2.680/docs/2.680-07-multiple\_vehicles\_2025.pdf}
\item See 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-08-ivphelm\_behaviors\_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 no 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 consisting 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.

\vspace{0.1in}
\noindent
\urlx{https://www.spiceworks.com/tech/networking/articles/tcp-vs-udp}

\vspace{0.1in}
\noindent
Messages can and will drop when using \app{pShare}. 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. Note: our lab has developed an additional app,
\app{pMediator} for this purpose, but it is in beta mode and not yet
part of the main MOOS-IvP release.


\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{A Very Brief Discussion on Launch Scripts}
%======================================================================
\label{sec_bash}

With multi-vehicle missions hereafter common in this course, we will
make regular use of launch scripts using Bash. You will want to use
these scripts. When baseline missions are provided as part of the lab,
a launch script will be provided.  For multi-vehicle missions meant to
run both on the water and in simulation, multiple nested scripts will
be provided. This may seem initially like an unwelcome additional
layer of complexity, but their utility will soon be
apparent. And they {\em do} make things simpler. Some knowledge of how
they work and how to make modifications will be helpful.

%======================================================================
\subsection{Why Launch Scripts are Used}

A quick review on launching a MOOS community. We {\em could} launch all
applications on the command line, one per terminal window, using something
like

\begin{consoleverb}
$ MOOSDB mission.moos
$ pHelmIvP mission.moos
$ uSimMarine mission.moos
  ...
$ pLogger mission.moos
\end{consoleverb}

\vspace{0.1in}
\noindent
But this would be insane and wouldn't scale, so that's why we have been
using \app{pAntler} instead, with the Antler config block at the top of
the \var{mission.moos} file. So all of the above is replaced with

\vspace{0.1in}
\begin{consoleverb}
$ pAntler mission.moos
\end{consoleverb}
\vspace{0.1in}

\noindent
A similar unscalable situation arises when we are simulating multiple
vehicles alongside a shoreside MOOS community (our Shoreside, a.k.a.,
uField Topology). Launching N vehicles would require:

\vspace{0.1in}
\begin{consoleverb}
$ pAntler shoreside.moos
$ pAntler vehicle1.moos
$ pAntler vehicle2.moos
  ...
$ pAntler vehicleN.moos
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
Although our multi-vehicle missions typically involve only two
vehicles, and we could almost get by with launching like the above, we
do routinely launch as many as 10-50 simulated vehicles in other
projects. Our use of launch scripts makes this easier, and we will use
them even in a two-vehicle-plus-shoreside missions. Although the {\em
  contents} of the script may vary, most multi-vehicle mission folders
simply can be launched with:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch.sh [WARP] [OPTIONS]
\end{consoleverb}

\vspace{0.1in}
\noindent
The arguments surrounded by brackets is common notation for being an
optional argument. The \var{[WARP]} argument is the time warp, which
defaults to 1. The other set of \var{[OPTIONS]} may vary between
launch scripts in different missions, but may include mission
parameters such as the number of vehicles to launch, their speed or
initial placement and so on. Most launch scripts support the
\var{--help} or \var{-h} arguments to see the full list of availble
command line arguments.

%======================================================================
\subsection{Launch Scripts are Bash Scripts}

Our launch scripts are Bash scripts, which is in itself its own sort of
programming language. Bash scripts have the distinct quality that each
line in the script could be something you just typed on the command
line. After all, your command line is a {\em Bash session}. It is possible
that your command line session is using some other shell, like \var{zsh} or
\var{tcsh}. But if you are, it will be very similar. And even if you
are using something different than Bash on your command line, our Bash
scripts always have the first line:

\vspace{0.1in}
\begin{fileverb}
#!/bin/bash
\end{fileverb}

\vspace{0.1in}
\noindent
This indicates that the prevailing shell program, e.g., Bash, will be
exactly Bash, in the form of the executable \var{/bin/bash}, rather
than some other shell program. Note also the location of
\var{/bin/bash}. It is in the top-level folder of your system
(\var{/bin}), which means it is a pretty baked-in utility that came
with your GNU/Linux or MacOS operating system.

%======================================================================
\subsection{Launching MOOS Communities from the Launch Script}

Take a look in the \var{launch.sh} file. It is an "executable" and we
may be accustomed to think of executables as binary files, not human
readable.  But a Bash script is just a text file, and can be opened in
your normal text editor. For the immediate purposes of this lab, most
of this script will be left for explaining later, but we will want to
edit this script to launch {\em three} MOOS communities in the next
exercise. Open the file in a text editor and find the block:

\vspace{0.1in}
\begin{fileverb}
#----------------------------------------------------------
#  Part 3: Launch the processes 
#---------------------------------------------------------- 
echo "Launching $COMMUNITY MOOS Community with WARP:" $TIME_WARP
pAntler $COMMUNITY.moos --MOOSTimeWarp=$TIME_WARP &gt;&amp; /dev/null &amp;

uMAC -t $COMMUNITY.moos
\end{fileverb}


\vspace{0.1in}
\noindent
In the block above, a single MOOS community, whose name is stored
in the variable \var{\$COMMUNITY}, is launched. It is launched using
\app{pAntler} in the background, indicated by the trailing ampersand on
that line. After the MOOS community is launched, the \app{uMAC} utility
is launched to provide an interactive Appcast session from the terminal
window. 

\vspace{0.1in}
\noindent
Modify and expand the above block with the one below, which essentially
does the same thing but launches the shoreside, alpha and bravo communities
with three successive \app{pAntler} calls.

\vspace{0.1in}
\begin{fileverb}
#----------------------------------------------------------
#  Part 3: Launch the processes 
#---------------------------------------------------------- 
echo "Launching All MOOS Communities with WARP:" $TIME_WARP
pAntler shoreside.moos --MOOSTimeWarp=$TIME_WARP &gt;&amp; /dev/null &amp;

pAntler alpha.moos --MOOSTimeWarp=$TIME_WARP &gt;&amp; /dev/null &amp;

pAntler bravo.moos --MOOSTimeWarp=$TIME_WARP &gt;&amp; /dev/null &amp;

uMAC -t shoreside.moos
\end{fileverb}

%======================================================================
\subsection{Bash Script Command Line Arguments}

Bash scripts, like C++ programs, can be built to support command line
arguments.  As a convention in our lab, all \var{launch.sh} scripts
will accept a single numerical argument, interpreted as the time warp
for the mission. Omitting this argument will result in a time warp of
1. For example:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch.sh  10              (launch the mission with time warp 10)
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
Generally speaking, there are two other types of command line
arguments. The simpler of the two involves the detection of an
argument:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch.sh  --verbose       
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
The other type of argument passes a parameter value. For example:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch.sh  --depth_thresh=45  --vehicle_name=henry
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
Command line parsing is generally handle at the outset of the script. Here
is an example block:


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

Before moving on to use the uField Toolbox in the next section, we have
one more mission experimenting with the \app{pShare} utility directly.
Before going much further, it may be a good spot to discuss launch scripts.


%======================================================================
\subsection{Assignment 3 (check off) - 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 (the Alpha pShare Mission from the Pre-Lab).
  \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-Communiity Alpha mission}

The first step is to copy the alpha example mission from the last
exercise from the Pre-Lab.  The file structure should be:

\begin{consoleverb}
 moos-ivp-extend/missions/lab_06/alpha_bravo_pshare
     shoreside.moos
     alpha.moos
     bravo.moos
     launch.sh
     clean.sh
\end{consoleverb}

\vspace{0.1in}
\noindent
You should have a script for launching all three communities.  

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

Your 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 (See section \ref{sec_bash}).
  \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]{educlips/lab_06_alpha_bravo_pshare.png}
  \caption{A simple two-vehicle mission connecting to vehicle
    communities, and a shoreside community, using pShare.}
  \label{fig_alpha_bravo_pshare}
  \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 lab 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{Assignment 4 (self check off) - The Henry Gilda Baseline Mission}

In this part we will:
\begin{packed_itemize}
  \item Copy the baseline mission from the moos-ivp missions-2680 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
\var{moos-ivp-2680} tree:

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-2680/missions
 $ cp -rp lab_06_henry_gilda_baseline moos-ivp-extend/missions/lab_06/henry_gilda_baseline
\end{consoleverb}
\vspace{0.1in}

\noindent
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
\pvar{DEPLOY} button, and return them with the \pvar{RETURN} button.
At any time you can station-keep them by hitting the \pvar{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.6\textwidth]{educlips/lab_06_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.}
  \label{fig_henry_gilda_baseline}
  \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. Also the lecture notes describe how these three applications
work together:

\vspace{0.1in}
\urlx{http://oceanai.mit.edu/2.680/docs/2.680-07-multiple\_vehicles\_2025.pdf}


\vspace{0.1in}
\noindent
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{Assignment 5 (self check off) - The Henry Gilda Refuel Mission}

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

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-extend/missions/lab_06/
 $ cp -rp henry_gilda_baseline   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 \pvar{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.6\textwidth]{educlips/lab_06_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.}
  \label{fig_henry_gilda_refuel}
  \urlvideo{https://vimeo.com/87950212}{0:40}
\end{figure}


%======================================================================
\subsection{Assignment 6 (check off) - 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}
 $ cd moos-ivp-extend/missions/lab_06/
 $ cp -rp henry_gilda_refuel  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 {\bf 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.6\textwidth]{educlips/lab_06_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.}
  \label{fig_henry_gilda_refuel}
  \urlvideo{https://vimeo.com/87958055}{0:47}
\end{figure}


%=======================================================================
\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  (pre-lab)
        alpha_pshare/               // Assignment 2 - self check off  (pre-lab)
        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}


%------------------------------------------------------------------
\subsection{Due Date}

This lab should be completed and ready for demonstration/check-off
by the end of lab Tuesday, March 4th, 2025.

\end{document}



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