uMayFinish: A command-line MOOS Tool for Waiting for Mission Completion

Maintained by: mikerb@mit.edu         Get PDF

src: project-pavlab/appdocs/app_umayfinish

1  Overview
2  Configuration Parameters for uMayFinish
3  Publications and Subscriptions for uMayFinish
     3.1 Variables Published by uMayFinish
     3.2 Variables Subscribed for by uMayFinish
     3.3 Command Line Usage of uMayFinish
4  Terminal and AppCast Output

1   Overview

uMayFinish is typically a terminal-launched MOOS app launched within a shell script, e.g., xlaunch.sh. It will connect to a MOOS community and monitor for a completion event or timeout based on DB_UPTIME. When completed, it simply exits. Presumably to allow the executing script to proceed to a next phase. For example a script could proceed to bring down the MOOS community for the mission it was monitoring.

Figure 1.1: Typical uMayFinish Topology: The uMayFinish app is typically not part of the initial MOOS community of either the shoreside or vehicles. Typically, shortly after everything is launched, the uMayFinish app is launched and connects to the shoreside MOOSDB. It waits for a either a time limit to be reached, or a specified MOOS variable to have a specified value. Then the app disconnects. The disconnection may be followed by an action to shut down all MOOS communities.

Consider the following pseudo-code snippet: 

 pAntler mission.moos [=&=]
 uMayFinish --max_time=600 mission.moos
 ktm

In the first line, the mission is launched. It is launched in the background, so control proceeds immediately to the next line. Then uMayFinish launches and connects to the same MOOSDB since it is invoked with the same mission file. It is not launched in the background, so control will stop here until the uMayFinish completes. After 10 minutes (600 seconds), it will disconnect from the MOOSDB, and exit. Control passes to the next line which invokes ktm (kill-the-moos), to bring down the entire mission.

Something similar is used in xlaunch.sh, which is meant to be a general way for auto-launching missions with provisions for time-conditioned or event-conditioned exiting. In the above snippet, the maximum time was passed on the command line. The maximum time can also be specified in the uMayFinish configuration file in the mission file, as described in Section 2.

2   Configuration Parameters for uMayFinish

The uMayFinish application may be configured with a configuration block within a MOOS mission file, typically with a .moos file suffix. The following parameters are defined for uMayFinish.

Listing 2.1 - Configuration Parameters for uMayFinish.

finish_var:A MOOS variable.
finish_val:A prescribed value for the MOOS variable.
max_db_uptime:The number of seconds, found in the MOOSDB published variable DB_UPTIME, after which this app will exit.

An Example MOOS Configuration Block    [top]

An example MOOS configuration block may be obtained from the command line with the following: 

  $ uMayFinish --example or -e

Listing 2.2 - Example configuration of the uMayFinish application. 

  1  =============================================================== 
  2  uMayFinish Example MOOS Configuration                           
  3  =============================================================== 
  4                                                                  
  5  ProcessConfig = uMayFinish                                      
  6  {                                                               
  7    AppTick   = 4                                                 
  8    CommsTick = 4                                                 
  9                                                                  
 10    finish_var = MISSION_EVALUATED  // Default                    
 11    finish_val = true               // Default                    
 12                                                                  
 13    max_db_uptime = 3600            // Default is -1 (off)        
 14  }

3   Publications and Subscriptions for uMayFinish

The interface for uMayFinish, in terms of publications and subscriptions, is described below. This same information may also be obtained from the terminal with: 

  $ uMayFinish --interface or -i

3.1   Variables Published by uMayFinish    [top]

  • APPCAST: Contains an appcast report identical to the terminal output. Appcasts are posted only after an appcast request is received from an appcast viewing utility.

3.2   Variables Subscribed for by uMayFinish    [top]

The uMayFinish application subscribes to the following MOOS variables:

  • APPCAST_REQ: A request to generate and post a new apppcast report, with reporting criteria, and expiration.
  • DB_UPTIME: The number of seconds since the MOOSDB has been launched. If a mission has been auto-started shortly after launch (e.g., using pAutoPoke), then this value is a good approximation for measuring how long the mission has been running. Note, this subscription will only be made if the configuration parameter max_db_uptime is set. This param is set to -1 by default, meaning there is no maximum time.

Node that uMayFinish will also subscribe for the variable named in the configuration parameter finish_var, if provided.

3.3   Command Line Usage of uMayFinish    [top]

The uMayFinish application is typically launched with pAntler, along with a group of other modules. However, it may be launched separately from the command line. The command line options may be shown by typing: 

  $ uMayFinish --help or -h

Listing 3.1 - Command line usage for the uMayFinish tool. 

   1  Usage: uMayFinish file.moos [OPTIONS]             
   2                                                         
   3  Options:                                               
   4    --alias=<ProcessName>                                
   5        Launch uMayFinish with the given process    
   6        name rather than uMayFinish.                
   7    --example, -e                                        
   8        Display example MOOS configuration block         
   9    --help, -h                                           
  10        Display this help message.                       
  14    --interface, -i                                               
  15        Display MOOS publications and subscriptions.      
  16    --version,-v                                         
  17        Display the release version of uMayFinish.  
  18    --max_time=1200                                               
  19        Maximum DB_UPTIME before exiting.  
  20    --web,-w                                                      
  21        Open browser to: https://oceanai.mit.edu/ivpman/apps/uMayFinish
  22 
  23  Note: If argv[2] is not of one of the above formats 
  24        this will be interpreted as a run alias. This 
  25        is to support pAntler launching conventions.

4   Terminal and AppCast Output

Some useful information is published by uMayFinish to the terminal on every iteration. An example is shown in Listing 4.1 below. This application is also appcast enabled, meaning its reports are published to the MOOSDB and viewable from any uMAC application or pMarineViewer. The counter on the end of line 2 is incremented on each iteration of uMayFinish, and also serves as a heartbeat indicator. The "0/0" also on line 2 indicates there are no configuration or run warnings detected.

Listing 4.1 - Example terminal or appcast output for uMayFinish. 

  1  ==============================================================
  2  uMayFinish shoreside                                   0/0(67)
  3  ==============================================================
  4  Config: 
  5    Finish Var: MISSION_EVALUATED
  6    Finish Val: true
  7    Max DBTime: -1
  8  
  9  State:
 10    DB_UPTIME: n/a
 11    MISSION_EVALUATED:

Lines 4-7 of the output show the user configuration. Lines 10 and 11 show the current state of the app. Note the DB_UPTIME output on line 10 indicates "n/a" since no max time was set for this launch (line 7).

When the exit criteria is met, the appcast output may change as below. Note the only change is on line 11, where the empty value for the current value of MISSION_EVALUATED in the listing above, is replaced with MISSION_EVALUATED: true in the listing below. Since this satisfies the exit criteria, this will be the very last appcasting output to either the terminal or seen in pMarineViewer.

Listing 4.2 - Example output as uMayFinish finishes. 

  1  ==============================================================
  2  uMayFinish shoreside                                  0/0(341)
  3  ==============================================================
  4  Config: 
  5    Finish Var: MISSION_EVALUATED
  6    Finish Val: true
  7    Max DBTime: -1
  8
  9  State:
 10    DB_UPTIME: n/a
 11    MISSION_EVALUATED: true

When uMayFinishApp exits due to satisfying the finish variable criteria, it will return with a value of 0. When uMayFinishApp exits due to exceeding a maximum time limit, the exit value is 1 instead.

Document Maintained by: mikerb@mit.edu        
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF