<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{pRealm: Integrated Scoping of the MOOSDB}
\vspace{0.1in}
\labdate{December 2020}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labsrc{project-pavlab/appdocs/app\_prealm} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PRealm}
\wikidoc{bugz=pRealm}
\wikidoc{auth=mikerb@mit.edu}

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

The \app{pRealm} application is a tool to enable a shoreside
multi-vehicle scope of the MOOSDB for all connected vehicles, as well
as the shoreside MOOSDB. An instance of \app{pRealm} in each MOOS
community, one per MOOSDB.  It creates a shadow copy of the MOOSDB by
registering for all known variables, i.e., those listed in the
\mvar{DB\_RWSUMMARY} published by the MOOSDB. The \app{pRealm} app
only {\em listens} and keeps a copy of all the mail processed by the
MOOSDB. Occasionally \app{pRealm} will receive and process a request
to produce a report, a \mvar{REALMCAST}, showing the current values of
a subset of known MOOS variables. Typically this subset is correlated
to the subscriptions and publications of a particular app connected to
the local MOOSDB.  The typical usage scenario for \app{pRealm} is
shown in Figure \ref{fig_prm_topology}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.55\textwidth]{figures/prealm_topology.png}
  \caption{{\bf Typical pRealm 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_prm_topology}
\end{figure}

The goal of this application is to enable the user, situated at a
shoreside console, to select any deployed vehicle and scope the MOOSDB
from a variety of vantage points. Initially this means selecting a
vehicle and process and seeing the publications and subscriptions of
that process. This is especially powerful for confirming the flow of
information between vehicles or between vehicles and the shoreside.
The \app{pMarineViewer} app has been substantially augmented to
capitalize on a set of MOOS communities that {\em realm enabled}. If
\app{pRealm} is not enabled, \app{pMarineViewer} and all other apps
will be unaffected.

\vspace{0.1in}
\noindent
The implementation of \app{pRealm} is similar to and based on {\em
  appcasting} which precedes \app{pRealm} by roughly seven years. It
is similar to appcasting in that a realmcast is only generated when
there is a client, e.g. \app{pMarineViewer}, with an open realmcast
window, pointed to a particular vehicle and particular channel. In this
case, \app{pRealm} on the chosen vehicle will only respond with a
generated report solely for the selected channel. Like appcasting,
the realmcast rate generation is immune time the MOOS Time Warp and
will be generated roughly once per second. This regime, like with
appcasting, minimizes bandwidth which may be limited in field operations. 

\vspace{0.1in}
\noindent
Unlike appcasting, \app{pRealm} requires no augmentation to the
participating apps. The only requirement is that an instance of
\app{pRealm} is launched alongside all the apps otherwise launched
in each MOOS community. No configuration is required. Although there
are configuration parameters the user may adjust, the default parameters
are fine in most cases. 

%===================================================================
\section{Configuration Parameters for pRealm}
%===================================================================
\label{sec_prm_params}

The \app{pRealm} application may be configured with a configuration
block within a MOOS mission file, typically with a \var{.moos} file
suffix. Unlike most other MOOS apps, there will no warning generated
if a configuration block is not provided. This is partly because the
default values of parameters rarely need changing, and partly because
not requiring a configuration block makes it even easier to add
\app{pRealm} to existing missions. 
The following parameters are defined for \app{pRealm}.

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

  \pvar{relcast\_interval}: &amp; Time duration, in seconds, that must
  occur between the previously generated realmcast and a new one.
  The allowable range is [0.4, 15]. Values outside this range will
  be clipped to the range. The default value is 0.8 seconds. \\

  \pvar{summary\_interval}: &amp; Time duration, in seconds, between
  auto-generated postings of \mvar{REALMCAST\_CHANNELS}. The allowable
  range is [1, 10]. Values outside this range will be clipped to the
  range. The default value is 2 seconds. \\

  \pvar{wrap\_length}: &amp; The number of characters, per line, when the
  user has opted to have the variable value field wrapped. Legal values
  are any integer value greater than zero. The default is 90. \\

  \pvar{trunc\_length}: &amp; The number of characters that the value
  field of an output line will be truncated to, when the user has
  opted to enable truncated output. Legal values are any integer value
  greater than zero. It is recommended to choose a number that is a
  multiple of the wrap length.  The default is 270. \\

  \pvar{msg\_max\_hist}: &amp; The number of MOOS mail messages held per
  variable. Currently multiple messages are only held for string
  messages. Legal values are any integer value greater than zero.  The
  default is 10. \\

\end{longtable}
\end{listing}

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

An example MOOS configuration block may be obtained from the command line
with the following:

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

\vspace{0.25in}
\begin{listing}{Example configuration of the pRealm application}
\label{lst_phi_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  pHostInfo Example MOOS Configuration                      
  3  ===============================================================
  4                            
  5  ProcessConfig = pRealm                                          
  6  {                                                               
  7    AppTick   = 4                                                 
  8    CommsTick = 4                                                 
  9                                                                
 10    relcast_interval = 0.8       //  [0.4, 15] Default is 0.8     
 11    summary_interval = 2.0       //  [1, 10] Default is 2         
 12    wrap_length = 90             //  [1,inf] Default is 90        
 13    trunc_length = 270           //  [1,inf] Default is 270       
 14    msg_max_history = 10         //  [1,inf] Default is 10        
 15  } 
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Publications and Subscriptions for pRealm}
%===================================================================
\label{sec_prm_interface}

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

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

%===================================================================
\subsection{Variables Published by pRealm}
\label{sec_prm_pubs}

\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{REALMCAST}: Contains a realmcast report, showing the
  current values of a set of MOOS variables. Typically the set of
  variables is related to a particular MOOS app running in the same
  community as \app{pRealm}. This is a multi-line text report that
  has been serialized into a single string. It will be unpacked as
  a multi-line text report by the receiving client.

\item \mvar{REALMCAST\_CHANNELS}: A list channels associated with
  this instance of \app{pRealm}. Typically this list contains the
  names of MOOS apps running in this MOOS community, but may contain
  other user-configured channels.

\item \mvar{WATCHCAST}: Contains a watchcast report, containing the
  the information on the most recent post for a particular single MOOS
  variable.
  
\end{packed_itemize}

%===================================================================
\subsection{Variables Subscribed for by pRealm}
\label{sec_prm_subs}

The \app{pRealm} 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{REALMCAST\_REQ}: A request to generate publications
  to \mvar{REALMCAST} for a specified channel, for specified duration.
  
\item \mvar{DB\_RWSUMMARY}: A report generated by the MOOSDB listing,
  for each app connected to the MOOSDB, the set of variables subscribed for
  by each app, and the set of variables observed to be published by each
  app. 
\end{packed_itemize}

\vspace{0.1in}
\noindent
Node that \app{pRealm} will also subscribe for all variables discovered
from the contents of \mvar{DB\_RWSUMMARY} publications. 

%===================================================================
\subsection{Command Line Usage of pRealm}
\label{sec_prm_cmdline}

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

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

\vspace{0.1in}
\begin{listing}{Command line usage for the pRealm tool}
\label{phi_usage}
\footnotesize
\begin{verbatim}
  1  Usage: pRealm file.moos [OPTIONS]             
  2                                                         
  3  Options:                                               
  4    --alias=&lt;ProcessName&gt;                                
  5        Launch pRealm with the given process    
  6        name rather than pRealm.                
  7    --example, -e                                        
  8        Display example MOOS configuration block         
  9    --help, -h                                           
 10        Display this help message.                       
 11    --HOSTIP=&lt;HostIP&gt;                                          
 12        Force the use of the given IP address as the reported IP  
 13        address ignoring any other auto-discovered IP address.    
 14    --interface, -i                                               
 15        Display MOOS publications and subscriptions.      
 16    --version,-v                                         
 17        Display the release version of pRealm.  
 18 
 19  Note: If argv[2] is not of one of the above formats 
 20        this will be interpreted as a run alias. This 
 21        is to support pAntler launching conventions.  
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Structure of RealmCast Reports}
%===================================================================

