<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{uTermCommand: Poking the MOOSDB with Pre-Set Values}
\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\_utermcommand} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UTermCommand}
\wikidoc{bugz=uTermCommand}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_util_utermcommand}
\index{uTermCommand}
\index{Command and Control!uTermCommand}
\index{uTermCommand!Command and Control}

The \app{uTermCommand} application is a terminal based tool for poking
the MOOS database with pre-defined variable-value pairs. This can be
used for command and control for example by setting variables in the
MOOSDB that affect the behavior conditions running in the helm. There 
are a few other ways of doing this:

\begin{packed_itemize}[2]
\item {\em pMarineViewer}: The action pull-down menu and on-screen
  buttons may be used for posting the MOOSDB.
\item {\em uPokeDB}: A command-line tool for poking the MOOSDB.  This
  may be used in conjunction with shell aliases or shell scripts for
  further convenience.
\item {\em iRemote}: The custom keys feature may be used to bind
  variable-value pairs to the numeric keys. The primary drawback is
  the limitation to ten mappings.
\end{packed_itemize}

%=================================================================
\section{Configuration Parameters for uTermCommand}
%=================================================================
\label{sec_utc_config}
\index{uTermCommand!Configuration Parameters}
\index{Configuration Parameters!uTermCommand}

The variable-value mappings are set in the \app{uTermCommand}
configuration block of the MOOS file. Each mapping requires one line
of the form:

\pivar{cmd}

\prevblue
\begin{verbatim}
  cmd = cue --&gt; variable --&gt; value
\end{verbatim}
\postverb

\noindent
The {\em cue} and {\em variable} fields are case sensitive, and the
{\em value} field may also be case sensitive depending on how the
subscribing MOOS process(es) handle the value. An example
configuration is given in Listing \ref{lst_utc_econfig}.

\vspace{0.1in}
\begin{listing}{An example uTermCommand configuration block}
\label{lst_utc_econfig}
\footnotesize
\begin{verbatim}
  1  //------------------------------------------------------------
  2  // uTermCommand configuration block
  4  
  5  ProcessConfig = uTermCommand
  6  {
  7    cmd = override_true  --&gt;  MOOS_MANUAL_OVERRIDE --&gt; true 
  8    cmd = override_false --&gt;  MOOS_MANUAL_OVERRIDE --&gt; false
  9    cmd = deploy_true    --&gt;  DEPLOY       --&gt; true 
 10    cmd = deploy_false   --&gt;  DEPLOY       --&gt; false
 11    cmd = return_true    --&gt;  RETURN       --&gt; true 
 12    cmd = return_false   --&gt;  RETURN       --&gt; false
 13  }
\end{verbatim}
\end{listing}
\normalsize

Recall the type of a MOOS variable is either a string, double or
binary data.  If a variable has yet to be posted to the MOOSDB, it
accepts whatever type is first written, otherwise postings of the
wrong type are ignored. If quotes surround the entry in the value
field, it is interpreted to be a string. If not, the value is
inspected as to whether it represents a numerical value. If so, it is
posted as a double. For example \var{true} and \var{"true"} are the
same type (no such thing as a Boolean type), \var{25} is a double and
\var{"25"} is a string.

%=================================================================
\subsection{Run Time Console Interaction}
%=================================================================

When \app{uTermCommand} is launched, a separate thread accepts user input at
the console window. When first launched the entire list of cues and
the associated variable-value pairs are listed. Listing
\ref{lst_utc_console_a} shows what the console output would look like
given the configuration parameters of Listing \ref{lst_utc_econfig}. This
configuration block is in the Alpha example mission. You can launch that
mission and then launch \app{uTermCommand}: 

\vspace{0.15in}
\begin{consoleverb}
  $ cd moos-ivp/ivp/missions/s1_alpha
  $ ./launch.sh
\end{consoleverb}
\vspace{0.15in}

\noindent
Then in a separate terminal:

\vspace{0.15in}
\begin{consoleverb}
  $ cd moos-ivp/ivp/missions/s1_alpha
  $ uTermCommand alpha.moos
\end{consoleverb}
\vspace{0.15in}

\noindent
The output in the terminal window should look similar to Listing
\ref{lst_utc_console_a}. Note that even though quotes were not
necessary in the configuration file to clarify that \var{true} was to
be posted as a string, the quotes are always placed around string
values in the terminal output.

\vspace{0.1in}
\begin{listing}{Console output at start-up}
\label{lst_utc_console_a}
\footnotesize
\begin{verbatim}
  1    Cue                     VarName                         VarValue
  2    -----------             ---------------                 --------------
  3    override_true           MOOS_MANUAL_OVERRIDE            "true"
  4    override_false          MOOS_MANUAL_OVERRIDE            "false"
  5    deploy_true             DEPLOY                          "true"
  6    deploy_false            DEPLOY                          "false"
  7    return_true             RETURN                          "true"
  8    return_false            RETURN                          "false"
  9
 10  &gt; 
\end{verbatim}
\end{listing}
\normalsize

\noindent
In the Alpha mission, the \var{DEPLOY} button in the lower right corner 
of \app{pMarineViewer} is configured to post:

\prevgreen
\begin{verbatim}
  MOOS_MANUAL_OVERRIDE = false
  DEPLOY = true
\end{verbatim}
\postverb

\noindent
This will be handled instead by \app{uTermCommand} in our simple
example.  A prompt is shown on the last line where user key strokes
will be displayed.  As the user types characters, the list of choices
is narrowed based on matches to the cue. After typing a single 'o'
character, only the \var{override\_true} and \var{override\_false}
cues match and the list of choices shown are reduced as shown in
Listing \ref{utc_console_b}. At this point, hitting the TAB key will
complete the input field out to \var{override\_}, much like
tab-completion works at a Linux shell prompt.

\vspace{0.1in}
\begin{listing}{Console output after typing a single character 'r'}
\label{utc_console_b}
\footnotesize
\begin{verbatim}
 1     Cue                     VarName                         VarValue
 2     -----------             ---------------                 --------------
 3     override_true           MOOS_MANUAL_OVERRIDE            "true"
 4     override_false          MOOS_MANUAL_OVERRIDE            "false"
 5
 6   &gt; o
\end{verbatim}
\end{listing}
\normalsize

\noindent
When the user has typed out a valid cue that matches a single entry, only
the one line is displayed, with the tag \var{&lt;-- SELECT} at the end of the
line, as shown in Listing \ref{utc_console_c}. 

\vspace{0.1in}
\begin{listing}{Console output when a single command is identified}
\label{utc_console_c}
\footnotesize
\begin{verbatim}
 1     Cue                     VarName                        VarValue
 2     -----------             ---------------                --------------
 3     override_false          MOOS_MANUAL_OVERRIDE           "false" &lt;-- SELECT
 4   
 5   &gt; override_false
\end{verbatim}
\end{listing}
\normalsize

\noindent
At this point hitting the ENTER key will execute the posting of that
variable-value pair to the MOOSDB, and the console output will return
to its original start-up output. A local history is augmented after
each entry is made, and the up- and down-arrow keys can be used to
select and re-execute postings on subsequent iterations. To finish the
launch in the Alpha mission, use \app{uTermCommand} to post
\msvar{DEPLOY=true}.

%=================================================================
\section{Connecting uTermCommand to the MOOSDB Under an Alias}
%=================================================================

A convention of MOOS is that each application connected to the MOOSDB
must register with a unique name. Typically the name used by a process
to register with the MOOSDB is the process name, e.g.,
\app{uTermCommand}. One may want to run multiple instances of
\app{uTermCommand} all connected to the same MOOSDB. To support this,
an optional command line argument may be provided when launching
\app{uTermCommand}:

\begin{consoleverb}
 $ uTermCommand file.moos --alias=uTermCommandAlpha
\end{consoleverb}

\noindent
The command line argument may also be invoked from within \app{pAntler}
to launch multiple \app{uTermCommand} instances simultaneously. The 
configuration block in the mission file needs to have the same 
name as the launch alias.

%=================================================================
\section{Publications and Subscriptions for uTermCommand}
%=================================================================
\index{uTermCommand!Publications and Subscriptions}
\index{Publications and Subscriptions!uTermCommand}

The only variables published by \app{uTermCommand} are those configured
and selected by the user at run-time, and \app{uTermCommand} does not
subscribe for any variables.


\end{document}

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