<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%========================================================================
\section{A First Example with MOOS-IvP - the Alpha Mission}
%========================================================================
\wikisec{grp=xmiss,file=XMissAlpha,short=Example Alpha}
\label{sec_alpha}

This section describes a simple mission using the helm. It
is designed to run in simulation on a single machine. 
The mission configuraiton files for this example are
distributed with the source code. Information on how to find these
files and launch this mission are described below in Section
\ref{find_alpha}. In this example the vehicle simply traverses a set
of pre-defined given waypoints and returns back to the launch
position. The user may return the vehicle any time before
completing the waypoints, and may subsequently command the vehicle to
resume the waypoints at any time. This example touches on 
the following issues:

\vspace{0.1in}
\begin{packed_itemize}[0]
\item Launching a mission with a given mission (\var{.moos}) file
  and behavior (\var{.bhv}) file.
\item Configuration of MOOS processes, including the IvP Helm, with a
  \var{.moos} file.
\item Configuration of the IvP Helm (mission planning) with a \var{.bhv}
  file.
\item Implementation of simple command and control with the IvP Helm.
\item Interaction between MOOS processes and the helm during normal
  mission operation.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Here is a bit of what the Alpha mission should look like:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{figures/Alpha.png}
  \caption{The Alpha mission.}
  \label{fig_alpha_video}
  \urlvideo{https://vimeo.com/84549446}{0:19}
\end{figure}
\vspace{0.1in}

%===================================================================
\subsection{Find and Launch the Alpha Example Mission}
\label{find_alpha}

The example mission should be in the same directory tree containing
the source code. There are two files - a MOOS file, also mission file
or \var{.moos} file, and a behavior file or \var{.bhv} file:

\footnotesize
\begin{verbatim}
   moos-ivp/ 
      MOOS/
      ivp/
         missions/
            s1_alpha/
               alpha.moos    &lt;---- The MOOS file
               alpha.bhv     &lt;---- The Behavior file
\end{verbatim}
\normalsize

\vspace{0.1in}
\noindent
To run this mission from a terminal window, simply change directories
and launch:

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

\noindent
After \app{pAntler} has launched each process, the \app{pMarineViewer}
window should be open and look similar to that shown in Figure
\ref{alpha_snap_one}. After clicking the \var{DEPLOY} button in the
lower right corner the vehicle should start to traverse the shown set
of waypoints.

\vspace{0.15in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/first_example1.png}
  \caption{{\bf The Alpha Example Mission - In the Surveying Mode}: A
    single vehicle is dispatched to traverse a set of waypoints and,
    upon completion, traverse to the waypoint (0,0) which is the
    launch point.}
\label{alpha_snap_one}
\end{figure}

\vspace{0.12in}
\noindent
This mission will complete on its own with the vehicle returning to
the launch point. Alternatively, by hitting the \var{RETURN} button
at any time before the points have been traverse, the vehicle will
change course immediately to return to the launch point, as shown 
in Figure \ref{alpha_snap_two}. When the vehicle is returning as in
the figure, it can be re-deployed by hitting the \var{DEPLOY} button
again.

\vspace{0.15in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/first_example2.png}
  \caption{{\bf The Alpha Example Mission - In the Returning Mode}':
    The vehicle can be commanded to return prior to the completion of
    its waypoints by the user clicking the \vvar{RETURN} button on the
    viewer.}
  \label{alpha_snap_two}
\end{figure}

\vspace{0.12in}
\noindent
The vehicle in this example is configured with two basic waypoint
behaviors. Their configuration with respect to the points traversed
and when each behavior is actively influencing the vehicle, is
discussed next.

%==================================================================
\subsection{A Look at the Behavior File used in the Alpha Example Mission}
\label{bhv_files}

The mission configuration of the helm behaviors is provided in a {\em
  behavior file}, and the complete behavior file for the example
mission is shown in Listing \ref{listing_alpha}. Behaviors are
configured in blocks of parameter-value pairs - for example lines 6-17
configure the waypoint behavior with the five waypoints shown in the
previous two figures. This is discussed in more detail in Section
\ref{bhv_params}.

\vspace{0.15in}
\begin{listing}{The behavior file for the Alpha example}
\label{listing_alpha}
\scriptsize
\begin{verbatim}
  1  initialize   DEPLOY = false
  2  initialize   RETURN = false
  3  
  4  //----------------------------------------------
  5  Behavior = BHV_Waypoint
  6  { 
  7    name      = waypt_survey
  8    pwt       = 100
  9    condition = RETURN = false
 10    condition = DEPLOY = true
 11    endflag   = RETURN = true
 12    perpetual = true
 13  
 14            lead = 8
 15     lead_damper = 1
 16           speed = 2.0   // meters per second
 17          radius = 4.0
 18       nm_radius = 10.0
 19          points = 60,-40:60,-160:150,-160:180,-100:150,-40
 20          repeat = 1
 21  }
 22  
 23  //----------------------------------------------
 24  Behavior = BHV_Waypoint
 25  {
 26    name       = waypt_return
 27    pwt        = 100
 28    condition  = RETURN = true
 29    condition  = DEPLOY = true
 30    perpetual  = true
 31    endflag    = RETURN = false
 32    endflag    = DEPLOY = false
 33  
 34         speed = 2.0
 35        radius = 2.0
 36     nm_radius = 8.0
 37         point = 0,0
 38  }
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
The parameters for each behavior are separated into two
groups. Parameters such as \bvar{name}, \bvar{priority},
\bvar{condition} and \bvar{endflag} are parameters defined generally
for all IvP behaviors. Parameters such as \bvar{speed}, \bvar{radius},
and \bvar{points} are defined specifically for the Waypoint behavior.
A convention used in \var{.bhv} files is to group the general behavior
parameters separately at the top of the configuration block.

\vspace{0.1in}
\noindent
In this mission, the vehicle follows two sets of waypoints in
succession by configuring two instances of a basic waypoint
behavior. The second waypoint behavior (lines 23-37) contains only a
single waypoint representing the vehicle launch point (0,0). It's
often convenient to have the vehicle return home when the mission is
completed - in this case when the first waypoint behavior has reached
its last waypoint. Although it's possible to simply add (0,0) as the
last waypoint of the first waypoint behavior, it is useful to keep it
separate to facilitate recalling the vehicle pre-maturely at any point
after deployment.

\vspace{0.1in}
\noindent
Behavior conditions (lines 9-10, 28-29), and endflags (line 110, lines
31-32) are primary tools for coordinating separate behaviors into a
particular mission. Behaviors will not participate unless each of its
conditions are met. The condtions are based on current values of the
MOOS variables involved in the condition. For example, both behaviors
will remain idle unless the variable \mvar{DEPLOY} is set to true.
This variable is set initially to be false by the initialization on
line 1, and is toggled by the \var{DEPLOY} button on the
\app{pMarineViewer} GUI shown in Figures \ref{alpha_snap_one} and
\ref{alpha_snap_two}. The \app{pMarineViewer} MOOS application is one
option for a command and control interface to the helm. The MOOS
variables in the behavior conditions in Listing \ref{listing_alpha} do
not care which process was responsible for setting the value. Endflags
are used by behaviors to post a MOOS variable and value when a
behavior has reached a completion. The notion of completion is
different for each behavior and some behaviors have no notion of
completion, but in the case of the waypoint behavior, completion is
declared when the last waypoint is reached. In this way, behaviors can
be configured to run in a sequence, as in this example, where the
returning waypoint behavior will have a necessary condition (line 28)
met when the surveying behavior posts its endflag on line 11.

%===================================================================
\subsection{A Closer Look at the MOOS Apps in the Alpha Example Mission}

Running the example mission involves five other MOOS applications in
addition to the IvP helm. In this section we take a closer look at
what those applications do and how they are configured.  The full MOOS
file, \var{alpha.moos}, used to run this mission is given in full in
the appendix. An overview of the situation is shown in Figure \ref{moos-mods-alpha}.

\vspace {0.15in}

\begin{figure}[ht]
  \centering 
  \includegraphics[width=0.92\textwidth]{figures/moos-mods-alpha.png}
  \caption{{\bf The MOOS processes in the example "alpha"
        mission}: In (1) The helm produces a desired heading and
    speed. In (2) the PID controller subscribes for the desired
    heading and speed and publishes actuation values. In (3) the
    simulator grabs the actuator values and the current vehicle pose
    and publishes a set of MOOS variables representing the new vehicle
    pose.  In (4) all navigation output is wrapped into a single
    node-report string to be consumed by the helm and the GUI
    viewer. In (5) the pMarineViewer grabs the node-report and renders
    a new vehicle posision.  The user can interact with the viewer to
    write limited commmand and control variables to the MOOSDB.}
  \label{moos-mods-alpha}
\end{figure}

%---------------------------------------------------------------------
\subsubsection{Antler and the Antler Configuration Block}
\label{sec_alpha_antler}

The \app{pAntler} tool is used to orchestrate the launching of all the
MOOS processes participating in this example. From the command line,
\app{pAntler} is run with a single argument the \var{.moos} file.  As
it launches processes, it hands each procoess a pointer to this same
MOOS file. The Antler configuration block in this example looks like:

\vspace{0.2in}
\begin{listing}{An example Antler configuration block for the Alpha mission}
\label{block_alpha_antler}
\footnotesize
\begin{verbatim}
  1  ProcessConfig = ANTLER
  2  {
  3    MSBetweenLaunches = 200
  4    
  5    Run = MOOSDB          @ NewConsole = false
  6    Run = uSimMarine      @ NewConsole = false
  7    Run = pNodeReporter   @ NewConsole = false
  8    Run = pMarinePID      @ NewConsole = false
  9    Run = pMarineViewer   @ NewConsole = false
 10    Run = pHelmIvP        @ NewConsole = false
 11  }
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
The first parameter on line 2 specifies how much time should be left
beteen the launching of each process. Lines 4-9 specify which
processes to launch. The MOOSDB is typically launched first. The
\var{NewConsole} switch on each line determines whether a new console
window should be opened with each process. Try switching one or more
of these to \var{true} as an experiment.

%---------------------------------------------------------------------
\subsubsection{The pMarinePID Application}
\label{sec_pmarinepid}

The \app{pMarinePID} application implements a simple PID controller
which produces values suitable for actuator control based on inputs
from the helm. In simulation the output is consumed by the vehicle
simulator rather than the vehicle actuatiors. 

\vspace{0.15in}
\noindent
In short: The \app{pMarinePID} application typically gets its info
from \app{pHelmIvP}; produces info consumed by \app{uSimMarine} or
actuator MOOS processes when not running in simulation.

\vspace{0.1in}
\noindent
Subcribes to: \mvar{DESIRED\_HEADING}, \mvar{DESIRED\_SPEED}.

\vspace{0.1in}
\noindent
Publishes to: \mvar{DESIRED\_RUDDER}, \mvar{DESIRED\_THRUST}.

\vspace{0.1in}

%---------------------------------------------------------------------
\subsubsection{The uSimMarine Application and Configuration Block}

The \app{uSimMarine} application is a very simple vehicle simulator
that considers the current vehicle pose and actuator commands and
produces a new vehicle pose. It can be initialized with a given pose
as shown in the configuration block used in this example, shown in
Listing \ref{block_alpha_ims}:

\vspace{0.1in}
\begin{listing}{An example uSimMarine configuration block for the Alpha mission}
\label{block_alpha_ims}
\footnotesize
\begin{verbatim}
  1  ProcessConfig = uSimMarine
  2  {
  3    AppTick	 = 10
  4    CommsTick = 10
  5   
  6    START_X       = 0
  7    START_Y       = 0
  8    START_SPEED   = 0
  9    START_HEADING = 180
 10    PREFIX        = NAV
 11  }
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.15in}
\noindent
In short: The \app{uSimMarine} application typically gets its info
from \app{pMarinePID}; produces info consumed by \app{pNodeReporter}
and itself on the next iteration of \app{uSimMarine}.

