MOOS Basics

Getting Started with MOOS Basics

These pages contain a handful of introductory MOOS topics designed for the absolutely new MOOS user.

Launching the MOOSDB:

The MOOSDB is the heart of MOOS. This page describes how it may be simply launched from the command line. Later we’ll see that typically the MOOSDB is launched as part of a group MOOS apps with the pAntler tool. But this a good page to start for someone who has never before launched the MOOSDB.
Scoping the MOOSDB:

This page describes how to scope the MOOSDB. Scoping refers to the idea of having a view into the current state (or even recent history) of the MOOSDB. This page describes the uXMS and uMS tools, among the several ways to scope the MOOSDB.
Poking the MOOSDB:

This page describes how to poke the MOOSDB. Poking refers to the idea of publishing a variable-value pair to the MOOSDB. Poking implies a publication that perhaps was not planned, or outside the normal mode of business. It is often very useful for debugging. Here we describe the uPokeDB tool.
Launching a Mission with pAntler:

This page describes how to launch a set of MOOS applications with pAntler. In theory, a set of N applications may be launched from N terminal windows, but this is cumbersome in practice. The pAntler tool allows a block to be declared in a mission file (.moos file) listing all the apps to be launched in one go.
Scripted Pokes to the MOOSDB:

This page describes MOOS scripting: configuring a set of pre-arranged pokes, at pre-arranged times to the MOOSDB. This may be useful for a number of reasons besides debugging. The primary tool described here is the uTimerScript MOOS application.
A Simple Example with pXRelay:

pXRelay is a simple MOOS app designed solely to illustrate basic functions of a MOOS app. It registers for a single variable, and upon receipt mail for that variable, it publishes another variable incremented by 1. It provides a framework for illustrating few other introductory topics.

A Simple Example with pXRelay

pXRelay is a simple MOOS app designed solely to illustrate basic functions of a MOOS app. It registers for a single variable, and upon receipt mail for that variable, it publishes another variable incremented by 1. It provides a framework for illustrating few other introductory topics.

Where to get more information:

Type pXRelay—example on the command line.
An Overview of MOOS-IvP and a Users Guide to the IvP Helm (Section 3.8) (PDF)

Basic pXRelay Usage

pXRelay is configured with its own block in the MOOS configuration file. It is configured with (a) an incoming variable, the variable it will register for incoming mail, and (b) an outgoing variable, a variable it will post an incremented integer each time it receives mail on the incoming variable. The basic form is:

 ProcessConfig = pXRelay
 {
   OUTGOING_VAR = 
   INCOMING_VAR = 
 }

A Simple Example with pXRelay

The below mission file contains a configuration for two instances of the pXRelay application. All MOOS apps must have a unique name to connect to the MOOSDB, so we launch them with an alias with pAntler using the ~pXRelay_PEARS alias for example. The two apps each register for what the other produces, and each produces what the other registers for.

 // (wget http://oceanai.mit.edu/2.S998/examples/xrelay.moos)
 ServerHost = localhost
 ServerPort = 9000
 Community  = alpha

  ProcessConfig = ANTLER
  {
   MSBetweenLaunches = 200

   Run = MOOSDB       @ NewConsole = false
   Run = pXRelay      @ NewConsole = false ~pXRelay_PEARS
   Run = pXRelay      @ NewConsole = false ~pXRelay_APPLES
  }

  ProcessConfig = pXRelay_APPLES
  {
   AppTick       = 10
   CommsTick     = 10
   INCOMING_VAR  = APPLES
   OUTGOING_VAR  = PEARS
  }

  ProcessConfig = pXRelay_PEARS
  {
   AppTick       = 10
   CommsTick     = 10
   INCOMING_VAR  = PEARS
   OUTGOING_VAR  = APPLES
  }

Upon launch, the two pXRelay apps are in a stalemate, each waiting for the other to make the first posting. We can break this stalemate with uPokeDB:

 $ uPokeDB xrelay.moos PEARS=1

This should get things going. Now it would be good to see it all running by launching a scope:

 $ uXMS xrelay.moos --all --show=time

This page describes how to launch a set of MOOS applications with pAntler. In theory, a set of N applications may be launched from N terminal windows, but this is cumbersome in practice. The pAntler tool allows a block to be declared in a mission file (.moos file) listing all the apps to be launched in one go.

Where to get more information:

pAntler: The MOOS Documents page

Basic pAntler Usage

The Antler block is typically the first configuration block in a .moos file, declared with ProcessConfig = ANTLER as below. The MSBetweenLaunches parameter specifies the number of milliseconds between launching processes. Each line thereafter specifies an app to be launched and whether a dedicated console window should be opened for the application.


ProcessConfig = ANTLER
{
  MSBetweenLaunches = 200

  Run = MOOSDB       @ NewConsole = true/false
  Run = AnotherApp   @ NewConsole = true/false
  ...
  Run = AnotherApp   @ NewConsole = true/false
}

Further options exist beyond the vanilla launch configuration described above, including (a) the ability to launch a given app under an aliased name, (b) specifying command-line arguments to app at launch time and more. See the documentation.

An Example: Launching the MOOSDB along with uXMS

In the example below we use pAntler to launch the MOOSDB and the uXMS Scope from a single mission file. The user preferences for uXMS are provided in its configuration block. Type “uXMS—example” on the command line for further options.


// (wget http://oceanai.mit.edu/2.S998/examples/db_and_uxms.moos)
ServerHost = localhost
ServerPort = 9000
Community  = alpha

ProcessConfig = ANTLER   
{   
  MSBetweenLaunches = 200

  Run = MOOSDB     @ NewConsole = false
  Run = uXMS       @ NewConsole = true
}

ProcessConfig = uXMS
{
  AppTick   = 4
  CommsTick = 4

  VAR            = DB_CLIENTS, DB_UPTIME, DB_TIME
  DISPLAY_SOURCE = true
  DISPLAY_TIME   = true
  COLOR_MAP      = DB_CLIENTS,red
}

The mission may be launched from the command-line with:

 $ pAntler db_and_uxms.moos

This should open a new console window for uXMS displaying the variables posted by the DB, with the (S)ource and (T)ime columns expanded, but not the (C)ommunity column.

This page describes how to launch the MOOSDB from the perspective of the first-time user. We’ll describe two minimalist methods, starting with the most bare-bones.

A Bare-Bones Launching of the MOOSDB

In a bare-bones manner, the MOOSDB may be launched from the command line without any arguments. Normally the MOOSDB needs to know at least two pieces of configuration information, (a) the machine (IP address) on which to run, and (b) the port number on which to serve clients. It will default to running on the localhost and port 9000. But it will complain a bit:

 $ MOOSDB
  Warning no mission file found - still serving but with trepidation
  ***************************************************
  *       This is MOOS Server for Community "#1"      
  *       c. P Newman 2001                           
  *                                                  
  *       Binding on 9000                              
  *                                                  
  *       This machine is Little endian                 
  ***************************************************
					
  ------------CONNECT-------------
  New client connected from machine "localhost"
  Handshaking....done
  clients name is "DBWebServer"
  There are now 1 clients connected.
  --------------------------------

  *****************************************************
    serving webpages HTTP on http://fred.csail.mit.edu:9080
  *****************************************************

At this point the MOOSDB is running on the local machine, serving clients on port 9000. There is also “DBWebServer” on port 9080. You can click on (your version of) the above URL in your browser and see a current state of the MOOSDB.

A More Civilized Launching of the MOOSDB

Virtually all MOOS applications are launched with a “mission configuration” file, a.k.a. a “dot-moos” file. The below mission file moosdb_alpha.moos provides the minimal configuration parameters the MOOSDB likes to see upon starting.


// (wget http://oceanai.mit.edu/2.S998/examples/moosdb_alpha.moos)
ServerHost = localhost
ServerPort = 9000
Community  = alpha

Passing the moosdb_alpha.moos file as a command line argument produces a somewhat happier output (no warnings of trepidation).

$ MOOSDB moosdb_alpha.moos
  ***************************************************
  *       This is MOOS Server for Community "alpha"      
  *       c. P Newman 2001                           
  *                                                  
  *       Binding on 9000                              
  *                                                  
  *       This machine is Little endian                 
  ***************************************************

  ------------CONNECT-------------
  New client connected from machine "localhost"
  Handshaking....done
  clients name is "DBWebServer"
  There are now 1 clients connected.
  --------------------------------

  *****************************************************
    serving webpages HTTP on http://fred.csail.mit.edu:9080
  *****************************************************

