Maintained by: mikerb@mit.edu         Get PDF


1  The FixedTurn Behavior
     1.1 Intended Mission Use
     1.2 The Core Algorithm
     1.3 Configuring A Turn Sequence
     1.4 Stem Distance and Stem Odometry
     1.5 Configuring the Zig Leg Leg Manner
     1.6 Configuring Speed and Speed Modifications
     1.7 Visual Configuration Options
     1.8 Configuration Parameters
     1.9 Variables Published
     1.10 Flags and Macros


1   The FixedTurn Behavior


The FixedTurn behavior allows a vehicle to execute a turn with parameters for configuring the duration of the turn (in degrees), and the commanded changes in desired heading during the turn. 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: FixedTurn Behavior: A vehicle executes a FixedTurn behavior, with a single turn shown. The behavior starts and finishes within a pause of the LegRun behavior using the basic LegRun ability to initiate an event at given point in a leg. (From demo mission s6_legrun).

Turns in a FixedTurn behavior are accomplished by continuously requesting a heading change of a configured fixed value, monitoring the number of degrees in a turn, until the turn completion criteria is reached. Completion criteria is in number of degrees, e.g, a 180 degree turn, or a 270 degree turn.

1.1   Intended Mission Use    [top]


A FixedTurn behavior is configured with a sequence of parameterized turns. A turn configuration will prescribe the turn speed, the fixed delta heading, the total number of degrees for the turn, and the turn direction. For example, the following two turns only differ in direction.

    turn_spec = spd=1.5, mhdg=10, fix=355, turn=star
    turn_spec = spd=1.5, mhdg=10, fix=355, turn=port

Once the turn has been completed, an end flag is published, presumably resulting in the FixedTurn behavior becoming idle. The next time the FixedTurn behavior enters the running state, the next turn in the list of turns will be executed. Presumably, in the meanwhile, while in the idle state, other behaviors in the mission will maneuver the vehicle to a position where the nexted turn is safe for execution. In the intended use case for this behavior, there is typically no obstacle or collision avoidance behaviors running during the turn. The mission author of course is free to do otherwise. However, the behavior was conceived to support the goal of conducting a controlled turn in a safe, hazard-free space, to gauge vehicle performance.

1.2   The Core Algorithm    [top]


The basic FixedTurn behavior will be configured with a sequence of turns, where each turn can be configured in terms of turn direction and size. The intended use for this behavior is for it to be run as a mission interuption of sorts, while the behavior is otherwise transiting. In the example in Figure 1.3, the turn is executing in the middle of the long straight leg of the vehicle running the LegRun behavior. This is from Example Mission N.

OnRunState() Flow Chart    [top]


The primary operation of the behavior is contained within the OnRunState() function. This is shown the flow chart and the pseudocode that follows. Step 1 of this sequence is to update the current value of ownship position and heading, a common first step in many behaviors. For this behavior, ownship heading is the key value for reasoning about turn completion.

Figure 1.2: FixedTurn Behavior Loop Flow Chart: Each iteration of the FixedTurn behavior will proceed through the steps shown, with branching determined by sensed events and the behavior configuration. Details of each step are discuss in their own sections as indicated.

OnRunState() Pseudo Code    [top]


In Step 2, the behavior checks to see if there is a timeout threshold specified for this turn. If there is, the timer is started as soon as the behavior transitions into the running state. The elapsed time since then is compared to the timeout threshold and, if it is exceeded, the behavior regards the turn as completed. In Step 3, the turn is checked for completion based on the turn degrees specified, and how much the vehicle has turned thus far. Although a full 360 degree turn is common, the specified turn may be any value, even beyond 360 degrees.

In Step 4, a behavior completion sequence is conducted. This includes the posting of end flags and inactive flags, if they are provided by the user in the behavior configuration. As well as turn flags, which are separate flags supported uniquely for this behavior, posted whenever a turn has been completed.

In Step 5, depending on whether the current turn is to the port or starboard, the desired heading set point θsp, is set to be offset from ownship current heading θOS by the number of degrees, prescribed in the configuration parameter mod_hdg. This heading set point is passed, in Step 6 to the function where the IvP objective function (ipf) is created. See Section ???.

In Step 7, finally the run flags and active flags are posted this at this stage the behavior is in both the running (non-idle) and active (generates an IvP Function) state. The IvP function is returned to the helm to contribute to the selection of the heading and speed for the current helm iteration.

1.3   Configuring A Turn Sequence    [top]


The FixedTurn behavior is configured with one or more turns, constituting a turn sequence. A single turn is comprised of the following turn elements:

  • turn length: number of degrees constituting a turn
  • heading offset: requested change of heading during the turn
  • turn speed: desired speed during the turn
  • turn direction: port or starboard
  • turn timeout: a max time, in seconds, allowed for the turn
  • turn flags: one or more flags to be posted at turn completion.
   turn_spec = spd=2.5, mhdg=20, fix=360, turn=star, timeout=60
   turn_spec = spd=2.5, mhdg=20, fix=360, turn=port, timeout=60
   turn_spec = spd=4.0, mhdg=10, fix=180, turn=star, flag=STAGE=complete
   turn_spec = spd=4.0, mhdg=10, fix=180, turn=port, flag=STAGE=complete

Figure 1.3: Back-to-back Turns: A vehicle executes a FixedTurn demo mission s6_legrun).

1.4   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.4

Figure 1.4: 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.5   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.6   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.7   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.5. This is enabled by setting:

visual_hints = draw_set_hdg = true

Figure 1.5: 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.8   Configuration Parameters    [top]


Listing 1.1 - Configuration Parameters for the FixedTurn Behavior.

ParameterDescription
fix_turn:The default turn threshold for any turn that does not provide one. The default value is 0 degrees. Section ???.
mod_hdg:The default heading offset, for any turn that does not specify a heading offset. The default value is 20 degrees. Section ???.
turn_dir:The default turn direction for any turn that does specify a direction. The default direction is port. Section ???.
speed:The default speed for any turn that does not specify a turn speed. The default value is 1 meter per second. Section ???.
timeout:The default timeout duration, in seconds, for any turn that does not specify one. The default value is -1, indicating there is not timeout for the turn. Section ???.
turn_delay:feading. Section ???.
turn_spec:A full specification for a scheduled turn. Section ???.
stale_nav_thresh:The number of seconds, after which an update nav position and heading has not been received, befor the behavior throws a warning. Section ???.
radius_rep_var:A MOOS variable where the numerical value of the most recently measure turn radius is posted. By default this variable is unspecified and no publication is made. Section ???.
schedule_repeat:feading. The number of times the full list of turns in the turn schedule will be repeated. The default is zero. Section ???.
visual_hints:Color and other settings for posted visual artifacts. Section ???.

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

1.10   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.4.
  • STEM_ODO: The current ownship distance parallel along the stem line. Section 1.4.
  • STEM_HDG: The stemline heading direction.
  • ZIGS: Total zig legs completed since behavior activation. Section ???.
  • ZAGS: Total zig zags completed since behavior activation. Section ???.
  • 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 ???.
  • 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 ???.
  • 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 ???.
  • ZAGS_TOGO: Remaining zig zags to complete before completion, including the current zig zag being executed. Section ???.

Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF