<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{uFldShoreBroker: Brokering Shore 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.UFldShoreBroker}
\wikidoc{bugz=uFldShoreBroker}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_shorebroker}
\index{uFldShoreBroker}

The \app{uFldShoreBroker} application is a tool for brokering
connections between a shoreside community and one or more nodes
(simulated or real vehicles). A shoreside community is collection of
MOOS processes typically running a GUI providing a situational display
and managing messages to and from fielded vehicles. This is depicted
in the notional rendering in Figure \ref{fig_ufsb_topology} below.
The shoreside community in practice is often situated on a ship with
UUVs below, and is more aptly referred to as the topside community.
The user interacts with the GUI or perhaps other communication
modules, to send high-level messages to the vehicles.

\pskip

The \app{uFldShoreBroker} application is used primarily in
coordination with \app{uFldNodeBroker}, running on the vehicles, 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
unduly 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 letting (\app{uFldShoreBroker})
respond to incoming pings, i.e., initialization messages, from nodes
on the network.  The typical layout is shown in Figure
\ref{fig_ufsb_topology}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/ufsb_topology.png}
  \caption{{\bf Typical uFldShoreBroker Topology:} A vehicle (node)
    sends information about itself (IP address and port number) to the
    shoreside, received by uFldShoreBroker. It responds by (a)
    acknowledging the connection to the node, and (b) establishing
    user configured bridges of particular MOOS variables to the node.}
\label{fig_ufsb_topology}
\end{figure}

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

\begin{packed_itemize}
\item Discover the shoreside's own host information (typically from
  \app{pHostInfo}).
\item Await incoming \mvar{NODE\_BROKER\_PING} messages from non-local
  vehicles.
\item Upon an incoming ping, respond to the nodes with a
  \mvar{NODE\_BROKER\_ACK} message to the location specified in the
  ping message.
\item Establish new bridges to the nodes for variables specified
  previously by the user in the \app{uFldShoreBroker} configuration.
\item Keep sending acknowledgments periodically to confirm to vehicles that
  they are still connected to the shoreside community.
\end{packed_itemize}

%=================================================================
\section{Bridging Variables Upon Connection to Nodes}
%=================================================================
\label{sec_ufsb_bridging}

A primary function of \app{uFldShoreBroker} is to establish bridging
relationships to a remote node community after it has received a ping
from that community. These variables are specified in the configuration 
block with lines like \psvar{bridge = "src=DEPLOY\_ALL, alias=DEPLOY"} as 
in Listing \ref{lst_ufsb_econfig}. This step is described next. 

%=================================================================
\subsection{Inter-MOOSDB Bridging with pShare}

Static bridging with \app{pShare} is done by specifying the desired
route in the \app{pShare} configuration block with a line of the
form:

\prevblue
\begin{verbatim}
   output = src_name=VAR, dest_name=ALIAS, route=ROUTE
\end{verbatim}
\postverb

\noindent
For example:

\prevblue
\begin{verbatim}
   output = src_name=DEPLOY_HENRY, dest_name=DEPLOY, route=12.56.111.1:9200
\end{verbatim}
\postverb