The primary output of \app{pRealm} is a realmcast, a posting to the
MOOS variable \mvar{REALMCAST}. If \app{pRealm} is running in a
vehicle MOOS community, then the realmcast is typically shared to the
shoreside community. A realmcast is only generated on demand, to
ensure minimal bandwidth, keeping in mind scenarios with large numbers
of vehicles and limited physical communications bandwidth. In this section
the structure of the realmcast message is described, how this message
is serialized, and how the content of the realmcast message may be
customized at run time to suit user preferences. 

% structure
% serialization
% when generated
% varied content
% 

% X Realmcast reports
% X Realmcast summaries
% X Viewer Preview
% X Using - issue with config
% X AppCast output

%===================================================================
\subsection{The RealmCast Structure}
\label{sec_prm_structure}

The structure of realmcast is simply a list of strings. While there is
a distinct formatting of the report, the end result is the list of
strings with inserted white space. The assumption is that whatever app
is rendering the report will be using a fixed-width character output,
which will preserve the columns and spacing of the report. An example
is shown below. 

\vspace{0.05in}
\begin{consoleverbx}
=======================================
pProxonoi                      ben (33)
=======================================
Subscriptions
=======================================
Variable        Source         Time    Comm       Variable
--------------  -------------  ------  ---------  -------------------------------------------------------
APPCAST_REQ     uMAC_5533      111.44  shoreside  node=all,app=all,duration=3.0,key=uMAC_5533:app,thresh=
NAV_X           uSimMarineX    111.69  ben        5408
NAV_Y           uSimMarineX    111.69  ben        -1725
NODE_REPORT     uFldNodeComms  39.22   shoreside  NAME=abe,X=5327,Y=-1769,SPD=0,HDG=287,TYPE=kayak,COLOR=
PROX_CLEAR      -              never   -          -
PROX_POLY_VIEW  -              never   -          -

=======================================
Publications
=======================================
Variable            Source          Time    Comm  Variable
------------------  --------------  ------  ----  -------------------------------------------------------
APPCAST             uFldNodeBroker  26.28   ben   formatted report
PPROXONOI_ITER_GAP  pProxonoi       111.43  ben   1.011477
PPROXONOI_ITER_LEN  pProxonoi       111.43  ben   0.000436
PPROXONOI_STATUS    pProxonoi       110.93  ben   AppErrorFlag=false,Uptime=112.009,cpuload=0.1298,memory
PROXONOI_PID        pProxonoi       -0.42   ben   63498
PROXONOI_POLY       pProxonoi       111.43  ben   active=false,label=vpoly_ben
PROXONOI_REGION     pProxonoi       110.43  ben   pts={-500,2300:-3500,-1000:-3500,-4600:3100,-4600:8400,
\end{consoleverbx}
\normalsize

\noindent
The above example output is typical of the default format used when \app{pRealm}
is generating a report for a particular application, the \app{pProxonoi}
app in this case. On the top line, the app name is listed on the left,
with the vehicle name on the right. The number in the parentheses is
a counter showning how many reports for this app have been generated.

\vspace{0.1in}
\noindent
The body of the report shows the set of variables subscribed for by
this application, followed by the variables published by this
application. For each variable, the variable name, source, time of the
publication, community and variable contents are shown, similar to
other scoping utilities like \app{uXMS}.

%===================================================================
\subsection{Serialization of the RealmCast Structure}
\label{sec_prm_serialize}

As mentioned above in Section \ref{sec_prm_structure}, a realmcast message
is comprised primarily of a list of strings. The entire message is serialized
into a single string for posting to the MOOSDB. The structure of this
message is:

\footnotesize
\begin{consoleverb}
node=&lt;nodename&gt;!Q!proc=&lt;procname&gt;!Q!count=&lt;num&gt;!Q!line!Z!line!Z!line!Z!....
\end{consoleverb}
\normalsize

\vspace{0.1in}
\noindent
It is comprised of four main components, each separated by \var{"!Q!"}:

\begin{packed_itemize}
\item The {\em node} is typically the name of the vehicle, or \var{"shoreside"}
  if this instance of \app{pRealm} is running in the shoreside community.
\item The {\em proc} is typically the name of the application related to this
  report. A realmcast may be custom configured to contain information not
  strictly correlated with an app. In such a case the {\em proc} name is the
  name used for this custom configuration.
\item The {\em count} represents the number of realmcast reports generated for
  this particular {\em node} and {\em proc} combination.
\item The {\em line} components represent each line in the report, separated
  by the \var{"!Z!"} separator. 
\end{packed_itemize}

\vspace{0.1in}
\noindent
The serialization methods are defined on the C++ class
\var{RealmCast}. There is a function defined to convert from the
RealmCast class to a string:

\begin{consoleverb}
RealmCast relcast;
... structure populated 

string realmcast_report = relcast.get_spec();
\end{consoleverb}

\vspace{0.1in}
\noindent
And a function convert from a string to a RealmCast class instance. 

\begin{consoleverb}
string realmcast_report;
... string otherwise populated

RealmCast relcast = string2Realmast(realmcast_report);
\end{consoleverb}


\vspace{0.1in}
\noindent
Serialization is handled internally by \app{pRealm} and
deserialization is handled internally by the client application, e.g.,
\app{pMarineViewer}.

%===================================================================
\subsection{When RealmCast Reports are Generated}
\label{sec_prm_timing}

The default state of \app{pRealm} is to be not generating any
realmcast messages.  Messages are only generated if there is a client
requesting this information.  A request comes in the form of the MOOS
variable \mvar{REALMCAST\_REQ}. Minimally this message specifies the
\app{pRealm} channel of interest and the duration of time into the
future during which it hopes to receive responding realmcast
messages. The basic idea is shown in Figure \ref{fig_prealmreq_one}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/realmreq_one.png}
  \caption{{\bf RealmCast Request:} A request is generated by a client, 
    specifying a proc (i.e., channel or app), and a duration. For the
    next period in time specified by the duration, \app{pRealm} will
    produce realmcast reports at a fixed interval.}
\label{fig_prealmreq_one}
\end{figure}

\vspace{0.1in}
\noindent
Note that if the client suddenly quits, or turns its attention
elsewhere, after the short duration, \app{pRealm}, resumes being
quiet. Note also that the rate of publications to \mvar{REALMCAST} by
\app{pRealm} is determined by the \app{pRealm} configuration parameter
\pvar{relcast\_interval}. This interval by default is 0.8 seconds. So,
in the above example, a {\em single} request with a duration of five
seconds should result in six realmcast publications. A typical client,
if interested in receiving a steady stream of realmcast reports over a
period longer than five seconds, would simply send requests at a
steady rate somewhat faster than the duration specified in each
request. Each newly received request will reset the duration.

%===================================================================
\section{Altering the RealmCast Format to Suit the User}
\label{sec_prm_format}
%===================================================================

