25   The AvdColregs Behavior

25.1 Configuration Parameters
25.2 Variables Published
25.3 Configuring and Using the AvdColregs Behavior
25.4 Automatic Requests for Contact Manager Alerts
25.5 Specifying the Priority Policy - the pwt_*_dist Parameters
25.6 Associating Utility to CPA of Candidate Maneuvers

The AvdColregs behavior will produce IvP objective functions designed to avoid collisions (and near collisions) with another specified vehicle, based on the protocol found in the US Coast Guard Collision Regulations (COLREGS) [54]. The IvP functions produced by this behavior are defined over the domain of posssible heading and speed choices. The utility assigned to a point in this domain (a heading-speed pair) depends in part on the calculated closest point of approach (CPA) between the candidate maneuver leg, and the contact leg formed from the contact's position and trajectory. A further user-defined utility function is applied to the CPA calculation for a candidate maneuver.

Note: This behavior is invoked as BHV_AvdColregsV17 in mission files. The m2_berta_detect mission is an example simulation mission for this behavior. Note finally that the configuration interface for this behavior is very similar to BHV_AvoidCollision, even though the effects of the behavior are quite different. Documenation is evolving for this behavior. If you would like a more detail discussion of the algorithms implementing the COLREGS behavior, please see MIT CSAIL TR-2017-09. As this remains a very active area of research in this lab, further releases and documentation are expected later in 2017 and beyond.

25.1   Configuration Parameters    [top]

Listing 25.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 25.2 - Configuration Parameters Common to Contact Behaviors.

ParameterDescription
bearing_linesIf true, a visual artifict will be produced for rendering the bearing line between ownship and the contact when the behavior is running. Not all behaviors implement this feature.
contactName or unique identifier of a contact to be avoided.
decayTime interval during which extrapolated position slows to a halt.
exit_on_filter_groupIf true, and if an exclusion filter is implemented for this contact behavior, an early exit of the behavior may be allowed when or if the group name changes and no longer satisfies the exclusion filter. The default is false.
exit_on_filter_vtypeIf true, and if an exclusion filter is implemented for this contact behavior, an early exit of the behavior may be allowed when or if the vehicle type changes and no longer satisfies the exclusion filter. The default is false.
exit_on_filter_regionIt true, and if an exclusion filter is implemented for this contact behavior, an early exit of the behavior may be allowed when or if the contact moves into a region that would no longer satisfy the exclusion filter. The default it false.
extrapolateIf true, contact position is extrapolated from last position and trajectory.
ignore_group:If specified, the contact group may not match the given ignore group. If multiple ignore groups are specified, the contact group must be different than all ignore groups. Introduced after Release 19.8.1. Section 23.2
ignore_name:If specified, the contact name may not match the given ignore name. If multiple ignore names are specified, the contact name must be different than all ignore names. Introduced after Release 19.8.1. Section 23.2
ignore_region:If specified, the contact group may be in the given ignore region. If multiple ignore regions are specified, the contact position must be external to all ignore regions. Introduced after Release 19.8.1. Section 23.2
ignore_type:If specified, the contact type may not match the given ignore type. If multiple ignore types are specified, the contact type must be different than all ignore types. Introduced after Release 19.8.1. Section 23.2
match_group:If specified, the contact group must match the given match group. If multiple match groups are specified, the contact group must match at least one match group. Introduced after Release 19.8.1. Section 23.2
match_name:If specified, the contact name must match the given match name. If multiple match names are specified, the contact name must match at least one. Introduced after Release 19.8.1. Section 23.2
match_region:If specified, the contact must reside in the given convex region. If multiple match regions are specified, the contact position must be in at least one match region. The multiple regions essentially can together support a non-convex regins. Introduced after Release 19.8.1. Section 23.2
match_type:If specified, the contact type must match the given match type. If multiple match types are specified, the contact type must match at least one match type. Introduced after Release 19.8.1. Section 23.2
on_no_contact_okIf false, a helm error is posted if no contact information exists. Applicable in the more rare case that a contact behavior is statically configured for a named contact. The default is true.
strict_ignoreIf true, and if one of the ignore exclusion filter components is enabled, then an exclusion filter will fail if the contact report is missing information related to the filter. For example if the contact group information is unknown. The default is true.
time_on_legThe time on leg, in seconds, used for calculating closest point of approach.

Listing 25.3 - Configuration Parameters for the AvdColregs Behavior.

ParameterDescription
completed_dist:Range to contact outside of which the behavior completes and dies.
max_util_cpa_dist:Range to contact outside which a considered maneuver will have max utility. Section 24.6.
giveway_bow_dist:In the giveway consideration, when determining if ok to cross the contact's bow, this range to contact at time of crossing from contact's port to starboard, must be met in order for ownship to consider crossing the contac'ts bow. This is a new option in V19 of this vehavior. If left unspecified, it will revert to the criteria used in previous versions.
min_util_cpa_dist:Range to contact within which a considered maneuver will have min utility. Section 24.6.
no_alert_request:If true will turn off automatic handshaking with the contact manager. Section 24.4.
pwt_grade:Grade of priority growth as the contact moves from the pwt_outer_dist to the pwt_inner_dist. Choices are linear, quadratic, or quasi. Section 24.5.
pwt_inner_dist:Range to contact within which the behavior has maximum priority weight. Section 24.5.
pwt_outer_dist:Range to contact outside which the behavior has zero priority weight. Section 24.5.
refinery:If true, the behavior will create an IvP Function using the refinery, using large pieces for plateau regions. This is a new feature after Release 19.8, and currently only is used in the CPA or in-extremis modes. The default is false.

Listing 25.4 - Example Configuration Block. 

 Behavior = BHV_AvdColregsV17
 {
   // General Behavior Parameters
   // ---------------------------
   name         = avdcollision_                     // example
   pwt          = 200                               // example
   condition    = AVOID = true                      // example
   updates      = CONTACT_INFO                      // example
   endflag      = CONTACT_RESOLVED = $[CONTACT]     // example 
   templating   = spawn                             // example


   // General Contact Behavior Parameters
   // -----------------------------------
       bearing_lines = white:0, green:0.65, yellow:0.8, red:1.0   // example

             contact = henry            // example
               decay = 15,30            // default (seconds)
         extrapolate = true             // default
    on_no_contact_ok = true             // default
         time_on_leg = 60               // default (seconds)


   // Parameters specific to this behavior
   // ------------------------------------
      completed_dist = 500              // default
   max_util_cpa_dist = 75               // default
   min_util_cpa_dist = 10               // default
    no_alert_request = false            // default
           pwt_grade = quasi            // default
      pwt_inner_dist = 50               // default
      pwt_outer_dist = 200              // default
 }

25.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.

  • BCM_ALERT_REQUEST: A request to the contact manager specifying the conditions for contact alerts.
  • CLOSING_SPD_AVD: The current closing speed, in meters per second, to the contact.
  • CONTACT_RESOLVED: Posted with contact name when the behavior completes and dies.
  • RANGE_AVD: The current range, in meters, to the contact.
  • VIEW_SEGLIST: A bearing line between ownship and the contact if configured for rendering.

25.3   Configuring and Using the AvdColregs Behavior    [top]

The AvdColregs behavior produces an objective function based on the relative positions and trajectories between the vehicle and a given contact. The objective function is based on applying a utility to the calculated closest point of approach (CPA) for a candidate maneuver. The user may configure a priority weight, but this weight is typically degraded as a function of the range to the contact. The behavior may be configured for avoidance with respect to a known contact, or it may be configured to spawn a new instance upon demand as contacts present themselves.

25.4   Automatic Requests for Contact Manager Alerts    [top]

