<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{uFldMessageHandler: Handling Incoming Node Messages}
\vspace{0.1in}
\labdate{March 2022}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UFldMessageHandler}
\wikidoc{bugz=uFldMessageHandler}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_msghandler}

The \app{uFldMessageHandler} application handles incoming messages
from a remote MOOSDB. In MOOS, applications "talk" to each other
through the normal publish-subscribe means of a common
MOOSDB. Distinct robots or vehicles can also share information between
vehicles and MOOSDBs using \app{pShare}. But often we want to simulate
inter-vehicle messaging where messages are sometimes dropped, and
messages are subject to inter-vehicle range limitations, band-width
limitations, and limitations on message frequency. To simulate this we
use the \app{uFldNodeComms} and \app{uFldMessageHandler} apps in
concert. A message meant for another vehicle is packaged up in a
format containing the message itself and a bit of routing information.
The receiving vehicle, running \app{uFldMessageHandler}, unpacks the
message and injects the message to the local vehicle by posting to the
local MOOSDB. The job of routing and applying communications
limitations is done by \app{uFldNodeComms} and is not the focus here.
The sole job of \app{uFldMessageHandler} is to do the message
unpacking and posting of information, while also keeping some stats
for debugging if needed.

%=================================================================
\section{Typical Application Topology}
%=================================================================

In the uField Toolbox typical arrangement, messages arrive from a
shoreside MOOS community running \app{uFldNodeComms} and \app{pShare}
as shown below in Figure \ref{fig_ufmh_topology}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/ufmh_topology.png}
  \caption{{\bf Typical uFldMessageHandler Topology:} A vehicle (node)
    sends a message to another vehicle by wrapping the message content
    and addressee information in a single string sent to the
    shoreside. On the shoreside, the uFldNodeComms application
    redirects the message to the appropriate vehicle(s). The message
    is received on the vehicle by the uFldMessageHandler application
    which parses the MOOS variable and the variable value from the
    string and posts the variable-value pair to the local MOOSDB.}
\label{fig_ufmh_topology}
\end{figure}

%=====================================================================
\section{Inter-vehicle Messaging Sequence of Events}
%=================================================================

\noindent
The functionality of \app{uFldMessageHandler} may be paraphrased:

\begin{packed_itemize}
\item A source vehicle {\em alpha} wishes to send a message to vehicle
  {\em bravo} of the form \msvar{SPEED=2.5}.
\item A local message is posted on vehicle {\em alpha} of the form:
\end{packed_itemize}

\prevgreen
\begin{verbatim}
  NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=SPEED,double_val=2.5
\end{verbatim}
\postverb

\begin{packed_itemize}
\item The above message is shared from {\em alpha} to the shoreside
  community using \app{pShare}.

\item The message is received in the shoreside community as the
  variable \mvar{NODE\_MESSAGE} and handled by \app{uFldNodeComms} and
  republished as \msvar{NODE\_MESSAGE\_BRAVO}.

\item The message is then shared out to {\em bravo} using \app{pShare}
  arriving in vehicle {\em bravo} as \mvar{NODE\_MESSAGE}.

\item On vehicle {\em bravo}, the \mvar{NODE\_MESSAGE} is handled by 
  \app{uFldMessageHandler}. The source variable and value are parsed
  and a post to the local MOOSDB on {\em bravo} is made, \msvar{SPEED=2.5}

\item A scope on the MOOSDB on {\em bravo} would show the source of
  the \msvar{SPEED=2.5} posting to be \app{"uFldMessageHandler"}, and the 
  auxiliary source would show \var{"alpha"}
\end{packed_itemize}


%=====================================================================
\section{Building an Outgoing Node Message}
%=====================================================================
\label{sec_ufmh_build}

To construct an outgoing node message, there are two options. A
message can be created through normal string construction, for
example:

\begin{fileverb} 
 string m_hostname;      // previously set name of ownship
 string m_dest_name;     // previously set name of vehicle to communicate
 string m_moos_varname;  // previously set name of MOOS variable to send
 string m_msg_contents;  // previously set contents of message;

 string msg;
 msg += "src_node="   + m_hostname;
 msg += ",dest_node=" + m_dest_name;
 msg += ",var_name="  + m_moos_varname;
 msg += ",string_val=" + m_msg_contents;
 
 Notify("NODE_MESSAGE_LOCAL", msg); 
\end{fileverb}
\vspace{0.1in}

\noindent
The above works, but may be prone to typos and may not be very
"future-proof" if the format for inter-vehicle messaging
changes. Another way to accomplish this is to use the
\var{NodeMessage} class which has the serializing and de-serializing
steps implemented:

\begin{fileverb}
 #include "NodeMessage.h"  // In the lib_ufield library

 string m_hostname;     // previously set name of ownship
 string m_dest_name;    // previously set name of vehicle to communicate
 string m_moos_varname; // previously set name of MOOS variable to send
 string m_msg_contents; // previously set contents of message;

 NodeMessage node_message;

 node_message.setSourceNode(m_hostname);
 node_message.setDestNode(m_dest_name);
 node_message.setVarName(m_moos_varname);
 node_message.setStringVal(m_msg_contents);

 string msg = node_message.getSpec();
 
 Notify("NODE_MESSAGE_LOCAL", msg); 
\end{fileverb}
\vspace{0.1in}

\noindent
In the opposite direction, creating a \var{NodeMessage} instance from a 
string is done with:

\begin{fileverb}
 #include "NodeMessageUtils.h"  // In the lib_ufield library

 string node_message_str;       // previously set string containing a message

 NodeMessage node_message = string2NodeMessage(node_message_str);
\end{fileverb}
\vspace{0.1in}

\noindent
Note that the \var{NodeMessage} class is part of the \var{lib\_ufield}
library.  The \app{uFldMessageHandler} app links to this library, but
if the above class is being used in a new app, to create a message,
the \var{lib\_ufield} library needs to be linked as part of the build
process of the new app.

%=====================================================================
\section{Building an Outgoing Node Message - A Note of Caution}
%=====================================================================

Note the structure of a node message, such as the one below, uses commas as 
component delimiters:

\prevgreen
\begin{verbatim}
  NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=SPEED,double_val=2.5
\end{verbatim}
\postverb

\noindent
Some care must be taken if the contents of the outgoing message is a
string also containing commas, such as:

\prevgreen
\begin{verbatim}
  NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=INFO,string_val=good,bad,ugly
\end{verbatim}
\postverb

\noindent
In this case the string contents should be wrapped in double quotes:

\prevgreen
\begin{verbatim}
  NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=INFO,string_val="good,bad,ugly"
\end{verbatim}
\postverb

\noindent
If the message is built using the \var{NodeMessage} class as in the
second example in Section \ref{sec_ufmh_build} above, the double quotes
are added automatically in the \var{setStringVal()} function if the
argument is not quoted and it contains a comma.



%=====================================================================
\section{Event Flags}
\label{sec_umh_flags}
%=====================================================================

With the optional \pvar{msg\_flag} and \pvar{bad\_msg\_flag}, the user may
configure events (postings) to be made whenever an incoming message results
in a successful posting, and whenever an incoming message does not result
in a posting.

\vspace{0.1in}
\noindent
The \pvar{msg\_flag} is configured with variable-value pair, for example:

\vspace{0.1in}
\pvar{msg\_flag = GOOD\_POSTING=true}

\vspace{0.1in}
\noindent
Likewise, the \pvar{bad\_msg\_flag} is configured with variable-value
  pair, for example:

\vspace{0.1in}
\pvar{bad\_msg\_flag = FAILED\_POSTING=true}

\vspace{0.1in}
\noindent
The value component of any posting may contain one or more of several supported
macros. A macro is expanded at the time of posting. Supported macros include:

\begin{packed_itemize}
\item \var{\$[CTR]}: The total of all received messages, regardless of whether a
  message resulted in a posting. 

\item \var{\$[GOOD\_CTR]}: The total of all received messages that resulted in a
  posting. 

\item \var{\$[BAD\_CTR]}: The total of all received messages that did
  not result in a posting.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Of course multiple postings may be configured. For example:

