Tethys Scripting Language¶

This section describes the main constructs of the Tethys Scripting Language.¹

Note

This section mainly uses TethysL syntax for illustration, but the conceptual model of the language applies regardless of the particular syntax (XML or TethysL).
In general, the documentation structure for language constructs, keywords, grammar description, etc., is still being worked out.

Main Constructs¶

The main constructs of the Tethys Scripting Language includes:

Layered Control: a subsumption architecture, in which a system is controlled by a stack of behaviors running in parallel, with higher priority behaviors subsuming the control commands from lower priority behaviors.
State configured layered control: a version of layered control in which the stack of behaviors changes over time depending on the state of the environment and system.
Behavior: an abstract interface between the Tethys Scripting Language and a portion the vehicle control and data system. Priority is set by position in the mission file: closer to the start of the file is higher priority. Behaviors includes state information to indicate when they should be active, and typically include parameters that dictate how the behavior should perform.
Mission: a file that can be run on a Tethys vehicle and contains both the layered control behavior stack and the state configuration commands that control how the behavior stack evolves.
Module behavior: a behavior included in a TethysL script via the behavior keyword. Each module behavior is namespaced within a module, and contains a specific set of set and sometimes outputArg parameters that can be specified to tailor how the module behavior acts within the mission.
Core Behavior: a behavior that is specified via a unique TethysL keyword (for example assign, readData, syslog, etc), and which typically has additional configuration keywords specific to the core behavior.
Aggregate Behavior: a collection of one or more behaviors, which can include state information that controls how the the contained behaviors state evolves. Aggregate behaviors can also be re-used within a mission and can be contained in external files.
Args: variables that can be supplied as inputs to the mission, and which can be used within the mission by behaviors for state control and parameters.
Outputs: variables that are generated by behaviors and can influence the state of other behaviors.

For the notation used in various parts to this documentation, see Notation.

Mission¶

A mission can be run from the LRAUV command line or scheduler, and is always contained in a distinct file. The general structure of a mission is:

mission ⟨id⟩? {
  ⟨testCode⟩?
  ⟨description⟩?
  ⟨defineArgs⟩?
  ⟨defineOutput⟩?
  ⟨break⟩?
  ⟨timeout⟩?
  ⟨behavior⟩*
}

The id parameter is used when logging data about the mission: all mission data is prefixed with the mission id. If omitted, the mission id is set to the simple name of the file containing the mission. For example, if the mission is contained in a file named Science/mission1.tl, then the mission id will be mission1.

The testCode section is optional and is only included in missions designed exclusively for regression testing. It contains python code that can be run after the mission is run in a simulation environment. See the test_code keyword documentation for more details.

The optional, but very important description section provides a human-readable description of the mission. See the description keyword documentation for more details.

The defineArgs section starts with an arguments keyword and contains initializations for all Args that will be available in the mission scope.

The defineOutputs section starts with an output keyword and contains initializations for all Outputs that will be written in the mission scope.

The break section starts with a break keyword and is followed by a boolean condition, which if true, terminates the mission.

The timeout section starts with a timeout keyword and is followed by a duration specification, which can either be the name of an existing mission Arg, or an exact duration inspired by the ISO-8601 duration format, but excluding the "T" time designator and including only Days, Hours, Minutes, and Seconds. For example, a 1-day, 30 minute duration would be P1D30M. When the timeout duration has been met, either the mission ends, or if the timeout section contains a collection behaviors, then those contained behaviors are run (in sequence only), and when they complete the mission ends.

The behaviors section contains any number of core, module, and aggregate behaviors, arranged with the highest priority behaviors nearer the beginning (top) of the mission.

Module behavior¶

The keyword behavior in TethysL allows to invoke a particular LRAUV module behavior, which is defined at the C++ level. The behaviors section describes some of commonly used LRAUV module behaviors.

The general form of this construct is:

behavior ⟨moduleName⟩:⟨behaviorName⟩  ⟦ id = "someId" ⟧? {
  ⟨description⟩?
  ⟨executionMode⟩
  ⟨break⟩?
  ⟨timeout⟩?
  ⟦ ⟨behaviorChoice1⟩ | ⟨behaviorChoice2⟩ ⟧*
}

