<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_packages}
\input{../common_latex_definitions}
\input{../common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{pNodeReporter: Summarizing a Node's Position and Status}
\vspace{0.1in}
\labdate{June 2018}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering, CSAIL}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PNodeReporter}
\wikidoc{bugz=pNodeNodeReporter}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
\section{Overview}
%===================================================================
\label{sec_util_pnr}
\index{pNodeReporter}

The \app{pNodeReporter} MOOS application runs on each vehicle (real or
simulated) and generates node-reports (as a proxy for AIS reports) for
sharing between vehicles, depicted in Figure \ref{pnr_topology}.  The
process serves one primary function - it repeatedly gathers local
platform information and navigation data and creates an AIS like
report in the form of the MOOS variable
\mvar{NODE\_REPORT\_LOCAL}. The \mvar{NODE\_REPORT} messages are
communicated between the vehicles and the shore or shipside command
and control through an inter-MOOSDB communications process such as
pShare or via acoustic modem.  Since a node or platform may both
generate and receive reports, the locally generated reports are
labeled with the \var{\_LOCAL} suffix and bridged to the outside
communities without the suffix. This is to ensure that processes
running locally may easily distinguish between locally generated and
externally generated reports.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.78\textwidth]{figures/pnreporter_topology.png}
  \caption{{\bf Typical \vvar{pNodeReporter} usage:} The
    \vvar{pNodeReporter} application is typically used with
    \vvar{pShare} or acoustic modems to share node summaries between
    vehicles and to a shoreside command-and-control GUI.}
  \label{pnr_topology}
\end{figure}
\vspace{0.15in}

To generate the local report, \app{pNodeReporter} registers for the
local \var{NAV\_*} vehicle navigation data and creates a report in the
form of a single string posted to the variable
\mvar{NODE\_REPORT\_LOCAL}. An example of this variable is given in
below in Section \ref{sec_pnr_nrep}. The \app{pMarineViewer} and
\app{pHelmIvP} applications are two modules that consume and parse the
incoming \mvar{NODE\_REPORT} messages.

\pskip

The \app{pNodeReporter} utility may also publish a second report, the
\mvar{PLATFORM\_REPORT}. While the \mvar{NODE\_REPORT} summary consists of
an immutable set of data fields described later in this section, the 
\mvar{PLATFORM\_REPORT} consists of data fields configured by the user
and may therefore vary widely across applications. The user may also
configure the frequency in which components of the \mvar{PLATFORM\_REPORT}
are posted within the report.

%===================================================================
\section{Using pNodeReporter}
%===================================================================

%===================================================================
\subsection{Overview Node Report Components}
\label{sec_pnr_nrep}

The primary output of \app{pNodeReporter} is the node report string.
It is a comma-separated list of key-value pairs. The order of the
pairs is not significant. The following is an example report:

\prevgreen
\begin{verbatim}
NODE_REPORT_LOCAL = "NAME=alpha,TYPE=UUV,TIME=1252348077.59,X=51.71,Y=-35.50,
                    LAT=43.824981,LON=-70.329755,SPD=2.00,HDG=118.85,YAW=118.84754,
                    DEP=4.63,LENGTH=3.8,MODE=MODE@ACTIVE:LOITERING"
\end{verbatim}
\postverb

\noindent
The \var{TIME} reflects the Coordinated Universal Time as indicated by
the system clock running on the machine where the MOOSDB is
running. Speed is given in meters per second, heading is in degrees in
the range $[0, 360)$, depth is in meters, and the local x-y
  coordinates are also in meters. The source of information for these
  fields is the \msvar{NAV\_*} navigation MOOS variables such as
  \mvar{NAV\_SPEED}. The report also contains several components
  describing characteristics of the physical platform, and the state
  of the IvP Helm, described next.

\pskip

If desired, \app{pNodeReporter} may be configured to use a different
variable than \mvar{NODE\_REPORT\_LOCAL} for its node reports, by
setting the configuration parameter \pvar{node\_report\_output} to
\var{MY\_REPORT} for example.  Most applications that subscribe to
node reports, subscribe to two variables, \mvar{NODE\_REPORT\_LOCAL}
and \mvar{NODE\_REPORT}. This is because node reports are meant to be
bridged to other MOOS communities (typically with \app{pShare} but not
necessarily). A node report should be broadcast only from the
community that generated the report. In practice, to ensure that node
reports that arrive in one community are not then sent out to other
communities, the node reports generated locally have the \var{\_LOCAL}
suffix, and when they are sent to other communities they are sent to
arrive with the new variable name, minus the suffix.

%===================================================================
\subsection{Helm Characteristics}
\label{sec_pnr_helm}

The node report contains one field regarding the current mode of the
helm, \var{MODE}. Typically the \app{pNodeReporter} and \app{pHelmIvP}
applications are running on the same platform, connected to the same
MOOSDB. When the helm is running, but disengaged, i.e., in manual
override mode, the \var{MODE} field in the node report simply reads
\var{"MODE=DISENGAGED"}. When or if the helm is detected to be not
running, the field reads \var{"MODE=NOHELM-SECS"}, where \var{SECS} is
the number of seconds since the last time \var{pNodeReporter} detected
the presence of the helm, or \var{"MODE=NOHELM-EVER"} if no helm
presence has ever been detected since \app{pNodeReporter} has been
launched. 

\pskip

How does \app{pNodeReporter} know about the health or status of the
helm? It subscribes to two MOOS variables published by the helm,
\mvar{IVPHELM\_STATE} and \mvar{IVPHELM\_SUMMARY}. These are described
more fully in helm documentation, but below are typical example values:

\prevgreen
\begin{verbatim}
  IVPHELM_STATE   = "DRIVE"

  IVPHELM_SUMMARY = "iter=72,ofnum=1,warnings=0,time=127349406.22,solve_time=0.00,
                     create_time=0.00,loop_time=0.00,var=course:209.0,var=speed:1.2,
                     halted=false,running_bhvs=none,modes=MODE@ACTIVE:LOITERING,
                     active_bhvs=loiter$17.8$100.00$9$0.04$0/0,completed_bhvs=none
                     idle_bhvs=waypt_return$17.8$0/0:station-keep$17.8$n/a
\end{verbatim}
\postverb

The \mvar{IVPHELM\_STATE} variable is published on each iteration of
the \app{pHelmIvP} process regardless of whether the helm is in manual
override (\var{"PARK"}) mode or not, and regardless of whether the
value of this variable has changed between iterations. It is
considered the "heartbeat" of the helm. This is the variable monitored
by \app{pNodeReporter} to determine whether a \var{"NOHELM"} message
is warranted. By default, a period of five seconds is used as a
threshold for triggering a \var{"NOHELM"} warning. This value may be
changed by setting the \pvar{nohelm\_threshold} configuration
parameter.

\pskip

When the helm is indeed engaged, i.e., not in manual override mode,
the value of \mvar{IVPHELM\_STATE} posting simply reads \var{"DRIVE"},
but the helm further publishes the \mvar{IVPHELM\_SUMMARY} variable
similar to the above example. If the user has chosen to configure the
helm using hierarchical mode declarations (as described in helm
documentation), the \mvar{IVPHELM\_SUMMARY} posting will include a
component such as \var{"modes=MODE@ACTIVE:LOITERING"} as above. This
value is then included in the node report by \app{pNodeReporter}. If
the helm is not configured with hierarchical mode declarations, the
node report simply reports \var{"MODE=DRIVE"}.

%===================================================================
\subsection{Platform Characteristics}
\label{sec_pnr_plat}

The node report contains three fields regarding the platform
characteristics, \var{NAME}, \var{TYPE}, and \var{LENGTH}. The name of
the platform is equivalent to the name of the MOOS community within
which \app{pNodeReporter} is running. The MOOS community is declared
as a global MOOS parameter (outside any given process' configuration
block) in the \var{.moos} mission file. The \var{TYPE} and
\var{LENGTH} parameters are set in the \app{pNodeReporter}
configuration block. They may alternatively derive their values from a
MOOS variable posted elsewhere by another process. The user may
configure \app{pNodeReporter} to use this external source by naming
the MOOS variables with the \pvar{platform\_length\_src} and
\var{platform\_type\_src} parameters. If both the source and explicit
values are set, as for example:

\prevblue
\begin{verbatim}
  platform_length     = 12              // meters
  platform_length_src = SYSTEM_LENGTH   // A MOOS Variable
\end{verbatim}
\postverb

\noindent
then the explicit length of $12$ would be used only if the MOOS
variable \mvar{SYSTEM\_LENGTH} remained unwritten to by any other MOOS
application connected to the MOOSDB. The platform length and type may
be used by other platforms as a parameter affecting collision avoidance
algorithms and protocol. They are also used in the \app{pMarineViewer}
application to allow the proper platform icon to be displayed at the
proper scale.

\pskip

If the platform type is known, but no information about the platform
length is known, certain rough default values may be used if the
platform type matches one of the following: \var{"kayak}" maps to 4
meters, \var{"mokai"} maps to 4 meters, \var{"uuv"} maps to 4 meters,
\var{"auv"} maps to 4 meters, \var{"ship"} maps to 18 meters,
\var{"glider"} maps to 3 meters.

\pskip

A color may also be associated with a vehicle, which can be useful in applications
like \app{pNodeReporter} or \app{alogview} to indicate a team, or a certain
vehicle configuration. This configuration parameter is completely optional. To 
specify the color:

\prevblue
\begin{verbatim}
  plstform_color    = dodgerblue 
\end{verbatim}
\postverb


%===================================================================
\subsection{Dealing with Local versus Global Coordinates}
\label{sec_pnr_crossfill}

A primary component of the node report is the current position of the
vehicle. The \app{pNodeReporter} application subscribes for the
following MOOS variables to garner this information:
\var{NAV\_X}, \var{NAV\_Y} in local coordinates, and the pair
\var{NAV\_LAT}, \var{NAV\_LONG} in global coordinates. These two pairs
should be consistent, but what if they aren't? And what if
\var{pNodeReporter} is receiving mail for one pair but not the other?
Three distinct policy choices are supported:

\begin{itemize}
\item The default policy: node reports include exactly what is
  given. If \mvar{NAV\_X} and \mvar{NAV\_Y} are being received only,
  then there will be no entry in the node report for global
  coordinates, and vice versa. If both pairs are being received, then
  both pairs are reported. No attempt is made to check or ensure that
  they are consistent.  This is the default policy, equivalent to the
  configuration \pvar{cross\_fill\_policy}\psvar{=literal}.

\item If one of the two pairs is not being received,
  \app{pNodeReporter} will fill in the missing pair from the
  other. This policy can be chosen with the configuration
  \pvar{cross\_fill\_policy}\psvar{=fill-empty}.

\item If one of the two pairs has been received more recently, the
  older pair is updated by converting from the other pair. The older
  pair may also be in a state where it has never been received.  This
  policy can be chosen with the configuration
  \pvar{cross\_fill\_policy}\psvar{=fill-latest}.
\end{itemize}

%===================================================================
\subsection{Processing Alternate Navigation Solutions}
\label{sec_pnr_altnav}

Under normal circumstances, node reports are generated reflecting the
current navigation solution as defined by the incoming \var{NAV\_*}
variables. The \app{pNodeReporter} application can handle the case
where the vehicle also publishes an alternate navigation solution, as
defined by a sister set of incoming MOOS variables separate from the
\var{NAV\_*} variables. In this case \app{pNodeReporter} will monitor
both sets of variables and may generate {\em two} node reports on each
iteration. The following two configuration parameters are needed to
activate this capability:

\prevblue
\begin{verbatim}
  alt_nav_prefix = &lt;prefix&gt;      // example: NAV_GT_
  alt_nav_name   = &lt;node-name&gt;   // example: _GT
\end{verbatim}
\postverb

\noindent
The configuration parameter, \pvar{alt\_nav\_prefix}, names a prefix
for the alternate incoming navigation variables. For example,
\pvar{alt\_nav\_prefix}\psvar{=NAV\_GT\_} would result in
\app{pNodeReporter} subscribing for \mvar{NAV\_GT\_X},
\mvar{NAV\_GT\_Y} and so on. A separate vehicle state would be
maintained internally based on this alternate set of navigation
information and a second node report would be generated.

\pskip

A second node report would be published under the same MOOS variable,
\mvar{NODE\_REPORT\_LOCAL}, but the \var{NAME} component of the report
would be distinct based on the value provided in the
\pvar{alt\_nav\_name} parameter. If a name is provided that does not
begin with an underscore character, that name is used. If the name
does begin with an underscore, the name used in the report is the
otherwise configured name of the vehicle plus the suffix.

%===================================================================
\section{The Optional Blackout Interval Option}
\label{sec_pnr_blackout}

Under normal circumstances, the \app{pNodeReporter} application will
post a node report once per iteration, the gap between postings being
determined solely by the \pvar{app\_tick} parameter (Figure
\ref{pnr_gap_one}). However, there are times when it is desirable to
add an artificial delay between postings. Node reports are typically
only useful as information sent to another node, or to a shoreside
computer rendering fielded vehicles, and there are often dropped node
report messages due to the uncertain nature of communications in the
field, whether it be acoustic communications, wifi, or satellite link.

\pskip

Applications receiving node reports usually implement provisions that
take dropped messages into account. A collision-avoidance or
formation-following behavior, or a contact manager, may extrapolate a
contact position from its last received position and trajectory.  A
shoreside command-and-control GUI such as \app{pMarineViewer} may
render an interpolation of vehicle positions between node reports. To
test the robustness of applications needing to deal with dropped
messages, a way of simulating the dropped messages is desired. One way
is to add this to the simulation version of whatever communications
medium is being used. For example, there is an acoustic communications
simulator where the dropping of messages may be simulated, where the
probability of a drop may even be tied to the range between
vehicles. Another way is to simply simulate the dropped message at the
source, by adding delay to the posting of reports by
\app{pNodeReporter}.

\pskip

By setting the \pvar{blackout\_interval} parameter, \app{pNodeReporter}
may be configured to ensure that a node report is not posted until
{\em at least} the duration specified by this parameter has elapsed, 
as shown in Figure \ref{pnr_gap_two}.


\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figures/pnr_interval1.png}
  \caption{{\bf Normal schedule of node report postings}: The
    \vvar{pNodeReporter} application will post node reports once per
    application iteration. The duration of time between postings is
    directly tied to the frequency at which \vvar{pNodeReporter} is
    configured to run, as set by the standard MOOS \vvar{AppTick}
    parameter.}
\label{pnr_gap_one}
\end{figure}
\vspace{0.15in}

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figures/pnr_interval2.png}
  \caption{{\bf The optional blackout interval parameter:} The
    schedule of node report postings may be altered by the setting the
    \vvar{BLACKOUT\_INTERVAL} parameter. Reports will not be posted
    until at least the time specified by the blackout interval has
    elapsed since the previous posting.}
\label{pnr_gap_two}
\end{figure}
\vspace{0.15in}

An element of unpredictability may be added by specifying a value for
the \pvar{blackout\_variance} parameter. This parameter is given in
seconds and defines an interval $[-t, t]$ from which a value is chosen
with uniform probability, to be added to the duration of the blackout
interval. This variation is re-calculated after each interval
determination. The idea is depicted in Figure \ref{pnr_gap_three}.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figures/pnr_interval3.png}
  \caption{{\bf Blackout intervals with varying duration:} The
    duration of a blackout interval may be configured to vary randomly
    within a user-specified range, specified in the
    \pvar{blackout\_variance} parameter.}
\label{pnr_gap_three}
\end{figure}
\vspace{0.15in}

Message dropping is typically tied semi-predictably to characteristics
of the environment, such as range between nodes, water temperature or
platform depth, an so on. This method of simulating dropped messages
captures none of that. It is however simple and allows for easily
proceeding with the testing of applications that need to deal with the
dropped messages.

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

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for pNodeReporter}
\label{lst_pmv_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 

  \pvar{alt\_nav\_prefix}: &amp; Source for processing alternate nav
  reports.  Section \ref{sec_pnr_altnav}. \\

   \pvar{alt\_nav\_name}: &amp; Node name in posting alternate nav
   reports. Section \ref{sec_pnr_altnav}. \\

  \pvar{blackout\_interval}: &amp; Minimum duration, in seconds, between
  reports (0). Section \ref{sec_pnr_blackout}. \\

  \pvar{blackout\_variance}: &amp; Variance in uniformly random blackout
  duration. Legal values: any non-negative value. The default is
  zero. Section \ref{sec_pnr_blackout}. \\

  \pvar{crossfill\_policy}: &amp; Policy for handling local versus
  global nav reports (\var{"literal"}).  Section
  \ref{sec_pnr_crossfill}. \\

  \pvar{node\_report\_output}: &amp; MOOS variable used for the node
  report (\mvar{NODE\_REPORT\_LOCAL}). Section \ref{sec_pnr_nrep}. \\

  \pvar{nohelm\_threshold}: &amp; Seconds after which a quiet helm is
  reported as AWOL. Legal values: any non-negative value. The default
  is 5 seconds. Section \ref{sec_pnr_helm}. \\

  \pvar{platform\_length}: &amp; The reported length of the platform in
  meters. Legal values: any non-negative value. The default is
  zero. Section \ref{sec_pnr_plat}. \\

  \pvar{plat\_report\_output}: &amp; The Platform report MOOS
  variable. Legal values: conventions for MOOS variable names. The
  default is \mvar{PLATFORM\_REPORT\_LOCAL}. Section
  \ref{sec_pnr_prep}. \\

  \pvar{plat\_report\_input}: &amp; A component of the optional platform
  report. Section \ref{sec_pnr_prep}. \\

  \pvar{platform\_color}: &amp; A hint on how to render the vehicle in a
  GUI application like \app{pMarineViewer} or \app{alogview}.
  Introduced in Release 16.5. Section \ref{sec_pnr_plat}. \\

  \pvar{platform\_type}: &amp; The reported type of the platform. Legal
  values: any string. The default is \var{"unknown"}. Section
  \ref{sec_pnr_plat}. \\

  \pvar{paused}: &amp; If true, posting of reports is suspended.
  The default is \var{"false"}. With release 15.3. \\

\end{longtable}
\end{listing}

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

An example MOOS configuration block is provided in Listing
\ref{lst_pnr_econfig} below.  To see an example MOOS configuration
block from the console, enter the following:

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

\noindent
This will show the output shown in Listing \ref{lst_pnr_econfig} below.

\vspace{0.2in}
\begin{listing}{Example configuration of pNodeReporter}
\label{lst_pnr_econfig}
\footnotesize
\begin{verbatim}
   1  =============================================================== 
   2  pNodeReporter Example MOOS Configuration                        
   3  =============================================================== 
   4  Blue lines: Default configuration                        
   5                                                                  
   6  ProcessConfig = pNodeReporter                                   
   7  {                                                               
   8    AppTick   = 4                                                 
   9    CommsTick = 4                                                 
  10                                                                  
  11    // Configure key aspects of the node                          
  12    platform_type      = glider   // or {uuv,auv,ship,kayak}   
  13    platform_length    = 8        // meters.  Range [0,inf)    
  14                                                                  
  15    // Configure optional blackout functionality                  
  16    blackout_interval  = 0        // seconds. Range [0,inf)    
  17                                                                  
  18     // Configure the optional platform report summary            
  19    plat_report_input  = COMPASS_HEADING, gap=1                   
  20    plat_report_input  = GPS_SAT, gap=5                           
  21    plat_report_input  = WIFI_QUALITY, gap=1                      
  22    plat_report_output = PLATFORM_REPORT_LOCAL                    
  23                                                                  
  24    // Configure the MOOS variable containg the node report       
  25    node_report_output = NODE_REPORT_LOCAL                        
  26                                                                  
  27    // Threshold for conveying an absense of the helm             
  28    nohelm_threshold   = 5        // seconds                   
  39                                                                  
  30    // Policy for filling in missing lat/lon from x/y or v.versa  
  31    crossfill_policy   = literal  // or {fill-empty,use-latest}
  32                                                                  
  33    // Configure monitor/reporting of dual nav solution           
  34    alt_nav_prefix     = NAV_GT                                   
  35    alt_nav_name       = _GT                                      
  36  }                                                        
\end{verbatim}
\end{listing}
\normalsize

%===================================================================
\section{Publications and Subscriptions for pNodeReporter}
%===================================================================
\index{pNodeReporter!Publications and Subscriptions}
\index{Publications and Subscriptions!pNodeReporter}
\label{sec_pnr_interface}

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

\begin{consoleverb}
 $ pNodeReporter --interface or -i
\end{consoleverb}

%===================================================================
\subsection{Variables Published by pNodeReporter}
\label{sec_pnr_pubs}

The primary output of pNodeReporter to the MOOSDB is the node
report and the optional platform report:

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

\item \mvar{NODE\_REPORT\_LOCAL}: Primary summary of the node's
  navigation and helm status. Section \ref{sec_pnr_nrep}.

\item \mvar{PLATFORM\_REPORT\_LOCAL}: Optional summary of certain
  platform characteristics. Section \ref{sec_pnr_plat}.
\end{packed_itemize}

%===================================================================
\subsection{Variables Subscribed for by pNodeReporter}
\label{sec_pnr_subs}

Variables subscribed for by \app{pNodeReporter} are summarized below.
A more detailed description of each variable follows. In addition to
these variables, any MOOS variable that the user requests to be
included in the optional \mvar{PLATFORM\_REPORT} will also be
automatically subscribed for.

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

\item \mvar{IVPHELM\_STATE}: A indicator of the helm state produced by
  \app{pHelmIvP}, e.g., \var{"PARK"}, \var{"DRIVE"} \var{"DISABLED"},
  or \var{"STANDBY"}.

\item \mvar{IVPHELM\_ALLSTOP}: A indicator of the helm allstop produced by
  \app{pHelmIvP}, e.g., \var{"clear"}, or a reason why the vehicle is
  at zero speed.

\item \mvar{IVPHELM\_SUMMARY}: A summary report produced by the IvP
  Helm (pHelmIvP).
 
\item \mvar{NAV\_X}: The ownship vehicle position on the $x$ axis of
  local coordinates.

\item \mvar{NAV\_Y}: The ownship vehicle position on the $y$ axis of
  local coordinates. 

\item \mvar{NAV\_LAT}: The ownship vehicle position on the $y$ axis of
  global coordinates. 

\item \mvar{NAV\_LONG}: The ownship vehicle position on the $x$ axis
  of global coordinates.

\item \mvar{NAV\_HEADING}: The ownship vehicle heading in degrees. 
  
\item \mvar{NAV\_YAW}: The ownship vehicle yaw in radians. 
     
\item \mvar{NAV\_SPEED}: The ownship vehicle speed in meters per second. 

\item \mvar{NAV\_DEPTH}: The ownship vehicle depth in meters. 
 
\item \mvar{PNR\_PAUSE}: Allows the paused state to be set or
  toggled. Acceptable values are \var{"true"} \var{"false"}
  \var{"toggle"}. With release 15.3.
 
\end{packed_itemize}

\noindent
If \app{pNodeReporter} is configured to handle a second navigation
solution as described in Section \ref{sec_pnr_altnav}, the
corresponding additional variables described in that section will also
be automatically subscribed for.

%===================================================================
\subsection{Command Line Usage of pNodeReporter}
\label{sec_pnr_cmdline}
\index{Command Line Usage!pNodeReporter}
\index{pNodeReporter!Command Line Usage}
\index{Configuration Parameters!pNodeReporter}
\index{pNodeReporter!Configuration Parameters}

The \var{pNodeReporter} application is typically launched as a part
of a batch of processes by pAntler, but may also be launched from the
command line by the user. The basic command line usage for the
\var{pNodeReporter} application is the following:

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{pNodeReporter} application}
\label{pnr_usage}
\footnotesize
\begin{verbatim}
  1  Usage: pNodeReporter file.moos [OPTIONS]               
  2                                                            
  3  Options:                                                  
  4    --alias=&lt;ProcessName&gt;                                   
  5        Launch pNodeReporter with the given process name    
  6        rather than pNodeReporter.                          
  7    --example, -e                                           
  8        Display example MOOS configuration block.           
  9    --help, -h                                              
 10        Display this help message.                          
 11    --version,-v                                            
 12        Display the release version of pNodeReporter.      
\end{verbatim}
\end{listing}
\normalsize

%===================================================================
\section{The Optional Platform Report Feature}
%===================================================================
\label{sec_pnr_prep}

The \app{pNodeReporter} application allows for the optional reporting
of another user-specified list of information. This report is made by
posting the \mvar{PLATFORM\_REPORT\_LOCAL} variable. An alternative
variable name may be used by setting the \mvar{PLAT\_REPORT\_SUMMARY}
configuration parameter. This report may be configured by specifying
one or more components in the \app{pNodeReporter} configuration
block, of the following form:

\prevblue
\begin{verbatim}
   plat_report_input = &lt;variable&gt;, gap=&lt;duration&gt;, alias=&lt;variable&gt;
\end{verbatim}
\postverb

If no component is specified, then no platform report will be
posted. The \var{&lt;variable&gt;} element specifies the name of a MOOS
variable.  This variable will be automatically subscribed for by
\app{pNodeReporter} and included in (not necessarily all) postings of
the platform report. If the variable \msvar{BODY\_TEMP} is specified, a
component of the report may contain \msvar{"BODY\_TEMP=98.6"}. An alias
for a MOOS variable may be specified. For example, \var{alias=T}, for
the \msvar{BODY\_TEMP} component would result in \var{"T=98.6"} in the
platform report instead.

