<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%====================================================================
\section{The Delta Mission}
%====================================================================
\wikisec{grp=xmiss}
\wikisec{file=HelmXMissDelta,short=Example Delta}
\label{exmissions_s4}

The Delta example mission is used to illustrate the operation of a a
vehicle in the depth plane (an underwater as opposed to surface
vehicle), the illustration of the PeriodicSurface behavior, the use of
the Waypoint behavior with survey patterns, and the use of the
\app{pMarineViewer} application to send field-control commands to
alter the mission as it unfolds. The vehicle will initially deploy
using the Loiter behavior, and will periodically come to the
surface. If commanded by the user, the vehicle will break off from the
Loiter behavior to execute a survey pattern, after which it will
resume loitering at its original location.

%====================================================================
\subsection{Overview of the Delta Mission Components and Topics}

\small
\begin{longtable}{|r|p{0.76\textwidth}|} \hline 
  \bsvar{Behaviors:} &amp; Waypoint, Loiter, PeriodicSurface, ConstantDepth \\ \hline
  
  \bsvar{MOOS Apps:} &amp; \app{pHelmIvP}, \app{pLogger},
  \app{uSimMarine}, \app{pMarinePID}, \app{pNodeReporter},
  \app{pMarineViewer} \app{uTimerScript} \\ \hline
  
  \bsvar{Primary Topics:} &amp;
  (1) Configuring the Helm for operation at depth \newline
  (2) The ConstantDepth behavior \newline
  (3) The PeriodicSurface behavior \newline
  (4) The Waypoint behavior with survey patterns \newline
  (5) Using pMarineViewer with Geo-referenced mouse clicks \\ \hline
  
  \bsvar{Side Topics:} &amp;
  (1) \app{uTimerScript} is used to simulate a UUV receiving a GPS 
    update.  \\ \hline
  
\end{longtable}
\normalsize

%====================================================================
\subsection{Launching the Delta Mission}

The delta mission may be launched from the command line:

\vspace{0.15in}
\begin{consoleverb}
 $ cd moos-ivp/missions/s4_delta/
 $ ./launch.sh --warp=10
\end{consoleverb}
\vspace{0.15in}

\noindent
This should bring up a \app{pMarineViewer} window like that shown in
Figure \ref{fig_delta_one}, with a single vehicle, \var{"dudley"},
initially in the \var{PARK} helm state. See Section
\ref{sec_helm_state} for more on the helm state. After hitting the
\var{DEPLOY} button in the lower right corner, the vehicle enters the
\var{DRIVE} state, and the \var{LOITERING} helm mode, and begins to
proceed along the waypoints as shown. See Section \ref{sec_mode_decls}
for more on more on the helm mode, vs. the helm state.  The mode
declarations for the Delta mission are defined at the top of the
\var{delta.moos} file, and amount to the following simple hierarchy:

\footnotesize
\begin{verbatim}
      o ROOT          
      |--o INACTIVE   
      |--o ACTIVE     
         |--o RETURNING
         |--o SURVEYING
         |--o LOITERING
\end{verbatim}
\normalsize

\noindent
In the initial helm mode after deployment, the \var{LOITERING} mode,
the helm is running the Loitering behavior, Section \ref{bhv_loiter},
the ConstantDepth behavior, Section \ref{bhv_constdepth}, and the
PeriodicSurface behavior, Section \ref{bhv_periodicsurface}. It will
stay in this mode indefinitely until it is either commanded to return
or break off to another region to conduct a survey pattern. In the
\var{LOITERING} mode the vehicle will periodically come to the surface
for a GPS fix, presumably to correct for accumulated navigation error.
The \app{uTimerScript} utility is used to simulate the event of
receiving a GPS fix. This script is described in more detail in the
\app{uTimerScript} documentation in the Section "A Script Used as
Proxy for an On-Board GPS Unit".

\vspace{0.1in}
\noindent
In the \var{SURVEYING} mode, the Waypoint behavior becomes active and
will execute a survey lawn-mower type pattern, as shown in Figures
\ref{fig_delta_two} and \ref{fig_delta_four}.  In this mode, the
periodic surfacing for GPS fixes is suppressed until the pattern is
completed. The \var{SURVEYING} mode is entered whenever the MOOS
variable \var{SURVEY} is set to \var{true}. In this mission,
\app{pMarineViewer} is configured to toggle the \mvar{SURVEY} MOOS
variable with on-screen buttons, and it is configured to accept mouse
clicks which not only put the vehicle into the \var{SURVEYING} mode,
but also accept the location of the mouse click as the center location
of a predefined survey pattern. This kind of \app{pMarineViewer}
configuration is discussed in Section \ref{sec_delta_pmv}.


