<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{pEchoVar: Re-publishing Variables Under a Different Name}
\vspace{0.1in}
\labdate{June 2018}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labsrc{project-pavlab/appdocs/app\_pechovar} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PEchoVar}
\wikidoc{bugz=pEchoVar}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\wikisec{grp=utils,file=PEchoVar,short=pEchoVar}
\label{sec_pechovar}
%\index{pEchoVar}

The pEchoVar application is a lightweight process that runs without
any user interaction for "echoing" the posting of specified
variable-value pairs with a follow-on posting having different
variable name. For example the posting of \msvar{FOO=5.5} could be
echoed such that \msvar{BAR=5.5} immediately follows the first
posting. The motivation for this tool was to convert, for example, a
posting such as \msvar{GPS\_X} to become \msvar{NAV\_X}. The former is the
output of a particular device, and the latter is a de facto standard
for representing the vehicle's longitudinal position in local coordinates.


%=================================================================
\section{Using pEchoVar}
%=================================================================

Configuring \app{pEchoVar} minimally involves the specification of one
or more \var{echo} or \var{flip} mapping events. It may also
optionally involve specifying one or more logic conditions that must
be met before mapping events are posted.

%=================================================================
\subsection{Configuring Echo Mapping Events}
\label{sec_pev_echo}
%\index{pEchoVar!Configuring Echo Event Mappings}
%\index{pEchoVar!Configuration Parameters} 
%\index{Configuration Parameters!pEchoVar}
\label{pechovar_config}

An {\em echo event mapping} maps one MOOS variable to another. Each
mapping requires one line using the \pvar{echo} configuration
parameter of the form:

\prevblue
\begin{verbatim}
  echo = &lt;MOOSVar&gt; -&gt; &lt;MOOSVar&gt;
\end{verbatim}
\postverb

\noindent
The source \var{&lt;MOOSVar&gt;} and target \var{&lt;MOOSVar&gt;} components are
case sensitive since they are MOOS variables. A source variable can be
echoed to more than one target variable. If the set of lines forms a
cycle, this will be detected and \app{pEchoVar} post a configuration
and run warning and cease to perform any function whatsoever. An
example configuration is given in Listing \ref{lst_echo_config}.

\vspace{0.1in}
\begin{listing}{An example pEchoVar configuration block}
\label{lst_echo_config}
\footnotesize
\begin{verbatim}
  1  //--------------------------------------------------------------
  2  // pEchoVar configuration block
  3  
  4  ProcessConfig = pEchoVar
  5  {
  6    AppTick   = 20
  7    CommsTick = 20
  8  
  9    echo = GPS_X           -&gt;  NAV_X
 10    echo = GPS_Y           -&gt;  NAV_Y
 11    echo = COMPASS_HEADING -&gt;  NAV_HEADING
 12    echo = GPS_SPEED       -&gt;  NAV_SPEED
 13  }
\end{verbatim}
\end{listing}
\normalsize

%=================================================================
\subsection{Configuring Flip Mapping Events}
\label{sec_pev_flip}
%\index{pEchoVar!Variable Flipping}

The \app{pEchoVar} application can be used to "flip" a variable
rather than doing a simple echo. A flipped variable, like an echoed
variable, is one that is republished under a different name, but a
flipped variable parses the contents of a string comprised of a series
of \var{variable=value } comma-separated pairs, and republishes a
portion of the series under the new variable name. For example, the
following string,

\prevgreen
\begin{verbatim}
    ALPHA = "xpos=23, ypos=-49, depth=20, age=19.3, certainty=1"
\end{verbatim}
\postverb

\noindent
may be flipped to publish the below new string, with the fields
\var{xpos}, \var{ypos}, and \var{depth} replaced with \var{x},
\var{y}, \var{vehicle\_depth} respectively.

\prevgreen
\begin{verbatim}
    BRAVO = "x=23, y=-49, vehicle_depth=20"
\end{verbatim}
\postverb

\noindent
The above "flip relationship" is configured with the \pvar{flip}
configuration parameter with the following form:

\prevblue
\begin{verbatim}
    flip:&lt;key&gt;   = source_variable  = &lt;variable&gt;
    flip:&lt;key&gt;   = dest_variable    = &lt;variable&gt;
    flip:&lt;key&gt;   = source_separator = &lt;separator&gt;
    flip:&lt;key&gt;   = dest_separator   = &lt;separator&gt;
    flip:&lt;key&gt;   = filter           = &lt;variable&gt;=&lt;value&gt;
    flip:&lt;key&gt;   = component        = &lt;old-field&gt; -&gt; &lt;new-field&gt;
    flip:&lt;key&gt;   = component        = &lt;old-field&gt; -&gt; &lt;new-field&gt;
\end{verbatim}
\postverb

\noindent
The relationship is distinguished with a \var{&lt;key&gt;}, and several
components. The \var{source\_variable} and \var{dest\_variable}
components are mandatory and must be different. The
\var{source\_separator} and \var{dest\_separator} components are
optional with default values being the string \var{","}. Fields in the
source variable will only be included in the destination variable if
they are specified in a component mapping \var{&lt;old-vield&gt; -&gt;
  &lt;new-field&gt;}. The example configuration in Listing
\ref{lst_flip_config} implements the above described example flip
mapping. In this case only postings that satisfy the further filter,
\var{certainty=1}, will be posted.

\vspace{0.15in}
\begin{listing}{An example pEchoVar configuration block with flip mappings}
\label{lst_flip_config}
\footnotesize
\begin{verbatim}
  1  //--------------------------------------------------------------
  2  // pEchoVar configuration block
  3  
  4  ProcessConfig = pEchoVar
  5  {
  6    AppTick   = 10
  7    CommsTick = 10
  8  
  9    flip:1   = source_variable  = ALPHA
 10    flip:1   = dest_variable    = BRAVO
 11    flip:1   = source_separator = ,
 12    flip:1   = dest_separator   = ,
 13    flip:1   = filter           = certainty=1
 14    flip:1   = component        = ypos -&gt; y
 15    flip:1   = component        = xpos -&gt; x
 16  }
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.15in}

\noindent
Some caution should be noted with flip mappings - the current
implementation does not check for cycles, as is done with echo
mappings.

%=================================================================
\subsection{Applying Conditions to the Echo and Flip Operation}
\label{sec_pev_conditions}

The execution of the mappings configured in \app{pEchoVar} may be
configured to depend on one or more logic conditions. If conditions
are specified in the configuration block, all specified logic
conditions must be met or else the posting of echo and flip mappings
will be suspended. The logic conditions are configured with the
\pvar{condition} parameter as follows:

\prevblue
\begin{verbatim}
  condition = &lt;logic-expression&gt;
\end{verbatim}
\postverb

\noindent 
The \var{&lt;logic-expression&gt;} syntax is described in the Appendix
document on logic utilities, and may involve the simple comparison of MOOS
variables to specified literal values, or the comparison of MOOS
variables to one another. If a \pvar{condition} parameter is
specified, \app{pEchoVar} will automatically subscribe to all MOOS
variables used in the condition expressions.

%=================================================================
\subsection{Holding Outgoing Messages Until Conditions are Met}
\label{sec_pev_hold_msgs}

If the conditions are not met, all incoming mail messages that would
otherwise result in an echo or flip posting, are held. When or if the
conditions are met at some point later, those mail messages are
processed in the order received and echo and flip mappings may be
posted en masse. However, if several mail messages for a given MOOS
variable are received and stored while conditions are unmet, only the
latest received mail message for that variable will be processed. As
an example, consider \app{pEchoVar} configured with the below two
lines:

\prevblue
\begin{verbatim}
  echo      = FOO -&gt; BAR
  condition = DEGREES &lt;= 32
\end{verbatim}
\postverb

\noindent
If the condition is not met for some period of time, and the following
mail were received during this interval: \msvar{FOO="apples"},
\msvar{FOO="pears"}, \msvar{FOO="grapes"}, followed by
\msvar{DEGREES=30}, then \app{pEchoVar} would post
\msvar{BAR="grapes"} immediately on the very iteration that the
\msvar{DEGREES=30} message was received.  Note that
\msvar{BAR="apples"} and \msvar{BAR="pears"} would never be posted. This
is to help ensure that the \app{pEchoVar} memory doesn't grow unbounded
by holding onto all mail while conditions are unmet.

\pskip

The user may alternatively configure \app{pEchoVar} to {\em not} hold
incoming mail messages when or if it is in a state where its logic
conditions are not met. This can be done with the \pvar{hold\_messages}
parameter:

\prevblue
\begin{verbatim}
  hold_messages = false   // The default is true
\end{verbatim}
\postverb

\noindent
When configured this way, upon meeting the specified logic conditions,
\var{pEchoVar} will begin processing echo and flip mappings when or if
new mail messages are received relevant to the mappings. In the above
example, once \msvar{DEGREES=30} is received by \app{pEchoVar}, nothing
would be posted until new incoming mail on the variable \msvar{FOO} is
received (not even \msvar{BAR="grapes"}).


%=================================================================
\subsection{Limiting the Echo Posting Frequency to the AppTick Setting}
\label{sec_pev_frequency}

By default, when the conditions are met, an echo posting is made once
for each incoming piece of mail related that echo mapping. If \msvar{FOO} is
echo mapped to \msvar{BAR}, and if $40$ pieces of incoming mail for
\msvar{FOO} are received on one iteration, $40$ postings are made to
\msvar{BAR} on that iteration. Instead one may wish that, on each
iteration where there is posting ready for \msvar{BAR}, that only the
latest value for \msvar{BAR} be made. This may be arranged with the 
\pvar{echo\_latest\_only} parameter:

\prevblue
\begin{verbatim}
  echo_latest_only = true    // The default is false
\end{verbatim}
\postverb

\noindent
In this case, the frequency of postings to \msvar{BAR} and all other
echo mappings will occur at most at a frequency equal to the \pvar{AppTick}
setting.

%=================================================================
\section{Configuring for Vehicle Simulation with pEchoVar}
%=================================================================
\label{sec_echo_sim}

When in simulation mode with uSimMarine, the navigation information is 
generated by the simulator and not the sensors such as GPS or 
compass as indicated in lines 9-12 in Listing \ref{lst_echo_config}. The
simulator instead produces \msvar{USM\_*} values which can be echoed
as \msvar{NAV\_*} values as shown in Listing \ref{lst_pev_econfig}.

\vspace{0.1in}
\begin{listing}{An example pEchoVar configuration block during simulation}
\label{lst_pev_econfig}
\footnotesize
\begin{verbatim}
  1  //--------------------------------------------------------------
  2  // pEchoVar configuration block (for simulation mode)
  3  
  4  ProcessConfig = pEchoVar
  5  {
  6    AppTick   = 20
  7    CommsTick = 20
  8  
  9    echo = USM_X       -&gt;  NAV_X
 10    echo = USM_Y       -&gt;  NAV_Y
 11    echo = USM_HEADING -&gt;  NAV_HEADING
 12    echo = USM_SPEED   -&gt;  NAV_SPEED
 13  }
\end{verbatim}
\end{listing}
\normalsize

\noindent
Note in more recent versions of \app{uSimMarine} the simulator output may 
be changed to have a \var{NAV\_} prefix by setting \pvar{prefix} \psvar{= NAV\_},
obviating the use of \app{pEchoVar} configured as above.


%=================================================================
\section{Configuration Parameters for pEchoVar}
%=================================================================
%\index{pEchoVar!Configuration Parameters}
%\index{Configuration Parameters!pEchoVar}

The following parameters are defined for \app{pEchoVar}. A more
detailed description is provided in other parts of this
section. Parameters having default values are indicated so.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{pEchoVar}}
\label{lst_pev_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.73\textwidth}} 

  \pvar{echo}: &amp; A mapping from one MOOS variable to another
  constituting an echo. Section \ref{sec_pev_echo}. \\

  \pvar{echo\_latest\_only}: &amp; If true, only the latest value of variable
  will be echoed on each iteration, even if several pieces of incoming
  mail have been received since the last posting. Legal values: true, false.
  The default is false. Section \ref{sec_pev_echo}. \\

  \pvar{condition}: &amp; A logic condition that must be met or all echo
  and flip publications are held. Section \ref{sec_pev_conditions}. \\

  \pvar{flip}: &amp; A description of how components from one variable are
  re-posted under another MOOS variable. Section \ref{sec_pev_flip}. \\

  \pvar{hold\_messages}: &amp; If true, messages are held when conditions
  are not met for later processing when logic conditions are indeed
  met. Legal values: true, false. The default is true. Section
  \ref{sec_pev_conditions}. \\

\end{longtable}
\end{listing}

%=================================================================
\section{Publications and Subscriptions for pEchoVar}
%=================================================================
%\index{pEchoVar!Publications and Subscriptions}
%\index{Publications and Subscriptions!pEchoVar}
\label{sec_pev_interface}

The interface for \app{pEchoVar}, in terms of publications and 
subscriptions, is described below. This same information may also be
obtained from the terminal with:

\vspace{0.15in}
\begin{consoleverb}
 $ pEchoVar --interface or -i
\end{consoleverb}
\vspace{0.05in}

%=================================================================
\subsection{Variables Posted by pEchoVar}
\label{sec_pev_pubs}

\begin{packed_itemize}[2]

\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Appcasts are posted only after an appcast request
  is received from an appcast viewing utility. Section
  \ref{sec_pev_appcast}.

\item \msvar{&lt;USER-DEFINED&gt;}: Any MOOS variable specified in either
  the \pvar{echo} or \vvar{flip} config parameters. 

\end{packed_itemize}

%=================================================================
\subsection{Variables Subscribed for by pEchoVar}
\label{sec_pev_subs}

\begin{packed_itemize}[2]

\item \mvar{APPCAST\_REQ}: A request to generate and post a new
  apppcast report, with reporting criteria, and expiration.

\item \msvar{&lt;USER-DEFINED&gt;}: Any MOOS variables found in the
  antecedent of either the \var{echo} or \var{flip} mappings. It will
  also subscribe for any MOOS variable found in any of its logic
  conditions.
\end{packed_itemize}

%=================================================================
\section{Terminal and AppCast Output}
%=================================================================
\label{sec_pev_appcast}

The \app{pEchoVar} application produces some useful information to the
terminal on every iteration of the application. An example is shown in
Listing \ref{lst_pev_appcast} below. This application is also appcast
enabled, meaning its reports are published to the MOOSDB and viewable
from any uMAC application or pMarineViewer. See the documentation on
\app{uMAC} viewing utilities for more on appcasting and viewing
appcasts.  The counter on the end of line 2 in parentheses is
incremented on each iteration of \app{pEchoVar}, and serves a bit as a
heartbeat indicator. The \var{"0/0"} also on line 2 indicates there
are no configuration or run warnings detected.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{pEchoVar}}
\label{lst_pev_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  pEchoVar alpha                                              0/0(81)
  3  ===================================================================
  4  conditions_met:   true
  5  hold_messages:    true
  6  echo_latest_only: false
  7  
  8  ==================================================
  9  Echoes: (5)
 10  ==================================================
 11  
 12  Source          Dest           Hits  Posts
 13  ---------  ---  -------------  ----  -----
 14  NAV_X      --&gt;  NAV_XX         324   324  
 15  NAV_X      --&gt;  NAV_XPOS       324   324  
 16  NAV_Y      --&gt;  NAV_YY         324   324  
 17  NAV_Y      --&gt;  NAV_YPOS       324   324  
 18  NAV_SPEED  --&gt;  NAV_SPEED_ALT  324   324  
 19  
 20  ==================================================
 21  Flips: (1)
 22  ==================================================
 23  
 24                                        Src  Dest              Old    New  
 25  Key  Hits  Source             Dest    Sep  Sep   Filter      Field  Field
 26  ---  ----  -----------------  ------  ---  ----  ----------  -----  -----
 27  1    162   NODE_REPORT_LOCAL  FOOBAR  ,    #     type:kayak  X      xpos 
 28  1    162   NODE_REPORT_LOCAL  FOOBAR  ,    #     type:kayak  Y      ypos 
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
Lines 4 indicates whether or not any specified logic conditions have
been met. This line will also read \var{true} even if no logic
conditions were provided. Lines 5 and 6 simply confirm the user's
settings for the \pvar{hold\_messages} and \pvar{echo\_latest\_only}
parameters discussed in Sections \ref{sec_pev_hold_msgs} and
\ref{sec_pev_frequency} respectively.

\pskip

Lines 12-18 convey the configured echo mappings, one for each line. At
the end of each line, the {\em Hits} column shows the number of
incoming mails received for that variable. The number of times it is
echoed, or re-posted is shown under the {\em Posts} column. When
\pvar{echo\_latest\_only} is false, these numbers should match.  Lines
20-28 convey the configure flips. A single flip configuration,
identified by its key, may have several lines, as in this
example. Here the only difference between lines 27 and 28 are the flip
components. One maps \var{X} to \var{xpos}, and the other maps \var{Y}
to \var{ypos}.

\pskip

The terminal or appcast output shown in Listing \ref{lst_pev_appcast} above
may be seen first hand by running the Alpha example mission. The below 
configuration block in Listing \ref{lst_pev_alpha} corresponds to the
above appcast output. The user just needs to add \app{pEchoVar} to the 
Antler launch list.

\vspace{0.16in}
\begin{listing}{Example pEchoVar configuration from the Alpha example mission}
\label{lst_pev_alpha}
\footnotesize
\begin{verbatim}
  1  ProcessConfig = pEchoVar
  2  {
  3    AppTick = 1
  4    CommsTick = 1
  5  
  6    echo = NAV_X     -&gt; NAV_XX
  7    echo = NAV_X     -&gt; NAV_XPOS
  8    echo = NAV_Y     -&gt; NAV_YY
  9    echo = NAV_Y     -&gt; NAV_YPOS
 10    //echo = NAV_YY    -&gt; FOOBAR
 11    //echo = FOOBAR    -&gt; NAV_Y
 12    echo = NAV_SPEED -&gt; NAV_SPEED_ALT
 13  
 14    FLIP:1    = source_variable  = NODE_REPORT_LOCAL
 15    FLIP:1    = dest_variable    = FOOBAR
 16    FLIP:1    = source_separator = ,
 17    FLIP:1    = dest_separator   = #
 18    FLIP:1    = filter = type == kayak
 19    FLIP:1    = component = X -&gt; xpos
 20    FLIP:1    = component = Y -&gt; ypos
 21  }
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.05in}
\noindent
The two echo mappings in lines 10 and 11 may be commented out to
demonstrate the detection of echo mapping cycles. The pairs of
mappings in Lines 6-7 and 8-9 demonstrate that a single incoming
variable may be mapped to multiple destinations.

\end{document}

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