Contact Related Behaviors of the IvP Helm
Maintained by: mikerb@mit.edu Get PDF
src: project-pavlab/chapters/chap_bhv_multi
1 Contact Related Behaviors of the IvP Helm
1.1 Static Versus Dynamically Spawned Behaviors
1.2 Exclusion Filters
1.2.1 Types of Contact Exclusion Filters
1.2.2 Configuring Exclusion Filters Globally or Locally
1.2.3 Enabling Strict Filtering
1.2.4 Failing an Exclusion Filter on Spawned Behavior
1.3 Contact Flags
1.3.1 Contact Flag Trigger Tags
1.3.2 Contact Flag Macros
1.4 Properties Common to All Contact Related Behaviors
1.4.1 Common Behavior Configuration Parameters
1 Contact Related Behaviors of the IvP Helm
The section contains is a description of five behaviors currently written for the helm that reason about relative position to another vehicle or contact.
- The AvoidCollision behavior
- The AvdColregsV19 behavior
- The CutRange behavior
- The Shadow behavior
- The Trail behavior
Each behavior needs to be continuously updated with the position and trajectory of a given contact. The helm subscribes to the MOOS variable, NODE_REPORT, which may have content similar to:
NODE_REPORT= "NAME=alpha,TYPE=UUV,MOOSDB_TIME=39.01,TIME=1252348077.59, X=51.71,Y=-35.50,LAT=43.824981,LON=-70.329755,SPD=2.00,HDG=118.85, YAW=118.84754,DEPTH=4.63,LENGTH=3.8,MODE=SURVEYING"
This contact information is stored in the helm information buffer for any behavior that wishes to retrieve it on any iteration. Since each behavior type needs to reason about contact information, the common code for this is handled in superclass called IvPContactBehavior. So for these behaviors, the class hierarchy looks like:
Figure 1.1: IvP Contact Behaviors: The contact-related behaviors share a common superclass to streamline the development of contact behaviors and provide a level consistency between behaviors.
1.1 Static Versus Dynamically Spawned Behaviors [top]
A contact behavior may be configured in one of two ways. The simplest way is to reason about a particular contact with a name known at mission time. This is more appropriate for a behavior that needs to operate on one contact at a time, such as a trail or cut-range behavior. While it is technically possible to try to cut-range or trail multiple contacts simultaneously, and the IvP solver will s upport such an attempt, typically such behaviors are focused on a single contact. Configuration of the behavior simply names the contact
contact = mothership
A second type of configuration is possible when we would like to have several simultaneous instances of the same behavior, as during collision avoidance with multiple contacts. In this case the behavior is configured to enable templating, and the contact name is left unspecified until a new contact emerges:
templating = spawn contact = to_be_determined
A templating contact behavior works closely with a contact manager, either the pBasicContactMgr app or the newer version, pContactMgrV20. The contact manager is responsible for generating the MOOS posting events that trigger the spawning of a new behavior. As depicted in below, the contact manager applies a certain configurable criteria to a contact, and if it passes that criteria, it generates an alert to the helm, resulting in a spawned behavior.
Figure 1.2: Relationship between the contact manager and spawned contact-related behaviors: (1) A contact closes range to ownship, crossing a range threshold. (2) The contact manager makes note and changes the internal record associated with the contact. (3) An alert it generated and received by the helm. (4) The helm spawns a new contact-related behavior dedicated to this contact.x
Typically the contact manager criteria for generating an alert is based on the range of the contact to ownship. However, the contact manager may also utilize additional filters, providing user configurable selectivity as to which contacts generate alerts resulting in behavior spawnings. These filters may be configured at the contact manager level, e.g., ignore all contacts of type sailboat. Or they may be configure at the behavior level, e.g., one collision avoidance behavior matches sailboats, and another collision avoidance behavior matches motorboats. This is covered in part in the documentation of pContactMgrV20, but portion that is accessible through behavior configuration is described next.
1.2 Exclusion Filters [top]
An exclusion filter is tool for allowing the contact manager and/or the helm to treat distinct contacts differently, or ignore selectively handle contacts with a certain property. The contact manager has an exclusion filter, and all behaviors have an exclusion filter. They can safely ignored if one wishes to simple treat all contacts equally, but they can provide some powerful options when applied to particular situation.
1.2.1 Types of Contact Exclusion Filters [top]
Contact exclusion filters may be configured around four different types of properties:
- name: This is the most direct method but rather brittle. But if there is a particular named vehicle that you'd like to handle differently, it can be just called out by name.
- type: The vehicle type is part of the incoming NODE_REPORT message, e.g., UUV, USV and so on.
- group: The vehicle group is part of the incoming NODE_REPORT message, e.g., friendly, foe and so on.
- region: A convex polygon describing a region of the operation area.
Each of the above four properties can be configured as match or ignore filters. For example, match_type=kayak indicates that the contact must by of type kayak. Likewise ignore_type=kayak indicates that the contact must be of some type other than kayak. The same is true for name, group, and region properties. This makes eight possible configuration parameters available to all contact behaviors when templating is enabled:
- match_group and ignore_group
- match_name and ignore_name
- match_type and ignore_type
- match_region and ignore_region
Multiple entries for each property may be used. If for example multiple match_name configurations are used, a contact will pass the filter if it matches at least one. If multiple ignore_name configurations are used, a contact will pass the filter only if it has a name different from all.
The region property is a bit different from the other three properties. While a contact's name, type, and group properties tend not to change as a mission unfolds, the contact position does. When the region is used by the contact manager as a filter it applies only to that moment in time. If, for example, the contact was outside a match_region but then enters it, it will now pass the filter and an alert will be generated, provided all other filter and range criteria are met. Likewise if the contact manager generated an alert for a contact, but then moved out of a match_region or into an ignore_region, the previously generated alert will not somehow be retracted.
One last note about region filters: non-convex regions may be implemented by using two or more convex regions that "cover" the desired non-convex region. And consistent with the above discussion, the approximating convex regions may harmlessly overlap.
1.2.2 Configuring Exclusion Filters Globally or Locally [top]
As shown in above, the contact manager is the gatekeeper for sending the helm alert messages that may trigger the spawning of the behavior. Users can configure the exclusion filters in one of two ways:
- Global configuration via the contact manager, pContactMgrV20, or
- Local configuration via individual behaviors in the helm.
- A third configuration method, dealing with behaviors after they have been spawned, is discussed in .
The former is method is arguably more convenient but the filters apply to all behavior templates equally. If the contact manager is configured to ignore sailboats, there is no way to otherwise configure the helm to have a spawnable behavior that will handle sailboats. Maybe you really do want to just ignore all sailboats. But if instead you'd like to have one type of behavior ignore sailboats and another type of behavior ignore motorboats, then the filter needs to be configured at the behavior level instead.
below depicts a helm locally configured with two distinct behavior templates, with the filter configuration done in the helm configuration. In this way, one distinct behavior is used for Contact Abe, and another for Contact Ben. It may be that both are collision avoidance behaviors, but perhaps the safety region around Abe is larger than Ben. Likewise the filter could have involved the vehicle type, group or region.
Figure 1.3: Configuration of contact filter at the local behavior level: Compare with , the match filters are provided in the helm configuration rather than the contact manager configuration. This allows different behavior types or templates to work with different contacts. In the previous example in every matched contact was handled by the same behavior type.
Using both global and local exclusion filters is certainly allowable, but keep in mind that if a contact is excluded at the global contact manager level, it does not matter what configurations are specified at the local behavior level.
1.2.3 Enabling Strict Filtering [top]
Filtering based on the contact type or group depends on this information being known about the contacts. Typically this is embedded in each incoming NODE_REPORT. In some cases, especially in sensor-based contact management, this information may not be known.
For match filtering, this is not an issue. This is because the spirit of match filtering is that, for example if we say that a contact must be of type motor-boat, and the contact type is unknown, it's pretty clear that condition is not satisfied and thus the contact with unknown type is filtered out.
With ignore filtering it is more ambiguous. This is because the spirit of ignore filtering is that, for example if we say that a contact cannot be of type motor-boat, and the contact type is unknown, we might be inclined to say that it should not be filtered out. The user may however want to be strict about this and say that it should be filtered out since we don't know the contact type, and for all we know it could be a motor-boat.
To allow the user to have some control and be explicit about the above situation, filtering can be configured to be strict by setting strict_ignore to be true or false. The below set of examples hopefully makes this clear.
Contact Type | Ignore Group | Strict Ignore | Filtered Out |
sailboat | sailboat | true or false | yes |
sailboat | motorboat | true or false | no |
unknown | motorboat | false | no |
unknown | motorboat | true | yes |
The strict_ignore parameter, as with other filtering parameters, is also used in configuring the contact manager, applied globally and overriding any local filter behavior configurations.
1.2.4 Failing an Exclusion Filter on Spawned Behavior [top]
The primary use of exclusion filters is to affect which behaviors are spawned. However, the configured criteria is based on the vehicle properties of group, name, platform type and location, and these properties may change after a behavior is spawned. Normally a contact behavior does not complete, and exit, until it has gone out of range. The user may also opt to have the behavior exit if its properties change after spawning such that it no longer satisfies the original exclusion filter.
A contact behavior will accept the following three configuration parameters:
- exit_on_filter_group: If true, will apply the current known group name to an exclusion filter.
- exit_on_filter_vtype: If true, will apply the current known vehicle to an exclusion filter.
- exit_on_filter_region: If true, will apply the current known vehicle position to the region component of an exclusion filter.
The default for all parameters is false. A common example is when a detected change of group name or vehicle type is learned via communications or sensors. A vehicle may also move into a region where a behavior may be configured to be no longer concerned with a contact. Failing the exclusion filter in a spawned behavior will simply result in the exit/removal of the behavior from the helm, and deletion of the behavior from memory space.
Unlike the group, vehicle type and region components of an exclusion filter, the vehicle name component of the exclusion filter is not re-assesed after a behavior has spawned, since contact behaviors are essentially keyed by vehicle name.
While the above three parameters are supported by all contact behaviors, not all contact behaviors respect this additional feature. Currently (Aug 2021) only the collision avoidance behaviors (CPA based and COLREGS based) support this feature. Support in additional behaviors will be rolled in on future updates.
1.3 Contact Flags [top]
Available after Release 19.8.1, contact flags are an additional way to configure behaviors to post configurable information upon events based on the relative position between ownship and the contact. Most other types of behavior flags contain simply a variable value pair. For example:
endflag = RETURN = true
Contact flags allow the user to check for expected results over the course of a mission. It also allows missions to be configured on contact related events such as posting a message to command-and-control or to another vessel when the relative position or range to a contact has been achieved.
1.3.1 Contact Flag Trigger Tags [top]
With contact flags, a trigger tag is included with the flag configuration corresponding to certain events. For example, the @cpa trigger tag will ensure the configured flag will be posted at the time of an observed CPA between ownship and the contact:
cnflag = @cpa SEND_MESSAGE = true
The trigger tag is always at the beginning of the flag configuration with at least one white space between the tag and the rest of the flag configuration. The trigger tags only apply to contact flags, for contact behaviors, using the cnflag parameter.
Supported trigger flags:
Trigger Flag | Meaning |
@cpa: | When the closes point of approach is observed |
@os_passes_cn: | When ownship passes contact's beam |
@os_passes_cn_port | When ownship passes contact's port beam |
@os_passes_cn_star: | When ownship passes contact's starboard beam |
@cn_passes_os | When ownship passes contact's beam |
@cn_passes_os_port | When contact passes contact's port beam |
@cn_passes_os_star | When contact passes contact's starboard beam |
@os_crosses_cn | When ownship crosses contact's side |
@os_crosses_cn_bow | When ownship crosses contact's side fore of contact |
@os_crosses_cn_stern | When ownship crosses contact's side aft of contact |
@cn_crosses_os | When contact crosses ownship's side |
@cn_crosses_os_bow | When contact crosses ownship's side fore of ownship |
@cn_crosses_os_stern | When contact crosses ownship's side aft of ownship |
An example is given in below of an encounter between ownship and a contact. The relevant trigger tags are shown.
Figure 1.4: An example encounter with trigger tags: As a contact passes ownship various trigger tags become satisfied. The first two trigger tags are based purely on range and are triggered as the vehicle enters the range. The last trigger tag is triggered as the contact opens range to 60. As the two vehicles pass, several trigger tags are satisfied simultaneously.
1.3.2 Contact Flag Macros [top]
Contact flags have a number of supported macros that may be expanded in any value component of a posting. For example, the range between ownship and the contact can be used in a cnflag posting:
cnflag = @cpa RANGE_TO_CONTACT = $[RANGE]
The value of $[RANGE]
is determined at the moment the flag is triggered. Supported macros:
MACROS | Meaning |
$[RANGE] | Range between ownship and contact |
$[CN_NAME] | Name of the contact |
$[CN_GROUP] | Name of the contact |
$[CN_VTYPE] | Vehicle type of the contact |
$[ROC] | Rate of Closure between ownship and the contact |
$[OS_CN_REL_BNG] | Relative bearing of the contact to ownship |
$[CN_OS_REL_BNG] | Relative bearing of ownship to the contact |
$[BNG_RATE] | Bearing Rate |
$[CN_SPD_IN_OS_POS] | Speed of contact in the direction of ownship position |
$[OS_FORE_OF_CN] | true if ownship is currently fore of the contact |
$[OS_AFT_OF_CN] | true if ownship is currently aft of the contact |
$[OS_PORT_OF_CN] | true if ownship is currently on port side of the contact |
$[OS_STAR_OF_CN] | true if ownship is currently on starboard side of the contact |
$[CN_FORE_OF_OS] | true if the contact is currently fore of ownship |
$[CN_AFT_OF_OS] | true if the contact is currently aft of ownship |
$[CN_PORT_OF_OS] | true if the contact is currently on port side of ownship |
$[CN_STAR_OF_OS] | true if the contact is currently on starboard side of ownship |
1.4 Properties Common to All Contact Related Behaviors [top]
Contact related behaviors are distinct from non contact related behaviors in that they share a fair amount of functionality in dealing with their contact of interest. Contact related behaviors are implemented as a subclass of the IvPContactBehavior class, which is a subclass of the IvPBehavior class. Much of the shared functionality of contact related behaviors is implemented in the former. The shared functionality includes several common configuration parameters, and mechanisms for reasoning about the closest point of approach (CPA) between the platform and contact for candidate maneuver considerations. These topics are discussed next, prior to the sections on the behaviors themselves.
1.4.1 Common Behavior Configuration Parameters [top]
The following set of parameters are common to all the contact related behaviors:
Listing 1.1 - Configuration Parameters Common to Contact Behaviors.
Parameter | Description |
bearing_lines | If 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. |
contact | Name or unique identifier of a contact to be avoided. |
decay | Time interval during which extrapolated position slows to a halt. |
exit_on_filter_group | If 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_vtype | If 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_region | It 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. |
extrapolate | If 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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
on_no_contact_ok | If 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_ignore | If 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_leg | The time on leg, in seconds, used for calculating closest point of approach. |
The contact parameter specifies the contact name or identifier. This name is used as a key by the behaviors for querying the contact position and trajectory. It must match the contact name received by the helm in an incoming NODE_REPORT message. The contact name may be specified at helm launch time, but it may also be specified at run time if the behavior is configured as a template for dynamic spawning. The latter is more common, for example, in a collision avoidance behavior where the name or ID of the contact is not known until a contact manager alerts the helm. See the Berta mission for an example of this usage.
The extrapolate and decay parameters are used to address the situation where a contact/node report has significant delays between updates. Extrapolation is enabled by setting the extrapolate parameter to true, which is the default. The behavior may be configured to have limited extrapolation by setting a decay time interval. The extrapolated position is based on the last known contact position, heading and speed. The speed used for calculations may begin decaying at the beginning of the decay interval and will have decayed to zero at the end of the decay interval. The default setting is "decay = 15, 30", in seconds. The idea is shown in .
Figure 1.5: Contact Extrapolations: Contact related behaviors may use an extrapolated position of the contact to compensate for periods of no new reports for the contact. A decay period may be used to effectively halt the extrapolated contact position after some specified period of time. In the example in this figure, the decay window is [15, 30] seconds. After 30 seconds, the extrapolated position does not extend further.
The on_no_contact_ok parameter determines how the behavior should regard the situation where it is unable to find any information about a given contact. If this parameter is set to true, the default, then the behavior will post a warning, BHV_WARNING if no contact information is found. Otherwise the behavior will post an error with BHV_ERROR. In the latter case the helm may interpret this as request to halt the helm and come to zero speed and depth.
The time_on_leg parameter refers to the behavior's calculations of the closest point of approach (CPA) for candidate maneuver legs. A candidate maneuver leg is defined by a the heading, speed, and time-on-leg components. Longer time-on-leg settings tend to report deceivingly worrisome CPA distances even for contacts at a great distance, and lower time-on-leg settings tend to report deceivingly comfortable CPA distances even for vehicles at relatively low distances. The default setting for this parameter is 60 seconds.
Document Maintained by: mikerb@mit.edu
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF