<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{Introduction to AppCasting}
\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.AppCastingIntro}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_appcast_intro}
\index{AppCasting}

AppCasting provides an {\em optional} and powerful new way of delivering
application status output beyond the traditional means of writing to
standard I/O in a terminal window. It is motivated by a few common
recurring observations:

\begin{packed_itemize}[2]

\item The biggest headache of users new to MOOS (e.g., students in MIT
  2.680) was the derailment of a mission due to an unnoticed
  configuration or runtime error.

\item Debugging typically involves re-launching with app terminal
  windows open and analyzing expected vs. observed output.

\item When deploying multiple simulated vehicles, each with multiple MOOS
  apps, the number of open terminal windows may be unmanageable.

\item When deploying a vehicle in the field, one cannot ssh in and see
  any application terminal output at all.

\item Since terminal output is rarely viewable for the above practical
  reasons, apps are rarely designed with much thought put into their
  status output.
\end{packed_itemize}

\noindent
AppCasting is designed to make it easier to see application terminal
output. This includes app-specific status messages, configuration and
runtime warnings, and notable events. It is designed to allow appcast
viewing tools to render this information and alerts on a single screen
across multiple vehicles, each with several running apps, whether in
simulation or the field. Having this form of information easier at
hand, application developers will find it more rewarding to add
thoughtful status reports to their application. Most applications in
the MOOS-IvP tree have been converted to support appcasting. It's
worth repeating that this is an opt-in feature of MOOS. All existing
MOOS apps work just fine without appcasting. Appcasting apps and
non-appcasting apps work side-by-side seamlessly.

%=================================================================
\section{MOOS Applications and Terminal Output}
%=================================================================

A MOOS application typically interacts with the world primarily through its
subscriptions and publications to the MOOSDB. It may also interact through
a terminal interface by generating status or debugging output, or in some
rare cases, accepting terminal input. 

\vspace{0.1in}

\begin{figure}[H]
    \centering 
    \includegraphics[width=0.54\textwidth]{figures/moos_noappcast.png}
  \caption{A typical MOOS application interacts with the world by
    publishing and receiving mail through the MOOSDB and by writing
    status messages to a terminal window, if one is open.}
\label{fig_moos_noappcast}
\end{figure}
\vspace{0.15in}

%\noindent
%When MOOS is run on a deployed vehicle or robot, a terminal window is
%virtually never open since the vehicle doesn't have a computer monitor
%connected to it. When \var{pAntler} is used to launch this kind of 
%MOOS community, terminal output for each application is purposefully 
%ignored, usually by re-directing it to a null device. 


Even MOOS GUI applications have the option of opening a terminal
interface in addition to the GUI. The terminal interface option is
invoked by setting \var{NewConsole=true} for the given app in the
\app{ANTLER} process configuration block in the mission file, or
simply by just launching the app manually from the command line.  With
AppCasting, an application still generates terminal output, but does
so by creating a report, in the form of an appcast data structure. The
data structure may be converted to a list of strings, sent to the
terminal, or a single long string, published to the MOOSDB.

\vspace{0.05in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.5\textwidth]{figures/moos_withappcast.png}
  \caption{An appcasting MOOS app produces terminal by repeatedly
    generating and sending an {\em appcast} to the terminal. The
    appcast is a also serialized and published to the MOOSDB for other
    MOOS applications to consume.}
\label{fig_moos_withappcast}
\end{figure}

\vspace{0.05in}

By sending the appcast to the MOOSDB this makes a few things
possible. First, even if the application was launched long ago without
a terminal, it is now possible to launch a separate MOOS application
(an appcast viewer tool discussed in Section
\ref{sec_appcast_viewers}) to start looking at the status
output. Second, the same appcast data structure may now also be
bridged to a separate off-board MOOS community, using something like
\app{pShare}, so remote users may be alerted to or debug
problems. Third, the appcast data structure may contain configuration
and run-time {\em alerts} to bring issues to the attention of
operators quickly. Fourth, the appcast structure may be logged like
any other MOOS variable, making it possible to review terminal output
during the post-mission analysis phase.

%=================================================================
\section{Viewing AppCasts and Navigating AppCast Collections}
%=================================================================

A primary motivation for appcasting is the ability to view appcasts over 
several applications with a single viewer:

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.5\textwidth]{figures/acview_one.png}
  \caption{An AppCast Viewer is a separate MOOS application for gathering
    and navigating through appcasts from several other MOOS applications.}
  \label{fig_acview_one}
\end{figure}
\vspace{0.1in}

In addition to being able to see application output from a single
window, it is possible to view application output for a particular app
regardless of how that application was launched. In comparison, if the
status output were only viewable from a terminal window, that app
would have had to be launched with a terminal window from the
outset. Furthermore, when the AppCast Viewer has a terminal interface,
a user may log onto a remotely deployed vehicle and launch the viewer
and see application output that would not be viewable otherwise since
applications on fielded platforms are never run with terminal windows
open.

\pskip

An AppCast Viewer may also handle appcasts from several vehicles as
conveyed in Figure \ref{fig_acview_two}. The viewer lets the user
navigate between different vehicles and appcasts within a vehicle. The
interface is discussed in a later section, but the idea is shown on the
right in Figure \ref{fig_umacview}.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/acview_two.png}
  \caption{An AppCast Viewer may also be used for sorting and
    navigating through appcasts from several applications {\em over
      several vehicles} or nodes. The appcasts may be bridged from one
    community to a single shoreside community using a tool such as
    \vvar{pShare}.}
\label{fig_acview_two}
\end{figure}
\vspace{0.15in}

The above arrangement assumes that appcasts are sent from each MOOS
community to a single {\em shoreside} MOOS community, to which the
appcast viewer is connected. This may be done with the \app{pShare}
utility. The uField Toolbox also provides a set of MOOS utilities to
facilitate this kind of arrangement.

%=================================================================
\section{The AppCast Data Structure}
%=================================================================

An example appcast is shown in Figure \ref{fig_acast_report}. It has four
distinct parts: 

\begin{packed_itemize}[2]

\item {\bf config warnings:} Configuration warnings are typically
  generated during the application's OnStartUp() routine.

\item {\bf run warnings:} Run warnings may be generated any time during
  the execution of the application. 

\item {\bf general messages:} A list of app developer-formatted
  strings having whatever the application developer thought would best
  constitute a succinct meaningful status report.

\item {\bf events:} A set of time-stamped events. Exactly what
  constitutes an event is determined by the application developer.

\end{packed_itemize}

\vspace{0.1in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/acast_report.png}
  \caption{An appcast consists of four main parts: (1) configuration
    warnings, (2) run-time warnings, (3) general status report
    messages, and (4) run-time events. The bar at the top of the
    figure is rendered in red due to the presence of a run-time
    warning. The \vvar{"1/1"} on this line indicates one configuration
    warning and one run-time warning.  The \vvar{"(150)"} on this line
    indicates that it is iteration \#150 for this application. This
    image is a screen shot take from the \vvar{uMACView} utility
    described later.}
\label{fig_acast_report}
\end{figure}

\vspace{0.1in}

For any given appcast, all fields are optional. Indeed, often an
appcast will be devoid of any configuration or run warnings. It is
also not uncommon for an application not to have a notion of an event.

\pskip

For reasons explained later, an appcast instance is typically created
once upon application startup. The block of general messages is
cleared and overwritten each time an appcast is generated. Run
warnings and events are added any time during the application
operation, but are limited in amount (first-in-first-out/FIFO). This
is done to ensure against unbounded growth of the appcast message, and
relieve the app developer from addressing the logic of bounded message
growth. Configuration warnings are unbounded however since they are only
generated at startup time and are typically bounded from above by the
number of application configuration lines.

%=================================================================
\section{A Preview of AppCast Viewing Utilities}
%=================================================================
\label{sec_appcast_viewers}

An appcast viewer is primarily a utility for viewing appcasts,
rendering an appcast to look something like that shown in Figure
\ref{fig_acast_report}.  It also does a couple other important
things. First, it provides a mechanism to allow the user to navigate
between incoming appcasts from multiple vehicles, each with multiple
applications. Second, it implements, under the hood, a protocol
between the appcast viewer utility and the applications, to ensure
on-demand appcasting.

\pskip

The \app{uMAC} utility shown on the left in Figure \ref{fig_umacview}
is run from a terminal window. The \app{uMACView} utility shown on the 
right is a GUI with a bit more capable interface, allowing the user
to see all vehicles, all apps for a chosen vehicle, and the appcast 
for a single chosen application. The advantage of the \app{uMAC}
utility however is that it may be launched remotely after logging in
to a vehicle that may otherwise be unresponsive and in need of some
debugging.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/figure_06a.png}
  \caption{Two appcast viewer utilities: On the left is the
    terminal-based \aapp{uMAC} utility. On the right is the GUI-based
    \vvar{uMACView} utility. Both provide access to the same information. 
    While the latter has a bit nicer user interface, the former may be 
    run remotely while ssh'ing into a fielded vehicle.}
\label{fig_umacview}
\end{figure}

While the \app{uMAC} and \app{uMACView} utilities are completely stand-alone
and do not assume the use of any other tool, a third option exists for users
of the \app{pMarineViewer} tool. This tool has been augmented to support an 
integrated \app{uMACView} style interface into the same single window as
shown in Figure \ref{fig_umac_pmv}. The appcasting interface may be toggled
on and off by simply hitting the \var{'a'} key. The user may also specify
the mode upon startup.


\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/figure_06b.png}
  \caption{The \aapp{pMarineViewer} application has been augmented to support
    appcast viewing in a separate window pane. The interface is nearly identical
    to that of the \aapp{uMACView} application. The integration is for better
    convenience to existing \aapp{pMarineViewer} users. The appcasting information
    may be toggled on and off with the \vvar{'a'} key.}
\label{fig_umac_pmv}
\end{figure}

\vspace{0.1in}


\end{document}

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