The default format for a typical realmcast report is shown in Section
\ref{sec_prm_structure}. There are seven simple ways to modify the output
to further accommodate the preferences of a user. Each modification is
a simple on/off state that can be toggled by the client application.
As \app{pMarineViewer} is such a client, it has seven on-screen buttons
for toggling the preferences. The seven methods are:

\begin{packed_itemize}
\item Omission of the variable Source column
\item Omission of the variable Community column
\item Omission of the Subscriptions (top) block
\item Masking out certain variables (described in Section \ref{sec_prm_mask})
\item Wrapping the output of the variable Value column
\item Truncating the output of the variabe Value column
\item Showing time stamps in UTC format
\end{packed_itemize}

\vspace{0.1in}
\noindent
Each of the above seven modifications come as part of the client's
request for a realmcast report. A keyword is associated with each
modification, and the absence of the keywork indicates that the
modification is not requested. For example, a realmcast request with
the Source and Community columns suppressed would look something like:

\vspace{0.1in}
\begin{consoleverb}
 REALMCAST_REQ = client=pmv,duration=5,nosrc,nocomm,proc=pProxonoi
\end{consoleverb}
\vspace{0.1in}

\noindent
The keywords for the seven modifications are: \var{nosrc},
\var{nocom}, \var{nosub}, \var{mask}, \var{wrap}, \var{trunc} and
\var{utc} respectively. Each incoming request sets the state for each
of these mods. For example if the next request after the above one
were:

\vspace{0.1in}
\begin{consoleverb}
 REALMCAST_REQ = client=pmv,duration=5,nocomm,proc=pProxonoi
\end{consoleverb}
\vspace{0.1in}

\noindent
then the next outoing realmcast would no longer suppress the Source column for
each variable.


%===================================================================
\subsection{Modifying the Column Output Based on Source and Community}

\vspace{0.1in}
\noindent
By omitting the Source and Community columns the original output from
Section \ref{sec_prm_structure} would look like that below, with both
columns removed in both the Subscriptions block (top) and the
Publications block (bottom):

\vspace{0.05in}
\begin{consoleverbx}
=======================================
pProxonoi                      ben (33)
=======================================
Subscriptions
=======================================
Variable        Time    Value
--------------  ------  -------------------------------------------------------
APPCAST_REQ     111.44  node=all,app=all,duration=3.0,key=uMAC_5533:app,thresh=run_warning
NAV_X           111.69  5408
NAV_Y           111.69  -1725
NODE_REPORT      39.22  NAME=abe,X=5327,Y=-1769,SPD=0,HDG=287,TYPE=kayak,COLOR=dodgerblue,MODE=PARK,ALLSTO
PROX_CLEAR      never   -
PROX_POLY_VIEW  never   -

=======================================
Publications
=======================================
Variable            Time    Value
------------------  ------  -------------------------------------------------------
APPCAST             26.28   formatted report
PPROXONOI_ITER_GAP  111.43  1.011477
PPROXONOI_ITER_LEN  111.43  0.000436
PPROXONOI_STATUS    110.93  AppErrorFlag=false,Uptime=112.009,cpuload=0.1298,memory_kb=1768,memory_max_kb=
PROXONOI_PID        -0.42   63498
PROXONOI_POLY       111.43  active=false,label=vpoly_ben
PROXONOI_REGION     110.43  pts={-500,2300:-3500,-1000:-3500,-4600:3100,-4600:8400,2300},label=prox_opregi
\end{consoleverbx}
\normalsize

\vspace{0.1in}
\noindent
The modified output simply allows more of the righthand Value columm
to be more visible to the user.

%===================================================================
\subsection{Modifying the Row Output By Masking and Dropping Subscriptions}
\label{sec_prm_mask}

Notice the last two lines of Subscriptions section of the above
output. These two variables have never been written to. They are
included in the output because \app{pRealm} noticed in the
\mvar{DB\_RWSUMMARY} content that this particular app subscribes to
those two variables. And at times it is helpful to see exactly the
list of variables subscribed to for a given app. For some apps,
however, these virgin variables can take big chunk of the report
space, and it may be better to mask them out. This can be achieved by
attaching the \var{mask} keyword to the realmcast request. The
resulting output is shown below, with the two lines dropped.

\vspace{0.05in}
\begin{consoleverbx}
=======================================
pProxonoi                      ben (33)
=======================================
Subscriptions
=======================================
Variable        Time    Value
--------------  ------  -------------------------------------------------------
APPCAST_REQ     111.44  node=all,app=all,duration=3.0,key=uMAC_5533:app,thresh=run_warning
NAV_X           111.69  5408
NAV_Y           111.69  -1725
NODE_REPORT      39.22  NAME=abe,X=5327,Y=-1769,SPD=0,HDG=287,TYPE=kayak,COLOR=dodgerblue,MODE=PARK,ALLSTO

