\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{The NSPatch Mission Configuration Utility}
\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{Overview}
%====================================================================

The \app{nspatch} utility is a mission configuration tool that
operates by applying "patch" information to an existing mission file,
either a MOOS (\var{.moos}), or behavior (\var{.bhv}) file, to create a
new modified file. It allows the user to use an existing mission
folder and create an unlimited number of variations without (a)
editing the existing mission file or (b) adding additional launch
command line switches.

%====================================================================
\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}




