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

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 09 - Introduction to Constrained}
\vspace{0.1in}
\labtitle{Inter-Vehicle Messaging}
\vspace{0.1in}
\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.3in}
\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}
\vspace{0.2in}
\labtoc{small}
\end{labcover}

%===================================================================
% Add a blank page so first body page is on the right when doubleside
\blankpage
%========================================================================
\newpage \section{Overview and Objectives}
\label{sec_overview}

The focus of today's lab is an introduction to inter-vehicle messaging, 
focusing first on messaging in simulation. This will be used in our next
lab on autonomous collaborative search. In the lab just prior to Spring
Break the focus will be on inter-vehicle messaging using acoustic modems.
In today's lab, two MOOS apps, used for the first time in our labs, will 
be our focus:

\vspace{0.1in}
\begin{packed_itemize}[2]
\item \app{uFldMessageHandler} - A MOOS handler for incoming message
  from other vehicles.
\item \app{uFldNodeComms} - A MOOS shoreside arbiter of inter-vehicle
  messages.
\end{packed_itemize}
%\vspace{0.1in}

\noindent
A summary of today's topics:

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Introduction to the uField Toolbox Inter-Vehicle Messaging Apps
\item Implement basic messaging in a two-vehicle example
\item Range-limited inter-vehicle messaging
\item Recovering from an messaging out-of-range situation
\end{packed_itemize}
\end{labinfo}


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

%=======================================================================
\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*     clean.sh      docs/         missions/ 
 README          build/      data/         lib/          scripts/      src/
\end{consoleverb}

