<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{uXMS: Scoping the MOOSDB from the Console}
\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}
\labsrc{project-pavlab/appdocs/app\_uxms} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UXMS}
\wikidoc{bugz=uXMS}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
\section{Overview}
%===================================================================
\label{sec_util_uxms}
%\index{uXMS}

\app{uXMS} is a terminal based MOOS app for scoping the MOOSDB. It has
no graphics library build dependencies and is easily launched from the
command line to scope on just what the user wants, from everything to
just one important variable.  For example, typing the following on the
command line after say the alpha example mission is launched, will
result in Figure \ref{fig_uxms_simple}.

\vspace{0.1in}
\begin{consoleverb}
 $ uXMS alpha.moos NAV_X NAV_Y DEPLOY RETURN IVPHELM_STATE
\end{consoleverb}
\vspace{0.15in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/uxms_simple_bdr.png}
  \caption{{\bf A simple scope on five variables with uXMS:} A line is
    used for each variable showing the variable name, the time of the
    most recent posting, the source, and the current value.}
\label{fig_uxms_simple}
\end{figure}


\vspace{0.1in}
\noindent
Scoping on the MOOSDB is a very important tool in the process of
development and debugging. The \app{uXMS} tool has a substantial set
of configuration choices for making this job easier by bringing just
the right data to the user's attention. The default usage, as shown
above, is fairly simple, but there are other options discussed in this
section that are worth exploiting by the more experienced user.

\begin{packed_itemize}
\item {\em Use with appcasting:} \app{uXMS} is appcast enabled meaning its
  terminal reports may be viewed with tools other than the terminal
  window. It is possible to configure multilple \app{uXMS} scopes to
  automatically launch with a mission and viewer each of them in
  remote appcast viewing tools.  More on this topic in Section
  \ref{sec_uxms_appcast}.

\item {\em Scoping on history:} \app{uXMS} may be configured to scope on the
  history of a variable to view not just its current state but recent
  values.

\item {\em Remote low-bandwidth scoping:} \app{uXMS} can be launched and
  connected to a remote MOOSDB over a low-bandwidth link, with refresh
  requests made only on the user's request. \app{uXMS} can also be on a
  remote vehicle via an ssh session.

\item {\em Dynamic changes to the scope list:} The set of scoped variables
  may be altered dynamically by selecting MOOS apps to include or 
  exclude from the scope list.
\end{packed_itemize}

\noindent
At any time the user may hit the \var{'h'} key to see a list of help
commands.

%===================================================================
\section{The uXMS Refresh Modes}
%===================================================================
\label{sec_uxms_refresh_mode}

Reports such as the one shown in Figure \ref{fig_uxms_simple} are
generated either automatically or specifically when the user asks for
it. The latter is important in situations where bandwidth is low. This
feature was the original motivation for developing \app{uXMS}. When a
new report is sent to the terminal is determined by the {\em refresh mode}.
The three refresh modes are shown in Figure \ref{uxms_modes} along with 
the key strokes for switching between modes.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.48\textwidth]{figures/uxms_refresh_modes.png}
  \caption{{\bf Refresh Modes:} The \vvar{uXMS} refresh mode
    determines when a new report is written to the screen. The user
    may switch between modes with the shown keystrokes.}
\label{uxms_modes}
\end{figure}

\vspace{0.1in}
\noindent
The refresh mode may be changed by the user as \app{uXMS} is running,
or it may be given an initial mode value on startup from the command
line with \var{--mode=paused}, \var{--mode=streaming}, or
\var{--mode=events}. The latter is the default. It may also be set in
the \app{uXMS} configuration block in the mission file with the
\pvar{refresh\_mode} parameter. The current refresh mode is shown in
parentheses in the report header as shown in Figure
\ref{fig_uxms_simple} where it is in the {\em events} refresh mode.

%===================================================================
\subsection{The Streaming Refresh Mode}

In the {\em streaming} refresh mode, a new report is generated and
written to stdout on every iteration of the \app{uXMS}
application. The frequency is limited from above by the apptick
setting in the MOOS configuration block.  It is also limited from
above by the parameter \pvar{term\_report\_interval}, which is by
default $0.6$ seconds. Each report written to the terminal will show
an incremented counter at the end of the first line, in parentheses.
This counter represents the \app{uXMS} iteration counter.  This mode
may be entered by hitting the \var{'r'} key, or chosen as the initial
refresh mode at startup from the command line with the
\var{--mode=streaming} option.

%===================================================================
\subsection{The Events Refresh Mode}

In the {\em events} refresh mode, the default refresh mode, a new
report is generated only when new mail is received for one of the
scoped variables. Note this does not necessarily mean that the value
of the variable has changed, only that it has been written to again by
some process. As with the {\em streaming} mode, the report frequency
is limited by the apptick and the \pvar{term\_report\_interval}
setting.  This mode is useful in low-bandwidth situations where a user
cannot afford the streaming refresh mode, but may be monitoring
changes to one or two variables. This mode may be entered by hitting
the \var{'e'} key, or chosen as the initial refresh mode at startup
from the command line with the \var{--mode=events} option.

%===================================================================
\subsubsection{The Paused  Refresh Mode}

