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

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 2 - Robot Middleware, Autonomy and Missions}
\vspace{0.2in}
\labcourse{2.S01 Introduction to Autonomous Underwater Vehicles}
\vspace{0.5in}
\labpng{0.35}{figures/sb2.png}
\vspace{0.25in}
\labdate{Spring 2025}
\vspace{0.23in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Supun Randeni, supun@mit.edu}
\labauth{Mike Sacarny, msacarny@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{scriptsize}
\labtocdepth{2}
\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}
%===================================================================

The goals of this lab are to introduce concepts on robot middleware,
autonomy, and methods for launching missions on an AUV and in
simulation.

\vspace{0.1in}
\noindent
Concepts introduced in this lab:

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item The difference between monolithic software applications
  and distributed/modular applications. 
\item Robot middleware and its role on an AUV
\item Launching and interacting with robot apps
\item The sense-plan-act loop for autonomous robots
\item Methods for launching missions in simulation and in the field
\end{packed_itemize}
\end{labinfo}

\vspace{0.1in}
\noindent
Pre-lab assumptions:

%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item You have a course laptop and AUV training kit
\item You have downloaded and built the course autonomy software
  and are able to run the Alpha mission
\item You are able to log into the RasPi and the PocketBeagle computer
\item You have reviewed and can identify the basic hardware components of the SB2 AUV
\item You are able to run the command-line scripts to access the sensors and actuators.
\end{packed_itemize}

%=======================================================================
\subsection*{Linking the Course Web Pages}

There are two main web pages for this course, the main course page on
the MIT server, and the Piazza Page. We recommend putting these pages
in your browser's bookmarks or Favorites tab as soon as possible. We
will be referring to them a lot:

\vspace{0.1in}
\begin{packed_itemize}
\item {\em Course wiki}: \urlx{https://oceanai.mit.edu/2.S01}
\item {\em Piazza}: \urlx{https://piazza.com/mit/spring2025/2s01}
\end{packed_itemize}
\vspace{0.1in}

%=======================================================================
\section{Concepts I: Robot Software}
%=======================================================================

At this stage we have thus far established how to log into our course
laptops, and from there log into the AUV RasPi computer, and from the
RasPi log into the PocketBeagle computer. We turn our attention now to
the software environment running on each computer. 

%=======================================================================
\subsection{Stand-Alone Applications vs Coordinated Applications}

A term {\em application} is refers to a {\em program} that runs on
your computer.  Examples include your web browsers, calendar, MS Word,
a PDF viewer and so on.  Other equivalent terms are an {\em
  executable}, or a {\em a binary}. The latter refers to a class of
programs that are compiled, i.e., translated from human-readable
software into a file that is runnable on your computer. C++
applications of this style. The executable C++ program is no longer
human-readable when examining the file contents, resembling more a
collections of 1's and 0's, thus the term {\em binary}.

\vspace{0.1in}
\noindent
Some applications are {\em stand-alone}, meaning the application is a
single program running, with perhaps I/O to the user using the
program, and I/O to the system hard drive, or I/O over the
Internet. Other applications are {\em coordinated}, meaning the
functionality is comprised of a number of applications coordinating
and communicating with each other to perform their tasks. Coordinated
applications my all be running on a single computer, or may be
distributed over a local network or over the Internet. Two common ways
of coordinating communications between multiple apps are shown in
Figure \ref{fig_multi_apps}.

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=0.64\textwidth]{figures/multi_apps.png}
\caption{Two ways of coordinating multiple apps: (a) direct
  communications between apps, or (b) inter-app communication through
  another app as a broker.}
\label{fig_multi_apps}
\end{figure}

\vspace{0.1in}
\noindent
The advantage of direct communications between apps is the reduced
latency since messages do not need to be routed through an
intermediate app. The advantage of using the intermediate app is
reduced complexity in how apps discover one another and other
simplifications. In practice, both styles are commonly found on
robots.

%=======================================================================
\subsection{Robot Middleware}

The primary role of a robot {\em middleware} is to facilitate
communication between applications. MOOS is the middleware used on the
Sea Beaver II AUV. It uses a publish-subscribe protocol where messages
are regarded as {\em mail} messages. A particular app has an {\em
  interface}, defined by which mail it publishes and to which mail it
subscribes. Sometimes such architectures are referred to as "pub-sub"
architectures. Each app is refereed to as a "MOOS App", and the app
handling the mail processing is an a called a MOOS Database, or
MOOSDB for short.

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=0.44\textwidth]{figures/pubsub.png}
\caption{MOOS uses an application called the MOOSDB to broker
  communications between applications. Each app looks for the mail it
  needs and otherwise typically is not concerned with which app or
  apps generated the mail. This enables one app to be swapped for
  another as long as it matches the publication/subscription interface
  of the app being replaced.}
