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

This behavior will periodically influence the depth and speed of the
vehicle while remaining neutral at other times. The purpose is to
bring the vehicle to the surface periodically to achieve some
event specified by the user, typically the receipt of a GPS
fix. Once this event is achieved, the behavior resets its internal
clock to a given period length and will remain idle until a clock
time-out occurs.  

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

\input{includes/bhv_all_properties}


\vspace{0.15in}
\begin{listing}{Configuration Parameters for the PeriodicSurface Behavior}
\label{lst_bhv_periodic_surface}
\small
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.7\textwidth}} 
  
  {\bf Parameter} &amp; {\bf Description} \\  
  
  \bvar{acomms\_mark\_variable} &amp; The incoming MOOS variable for
  resetting the acomms period clock.\\

  \bvar{ascent\_grade} &amp; Manner in which desired speed approaches zero
  on the approach to the surface. The default is \var{linear}. Section
  \ref{sec_psurf_ascent_grade}. \\
  
  \bvar{ascent\_speed} &amp; Desired speed of the vehicle during the
  \bvar{ascent} mode. Section \ref{sec_psurf_ascent_speed}. \\

  \bvar{atsurface\_status\_var} &amp; MOOS variable indicating number of seconds
  at the surface. Section \ref{sec_psurf_atsurface_status_var}. \\

  \bvar{mark\_variable} &amp; The incoming MOOS variable for resetting the
  period clock. Section \ref{sec_psurf_mark_variable}. \\
  
  \bvar{max\_time\_at\_surface} &amp; The maximum time, in seconds, the
  vehicle will wait at the surface. Section
  \ref{sec_psurf_max_time_at_surface}. \\
  
  \bvar{pending\_status\_var} &amp; MOOS variable written to with remaining
  time on idle clock. Section \ref{sec_psurf_pending_status_var}. \\

  \bvar{period} &amp; Duration of the \var{WAITING} mode. Section
  \ref{sec_psurf_period}.\\
  
  \bvar{zero\_speed\_depth} &amp; The depth, in meters, at which the
  desired speed becomes zero on ascent. Section
  \ref{sec_psurf_zero_speed_depth}.

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

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

\begin{fileverb}
Behavior = BHV_PeriodicSurface
{
  // General Behavior Parameters
  // ---------------------------
  name         = periodic_surface   // example
  pwt          = 100                // default
  condition    = MODE==TRANSITING   // example
  updates      = PSURFACE_UPDATES   // example

  // Parameters specific to this behavior
  // ------------------------------------
  acomms_mark_variable = ACOMMS_RECEIVED       // example
          ascent_grade = linear                // default
          ascent_speed = -1                    // default
  atsurface_status_var = TIME_AT_SURFACE       // default
         mark_variable = GPS_UPDATE_RECEIVED   // default
   max_time_at_surface = 300                   // default
    pending_status_var = PENDING_SURFACE       // default
                period = TIME_AT_SURFACE       // default
      zero_speed_depth = 0                     // default
}
\end{fileverb}
\end{listing}


%=======================================================================
\subsection{Detailed Discussions of Behavior Parameters}

%----------------------------------------------------------------------
\subsubsection{The \bvar{period} Parameter}
\label{sec_psurf_period}

The \bvar{period} parameter sets the duration of the period, in
seconds, during which the behavior will remain in the
\var{IDLE\_WAITING} state.

%----------------------------------------------------------------------
\subsubsection{The \bvar{mark\_variable} Parameter}
\label{sec_psurf_mark_variable}

The \bvar{mark\_variable} names a variable used for indicating when
the behavior witnesses the event that would reset the period clock. On
each iteration, the variable is checked against its last known value
and if different, the clock is reset. The default value for this
parameter is \mvar{GPS\_UPDATE\_RECEIVED}. If this variable is
populated by another process with a value indicating the time a GPS
fix is obtained, then the mark will occur on each GPS fix.  Since the
value of this argument names a MOOS variable, it is case sensitive.


%----------------------------------------------------------------------
\subsubsection{The \bvar{pending\_status\_var} Parameter}
\label{sec_psurf_pending_status_var}

The \bvar{pending\_status\_var} names a variable to be written to with
the value of the remaining time on the idle clock, rounded to integer
seconds. The default value is \mvar{PENDING\_SURFACE}.  Since the
value of this argument names a MOOS variable, it is case sensitive.

%----------------------------------------------------------------------
\subsubsection{The \bvar{atsurface\_status\_var} Parameter}
\label{sec_psurf_atsurface_status_var}

The \bvar{atsurface\_status\_var} parameter names a variable to be
written to with the number of seconds that the vehicle has been
waiting at the surface (for the event indicated by the MOOS variable
specified in the \bvar{mark\_variable} parameter). The number of
seconds is rounded to the nearest integer and will be zero when the
vehicle is not at the surface.  The default value is
\bvar{time\_at\_surface}.  Since the value of this parameter names a
MOOS variable, it is case sensitive.


%----------------------------------------------------------------------
\subsubsection{The \bvar{ascent\_speed} Parameter}
\label{sec_psurf_ascent_speed}

The \bvar{ascent\_speed} parameter indicates the desired speed (m/s)
of the vehicle during the ascent state. If left unspecified, the
ascent speed will be equal to the current noted speed at moment it
transitions into the ascent state.

%----------------------------------------------------------------------
\subsubsection{The \bvar{ascent\_grade} Parameter}
\label{sec_psurf_ascent_grade}

The \bvar{ascent\_grade} parameter indicates the manner in which the
ascent speed approaches zero as the vehicle progresses toward the
\bvar{zero\_speed\_depth}. It has four legal values: \var{fullspeed},
\var{linear}, \var{quadratic}, and \var{quasi}. The default is
\var{linear}.  In all four cases, the initial speed is determined by
the parameter \bvar{ascent\_speed}, and the desired speed will be zero
once the \bvar{zero\_speed\_depth} has been achieved. The four
settings determine the manner of slowing to zero speed during the
ascent. The \var{fullspeed} setting indicates that desired speed
should remain constant through the ascent right up to the instant the
vehicle achieves \bvar{zero\_speed\_depth}. For the other three
settings the speed reduction is relative to the starting depth (the
depth noted at the outset of the ascent state) and the
\bvar{zero\_speed\_depth}. With the \var{linear} setting, the speed
reduction is linear. With the \var{quadratic} setting, the speed
reduction is quadratic (quicker initial speed reduction). With the
\var{quasi} setting the speed reduction is between linear and
quadratic. The value passed to this parameter is not case sensitive.


%----------------------------------------------------------------------
\subsubsection{The \bvar{zero\_speed\_depth} Parameter}
\label{sec_psurf_zero_speed_depth}

The \bvar{zero\_speed\_depth} parameter sets the depth (in meters)
during the ascent state at which the desired speed becomes zero, and
presumably further ascent is achieved through positive buoyancy.

%----------------------------------------------------------------------
\subsubsection{The \bvar{max\_time\_at\_surface} Parameter}
\label{sec_psurf_max_time_at_surface}

The \bvar{max\_time\_at\_surface} parameter sets the maximum time (in
seconds) spent in the \var{AT\_SURFACE} state, waiting for the event
indicated by the \bvar{mvar\_variable}, before the behavior
transitions into the \var{IDLE} state.


%======================================================================
\subsection{Internal States of Periodic Surface Behavior}

The behavior can be in one of four states as
described in Figure \ref{periodsurfacestates_fig} below.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.78\textwidth]{figures/periodic_surface.png}
  \caption{Possible modes of the PeriodicSurface behavior.}
  \label{periodsurfacestates_fig} 
\end{figure}

\vspace{0.1in}
\noindent
In the \var{WAITING} state the behavior is simply waiting for
its clock to wind down to zero. The duration is given by the
\bvar{period} parameter listed below. The clock is active despite any
other run conditions that may apply to the behavior. It is started
when the behavior is first instantiated and also when the desired
event occurs at the surface. The \var{ASCENDING\_BLOCKED} state indicates
that the behavior timer has reached zero, but another run condition
has not been met. This is to prevent the behavior from trying to
surface the vehicle when other circumstances override the need to
surface. In the \var{ASCENDING} state, the behavior will produce an
objective function over depth and speed to bring the vehicle to the
surface. A couple parameters described below can determine the
trajectory of the vehicle during ascent. This state can transition
back to the \var{ASCENDING\_BLOCKED} state if run conditions become no
longer satisfied prior to the vehicle reaching the surface. In the 
\var{AT\_SURFACE} state the vehicle is at the surface waiting for 
a specified event. 

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