The ZigZag Behavior

Maintained by: mikerb@mit.edu         Get PDF

src: project-pavlab/bhvdocs/bhv_zigzag

1  The ZigZag Behavior
     1.1 Configuring the Number of Legs and Direction
     1.2 Stem Distance and Stem Odometry
     1.3 Configuring the Zig Leg Leg Manner
     1.4 Configuring Speed and Speed Modifications
     1.5 Visual Configuration Options
     1.6 Configuration Parameters
     1.7 Variables Published
     1.8 Flags and Macros

1   The ZigZag Behavior

The ZigZag behavior allows a vehicle to excute a series of port-starboard turns, creating a zigzag pattern. The behavior is primarily motivated by supporting surface vehicle shake-out tests, but may be used in any mission where this pattern is desired. The behavior can be configured with varying number of turns, order of turns, and the number of degrees for each turn, and the manner in which the turn is requested.

Figure 1.1: ZigZag Behavior: A vehicle executes a ZigZag behavior, with a pair of zigzags. The behavior starts and finishes within a LegRun behavior using the basic LegRun ability to initiate an event at given point in a leg. (From demo mission s6_zigzag)

The basic ZigZag behavior will be configured with (a) the number of zig legs desired, (b) the target change in ownship heading comprising the satisfaction of a zig leg, (c) the initial zig direction, and a few other parameters. The idea is shown in Figures 1.1 and 1.2.

Figure 1.2: ZigZag Behavior: A zig leg is comprised of a change in heading to either the port or starboard side. Once the change of heading has been achieved, the next zig leg is executed. When all scheduled zig legs have been executed. the behavior completes.

1.1   Configuring the Number of Legs and Direction    [top]

A zigzag consists of two zig legs. The behavior can be configured by specifying the amount of zig zags or zig legs. They following two parameters are equivalent:

max_zig_legs = 6
max_zig_zags = 3

By default, the first zig leg will be a turn in the port direction. This can be overridden with:

zig_first = star

When the target number of zig legs has been completed, the behavior itself will complete, posting its end flags as any other behavior. Additionally, like any other behavior, it may be configured with perpetual=true, to allow additional zigzag runs. The s6_zigzag example mission is configured in this way.

Several macros are supported to reveal state during a mission. The total number of zig legs completed, total number of zig zags completed, current zig leg direction, total zig legs remaining. See Section 1.8.

1.2   Stem Distance and Stem Odometry    [top]

The ZigZag behavior establishes a stem line when it begins its sequence of zig legs. Two distances relative to the stem line are updated during the sequence of zig legs. The stem distance is the current distance of ownship perpendicular to the stem line. The stem odometry is the current distance of ownship parallel to the stem line as shown in Figure 1.3

Figure 1.3: Stem Line Metrics: The stem distance and stem odometry.

The stem odometry can be optionally used as a completion criteria for the behavior (as opposed to relying solely on a maximumn number of zig legs). This can be configured with:

max_stem_odo=100

With the above configuration, the behavior will complete after the max number of zig legs is reached, or when the stem odometry exceeds 100 meters, whichever comes first.

These two values are in accessible in the macros $[STEM_DIST] and $[STEM_ODO]. As with any macro, they can be published as part of any behavior flag. For exemple:

endflag=TOTAL_STEM_ODO=$[STEM_ODO]

Or, for a flag available only to ZigZag behavior:

zigflag=CURR_STEM_DIST=$[STEM_DIST]

The stem odometry is stem distance are reset to zero when the behavior completes or becomes idle.

1.3   Configuring the Zig Leg Leg Manner    [top]

A zig leg is accomplished by achieving a requested change in heading. The change is relative to a stem heading. This stem heading value can be explicitly set to a value, e.g.,

stem_hdg=90

Alternatively, and arguably more common, the stem heading can be set to the ownship current heading when the behavior enters the running state. To use this mode:

stem_on_active=true

The delta heading is specified relative to the stem heading with the parameter:

zig_angle=45

A tolerance for achieving the heading change can be specified with the following parameter, given in degrees:

hdg_thresh=2

By default the tolerance threshold is zero degrees.

By default, the change in heading is affected by the "normal" means of continuously requesting a heading value N degrees offset from the stem heading. The rate of heading change will presumably be modulated by the vehicle, e.g., PID, controller. The heading actuator value typically approaching zero the closer the measured heading nears the requested heading.

As an alternative means, the behavior can be configured to achieve the heading change by constantly requesting a heading change of N degrees, relatively to the updated current vehicle heading as the vehicle turns. This is accomplished with the pair of parameters:

fierce_zigging=true
zig_angle_fierce=10

In this mode, presumably the actuator setting will remain in an constant setting since the difference between the target heading and current ownship heading remains constant through the turn. Regardless of which method is used, the zig leg is still considered complete when the intial heading change has been achieved (within the tolerance of the hdg_thresh).

1.4   Configuring Speed and Speed Modifications    [top]

The goal speed of the ZigZag behavior is configured by setting:

speed = 1.5

The default speed is zero, essentially making this a mandatory parameter. A negative requested speed will result in a configuration error. A speed exceeding the prevailing max speed of the helm configuration will simply be clipped without an error.

The speed can be updated during the mission using the behavior updates parameter, just like any parameter for any other behavior. It may be convenient, however, to modify the speed by requesting a delta value relative to the current speed. This can be done with:

mod_speed = 0.2, or
mod_speed = -0.1

The behavior goal speed will be modified by applying the delta value. A resulting goal speed less than zero or greater than the helm's prevailing max speed will simply be clipped without an error warning. The goal speed can be modified to the original speed setting with:

mod_speed = reset

