\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=MCA.Lab06IntroMessaging} \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{Nov 17-21 2025} \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} \vspace{0.1in} \noindent In this lab, several new missions will be created. As in the previous lab, each mission will begin by copying a previous similar mission and modifying from that starting point. Each mission folder will contain an \var{alpha.moos} and \var{alpha.bhv} file. In this lab we will create the following missions: \begin{packed_itemize} \item \var{s20\_charlie\_dana\_baseline}: By copying \var{lab\_charlie\_dana\_baseline} (from moos-ivp/ivp/missions-minicourse) \item \var{s21\_charlie\_dana\_nodecomms}: By copying \var{s20\_charlie\_dana\_baseline} \item \var{s22\_charlie\_dana\_message}: By copying \var{s21\_charlie\_dana\_nodecomms} \item \var{s23\_charlie\_dana\_reassign}: By copying \var{s22\_charlie\_dana\_message} \end{packed_itemize} %======================================================================= \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*{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. \vspace{0.1in} \noindent 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 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 $ 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 <-- 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 <-- 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. \vspace{0.1in} \noindent 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 <-- 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. \vspace{0.1in} \noindent 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{consoleverb} 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{consoleverb} \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 the Figure above. Charlie is loitering in the north-west, and dana in the south-east but dana just manages to squeeze out a message to charlie. \vspace{0.1in} \noindent 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? \vspace{0.1in} \noindent 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 oceanai course server as below after the course is over. Two utilities are needed for retrieving solution tar files. The \cmd{wget} and \cmd{tar} commands. The latter is in virtually all Linux and MacOS intalls. The former can be obtained for free using you package manager, e.g., \cmd{apt} in Linux, and \cmd{brew} in MacOS. %====================================================================== \subsection{Solutions to Exercise: Charlie Dana Baseline Mission} Get the whole folder with: \begin{consoleverb} $ wget https://oceanai.mit.edu/minicourse-pisa/missions/s20_charlie_dana_baseline.tar \end{consoleverb} %====================================================================== \subsection{Solutions to Exercise: Charlie Dana NodeComms Mission} Get the whole folder with: \begin{consoleverb} $ wget https://oceanai.mit.edu/minicourse-pisa/missions/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 https://oceanai.mit.edu/minicourse-pisa/missions/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 https://oceanai.mit.edu/minicourse-pisa/missions/s23_charlie_dana_reassign.tar \end{consoleverb} \noindent (The \app{uTimerScript} 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}