<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{Help Topic: IvP Behavior Utility Functions}
\vspace{0.1in}
\labdate{Spring 2020}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labline
\end{labcover}

\wikidoc{file=Help.MIPBHVFunc}
\wikidoc{auth=mikerb@mit.edu}

%======================================================================
\section*{IvP Behavior Utility Functions}
%======================================================================
\label{sec_bhv_util_funcs}

The below describe a set of string utilities defined in the IvPBehavior
superclass. Any behavior that subclasses from this class will have these
functions at their disposal. 

%======================================================================
\subsection*{The \func{addInfoVars(string)} function}

\vspace{0.08in}
\begin{consoleverb}
 void IvPBehavior::addInfoVars(string);
\end{consoleverb}
\vspace{0.08in}

\noindent
The \func{addInfoVars()} function accepts a comma-separated list of
MOOS variables. This is typically invoked in the behavior constructor
and it allows the behavior to declare to the helm which MOOS variables
the behavior will need to know about. The variables may be provided 
in one long comma-separated list in a single \func{addInfoVars()} 
invocation, or in multiple separate invocations, or a combination. 
Declaring a variable twice does no harm.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
  addInfoVars("NAV_X, NAV_Y");
  addInfoVars("NAV_SPEED, NAV_HEADING");
\end{fileverb}

%======================================================================
\subsection*{The \func{getBufferDoubleVal(string, bool\&amp;)} function}

\vspace{0.08in}
\begin{consoleverb}
 double IvPBehavior::getBufferDoubleVal(string, bool&amp;);
\end{consoleverb}
\vspace{0.08in}

\noindent
The \func{getBufferDoubleVal()} function returns the most recent
numerical value for the given MOOS variable provided as an
argument. The second argument is a reference to a Boolean argument
which will be filled in with true if the variable is known to the Info
Buffer, and false otherwise. If the variable is not known to the Info
Buffer, the return value will be zero.


\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 bool ok1, ok2;
 double ownship_x = getBufferDoubleVal("NAV_X", ok1);
 double ownship_y = getBufferDoubleVal("NAV_Y", ok2);
 if(!ok1)
   postWMessage("NAV_X info not found in the info buffer");
 if(!ok2)
   postWMessage("NAV_Y info not found in the info buffer");
\end{fileverb}

%======================================================================
\subsection*{The \func{getBufferStringVal(string, bool\&amp;)} function}

\vspace{0.08in}
\begin{consoleverb}
 double IvPBehavior::getBufferDoubleVal(string, bool&amp;);
\end{consoleverb}
\vspace{0.08in}

\noindent
The \func{getBufferStringVal()} function returns the most recent
string value for the given MOOS variable provided as an argument. The
second argument is a reference to a Boolean argument which will be
filled in with true if the variable is known to the Info Buffer, and
false otherwise. If the variable is not known to the Info Buffer, the
return value will be zero.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 bool ok
 string ownship_name = getBufferDoubleVal("OWNSHIP_NAME", ok);
 if(!ok)
   postWMessage("OWNSHIP_NAME info not found in the info buffer");
\end{fileverb}

%======================================================================
\subsection*{The \func{getBufferStringVal(string)} function}

\vspace{0.08in}
\begin{consoleverb}
 double IvPBehavior::getBufferDoubleVal(string);
\end{consoleverb}
\vspace{0.08in}

\noindent
This function is a variation of the previous \var{getBufferStringVal()}
function. In this case it does not take a Boolean argument. The user
may simply interpret an empty string as an indication that the variable
is unknown to the Info Buffer.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 string ownship_name = getBufferDoubleVal("OWNSHIP_NAME");
 if(ownship_name == "")
   postWMessage("OWNSHIP_NAME info not found in the info buffer");
\end{fileverb}

%======================================================================
\subsection*{The \func{getBufferCurrTime()} function}

\begin{consoleverb}
 double IvPBehavior::getBufferCurrTime();
\end{consoleverb}

\noindent
The \func{getBufferCurrTime()} function returns the current time
according to the InfoBuffer. This is given in UTC time, the number of
seconds since midnight January 1st, 1970. The InfoBuffer is updated
with the current time when it the buffer is updated with incoming MOOS
mail at the beginning of each helm iteration. This time stamp is then
frozen as the behaviors are processed by the helm on the present
iteration. This helps preserve the idea that behavior can be thought
of as running in parrallel. The order in which they are processed
internally by the helm is irrelevant.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 double my_curr_time = getBufferCurrTime();
\end{fileverb}


%======================================================================
\subsection*{The \func{getBufferLocalTime()} function}

