\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}
%===================================================================
\begin{document}
\wikidoc{file=MCP.Lab04IntroBehaviors}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 4 - Working With Helm Behaviors}
\vspace{0.1in}
%\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.1in}
\labpng{0.75}{figs_common/header.png}
\labdate{Nov 17-21 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{footnotesize}
\end{labcover}

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

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

This lab will provide further experience with the IvP Helm to new
users. It assumes some experience with the Helm, editing mission and
behavior files, from the previous lab. It also assumes access to the
corresponding lecture and lab overview lecture.


\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item The Loiter Behavior
\item Simulating UUVs (adding depth to the simulations)
\item The Timer Behavior
\item The Behavior updates parameter
\item Constant Depth behavior 
\item MaxDepth behavior 
\item Simulated Drift
\end{packed_itemize}
\end{labinfo}


\subsection{Preliminaries}
\label{prelims}

In this lab, several new missions will be created. As in the previous
lab, each mission will begin by copying a previous similar mission and
modifying from that starting point. Each mission folder will contain
an \var{alpha.moos} and \var{alpha.bhv} file. In this lab we will
create the following missions:

\begin{packed_itemize}
\item \var{s8\_alpha}: By copying \var{s1\_alpha}, then modifying
\item \var{s9\_alpha}: By copying \var{s8\_alpha}, then modifying
\item \var{s10\_alpha}: By copying \var{s9\_alpha}, then modifying
\item \var{s11\_alpha}: By copying \var{s10\_alpha}, then modifying
\item \var{s12\_alpha}: By copying \var{s11\_alpha}, then modifying
\item \var{s13\_alpha}: By copying \var{s9\_alpha}, then modifying
\item \var{s14\_alpha}: By copying \var{s13\_alpha}, then modifying
\end{packed_itemize}


%======================================================================
\newpage
\section{Exercises}
%======================================================================

%======================================================================
\subsection{Exercise 1 - Changing the Alpha Mission to Use the Loiter Behavior}
\label{sec_s8}

In this exercise the goal is make a version of the Alpha mission and
swap out the Waypoint Behavior and use the Loiter Behavior instead. It should
look something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.75\textwidth]{figures/s8_alpha.png}
  \caption{{\bf s8\_alpha:} Using the Loiter Behavior} 
\label{fig_s8}
\gif{figures/s8_alpha.gif}
\end{figure}


\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{itemize}
\item Copy the \var{s1\_alpha} mission, naming it \var{s8\_alpha}
\item Remove the Waypoint survey behavior (keep the return waypoint behavior)
\item Add a Loiter Behavior 
\end{itemize}

\vspace{0.1in}
\noindent
The Loiter behavior documentation is here:

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

\vspace{0.1in}
\noindent
The behavior block should look like that below. You can copy it into
your behavior file, but try to understand the configuration parameters by
reading the Loiter documentation above.

\begin{fileverb}
//----------------------------------------------
Behavior = BHV_Loiter
{  
   name         = loiter  
   priority     = 100  
   condition    = RETURN = false  
   condition    = DEPLOY = true  
   updates      = UP_LOITER         
   speed        = 1.3     
   clockwise    = false        
   radius       = 6.0     
   slip_radius  = 25.0       
   polygon      = format=radial, x=75, y=-75, radius=30, pts=8, snap=1
   visual_hints = nextpt_color=yellow, nextpt_lcolor=khaki  
   visual_hints = edge_color=white, vertex_color=dodger_blue  
   visual_hints = edge_size=1, vertex_size=3, label=LOITER_POLYGON
   visual_hints = nextpt_vertex_size=5
} 
\end{fileverb}



%======================================================================
\newpage
\subsection{Exercise 2 - Adding Depth to our Missions, Constant Depth Behavior}
\label{sec_s9}

In this exercise the goal is to modify the previous \var{s8\_alpha}
mission to have a vehicle that operates underwater, reasoning about
depth in addition to heading and speed. It should look something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.75\textwidth]{figures/s9_alpha.png}
  \caption{{\bf s9\_alpha:} A simulated UUV showing its current depth.} 
