<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_packages}
\input{../../common_latex_lab_format}
\input{../../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 7 - Simulation of Multi-Vehicle Deployments}
\vspace{0.1in}
\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.15in}
\vspace{0.15in}
\labdate{Spring, 2018}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Henrik Schmidt, henrik@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 today's lab we will begin shifting our focus to autonomy
configurations involving multiple vehicles. 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 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.

\pskip

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
\item Hand-in assignment: A Distributed Traveling Salesman Problem
\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
 $ svn update
\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}
Updating '.':
At revision 6168.
\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.MachineSetup}

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

As with previous labs, we will use your version of the \var{moos-ivp-extend} tree, 
which by now you should have re-named something like \var{moos-ivp-janedoe}, where
your email may be \var{janedoe@mit.edu}. In this tree, there is a missions folder:

\begin{consoleverb}
 $ cd moos-ivp-janedoe
 $ 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\_07} 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}.
\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 today's 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-multiv-autonomy.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.

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

\pskip

\noindent
As the very first step, we begin by updating the moos-ivp tree and
making sure we have the very latest build from the class SVN branch:

\begin{consoleverb}
 $ cd moos-ivp
 $ svn update
 Updated to revision 6993.
 $ ./build-ivp.sh
\end{consoleverb}

\noindent
Assuming there were no problems with the update and build, we're ready to go.

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

In this lab we will mostly be building and modifying mission files
rather than writing source code.  The first step is to copy the xrelay
example mission from your \var{moos-ivp-extend} tree in your own
moos-ivp-extend tree. This tree by now should be re-named something
like \var{moos-ivp-janedoe} where your MIT email is
\var{janedoe@mit.edu}.  

\begin{consoleverb}
 $ cp -rp moos-ivp/ivp/missions/xrelay  moos-ivp-janedoe/missions/lab_07/xrelay_pshare
\end{consoleverb}

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


%------------------------------------------------------------------------
\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 .moos files, each launching a
\app{MOOSDB} and one 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 .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
pShare in both files.

\pskip
\noindent
The \app{pShare} application is a relatively new application
distributed with MOOS, only available since November 2012. It is a
replacement for the \app{pMOOSBridge} application with new valuable
capabilities such as dynamic (run-time) configurations.  Some quick
documentation can be found by just typing \var{"pShare --help"} on the
command line. Or you can find more complete documentation here:

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

\vspace{0.1in}

\noindent 
Your \app{pShare} configuration block will look something like:

\vspace{0.15in}
\footnotesize
\begin{Verbatim}[frame=single]
ServerHost = localhost
ServerPort = 9000
Community  = apples

ProcessConfig = pShare
{
  AppTick    = 4
  CommsTick  = 4

  input  = route = localhost:9200

  output = src_name=APPLES, route=localhost:9201
}
\end{Verbatim}
\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. Note that "Community" field on scoped items now. You
should see postings from both the local community, and the second
remote community.

\pskip
\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 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 .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 moos-ivp-extend tree. 

\begin{consoleverb}
 $ cp -rp moos-ivp/ivp/missions/s1_alpha  moos-ivp-janedoe/missions/lab_07/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 up 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.

\pskip
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). 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 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}


%=============================================================================
\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.
  \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 previous
exercise in Section \ref{sec_one_alpha}.  The file structure should
be:

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

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.
  \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_07_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 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{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 moos-ivp tree:

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp/ivp/missions-2680
 $ cp -rp lab_07_henry_gilda_baseline moos-ivp-janedoe/missions/lab_07/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]{educlips/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.}
  \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.

\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{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-janedoe/missions/lab_07/
 $ 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 \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]{educlips/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.}
  \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-janedoe/missions/lab_07/
 $ 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 (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}[1]

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

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/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.}
  \label{fig_henry_gilda_refuel}
  \urlvideo{https://vimeo.com/87958055}{0:47}
\end{figure}


%=======================================================================
\section{Assignment 7 (check off and hand in) - Distributed Traveling Salesman}
%=======================================================================

The Travelling Salesman Problem (TSP) is the problem of finding a path to visit
a set of cities, with known distances between any two cities, in such a way as to
visit every city at least once and to minimize the total distance travelled. In 
this section we use the TSP problem to exercise our new skills in deploying
multiple vehicles to handle a version of the TSP problem - the Distributed TSP
problem. Given a set of points to visit, assign the points to a set of vehicles
to visit those points. Since optimal TSP algorithms can be quite involved, we
simplify things a bit and allow for non-optimal shortest tour distances while
focussing on the mechanics of getting multiple cooperating vehicles running.

\pskip
\noindent
In this part we will:
\begin{packed_itemize}
  \item Create a \app{uTimerScript} script to generate 100 random points in
    a specified region.
  \item Create a \app{pPointAssign} MOOS module on the shoreside to
    send half the points to one vehicle and half to the other.
  \item Create \app{pGenPath} MOOS module on the vehicle side. It should
    subscribe for the points coming from \app{pPointAssign} on the
    shoreside, generate a sequence of waypoints, and then send them to
    the vehicle awaiting the points.
  \item Configure an autonomy mission on the vehicle to traverse the points
    while periodically returning to home.
\end{packed_itemize}

%=======================================================================
\subsection{Create a uTimerScript Script for Generating Visit Points}

Configure a \app{uTimerScript} script running on the shoreside
community, to generate a random sequence of points within a region of
the operation area. This region should be:

\vspace{0.03in}
\footnotesize
\begin{verbatim}
  -25,-25
  -25,-175
  200,-25
  200,-175
\end{verbatim}
\normalsize
\vspace{0.03in}

\noindent
The script should generate 100 postings to the \app{MOOSDB} of the form:

\prevgreen
\begin{verbatim}
  VISIT_POINT = x=8,   y=9,  id=1
  VISIT_POINT = x=33,  y=29, id=2
  ...
  VISIT_POINT = x=-11, y=-9, id=100
\end{verbatim}
\postverb

\noindent
The first posting in the script should be
\msvar{VISIT\_POINT="firstpoint"}.  The last posting in the script
should be \msvar{VISIT\_POINT="lastpoint"}.  These are the cues to
recipients to indicate completeness of the set of points posted. The
id values don't need to be perfectly in order, but should just be
unique. 

\vspace{0.1in}
\noindent
HINT: Consult the example script in the \app{uTimerScript}
documentation in the example "A Script for Generating 100 Random
Numbers" in the "Examples" section. The \app{uTimerScript}
documentation is found:

\vspace{0.1in}
\noindent
\urlx{http://oceanai.mit.edu/ivpman/apps/uTimerScript}


%=======================================================================
\subsection{Create shoreside pPointAssign MOOS app for distributing points}

Create a new \app{pPointAssign} MOOS application on the shoreside to send
half the points to one vehicle and half to the other. The app should have
the following capabilities:

\begin{packed_itemize}[1]

\item The app should subscribe to the \msvar{VISIT\_POINT} output of
  the timer script and produce output along the lines of:

\prevgreen
\begin{verbatim}
  VISIT_POINT_HENRY = x=8,   y=9,   id=1
  ...
  VISIT_POINT_HENRY = x=33,  y=29,  id=50
  VISIT_POINT_GILDA = x=19,  y=111, id=51

  VISIT_POINT_GILDA = x=-11, y=-9,  id=100
\end{verbatim}
\postverb

\item The first and last postings made by \app{pPointAssign}, shared
  to each of the vehicles, should be
  \msvar{VISIT\_POINT\_VNAME="firstpoint"} and
  \msvar{VISIT\_POINT\_VNAME="lastpoint"}.  These are the indicators
  usable on the vehicle that confirm that the complete set of visit
  points have been sent and received.  The component \var{VNAME} above
  should be replaced by the vehicle name and there should be one such
  posting per vehicle.

\item The app should have a configuration parameter, \pvar{vname}, which adds
  a known vehicle to the list of vehicles to which points will be distributed.

\item Your app should support the assignment of points in one of two
  manners.  In the first manner, points are assigned in an alternating
  fashion. The first point to the first vehicle, second point to the
  second vehicle, third point to the first vehicle and so on. In the
  second manner, points are assigned according to region, e.g.,
  east-west. The app should be configurable to either way with a
  configuration parameter \pvar{assign\_by\_region} set to either true
  or false. You can see the difference in the two videos shown in 
  Section \ref{sec_tsp_runs}.
\end{packed_itemize}

\noindent
You also need to share \app{pPointAssign} postings out to their
respective vehicles. For example you may want to share
\msvar{VISIT\_POINT\_HENRY} out to vehicle {\em henry} with the
arrival name \msvar{VISIT\_POINT}. Remember that you should handle the
share configuration with \app{uFldShoreBroker} now - not \app{pShare}.

\vspace{0.1in}
\noindent
HINT/WARNING: Recall that the MOOSDB only keeps track of the {\em most
  recent} value of a variable. When a new app connects and registers
for mail, it will get only the latest value, not the entire
history. Keep in mind that your \app{pPointAssign} app needs {\em all}
the output of your timer script producing points. For this reason you
will want to ensure that the script starts {\em after}
\app{pPointAssign} has connected to the MOOSDB.  Consider launching
the time script in a paused mode, where it gets automatically
un-paused by the actions of \app{pPointAssign}. See the
\pvar{pause\_var} and \pvar{paused} configuration parameters for
\app{uTimerScript}.

%=======================================================================
\subsection{Create a vehicle pGenPath MOOS App for traversing points }

Create a new \app{pGenPath} MOOS module for running on the vehicle,
that takes as input a series of \msvar{VISIT\_POINT} messages from the
shoreside, and generates a waypoint list suitable for consumption by
the waypoint behavior.

\pskip

\noindent
In your behavior configuration, use a Waypoint behavior with an
\bvar{updates} parameter specifying the MOOS variable used for incoming
dynamic parameter configuration. In this case, the primary incoming
configuration will be the list of waypoints from your \app{pGenPath}
module. To make things a bit easier, your shortest path algorithm may
simply be a greedy shortest path with an imaginary virtual initial
point being the vehicle's present position.

\pskip

\noindent
In your \app{pGenPath} module you can use the following pseudo code as
guidance for how to build a proper list of waypoints recognized by the
waypoint behavior:

\vspace{0.1in}
\footnotesize
\begin{verbatim}
  XYSegList my_seglist;
  my_seglist.add_vertex(3, 8);
  my_seglist.add_vertex(43, 99);
  my_seglist.add_vertex(44, -111);
  
  string update_str = "points = ";
  updates_str      += my_seglist.get_spec();
  Notify("UPDATES_VAR", update_str);  // UPDATES_VAR depends on your config
\end{verbatim}
\normalsize


\vspace{0.1in}
\noindent
If your application uses the \var{XYSegList} class (recommended), your
app must link against the {\em geometry} library.  You will need to
edit the \var{CMakeLists.txt} file in your \app{pGenPath} application
folder.  In this file, simply add \var{geometry} in the
\var{TARGET\_LINK\_LIBRARIES} block.

%=======================================================================
\subsection{Mission Constraints}

\begin{packed_itemize}
\item {\em Maximum vehicle speed}: The vehicle may go no faster than 1.2 meters/sec.
\item {\em Tour Duration}: The vehicle may be underway no longer than
  10 minutes (600 seconds) before re-fueling will be required. To simplify things, 
  you need not include the time required to return to home in this time limit.
\item {\em Refuel Duration}: Once the vehicle has returned home, it must wait at
  least 60 seconds before resuming its mission.
\end{packed_itemize}


%=======================================================================
\subsection{Handling and Re-visiting Missed Points}

You may find that the tour generated by a greedy algorithm has turns
that the vehicle simply cannot make quickly enough, causing the
vehicle to "miss" a point on the tour. You should use the
\bvar{slip\_radius} parameter (in the Waypoint behavior) with a high
enough number, e.g., 15, such that the vehicle does {\em not} come
back around for missed points.  For our lab, a visit to point is
satisfied if the vehicle comes within three meters of the point.

\pskip

In the {\em next} lab, we will re-design this mission such that, upon
completion of the tour, the \app{pGenPath} app makes a new tour of all
points missed on the previous tour. The \app{pGenPath} app can keep
track of visited points by simply noting the present vehicle position
on each iteration, and comparing it to known points in the tour.  Upon
each completion of a tour, or modified tour, the vehicle should return
home for re-fueling regardless of how long it has been deployed since
the previous re-fueling.

\pskip

For now, in this lab, we won't worry about "missed" points or
re-visiting points on a second tour. We mention this now in case you want
to keep in mind this upcoming challenge in building your \app{pGenPath}
application in this lab.


%=======================================================================
\subsection{Practical Suggestions}

\subsubsection*{Make pGenPath an AppCastingMOOSApp}

In your \app{pGenPath} module, keep records of various state values, e.g., 
number of points received, visited, unvisted etc. Below is the appcast
output of my own implementation. Store and report whatevery helps you 
debug your application.

\vspace{0.1in}
\begin{consoleverb}
===================================================================
pGenPath henry                                            0/0(6011)
===================================================================
Visit Radius:            3
Total Points Received:   55
Invalid Points Received: 0
First Point Received:    true
Last Point Received:     true
NAV_X/Y Received:        true

Tour Status              
------------------------ 
   Points Visited:       55
   Points Unvisited:     0
\end{consoleverb}
\vspace{0.1in}

\subsubsection*{Make pPointAssign an AppCastingMOOSApp}

For the same reasons as above, you may find good appcasting output for
\app{pPointAssign} will help you debug.


\subsubsection*{Use a plug for the pGenPath.moos file}

When you configure this \app{pGenPath} module to run with your
vehicle, create a new \var{plug\_pGenPath.moos} component similar to
the other plugs, and create a new \var{\#include} for this plug in the
\var{meta\_vehicle.moos} file.

%=======================================================================
\subsection{Confirm your mission runs}
\label{sec_tsp_runs}

When your \app{pPointAssign} application is configured to assign points
in an alternating manner as they come in, your mission may look
something similar to the video posted below. Note that in this mission
the vehicle returns to visit points missed on the first tour. You don't need
to be concerned with this aspect of the mission until the next lab. 

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_07_distributed_tsp_one.png}
  \caption{In the First Distributed TSP mission two vehicles are assigned 
    randomly chosen points in the region to visit on a first-come basis.
    Therefore their paths overlap and the mission is somewhat inefficient, but
    at least the same amount of points are assigned to each vehicle.}
  \label{fig_distributed_tsp_one}
  \urlvideo{https://vimeo.com/88013053}{1:52}
\end{figure}

\pskip
\noindent
When \app{pPointAssign} is configured to assign points by region, your
mission may look something like the video posted below.  Note that in
this mission the vehicle returns to visit points missed on the first
tour. You don't need to be concerned with this aspect of the mission
until the next lab.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_07_distributed_tsp_two.png}
  \caption{In the Distributed TSP Two mission two vehicles are
    assigned randomly chosen points in the region based on the section
    of the region.  Therefore their paths do not overlap and the
    mission is somewhat more efficient.}
  \label{fig_distributed_tsp_two}
  \urlvideo{https://vimeo.com/88017560}{2:03}
\end{figure}




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

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

Only Assignment 6 needs to be handed in, but you're welcome to upload
all mission files.  Here is the requested file structure:

\vspace{0.1in}
\begin{consoleverb}
  moos-ivp-johndoe/
    missions/
      lab_07/
        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
        distributed_tsp/            // Assignment 7 - check off and hand in
    src/
      pPointAssign/
      pGenPath/
\end{consoleverb}
\vspace{0.1in}


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

This lab should be handed in prior to next Monday's lab (Mar 16th,
2015). The beginning of the next lab may be used to check off
outstanding components.

\end{document}


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