\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=MCA.Lab03IntroHelm}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 3 - Introduction to the Helm}
\vspace{0.1in}
%\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.1in}
\labpng{0.7}{figs_common/header.png}
\labdate{Nov 17-21 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Dept of Mechanical Engineering, 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 introduce the IvP Helm to new users. It assumes nothing
regarding prior experience with the Helm, other than the material
included in the accompanying lecture "Introduction to the IvP Helm".
The goals of this lab are to (a) understand the role of mission files
(.moos) and behavior files (.bhv) in constructing new missions, (b)
get comfortable with different ways to generate mission changing
events, with endflags, \app{pMarineViewer} and the \app{uTimerScript},
(c) explore the \app{iSay} MOOS App, (d) explore the StationKeeping
behavior.

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Mission and Behavior Files
\item Adding new behaviors to a mission
\item Behavior endflags
\item Waypoint behavior wptflags
\item SationKeep behavior 
\item The iSay MOOS App
\item The uTimerScript MOOS App
\end{packed_itemize}
\end{labinfo}


\subsection*{Preliminaries}
\label{prelims}


All exercises begin by copying an existing mission folder (containing
an \var{alpha.moos} and \var{alpha.bhv} file. Each folder contains
a new mission variation. In this lab we will create the following
missions:

\begin{packed_itemize}
\item \var{s2\_alpha}: By copying \var{s1\_alpha}, then modifying
\item \var{s3\_alpha}: By copying \var{s2\_alpha}, then modifying
\item \var{s4\_alpha}: By copying \var{s3\_alpha}, then modifying
\item \var{s5\_alpha}: By copying \var{s2\_alpha}, then modifying
\item \var{s6\_alpha}: By copying \var{s1\_alpha}, then modifying
\item \var{s7\_alpha}: By copying \var{s6\_alpha}, then modifying
\end{packed_itemize}

\vspace{0.1in}
\noindent
To prepare, create your own missions folder, \var{missions\_lab}, and
put all your work in this folder. The folder and the first mission
variation can be created as below:

\vspace{0.1in}
\begin{consoleverb}
$ cd
$ mkdir missions_lab
$ cp -rp moos-ivp/ivp/missions/s1_alpha  missions_lab/s2_alpha
\end{consoleverb}

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

%======================================================================
\subsection{Exercise 1 - Add a New Behavior to the Alpha Mission}
\label{sec_s2}

In this exercise the goal is make a version of the Alpha mission
that uses another waypoint behavior to perform a second survey
before returning. It should look something like:

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


\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s1\_alpha} mission, naming it \var{s2\_alpha}
\item Add second Waypoint survey behavior
\item Make the end flags for the first behavior trigger the second
  survey behavior.
\item Make the end flags for the second behavior trigger the return
  behavior
\end{packed_itemize}


\vspace{0.1in}
\noindent
For the second survey behavior, give it the name \var{"west\_wpt\_survey"}.
And give it the survey points below. Give a run condition requiring the
survey region mode (given by the \var{REGION} MOOS variable) is \var{"west"}.
Finally give it an end flag that triggers the return home behavior. The
relevant parameters are:

\begin{fileverb}
//----------------------------------------------
Behavior = BHV_Waypoint
{  
  . . .
  name = west_wpt_survey
  condition = REGION = west
  endflag   = RETURN = true

  points = -35,-65 : -35,-125 : 20,-125 : 20, -65
  . . .
} 
\end{fileverb}

\vspace{0.1in}
\noindent
For the first survey behavior, give it the name
\var{"east\_wpt\_survey"}.  Give a run condition requiring the survey
region is \var{"east"}.  Finally give it an end flag that triggers the
second survey behavior. The relevant parameters are:

\begin{fileverb}
//----------------------------------------------
Behavior = BHV_Waypoint
{  
  . . .
  name = east_wpt_survey
  condition = REGION = east
  endflag   = REGION = west

  points = 60,-40 : 60,-160 : 150,-160 : 180,-100 : 150,-40
  . . .
} 
\end{fileverb}


\vspace{0.1in}
\noindent
Lastly, you need to initialize the survey region to be east initially.
At the top of the behavior file:

\vspace{0.1in}
\begin{fileverb}
//--------    FILE: alpha.bhv   -------------                                   

initialize   DEPLOY = false
initialize   RETURN = false
initialize   REGION = east
\end{fileverb}

\vspace{0.1in}
\noindent
The end result when properly working should look like: 

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figures/s2_alpha_gif.png}
  \caption{The \var{s2\_alpha} mission in final working state.}
  \label{fig_s2_alpha_gif}
  \gif{figures/s2_alpha.gif}
\end{figure}



%======================================================================
\newpage
\subsection{Exercise 2 - Add Command and Control Switches to pMarineViewer}
\label{sec_s3}

In this exercise the goal is make a version of the Alpha mission
that requires the user to command the vehicle between the east and
west regions. Otherwise the vehicle will remain surveying in its
current region indefinitely. 

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s2\_alpha} mission, naming it \var{s3\_alpha}
\item Reconfigure each survey behavior to repeat forever
\item Configure \app{pMarineviewer} to have two new buttons for
  commanding the vehicle between the east and west regions
\end{packed_itemize}

\vspace{0.1in}
\noindent
To change the survey behaviors to repeat forever, change the repeat
paramter to be \var{"forever"}

\begin{fileverb}
//----------------------------------------------
Behavior = BHV_Waypoint
{  
  . . .
  repeat = forever
  . . .
} 
\end{fileverb}


\vspace{0.1in}
\noindent
The \app{pMarineViewer} app can be configured to add additional buttons
besides the \var{DEPLOY} and \var{RETURN} buttons in the Alpha mission.
The documentation for \app{pMarineViewer} can be found here:

\urlx{http://oceanai.mit.edu/ivpman/apps/pMarineViewer}


\vspace{0.1in}
\noindent
The \app{pMarineViewer} buttons are added as below. 

\begin{fileverb}
//----------------------------------------------
ProcessConfig = pMarineViewer
{  
  . . .
 button_three = WEST  #  REGION=west
 button_four  = EAST  #  REGION=east
  . . .
} 
\end{fileverb}


\vspace{0.1in}
\noindent
The end result when properly working should look like below. Note the buttons
and the button pushes by the user.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figures/s3_alpha.png}
  \caption{The \var{s3\_alpha} mission in final working state.}
  \label{fig_s3_alpha}
  \gif{figures/s3_alpha.gif}
\end{figure}


%======================================================================
\newpage
\subsection{Exercise 3 - Use uTimerScript to Control Mission State}
\label{sec_s4}

In this exercise the goal is to further modify the previous Alpha mission
where the vehicle changes between east and west based on the output
of a script, running in the \app{uTimerScript} MOOS Application.

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s3\_alpha} mission, naming it \var{s4\_alpha}
\item Add \app{uTimerScript} to the list of apps launched in the
  mission, inside the Antler configuration block of alpha.moos.
\item Configure \app{uTimerScript} with a simple script to switch
  between east and west mission every 90 seconds.
\end{packed_itemize}


\vspace{0.1in}
\noindent
The \app{uTimerScript} documentation can be found here:

\urlx{http://oceanai.mit.edu/ivpman/apps/uTimerScript}


\vspace{0.1in}
\noindent
The timer script for this exercise is below: You can copy it into your
mission file, but try to understand the configuration parameters by
reading the documentation.

\begin{fileverb}
//------------------------------------------
// uTimerScript config block
ProcessConfig = uTimerScript
{
  AppTick   = 4
  CommsTick = 4

  condition   = DEPLOY = true 
  event       = var=REGION, val="west", time=90 
  event       = var=REGION, val="east", time=180  
  reset_max   = nolimit  
  reset_time  = all-posted
}
\end{fileverb}

\vspace{0.1in}
\noindent
The end result when properly working should look like below. Note, at
every 90 seconds, the vehicle toggles between the East and the West
regions.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.84\textwidth]{figures/s4_alpha.png}
  \caption{The \var{s4\_alpha} mission in final working state.}
  \label{fig_s4_alpha}
  \gif{figures/s4_alpha.gif}
\end{figure}



%======================================================================
\newpage
\subsection{Exercise 4 - Integrate the iSay App to Behavior Events}
\label{sec_s5}

