Embed Size (px)
Citation preview
Lab 4 - Introduction to MOOS Programming2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications
February 13th, 2020
Michael Benjamin, [email protected] Schmidt, [email protected]
Department of Mechanical EngineeringMIT, Cambridge MA 02139
1 Overview and Objectives 31.1 Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 MOOS, MOOS-IvP and Your Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 More MOOS / MOOS-IvP Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 The MOOS Application Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 Handy Functions Defined on MOOSMsg (MOOS mail) . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Downloading and Building the moos-ivp-extend Tree 72.1 Assignment 1 (self check off) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.2 A Peek Under the Hood . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3 Build Your First MOOS App - An Odometry MOOS App 93.1 Generating a Template App and Augmenting the Build System . . . . . . . . . . . . . . . . . . . . . . 93.2 Assignment 2: (self check off) Verify Skeleton pOdometry has Built . . . . . . . . . . . . . . . . . . . . 103.3 Writing the Odometry MOOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.4 Use Your pOdometry app in the Alder mission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.5 Assignment 3 (check off) Verify Your pOdometry Works . . . . . . . . . . . . . . . . . . . . . . . . . . 133.6 Assignment 4 (check off) Convert pOdometry to an AppCasting MOOSApp . . . . . . . . . . . . . . . 14
4 Due Date and Grading Criteria 144.1 Due Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.2 Grading Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.3 Submitting Instructions for Lab 04 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.4 Submitting 2.680 Lab Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5 Preparations for the Next Lab - Prime Factorization 195.1 Overview of the pPrimeFactor MOOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.2 Create the New App, Augment Your Build Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.3 Augment Your App to Accept and Process Numerical Entries . . . . . . . . . . . . . . . . . . . . . . . 195.4 Augment Your Testing to use uTimerScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205.5 Handle your Work Inside the Iterate Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205.6 A C++ Refresher on the STL List Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1
2
1 Overview and Objectives
In this lab we will produce our own MOOS applications. We begin by downloading an exampleapplication complete with it’s own build structure. We proceed by making our first simple MOOSapp emphasizing the usage of the basic MOOS components. This is followed by a couple morecomplex application exercises.
This lab contains our first hand-in assignment. Although later in the class we will be working withpartners, in this lab, all work should be done by individuals. When students post questions ofgeneral relevance, we will make that information available to everyone.
• The MOOS Application Structure (Iterate, OnNewMail, OnStartUp Methods)
• The MOOS Message Structure
• Downloading and Building the moos-ivp-extend tree
• Build Your First MOOS App - An Odometry App
• Build Your Second MOOS App - Prime Factorization App
1.1 Preliminaries
This lab does assume that you have a working MOOS-IvP tree checked out and installed on yourcomputer. To verify this make sure that the following executables are built and findable in yourshell path:
$ which MOOSDB
/Users/you/moos-ivp/bin/MOOSDB
$ which pHelmIvP
/Users/you/moos-ivp/bin/pHelmIvP
If unsuccessful with the above, return to the steps in Lab 1:
http://oceanai.mit.edu/ivpman/labs/machine_setup
1.2 MOOS, MOOS-IvP and Your Applications
In the previous lab we discussed the relationship between MOOS and MOOS-IvP. The MOOS treeis a body of software distributed as part of the MOOS-IvP tree as depicted in Figure 1. MOOS-IvPprovides additional MOOS applications, including the IvP Helm behavior-based architecture, andhas C++ build dependencies on the MOOS libraries. Today the focus is on building additionalMOOS applications. Your MOOS apps will have a build dependency on the MOOS libraries, and youmay choose to utilize libraries in the MOOS-IvP tree. We start by downloading the 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 issuesfor now. You likely have already downloaded and built this tree if you finished the last part of theprevious lab.
3
Figure 1: Nested Repositories: The MOOS-IvP tree contains the Oxford MOOS tree and additional modules fromMIT including the Helm architecture, Helm behaviors and further MOOS applications. The set of modules may beexpanded with user third-party applications or behaviors.
1.3 More MOOS / MOOS-IvP Resources
We will only just touch the MOOS programming basics today. A few further resources are worthmentioning for following up this lab with your own exploration.
• See the slides from the today’s class which give a bit more background into MOOS andMOOS-IvP related to marine robotics.http://oceanai.mit.edu/2.680/docs/2.680-04-moos_programming_2020.pdf
• The Programming with MOOS documentation.http://oceanai.mit.edu/2.680/docs/ProgrammingWithMOOS.pdf
• The moos-ivp.org website documentation.http://oceanai.mit.edu/ivpman
1.4 The MOOS Application Structure
The main idea explored today is the notion and structure of a MOOS application. We know fromthe last lab that MOOS apps publish, subscribe for, and handle mail passed from one application toanother through the MOOSDB. In the last lab we worked with existing MOOS apps, only modifyingtheir functionality through configuration options provided by the application author. Even withoutmodifying the code of existing MOOS apps there are many ways to configure a system for uniquedomains. However, the real power of MOOS comes from the fact that no application is sacred. Ifyou don’t like what it does (or doesn’t) do, you are free copy and rename it, and modify the code toyour satisfaction. Or you can just build your own application from scratch. This is the focus oftoday’s lab.
4
The key components to keep in mind in today’s lab are shown in Figure 2 below. All MOOSapps 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.
Figure 2: The MOOSApp Key Functions: All MOOS apps are a subclass of the MOOSApp superclass. Develop-ment mostly boils down to overriding the three functions below with the particulars of one’s own liking.
Documentation Conventions
To help distinguish between MOOS variables, MOOS configuration parameters, and behaviorconfiguration parameters, we will use the following conventions:
• MOOS variables are rendered in green, such as IVPHELM STATE, as well as postings to theMOOSDB, such as DEPLOY=true.
• MOOS configuration parameters are rendered in blue, such as AppTick=10 and verbose=true.Except for AppTick and CommsTick, configuration parameters are generally lower case.
• MOOS apps and executables generally, are rendered in magenta as with MOOSDB and GenMOOSApp.
• IvP Helm Behavior configuration parameters are rendered in brown, such as priority=100 andendflag=RETURN=true.
This convention closely follows the convention used in the helm documentation.
1.5 Handy Functions Defined on MOOSMsg (MOOS mail)
The below methods are defined on an instance of MOOSMsg. Typically we are dealing with MOOSmessages in the OnNewMail() loop of an application. Besides knowing the name of the variable, youmay also want to know (a) what is its value, (b) by whom or which app was it posted, (c) when wasit posted, (d) is its value of type string or double, and so on.
In our pXRelayTest example app, we only call msg.GetKey() in Relayer.cpp, but all the belowmethods are available for getting the message fields. (See today’s lecture notes for a description of a
5
MOOS Message.) This information is probably in the MOOS documentation, but is repeated herefor convenience.
// 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();
Later on in this lab you will see that we provide a template for generating the skeleton code of anew MOOS app. This is done using the GenMOOSApp script. This skeleton code will generate thefollowing OnNewMail() method:
6
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);
}
Note all the typical function calls you may want to make on an incoming MOOS message areright there, commented out to start with, but ready to use if you need them in your application.(Everything between the if 0 and endif is ignored by the compiler, so these lines have the sameeffect as comment lines.)
2 Downloading and Building the moos-ivp-extend Tree
The first step of today’s lab is to download the moos-ivp-extend tree, if you haven’t already. Thistree may be regarded as a template for building your own set of MOOS applications or (later on)Helm behaviors. It contains a single MOOS app and a single Helm behavior, but more importantlya file structure and CMake C++ build system for building the source code. Eventually you willwant to understand more about GNU Make and CMake files. But for now, by starting with aworking template, the addition of new MOOS applications to the build structure is a simple matterof editing one or two files.
Your goals in this part are:
1. From a terminal window download a copy of the moos-ivp-extend tree. Note: Download thistree so it is in the same folder that you downloaded the moos-ivp tree. Download with thefollowing svn command:
$ svn co https://oceanai.mit.edu/svn/moos-ivp-extend/trunk moos-ivp-extend
Verify that you can build this tree by:
$ cd moos-ivp-extend
$ ./build.sh
The build should produce an executable, pXRelayTest, in moos-ivp-extend/bin/.
7
2. Re-name your moos-ivp-extend tree to something indicative of your name, e.g., moos-ivp-janedoe.(However, we may continue to refer to this tree generically as moos-ivp-extend).
3. Add the following directory to your shell path: moos-ivp-janedoe/bin
4. The pXRelayTest application built in this tree is very close to the pXRelay app distributedwith the moos-ivp tree. Modify your xrelay.moos mission from Lab 3 to use the pXRelayTest
application instead.
2.1 Assignment 1 (self check off)
Verify that you have successfully downloaded and built the moos-ivp-extend tree, and that thebinaries of this tree are findable in your shell path. Verify with the following:
$ which pXRelayTest
$ /home/you/moos-ivp-you/bin/pXRelayTest
If the which function returns no value, then either the binary pXRelayTest was not built or youhaven’t successfully augmented your shell path. First check to ensure it was built by examining thecontents of moos-ivp-you/bin/. If pXRelayTest is there, then double check that you have properlyaugmented your shell path. If need be, return to the help page:
http://oceanai.mit.edu/ivpman/help/cmdline_augment_shell_path/
You can also display your shell’s current path with:
$ echo $PATH
If you don’t see /home/you/moos-ivp-ivp/bin in the colon-separated list of locations constitutingyour shell path, then you are not done.
2.2 A Peek Under the Hood
Before moving on to the next exercise, take a quick look at the Relayer MOOS app class definitionfrom this example. It is shown below and may also be found in moos-ivp-extend/src/pXRelayTest/.Note a couple things:
• The class declaration, on line 1, declares itself to be a subclass of CMOOSApp, the generalsuperclass of all MOOS apps.
• Our class overrides the three key virtual functions of the parent class, declared in lines 8-10.
• Coding convention: All member functions are declared before all member variables. OverriddenMOOSApp member functions are declared before subclass specific member functions.
• Coding convention: All member variables begin with m , to set them apart from locally declaredvariables in the code.
• Coding convention: All member variables protected. Setting member variables happensthrough a public member function, e.g., lines 14,15.
8
File Relayer.h
1 #include "MOOS/libMOOS/MOOSLib.h"
2 class Relayer : public CMOOSApp
3 {
4 public:
5 Relayer();
6 virtual ~Relayer() {};
7
8 bool OnStartUp(); // Overriding key virtual function
9 bool OnNewMail(MOOSMSG_LIST &NewMail); // Overriding key virtual function
10 bool Iterate(); // Overriding key virtual functionx
11
12 bool OnConnectToServer();
13 void RegisterVariables();
14
15 void setIncomingVar(std::string s) {m_incoming_var=s;}
16 void setOutgoingVar(std::string s) {m_outgoing_var=s;}
17
18 protected:
19 unsigned long int m_tally_recd;
20 unsigned long int m_tally_sent;
21 unsigned long int m_iterations;
22
23 std::string m_incoming_var;
24 std::string m_outgoing_var;
25 double m_start_time_postings;
26 double m_start_time_iterations;
27 };
3 Build Your First MOOS App - An Odometry MOOS App
The Focus of this section is on building your first MOOS App. Your goals are:
1. Learn how to generate a MOOS application from scratch using a template-generating script.
2. Learn how to add the new MOOS application to the build system.
3. Write your new MOOS app, pOdometry, to calculate the total distance traveled by the vehicle.
4. Test your MOOS app by using it in the Alder example mission to have the vehicle return aftertraveling 50 meters.
5. Convert your MOOS app into an AppCasting MOOS App.
3.1 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 fullapplication template. The resulting template should be buildable immediately without furthermodification, but will essentially do nothing meaningful until you add your own functionality.
3.1.1 Generate the MOOS App
To generate the new MOOS app, in a terminal window change directories to moos-ivp-extend/src/.From here you should be able to invoke the below command:
9
$ GenMOOSApp Odometry p "Jane Doe"
The above script, GenMOOSApp, should be in your shell path under moos-ivp/scripts/. You may needadd this directory to your shell path if you haven’t done so already. The above script invocationbuilds a new app called pOdometry. The third argument is your name. You can type GenMOOSApp -h
in the future to remind yourself.
3.1.2 Add Your Name
Always, always, always put your name at the top of your source code files! This is a good practicein general, but even more so in a class setting, or an open source environment where people aresharing code. It wouldn’t hurt to add the date and organization information too.
3.1.3 Add Your New Application to the Build System
Add your new app to the build system. Edit the file moos-ivp-extend/src/CMakeLists.txt and lookfor the line referring to pXRelayTest. Copy that as an example for your new app.
#==========================================================================
# List the subdirectories to build...
#==========================================================================
ADD_SUBDIRECTORY(lib_behaviors-test)
ADD_SUBDIRECTORY(pXRelayTest)
ADD_SUBDIRECTORY(pExampleApp)
ADD_SUBDIRECTORY(pOdometry) <-- Add your line here
3.2 Assignment 2: (self check off) Verify Skeleton pOdometry has Built
Go back and re-run your build script. Check to see that pOdometry has been built, and is in yourbin directory (e.g., moos-ivp-you/bin).
Verify that pOdometry is in your shell path with:
$ which pOdometry
$ /home/you/moos-ivp-you/bin/pOdometry
If the which function returns no value, then either the binary pXRelayTest was not built or youhaven’t successfully augmented your shell path. See above in Section 2.1 for tips on how to remedythe problem.
3.3 Writing the Odometry MOOS App
The goal of this step is to build a new simple MOOS application that calculates vehicle odometry.It will:
1. Register for the NAV X and NAV Y position of the vehicle.
2. Repeatedly read in the NAV X and NAV Y position of the vehicle.
10
3. Update the total distance traveled by calculating the distance between the present positionand the previous position.
4. Post the odometry information in the MOOS variable ODOMETRY DIST.
We will do this in your newly checked out moos-ivp-extend tree. Begin as follows:
• Edit Odometry.h to have six member variables:
bool m_first_reading;
double m_current_x;
double m_current_y;
double m_previous_x;
double m_previous_y;
double m_total_distance;
• Edit Odometry.cpp to initialize the above member variables, in the class constructor.
• Edit Odometry.cpp to register for NAV X and NAV Y.
• Edit the Odometry::OnNewMail() method to handle the updated navigation position. Setprevious x to current x, and current x to the new NAV X value. Same for Y.
• Edit the Odometry::Iterate() method to calculate the new distance. Handle the specialcase of the first navigation measurement. Post the total distance to the MOOS variableODOMETRY DIST.
• Verify that everything builds...
There is one common ”gotcha” in this lab. Keep in mind that the NAV X and the NAV Y variables arebeing published by the uSimMarine application. This application is running at 10Hz and producingon average 10 incoming mail messages for your pOdometry app. If your pOdometry app is running atthe default rate of 4Hz, then on average your app will have 2-3 incoming mail messages on eachiteration. If you find that your odometry calculations only reflect about half of the actual distancetravelled, reconsider how you are calculating the length of new legs.
3.4 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 touse the information to alter the mission behavior.
3.4.1 Running the Un-modified Alder Mission
First make sure that you can run the Alder mission. Try it:
$ cd moos-ivp-extend/missions/alder
$ pAntler --MOOSTimeWarp=10 alder.moos
It should look something like the video posted at:
11
Figure 3: The Alder mission.
video:(0:13): https://vimeo.com/80730664
3.4.2 Run the Alder Mission with pOdometry
Next we’ll add the pOdometry application to the mission and just verify it is generating the rightoutput. Do the following steps:
• Modify the Alder mission (moos-ivp-extend/missions/alder/alder.moos) to include pOdometry
at launch time by editing the Antler block in the alder.moos file.
• Add ODOMETRY DIST to the scope list in pMarineViewer. See the pMarineViewer documentationto see how to do this. It should look something like:
ProcessConfig = pMarineViewer
{
AppTick = 4
CommsTick = 4
...
scope = ODOMETRY_DIST // <-- Add this line
...
}
• Re-launch the mission. Now you should be able to see the odometry distance in the scopefield at the bottom of pMarineViewer. Does it look correct?
12
3.4.3 Modify the Alder Mission Using pOdometry
In the next step, we will modify the alder mission as follows. Instead of transiting to the waypointspecified in the waypoint behavior, the vehicle will return home after it has transited 50 meters. Wehaven’t covered the Helm yet in class, so some of this we’ll take on faith for now.
Take a look inside alder.bhv. This is where the helm is configured. The mission is comprised oftwo instances of a waypoint behavior. The first transits to a given point and is called waypt to point.It has two conditions, we’ll add a third:
//----------------------------------------------
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
}
The second waypoint behavior is designed to return after the first one completes. It also has twoconditions:
condition = RETURN = true
condition = DEPLOY = true
We’ll change that to:
condition = (RETURN = true) or (ODOMETRY_DIST >= 50)
condition = DEPLOY = true
3.5 Assignment 3 (check off) Verify Your pOdometry Works
After the above modifications, re-launch the mission. Demonstrate to one of the TAs that yourpOdometry works. It should look something like:
13
Figure 4: The Alder mission running with the pOdometry app.
video:(0:06): https://vimeo.com/80755512
3.6 Assignment 4 (check off) Convert pOdometry to an AppCasting MOOSApp
The last step will be to convert your pOdometry application to be appcast enabled. Follow theinstructions from today’s lecture notes, or read the documentation for enabling appcasting:
http://oceanai.mit.edu/ivpman/appcast_enable
The output of your appcast report (in the buildReport() function) should simply show the totaldistance traveled.
4 Due Date and Grading Criteria
4.1 Due Date
All MOOS apps described in this lab are due during lab Thursday Feb 20th, 2020. Apps will betested during lab, and source code is due to the graders at the beginning of the lab.
4.2 Grading Criteria
Grading will be based on
1. Implementation Credit (60%)
2. Code Organization (40%)
14
Full implementation credit for each application will given be based on whether or not you have metthe given specs.
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 healthyamount of constructive criticism in the first assignments. See the 9th and 10th C++ labs on thewebsite: ”C++ Coding Guidelines” and ”C++ Coding Style Guidelines”.
Unfinished assignments will be tested and accepted in the next lab. A 5% deduction will be appliedfor each lab that goes by unfinished.
4.3 Submitting Instructions for Lab 04
Lab 04 assignments should be submitted using the version control mechanism described below inSection 4.4. Your directory format should have the naming and file organization as indicated below:
moos-ivp-yourname/
src/
pOdometry
missions/
alder/
alder_lab4.moos
alder_lab4.bhv
lib/ (should be empty)
bin/ (should be empty)
build/ (should be empty)
build.sh (should be unchanged)
CMakeLists.txt (should be unchanged)
)
15
4.4 Submitting 2.680 Lab Assignments
Lab submissions for 2.680 will be done through a version control system such as SVN. Althoughthere are other ways to do this, e.g., via the MIT Stellar uploads, or Dropbox, we prefer SVN (orGit) for a couple reasons:
• When our labs begin to involve lab partner collaboration, you will need to access each other’scode.
• You will be required in this course to use a version control tool such as SVN that allowsmerges between two people’s work and allows one to revert to prior revisions of code.
• You won’t have access to DropBox on the robots. You will however be able to check out yourcode onto the robots with SVN or Git.
4.4.1 Submission Format
In this course, your lab assignments may be viewed as successive additions to the moos-ivp-extend
tree. Here you can insert new MOOS applications, Helm behaviors, autonomy missions, and ofcourse regular lab report write-ups or presentations.
The overall submission process will look like this:
• One time: Set up an SVN service account and upload your moos-ivp-johndoe tree.
• For each lab, develop and add to your moos-ivp-johndoe tree, and check in the changes.
• Declare to the 2.680 staff that you have finished your lab.
• 2.680 staff will grade the lab after checking out or updating your lab tree.
4.4.2 Step 1 (one time): Set up your Version Control Service
We recommend using an inexpensive service such as CloudForge detailed below for your versioncontrol service. You can use another service if you like, or use a git service such as GitHub. Mainlywe care only that we can grab a latest version of your tree from the web. CloudForge and SVN justseem the easiest and it’s free.
Alternatively if you would like us to set up an account for you on the MIT ”oceanai” server, wecan do that too. The only drawback is that you likely won’t have access to this server after theend of 2.680. We also view the use of a version control service to be a good practice in general forgraduate studies, not just 2.680 code, but all your valuable class projects, documents, and thesis.
(CloudForge Option) Set up your CloudForge account and set up a new project
• Create a new account on CloudForge or equivalent. See the help page on setting this up:http://oceanai.mit.edu/ivpman/help/svn_setup_your_own_repo.
• In CloudForge, once you have set up a new account, create a new project with SVN service asdescribed in the above help link.
• Make sure you follow the above steps to the end. The end result should be that you can checkout a newly created project from CloudForge, initially with nothing in it.
16
$ svn co https://YourCloudForgeAcct.svn.cloudforge.com/YourProjectName
Checked out revision 0.
$ cd YourProjectName
$ ls
(nothing)
(Oceanai Option) Set up an account on the oceanai server To use oceanai, you will needto (a) have an account set up on oceanai, and (b) create a tar file of your tree and send it to be setup. The tarfile is discussed below. To initiate an account on oceanai, let us know this is your choice,and provide us with a username. This username should ideally be the same as used on your laptopand on MIT Athena.
Prepare to upload your material
• Check out the moos-ivp-extend tree as a starting template. This is checked out from theclass oceanai.mit.edu server and you likely have done this aleady as the last step in Lab 3.Re-name it to something indicative of who you are, e.g., your Athena/MIT account name,moos-ivp-johndoe.
• You will need to prepare this tree for uploading to a different SVN server, the one you set upwith CloudForge or similar. All SVN trees contain ”meta-information” indicating where thetree was originally checked out from. You will need to remove this SVN meta informationfrom the tree you check out from the class server. To do this, remove the .svn/ directory inthe top level of this tree. "rm -rf ./.svn"
• IMPORTANT: Before you upload your moos-ivp-johndoe tree, remove any generated files.Don’t check in things that have been built as part of the build process. For example yourbuild/ and lib/ directories should be empty. Your bin/ directory should only have what wasin it originally. Your missions/ directory should not have log files. A virgin moos-ivp-extend
tree is less then a megabyte. Your checked in version shouldn’t be much bigger. You can usethe clean.sh script in the moos-ivp-extend directory as a shortcut for cleaning. But as yourdirectory evolves, this clean script may need to evolve too.
• CloudForge: Upload your moos-ivp-johndoe directory to your newly created project onCloudForge. If the CloudForge project name is YourProjectName and your local moos-ivp-extend tree is moos-ivp-johndoe, then just do the following:
$ mv moos-ivp-johndoe YourProjectName
$ cd YourProjectName
$ svn add moos-ivp-johndoe
$ svn commit -m "comment, e.g., initial setup"
• Oceanai: If you’re using the oceanai server, the send a tar file of your directory to me (mikerb).I will initiate a new tree by this name on the oceanai server and give you access. If you haven’tused tar before here’s the quick start (assuming you are in the directory containing yourmoos-ivp-johndoe tree:
$ tar cvf moos-ivp-johndoe.tar moos-ivp-johndo
$ ls
moos-ivp-johndoe/ moos-ivp-johndoe.tar
17
To untar the file back into directory form:
$ tar xvf moos-ivp-johndoe.tar (note the ’x’ replaces the ’c’)
4.4.3 Confirm it Works and Provide Access to 2.680 staff
• Confirm in a temporary directory that you can checkout this tree from CloudForge. Afterthis, only use this tree.
• Take note of the SVN URL and email it to the 2.680 staff. This should only need to be doneonce. Subsequent TA access will come by the TA entering his/her local copy of your tree andjust updating the tree from the server.
In CloudForge, you have the option of allowing access to your tree with a password, or without.Allowing access without a password is called ”anonymous access”. This is ok, but it seems thatCloudForge does not support anonymous read-only access. So if you allow anonymous access, otherscan check in changes to your tree. This may be ok for the class. It’s up to. If your tree does need apassword, you will need to let the TAs know what that password is.
4.4.4 Step 2 (each lab): Submit your 2.680 Lab Assignment
For each lab assignment, here’s what to do:
• Develop and test your code.
• Follow the requested naming conventions: If a particular MOOS module is part of theassignment, and we ask that you call it pFooBar, then please name if pFooBar.
• IMPORTANT: Make sure you have not checked in build-generated files, in bin/, lib/, orbuild/ directories. Or any log files in your missions/ directory.
• Check in your changes to the server. (Actually don’t wait until your done with the lab tocheck in changes. This is something you should be doing regularly as a way of backing upyour work.)
• Inform the 2.680 staff that you are done with you lab. Include the SVN revision number ofyour final check-in.
18
5 Preparations for the Next Lab - Prime Factorization
The next lab involves the writing of new MOOS application, considerably more involved than thepOdometry exercise. It is best approached in successive incremental stages and our objective is tolay out the stages so each is readily digestible. In this lab, you gained experience in:
• Acquiring your own software moos-ivp-extend software tree
• Generating a new MOOS app from template generate by a script
• Writing your first app, pOdometry, accepting and receiving mail
• Augmenting your moos-ivp-extend tree with your new app
• Using your new app in an actual mission to influence a vehicle
• Putting your whole tree under version control and making it accessible to others.
The next lab builds on the above experience to focus on a new MOOS app with more complexity.
5.1 Overview of the pPrimeFactor MOOS App
This new app will be designed to accept a stream of numbers as incoming mail, and calculate itsprime factors, returning the list of prime factors in an outgoing mail message. The challenge will bein handling very large numbers of say twenty digits. In some cases factorization will be quick, andsome cases it may take several seconds.
The challenge will be to design your app such that it does not block on the large number. Inother words, the app should ingest its incoming mail, augmenting its to-do list, and perform work onthis during its Iterate() loop. Some work will complete, resulting in outgoing posted mail. Otherwork, on larger numbers, may not yet complete in a given iteration, and will need to be resumed onthe next iteration.
Below are a few initial steps to provide a good start to the next lab.
5.2 Create the New App, Augment Your Build Tree
The first steps in the Prime Factors lab will be the same as this lab.
• Generate a new app template using GenMOOSApp, as described above in Section 3.1.1. Be sureto call it pPrimeFactor.
• Add your pPrimeFactor app to the build tree, as described above for your pOdometry app inSection 3.1.3.
• Verify that it builds and is in your shell path. See Section 3.2
5.3 Augment Your App to Accept and Process Numerical Entries
A good first step is to begin to edit your pPrimeFactor MOOS app to accept numerical input. Pickan incoming variable, say NUM VALUE. Augment your OnNewMail() function to handle this input. Asa first step, you can simply determine if the number is odd or even, and immediately post theresult. For now you can do this all in OnNewMail(), leaving your Iterate() method empty. Theresult should be posted as a string, with the original number, and the ”odd/even” evaluation. Forexample:
19
NUM RESULT = "37,odd"
To test this, launch your new app in a simple mission (.moos) file, of your own making. This willjust launch a MOOSDB and your pOdometry app. In two seperate terminal windows, launch a uXMS
scope, and use the second window for poking the MOOSDB
$ uXMS myfile.moos NUM_VALUE NUM_RESULT
Then in the other window:
$ uPokeDB myfile.moos NUM_VALUE=37
$ uPokeDB myfile.moos NUM_VALUE=22
Verify it’s all working in your scope window.
5.4 Augment Your Testing to use uTimerScript
In this next step, use uTimerScript to test your pPrimeFactor app rather than manually poking theMOOSDB with uPokeDB. You will need to add a uTimerScript configuration block to your missionfile.
The uTimerScript app was introduced in Lab 3, and the full documentation is on line. The goalhere is to repeatedly post about 10-20 numbers. By setting it to repeat, it can just be active uponthe mission launch. I recommend about a half second between posts in by your script.
For starters, just create a script with a fixed set of numbers repeatedly posted. As a bonus, use theuTimerScript utility to repeatedly generate random numbers.
As before, verify with uXMS open in another terminal to verify that your app is working properly onthese auto-generated values.
5.5 Handle your Work Inside the Iterate Method
The next step in developing your pPrimeFactor app is to handle your mail by creating a C++ listof numbers. In your OnNewMail() function, don’t do any work determining the even or odd natureof your incoming numbers. And don’t post mail from within your OnNewMail() method. In the mailloop, just build a C++ list of received mail. You may need to read up a bit on C++ lists. It is adoubly linked list, meaning you can access from the beginning, or the end of the list. For now, inyour mail function, push new numbers onto the beginning of the list.
Since this list will need to be accessed by OnNewMail() and your Iterate() loop, it should be amember variable of your PrimeFactor class definition. Declare it in your app’s header file.
In your Iterate() loop, access the list by repeatedly popping a value off the end of the list, determineif it is even or odd, and post as before. At the end of each Iterate() loop, the list should be empty.
If you get this far on the pPrimeFactor app, you’ll be in great shape at the start of the next lab!!
20
5.6 A C++ Refresher on the STL List Data Structure
The C++ Standard Template Library (STL) contains the very usful list data structure. Lists areconvenient when we want to add and remove items from either end, or from in the middle of thelist. Other data structures like the STL vector for example, wouldn’t be appropriate in this case.
There are a few basic things you’ll want to do with a list:
• Add and remove items (from either end)
• Iterate through the list, operating on each element
• Remove an item not at either the beginning or end
• Work with a reference to a list element vs. a copy of a element
We review each of the above here. As an aside, you have already touched the idea of iteratingthrough a list in the MOOS OnNewMail() and OnStartUp() methods. The set of mail messages andthe set of configuration parameters are actually STL lists of STL strings.
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 ofstrings:
1 #include <list>
2 #include <string>
3
4 list<string> 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<string>::iterator p;
11 for(p=my_strings.begin(); p!=my_strings.end(); p++) {
12 string str = *p;
13 if(str.length() > 6)
14 cout << "Long fruit name: " << str << endl;
15 }
16 cout << "List size: " << my_strings.size() << endl;
The code above does not modify the list once it’s been built, but detects list entries with stringlength longer than six characters. It should produce the output:
Long fruit name: watermelons
Long fruit name: blackberry
List size: 4
21
Removing a List Item While Iterating Through the List
Although the documentation for lists is quite good in most C++ text books or at cplusplus.com,the syntax for deletion of list items from the middle of the list, while iterating through may be a bittricky so we cover it here. The next code segment is similar to the above example, but this time itremoves elements of the list with string length greater than six:
1 #include <list>
2 #include <string>
3
4 list<string> 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<string>::iterator p;
11 for(p=my_strings.begin(); p!=my_strings.end(); ) {
12 string str = *p;
13 if(str.length() > 6) {
14 cout << "Removing long fruit: " << str << endl;
15 p = my_strings.erase(p);
16 }
17 else
18 ++p;
29 }
20 cout << "List size: " << my_strings.size() << endl;
Note how line 11 has changed between the two listings. The p++ in the first listing is left out in thesecond listing. The iterator instead is incremented on line 18. This code should produce the belowoutput.
Removing long fruit: watermelons
Removing long fruit: blackberry
List size: 2
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 stringsis to derefernce the contents of the iterator. The line:
string str = *p;
makes a copy of the string in the list. Let’s suppose we wanted modify the strings in the list. Forexample we may want to go through the list of strings and truncate to ten characters, all stringsgreater than ten characters. You might be inclined to try something like:
22
list<string>::iterator p;
for(p=my_strings.begin(); p!=my_strings.end(); ) {
string str = *p;
if(str.length() > 10) {
str = str.substr(0,10);
}
}
The above will not work because we truncated a copy of the string in the list. This original list ofstrings may still contain strings of length greater than ten. You instead need to use the line:
string& str = *p;
The extra ampersand now means that str is the element/string in the list, not a copy of it.
23