=======================================
Publications
=======================================
Variable            Time    Value
------------------  ------  -------------------------------------------------------
APPCAST             26.28   formatted report
PPROXONOI_ITER_GAP  111.43  1.011477
PPROXONOI_ITER_LEN  111.43  0.000436
PPROXONOI_STATUS    110.93  AppErrorFlag=false,Uptime=112.009,cpuload=0.1298,memory_kb=1768,memory_max
PROXONOI_PID        -0.42   63498
PROXONOI_POLY       111.43  active=false,label=vpoly_ben
PROXONOI_REGION     110.43  pts={-500,2300:-3500,-1000:-3500,-4600:3100,-4600:8400,2300},label=prox_o
\end{consoleverbx}
\normalsize

\vspace{0.1in}
\noindent
Furthermore, for certain apps, the number of variable subscriptions
can be huge, and the user may be solely interested in monitoring one
or more variable publications. The Subscriptions section can be
omitted entirely by attaching the \var{nosubs} keyword to the realmcast
request, resulting in the above output being further reduced
to:

\vspace{0.05in}
\begin{consoleverbx}
=======================================
pProxonoi                      ben (33)
=======================================
Subscriptions
=======================================
Variable        Time    Variable
--------------  ------  -------------------------------------------------------
APPCAST_REQ     111.44  node=all,app=all,duration=3.0,key=uMAC_5533:app,thresh=run_warning
NAV_X           111.69  5408
NAV_Y           111.69  -1725
NODE_REPORT      39.22  NAME=abe,X=5327,Y=-1769,SPD=0,HDG=287,TYPE=kayak,COLOR=dodgerblue,MODE=PARK,ALLSTO
PROX_CLEAR      never   -
PROX_POLY_VIEW  never   -
\end{consoleverbx}
\normalsize

%===================================================================
\subsection{Modifying the Content of Very Large String Publications}

Occasionally an app will publish very long string messages. In many
cases, just seeing the first part of the message is sufficient for a
user monitoring the system. As with the \mvar{NODE\_REPORT} posting in
the example above, the last part of the variable value is simply cut
off in the output presented to the user. Rather than cutting off the
line, it can be wrapped instead, by including the \var{wrap} tag
in the realmcast request. Wrapping is shown in the example below.

\vspace{0.05in}
\begin{consoleverbx}
=======================================
pProxonoi                      ben (33)
=======================================
Subscriptions
=======================================
Variable        Time    Value
--------------  ------  -------------------------------------------------------
APPCAST_REQ     111.44  node=all,app=all,duration=3.0,key=uMAC_5533:app,thresh=run_warning
NAV_X           111.69  5408
NAV_Y           111.69  -1725
NODE_REPORT      39.22  NAME=abe,X=5327,Y=-1769,SPD=0,HDG=287,TYPE=kayak,COLOR=dodgerblue,MODE=PARK,
                        ALLSTOP=ManualOverride,INDEX=81,TIME=3216098849.96,LENGTH=4
PROX_CLEAR      never   -
PROX_POLY_VIEW  never   -

=======================================
Publications
=======================================
Variable            Time    Value
------------------  ------  -------------------------------------------------------
APPCAST             26.28   formatted report
PPROXONOI_ITER_GAP  111.43  1.011477
PPROXONOI_ITER_LEN  111.43  0.000436
PPROXONOI_STATUS    110.93  AppErrorFlag=false,Uptime=112.009,cpuload=0.1298,memory_kb=1768,memory_max
                            _kb=1768,
PROXONOI_PID        -0.42   63498
PROXONOI_POLY       111.43  active=false,label=vpoly_ben
PROXONOI_REGION     110.43  pts={-500,2300:-3500,-1000:-3500,-4600:3100,-4600:8400,2300},label=prox_o
                            pregion
\end{consoleverbx}
\normalsize

\vspace{0.1in}
\noindent
By default, the wrapping is done in 90 character increments. This can
be changed with the \app{pRealm} configuration parameter,
\pvar{wrap\_length}.

\vspace{0.1in}
\noindent
Finally, in some cases wrapping may not be enough. If the string is
thousands of characters long, it will dominate the realmcast output
and make it hard to read anything else. The user has the option of
also truncating the variable string value, by default, to 270
characters. This can be modified with the \pvar{trunc\_length}
parameter. To make the most of each line of output, it is recommended
to set the \pvar{trunc\_length} to be a multiple of the
\pvar{wrap\_length}.

%===================================================================
\subsection{Modifying the Time Format to UTC}
\label{sec_prm_time}

Normally the posted time stamp is relative to the "start of the
mission". There is no consensus on then the start of the mission
occurs, although one could argue that it is the very instance the
MOOSDB starts. However, in multi-vehicle missions, each MOOSDB starts
at a slightly different time. In the case of \app{pRealm}, the start
time used for calculating timestamps is simply the UTC time when
\app{pRealm} started. This vagary is usually tolerated because we are
simply trying to get a feel for the rough time or age of a variable
post, and the nice small numbers help get a quick sense. However, at
times, more precision may be preferred. The user has the option of
requesting timestamps to be posted in absolute UTC time, i.e., the
number of seconds since January 1st, 1970. In this way, all postings
from all vehicles will be referencing the same start time, regardless
of when the MOOSDB or other processes began.