\label{fig_pubsub}
\end{figure}

\vspace{0.1in}
\noindent
Each MOOS app has an internal endlessly running loop. At the outset of
each loop, MOOS reads a mailbox for any incoming mail messages. Each
message is characterized by a MOOS variable and the value for that
variable. Each app {\em registers} for mail by subscribing to one or
named variables at the outset. Once the mail has been read, the
primary loop is executed, during which the app may publish outgoing
messages of its own. The frequency of this loop can be configured by
the user, and depends on the operation. For example, an app handling
GPS messages may run at 5 Hz if the GPS device is publishing updated
positions five times per second.

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=0.4\textwidth]{figures/moos_freq.png}
\caption{{\bf MOOS Community}: a collection of MOOS apps communicating
  with a single MOOSDB is a MOOS {\em community}. MOOS middleware
  allows the user to configure the execution rate for each app.}
\label{fig_moos_freq}
\end{figure}

\vspace{0.1in}
\noindent
When an AUV is prepared for launch, the operator will run a script to
launch all apps including the MOOSDB. Once the apps have started with
no errors or warnings, the operator can release the vehicle to begin
its mission in the water. The MOOS middleware includes utilities for
launching the mission, monitoring for warnings, and logging the data
during the mission.

\vspace{0.1in}
\noindent
Other well known middlewares include ROS, MOOS, LCM and DDS.

%=======================================================================
\subsection{Further MOOS Basics}

A few further basic MOOS features are described there that are useful
up front and for today's lab.

%-----------------------------------------------------------------------
\subsubsection{MOOS IP Address, Port Number, and Community Name}

The \app{MOOSDB} is a {\em server}, with clients (apps) in regular
communication with incoming and outgoing mail messages. Apps need to
know where to reach the MOOSDB, so the MOOSDB needs to launch with
three pieces of configuration information, (a) the machine IP address
on which to run, and (b) the port number on which to serve clients,
and the community name. Typically the latter corresponds to the
name of the robot. 

\vspace{0.1in}
\noindent
An IP address is comprised of four numbers in the range of [0,255]
separated by a period. IP addresses are used for finding a particular
machine on the Internet. For example, the oceanai class server resides
at 18.18.38.22. The term "localhost" acts as a stand-in IP address
when referring to one's own machine. The port number refers to a
channel of sorts on a computer. It's fair to think of the IP address
like the street address of an apartment building, and the port number
as the unit number within the building where a particular resident
resides.

\vspace{0.1in}
\noindent
When the MOOSDB is launched, it is launched with the IP address
and port number as configuration parameters. All apps are also
launched with the same IP address and port number, so they know
where to find the MOOSDB. 

%-----------------------------------------------------------------------
\subsubsection{MOOSDB Contents}

The MOOSDB holds the latest value of all published mail for all
variables.  We say a variable has been {\em written} to if some MOOS
app published an outgoing mail message using that variable name. Two
important notes: (1) If an app writes to a variable several times, an
app that has registered for that variable may have several mail
messages for that variable in its in-box on its next iteration. The
receiving app will receive all mail messages, even if the publishing
app is posting the mail much more frequently than the receiving
app. (2) When an app is launched and first connects to the MOOSDB, if
it registers for a variable \var{FOOBAR}, it will at least receive the
most recently posted mail to \var{FOOBAR}, even it was published by an
app long ago.

