<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{uFldNodeBroker: Brokering Node Connections}
\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}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UFldNodeBroker}
\wikidoc{bugz=uFldNodeBroker}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_nodebroker}
\index{uFldNodeBroker}

The \app{uFldNodeBroker} application is a tool for brokering
connections between a node (a simulated or real vehicle) and a
shoreside community. It is used primarily in coordination with
\app{uFldShoreBroker} to discover and share host IP and port
information to automate the dynamic configurations of
\app{pShare}. Inter-vehicle communications over the network are
handled by \app{pShare} in both simulation with single or multiple
machines as well as on fielded vehicles using Wi-Fi or cellphone
connections. The \app{pShare} application simply needs to know the IP
address and port number of connected machines. Often these aren't
known at run-time and even if they were, maintaining that information
in configuration files may be cumbersome, especially for large
sets of vehicles. This tool is meant to automate the configuration by
letting the nodes and shoreside community discover each other by
giving the node (\app{uFldNodeBroker}) some initial hints on where to
find the shoreside community on the network.  The typical layout is
shown in Figure \ref{fig_ufnb_topology}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/ufnb_topology.png}
  \caption{{\bf Typical uFldNodeBroker Topology:} A vehicle (node)
    sends information about itself (IP address and port number) to
    possible shoreside locations. Once a connection is made, further
    sharing is established between the node and shoreside
    communities.}
\label{fig_ufnb_topology}
\end{figure}

\noindent
The functionality of \app{uFldNodeBroker} paraphrased:

\begin{packed_itemize}
\item Discover the node's host information (typically from \app{pHostInfo}).
\item For candidate shoreside hosts, request a new share configuration
  in \app{pShare} to each candidate for the variable
  \mvar{NODE\_BROKER\_PING}.
\item Publish \mvar{NODE\_BROKER\_PING} with the node's host
  information.
\item Await a reply in the form of incoming \mvar{NODE\_BROKER\_ACK}
  mail, presumably from the shoreside community running
  \app{uFldShoreBroker}.
\item Now that a shoreside community is known, request new share
  configurations from the node's local \app{pShare} for all the info
  otherwise wanted for sharing to the shoreside.
\item Keep sending pings periodically in case the shoreside community
  is re-started and needs to re-establish connections to nodes.
\end{packed_itemize}


%=================================================================
\section{The uFldNodeBroker Interface and Configuration Options}
%=================================================================

The \app{uFldNodeBroker} application may be configured with a
configuration block within a \var{.moos} file.  Its interface is
defined by its publications and subscriptions for MOOS variables
consumed and generated by other MOOS applications. An overview of the
set of configuration options and interface is provided in this
section.  If one has access to a command line where
\app{uFldNodeBroker} has been built, interface information may also be
seen by typing \var{"uFldNodeBroker --interface"}, and configuration
information by typing \var{"uFldNodeBroker --example"}.