\pskip

How often is the platform report posted? Certainly it will not be
posted any more often than the \pvar{apptick} parameter allows, but it
may be posted far more infrequently depending on the user
configuration and how often the values of its components are changing.
The platform report is posted only when one or more of its components
requires a re-posting. A component requires a re-posting only if (a)
its value has changed, {\em and} (b) the time specified by its gap
setting has elapsed since the last platform report that included that
component. When a \mvar{PLATFORM\_REPORT\_LOCAL} posting is made, only
components that required a posting will be included in the report.

\pskip

The wide variation in configurations of the platform report allow for
reporting information about the node that may be very specific to the
platform, not suitable for a general-purpose node report. As an
example, consider a situation where a shoreside application is running
to monitor the platform's battery level and whether or not the payload
compartment has suffered a breach, i.e., the presence of water is
detected inside. A platform report could be configured as follows:

\prevblue
\begin{verbatim}
   plat_report_input = ACME_BATT_LEVEL, gap=300, alias=BATTERY_LEVEL
   plat_report_input = PAYLOAD_BREACH
\end{verbatim}
\postverb

\noindent
This would result in an initial posting of:

\prevgreen
\begin{verbatim}
   PLATFORM_REPORT_LOCAL = "platform=alpha,utc_time=1273510720.99,BATTERY_LEVEL=97.3,
                           PAYLOAD_BREACH=false"             