\vspace{0.1in}
\pvar{msg\_flag = GOOD\_POSTING=true}

\pvar{msg\_flag = POSTING\_COUNT=\$[CTR]}



%=====================================================================
\section{Configuration Parameters of uFldMessageHandler}
%=====================================================================

The following parameters are defined for \app{uFldMessageHandler}. 

\vspace{0.15in}
\begin{listing}{Configuration parameters for \app{uFldMessageHandler}}
\label{lst_ufmh_params}
\renewcommand{\arraystretch}{1.1}

\begin{longtable}{rp{0.7\textwidth}} 
  \pvar{appcast\_trunc\_msg}: &amp; Number of characters allowed in the appcast
  report for each line reporting a successful message. For example, Lines
  19-24 in Listing \ref{lst_ufmh_appcast}. The default is 75. Setting it to
  zero means no truncating will be applied. \\

  \pvar{strict\_addressing}: &amp; If true, only messages with a
  destination specified by \var{dest\_node}, matching the local
  community name are processed. Other messages with a destination
  specified by a group designation are ignored. The default is
  false. \\

  \pvar{msg\_flag}: &amp; A variable-value pair posted upon receipt of a
  valid, un-rejected incoming message and posting to the MOOSDB. Section
  \ref{sec_umh_flags}. \\

  \pvar{bad\_msg\_flag}: &amp; A variable-value pair posted upon receipt
  of a valid, but rejected incoming message. Section
  \ref{sec_umh_flags}. \\

  \pvar{aux\_info}: &amp; Adjust the content of the source auxilliary field. By
  default this is set to \var{"node"}. If set to \var{"node+app"}, the
  source auxialliary field of posted messages will contain both the sending
  node and the sending app. \\
  
\end{longtable}
\end{listing}

%=====================================================================
\subsection*{An Example MOOS Configuration Block}

Listing \ref{lst_ufmh_econfig} shows an example MOOS configuration
block produced from the following command line invocation:

\begin{consoleverb}
 $ uFldMessageHandler --example or -e
\end{consoleverb}

