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

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

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/fixedturn.png}
  \caption{{\bf 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 \var{missions-auto/04-fixedturn}).}
  \label{fig_fixedturn_basic}
\gif{figures/fixedturn_basic.gif}
\end{figure}
\vspace{0.1in}

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


%=======================================================================
\subsection{Intended Mission Use}
\label{sec_ft_use}

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.

\vspace{0.1in}
\begin{consoleverb}
   turn_spec = spd=1.5, mhdg=10, fix=355, turn=star
   turn_spec = spd=1.5, mhdg=10, fix=355, turn=port
\end{consoleverb}
\vspace{0.1in}

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



%====================================================================
\subsection{The Core Algorithm}
\label{sec_ft_core}
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 \ref{fig_fixedturn_basic}, 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. 

\subsubsection*{OnRunState() Flow Chart}

The primary operation of the behavior is contained within the
\var{OnRunState()} function. This is shown the flow chart and the
pseudocode that follows. \bvar{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.

\vspace{0.1in}
\begin{figure}[ht]
  \centering 
  \includegraphics[width=0.65\textwidth]{figures/fixedturn_fchart.png}
  \caption{{\bf 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.}
  \label{fig_fixedturn_fchart}
\end{figure}
\vspace{0.1in}

%--------------------------------------------------------------------
\subsubsection*{OnRunState() Pseudo Code}

\vspace{0.1in}
\begin{twalgorithm}{FixedTurn Behavior Main Loop}{alg_fturn_onrun}
  \input{alg_fturn_onrun}
\end{twalgorithm}

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

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

\vspace{0.1in}
\noindent
In \bvar{Step 5}, depending on whether the current turn is to the
port or starboard, the desired heading set point $\theta_{sp}$, is
set to be offset from ownship current heading $\theta_{OS}$ by the
number of degrees, $\theta_{\Delta}$ prescribed in the configuration
parameter \bvar{mod\_hdg}. This heading set point is passed, in
\bvar{Step 6} to the function where the IvP objective function (ipf)
is created. See Section \ref{sec_ft_ipf}.

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

% Should have an OnIdleToRunState()
% Should have an OnRunToIdleState()
% Should have an OnCompleteState()

% Global notion of t_UTC  current time
% t_{UTC}(run) time since entering the running state
% t_{UTC}(idle) time since entering the idle state
% t_{UTC}(event) time a certain event ocurred.



%===================================================================
\subsection{Configuration and Operation Mechanics}
\label{sec_ft_mechs}

%--------------------------------------------------------------------
\subsubsection{Configuring the Turns}
\label{sec_ft_spec}

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

\begin{packed_itemize}
\item {\em turn length}: number of degrees constituting a turn
\item {\em heading offset}: requested change of heading during the turn
\item {\em turn speed}: desired speed during the turn
\item {\em turn direction}: port or starboard
\item {\em turn timeout}: a max time, in seconds, allowed for the turn
\item {\em turn flags}: one or more flags to be posted at turn completion.
\end{packed_itemize}

\vspace{0.1in}
\begin{fileverb}
  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
\end{fileverb}
\vspace{0.1in}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/fixedturn_double.png}
  \caption{{\bf Back-to-back Turns}: A vehicle executes a FixedTurn
    mission \var{s6\_legrun}).}
  \label{fig_fixedturn_basic}
\gif{figures/fixedturn_double.gif}
\end{figure}
\vspace{0.1in}


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

%\input{includes/bhv_all_properties}

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

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

  \bvar{fix\_turn}: &amp; The default turn threshold for any turn that
  does not provide one. The default value is 0 degrees. Section
  \ref{sec_ft_spec}. \\

  \bvar{mod\_hdg}: &amp; The default heading offset, $\theta_{\Delta}$
  for any turn that does not specify a heading offset.
  The default value is 20 degrees. Section \ref{sec_ft_spec}. \\

  \bvar{turn\_dir}: &amp; The default turn direction for any turn that
  does specify a direction. The default direction is {\em
    port}. Section \ref{sec_ft_spec}. \\

  \bvar{speed}: &amp; The default speed for any turn that
  does not specify a turn speed. The default value is
  1 meter per second. Section \ref{sec_ft_spec}. \\

  \bvar{timeout}: &amp; 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 \ref{sec_ft_spec}. \\
  
  \bvar{turn\_delay}: &amp; Duration in seconds at the start of turn before
  requesting a heading change, presumably to allow for a speed adjustment
  befor turning. \\

  \bvar{turn\_spec}: &amp; A full specification for a scheduled
  turn. Section \ref{sec_ft_spec}. \\

  \bvar{stale\_nav\_thresh}: &amp; The number of seconds, after which an
  update nav position and heading has not been received, befor the
  behavior throws a warning. Section \ref{sec_ft_spec}. \\
    
  \bvar{schedule\_repeat}: &amp; The number of times the full
  list of turns in the turn schedule will be repeated. The default is
  zero. Section \ref{sec_ft_spec}. \\
    
  \bvar{visual\_hints}: &amp; Color and other settings for posted
  visual artifacts. Section \ref{sec_ft_spec}. \\
    


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

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

\begin{fileverb}
Behavior = BHV_FixedTurn
{
  name      = zig
  pwt       = 100
  condition = MODE==FTURNING
  endflag   = FIX_TURN = false

  updates   = FTURN_UPDATE
  perpetual = true

  fix_turn   = tbd
  mod_hdg    = 20
  turn_dir   = star
  speed      = 2
  timeout    = 60
  turn_delay = 10
  
  turn_spec = spd=auto, mhdg=10, fix=355, turn=auto, flag=FIX_TURN=false
  turn_spec = spd=auto, mhdg=30, fix=355, turn=port, flag=FIX_TURN=false
  
  stale_nav_thresh = 5
  schedule_repeat  = true
  visual_hints     = vertex_color=dodger_blue
  visual_hints     = vertex_size=4

}
\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}.

\item \mvar{FT\_REPORT}: A report posted at the end of each turn, with parameter
  for the turn and observed turn radius information. An example is given
  below.
  
\end{packed_itemize}

\vspace{0.1in}
\begin{fileverb}
  FT_REPORT = spd=0.88,mod_hdg=10,rudder_avg=10.7,avg_rad=55.5,min_rad=54.23,max_rad=56.1}
\end{fileverb}


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

The FixedTurn behavior supports all the normal behavior flags, and a
custom flag(s) can be added to the end of each turn.

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

\vspace{0.1in}
\begin{packed_itemize}
\item \pvar{\$[TURN\_DIST]}: Total odometry in the current or most recent
  turn.
\item \pvar{\$[TURN\_TIME]}: Total time since the beginning of the current or
  most recent turn.
\end{packed_itemize}




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