10   The OpRegion Behavior

10.1 Configuration Parameters
10.2 Variables Published
10.3 Safety Checking Applied to an Operation Region
10.4 Safety Limits on Operation Time, Depth, and Vehicle Altitude
10.5 Variables Published by the OpRegion Behavior
10.6 Publishing Breach Flags
10.7 Resetting a Breach Condition

This behavior provides four different types of safety functionality, (a) a boundary box given by a convex polygon in the x-y or lat-lon plane, (b) an overall timeout, (c) a depth limit, (d) an altitude limit. The behavior does not produce an objective function to influence the vehicle to avoid violating these safety constraints. This behavior merely monitors the constraints and posts an error which results in the posting of all-stop commands, which could put the vehicle into the PARK state if the helm is configured with park_on_allstop is set to true. More on this parameter can be found in Section 5.3.

10.1   Configuration Parameters    [top]

Listing 10.1 - Configuration Parameters Common to All Behaviors.

activeflag:A MOOS variable-value pair posted when the behavior is in the active state. Section 6.5.4.
condition:Specifies a condition that must be met for the behavior to be running. Section 6.5.1.
duration:Time in behavior will remain running before declaring completion. Section 7.2.6.
duration_idle_decay:When true, duration clock is running even when in the idle state. Section 7.2.6.
duration_reset:A variable-pair such as MY_RESET=true, that will trigger a duration reset. See Section 7.2.6.
duration_status:The name of a MOOS variable to which the vehicle duration status is published. Section 7.2.6.
endflag:A MOOS variable-value pair posted when the behavior has completed. Section 6.5.4.
idleflag:A MOOS variable-value pair posted when the behavior is in the idle state. Section 6.5.4.
inactiveflag:A MOOS variable-value posted when the behavior is not in the active state. Section 6.5.4.
name:The (unique) name of the behavior. Section 7.2.2.
nostarve:Allows a behavior to assert a maximum staleness for a MOOS variable Section 7.2.9.
perpetual:If true allows the behavior to to run even after it has completed. Section 7.2.7.
post_mapping:Re-direct behavior output normally to one MOOS variable to another instead. Section 7.2.4.
priority:The priority weight of the behavior. Section 7.2.3.
pwt:Same as priority.
runflag:A MOOS variable and a value posted when a behavior has met its conditions. Section 6.5.4.
spawnflag:A MOOS variable and a value posted when a behavior is spawned. Section 6.5.4.
templating:Turns a behavior into a template for spawning behaviors dynamically. Section 7.7.
updates:A MOOS variable from which behavior parameter updates are read dynamically. Section 7.2.5.

Listing 10.2 - Configuration Parameters for the OpRegion Behavior.

Parameter:Description
breached_altitude_flag:A MOOS variable-value pair to be posted when or if the vehicle breaches the altitude limit set by this behavior. New with Release 14.7.1. Section 10.6.
breached_depth_flag:A MOOS variable-value pair to be posted when or if the vehicle breaches the depth limit set by this behavior. New with Release 14.7.1. Section 10.6.
breached_poly_flag:A MOOS variable-value pair to be posted when or if the vehicle breaches the convex polygon op area limit set by this behavior. New with Release 14.7.1. Section 10.6.
breached_time_flag:A MOOS variable-value pair to be posted when or if the vehicle breaches the time limit set by this behavior. New with Release 14.7.1. Section 10.6.
max_time:The max allowable time in seconds. Section 10.4.
max_depth:The max allowable depth in meters. Section 10.4.
min_altitude:The min allowable altitude in meters. Section 10.4.
opregion_poly_var:The name of a MOOS variable to which the polygon points will be posted. By default is empty, meany no such post is made.
polygon:The lat-lon area the vehicle is restricted to stay within. Section 10.3.
reset_var:A MOOS variable to allow behavior reset when or if the behavior is breached. New with Release 14.7.1. Section 10.7.
time_remaining_var:A MOOS variable to publish the remaining time left if max_time is specified. If this variable is specified, but the maximum time is not enforced, then it will publish with a value of -1. New with Release 14.7.1.
trigger_entry_time:The time required for the vehicle to have been within the polygon region before triggering the polygon requirement. Section 10.3.
trigger_exit_time:The time required to have been outside the polygon before declaring a polygon containment failure. Section 10.3.
visual_hints:Hints for visual properties in variables posted intended for rendering.

Listing 10.3 - Example Configuration Block. 

 Behavior = BHV_OpRegion
 {
   // General Behavior Parameters
   // ---------------------------
   name         = op_region                 // example
   pwt          = 100                       // default
   condition    = SAFETY=true               // example
   updates      = OPREGION_UPDATES          // example

   // Parameters specific to this behavior
   // ------------------------------------
                  max_time = 0              // default (seconds)
                 max_depth = 0              // default (meters)
              min_altitude = 0              // default (meters)
                 reset_var = OPREGION_RESET // example
        trigger_entry_time = 1              // default (seconds)
         trigger_exit_time = 0.5            // default (seconds) 

                   polygon = pts={-80,-50:-30,-175:150,-100:95,25}, label=area_x

    breached_altitude_flag = SAY_MOOS = Sir, the min altitude has been excceded
       breached_depth_flag = SAY_MOOS = Sir, the max depth has been excceded
        breached_poly_flag = SAY_MOOS = Sir, the op region has been violated
        breached_time_flag = SAY_MOOS = Sir, the maximum mission time has been exceeded

              visual_hints = vertex_color = brown  // default
              visual_hints = vertex_size  = 3      // default
              visual_hints = edge_color   = aqua   // default
              visual_hints = edge_size    = 1      // default
 }

10.2   Variables Published    [top]