This page describes how to scope the MOOSDB. Scoping refers to the idea of having a view into the current state (or even recent history) of the MOOSDB. There are multiple tools for scoping the DB, each providing conveniences of one kind or another to the user. Here we describe the uXMS and uMS tools, the two favorites of our own lab.

Where to get more information:

uXMS: From the MOOS-IvP Autonomy Tools Users Manual (find the most recent version of this document here).
uMS: The MOOS Documents page.

Scoping the MOOSDB with uXMS:

uXMS is a terminal based scope. It may be launched from the command-line, passing it a .moos file. Several command-line options are available; a full list may be seen by passing it the—help command-line option. If simply a MOOSDB is running, launching uXMS may look like:

 $ uXMS moosdb_alpha.moos --all --show=time    
 ****************************************************    
 *                                                  *    						   
 *         This is MOOS Client                      *                 
 *            c. P Newman 2001                      *                
 *                                                  *                                                                                                      
 ****************************************************    
  ---------------MOOS CONNECT-----------------------     
  contacting a MOOS server localhost:9000 -  try 00001       
  Contact Made      
  Handshaking as "XMS_418"      
  Handshaking Complete      
  Invoking User OnConnect() callback...ok    
--------------------------------------------------    
 
uXMS_418 is Running:   	       
    AppTick   @ 5.0 Hz   	       
    CommsTick @ 10 Hz      
VarName                (S) (T)ime       (C) VarValue (MODE = SCOPE:EVENTS)    
 ----------------       --- ----------   ---  ----------- (2)     
DB_CLIENTS                  19.99            "uXMS_318,DBWebServer,"    
 DB_TIME                     19.99            1329084452.15727        
 DB_UPTIME                   19.99            20.0471      
-- displaying all variables --

The three variables shown are all published by the MOOSDB. The user may choose whether or not to show the variable (S)ource, (T)ime of post, or (C)ommunity from where the post was made. key feature of uXMS vs. uMS is the ability to specify on the command-line exactly which subset of variables to scope, possibly with color-coding. This is helpful when there are hundreds of variables in the DB.

Scoping the MOOSDB with uMS

uMS is a GUI-based tool for scoping the MOOSDB. It may be invoked from the command-line similarly by passing it a .moos file describing where a MOOSDB is running:

 $ uMS moosdb_alpha.moos

Upon launch, and clicking the “Connect” button , a new window should open.

This page describes how to scope the MOOSDB. Scoping refers to the idea of having a view into the current state (or even recent history) of the MOOSDB. There are multiple tools for scoping the DB, each providing conveniences of one kind or another to the user. Here we describe the uXMS and uMS tools, the two favorites of our own lab.

Where to get more information:

uXMS: From the MOOS-IvP Autonomy Tools Users Manual (find the most recent version of this document here).
uMS: The MOOS Documents page.

Scoping the MOOSDB with uXMS

uXMS is a terminal based scope. It may be launched from the command-line, passing it a .moos file. Several command-line options are available; a full list may be seen by passing it the—help command-line option. If simply a MOOSDB is running, launching uXMS may look like:


$ uXMS moosdb_alpha.moos --all --show=time
  ****************************************************
  *                                                  *
  *       This is MOOS Client                        *
  *       c. P Newman 2001                           *
  *                                                  *
  ****************************************************
		
  ---------------MOOS CONNECT-----------------------
    contacting a MOOS server localhost:9000 -  try 00001 
    Contact Made
    Handshaking as "uXMS_418"
    Handshaking Complete
    Invoking User OnConnect() callback...ok
  --------------------------------------------------

  uXMS_418 is Running:
  	 AppTick   @ 5.0 Hz
  	 CommsTick @ 10 Hz

   VarName                (S) (T)ime       (C) VarValue (MODE = SCOPE:EVENTS)
   ----------------       --- ----------   ---  ----------- (2)
   DB_CLIENTS                  19.99            "uXMS_318,DBWebServer,"
   DB_TIME                     19.99            1329084452.15727
   DB_UPTIME                   19.99            20.0471
   -- displaying all variables --

The three variables shown are all published by the MOOSDB. The user may choose whether or not to show the variable (S)ource, (T)ime of post, or (C)ommunity from where the post was made. key feature of uXMS vs. uMS is the ability to specify on the command-line exactly which subset of variables to scope, possibly with color-coding. This is helpful when there are hundreds of variables in the DB.

