<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{Help Topic: Scoping the MOOSDB}
\vspace{0.1in}
\labdate{Spring 2020}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labline
\end{labcover}

\wikidoc{file=Help.MIPScoping}
\wikidoc{auth=mikerb@mit.edu}

%====================================================================
\section*{Scoping the MOOSDB}
%====================================================================

A MOOS {\em scope} is a tool for examining the state of the
\app{MOOSDB}. The \app{MOOSDB} does not keep a history of prior values
for a given variable, but rather just the most recent value
posted. This means that the {\em state} of the \app{MOOSDB} may be
regarded as the set of current MOOS variables, their values, and who
made the last posting to the variable and when.  Scoping allows a view
into the current state (or even recent history) of the
\app{MOOSDB}. There are multiple tools for scoping the DB, each
providing conveniences of one kind or another.  Here we describe the
\app{uXMS}, \app{uMS}, and \app{pRealm} tools, the three favorites of
our own lab.

\pskip
\noindent 
More info on these two tools can be found at:

\vspace{0.05in}
\begin{packed_itemize}[0]
\item uXMS: \urlx{http://oceanai.mit.edu/ivpman/apps/uXMS}
\item pRealm: \urlx{http://oceanai.mit.edu/ivpman/apps/pRealm}
\end{packed_itemize}

\vspace{0.1in}
\noindent
You can also navigate to the above two web pages by launching the app with the
\var{--web} or \var{-w} option.

\vspace{0.1in}
\begin{consoleverb}
  $ uXMS --web
  $ pRealm -w
\end{consoleverb}
\vspace{0.1in}

\noindent
Most MOOS-IvP distributed apps support this command-line option.

%=======================================================================
\subsection*{Scoping the MOOSDB with uXMS}

Your goals in this part are:

\begin{packed_enumerate}[2]
\item Open a terminal window and launch the \app{MOOSDB} as done at
  the end of the previous exercise:

\vspace{0.05in}
\begin{consoleverb}
 $ MOOSDB
 ------------------- MOOSDB V10 -------------------
  Hosting  community                "#1"
  Name look up is                   off
  Asynchronous support is           on
  Connect to this server on port    9000
 --------------------------------------------------
 network performance data published on localhost:9020
 listen with "nc -u -lk 9020"
\end{consoleverb}
\vspace{0.05in}

\noindent
The \app{MOOSDB} is normally launched with a mission file specifying the
\pvar{ServerHost} and \pvar{ServerPort} parameters. When launched from
the command line as above with no command line arguments, these two
parameters default to \var{localhost} and \var{9000}.

\vspace{0.1in}

\item Open a second terminal window and launch \app{uXMS}, passing it
  the \var{--all} command line switch. Just hit \var{ENTER} when prompted
for the IP address and Port number, accepting the defaults of \var{localhost}
and \var{9000}. It should look something like:

\vspace{0.05in}
\begin{consoleverb}
 $ uXMS --all 
 Enter IP address:  [localhost] 
 Enter Port number: [9000] 
 ***************************************************
 *  uXMS_632 starting ...
 ***************************************************
 uXMS_632 is Running:
  |-Baseline AppTick   @ 5.0 Hz
  |--Comms is Full Duplex and Asynchronous
  -Iterate Mode 0 :
    |-Regular iterate and message delivery at 5 Hz
\end{consoleverb}
\vspace{0.05in}

After the above initial standard MOOSApp output, you should see a 
sequence of \app{uXMS} reports similar to:

\vspace{0.05in}
\begin{consoleverb}
==============================================================
uXMS_443                                               0/0(31)
==============================================================
VarName            (S)  (T)  (C)  VarValue (SCOPING:EVENTS)
-----------------  ---  ---  ---  -------------------------
DB_CLIENTS                        "uXMS_443,"
DB_EVENT                          "connected=uXMS_443"
DB_QOS                            "uXMS_443=0.448942:0.573874:0.364065:0.490189,"
DB_TIME                           1424028179.877422
DB_UPTIME                         16.741557
UXMS_443_ITER_GAP                 1.019045
UXMS_443_ITER_LEN                 0.00024
  -- displaying all variables --
\end{consoleverb}
\vspace{0.05in}

\noindent
Notice the number in parentheses on the second line is
incrementing. This indicates that the report has been refreshed to
your terminal. If you launched as above, the scope should come up in a
mode that refreshes the report any time a scoped variable changes
values. In this case, the \app{MOOSDB} is updating \mvar{DB\_TIME} and
\mvar{DB\_UPTIME} about once per second.
By default, \app{uXMS} only scopes on the variables named on the
command line. In the above case, the \var{--all} option was used to
tell \app{uXMS} to scope on all variables known to the \app{MOOSDB}.

\end{packed_enumerate}

\pskip
\noindent
The five variables shown beginning with \var{DB\_} are all published
by the \app{MOOSDB}. The user may choose whether or not to show the
variable (S)ource, (T)ime of post, or (C)ommunity from where the post
was made. A key feature of \app{uXMS} vs. \app{uMS} is the ability to
specify on the command-line exactly which subset of variables to
scope, possibly with color-coding. This is helpful when there are
hundreds of variables in the DB.


%=====================================================================
\subsection*{More Suggested Tinkering with uXMS}

\pskip
\noindent
Try a few other things:

\begin{packed_enumerate}[2]
 \item Hit the \var{'h'} key to see some keyboard interaction options
   that are available anytime the scope is running. Hit \var{'h'}
   again any time to return to the previous mode.

 \item Hit the space-bar to pause the stream of reports. This is useful
   if numbers are changing rapidly and you just need to take a close
   look at something.  Return to the previous mode by hitting
   \var{'e'}.

 \item Hit the \var{'s'} key to expand the \var{(S)ource} column. This
   column tells you which app made the last posting. Try the same for
   the \var{(T)ime} and \var{(C)ommunity} columns.

\item The whole purpose of a scope is to give you the key information
  you're looking for, without needing to sift through a lot of
  unwanted information, with as little effort as possible.  In this
  step we'll pretend to be interested in focusing our attention on the
  \mvar{DB\_UPTIME} variable. Try launching \app{uXMS} with an
  additional command line argument:

\begin{consoleverb}
 $ uXMS --all --colormap=DB_UPTIME,blue
\end{consoleverb}

This may seem unnecessary when there are only three variables, but in
real applications there may be hundreds of variables. In fact, the
variable you're looking for may have scrolled off the window! 

\item A similar way to focus on a single variable is to only scope on the one
variable we're looking for:

\begin{consoleverb}
 $ uXMS DB_UPTIME
\end{consoleverb}

\item \app{uXMS} only shows you the current snapshot of the variables
  in the \app{MOOSDB}. What if you would like to see how a variable is
  changing? In our case, we know how the \mvar{DB\_UPTIME} variable is
  changing, but for the sake of showing this feature, try:

\begin{consoleverb}
 $ uXMS --history=DB_UPTIME
\end{consoleverb}

\end{packed_enumerate}



%=========================================================================
\subsection*{Scoping with uMS}

The \app{uMS} scope is a graphical MOOS scope, often preferred by
those inclined to like GUIs vs. command line tools. It has some other
advantages over \app{uXMS} as well.

\pskip

\noindent
Your goals in this part are:

\begin{packed_enumerate}[2]
\item If you don't still have a \app{MOOSDB} running, open a terminal
  window and launch the \app{MOOSDB} as done previously:

\begin{consoleverb}
 $ MOOSDB
\end{consoleverb}

\item Open a second terminal window and launch \app{uMS}, passing it
  the same mission file as an argument:

\begin{consoleverb}
 $ uMS 
\end{consoleverb}

\noindent
You should see a window open and, after clicking on the \var{Connect}
button, you should see something similar to:

\end{packed_enumerate}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figs_help/ums.png}
  \caption{The uMS MOOS Scope}
\label{fig_ums}
\end{figure}


%--------------------------------------------------------------------------
\subsection*{Pros/Cons of uXMS vs uMS}

The choice of \app{uXMS} vs \app{uMS} is often just a matter of
taste. A couple of differences are noteworthy however.

\begin{packed_itemize}[2]

\item \app{uMS} allows for connections to multiple MOOSDBs, on perhaps
  multiple vehicles, simultaneously. The user may select the vehicle
  with the tab at the top of the screen.

\item \app{uXMS} allows the user to scope on as few as one single
  variable, or to name the variable scope list explicitly. \app{uMS} scopes
  on all variables all the time, with a few mechanisms for reducing
  the scope list based on process name.

\item \app{uXMS} may be a better choice if one is scoping on a remote
  \app{MOOSDB}, perhaps on a robot with a poor connection. It is a
  low-bandwidth client compared to \app{uMS}. If running on a remote
  terminal, its bandwidth back to the user is zero in the paused mode.

\item \app{uXMS} has provisions for at least limited scoping on a variable
  history.

\item \app{uXMS} will display a variable's "auxiliary source"
  information. This is a secondary field associated with each posting
  describing the source of the posting. This is key when using the
  IvPHelm. Variables posted by helm behaviors will have a source of
  \app{pHelmIvP} and an auxiliary source showing the behavior
  responsible for the posting.

\end{packed_itemize}


%--------------------------------------------------------------------------
\subsection*{Scoping with pRealm}

Realmcasting is a feature first introduced in 2021. It complements Appcasting,
which is the default set of windows open to the left of the GUI when running
\app{pMarineViewer} in say the Alpha mission. If you are running a mission with
\app{pMarineViewer}, it may be the only scoping tool you need. You can scope
on selected vehicle (MOOS community), and selected app, as shown in Figure
\ref{fig_realmcasting}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.97\textwidth]{figs_help/realmcasting.png}
  \caption{The RealmCasting interface in \app{pMarineViewer} is the
    lefthand side of the GUI comprising the three panels
    shown. Toggling between AppCasting and RealmCasting is done with
    the \var{'a'} key.}
\label{fig_realmcasting}
\end{figure}

\vspace{0.1in}
\noindent
The realmcasting pane on the lower-left is the primary output. It is
split into two parts. On the top is a scope on all variables
subscribed for by the selected application. The bottom half is a scope
on all variables published by the application.

\vspace{0.1in}
\noindent
If you are running \app{pMarineViewer} and do not see any content in
this window, it is most likely due to the omission of running
\app{pRealm} in both the shoreside and vehicle communities. It is
enabled by default in the Alpha mission. Most other example missions
also have realmcasting enabled.


\end{document}


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