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


%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 4 - 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 25th, 2021}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Henrik Schmidt, henrik@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

%===================================================================
\newpage
\section{Preparations for the Next Lab - Prime Factorization}
%===================================================================

The next lab involves the writing of new MOOS application, considerably
more involved than the \app{pOdometry} exercise. It is best approached
in successive incremental stages and our objective is to lay out the
stages so each is readily digestible. In this lab, you gained experience
in:

\begin{packed_itemize}
\item Acquiring your own software \var{moos-ivp-extend} software tree
\item Generating a new MOOS app from template generate by a script
\item Writing your first app, \app{pOdometry}, accepting and receiving mail
\item Augmenting your \var{moos-ivp-extend} tree with your new app
\item Using your new app in an actual mission to influence a vehicle
\item Putting your whole tree under version control and making it accessible
  to others.  
\end{packed_itemize}

\vspace{0.1in}
\noindent
The next lab builds on the above experience to focus on a new MOOS app with
more complexity.

%===================================================================
\subsection{Overview of the pPrimeFactor MOOS App}

This new app will be designed to accept a stream of numbers as
incoming mail, and calculate its prime factors, returning the list of
prime factors in an outgoing mail message. The challenge will be in
handling very large numbers of say twenty digits. In some cases
factorization will be quick, and some cases it may take several seconds.

The challenge will be to design your app such that it does not {\em
  block} on the large number. In other words, the app should ingest
its incoming mail, augmenting its to-do list, and perform work on this
during its \var{Iterate()} loop. Some work will complete, resulting in
outgoing posted mail. Other work, on larger numbers, may not yet
complete in a given iteration, and will need to be resumed on the next
iteration.

\vspace{0.1in}
\noindent
Below are a few initial steps to provide a good start to the next lab.

%===================================================================
\subsection{Create the New App, Augment Your Build Tree}

The first steps in the Prime Factors lab will be the same as this lab.

\begin{packed_itemize}
\item Generate a new app template using \var{GenMOOSApp}, as described above
  in Section \ref{sec_gen_moosapp}. Be sure to call it \app{pPrimeFactor}.
\item Add your \app{pPrimeFactor} app to the build tree, as described above
  for your \app{pOdometry} app in Section \ref{sec_add_bld}.
\item Verify that it builds and is in your shell path. See Section
  \ref{sec_path}
\end{packed_itemize}

%===================================================================
\subsection{Augment Your App to Accept and Process Numerical Entries}

A good first step is to begin to edit your \app{pPrimeFactor} MOOS app
to accept numerical input. Pick an incoming variable, say
\mvar{NUM\_VALUE}. Augment your \var{OnNewMail()} function to handle
this input. As a first step, you can simply determine if the number
is odd or even, and immediately post the result. For now you can do this
all in \var{OnNewMail()}, leaving your \var{Iterate()} method empty. The
result should be posted as a string, with the original number, and the
"odd/even" evaluation. For example:

\vspace{0.1in}
\noindent
\var{NUM\_RESULT = "37,odd"}

\vspace{0.1in}
\noindent
To test this, launch your new app in a simple mission (\var{.moos})
file, of your own making. This will just launch a \app{MOOSDB} and
your \app{pOdometry} app. In two seperate terminal windows, launch
a \app{uXMS} scope, and use the second window for poking the
\app{MOOSDB}

\vspace{0.1in}
\begin{consoleverb}
$ uXMS myfile.moos NUM_VALUE NUM_RESULT
\end{consoleverb}
\vspace{0.1in}

\noindent
Then in the other window:

\vspace{0.1in}
\begin{consoleverb}
$ uPokeDB myfile.moos NUM_VALUE=37
$ uPokeDB myfile.moos NUM_VALUE=22
\end{consoleverb}
\vspace{0.1in}

\noindent
Verify it's all working in your scope window.

%===================================================================
\subsection{Augment Your Testing to use uTimerScript}

In this next step, use \var{uTimerScript} to test your \app{pPrimeFactor}
app rather than manually poking the MOOSDB with \app{uPokeDB}. You will
need to add a \app{uTimerScript} configuration block to your mission file.

\vspace{0.1in}
\noindent
The \app{uTimerScript} app was introduced in Lab 3, and the full documentation
is on line. The goal here is to repeatedly post about 10-20 numbers. By setting
it to repeat, it can just be active upon the mission launch. I recommend about
a half second between posts in by your script.

\vspace{0.1in}
\noindent
For starters, just create a script with a fixed set of numbers repeatedly posted.
As a bonus, use the \app{uTimerScript} utility to repeatedly generate
random numbers. 

\vspace{0.1in}
\noindent
As before, verify with \app{uXMS} open in another terminal to verify that
your app is working properly on these auto-generated values.

%===================================================================
\subsection{Handle your Work Inside the Iterate Method}

The next step in developing your \app{pPrimeFactor} app is to handle
your mail by creating a C++ list of numbers. In your \var{OnNewMail()}
function, don't do any work determining the even or odd nature of your
incoming numbers. And don't post mail from within your
\var{OnNewMail()} method.  In the mail loop, just build a C++ list of
received mail. You may need to read up a bit on C++ lists. It is a
doubly linked list, meaning you can access from the beginning, or the
end of the list.  For now, in your mail function, push new numbers
onto the beginning of the list.

\vspace{0.1in}
\noindent
Since this list will need to be accessed by \var{OnNewMail()} and your
\app{Iterate()} loop, it should be a member variable of your
\var{PrimeFactor} class definition. Declare it in your app's header
file.