\vspace{0.1in}
\noindent
A client application simply needs to add the \var{utc} component to the
end of a realmcast request as such:

\vspace{0.1in}
\begin{consoleverb}
 REALMCAST_REQ = client=pmv,duration=5,utc,proc=pProxonoi
\end{consoleverb}
\vspace{0.1in}



%===================================================================
\subsection{How Does the User Actually Modify Output?}

As described above, modification to the realmcast report content is
achieved by adding tags to the incoming \mvar{REALMCAST\_REQ}
messages. For example, the Source and Community columns are removed
when the request contains the \var{nosrc} and \var{nocom} tags:

\vspace{0.1in}
\begin{consoleverb}
 REALMCAST_REQ = client=pmv,duration=5,nosrc,nocomm,proc=pProxonoi
\end{consoleverb}
\vspace{0.1in}

\noindent
And virgin variables and string content can be wrapped with the
\var{mask} and \var{wrap} tags:

\vspace{0.1in}
\begin{consoleverb}
 REALMCAST_REQ = client=pmv,duration=5,mask,wrap,proc=pProxonoi
\end{consoleverb}
\vspace{0.1in}

\noindent
In general the user does not need to be involved in formatting string
messages with these tags. The \app{pMarineViewer} app is a client that
interacts with the user and contains toggle buttons for the above
content modifiers. Figure \ref{fig_prealm_pmv} shows the lefthand
bottom corner of the \app{pMarineViewer} window when realmcast output
is being viewed. (Also see Figure \ref{fig_prealm_pmv_rcast}.) Each
button is a toggle button.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.35\textwidth]{figures/pmv_content_buttons.png}
  \caption{{\bf Content Modifier Buttons:} The \app{pMarineViewer} app
    acts as a client requesting and receiving realmcast reports. The
    modifier buttons will toggle the seven modifiers affecting
    realmast formatting.}
\label{fig_prealm_pmv}
\end{figure}

\vspace{0.1in}
\noindent
When \app{pMarineViewer} is in the mode to present realmcast content, it will
generate a steady stream of \mvar{REALMCAST\_REQ} messages. As the above
seven content buttons are toggled, the next outgoing request message will be
modified with the proper content tags.


%===================================================================
\section{WatchCasting: A Special Type of RealmCast}
\label{sec_prm_wcast}
%===================================================================

In addition to the outgoing \mvar{REALMCAST} message, \app{pRealm}
supports a second type of message called a watchcast, posted in the
variable \mvar{WATCHCAST}. This message contains the information about
the most recent post to {\em one} MOOS variable. Watchcasts are generated
when the most recent realmcast request names a set of MOOS variables.
Here is a normal realmcast request discussed above, requesting the
pub/sub information for \app{pHelmIvP}:

\vspace{0.1in}
\begin{consoleverb}
 REALMCAST_REQ = client=pmv,duration=5,proc=pHelmIvP
\end{consoleverb}
\vspace{0.1in}

\noindent
And here is a realmcast request that specifies a particular set of MOOS variables:

\vspace{0.1in}
\begin{consoleverb}
 REALMCAST_REQ = client=pmv,duration=5,vars=DEPLOY:RETURN:STATION_KEEP
\end{consoleverb}
\vspace{0.1in}

\noindent
When \app{pRealm} has been asked to produce this kind of content, it produces
it in a watchcast message, one per variable. The idea is shown in Figure
\ref{fig_prealm_watchcast}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figures/prealm_watchcast.png}
  \caption{{\bf WatchCast Request:} A request is generated by a client, 
    specifying a set of variables, and a duration. For the
    next period in time specified by the duration, \app{pRealm} will
    produce a watchcast report for each variable, each time the variable
    changes, but no more frequent than a fixed interval.}
\label{fig_prealm_watchcast}
\end{figure}

\vspace{0.1in}
\noindent
Watchcasting allows the client to configure a cluster of variables
that may be important to the user. These variables may be involved in
several different MOOS applications and thus hard to visualize and
monitor. Clients of \app{pRealm} like \app{pMarineViewer} and
\app{uMACView} are able to specify watch clusters and view a single
report similar to:

\vspace{0.1in}
\begin{consoleverb}
Node    DEPLOY     RETURN    STATION_KEEP
----    ------     ------    ------------
abe     true       false     false 
ben     true       false     false 
cal     true       false     false 
deb     true       false     false 
eve     true       false     false 
fin     true       false     false 
gus     true       false     false 
hal     true       false     false 
\end{consoleverb}
\vspace{0.1in}

\noindent
These may be the key variables in the autonomy of a particular mission,
or they could be health montitoring variables for deployed platforms:

\vspace{0.1in}
\begin{consoleverb}
Node    BATT_VOLTAGE     CPU_TEMP    GPS_SATELLITES
----    ------------     --------    --------------
abe     17.2             111.2       11
ben     16.9             112.0       8
cal     17.4             111.9       9
deb     17.4             108.7       10
eve     17.0             101.2       11
fin     15.8             105.5       11
gus     16.4             114.2       9
hal     16.1             105.6       10
\end{consoleverb}
\vspace{0.1in}