\vspace{0.1in}
\noindent
Subcribes to: \mvar{DESIRED\_RUDDER}, \mvar{DESIRED\_THRUST}, 
\mvar{NAV\_X}, \mvar{NAV\_Y}, \mvar{NAV\_SPEED}, \mvar{NAV\_HEADING}.

\vspace{0.1in}
\noindent
Publishes to: \mvar{NAV\_X}, \mvar{NAV\_Y}, \mvar{NAV\_HEADING},
\mvar{NAV\_SPEED}.

%---------------------------------------------------------------------
\subsubsection{The pNodeReporter Application and Configuration Block}

An Automated Information System (AIS) is commonplace on many larger
marine vessels and is comprised of a transponder and receiver that
broadcasts one's own vehicle ID and pose to other nearby vessels
equiped with an AIS receiver.  It periodically collects all latest
pose elements, e.g., latitutude and longitude position and latest
measured heading and speed, and wraps it up into a single update to be
broadcast. This MOOS process collects pose information by subscribing
to the \app{MOOSDB} for \mvar{NAV\_X}, \mvar{NAV\_Y},
\mvar{NAV\_HEADING}, \mvar{NAV\_SPEED}, and \mvar{NAV\_DEPTH} and
wraps it up into a single MOOS variable called
\mvar{NODE\_REPORT\_LOCAL}. This variable in turn can be subscribed to
another MOOS process connected to an actual serial device acting as an
AIS transponder. For our purposes, this variable is also subscribed to
by pMarineViewer for rendering a vehicle pose sequence.