\noindent
The above connection may be used to send the vehicle Henry the deploy command
from the shoreside community. The problem is that the shoreside may not know
the IP address of Henry (or the port on which it's pShare is listening) until
it presents itself to the shoreside at run time.

In this case, dynamic share registration needs to be used by sending
\app{pShare} a message after it has been launched. For example, the
above sharing relationship could be established by sending the
following message:

\prevgreen
\begin{verbatim}
   PSHARE_CMD = "cmd=output, src_name=DEPLOY_ALL, dest_name=DEPLOY, 
                route=2.56.111.1:9200
\end{verbatim}
\postverb

\noindent
It is the job of \app{uFldShoreBroker} to post the above style dynamic 
requests once the node information becomes known to the shoreside community.

%=================================================================
\subsection{Handling a Valid Incoming Ping from a Remote Node}

The basic job of \app{uFldShoreBroker} is to await incoming pings, and use
the information in a ping message to (a) decide if the ping should be accepted,
and (b) send the appropriate response back to the sender, and (c) set up new
outgoing \app{pShare} relationships if the ping is indeed accepted. The contents of 
a ping may look something like:

\prevgreen
\begin{verbatim}
  NODE_BROKER_PING = "community=henry,host=192.168.1.22,port=9000,time_warp=10
                      pshare_iroutes=192.168.1.22:9200,time=1325178800.81"
\end{verbatim}
\postverb

\noindent
There must be a match in the MOOS {\em time warp} used by the
shoreside MOOS community and any node connected to the shore. This is
always $1$ when operating vehicles in the field, but may be set to a
much larger number in simulation. The time warp is set with the
parameter \pvar{MOOSTimeWarp} at the top of the .moos configuration
file. 

\pskip

\noindent
The ping consists of three key pieces of information:

\begin{packed_itemize}
\item The community name of the node,
\item The IP address of the node,
\item The input routes on which the node is listening for messages
  with its own local \app{pShare} running.
\end{packed_itemize}


\noindent
Once this information is known by the shoreside broker, new bridges
can be established for variables identified by the user. The only
other information needed is (a) the name of the variable in the local
\app{MOOSDB}, and (b) the name (alias) of the variable as it is to be
known in the remote \app{MOOSDB}. Once a valid ping has been received
and accepted, \app{uFldShoreBroker} is ready to establish bridge
arrangements with its local pShare running.

%=================================================================
\subsection{Vanilla Bridge Arrangements}
\label{sec_ufsb_bridge}

The simplest bridge arrangement specifies (a) the variable as it is 
known locally, and (b) the variable name as it is to be known remotely. 
This is done with a \app{uFldShoreBroker} configuration line similar to:

\prevblue
\begin{verbatim}
  bridge = src=DEPLOY_ALL, alias=DEPLOY
\end{verbatim}
\postverb

\noindent
For {\em each} unique incoming ping, a new bridge arrangement will be
requested. By unique, we mean having a distinct community (remote
vehicle) name. For example, if pings are received and accepted from
{\em henry}, {\em james}, and {\em ike}, \app{uFldShoreBroker} would
make three separate posts, perhaps looking like:

\prevgreen
\begin{verbatim}
   PSHARE_CMD = "src_name=DEPLOY_ALL, dest_name=DEPLOY, route=2.56.111.1:9200"
   PSHARE_CMD = "src_name=DEPLOY_ALL, dest_name=DEPLOY, route=2.56.111.3:9200"
   PSHARE_CMD = "src_name=DEPLOY_ALL, dest_name=DEPLOY, route=2.56.111.6:9200"
\end{verbatim}
\postverb

\noindent
At this point the behavior of \app{pShare} on the shoreside would be
functionally equivalent to the scenario where the following three
lines were in the \app{pShare} configuration block:

\prevblue
\begin{verbatim}
   output = src_name=DEPLOY_ALL, dest_name=DEPLOY, route=12.56.111.1:9200
   output = src_name=DEPLOY_ALL, dest_name=DEPLOY, route=12.56.111.3:9200
   output = src_name=DEPLOY_ALL, dest_name=DEPLOY, route=12.56.111.6:9200
\end{verbatim}
\postverb[0in]

%=================================================================
\subsection{Bridge Arrangements with Macros}

The user may configure \app{uFldShoreBroker} with bridge arrangements containing
a couple types of macros. For example, consider the configuration:

\prevblue
\begin{verbatim}
  bridge = src=DEPLOY_$V, alias=DEPLOY
\end{verbatim}
\postverb

\noindent
The \var{\$V} macro will expand to the name of the vehicle when it comes
time to request a new bridge. If the newly received ping is from the node
named {\em gilda}, the bridge request from the above pattern may look like:

\prevgreen
\begin{verbatim}
   PSHARE_CMD = cmd=output, src_name=DEPLOY_GILDA, dest_name=DEPLOY, 
                route=2.56.111.1:9200
\end{verbatim}
\postverb

\noindent
Note the vehicle name in the MOOS variable macro was expanded to be
upper case, even though the ping information referred to the vehicle as
{\em gilda}.  This is just to aid in the convention that MOOS variable
are typically all upper case. If one really want a literal expansion
with no case altering, the macro \var{\$v}, lower-case \var{v}, may be
used instead.  The macro is only respected as part of \var{src}
field. In other words, if the bridge were configured with
\var{alias=DEPLOY\_\$V}, the macro would not be expanded.  

\pskip
\noindent
The other type of macro implemented is the \var{\$N} macro, as in:

\prevblue
\begin{verbatim}
  bridge = src=LOITER_$N, alias=LOITER
\end{verbatim}
\postverb

\noindent
The \var{\$N} macro will expand to the integer value representing
number of unique pings received thus far. For example, if three pings
are received and accepted from {\em henry}, {\em james}, and {\em
  ike}, \app{uFldShoreBroker} would make three separate posts, perhaps
looking like:

\prevgreen
\begin{verbatim}
   PSHARE_CMD = "src_name=LOITER_1, dest_name=LOITER, route=2.56.111.1:9200"
   PSHARE_CMD = "src_name=LOITER_2, dest_name=LOITER, route=2.56.111.4:9200"
   PSHARE_CMD = "src_name=LOITER_3, dest_name=LOITER, route=2.56.111.12:9200"
\end{verbatim}
\postverb

\noindent
This may be useful when used in conjunction with another MOOS process generating
output generically for $N$ vehicles, without having to know the vehicle names
in advance.

%=================================================================
\subsection{A Common Configuration Shortcut - the qbridge Parameter}
\label{sec_qbridge}

A common usage pattern is to configure \app{uFldShoreBroker} to request two 
types of bridges for a given variable, for example:
\prevblue
\begin{verbatim}
  bridge = src=DEPLOY_ALL, alias=DEPLOY
  bridge = src=DEPLOY_$V,  alias=DEPLOY
  bridge = src=RETURN_ALL, alias=RETURN
  bridge = src=RETURN_$V,  alias=RETURN
\end{verbatim}
\postverb

\noindent
This could be use in the shoreside community for easily commanding
vehicles. When the user wishes to deploy all vehicles, a posting of
\msvar{DEPLOY\_ALL="true"} does the trick. If the user wishes only the
vehicle {\em james} to return, a posting of \msvar{RETURN\_JAMES="true"}
may be be made. This pattern is so common that this shortcut is
supported. This is done with the \pvar{qbridge}, "quick bridge",
parameter. The above four configuration lines could be accomplished
instead by:

\prevblue
\begin{verbatim}
  qbridge = DEPLOY, RETURN
\end{verbatim}
\postverb[0in]

%=================================================================
\section{Usage Scenarios for the uFldShoreBroker Utility}
%=================================================================

The \app{uFldShoreBroker} was designed with a canonical command-and
control scenario in mind. The idea is that the $N$ deployed vehicles
have a common autonomy protocol implemented. For example, a message to
deploy or return a vehicle is the same message for each deployed
vehicle. The idea is that two types of communication channels need to
be established with \app{pShare}, (a) messages sent to all vehicles,
and (b) messages sent to a particular named vehicle. The convention
proposed here is to do this with the two types of bridging described
in the discussion of the \pvar{qbridge} parameter, in Section
\ref{sec_qbridge}. For a variable such as \msvar{DEPLOY}, a posting in
the shoreside community to \msvar{DEPLOY\_ALL} would go to all known
vehicles, and a posting to \msvar{DEPLOY\_HENRY} would only go to that
particular vehicle.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/ufsb_usage.png}
  \caption{{\bf Common uFldShoreBroker Usage Scenario:} As vehicles
    become known to the shoreside, each vehicle has two new bridges
    established. The first is the same for all vehicles to allow
    broadcasting, and the second bridge is unique to the particular
    vehicle, for individual command and control.}