In the {\em paused} refresh mode, the report will not be updated until
the user specifically requests a new update by hitting the spacebar
key. This mode is the preferred mode in low bandwidth situations, and
simply as a way of stabilzing the rapid refreshing output of the other
modes so one can actually read the output. This mode is entered by the
spacebar key and subsequent hits refresh the output once. To launch
\app{uXMS} in the paused mode, use the \var{--mode=paused} command
line switch.

%===================================================================
\section{The uXMS Content Modes}
%===================================================================
\label{uxms_content_mode}

The contents of the \app{uXMS} report vary between one of a few modes.
In the {\em scoping} mode, a snapshot of a subset of MOOS variables is
generated, similar to what is shown in Figure
\ref{fig_uxms_simple}. In the {\em history} mode the recent history of
changes to a single MOOS variable is reported.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.54\textwidth]{figures/uxms_content_modes.png}
  \caption{{\bf Content Modes:} The \vvar{uXMS} content mode
    determines what data is included in each new report. The two major
    modes are the {\em scoping} and {\em history} modes. In the
    former, snapshots of one or more MOOS variables are reported. In
    the latter, the recent history of a single variable is reported.}
\label{uxms_content_modes}
\end{figure}

%===================================================================
\subsection{The Scoping Content Mode}
\label{sec_scoping_mode}

The {\em scoping} mode has two sub-modes as shown in Figure
\ref{uxms_content_modes}. In the first sub-mode, the {\em SelectVars}
sub-mode, the only variables shown are the ones the user
requested. They are requested on the command-line upon start-up
(Section \ref{sec_uxms_cmdline}), or in the \app{uXMS} configuration
block in the \var{.moos} file provided on startup, or both. One may
also select variables for viewing by specifying one or MOOS processes
with the command line option \var{--src=&lt;process&gt;,&lt;process&gt;,...}. All
variables from these processes will then be included in the scope
list.

\pskip

In the {\em AllVars} sub-mode, all MOOS variables in the MOOSDB
are displayed, unless explicitly filtered out. The most common way
of filtering out variables in the {\em AllVars} sub-mode is to 
provide a filter string interactively by typing the \var{'/'} key
and entering a filter. Only lines that contain this string as a
substring in the variable name will then be shown. The filter may
also be provided on startup with the \var{--filter=pattern} command
line option.

\pskip

In both sub-modes, variables that would otherwise be included in the
report may be masked out with two further options. Variables that have
never been written to by any MOOS process are referred to as virgin
variables, and by default are shown with the string \var{"n/a"} in
their value column. These may be shut off from the command line with
\var{--mask=virgin}, or in the MOOS configuration block by including
the line \pvar{display\_virgins}\psvar{=false}. Similarly, variables
with an empty string value may be masked out from the command line
with \var{--mask=empty}, or with the line
\pvar{display\_empty\_strings}\psvar{=false} in the MOOS configuration
block of the \var{.moos} file.


%===================================================================
\subsection{The History Content Mode}
\label{sec_uxms_history_mode}

\noindent
In the {\em history} content mode, the recent values for a single MOOS
variable are reported. Contrast this with the {\em scoping} mode where
a snapshot of a variable value is displayed, and that value may have
changed several times between successive reports.  The output
generated in this mode may look like that in Figure
\ref{fig_uxms_history} which shows the desired heading of a vehicle
going into the first turn of the alpha mission. This \app{uXMS}
session can by launched from the command line with:

\vspace{0.1in}
\begin{consoleverb}
 $ uXMS alpha.moos --history=DESIRED_HEADING
\end{consoleverb}
\vspace{0.1in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/uxms_history_bdr.png}
  \caption{{\bf A uXMS scope on a single variable history:} A
    vehicle's desired heading is monitored as it goes into the first
    turn of the alpha mission. Values in parentheses indicate the
    number of successive postings without a change of value.}
\label{fig_uxms_history}
\end{figure}

\vspace{0.15in}

The output structure in the {\em history} mode is the same as in the
{\em scoping} mode in terms of what data is in the columns and header
lines. Each line however is dedicated to the same variable and shows
the progression of values through time. To save screen real estate,
successive mail received for with identical source and value will
consolidated on one line, and the number in parentheses is merely
incremented for each such identical mail. For example, the last line
shown in Figure \ref{fig_uxms_history}, the value of
\mvar{DESIRED\_HEADING} has remained the same for 57 consecutives
posts to the MOOSDB.  %\index[vars]{\mvar{DESIRED\_HEADING}}

\pskip

\noindent
The output in the {\em history} mode may be adjusted in a few ways:

\begin{packed_itemize}
\item {\em Modifying the number of history lines:} The number of lines
  of history may be increased or descreased by hitting the \var{'&gt;'}
  or \var{'&lt;'} keys respectively. A maximum of 100 and minimum of 5
  lines is allowed. The default is 40.
\item {\em Setting the history variable:} The history variable may be
  set on the command line with \var{--history=VAR}, or set in the the
  mission file with \pvar{history\_var}\psvar{=&lt;MOOSVar&gt;}. If set in
  both, the command line setting takes precedent.
\item {\em Hiding the history variable:} To increase the available
  real estate on each line, the variable name column may be supressed
  or restored by toggling the \var{'j'} key. The history variable is 
  shown by default but may be configured to be off upon startup by 
  setting \pvar{display\_history\_var}\psvar{=false} in the mission file.
\end{packed_itemize}

\noindent
Presently there is no way to dynamically change the history variable,
or scope on more than one variable's history. (But you can open more
than one \app{uXMS} session to scope on more than one variable's 
history.)

