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


%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 3 - Introduction to MOOS Programming}
\vspace{0.1in}
\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.1in}
\labpng{0.42}{figures/longfellow_rnd.png}
\vspace{0.1in}
\labdate{February 10th, 2026}
\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}
%===================================================================

In this lab we will produce our own MOOS applications. We begin by
downloading an example application complete with it's own build
structure. We proceed by making our first simple MOOS app emphasizing
the usage of the basic MOOS components.  This is followed by a couple
more complex application exercises.

\pskip

\noindent
This lab contains our first hand-in assignment. Although later in the
class we will be working with partners, in this lab, all work should
be done by individuals. When students post questions of general
relevance, we will make that information available to everyone.


\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item The MOOS Application Structure (Iterate, OnNewMail, OnStartUp Methods)
\item The MOOS Message Structure
\item Getting Started with Software Version Control
\item Downloading and Building the moos-ivp-extend tree
\item Build Your First MOOS App - An Odometry App
\end{packed_itemize}
\end{labinfo}


\subsection{Preliminaries}
\label{prelims}

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:

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

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

\vspace{0.1in}
\urlxx{https://oceanai.mit.edu/ivpman/labs/machine_setup}{Lab.ClassSetup}

%=====================================================================
\subsection{MOOS, MOOS-IvP and Your Applications}

In the previous lab we discussed the relationship between MOOS and
MOOS-IvP.  The MOOS tree is a body of software distributed as part of
the MOOS-IvP tree as depicted in Figure
\ref{fig_nested_archs}. MOOS-IvP provides additional MOOS
applications, including the IvP Helm behavior-based architecture, and
has C++ build dependencies on the MOOS libraries. Today the focus is
on building additional MOOS applications. Your MOOS apps will have a
build dependency on the MOOS libraries, and you may choose to utilize
libraries in the MOOS-IvP tree.  We start by downloading the
\var{moos-ivp-extend} tree which may be regarded as a template for
extending the MOOS-IvP tree with apps and behaviors. This tree also
includes a functioning build structure to ease the learning curve on
C++ build issues for now. You likely have already downloaded and built
this tree if you finished the last part of the previous lab.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/nested_moos_3pty.png}
  \caption{{\bf Nested Repositories:} The MOOS-IvP tree contains the
    Oxford MOOS tree and additional modules from MIT including the
    Helm architecture, Helm behaviors and further MOOS
    applications. The set of modules may be expanded with user
    third-party applications or behaviors.}
\label{fig_nested_archs}
\end{figure}

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

We will only just touch the MOOS programming basics today. A few
further resources are worth mentioning for following up this lab with
your own exploration.

\begin{itemize}