\noindent
Since multiple \app{pRealm} clients may be run simultaneously, e.g.,
\app{pMarineViewer} and one or more instances of \app{uMACView}, then
the user could have several such tables viewable. In multi-robot
vehicle deployments, this may be extremely useful. Unlike appcast
content, the above content is customizable by the user without any
adjustments to code. Watch clusters are configured in
\app{pMarineViewer} or \app{uMACView} configuration files. See the
documentation for these app for more information, \cite{url_pmv},
\cite{url_umacview}.


%===================================================================
\section{How pRealm Informs Potential Clients}
\label{sec_prm_summary_posts}
%===================================================================

We have established how clients of \app{pRealm} may request reports on
a given channel, Figure \ref{fig_prealmreq_one}. But how does a client
like \app{pMarineViewer} know there exists a \app{pRealm} to query,
and which channels may be queried? To accomplish this, \app{pRealm}
publishes its key information periodically for clients to discover.
At a rate of once per five seconds, \app{pRealm} publishes to the MOOS
variable \mvar{REALMCAST\_CHANNELS} a report that identifies the name
of the node/vehicle, and all available channels for querying. This
idea is conveyed below.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/realmcast_channels.png}
  \caption{{\bf RealmCast Channels:} The \app{pRealm} app periodically posts
    information about itself. This information is used later by clients to
    request realmcast reports from specific nodes and specific channels.}
\label{fig_prm_channels}
\end{figure}

\vspace{0.1in}
\noindent
By default, these messages are posted once every 5 seconds. This value
can be changed with the \pvar{summary\_interval} parameter. There are
two exceptions to this interval. For the first minute after launch,
the summary will be posted every half second. The second exception is
applied when a new app has been detected. The set of apps
participating in the local MOOS community normally doesn't change
after the initial startup. But if a new app is later detected by
\app{pRealm}, the \mvar{REALMCAST\_CHANNELS} variable will be
published immediately with this new information.

\vspace{0.1in}
\noindent
A final note: the time interval between summaries is real time, not time warp time.


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

The \app{pRealm} application produces some useful information to the
terminal on every iteration of the application. An example is shown in
Listing \ref{lst_prm_appcast} below. This application is also appcast
enabled, meaning its reports are published to the MOOSDB and viewable
from any uMAC application or \app{pMarineViewer}. The counter on the
end of line 2 is incremented on each iteration of \app{pRealm}, and
serves a bit as a heartbeat indicator. The \var{"0/0"} also on line 2
indicates there are no configuration or run warnings detected.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{pRealm}}
\label{lst_prm_appcast}

%\begin{consoleverbx}
\footnotesize
\begin{verbatim}
 1  ===================================================================
 2  pRealm gilda                                              0/0(3074)
 3  ===================================================================
 4  Configuration: 
 5  --------------------------------------------
 6    RelCast Interval: 0.55
 7    Summary Interval: 7.60
 8    Wrap Length:  90
 9    Trunc Length: 270
10    Max Msg Hist: 10
11  
12  MOOS Community State: 
13  --------------------------------------------
14    MOOSDB Name: MOOSDB_gilda
15     Known Apps: 15
16     Known Apps: MOOSDB_gilda,iSay,pContactMgrV20,pHelmIvP,
17                 pHostInfo,pLogger,pMarinePID,pNodeReporter,
18                 pRealm,pShare,uFldNodeBroker,uLoadWatch,
19                 uMemWatch,uProcessWatch,uSimMarine
20    Total SVars: 196
21    Total PVars: 137
22    Unique Vars: 206
23    UTC Time:    12874301098.43
24    Local Time:  1605.84
25    Summaries:   40
26  
27  Recent RealmCasts or WatchCasts:
28  --------------------------------------------
29    Total RealmCasts: 238
30    Total WatchCasts: 6
31  --------------------------------------------
32  Count     Time  Client  Content
33  -----  -------  ------  -------------------------------------------
34  (165)  1604.28  pmv     pHelmIvP
35  (47)    829.04  pmv     iSay
36  (1)     424.30  pmv     vars=DEPLOY
37  (1)     137.69  pmv     vars=AVOID,DEPLOY,LOITER,RETURN,STATION_KEE
38  (26)    132.98  pmv     iSay
39 
40  Currently Active Clients:
41  --------------------------------------------
42  Client  Active  Content
43  ------  ------  --------
44  pmv     21.37   pHelmIvP
45  
46  ===================================================================
47  Most Recent Events (8):
48  ===================================================================
49  [831.62]: Client pmv, new pipe: pHelmIvP
50  [533.97]: Client pmv, new pipe: iSay
51  [386.22]: Client pmv, new pipe: vars=DEPLOY
52  [336.66]: Client pmv, new pipe: vars=AVOID
  