\label{fig_ufsb_usage}
\end{figure}

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

The \app{uFldShoreBroker} application produces some useful information
to the terminal on every iteration of the application. An example is
shown in Listing \ref{lst_ufsb_appcast} below. This application is
also appcast enabled, meaning its reports are published to the
\app{MOOSDB} and viewable from any \app{uMAC} application or
\app{pMarineViewer}. See the appcasting documentation for more on
appcasting and viewing appcasts.

On line 1, the application iteration is shown, more as a heartbeat 
indicator. In lines 4-7, the primary variables consumed and posted 
by \app{uFldShoreBroker} are summarized in terms of how many posts
have been made and received for each variable.

\vspace{0.1in}
\begin{listing}{Example terminal output of the \app{uFldShoreBroker} tool}
\label{lst_ufsb_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  uFldShoreBroker_PS shoreside                                  (109)
  3  ===================================================================
  4  
  5   Total PHI_HOST_INFO    received: 11
  6   Total NODE_BROKER_PING received: 180
  7   Total NODE_BROKER_ACK    posted: 180
  8   Total PSHARE_CMD         posted: 34
  9                                                                    
 10                                                                    
 11  ===========================================================       
 12              Shoreside Node(s) Information:                        
 13  ===========================================================       
 14                                                                    
 15       Community: shoreside
 16          HostIP: 128.30.27.202
 17     Port MOOSDB: 9000
 18       Time Warp: 6
 19         IRoutes: localhost:9200
 20                                                                    
 21  ===========================================================       
 22               Vehicle Node Information:                            
 23  ===========================================================       
 24                                                                    
 25  Node   IP                     Elap  pShare                    
 26  Name   Address        Status  Time  Input Route(s)      Skew  
 27  -----  -------------  ------  ----  ------------------  ------
 28  henry  128.30.27.202  ok      0.0   128.30.27.202:9301  1.6542
 29  gilda  128.30.27.202  ok      0.0   128.30.27.202:9302  1.7572
 30  
 31  Recent Events (2):
 32  [22.06]: New node discovered: gilda
 33  [16.04]: New node discovered: henry
\end{verbatim}
\end{listing}
\normalsize

\noindent
In lines 11-19, the key shoreside properties are listed. Typically,
but not always, the shoreside community is name \var{"shoreside"} as
indicated on line 15. The shoreside IP address, determined by
\app{pHostInfo}, is shown on line 16. The time warp, and \app{MOOSDB}
port are read from the shoreside .moos file and listed on lines 17 and
18.  The input routes used by \app{pShare} are listed on line 19. If
lines 16 or 19 are blank, \app{uFldShoreBroker} will not make any
connections and the first place to look is whether or not
\app{pHostInfo} is running and producing valid information.

\pskip

In lines 21-33, the status of each of the known vehicles is shown. The
first two vehicles had their pings accepted. Their IP addresses are
shown in the second column. Their status is shown in the third column.
The elapsed time in the fourth column is the time since the last ping
was received by the shoreside. The fifth column shows the input routes
being used by \app{pShare} running on the vehicle node.  If multiple
routes are in use, this will be shown over multiple lines.  The sixth
column shows the time skew between the timestamp in the
\mvar{NODE\_BROKER\_PING} message compared to the time it was
received. Some of this is due to (a) latency in transmission, (b)
latency due to App Ticks in brokers on both sides, and (c) clock
discrepancy between the shoreside and the node computers.  It's also
worth mentioning that the skew will be magnified for higher time
warps. Currently incoming ping connection requests are not denied due
to a high clock skew, but this may be implemented in the future.


%=================================================================
\section{Configuration Parameters of uFldShoreBroker}
%=================================================================
\index{uFldShoreBroker!Configuration Parameters}
\index{Configuration Parameters!uFldShoreBroker}

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{uFldShoreBroker}}
\label{lst_ufsb_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.75\textwidth}} 

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

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

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

  \pvar{bridge}: &amp; Names a MOOS variable to be bridged to a node
  community. Section \ref{sec_ufsb_bridge}. \\

  \pvar{keyword}: &amp; Optionally set a keyword. If set, incoming
  \mvar{NODE\_BROKER\_PING} messages must contain this keyword or
  else they ping will not get a response. Section TBD. \\

  \pvar{qbridge}: &amp; Shorthand notation for a common bridging
  pattern. Section \ref{sec_qbridge}. \\

  \pvar{try\_vnode}: &amp; TBD \\

  \pvar{warning\_on\_stale}: &amp; If true, generate a warning if a
  previously known node has not been heard from in more than 10
  seconds. \\
