29   Extended Example Missions with the IvP Helm

29.1 Preliminaries
29.2 Using pAntler to Launch Missions
29.3 Using the nsplug Utility for Configuring Mission and Behavior Files

This section addresses a number of example mission configurations the user may run in simulation, to explore various aspects of the helm, certain behaviors, and certain tools for configuring, running and analyzing missions. All missions are available in the moos-ivp software tree in the following location: 

  $ cd moos-ivp/ivp/missions/

Obtaining the moos-ivp software tree from the public server was discussed in Section 4.

29.1   Preliminaries    [top]

Each mission in the missions/ directory is contained in a dedicated subdirectory such as s1_alpha, or m2_berta. The 's' and 'm' in the prefix indicate whether it is a single-vehicle or multi-vehicle mission. The numbering roughly correlates to an increase in complexity from commonly used bread-and-butter behaviors and configurations to more complex mission configurations.

    Each directory contains one or more mission files, i.e., files that end in the .moos suffix, and one or more behavior files, i.e., files that end in the .bhv suffix. During the course of running a mission, certain additional temporary files may be created. In all cases, the temporary files may be removed by running the clean.sh script included in each directory. The configuration and launching of the missions requires some familiarity with three tools, (a) pAntler, for launching multiple MOOS applications, (b) the nsplug tool, for building composite .moos and .bhv files from a template and set of include files, and (c) basics of shell scripts for organizing the overall launch process and cleanup. A brief recap of these three tools is covered next.

29.2   Using pAntler to Launch Missions    [top]

The pAntler utility is a command-line tool used to orchestrate the launching of a group of MOOS processes. A typical invocation is: 

  $ pAntler charlie.moos

The MOOS file contains a configuration block for each process, and an Antler configuration block which is typically the first block in the file. Each block contains a collection of local ``parameter = value'' pairs read in by each individual application. There are also typically a number of global parameter=value pairs for possible use by all applications.

29.3   Using the nsplug Utility for Configuring Mission and Behavior Files    [top]

In multi-vehicle missions, the maintenance of mission and behavior files across multiple vehicles can become cumbersome and user error-prone. Since many of the file components are identical between vehicles, a fair amount of the problem is mitigated by building the files from file template files that include the common components from separate files. The nsplug command-line utility is used to expand a template file into a target file, with arguments passed that typically distinguish the produced file from others produced from the same template. For example, two mission files, one for the vehicle "charlie", and one for the vehicle "frankie" may differ only in their vehicle names and IP Port number, and may be produced from a template file with the following two commands: 

  $ nsplug  meta_vehicle.moos targ_charlie.moos VNAME=charlie PORT=9201
  $ nsplug  meta_vehicle.moos targ_frankie.moos VNAME=charlie PORT=9202

For the multi-vehicle example missions distributed with the moos-ivp tree and described in this section, this use of templates is used in all cases. The mission directories downloaded will not contain the nsplug "output" files such as targ_charlie.moos above. Rather, they are built by executing the launch scripts provided in each directory with a command such as: 

  $ ./launch.sh

The above invocation will both build the mission and behavior files and invoke pAntler for each vehicle to start the simulation. Certain common command-line options such as "./launch --just_build", to build the mission files without launching, are available in all scripts. A few conventions with respect to templates and nsplug are used across all example mission directories.

  1. Files used as templates have a "meta_" prefix.
  1. Files meant to be included or plugged into another template file have a "plug_" prefix.
  1. Output files that are built from templates and plug-ins via nsplug have "targ_" prefix.
  1. Template or plug-in files that contribute to a target MOOS file have ".moos" suffix.
  1. Template or plug-in files that contribute to a target Helm behavior file have ".bhv" suffix.

For example, in the m2_berta mission, the following files exist prior to building any target files and launching: 

 $ cd missions/m2_berta
 $ ls
 clean.sh*                   plug_uSimMarine.moos        plug_pMOOSBridgeV.moos
 launch.sh*                  plug_origin_warp.moos       plug_pMarinePID.moos
 meta_shoreside.moos         plug_pBasicContactMgr.moos  plug_pNodeReporter.moos
 meta_vehicle.bhv            plug_pHelmIvP.moos          plug_uProcessWatch.moos
 meta_vehicle.moos           plug_pLogger.moos           plug_uXMS.moos

After building all the target files, the following additional targ_* files exist: 

 $ ./launch.sh --just_build
 $ ls
 clean.sh*                   plug_pBasicContactMgr.moos  plug_uXMS.moos
 launch.sh*                  plug_pHelmIvP.moos          targ_gilda.bhv
 meta_shoreside.moos         plug_pLogger.moos           targ_gilda.moos
 meta_vehicle.bhv            plug_pMOOSBridgeV.moos      targ_henry.bhv
 meta_vehicle.moos           plug_pMarinePID.moos        targ_henry.moos
 plug_uSimMarine.moos        plug_pNodeReporter.moos     targ_shoreside.moos
 plug_origin_warp.moos       plug_uProcessWatch.moos

The mission may launched, with MOOSTimeWarp=10, by: 

  $  ./launch.sh 10

Page built from LaTeX source using the texwiki program.