<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%====================================================================
\section{Extended Example Missions with the IvP Helm}
%====================================================================
\wikisec{grp=xmiss}
\wikisec{file=HelmXMissions,short=Example Missions}
\label{exam_extended}

This section addresses a number of example mission configurations the
user may run in simulation, to explore various aspects of the helm,
certain behaviors, and certain tools for configuring, running and
analyzing missions. All missions are available in the moos-ivp
software tree in the following location:

\vspace{0.15in}
\begin{consoleverb}
 $ cd moos-ivp/ivp/missions/
\end{consoleverb}
\vspace{0.15in}

%====================================================================
\subsection{Preliminaries}

Each mission in the \var{missions/} directory is contained in a
dedicated subdirectory such as \var{s1\_alpha}, or
\var{m2\_berta}. The \var{'s'} and \var{'m'} in the prefix indicate
whether it is a single-vehicle or multi-vehicle mission. The numbering
roughly correlates to an increase in complexity from commonly used
bread-and-butter behaviors and configurations to more complex mission
configurations.

\vspace{0.1in}
\noindent
Each directory contains one or more {\em mission} files, i.e., files
that end in the \var{.moos} suffix, and one or more {\em behavior}
files, i.e., files that end in the \var{.bhv} suffix. During the
course of running a mission, certain additional temporary files may be
created. In all cases, the temporary files may be removed by running
the \var{clean.sh} script included in each directory. The
configuration and launching of the missions requires some familiarity
with three tools, (a) pAntler, for launching multiple MOOS
applications, (b) the \var{nsplug} tool, for building composite
\var{.moos} and \var{.bhv} files from a template and set of include
files, and (c) basics of shell scripts for organizing the overall
launch process and cleanup. A brief recap of these three tools is
covered next.

%====================================================================
\subsection{Using pAntler to Launch Missions}

The \var{pAntler} utility is a command-line tool used to orchestrate
the launching of a group of MOOS processes. A typical invocation is:

\vspace{0.15in}
\begin{consoleverb}
 $ pAntler charlie.moos
\end{consoleverb}
\vspace{0.15in}

\noindent
The MOOS file contains a configuration block for each process, and an
Antler configuration block which is typically the first block in the
file. Each block contains a collection of local ``parameter = value''
pairs read in by each individual application. There are also typically
a number of global parameter=value pairs for possible use by all
applications.

%====================================================================
\subsection{Using the nsplug Utility for Configuring Mission and Behavior Files}

In multi-vehicle missions, the maintenance of mission and behavior
files across multiple vehicles can become cumbersome and user
error-prone. Since many of the file components are identical between
vehicles, a fair amount of the problem is mitigated by building the
files from file template files that include the common components from
separate files. The \var{nsplug} command-line utility is used to
expand a template file into a target file, with arguments passed that
typically distinguish the produced file from others produced from the
same template. For example, two mission files, one for the vehicle
"charlie", and one for the vehicle "frankie" may differ only in their
vehicle names and IP Port number, and may be produced from a template
file with the following two commands:

\vspace{0.14in}
\noindent
\begin{consoleverb}
 $ nsplug  meta_vehicle.moos targ_charlie.moos VNAME=charlie PORT=9201
 $ nsplug  meta_vehicle.moos targ_frankie.moos VNAME=charlie PORT=9202
\end{consoleverb}
\vspace{0.14in}

\noindent
For the multi-vehicle example missions distributed with the moos-ivp
tree and described in this section, this use of templates is used in
all cases. The mission directories downloaded will not contain the
\var{nsplug} "output" files such as \var{targ\_charlie.moos} above.
Rather, they are built by executing the launch scripts provided in
each directory with a command such as:

\vspace{0.14in}
\begin{consoleverb}
 $ ./launch.sh
\end{consoleverb}
\vspace{0.14in}

\noindent
The above invocation will both build the mission and behavior files
and invoke pAntler for each vehicle to start the simulation. Certain
common command-line options such as \var{"./launch --just\_build"}, to
build the mission files without launching, are available in all
scripts.  A few conventions with respect to templates and \var{nsplug}
are used across all example mission directories.

\begin{packed_enumerate}[3]

\item Files used as templates have a \var{"meta\_"} prefix.
\item Files meant to be included or plugged into another template file
  have a \var{"plug\_"} prefix.
\item Output files that are built from templates and plug-ins via
  \var{nsplug} have \var{"targ\_"} prefix.
\item Template or plug-in files that contribute to a target MOOS file
  have \var{".moos"} suffix.
\item Template or plug-in files that contribute to a target Helm
  behavior file have \var{".bhv"} suffix.
\end{packed_enumerate}

\noindent
For example, in the \var{m2\_berta} mission, the following files
exist prior to building any target files and launching:

\vspace{0.14in}
\noindent
\begin{consoleverb}
$ cd missions/m2_berta
$ ls
README               launch.sh*           meta_shoreside.moos  plugs.moos
clean.sh*            launch_shoreside.sh* meta_vehicle.bhv
init_field.sh*       launch_vehicle.sh*   meta_vehicle.moos
\end{consoleverb}
\vspace{0.14in}

\noindent
After building all the target files, the following additional
\var{targ\_*} files exist:


\vspace{0.14in}
\noindent
\begin{consoleverb}
$ ./launch.sh --just_build
$ ls
README               launch_vehicle.sh*   targ_abe.bhv         vcolors.txt
clean.sh*            meta_shoreside.moos  targ_abe.moos        vloiterpos.txt
init_field.sh*       meta_vehicle.bhv     targ_ben.bhv         vnames.txt
launch.sh*           meta_vehicle.moos    targ_ben.moos        vpositions.txt
launch_shoreside.sh* plugs.moos           targ_shoreside.moos  vspeeds.txt
\end{consoleverb}
\vspace{0.15in}

\noindent
The mission may launched, with \var{MOOSTimeWarp=10}, by:

\vspace{0.1in}
\begin{consoleverb}
 $  ./launch.sh 10
\end{consoleverb}
\vspace{0.1in}


%\subsubsection{Shell Scripts}
%\label{sec_shell_scripts}

%\newpage  \input{example_missions/chap_exam_s3_charlie}
%\newpage  \input{example_missions/chap_exam_s4_delta}
%\newpage  \input{example_missions/chap_exam_s5_echo}
%\newpage  \input{example_missions/chap_exam_s11_kilo}
%%%%%\newpage  \input{example_missions/chap_exam_m1_anton}
%\newpage  \input{example_missions/chap_exam_m2_berta}


%German: Anton, Berta, Casar, Dora, Emil, Friedrich, Gustav, Heinrich,
%   Ida, Julius, Kaufmann, Ludwig, Martha, Nordpol, Otto, Paula, Quelle
%   Richard, Samuel, Theodor, Ulrich, Viktor, Wilhelm, Xanthippe, 
%   Ypsilon, Zeppelin

%NATO: Alpha, Bravo, Charlie, Delta, Echo, Foxtrot, Golf, Hotel, India
%   Juliet, Kilo, Lima, Mike, November, Oscar, Papa, Quebec, Romeo
%   Sierra, Tango, Uniform, Victor, Whisky, X-ray, Yankee, Zulu
</pre></body></html>