Scoping the MOOSDB with uMS

uMS is a GUI-based tool for scoping the MOOSDB. It may be invoked from the command-line similarly by passing it a .moos file describing where a MOOSDB is running:

$ uMS moosdb_alpha.moos

Upon launch, and clicking the “Connect” button, you should see a new window.

This page addresses the concept of having a script of pre-arranged pokes to the MOOSDB. This may be useful for a number of reasons besides debugging. The primary tool described here is the uTimerScript MOOS application. It is capable of (a) scripted pokes at a pre-defined times after launch, (b) pokes times specified to fall randomly within an specified interval, (c) pokes having numerical values falling with a uniformly random interval, and several other features including conditioning the running of the script based on other MOOS variables.

Basic uTimerScript Usage

uTimerScript is configured with its own block in the MOOS configuration file. The general format is below. The primary entries are the events themselves, defined by a MOOS variable, value, and time or time-range when the event is to occur. There are many options for configuring the script. These options are described in the IvP Helm Documentation and MOOS Documentation, but a quick look at the options can be seen by typing “uTimerScript—example” on the command line.

 ProcessConfig = uTimerScript
 {
   event = var=, val=, time=
   event = var=, val=, time=
   ...
   event = var=, val=, time=

    [OPTIONS]
 }

Further options exist beyond the vanilla launch configuration described above, including (a) the ability to launch a given app under an aliased name, (b) specifying command-line arguments to app at launch time and more. See the MOOS documentation.

A Simple Example with uTimerScript

The below mission file contains a uTimerScript script for repeatedly posting the variable ‘COUNTER_A’ with values 1–10 in ascending order roughly once every half second. The last event in the script is posted at time chosen from a random five second interval.

 // (wget http://oceanai.mit.edu/2.S998/examples/utscript.moos)
 ServerHost = localhost
 ServerPort = 9000
 Community  = alpha

  ProcessConfig = ANTLER
 {
   MSBetweenLaunches = 200

   Run = MOOSDB       @ NewConsole = false
   Run = uXMS         @ NewConsole = true
   Run = uTimerScript @ NewConsole = false
 }

  ProcessConfig = uXMS
 {
   VAR            = COUNTER_A, DB_CLIENTS, DB_UPTIME
   COLOR_MAP      = COUNTER_A, red
   HISTORY_VAR    = COUNTER_A
 }

  ProcessConfig = uTimerScript
 {
   paused = false

   event  = var=COUNTER_A, val=1,  time=0.5
   event  = var=COUNTER_A, val=2,  time=1.0
   event  = var=COUNTER_A, val=3,  time=1.5
   event  = var=COUNTER_A, val=4,  time=2.0
   event  = var=COUNTER_A, val=5,  time=2.5
   event  = var=COUNTER_A, val=6,  time=3.0
   event  = var=COUNTER_A, val=7,  time=3.5
   event  = var=COUNTER_A, val=8,  time=4.0
   event  = var=COUNTER_A, val=9,  time=4.5
   event  = var=COUNTER_A, val=10, time=5:10

    reset_max  = nolimit
   reset_time = all-posted
 }

The mission may be launched from the command-line with:

 $ pAntler utscript.moos

This should open a new console window for uXMS displaying the variables COUNTER_A variable repeatedly incrementing from 1 to 10. Note that reaching 10 happens somewhere between 0.5 and 5.5 seconds after reaching 9.

Browse Course Material

Course Info

Instructors

Departments

As Taught In

Level

Topics

Marine Autonomy, Sensing and Communications

MOOS Basics

Getting Started with MOOS Basics

A Simple Example with pXRelay

Basic pXRelay Usage

A Simple Example with pXRelay

Basic pAntler Usage

An Example: Launching the MOOSDB along with uXMS

A Bare-Bones Launching of the MOOSDB

A More Civilized Launching of the MOOSDB

Scoping the MOOSDB with uXMS:

Scoping the MOOSDB with uMS

Scoping the MOOSDB with uXMS

Scoping the MOOSDB with uMS

Basic uTimerScript Usage

A Simple Example with uTimerScript

Course Info

Instructors

Departments

As Taught In

Level

Topics