%====================================================================
\subsection{Topic \#1: Configuring the Helm for Operation at Depth}

The Delta mission is configured to simulate a UUV and the helm is
configured to produce decisions about the decision variables {\em
  heading}, {\em speed}, as well as {\em depth}. Adding {\em depth} to
the helm decision space is done in the helm configuration block as
shown below in Listing \ref{helm_with_depth}, taken from the
\var{delta.moos} mission file. In this case, the {\em depth} decision
space is defined on line 13 with a range from 0 to 500 meters, with a
resolution of 1 meter. See Section \ref{hparam_domain} for more on
configuring the helm decision space with the \bvar{domain} parameter.

\vspace{0.2in}
\begin{listing}{Configuring pHelmIvP in the Delta mission to use behaviors concerning vehicle depth}
\label{helm_with_depth}
\scriptsize
\begin{verbatim}
  1  // pHelmIvP config block
  2  
  3  ProcessConfig = pHelmIvP
  4  {
  5    AppTick    = 4
  6    CommsTick  = 4
  7  
  8    behaviors  = delta.bhv
  9    verbose    = quiet
 10    domain     = course:0:359:360
 11    domain     = speed:0:4:21
 12    domain     = depth:0:500:501
 13  }
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
In this example, the {\em depth} decision variable is a mandatory
variable, along with {\em heading} and {\em speed}. This means that,
on any given helm iteration, there {\em must} be a decision made about
depth, or else the helm will post a helm error. How does the helm
ensure that a depth decision is always part of any decision? The helm
must be configured such that a behavior that reasons about {\em depth}
is always active regardless of the helm mode. In the Delta mission,
the three primary modes, \var{LOITERING}, \var{SURVEYING},
\var{RETURNING}, are all sub-modes of the \var{ACTIVE} mode, as
shown above. The ConstantDepth behavior is configured to be running
whenever the helm is in the Active mode.

%====================================================================
\subsection{Topic \#2: The ConstantDepth Behavior}

The ConstantDepth behavior is used in the Delta mission to keep the
vehicle a prescribed depth while it is transiting, surveying, and 
loitering. For simplicity a single ConstantDepth behavior is used, 
but a different behavior instance could also be used for each vehicle
mode. The behavior configuration, in file \var{delta.bhv} is shown 
in Listing \ref{lst_delta_constdepth} below.  The first part of the 
configuration block, in lines 3-6, are for parameters defined 
generally for all IvP Helm behaviors, and the second part, on 
line 8, is a parameter defined for the ConstantDepth behavior.

\vspace{0.18in}
\begin{listing}{The ConstantDepth behavior in the Delta mission, from the file delta.bhv}
\label{lst_delta_constdepth}
\footnotesize
\begin{verbatim}
 1  Behavior = BHV_ConstantDepth
 2  {
 3    name      = bhv_const_depth
 4    pwt       = 100
 5    duration  = no-time-limit
 6    condition = MODE==ACTIVE
 7  
 8        depth = 15
 9  }
\end{verbatim}
\end{listing}
\normalsize

The ConstantDepth behavior's primary parameter is the \bvar{depth}
parameter on line 8. This behavior does make provisions for 
providing a range of depths, or a more gradually degrading utility
function when this behavior is used to work with other behaviors
reasoning about depth. In this mission however, the depth is mostly
non-contentious between behaviors. The exception is when the 
PeriodicSurface behavior is active, in which case the priority
weight for the PeriodicSurface behavior is simply set to suppress
the ConstantDepth behavior.

%====================================================================
\subsection{Topic \#3: The PeriodicSurface Behavior}

The PeriodicSurface behavior, described generally in Section
\ref{bhv_periodicsurface}, is used in the Delta mission to bring the
vehicle to the surface for GPS fixes periodically, to simulate the
need for occasional navigation corrections.  The behavior
configuration, in file \var{delta.bhv} is shown in Listing
\ref{lst_delta_psurface} below.  The first part of the configuration
block, in lines 3-6, is for parameters defined generally for all IvP
Helm behaviors, and the second part, in lines 8-13, is for parameters
defined for the PeriodicSurface behavior.

\vspace{0.18in}
\begin{listing}{The PeriodicSurface behavior in the Delta mission, from the file delta.bhv}
\label{lst_delta_psurface}
\footnotesize
\begin{verbatim}
  1  Behavior = BHV_PeriodicSurface
  2  {
  3    name             = bhv_periodic_surface
  4    pwt              = 1000
  5    condition        = (MODE == LOITERING) or (MODE == RETURNING)
  6    condition        = PSURFACE = true
  7  
  8                 period = 120
  9       zero_speed_depth = 2
 10    max_time_at_surface = 60
 11           ascent_speed = 1.0
 12           ascent_grade = fullspeed
 13          mark_variable = GPS_UPDATE_RECEIVED
 14  }
\end{verbatim}
\end{listing}
\normalsize

The PeriodicSurface behavior outputs an objective function solely on
the {\em depth} decision variable. Note the priority weight in line 4
in Listing \ref{lst_delta_psurface} is set to 1000, in comparison to
the priority weight set for the ConstantDepth behavior on line 4 in
Listing \ref{lst_delta_constdepth}. When the PeriodicSurface behavior
is running, it may or may not be active and producing an objective
function over the {\em depth} decision variable. When it {\em is}
active, the influence on {\em depth} simply overrules the influence
from the ConstantDepth behavior due to these relative priority
weights. For this reason, the ConstantDepth behavior may be
conditioned on all active modes as in line 6 of Listing
\ref{lst_delta_constdepth}.

\pskip

Note the parameter setting on line 13 above, setting the "mark
variable" to \mvar{GPS\_UPDATE\_RECEIVED}. This is the default value,
and the line could be safely be removed from the configuration block,
but it is included anyway to be clear. The PeriodicSurface behavior,
once it has noted that the vehicle has reached the surface, will wait
until a value has been posted to \mvar{GPS\_UPDATE\_RECEIVED} that is
different than its previous posting. Usually a timestamp suffices.
The configuration of \app{uTimerScript} to achieve simulated GPS
updates is described in more detail in the \app{uTimerScript}
documentation in the Section "A Script Used as Proxy for an On-Board
GPS Unit".

%=======================================================================
\subsection{Topic \#4: The Waypoint Behavior with Survey Patterns}
\label{sec_delta_pmv}

The Waypoint behavior, described generally in Section
\ref{bhv_waypoint}, is used in the Delta mission to conduct survey
patterns like that shown in Figure \ref{fig_delta_two}.  The behavior
configuration, in file \var{delta.bhv} is shown in Listing
\ref{lst_delta_wsurvey} below. Note the survey pattern, described on
line 15, does not list a set of points, but instead describes
the pattern in terms of its properties such as the lane width and
pattern orientation. This format is supported generally for building
SegList objects from string specifications, discussed in the Geometry
documentation.

\vspace{0.18in}
\begin{listing}{The Waypoint behavior in the Delta mission, from the file delta.bhv}
\footnotesize
\label{lst_delta_wsurvey}
\begin{verbatim}
  1 Behavior = BHV_Waypoint
  2 {
  3   name      = waypt_survey
  4   pwt       = 100
  5   condition = MODE==SURVEYING
  6   perpetual = true
  7   updates   = SURVEY_UPDATES
  8   endflag   = SURVEY = false
  9 
 10           lead = 8
 11    lead_damper = 1
 12          speed = 2.0   // meters per second
 13         radius = 8.0
 14         points = format=lawnmower, label=dudley_survey, x=80, y=-80,  
                     width=70, height=30, lane_width=8, rows=north-south, 
                     degs=30
 15 }
\end{verbatim}
\end{listing}
\normalsize

The waypoint behavior is configured to execute the survey pattern
once, since the \bvar{repeat} parameter is not set and defaults to
zero. Upon completion, it posts an end flag, configured on line 8,
\msvar{SURVEY=false} to the \app{MOOSDB}. This immediately moves the
vehicle out of the \var{SURVEYING} and into either the \var{LOITERING}
or \var{RETURNING} mode depending on what it was doing when it was
commanded to begin the survey. See the hierarchical mode declarations
at the top of the \var{delta.bhv} file. Since the behavior is set with
\bvar{perpetual}\bsvar{=true} on line 6, completion of the survey
pattern merely puts the behavior in a virtual stand-by mode until it
is given a new set of waypoints and it once again meets its run
conditions.

\pskip

The waypoint behavior is configured to accept dynamic parameter
updates on line 7 through the MOOS variable \mvar{SURVEY\_UPDATES}. In
the Delta mission, updates are initiated by a mouse click in the
\app{pMarineViewer} window, with the result being a post to the MOOSDB
of the \mvar{SURVEY\_UPDATES} variable. Such a posting would consist of
a new value for the \bvar{points} parameter, replacing the initial
configuration on line 14. This is discussed next.

%=======================================================================
\subsection{Topic \#4: Using pMarineViewer with Geo-referenced Mouse Clicks}
\label{sec_delta_pmv_mouse}

In the Delta mission, the \app{pMarineViewer} application is used to
post messages to the MOOSDB to (a) put the vehicle into the
\var{SURVEYING} mode from either the \var{LOITERING} or
\var{RETURNING} modes and (b) grab a user specified point in the
operation area, from the user's mouse click, to be used as the center
point of the commanded survey pattern. This situation is shown in
Figure \ref{fig_delta_two}.  This is achieved by utilizing the Mouse
Context feature of \app{pMarineViewer}, discussed in the
\app{pMarineViewer} documentation, \cite{url_pmv}, in the section {\em
  "Contextual Mouse Poking with Embedded OpArea Information"}. The
below two lines are inserted into the \app{pMarineViewer}
configuration block in \var{delta.moos}:

\prevblue
\begin{verbatim}
  left_context[survey-point] = SURVEY = true
  left_context[survey-point] = SURVEY_UPDATES = points = vname=$(VNAME),  \
        x=$(XPOS), y=$(YPOS), format=lawnmower, label=delta, width=70,    \
        height=30, lane_width=8, rows=north-south, degs=80
\end{verbatim}
\postverb

\noindent
Both lines declare that a MOOS variable-value pair is to be posted
whenever a left mouse click is generated by the user. The fist line
sets \msvar{SURVEY=true}, in an attempt to put the helm into the
\var{SURVEYING} mode. This alone will not suffice to switch modes if
the current value of the MOOS variable \mvar{RETURN} is set to
\var{true}. See the mode declarations near the top of the
\var{delta.bhv} file for this mission - a command to return overrides
a command to perform a survey. The second line above associates with a
left-mouse click a posting to the \msvar{SURVEY\_UPDATES}
variable. Recall from Listing \ref{lst_delta_wsurvey} that this
is the very variable through which the surveying waypoint
behavior is configured to receive dynamic parameter updates. This
posting is configured with a few macros, \var{\$(VNAME)},
\var{\$(XPOS)}, \var{\$(YPOS)}, which are filled in with the name and
position of the current vehicle in the \app{pMarineViewer} window
. Each user left-mouse click thus re-assigns the vehicle to a new
survey pattern, and switches the helm mode, unless it has been
commanded to return.

%-------------------------------------------------------------------
\subsection{Suggestions for Further Experimenting with the Delta Mission}

%-------------------------------------------------------------------
\subsubsection{Failing to Reason about Depth}

In this mission, {\em depth} is a mandatory helm decision variable,
along with {\em course} and {\em speed}, as configured in
\var{delta.moos} and shown in Listing \ref{helm_with_depth}. If a
mission is not configured properly it's possible to bring about a helm
mode where no behavior is reasoning about depth. Declaring {\em depth}
to mandatory is equivalent to declaring that a situation where a helm
iteration with no decision on {\em depth} is an error condition worth
of an all-stop.

\vspace{0.1in}
\noindent
One way to bring this about in this mission, is to reconfigure the
ConstantDepth behavior configuration in \var{delta.bhv} to replace
line 6 in Listing \ref{lst_delta_constdepth} with the following

\prevbhv
\begin{verbatim}
    condition = (MODE==LOITERING)
\end{verbatim}
\postverb
  
\noindent
By doing this, there will be no {\em depth} related behavior when the
vehicle is in the \var{RETURNING} mode. Try re-running the mission.
Note when the mission is first launched, the label next to the vehicle
in \app{pMarineViewer} reads \var{"dudley (PARK)(ManualOverride)"}.
This is normal and indicates that the helm state is \var{PARK}, simply
because the operator retains manual control. In addition to seeing
this in the \app{pMarineViewer} window, this can also be confirmed by
scoping on a few key helm variables including \mvar{IVPHELM\_STATE}
and \mvar{IVPHELM\_ALLSTOP}:

\vspace{0.15in}
\begin{consoleverb}
 $ uXMS delta.moos IVPHELM_STATE IVPHELM_ALLSTOP BHV_ERROR --show=source,time,community
\end{consoleverb}
\vspace{0.15in}

\noindent
should produce something similar to:

\vspace{0.15in}
\noindent
\begin{consoleverb}
  VarName            (S)ource    (T)ime      (C)ommunity   VarValue (MODE = SCOPE:PAUSED)
  ----------------   ----------  ----------  ----------    ----------- (61)
  IVPHELM_STATE      pHelmIvP    81.86       dudley        "PARK"
  IVPHELM_ALLSTOP    pHelmIvP    1.69        dudley        "ManualOverride"
  BHV_ERROR           n/a         n/a         n/a          n/a
  MODE                n/a         n/a         n/a          n/a
\end{consoleverb}
\vspace{0.15in}

\noindent
Note that the \mvar{IVPHELM\_ALLSTOP} value is posted once, until its value
changes, and \mvar{IVPHELM\_STATE} posts its value on every helm iteration
regardless of the value. The latter variable also serves the purpose of 
a helm heartbeat indicator.

\vspace{0.1in}
\noindent
After noting the above, launch the mission by hitting the \var{DEPLOY}
button, and note that the label next to the vehicle has changed to
\var{"dudley (LOITERING)"}. The four MOOS variables from above have
also changed to:

\vspace{0.15in}
\noindent
\begin{consoleverb}
 VarName            (S)ource    (T)ime      (C)ommunity   VarValue (MODE = SCOPE:PAUSED)
 ----------------   ----------  ----------  ----------    ----------- (103)
 IVPHELM_STATE      pHelmIvP    109.56      dudley        "DRIVE"
 IVPHELM_ALLSTOP    pHelmIvP    98.07       dudley        "clear"
 BHV_ERROR           n/a         n/a         n/a          n/a
 MODE               pHelmIvP    98.07       dudley        "ACTIVE:LOITERING"
\end{consoleverb}
\normalsize
\vspace{0.15in}

After the vehicle has been running a bit, try hitting the \var{RETURN}
button which changes the helm to the \var{RETURNING} mode.  In this
case, due to our tinkering with the mission above, there is no
behavior reasoning about depth, and the following message appears next
to the vehicle on the screen: \var{"dudley
  (Returning)(MissingDecVars:depth)"}. The four scoped MOOS variables 
also change to the following:

\vspace{0.15in}
\noindent
\begin{consoleverb}
 VarName            (S)ource    (T)ime      (C)ommunity   VarValue (MODE = SCOPE:PAUSED)
 ----------------   ----------  ----------  ----------    ----------- (134)
 IVPHELM_STATE      pHelmIvP    621.34      dudley        "DRIVE"
 IVPHELM_ALLSTOP    pHelmIvP    617.09      dudley        "MissingDecVars:depth"
 BHV_ERROR          pHelmIvP    621.59      dudley        "MissingDecVars:depth"
 MODE               pHelmIvP    617.09      dudley        "ACTIVE:RETURNING"
\end{consoleverb}
\vspace{0.15in}

\noindent
Note that, despite the error and all-stop event, the helm remains in
drive, and may return to loitering or surveying at any time. Try
configuring the helm in \var{delta.moos} to contain the line
\pvar{park\_on\_allstop}\psvar{=true} and note the difference in the
above experiment. The generated error will bump the helm into the
\var{PARK} helm status.



\newpage
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/delta_one.png}
  \caption{{\bf The Delta Mission (1):} The vehicle \var{"dudley"}
    heads to its loiter region where it will remain indefinitely until
    it is commanded to return or perform a survey pattern. It will
    periodically surface for a GPS fix.}
\label{fig_delta_one}
\end{figure}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/delta_two.png}
  \caption{{\bf The Delta Mission (2):} The user has clicked a point
    in the viewer around which a survey pattern is built. The vehicle
    exits the loitering mode and begins to execute the survey
    pattern.}
\label{fig_delta_two}
\end{figure}

\newpage
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/delta_three.png}
  \caption{{\bf The Delta Mission (3):} Once the vehicle has finished
    the survey pattern, it re-enters the loiter mode returning to its
    loiter region. It resumes periodic surfacing and immediately
    surfaces for a GPS fix.}
\label{fig_delta_three}
\end{figure}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/delta_four.png}
  \caption{{\bf The Delta Mission (4):} After resumption of loitering,
    the user clicks in the viewer a new point around which a new
    survey pattern is built. The entry point of the survey pattern
    automatically accommodates the vehicle.}
\label{fig_delta_four}
\end{figure}
</pre></body></html>