\end{longtable}
\end{listing}

\noindent
As an example, \pvar{bridge} \psvar{= src =DEPLOY\_ALL, alias=DEPLOY},
will result in the bridging of variable \msvar{DEPLOY\_ALL} from the
local \app{MOOSDB}, to the variable \msvar{DEPLOY} in a remote MOOS
community.  Further examples are given in Section
\ref{sec_ufsb_bridging}.

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

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

\vspace{0.15in}
\begin{consoleverb}
 $ uFldShoreBroker --example or -e
\end{consoleverb}
\vspace{0.15in}

\vspace{0.25in}
\begin{listing}{Example configuration of the \app{uFldShoreBroker} application}
\label{lst_ufsb_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  uFldShoreBroker Example MOOS Configuration                       
  3  =============================================================== 
  4                                                                  
  5  ProcessConfig = uFldShoreBroker                                  
  6  {                                                               
  7    AppTick   = 4                                                 
  8    CommsTick = 4                                                 
  9                                                                  
 10    warning_on_stale      = false (default)                       
 11    auto_bridge_realmcast = true  (default)                       
 12    auto_bridge_appcast   = true  (default)    
 13    auto_bridge_mhash     = true  (default) 
 15
 15    bridge =  src=DEPLOY_ALL, alias=DEPLOY                        
 16    bridge =  src=DEPLOY_$V,  alias=DEPLOY                        
 17                                                                  
 18    try_vnode = 192.168.4.24:9200                                 
 19    try_vnode = 192.168.4.25:9200 
 20                                                                  
 21    qbridge = RETURN                                              
 22    qbridge = NODE_REPORT, STATION_KEEP 
 23                                                             
 24    bridge  = src=UP_LOITER_$N, alias=UP_LOITER                   
 25                                                                  
 26    // Note: [qbridge = FOO]  is shorthand for                    
 27/   //       [bridge = src=FOO_$V,  alias=FOO] and                
 28    //       [bridge = src=FOO_ALL, alias=FOO]                    
 29                                                               
 30    app_logging = true  // false is default
 31 }                                                    
\end{verbatim}
\end{listing}
\normalsize

%=================================================================
\section{Publications and Subscriptions for uFldShoreBroker}
%=================================================================
\index{uFldShoreBroker!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldShoreBroker}
\label{sec_ufsb_interface}

The interface for \app{uFldShoreBroker}, 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}
 $ uFldShoreBroker --interface or -i
