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

\small
\begin{longtable}{rp{0.76\textwidth}}
  \bsvar{Behaviors:} &amp; Loiter, StationKeep, Waypoint \\ 
  
  \bsvar{MOOS Apps:} &amp; \app{pHelmIvP}, \app{pLogger}, \app{uSimMarine},
  \app{pMarinePID}, \app{pNodeReporter}, \app{pMarineViewer},
  \app{uTimerScript} \\ 
  
  \bsvar{Primary Topics:} &amp;
  (1) Hierarchical Mode Declarations \newline
  (2) The Loiter behavior \newline
  (2a) Loiter traversal - Clockwise vs. counter-clockwise \newline
  (2b) Loiter polygon shapes, hexagons, ellipses \newline
  (2c) Loiter dynamic changes to the polygon center position \newline
  (2d) Loiter robustness to periodic external forces \newline
  (3) The StationKeep Behavior \\ 

  \bsvar{Side Topics:} &amp;
  (1) \app{uTimerScript} is used to simulate wind gusts, external forces \newline
  (2) Use of \app{pMarineViewer} action buttons and action 
    pull-down menu \\ 

\end{longtable}
\normalsize

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

The charlie mission may be launched from the command line in the following 
manner:

\vspace{0.15in}
\noindent
\begin{consoleverb}
 $ cd moos-ivp/missions/s3_charlie/
 $ ./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_charlie_one}, with a single vehicle, {\em henry}, initially
in the PARK mode. After hitting the \var{DEPLOY} button in the
lower right corner, the vehicle enters the \var{"LOITERING"} mode and
begins to proceed to the polygon shown. To get a quick feel for what's
possible in this simulation, the following are some things to try. (a)
Click on the \var{"CWISE"} and \var{"CCWISE"} buttons to change the
direction of loitering around the polygon. (b) Click the \var{RETURN}
and \var{DEPLOY} buttons repeatedly to see the vehicle switch between
two primary modes. (c) Select the \var{"WIND\_GUSTS=true"} option in
the \var{ACTION} pull-down menu to see the vehicle adjust to random
periodic external forces. (d) Select the \var{"STATION\_KEEP=true"}
option in the \var{ACTION} pull-down menu to see how the vehicle
station keeps with simulated wind gust. (e) Let the vehicle return to
its return point and watch how it automatically switches to the
station keeping mode, and then re-deploy it. (f) Select the ellipse
polygon from the \var{ACTION} pull-down menu to see a different loiter
shape. (g) Select the different center points for the loiter ellipse
from the \var{ACTION} pull-down menu to see just the location of the
loiter polygon change and the vehicle adjust.

%====================================================================
\subsection{Topic \#1:  Hierarchical Mode Declarations in the Charlie Mission}
\label{charlie_t1}

The Charlie mission is organized by hierarchical mode declarations
into four modes: \var{INACTIVE}, \var{LOITERING}, \var{RETURNING}, and
\var{STATION-KEEPING}. The mode declarations are given a the top of
the \var{charlie.bhv} file and shown again in Figure
\ref{fig_charlie_hmd}. The \app{pMarineViewer} application by default
shows the vehicle's mode alongside the vehicle name, and when the
simulation is first launched, the Charlie vehicle is shown on the
screen with the mode \var{PARK}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/hmd-charlie.png}
  \caption{{\bf Charlie Mission Mode Declarations:} The helm, when in
    drive, will be in one of the four modes indicated by the leaf
    nodes on the tree. The hierarchical mode structure means, for
    example, that when the vehicle is in the \vvar{"RETURNING"} mode,
    it is also considered to be in the \vvar{"ACTIVE"} mode. The
    vehicle mode, by default, is displayed alongside the vehicle name
    in the \aapp{pMarineViewer} window.}
\label{fig_charlie_hmd}
\end{figure}
\vspace{0.1in}

The \var{"PARK"} mode displayed with the vehicle when the simulation
is launched is actually the high level helm state.  As described in
Section \ref{sec_helm_state}, the helm has a higher level {\em helm
  state} which is either \var{PARK} or \var{DRIVE}, analogous to a