The value stored in memory, as the "reset speed", is the value whenever the speed parameter is set. As discussed above, this can be set in the initial behavior configuration, or with dynamic updates.

The value of the speed parameter can also be configured to be set to the current ownship speed upon behavior activation:

spd_on_active = true

By default this is false. If enabled, when the behavior transitions from idle to running state, the speed is set to ownship speed, and this is the speed applied if mod_speed=reset is later applied.

1.5   Visual Configuration Options    [top]

On occasion it is useful to have a visual marker indicating the current goal heading. When enabled, the goal heading is rendered as a short line segment from the center of the vehicle as shown in Figure 1.4. This is enabled by setting:

visual_hints = draw_set_hdg = true

Figure 1.4: ZigZag Behavior: A vehicle executes a ZigZag behavior, with leg. (From demo mission s6_zigzag)

When fierce_zigging is enabled, the behavior uses a different heading value to achieve the goal heading. This heading can be visualized instead, or alongside, of the goal heading by setting:

visual_hints = draw_req_hdg = true

1.6   Configuration Parameters    [top]

Listing 1.1 - Configuration Parameters for the ZigZag Behavior.

ParameterDescription
fierce_zigging:Effect zig maneuver by requesting constant delta relative heading. Section 1.3.
hdg_thresh:Angle difference to target zig heading for zig leg completion. Section 1.3.
mod_speed:Apply a delta speed modification to the prevailing speed value. Typically applied during a mission rather than at mission startup. Section 1.4.
max_zig_legs:Number of zig legs required for behavior completion. Section 1.1.
max_stem_odo:Max distance parallel to the stem line, beyond which results in behavior completion, equivalent to reaching max_zig_legs. Section 1.1.
speed:Speed in m/s to maintain during zig zag maneuvers. Default value is zero (must be set). Section 1.4.
speed_on_active:The goal speed is set to the current ownship speed when the behavior becomes active. Default is false. Section 1.4.
stem_hdg:Heading around which zig zag maneuvers will vary. Section 1.3.
stem_on_active:Stem heading is set to ownship heading when the behavior becomes active. Default is false. Section 1.3.
visual_hints:Viewing Options. See Section 1.5.
zig_angle:Target relative angle required for zig leg completion. Section 1.3.
zig_angle_fierce:Relative heading requested to effect a zig leg. Section 1.3.
zig_first:Which side for initial zig first. Default is port. Other option is star. Section 1.1.

Listing 1.2 - Example Configuration Block. 

 Behavior = BHV_ZigZag
 {
   name      = zig
   pwt       = 100
   condition = MODE==ZIGZAG
   endflag   = ZIGGING = false

   updates   = ZIG_UPDATE
   perpetual = true

             speed = 2.0   // meters per sec
    stem_on_active = true
         zig_first = star
      max_zig_zags = 2
         zig_angle = 45
  zig_angle_fierce = 30

      max_stem_odo = 100

      visual_hints = draw_set_hdg = true
      visual_hints = draw_req_hdg = true

        hdg_thresh = 2
    fierce_zigging = false
 }

1.7   Variables Published    [top]

The below MOOS variables will be published by the behavior during normal operation, in addition to any configured flags.

  • VIEW_SEGLIST: A visual cue for rendering the requested zig angle, if either draw_set_hdg=true or draw_req_hdg=true in the visual_hints. See Section 1.5.

1.8   Flags and Macros    [top]

The ZigLeg behavior supports the below set of event flags in addition to the standard behavior flags, e.g., endflags, runflags. These are:

  • zigflag: Posted each time a zig leg is completed. These flags are posted twice as frequent as zagflag postings.
  • zagflag: Posted each time a zig zag is completed. These flags will be posted half as frequent as zigflag postings.
  • starflag: Posted each time a zig leg started in the starboard direction.
  • portflag: Posted each time a zig leg started in the port direction.
  • starflagx: Posted each time a zig leg has completed in the starboard direction.
  • portflagx: Posted each time a zig leg has completed in the port direction.

The folowing macros are supported in the ZigZag behavior. These macros will be expanded in any event flag, including event flags defined for all IvP behaviors as well as event flags defined only for the ZigZag behavior.

  • ODO: Total odometry distance since the behavior became active.
  • ZIG_ODO: Total odometry distance since the behavior began its current zig leg.
  • ZAG_ODO: Total odometry distance since the behavior began its current zig zag.
  • STEM_DIST: The current ownship distance perpendicular from the stem line. Section 1.2.
  • STEM_ODO: The current ownship distance parallel along the stem line. Section 1.2.
  • STEM_HDG: The stemline heading direction.
  • ZIGS: Total zig legs completed since behavior activation. Section 1.1.
  • ZAGS: Total zig zags completed since behavior activation. Section 1.1.
  • ZIGS_EVER: Total zig legs completed since this activation and all prior activations. For example if perpetual=true and repeated activations as in example mission s6_zigzag. Section 1.1.
  • ZAGS_EVER: Total zig zags completed since this activation and all prior activations. For example if perpetual=true and repeated activations as in example mission s6_zigzag. Section 1.1.
  • ZIG_START_SPD: Ownship speed at the start of the current zig leg.
  • ZIG_MIN_SPD: Minimum ownship speed recorded since the start of the current zig leg.
  • ZIG_SPD_DELTA: Change in ownship speed since the start of the current zig leg.
  • ZIGS_TOGO: Remaining zig legs to execute before completion, including the current zig leg being executed. Section 1.1.
  • ZAGS_TOGO: Remaining zig zags to complete before completion, including the current zig zag being executed. Section 1.1.

Document Maintained by: mikerb@mit.edu        
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF