<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{The uMAC Utilities}
\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.UMACTools}
\wikidoc{bugz=uMAC}
\wikidoc{auth=mikerb@mit.edu}

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

In this section the utilities for viewing appcasts and/or realmcasts
are discussed. They include:

\begin{packed_itemize}[2]
\item The \app{uMACView} utility: A GUI tool containing navigation
  tools for viewing appcasts or realmcasts across multiple vehicles or nodes. A
  snapshot is shown in Figure \ref{fig_umacview_window}.
\item The \app{uMAC} utility: A utility implement in the terminal
  window. Simpler in the interface, but notable in that it allows a
  user to remotely launch the tool on deployed vehicle.
\item \app{uMACView} integrated with \app{pMarineViewer}: An interface
  nearly identical with \app{uMACView} fully integrated within
  \app{pMarineViewer}, convenient for those already using
  \app{pMarineViewer}.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Note: Starting with the first release after 2019's Release 19.8,
\app{uMACView} and \app{pMarineViewer} were augmented to include
realmcasting in addition to appcasting. The term {\em infocasting} is
the general term referring to either appcasting or realmcasting. To use
realmcasting, an additional app, \app{pRealm} needs to be running in
each MOOS community, typically on the shoreside and in each vehicle
community. More information on \app{pRealm} can be found in
\cite{url_prealm}

\vspace{0.1in}
\noindent
The \app{uMAC} utility currently only support appcasting output.





%=================================================================
\section{The uMACView Utility}
%=================================================================
\label{sec_umacview}

The \app{uMACView} utility is an appcast or realmcast viewer with a
graphical user interface using the FLTK library. It contains three
panes as shown in Figure \ref{fig_umacview_window}. The bottom pane
renders incoming appcasts or realmcasts. The top right pane lists
possible applications for selecting appcast or realmcast viewing for
the present node. The upper left pane shows all presently known nodes
from which appcasts or realmcasts have been received. In realmcasting,
the upper left pane may also offer a number of variable clusters to
select from.

\begin{figure}[H]
  \centering
  \includegraphics[width=0.98\textwidth]{figures/fig_umacview_window.png}
  \caption{The uMACView utility receives appcasts or realmcasts from
    perhaps several different nodes and applications on each node. The
    interface allows the user to select a node and application for
    viewing the selected application's latest appcast or
    realmcast. The with appcasting, the viewer will raise alerts from
    non-selected nodes and applications when or if a run warning
    occurs. To toggle between appcasting and realmcasting, the
    \var{'a'} key is used.}
  \label{fig_umacview_window}
\end{figure}

\vspace{0.1in}
\noindent
The content mode is either {\em appcasting} or {\em realmcasting}. To toggle
between the two modes, the \var{'a'} key is used. Alternatively the startup
mode can be set with the \pvar{content\_mode} configuration parameter, which
is set to either \var{appcast} or \var{realmcast}, with the former being the
default.


%=================================================================
\subsection{AppCasting}

\noindent
The content of the {\em appcast pane} is solely determined by the
appcast content itself. From the viewer's perspective it is simply
pushing a list of strings to a browser pane. Even the formatting of
the header lines showing the application name, node name and
application iteration, are formatted by a method defined over the
AppCast class.

\pskip

The content of the \var{application pane} lists the applications known
thus far to the viewer from incoming appcasts for a particular
node. The order is shown by the order in which they were received. The
three columns, \var{"AC"}, \var{"CW"}, and \var{"RW"}, show the number
of appcasts received from the application, and the number of run
warnings and configuration warnings in the latest appcast.

\pskip

The content of the {\em node pane} in the upper left lists the nodes
known thus far to the viewer from incoming appcasts.  The order is
shown by the order in which they were received. The three columns,
\var{"AC"}, \var{"CW"}, and \var{"RW"}, show the number of appcasts
received from a given node for {\em all} applications from that node,
as well as the sum of all run warnings and configuration warnings for
all applications received from the given node.


%=================================================================
\subsection{RealmCasting}

The content of the {\em realmcast pane} is fed from an app called \app{pRealm}
running on the node selected in the node pane, and related to the application
selected in the upper right app pane. A typical realmcast report is shown
in Figure \ref{fig_pmv_rc_example}:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.98\textwidth]{figures/pmv_relcast_example.png}
  \caption{{\bf Example RealmCast Report:} A realmcast message is expanded
    into a multi-line report, consisting of a report on subscribed variables
    and published variables for a given application. In this case the report
    is for the \app{pContactMgrV20} application on vehicle \var{gilda}.}