\vspace{0.1in}
\noindent
The current state of the MOOSDB can be thought of in terms of a table
like that shown in Figure \ref{fig_moosdb_contents} below. Each row in
the table contains the MOOS variable name, the app the that last
published the variable, the MOOSDB community name, time of the last
publication, and the current value of the variable. 

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=0.64\textwidth]{figures/moosdb_contents.png}
\caption{MOOS uses an application called the MOOSDB to broker
  of the app being replaced.}
\label{fig_moosdb_contents}
\end{figure}

\vspace{0.1in}
\noindent
Not surprisingly, the structure of every MOOS message, i.e., piece of
mail, contains these fields, and a few others discussed later. The
timestamp, in seconds, is relative to the start time of the MOOSDB.
When the MOOSDB is started, the start time is noted and logged so each
message can be traced back to a global time stamp.


%-----------------------------------------------------------------------
\subsubsection{MOOS Conventions}

A few conventions are worth mentioning at this stage. Like most
conventions, these are not enforced rules, but rather a set of common
practices that make things easier to understand for users.

\begin{packed_itemize}
\item {\em MOOS app names}: MOOS apps typically start with a lower
  case letter, usually \var{'p'}, \var{'u'}, or \var{'i'}. For example
  \app{pHelmIvP}, \app{uXMS}, or \app{iGPS}. The \var{'p'} apps are
  typically core processes like \app{pHelmIvP} or \app{pNodeReporter}.
  The \var{'u'} apps are typically utilities like \app{uXMS}, \app{uMAC},
  or \app{uTimerScript}. The \var{'i'} apps are typically associated with
  drivers of instruments, like \app{iGPS}, \app{iSeaTrackX15}. Apps that
  begin with \var{'uFld'} belong to the uField Toolbox collection of
  utilities for coordinating shore and field operations. 
\item MOOS variable names are typically (a) upper case, (b) only
  contain the underscore character for white space, (c) and if they
  contain numbers, they are usually the trailing characters of the
  variable name.  Good names: \mvar{DEPTH}, \mvar{NAV\_SPEED},
  \mvar{THRUSTER\_4}. Bad examples: \mvar{temperature},
  \mvar{LEFT@SIDE}, \mvar{856\_VALUE}.
\item Most MOOS apps support a few useful command-line options. For
  these options, instead of launching the app, useful help output will
  be displayed followed by the immediate quit of the app.  The
  \var{--example}, or \var{-e} option will display an example
  configuration block for the app, often with indications of default
  values an parameter value options. The \var{--interface}, or
  \var{-i} option will display the variables published and subscribed
  for by the app, often with example variable values to give an idea
  of the format or type of certain variables. The \var{--web}, or {-w}
  option will open a web browser to the full documentation of the MOOS
  app. Most but not all apps support this option.
\end{packed_itemize}

\noindent
In documentation, MOOS apps are indicated in color by magenta, e.g.,
\app{pHelmIvP}, MOOS variable names in green, e.g., \mvar{NODE\_REPORT},
and MOOS app configuration parameters in blue, e.g., \pvar{vehicle\_name}.


%=======================================================================
\section{Exercises I: Experimenting with Robot Software}
%=======================================================================

In the below exercises we will experiment with the MOOS middleware
and AUV software in simulation, both on the course laptop and the
AUV training kit. 

\subsection{Exercise 1: Launch MOOSDB and a Scope (self checkoff)}

In this exercise you will use your course laptop to launch a small
MOOS community of just the MOOSDB and a scope. A {\em scope} is any
app that connects to and provides visibility into the values currently
held by the MOOSDB. We will bump into a few tools in this class that
act as a scope. A simple tool used in this exercise is
\app{uXMS}. First let's launch a MOOSDB in a terminal window. In this
exercise we will want a few open terminal windows, so before you begin,
open three distinct terminal windows on your laptop and make sure all
can be viewed simultaneously.