%===================================================================
\subsection{The Processes Content Mode}
\label{sec_uxms_processes_mode}

\noindent
In the {\em processes} content mode running processes may be monitored
and selected for either including or excluding variables from the
selected processes. This mode may be toggled with the \var{'p'}
key. For example, launching the alpha mission and then \app{uXMS} from
the command line:

\vspace{0.1in}
\begin{consoleverb}
 $ uXMS alpha.moos DESIRED_HEADING
\end{consoleverb}
\vspace{0.1in}

\noindent
After \app{uXMS} is launched, toggle into the procesess content mode with 
the \var{'p'}. This should present something similar to Figure 
\ref{fig_uxms_processes_a}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/uxms_processes_a_bdr.png}
  \caption{{\bf A uXMS processes content mode:} All processes known to
    the scope (via the \vvar{DB\_CLIENTS} variable) are shown. The
    Mail column shows the time since mail has been received from the
    client.  The Client column shows the time since the client has
    shown up on the \vvar{DB\_CLIENTS} list.}
\label{fig_uxms_processes_a}
\end{figure}

\vspace{0.15in}

\noindent
The first two columns show the processes known to \app{uXMS} and a
process ID randomly assigned to each process. These IDs may be used
select a process as explaine shortly. The last two columns show the
time since mail was last received and the time since the process last
appeared on the \mvar{DB\_CLIENTS} list. Try killing one of the
processes and see what happens.

\pskip
By default \app{uXMS} tries to make use of information produced by
\app{uProcessWatch}. The first line in the body of the report in
Figure \ref{fig_uxms_processes_a} shows the contents of the
\mvar{PROC\_WATCH\_SUMMARY} variable. In this example, mail has only
been received from \app{pHelmIvP} and \app{uProcessWatch}. The former
because \app{uXMS} was launched from the command line scoping on
\mvar{DESIRED\_HEADING}, and the latter because \app{uXMS} is
automatically configured to received the \mvar{PROC\_WATCH\_SUMMARY}
mail from \app{uProcessWatch}. If \app{uProcessWatch} is not running
the report will simply state so.

\pskip

Perhaps the most useful feature of the {\em processes} content mode is
the ability to select a process to either include or exclude variables
published by that process on the watch list. To {\em include}
variables from a process, type the \var{'+'} key, and a menu and
prompt like that shown in Figure \ref{fig_uxms_processes_b}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.63\textwidth]{figures/uxms_processes_b_bdr.png}
  \caption{{\bf Adding watch-list variables based process inclusion:}
    All processes known to the scope (via the \vvar{DB\_CLIENTS}
    variable) are shown. Each process has a single-character ID which
    may be entered at the prompt to select the process for inclusion.}
\label{fig_uxms_processes_b}
\end{figure}

\vspace{0.1in}
\noindent
Once a process has been selected, \app{uXMS} will subscribe for all
variables published by the selected process. Note this is different
from subscribing for mail solely produced by the selected MOOS app
since the same variable(s) may be also published by other MOOS
applications. The example in Figure \ref{fig_uxms_processes_b} is 
also from the alpha mission. If the \app{pMarineViewer} application
were selected, a scoping report something like that below in Figure
\ref{fig_uxms_processes_c} would result.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/uxms_processes_c_bdr.png}
  \caption{{\bf Augmented scoping report:} The variables published by
    \app{pMarineViewer} are now included in the scoping report after
    this process was selected for inclusion.}
\label{fig_uxms_processes_c}
\end{figure}

\noindent
Once a process has been added or excluded, its status will be
indicated next time the processes mode is entered, with either a
\var{'+'} or \var{'-'} next to the process ID. For example, the report
shown in Figure \ref{fig_uxms_processes_d} below is generated after
hitting the \var{'-'} key to select a process for exclusion. The plus
sign next to the \app{pMarineViewer} indicates that it has been
selected for inclusion previously.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.65\textwidth]{figures/uxms_processes_d_bdr.png}
  \caption{{\bf Excluding watch-list variables based on process
      origin:} The process list includes an indicator to the left of
    the ID showing whether the process is presently included
    (\var{'+'}) or excluded (\var{'-'}). In this case the
    \vvar{pMarineViewer} application has been included but no action
    has been taken regarding any other processes.}
\label{fig_uxms_processes_d}
\end{figure}
\vspace{0.1in}

\noindent
When a process or application has been selected for {\em exclusion}, this
is handled in the following way. When a scoping report is being generated, 
if a particular variable has most recently been set by an excluded process, 
it is not include in the scoping report. Note, it may have also been published
by another application not on the exclusion list.


%===================================================================
\section{Configuration File Parameters for uXMS}
%===================================================================
\label{sec_uxms_config}
%\index{Configuration Parameters!uXMS}
%\index{uXMS!Configuration Parameters}

Configuraton of \app{uXMS} may be done from a configuration file
(\var{.moos} file), from the command line, or both. Generally the 
parameter settings given on the command line override the settings
from the \var{.moos} file, but using the configuration file is a 
convenient way of ensuring certain settings are in effect on repeated
command line invocations. The following is short description of 
the parameters:

\vspace{0.25in}
\begin{listing}{Configuration Parameters for \app{uXMS}}
\label{params_uxms}

\renewcommand{\arraystretch}{1.2}
\begin{longtable}{rp{0.76\textwidth}} 
  
  \pvar{colormap}: &amp; Associates a color for the line of text reporting
  the given variable. \\

  \pvar{content\_mode}: &amp; Set content mode to either \var{scoping},
  \var{history}, \var{procs}, or \var{help}. \\

  \pvar{display\_all}: &amp; If \var{true}, all variables are reported in
  the {\em scoping} content mode. \\

  \pvar{display\_aux\_source}: &amp; If \var{true}, non-null auxilliary
  source is shown in place of source. \\

  \pvar{display\_community}: &amp; If \var{true}, the Community column is
  rendered.  \\

  \pvar{display\_history\_var}: &amp; If \var{false}, history var not
  shown in history mode. \\

  \pvar{display\_source}: &amp; If \var{true}, the Source column is
  rendered. \\

  \pvar{display\_time}: &amp; If \var{true}, the Time column is rendered.
  \\

  \pvar{display\_virgins}: &amp; If \var{false}, variables never written
  to the MOOSDB are not reported. \\

  \pvar{history\_var}: &amp; Names the MOOS variable reported in the {\em
    history} mode.  \\

  \pvar{refresh\_mode}: &amp; Determines when new reports are written to
  the screen. \\

  \pvar{source}: &amp; Names a MOOS app for which all variables will be
  scoped. \\

  \pvar{term\_report\_interval}: &amp; Time (secs) between report updates
  (default 0.6). \\

  \pvar{trunc\_data}: &amp; If \var{true}, variable string values are
  truncated. \\

  \pvar{wrap\_data}: &amp; If \var{true}, variable string values are
  multi-line wrapped. \\

  \pvar{wrap\_data\_len}: &amp; Content line length if wrapping string
  value output. Default is 45.\\

  \pvar{var}: &amp; A comma-separated list of variables to scope on in the 
      {\em scoping} mode. \\
      
\end{longtable}
\end{listing}

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

An example configuration is given in Listing \ref{uxms_config}. This may 
also be elicited from the command line:

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

\begin{listing}{An example \app{uXMS} configuration block}
\label{uxms_config}
\footnotesize
\begin{verbatim}
  1  ProcessConfig = uXMS                                            
  2  {                                                               
  3    AppTick   = 4                                                 
  4    CommsTick = 4                                                 
  5                                                                  
  6    var    = NAV_X, NAV_Y, NAV_SPEED, NAV_HEADING                 
  7    var    = PROC_WATCH_SUMMARY                                   
  8    var    = PROC_WATCH_EVENT                                     
  9    source = pHelmIvP, pMarineViewer                              
 10                                                                  
 11    history_var           = DB_CLIENTS                            
 12                                                                  
 13    display_virgins       = true    // default                    
 14    display_source        = false   // default                    
 15    display_aux_source    = false   // default                    
 16    display_time          = false   // default                    
 17    display_community     = false   // default                    
 18    display_all           = false   // default                    
 19    trunc_data            = 40      // default is no trucation.   
 20                                                                  
 21    wrap_data             = false   // default                                 
 22    wrap_data_len         = 45      // default                                 
 23                                                                  
 24    term_report_interval  = 0.6     // default (seconds)          
 25                                                                  
 26    color_map    = pHelmIvP, red   // All postings by pHelmIvP red
 27    color_map    = NAV_SPEED, blue // Only var NAV_SPEED is blue  
 28                                                                  
 29    refresh_mode = events     // default (or streaming/paused)    
 30    content_mode = scoping    // default (or history,procs)       
 31  }                                                               
\end{verbatim}
\end{listing}
\normalsize

%===================================================================
\subsection{The colormap Configuration Parameter}

Most of the the configurable options deal with content and
layout of the information in the terminal window, but color can also
be used to faciliate monitoring one or more variables. The parameter

\prevblue
\begin{verbatim}
    colormap = &lt;variable/app&gt;, &lt;color&gt;
\end{verbatim}
\postverb

\noindent
is used to request that a line the report containing the given
variable or produced by the given MOOS application (source) is
rendered in the given color. The choices for color are limited to red,
green, blue, cyan, and magenta.

%===================================================================
\subsection{The content\_mode Configuration Parameter}

The content mode determines what information is generated in each
report to the terminal output (Section \ref{uxms_content_mode}). This
mode is set with the following parameter:

\prevblue
\begin{verbatim}
    content_mode = &lt;mode-type&gt;   // Default is "scoping"
\end{verbatim}
\postverb


\noindent
The default setting is \var{"scoping"} to select the scoping content
mode described in Section \ref{sec_scoping_mode}. It may also be set
to \var{"history"} to select the history mode described in Section
\ref{sec_uxms_history_mode}, or set to \var{"procs"} to select the
processes mode described in Section \ref{sec_uxms_processes_mode}.

%===================================================================
\subsection{The display* Configuration Parameters}

In the scoping and history content modes, the \app{uXMS} report has
columns of data that may be optionally turned off to conserve real
estate, the {\em Time}, {\em Source} and {\em Community} columns as
shown in Figures \ref{fig_uxms_simple}, \ref{fig_uxms_history}, and
\ref{fig_uxms_processes_c}. By default they are turned off, and they
may be toggled on and off by the user at run time. Their initial state
may also be configured with the following three parameters:

\prevblue
\begin{verbatim}
     display_community  = &lt;Boolean&gt; // Default is false
     display_source     = &lt;Boolean&gt; // Default is false
     display_time       = &lt;Boolean&gt; // Default is false
     display_aux_source = &lt;Boolean&gt; // Default is false 
\end{verbatim}
\postverb

\noindent
The \pvar{display\_aux\_source} parameter, when true, not only
activates this column, but also indicates that the auxilliary source
is to be shown instead of the source. Not all MOOS variable postings
have the auxilliary source field filled in. In the case of variables
posted by the helm, however, this field contains the both the helm
iteration and name of the behavior. If the auxilliary source is empty
for a particular variable, the primary source is shown instead. To be
clear what is being shown, the auxilliary source is always contained
in brackets. For example, \var{[241:waypoint\_return]}, may indicate
the variable was posted by the helm on iteration 241 by the waypoint
return behavior.

\pskip

The \pvar{display\_all} parameter determines whether the scope list
contains only those variables specified by the user, or all MOOS
variables pubished by any MOOS process. The latter is useful at times
when you can't quite remember the variable name you're looking for or
who publishes it. When displaying all variables, certain variables may
be masked out by selecting a process (MOOS app) to exclude, as
described in Section \ref{sec_uxms_processes_mode}. It may also be
enabled with the \var{'A'} key, and disabled with the \var{'a'} key at
the terminal at run time. It may also be enabled from the command line
with the \var{--all} or \var{-a} switches.

\prevblue
\begin{verbatim}
    display_all = &lt;Boolean&gt; // Default is false
\end{verbatim}
\postverb

\noindent
Using the \pvar{dipplay\_virgins} parameter, the report content may be
further modified to mask out lines containing variables that have
never been written to, and variables with an empty-string value. This
is done with the below configuration line.  It may also be toggled
with the \var{'v'} key at the terminal at run time, and it may also be
specified from the command line with the \var{--novirgins} or \var{-g}
switches.

\prevblue
\begin{verbatim}
    display_virgins = &lt;Boolean&gt; // Default is true
\end{verbatim}
\postverb

\noindent
In the history mode, the name of the variable is the same on each
line.  This makes it clear what variable is being shown, but takes up
screen real estate and is redundant. It may be suppressed by setting
\pvar{display\_history\_var} to false in the mission file. It may also
be toggled with the \var{'j'} key at the terminal at run time.

\prevblue
\begin{verbatim}
    display_history_var = &lt;Boolean&gt; // Default is true
\end{verbatim}
\postverb[0in]

%===================================================================
\subsection{The history\_var Configuration Parameter}

The variable reported in the {\em history} mode is set with the below
configuration line:

\prevblue
\begin{verbatim}
    history_var = &lt;MOOSVar&gt;
\end{verbatim}
\postverb

\noindent
The history report only allows for one variable, and multiple
instances of the above line will simply honor the last line provided.
The history variable is also automatically added to the watch list 
used in the scoping mode. The history variable may also be set on 
the command line when \app{uXMS} is launched from the terminal, with 
\var{--history=&lt;MOOS-variable&gt;}. If set in both places, the command 
line choice overrides the choice in the mission file.

%===================================================================
\subsection{The refresh\_mode Configuration Parameter}

The {\em refresh} mode determines when new reports are generated to
the screen, as discussed in Section \ref{sec_uxms_refresh_mode}. It is set
with the below configuration line:

\prevblue
\begin{verbatim}
    refresh_mode = &lt;mode&gt;  // Valid modes are "paused", "streaming", "events"
\end{verbatim}
\postverb

\noindent
The initial refresh mode is set to \var{"events"} by default. The
refresh mode set in the configuration file may be overridden from the
command line with \var{--mode=paused|events|streaming}, or chosen
interactively at run time with the \var{'e'} key for {\em events}, the
spacebar key for {\em paused}, or the \var{'r'} key for {\em
  streaming}.

%===================================================================
\subsection{The \pvar{source} Configuration Parameter}
\label{sec_uxms_param_source}

The variable scope list may be set or augmented by naming a particular
MOOS app source with the below parameter:

\prevblue
\begin{verbatim}
    source = &lt;MOOSApp&gt;, &lt;MOOSApp&gt;, ...
\end{verbatim}
\postverb

\noindent
With this, \app{uXMS} will subscribe for any MOOS variable published by
the named application(s). Since variables may be published by multiple
applications, don't be surprised to see postings made by other
applications.  This is {\em not} a request to receive mail only from
the named source(s). Sources may also be chosen from the command line 
with the \var{--src=&lt;MOOSApp&gt;,&lt;MOOSApp&gt;,..K} command line switch. Sources
may also be included or excluded dynamically in the \var{processes} content
mode as described in Section \ref{sec_uxms_processes_mode}, with the 
'+' and '-' keys.

%===================================================================
\subsection{The \pvar{term\_report\_interval} Configuration Parameter}

The \pvar{term\_report\_interval} is a parameter defined for all
AppCasting MOOS applications. It specifies the amount of time between
success updates to the terminal. Report updates are not based on the
application's apptick since this may be considerably faster than the
human may absorb and wastes CPU resources. The default refresh rate is
$0.6$ seconds between refreshes. This may be overridden with:

\prevblue
\begin{verbatim}
    term_report_interval = &lt;Non-Zero Value&gt; // Default is 0.6 seconds
\end{verbatim}
\postverb