Each module behavior is name-spaced within the module that defines the behavior. For instance, the Guidance module defines the Waypoint behavior, so this module behavior is referred to as Guidance:Waypoint.

The id parameter is optional, but can be useful for tracking data generated by the behavior. Otherwise, the id is set to the location of the behavior within its mission or aggregate container, with the highest behavior having an id of "A", followed by "B", etc.

The optional description section is useful for including a human-readable description of how the module behavior is being used within the containing mission or aggregate behavior.

The executionMode is one of the modes described below, either parallel, sequence, progression, when, or while.

The break section starts with a break keyword and is followed by a boolean condition. If the execution mode is sequence or when, then when the break condition is true then the behavior completes and the next sequenced item begins. If the execution mode is parallel, progression, or while and the behavior otherwise would be active, then a true break condition blocks the behavior from running while the break condition is true.

Aggregate Behavior¶

The general structure of an aggregate behavior is:

aggregate ⟨id⟩? {
  ⟨description⟩?
  ⟨defineArgs⟩?
  ⟨defineOutput⟩?
  ⟨executionMode⟩?
  ⟨break⟩?
  ⟨timeout⟩?
  ⟨preemptive⟩?
  ⟨behavior⟩*
}

Note that the structure of an aggregate behavior is almost identical to a mission, except that an aggregate behavior can include a executionMode like a module behavior although the executionMode is optional for aggregate behaviors and defaults to sequence.

Execution modes¶

A tenet of state configured layered control is that only a subset of behaviors needs to be active at the same. The following execution modes help to control which behaviors are active at any moment.

`in parallel`¶

This is the most basic execution mode. The behavior runs along with any other active behaviors, and does not stop either until the mission or aggregate behavior that contains it completes or until a break condition is satisfied.

`in sequence`¶

In the sequence execution mode, the behavior becomes active if it is the first sequence behavior in the mission or aggregate behavior that contains it, or when a preceding sequence behavior reaches a state of completion. Then the behavior remains active until it reaches a state of completion, either because it is a goal oriented behavior or because either a break or timeout condition becomes true. Then the next (if any) sequence behavior becomes active. If this is the last sequence behavior in the mission or aggregate behavior that contains it, then the mission or aggregate behavior also reaches a state of completion.

The sequence execution mode can also be followed by repeat = ⟨value⟩ where the value is a countable integer. This causes the behavior to repeat the specified number of times.

`in progression`¶

The progression execution mode is equivalent to running a behavior both in parallel and in sequence. The behavior runs continuously, but does not allow subsequent sequence behaviors to become active until it reaches it goal. Conceptually, this could be behavior like drive to depth X and stay there which could be followed by a behavior like take a measurement every Y minutes, Z times.

The progression execution mode can also be followed by repeat = ⟨value⟩ which causes the goal to be achieved the specified number of times before the next sequence behavior to becomes active (or the container becomes inactive if there is no next sequence behavior).

`when (_condition_)`¶

The when execution mode kicks off a goal-oriented behavior, similar to a sequence behavior, except that the behavior only becomes active when the when condition becomes true. When the goal is achieved (or a break or timeout occurs), the behavior becomes inactive until the when condition becomes true again.

The when execution mode can also be followed by repeat = ⟨value⟩, which causes the behavior to run the specified number of times after the when condition becomes true.

`while (_condition_)`¶

The while execution mode kicks off a continuous behavior, similar to a parallel behavior, except that the behavior is only active when the while condition is true. When while condition becomes false (or a break occurs), the behavior becomes inactive until the while condition becomes true again.

M. A. Godin, J. G. Bellingham, B. Kieft and R. McEwen, "Scripting language for state configured layered control of the Tethys long range autonomous underwater vehicle," OCEANS 2010 MTS/IEEE SEATTLE, 2010, pp. 1-7, doi: 10.1109/OCEANS.2010.5664515. ↩

Tethys Scripting Language¶

Main Constructs¶

Mission¶

Module behavior¶

Aggregate Behavior¶

Execution modes¶

in parallel¶

in sequence¶

in progression¶

when (_condition_)¶

while (_condition_)¶

`in parallel`¶

`in sequence`¶

`in progression`¶

`when (_condition_)`¶

`while (_condition_)`¶