\label{fig_s9}
\gif{figures/s9_alpha.gif}
\end{figure}


\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s8\_alpha} mission, naming it \var{s9\_alpha}
\item Configure the Helm to reason about depth
\item Configure the simulator to reason about depth
\item Configure the PID controller to reason about depth
\item Add the ConstantDepth Behavior to the behavior file
\end{packed_itemize}

%-------------------------------------------------------------
\subsubsection{Configure the Helm to Reason about Depth}

The Helm documentation is at the link below. In particular, Section
1.4.6 discusses the helm decision space.

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

\vspace{0.1in}
\noindent
The helm configuration block should look like that below. You can copy it into
your mission file, but try to understand the configuration parameters by
reading the documentation.

\begin{fileverb}
ProcessConfig = pHelmIvP
{
  AppTick    = 4
  CommsTick  = 4

  bhv_dir_not_found_ok = true

  behaviors  = alpha.bhv
  domain     = course:0:359:360
  domain     = speed:0:4:41
  domain     = depth:0:100:101     <-- Add this line
}
\end{fileverb}

%-------------------------------------------------------------
\subsubsection{Configure the Simulator to Reason about Depth}

The Simulator documentation is at the link below.

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

\vspace{0.1in}
\noindent
The \app{uSimMarineV22} configuration block should look like that
below. You can copy it into your mission file, but try to understand
the configuration parameters by reading the documentation. The last
four lines are needed with simulating depth.

\begin{fileverb}
ProcessConfig = uSimMarineV22
{
  AppTick   = 4
  CommsTick = 4

  start_x       = 0
  start_y       = -20
  start_heading = 180
  start_speed   = 0

  prefix        = NAV

  turn_rate     = 95
  thrust_map    = 0:0, 20:1, 40:2, 60:3, 80:4, 100:5
  thrust_reflect = true

  buoyancy_rate        = 0.025
  max_depth_rate       = 7
  max_depth_rate_speed = 1.0
  default_water_depth  = 400
}

\end{fileverb}


%-------------------------------------------------------------
\subsubsection{Configure the PID Controller to Reason about Depth}

You will need to add the below lines to the 
\app{pMarinePID} configuration block in your mission file to reason
about depth.

\begin{fileverb}
  // Depth control configuration                                
  depth_control      = true   // or {false}                  
  z_to_pitch_pid_kp  = 0.12                                     
  z_to_pitch_pid_kd  = 1.0                                      
  z_to_pitch_pid_ki  = 0.004                                    
  z_to_pitch_pid_integral_limit = 0.05                          
  maxpitch           = 15                                       
                                                                
  // Depth control configuration                                
  pitch_pid_kp       = 2.5                                      
  pitch_pid_kd       = 1.0                                      
  pitch_pid_ki       = 0                                        
  pitch_pid_integral_limit = 0                                  
  maxelevator        = 13          
}
\end{fileverb}

%-------------------------------------------------------------
\subsubsection{Add the ConstantDepth Behavior to the behavior file}

\vspace{0.1in}
\noindent
The ConstantDepth behavior documentation is at the below URL.

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

\vspace{0.1in}
\noindent
You will need to add a configuration block like that below. You can
copy it into your behavior file, but try to understand the
configuration parameters by reading the documentation.

\begin{fileverb}
//----------------------------------------------            
Behavior=BHV_ConstantDepth
{
  name       = const_depth
  pwt        = 100
  condition  = DEPLOY = true
  duration   = no-time-limit

       depth = 20
}
\end{fileverb}





%======================================================================
\newpage
\subsection{Exercise 3 - Allow the User to Dynamically Change Depth}
\label{sec_s10}

In this exercise the goal is to modify the previous \var{s9\_alpha}
mission to accept user specified changes to the commanded UUV depth,
during the mission. The user should be able to toggle between
commanded depths of 20 and 40 meters.  Two buttons will be added to
\app{pMarineViewer} to initiate the depth changes.  It should look
something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.75\textwidth]{figures/s10_alpha.png}
  \caption{{\bf s10\_alpha:} A simulated UUV with two new operator
    buttons for changing the depth between 20 and 40 meters.} 