\noindent
The interval may also be specified on the command line with the
\var{--termint=&lt;Non-Zero Value&gt;} switch. The accepted range, in seconds,
is $[0,10]$. Keep in mind that report frequency cannot be any faster 
than the actual apptick set for \app{uXMS}.

%===================================================================
\subsection{The \pvar{trunc\_data} Configuration Parameter}

The current value of a MOOS variable is shown in the \var{VarValue} 
column in both the scoping and history content modes. This value may be
quite long and overwrap several lines and make things hard to read.
The user can choose to truncate the content by setting \pvar{trunc\_data}
parameter:

\prevblue
\begin{verbatim}
    trunc_data = &lt;unsigned int&gt; // Default is zero (no truncating)
\end{verbatim}
\postverb

\noindent
Values are accepted in the range $[10,1000]$. Truncated string output
will be further indicated by adding a trailing \var{"..."} to the end
of the output. Truncation may be toggled on/off at run time by hitting
the \var{'`'} (back-tick) key. The default truncation length is 40 
characters. The length of truncated output may also be adjusted at run time
with the '\{' and `\}' keys.

%===================================================================
\subsection{The \pvar{wrap\_data} and \pvar{wrap\_data\_len} Configuration Parameters}

The current value of a MOOS variable is shown in the \var{VarValue}
column in both the scoping and history content modes. This value may
be quite long and overwrap several lines and make things hard to read.
When view \app{uXMS} output in the appcasting window of
\app{pMarineViewer}, it is really hard to see long output.  The user
can choose to wrap the content {\em within the value column of the
  output} by setting \pvar{wrap\_data} parameter:

\prevblue
\begin{verbatim}
    wrap_data = true
    wrap_data_len = 30  // default is 45
\end{verbatim}
\postverb

\noindent
Values for \pvar{wrap\_data\_data} are accepted in the range $[10,120]$.
The default value is 45. The value of this parameter is set only in the
configuration file and cannot be changed at run time. If \app{uXMS} is run
from the terminal (rather than viewing content in an appcasting window),
the wrapping can be toggled on and off with the \var{'w'} character.

%===================================================================
\subsection{The \pvar{var} Configuration Parameter}
\label{sec_uxms_param_var}

The variables reported on in the {\em scoping} mode, the scope list,
are declared with configuration lines of the form:

\prevblue
\begin{verbatim}
    var = &lt;MOOSVar&gt;, &lt;MOOSVar&gt;, ... 
\end{verbatim}
\postverb

\noindent
Multiple such lines, each perhaps with multiple variables, are
accommodated.  The scope list may be {\em augmented} on the command
line by simply naming variables as command line arguments. The scope
list provided on the command line may {\em replace} the list given in
the configuration file if the \var{--clean} command line option is
also invoked.

%===================================================================
\section{Command Line Usage of uXMS}
\label{sec_uxms_cmdline}
%\index{Command Line Usage!uXMS}
%\index{uXMS!Command Line Usage}
%\index{Configuration Parameters!uXMS}
%\index{uXMS!Configuration Parameters}

Many of the parameters available for setting the \var{.moos} file
configuration block can also be affected from the command line. The
command line configurations always trump any configurations in the
\var{.moos} file. As with the \app{uPokeDB} application, the server
host and server port information can be specified from the command
line too to make it easy to open a \app{uXMS} window from anywhere
within the directory tree without needing to know where the
\var{.moos} file resides. A \app{uXMS} session can be launched to
connect to the MOOSDB of a remote vehicle on the network, if the IP
address and port number are known, with:

\vspace{0.1in}
\begin{consoleverb}
 $ uXMS --serverhost=10.25.0.191 --serverport=9000 --src=pHelmIvP
\end{consoleverb}
\vspace{0.15in}

\noindent
The basic command line usage for the \app{uXMS} application is the
following:

\vspace{0.1in}
\begin{consoleverb}
 $ uXMS --help or -h
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{uXMS} tool}
\label{uxms_usage}
\footnotesize
\begin{verbatim}
   1  Usage: uXMS [file.moos] [OPTIONS]
   2  Options:                                                        
   3    --alias=&lt;ProcessName&gt;                                      
   4        Launch uXMS with the given process name rather than uXMS. 
   5    --all,-a                                                      
   6      Show ALL MOOS variables in the MOOSDB                       
   7    --clean,-c                                                    
   8      Ignore scope variables in file.moos                         
   9    --colormap=&lt;MOOSVar&gt;,&lt;color&gt;                               
  10      Display all entries where the variable, source, or community
  11      has VAR as substring. Allowable olors: blue, red, magenta,  
  12      cyan, or green.                                             
  13    --colorany=&lt;MOOSVar&gt;,&lt;MOOSVar&gt;,...                         
  14      Display all entries where the variable, community, or source
  15      has VAR as substring. Color auto-chosen from unused colors. 
  16    --example, -e                                                 
  17        Display example MOOS configuration block.                 
  18    --help,-h                                                     
  19        Display this help message.                                
  20    --history=&lt;MOOSVar&gt;                                           
  21      Allow history-scoping on variable                           
  22    --interface,-i                                                
  23        Display MOOS publications and subscriptions.              
  24    --novirgins,-g                                                
  25      Don't display virgin variables                              
  26    --mode=[paused,EVENTS,streaming]                           
  27      Determine display mode. Paused: scope updated only on user  
  28      request. Events: data updated only on change to a scoped    
  29      variable. Streaming: updates continuously on each app-tick. 
  30    --serverhost=&lt;IPAddress&gt;                                  
  31    --mooshost=&lt;IPAddress&gt;                                  
  32      Connect to MOOSDB at IP=value, not from the .moos file.     
  33    --serverport=&lt;PortNumber&gt;                                 
  34    --moosport=&lt;PortNumber&gt;                                 
  35      Connect to MOOSDB at port=value, not from the .moos file.   
  36    --show=[source,time,community,aux]                         
  37      Turn on data display in the named column, source, time, or  
  38      community. All off by default enabling aux shows the        
  39      auxilliary source in the souce column.                      
  40    --src=&lt;MOOSApp&gt;,&lt;MOOSApp&gt;, ...                             
  41      Scope only on vars posted by the given MOOS processes       
  42    --trunc=value [10,1000]                                    
  43      Truncate the output in the data column.                     
  44    --termint=value [0,10]  (default is 0.6)                   
  45      Minimum real-time seconds between terminal reports.         
  46    --version,-v                                                  
  47      Display the release version of uXMS.                        
  48                                                                  
  49  Shortcuts                                                       
  50                                                                  
  51    -t  Short for --trunc=25                                      
  52    -p  Short for --mode=paused                                   
  53    -s  Short for --show=source                                   
  55    -st Short for --show=source,time             
\end{verbatim}
\end{listing}
\normalsize

Using the \var{--clean} switch will cause \app{uXMS} to ignore the
variables or sources specified in the \var{.moos} file configuration
block and only scope on the variables specified on the command line
(otherwise the union of the two sets of variables is used).  Typically
this is done when a user wants to quickly scope on a couple variables
and doesn't want to be distracted with the longer list specified in
the \var{.moos} file.  Arguments on the command line other than the
ones described above are treated as variable requests. 

\pskip

If the \var{serverhost} or the \var{serverport} arguments are not provided
on the command line, and a MOOS file is also not provided, the user
will be prompted for the two values. Since the most common scenario is
when the MOOSDB is running on the local machine ("localhost") with
port 9000, these are the default values and the user can simply hit
the return key.

\begin{consoleverb}
 $ uXMS 
 $ Enter Server: [localhost] &lt;return&gt;
     The server is set to "localhost"
 $ Enter Port: [9000] &lt;return&gt;
 $    The port is set to "9000"
\end{consoleverb}

%===================================================================
\section{Console Interaction with uXMS at Run Time}
%===================================================================
\label{uxms_runtime}
%\index{uXMS!Console Interaction}

Many of the launch-time configuration parameters may be altered at run
time through interaction with the console window. For example, the
displaying of the Source column is configured to be false by default,
may be configured in the mission file with \pvar{display\_source}\psvar{=true},
and may be configured on the command line with \var{--show=source}. It
may also be toggled at run time by typing the \var{'s'} character at
the console window. A list of run-time key mappings may be shown at
any time by typing the \var{'h'} key for help. Re-hitting this key
resumes prior scoping. Listing \ref{uxms_console_help} shows the
contents of the help menu.

\vspace{0.1in}
\begin{listing}{The help-menu on the \app{uXMS} console}
\label{uxms_console_help}
\footnotesize
\begin{verbatim}
   1  KeyStroke    Function         (HELP)      
   2  ---------    ---------------------------             
   3      s        Toggle show source of variables         
   4      t        Toggle show time of variables           
   5      c        Toggle show community of variables      
   6      v        Toggle show virgin variables            
   7      x        Toggle show Auxilliary Src if non-empty 
   8      d        Content Mode: Scoping Normal            
   9      h        Content Mode: Help. Hit 'R' to resume   
  10      p        Content Mode: Processes Info            
  11      z        Content Mode: Variable History          
  12    &gt; or &lt;     Show More or Less Variable History      
  13    } or {     Show More or Less Truncated VarValue
  14      /        Begin entering a filter string          
  15      `        Toggle Data Field truncation            
  16      ?        Clear current filter                    
  17      a        Revert to variables shown at startup    
  18      A        Display all variables in the database   
  19     u/SPC     Refresh Mode: Update then Pause         
  20      r        Refresh Mode: Streaming                 
  21      e        Refresh Mode: Event-driven refresh      