\end{consoleverb}
\vspace{0.05in}

%=================================================================
\subsection{Variables Published by uFldShoreBroker}
\label{sec_ufsb_pubs}

The primary output of \app{uFldShoreBroker} to the \app{MOOSDB} are the 
requests to \app{pShare} for registrations, and the outgoing
acknowledgment replies to remote node/vehicle 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_ufsb_appcast}.

\item \mvar{PMB\_REGISTER}: A 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.

\item \mvar{NODE\_BROKER\_ACK}: A message written locally but bridged
  to a remote vehicle MOOS community, containing IP address and port
  information about the local shoreside community.
\end{packed_itemize}

%=================================================================
\subsection{MOOS Variables Subscribed for by uFldShoreBroker}
\label{sec_ufsb_subs}

The \app{uFldShoreBroker} 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{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.

\item \mvar{NODE\_BROKER\_PING}: Information published presumably by
  \app{uFldNodeBroker} running in a remote vehicle community.  Message
  has information about the node host including the community name, IP
  address, the port number for the \app{MOOSDB}, input route(s) for the
  local \app{pShare} process.
\end{packed_itemize}

%=================================================================
\subsection{Command Line Usage of uFldShoreBroker}
\label{sec_ufsb_cmdline}
\index{Command Line Usage!uFldShoreBroker}
\index{uFldShoreBroker!Command Line Usage}

The \app{uFldShoreBroker} application is typically launched with
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.1 in}
\begin{consoleverb}
 $       uFldShoreBroker --help or -h
\end{consoleverb}
\vspace{0.1 in}

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{uFldShoreBroker} tool}
\label{ufsb_usage}
\footnotesize
\begin{verbatim}
  1  ==========================================================
  2  Usage: uFldShoreBroker file.moos [OPTIONS]                 
  3  ==========================================================
  4                                                            
  5  Options:                                                  
  6    --alias=&lt;ProcessName&gt;                                
  7        Launch uFldShoreBroker with the given                
  8        process name rather than uFldShoreBroker.            
  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 uFldShoreBroker.          
\end{verbatim}
\end{listing}
\normalsize
 
\end{document}

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