\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_memo_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{Missions: Structure, Launching and Killing}
\vspace{0.17in}
\labpng{0.45}{figures/nspatch.png}
\vspace{0.15in}
\labdate{July 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=Memo.NSPatch}
\wikidoc{auth=mikerb@mit.edu}


%====================================================================
\section{MOOS-IvP Missions}
%====================================================================

This document covers the topics related to MOOS-IvP {\em missions}, including:

\begin{packed_itemize}
\item Mission structure in terms file structure and syntax
\item Launching a mission
\item Bringing down (killing a mission)
\end{packed_itemize}

\vspace{0.1in}
\noindent
For the most part these issues are the regardless of the context of the mission
launch. Some common contexts: 

\begin{packed_itemize}
\item A mission for one or more vehicles simulated on a single computer,
\item A mission running on one or vehicles in the physical world with perhaps
  components of the mission running on one or more laptops for command and control,
\item A mission running in simulation with components of the simulations running
  on a set of machines rather than a single laptop.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Under most circumstances a mission is run with some command and
control (C2) capability, enabling a user to have a visual display to
have awareness of vehicle activity, and some mechanisms for injecting
commands to one or more vehicles. However this is not always the case and
introduces another category of mission topics: 
\vspace{0.1in}

\begin{packed_itemize}
\item Missions with one or more computers supporting a C2 GUI for managing a
  mission. 
\item Headless missions that are run without a GUI.
\end{packed_itemize}

\vspace{0.1in}
\noindent
A headless mission is usually launched for the purposes of automatic testing.
They can be invoked by the user directly, or from withing a script, or as part
of a script that is invoked automatically as part of the development process
after each code commit.

\vspace{0.1in}
\noindent
Automated missions are usually one of three flavors:

\begin{packed_itemize}
\item A mission with a defined pass/fail criteria. Such a mission may quickly
  create a prescribed circumstance, check for a desired event, and quit to report
  a pass/fail result.
\item A mission that generates a performance score: Such a mission may have some
  component of randomness in either the starting conditions, or simulated reality,
  e.g., placement of obstacles. It may be left to run for some number of events,
  and will report a score.
\item A mission that oversees a competition between two teams. Such a mission may
  start by picking teams and starting conditions, followed by a competition with
  a defined beginning, end and win/lose criteria, with the resulting winning team
  reported along with score and other aspects of the competion.
\end{packed_itemize}

\noindent
In theh case of {\em automated} missions, the issue of bringing down the mission
apps is critical, to enable a successive launch of a new mission.

\vspace{0.1in}
\noindent
The above topics arise at different stages of working with the MOOS-IvP
software environment. 


%====================================================================
\section{A MOOS Community}
%====================================================================

A MOOS {\em community} is set of MOOS apps connected to a single MOOSDB.
We assume here the reader has some familiarity with the basic functioning
of publish-subscribe within the context of the MOOS middleware. The MOOSDB
is its own process with its own process ID, communicating over a prescribed
port number. A MOOS community can conceptually be viewed in Figure
\ref{fig_moos}.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.45\textwidth]{figs/moos.png}
  \caption{{\bf A MOOS Community}: consists of a MOOSDB with a number
    of MOOS apps connected and communicating with the MOOSDB app.}
  \label{fig_moos}
\end{figure}
\vspace{0.1in}

\noindent
MOOS is sometimes described as a "star" architecture since all apps communicate
with each other through the MOOSDB.

\vspace{0.1in}
\noindent
For now, we'll expand on the above concept diagram in two ways: typically
there is a command and control GUI app connected involved in a mission
and typically there is an IvP Helm as one of the apps. These apps are
\app{pMarineViewer} and \app{pHelmIvP} respectively. Of course, nothing about
the MOOS middleware requires that C2 and autonomy must be these two particular
apps, but these two apps are our baseline. 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.9\textwidth]{figs/moos-ivp.png}
  \caption{{\bf A MOOS Communit with Autonomy and C2}: Two ubiquitous
    apps in the MOOS-IvP ecosystem are \app{pHelmIvP} for autonomy and
    \app{pMarineViewer} for command and control.}
  \label{fig_moos-ivp}
\end{figure}
\vspace{0.1in}

\noindent
A MOOS community comprise of several apps, including the helm with
several behaviors, is configured with a setting contained in two {\em
  mission} files, a MOOS file and a behavior file.  These files
typically have a \var{.moos} and \var{.bhv} suffix respectively.  A
{\em mission folder} is a directory containing these mission
files. For the Alpha mission by example, it contains two files,
\var{alpha.moos} and {\em alpha.bhv}. Both are plain text files,
typically edited through a text file editor, but there may be other
utilities which auto-generate components of the mission files, and
will be discussed later in the document. The behavior file is normally
named as a configuration parameter in the helm configuration block within
the MOOS file. 

%====================================================================
\section{Launching a Mission}
%====================================================================

There are several ways to launch a mission. In each case, the goal is
to launch all processes of the MOOS community, each ingesting the
configuration parameters found in the mission files. When the helm
launches, it will look for the name of the behavior file and will also
read that file. Below are the possible methods. For now we will only
focus on the first two, and after additional discussions on mission
concepts, the other methods will be discussed.

\vspace{0.1in}
\begin{packed_itemize}
\item Each app launched separately from the command line. Almost never used,
  but in isolated cases it can be useful, and at least worth knowing this is
  possible.
\item Using \app{pAntler}. This is the original convenience method distributed
  with MOOS for launching several apps with single stroke of the command line.
  The Alpha mission is launchable in this way. And the more exquisite methods
  of launching all invoke \app{pAntler} as internal steps.
\item Using {\em launch} scripts. These are bash scripts that support
  command line arguments for choosing certain launch parameter
  preferences, avoiding the need to edit the mission files with the
  preference. All multi-vehicle missions use the launch script
  structure, and all launch scripts under the hood will invoke
  \app{pAntler} as the nearly final step.
\item Using an {\em xlaunch} script. This bash script is used for
  automated or headless missions. It will invoke the launch script,
  monitor for for completion of the mission and finally ensure all
  apps have been cleanly executed. It may also invoke post-mission
  scripts to process the logged data of the mission or archive the log
  files and results.
\item Using a {\em batch} script. This script (typically bash but not
  necessarily) will invoke xlaunch several times, perhaps cycling through
  some choices for launch conditions. Example choices could be, the number
  of vehicles, the number of obstacles, the magnitude and direction of
  simulated wind, the max vehicle speed and so on. 
\end{packed_itemize}

%====================================================================
\subsection{Launching a Mission on the Command Line}

All MOOS apps can be launched from the command line individually. For
example the Alpha mission can be launched by opening several terminal
windows, and invoking:

\vspace{0.1in}
\begin{consoleverb}
  $ MOOSDB alpha.moos
  $ pMarineViewer alpha.moos
  $ pHelmIvP alpha.moos
  $ uSimMarineV22 alpha.moos
  $ pMarinePIDV22 alpha.moos
  $ pNodeReporter alpha.moos
\end{consoleverb}
\vspace{0.1in}

\noindent
The MOOSDB and MOOS apps all handle a command line argument ending in
\var{.moos} and ingest the contents of the file looking for
configuration parameters. Parameters are isolated in labeled blocks
dedicated to each app. With six terminal windows open you will see
the terminal/debugging output for each app. Or you can open one
terminal window and launch each in the background with:

\vspace{0.1in}
\begin{consoleverb}
  $ MOOSDB alpha.moos &; pMarineViewer alpha.moos &; pHelmIvP alpha.moos &; \
    uSimMarineV22 alpha.moos &; pMarinePIDV22 alpha.moos &; pNodeReporter alpha.moos &
\end{consoleverb}
\vspace{0.1in}

\noindent
All the same terminal output is generated, but the output of each app will be interleaved
and mixed, making it virtually impossible to use the information.

\vspace{0.1in}
\noindent
We normally will not launch missions like this, for several reasons, but it's good to
know this is possible and keep two things in mind:

\begin{packed_itemize}
\item At times it is useful to launch an app in its own terminal
  window to see the debugging output.
\item Most MOOS apps support command line arguments such as \var{-i}, \var{-e}
  which show the apps interface and example config block respectively. The \var{-w}
  arg will open a web browser to the app's documentation page. The \var{-h} arg
  will show which arguments are supported for that app. Of course when one of
  these args is used, the app will not actually start and connect to the MOOSDB. 
\end{packed_itemize}


%====================================================================
\subsection{Launching a Mission on the Command Line with pAntler}

One of the core apps distributed with MOOS is \app{pAntler}, designed to
launch all apps in a mission with a single command. For the Alpha mission
it would look like:

\vspace{0.1in}
\begin{consoleverb}
  $ pAntler alpha.moos
\end{consoleverb}
\vspace{0.1in}

\noindent
The \app{pAntler} app will look for an \var{ANTLER} configuration block
in the \var{.moos} file, identifying all the apps to be launched. For
the Alpha mission this looks like:

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

  Run = MOOSDB         @ NewConsole = false
  Run = pMarineViewer  @ NewConsole = false
  Run = uSimMarineV22  @ NewConsole = false
  Run = pNodeReporter  @ NewConsole = false
  Run = pMarinePIDV22  @ NewConsole = false
  Run = pHelmIvP       @ NewConsole = false
}
\end{fileverb}
\vspace{0.1in}

\noindent
Each \var{Run} configuration names a MOOS app to launch, while
indicating whether a dedicated terminal window should be opened for
each app (typically not).