\label{fig_pmv_rc_example}
\end{figure}

\vspace{0.1in}
\noindent
The content of the report can be adjusted by the client, e.g.,
\app{uMACViewer} user, to help visualize the important information. There
are seven options:

\begin{packed_itemize}
\item Source: The Source column of the report may be suppressed.
\item Community: The Community column of the report may be suppressed.
\item UTC Time: The time format may be shown in absolute UTC time, or relative
  to the start of the local MOOSDB.
\item Subscriptions: The subscriptions portion of the report may be suppressed.
\item Mask: In the subscriptions portion, virgin variables may be suppressed.
\item Wrap: Long string content may be wrapped over several lines, e.g., as in
  Figure \ref{fig_pmv_rc_example}.
\item Truncate: Long string content may be truncated.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Realmcast content may be adjusted through the seven buttons on the
lower part of \app{uMACViewer}.  These buttons are only present when
realmcasting is enabled.

\vspace{0.1in}
\noindent
The start-up value of these settings may also be set to the user's
liking in the \app{uMACViewer} configuration block:

\prevblue
\begin{verbatim}
  realmcast_show_source        = true/false   // Default is true
  realmcast_show_community     = true/false   // Default is true
  realmcast_show_subscriptions = true/false   // Default is true
  realmcast_show_masked        = true/false   // Default is true
  realmcast_wrap_content       = true/false   // Default is false
  realmcast_trunc_content      = true/false   // Default is false
  realmcast_time_format_utc    = true/false   // Default is false
\end{verbatim}
\postverb



%=================================================================
\subsection{Publications and Subscriptions}
%=================================================================
\label{sec_umacview_pubs}

%-----------------------------------------------------------------
\subsubsection{Variables Published by uMACViewer}

\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{APPCAST\_REQ\_&lt;COMMUNITY&gt;}: As an appcast viewer,
  \app{pMarineViewer} also generates outgoing appcast requests to MOOS
  communities it is aware of, including its own MOOS community. These
  postings are typically bridged to the other named MOOS community 
  with the variable renamed simply to \mvar{APPCAST\_REQ} when it
  arrives in the other community.
\end{packed_itemize}

%-----------------------------------------------------------------
\subsubsection{Variables Subscribed for by uMACViewer}
\label{sec_pmv_subs}

\begin{packed_itemize}[2]
\item \mvar{APPCAST}: As an appcast enabled {\em viewer}, \app{pMarineViewer} also
  subscribes for appcasts from other other applications and communities to 
  provide the content for its own viewing capability.

\item \mvar{REALMCAST}: As an realmcast enabled {\em viewer},
  \app{pMarineViewer} also subscribes for realmcasts from MOOS communities
  running \app{pRealm}, and renders them in the infocast panes
  described in Section \ref{sec_pmv_ac_vs_rc}.

\item \mvar{WATCHCAST}: As an realmcast enabled {\em viewer},
  \app{uMACViewer} also subscribes for watchcasts from MOOS
  communities running \app{pRealm}, and renders them in the infocast
  panes.

\end{packed_itemize}
 

%=================================================================
\subsection{Configuration File Parameters}
\label{sec_umacview_config}
\index{uMACView!Configuration Parameters}
\index{Configuration Parameters!uMACView}

A few configuration parameters are exposed to facilitate visual
preference settings that would otherwise need to be done each time the
application is launched via pull-down menus. These parameters are
listed below, but may be recalled anytime by typing on the command
line: \var{"uMACView -e"}.

\vspace{0.1in}
\noindent
Note: \app{uMACView} was released in 2012. Starting with the first
release after 2019's Release 19.8, this app was augmented to include
realmcasting in addition to appcasting. The term {\em infocasting} is
the general term referring to either appcasting or realmcasting.  As
such, some of the earlier configuration parameters, e.g.,
\pvar{appcast\_font\_size}, have been replace with a term like
\app{infocast\_font\_size}. The older configuration parameters are
deprecated but still supported foreseeable releases.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for uMACView}
\label{lst_umv_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.63\textwidth}} 

  \pvar{appcast\_color\_scheme}: &amp; Possible settings, {\var{default},
    \var{beige}, \var{indigo} or \var{white}}. The default is
  \var{indigo}. \\

  \pvar{content\_mode}: &amp; Sets the on startup content, which can be
  changed by the user at any time. Either \var{appcast} or
  \var{realmcast}. The default is \var{appcast}. \\

  \pvar{infocast\_font\_size}: &amp; Possible settings, {\var{xsmall},
    \var{small}, \var{medium},\var{large},\var{xlarge}}. The default
  is \var{medium}. \\

  \pvar{infocast\_height}: &amp; Possible settings, [\var{30,35,40,...,
      85,90}].  The default is \var{70}. \\

  \pvar{nodes\_font\_size}: &amp; The font size used in the {\em nodes}
  pane of the set of infocasting panes. Possible settings,
  {\var{xsmall}, \var{small}, \var{medium}, \var{large}, or
    \var{xlarge}}. The default is \var{large}. \\


  \pvar{procs\_font\_size}: &amp; Possible settings, {\var{xsmall},
    \var{small}, \var{medium}, \var{large} or \var{xlarge}}. The
  default is \var{large}. \\
  
  \pvar{realmcast\_color\_scheme}: &amp; Either \var{indigo}, \var{beige},
  \var{hillside}, \var{white}, or \var{default}. The default is
  \var{hillside}. \\

  \pvar{realmcast\_show\_source}: &amp; If \var{true}, the Source column
  is shown on realmcast output. Setting to \var{false} conserves
  screen space, possibly enhancing readability.  The default is
  \var{true}. \\

  \pvar{realmcast\_show\_community}: &amp; If \var{true}, the Community
  column is shown on realmcast output. Setting to \var{false}
  conserves screen space, possibly enhancing readability.  The default
  is \var{true}. \\
  
  \pvar{realmcast\_show\_subscriptions}: &amp; If \var{true}, the
  Subscriptions block is shown on realmcast output. Setting to
  \var{false} conserves screen space, possibly enhancing readability.
  The default is \var{true}. \\

  \pvar{realmcast\_show\_masked}: &amp; If \var{true}, certain variables
  are excluded in realmcast output, e.g., virgin variables. Setting to
  \var{false} conserves screen space, possibly enhancing readability.
  The default is \var{true}. \\
  
  \pvar{realmcast\_wrap\_content}: &amp; If \var{true}, the variable Value
  column in realmcast output will wrap onto several lines. Setting to
  \var{true} possibly enhances readability for very long output.  The
  default is \var{false}. \\

  \pvar{realmcast\_trunc\_content}: &amp; If \var{true}, the variable Value
  column in realmcast output will be truncated. Setting to
  \var{true} possibly enhances readability for very long output.  The
  default is \var{false}. \\

  \pvar{realmcast\_time\_format\_utc}: &amp; If \var{true} the Time column
  in realmcast output will be shown in UTC time instead of local time
  since app startup. The default is \var{false}. \\

  \pvar{refresh\_mode}: &amp; Possible settings, {\var{paused},
    \var{events}, \var{streaming}}. The default is \var{events}. \\

\end{longtable}
\end{listing}

\noindent
The \pvar{infocast\_height} refers to the relative height of the infocast
pane to the window. The default of \var{70} means the pane will be
\var{70\%} of the overall window height.

\pskip
The \pvar{refresh\_mode} refers to the policy of refreshing appcasts
via appcast requests sent to the nodes and their applications. This is
discussed below in Section \ref{sec_umv_refresh_modes}

%=================================================================
\subsection{Command Line Arguments and Options}

A few command line arguments are available. They are similar to most other
MOOS-IvP applications. These arguments are listed below, but may
be recalled anytime by typing on the command line:

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

\begin{packed_itemize}[2]
\item \var{--alias=&lt;ProcessName&gt;}: Launch with the given process name
  rather than uMACView.
\item \var{--example, -e}: Display example MOOS configuration block.
\item \var{--help, -h}: Display command line usage.
\item \var{--interface, -i}: Display MOOS publications and subscriptions.
\item \var{--version, -v}: Display release version information.
\end{packed_itemize}

%=================================================================
\subsection{Refresh Modes}
\label{sec_umv_refresh_modes}

The \app{uMACView} utility, operates in one of three {\em refresh
modes}.  This mode is always shown on the upper right in the title bar
in reverse color.  The three modes are the {\em streaming}, {\em
events}, and {\em paused} modes.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.45\textwidth]{figures/fig_umac_refresh_modes.png}
  \caption{The \var{uMAC} utility is in one of three {\em refresh
      modes}, determining the manner in which appcast requests are
    conveyed to known applications and nodes. Reserved keyboard keys
    are used to transition between modes.}
  \label{fig_umac_refresh_modes}
\end{figure}
\vspace{0.1in}


\paragraph{The Paused Refresh Mode}
In the {\em paused} refresh mode, no appcasts are solicited by
the \app{uMAC} utility. The information being rendered should remain
constant, virtually paused. Since appcast requests have a duration
associated with them, prior appcast requests received by an
application may need some time before expiring. Therefore
the \app{uMAC} user may still see a trickle of updates after entering
the paused mode. Furthermore, if there is another \app{uMAC} utility
open, generating appcast requests, updates might still be seen after
pausing.