\end{verbatim}
\postverb

\noindent
In this case, the platform uses batteries made by the ACME Battery
Company and the interface to the battery monitor happens to publish
its value in the variable \msvar{ACME\_BATT\_LEVEL}, and the software on
the shoreside that monitors all vehicles in the field accepts the
generic variable \msvar{BATTERY\_LEVEL}, so the alias is used. It is
also known that the ACME battery monitor output tends to fluctuate a
percentage point or two on each posting, so the platform report is
configured to include a battery level component no more than once
every five minutes, (\var{gap=300}). The MOOS process monitoring the
indication of a payload breach is known to have few false alarms and
to publish its findings in the variable \msvar{PAYLOAD\_BREACH}. Unlike
the battery level which has frequent minor fluctuations and degrades
slowly, the detection of a payload breach amounts to the flipping of a
Boolean value and needs to be conveyed to the shoreside as quickly as
possible.  Setting \var{gap=0}, the default, ensures that a platform
report is posted on the very next iteration of \app{pNodeReporter},
presumably to be read by a MOOS process controlling the platform's
outgoing communication mechanism.

%===================================================================
\section{An Example Platform Report Configuration Block for pNodeReporter}
%===================================================================
\index{pNodeReporter}
\index{pNodeReporter!Configuration Parameters}
\index{Configuration Parameters!pNodeReporter}

Listing \ref{lst_pnr_econfig_platrpt} below shows an example
configuration block for \app{pNodeReporter} where an extensive
platform report is configured to report information about the
autonomous kayak platform to support a ``kayak dashboard'' display
running on a shoreside computer. Most of the components in the
platform report are specific to the autonomous kayak platform, which
is precisely why this information is included in the platform report,
and not the node report.

\vspace{0.1in}
\begin{listing}{An example pNodeReporter configuration block}
\label{lst_pnr_econfig_platrpt}
\footnotesize
\begin{verbatim}
  1  //------------------------------------------------------------------
  2  // pNodeReporter config block
  3  
  4  ProcessConfig = pNodeReporter
  5  {
  6    AppTick	= 2
  7    CommsTick	= 2
  8   
  9    platform_type       = KAYAK   
 10    platform_length     = 3.5     // Units in meters
 11    nohelm_thresh       = 5       // The default
 12    blackout_interval   = 0       // The default
 13    blackout_variance   = 0       // The default
 14
 15    node_report_output  = NODE_REPORT_LOCAL        // The default
 16    plat_report_output  = PLATFORM_REPORT_LOCAL    // The default
 17
 18    plat_report_input = COMPASS_PITCH, gap=1
 19    plat_report_input = COMPASS_HEADING, gap=1
 20    plat_report_input = COMPASS_ROLL, gap=1
 21    plat_report_input = DB_UPTIME, gap=1
 22    plat_report_input = COMPASS_TEMPERATURE, gap=1, alias=COMPASS_TEMP
 23    plat_report_input = GPS_MAGNETIC_DECLINATION, gap=10, alias=MAG_DECL
 24    plat_report_input = GPS_SAT, gap=5
 25    plat_report_input = DESIRED_RUDDER, gap=0.5
 26    plat_report_input = DESIRED_HEADING, gap=0.5
 27    plat_report_input = DESIRED_THRUST, gap=0.5
 28    plat_report_input = GPS_SPEED, gap=0.5
 29    plat_report_input = DESIRED_SPEED, gap=0.5
 30    plat_report_input = WIFI_QUALITY, gap=0.5
 31    plat_report_input = WIFI_QUALITY, gap=1.0
 32    plat_report_input = MOOS_MANUAL_OVERRIDE, gap=1.0
 33  }
\end{verbatim}
\end{listing}
\normalsize

\end{document}
</pre></body></html>