\label{fig_s10}
\gif{figures/s10_alpha.gif}
\end{figure}


\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s9\_alpha} mission, naming it \var{s10\_alpha}
\item Add the updates parameter to the ConstantDepth behavior
\item Add the appropriate buttons to the pMarineViewer configuration
\end{packed_itemize}


%-------------------------------------------------------------
\subsubsection{Add the updates Parameter to the ConstantDepth Behavior}

The \var{updates} parameter is defined for all IvP Behaviors. It
specifies a MOOS variable from which updates to prior behavior
configurations can be applied. Read more here:

\vspace{0.1in}
\noindent
\urlx{http://oceanai.mit.edu/ivpman/pmwiki/pmwiki.php?n=Helm.HelmBehaviors\#sec_updates}

\vspace{0.1in}
\noindent
You will need to add one line to the existing configuration block below:

\begin{fileverb}
//----------------------------------------------            
Behavior=BHV_ConstantDepth
{
  name       = const_depth
  pwt        = 100
  condition  = DEPLOY = true
  duration   = no-time-limit
  updates    = DEPTH_UPDATE
 
       depth = 20
}
\end{fileverb}


%-------------------------------------------------------------
\subsubsection{Add Buttons to pMarineViewer}

The next step is to add a pair of buttons to the \app{pMarineViewer}
configuration block that allow us to command different depths:

\vspace{0.1in}
\noindent
The \app{pMarineViewer} documentation is here (see Sec 47.1.5):

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

\vspace{0.1in}
\noindent
You will need to add the below line to the existing configuration block below:

\vspace{0.1in}
\begin{fileverb}
  button_three = DEPTH_20 # DEPTH_UPDATE=depth=20
  button_four  = DEPTH_40 # DEPTH_UPDATE=depth=40
\end{fileverb}




%======================================================================
\newpage
\subsection{Exercise 4 - Use a Script to Randomly Change Depth}
\label{sec_s11}

In this exercise the goal is to copy the previous \var{s10\_alpha}, to
a new mission \var{s11\_alpha}, to use a timer script to randomly
change the vehicle depth between 20 and 80 meters.

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s10\_alpha} mission, naming it \var{s11\_alpha}
\item Add the \app{uTimerScript} to the Antler block in the mission file
\item Configure the \app{uTimerScript}
\end{packed_itemize}

\vspace{0.1in}
\noindent
To enable \app{uTimerScript} to be launched, it needs to be added to
the Antler configuration block in \var{alpha.moos}. Just add the last
line as in the example below.

\begin{fileverb}
//------------------------------------------
// Antler configuration  block
ProcessConfig = ANTLER
{  
  MSBetweenLaunches = 200  
  
  Run = MOOSDB          @ NewConsole = false  
  Run = pLogger         @ NewConsole = false  
  Run = uSimMarineV22   @ NewConsole = false  
  Run = pMarinePIDV22   @ NewConsole = false  
  Run = pHelmIvP        @ NewConsole = false  
  Run = pMarineViewer   @ NewConsole = false  
  Run = uProcessWatch   @ NewConsole = false  
  Run = pNodeReporter   @ NewConsole = false  
  Run = uTimerScript    @ NewConsole = false   <-- Add this line (but not the comment)
}
\end{fileverb}

\vspace{0.1in}
\noindent
The documentation for \app{uTimerScript} can be found at the below link:

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

\vspace{0.1in}
\noindent
Or on the command line with:

\vspace{0.1in}
\begin{consoleverb}
$ uTimerScript --web
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
The configuration block should look like that below. You can copy it
into your mission file, but try to understand the configuration
parameters by reading the documentation.