\vspace{0.25in}
\begin{listing}{Example configuration of the \app{uFldMessageHandler} application}
\label{lst_ufmh_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  uFldMessageHandler Example MOOS Configuration                       
  3  =============================================================== 
  4                                                                  
  5  ProcessConfig = uFldMessageHandler                                  
  6  {                                                               
  7    AppTick   = 4                                                 
  8    CommsTick = 4                                                 
  9         
 10    strict_addressing = false   // the default     
 11    appcast_trunc_msg = 75      // default: the number of chars per
 12                                // line in the appcasting output   
 13                                                               
 14    msg_flag     = RETURN=true                                    
 15    bad_msg_flag = TOTAL_BAD=$[BAD_CTR]                           
 16                                                               
 17    aux_info = node+app  // {node or node+app} Default is node    
 18                                                               
 19    app_logging  = true  // {true or file} By default disabled  
 20  }                                                          
\end{verbatim}
\end{listing}
\normalsize
 
%=====================================================================
\subsection{Variables Published}
\label{sec_ufmh_pubs}

The primary output of \app{uFldMessageHandler} to the MOOSDB are the
messages posted by parsing incoming \mvar{NODE\_MESSAGE} postings. A
summary is also posted periodically to recap message handling totals.

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

\item \mvar{UMH\_SUMMARY\_MSGS}: A summary of total messages, valid
  messages and rejected messages handled thus far. An example:
  \mvar{UMH\_SUMMARY\_MSGS=total=3,valid=3,rejected=0}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Further publications will be made if the app is configure with any
\pvar{msg\_flag} or \pvar{bad\_msg\_flag} flags. For example if
configured with \pvar{msg\_flag=POSTING=\$[CTR]}, the variable
\mvar{POSTING} will be posted each time \app{uFldMessageHhandler}
posts an incoming message. The value of \mvar{POSTING} will be the
total number of messages posted by \app{uFldMessageHandler} thus far.

%=====================================================================
\subsection{Variables Subscriptions}
\label{sec_ufmh_subs}

The \app{uFldMessageHandler} application subscribes to the following MOOS
variables:

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

\item \mvar{NODE\_MESSAGE}: Incoming node messages.
\end{packed_itemize}

%=====================================================================
\section{Command Line Usage of uFldMessageHandler}
%=====================================================================
\label{sec_ufmh_cmdline}

The \app{uFldMessageHandler} application is typically launched with
\app{pAntler}, along with a group of other vehicle modules. However, it
may be launched separately from the command line.  The command line
options may be shown by typing:

\begin{consoleverb}
 $ uFldMessageHandler --help or -h
\end{consoleverb}

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{uFldMessageHandler} tool}
\label{ufmh_usage}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  Usage: uFldMessageHandler file.moos [OPTIONS]                   
  3  =============================================================== 
  4                                                                  
  5  SYNOPSIS:                                                       
  6  ------------------------------------                            
  7    The uFldMessageHandler tool is used for handling incoming     
  8    messages from other nodes. The message is a string that       
  9    contains the source and destination of the message as well as 
  0    the MOOS variable and value. This app simply posts to the     
 11    local MOOSDB the variable-value pair contents of the message. 
 12                                                                  
 13  Options:                                                        
 14    --alias=&lt;ProcessName&gt;                                      
 15        Launch uFldMessageHandler with the given process name     
 16        rather than uFldMessageHandler.                           
 17    --example, -e                                                 
 18        Display example MOOS configuration block.                 
 19    --help, -h                                                    
 10        Display this help message.                                
 21    --interface, -i                                               
 22        Display MOOS publications and subscriptions.              
 23    --version,-v                                                  
 24        Display the release version of uFldMessageHandler.        
 25    --web,-w                                                      
 26        Open browser to:                                          
 27        https://oceanai.mit.edu/ivpman/apps/uFldMessageHandler  
 28                                                                  
 29  Note: If argv[2] does not otherwise match a known option,       
 30        then it will be interpreted as a run alias. This is       
 31        to support pAntler launching conventions.                 
\end{verbatim}
\end{listing}
\normalsize
 
%=====================================================================
\section{Terminal and AppCast Output}
\label{sec_ufmh_appcast}

The \app{uFldMessageHandler} application produces some useful
information to the terminal and identical content through
appcasting. An example is shown in Listing \ref{lst_ufmh_appcast}
below.  On line 2, the name of the local community or vehicle name is
listed on the left. On the right, \var{"0/0(841)} indicates there are
no configuration or run warnings, and the current iteration of
\app{uFldMessageHandler} is 841.  In lines 4-9, general tallies are
shown of received, invalid, and rejected messages. In lines 11-15, the
tallies for received messages sorted by source vehicle are shown. The
variable-value columns reflect only the last received message.

\vspace{0.2in}

\begin{listing}{Example appcast and terminal output of \app{uFldMessageHandler}}
\label{lst_ufmh_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  uFldMessageHandler gilda                                   0/0(841)
  3  ===================================================================
  4  Overall Totals Summary
  5  ======================================
  6     Total Received Valid: 5
  7                  Invalid: 0
  8                 Rejected: 0
  9      Time since last Msg: 101.3
 10  
 11  Per Source Node Summary
 12  ======================================
 13  Source  Total  Elapsed  Variable  Value
 14  ------  -----  -------  --------  -----
 15  henry   5      101.3    RETURN    true 
 16  
 17  Last Few Messages: (oldest to newest) 
 18  ======================================
 19  Valid Mgs: 
 20    src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed
 21    src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed
 22    src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed
 23    src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed
 24    src_node=henry,dest_node=gilda,var_name=RETURN,string_val=true
 25  Invalid Mgs: 
 26    NONE  
 27  Rejected Mgs: 
 28    NONE  
\end{verbatim}
\end{listing}
\normalsize

The information group starting on line 17 shows the last five received
valid, invalid and rejected messages. Note that a rejected message may 
be rejected for being invalid, or if the destination field doesn't
match, or if strict addressing is enabled and there is not a precise
destination field match.

\end{document}

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