\paragraph{The Events Refresh Mode}
In the {\em events} refresh mode, appcast requests of two types are 
sent to all known nodes and applications. The first type of request
is sent only to the selected node and application. This type requests
a continual update of appcasts, unconditionally. This application is,
after all, the selected application for viewing. The second type of
request is sent to all other nodes and applications requesting an 
appcast {\em only if a new run warning is generated}. The {\em events}
refresh mode is the default mode upon launch. 

\paragraph{The Streaming Refresh Mode}
In the {\em streaming} refresh mode, appcast requests are sent to all
nodes and all applications, all the time. Furthermore, the request
type is unconditional, meaning the application is requested to post
a new appcast regardless of whether anything has changed in the application
status. This mode is normally used for brief debugging, perhaps to 
check whether a node or application fails to respond. It creates a lot
of appcast messaging traffic. It is not recommended to operate in 
this mode normally.

%=================================================================
\section{The uMAC Utility}
%=================================================================
\label{sec_umac}

The \app{uMAC} utility is an appcast viewer implemented in the
terminal console. It acts the same as \app{uMACView} in terms of
soliciting appcasts by publishing \mvar{APPCAST\_REQ} messages and
receiving \mvar{APPCAST} mail. The advantage over the GUI tool is the
ability to remotely log into a vehicle and launch \app{uMAC} in a
terminal window. This is espcially useful if the vehicle is otherwise
not behaving in its communication with a shoreside MOOS community.
Like \app{uMACView}, multiple versions of the utility may be running
at the same time without interference with one another.

%=================================================================
\subsection{Content Modes}

The viewable information in the \app{uMAC} tool is rendered in one of
four {\em content modes}. Besides a {\em help} mode, the other three
modes correlate to one of the three panes of the \app{uMACView} window
in Figure \ref{fig_umacview_window}. The primary content mode is the
{\em appcast content mode}, where the output is an appcast of a
particular application as shown in Figure \ref{fig_umac_window}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.62\textwidth]{figures/fig_umac_window.png}
  \caption{The \vvar{uMAC} utility monitors appcasts from a terminal
    window. The user may switch between appcasting sources by
    navigating with a keyboard menu. The primary advantage or
    \vvar{uMAC} is the ability to run it on a remotely deployed
    vehicle with a network connection.}
  \label{fig_umac_window}
\end{figure}
\vspace{0.1in}

\noindent 
The content of this window should look very similar to the bottom pane of the 
\app{uMACView} window in Figure \ref{fig_umacview_window}. Two other content
modes are supported, the {\em nodes content mode}, and the {\em procs
content mode}. The former allows the user to select between different
nodes, i.e., vehicles. The latter allows selection between different
processes (MOOS applications) for the selected node.  These modes
correlate to the top two panes in the \app{uMACView} tool shown in
Figure \ref{fig_umacview_window}. A fourth, help, content mode is also
supported. Transitioning between modes usually is done by selecting
one of the choices presented, or popping back up a mode to allow a
higher level choice. This done with three reserved keyboard
keys, \var{{p, n, h}}, implementing the transitions shown in
Figure \ref{fig_umac_modes}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/fig_umac_modes.png}
  \caption{The \vvar{uMAC} utility monitors appcasts from a terminal window. The }
  \label{fig_umac_modes}
\end{figure}
\vspace{0.1in}

\noindent
An example rendering of \app{uMAC} in the {\em nodes content mode} is
shown on the left in Figure \ref{fig_umac_nodes_procs}. Each
discovered node is assigned a character ID in the left-most column for
selecting the node. The ID's are assigned as the nodes are discovered
from incoming \mvar{APPCAST} messages. 

\pskip

The title line at the top of the report shows, on the left, the name
of the \app{uMAC} application as it is known to the MOOSDB, and the
number of nodes discovered. When \app{uMAC} is launched it gives
itself a random suffix, such as \app{uMAC\_5991} in this example, to
allow multiple \app{uMAC} sessions connect with the same
MOOSDB. Recall the MOOSDB requires unique names across
applications. The righthand side of the title line shows the number of
iterations of the \app{uMAC} in parentheses, and the {\em refresh
mode} shown in reverse color.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figures/fig_umac_nodes_procs_modes.png}
  \caption{The \vvar{uMAC} utility monitors appcasts from a terminal
    window. The user may switch between appcasting sources by
    navigating with a keyboard menu. The primary advantage or
    \vvar{uMAC} is the ability to run it on a remotely deployed
    vehicle with a network connection.}
  \label{fig_umac_nodes_procs}
\end{figure}
\vspace{0.1in}

An example from the {\em procs content mode} is shown on the right in
Figure \ref{fig_umac_nodes_procs}. Each discovered process (MOOS
application) is assigned an ID in the left-most column for selecting
the process. The ID's are assigned as the apps are discovered from incoming
\mvar{APPCAST} messages. The title line at the top is nearly the same format
as in the {\em nodes} content mode, except that the selected node is
shown rather than the total nodes. The appcast counter just below the
title line indicates the total number of appcasts received over all
nodes, not just the selected node.

%=================================================================
\subsection{Refresh Modes}

The \app{uMAC} utility, like the \app{uMacView} utility, operates in
one of three {\em refresh modes}.  This mode is always shown on the
upper right in the title bar in reverse color.  The three modes are
the {\em streaming}, {\em events}, and {\em paused} modes. The desciption of 
these modes, given in Section
\ref{sec_umv_refresh_modes}, is also applicable to the operation
for the \app{uMAC} utility.

%=================================================================
\subsection{A Tip Regarding Process Monitoring and uMAC Sessions}

The \app{uProcessWatch} application is a utility for monitoring the
presence of applications connected to the MOOSDB. It is appcast
enabled, and will post a run warning when it detects the disappearance of a
prior noted process. If a \app{uMAC} is launched and then exited,
the \app{uProcessWatch} utility may interpret this as a problem and
post a run warning. The effect may be that real run warnings are then
later ignored. Tip: Add the following configuration line to \app{uProcessWatch}
to ignore the exit of a \app{uMAC} session: \pvar{nowatcth} \psvar{ = uMAC*}.

%=================================================================
\subsection{Publications and Subscriptions}

The sole subscription for \app{uMACView} is the appcast message in the MOOS
variable \mvar{APPCAST}. The sole publication is the appcast request, in the 
variable \mvar{APPCAST\_REQ}.


%=================================================================
\subsection{Configuration File Parameters}

There are no configuration file parameters specific to \app{uMAC}.

\subsubsection{Command Line Arguments and Options}

A few command line arguments are available. They are similar to most other
MOOS-IvP applications. These arguments are listed below, but may
be recalled anytime by typing on the command line:

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

\begin{packed_itemize}[2]
\item \var{--alias=&lt;ProcessName&gt;}: Launch with the given process name
  rather than uMACView.
\item \var{--example, -e}: Display example MOOS configuration block.
\item \var{--help, -h}: Display command line usage.
\item \var{--interface, -i}: Display MOOS publications and subscriptions.
\item \var{--version, -v}: Display release version information.
\end{packed_itemize}

\newpage
%=================================================================
\section{The uMACView Utility Integrated with pMarineViewer}
%=================================================================

The final uMAC tool is essentially \app{uMACView} embedded in
the \app{pMarineViewer} application as shown in
Figure \ref{fig_pmviewer}.  This is mostly just a convenience for
users already using \app{pMarineViewer}.  The appcasting mode may be
toggled with the \var{'a'} key to return to the traditional viewing
layout. The \var{AppCasting} pull-down menu offers the same set of
selections as \app{uMACView} with the exception of the hot keys used 
to switch between appcasting refresh modes since those keys were already 
used for other things in \app{pMarineViewer}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figures/fig_pmviewer.png}
  \caption{The \vvar{pMarineViewer} utility has an appcasting viewing
    capability very similar to \vvar{uMACView} embedded in the
    viewer. The rendering of the appcasting panes may be toggled
    on/off with the \vvar{'a'} key.}
  \label{fig_pmviewer}
\end{figure}
\vspace{0.1in}

In addition to toggling on/off the appcasting portion of the window,
the width of the set of appcasting panes may be made wider or thinner
using the \var{CTRL-ALT-ARROW} keys. By default the appcasting panes
consume 30\% of the width. The default height of the appcasting
(bottom) portion of the appcasting panes consume 75\% of the height of
the set of appcasting panes. These startup extents may be changed with
configuration the parameters:

\prevblue
\begin{verbatim}
  appcasting_width  = 25    // legal values [20, 25,... ,65, 70]
  appcasting_height = 80    // legal values [30, 35,..., 85, 90]
\end{verbatim}
\postverb

\noindent
The prevailing value of these parameters can always be discovered by
checking which radio button in the pull-down menu is presently selected.

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

\end{document}

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