\end{verbatim}
%\end{consoleverbx}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
Lines 6-10 of the output show the current values of the five
\app{pRealm} configuration parameters listed in Section
\ref{sec_prm_params}.

\vspace{0.1in}
\noindent
Lines 12-22 relate state of the MOOSDB, including the name of the
MOOSDB which is always the community name at the end of the
\var{MOOSDB\_} prefix. The number of and list of know apps connected
to the MOOSDB are shown in lines 15 and 16. Line 20 shows the number
of MOOS variables involved in a subscription by at least one app. Line
21 shows the number of unique MOOS variable publications. Line 22
shows the number of unique variables known to the MOOSDB involved in
either a subscription or publication. Line 33 shows the current UTC
time, with the time warp multiplier applied. Line 24 shows the local
time, i.e., the time since \app{pRealm} was started. Line 25 shows
the total number of realmcast summaries posted, to the variable
\mvar{REALMCAST\_CHANNELS}.

\vspace{0.1in}
\noindent
Lines 27-38 indicate the most recent realmcasts or watchcasts. First
the total of each is shown on lines 29 and 30. Lines 34-38 show the
five most recent content settings. The first column, Count, shows the
number of successive outgoing messages. The Time column shows the
local time of the most recent message in that group. The Client column
shows which app is requesting the content. This will show as
\var{"pmv"} when \app{pMarineViewer} is the client. Finally, the
Client column indicates the content of the outgoing message. When the
content begins with \var{"vars="}, this indicates that it is a
watchcast.

\vspace{0.1in}
\noindent
Lines 40-44 show the status of active clients. A client is active if
\app{pRealm} has recently received a realmcast request. As discussed
earlier, each request has a duration. The duration implies a time
remaining before the request expires. This time is shown in column
two. Column three shows the content being requested in the realmcast
request.

\vspace{0.1in}
\noindent
Lines 46-56 contain the typical recent events block for all appcasting
apps. In the case of \app{pRealm}, an event is posted each time a
realmcast request has been received that contains a change in
requested content.


%===================================================================
\section{A Preview of Using pRealm Information within pMarineViewer}

In most cases the user won't give another thought about \app{pRealm} beyond
simply including it in the \app{pAntler} launch lists. The user experience
is through \app{pMarineViewer}. Initially this is the only app that is able
to handle realmcasts and present them to a user. So here is a quick preview
of the \app{pMarineViewer} experience.

\vspace{0.1in}
\noindent
Normally when the a mission is launched with the \app{pMarineViewer}
the window shows the three "infocast" panes shown on the left. The
infocast panes are either showing appcast content, or realmcast
content. The infocast panes show appcast content by default. Unless
the user changes the default color schemes, appcasting is
distinguished by an indigo background as in Figure
\ref{fig_prealm_pmv_acast}. 

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/pmv_appcasting.png}
  \caption{{\bf The pMarineViewer AppCasting Mode:} When
    \app{pMarineViewer} starts, normally it is in appcasting mode, with
    the left three appcasting panes rendered in indigo showing appcast
    content in the lower pane.}
\label{fig_prealm_pmv_acast}
\end{figure}

\noindent
The appcasting panes let the user select the node in the upper left
pane, e.g., the shoreside or one of several vehicles. The upper right
pane lets the user select the MOOS app running on the selected
node. The bottom pane shows the appcast content for the node and app
selected in the top two panes.

\vspace{0.1in}
\noindent
The realmcast mode is very similar. To toggle between modes, the
\var{'a'} key is used. Unless the user changes the default color
schemes, the realmcasting is distinguished by a beige background as in
Figure \ref{fig_prealm_pmv_rcast}. As in the appcasting mode, the top
two panes offer virtually the same options based on nodes and processes.
The bottom middle pane switches however to show realmcast content.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.97\textwidth]{figures/pmv_relcast_buttons_both.png}
  \caption{{\bf The pMarineViewer RealmCasting Mode:} The
    \app{pMarineViewer} user may toggle into realmcasting mode using
    the \var{'a'} key, with the left three panes rendered in beige.}
\label{fig_prealm_pmv_rcast}
\end{figure}

\vspace{0.1in}
\noindent
When in realmcast mode, \app{pMarineViewer} will display the seven buttons
shown above. These buttons allow the user to modify the content modes
discussed in Section \ref{sec_prm_format}.


%===================================================================
\section{Additional Notes}

Some additions planned for the future:

\begin{packed_itemize}
\item General masking: Currently masking is only done on virgin variables. The
  plan is to also allow the user to mask out entire apps, or a list of variables
  for an app, or list of variables across all apps.
\item Configurable channels: Currently the only channels are connected apps, plus
  an artficial channel for the MOOSDB. Like \app{uXMS}, the plan is to allow the
  user to define their own channel with a custom list of variables to watch.
  
\item Global channel: Currently there is no channel that simply lists all variables.

\item Messaging channel: A channel specifically for monitoring inter-vehicle messaging.

\end{packed_itemize}


\bibliographystyle{plain}
\footnotesize
\bibliography{biblio.bib}

\end{document}

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