\end{verbatim}
\end{listing}
\normalsize

%===================================================================
\section{Running uXMS Locally or Remotely}
%===================================================================
\label{uxms_remote}

The choice of \app{uXMS} as a scoping tool was designed in part to
support situations where the target MOOSDB is running on a vehicle
with low bandwidth communications, such as an AUV sitting on the
surface with only a weak RF link back to the ship. There are two
distinct ways one can run \app{uXMS} in this situation and its worth
noting the difference. One way is to run \app{uXMS} locally on one's
own machine, and connect remotely to the MOOSDB on the vehicle. The
other way is to log onto the vehicle through a terminal, run
\app{uXMS} remotely, but in effect connecting locally to the MOOSDB
also running on the vehicle.

The difference is seen when considering that \app{uXMS} is running three
separate threads. One accepts mail delivered by the MOOSDB, one
executes the iterate loop of \app{uXMS} where reports are written to the
terminal, and one monitors the keyboard for user input. If running
\app{uXMS} locally, connected remotely, even though the user may be in
paused mode with no keyboard interaction or reports written to the
terminal, the first thread still may have a communication requirement
perhaps larger than the bandwidth will support. If running remotely,
connected locally, the first thread is easily supported since the mail
is communicated locally. Bandwidth is consumed in the second two
threads, but the user controls this by being in paused mode and
requesting new reports judiciously.