\vspace{0.1in}
\begin{consoleverb}
//------------------------------------------
// uTimerScript configuration block
ProcessConfig = uTimerScript                                    
{  
  AppTick   = 4    
  CommsTick = 4   
 
  condition   = DEPLOY = true  
  randvar     = varname=RND_DEPTH, min=20, max=80, key=at_reset
  event       = var=DEPTH_UPDATE, val=depth=$[RND_DEPTH], time=120
  reset_max   = nolimit  
  reset_time  = all-posted
}
\end{consoleverb}

\vspace{0.1in}
\noindent
The end result when properly working should look like below. Note the
events being posted with random depth values in \app{uTimerScript}, and
the subsequent depth changes in the simulation.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.94\textwidth]{figures/s11_alpha.png}
  \caption{The \var{s11\_alpha} mission in final working state.}
  \label{fig_s11_alpha}
  \gif{figures/s11_alpha.gif}
\end{figure}



%======================================================================
\newpage
\subsection{Exercise 5 - Use the MaxDepth Behavior to Limit Depth}
\label{sec_s12}

In this exercise the goal is to extend the previous mission to include
a MaxDepth behavior. This behavior will be used to make sure that
the maximum command depth will be 50 meters, even though random depths
between 20 and 80 meters will continue to be generated by the script.

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s11\_alpha} mission, naming it \var{s12\_alpha}
\item Add a \var{MaxDepth} behavior to the behavior file, limiting the
  maximum commanded depth to be 50 meters
\item Ensure the priority weight for this behavior is higher than the
  ConstantDepth behavior.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The documentation for \app{MaxDepth} behavior can be found at the below link:

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

\vspace{0.1in}
\noindent
The configuration block should look like that below. You can copy it
into your behavior file, but try to understand the configuration
parameters by reading the documentation.

\vspace{0.1in}
\begin{fileverb}
//----------------------------------------------
Behavior=BHV_MaxDepth
{  
   name       = max_depth  
   pwt        = 200  
   condition  = DEPLOY = true  
   duration   = no-time-limit  	   
   max_depth  = 50   
   basewidth  = 0
}
\end{fileverb}

\vspace{0.1in}
\noindent
The end result when properly working should look like below. Note the
vehicle depth remains about 50 meters or less even when the timer script
has chosen a deeper value.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.92\textwidth]{figures/s12_alpha.png}
  \caption{The \var{s12\_alpha} mission in final working state.}
  \label{fig_s12_alpha}
  \gif{figures/s12_alpha.gif}
\end{figure}


%======================================================================
\newpage
\subsection{Exercise 6 - Simulate Surfacing for GPS}
\label{sec_s13}

In this exercise the goal is to extend the \var{s9\_alpha} mission to
have a loitering UUV periodically stop and float to the surface, and
weight at the surface for a period of time (presumably to get a GPS
fix). Two new behavior instances will be added. Both are Timer
behaviors. These behavior do not produce any objective function, no
influence over heading, speed or depth decisions. They simply use the
built-in timer (duration) feature available to all behaviors, to
periodically post end flags.

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s9\_alpha} mission, naming it \var{s13\_alpha}
\item Add a \var{Timer} behavior to the behavior file. This behavior
  will be on when (a) the vehicle is deployed (\var{DEPLOY=true}), and
  when a GPS fix is not needed (\var{NEED\_GPS=false}). It will have
  duration of 200 seconds, and when it completes, it will declare that
  a GPS fix is needed (\var{NEED\_GPS=true}).
\item Add a second \var{Timer} behavior to the behavior file. This
  behavior will be on when (a) the vehicle is deployed
  (\var{DEPLOY=true}), and when a GPS fix is needed
  (\var{NEED\_GPS=true}), and when the vehicle is still not yet at the
  surface (\var{NAV\_DEPTH < 2}). It will have duration of 30 seconds,
  and when it completes, it will declare that a GPS fix is not needed
  (\var{NEED\_GPS=false}).
\item The behavior file will need to declare that initially a GPS fix is
  not needed (\var{initialize NEED\_GPS = false}).
\end{packed_itemize}

\vspace{0.1in}
\noindent
The documentation for \app{Timer} behavior can be found at the below link:

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