\vspace{0.1in}
\noindent
{\bf Step 1:} In the first terminal window:

\begin{consoleverb}
 $ MOOSDB
 ------------------- MOOSDB V10 -------------------
 Hosting  community                "#1"
 Name look up is                   off
 Asynchronous support is           on
 Connect to this server on port    9000
 --------------------------------------------------
 network performance data published on localhost:9020
 listen with "nc -u -lk 9020"
\end{consoleverb}

\noindent
At this point the \app{MOOSDB} is running on the local machine,
serving clients on port 9000. A few variables are already being
published, by the \app{MOOSDB} itself.

\vspace{0.1in}
\noindent
{\bf Step 2:} In the second terminal window, open a scope by launching
the \app{uXMS} app: 

\vspace{0.15in}
\begin{consoleverb}
  $ uXMS DB_CLIENTS DB_TIME DB_UPTIME --serverhost=localhost --serverport=9000 

  ==============================================================
  uXMS_581                                              0/0(154)
  ==============================================================
  VarName     (S)ource   (T)ime  (C)  VarValue (SCOPING:EVENTS)
  ----------  ---------  ------  ---  -------------------------
  DB_CLIENTS  MOOSDB_#1  38.14        "uXMS_581,"
  DB_TIME     MOOSDB_#1  38.14        1387380731.414707
  DB_UPTIME   MOOSDB_#1  38.14        39.00859
\end{consoleverb}

\noindent
The Source and Time columns may be expanded by hitting the \var{"s"} and 
\var{"t"} keys respectively after it launches, or you can add 
\var{--show=source,time} as a command line argument to \app{uXMS}, to 
launch with these two columns expanded.

\vspace{0.1in}
\noindent
{\bf Step 3:} Create a file with the following three lines, and
save it as \var{mission.moos}

\vspace{0.1in}
\begin{consoleverb}
ServerHost = localhost
ServerPort = 9005
Community  = alpha
\end{consoleverb}

\noindent
In the two terminal windows running the MOOSDB and \app{uXMS}, quit by
typing \var{ctrl-c}. In this step, repeat the above launches except
this time provide the \var{mission.moos} file as an argument, like:

\vspace{0.1in}
\begin{consoleverb}
$ MOOSDB mission.moos         (in terminal one)
\end{consoleverb}

\noindent
and

\begin{consoleverb}
$ uXMS mission.moos --all      (in terminal two)
\end{consoleverb}
\vspace{0.1in}

\noindent
Both apps should launch, providing essentially the same output as
before, but notice that the community name is \var{"alpha"}, and the
MOOSDB is serving content on port 9005. The use of the
\var{mission.moos} file makes launching much easier, and the mission
file will be used in most all cases in the future. 

%====================================================================
\subsection{Exercise 2: Launch MOOSDB, Scope and Poke (self checkoff)}

In this exercise, still on the course laptop, we will again launch a
MOOSDB and scope, but also {\em poke} the MOOSDB with new values for
new variables. We will need three terminal windows open to do this
exercise. We will also use the three-line \var{mission.moos} file with
contents:

\vspace{0.1in}
\begin{fileverb}
ServerHost = localhost
ServerPort = 9005
Community  = alpha
\end{fileverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
{\bf Step 1:} In two side-by-side terminal windows, again launch a
MOOSDB in one window, and the \app{uXMS} app. In this case \app{uXMS}
is launched with \var{--show=source} so the column showing the app
responsible for the posting the most recent value is shown.

\vspace{0.1in}
\begin{consoleverb}
$ MOOSDB mission.moos                      (in terminal one)
$ uXMS mission.moos --all --show=source    (in terminal two)
\end{consoleverb}
\vspace{0.1in}

\noindent
In the third terminal window, invoke the \app{uPokeDB} app to publish
a new variable with a value. Since \app{uPokeDB} will connect to the
MOOSDB just launched, it also needs to know the IP address and port
number. Try the following in the third window:

\vspace{0.1in}
\begin{consoleverb}
$ uPokeDB mission.moos DEPTH=85
  ...

VarName  Source  Time  VarValue
-------  ------  ----  --------
DEPTH                  n/a     

VarName  Source   Time   VarValue
-------  -------  -----  --------
DEPTH    uPokeDB  34.18  85.00000
\end{consoleverb}
\vspace{0.1in}

\noindent
The poke will be made and you should see the output similar to the
above where the previous value of \mvar{DEPTH} is shown, followed by
the new value after the poke. If the variable has never been written
to before, the value will simply be \var{"n/a"} as in this example.

\vspace{0.1in}
\noindent
The output of \app{uXMS} should have also changed, with addition of
the new line for the variable \mvar{DEPTH}, and it should also show
\app{uPokeDB} as the source application responsible for this value.

\vspace{0.1in}
\noindent
{\bf Step 2:} Try poking again with a different value: 

\vspace{0.1in}
\begin{consoleverb}
$ uPokeDB mission.moos DEPTH=9000
\end{consoleverb}
\vspace{0.1in}

\noindent
Verity that the effect is apparent in both the \app{uPokeDB} and
\app{uXMS} output. Then try poking the following to the same
variable:

\vspace{0.1in}
\begin{consoleverb}
$ uPokeDB mission.moos DEPTH=shallow
\end{consoleverb}
\vspace{0.1in}

\noindent
Notice that the poke is ignored, apparent in both the \app{uPokeDB}
and \app{uXMS} output. This is not because MOOS somehow knows anything
about legal values for the variable \mvar{DEPTH}. This is because
MOOS variables are either of type \var{string} or \var{double}, and
the variable type is determined by the first publication. If the
first poke had the value \var{"shallow"}, it would have been accepted.

\vspace{0.1in}
\noindent
{\bf Step 3:} Try poking the variable \mvar{DB\_UPTIME}. This is the
number of seconds that the MOOSDB has been running. Notice it is already
in the \app{uXMS} output, with regular updates posted by the MOOSDB
app itself. What happens when another app like \app{uPokeDB} writes
to it?

\vspace{0.1in}
\begin{consoleverb}
$ uPokeDB mission.moos DB_UPTIME=50
\end{consoleverb}
\vspace{0.1in}

\noindent
After the poke, the value of 50 should be evident in the output of the
\app{uXMS} window briefly. And the source of the value should show
that the value of 50 came from the \app{uPokeDB} app. Notice that soon
it returns to the values published by the MOOSDB. Multiple apps can
publish to any variable. MOOS does not prevent this. However, the
source of the value is also always known. Any subscriber can choose to
ignore mail postings if they are not posted by a certain app if the
the subscribing app choose to listen to only a certain source.

%=======================================================================
\subsection{Exercise 3: Repeat on the AUV Training Kit (self checkoff)}

In this exercise the goal is to repeat the steps from the previous
exercise, on the SB2 training kit rather than your laptop.

\vspace{0.1in}
\noindent
{\bf Step 1:} Ensure there are three open terminal windows on the laptop,
and in each terminal, log into the training kit. This assumes your
training kit is connected by Ethernet cable and the training kit has
the IP address below. To log in:

\vspace{0.1in}
\begin{consoleverb}
$ ssh seabeaver-raspi@10.42.0.5
\end{consoleverb}
\vspace{0.1in}

\noindent
For each of the three terminal windows, log into the training kit.

\vspace{0.1in}
\noindent
{\bf Step 2:} In one of the terminal windows where you are logged
onto the training kit, create a \var{mission.moos} file as before
with the contents:

\begin{consoleverb}
ServerHost = localhost
ServerPort = 9005
Community  = alpha
\end{consoleverb}

\noindent
{\bf Step 3:} Repeat the actions of the previous exercise with the
below three commands in each of the terminal windows. Make sure
each of the below commands is invoked in the directory with the
newly created \var{mission.moos} file:

\begin{consoleverb}
$ MOOSDB mission.moos                      (in terminal one)
$ uXMS mission.moos --all --show=source    (in terminal two)
$ uPokeDB mission.moos DEPTH=50            (in terminal three)
\end{consoleverb}
\vspace{0.1in}

%=======================================================================
\section{Concepts II: Autonomy}
%=======================================================================

The {\em Autonomous} in AUVs is the focus here. The ability of an AUV
to autonomous make decisions about its own trajectory is what
distinguishes an AUV from an ROV (remotely operated,
tethered). Autonomy decisions are deeply tied to the goals of the
mission, sensors on board, the physical mobility limitations of the
vehicle, and inter-vehicle messages if the AUV is equipped with
underwater communications.

%=======================================================================
\subsection{Sense-Plan-Act}
%=======================================================================

An AUV is a type of robot and virtually all robots at a high enough
level can be described as conforming to a sense-plan-act loop like
that shown in Figure \ref{fig_spa}.

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=0.29\textwidth]{figures/spa.png}
\caption{Sense-Plan-Act loop for autonomous robots.}
\label{fig_spa}
\end{figure}

