This page describes the organization of the new missions directory located in ivp-extend/missions and how the files there should be used when creating your own mission. The new arrangement should make it easier for all missions to share some common plugs and configuration parameters, reducing the need to update multiple missions when serial ports change, etc.
trunk
This is the main missions directory, where the standard missions, plugs, and configurations are stored.
plugs
Default plugs for shore, vehicle, and simulation are located in this directory. Meta files should include plugs from this directory to easily inherit any changes.
config
There are just two files in this directory, "hard_config" and "soft_config". These are not MOOS files, but standard bash files that should be sourced by the launch script. hard_config includes definitions for IP addresses, port number, serial ports, and other 'hard' configuration parameters. All missions should use this file.
soft_config includes 'soft' configuration parameters such as return locations, rudder offsets, and cruise speeds. These are parameters you may want to change in your own missions, in which case you should either rewrite these parameters in your own launch script or include your own copy of this file.
baseline folders
These are the standard mission configurations. Each includes scripts for launching the mission and the meta files for simulation, shoreside, icarus, and vehicles.
baseline_uFld - the standard mission, using uFld to configure variable sharing between communities.
baseline_pShare - currently preferred, uses single variable pShare configuration to avoid the communications overhead imposed by uFld.
baseline_pShare_wild - similar to baseline_pShare, but uses wildcard shares to simplify the sharing configuration. Should not be used until a newer version of MOOS with updated wildcard handling makes its way to the kayaks.
scheduledTransmit_pShare - based on the pShare baseline, but with the pScheduledTransmit application included. Global transmit period and offsets for each vehicle are defined in the vehicle launch script.
How it works
If you look at one of the launch script you should typically see the following steps:
- Source the hard and soft config files to pull in those configuration variables
- Read command line options, such as which vehicle is to be launched
- Check options for errors and make sure all required options are set.
- Run nsplug on the meta file (.moos or .bhv), and pass it all the variables to be set in the files
- nsplug will first copy into the meta file the contents of any include statements
- second, nsplug will attempt to fill any variable placeholders with the values passed to it by the script
- launch!
Make your own
Start your own mission by copying one of the baseline folders (currently prefer baseline_pShare) into your own folder in the missions directory. Rename it to something else, and make whatever changes are necessary. You can make your own plugs to replace the defaults as well and save them anywhere in your folder, as long as the include paths in the meta moos file are appropriately modified. Some other suggestions/guidelines:
- Whenever possible, include the plugs in the trunk so you can inherit any changes there. Always include the trunk's hard_config file.
- It's usually preferable to add command line options to a launch script rather than copy most of it to a new file. Help fight excessive copy-pasting.
- Nsplug supports using C-style #ifdef statements. Useful, for example, if you want to use the same meta file for two vehicles but need to start a different application on each.