<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{uMayFinish: A command-line MOOS Tool for Waiting for Mission Completion}
\vspace{0.1in}
\labdate{January 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labsrc{project-pavlab/appdocs/app\_umayfinish} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UMayFinish}
\wikidoc{auth=mikerb@mit.edu}

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

\app{uMayFinish} is typically a terminal-launched MOOS app launched
within a shell script, e.g., \cmd{xlaunch.sh}. It will connect to a MOOS
community and monitor for a completion event or timeout based on
\mvar{DB\_UPTIME}. When completed, it simply exits.  Presumably to
allow the executing script to proceed to a next phase. For example a
script could proceed to bring down the MOOS community for the mission
it was monitoring.
  

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.55\textwidth]{figures/umayfinish_topology.png}
  \caption{{\bf Typical uMayFinish Topology:} The \app{uMayFinish} app is
    typically not part of the initial MOOS community of either the shoreside
    or vehicles. Typically, shortly after everything is launched, the
    \app{uMayFinish} app is launched and connects to the shoreside MOOSDB.
    It waits for a either a time limit to be reached, or a specified MOOS
    variable to have a specified value. Then the app disconnects. The
    disconnection may be followed by an action to shut down all MOOS
    communities.}
\label{fig_umf_topology}
\end{figure}


\vspace{0.1in}
\noindent
Consider the following pseudo-code snippet:

\vspace{0.1in}
\begin{consoleverb}
pAntler mission.moos &amp;
uMayFinish --max_time=600 mission.moos
ktm
\end{consoleverb}
\vspace{0.1in}

\noindent
In the first line, the mission is launched. It is launched in the
background, so control proceeds immediately to the next line. Then
\app{uMayFinish} launches and connects to the same MOOSDB since it is
invoked with the same mission file. It is {\em not} launched in the
background, so control will stop here until the \app{uMayFinish}
completes.  After 10 minutes (600 seconds), it will disconnect from
the MOOSDB, and exit.  Control passes to the next line which invokes
\cmd{ktm} (kill-the-moos), to bring down the entire mission.

\vspace{0.1in}
\noindent
Something similar is used in \cmd{xlaunch.sh}, which is meant to be a
general way for auto-launching missions with provisions for
time-conditioned or event-conditioned exiting. In the above snippet,
the maximum time was passed on the command line. The maximum time can
also be specified in the \app{uMayFinish} configuration file in the
mission file, as described in Section \ref{sec_umf_params}.



%===================================================================
\section{Configuration Parameters for uMayFinish}
%===================================================================
\label{sec_umf_params}

The \app{uMayFinish} application may be configured with a configuration
block within a MOOS mission file, typically with a \var{.moos} file
suffix.  The following parameters are defined for \app{uMayFinish}.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for uMayFinish}
\label{lst_umf_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 

  \pvar{finish\_var}: &amp; A MOOS variable. \\

  \pvar{finish\_val}: &amp; A prescribed value for the MOOS variable. \\

  \pvar{max\_db\_uptime}: &amp; The number of seconds, found in the MOOSDB
  published variable \var{DB\_UPTIME}, after which this app will exit.
\end{longtable}
\end{listing}

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

An example MOOS configuration block may be obtained from the command line
with the following:

\begin{consoleverb}
 $ uMayFinish --example or -e 
\end{consoleverb}

\vspace{0.25in}
\begin{listing}{Example configuration of the uMayFinish application}
\label{lst_umf_econfig}
\footnotesize
\begin{verbatim}
 1  =============================================================== 
 2  uMayFinish Example MOOS Configuration                           
 3  =============================================================== 
 4                                                                  
 5  ProcessConfig = uMayFinish                                      
 6  {                                                               
 7    AppTick   = 4                                                 
 8    CommsTick = 4                                                 
 9                                                                  
10    finish_var = MISSION_EVALUATED  // Default                    
11    finish_val = true               // Default                    
12                                                                  
13    max_db_uptime = 3600            // Default is -1 (off)        
14  }                                                          
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Publications and Subscriptions for uMayFinish}
%===================================================================
\label{sec_umf_interface}

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

\begin{consoleverb}
 $ uMayFinish --interface or -i
\end{consoleverb}

%===================================================================
\subsection{Variables Published by uMayFinish}
\label{sec_umf_pubs}

\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. 
  
\end{packed_itemize}

%===================================================================
\subsection{Variables Subscribed for by uMayFinish}
\label{sec_umf_subs}

The \app{uMayFinish} application subscribes to the following MOOS
variables:

\begin{packed_itemize}[2]
\item \mvar{APPCAST\_REQ}: A request to generate and post a new
  apppcast report, with reporting criteria, and expiration. 
 
\item \mvar{DB\_UPTIME}: The number of seconds since the MOOSDB has
  been launched. If a mission has been auto-started shortly after
  launch (e.g., using \app{pAutoPoke}), then this value is a good
  approximation for measuring how long the mission has been running.
  Note, this subscription will only be made if the configuration
  parameter \pvar{max\_db\_uptime} is set. This param is set to \var{-1}
  by default, meaning there is no maximum time.

\end{packed_itemize}

\vspace{0.1in}
\noindent
Node that \app{uMayFinish} will also subscribe for the variable named in
the configuration parameter \pvar{finish\_var}, if provided. 

%===================================================================
\subsection{Command Line Usage of uMayFinish}
\label{sec_umf_cmdline}

The \app{uMayFinish} application is typically launched with pAntler, along
with a group of other modules. However, it may be launched
separately from the command line. The command line options may be
shown by typing:

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

\vspace{0.1in}
\begin{listing}{Command line usage for the uMayFinish tool}
\label{umf_usage}
\footnotesize
\begin{verbatim}
  1  Usage: uMayFinish file.moos [OPTIONS]             
  2                                                         
  3  Options:                                               
  4    --alias=&lt;ProcessName&gt;                                
  5        Launch uMayFinish with the given process    
  6        name rather than uMayFinish.                
  7    --example, -e                                        
  8        Display example MOOS configuration block         
  9    --help, -h                                           
 10        Display this help message.                       
 14    --interface, -i                                               
 15        Display MOOS publications and subscriptions.      
 16    --version,-v                                         
 17        Display the release version of uMayFinish.  
 18    --max_time=1200                                               
 19        Maximum DB_UPTIME before exiting.  
 20    --web,-w                                                      
 21        Open browser to: https://oceanai.mit.edu/ivpman/apps/uMayFinish
 22 
 23  Note: If argv[2] is not of one of the above formats 
 24        this will be interpreted as a run alias. This 
 25        is to support pAntler launching conventions.  
\end{verbatim}
\end{listing}
\normalsize

%===================================================================
\section{Terminal and AppCast Output}

Some useful information is published by \app{uMayFinish} to the
terminal on every iteration. An example is shown in Listing
\ref{lst_umf_appcast} below. This application is also appcast enabled,
meaning its reports are published to the MOOSDB and viewable from any
uMAC application or \app{pMarineViewer}. The counter on the end of
line 2 is incremented on each iteration of \app{uMayFinish}, and also
serves as a heartbeat indicator. The \var{"0/0"} also on line 2
indicates there are no configuration or run warnings detected.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{uMayFinish}}
\label{lst_umf_appcast}

\footnotesize
\begin{verbatim}
 1  ==============================================================
 2  uMayFinish shoreside                                   0/0(67)
 3  ==============================================================
 4  Config: 
 5    Finish Var: MISSION_EVALUATED
 6    Finish Val: true
 7    Max DBTime: -1
 8  
 9  State:
10    DB_UPTIME: n/a
11    MISSION_EVALUATED: 
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
Lines 4-7 of the output show the user configuration. Lines 10 and 11
show the current state of the app. Note the \mvar{DB\_UPTIME}
output on line 10 indicates \var{"n/a"} since no max time was set for
this launch (line 7). 

\vspace{0.1in}
\noindent
When the exit criteria is met, the appcast output may change as below.
Note the only change is on line 11, where the empty value for the
current value of \mvar{MISSION\_EVALUATED} in the listing above, is
replaced with \mvar{MISSION\_EVALUATED: true} in the listing below.
Since this satisfies the exit criteria, this will be the very last
appcasting output to either the terminal or seen in
\app{pMarineViewer}. 

\vspace{0.1in}
\begin{listing}{Example output as \app{uMayFinish} finishes.}
\label{lst_umf_appcast2}

\footnotesize
\begin{verbatim}
 1  ==============================================================
 2  uMayFinish shoreside                                  0/0(341)
 3  ==============================================================
 4  Config: 
 5    Finish Var: MISSION_EVALUATED
 6    Finish Val: true
 7    Max DBTime: -1
 8
 9  State:
10    DB_UPTIME: n/a
11    MISSION_EVALUATED: true
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
When \app{uMayFinishApp} exits due to satisfying the finish variable
criteria, it will return with a value of \var{0}. When
\app{uMayFinishApp} exits due to exceeding a maximum time limit, the
exit value is \var{1} instead.

\end{document}



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