car in either the "Park" or "Drive" modes. When the Charlie mission is
first launched, the helm is not yet in drive, and is put into drive
when the \var{DEPLOY} button is hit. This button is configured in the
\app{pMarineViewer} configuration block to make several MOOS pokes
with a single button click. It posts
\mvar{MOOS\_MANUAL\_OVERRIDE}\msvar{=false}, to put the vehicle in the
\var{DRIVE} helm state. It posts \msvar{DEPLOY=true} to put the
helm in the \var{ACTIVE} mode, and it posts \msvar{LOITER=true} to put
the helm in the \var{ACTIVE:LOITERING} mode.

\pskip

The Charlie mission is configured to allow for easy transition between
the other modes via the \app{pMarineViewer} interface. The vehicle may
be put into the \var{STATION-KEEPING} mode at any time via the
\msvar{STATION\_KEEP=true} option in the \var{ACTION} pull-down menu
in \app{pMarineViewer}. This does nothing more than make the
\msvar{STATION\_KEEP=true} post to the MOOSDB. The same could have
been accomplished by uPokeDB for example:

\vspace{0.18in}
\noindent
\begin{consoleverb}
 $ cd moos-ivp/missions/s3_charlie/
 $ uPokeDB charlie.moos STATION_KEEP=true
\end{consoleverb}
\normalsize
\vspace{0.18in}


\noindent
Referring to the mode declarations in Figure \ref{fig_charlie_hmd},
the \var{LOITERING} and \var{RETURNING} modes both have the condition
\var{STATION\_KEEP != true}, so both of those mode requirements fail
to be satisfied. The \var{STATION-KEEPING} mode is the default mode,
i.e., the "else" mode when the requirements of the \var{RETURNING}
mode are not met.  The \msvar{STATION\_KEEP=true} posting could also
have been made by another MOOS process, for example, connected to an
acoustic modem, an Iridium satellite, or wifi interface.

\pskip

The helm mode is communicated to \app{pMarineViewer} from the helm via
the MOOS variable \mvar{IVPHELM\_SUMMARY}. This variable is parsed and
the mode is rendered next to the vehicle name in the viewer. This
rendering may be turned off by toggling through the "name options",
with the \var{'n'} key, or setting the \bvar{vehicles\_name\_viewable}
parameter in the \app{pMarineViewer} configuration block to one of the
values described in the "Vehicles Pull-Down Menu" Section of
\cite{url_pmv}.