\begin{consoleverb}
 double IvPBehavior::getBufferLocalTime();
\end{consoleverb}

\vspace{0.1in}
\noindent
The \func{getBufferLocalTime()} function returns the current time
according to the InfoBuffer. It has the same functionality as
\func{getBufferCurrTime()} but instead returns the number of seconds
since the start of the helm.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 double my_local_time = getBufferLocalTime();
\end{fileverb}


%======================================================================
\subsection*{The \func{getBufferTimeVal(string)} function}

\begin{consoleverb}
 double IvPBehavior::getBufferTimeVal(string);
\end{consoleverb}

\vspace{0.1in}
\noindent
This function returns the amount of time since the given MOOS variable
has been updated in the InfoBuffer. If the helm has received mail on 
this variable on the present helm iteration, this function will return
zero. If the helm has never received any mail for this variable, the 
Info Buffer knows nothing about this variable and it will return -1.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 double info_age = getBufferTimeVal("NAV_HEADING");
 if(info_age == -1)
   postWMessage("No Heading info in the Info Buffer");
 if(info_age == 0)
   postMessage("HEADING_CHANGE", "true");
\end{fileverb}


%======================================================================
\subsection*{The \func{postMessage(string, string, string)} function}

\begin{consoleverb}
 void IvPBehavior::postMessage(string moosvar, string value, string key="");
\end{consoleverb}

\vspace{0.1in}
\noindent
This function will result in the posting to the MOOSDB of the given
MOOS variable and given string value. The optional \var{key} parameter
may be provided to override the helm duplication filter which otherwise
blocks successive postings with the same variable-value unless they have
different keys. Postings are collected by the helm from each behavior
and posted to the MOOSDB by the helm at the end of each helm iteration.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 postMessage("ARRIVAL_TIME", "now");
\end{fileverb}

%======================================================================
\subsection*{The \func{postMessage(string, double, string)} function}

\begin{consoleverb}
 void IvPBehavior::postMessage(string moosvar, double value, string key="");
\end{consoleverb}

\vspace{0.1in}
\noindent
This function will result in the posting to the MOOSDB of the given
MOOS variable and given {\em double} value. The optional \var{key}
parameter may be provided to override the helm duplication filter
which otherwise blocks successive postings with the same
variable-value unless they have different keys.  Postings are
collected by the helm from each behavior and posted to the MOOSDB by
the helm at the end of each helm iteration.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 postMessage("ARRIVAL_TIME", utc_time);
\end{fileverb}


%======================================================================
\subsection*{The \func{postMessage(string, bool, string)} function}

\begin{consoleverb}
 void IvPBehavior::postMessage(string moosvar, bool value, string key="");
\end{consoleverb}

\vspace{0.1in}
\noindent
This function will result in the posting to the MOOSDB of the given
MOOS variable and given {\em Boolean} value. The optional \var{key}
parameter may be provided to override the helm duplication filter
which otherwise blocks successive postings with the same
variable-value unless they have different keys. Boolean postings are
actually converted to string postings. This function is merely a
convenience function.  Postings are collected by the helm from each
behavior and posted to the MOOSDB by the helm at the end of each helm
iteration.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 postMessage("ARRIVAL_TIME", utc_time);
\end{fileverb}


%======================================================================
\subsection*{The \func{postRepeatableMessage(string, string)} function}

\begin{consoleverb}
 void IvPBehavior::postRepeatableMessage(string moosvar, string value);
\end{consoleverb}

\vspace{0.1in}
\noindent
This function will result in the posting to the MOOSDB of the given
MOOS variable and given string value. This function is similar to
\func{postMessage(string, string, string)} function, but does not make
use of a key. Instead, this function guarantees that all postings are
made, even if successive postings have identical variable-value pairs.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 postRepeatableMessage("ARRIVAL_TIME", "now");
\end{fileverb}


%======================================================================
\subsection*{The \func{postRepeatableMessage(string, double)} function}

\begin{consoleverb}
 void IvPBehavior::postRepeatableMessage(string moosvar, double value);
\end{consoleverb}

\vspace{0.1in}
\noindent
This function will result in the posting to the MOOSDB of the given
MOOS variable and given {\em double} value. This function is similar
to \func{postMessage(string, double, string)} function, but does not
make use of a key. Instead, this function guarantees that all postings
are made, even if successive postings have identical variable-value
pairs.

\vspace{0.1in}
\noindent
For example:

\vspace{0.08in}
\begin{fileverb}
 postRepeatableMessage("ARRIVAL_TIME", 0);
\end{fileverb}



\end{document}

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