<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{pMissionHash: A Lightweight App for Generating a Mission Hash}
\vspace{0.1in}
\labdate{January 28th 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\_pmhash} 
\labtoc{small}
\end{labcover}

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

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

The \app{pMissionHash} app was meant to run and generate a mission
hash when (a) \app{pMarineViewer} is {\em not} being run, and (b)
mission hash generation is still desired. A mission hash is normally
generated on the shoreside MOOS community in the form of a posting to
the variable \mvar{MISSION\_HASH}. Normally the hash is generated and
posted by \app{pMarineViewer}. However, in headless missions, where
there is no GUI and no \app{pMarineViewer}, a mission hash posting can
be generated instead with \app{pMissionHash}. Headless mission
configurations are common in automated missions, e.g., for validation,
automated competitions, or Monte Carlo testing.

\vspace{0.1in}
\noindent
Why are mission hashes important? The mission hash is created and
logged on the shoreside and shared to and logged on all the vehicles.
The presence of identical mission hashes is the definitive
confirmation that the individual log files are all part of the same
instance of a particular mission, either in simulation or in the
physical world. As of this writing, a mission hash is generated
either with \app{pMarineViewer} or \app{pMissionHash}. The command-line
tool \app{mhash\_gen} is also distributed with MOOS-IvP but is
not generally part of a mission.

%=================================================================
\section{Typical Application Topology}
%=================================================================

The \app{pMissionHash} app typically runs in the shoreside community,
in a headless mission, when \app{pMarineViewer} is not running.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/pmh_topology.png}
  \caption{{\bf Typical pMissionHash Topology:} A unique randomly
    created mission hash is generated by \app{pMissionHash} at startup,
    and shared to the MOOS communities of all vehicles. This unique
    has is thus logged in all log files for each vehicle and shoreside,
    thus allowing for confirmation that the log files were all part
    of the same mission.}
\label{fig_pmh_topology}
\end{figure}

%=====================================================================
\section{Configuration Parameters of pMissionHash}
%=====================================================================

The following parameters are defined for \app{pMissionHash}. If a
configuration block is not provided for \app{pMissionHash} in the
mission file, this is acceptable and no warning will be posted.

\vspace{0.15in}
\begin{listing}{Configuration parameters for \app{pMissionHash}}
\label{lst_pmh_params}
\renewcommand{\arraystretch}{1.1}

\begin{longtable}{rp{0.7\textwidth}} 

  \pvar{mission\_hash\_var}: &amp; The variable to which the mission hash is
  posted. The default is \mvar{MISSION\_HASH}. \\
  
  \pvar{mhash\_short\_var}: &amp; The variable to which the short version
  of the mission hash is posted. If this parameter is not specified,
  this information will not be published. This cannot be the same
  variable as the \pvar{mission\_hash\_var}. \\
  
\end{longtable}
\end{listing}

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

Listing \ref{lst_pmh_econfig} shows an example MOOS configuration
block produced from the following command line invocation:

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

\vspace{0.25in}
\begin{listing}{Example configuration of the \app{pMissionHash} application}
\label{lst_pmh_econfig}
\footnotesize
\begin{verbatim}
 1  =============================================================== 
 2  pMissionHash Example MOOS Configuration                         
 3  =============================================================== 
 4                                                                  
 5  ProcessConfig = pMissionHash                                    
 6  {                                                               
 7    AppTick   = 4                                                 
 8    CommsTick = 4                                                 
 9                                                                  
10    mission_hash_var = MISSION_HASH  // default                   
11    mhash_short_var  = MHASH_SHORT   // default is disabled                   
12                                                                  
13    // Note: If a config block is NOT provided in the mission     
14    //       file, NO config warning will be generated.           
15  }          
\end{verbatim}
\end{listing}
\normalsize
 
%=====================================================================
\subsection{Variables Published}
\label{sec_pmh_pubs}

The primary output of \app{pMissionHash} to the MOOSDB is the mission
hash message, or the short mission hash publication if this is enabled.

\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. Section
  \ref{sec_pmh_appcast}.

\item \mvar{MISSION\_HASH}: The full mission hash. This may be published
  to another variable name, depending on the user configuration.

\item \mvar{MHASH\_SHORT}: The short mission hash. This will only be
  published if enabled through configuration.
  
\end{packed_itemize}

\vspace{0.1in}
\noindent
For examples of a full and short mission hash, see Section
\ref{sec_pmh_appcast}.

\vspace{0.1in}
\noindent
Both variables are published immediately upon startup, and once every
30 seconds thereafter.

%=====================================================================
\subsection{Variables Subscriptions}
\label{sec_ufmh_subs}

The \app{pMissionHash} 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\_CLIENTS}: The list of running MOOS apps is monitored,
  checking for \app{pMarineViewer}, and posting a warning if present.
  Both apps should not be running and generating conflicting mission
  hash values.

\item \mvar{RESET\_MHASH}: A request to reset the mission hash.

\end{packed_itemize}

%=====================================================================
\section{Command Line Usage of pMissionHash}
%=====================================================================
\label{sec_pmh_cmdline}

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

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

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{uFldMessageHandler} tool}
\label{ufmh_usage}
\footnotesize
\begin{verbatim}
 1  =============================================================== 
 2  Usage: pMissionHash file.moos [OPTIONS]                         
 3  =============================================================== 
 4                                                                  
 5  SYNOPSIS:                                                       
 6  ------------------------------------                            
 7    The pMissionHash app is used for generating a MISSION_HASH    
 8    posting. Normally this is produced by pMarineViewer. In       
 9    headless mission not running pMarineViewer, this app can be   
10    used instead. They should not be both run unless the mission  
11    feature is configured to be disabled in pMarineViewer.        
12                                                                  
13  Options:                                                        
14    --alias=&lt;ProcessName&gt;                                      
15        Launch pMissionHash with the given process name           
16        rather than pMissionHash.                                 
17    --example, -e                                                 
18        Display example MOOS configuration block.                 
19    --help, -h                                                    
20        Display this help message.                                
21    --interface, -i                                               
22        Display MOOS publications and subscriptions.              
23    --version,-v                                                  
24        Display the release version of pMissionHash.              
25    --web,-w                                                      
26        Open browser to:                                          
27        https://oceanai.mit.edu/ivpman/apps/pMissionHash          
28                                                                  
29  Note: If argv[2] does not otherwise match a known option,       
30        then it will be interpreted as a run alias. This is       
31        to support pAntler launching conventions.        
\end{verbatim}
\end{listing}
\normalsize
 
%=====================================================================
\section{Terminal and AppCast Output}
\label{sec_pmh_appcast}

The \app{pMissionHash} application produces some useful information to
the terminal and identical content through appcasting. An example is
shown in Listing \ref{lst_pmh_appcast} below.  On line 2, the name of
the local community or vehicle name is listed on the left. On the
right, \var{"0/0(95)} indicates there are no configuration or run
warnings, and the current iteration of \app{pMissionHash} is 95.

On line 4, the full mission hash is shown and the variable it is posted
to, by default \mvar{MISSION\_HASH}. On line 6, the short version of the
the mission hash is shown, presumably do to the configuration of
\pvar{mhash\_short=MHASH}.

\vspace{0.2in}

\begin{listing}{Example appcast and terminal output of \app{pMissionHash}}
\label{lst_pmh_appcast}
\footnotesize
\begin{verbatim}
  1  =================================================================== 
  2  pMissionHash shoreside                                      0/0(95)
  3  ===================================================================
  4  MISSION_HASH=mhash=250127-1826S-LUSH-ARMY,utc=1738020397.43
  5  MHASH=LUSH-ARMY
\end{verbatim}
\end{listing}
\normalsize

\end{document}

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