pMissionHash: A Lightweight App for Generating a Mission Hash

Maintained by: mikerb@mit.edu         Get PDF

src: project-pavlab/appdocs/app_pmhash

1  Overview
2  Typical Application Topology
3  Configuration Parameters of pMissionHash
     3.1 Variables Published
     3.2 Variables Subscriptions
4  Command Line Usage of pMissionHash
5  Terminal and AppCast Output

1   Overview

The pMissionHash app was meant to run and generate a mission hash when (a) pMarineViewer is not being run, and (b) mission hash generation is still desired. A mission hash is normally generated on the shoreside MOOS community in the form of a posting to the variable MISSION_HASH. Normally the hash is generated and posted by pMarineViewer. However, in headless missions, where there is no GUI and no pMarineViewer, a mission hash posting can be generated instead with pMissionHash. Headless mission configurations are common in automated missions, e.g., for validation, automated competitions, or Monte Carlo testing.

Why are mission hashes important? The mission hash is created and logged on the shoreside and shared to and logged on all the vehicles. The presence of identical mission hashes is the definitive confirmation that the individual log files are all part of the same instance of a particular mission, either in simulation or in the physical world. As of this writing, a mission hash is generated either with pMarineViewer or pMissionHash. The command-line tool mhash_gen is also distributed with MOOS-IvP but is not generally part of a mission.

2   Typical Application Topology

The pMissionHash app typically runs in the shoreside community, in a headless mission, when pMarineViewer is not running.

Figure 2.1: Typical pMissionHash Topology: A unique randomly created mission hash is generated by pMissionHash at startup, and shared to the MOOS communities of all vehicles. This unique has is thus logged in all log files for each vehicle and shoreside, thus allowing for confirmation that the log files were all part of the same mission.

3   Configuration Parameters of pMissionHash

The following parameters are defined for pMissionHash. If a configuration block is not provided for pMissionHash in the mission file, this is acceptable and no warning will be posted.

Listing 3.1 - Configuration parameters for pMissionHash.

mission_hash_var:The variable to which the mission hash is posted. The default is MISSION_HASH.
mhash_short_var:The variable to which the short version of the mission hash is posted. If this parameter is not specified, this information will not be published. This cannot be the same variable as the mission_hash_var.

An Example MOOS Configuration Block    [top]

Listing 3.2 shows an example MOOS configuration block produced from the following command line invocation: 

  $ pMissionHash --example or -e

Listing 3.2 - Example configuration of the pMissionHash application. 

  1  =============================================================== 
  2  pMissionHash Example MOOS Configuration                         
  3  =============================================================== 
  4                                                                  
  5  ProcessConfig = pMissionHash                                    
  6  {                                                               
  7    AppTick   = 4                                                 
  8    CommsTick = 4                                                 
  9                                                                  
 10    mission_hash_var = MISSION_HASH  // default                   
 11    mhash_short_var  = MHASH_SHORT   // default is disabled                   
 12                                                                  
 13    // Note: If a config block is NOT provided in the mission     
 14    //       file, NO config warning will be generated.           
 15  }

3.1   Variables Published    [top]

The primary output of pMissionHash to the MOOSDB is the mission hash message, or the short mission hash publication if this is enabled.

  • 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. Section 5.
  • MISSION_HASH: The full mission hash. This may be published to another variable name, depending on the user configuration.
  • MHASH_SHORT: The short mission hash. This will only be published if enabled through configuration.

For examples of a full and short mission hash, see Section 5.

Both variables are published immediately upon startup, and once every 30 seconds thereafter.

3.2   Variables Subscriptions    [top]

The pMissionHash 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_CLIENTS: The list of running MOOS apps is monitored, checking for pMarineViewer, and posting a warning if present. Both apps should not be running and generating conflicting mission hash values.
  • RESET_MHASH: A request to reset the mission hash.

4   Command Line Usage of pMissionHash

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

  $ uFldMessageHandler --help or -h

Listing 4.1 - Command line usage for the uFldMessageHandler tool. 

  1  =============================================================== 
  2  Usage: pMissionHash file.moos [OPTIONS]                         
  3  =============================================================== 
  4                                                                  
  5  SYNOPSIS:                                                       
  6  ------------------------------------                            
  7    The pMissionHash app is used for generating a MISSION_HASH    
  8    posting. Normally this is produced by pMarineViewer. In       
  9    headless mission not running pMarineViewer, this app can be   
 10    used instead. They should not be both run unless the mission  
 11    feature is configured to be disabled in pMarineViewer.        
 12                                                                  
 13  Options:                                                        
 14    --alias=<ProcessName>                                      
 15        Launch pMissionHash with the given process name           
 16        rather than pMissionHash.                                 
 17    --example, -e                                                 
 18        Display example MOOS configuration block.                 
 19    --help, -h                                                    
 20        Display this help message.                                
 21    --interface, -i                                               
 22        Display MOOS publications and subscriptions.              
 23    --version,-v                                                  
 24        Display the release version of pMissionHash.              
 25    --web,-w                                                      
 26        Open browser to:                                          
 27        https://oceanai.mit.edu/ivpman/apps/pMissionHash          
 28                                                                  
 29  Note: If argv[2] does not otherwise match a known option,       
 30        then it will be interpreted as a run alias. This is       
 31        to support pAntler launching conventions.

5   Terminal and AppCast Output

The pMissionHash application produces some useful information to the terminal and identical content through appcasting. An example is shown in Listing 5.1 below. On line 2, the name of the local community or vehicle name is listed on the left. On the right, "0/0(95) indicates there are no configuration or run warnings, and the current iteration of pMissionHash is 95.

    On line 4, the full mission hash is shown and the variable it is posted to, by default MISSION_HASH. On line 6, the short version of the the mission hash is shown, presumably do to the configuration of mhash_short=MHASH.

Listing 5.1 - Example appcast and terminal output of pMissionHash. 

   1  =================================================================== 
   2  pMissionHash shoreside                                      0/0(95)
   3  ===================================================================
   4  MISSION_HASH=mhash=250127-1826S-LUSH-ARMY,utc=1738020397.43
   5  MHASH=LUSH-ARMY

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