<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
% Include common packages, environments, counters etc
\input{./common_latex/common_latex_packages}
\input{./common_latex/common_latex_lab_format}
\input{./common_latex/common_latex_definitions}
%===================================================================

\begin{document}
\wikidoc{file=MiniCourse.IntroMessaging}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 06 - Introduction to Constrained}
\vspace{0.1in}
\labtitle{Inter-Vehicle Messaging}
\vspace{0.1in}
\labpng{0.75}{figs_common/header.png}
%\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.3in}
\labdate{August 14-15 2024}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Dept of Mechanical Engineering, 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

%===================================================================
% Begin the body of the text
%===================================================================
\newpage
\section{Overview and Objectives}
\label{sec_overview}

The focus of this lab is an introduction to inter-vehicle messaging,
focusing first on messaging in simulation. In this 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}

%=======================================================================
\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 Messaging lecture: \newline 
  \urlx{http://oceanai.mit.edu/tx/lecture_06.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}


%======================================================================
\subsection*{Inter-Vehicle Messaging}
\label{sec_msg}
%======================================================================

The exercises in this lab involve inter-vehicle messaging.  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 the
lecture slides for a description, and see the MOOS-IvP Tools
documentation available on the \urlx{http://oceanai.mit.edu/ivpman}
website for full documentation. The figure below illustrates the basic
setup. The focus in this lab 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{Exercises}
\subsection{Exercise 1 - The Charlie Dana Baseline Mission}
\label{sec_baseline}
%======================================================================

The 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 local folder.

\vspace{0.1in}
\begin{consoleverb}
 $ cd &lt;your lab exercice folder&gt;
 $ cp -rp moos-ivp/ivp/missions-minicourse/lab_charlie_dana_baseline s20_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 s20_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:

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

%======================================================================
\newpage 
\subsection{Exercise 2 - 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{s21\_charlie\_dana\_nodecomms}.

\vspace{0.1in}
\begin{consoleverb}
 $ cp -rp s20_charlie_dana_baseline  s21_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 s21_charlie_dana_nodecomms
 $ ./launch.sh 15
\end{consoleverb}
\vspace{0.1in}

\noindent
It should look something like:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/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. \url{https://vimeo.com/88540265}}
  \label{fig_charlie_dana_nodecomms}
  \gif{educlips/gifs/lab_09_charlie_dana_nodecomms.gif}
  %\urlvideo{https://vimeo.com/88540265}{0:21}
\end{figure}


%======================================================================
\newpage 
\subsection{Exercise 3 - 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}
 $ cp -rp s21_charlie_dana_nodecomms  s22_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 s22_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 exercise), 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:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/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. \url{https://vimeo.com/88569374}}
  \label{fig_charlie_dana_message}
  \gif{educlips/gifs/lab_09_charlie_dana_message.gif}
  %\urlvideo{https://vimeo.com/88569374}{0:29}
\end{figure}

%======================================================================
\subsection{Exercise 4 - 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}
 $ cp -rp s22_charlie_dana_message  s23_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:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/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. \url{https://vimeo.com/88640064}}
  \label{fig_charlie_dana_reassign}
  \gif{educlips/gifs/lab_09_charlie_dana_reassign.gif}
  %\urlvideo{https://vimeo.com/88640064}{0:52}
\end{figure}

%======================================================================
\subsection{Exercise 5 (bonus!) - 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?

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

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

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

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

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

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

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


%======================================================================
\subsection{Solutions to Exercise: Charlie Dana Baseline Mission}

Get the whole folder with:

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

%======================================================================
\subsection{Solutions to Exercise: Charlie Dana NodeComms Mission}

Get the whole folder with:

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

\noindent
(The \app{uFldNodeComms} app added.)


%======================================================================
\subsection{Solutions to Exercise: Charlie Dana Message Mission}

Get the whole folder with:

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

\noindent
(The \app{uFldMessageHandler} app added to each vehicle. Messaging done
via \app{uPokeDB} to either the source vehicle, or receiving vehicle
directly. Mods to \app{uFldNodeBroker} bridging to accommodate the message.)

%======================================================================
\subsection{Solutions to Exercise: Charlie Dana Message Re-Assign}

Get the whole folder with:

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

\noindent
(The \app{uTimeScript} app added to each vehicle. Messaging done
on a fixed schedule to a randomly chosen Y location. At some point
vehicles will get out of range for talking to each other.)


\end{document}


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