\vspace{0.15in}
\noindent
In short: The \app{pNodeReporter} application typically gets its info
from \app{uSimMarine} or otherwise on-board navigation systems such as
GPS or compass; produces info consumed by \app{pMarineViewer} and
instances of \app{pHelmIvP} running in other vehicles or simulated
vehicles.

\vspace{0.1in}
\noindent
Subcribes to: \mvar{NAV\_X}, \mvar{NAV\_Y}, \mvar{NAV\_SPEED},
\mvar{NAV\_HEADING}.

\vspace{0.1in}
\noindent
Publishes to: \mvar{NODE\_REPORT\_LOCAL}

%---------------------------------------------------------------------
\subsubsection{The pMarineViewer Application and Configuration Block}

The \app{pMarineViewer} is a MOOS process that subscribes to the MOOS
variable \mvar{NODE\_REPORT\_LOCAL} and \mvar{NODE\_REPORT} which
contains a vehicle ID, pose and timestamp. It renders the updated
vehicle(s) position. It is a multi-threaded process to allow both
communication with MOOS and let the user pan and zoom and otherwise
interact with the GUI. It is non-essential for vehicle operation, but
essential for visually confirming that all is going as planned.

\vspace{0.15in}
\noindent
In short: The \app{pMarineViewer} application typically gets its info
from \app{pNodeReporter} and \app{pHelmIvP}; produces info consumed by
\app{pHelmIvP} when configured to have command and control hooks (as
in this example).

\vspace{0.1in}
\noindent
Subcribes to: \mvar{NODE\_REPORT}, \mvar{NODE\_REPORT\_LOCAL},
\mvar{VIEW\_POINT}, \mvar{VIEW\_SEGLIST}, \mvar{VIEW\_POLYGON}, 
\mvar{VIEW\_MARKER}.

\vspace{0.1in}
\noindent
Publishes to: Depends on configuration, but in this 
example: \mvar{DEPLOY}, \mvar{RETURN}.
</pre></body></html>