Mission script structure

2026-06-18

This section is a draft started after some inquiries in Slack about the difference between mission level and insert parameters.

Final location for this documentation is still TBD, but it will probably belong to the general Mission documentation site under https://docs.mbari.org/lrauvmissions/missions/.

Feedback welcome!

Overview

A mission script defines the behavior to be run on a vehicle. It declares a set of parameters (arguments) that can be adjusted at run time, for example to set a speed, a depth bound, or the duration of the mission.

In addition to its own parameters, a mission script can pull in functionality from other reusable scripts called inserts. Each insert can contribute its own set of parameters to the mission. This is the source of a common point of confusion: a parameter you see while running a mission may belong either to the mission level or to one of the inserts, and the syntax to set it differs depending on which.

Background

The mission structure, including the notion of inserts, is described in the "Tethys Mission Structure" section of Godin et al. (2010); see References below.

You can inspect any mission and its inserts on the LRAUV missions documentation site. For example, sci2_circle_hotspot.tl includes several inserts, among them one identified as Science (source):

insert id="Science" Insert/Science.tl { ... }

The id given here (Science) is the name used to reference the parameters that the insert contributes.

Note

Such explicit insert id is optional. When not explicitly set, the id is as indicated in the inserted script itself.

Setting a parameter

UIs typically provide a wizard that guides you step by step, but the set command can also be issued directly. The syntax depends on whether the parameter is defined at the mission level or inside an insert.

Mission-level parameter — use the parameter name directly:

set <mission>.<Parameter> <value> <units>

Insert parameter — qualify the parameter name with the insert's id, using a colon (:) between the mission and the insert, and a dot (.) between the insert and the parameter:

set <mission>:<InsertId>.<Parameter> <value> <units>

Tip

The colon is the key. If a parameter belongs to an insert and you omit the :<InsertId> part, the command will be rejected because that name does not exist at the mission level.

Worked example

Suppose you want to set MedianFilterLen to 1 count for the sci2_circle_hotspot mission.

MedianFilterLen is not a mission-level parameter — it is contributed by the Science insert. So the following command is incorrect and will be reported as an error, because MedianFilterLen does not exist at the first (mission) level:

set sci2_circle_hotspot.MedianFilterLen 1 count

The correct command qualifies the parameter with the Science insert id:

set sci2_circle_hotspot:Science.MedianFilterLen 1 count

If you are unsure whether a given parameter is mission-level or comes from an insert, look up the mission on the LRAUV missions site: parameters listed under an insert must be set using the <mission>:<InsertId>.<Parameter> form.

Note

However, although regularly updated, the mission documentation site may not necessarily reflect the latest state of the mission scripts, which really depends on the particular deployment configuration (git tag) associated with the vehicle. Again, the UI wizard is the most accurate way to enter your commands.

References

• M. A. Godin, J. G. Bellingham, B. Kieft, and R. McEwen, "A scripting language for state configured layered control of the Tethys long-range autonomous underwater vehicle," OCEANS 2010 MTS/IEEE SEATTLE, Seattle, WA, Sept. 2010. DOI: 10.1109/OCEANS.2010.5664515. (See the "Tethys Mission Structure" section, in particular the description of inserts.)