\vspace{0.1in}
\noindent
The configuration block should look like that below. You can copy it
into your behavior file, but try to understand the configuration
parameters by reading the documentation.

\vspace{0.1in}
\begin{fileverb}
//----------------------------------------------
Behavior=BHV_Timer
{
  name       = timer_need_gps
  pwt        = 100
  condition  = DEPLOY   = true
  condition  = NEED_GPS = false
  perpetual  = true
  endflag    = NEED_GPS = true

             duration = 200
  duration_idle_decay = false
}
\end{fileverb}

\vspace{0.1in}
\noindent
As mentioned above, you will need a second timer behavior, to act as the
timer when the vehicle is on the surface. It should run for 30 seconds,
to simulate a vehicle acquiring a GPS fix. When it completes after 30 seconds
the vehicle should once again dive. We leave it up to you to add this
configuration block.

\vspace{0.1in}
\noindent
The end result when properly working should look like below. Note the
vehicle depth slowly returns to zero when the vehicle is stopped, relying
on buoyancy to float to the surface.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.92\textwidth]{figures/s13_alpha.png}
  \caption{The \var{s13\_alpha} mission in final working state.}
  \label{fig_s13_alpha}
  \gif{figures/s13_alpha.gif}
\end{figure}


%======================================================================
\newpage
\subsection{Exercise 7 - Add Simulated Drift to the Mission}
\label{sec_s14}

In this exercise the goal is to extend the \var{s13\_alpha} mission to
have include simulated drift in the simulation

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s13\_alpha} mission, naming it \var{s14\_alpha}
\item Add two buttons to the \app{pMarineViewer} configuration to turn
  drift on and off. Add a drift at of 0.3 m/sec at heading 45 degrees.
\item Note the performance of the Loiter behavior under drift.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The documentation for the \app{uSimMarineV22} MOOS App can be found at
the below link. The relevant part for this exercise is the drift vector
feature. (This is just FYI - no need to modify the simulator in this
exercise)

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

\vspace{0.1in}
\noindent
The line in the \app{pMarineViewer} configuration block should look
like that below. You can copy it into your behavior file, but try to
understand the configuration parameters by reading the documentation.
The last two lines are the key additions for this exercise.

\vspace{0.1in}
\begin{fileverb}
 button_one = DEPLOY # DEPLOY=true  
 button_one = MOOS_MANUAL_OVERRIDE=false # RETURN=false
 button_two = RETURN # RETURN=true  

 button_three = DRIFT_ON  # DRIFT_VECTOR = 45,0.3 
 button_four  = DRIFT_OFF # DRIFT_VECTOR = 0,0
\end{fileverb}

\vspace{0.1in}
\noindent
The end result when properly working should look like below. The drift
vector was set shortly into the mission, and note the vehicle drifting
Northeast when it has stopped and is floating to the surface. 

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.92\textwidth]{figures/s14_alpha.png}
  \caption{The \var{s14\_alpha} mission in final working state.}
  \label{fig_s14_alpha}
  \gif{figures/s14_alpha.gif}
\end{figure}


%======================================================================
\newpage
\section{Where to Find the Solutions}
%======================================================================

All solutions can be dowloaded from the class server (after the end of
the class):

\vspace{0.1in}
\noindent
Exercise 1:
\begin{packed_itemize}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s8\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s8\_alpha/alpha.bhv}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Exercise 2:
\begin{packed_itemize}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s9\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s9\_alpha/alpha.bhv}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Exercise 3:
\begin{packed_itemize}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s10\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s10\_alpha/alpha.bhv}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Exercise 4:
\begin{packed_itemize}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s11\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s11\_alpha/alpha.bhv}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Exercise 5:
\begin{packed_itemize}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s12\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s12\_alpha/alpha.bhv}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Exercise 6:
\begin{packed_itemize}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s13\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s13\_alpha/alpha.bhv}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Exercise 7:
\begin{packed_itemize}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s14\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s14\_alpha/alpha.bhv}
\end{packed_itemize}



\end{document}
