<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{uFldNodeComms: Simulating Inter-vehicle Communications}
\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.UFldNodeComms}
\wikidoc{bugz=uFldNodeComms}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_nodecomms}
\index{uFldNodeComms}

The \app{uFldNodeComms} application is a tool for handling node
reports and messages between vehicles. Rather than directly sending
node reports and messages between vehicles, \app{uFldNodeComms} acts
as an intermediary to conditionally pass a report or message on to
another vehicle, where conditions may be the inter-vehicle range or
other criteria.  The assumption is that \app{uFldNodeComms} is running
on a topside or shoreside computer, and receiving information about the 
present physical location of deployed vehicles through node reports.
The typical layout is shown in Figure \ref{fig_unc_topology}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.5\textwidth]{figures/unc_topology.png}
  \caption{{\bf Typical uFldNodeComms Topology:} A shoreside or
    topside community is receiving information from several deployed
    vehicles, in the form of node reports. The node reports contain
    time-stamped updated vehicle positions, from which the speed and
    distance measurements are derived and posted to the shoreside
    MOOSDB.}
\label{fig_unc_topology}
\end{figure}

In short, \app{uFldNodeComms} subscribes for incoming node reports for
any number of vehicles, and keeps the latest node report for each
vehicle. On each iteration, for a each vehicle, if the node report has
been updated, the report is published to a specially created MOOS
variable for the other n-1 vehicles. A user-configured criteria is
applied before publishing the new information. Typically this criteria
involves the range between vehicles, but the criteria may be further
involved. The idea is conveyed for three vehicles {\em alpha}, {\em
  bravo}, and {\em charlie}, shown below in Figure
\ref{fig_unc_example}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/unc_example.png}
  \caption{{\bf Brokering by uFldNodeComms:} Each incoming node report
    is sent out to a specially named variable corresponding to one
    each of the other n-1 vehicles.}
\label{fig_unc_example}
\end{figure}
\vspace{0.1in}

%=================================================================
\subsection{The Difference Between a Node Report and Node Message}

There are two distinct message types in play with \app{uFldNodeComms}:

\begin{packed_itemize}
\item Node reports - concise vehicle trajectory/state, in \mvar{NODE\_REPORT}
\item Node messages - open ended inter-vehicle content, in \mvar{NODE\_MESSAGE}
\end{packed_itemize}
\vspace{0.1in}

\noindent
A {\em node report} contains concise information regarding a vehicle's
state, including its position, speed, heading and depth for underwater
vehicles. It may also include information regarding the helm,
including the current all-stop state and helm mode. It is typically
published by \app{pNodeReporter} running on each vehicle, and generated
by default at 4Hz. This may be faster for higher speed vehicles
operating in close proximity, and lower for slower moving vehicles
operating in expansive waters. A node report is typically contained in
one of two variables, either \mvar{NODE\_REPORT\_LOCAL} or
\mvar{NODE\_REPORT}.  The former is used by \app{pNodeReporter} to
indicate the report has been generated locally about ownship. When
this information is sent off-board, to the shoreside,
\app{uFldNodeComms}, and eventually other vehicles, it converted to
the variable \mvar{NODE\_REPORT}.

\vspace{0.1in}
\noindent
A {\em node message} contains open ended inter-vehicle message
content, in the form of (a) a destination vehicle, (b) a MOOS variable
name, and (c) the value of the MOOS variable. Not all messages sent
will arrive at their destination and \app{uFldNodeComms} is the
arbiter of which messages get through. There is no single app the
generates a node message. Any app, by the configuration of the user,
may publish an outgoing message to \app{NODE\_MESSAGE\_LOCAL}. This
indicates the message was generated on ownship to be sent
elsewhere. In the uField simulation scheme, using \app{uFldNodeComms},
it will arrive on the shoreside as \mvar{NODE\_MESSAGE} and, if
allowed through, will arrive on the destination vehicle(s) as
\mvar{NODE\_MESSAGE}. The receiving vehicle will unpack the incoming
node message using an app called \app{uFldMessageHandler}.

\vspace{0.1in}
\noindent
In short, \app{uFldNodeComms} reasons about node reports and node
messages, but it uses node reports to have situational awareness of
all vehicle positions.  It uses this situational awareness to be the
arbiter of which node messages are allowed to travel between which
vehicles, depending on the restrictions configured by the user as
\app{uFldNodeComms} parameters.




%=================================================================
\section{Handling Node Reports}
%=================================================================
\index{uFldNodeComms!Handling Node Reports}

Node reports may contain a bundle of useful information for sharing
between vehicles. Perhaps the most important is the present vehicle
position and trajectory. This may be used by the receiving vehicle for
collision avoidance and formation keeping and so on. The vehicle
position is also used by \app{uFldNodeComms} to determine if the node
reports themselves are to be shared between vehicles. The
inter-vehicle ranges derived from the \mvar{NODE\_REPORT} messages are
also used to determine if other more generic information contained in
the \mvar{NODE\_MESSAGE} variable is to be shared between vehicles.

%=================================================================
\subsection{The Criteria for Routing Node Reports}
\label{param_unc_comms}

The basic criteria for sharing node reports is range. By default, the
node report received for any one vehicle is passed on to {\em all}
other known vehicles within comms range of the originating
vehicle. The comms range is set by the parameter \pvar{comms\_range}
as on line 9 in Listing \ref{lst_unc_econfig}. Starting with this as a
baseline, a few other factors may be involved in determining whether a
node report is shared.

%=================================================================
\subsection*{Using Vehicle Group Information}
\label{param_unc_groups}

If \app{uFldNodeComms} is configured with the parameter \pvar{groups}
set to true, as on line 21 in Listing \ref{lst_unc_econfig}, then node
reports are only shared between vehicles having the same group
name. The group name is a field contained in the node report itself,
so the onus is on the vehicle to include this information as part of
its report. The \app{pNodeReporter} application contains an optional
configuration parameter \psvar{group=&lt;group-name&gt;} where the group
information is declared for inclusion in all node reports. The
motivation for the grouping option is to support multi-vehicle
competitions where some vehicles want to convey positions to
teammates, but not adversarial vehicles.

\pskip

The \pvar{groups} feature only affects the passing of node reports
between vehicles. It does not affect the passing of node {\em
  messages} discussed further below. Node messages contain their
addressee information explicitly.

\pskip

The \pvar{msg\_groups} feature only affects the passing of node {\em
  messages} between vehicles. It does not affect the passing of node
{\em reports} discussed above. This feature is introduced in the
release following 19.8.2.

%=================================================================
\subsection*{Establishing and Inter-Vehicle Critical Range}
\label{param_unc_critical}
\index{uFldNodeComms!CriticalRange}

When the two vehicles are within a range deemed critical, as set by
the \pvar{critical\_range} configuration parameter as on line 10 in
Listing \ref{lst_unc_econfig}, node reports are shared between
vehicles regardless of the \pvar{comms\_range} parameter and the
\pvar{groups} parameter.  The default for this parameter is 30
meters. The thought behind this feature is that, while it may be
advantageous to not broadcast your own vehicle position to non group
members for the purposes of a competition, it may be a good idea to
share this information for the sake of collision avoidance.

%=================================================================
\subsection*{Checking for Staleness}
\index{uFldNodeComms!Staleness}
\index{Staleness!uFldNodeComms}
\label{param_unc_stale}

Since up-to-date inter-vehicle range information is used as part of
the criteria in determining whether a vehicle receives a new node
report from another, the position of the candidate recipient vehicle
needs to reasonably up-to-date. The \pvar{stale\_time} configuration
parameter may be set as on line 11 in Listing \ref{lst_unc_econfig}, to
determine the amount of elapsed time without receiving a node report
from a vehicle before it is considered stale. If a recipient vehicle
becomes stale, it will also not receive node messages.

%=================================================================
\subsection*{Ignoring a Group}
\index{uFldNodeComms!IgnoreGroup}
\index{IgnoreGroup!uFldNodeComms}
\label{param_unc_ignore}

The user may specify a group name with the \pvar{ignore\_group} parameter.
All incoming node reports that match this group will simply be ignored.
Introduced after Release 19.8.x.


%=================================================================
%\subsection{A Momentary One-Time Exemption of All Criteria}
%\label{param_unc_exemp}









%=================================================================
\subsection{Optional Limitation on the Node Report Share Rate}
\index{uFldNodeComms!ShareRate}
\index{ShareRate!uFldNodeComms}
\label{param_unc_mri}

The \pvar{min\_report\_interval}, given in seconds, sets the minimum
amount of time between node report messages from one vehicle to
another.  The default value is -1, disabling this feature.

\vspace{0.1in}
\noindent
Note that when the \pvar{view\_node\_rpt\_pulses} parameter is set to
true, then \app{uFldNodeComms} also publishes a visual artifact in a
posting to \mvar{VIEW\_COMMS\_PULSE}. By limiting the node report
share rate, the rate of this variable posting is limited too. This may
also be a consideration in extreme missions of very high numbers of
vehicles and very high time warp, for easing the burden on the viewer,
e.g., \app{pMarineViewer}.


%=================================================================
\subsection{Node Report Transmissions and pShare}
\index{uFldNodeComms!Transmission with pShare}

Node reports are communicated to recipient vehicles in coordination
with the \app{pShare} application. For each unique vehicle name
discovered by \app{uFldNodeComms} via received node reports, it will
publish a new MOOS variable \msvar{NODE\_REPORT\_NAME}. This variable
will be published with the contents of other vehicles' node reports. 

\pskip

As shown in Figure \ref{fig_unc_example}, if three vehicles, {\em
  alpha}, {\em bravo}, and {\em charlie} become known, three
corresponding MOOS variables \msvar{NODE\_REPORT\_ALPHA},
\msvar{NODE\_REPORT\_BRAVO}, and \msvar{NODE\_REPORT\_CHARLIE} will be
published.  The variable \msvar{NODE\_REPORT\_ALPHA} will be published
with reports from {\em bravo} and {\em charlie} and so on.  To make
this happen, \app{uFldNodeComms} needs the corresponding share
relationships from, for example, \msvar{NODE\_REPORT\_ALPHA} in the
shoreside community to the variable \mvar{NODE\_REPORT} in the alpha
community on the alpha vehicle. This sharing relationship is
established separately by the \app{uFldShoreBroker} application
running in the shoreside community.

%=================================================================
\section{Asymmetric Node Report Sharing}
%=================================================================
Under normal circumstances, if one vehicle is within range to send a
node report or message to another, it should also be able to receive
node reports and messages from the same vehicle. In this section we
discuss ways to make this relationship asymmetric. This is done in one
of two ways:

\begin{packed_itemize}
\item Increasing a vehicle's {\em stealth}, i.e., requiring other
  receiving vehicles to be closer than normal to receive reports and
  messages, or
\item Increasing a vehicle's {\em earange}, i.e., allowing other
  receiving vehicles to be farther than normal and still receive
  node reports and messages.
\end{packed_itemize}


%=================================================================
\subsection{Bestowing a Vehicle with an Enhanced Stealth Property}
\label{param_unc_stealth}
\index{uFldNodeComms!Enhanced Stealth}

By using the {\em stealth} parameter, one vehicle may be given a bit
of an advantage. The stealth parameter is assigned to a particular
vehicle and is a number in the range [0.5, 1]. A message from
source to destination is sent if:

\wikihint{width=550}
\begin{equation}
\label{comms_stealth}
 actual\_range(src, dest) &lt; comms\_range * stealth(src) 
\end{equation}

\noindent
By default, the stealth factor for each vehicle is 1. A stealthy
vehicle with a factor of one half, means the receiving vehicle needs
to be twice as close as it would otherwise to receive the stealthy
vehicle's node report or node message. The \pvar{critical\_range}
parameter may be used to override a vehicle's stealthiness with
respect to sending node reports. That is, a message from source to
destination is sent if:

\wikihint{width=550}
\begin{equation}
\label{comms_stealth2}
 actual\_range(src, dest) &lt; max((comms\_range * stealth(src)), critical\_range)
\end{equation}

\noindent
The \pvar{stealth} value for a particular vehicle may be set in the
MOOS configuration file as shown on line 18 in Listing
\ref{lst_unc_econfig}. It may also be set dynamically by receiving
mail on the variable \mvar{UNC\_STEALTH}. For example the posting

\prevgreen
\begin{verbatim}
  UNC_STEALTH = vname=alpha, stealth=0.75
\end{verbatim}
\postverb

\noindent
would immediately reset the stealth factor for vehicle {\em alpha} on
the next iteration. The motivation for exposing this parameter via
incoming MOOS mail is that another shoreside application, monitoring
vehicle speed for example, may reward a vehicle operating in the field
with increased stealth based on any criteria. This can be useful in
constructing vehicle competitions.

%=================================================================
\subsection{Bestowing a Vehicle with an Enhanced Listening Property}

\label{param_unc_earange}
\index{uFldNodeComms!Asymmetric Inter-vehicle Message Arrival}

In addition to the stealth property, a complementary property may be
bestowed upon a vehicle using the \pvar{earange} parameter.  The
earange parameter is assigned to a particular vehicle and is a number
in the range [1, 2]. A message from source to destination is sent
if:

\wikihint{width=550}
\begin{equation}
  actual\_range(src, dest) &lt; comms\_range * earange(dest) 
\end{equation}

\noindent
By default, the earange factor for each vehicle is 1. A vehicle with
a factor of two may receive node reports of another vehicle at twice the
range it may otherwise. In the end the stealth and earange properties 
may cancel each other out when their extreme values are factored together.
Taken together a message from source to destination is sent if:

\begin{equation}
  actual\_range(src, dest) &lt; comms\_range * stealth(src) * earange(dest) 
\end{equation}

\noindent
The \pvar{earange} value for a particular vehicle may be set in the
MOOS configuration file as shown on line 19 in Listing
\ref{lst_unc_econfig}. It may also be set dynamically by receiving
mail on the variable \mvar{UNC\_EARANGE}. For example the posting

\prevgreen
\begin{verbatim}
  UNC_EARANGE = vname=alpha, earange=1.5
\end{verbatim}
\postverb

\noindent
would immediately reset the earange factor for vehicle {\em alpha} on
the next iteration. The motivation for exposing this parameter via
incoming MOOS mail is that another shoreside application, monitoring
vehicle speed for example, may reward a vehicle operating in the field
with increased earange based on any criteria. This can be useful in
constructing vehicle competitions.

%=================================================================
\section{Handling Node Messages}
%=================================================================
\index{uFldNodeComms!Message Handling}

Node messages are of a generic structure for sharing a MOOS variable-value
pair between a source node and a destination node. A node message from
vehicle {\em alpha} to vehicle {\em bravo} would be posted locally by 
{\em alpha} with something like:

\prevgreen
\begin{verbatim}
  NODE_MESSAGE = "src_node=alpha,dest_node=bravo,var_name=FOOBAR,string_val=hello"
\end{verbatim}
\postverb

\noindent
The local \mvar{NODE\_MESSAGE} posting is shared to the shoreside
community running \app{uFldNodeComms} where it is considered for
re-routing to the destination vehicle.

%=================================================================
\subsection{The Criteria for Routing Node Messages}
\index{uFldNodeComms!Routing Criteria}

The basic criteria for sharing node messages is (a) the message
addressee, and (b) the range between the source and destination
vehicles.  Since \app{uFldNodeComms} is receiving and keeping track of
incoming node reports from all vehicles, it has ready access to the
inter-vehicle range between the source and destination nodes. The same
criteria used for sending node {\em reports} is used for sending node
messages. It must meet the range criteria as perhaps modified by the
stealth and earange factors discussed earlier. The only difference is
that the \pvar{critical\_range} parameter is irrelevant for the issue
of sending node messages. This parameter was only used for node
reports in the interest of safety and collision avoidance. There are
however two other factors that may affect node message transmission,
discussed next, message frequency and message size.

%=================================================================
\subsection{Enforcing a Minimum Time Between Node Messages}
\label{param_unc_interval}
\index{uFldNodeComms!Minimum Message Length}

A maximum send frequency is enforced by requiring a minimum wait time
between successful sends from a given source node. This minimum time
is given by the parameter \pvar{min\_msg\_interval} as on line 13 in
Listing \ref{lst_unc_econfig}. The default is 30 seconds. This interval
is defined by the time starting with a successful transmission of a
node message from a source to any destination. A separate log is kept
by \app{uFldNodeComms} for each known vehicle.

\pskip

Further clarification: Suppose for example, the
\pvar{min\_msg\_interval} is set to 60 seconds.  If a vehicle attempts
an outgoing message 58 second after the previous message, it will not
go through. If attempted 4 seconds later or 62 seconds after the
previous successful message, then it will go through. It's as if the
unsuccessful attempt never happened.

\pskip

Continuing this example, consider a vehicle that attempts a message 62
seconds after the previous message was sent. Suppose this new message
fails due to the inter-vehicle range being to large, the message
length being too long, or the destination node not being
recognized. In this case the failure results in another full 60
seconds being needed before the next message will be handled.

%=================================================================
\subsection{Enforcing a Maximum Node Message Length}
\label{param_unc_maxlen}
\index{uFldNodeComms!Maximum Message Length}

The length of node messages may be limited with the parameter
\pvar{max\_msg\_length}, as on line 14 in Listing
\ref{lst_unc_econfig}. The default maximum length is 1000
characters. The length of a message refers to the number of characters
in the \var{string\_val} field. For example, the length of the message

\prevgreen
\begin{verbatim}
  NODE_MESSAGE = "src_node=alpha,dest_node=bravo,var_name=FOOBAR,string_val=hello"
\end{verbatim}
\postverb

\noindent
is five. Limiting the message length is a proxy for inter-vehicle communications
where message packet length is constrained, as with acoustic communications
for example.

%=================================================================
\subsection{Posting Messages to a Vehicle Group}

A node message is typically addressed to another named vehicle. The
sender may also address the message by group name. All vehicles in the
group meeting the prevailing range criteria will receive the
message. The group associated with the vehicle is declared in the node
report sent by that vehicle. A node message using a group address is
similar except for the use of the \var{dest\_group} parameter

\prevgreen
\begin{verbatim}
  NODE_MESSAGE = "src_node=alpha,dest_group=red_team,var_name=FOOBAR,string_val=hello"
\end{verbatim}
\postverb

The sender has the option of indicating {\em both} a group name and vehicle name
as the message destination. It may also specify more than one vehicle name 
explicitly. Thus the following is allowed:

\prevgreen
\begin{verbatim}
  NODE_MESSAGE = "src_node=alpha,dest_name=bravo:charlie:gilda,dest_group=red_team,
                  var_name=FOOBAR,string_val=hello"
\end{verbatim}
\postverb

\noindent
If a destination vehicle is specified twice in the list of
destinations or implicitly in the named group, the message will be
sent only once to the destination vehicle.

%=================================================================
\section{Visual Artifacts for Rendering Inter-Vehicle Communications}
%=================================================================
\label{sec_comms_pulses}

Each time a node report or message is sent to a vehicle by
\app{uFldNodeComms}, another posting is made to the variable
\mvar{VIEW\_COMMS\_PULSE}. This message may be subscribed for by
another application using it to visually render the communications
events. The screen shot in Figure \ref{fig_unc_pulse} below shows four
vehicles. The two bottom vehicles are sharing node reports indicated
by the red and blue comms pulses. 

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/unc_comms_pulse.png}
  \caption{{\bf Communication Pulses:} A visual artifact, a
    \mvvar{VIEW\_COMMS\_PULSE}, is rendered between vehicles when
    either a node report or node message is generated. The white pulse
    indicates a node message, and the non-white pulses indicate a node
    report. The pulse widens from a point at the source vehicle to
    maximum width at the destination vehicle. A pulse will remain
    rendered in pMarineViewer for some number of seconds after initial
    post, unless it is replace by a new pulse with the same label.}
\label{fig_unc_pulse}
\end{figure}
\vspace{0.1in}

The top two vehicles are also
sharing node reports seen by the yellow and green pulses. The bottom
left vehicle has also just sent a node message to the top two vehicles
indicated by the two white pulse. Note the pair of white pulses were
posted a few seconds prior to the present point in time since they
point to vehicle positions just back in the vehicle history. The node
reports are updated continuously, constantly replacing the pulse just
previously posted.

\pskip

The pulse colors are chosen automatically by \app{uFldNodeComms}. They
may be toggled off in \app{pMarineViewer} with the \var{'@'} key.  The
comms pulse is conveyed in a posting to the variable
\mvar{VIEW\_COMMS\_PULSE}.  The format is shown with the following
example.

\prevgreen
\begin{verbatim}
  VIEW_COMMS_PULSE = "sx=109.63,sy=-60.06,tx=30.96,ty=-60.22,beam_width=7,duration=10,
                      fill=0.35,label=JAMES2IKE,edge_color=green,fill_color=red,
                      time=2652414456.59,edge_size=1"
\end{verbatim}
\postverb

\noindent
Comms pulses may be generated by other applications besides
\app{uFldNodeComms}, and may be consumed and rendered by other
applications besides \app{pMarineViewer}. The definition of the comms
pulse object and the methods for serializing and de-serializing
between object and string representation may be found in the
\var{lib\_geometry} library in the moos-ivp software tree.


%=================================================================
\section{Node Report Filtering and Sharing}
%=================================================================
\label{sec_unc_nrshare}

As discussed above, a core input to \app{uFldNodeComms} are all the node
reports arriving from each vehicle. Node reports are needed to:

\begin{packed_itemize}
\item Send node reports back out to other vehicles, serving as proxy AIS
  system between vehicles
\item Determine where vehicles are relative to each other, to decide
  whether inter-vehicle messages are sent from one vehicle to another. 
\end{packed_itemize}

\vspace{0.1in}
\noindent
The rate of node report arrivals may huge, especially when the
shoreside is supporting a multi-vehicle mission of say 50 or more
vehicles, and in simulations of say time warp 50 or higher. On each
vehicle a node report is typically generated by \app{pNodeReporter} at
4Hz. Together this would amount to 10,000 node reports per second. The
\app{uFldNodeComms} app can routinely handle this load without issue
on any machine we have tested.

\vspace{0.1in}
\noindent
However, \app{pMarineViewer} also ingests this same stream of node
reports, primarily for the purpose of updating and rendering vehicle
trajectories. In a high time warp simulation resulting in a single
vehicle generating a node report at 100-200 node reports per second,
this rate is far more than what \app{pMarineViewer} needs to smoothly
render a vehicle trajectory. Roughly 10-20 position updates per second
is sufficient to give the human eye the feeling of a smoothly updated
trajectory.

\vspace{0.1in}
\noindent
As an optional configuration, \app{uFldNodeComms} can be configured to
re-post node reports under a different variable name,
\mvar{NODE\_REPORT\_UNC}. The re-posting is generated at a rate that
considers the prevailing time warp, and ensures a posting rate
commensurate with what is needed for human visual updates,
e.g. 10-20Hz. The idea is conveyed below in Figure
\ref{fig_unc_nrshare}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/unc_report_sharing.png}
  \caption{{\bf Node Report Sharing:} With the optionally node report
    sharing configured, \app{uFldNodeComms} can act as a filter of
    node reports, re-posting node reports at a slower rate, in very
    high time warp situations.}
\label{fig_unc_nrshare}
\end{figure}

\vspace{0.1in}
\noindent
An experienced MOOS user may note that \app{pMarineViewer} could be
configured to simply register for \mvar{NODE\_REPORT} at a slower
rate, when the app registers for this variable. Of course the
registration rate would have to also consider the prevailing time
warp, but this is easy enough. This approach would be problematic
however because using the MOOSDB to filter out say 9 of every 10 node
reports may result in un-even filtering per vehicle. Since all
vehicles publish to \mvar{NODE\_REPORT} and not
\mvar{NODE\_REPORT\_ABE} for example, the above approach may end up
filtering out 99 of 100 reports from one vehicle and 4 of 5 reports
from another, leading to jumpy rendering and false stale report
warnings.

\vspace{0.1in}
\noindent
By shifting node report filtering to \app{uFldNodeComms}, under such
extreme high contact, high time warp situations, \app{uFldNodeComms}
shifts computational burden away from \app{pMarineViewer}. The viewer
is probably the most computationally burdened app running in these
kinds of missions and \app{uFldNodeComms} is already processing the
full set of node reports anyway as part of its basic job. Finally,
most users are typically using a computer with multiple cores
available, with \app{uFldNodeComms} and \app{pMarineViewer} running on
different cores.

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

The \app{uFldNodeComms} application produces some useful information
to the terminal and identical content through appcasting. An example
is shown in Listing \ref{lst_unc_appcast} below.  On line 2, the name
of the local community (usually shoreside) is listed on the left. On
the right, \var{"0/0(1822)} indicates there are no configuration or
run warnings, and the current iteration of \app{uFldNodeComms} is
1822.  Lines 4-13 show the configuration requested from the mission
configuation file.

\vspace{0.1in}
\noindent
Lines 15-30 convey a summary of received and sent node reports from
each vehicle. The number in parentheses at the end of lines 18-22
indicate the elapsed time since the last node report was received.
The number in brackets indicates the rate of received node reports
(total node reports received per vehicle over time since app startup).
This number should roughly equal the AppTick for \app{pNodeReporter}
running on each vehicle.

\vspace{0.1in}
\begin{listing}{Example uFldNodeComms console and appcast output}
\label{lst_unc_appcast}
\footnotesize
\begin{verbatim}
 1  ===================================================================
 2  uFldNodeComms shoreside                                   0/0(1822)
 3  ===================================================================
 4  Configuration:  
 5         Comms Range: 1000
 6      Critical Range: 10
 7          Stale Drop: 5
 8         Stale Foget: 100
 9     Max Message Len: 1000
10     Min Message Int: 20
11     Min Report  Int: 60
12         Apply Group: false
13       Share Reports: true (0.1)
14  
15  Node Report Summary
16  ======================================
17       Total Received: 9112      Elapsed      Rate
18                  ABE: 1828      (0.0)        [3.60]
19                  BEN: 1824      (0.0)        [3.59]
20                  CAL: 1820      (0.0)        [3.58]
21                  DEB: 1818      (0.0)        [3.58]
22                  EVE: 1822      (0.0)        [3.58]
23       --------------- 
24           Total Sent: 90
25                  ABE: 27
26                  BEN: 18
27                  DEB: 18
28                  EVE: 27
29       --------------- 
30       Stale Vehicles: 0
31  
32  Node Message Summary
33  ======================================
34     Total Msgs Received: 3
35                     ABE: 3     (24.9)
36       ------------------ 
37              Total Sent: 3
38                     BEN: 3
39       ------------------ 
40      Total Blocked Msgs: 0
41                 Invalid: 0
42            Missing Info: 0
43          Stale Receiver: 0
44              Too Recent: 0
45            Msg Too Long: 0
46           Range Too Far: 0
47  
48    ===================================================================
49    Most Recent Events (3):
50    ===================================================================
51    [96.22]: Msg rec'd: src_node=abe,dest_node=ben,var_name=UPDATE_LOITER,string_val=speed=2.4
52    [71.10]: Msg rec'd: src_node=abe,dest_node=ben,var_name=UPDATE_LOITER,string_val=speed=2.4
53    [56.46]: Msg rec'd: src_node=abe,dest_node=ben,var_name=UPDATE_LOITER,string_val=speed=2.4
\end{verbatim}
\end{listing}
\normalsize

\noindent
The summary of node messages is shown in the second half of the
report, in lines 32-46 in this case. The total messages received is
shown on line 34, with a breakdown of where they have been received
from in the following lines.  Starting on line 37, a summary of sent
node messages is given. First the total sent messages on line 37 and a
breakdown of receivers in the following lines. A summary of blocked
messages is given next, in this case in lines 40-46. The total number
of blocked messages is given first, followed by the possible reasons
for blocking in lines 41-46. Finally, the most recent messages are
shown as events in the last lines of the report.

%=================================================================
\section{Configuration Parameters of uFldNodeComms}
%=================================================================
The following parameters are defined for \app{uFldNodeComms}. 

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{uFldNodeComms}}
\label{lst_ufsb_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.7\textwidth}} 
  \pvar{comms\_range}: &amp; Max range outside which inter-vehicle node
  reports and node messages will not be sent. Legal values: any
  numerical value. The default is 100 meters. Section
  \ref{param_unc_comms}. \\

  \pvar{critical\_range}: &amp; Range in meters within which inter-vehicle
  node reports will be shared even if group membership would otherwise
  disallow. Legal values: any numerical value. The default is 30
  meters. Section \ref{param_unc_critical}. \\

  \pvar{debug}: &amp; If true, further debugging information is produced to
  the terminal output. Legal values: true, false. The default is
  false. \\

  \pvar{earange}: &amp; A parameter in the range of [1,10] for extending
  the range a vehicle may otherwise hear node reports from other
  vehicles. The default is 1. Section \ref{param_unc_earange}. \\

  \pvar{groups}: &amp; If true, inter-vehicle node reports are shared only
  if two vehicles are in the same group. May be overridden if the two
  vehicles are within the critical range. The vehicle group
  designation is typically declared in \app{pNodeReporter}.  The
  default is false. Section \ref{param_unc_groups}. \\

  \pvar{ignore\_group}: &amp; If specified, incoming node reports that
  match this group will be ignored. Introduced after Release 19.8.x. \\

  \pvar{min\_msg\_interval}: &amp; The number of seconds required between
  messaged sends for any one source vehicle. The default is 30
  seconds. Section \ref{param_unc_interval}. \\

  \pvar{max\_msg\_length}: &amp; The total number of characters that may
  be sent in a string component of a node message. The default is
  1000. Section \ref{param_unc_maxlen}. \\

  \pvar{min\_rpt\_interval}: &amp; The number of seconds required between
  report sends for any one source vehicle. The default is -1, meaning
  no dropping of reports. Section \ref{param_unc_mri}. \\

  \pvar{msg\_groups}: &amp; If true, inter-vehicle node messages are
  shared only if the two vehicles are in the same group. The vehicle
  group designation is typically declared in \app{pNodeReporter}.
  The default is false. Section \ref{param_unc_groups}. \\

  \pvar{msg\_color}: &amp; The color of inter-vehicle message comms
  pulses.  The default is \var{"white"}. Section
  \ref{sec_comms_pulses}. \\

  \pvar{msg\_repeat\_color}: &amp; The color of inter-vehicle message
  comms pulses when the message represents a repeat of a previously
  dropped message, under mediated message passing. The default is
  \var{"light\_green"}. Section \ref{sec_comms_pulses}. \\

  \pvar{stealth}: &amp; A parameter in the range [0,1] for reducing the
  range other vehicles may otherwise hear the node reports from a
  source vehicle. The default is 1. Section
  \ref{param_unc_stealth}.\\

  \pvar{pulse\_duration}: &amp; A duration, in seconds, that the comms or
  node pulse should be viewable. It is a field in
  \mvar{VIEW\_COMMS\_PULSE} message that is respected by at least
  \app{pMarineViewer} to render and slowly fade-out the rendering
  after this duration. The default is 10 seconds. Section
  \ref{sec_comms_pulses}. \\

  \pvar{shared\_node\_reports}: &amp; When enabled with \var{true}, node
  reports are re-posted to the shoreside community as
  \mvar{NODE\_REPORT\_UNC}.  The default is false. This feature may
  also be more commonly enabled via in incoming message. See
  \var{UNC\_SHARED\_NODE\_REPORTS}. Section \ref{sec_unc_nrshare}.\\

  \pvar{stale\_time}: &amp; Time in seconds after which a vehicle will not
  receive node reports or messages unless a node report has been
  received by that vehicle. The default is 5 seconds. Section
  \ref{param_unc_stale}.\\

  \pvar{verbose}: &amp; If true, status reports are displayed to the
  terminal during operation. The default is false. \\

  \pvar{view\_node\_rpt\_pulses}: &amp; If true, comms pulses are rendered
  between vehicles whenever a node report successfully makes its way
  from one vehicle to another. The default is true. Section
  \ref{sec_comms_pulses}. \\
\end{longtable}
\end{listing}

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

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

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

\vspace{0.25in}
\begin{listing}{Example configuration of the \app{uFldNodeComms} application}
\label{lst_unc_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  uFldNodeComms Example MOOS Configuration                      
  3  ===============================================================
  4
  5  ProcessConfig = uFldNodeComms                            
  6  {             
  7    AppTick   = 4     
  8    CommsTick = 4    
  9                                                                  
 10    comms_range    = 100       // default (in meters)
 11    critical_range = 30        // default (in meters)
 12    stale_time     = 5         // default (in seconds
 13    
 14    max_msg_length   = 1000    // default (# of characters)       
 15    min_msg_interval = 30      // default (in seconds)               
 16    min_rpt_interval = -1      // default (in seconds)
 17    
 18    verbose    = true          // default
 19    groups     = false         // default 
 20    msg_groups = false         // default
 21                                                                 
 22    stealth  = vname=alpha, stealth=0.8  
 23    earange  = vname=alpha, earange=4.5  
 24 
 25    shared_node_reports = true/false or any non-neg number 
 26
 27    pulse_duration = 10;         // default (in seconds)
 27    view_node_rpt_pulses = true  // default
 28  }                   
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Publications and Subscriptions for uFldNodeComms}
%===================================================================
\index{uFldNodeComms!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldNodeComms}
\label{sec_unc_interface}

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


%===================================================================
\subsection{Variables Published by uFldNodeComms}
\label{sec_unc_pubs}

The primary output of \app{uFldNodeComms} to the MOOSDB are the node
reports and node messages out to the recipient vehicles, and visual
artifacts to be used for rendering the inter-vehicle communications.

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

\item \mvar{NODE\_MESSAGE\_&lt;VNAME&gt;}: Node messages destined to be sent
  to a destination vehicle \var{&lt;VNAME&gt;} indicated as the recipient in
  the node message. 

\item \mvar{NODE\_REPORT\_&lt;VNAME&gt;}: Node reports destined to be sent to
  a given vehicle \var{&lt;VNAME&gt;} about the vehicle named in the node
  report. 

\item \mvar{NODE\_REPORT\_UNC}: When node report sharing is enabled,
  a subset of all node reports will be re-posted to this variable.
  See Section \ref{sec_unc_nrshare}. \\

\item \mvar{VIEW\_COMMS\_PULSE}: A visual artifact for rendering the
  sending of a node report or node message between vehicles. 
\end{packed_itemize}

%===================================================================
\subsection{Variables Subscribed for by uFldNodeComms}
\label{sec_unc_subs}

The \app{uFldNodeComms} 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}: A node message from one vehicle to another.

\item \mvar{NODE\_REPORT}: A node report for a given vehicle from
  \app{pNodeReporter}.

\item \mvar{NODE\_REPORT\_LOCAL}: Another name for a node report for a
  given vehicle from \app{pNodeReporter}.

\item \mvar{UNC\_STEALTH}: The extra stealth allowed a given vehicle to
  "hide" node reports to others.

\item \mvar{UNC\_EARANGE}: The extra range allowed a given vehicle to
  "hear" node reports of others.

\item \mvar{UNC\_FULL\_REPORT\_REQ}: For a given vehicle name, the
  next node report from each of the other vehicles will be received,
  regardless of all other criteria such as range, frequency,
  group. This only applies for the very next report only, then all
  criteria reverts. This is a convenient debugging tool.

\item \mvar{UNC\_SHARED\_NODE\_REPORTS}: If enabled, set to true,
  \app{uFldNodeComms} will re-post node reports from all vehicles to
  the variable \mvar{NODE\_REPORT\_UNC} but will clamp the publication
  rate, regardless of time warp, to a rate suitable for visual
  consumption, typically no more than 10 updates per second per
  vehicle.  This feature is used in coordination with
  \app{pMarineViewer} to improve performance in high time warp
  missions with a high number of contacts. This variable is typically
  published by \app{pMarineViewer} requesting this service from
  \app{uFldNodeComms}. Section \ref{sec_unc_nrshare}. \\

\item \mvar{UNC\_VIEW\_NODE\_RPT\_PULSES}: A way for external apps to
  tell \app{uFldNodeComms} to turn off or on the rendering of comms
  pulses whenever a node report is sent from one vehicle to another.
  Section \ref{sec_comms_pulses}.
\end{packed_itemize}

%===================================================================
\subsection*{Command Line Usage of uFldNodeComms}
\label{sec_unc_cmdline}

The \app{uFldNodeComms} 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}
 $ uFldNodeComms --help or -h
\end{consoleverb}
\vspace{0.1 in}

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{uFldNodeComms} tool}
\label{lst_unc_usage}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  Usage: uFldNodeComms file.moos [OPTIONS]                        
  3  =============================================================== 
  4                                                                  
  5  Options:                                                        
  6    --alias=&lt;ProcessName&gt;                                      
  7        Launch uFldNodeComms with the given process               
  8        name rather than uFldNodeComms.                           
  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 the release version of uFldNodeComms.             
 17                                                                  
 18  Note: If argv[2] does not otherwise match a known option,       
 19        then it will be interpreted as a run alias. This is       
 20        to support pAntler launching conventions.                 
\end{verbatim}
\end{listing}
\normalsize
 
\end{document}

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