\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.Lab05IntroMultiVehicle} \wikidoc{auth=mikerb@mit.edu} %=================================================================== % Build the Cover Page in an environment style easy for wiki parsing \begin{labcover} \labtitle{Lab 5 - Simulation of Multi-Vehicle Deployments} \vspace{0.1in} %\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications} \vspace{0.15in} \labpng{0.7}{figs_common/header.png} \vspace{0.15in} \labdate{Nov 17-21, 2025} \vspace{0.1in} \labauth{Michael Benjamin, mikerb@mit.edu} \labauth{Dept of Mechanical Engineering, 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 this lab we shift focus to autonomy configurations involving multiple vehicles. Ultimately the inter-\app{MOOSDB} or inter-vehicle communication may come over an 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. \vspace{0.1in} \noindent 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 Converting the Alpha Mission to use a Shoreside / Vehicle Topology \item Converting the Alpha Mission to a Two-Vehicle Mission with \app{pShare} \item Using the uField Toolbox to Ease \app{pShare} Configuration \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{s15\_alpha\_pshare}: By copying \var{s1\_alpha} (from moos-ivp/ivp/missions) \item \var{s16\_alpha\_pshare}: By copying \var{s15\_alpha\_pshare} \item \var{s17\_henry\_gilda\_baseline}: By copying \var{s17\_henry\_gilda\_baseline} (from moos-ivp/ivp/missions-minicourse) \item \var{s18\_henry\_gilda\_refuel}: By copying \var{s17\_henry\_gilda\_baseline} \item \var{s19\_henry\_gilda\_auto\_refuel}: By copying \var{s18\_henry\_gilda\_refuel} \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} %========================================================================== \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 workshop. \vspace{0.15in} \begin{figure}[H] \centering \includegraphics[width=0.65\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. %======================================================================= \subsection{Exercise 1 - 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 directory. \begin{consoleverb} $ cp -rp moos-ivp/ivp/missions/s1_alpha s15_alpha_pshare \end{consoleverb} \postverb %--------------------------------------------------------------------- \subsubsection{Split the alpha mission 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. \vspace{0.1in} \noindent 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, or by hovering your mouse over the button.) Make sure those variables are being properly shared to the alpha vehicle community. \vspace{0.1in} \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 \var{s1\_alpha} mission, but, under the hood, things are just running in two separate MOOS communities: \vspace{0.1in} \begin{figure}[H] \centering \includegraphics[width=0.92\textwidth]{figures/Alpha.png} \caption{The Alpha mission.} \label{fig_alpha_video} \gif{educlips/gifs/Alpha.gif} \end{figure} \vspace{0.1in} %============================================================================= \subsection{Exercise 2 - 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-Community Alpha mission} The first step is to copy the alpha example mission from the exercise in the previous Section. The file structure should be, calling it \var{s16\_alpha\_bravo\_pshare}. %------------------------------------------------------------------------- \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. \vspace{0.1in} \noindent 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} YYour 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.92\textwidth]{figures/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} \gif{figures/lab_07_alpha_bravo_pshare.gif} % \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. \vspace{0.1in} \noindent 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{Exercise 3 - The Henry Gilda Baseline Mission} In this part we will: \begin{packed_itemize} \item Copy the baseline mission from the moos-ivp/ivp/missions-minicourse 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 repo: \begin{consoleverb} $ cp -rp moos-ivp/ivp/missions-minicourse/lab_henry_gilda_baseline s_17_henry_gilda_baseline \end{consoleverb} \noindent 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.92\textwidth]{figures/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 \app{pShare} connections. \url{https://vimeo.com/87907093}{0:20}} \label{fig_henry_gilda_baseline} \gif{figures/henry_gilda_baseline.gif} \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.01in} \begin{consoleverb} $ nsplug -h $ nsplug -m | less \end{consoleverb} \vspace{0.01in} \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! \vspace{0.1in} \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. \vspace{0.1in} \noindent 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{Exercise 4 - The Henry Gilda Refuel Mission} Copy your "Henry Gilda Baseline" mission from the previous exercise to create a new mission folder: \begin{consoleverb} $ cp -rp s17_henry_gilda_baseline s18_henry_gilda_refuel \end{consoleverb} \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. \vspace{0.1in} \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.92\textwidth]{figures/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. \url{https://vimeo.com/87950212}} \label{fig_henry_gilda_refuel} \gif{educlips/gifs/lab_07_henry_gilda_refuel.gif} \end{figure} %====================================================================== \subsection{Exercise 5 - 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} $ cp -rp s18_henry_gilda_refuel s19_henry_gilda_auto_refuel \end{consoleverb} \vspace{0.1in} \noindent 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. \vspace{0.1in} \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} \vspace{0.1in} \noindent It should look something like the video posted at: \begin{figure}[H] \centering \includegraphics[width=0.92\textwidth]{figures/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. \url{https://vimeo.com/87958055}} \label{fig_henry_gilda_auto_refuel} \gif{educlips/gifs/lab_07_henry_gilda_auto_refuel.gif} \end{figure} %====================================================================== \newpage \section{Where to Find the Solutions} %====================================================================== All solutions can be downloaded from the MIT OceanAI server as below, after the course is completed. 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} \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: Alpha pShare} Get the whole folder with: \begin{consoleverb} $ wget https://oceanai.mit.edu/minicourse-pisa/missions/s15_alpha_pshare.tar \end{consoleverb} %====================================================================== \subsection{Solutions to Exercise: Alpha Bravo pShare} Get the whole folder with: \begin{consoleverb} $ wget https://oceanai.mit.edu/minicourse-pisa/missions/s16_alpha_bravo_pshare.tar \end{consoleverb} %====================================================================== \subsection{Solutions to Exercise: Henry Gilda Baseline} Get the whole folder with: \begin{consoleverb} $ wget https://oceanai.mit.edu/minicourse-pisa/missions/s17_henry_gilda_baseline.tar \end{consoleverb} %====================================================================== \subsection{Solutions to Exercise: Henry Gilda Refuel} Get the whole folder with: \begin{consoleverb} $ wget https://oceanai.mit.edu/minicourse-pisa/missions/s18_henry_gilda_refuel.tar \end{consoleverb} %====================================================================== \subsection{Solutions to Exercise: Henry Gilda Auto Refuel} Get the whole folder with: \begin{consoleverb} $ wget https://oceanai.mit.edu/minicourse-pisa/missions/s19_henry_gilda_auto_refuel.tar \end{consoleverb} \end{document}