%==================================================================
\subsection{Topic \#2: The Loiter Behavior}
\label{charlie_t2}

The \var{LOITERING} mode in the Charlie mission is characterized by
the \var{BHV\_Loiter} behavior, and we explore some of capabilities
and options for this behavior here.  The behavior configuration, in
file \var{charlie.bhv} is shown in Listing \ref{lst_charlie_loiter}
below.  The first configuration block, in lines 3-6, are for
parameters defined generally for all IvP Helm behaviors, and the
second block, in lines 8-16, are for parameters defined explicitly for
the Loiter behavior.

\vspace{0.18in}
\begin{listing}{Configuration of the Loiter behavior in the Charlie mission, from the file charlie.bhv}
\label{lst_charlie_loiter}
\footnotesize
\begin{verbatim}
  1  //----------------------------------------------
  2  Behavior = BHV_Loiter
  3  {
  4    name      = loiter
  5    priority  = 100
  6    condition = MODE==LOITERING
  7    updates   = UP_LOITER
  8  
  9             speed = 1.3
 10         clockwise = false
 11    capture_radius = 4.0
 12         nm_radius = 15.0
 13           polygon = format=radial, x=0, y=-75, radius=40, pts=6, snap=1,
 14      visual_hints = nextpt_color=white, nextpt_lcolor=khaki
 15      visual_hints = edge_color=blue, vertex_color=yellow
 16      visual_hints = edge_size=1, vertex_size=2, label=LOITER_POLYGON
 17  }
\end{verbatim}
\end{listing}
\normalsize
 
\noindent
When the vehicle is first deployed, it heads to the hexagon shaped
polygon shown in Figure \ref{fig_charlie_one}, configured in line 13.
It traverses the polygon in a counter-clockwise manner due to the
configuration in line 10. The Loiter behavior maintains an internal
mode, the \var{"acquire\_mode"} which is true when the vehicle
is not sufficiently close to the polygon, defined by the
\bvar{acquire\_dist} parameter which is by default 10 meters. It also
keeps track of how many vertex arrivals come by way of achieving the
capture radius, and how many by way of the non-monotonic radius. These
internal state variables are summarized by the Loiter behavior by
publishing a variable \mvar{LOITER\_REPORT}. An example might look
like:

\prevgreen
\begin{verbatim}
  LOITER_REPORT = "index=2,capture_hits=12,nonmono_hits=3,acquire_mode=false"
\end{verbatim}
\postverb

In the Charlie mission, \app{pMarineViewer} is configured to scope
on this variable by default, and the evolving \mvar{LOITER\_REPORT}
may be monitored as the vehicle progresses around the polygon.

%-------------------------------------------------------------------
\subsubsection{Loiter Traversal - Clockwise vs. Counter-Clockwise} 
\label{charlie_t2a}

The traversal direction of the Loiter behavior is by default clockwise
and can be set to counter-clockwise with the parameter
\bvar{clockwise}\bsvar{=false}. In the Charlie mission, the traversal
direction can be changed by selecting \mvar{UP\_LOITER} \msvar{=
  clockwise=true} and \msvar{UP\_LOITER=clockwise=false} from the
\var{ACTION} pull-down menu. This is a good way to observe the
algorithm used by the behavior to acquire the polygon when
sufficiently far inside the polygon. The traversal direction could
also have been affected by any other MOOS application capable of
executing the above two MOOS pokes, including uPokeDB, or any
application connected to a communications device.

%-------------------------------------------------------------------
\subsubsection{Loiter Polygon Shapes, Hexagons, and Ellipses}
\label{charlie_t2b}
The only restriction on the shape traversed by the Loiter behavior is
that it be a convex polygon. The typical specification of the polygon
is shown in line 13, via the "radial" syntax, which accepts a center
position (\var{"x=0, y=-75"}), a distance from the center point to
each vertex (\var{"radius=40"}), the number of points in the polygon,
(\var{"pts=6"}), and a snap value, which rounds the vertex positions
to, in this case, the nearest whole meter (\var{"snap=1"}). Ellipse 
shapes are supported with a string such as:

\prevbhv
\begin{verbatim}
  polygon = format=ellipse, x=110, y=-75, degs=150, pts=14, major=80, minor=20
\end{verbatim}
\postverb

\noindent
The above ellipse specification is selectable in the Charlie mission
via the \var{ACTION} pull-down menu. If selected while in the loiter
mode, the vehicle immediately begins traversing to this new polygon,
as shown in Figure \ref{fig_charlie_two}.

%-------------------------------------------------------------------
\subsubsection{Loiter Dynamic Changes to the Polygon Position}
\label{charlie_t2c}

In addition to the an outright change to the loiter polygon as
described above, which includes shape changes, number of vertices and
position, there are a few methods for just changing the polygon
position while leaving the other characteristics in tact. The Loiter
behavior accepts a parameter for just the center position. The following
two such assignments are selectable in the \var{ACTION} pull-down
menu in the \app{pMarineViewer} for the Charlie mission:

\prevbhv
\begin{verbatim}
  center_assign = 40,-40
  center_assign = x=100, y=-80
\end{verbatim}
\postverb

\noindent
Try selecting either of these options, with the polygon set to either
the hexagon or ellipse and confirm that only the position changes. One
other method for affecting the polygon position is via the
\var{center\_activate} parameter, which is \var{false} by
default. When set to \var{true}, the polygon center is set to be the
vehicle's present position when the Loiter behavior enters the running
state. In the Charlie mission, try selecting
\var{center\_activate=true} from the \var{ACTION} pull-down menu. If
already in the \var{LOITERING} mode, then nothing happens immediately.
If and when the helm exits and returns to the \var{LOITERING} mode,
for example after clicking the \var{RETURN} button, and then the
\var{DEPLOY} button again, note that the loiter polygon is centered on
the vehicle's present position. The \bvar{center\_activate} feature is
particularly useful when the Loiter behavior is used more or less as a
station keeping behavior and one wants to be able to command the
vehicle to loiter at the present position at any given time.

%-------------------------------------------------------------------
\subsubsection{Loiter Robustness to Periodic External Forces}
\label{charlie_t2d}

When the Loiter behavior is active and the vehicle is proceeding
around the polygon vertices, it is proceeding more or less like the
Waypoint behavior (both behaviors share the same WaypointEngine class
as a sub-component). Things get interesting when the vehicle is
approaching the polygon from the outside or from a distance internally
(for example when the \bvar{center\_activate} parameter set to
\var{true}. To test and demonstrate this robustness, the Charlie
mission is configured with the uTimerScript utility to generate
periodic random forces to simulate wind gusts, to push the vehicle off
the loiter polygon in unpredictable ways. An example is shown in
Figure \ref{fig_charlie_three}.

\pskip

The simulated wind gusts may be activated by selecting the
\var{WIND\_GUSTS=true} option from the \app{pMarineViewer}
\var{ACTION} pull-down menu. The details of the simulated forces can
be found in the uTimerScript configuration block in the
\var{charlie.moos} file.  The script works by posting external force
vectors to the MOOS variable \mvar{USM\_DRIFT\_VECTOR\_ADD}, which is
read by the \app{uSimMarine} application to alter the prevailing
external force vector, which by default has a magnitude of zero. The
syntax of the \app{uTimerScript} script to implement the drift effects
in this example are described in more detail in the "A Script as a
Proxy for Simulating Random Wind Gusts" Section of the \app{uTimerScript}
documentation, \cite{url_utimerscript}.

%(a) clockwise v. counter clockwise
%(b) changing the center position only
%(c) setting the center position to be where it activates
%(d) robustness to external forces
%(e) tinkering with the radius and nm_radius to near-zero values.

%=====================================================================
\subsection{Topic \#3: The StationKeep Behavior}
\label{charlie_t3}

The \var{STATION-KEEPING} mode in the Charlie mission is characterized
by the \var{BHV\_StationKeep} behavior, and we explore some of
capabilities and options for this behavior here.  The behavior
configuration, in file \var{charlie.bhv} is shown in Listing
\ref{lst_charlie_skeep} below.  The first configuration block, in
lines 3-5, are for parameters defined generally for all IvP Helm
behaviors, and the second block, in lines 7-11, are for parameters
defined explicitly for the Loiter behavior.

\vspace{0.18in}
\begin{listing}{Configuration of the StationKeep behavior in the Charlie mission, from the file charlie.bhv}
\label{lst_charlie_skeep}
\footnotesize
\begin{verbatim}
  0  //----------------------------------------------
  1  Behavior = BHV_StationKeep
  2  {
  3    name      = station-keep
  4    priority  = 100
  5    condition = MODE==STATION-KEEPING
  6   
  7    center_activate = true 
  8       inner_radius = 5 
  9       outer_radius = 10  
 10        outer_speed = 1.0
 11         swing_time = 0
 12  }
\end{verbatim}
\end{listing}
\normalsize
 
%----------------------------------------------------------------------
\subsubsection{Putting the Vehicle into the Station Keeping Mode}

The vehicle is put into the station keeping mode by posting
\msvar{STATION\_KEEP=true} to the MOOSDB. This results in the helm
mode, represented by the MOOS variable \var{MODE}, being set to
station keeping. The hierarchical mode declarations used in the
Charlie mission are declared in the top of the \var{charlie.bhv} file
and were shown in Figure \ref{fig_charlie_hmd}. The StationKeep
behavior is conditioned on \var{MODE==STATION-KEEPPING}, on line 5
above. The StationKeep behavior may be configured to station keep at a
specified point in water (with the \bvar{station\_pt} parameter), or
it may be configured to station keep wherever it happens to be when it
enters or re-enters the running state, as it is configured in the
Charlie mission by virtue of line 7 above. In the Charlie mission,
\app{pMarineViewer} is configured with four on-screen buttons. For
more info, see the "Command-and-Control" section of the
\app{pMarineVeiwer} documentation, \cite{url_pmv}. Two of the buttons
are used for toggling the \mvar{STATION\_KEEP} variable to the MOOSDB.

%----------------------------------------------------------------------
\subsubsection{What is Happening in the Station Keeping Mode} 

The station keeping behavior (the only running behavior in this mode)
attempts to keep the vehicle within a certain distance, given by 
the \bvar{inner\_radius}  parameter, to a center point. Inside this
radius, it simply lets the vehicle drift. Outside the radius it
sets a heading and speed to drive the vehicle back to the center point.
The speed decreases as it approaches the inner circle, and is 
at its highest speed (set by the \bvar{outer\_speed} parameter on 
line 10 above) when its range to the center point is greater than
that given by the \bvar{outer\_radius} distance. It also 
makes two postings to the \mvar{VIEW\_POLYGON} object to represent
the circles implied by the \bvar{inner\_radius} and \bvar{outer\_radius}
parameters, as shown in Figure \ref{fig_charlie_four}.

%=====================================================================
\subsection{Suggestions for Tinkering in the Charlie Mission}

\begin{itemize}

\item Station keeping is trivial if the vehicle doesn't drift. Try turning
on the artificial wind gusts available in the Charlie mission, 
courtesy of the \app{uTimerScript} script, available by selecting 
\var{WIND\_GUSTS=true} from the Action pull-down menu. The vehicle
performance is a bit more interesting now in the station keeping mode.

\item Try configuring the simulator, \app{uSimMarine}, to reflect a
  vehicle that takes much more time to come to a full stop in the
  water.  This can be done by setting \pvar{deceleration}\psvar{=0.1}
  in the \app{uSimMarine} configuration block, or by posting
  \mvar{USM\_DECELERATION}\msvar{=0.1} to the MOOSDB once the mission
  is running. Note that when the vehicle is put into station keeping
  mode, its station point is set to the point where it is when it
  enters this mode. Since the vehicle takes so long to slow down, it
  immediately drifts out of the inner radius and turns around 180
  degrees. This is a typical situation seen in the field. This can be
  countered a bit by setting the \bvar{swing\_time} parameter in the
  StationKeep behavior. This parameter is the number of elapsed
  seconds after the vehicle enters the station keeping mode before the
  station keeping behavior marks its present position as the point to
  station keep around. Try setting \bsvar{swing\_time=5} and re-running
  the above to see the difference.
\end{itemize}


\newpage
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/charlie_one.png}
  \caption{{\bf The Charlie Mission (1):} The vehicle \var{"charlie"}
    proceeds to a loiter polygon, traversing in a counter-clockwise
    manner to the first waypoint labelled \var{"charlie's next
      waypoint"}.}
  \label{fig_charlie_one}
\end{figure}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/charlie_two.png}
  \caption{{\bf The Charlie Mission (2):} The loiter traversal polygon
    for the vehicle \var{"charlie"} has been dynamically changed to an
    ellipse via a selection from the \vvar{ACTION} pull-down menu.}  
  \label{fig_charlie_two}
\end{figure}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/charlie_three.png}
  \caption{{\bf The Charlie Mission (3):} The vehicle, \var{"charlie"}
    recovers from a wind gust and proceeds to re-enter the polygon
    trajectory at the tangential vertex labelled \var{"charlie's next
      waypoint"}.}
  \label{fig_charlie_three}
\end{figure}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/charlie_four.png}
  \caption{{\bf The Charlie Mission (4):} The vehicle \var{"charlie"}
    is put into the station keeping mode. The two rings around the vehicle
    are the \bvar{inner\_radius} and \bvar{outer\_radius} parameters.}
  \label{fig_charlie_four}
\end{figure}

</pre></body></html>