\vspace{0.1in}
\noindent
{\bf Note:} Killing \app{pAntler} will result in killing all the
apps that were launched with \app{pAntler}. So, if it is launched
on the command line as above, typing ctrl-c should bring everything
down.

%====================================================================
\subsection{Motivation}

Mission folders are their own complex entity. They contain mission
files for both the robots and the shoreside computer, and launch
scripts for each. In most cases, a mission folder supports the options
for a pure simulation simulation on a single laptop, as well as an
in-water deployment. The \app{nspatch} utility, and it's sister
utility, \app{nsplug}, enable us to dynamically configure a set of
mission files at launch time. This allows us to have virtually
unbounded variations from the same mission folder. 

\vspace{0.1in}
\noindent
On one hand (b) we aspire to have a core set of missions that act as
good examples for users seeking initial understanding of applications
and behaviors, and on the other hand (b) we aspire to build a
substantial body of missions, perhaps in the many hundreds, where each
mission tests and validates a certain code functionality.

\vspace{0.1in}
\noindent


%====================================================================
\subsection{Differences between }




They hold the configuration for
all software modules used in the mission, on both the vehicle and shoreside
computer. Many things need to be set correctly and consistently. The mission
files are 

0. Certain variations only known at run time are accessible through args
1. same for sim and water
2. Mission serve as exemplars and stems


o Want one mission file structure to rule them all (for readability and to
capture all the lessons learned over time.

o Want missions to 

o They suport headless launching for Monte Carlo testing



%====================================================================
\subsection{Mission Structure}

The standard mission structure includes three launch files: 

\begin{packed_itemize}
\item \var{launch.sh}
\item \var{launch\_shoreside.sh}
\item \var{launch\_vehicle.sh}
\end{packed_itemize}

\vspace{0.1in}
\noindent
The first is used when running all components in simulation, and will
invoke the shoreside script once and the vehicle script once for each
vehicle involved in the simulation. The other two scripts are used when
operating on actual robots. The operator will launch the shored from
user station, and the vehicle script will be launched on each robot.
Each script has a number of command-line options that allow the user to
select choice at launch time without needing to edit any other file.

\vspace{0.1in}
\noindent
The mission files for the standard mission include:

\begin{packed_itemize}
\item \var{meta\_shoreside.moos}
\item \var{meta\_vehicle.moos}
\item \var{meta\_vehicle.bhv}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Each of these files contains a general structure with certain
components filled in a launch time. For a three vehicle mission in
simululation with say vehicles \var{"abe"}, \var{"ben"} and \var{"cal"},
the following seven files will be created:

\begin{packed_itemize}
\item \var{targ\_shoreside.moos}
\item \var{targ\_abe.moos}
\item \var{targ\_abe.bhv}
\item \var{targ\_ben.moos}
\item \var{targ\_ben.bhv}
\item \var{targ\_cal.moos}
\item \var{targ\_cal.bhv}
\end{packed_itemize}

\noindent
The launch scripts will (a) create this set of \var{targ\_*.moos}
files, using the \app{nsplug} utility, and subsequently (b) launch the
mission using \app{pAntler} on these files.

\vspace{0.1in}
\noindent
If the mission is run in simulation, all the above files will be
created on the local machine. If running on robots, only the shoreside
file will be created on the user shoreside computer, and the
corresponding pair is create on the abe, ben and cal robots.

\vspace{0.1in}
\noindent
In our convention, only the \var{targ\_*} files are actually run in a
mission. The \var{meta\_*} files are the templates. The templates are
expanded with run-time user choices, as well as vehicle-specific such
as the vehicle name, network ports and so on. In this way, we can have
a 20-vehicle mission, with all 20 pairs of mission files create from
the same meta files.

\vspace{0.1in}
\noindent
Note: Only the meta files are retained under version control. The targ
files are discarded when the folder is cleaned. The logger will
however create a copy of the targ files along with other mission data.

%====================================================================
\subsection{Mission Variations}

A mission variation may be desired for two main reasons:

\begin{packed_itemize}
\item Monte Carlo performance testing
\item Correctness testing
\end{packed_itemize}

\vspace{0.1in}
\noindent
In the former, the mission may be modified to either (a) change the
robot conditions, such as the starting position, vehicle speeds,
location of obstacles etc, or (b) change one or more autonomy
algorithm parameters.

\vspace{0.1in}
\noindent
For correctness testing, the goal of the mission may be to unit test a
number of very explicit features of participating MOOS apps or behaviors.
Each mission variation will ensure the mission is launched with an
initial state and check later for an expected pass/fail state, and exit
with the result.

\vspace{0.1in}
\noindent
Regardless of the motivation for a mission variation, there is a need
to use {\em one} set of mission files to test many things. And the goal
is the same: run any mission variation with run-time options that
generate the desired targ files without require an edit to any launch file
or meta file.

%====================================================================
\subsection{Motivation}

Consider a simple example with the Alpha mission, where the simulated
vehicle traverses a set of five points in a home-plate pattern.  In
the \var{meta\_vehicle.bhv} file, the waypoint behavior is configured
with the below line selecting the vehicle speed:

\vspace{0.1in}
\begin{fileverb}
     speed = $(STOCK_SPD)
\end{fileverb}
\vspace{0.1in}

\noindent
The speed is filled in at launch time by replacing the macro
\var{\$(STOCK\_SPD)}, using the \var{nsplug} utility invoked inside
the \var{launch\_vehicle.sh} script. This launch script itself will
accept the argument, e.g., \var{./launch\_vehicle.sh --stock\_spd=2},
which will pass in the requested speed and propogate it to the
\var{\$(STOCK\_SPD)} macro.

\vspace{0.1in}
\noindent
In general, the launch script structure allows for unlimited
augmentation to allow for additional command line arguments,
additional macros, applied to addition lines in the mission files.
However, this can create quite complex and bloated mission files if
there are say 20 different mission modifications to be supported.

\vspace{0.1in}
\noindent
Our goal is to create thin mission files, that (a) serve as simple
(non-bloated) exemplars and (b) allow for unlimited variations for
automated testing of certain component functions. 

\vspace{0.1in}
\noindent
Consider the Alpha mission again, the waypoint behavior also has the 
following configuration for the five waypoints:

\vspace{0.1in}
\begin{fileverb}
         polygon = 60,-40 : 60,-160 : 150,-160 : 180,-100 : 150,-40
\end{fileverb}
\vspace{0.1in}

\noindent
This mission has no macro for the \bvar{polygon} parameter and no
corresponding command-line switches in the launch script. To run this
mission with say four different choices for waypoint patterns, the
file would have to be edited with the new points and then re-run, or
the required macro and command-line switches would need to be added.

o Sometimes we want to run a mission with several variations:

- Monte Carlo testing
- Unit testing

- Stem missions





%====================================================================
\section{How to Use NSPatch}

NSPatch is run with the \cmd{nspatch} command-line utility. It is run
in one of two modes, for patching a \var{.moos} file or a \var{.bhv}
file. For example:

\vspace{0.1in}
\begin{consoleverb}
  $ nspatch  vehicle.xmoos  targ_abe.moos [newfile.moos]
  $ nspatch  shoreside.xmoos  targ_shoreside.moos [newfile.moos]
\end{consoleverb}
\vspace{0.1in}

\noindent
or

\begin{consoleverb}
  $ nspatch  vehicle.xbhv  targ_abe.bhv [newfile.bhv]
\end{consoleverb}
\vspace{0.1in}

\noindent
The patch file is detected on the command line as having \var{.xmoos}
or \var{.xbhv} suffix. The file to which the patch will be applied is
detected with the \var{.moos} or \var{.bhv} suffix. Anything other than
a \var{.xmoos/.moos} pair or \var{.xbhv/.bhv} pair will result in
return with error. The same if either file is not found.

\vspace{0.1in}
\noindent
If the optional \var{[newfile]} argument is provided, the result will be
sent to this file. If it is not provided, the result will be overwritten
to the target file.

\vspace{0.1in}
\noindent
Note that the implied usage is that the patch will be applied to a mission
targ file and not the meta file.

%====================================================================
\section{How NSPatch Works}

The implemenation for patching MOOS and Behavior files similar but slightly
different. They are discussed separately below.

%====================================================================
\subsection{How NSPatchs Works for MOOS Files}

For MOOS files, \cmd{nspatch} parses both the \var{.xmoos} patch file
and \var{.moos} target file into a C++ class \var{MOOSFile}. The patch
is then applied from one instance of the class to the other, and then
re-serialized to text output

%--------------------------------------------------------------------
\subsection{MOOS File Format}

Recall that a \var{.moos} file is regarded as having the below
structure.  Typically globally scoped parameters are all at the top of
the file, but not necessarily so. Typically there is one configuration
block per app, but if more than one block is provided, this is not
considered an error.  As with a normal \var{.moos} file ingested by
\app{pAntler}, if two blocks are provided, the first block will be
used and the other(s) ignored.

\vspace{0.1in}
\begin{fileverb}
  param=value     // global scope
  ...
  param=value     // global scope

  ProcessConfig = pFoo
  {
    param = value    // pFoo scope
    ...
    param = value    // pFoo scope
  }

  ...
  
  ProcessConfig = pBar
  {
    param = value    // pBar scope
    ...
    param = value    // pBar scope
  }
\end{fileverb}
\vspace{0.1in}

%--------------------------------------------------------------------
\subsection{MOOSFile C++ Class Structure}







%====================================================================
\subsection{How NSPatchs Works for Behavior Files}







\end{document}