\vspace{0.1in}
\noindent
The robot repeatedly assesses the world through its set of sensors,
and incoming communications, and determines a course of action. The
course of action is a set of decisions concerning the robot direction,
speed (and depth for AUVs). These decisions are converted into
actuator actions by control software that converts the direction,
speed and depth into rudder position, propeller speed, and depth
actuators. Then the whole loop repeats.

\vspace{0.1in}
\noindent
A further distinction can be made within the "plan" box. We
distinguish a {\em plan} to be a sequence of states, such as waypoints
in the water, over a period of time. We regard a {\em decision} as
choice for direction, speed, or depth made in service of execution of
a plan, perhaps with momentary modifications for other
considerations outside the plan, such as collision or obstacle
avoidance. We regard an {\em action} as a control setting in service
of achieving a heading, speed or depth decision. The distinction is
shown in Figure \ref{fig_spa2}.

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=0.49\textwidth]{figures/spa2.png}
\caption{Sense-Decide-Act loop for autonomous robots.}
\label{fig_spa2}
\end{figure}


%=======================================================================
\subsection{Sense-Decide-Act for an AUV}

On an AUV the sense-decide-act loop still applies at a certain
level. But how does the notion of a "loop" play out in a
publish-subscribe architecture like MOOS, especially since MOOS apps
are all talking through a central MOOSDB in an asynchronous manner.
In Figure \ref{fig_spa_auv} below, the sense-decide-act loop is
stretched out a bit and conveyed also in a MOOS structure. 

\begin{figure}[H]
\centering
\includegraphics[width=0.56\textwidth]{figures/spa_auv.png}
\caption{Sense-Plan-Act loop for autonomous robots. The numbers and
  directions of the arrows imply a flow of information, however each
  stage may be running at much different frequencies in terms of
  subscription, calculation and publication of information.}
\label{fig_spa_auv}
\end{figure}

\noindent
Recall that MOOS processes operate asynchronously. Even if they were
all running at the same frequency, they should always be considered as
asynchronous - there are no strict timing guarantees. In the processes
in Figure \ref{fig_spa_auv}, a few observations can be made regarding
timing. First, we can safely assume the frequency of the controller
apps, talking directly to the hardware actuators, is not going to be
faster than the output of the controller. A controller on an AUV is
likely to run about 10-40 Hz. The frequency of the helm is usually in
the range of 1-4 Hz, with 4 being more typical. Certainly the helm
will not run faster than the rate of change coming from the sensors.
There are usually multiple AUV sensors, both for AUV position
navigation, and detection of external objects, or environmental
quality sensors. Certain sets of sensors, especially for navigation,
will be process by a sensor fusion app before the helm uses such
information.

%=======================================================================
\subsection{Sense-Decide-Act for the Alpha Mission}

The sense-decide-act loop can be found in the Alpha mission and this
is explored here. Recall the Alpha mission is the first mission
recommended to run after downloading and installing MOOS-IvP on your
machine. It is launched with:

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp/ivp/missions/s1_alpha        (navigate to mission folder)
  $ ./launch.sh 10                           (launch with time warp 10)