\item See the slides from the today's class which give a bit more
  background into MOOS and MOOS-IvP related to marine
  robotics. \newline
  \urlx{https://oceanai.mit.edu/2.680/docs/2.680-03-moos_programming_2026.pdf}

\item The Programming with MOOS documentation. \newline 
  \urlx{https://oceanai.mit.edu/2.680/docs/ProgrammingWithMOOS.pdf}

\item The moos-ivp.org website documentation. \newline 
  \urlx{https://oceanai.mit.edu/ivpman}

\end{itemize}

%==========================================================================
\subsection{The MOOS Application Structure}

The main idea explored today is the notion and structure of a MOOS
application.  We know from the last lab that MOOS apps publish,
subscribe for, and handle mail passed from one application to another
through the \app{MOOSDB}. In the last lab we worked with existing MOOS
apps, only modifying their functionality through configuration options
provided by the application author. Even without modifying the code of
existing MOOS apps there are many ways to configure a system for
unique domains.  However, the real power of MOOS comes from the fact
that no application is sacred. If you don't like what it does (or
doesn't) do, you are free copy {\em and rename it}, and modify the
code to your satisfaction. Or you can just build your own application
from scratch. This is the focus of today's lab.

\pskip

\noindent
The key components to keep in mind in today's lab are shown in Figure
\ref{fig_moos_functions} below. All MOOS apps begin by being a subclass
of the MOOSApp superclass defined in the Oxford MOOS library. The primary
work of the app developer is in writing the three functions shown in the 
figure.


\vspace{0.3in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.65\textwidth]{figures/moos_functions.png}
\caption{{\bf The MOOSApp Key Functions:} All MOOS apps are a subclass
  of the MOOSApp superclass. Development mostly boils down to
  overriding the three functions below with the particulars of one's
  own liking.}
\label{fig_moos_functions}
\end{figure}

%---------------------------------------------------------------------
\subsubsection*{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 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}. Except for \pvar{AppTick} and 
  \pvar{CommsTick}, configuration parameters are generally lower case. 
\item MOOS apps and executables generally, are rendered in magenta as with 
 \app{MOOSDB} and \app{GenMOOSApp}.
\item IvP Helm Behavior configuration parameters are rendered in \bvar{brown}, such
  as \bvar{priority=100} and \bvar{endflag=RETURN=true}.
\end{packed_itemize}

\noindent
This convention closely follows the convention used in the helm
documentation.

%==========================================================================
\subsection{Handy Functions Defined on MOOSMsg (MOOS mail)}

The below methods are defined on an instance of
\var{MOOSMsg}. Typically we are dealing with MOOS messages in the
\var{OnNewMail()} loop of an application.  Besides knowing the name of
the variable, you may also want to know (a) what is its value, (b) by
whom or which app was it posted, (c) when was it posted, (d) is its
value of type string or double, and so on.

\pskip

\noindent 
In our \app{pXRelayTest} example app, we only call \var{msg.GetKey()}
in \var{Relayer.cpp}, but all the below methods are available for
getting the message fields. (See today's lecture notes for a
description of a MOOS Message.)  This information is probably in the
MOOS documentation, but is repeated here for convenience.

\footnotesize
\begin{verbatim}

  // return the name of the message
  std::string GetKey();

  // return the name of the message (just another way)
  std::string GetName();

  // check data type is double
  bool IsDouble();

  // check data type is string
  bool IsString();

  // return time stamp of message
  double GetTime();

  // return double val of message
  double GetDouble();

  // return string value of message
  std::string GetString();

  // return the name of the process (as registered with the DB) which
  posted this notification
  std::string GetSource();

  // return the name of the MOOS community in which the orginator lives
  std::string GetCommunity();
\end{verbatim}
\normalsize

\vspace{0.1in} 
\noindent
Later on in this lab you will see that we provide a template for
generating the skeleton code of a new MOOS app. This is done using the
\cmd{GenMOOSApp} script. This skeleton code will generate the
following \var{OnNewMail()} method:

\vspace{0.1in}
\begin{fileverb}
bool MyApp::OnNewMail(MOOSMSG_LIST &NewMail)
{
  MOOSMSG_LIST::iterator p;
  for(p=NewMail.begin(); p!=NewMail.end(); p++) {
    CMOOSMsg &msg = *p;

#if 0 // Keep these around just for template 
    string key   = msg.GetKey();
    string comm  = msg.GetCommunity();
    double dval  = msg.GetDouble();
    string sval  = msg.GetString();
    string msrc  = msg.GetSource();
    double mtime = msg.GetTime();
    bool   mdbl  = msg.IsDouble();
    bool   mstr  = msg.IsString();
#endif
   }
   return(true);
}
\end{fileverb}

\vspace{0.1in}
\noindent
Note all the typical function calls you may want to make on an incoming 
MOOS message are right there, commented out to start with, but ready
to use if you need them in your application. (Everything between the 
\var{if 0} and \var{endif} is ignored by the compiler, so these lines
have the same effect as comment lines.)



%========================================================================
\subsection{Assignment 1 (self check off)}
\label{sec_assign1}

Verify that you have successfully downloaded and built the
\var{moos-ivp-extend} tree, and that the binaries of this tree are
findable in your shell path. If you haven't done this yet, see Section
\ref{sec_git} for info on how to obtain the \var{moos-ivp-extend} tree
from \cmd{git}.

\vspace{0.1in}
\noindent
Verify with the following:

\vspace{0.1in}
\begin{consoleverb}
  $ which pXRelayTest
  $ /home/you/moos-ivp-you/bin/pXRelayTest
\end{consoleverb}
\vspace{0.1in}

\noindent
If the \cmd{which} function returns no value, then either the binary
\app{pXRelayTest} was not built or you haven't successfully augmented
your shell path. First check to ensure it was built by examining the
contents of \var{moos-ivp-you/bin/}. If \app{pXRelayTest} is there,
then double check that you have properly augmented your shell path. If
need be, return to the help page:

\vspace{0.1in}

\urlxx{https://oceanai.mit.edu/ivpman/help/cmdline_augment_shell_path}{Help.CMDPath}

\vspace{0.1in}
\noindent
You can also display your shell's current path with:

\vspace{0.1in}
\begin{consoleverb}
$ echo $PATH
\end{consoleverb}
\vspace{0.1in}

\noindent
If you don't see \var{/home/you/moos-ivp-you/ivp/bin} in the colon-separated list
of locations constituting your shell path, then you are not done.

%======================================================================
\section{Getting Started with Version Control}
\label{sec_git}
%======================================================================

In Lab 3, a supplement document distributed for getting started with
\cmd{git}, and obtaining a copy of your \var{moos-ivp-extend} tree. This
document is online here:

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

\vspace{0.1in}
\noindent
At this stage you should have few steps under your belt:

\vspace{0.1in}
\begin{packed_itemize}
\item Created a GitHub account
\item Created a new \var{moos-ivp-extend} repo by importing the generally provided
  \var{moos-ivp-extend} repository.
\item Provided collaborator access to the TAs
\item Confirm you know how to modify a file in your tree and commit the changes
\item Confirm you can add a file or directory to your tree and commit changes.
\end{packed_itemize}

\vspace{0.1in}
\noindent
If the above steps are not complete, you should make sure they are
complete before moving on to the next section.

%======================================================================
\section{Build Your First MOOS App - An Odometry MOOS App}
%======================================================================

The focus of this section is on building your first MOOS App. Your goals are:

\begin{packed_enumerate}[3]
\item Learn how to generate a MOOS application from scratch using a
  template-generating script.
\item Learn how to add the new MOOS application to the build system.
\item Write your new MOOS app, \app{pOdometry}, to calculate the total
  distance traveled by the vehicle.
\item Test your MOOS app by using it in the Alder example mission to 
  have the vehicle return after traveling 50 meters.
\item Convert your MOOS app into an AppCasting MOOS App.
\end{packed_enumerate}

%=====================================================================
\subsection{Generating a Template App and Augmenting the Build System}

Your goal in this part is to generate a new application by using a
shell script to generate a full application template. The resulting
template should be buildable immediately without further modification,
but will essentially do nothing meaningful until you add your own
functionality.

%---------------------------------------------------------------------  
\subsubsection{Generate the MOOS App}
\label{sec_gen_moosapp}

To generate the new MOOS app, in a terminal window change directories to
\var{moos-ivp-extend/src/}. From here you should be able to invoke the 
below command:

\vspace{0.1in}
\begin{consoleverb}
 $ GenMOOSApp_AppCasting Odometry p "Jane Doe"
\end{consoleverb}
\vspace{0.1in}

\noindent
The above script, \app{GenMOOSApp\_AppCasting}, should be in your
shell path under \var{moos-ivp/scripts/}. You may need add this
directory to your shell path if you haven't done so already. The above
script invocation builds a new app called \app{pOdometry}. The third
argument is your name. You can type \app{GenMOOSApp\_AppCasting -h} in
the future to remind yourself.

%---------------------------------------------------------------------  
\subsubsection{Add Your Name}

Always, always, always put your name at the top of your source code
files!  This is a good practice in general, but even more so in a
class setting, or an open source environment where people are sharing
code. It wouldn't hurt to add the date and organization information too.

%---------------------------------------------------------------------  
\subsubsection{Add Your New Application to the Build System}
\label{sec_add_bld}

Add your new app to the build system. Edit the file
\var{moos-ivp-extend/src/CMakeLists.txt} and look for the line
referring to \app{pXRelayTest}. Copy that as an example for your new
app.

\vspace{0.15in}
\begin{fileverb}
 #==========================================================================
 # List the subdirectories to build...   
 #========================================================================== 
 ADD_SUBDIRECTORY(lib_behaviors-test)
 ADD_SUBDIRECTORY(pXRelayTest)
 ADD_SUBDIRECTORY(pExampleApp)       
 ADD_SUBDIRECTORY(pOdometry)                 <-- Add your line here
\end{fileverb}
\vspace{0.05in}

%======================================================================
\subsection{Assignment 2: (self check off) Verify Skeleton pOdometry has Built}
\label{sec_path}

Go back and re-run your build script. Check to see that
\app{pOdometry} has been built, and is in your bin directory (e.g.,
\var{moos-ivp-you/bin)}.

\vspace{0.1in}
\noindent
Verify that \app{pOdometry} is in your shell path with:

\vspace{0.1in}
\begin{consoleverb}
  $ which pOdometry
  $ /home/you/moos-ivp-you/bin/pOdometry
\end{consoleverb}
\vspace{0.1in}

\noindent
If the \cmd{which} function returns no value, then either the binary
\app{pXRelayTest} was not built or you haven't successfully augmented
your shell path. See above in Section \ref{sec_assign1} for tips on how
to remedy the problem.



%======================================================================
\subsection{Writing the Odometry MOOS App}

The goal of this step is to build a new simple MOOS application that
calculates vehicle odometry. It will:

\begin{packed_enumerate}[3]
\item Register for the \mvar{NAV\_X} and \mvar{NAV\_Y} position of  the vehicle.
\item Repeatedly read in the \mvar{NAV\_X} and \mvar{NAV\_Y} position of
  the vehicle.
\item Update the total distance traveled by calculating the distance
  between the present position and the previous position.
\item Post the odometry information in the MOOS variable \mvar{ODOMETRY\_DIST}.
\item The posted odometry distance should be consistent regardless of
  the AppTick of the \app{pOdometry} app. You can check this by
  changing the AppTick of your app while leaving the AppTick of
  \app{uSimMarineV22} unchanged.
\end{packed_enumerate}

\pskip

\noindent
We will do this in your newly checked out moos-ivp-extend tree. Begin
as follows:

\begin{packed_itemize}[3]

\item Edit \var{Odometry.h} to have at least the six member variables:
 
\vspace{0.15in}
\begin{Verbatim}[frame=single]
 bool   m_first_reading;
 double m_current_x; 
 double m_current_y; 
 double m_previous_x; 
 double m_previous_y; 
 double m_total_distance;
\end{Verbatim}

\noindent
You may of course use further member variables if you see the need. 

\item Edit \var{Odometry.cpp} to initialize the above member
  variables, in the class constructor.

\item Edit \var{Odometry.cpp} to register for \msvar{NAV\_X} and \msvar{NAV\_Y}.

\item Edit the \func{Odometry::OnNewMail()} method to handle the
  updated navigation position.

\item Edit the \func{Odometry::Iterate()} method to calculate the new
  distance. Handle the special case of the first navigation
  measurement. Post the total distance to the MOOS variable
  \msvar{ODOMETRY\_DIST}.

\item Verify that everything builds...
\end{packed_itemize}

\noindent
There is one common "gotcha" in this lab. Keep in mind that the
\msvar{NAV\_X} and the \msvar{NAV\_Y} variables are being published by
the \app{uSimMarineV22} application. This application is running at 10Hz
and producing on average 10 incoming mail messages for your
\app{pOdometry} app. If your \app{pOdometry} app is running at the
default rate of 4Hz, then on average your app will have 2-3 incoming
mail messages on each iteration. If you find that your odometry
calculations only reflect about half of the actual distance traveled,
reconsider how you are calculating the length of new legs.

%================================================================
\subsection{Use Your pOdometry app in the Alder mission}

The first goal is to just make sure it runs and posts the correct
information.  The second goal is to use the information to alter the
mission behavior.

\vspace{0.1in}
\noindent
{\bf NOTE:} Depending on when you cloned the \var{moos-ivp-extend} tree,
you may need to ensure that all references to \app{uSimMarine} are replaced
with \app{uSimMarineV22} and all references to \app{pMarinePID} are replaced
with \app{pMarinePIDV22}, in the \var{alder.moos} file.

%----------------------------------------------------------
\subsubsection{Running the Un-modified Alder Mission}

First make sure that you can run the Alder mission. Try it:

\vspace{0.15in}
\begin{consoleverb}
 $ cd moos-ivp-extend/missions/alder
 $ pAntler --MOOSTimeWarp=10 alder.moos
\end{consoleverb}
\vspace{0.15in}

\noindent
It should look something like the video posted at:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.94\textwidth]{figures/alder_one.png}
  \caption{The Alder mission. The vehicle travels to point
  (100,-50) and returns home.}
  \label{fig_alder}
  \gif{figures/alder_one.gif}
\end{figure}
\vspace{0.1in}

%----------------------------------------------------------
\subsubsection{Run the Alder Mission with pOdometry}

Next we'll add the \app{pOdometry} application to the mission and just
verify it is generating the right output.  Do the following steps:

\begin{packed_itemize}[3]
\item Modify the Alder mission
  (\var{moos-ivp-extend/missions/alder/alder.moos}) to include
  \app{pOdometry} at launch time by editing the \app{Antler} block in the
  alder.moos file.

\item Add \mvar{ODOMETRY\_DIST} to the scope list in
  \app{pMarineViewer}. See the \app{pMarineViewer} documentation to
  see how to do this. It should look something like:

\vspace{0.1in}
\begin{fileverb}
ProcessConfig = pMarineViewer
{
  AppTick    = 4
  CommsTick  = 4

  ...
  scope = ODOMETRY_DIST    // <-- Add this line
  ...
}
\end{fileverb}
\vspace{0.1in}

\item Re-launch the mission. Now you should be able to see the odometry
distance in the scope field at the bottom of \app{pMarineViewer}. Does
it look correct?

\end{packed_itemize}


%----------------------------------------------------------
\subsubsection{Modify the Alder Mission Using pOdometry}

In the next step, we will modify the alder mission as follows. Instead
of transiting to the waypoint specified in the waypoint behavior, the
vehicle will return home after it has transited 50 meters. We haven't 
covered the Helm yet in class, so some of this we'll take on faith for 
now. 

\pskip
Take a look inside \var{alder.bhv}. This is where the helm is
configured.  The mission is comprised of two instances of a waypoint
behavior. The first transits to a given point and is called
\var{waypt\_to\_point}. It has two conditions, we'll add a third:

\vspace{0.1in}
\begin{fileverb}
//----------------------------------------------
Behavior = BHV_SimpleWaypoint
{
  name      = waypt_to_point
  pwt       = 100
  condition = RETURN = false
  condition = DEPLOY = true
  condition = (ODOMETRY_DIST < 50)         // <-- Add this line

  endflag   = RETURN = true

  speed      = 2.0   // meters per second
  radius     = 8.0
  ptx        = 100
  pty        = -50
}
\end{fileverb}
\vspace{0.1in}

\noindent
The second waypoint behavior is designed to return after the first one
completes. It also has two conditions:

\vspace{0.1in}
\begin{fileverb}
 condition = RETURN = true
 condition = DEPLOY = true
\end{fileverb}
\vspace{0.1in}

\noindent
We'll change that to:

\vspace{0.1in}
\begin{fileverb}
condition = (RETURN = true) or (ODOMETRY_DIST >= 50)
condition = DEPLOY = true
\end{fileverb}
\vspace{0.1in}

%================================================================
\subsection{Assignment 3 (check off) Verify Your pOdometry Works}

After the above modifications, re-launch the mission. Demonstrate to
one of the TAs that your \app{pOdometry} works. It should look
something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.94\textwidth]{figures/alder_two.png}
  \caption{The Alder mission with odemetry. The vehicle begins to travel
    to point (100,-50), but returns home early based on odometry
    distance.}
  \label{fig_alder}
  \gif{figures/alder_two.gif}
\end{figure}
\vspace{0.1in}



%========================================================================
\subsection{Assignment 4 (check off) Convert pOdometry to an AppCasting MOOSApp}

The last step will be to convert your \app{pOdometry} application to
be appcast enabled. Follow the instructions from today's lecture
notes, or read the documentation for enabling appcasting:

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

\vspace{0.15in}
\noindent
If you used the \var{GenMOOSApp\_AppCasting} script to make your
initial folder for \app{pOdometry}, then your app is already mostly
AppCast enabled. You just need to implement the AppCasting output.
The output of your appcast report (in the \func{buildReport()}
function) should simply show the total distance traveled.


%======================================================================
\newpage
\section{Some Hints for Debugging}
%======================================================================

There are a few common methods for debugging a MOOS App, and we'll
have more to say about this during the semester. But here are a few
methods. The third method described below is a new feature added only
in the last six months and is probably you most powerful option.

%======================================================================
\subsection{Run the Logger}

If your Alder mission is not yet including \app{pLogger}, you will need to
add it to your mission for these steps.

\vspace{0.1in}
\noindent
To add \app{pLogger} to your mission, add it the Antler config block
with the additional line:

\vspace{0.1in}
\begin{fileverb}
  Run = pLogger @ NewConsole = false
\end{fileverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
You will also need a configuration block for \app{pLogger} in the same mission file,
e.g., \var{alder.moos}. The below block should work fine:

\vspace{0.1in}
\begin{fileverb}
ProcessConfig = pLogger
{
  AppTick   = 8
  CommsTick = 8

  AsyncLog = true
  WildCardLogging = true
}
\end{fileverb}
\vspace{0.1in}




%======================================================================
\subsection{Debugging with Additional MOOS Publications}

In this lab, the primary output of your app is the variable
\mvar{ODOMETRY\_DIST}. You are free to publish as many other variables
as you like, to perhaps reveal any intermediate calculations, or other
information. For example you can publish \mvar{LEG\_DIST} if you are
calculating the distance one leg at a time.

\vspace{0.1in}
\noindent
To utilize this method, you will need to either (a) scope on this
additional variable while the mission is running, or (b) examine the
variable from the log file after the mission is complete. The latter
method gives you more time to ponder the values. To examine the
log file, you can use \cmd{aloggrep}, along the lines of:

\vspace{0.1in}
\begin{consoleverb}
$ aloggrep logfile.alog ODOMETRY_DIST LEG_DIST
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
Or you can open \cmd{alogview} and scope on the above two variables using the
\var{VarHist} pull-down menu. See the documentation for \app{alogview}. Either
point your browser to:

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

\vspace{0.1in}
\noindent
Or, on the command line, just type the below, and your browser should take you there.

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

%======================================================================
\subsection{Debugging with Terminal Output, Method 1}

Another powerful method for debugging is to add \var{cout} statements to your code,
to show intermediate values. So, for example, instead of publishing \mvar{LEG\_DIST}
as a MOOS variable, you can instead add something like this to your code:

\vspace{0.1in}
\begin{fileverb}
double leg_dist = ...
cout << "Leg dist: " << leg_dist << endl;
\end{fileverb}
\vspace{0.1in}

\noindent
To see this output, you would need to launch your app with a terminal window open, OR
remove your app from the Antler block and run it separately from another terminal
window. So in the first terminal window:

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

In the second terminal window:

\vspace{0.1in}
\begin{consoleverb}
$ pOdometry file.moos
\end{consoleverb}
\vspace{0.1in}

\noindent
Make sure you use the same \var{.moos} file in both launches. And note that if
you launch your mission with a time warp, \app{Antler} will generate a
\var{file.moos++} mission file with the proper time warp. You would then need to
launch your app with the same \var{.moos++} file to get the same time warp.

%======================================================================
\subsection{Debugging with Terminal Output, Method 2 (Recommended)}

If you have successfully created your app as an AppCasting MOOS App, then there
is another simpler option for debugging with terminal output.

\vspace{0.1in}
\noindent
As above, inject your code with \var{cout} statements to produce what you would
like. But rather than running your app in a separate Terminal window, simply add
the below line to the configuration block for your app:

\vspace{0.1in}
\begin{fileverb}
app_logging = log
\end{fileverb}
\vspace{0.1in}

\noindent
This will log all the terminal output from your app in the \var{alog} file. Then
you can view your terminal output by launching \app{alogview}. Once this is
launched, select \var{AppLog} from the pull-down menu, select the vehicle name,
and select your app from the list. You should then be able to see all your
terminal output.

\vspace{0.1in}
\noindent
If you are trying this debugging method and have issues, please come
find me. This is a new feature and not yet documented in the
\app{alogview} documentation.





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

%======================================================================
\subsection{Adding Terminal Output to your App for Debugging}

At some point you will need to debug a faulty app. A powerful tool for doing
this is to generate terminal output (\var{cout} commands). In this exercise
we will generate some simple output and show how we can view this output {\em after}
the mission has completed using the \app{alogview} tool.


\begin{packed_itemize}
\item Make sure your app is AppCast enabled if it is not already.
\item Add terminal output in your app to show each new \mvar{NAV\_X} and \mvar{NAV\_Y}
  received, e.g., \newline \var{cout << "nav\_x: " << value << endl;}

  
\item Add terminal output in your app to show each new value of  \mvar{ODOMETRY\_DIST}
  calculated.
\item Enable app logging by setting \var{app\_logging=log} in the \app{pOdometry}
  configuration block of your misssion file.
\item Run your mission to completion.
\item Find the alog file and launch \app{alogview} on this alog file.
\item Select \var{AppLog} from the pull-down menu and confirm that you can see your
  terminal output.
\item Show a TA.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Note that some of this functionality could also be achieved by
generating AppCasting output. This is not a replacement for that. One
advantage of AppLogging is that terminal output can be captured
regardless of the level of code being executed. The \var{cout} call
may be used in code that is called by your app several levels down.

%======================================================================
\subsection{Adding Run Time Checks for Steady Nav Information}

Another powerful tool for developing robust apps is the use of run time
err checking. AppCasting MOOS Apps support this with the \var{reportRunWarning()}
function. In this exercise:

\begin{packed_itemize}
\item Add a timestamp (a new member variable) to note when the latest \mvar{NAV\_X}
  or \mvar{NAV\_Y} was received.
\item If an interval of 10 seconds or more passes, without receiving new NAV info,
  generate a run warning.
\item Retract this warning when or if the NAV info resumes.
\item To test this, run the Alder mission as normal. In another terminal window,
  type \var{killall uSimMarineV22}. This will halt the NAV info. Verify the run warning
  appears in your Odometry app.
\item Then, also in a separate terminal window in your Alder mission, restart the
  simulator with \var{uSimMarineV22 alder.moos}.
\item  Show a TA.
\end{packed_itemize}

%======================================================================
\subsection{Bonus: Configure the Staleness Threshold}

To gain some experience with configuration parameters:

\begin{packed_itemize}
\item Add a configurtion parameter to set the staleness threshold to something
  else besides the above default of 10 seconds.
\item You will need to make this value a variable in your MOOS App instead of the
  the hard-coded \var{"10"} as before.
\item Perform a check on the configuration parameter that it is a number greater
  than zero. If a user provides a faulty number in the mission file, produce a
  configuration warning.
\item Show a TA.  
\end{packed_itemize}

%======================================================================
\subsection{Bonus: Configurable Units}

Parameters that may be configured at {\em launch-time} are sometimes
also configurable at {\em run-time}. There are many reasons for
this. The two most-common reasons are (1) a parameter setting {\em
  augments} a set of parameters given at launch-time, with additional
components that become known at run-time. (2) a parameter setting may
involve the verbosity of output, perhaps in toggling on/off the
publication of a MOOS variable providing debugging output. The need
for debugging verbosity may change during run-time.

\vspace{0.1in}
\noindent
In this last bonus exercise, the task is to augment the \app{pOdometry}
app with the ability to configure an additional publication of odometry
distance in any arbitrary units provided either at configuration time
or at run-time.




%======================================================================
\newpage
\section{Due Date and Grading Criteria}
%======================================================================

%======================================================================
\subsection{Due Date}

All MOOS apps described in this lab are due during lab Thursday February
12th, 2026.  Apps will be tested during lab, and source code is due to
the graders at the end of the lab.

%======================================================================
\subsection{Grading Criteria}

Grading will be based on 

\begin{packed_enumerate}
\item Implementation Credit (60\%)
\item Code Organization (40\%) 
\end{packed_enumerate}


\vspace{0.15in}
\noindent
Full credit will given be based on whether or not you have met the
given specs.

\vspace{0.15in}
\noindent
Code organization includes the issue of commenting your code, and
choosing a robust code structure, e.g., properly initializing
variables etc.  Beginners to C++ programming can expect a healthy
amount of constructive criticism in the first assignments. See the
9th and 10th C++ labs on the website: "C++ Coding Guidelines" and "C++
Coding Style Guidelines".


\vspace{0.1in}
\noindent
Unfinished assignments will be tested and accepted in the next lab. 
A 5\% deduction will be applied for each lab that goes by unfinished.


%===================================================================
\subsection{Submitting Instructions for Lab 03}

Lab 03 assignments should be submitted using the version control
mechanism described earlier.  Your directory format should have the
naming and file organization as indicated below:

\small
\begin{consoleverb}
moos-ivp-yourname/
   src/
     pOdometry

   missions/
     alder/
       alder_lab3.moos
       alder_lab3.bhv

   lib/                (should be empty)
   bin/                (should be empty)
   build/              (should be empty)
   build.sh            (should be unchanged)
   CMakeLists.txt      (should be unchanged)

\end{consoleverb}
\normalsize

\end{document}