\vspace{0.1in}
\noindent
In your \var{Iterate()} loop, access the list by repeatedly popping a
value off the end of the list, determine if it is even or odd, and post
as before. At the end of each \var{Iterate()} loop, the list should be
empty.

\vspace{0.1in}
\noindent
If you get this far on the \app{pPrimeFactor} app, you'll be in great shape
at the start of the next lab!!

%===================================================================
\subsection{A C++ Refresher on the STL List Data Structure}

The C++ Standard Template Library (STL) contains the very usful {\em
  list} data structure. Lists are convenient when we want to add and
remove items from either end, or from in the middle of the list. Other
data structures like the STL vector for example, wouldn't be
appropriate in this case.

\vspace{0.1in}

\noindent
There are a few basic things you'll want to do with a list:

\begin{packed_itemize}
\item Add and remove items (from either end) 
\item Iterate through the list, operating on each element
\item Remove an item not at either the beginning or end
\item Work with a reference to a list element vs. a copy of a element
\end{packed_itemize}

\vspace{0.1in}
\noindent
We review each of the above here. As an aside, you have already touched
the idea of iterating through a list in the MOOS \var{OnNewMail()} and
\var{OnStartUp()} methods. The set of mail messages and the set of
configuration parameters are actually STL lists of STL strings.

%---------------------------------------------------------------------
\subsubsection*{Review of Simple Usage of a List of Strings}

The first snippet below just reminds us how to declare, populate and
iterate through an STL list of strings:

\vspace{0.12in}
\begin{fileverb}
   1  #include &lt;list&gt;
   2  #include &lt;string&gt;
   3  
   4  list&lt;string&gt; my_strings;
   5  my_strings.push_back("apples");
   6  my_strings.push_back("watermelons");
   7  my_strings.push_back("pears");
   8  my_strings.push_back("blackberry");
   9  
  10  list&lt;string&gt;::iterator p;
  11  for(p=my_strings.begin(); p!=my_strings.end(); p++) {
  12     string str = *p;
  13     if(str.length() &gt; 6)
  14       cout &lt;&lt; "Long fruit name: " &lt;&lt; str &lt;&lt; endl;
  15  }
  16  cout &lt;&lt; "List size: " &lt;&lt; my_strings.size() &lt;&lt; endl;
\end{fileverb}
\vspace{0.12in}

\noindent
The code above does not modify the list once it's been built, but detects
list entries with string length longer than six characters. It should
produce the output:

\vspace{0.12in}
\begin{consoleverb}
 Long fruit name: watermelons
 Long fruit name: blackberry
 List size: 4
\end{consoleverb}


%----------------------------------------------------------------------
\subsubsection*{Removing a List Item While Iterating Through the List}

Although the documentation for lists is quite good in most C++ text
books or at \urlx{cplusplus.com}, the syntax for deletion of list
items {\em from the middle of the list, while iterating through} may
be a bit tricky so we cover it here.  The next code segment is similar
to the above example, but this time it {\em removes} elements of the
list with string length greater than six:

\vspace{0.12in}
\footnotesize
\begin{fileverb}
   1  #include &lt;list&gt;
   2  #include &lt;string&gt;
   3  
   4  list&lt;string&gt; my_strings;
   5  my_strings.push_back("apples");
   6  my_strings.push_back("watermelons");
   7  my_strings.push_back("pears");
   8  my_strings.push_back("blackberry");9
   9  
  10  list&lt;string&gt;::iterator p;
  11  for(p=my_strings.begin(); p!=my_strings.end(); ) {
  12     string str = *p;
  13     if(str.length() &gt; 6) {
  14        cout &lt;&lt; "Removing long fruit: " &lt;&lt; str &lt;&lt; endl;
  15        p = my_strings.erase(p);
  16     }
  17     else
  18        ++p;
  29  }
  20  cout &lt;&lt; "List size: " &lt;&lt; my_strings.size() &lt;&lt; endl;
\end{fileverb}
\normalsize
\vspace{0.12in}

\noindent
Note how line 11 has changed between the two listings. The \var{p++}
in the first listing is left out in the second listing. The iterator
instead is incremented on line 18. This code should produce the below
output.

\vspace{0.12in}
\footnotesize
\begin{consoleverb}
 Removing long fruit: watermelons
 Removing long fruit: blackberry
 List size: 2
\end{consoleverb}
\normalsize

%----------------------------------------------------------------------
\subsubsection*{Accessing a Reference to a List Element vs a Copy}

In the above two examples, on line 12, the first thing done while
iterating through the list of strings is to derefernce the contents of 
the iterator. The line:

\vspace{0.1in}
\begin{fileverb}
  string str = *p;
\end{fileverb}
\vspace{0.1in}

\noindent
makes a {\em copy} of the string in the list. Let's suppose we wanted 
modify the strings in the list. For example we may want to go through 
the list of strings and truncate to ten characters, all strings greater
than ten characters. You might be inclined to try something like:

\vspace{0.1in}
\begin{fileverb}
 list&lt;string&gt;::iterator p;
 for(p=my_strings.begin(); p!=my_strings.end(); ) {
    string str = *p;
    if(str.length() &gt; 10) {
      str = str.substr(0,10);
    }
 }
\end{fileverb}
\vspace{0.1in}

\noindent
The above will not work because we truncated a {\em copy} of the string
in the list. This original list of strings may still contain strings
of length greater than ten. You instead need to use the line:

\vspace{0.1in}
\begin{fileverb}
 string&amp; str = *p;
\end{fileverb}
\vspace{0.1in}

\noindent 
The extra ampersand now means that \var{str} {\em is} the element/string
in the list, not a copy of it.


\end{document}



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