\end{consoleverb}
\vspace{0.1in}

\noindent
It looks like:

\begin{figure}[H]
\centering
\includegraphics[width=0.72\textwidth]{figures/alpha.png}
\caption{{\bf The Alpha Mission}: A simple single vehicle mission
  traversing a set of five waypoints. The highlighted sub-window on
  the left indicates the set of MOOS apps running during this
  mission.}
\label{fig_alpha}
\end{figure}

\noindent
The set of control windows on the left show (a) the set of vehicles
running in the mission, only "alpha" in this case (b) the set of MOOS
apps participating in the mission, in the upper right blue window, and
(c) the "engineering" information related to the selected application,
\app{pRealm} in this case.

\noindent
The primary apps involved in this mission are shown in Figure
\ref{fig_alpha_pub_sub} below. First, note that this mission is
started with two configuration files, \var{alpha.moos} and
\var{alpha.bhv}. For now just know that the \var{.moos} file names
the handful of apps to run in this mission, and the \var{.bhv} file
configures the helm, which in this example includes the five waypoints
to be traversed. 

\begin{figure}[H]
\centering
\includegraphics[width=0.72\textwidth]{figures/alpha_pub_sub.png}
\caption{{\bf The Alpha Mission}: A simple single vehicle mission
  traversing a set of five waypoints. The highlighted sub-window on
  the left indicates the set of MOOS apps running during this
  mission.}
\label{fig_alpha_pub_sub}
\end{figure}

\noindent
To find the sense-decide-act loop in this mission consider the
sequence starting with the helm:

\begin{packed_itemize}
\item The helm, \app{pHelmIvP} is configured with a set of waypoints
  from the \var{alpha.bhv} configuration file. The helm "senses" its
  own position through the receipt of the \mvar{NODE\_REPORT} message.
  It determines a heading and speed relative to its current position
  and the next waypoint, and publishes \mvar{DESIRED\_HEADING}
  and \mvar{DESIRED\_SPEED}.
\item The PID controller, \app{pMarinePID}, the controller compares
  the current heading and speed against the desired heading and speed
  and publishes \mvar{DESIRED\_RUDDER} and \mvar{DESIRED\_THRUST} to
  bring the desired values closer to the actual values. The actual
  current heading and speed, in the field are obtained from navigation
  sensors, and in simulation are obtained from simulator output.
\item The simulator, \app{uSimMarine}, converts the previous vehicle
  position, heading and speed into a new updated position heading and
  speed based on the current actuator values. The "nav solution" is
  in the form of \mvar{NAV\_X}, \mvar{NAV\_Y}, \mvar{NAV\_HEADING},
  and \mvar{NAV\_SPEED}.
\item The node reporter, \app{pNodeReporter}, subscribes to the nav
  solution variables, and packages a single string summary in the form
  of a \mvar{NODE\_REPORT} published. The node report is then used
  for the next iteration of the loop. 
\end{packed_itemize}

\noindent
It is worth pointing out again that these apps to not run all at the
same frequency. The \mvar{NODE\_REPORT} variable is also read by the
\app{pMarineViewer} GUI, to allow the vehicle position to be updated
on the screen.

\noindent
The other two apps running in this mission are \app{pRealm} and
\app{uProcessWatch}. The latter monitors the list of expected apps
and will post a warning if one disappears. The former, \app{pRealm}
is an app that summarizes the publications and subscriptions for
each app for debugging support. 

%=======================================================================
\section{Exercises II: Autonomy}
%=======================================================================

In the below exercises we will experiment with the Alpha mission
simulation on the course laptop, and explore the the publish-subscribe
interface of the apps involved, and methods for affecting change
into the simulation.

%=======================================================================
\subsection{Exercises 4: Interjecting Autonomy Commands}

In this exercise the goal is to explore methods for interjecting
autonomy commands into a running simulation, as well as methods
for scoping MOOS variables during a mission.