In this exercise the goal is to further modify the previous Alpha
mission to generate audio events when the vehicle completes surveying
in either region. Audio events will be generated with the \app{iSay}
MOOS App.

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s2\_alpha} mission, naming it \var{s5\_alpha}
\item Add \app{iSay} to the list of apps launched in the
  mission, inside the Antler configuration block of alpha.moos.
\item Configure \app{iSay} with its default configuration block
  and add it to alpha.moos.
\item Download to audio files \var{shipbell.wav}, and \var{buzzer.wav}
  from the MIT server.

\vspace{0.1in}
\begin{consoleverb}
 $ wget http://oceanai.mit.edu/pavlab/txt/shipbell.wav
 $ wget http://oceanai.mit.edu/pavlab/txt/buzzer.wav
\end{consoleverb}
\vspace{0.1in}

\item Configure the east survery mission to sound the shipbell sound
  upon completion. 
\item Configure the west survery mission to sound the buzzer sound
  upon completion. 

\end{packed_itemize}


\vspace{0.1in}
\noindent
The \app{iSay} documentation can be found here:

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



\vspace{0.1in}
\noindent
You will need to add an iSay event as an endflag for each behavior. For
example:

\begin{fileverb}
//--------------------------------------
Behavior = BHV_Waypoint
{   
  name      = east_waypt_survey  
  pwt       = 100  
  condition = RETURN = false  
  condition = DEPLOY = true   
  condition = REGION = east  
  endflag   = REGION = west
  endflag   = SAY_MOOS = file=shipbell.wav

  . . .
}
\end{fileverb}

\vspace{0.1in}
\noindent
And:

\begin{fileverb}
//--------------------------------------
Behavior = BHV_Waypoint
{   
  name      = west_waypt_survey  
  pwt       = 100  
  condition = RETURN = false  
  condition = DEPLOY = true   
  condition = REGION = east  
  endflag   = REGION = west
  endflag   = SAY_MOOS = file=buzzer.wav

  . . .
}
\end{fileverb}



%======================================================================
\newpage
\subsection{Exercise 5 - Station Keeping at Waypoints}
\label{sec_s6}

In this exercise the goal is to modify the original Alpha
mission to station-keep each time it arrives at one of its waypoints.
The user then re-clicks the DEPLOY button in \app{pMarineViewer}
to send the vehicle in motion again.

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s1\_alpha} mission, naming it \var{s6\_alpha}
\item Add a StationKeep behavior to the behavior file.
\item Add a wptflag configuration to the Waypoint behavior, such
  that it turns {\em off} the Waypoint behavior, and turns {\em on}
  the StationKeeping behavior.
\item Modify the \app{pMarineViewer} DEPLOY button such that it also
  turns off StationKeeping when it is clicked.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The end result when properly working should look like below. Note the buttons
and the button pushes by the user.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figures/s6_alpha.png}
  \caption{The \var{s6\_alpha} mission in final working state.}
  \label{fig_s6_alpha}
  \gif{figures/s6_alpha.gif}
\end{figure}

%======================================================================
\newpage
\subsection{Exercise 6 - Station Keeping at Waypoints, for Fixed Durations}
\label{sec_s7}

In this exercise the goal is to modify the previous Alpha mission,
which will station-keep each time it arrives at one of its waypoints,
to automatically resume its deployment after a short period of
time. No user involvement required.

\vspace{0.1in}
\noindent
You will need to do the following steps:
\begin{packed_itemize}
\item Copy the \var{s6\_alpha} mission, naming it \var{s7\_alpha}
\item Modify the StationKeep behavior to have a duration.
\item Add an endflag to the StationKeep behavior such that it shuts
  itself off after the duration expires.
\item Declare the StationKeep behavior to be perpetual - so that it
  can be used again after it completes.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The end result when properly working should look like below. Note that no buttons
are being pushed by the user.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figures/s7_alpha.png}
  \caption{The \var{s7\_alpha} mission in final working state.}
  \label{fig_s7_alpha}
  \gif{figures/s7_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/s2\_alpha/alpha.moos}
\item \urlx{https://oceanai.mit.edu/minicourse-pisa/missions/s2\_alpha/alpha.bhv}
\end{packed_itemize}

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

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

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

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

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


\end{document}