%===================================================================
\section{Connecting multiple uXMS processes to a single MOOSDB}
%===================================================================

Multiple versions of \app{uXMS} may be connected to a single
MOOSDB. This is to simultaneously allow several people a scope onto a
vehicle. Although MOOS disallows two processes of the same name to
connect to MOOSDB, \app{uXMS} generates a random number between 0-999
and adds it as a suffix to the \app{uXMS} name when connected. Thus it
may show up as something like \var{uXMS\_871} if you scope on the
variable \mvar{DB\_CLIENTS}. In the unlikely event of a name collision,
the user can just try again.

%===================================================================
\section{Using uXMS with Appcasting}
%===================================================================
\label{sec_uxms_appcast}

Appcasting allows a really useful way of using \app{uXMS}, especially
in the case of multiple deployed vehicles. Prior to appcasting, the 
only way to use \app{uXMS} is through a terminal window. With appcasting
the \app{uXMS} report may also be published to the MOOSDB for remote
viewing via a \app{uMAC} utility or with \app{pMarineViewer}. 

\pskip

For example, consider a case where some number of vehicles are deployed,
each with an interface to their batteries, compass and GPS. The interfaces
may be named \app{iBatteryMonitor}, \app{iCompass}, and \app{iGPS}. Each 
interface publishes several MOOS variables including health status messages.
A mission could be configurd with three \app{uXMS} processes launched 
at mission startup with something similar to:

\vspace{0.15in}
\begin{listing}{Launching several \app{uXMS} processes with appcasting}
\label{lst_uxms_appcast}
\footnotesize
\begin{verbatim}
  1  ProcessConfig = ANTLER
  2  {
  3    MSBetweenLaunches = 200
  4    
  5    Run = MOOSDB          @ NewConsole = false
  6    // Other MOOS Apps
  7    Run = iGPS            @ NewConsole = false
  8    Run = iBatteryMonitor @ NewConsole = false
  9    Run = iCompas         @ NewConsole = false
 10    Run = uXMS            @ NewConsole = false ~ uXMS_GPS
 11    Run = uXMS            @ NewConsole = false ~ uXMS_BATTERY_MONITOR
 12    Run = uXMS            @ NewConsole = false ~ uXMS_COMPASS
 13  }
 14    
 15  ProcessConfig = uXMS_GPS
 16  {
 17    SOURCE = iGPS
 18  }
 19  ProcessConfig = uXMS_BATTERY_MONITOR
 20  {
 21    SOURCE = iBatteryMonitor
 22  }
 23  ProcessConfig = uXMS_COMPASS
 24  {
 25    SOURCE = iCompass
 26  }
\end{verbatim}
\end{listing}
\normalsize

\noindent 
With this configuration the three \app{uXMS} processes will launch,
each {\em without} a terminal window open, and each with a different
descriptive name. The \app{uXMS} reports are accessible with any of
the appcast viewing tools, \app{uMAC}, \app{uMACView}, and
\app{pMarineViewer}. In the latter two tools for example, the \app{uXMS}
reports may appear in a menu selection like that shown in Figure
\ref{fig_uxms_appcast}. 

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.62\textwidth]{figures/uxms_appcast.png}
  \caption{{\bf Appcasting and uXMS:} Multiple vehicles are each
    configured with three dedicated \aapp{uXMS} processes to scope on
    variables particular to a given device or sensor. The \aapp{uMAC}
    viewer interface allows the user to select any vehicle and select
    a \vvar{uXMS} report to see the desired information for that
    vehicle and device.}
\label{fig_uxms_appcast}
\end{figure}

\noindent
In this way the user may monitor the health of these three instruments
across all fielded vehicles with a single GUI without having to write
any special code for these devices.


%===================================================================
\section{Publications and Subscriptions for uXMS}
%===================================================================
%\index{uXMS!Publications and Subscriptions}
%\index{Publications and Subscriptions!uXMS}
\label{sec_uxms_interface}

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

\vspace{0.10in}
\begin{consoleverb}
 $ uXMS --interface or -i
\end{consoleverb}
\vspace{0.05in}

%===================================================================
\subsection{Variables Published by uXMS}
\label{sec_uxms_pubs}

\begin{packed_itemize}
\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Appcasts are posted only after an appcast request
  is received from an appcast viewing utility. Section
  \ref{sec_uxms_appcast}.
\end{packed_itemize}

%===================================================================
\subsection{Variables Subscribed for by uXMS}
\label{sec_uxms_subs}

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

\item \mvar{DB\_CLIENTS}: To handle requests to scope on all
  variables.

\item \mvar{DB\_UPTIME}: To determine the MOOSDB start time. All
  \app{uXMS} times reported are times since MOOSDB started.

\item \mvar{PROC\_WATCH\_SUMMARY}: As a convenience this summary is
  displayed in the {\em processes} content mode. It is posted by
  \app{uProcessWatch}.

\item \mvar{USER-DEFINED}: The variables subscribed for are those
  on the {\em scope list}, augmented with the \pvar{var} and \pvar{source}
  parameters described in Sections \ref{sec_uxms_param_source} and 
  \ref{sec_uxms_param_var}.
\end{packed_itemize}

\end{document}

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