The collision avoidance behavior is most commonly configured as a template, meaning instances will not be spawned until an outside event, i.e, posting to the MOOSDB, is received by the helm. This was discussed in detail in Section 7.7. The spawning event for the collision avoidance behavior typically comes from the pBasicContactMgr application. This app therefore needs to be informed, by the collision avoidance behavior, of the desired conditions for generating behavior-spawning alerts. This is done automatically upon helm startup with a posting of the form: 

   BCM_ALERT_REQUEST = id=avd, var=CONTACT_INFO, val="name=$[VNAME] # contact=$[VNAME]", 
                       alert_range=80, cpa_range=100

The values for this posting are chosen as follows:

  • The value from the var component, e.g., CONTACT_INFO in the example above, is the variable named in the updates parameter for the behavior.
  • The value from the alert_range component, e.g., 80 in the example above, is the value specified in the pwt_outer_dist parameter for the behavior. This is the range between ownship and contact beyond which the behavior assigns a priority weight of zero.
  • The value from the alert_range_cpa component, e.g., 100 in the example above, is the value specified in the completed_dist parameter for the behavior. This is the range between ownship and contact beyond which the behavior will initiate its own completion and de-instatiation.

If some other contact manager regime is being used other than pBasicContactMgr, the above automatic posting is probably harmless. However, if one really wants to disable this automatic posting, it can be turned off by setting the configuration parameter no_alert_request to true.

    Implementation note: One may wonder when or how the behavior can make this automatic posting when the behavior is configured as a template. An instance is never spawned until an alert is received, but the alert parameters are posted by the behavior, creating a bit of a chicken or the egg conundrum. The alert request is actually posted by an instance of the behavior created ever so briefly at helm startup. At startup, the helm creates instances of all behaviors, even templates, to ensure the configuration parameters are correct. The ultimate confirmation of behavior parameter correctness is obtained by a behavior instance itself confirming each parameter. The helm will then immediately, before its first iteration, delete any behaviors temporarily created from template behaviors. During this brief startup period, the helm will invoke the function onHelmStart() for all behaviors. This function is defined at the IvPBehavior superclass level just like onRunState(). In the case of the collision avoidance behavior, this function is implemented to make the automatic alert configuration posting to BCM_ALERT_REQUEST.

25.5   Specifying the Priority Policy - the pwt_*_dist Parameters    [top]

The AvdColregs behavior may be configured to increase its priority as its range to the contact diminishes. The priority weight specified in its configuration represents the maximum possible priority applied to the behavior, presumably in close range to the contact. The range at which this maximum priority applies is specified in the pwt_inner_dist parameter. Likewise, the pwt_outer_dist parameter specifies a range to the contact where the priority weight becomes zero, regardless of the priority weight specified in the configuration file. This relationship is shown in Figure 25.1.

Figure 25.1: Parameters for the BHV_AvdColregs behavior: The ownship vehicle is the platform running the helm. The range between the two vehicles affects whether the behavior is active and with what priority weight. Beyond the range specified by pwt_outer_dist, the behavior is not be active. Within the range of pwt_inner_dist, the behavior is active with 100% of its configured priority weight.

    By default, the priority weight decreases linearly between the two depicted ranges. The pwt_grade parameter allows the degradation from maximum priority to zero priority to fall more steeply by setting pwt_grade=quadratric.

25.6   Associating Utility to CPA of Candidate Maneuvers    [top]

  • min_util_cpa_dist: The distance (in meters) between ownship and the contact at the closest point of approach (CPA) for a candidate maneuver, below which the behavior treats the distance as it would an actual collision between the two vehicles.
  • max_util_cpa_dist: The distance (in meters) between ownship and the contact at the closest point of approach (CPA) for a candidate maneuver, above which the behavior treats the distance as having the maximum utility.

Figure 25.2: Parameters for the BHV_AvdColregs behavior. The ownship vehicle is the platform running the helm. The collision_distance is used when applying a utility metric to a calculated closest point of approach (CPA) for a candidate maneuver. A CPA less than or equal to the collision_distance is treated as an actual collision with the lowest utility rating.

    k

Page built from LaTeX source using the texwiki program.