The below MOOS variables will be published by the behavior during normal operation, in addition to any configured flags. A variable published by any behavior may be supressed or changed to a different variable name using the post_mapping configuration parameter described in Section 7.2.8.

  • OPREG_TRAJECTORY_PERIM_DIST: Distance, in meters, to the perimeter on the current trajectory.
  • OPREG_TRAJECTORY_PERIM_ETA: Time to the perimiter on the current speed and trajectory.
  • OPREG_ABSOLUTE_PERIM_DIST: Distance, in meters, to the op-region in any direction.
  • OPREG_ABSOLUTE_PERIM_ETA: Time to the op-region perimeter at current speed in any direction.
  • OPREG_TIME_REMAINING: Time, in seconds, until the max_time upper bound is exceeded.
  • VIEW_POLYGON: A visual cue for rendering the polygon containment region.

10.3   Safety Checking Applied to an Operation Region    [top]

One safety check performed by the OpRegion behavior is to ensure that the vehicle remains in an operation region defined by a convex polygon in the x-y plane.

  • polygon: A colon separated list of x,y pairs given as points in space, typically meters. A pair given by "label,string" can associate an optional label with the point list. The collection of points must be a convex polygon. A check for convexity is done upon helm/behavior start-up. Behavior initialization will fail if it is not convex. If no polygon is provided, no X,Y checks are made.
  • trigger_entry_time: The amount of time required for the vehicle to have been within the polygon containment region before triggering the polygon containment requirement. This is useful when launching vehicles from a dock structure such as the MIT Sailing Pavilion. The default setting is zero meaning the polygon containment requirement is active immediately.
  • trigger_exit_time: The amount of time required to have been outside the polygon containment region before declaring a polygon containment failure. This is useful if the vehicle NAV_X and NAV_Y position is based on a sensor without outlier detection. The kayaks, for example, are often relying solely on GPS which occasionally emits an outlier well out of the containment region. By setting this value high enough, outliers are ignored. Each time a recorded position is contained within the polygon region, the clock is set to zero. The default setting is zero, meaning the very first detection outside the polygon will result in a polygon containment error.

10.4   Safety Limits on Operation Time, Depth, and Vehicle Altitude    [top]

  • max_time: The maximum allowable time (in seconds) that the helm is allowed to run. The clock starts when the pHelmIvP process first takes control, i.e., enters the DRIVE state. If no maximum time is specified, then no time checks are made.
  • max_depth: The maximum allowable depth of the vehicle (in meters). If no depth is provided, no depth checks are made.
  • min_altitude: The minimum allowable altitude of the vehicle (in meters). If no altitude is provided, no altitude checks are made.

10.5   Variables Published by the OpRegion Behavior    [top]

The behavior also produces a set of status variables regarding the vehicle position with respect to the containment region. Since a violation of this constraint results in a vehicle full-stop and the helm relinquishing control, other behaviors or MOOS processes may want to take measures to avoid it. These status variables provide information on the position and estimated time between the vehicle and the perimeter, based both on the absolute position as well as the current vehicle trajectory. See Figure 10.1.

Figure 10.1: The OpRegion polygon and status variables: The OpRegion behavior publishes information regarding its estimated distance and time of arrival (ETA) to the perimeter of the polygon containment region. It publishes two sets of information; one based on the current trajectory and the other based on the absolute distance to the perimeter at top vehicle speed.

The four variables produced by the behavior (and posted to the MOOSDB by the Helm) are:

  • OPREG_TRAJECTORY_PERIM_DIST: The distance (in meters) between the current vehicle position to the perimeter of the polygon containment region (given by the polygon parameter), based on the vehicle remaining on the current trajectory.
  • OPREG_TRAJECTORY_PERIM_ETA: The amount of time (in seconds) needed for the vehicle to reach the perimeter of the polygon containment region (given by the polygon parameter), based on the vehicle remaining on the current trajectory.
  • OPREG_ABSOLUTE_PERIM_DIST: The distance (in meters) between the current vehicle position to the perimeter of the polygon containment region (given by the polygon parameter), regardless of the current vehicle trajectory.
  • OPREG_ABSOLUTE_PERIM_ETA: The amount of time (in seconds) needed for the vehicle to reach the perimeter of the polygon containment region (given by the polygon parameter), regardless of the current vehicle trajectory. Calculated on the maximum vehicle speed.

10.6   Publishing Breach Flags    [top]

The behavior may be configured with four different types of breach flags:

  • The breached_altitude_flag names a MOOS variable-value pair to be posted when or if the minimum altitude (if set) is exceeded.
  • The breached_depth_flag names a MOOS variable-value pair to be posted when or if the maximum depth (if set) is exceeded.
  • The breached_poly_flag names a MOOS variable-value pair to be posted when or if the vehicle exits the polygon containment area (if set).
  • The breached_time_flag names a MOOS variable-value pair to be posted when or if the maximum mission time (if set) is exceeded.

Each type of flag may be configured with more than one posting using separate lines in the configuration block. The flags are posted once upon the initial breach, but may be posted again later if the behavior is re-set and the breach re-occurrs.

10.7   Resetting a Breach Condition    [top]

The behavior may be configured to accept a reset after one of the breach conditions occur. This is done by naming a MOOS variable using the reset_var parameter. Upon receipt of this mail, the behavior returns to the state as when it was first spawned at launch time.

For example, if the behavior were configured with:

    reset_var = OPR_RESET

then the following postings would reset the behavior if the vehicle breached the OpRegion polygon:

    OPR_RESET = poly

Similarly, if the OpRegion behavior were breached due to a depth violation, posting OPR_RESET=depth would reset the behavior. Posting OPR_RESET=time would reset the behavior after breaching its max time limit. Posting OPR_RESET=altittude would reset the behavior after breaching its min altitude limit.

Page built from LaTeX source using the texwiki program.