<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{uFldScope: Gathering a Multi-Vehicle Status Summary}
\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.UFldScope}
\wikidoc{bugz=uFldScope}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_scope}
\index{uFldScope}

The \app{uFldScope} application is a tool for collecting diverse sets
of information regarding a field of vehicles remotely deployed.
Suppose, for example, one is interested in monitoring, for each
deployed vehicle, the (a) helm mode, (b) total distance travelled, (c)
battery level, and (d) the number of times it has visited a certain
beacon. Each piece of information may be embedded in one of a number
of MOOS variables, perhaps along with a lot of other information of no
concern.  For example, a typical \mvar{NODE\_REPORT} posting contains
the helm mode, but the full string may look like:

\prevgreen
\begin{verbatim}
NODE_REPORT= "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,DEPTH=4.63,LENGTH=3.8,MODE=LOITERING"
\end{verbatim}
\postverb

\noindent
While there are several methods to scope on the above variable and
pick out the helm mode, the goal of the \app{uFldScope} tool is to
have this information readily visible for each vehicle perhaps
alongside other key fields for all vehicles, in a continuously updated
simple table like the following:

\vspace{0.1in}
\footnotesize
\begin{verbatim}
   VName       MODE    TripDist  Speed  STREAMING(2)
   =====    =======    ========  =====  (15)
   alpha    LOITERING      66.8   1.96 
   bravo         PARK       0.0   0.00
   charlie  RETURNING    1466.3   1.05 
\end{verbatim}
\normalsize
\vspace{0.1in}

The assumption is that \app{uFldScope} is running on a topside computer,
interacting with a user, and receiving information on deployed
vehicles primarily through node reports or other summary report
variables. The typical layout is shown in Figure
\ref{fig_ufs_topology}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/ufs_topology.png}
  \caption{{\bf Typical uFldScope Topology:} A shoreside or topside
    community is receiving information from several deployed vehicles.
    Key information is embedded in one of several possible MOOS report
    variables. The uFldScope tool runs in the topside community to
    parse key information from the variables and display them in a
    table format configured by the user.}
\label{fig_ufs_topology}
\end{figure}
\vspace{0.1in}

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

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

\vspace{0.15in}
\begin{listing}{Configuration parameters for \app{uFldScope}}
\label{lst_ufs_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.72\textwidth}} 

  \pvar{scope:} &amp; Description info include in main report along with
  source info. \\ 

  \pvar{layout:} &amp; An alternative table layout showing only selected
  fields in each report. \\

\end{longtable}
\end{listing}

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

To see an example MOOS configuration block, enter the following from
the command-line:

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

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

