<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
% Include common packages, environments, counters etc
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_lab_format}
\input{common_latex/common_latex_definitions}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

\begin{document}
\wikidoc{file=Lab.ClassHelmAutonomy}
\wikidoc{auth=mikerb@mit.edu}
\helplevelsubsec

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 5 - Introduction to Helm Autonomy}
\vspace{0.1in}
\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.15in}
\labpng{0.5}{figures/arthur_launch.png}
\vspace{0.05in}
\labdate{Feb 20th, 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

%===================================================================
% Add a blank page so first body page is on the right when double-side
\blankpage

%===================================================================
% Begin the body of the text
%===================================================================
\section{Overview and Objectives}
%==================================================================

In today's lab we will create our own autonomy missions by
constructing helm configuration files. Up to now, configuring a MOOS
community has consisted of configuring a single \var{.moos} file. In
using the helm, a second file, referred to as the behavior file, will
be constructed, with suffix \var{.bhv}. We begin with the alpha
mission downloaded along with the moos-ivp tree and proceed by making
our first simple missions emphasizing the usage of the basic helm
features and MOOS autonomy utilities.  This is followed by a couple
more complex applications assignments.

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item The Basic Helm Structure
\item The High-Level Helm State - Putting the Helm into Drive
\item Launching the Alpha Autonomy Mission
\item Understanding the Helm During the Alpha Mission Execution
\item Methods in pMarineViewer for Controlling a Mission
\item Assignment: Modify the Alpha Mission to Accept a User Return Point
\item Assignment: Build the Single Double Loiter Bravo Missions
\item Assignment: A Double Loiter Bravo Mission with Periodic Surfacing
\end{packed_itemize}
\end{labinfo}

%==================================================================
\section{Preliminaries}
\label{prelims}

%-----------------------------------------------------------------
\subsection*{Make Sure You Have the Latest Updates}

It is possible we will be making changes to the MOOS-IvP tree during the semester. 
Always make sure you have the latest code:

\begin{consoleverb}
 $ cd moos-ivp
 $ svn update
\end{consoleverb}

\vspace{0.1in}
\noindent
If you see see a response similar to the below, indicating that no updates were
pulled in from the server, then you shouldn't need to re-build the software.

\begin{consoleverb}
Updating '.':
At revision 9615.
\end{consoleverb}

\vspace{0.1in}
\noindent
Otherwise you will need to rebuild:

\begin{consoleverb}
 $ ./build-moos.sh
 $ ./build-ivp.sh
\end{consoleverb}

%-----------------------------------------------------------------
\subsection*{Make Sure Key Executables are Built and In Your Path}

This lab does assume that you have a working MOOS-IvP tree checked out
and installed on your computer. To verify this make sure that the
following executables are built and findable in your shell path:

\begin{consoleverb}
 $ which MOOSDB
 /Users/you/moos-ivp/bin/MOOSDB
 $ which pHelmIvP
 /Users/you/moos-ivp/bin/pHelmIvP
\end{consoleverb}

\noindent
If unsuccessful with the above, return to the steps in Lab 1:

\urlxx{http://oceanai.mit.edu/ivpman/labs/machine_setup}{Lab.ClassSetup}

%-------------------------------------------------------------------
\subsection*{Where to Build and Store Lab Missions}

As with previous labs, we will use your version of the
\var{moos-ivp-extend} tree, which by now you should have re-named
something like \var{moos-ivp-jsmith}, where your email may be
\var{jsmith@mit.edu}. In this tree, there is a missions folder:

\begin{consoleverb}
 $ cd moos-ivp-extend
 $ ls
 CMakeLists.txt  bin/        build.sh*     docs/     missions/       src/
 README          build/      data/         lib/      scripts/
\end{consoleverb}

\noindent
For each distinct assignment in this lab, there should be a
corresponding subdirectory in a \var{lab\_05} sub-directory of the
\var{missions} folder, typically with both a \var{.moos} and
\var{.bhv} configuration file. See Section \ref{sec_hand_in} for the 
full requested file structure.

%---------------------------------------------------------------------
\subsection*{Documentation Conventions}

To help distinguish between MOOS variables, MOOS configuration
parameters, and behavior configuration parameters, we will use the
following conventions:

\begin{packed_itemize}[3]
\item Applications or any executables are rendered in \app{magenta}, such
  as \app{MOOSDB} or \app{pHelmIvP}.
\item MOOS variables are rendered in \mvar{green}, such as
  \mvar{IVPHELM\_STATE}, as well as postings to the \app{MOOSDB}, such
  as \mvar{DEPLOY=true}.
\item MOOS configuration parameters are rendered in \pvar{blue}, such
  as \pvar{AppTick=10} and \pvar{verbose=true}.
\item Behavior  parameters are rendered in \bvar{brown},
  such as \bvar{priority=100} and \bvar{endflag=RETURN=true}.
\end{packed_itemize}

%==========================================================================
\subsection*{More MOOS / MOOS-IvP Resources}

A few further resources are worth mentioning for following up this lab
with your own exploration.

\begin{packed_itemize}[2]
\item See the slides from the today's class which give a bit more
  background into marine autonomy and the IvP Helm: 
  \urlx{http://oceanai.mit.edu/2.680/docs/2.680-06-intro\_to\_autonomy\_2025.pdf}
\item The IvP Helm and Utilities documentation:
  \urlx{http://oceanai.mit.edu/ivpman}
\item The moos-ivp.org website documentation:
  \urlx{http://www.moos-ivp.org}
\end{packed_itemize}

%==========================================================================
\section{The Basic Helm Structure}

In the course of today's lab it may be helpful to keep in mind the
high-level components of the helm and flow of events covered in
today's class.  The key components to keep in mind are shown in Figure
\ref{fig_helmarch} below. All behaviors produce either an objective
function, or a set of variable-values pairs posted to the
\app{MOOSDB}. The helm minimally posts, on each iteration, a set of
variable-value pairs representing the current decision. This is
typically \msvar{DESIRED\_HEADING} and \msvar{DESIRED\_SPEED}, but also
\msvar{DESIRED\_DEPTH} when the helm is implemented on an underwater
vehicle.

\vspace{0.2in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/helmarch.png}
  \caption{{\bf The Helm Iterate Loop:} (1) Mail is read from the
    \aapp{MOOSDB}. It is parsed and stored in a local buffer to be
    available to the behaviors. (2) If there were any mode
    declarations in the mission behavior file, they are evaluated at
    this step. (3) Each behavior is queried for its contribution and
    may produce an IvP function and a list of variable-value pairs to
    be posted to the \aapp{MOOSDB} at the end of the iteration. (4)
    The objective functions are resolved to produce an action,
    expressible as a set of variable-value pairs. (5) All
    variable-value pairs are published to the \aapp{MOOSDB} for other
    MOOS processes to consume.}
\label{fig_helmarch}
\end{figure}
\vspace{0.15in}

\noindent
The behaviors get their information from a common data structure on
each iteration. This information buffer gets its information from the
\app{MOOSDB} by processing mail just like any other MOOS app. The
behaviors perform their function effectively in parallel. Internally
the helm calls for their contribution in sequence, but since they all
operate on an identical information buffer, and no behavior produces
output used by any other behavior as input, they are essentially
operating independently and in parallel. Behavior coordination takes
place in the solver, ultimately choosing a single decision of
\var{heading}, \var{speed} and \var{depth}. Additionally, any 
behavior may post a variable-value pair to the \app{MOOSDB} read by
another behavior on the {\em next} iteration.  However, within a given
iteration, behaviors are essentially independent.



%==========================================================================
\section{Putting the Helm into Drive: The High-Level Helm State}

One of the first topics encountered in using the helm is how to turn
it loose!  The helm's highest level state description is simple - it
is in the \var{PARK} or \var{DRIVE} state:

\vspace{0.2in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.63\textwidth]{figures/helm_engage.png}
  \caption{{\bf The Helm State of the IvP Helm}: The helm state has a
    value of either \vvar{PARK} or \vvar{DRIVE}, depending on both how
    the helm is initialized and the mail received by the helm after
    start-up on the variable \vvar{MOOS\_MANUAL\_OVERRIDE}. The helm
    may also park itself if an all-stop event has been detected.}
\label{fig_helm_state}
\end{figure}

\vspace{0.15in}
\noindent
Often when a mission is launched, the helm begins in the park state,
and the user {\em deploys} the vehicle by putting it into drive. This
is done by changing (poking) the MOOS variable
\mvar{MOOS\_MANUAL\_OVERRIDE} from true to false.  The helm state may
simply be apparent by watching what is going on in the GUI, and often
the helm state is also rendered next to the vehicle in a GUI like
\app{pMarineViewer}. But one may also confirm the helm state by
scoping on the variable \mvar{IVPHELM\_STATE}.

\vspace{0.1in}
\noindent
Just because a vehicle is not moving doesn't mean the high-level helm
state is in park. As with driving a car, there may be several reasons
why a car is not moving while the car is still in drive (traffic
light, pedestrian crossing, stopping to look at a road sign,
etc.). Further information regarding {\em why} a vehicle is stopped
may be gleaned from scoping on the MOOS variable
\mvar{IVPHELM\_ALLSTOP}. We will explore some cases in the first
exercise.

%======================================================================
\newpage \section{Experimenting with and Modifying the Alpha Example Mission}
%======================================================================

In the first exercise in today's lab, the goal is to use the alpha
example mission to explore a few ideas with the helm and tools
available for configuring and interacting with the helm.  As the very
first step, we begin by updating the moos-ivp tree and making sure we
have the very latest version of the moos-ivp trunk:

\begin{consoleverb}
 $ cd moos-ivp
 $ git pull
 Already up to date.
 $ ./build-moos.sh
 $ ./build-ivp.sh
\end{consoleverb}

\noindent
Assuming there were no problems with the update and build, everything
should be ready to go.

%===========================================================================
\subsection{The basics of launching an autonomy mission}

In this part we will:
\begin{packed_itemize}[2]
  \item Prepare a copy of the alpha mission for experimenting
  \item Examine the alpha mission file structure
  \item Launch the alpha mission using MOOS time warp.
  \item Recognize when something has gone wrong
\end{packed_itemize}

%---------------------------------------------------------------------------
\subsubsection{Make a copy of the alpha mission}

In this lab we will mostly be building and modifying mission files
rather than writing source code. The mission files consist of
\var{.moos} (MOOS) files, and \var{.bhv} (Helm) files. The first step
is to copy the alpha example mission from the moos-ivp tree into your
own moos-ivp-extend tree. As with lab 4, this directory is what you will
be submitting in later problem sets, so it's good to begin the habit
of working in this directory.

\vspace{0.15in}
\begin{consoleverb}
 $ mkdir moos-ivp-jsmith/missions/lab_05
 $ cp -rp moos-ivp/ivp/missions/s1_alpha  moos-ivp-jsmith/missions/lab_05/alpha
\end{consoleverb}

\vspace{0.15in}
\noindent
(Note in the \cmd{cp} command we use the \var{-r} switch to recursively copy
the entire directory and the \var{-p} switch to preserve file meta data
such as mode, ownship and timestamps.)

%---------------------------------------------------------------------------
\subsubsection{Note the MOOS and helm mission file structures}

Note that the alpha mission has two files; the MOOS mission file, and the helm 
behavior file. The \var{alpha.moos} contains a configuration block for the 
\app{pHelmIvP} MOOS app (the helm). This block looks like:

\vspace{0.15in}
\begin{fileverb}
  1  ProcessConfig = pHelmIvP
  2  {
  3    AppTick    = 4
  4    CommsTick  = 4
  5    
  6    behaviors  = alpha.bhv
  7    domain     = course:0:359:360
  8    domain     = speed:0:4:41
  9  }
\end{fileverb}
\vspace{0.15in}

\noindent
The two immediately important components of this are (a) the
indication of the behavior file on line 6, and (b) the decision domain
specified in lines 7 and 8.  The latter indicates that the helm is
expected to make a decision for each iteration on the desired heading
and speed of the vehicle. The possible heading values are between 0
and 359 on one-degree increments, and the possible speed values are
between 0 and 4 meters per second in 0.1 m/s increments.

%------------------------------------------------------------------------
\subsubsection{Launch and experiment with MOOS time warp}

The alpha mission is described in a fair amount of detail in the helm
documentation:

\urlxx{http://oceanai.mit.edu/ivpman/examples/alpha}{Helm.XMissAlpha}

\vspace{0.1in}
\noindent
Take a few minutes to read this through and then go ahead and launch the mission:

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

\noindent
Or you can launch the mission with the launch script as below. This will
launch \app{pAntler} and then launch the \app{uMAC} interactive utility.

\vspace{0.05in}
\begin{consoleverb}
 $ cd moos-ivp-jsmith/missions/lab_05/alpha/
 $ ./launch.sh
\end{consoleverb}
\vspace{0.15in}



\noindent
Things should look similar to the figure in the alpha mission
description.  One thing you may notice right away is that the
simulation progresses slowly.  This may be sped up by altering the
\pvar{MOOSTimeWarp}. This parameter is set to 1 at the top of the
.moos file. Try changing this to something, like 20, and
re-launch. You will find that the using a higher time warp is often
essential for quick experimentation. A short-cut for using the time
warp is to pass the time warp to \cmd{pAntler} on the command-line
rather than editing the line in the MOOS file. This is done by:

\vspace{0.15in}
\begin{consoleverb}
 $ pAntler --MOOSTimeWarp=20
\end{consoleverb}
\vspace{0.1in}

\noindent
Many mission folders also have a launch script (\var{launch.sh}) to make 
launching even easier, especially with multi-vehicle missions we encounter
later on. So you could also launch the alpha mission with:

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

\vspace{0.1in}

\noindent
where 20 is the time warp.


%======================================================================
\subsection{Understanding the helm during mission execution}

In this part we will:
\begin{packed_itemize}[1]
  \item Find the vehicle helm-state during mission execution
  \item Understand the difference between helm-state and all-stop status
  \item Understand the behavior condition and endflag parameters
\end{packed_itemize}

%-----------------------------------------------------------------------
\subsubsection{Find the vehicle helm state during mission execution}

The helm may be characterized at its highest level by two MOOS variables,
\mvar{IVPHELM\_STATE} and \mvar{IVPHELM\_ALLSTOP}. These two issues are
described in Sections 6.2 and 6.3 in the helm documentation:

\vspace{0.1in}
\noindent
\urlx{http://oceanai.mit.edu/ivpman/helm/helm\_state}
\vspace{0.1in}

\noindent
Take a few minutes to read this through. 

\vspace{0.1in}
\noindent
The helm-state and all-stop status may be determined at run-time by
simply scoping on the two MOOS variables. In typical \app{pMarineViewer}
configurations, they are also typically viewable right next to the
vehicle icon. When you launch the alpha mission, you should see the
following text right next to the vehicle icon: \var{"(PARK)(Manual
  Override)"}. The first indicates the helm-state, and the second
indicates the all-stop status. When the vehicle is deployed by hitting
the \pvar{DEPLOY} button, the helm-state changes to \var{DRIVE}, and the
all-stop status disappears. Examination of the \mvar{IVPHELM\_ALLSTOP}
variable would show that it equals \var{"clear"}, but \app{pMarineViewer} is
implemented to just not render the all-stop status when it is equal to
\var{"clear"}. 

%-------------------------------------------------------------------------
\subsubsection{Understand the difference between the helm-state and all-stop status}

The helm-state is always either in \var{PARK} or \var{DRIVE}. The
all-stop status is a way of further indicating why the helm is not
moving the vehicle (equivalent to producing a \mvar{DESIRED\_SPEED}
decision).

\vspace{0.1in}
\noindent
Experiment with this a bit. First note that, in the alpha mission,
once the vehicle completes its waypoints and returns to its mission,
the vehicle is still in the \var{DRIVE} helm-state, but the all-stop status
indicates \var{"NothingToDo"}. This simply means that all behaviors have
{\em completed}, and the mission is effectively over. 

\vspace{0.1in}
\noindent
Try poking the \app{MOOSDB} during the alpha mission with the following variable-data
pair: \mvar{DEPLOY=false}. What happens?

%---------------------------------------------------------------------------
\subsubsection{Understand the behavior condition and endflag parameters}

Two key parameters defined for all behaviors are the \bvar{condition} and 
\bvar{endflag} parameters. They are described here:

\vspace{0.1in}
\urlx{http://oceanai.mit.edu/ivpman/helm/conditions}

\noindent
and

\vspace{0.1in}
\urlx{http://oceanai.mit.edu/ivpman/helm/flags}

\vspace{0.1in}
\noindent
Note in the alpha mission (in \var{alpha.bhv}) the conditions and endflags for 
the waypoint-survey behavior:

\prevbhv
\begin{verbatim}
  condition = RETURN = false
  condition = DEPLOY = true
  endflag   = RETURN = true
\end{verbatim}
\postverb

\noindent
and the conditions and endflags for the waypoint-return behavior

\prevbhv
\begin{verbatim}
  condition  = RETURN = true
  condition  = DEPLOY = true
  endflag    = RETURN = false
  endflag    = DEPLOY = false
\end{verbatim}
\postverb

\noindent
Both behaviors are conditioned on the variable \mvar{DEPLOY} being
true. But the waypoint behavior will only be active if \mvar{RETURN}
is false. Also note that these two conditions are initialized in the
top of the behavior file with the two lines \bvar{initialize
  DEPLOY=false} and \bvar{initialize RETURN=false}.

\vspace{0.1in}
\noindent
When the waypoint-survey behavior completes its set of waypoints, it
posts its endflag, \mvar{RETURN=true}, which is just what the
waypoint-return behavior needs to satisfy its condition and begin
executing.  This mechanism is not only a way to string together a
sequence of behaviors, essentially a {\em plan}, but run conditions
may switch in and out of satisfaction to implement a helm mode-space
where behaviors are periodically active and not active.

%=========================================================================
\subsection{Methods in pMarineViewer for Understanding and Controlling a Mission}

In this part we will:
\begin{packed_itemize}
  \item Use \app{pMarineViewer} buttons for poking the \app{MOOSDB} and
    altering the helm
  \item Scoping with \app{pMarineViewer}
  \item Poking with \app{pMarineViewer} geo-referenced mouse clicks
\end{packed_itemize}
%-------------------------------------------------------------------------
\subsubsection{Use pMarineViewer Buttons for Poking the MOOSDB and Altering the Helm}

In the alpha mission, the \pvar{DEPLOY} button is configured to start
the mission upon a user click. This is not hard-coded in the
\app{pMarineViewer} implementation, but represents how this button was
configured for specific use in this mission. The \app{pMarineViewer}
tool is a primary tool used in this and later labs. It is used for
rendering a mission as it unfolds, and for interacting with the
vehicle while it is deployed. It is used not only in simulation, but
also when deployed on the water. It has a few configuration hooks that
are worth knowing about.

\vspace{0.1in}
\noindent
In the case of the alpha mission, the \pvar{DEPLOY} and \pvar{RETURN}
buttons are configured with the following three lines found in the
\var{alpha.moos} file:

\prevblue
\begin{verbatim}
  button_one = DEPLOY # DEPLOY=true
  button_one = MOOS_MANUAL_OVERRIDE=false # RETURN=false
  button_two = RETURN # RETURN=true
\end{verbatim}
\postverb

\noindent
The syntax and general usage is described in \app{pMarineViewer}
documentation (in the section "Command and Control"). In short, there
are up to twenty configurable buttons, \pvar{button\_one} through
\pvar{button\_twenty}, or \pvar{button\_1} through \pvar{button\_20}.
If they are not configured, they are not shown. They may be configured
to make one or {\em more} distinct pokes upon click.

\vspace{0.1in}
\noindent
Try configuring the third and fourth buttons in the alpha mission to
poke something to the \app{MOOSDB} upon click, and verify this works by
scoping on the variable. This step of creating a specific button
configuration for simple command and control will be a component of
lab assignments frequently in this class. Try it here.

%-------------------------------------------------------------------------
\subsubsection{Scoping with pMarineViewer}

The \app{pMarineViewer} application may also be used as limited scope. The
bottom row of fields in the window show the variable name, time of
last write, and variable value, forming a "single variable scope".
The variable to be scoped is set in the \app{pMarineViewer} configuration 
block with a line like:

\prevblue
\begin{verbatim}
  scope = NAV_X
\end{verbatim}
\postverb

\noindent
Multiple lines may be provided. The scoped variable may be changed via
the MOOS-Scope pull-down menu in \app{pMarineViewer}, or changed by
repeatedly hitting \var{ctrl-'/'}. A variable may be added to the
scope list by typing \var{&lt;shift&gt; 'A'} at any time, and entering the variable
name in the dialog box.

\vspace{0.1in}
\noindent
{\bf 2022 Note:} Recently, "Realmcasting" has been added to MOOS-IvP
with support n \app{pMarineViewer}. To enable realmcasting, just run
\app{pRealm} in your mission (no configuration block required), if it
is not present already. During your mission you can see the
realmcasting output by toggling between realmcasting and appcasting
with the \var{'a'} key.

%-------------------------------------------------------------------------
\subsubsection{Poking with pMarineViewer geo-referenced mouse clicks}

The \app{pMarineViewer} app supports a further useful method for
poking the \app{MOOSDB} with mouse clicks containing the location of
the click in the operation area in the value poked to the
\app{MOOSDB}. This is described in \app{pMarineViewer} documentation,
\urlx{http://oceanai.mit.edu/ivpman/apps/pMarineViewer}, in the
section "Custom Poking of the MOOSDB with the Operation Area
Position".  Try adding the below line, for example, in the
\app{pMarineViewer} configuration block of your \var{.moos} file.

\prevblue
\begin{verbatim}
 left_context[view_point]  = VIEW_POINT = x=$(XPOS),y=$(YPOS),label=hello
\end{verbatim}
\postverb

\noindent
This line adds the ability to left-click on the \app{pMarineViewer}
window with the result that a \mvar{VIEW\_POINT} message will be
posted to the \app{MOOSDB} with the location of the mouse-click
embedded in the message. It is possible to configure
\app{pMarineViewer} with a selectable list of left-mouse-click
contexts.  For example, add the below line to the first one above. You
should be able to then choose what action a left click performs by
using the Mouse-Context pull-down menu.

\prevblue
\begin{verbatim}
 left_context[view_poly]  = VIEW_POLYGON = format=radial,x=$(XPOS),y=$(YPOS),
                            radius=10, pts=8, edge_size=1,label=mypoly
\end{verbatim}
\postverb

\noindent
In the above line, don't actually use the backslash character at the
end of the line. It all needs to be on one line - a limitation of .moos
files, for now at least.

\vspace{0.1in}
\noindent
Try configuring your mission with a third context, e.g.,
\var{"view\_both"}, such that both types of events occur with the same
mouse click. You will need this trick in Assignment 2 below.

%==========================================================================
\newpage
\subsection{Assignment 1 (self check off) - The Alpha Return Mission}

This assignment involves the modification of the alpha example mission
to accept a return waypoint for the vehicle based on a user click in
the \app{pMarineViewer} window. Your goals are:

\begin{packed_itemize}[2]
\item Modify the \var{alpha.moos} and \var{alpha.bhv} (if necessary)
  files to accept a user left-mouse click in \app{pMarineViewer}
  determining the point to where the vehicle should return. Your
  modification should result in the posting of a point to the
  \app{pMarineViewer} window with the label "return\_point"
  immediately upon a user click. After the vehicle has completed its
  waypoint survey, it will proceed to the return point.
\end{packed_itemize}


\vspace{0.1in}
\noindent
Hint: You will need to utilize the \bvar{updates} parameter defined
for all behaviors. The return home waypoint behavior already has
an \bvar{updates} parameter configured to name the MOOS variable
\mvar{RETURN\_UPDATE}. Your mouse click needs to result in a posting
to this variable. The contents of this posting should be a string,
where the string is a drop-in replacement for any configuration line
in the behavior configuration block. More on the \bvar{updates}
parameter can be found here:

\vspace{0.1in}

\urlx{http://oceanai.mit.edu/ivpman/helm/updates}


\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_05_alpha_return.png}
  \caption{The modified alpha mission with user commanding the return point.}
  \label{fig_alpha_return}
  \urlvideo{https://vimeo.com/87301755}{0:23}
\end{figure}

%==========================================================================
\newpage
\subsection{Assignment 2 (check off) - The Alpha Return Now Mission}

Extending the first mission, configure your mission and
\app{pMarineViewer} to have a second left-mouse-click context
directing the vehicle to return as soon as the mouse is
clicked. Instead of the vehicle waiting until the waypoint-survey
behavior to complete, a left-mouse click results in the immediate
return to the specified point.

\vspace{0.1in}
\noindent
Hint: the only thing that needs to be done additionally in this
mission is to tie two MOOS postings to one mouse click.

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_05_alpha_return.png}
  \caption{The modified alpha mission with user commanding the return
    point. The selection of the return point also triggers the switch
    to return mode.}
  \label{fig_alpha_return_now}
  \urlvideo{https://vimeo.com/87301981}{0:15}
\end{figure}

   

%======================================================================
\newpage \section{Building Your First Autonomy Mission - The Bravo Mission}
%======================================================================

In the second part of today's lab, the goal is to create an autonomy
mission from scratch. Primarily we will be using the Loiter behavior,
but we will also have occasion to use the \bhv{Waypoint},
\bhv{ConstantDepth}, \bhv{ConstantSpeed}, and \bhv{Timer} 
behaviors. We will start by constructing a mission for a surface
vehicle, but will migrate shortly to configuring for an underwater
vehicle.

\vspace{0.1in}
\noindent
Much of the information you will need regarding the workings of various
behaviors and the helm are described in the helm documentation
(\urlx{http://oceanai.mit.edu/ivpman}).  Several of the target
missions we will be building have been simulated prior to the lab with
short videos available.

%=======================================================================
\subsection{Assignment 3 (self check off) - The Bravo Loiter Mission}

In this part we will:

\begin{packed_itemize}[2]
  \item Prepare a new mission from scratch
  \item Get familiar with the Loiter behavior
  \item Introduce the notion of behavior run-states.
  \item Understand the \var{"perpetual"} flag defined on all behaviors.
\end{packed_itemize}

\vspace{0.05in}
\noindent
Our first step is to create a new mission and behavior file, and call
them \var{bravo.moos} and \var{bravo.bhv}. This should be put into a
folder in \var{missions/lab\_05/} called \var{bravo\_loiter}.  It is
certainly fine to copy the alpha mission as a starting point. The
bravo mission should be configured with the following features:


\vspace{0.1in}
\begin{packed_itemize}
  \item It should have a Loiter behavior, which is primarily active
    upon an initial deploy. It should have a location
    \var{x=100,y=-75}, a radius of 30 meters, and the loiter polygon
    should have 8 vertices. It should be set with a loiter speed of
    2.5 m/sec. It should loiter counter-clockwise.
  
  \item It should have a waypoint behavior that simply returns the
    vehicle to the vehicle starting position \var{x=0,y=0}, when the
    variable \mvar{RETURN=true} as in the alpha mission.

  \item The Loiter behavior should utilize the \pvar{duration}
    parameter to automatically "complete" after 150 seconds,
    triggering the return waypoint behavior.
\end{packed_itemize}


\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_05_bravo_loiter.png}
  \caption{A simple loiter mission (the Bravo Loiter Mission) - the
    vehicle loiters at the prescribed location for the prescribed
    amount of time, and returns home automatically.}
  \label{fig_bravo_loiter}
  \urlvideo{https://vimeo.com/87311982}{0:14}
\end{figure}


\vspace{0.1in}
\noindent
The Loiter behavior is in the helm documentation
(\urlx{http://oceanai.mit.edu/ivpman/bhvs/Loiter}). The primary
parameters of interest here are the \bvar{polygon}, \bvar{clockwise},
and \bvar{speed} parameters. Use the \bvar{format=radial} format for
describing the loiter polygon as described in the above referenced
Loiter documentation in the section \var{"Setting and Altering the
  Loiter Region"}.

\vspace{0.1in}
\noindent
The waypoint return behavior is configured similarly to the alpha mission, 
but more information on this behavior may be found at
\urlx{http://oceanai.mit.edu/ivpman/bhvs/Waypoint}.


\vspace{0.1in}
\noindent
The duration behavior parameter is defined for all behaviors. Most
behaviors regard the duration to be limitless if left unspecified. A
more detailed discussion of this parameter may be found in the helm
documentation: \urlx{http://oceanai.mit.edu/ivpman/helm/param\_duration}.

\vspace{0.1in}
\noindent
We will be exploring the concepts of behavior run-states and run-flags
in this and the following missions. A good discussion of this may be
found here: \urlx{http://oceanai.mit.edu/ivpman/helm/run\_states}.


%=====================================================================
\subsection{Assignment 4 (self check off) - The Bravo Double Loiter Mission}

In this part we will:
\begin{packed_itemize}
  \item Explore a non-sequential mission - a mission that alternates
    between modes.
  \item Become familiar with the \bvar{duration}, \bvar{endflag}, and
    \bvar{perpetual} behavior parameters.
  \item Learn about the special but versatile Timer behavior in
    \app{pHelmIvP}.
\end{packed_itemize}
   
\vspace{0.15in}
\noindent
Our next step is to add a second loiter behavior to the bravo
mission. The idea is to construct a mission where the vehicle is able
to periodically switch between loitering at the two locations. We will
experiment with ways to enable this switching, both automatically and
via user interaction. The second bravo mission should be configured
with the following features:

\vspace{0.1in}
\begin{packed_itemize}
  \item Make a copy of the previous bravo mission, making a new
    directory in the \var{missions/lab\_05/} folder called
    \var{bravo\_loiter\_dbl}.

  \item The new bravo mission should have a second loiter behavior,
    which is not active upon an initial deploy. It should have a
    location \bvar{x=160,y=-50}, a radius of 20 meters, and the loiter
    polygon should have 8 vertices. It should be set with a loiter
    speed of 2.5 m/sec.
  
  \item Make the two loiter behaviors mutually exclusive using their
    \bvar{condition} parameters, e.g.,
    \bvar{condition=LOITER\_REGION=west}.
     
  \item Utilize the \bvar{duration}, \bvar{endflag}, and
    \bvar{perpetual} parameters to accomplish the periodic switching
    between loiter regions. Set the \bvar{duration} to be 150 seconds
    for each, use a couple of \bvar{endflag} parameters in each
    behavior to both (a) trigger the conditions of the other loiter
    behavior, and (b) negate the condition of the behavior ending. Set
    the \bvar{perpetual} parameter to be true so that a completed
    behavior does not complete permanently, but simply awaits its
    conditions to once again be satisfied.

  \item {\bf Note:} You may need to understand how the \bvar{duration}
    timer works. Recall the \bvar{duration} feature is defined for all
    behaviors. By default the timer re-starts immediately once it has
    count down completely and \bvar{perpetual} is set to true. This
    may not be what you want. You may want your behavior to wait until
    it is again running (logic conditions satisfied) before resuming
    the duration timer count-down. In this case you would need to set
    \bvar{duration\_idle\_decay} to be false. The default is true.

\end{packed_itemize}

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_05_bravo_loiter_dbl.png}
  \caption{A simple loiter mission (the Bravo Double Loiter mission) -
    the vehicle loiters at one of two prescribed locations for a
    prescribed amount of time before automatically switching to the
    other location. The vehicle doesn't return until the user
    explicitly calls for its return by hitting the \pvar{RETURN}
    button.}
  \label{fig_bravo_loiter_dbl}
  \urlvideo{https://vimeo.com/87349082}{0:42}
\end{figure}
\vspace{0.1in}

\noindent
As bonus, can you make a variation of this mission where the second (east)
loiter location is chosen by the user at run time with a mouse click?

%===================================================================
\subsection{Assignment 5 (check off) - The Bravo UUV Mission}

{\bf Note:} The \app{pMarinePID} and \app{pMarinePIDV22} apps may be
used interchangebly in this lab. Same with \app{uSimMarine} and
\app{uSimMarineV22}. The V22 version is newer and the other version will
soon be deprecated. They should have the same config parameters however.

\vspace{0.1in}
\noindent
Our next step is to change the Bravo mission to simulate a UUV instead
of a surface vehicle. We'll need to modify a few configurations for
\app{uSimMarineV22}, \app{pMarinePIDV22}, and in \app{pHelmIvP}. And of
course, we will also add some behavior components to our mission so
the UUV may actually dive.

\vspace{0.1in}
\noindent
In this part we will:

\begin{packed_itemize}
  \item Understand how to augment \app{pMarinePIDV22} when using UUVs
  \item Understand how to augment \app{uSimMarineV22} when using UUVs
  \item Understand how to augment \app{pHelmIvP} when using UUVs
  \item Learn to use the \bhv{ConstantDepth} behavior
  \item Learn to tie behaviors together to operate in coordination.
  \item Learn how to use \app{pMarineViewer} when dealing with
    underwater vehicles.
\end{packed_itemize}

\vspace{0.15in}
\noindent
The first step is to make modifications to a handful of MOOS apps use
thus far in our examples, to support depth. These modifications are
listed on the last page of this lab handout, and also on the course
website under lab updates. The latter may be better for the purposes
of cutting and pasting into your files.  The third bravo mission
should be configured with the following features:

\vspace{0.1in}
\begin{packed_itemize}
  \item Make a copy of the previous bravo mission, making a new directory
    in the \var{missions/lab\_05/} folder called \var{bravo\_loiter\_uuv}.

  \item Make the changes to \app{pMarinePIDV22}, \app{uSimMarineV22},
    \app{pHelmIvP} and \app{pNodeReporter} as described in Section 
    \ref{sec_depth_config}.
  
  \item Add a pair of \bhv{ConstantDepth} behaviors to the behavior file, and 
    configure them such that the vehicle operates at 30 meters depth when 
    loitering in the west, and 10 meters depth when loitering in the east.
\end{packed_itemize}

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_05_bravo_loiter_uuv.png}
  \caption{The modified bravo double-loiter mission now with a UUV operating
    at a depth of 30 meters.}
  \label{fig_bravo_loiter_uuv}
  \urlvideo{https://vimeo.com/87399032}{0:25}
\end{figure}

\vspace{0.1in}
\noindent
Tips:

\vspace{0.1in}
\noindent
You may change the label rendered next to the vehicle in
\app{pMarineViewer} by repeatedly hitting the \var{'n'} key. It's
helpful to have the depth of the vehicle rendered while operating. You can
configure \app{pMarineViewer} to come up in this mode by setting:

\prevblue
\begin{verbatim}
 vehicles_name_mode = names+depth
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
More information on the \bhv{ConstantDepth} behavior may be found in the
helm documentation:

\vspace{0.1in}
\noindent
\urlx{https://oceanai.mit.edu/ivpman/bhvs/ConstantDepth}.

\vspace{0.1in}
\noindent
You can leave the \bvar{peakwidth}, \bvar{basewidth}, and
\bvar{summitdelta} parameters unspecified for now, using their default
values. {\bf Note:} The ConstantDepth behavior {\em must} have its
\bvar{duration} parameter set to a non-zero value, or set to
\bvar{duration=no-time-limit}.  You may want to read more on these
parameters after the lab.

\vspace{0.1in}
\noindent
To tie the depth behaviors to the loiter behaviors, simply make their run
conditions identical.

%=========================================================================
\subsection{Assignment 6 (check off) - The Bravo UUV Surface Mission}

This assignment involves a final modification to the Bravo example mission. 
In this mission, the bravo vehicle will periodically come to the surface, 
wait some number of seconds at the surface at zero speed, and then dive
and resume its mission. Presumably this to simulate roughly what happens
in a UUV that needs to occasionally come to the surface for a GPS fix to
re-set its navigation solution. Your goals are:

\begin{packed_itemize}[2]
  \item Make a copy of the previous bravo mission, creating a new directory
    \var{bravo\_uuv\_surface}.

  \item Make use of the helm Timer behavior to augment your mission to
    have the vehicle periodically come to the surface (every 200
    seconds). While at the surface it should be stopped, as a placeholder
    ostensibly to wait for a GPS fix. Make use of another Timer behavior
    that begins when the
    vehicle is at the surface, to wait 60 seconds before allowing the
    vehicle to dive again.
\end{packed_itemize}  

\vspace{0.1in}
\noindent
It should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_05_bravo_uuv_surface.png}
  \caption{A UUV loiters between two regions and periodically comes to the 
    surface and waits for a GPS fix before proceeding.}
  \label{fig_bravo_uuv_surface}
  \urlvideo{https://vimeo.com/87422920}{0:45}
\end{figure}

\vspace{0.1in}
\noindent
{\bf NOTE:} There is an existing helm behavior called \var{BHV\_PeriodicSurface}
that can accomplish some of the functionality of this lab. Your goal is to
complete the lab without using this behavior, but instead use a compbination of
other simpler behaviors.

%=========================================================================
\subsection{Assignment 7 (checkoff) Bravo UUV Fair Time Mission}

You may noticed with your Assignment 6 mission that when the vehicle
surfaces and waits for the prescribed time at the surface, when it
finally does resume it usually heads off directly to the opposite
loiter region. Take a look again at the video from Figure
\ref{fig_bravo_uuv_surface}. Why is this?  The loiter behavior that
    {\em was} active when the surfacing sequence began immediately
    became idle, and the duration clock for that loiter behavior never
    stopped during the surfacing sequence. 

\vspace{0.1in}
\noindent
We would like the vehicle instead to resume its
interrupted loiter for the time duration that remained when the loiter
was interrupted. To do this, see the parameter defined on all
behaviors called \bvar{duration\_idle\_decay}. See
\urlx{http://oceanai.mit.edu/ivpman/helm/param\_duration}

\vspace{0.1in}
\noindent
The new mission should look something like the video posted at:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{educlips/lab_05_bravo_uuv_surface_nodecay.png}
  \caption{A UUV loiters between two regions and periodically comes to
    the surface and waits for a GPS fix before proceeding. The time
    spent during the surfacing sequences does not count in time spent
    spent at each loiter region. }
  \label{fig_bravo_uuv_surface_nodecay}
  \urlvideo{https://vimeo.com/87425349}{1:10}
\end{figure}

%=========================================================================
\subsection{Assignment 8 (checkoff) Bravo UUV Odometry Misssion}

In the final step, dust off your \app{pOdometry} app and modify it to accept
a configuration parameter \pvar{depth\_thresh}. This parameter will accept
a depth, in meters. When enabled (the default value is zero), the odometry
distance will only accumulated when the vehicle depth \mvar{NAV\_DEPTH} is
greater then \pvar{depth\_thresh}.

\vspace{0.1in}
\noindent
You should modify the appcasting output of your Odometry behavior to display
both the total odometry distance, and the distance meeting the depth threshold.
The latter should be published to the MOOSDB as \mvar{ODOMETRY\_DIST\_AT\_DEPTH}. 
In your mission, you can have a return behavior (a Waypoint behavior) configured
to return home, with a condition based on the above MOOS variable.

\vspace{0.1in}
\noindent
Modify the double-loiter mission to have the vehicle return home after a set
amount of distance, 200 meters, at a depth greater than 25 meters. As a BONUS,
make the distance and depth configuration parameters of your \var{launch.sh}
script. See how far you can get on this step on your own, but we will post some
info/tips on this topic during the week.

%==================================================================
\newpage 
\section{Simulator Configurations for Operating at Depth}
\label{sec_depth_config}
%==================================================================

The below four modifications are needed for configuring your simulation
to simulate a UUV, i.e., simulating depth in a vehicle. 

%------------------------------------------------------------------
\subsection*{Modifying the pMarinePIDV22 configuration} 

To have a simulated {\em underwater} vehicle, add the below lines to
your \app{pMarinePIDV22} configuration block in your mission
file(s). Note that in the case of \pvar{depth\_control=true}, you are
probably {\em replacing} an existing line.

\prevblue[0in]
\begin{verbatim}
  depth_control = true

  //Pitch PID controller
  pitch_pid_kp                   = 1.5
  pitch_pid_kd                   = 0.3
  pitch_pid_ki                   = 0.004
  pitch_pid_integral_limit       = 0

  //ZPID controller
  z_to_pitch_pid_kp              = 0.12
  z_to_pitch_pid_kd              = 0.1
  z_to_pitch_pid_ki              = 0.004
  z_to_pitch_pid_integral_limit  = 0.05

  maxpitch     = 15
  maxelevator  = 13
\end{verbatim}
\postverb[0in]

%------------------------------------------------------------------
\subsubsection*{Modifying the uSimMarineV22 configuration} 

To have a simulated {\em underwater} vehicle, add the below lines to 
your \app{uSimMarineV22} configuration block in your mission file(s).

\prevblue[0in]
\begin{verbatim}
  buoyancy_rate        = 0.15
  max_depth_rate       = 5
  max_depth_rate_speed = 2.0
  default_water_depth  = 400
\end{verbatim}
\postverb[0in]


%------------------------------------------------------------------
\subsubsection*{Modifying the pHelmIvP configuration} 

The below augments the helm decision space to include 101 possible
depth decisions. In deeper water, a different configuration may be
used. This line needs to be added to the \app{pHelmIvP} configuration
block in your mission file(s).

\prevblue
\begin{verbatim}
  domain = depth:0:100:101
\end{verbatim}
\postverb[0in]


%------------------------------------------------------------------
\subsubsection*{Modifying the pNodeReporter configuration} 

The modification below to pNodeReporter is mostly cosmetic. It changes
the vehicle type to "UUV" so you see a UUV icon in your simulator
diving, rather than a kayak.  This line can be found in the
\app{pNodeReporter} configuration block in your mission file(s).

\prevblue
\begin{verbatim}
  platform_type = UUV
\end{verbatim}
\postverb[0in]

%==================================================================
\newpage 
\section{Instructions for Handing In Assignments}
\label{sec_hand_in}

Missions should be added to your GitHub trees. In this lab, only the
mission files are added - no source code.

%------------------------------------------------------------------
\subsection{Requested File Structure}
Here is the requested file structure:

\vspace{0.1in}
\begin{consoleverb}
  moos-ivp-extend/
    missions/
      lab_05/
        alpha_return/               // Assignment 1 - self check off
        alpha_return_now/           // Assignment 2 - check off
        bravo_loiter/               // Assignment 3 - self check off
        bravo_loiter_dbl/           // Assignment 4 - self check off
        bravo_loiter_uuv/           // Assignment 5 - check off
        bravo_uuv_surface/          // Assignment 6 - check off
        bravo_uuv_fair/             // Assignment 7 - check off
        bravo_uuv_odometry/         // Assignment 8 - check off
\end{consoleverb}
\vspace{0.1in}

%------------------------------------------------------------------
\subsection{Due Date}

This lab should have its check-off components checked off, and labs
under version control by the end of lab on Thursday Feb 27th,
2025. Lab hours on Thu Feb 27th, will be dedicated to working on Lab
06. 

\end{document}

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