\noindent
For each distinct assignment in this lab, there should be a
corresponding subdirectory in a \var{lab\_09} 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 Monday's class: \newline 
  \urlx{http://oceanai.mit.edu/2.680/docs/2.680-09-collab_search.pdf}

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

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

\end{itemize}


%======================================================================
\newpage 
\section{Inter-Vehicle Messaging}
\label{sec_msg}
%======================================================================

The exercise in today's lab involves inter-vehicle messaging. Since
inter-vehicle messaging is a component of following labs, we isolate
this issue first with today's lab. The goal will be to construct a two
vehicle mission where each vehicle is loitering in a pattern on the
west and east side of an operation area respectively. Each vehicle
will periodically send the other vehicle a message containing a new
latitude (Y value in local coordinates) to shift its loiter pattern.

\pskip

The primary new modules being used in this lab are the
\app{uFldMessageHandler} and \app{uFldNodeComms} modules. See today's
(lecture 09) class notes for a description, and see the MOOS-IvP Tools
documentation available on the course website for full
documentation. The figure below from today's lecture illustrates the
basic setup. The focus today is on these two modules.

\begin{figure}[H]
  \centering
  \includegraphics[width=0.6\textwidth]{figures/ufmh_topology.png}
  \caption{{\bf The uFldMessageHandler and uFldNodeComms Modules:} The
    \app{uFldMessageHandler} runs on each vehicle and parses incoming
    \mvar{NODE\_MESSAGE} postings. The \app{uFldNodeComms} module
    runs on the shoreside and routes messages to their destination
    vehicle(s).}
\label{fig_msg_overview}
\end{figure}


%======================================================================
\newpage 
\section{Assignment 1 (self check off) - The Charlie Dana Baseline Mission}
\label{sec_baseline}
%======================================================================

Our first step is to get and run the baseline mission we will be starting from
in this lab. Get a copy and put it in your new \var{lab\_09} folder.

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp/ivp/missions-2680
 $ cp -rp lab_09_charlie_dana_baseline moos-ivp-janedoe/missions/lab_09/charlie_dana_baseline
\end{consoleverb}
\vspace{0.1in}

\noindent
This mission is configured for two vehicles, \var{charlie} and \var{dana}, each
doing a simple loiter mission with the ability to return and station-keep at
any time. It should contain nothing you have not seen before in prior labs. It
should be launchable with 

\vspace{0.1in}
\begin{consoleverb}
 $ cd charlie_dana_baseline
 $ ./launch.sh 15
\end{consoleverb}
\vspace{0.1in}

\noindent
It is our starting point for this lab, and should look something like
the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_09_charlie_dana_baseline.png}
  \caption{A simple two-vehicle baseline mission with both vehicles loitering at
    a fixed location.}
  \label{fig_charlie_dana_baseline}
  \urlvideo{https://vimeo.com/88522655}{0:18}
\end{figure}

%======================================================================
\newpage 
\section{Assignment 2 (self check off) - The Charlie Dana NodeComms Mission}
\label{sec_nodecomms}
%======================================================================

The next step is to augment your baseline mission to support
inter-vehicle communications. The first key addition is the module
\app{uFldNodeComms} which runs on the shoreside and accepts node
reports from all connected vehicles.  To get started, make a copy of
your baseline mission into a folder called
\var{charlie\_dana\_nodecomms}.

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-janedoe/missions/lab_09
 $ cp -rp charlie_dana_baseline  charlie_dana_nodecomms
\end{consoleverb}
\vspace{0.1in}

\noindent
The first step is to add a \app{uFldNodeComms} to your \app{pAntler}
configuration block in \var{meta\_shoreside.moos}:


\vspace{0.1in}
\begin{fileverb}
ProcessConfig = ANTLER
{
  MSBetweenLaunches = 100

  Run = MOOSDB          @ NewConsole = false
  Run = pMarineViewer   @ NewConsole = false
  Run = pLogger         @ NewConsole = false
  Run = uXMS            @ NewConsole = false
  Run = uProcessWatch   @ NewConsole = false
  Run = pShare          @ NewConsole = false
  Run = pHostInfo       @ NewConsole = false
  Run = uFldShoreBroker @ NewConsole = false
  Run = uFldNodeComms   @ NewConsole = false   &lt;-- Add this line (but not this comment)
}
\end{fileverb}
\vspace{0.1in}

\noindent
The next step is to add a \app{uFldNodeComms} configuration block also to the
\var{meta\_shoreside.moos} configuration file. You are encouraged to take a 
read through the \app{uFldNodeComms} documentation to know more about the 
below parameters, but here is an example configuration block:

\vspace{0.1in}
\begin{fileverb}
 ProcessConfig = uFldNodeComms
 {
   AppTick    = 2
   CommsTick  = 2
 
   comms_range      = 120
   min_msg_interval = 15
   max_msg_length   = 1000 
 
   view_node_rpt_pulses = true
 }
\end{fileverb}
\vspace{0.1in}

\noindent
The key parameter initially is the \pvar{comms\_range} parameter. Setting this
value here to 120 means that any two vehicles must be within 120 meters of one
another in order for an inter-vehicle message to go through. The other parameters
limit the message frequency and length, and the last parameter affects whether
visual artifacts are also produced by \app{uFldNodeComms} when it is running. 
Once you have these changes in place, re-launch the mission.

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-janedoe/missions/lab_09/charlie_dana_nodecomms
 $ ./launch.sh 15
\end{consoleverb}
\vspace{0.1in}

\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_09_charlie_dana_nodecomms.png}
  \caption{A simple two-vehicle baseline mission with both vehicles
    loitering at a fixed location, and inter-vehicle communications
    supported with uFldNodeComms running. The colored cones between
    vehicles indicate the vehicles are within comms range of each
    other.}
  \label{fig_charlie_dana_nodecomms}
  \urlvideo{https://vimeo.com/88540265}{0:21}
\end{figure}


%======================================================================
\newpage 
\section{Assignment 3 (check off) - The Charlie Dana Message Mission}
\label{sec_message}
%======================================================================

The next step is to augment your mission to test inter-vehicle
communications. The first key addition is the module \app{uFldMessageHandler} 
which runs on each of the vehicles and accepts node messages from other
vehicles. To get started, you can make a copy of your previous mission into
a folder called \var{charlie\_dana\_message}.

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-janedoe/missions/lab_09
 $ cp -rp charlie_dana_nodecomms  charlie_dana_message
\end{consoleverb}
\vspace{0.1in}

\noindent
The first step is to add a \app{uFldMessageHandler} to your \app{pAntler}
configuration block in \var{meta\_vehicle.moos}:

\vspace{0.1in}
\begin{fileverb}
ProcessConfig = ANTLER
{
  MSBetweenLaunches = 100

  Run = MOOSDB           @ NewConsole = false
  Run = uProcessWatch    @ NewConsole = false
  Run = pShare           @ NewConsole = false
  Run = uSimMarine       @ NewConsole = false
  Run = pLogger          @ NewConsole = false
  Run = pNodeReporter    @ NewConsole = false
  Run = pMarinePID       @ NewConsole = false
  Run = pHelmIvP         @ NewConsole = false
  Run = pHostInfo        @ NewConsole = false
  Run = uFldNodeBroker   @ NewConsole = false
  Run = uFldMessageHandler @  NewConsole = false   &lt;-- Add this line (but not this comment)
}
\end{fileverb}
\vspace{0.1in}

\noindent
The next step is to add a \app{uFldMessageHandler} configuration block
also to the \var{meta\_vehicle.moos} configuration file. You are
encouraged to take a read through the \app{uFldMessageHandler} if you
have time, but here is an example configuration block:

\vspace{0.1in}
\begin{fileverb}
 ProcessConfig = uFldMessageHandler
 {
   AppTick    = 2
   CommsTick  = 2
 
   strict_addressing = false
 }
\end{fileverb}
\vspace{0.1in}

\noindent
The \pvar{strict\_addressing} configuration parameter indicates
whether incoming messages need to be addressed strictly to the named
vehicle or whether messages sent to "all" vehicles will also be
accepted. We leave it set to false so both kinds of messages are
accepted. You can also put the above configuration block into a
\var{plug\_uFldMessageHandler.moos} file and \var{\#include} it in the
\var{meta\_vehicle.moos} file, but either way is fine for now.

\pskip

The last step is to share outgoing vehicle messages, generated on a
vehicle, to the shoreside for distribution to other vehicles. To do
this, the \var{plug\_uFldNodeBroker.moos} file needs to be augmented:

\vspace{0.1in}
\begin{fileverb}
  BRIDGE = src=VIEW_POINT
  BRIDGE = src=VIEW_SEGLIST
  BRIDGE = src=APPCAST
  BRIDGE = src=NODE_REPORT_LOCAL, alias=NODE_REPORT
  BRIDGE = src=NODE_MESSAGE_LOCAL,  alias=NODE_MESSAGE  &lt;-- Add this line (but not this comment)
\end{fileverb}
\vspace{0.1in}
  
\noindent
Once you have these changes in place, re-launch the mission.

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-janedoe/missions/lab_09/charlie_dana_message
 $ ./launch.sh 15
\end{consoleverb}
\vspace{0.1in}

\noindent
At this point, the vehicles are ready to send messages between each
other, but nothing is happening yet.

\pskip

How does charlie, meaning to be send a message to dana, initiate this
message? Charlie posts to its MOOSDB, an outgoing message in the
variable \mvar{NODE\_MESSAGE\_LOCAL}. As described in the
\app{uFldMessageHandler} documentation, this message has four main
components:

\begin{packed_itemize}[1]
\item \var{src\_node}: The name of the vehicle originating the
  message, in this case charlie.

\item \var{dest\_node}: The name of the vehicle for which the message is intended
  to be sent, in this case dana.

\item \var{var\_name}: Name of the MOOS variable we want written in the receiving
  vehicle's MOOS community. In this case the variable name is \msvar{UP\_LOITER}
  because each vehicle is running with a loiter behavior configured with 
  \bsvar{updates=UP\_LOITER} to accept dynamic behavior parameter changes. See
  the loiter configuration block inside \var{meta\_vehicle.bhv}.

\item \var{string\_val}: The contents of the MOOS variable when posted in the 
  receiving vehicle's MOOS community. In this case we use \var{string\_var} to 
  indicate we are posting a string rather than a double. And in this case we are
  passing a new loiter y-position to the receiving vehicle. The parameter
  \bvar{ycenter\_assign} is a defined parameter for the loiter behavior, meant just
  for these situations.
\end{packed_itemize}
\vspace{0.1in}

\noindent
So, the outgoing node message will have the following four components:

\begin{packed_itemize}[1]
\item \var{src\_node=charlie}
\item \var{dest\_node=dana}
\item \var{var\_name=UP\_LOITER}
\item \var{string\_val=ycenter\_assign=-50}
\end{packed_itemize}
\vspace{0.1in}

\noindent
If you'd like to poke the loiter change {\em directly} into dana, try this:

\vspace{0.1in}
\begin{consoleverb}
 $ uPokeDB targ_dana.moos UP_LOITER=ycenter_assign=-50
\end{consoleverb}
\vspace{0.1in}

\noindent
To simulate a message going from charlie to dana (the goal/criteria of this
assignment), poke charlie with an outgoing message formed as above:

\vspace{0.1in}
\begin{consoleverb}
 $ uPokeDB targ_charlie.moos NODE_MESSAGE_LOCAL="src_node=charlie,dest_node=dana,
           var_name=UP_LOITER,string_val=ycenter_assign=-50"
\end{consoleverb}
\vspace{0.1in}

\noindent
Keep a command window open and try poking the above message
alternating between -50 and -100 for the new y-loiter position for
dana. It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_09_charlie_dana_message.png}
  \caption{A simple two-vehicle baseline mission with both vehicles
    loitering at a fixed location, and inter-vehicle communications
    supported with uFldNodeComms running. A message is periodically sent from
    charlie to dana, indicated by the brief white comms cone between the 
    two vehicles. When they are outside of comms range, no colored comms cones
    rendered, there are no inter-vehicle messages.}
  \label{fig_charlie_dana_message}
  \urlvideo{https://vimeo.com/88569374}{0:29}
\end{figure}

%======================================================================
\newpage 
\section{Assignment 4 (check off) - The Charlie Dana ReAssign Mission}
\label{sec_reassign}
%======================================================================

We augment the previous mission where messages were sent by poking the
MOOSDB on the sender vehicle. In this mission, messages originate from
both vehicles automatically with a simple timer script to re-assign the
location of the other vehicle. To get started, make a copy of your
previous mission into a folder called \var{charlie\_dana\_nodecomms}.

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-janedoe/missions/lab_09
 $ cp -rp charlie_dana_message  charlie_dana_reassign
\end{consoleverb}
\vspace{0.1in}

\noindent
The first step is to add a timer script to your vehicles.  The timer
script essentially does the same thing you did manually by poking the
MOOSDB in the Charlie Dana Message mission. A script should be
added to your mission by creating a \var{plug\_uTimerScript.moos} file
and including this plug in your \var{meta\_vehicle.moos} file.

\vspace{0.1in}
\begin{fileverb}
ProcessConfig = uTimerScript
{
  AppTick    = 2
  CommsTick  = 2

  condition  = DEPLOY=true
  randvar    = varname=YPOS, min=-125, max=0, key=at_reset

  // THE BELOW EVENT ALL ON ONE LINE IN THE ACTUAL MOOS FILE

  event      = var=NODE_MESSAGE_LOCAL, val="src_node=$(VNAME),dest_node=all,
               var_name=UP_LOITER,string_val=ycenter_assign=$[YPOS]", time=60:90

  reset_max = nolimit
  reset_time = all-posted
}
\end{fileverb}
\vspace{0.1in}

\noindent
A re-assign message is periodically sent to the other
vehicle. Actually with the syntax above, the message is sent to "all"
other vehicles, but in our simple example there is only one other
vehicle, and \app{uFldMessageHandler} and \app{uFldNodeComms} prevent
messages from being sent back to the sender. The additional condition of
\pvar{DEPLOY=true} is meant to prevent the re-assigning from happening until
the vehicles are deployed.

\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_09_charlie_dana_reassign.png}
  \caption{The same simple two-vehicle baseline mission with both
    vehicles loitering, initially at a fixed location.  Inter-vehicle
    communications is supported with \app{uFldNodeComms} and
    \app{uFldMessageHandler} running. A message is periodically sent
    from charlie to dana, and vice versa, indicated by the brief white
    comms cone between the two vehicles. Each message re-assigns the
    other vehicle to a different loiter location either a little bit
    north or south of its present position.  When they are outside of
    comms range, with no colored comms cones rendered, there are no
    inter-vehicle messages.}
  \label{fig_charlie_dana_reassign}
  \urlvideo{https://vimeo.com/88640064}{0:52}
\end{figure}

%======================================================================
\newpage 
\section{Assignment 5 (check off extra credit) - The Charlie Dana Recover Mission}
\label{sec_recover}
%======================================================================

In the previous mission, Charlie Dana ReAssign, note that it is possible that
the two vehicles re-assign each other to be perpetually out of comms range with
one another. Once they are out of comms range, they never change their loiter
position to get back into comms range. You may even notice that this almost happens
right at the start of the example video in Figure \ref{fig_charlie_dana_reassign}. 
Charlie is loitering in the north-west, and dana in the south-east but dana just
manages to squeeze out a message to charlie. 

\pskip

The challenge is to come up with ways to recover from this scenario of
being outside of comms range. How can it be detected? What can be done
to recover?  One way to recover is to have both vehicles return home,
and re-connect this way.  But can you do better? Can this be done
without writing a new MOOS App? (Disclosure - I have not implemented
my own solution for this, so there is no particular answer I'm looking
for. But there are perhaps several ways to mitigate this problem.)

\pskip

Note that you can make the problem situation a bit more likely to
occur, for the sake of efficient testing, if you shrink the comms
range by reducing \pvar{comms\_range=120} in the \app{uFldNodeComms}
configuration block. Or you can expand the possible loiter locations
to the north and south by adjusting the \pvar{randvar} parameter
in the \app{uTimerScript} configuration on the vehicles.


%=======================================================================
\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_09/
        charlie_dana_baseline/      // Assignment 1 - self check off
        charlie_dana_nodecomms/     // Assignment 2 - self check off
        charlie_dana_message/       // Assignment 3 - check off
        charlie_dana_reassign/      // Assignment 4 - check off
        charlie_dana_recover/       // Challenge Problem - check off (EXTRA CREDIT)
\end{consoleverb}
\vspace{0.1in}


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

This lab should be completed prior to lab on Thursday March 23rd, 2017.

\end{document}


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