\vspace{0.25in}
\begin{listing}{Example configuration of the \app{uFldScope} application}
\label{ufs_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  uFldScope Example MOOS Configuration                      
  3  =============================================================== 
  4 
  5  ProcessConfig = uFldScope   
  6  {                                     
  7    AppTick   = 4                              
  8    CommsTick = 4                                            
  9                                                             
 10    scope = var=NODE_REPORT,key=vname,fld=TIME,alias=Time               
 11    scope = var=NODE_REPORT,key=vname,fld=MODE                    
 12    scope = var=SPEED_REPORT,key=vname,fld=avg_speed,alias=speed  
 13    scope = var=ODOMETRY_REPORT,key=vname,fld=trip_dist           
 14    scope = var=ODOMETRY_REPORT,key=vname,fld=total_dist          
 15   
 16    layout = trip_dist, total_dist                      
 17    layout = MODE, speed, Time        
 18  }                                                               
\end{verbatim}
\end{listing}
\normalsize
 

%=================================================================
\section{Publications and Subscriptions for uFldScope}
\index{uFldScope!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldScope}
\label{sec_pcm_interface}

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

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

%=================================================================
\subsection{Variables Published by uFldScope}
\label{sec_ufs_pubs}

The primary output of \app{uFldScope} to the MOOSDB is the report
output to the terminal or appast. The only publication to the MOOSDB
is the \mvar{APPCAST} publication.

%=================================================================
\subsection{MOOS Variables Subscribed for by uFldScope}
\label{sec_ufs_subs}

The \app{uFldScope} 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.
\end{packed_itemize}

\noindent
The \app{uFldScope} application will also subscribe for the MOOS
variables prescribed in the \pvar{scope} configuration parameter(s).

%=================================================================
\subsection*{Command Line Usage of uFldScope}
\label{sec_ufs_cmdline}
\index{Command Line Usage!uFldScope}
\index{uFldScope!Command Line Usage}

Although the \app{uFldScope} application may be launched with
\app{pAntler}, it is typically launched separately from the command
line:

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

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

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

The \app{uFldScope} utility may be configured to choose (a) which MOOS
variables are scoped, (b) which fields in those messages are scoped,
and (c) how that data is presented to the user. In all usage scenarios
it is presumed that the messages are strings comprised of
comma-separated variable=value pairs. For example:

\prevgreen
\begin{verbatim}
NODE_REPORT= "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,DEPTH=4.63,LENGTH=3.8,MODE=LOITERING"
\end{verbatim}
\postverb

\noindent
For each variable specified by the user for scoping, a {\em key} needs
to also be specified identifying the vehicle name. In the above case,
the key is the string \var{"NAME"}.

%=================================================================
\subsection{Configuring Scope Elements} 

A {\em scope element} corresponds to particular MOOS message and a particular
field in that MOOS message. It also corresponds to a column in the tabular
report presented to the user. For example, the second column in the table
below, with the header \var{"MODE"}, corresponds to a scope element deriving
its information from postings to \mvar{NODE\_REPORT}, in the field \var{"MODE"}.

\footnotesize
\begin{verbatim}
   VName         MODE    TripDist  Speed  STREAMING(2)
   =====      =======    ========  =====  (15)
   alpha    LOITERING        66.8   1.96 
   bravo         PARK         0.0   0.00
   charlie  RETURNING      1466.3   1.05 
\end{verbatim}
\normalsize

\noindent
A scope element is configure in the mission configuration file with entries
of the form:

\prevblue
\begin{verbatim}
  scope = var=&lt;MOOSVar&gt;, key=&lt;KEYNAME&gt;, fld=&lt;FIELDNAME&gt;, alias=&lt;ALIAS&gt;
\end{verbatim}
\postverb

\noindent
The \var{&lt;MOOSVAR&gt;} specifies the name of the MOOS variable. Multiple
scope elements may use the same MOOS variable. The \var{&lt;KEYNAME&gt;}
specifies the field in the message used to designate the name of the
vehicle. There should be only one right answer for this, and if it is
wrongly specified, the column for that scope element will simply be
empty. The \var{&lt;FIELDNAME&gt;} specifies the other field in the message
holding the information of interest. For example, line 10 in Listing
\ref{ufs_econfig} is the scope configuration resulting in the second 
column of the above tabular output. The \var{&lt;ALIAS&gt;} is a string to 
use in the column output header if the user doesn't want to just use
the name of scoped field.

%=================================================================
\subsection{Configuring Scope Layouts}

By default the tabular output produced by \app{uFldScope} contains
a column for each scope element. If the number of scope elements is large
the user may be interested, at times, in rendering only a subset of the
scope elements. The user may define these subsets using the \var{LAYOUT}
configuration parameter, of the form:

\footnotesize
\begin{verbatim}
  LAYOUT = &lt;FLDNAME&gt;, &lt;FLDNAME&gt;, ..., &lt;FLDNAME&gt;
\end{verbatim}
\normalsize

\noindent
The \var{&lt;FLDNAME&gt;} specifies the name of the field in a given scope
element. Note that it is {\em possible} that the field names may be the 
same for two different scope elements. For this reason the field name 
used in the layout definition is the field name alias. This gives the 
user the chance to distinguish two otherwise identical field names. If 
the user does not specify an alias in configuration of scope element, 
the alias is by default the same as the field name. 

\pskip

For the \app{uFldScope} configuration shown in Listing \ref{ufs_econfig}, 
the following five scope elements are rendered to the user as 
follows.

\footnotesize
\begin{verbatim}
  VName           Time                   MODE  speed  trip_dist  total_dist  PAUSED(A)
  =====  =============  =====================  =====  =========  ==========  (1800)
  gilda  2651922526.73  MODE@ACTIVE:LOITERING   1.06      517.1       517.1  
  henry  2651922526.54  MODE@ACTIVE:LOITERING   1.17      526.4       526.4  
    ike  2651922526.45  MODE@ACTIVE:LOITERING   1.07      520.1       520.1  
  james  2651922526.65  MODE@ACTIVE:LOITERING   1.16      515.1       515.1  
\end{verbatim}
\normalsize

\noindent
Note the \var{"(A)"} at the end of the first line. This indicates that
all scope elements are being presented. If the user hits the \var{'l'}
or \var{'L'} keys the presentation will be toggled through the various
layouts configured by the user. In this example case, the following
two layouts may be selected:

\footnotesize
\begin{verbatim}
  VName           Time                   MODE  speed  PAUSED(1)
  =====  =============  =====================  =====  (1802)
  gilda   2651923071.3  MODE@ACTIVE:LOITERING   1.17  
  henry  2651923071.11  MODE@ACTIVE:LOITERING   1.17  
    ike  2651923071.03  MODE@ACTIVE:LOITERING   1.18  
  james  2651923071.24  MODE@ACTIVE:LOITERING   1.17  
\end{verbatim}
\normalsize

\noindent
Note that only the {\em Time}, {\em MODE}, and {\em speed} scope
elements are produced, corresponding to the layout configured on Line
16 in Listing \ref{ufs_econfig}. Also note that the \var{"(A)"} on the
first line switched to \var{"(1)"} to indicate that the first
user-configured layout is being used. By hitting \var{'L'} once more,
the second user-configured layout will be instead shown:

\footnotesize
\begin{verbatim}
  VName  trip_dist  total_dist  PAUSED(2)
  =====  =========  ==========  (1801)
  gilda     1081.9      1081.9  
  henry     1072.1      1072.1  
    ike     1117.7      1117.7  
  james     1067.0      1067.0  
\end{verbatim}
\normalsize

\noindent
Note that the \var{"(1)"} on the first line switched to \var{"(2)"} to
indicate that the second user-configured layout is being used. By
hitting \var{'L'} once more, the full table will again be rendered.

%=================================================================
\subsection{Further Control of the Terminal Output}

If multiple layouts have been configured, the user may either toggle
through the list of layouts with the \var{'l'} or \var{'L'} key as
mentioned above, or toggle between the last-used user-configured
layout and the mode of rendering all scope elements, by using the
\var{'a'} or \var{'A'} key.

\pskip

By default the output produced to the terminal is refreshed on each
iteration of the \app{uFldScope} application. This may be useful for
watching a trend as time passes. The user may also wish to pause the
output to take a careful look at the data. This may be done by hitting
the \var{'p'} or \var{'P'} keys, or simply the spacebar. Subsequent
similar keystrokes will keep the refresh mode in the paused mode, but
the output will be refreshed to their current values before again
pausing. Returning to the streaming mode may be done by hitting the
\var{'r'} or \var{'R'} keys. At any time the user may also hit the
\var{'h'} or \var{'H'} keys for a help menu.


\end{document}

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