<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\section{The ZigZag Behavior}
%=====================================================================
\label{sec_bhv_zigzag}

The {\em 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.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/zigzag1.png}
  \caption{{\bf 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 \var{s6\_zigzag})}
  \label{fig_bhv_zigzag_gif}
\gif{figures/zigzag1.gif}
\end{figure}
\vspace{0.1in}

\noindent
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 \ref{fig_bhv_zigzag_gif} and \ref{fig_zigzag_idea}.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.5\textwidth]{figures/zigzag_idea.png}
  \caption{{\bf 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.}
  \label{fig_zigzag_idea}
\end{figure}
\vspace{0.1in}

%=======================================================================
\subsection{Configuring the Number of Legs and Direction}
\label{sec_zig_legs}

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

\vspace{0.1in}
\noindent
\bvar{max\_zig\_legs = 6} \newline
\bvar{max\_zig\_zags = 3}

\vspace{0.1in}
\noindent
By default, the first zig leg will be a turn in the port direction. This can
be overridden with:

\vspace{0.1in}
\noindent
\bvar{zig\_first = star}

\vspace{0.1in}
\noindent
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 \bvar{perpetual=true}, to allow additional zigzag runs. The
\var{s6\_zigzag} example mission is configured in this way.

\vspace{0.1in}
\noindent
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
\ref{sec_zig_fmac}.

%=======================================================================
\subsection{Stem Distance and Stem Odometry}
\label{sec_zig_stem_odo}

The \var{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 {\em stem distance} is the current distance of ownship perpendicular
to the stem line. The {\em stem odometry} is the current distance of ownship parallel
to the stem line as shown in Figure \ref{fig_zig_stem_odo}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/zig_stem_odo.png}
  \caption{{\bf Stem Line Metrics}: The stem distance and stem odometry.}
  \label{fig_zig_stem_odo}
\end{figure}
\vspace{0.1in}

\noindent
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:

\vspace{0.1in}
\noindent
\bvar{max\_stem\_odo=100}

\vspace{0.1in}
\noindent
With the above configuration, the behavior will complete after the max
number of zig legs is reached, {\em or} when the stem odometry exceeds
100 meters, whichever comes first.

\vspace{0.1in}
\noindent
These two values are in accessible in the macros \pvar{\$[STEM\_DIST]}
and \pvar{\$[STEM\_ODO]}. As with any macro, they can be published as part of
any behavior flag. For exemple:

\vspace{0.1in}
\noindent
\pvar{endflag=TOTAL\_STEM\_ODO=\$[STEM\_ODO]}

\vspace{0.1in}
\noindent
Or, for a flag available only to \var{ZigZag} behavior: 

\vspace{0.1in}
\noindent
\pvar{zigflag=CURR\_STEM\_DIST=\$[STEM\_DIST]}

\vspace{0.1in}
\noindent
The stem odometry is stem distance are reset to zero when the behavior completes
or becomes idle. 

%=======================================================================
\subsection{Configuring the Zig Leg Leg Manner}
\label{sec_zig_manner}

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

\vspace{0.1in}
\noindent
\bvar{stem\_hdg=90}

\vspace{0.1in}
\noindent
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:

\vspace{0.1in}
\noindent
\bvar{stem\_on\_active=true}

\vspace{0.1in}
\noindent
The delta heading is specified relative to the stem heading with the
parameter:

\vspace{0.1in}
\noindent
\bvar{zig\_angle=45}

\vspace{0.1in}
\noindent
A tolerance for achieving the heading change can be specified with the
following parameter, given in degrees:

\vspace{0.1in}
\noindent
\bvar{hdg\_thresh=2}

\vspace{0.1in}
\noindent
By default the tolerance threshold is zero degrees.

\vspace{0.1in}
\noindent
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.

\vspace{0.1in}
\noindent
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:

\vspace{0.1in}
\noindent
\bvar{fierce\_zigging=true} \newline
\bvar{zig\_angle\_fierce=10}

\vspace{0.1in}
\noindent
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 \bvar{hdg\_thresh}).

%=======================================================================
\subsection{Configuring Speed and Speed Modifications}
\label{sec_zig_spd}

The goal speed of the \var{ZigZag} behavior is configured by setting:

\vspace{0.1in}
\noindent
\bvar{speed = 1.5}

\vspace{0.1in}
\noindent
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.

\vspace{0.1in}
\noindent
The \bvar{speed} can be updated during the mission using the behavior
\bvar{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:

\vspace{0.1in}
\noindent
\bvar{mod\_speed = 0.2}, or \newline
\bvar{mod\_speed = -0.1}

\vspace{0.1in}
\noindent
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:

\vspace{0.1in}
\noindent
\bvar{mod\_speed = reset}

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

\vspace{0.1in}
\noindent
The value of the \bvar{speed} parameter can also be configured to be set
to the current ownship speed upon behavior activation:

\vspace{0.1in}
\noindent
\bvar{spd\_on\_active = true}

\vspace{0.1in}
\noindent
By default this is false. If enabled, when the behavior transitions from idle
to running state, the \bvar{speed} is set to ownship speed, and this is the
speed applied if \bvar{mod\_speed=reset} is later applied.


%=======================================================================
\subsection{Visual Configuration Options}
\label{sec_zig_visuals}

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 \ref{fig_zigzag2}. This is
enabled by setting:

\vspace{0.1in}
\noindent
\bvar{visual\_hints = draw\_set\_hdg = true}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/zigzag2.png}
  \caption{{\bf ZigZag Behavior}: A vehicle executes a ZigZag behavior, with
    leg. (From demo mission \var{s6\_zigzag})}
  \label{fig_zigzag2}
\gif{figures/zigzag2.gif}
\end{figure}
\vspace{0.1in}

\vspace{0.1in}
\noindent
When \bvar{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: 

\vspace{0.1in}
\noindent
\bvar{visual\_hints = draw\_req\_hdg = true}


%=======================================================================
\subsection{Configuration Parameters}

%\input{includes/bhv_all_properties}

\vspace{0.15in}
\begin{listing}{Configuration Parameters for the ZigZag Behavior}
\label{lst_bhv_zigzag}
\small
\renewcommand{\arraystretch}{1.15}
\begin{longtable}{rp{0.7\textwidth}} 

  {\bf Parameter} &amp; {\bf Description} \\  

  \bvar{fierce\_zigging}: &amp; Effect zig maneuver by requesting constant
  delta relative heading. Section \ref{sec_zig_manner}. \\

  \bvar{hdg\_thresh}: &amp; Angle difference to target zig heading for zig leg
  completion. Section \ref{sec_zig_manner}. \\

  \bvar{mod\_speed}: &amp; Apply a delta speed modification to the prevailing
  \bvar{speed} value. Typically applied during a mission rather than at
  mission startup. Section \ref{sec_zig_spd}. \\

  \bvar{max\_zig\_legs}: &amp; Number of zig legs required for behavior completion.
  Section \ref{sec_zig_legs}. \\

  \bvar{max\_stem\_odo}: &amp; Max distance parallel to the stem line, beyond which
  results in behavior completion, equivalent to reaching \bvar{max\_zig\_legs}.
  Section \ref{sec_zig_legs}. \\

  \bvar{speed}: &amp; Speed in m/s to maintain during zig zag maneuvers.
  Default value is zero (must be set). Section \ref{sec_zig_spd}. \\

  \bvar{speed\_on\_active}: &amp; The goal speed is set to the current
  ownship speed when the behavior becomes active. Default is
  \var{false}. Section \ref{sec_zig_spd}. \\

  \bvar{stem\_hdg}: &amp; Heading around which zig zag maneuvers will vary.
  Section \ref{sec_zig_manner}. \\

  \bvar{stem\_on\_active}: &amp; Stem heading is set to ownship heading when
  the behavior becomes active. Default is \var{false}. Section
  \ref{sec_zig_manner}. \\

  \bvar{visual\_hints}: &amp; Viewing Options. See Section \ref{sec_zig_visuals}. \\
  
  \bvar{zig\_angle}: &amp; Target relative angle required for zig leg completion.
  Section \ref{sec_zig_manner}. \\

  \bvar{zig\_angle\_fierce}: &amp; Relative heading requested to effect a zig leg.
  Section \ref{sec_zig_manner}. \\
  
  \bvar{zig\_first}: &amp; Which side for initial zig first. Default is \var{port}.
  Other option is \var{star}.  Section \ref{sec_zig_legs}. \\


\end{longtable}
\end{listing}
\normalsize

\vspace{0.15in}
\begin{listing}{Example Configuration Block}
\label{lst_bhv_zig}

\begin{fileverb}
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
}
\end{fileverb}
\end{listing}


%=======================================================================
\subsection{Variables Published}

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

\begin{packed_itemize}[2]

\item \mvar{VIEW\_SEGLIST}: A visual cue for rendering the requested
  zig angle, if either \bvar{draw\_set\_hdg=true} or
  \bvar{draw\_req\_hdg=true} in the \bvar{visual\_hints}. See Section
  \ref{sec_zig_visuals}.

\end{packed_itemize}

%=======================================================================
\subsection{Flags and Macros}
\label{sec_zig_fmac}

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

\vspace{0.1in}
\begin{packed_itemize}
\item \bvar{zigflag}: Posted each time a zig leg is completed. These
  flags are posted twice as frequent as \bvar{zagflag} postings.
\item \bvar{zagflag}: Posted each time a zig zag is completed. These
  flags will be posted half as frequent as \bvar{zigflag} postings.
\item \bvar{starflag}: Posted each time a zig leg started in the starboard
  direction.
\item \bvar{portflag}: Posted each time a zig leg started in the
  port direction.
\item \bvar{starflagx}: Posted each time a zig leg has {\em completed} in the starboard
  direction.
\item \bvar{portflagx}: Posted each time a zig leg has {\em completed} in the
  port direction.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The folowing macros are supported in the \var{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 \var{ZigZag} behavior.


\vspace{0.1in}
\begin{packed_itemize}
\item \pvar{\$[ODO]}: Total odometry distance since the behavior
  became active.
\item \pvar{\$[ZIG\_ODO]}: Total odometry distance since the behavior
  began its current zig leg.
\item \pvar{\$[ZAG\_ODO]}: Total odometry distance since the behavior
  began its current zig zag.
\item \pvar{\$[STEM\_DIST]}: The current ownship distance
  perpendicular from the stem line. Section \ref{sec_zig_stem_odo}.
\item \pvar{\$[STEM\_ODO]}: The current ownship distance parallel
  along the stem line. Section \ref{sec_zig_stem_odo}.
\item \pvar{\$[STEM\_HDG]}: The stemline heading direction.
\item \pvar{\$[ZIGS]}: Total zig legs completed since behavior
  activation. Section \ref{sec_zig_legs}.
\item \pvar{\$[ZAGS]}: Total zig zags completed since behavior
  activation. Section \ref{sec_zig_legs}.
\item \pvar{\$[ZIGS\_EVER]}: Total zig legs completed since this
  activation and all prior activations. For example if
  \bvar{perpetual=true} and repeated activations as in example mission
  \var{s6\_zigzag}. Section \ref{sec_zig_legs}.
\item \pvar{\$[ZAGS\_EVER]}: Total zig zags completed since this
  activation and all prior activations. For example if
  \bvar{perpetual=true} and repeated activations as in example mission
  \var{s6\_zigzag}. Section \ref{sec_zig_legs}.
\item \pvar{\$[ZIG\_START\_SPD]}: Ownship speed at the start of the
  current zig leg.
\item \pvar{\$[ZIG\_MIN\_SPD]}: Minimum ownship speed recorded since
  the start of the current zig leg.
\item \pvar{\$[ZIG\_SPD\_DELTA]}: Change in ownship speed since the
  start of the current zig leg.
\item \pvar{\$[ZIGS\_TOGO]}: Remaining zig legs to execute before
  completion, including the current zig leg being executed. Section
  \ref{sec_zig_legs}.
\item \pvar{\$[ZAGS\_TOGO]}: Remaining zig zags to complete before
  completion, including the current zig zag being executed. Section
  \ref{sec_zig_legs}.
  
\end{packed_itemize}




</pre></body></html>