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

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 8 - Distributed Simulation of Multi-Vehicle Deployments}
\vspace{0.1in}
\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.35in}
\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
%===================================================================
\section{Overview and Objectives}
%===================================================================

In today's lab, our objectives are dependent on your current progress
in implementing the Lab 07 assignments. Depending on where you are in
your work, today's focus will be on:

\vspace{0.1in}
\begin{packed_itemize}[1]
\item Implement the Lab 07 missions, with TA help if need be,
\item Run a simple baseline double-loiter mission over multiple machines,
\item Extend the Lab 07 Distributed TSP mission with re-planning.
\item Run the Distributed TSP mission over multiple machines..
\end{packed_itemize}
\vspace{0.1in}

The goal of the second and fourth items above is to begin migrating
our lab work-flow to making use of an in-lab simulation environment
where individual (or group) autonomy configurations are
demonstrated. In short, the goal is to replace the shoreside MOOS
community you have been running on your laptops with a single
classroom shoreside community to which you connect your simulated
vehicle. This is much closer to the setup that will be used during
experimentation on the river.

\pskip

The goal of the third item above is to gain more familiarity with
behavior configurations and MOOS app development by implementing a
further capability on your current Lab 07 assignment.


\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Experimenting with Distributed Simulation Across Multiple Machines
\item Assignment - Run a Baseline Double Loiter Mission Over Multiple Machines
\item Assignment - Add Re-planning to the Lab 07 Distributed TSP Mission
\item Assignment - Run the Distributed TSP Mission on Multiple Machines
\end{packed_itemize}
\end{labinfo}


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

%=======================================================================
\subsection*{Make Sure Your Machine Hostname is Set}

Make sure your machine hostname is set to a meaningful value. To check your
hostname, run the following from the command line:

\vspace{0.1in}
\begin{consoleverb}
 $ hostname
\end{consoleverb}
\vspace{0.1in}

\noindent
If you're using one of the lab MacBooks, you may be surprised to see it return
a number instead of the lab assigned machine name. If this is the case, set your
hostname to match the name assigned on your machine label using the following 
command:

\vspace{0.1in}
\begin{consoleverb}
 $ sudo scutil --set HostName &lt;your-machine-name&gt;
\end{consoleverb}
\vspace{0.1in}


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

Always make sure you have the latest code:

\begin{consoleverb}
 $ cd moos-ivp
 $ svn update
\end{consoleverb}

\vspace{0.1in}
\noindent
And rebuild if necessary:

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

\pskip
\noindent
\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\_08} 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}

\begin{itemize}

\item The slides from class last Thusday (March 9th 2017): \newline 
  \urlx{http://oceanai.mit.edu/2.680/docs/2.680-07-multiv-autonomy.pdf}

\item The slides from class today Thusday (March 16th 2017): \newline 
  \urlx{http://oceanai.mit.edu/2.680/docs/2.680-09-collab_search.pdf}

\item The uFldNodeBroker documentation \newline
  \urlx{http://oceanai.mit.edu/ivpman/apps/uFldNodeBroker}

\item The uFldShoreBroker documentation \newline
  \urlx{http://oceanai.mit.edu/ivpman/apps/uFldShoreBroker}

\item The pHostInfo documentation \newline
  \urlx{http://oceanai.mit.edu/ivpman/apps/pHostInfo}

\end{itemize}

%===================================================================
\section{Experimenting with Distributed Simulation}

The first exercise in today's lab involves simulation distributed over
more than one machine. Note that in lab 7, the mission configuration
structure began to take the form of (a) single shoreside MOOS
community running \app{pMarineViewer}, and (b) some number of vehicle
communities. All of these communities were still running on a single
machine, e.g., your laptop. When our labs move to the water, this of
course will change, but the logical topology will be the same.  As a
step in this direction, in today's lab we experiment with simulation
distributed over multiple machines.

\vspace{0.15in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.6\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{Assignment 1 (check off) Run the Double-Loiter Mission On Multiple Machines}
%======================================================================

In this part we will:
\begin{packed_itemize}
  \item Obtain a copy of the lab 8 baseline mission configuration.
  \item Confirm that it is runnable on your own machine.
  \item Work with a lab partner to test it over two machines.
\end{packed_itemize}

%======================================================================
\subsection{Obtain a copy of the lab 8 baseline mission configuration}

The first step is to copy the baseline example mission from the moos-ivp
tree and copy it into your own moos-ivp-janedoe tree. 

\vspace{0.1in}
\begin{consoleverb}
 $ mkdir moos-ivp-janedoe/missions/lab_08/
 $ cp -rp moos-ivp/ivp/missions-2680/lab_08_baseline  moos-ivp-janedoe/missions/lab_08/
\end{consoleverb}
\vspace{0.1in}

\noindent
The \var{lab\_08\_baseline} mission files should like:

\vspace{0.1in}
\begin{consoleverb}
 $ ls lab_08_baseline
 clean.sh*                 plug_origin_warp.moos     plug_pShare.moos
 launch_shoreside.sh*      plug_pHelmIvP.moos        plug_uFldNodeBroker.moos
 launch_vehicle.sh*        plug_pHostInfo.moos       plug_uProcessWatch.moos
 meta_shoreside.moos       plug_pLogger.moos         plug_uSimMarine.moos
 meta_vehicle.bhv          plug_pMarinePID.moos
 meta_vehicle.moos         plug_pNodeReporter.moos
\end{consoleverb}


\vspace{0.1in}
\noindent
As with previous missions, the actual mission files are auto-generated
upon executing the launch scripts. Here there are {\em two} launch
scripts - one (\var{launch\_shoreside.sh}) if you are launching the
shoreside community on your machine and serving others, and the other
(\var{launch\_vehicle.sh}) if you are launching a vehicle community
and connecting to a remote shoreside community. Both scripts support
the \var{-h} switch and both support the \var{--just\_build} (or
simply \var{-j}) switch if you want to just build the target files
without actually launching. For example:

\vspace{0.1in}
\begin{consoleverb}
 $ cd lab_08
 $ launch_shoreside.sh --just_build
 $ launch_vehicle.sh --just_build
 $ ls
 clean.sh*                 plug_pHelmIvP.moos        plug_uProcessWatch.moos
 launch_shoreside.sh*      plug_pHostInfo.moos       plug_uSimMarine.moos
 launch_vehicle.sh*        plug_pLogger.moos         targ_janedoe@machinename.bhv
 meta_shoreside.moos       plug_pMarinePID.moos      targ_shoreside.moos
 meta_vehicle.bhv          plug_pNodeReporter.moos   targ_vehicle.moos
 meta_vehicle.moos         plug_pShare.moos
 plug_origin_warp.moos     plug_uFldNodeBroker.moos
\end{consoleverb}

\noindent
Note the three target files newly created. 


%======================================================================
\subsection{Confirm the Baseline Mission is Runnable on a Single Machine}

The goal of this step is to launch two communities with the two
specialized shell scripts provided in the \var{lab\_08} (baseline copy)
mission. Although the intention is that typically you would launch
just one or the other, launching both on the same machine should work
just fine. To to this, first launch the shoreside community with a
time warp of ten:

\vspace{0.1in}
\begin{consoleverb}
 $ ./launch_shoreside.sh 10
\end{consoleverb}
\vspace{0.1in}

\noindent
Then launch a vehicle community with a matching time warp:

\vspace{0.1in}
\begin{consoleverb}
 $ ./launch_vehicle.sh 10
\end{consoleverb}
\vspace{0.1in}

\noindent
In launching the vehicle community as above with no command-line
arguments other than the time warp, defaults are used for the vehicle
name (\var{username@machine}), MOOSDB ServerPort (\var{9001}), and
pShare listen port (\var{9201}). To launch a second or more vehicles,
these arguments need to be provided with different values on the
command line. For example, try launching a second vehicle with:

\vspace{0.1in}
\begin{consoleverb}
 $ ./launch_vehicle.sh --vname=henry --mport=9002 --lport=9202 10
\end{consoleverb}
\vspace{0.1in}

\noindent
It may seem strange that there are two \app{pMarineViewer} communities
launched. But this is more sensible when these two communities are
being launched on separate machines, as intended normally. The {\em
  shoreside} \app{pMarineViewer} will render all vehicles.  The {\em
  vehicle} \app{pMarineViewer} will render just what is known
locally. This may include other vehicles depending on the situation.


%======================================================================
\subsection{Work with a Lab Partner to Launch the Baseline Mission}

In the next step, find a lab partner to work with launching the
baseline mission. Take turns playing the vehicle role and the
shoreside role. If you want to work with multiple partners to launch
several vehicles connected to a single shoreside community, that's
fine too.

\vspace{0.1in}
\noindent
As before, the first step is to launch the shoreside community. Pick a 
desired time warp and inform those connecting with a vehicle of this 
value:

\vspace{0.1in}
\begin{consoleverb}
 $ ./launch_shoreside.sh  &lt;time-warp&gt;
\end{consoleverb}
\vspace{0.1in}

\pskip
\noindent
{\em Noting the shoreside IP address:} To next launch a vehicle
community on another machine, the person launching the vehicle
community needs to know the IP address of the shoreside
community. This can be found many ways but perhaps the easiest is to
just look at the top of the \app{pMarineViewer} window.  Once this is
known, the vehicle community is launched with:

\vspace{0.1in}
\begin{consoleverb}
 $ ./launch_vehicle.sh --shore=&lt;ip-address&gt; --vname=&lt;vname&gt; --mport=&lt;port&gt; 
  --lport=&lt;port&gt; &lt;time-warp&gt;
\end{consoleverb}
\vspace{0.1in}

\noindent
If you are only launching one vehicle per machine, the \var{--vname},
\var{--mport}, and \var{--lport} arguments may be omitted. The
default values will suffice. They only need to be specified to make
sure that when launching more than one vehicle on a single machine
that the vehicle name, MOOSDB port and \app{pShare} input ports are
unique for each machine.

\pskip
\noindent
To know the IP address of the shoreside community, you can look at the top
of the \app{pMarineViewer} window which should show the IP address. If you
are running both the shoreside and vehicle communities on the same subnet then
you may not even need to specify the shore IP address.

\pskip
\noindent
Regarding the network IP address on the two machines, note that it's important 
that either:

\small
\begin{packed_itemize}[2]
  \item Both machines are on the same local network. This is the case
    when the IP address is assigned by a router perhaps in the
    room. In this case the IP address may begin with one of a couple
    special numbers, \var{192.168.x.x}, or \var{10.1.x.x}.
  \item Both machines are on the global network, with an IP address known
    to the rest of the Internet. 
\end{packed_itemize}
\normalsize

\noindent
One way to test your network setup between the two machines is both of you 
are able to ping each other using the \var{ping} command. This utility
is found at \var{/sbin/ping} on most machines. Test the ping in both
directions.

%======================================================================
\section{Assignment 2 (check off) - Add Re-planning to the Distributed TSP Mission}

The next exercise in today's lab is to augment the lab 7 Distributed
TSP mission with a re-planning component. Note that when the vehicle
makes sharp turns, it often "achieves" its next waypoint by a wide
margin. This is due to fortuitous settings of the capture radius and
slip radius parameters in the waypoint behavior.

\pskip

In this exercise, we will define a separate notion of what it means to have
successfully visited a waypoint. We augment the \app{pGenPath} application
to keep track of which points were visited by its own observation and 
criteria for achieving a visit. Once the vehicle has completed its first
pass on the waypoints, it will repeatedly go back to visit waypoints it 
missed the first time.

\vspace{0.1in}
\noindent
Here's what we need to do:

\begin{packed_itemize}[2]
  \item Augment the \var{pGenPath} application to keep track of which
    points a vehicle actually visits. The \var{pGenPath} app may be
    configured with a parameter \pvar{visit\_radius=N}, setting the
    criteria for visiting a waypoint to be within $N$ meters. The
    default should be $5$. (Note the app will have to subscribe to 
    \msvar{NAV\_X} and \msvar{NAV\_Y} if it isn't doing so already.)
  \item Configure your autonomy mission such that when it ends and returns
    to home, it posts a message to \msvar{GENPATH\_REGENERATE}. 
  \item The \app{pGenPath} app registers for this message and regenerates 
    a new path consisting of all the points missed on the previous pass.
  \item Once a new path has been regenerated, the vehicle resumes its
    mission until the new path has been traversed.
  \item The mission continues until there are no points left unvisited
    (as determined by the \app{pGenPath} application).
\end{packed_itemize}
\vspace{0.1in}

\noindent
You can demonstrate this re-planning capability from within the
mission folder you created for Lab 07, or you can create/copy a new
mission folder for Lab 08 and call it
\var{missions/lab\_08/distributed\_tsp\_replan}.


%======================================================================
\section{Assignment 3 (check off) - The Distributed TSP Mission on Multiple Machines}

In this last assignment, the goal is to convert your distributed TSP
mission to be launchable/runnable across separate machines. 

\vspace{0.1in}
\noindent
Here's what we need to do:

\begin{packed_itemize}[2]
  \item Copy the \var{launch\_vehicle.sh} and \var{launch\_shoreside.sh} scripts
    from the baseline mission into your \var{distributed\_tsp\_replan} mission
    folder.
  \item Consider putting a \app{pShare} configuration block like the
    one below into the shoreside configuration. This configuration
    adds the multicast input route which makes it easier for vehicles
    (on the same subnet) to find the shoreside.
\end{packed_itemize}

\vspace{0.1in}
\begin{consoleverb}
 ProcessConfig = pShare
 {
   AppTick    = 2
   CommsTick  = 2
 
   input = route =  localhost:$(SHARE_LISTEN)
 }
\end{consoleverb}
\vspace{0.1in}

\begin{packed_itemize}[2]
  \item Add the following line to the \app{uFldNodeBroker} configuration block
    that indicates the shoreside community may be found at location \var{\$(SHOREIP)},
    listening on port \var{\$(SHORE\_LISTEN)}. The port number has a default
value in the \var{./launch\_vehicle.sh} script of \var{9200}. This can just be
left alone. However, the shoreside IP address is something that needs to be 
typed into the command line, like \var{./launch\_vehicle.sh --shore=128.22.44.22}.
The actual IP address you type is the IP address where the shoreside \app{pMarineViewer}
is running. And if you look at the top of the \app{pMarineViewer} window, you should
see the IP address.


\end{packed_itemize}

\vspace{0.1in}
\begin{consoleverb}
 ProcessConfig = uFldNodeBroker
 {
   ...
   TRY_SHORE_HOST = pshare_route=$(SHOREIP):$(SHORE_LISTEN)
   ...
 }
\end{consoleverb}
\vspace{0.1in}


\noindent
You can demonstrate this replanning capability from with the mission
folder you created for Lab 07, of if you created a new mission folder
for Lab 08, e.g., \var{missions/lab\_08/distributed\_tsp\_replan},
you can use that mission folder. The changes made in this assignment
to run across multiple machines should not break the ability to run
everything on one machine.



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

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

Here is the requested file structure:

\vspace{0.1in}
\begin{consoleverb}
  moos-ivp-janedoe/
    missions/
      lab_08/
        lab_08_baseline/            // Assignment 1 - self check off
        distributed_tsp_replan/     // Assignment 2,3 - check off
\end{consoleverb}
\vspace{0.1in}


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

This lab should be handed in prior to next Tuesday's lab (Mar 21st,
2017). The beginning of the next lab may be used to check off
outstanding components.


\end{document}


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