%=================================================================
\subsection{Configuration Parameters of uFldNodeBroker}
\index{uFldNodeBroker!Configuration Parameters}
\index{Configuration Parameters!uFldNodeBroker}

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{uFldNodeBroker}}
\label{lst_ufnb_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 

%  \pvar{keyword}: &amp; An optional unique identifier to be read by the
%  shoreside broker to conditionlly respond to pings. \\

  \pvar{auto\_bridge\_appcast}: &amp; Suppress the normal automatic bridging
  of the \mvar{APPCAST} variable. The default is false. \\

  \pvar{auto\_bridge\_realmcast}: &amp; Suppress the normal automatic
  bridging of the \mvar{REALMCAST} and \mvar{REALMCAST\_CHANNELS}
  variables. The default is false. \\

  \pvar{bridge}: &amp; A variable to register with \app{pShare} for bridging 
  to a shoreside MOOS community once a shoreside connection has been 
  established. \\

  \pvar{try\_shore\_host}: &amp; A candidate route to send send initial
  pings in hopes of establishing a connection. The route specifies
  an input route for pShare running in a shoreside community. \\
\end{longtable}
\end{listing}

\vspace{0.1in}
\noindent
Since appcasting and realmcasting are common and recommended practices
for users of the uField Toolbox, key variables that are bridged are
done automatically.  Normally the \mvar{APPCAST} variable is auto
bridged to support appcasting.  And the \mvar{REALMCAST} and
\mvar{REALMCAST\_CHANNELS} variables are auto bridged to support
realmcasting. The user has the option to opt out of this configuration
by setting the \pvar{auto\_bridge\_*} configuration parameters
described above. Note that realmcasting was first introduced to the
uField Toolbox and MOOS-IvP code in the first release after 19.8.1.

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

An example MOOS configuration block can be obtained by entering the
following from the command-line: 

\vspace{0.1in}
\begin{consoleverb}
 $ uFldNodeBroker --example or -e
\end{consoleverb}
\vspace{0.1in}

\vspace{0.15in}
\begin{listing}{Example configuration of the \app{uFldNodeBroker} application}
\label{ufnb_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  uFldNodeBroker Example MOOS Configuration                       
  3  =============================================================== 
  4                                                                  
  5  ProcessConfig = uFldNodeBroker                                  
  6  {                                                               
  7    AppTick   = 4                                                 
  8    CommsTick = 4                                                 
  9         
 10    keyword        = lemon                                        
 11                                                            
 12    try_shore_host = pshare_route=localhost:9200                  
 13    try_shore_host = pshare_route=192.168.0.122:9301              
 14    try_shore_host = pshare_route=multicast_8           
 15                                                            
 16    bridge = src=VIEW_POLYGON                                     
 17    bridge = src=VIEW_POINT                                       
 18    bridge = src=VIEW_SEGLIST                                     
 19                                                              
 20    bridge = src=NODE_REPORT_LOCAL, alias=NODE_REPORT             
 21  }                                                          
\end{verbatim}
\end{listing}
\normalsize
  
%=================================================================
\section{Publications and Subscriptions for uFldNodeBroker}
%=================================================================
\index{uFldNodeBroker!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldNodeBroker}
\label{sec_ufnb_interface}

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

\vspace{0.1in}
\begin{consoleverb}
 $ uFldNodeBroker --interface or -i
\end{consoleverb}
\vspace{0.05in}

%=================================================================
\subsection{Variables Published by uFldNodeBroker}
\label{sec_ufnb_pubs}

The primary output of \app{uFldNodeBroker} to the MOOSDB are the 
requests to \app{pShare} for registrations, and the outgoing
pings to candidate shoreside communities.

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

\item \mvar{NODE\_BROKER\_PING}: A message written locally but
  bridged to a candidate shoreside MOOS community, containing IP
  address and \app{pShare} route information about the local community. 

\item \mvar{PSHARE\_CMD}: message to \app{pShare} to add a new bridge
  for a given variable and given target MOOS community at a specified
  IP address and port number.
\end{packed_itemize}

%=================================================================
\subsection{Variables Subscribed for by uFldNodeBroker}
\label{ufnb_subs}

The \app{uFldNodeBroker} 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\_BROKER\_ACK}: Information published presumably by
  \app{uFldShoreBroker} running in a separate shoreside community.
  Message has information about the shoreside host including the
  community name, IP address and port numbers for the MOOSDB and its
  local \app{pShare} process.

\item \mvar{PHI\_HOST\_INFO}: Information about the local host IP
  address, the MOOS community name, the port on which the DB is
  running, and the port on which the local \app{pShare} is listening
  for UDP messages.
\end{packed_itemize}

%=================================================================
\subsection{Command Line Usage of uFldNodeBroker}
\label{sec_ufnb_cmdline}
\index{Command Line Usage!uFldNodeBroker}
\index{uFldNodeBroker!Command Line Usage}

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

\vspace{0.1in}
\begin{consoleverb}
 $ uFldNodeBroker --help or -h
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{uFldNodeBroker} tool}
\label{ufnb_usage}
\footnotesize
\begin{verbatim}
  1  ==========================================================
  2  Usage: uFldNodeBroker file.moos [OPTIONS]                 
  3  ==========================================================
  4                                                            
  5  Options:                                                  
  6    --alias=&lt;ProcessName&gt;                                
  7        Launch uFldNodeBroker with the given                
  8        process name rather than uFldNodeBroker.            
  9    --example, -e                                           
 10        Display example MOOS configuration block.           
 11    --help, -h                                              
 12        Display this help message.                          
 13    --interface, -i                                         
 14        Display MOOS publications and subscriptions.        
 15    --version,-v                                            
 16        Display release version of uFldNodeBroker.          
\end{verbatim}
\end{listing}
\normalsize
 
%---------------------------------------------------------------------
%\subsection{Usage Scenarios the uFldNodeBroker Utility}

%---------------------------------------------------------------------
%\subsection{Configuring uFldNodeBroker}
%\index{Configuration Parameters!uFldNodeBroker}
%\index{uFldNodeBroker!Configuration Parameters}