\vspace{0.1in}
\noindent
{\bf Step 1:} Navigate to the Alpha mission and launch with time warp 5.

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp/ivp/mission/s1_alpha
  $ ./launch.sh 5
\end{consoleverb}
\vspace{0.1in}

\begin{figure}[H]
\centering
\includegraphics[width=0.72\textwidth]{figures/pmv_return.png}
\caption{{\bf The Alpha Mission}: The viewer is configured to scope on
  the single MOOS variable \mvar{RETURN}. The \var{Return} button
  is configured to set this variable to \var{true} when clicked.
  mission.}
\label{fig_alpha_pub_sub}
\end{figure}

\noindent
Note the bottom most field in the viewer is field for scoping a single
MOOS variable. In this mission, the viewer is configured on startup to
scope on the MOOS variable \mvar{RETURN}. Note that it is set to
\var{false} at the outset. If you hover the mouse over the \var{RETURN}
button (or any button), you will see what value is poked to the MOOSDB
when the button is pressed. 

\vspace{0.1in}
\noindent
{\bf Step 2:} Launch the mission by hitting the \var{DEPLOY} button.

\noindent
Hover the mouse over the deploy button to see that this button
publishes \mvar{DEPLOY} to \var{true} and
\mvar{MISSION\_MANUAL\_OVERRIDE} to \var{false} and \mvar{RETURN} to
\var{false}. Pressing the \var{DEPLOY} button results in all three
values being published. Try repeatedly hitting the \var{DEPLOY} and
\var{RETURN} buttons to see the vehicle toggle between two modes.

\vspace{0.1in}
\noindent
{\bf Step 3:} In the \app{pMarineViewer} window, type the \var{'a'} key
to toggle between the blue and yellow information panels on the left.

\noindent
The yellow panels are called "realmcast" panels. Click on the
\app{pHelmIvP} menu item in the upper right hand panel. In the main
bottom yellow panel there are two tables, the top listing all the
variables currently subscribed for by the helm, and the bottom are all
the MOOS variables published by the helm. You can change the text size
if you want by selecting options in the \var{InfoCasting} pull-down
menu.

\vspace{0.1in}
\noindent
{\bf Step 4:} Note three of the variables subscribed for by the helm
are \mvar{DEPLOY}, \mvar{RETURN}, and \mvar{MOOS\_MANUAL\_OVERRIDE}.
Note the current values. Try hitting the \var{DEPLOY} and \var{RETURN}
buttons again and notice the change of values. Not also that the "source"
of the variable is list as \app{pMarineViewer}.

\vspace{0.1in}
\noindent
{\bf Step 4:} Note three of the variables subscribed for by the helm
are \mvar{DEPLOY}, \mvar{RETURN}, and \mvar{MOOS\_MANUAL\_OVERRIDE}.
Note the current values. Try hitting the \var{DEPLOY} and \var{RETURN}
buttons again and notice the change of values. Not also that the "source"
of the variable is list as \app{pMarineViewer}.

\vspace{0.1in}
\noindent
{\bf Step 5:} Assuming the mission is still running, in a separate
terminal window, navigate again to the mission folder.

\noindent
Try using \app{uPokeDB} to emulate the job of the \var{RETURN} button.

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp/ivp/missions/s1_alpha
  $ uPokeDB alpha.moos++  RETURN=true
\end{consoleverb}
\vspace{0.1in}

\noindent
Note that we use the \var{alpha.moos++} file instead of
\var{alpha.moos}. They are the same except the time warp in the former
is set to 5, like the rest of the mission when launched. Note the
value of the \mvar{RETURN} value changing in the realmcast window, and
notice the source of the current value will be \app{uPokeDB} after the
poke. You can also try poking \mvar{RETURN} to \var{false} and the
vehicle should resume its original path again.


%\begin{packed_itemize}
%\item AUV simulation completely on the laptop 
%\item AUV simulation on the AUV connected to laptop
%\item Field deployment of an AUV
%\end{packed_itemize}




\end{document}

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