%- TRY\_SHORE\_HOST
%- BRIDGE

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

The \app{uFldNodeBroker} application produces some useful information
to the terminal on every iteration of the application. An example is
shown in Listing \ref{lst_ufnb_appcast} below. This application is
also appcast enabled, meaning its reports are published to the MOOSDB
and viewable from any uMAC application or \app{pMarineViewer}.  The
counter on the end of line 2 is incremented on each iteration of
\app{uFldNodeBroker}, 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{uFldNodeBroker}}
\label{lst_ufnb_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  uFldNodeBroker henry                                       0/0(129)
  3  ===================================================================
  4  
  5    Total OK  PHI_HOST_INFO    received: 13
  6    Total BAD PHI_HOST_INFO    received: 0
  7    Total HOST_INFO changes    received: 1
  8    Total          PSHARE_CMD    posted: 7
  9    Total BAD NODE_BROKER_ACK  received: 6
 10  
 11  ===========================================================
 12               Vehicle Node Information:
 13  ===========================================================
 14  
 15       Community: henry
 16          HostIP: 10.0.0.5
 17     Port MOOSDB: 9001
 18       Time Warp: 4
 19        IRoutes: 10.0.0.5:9301
 20  
 21  ===========================================================
 22              Shoreside Node(s) Information:
 23  ===========================================================6
 24  
 25  Community                  Pings  Pings  IP        Time
 26  Name       Route           Sent   Acked  Address   Warp
 27  ---------  --------------  -----  -----  --------  ----
 28  shoreside  localhost:9300  128    120    10.0.0.5  4   
 29  Phase Completion Summary:
 30  ------------------------------------
 31   Phase 1: (Y) Valid Host information retrieved (iroutes).
 32   Phase 2: (Y) Valid TryHosts (1) configured.
 33   Phase 3: (Y) NODE_BROKER_PINGS are being sent to TryHosts.
 34   Phase 4: (Y) A Valid NODE_BROKER_ACK has been received.
 35   Phase 5: (Y) pShare requested to share user vars with shoreside.
 36  All Phases complete. Things should be working as configured. 
\end{verbatim}
\end{listing}
\normalsize

On line 5, the number of incoming mail messages for
\mvar{PHI\_HOST\_INFO} is tallied where the host information bundle is
deemed complete. It is complete if it contains the host community, IP
address, time warp and \app{pShare} input route information.  If an
incomplete host information packet is received, it is tallied in line
6. The number on line 6 should always be zero. If the number on line 6
is not zero, or the number on line 5 never increments, you should
check the operation of the \app{pHostInfo}. 

\pskip
The number on line 7 indicates the number of time the detected host
information changes. This number should stabilize very quickly maxing
out at 1 or 2 typically. The number on line 8 indicates the number of
dynamic bridge requests posted to \app{pShare}.  These are in the form
of postings to the variable \mvar{PSHARE\_CMD}, which occur first for
outgoing pings to candidate shoreside hosts, and then for the user
\pvar{bridge} configuration variables after a shoreside host has been
connected.  Invalid \mvar{NODE\_BROKER\_ACK} messages are tallied on
line 9. An invalid ack may be due to a mismatch in time warp between
node and shoreside, or a mismatch in keywords if keywords are being
used.

\pskip
Self node information is displayed in the next group, lines 11-19.
The community name, MOOSDB port, and time warp are all read from the
.moos mission configuration file. The node's IP address (line 16) and
the local \app{pShare} input routes (line 19) are obtained from output
received from \app{pHostInfo}.

\pskip

Information about candidate and connected shoreside communities is
shown next in lines 21-28. In this case there is only one entry, line
27.  For each candidate entry, the community name, shoreside
\app{pShare} input route, number of pings sent and acknowledged are in
the first four columns. The last two columns indicate the IP address
and time warp of the shoreside learned from \mvar{NODE\_BROKER\_ACK}
messages received from the shoreside.  When a candidate shoreside
community has {\em not} been connected, the entry in this table will
something like:

\footnotesize
\begin{verbatim}
    Community                   Pings  Pings  IP       Time
    Name       Route            Sent   Acked  Address  Warp
    ---------  ---------------  -----  -----  -------  ----
               localhost:92003  385    0                   
\end{verbatim}
\normalsize

The last block of information in the report is the Phase Completion
Summary, lines 29-36. It lists the rough sequence of events typical
to reach a shoreside community connection. If any one of these phases
is incomplete, the output on line 36 will be replaced with a few hints
on where to troubleshoot.

\end{document}

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