<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{pMissionEval: Evaluating User-Defined Mission Success}
\vspace{0.1in}
\labdate{September 2020}
\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.PMissionEval}
\wikidoc{bugz=pMissionEval}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_pmeval}
\index{uMemWatch}

The \app{pMissionEval} application enables the mission planner to
automate the evaluation of mission into a single pass/fail assessment.
The app configuration is comprised of three components:

\begin{packed_itemize}
\item When to perform the evaluation
\item What is the criteria for success or failure
\item What information will be published upon evaluation
\end{packed_itemize}


%=================================================================
\subsection{An Overview of the Implementation}

Measuring the memory usage of another app, from within
\app{uMemWatch}, is achieved through a system call, with the knowledge
of the system process ID (PID) of the application to be measured.


%=================================================================
\subsection{Flag Postings}

%=================================================================
\subsection{Flag Postings}

The \app{pMissionEval} app can configured to post any number of flags
upon certain events. A flag is a MOOS variable-value pair, similar to
flag postings in the helm or other MOOS apps. There are three events
where flags will be posted.

%-----------------------------------------------------------------
\subsubsection{Result Flags}

A {\em result flag} is posted when the mission has been evaluated with
either a failure or passing grade. This flag is posted regardless of the
grade. The configuration parameter is \pvar{result\_flag}. For example:

  \pvar{result\_flag = EVAL=true}

\vspace{0.1in}
\noindent
The result flag will be posted when the lead conditions have all been met, and...
  
%=================================================================
\subsection{Flag Postings}



%===========================================================
\section{Configuration Parameters for pMissionEval}
%===========================================================
\index{pMissionEval!Configuration Parameters}
\index{Configuration Parameters!pMissionEval}

The following parameters are defined for \app{pMissionEval}. A more
detailed description is provided in other parts of this
section. Parameters having default values are indicated.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{pMissionEval}}
\label{lst_params_pmeval}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 

  \pvar{lead\_condition}: &amp; A logic condition that must be satisfied
  before the mission can be evaluated. Section
  \ref{sec_pmeval_cond}.\\

  \pvar{pass\_condition}: &amp; A logic condition that must be satisfied
  for the overall mission to be considered successful. Section
  \ref{sec_pmeval_cond}.\\

  \pvar{fail\_condition}: &amp; A logic condition that must {\em not} be
  satisfied or otherwise the overall mission will be considered
  successful. Section \ref{sec_pmeval_cond}.\\

  \pvar{result\_flag}: &amp; A flag to be publish once the result is
  known.  Section \ref{sec_pmeval_flags}. \\

  \pvar{pass\_flag}: &amp; A flag to be publish once the result is known
  and is mission has been deemed to be successful.  Section
  \ref{sec_pmeval_flags}. \\

  \pvar{fail\_flag}: &amp; A flag to be publish once the result is known
  and is mission has been deemed to be not successful.  Section
  \ref{sec_pmeval_flags}. \\

  \pvar{vcheck}: &amp; Section \ref{sec_pmeval_vcheck}. \\

  \pvar{vcheck\_start}: &amp; Section \ref{sec_pmeval_vcheck}. \\

  \pvar{vcheck\_max\_report}: &amp; Section \ref{sec_pmeval_vcheck}. \\

  \pvar{fail\_on\_first}: &amp; Section \ref{sec_pmeval_vcheck}. \\

\end{longtable}
\end{listing}
  

%=================================================================
\section{Publications and Subscriptions of pMissionEval}
%=================================================================
\index{pMissionEval!Publications and Subscriptions}
\index{Publications and Subscriptions!pMissionEval}
\label{sec_pmeval_interface}

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

\vspace{0.1in}
\begin{consoleverb}
 $ pMissionEval --interface or -i
\end{consoleverb}
\vspace{0.05in}

%=================================================================
\subsection{Variables Published by pMissionEval}
\label{sec_pmeval_pubs}

The only output of \app{pMissionEval} is: 

\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_pmeval_appcast}.

\item \mvar{APPNAME\_MEM}: The amount of memory currently measured
  for the given applicion. This is a numerical value in Megabytes.
\end{packed_itemize}

%=================================================================
\subsection{Variables Subscribed for by pMissionEval}
\label{sec_pmeval_subs}

The \app{pMissionEval} application will subscribe for the following
four 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}: A list of clients (apps) known the
  local MOOSDB community. 

\item \mvar{APPNAME\_PID}: 
  \var{"ignore"} (\var{"none"}). Section \ref{sec_pmeval_getpid}.

\end{packed_itemize}


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

The \app{pMissionEval} application produces some useful information to
the terminal on every iteration of the application. An example is
shown in Listing \ref{lst_pmeval_appcast} below. This application is
also appcast enabled, meaning its reports are published to the MOOSDB
and viewable from any \app{uMAC} application or
\app{pMarineViewer}. See Section \ref{sec_umac_utils} for more on
appcasting and viewing appcasts.  The counter on the end of line 2 is
incremented on each iteration of \app{pMissionEval}, and serves a bit as
a heartbeat indicator.  The \var{"0/0"} also on line 2 indicates there
are no configuration or run warnings detected.

\pskip

\noindent
The output in the below example comes from the example described in 
Section \ref{sec_pmeval_example}. 

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{pMissionEval}}
\label{lst_pmeval_appcast}
\footnotesize
\begin{verbatim}
 1  ===================================================================
 2  pMissionEval alpha                                            0/0(394)
 3  ===================================================================
 4  Configuration:     
 5    Watch Only Apps: pHelmIvP,pMarineViewer
 6        Ignore Apps: None
 7  Absolute Time Gap: 1
 8
 9 
10  App            PID    Memory  Delta 
11  -------------  -----  ------  ------
12  pHelmIvP       35346  1.988   0.008 
13  pMarineViewer  35347  95.492  -0.016
14  
15   Last ix: 0
16  Last app: pHelmIvP
17  Last mem: 1.988
18  Last raw: 1988
19  Warp: 10
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The first few lines (4-7) show the configuration settings for
\app{pMissionEval}.  The status of \app{pMissionEval} is shown in Lines
10-19. The watch list is comprised of \app{pHelmIvP} and
\app{pMarineViewer}, and their status is shown on lines 12 and 13. The
system process ID (PID) is shown in the second column.  The latest
measure of memory usage is shown in the third column, and the change
in memory usage since the previous measurement is shown in the last
column. Line 15 shows the index of the most recently measured
application, and line 16 shows the name of the app at this index. As
the mission unfolds one can see this index cycling from 0 to N-1 where
N is the number of processes being monitorer. This cycling through
processes was discussed in Section \ref{umwatch_pace} as way to ensure
infrequent system calls. The latest memory measurement is shown
in lines 17-18. Line 17 shows the memory usage in Megabytes, and
line 18 shows the raw output from the system command. Line 19
simply confirms that time warp detected by \app{pMissionEval}.

%=================================================================
\section{A Simple Example}
%=================================================================
\label{sec_pmeval_example}

The below is a simple example configuration of \app{pMissionEval}.
In this case only two processes are watched, \app{pHelmIvP} and
\app{pMarineViewer}. This example configuration may also be
obtained by typing on the command line: \var{pMissionEval -e}.

\vspace{0.1in}
\begin{listing}{A Simple \app{pMissionEval} Example}
\label{lst_pmeval_example}
\footnotesize
\begin{verbatim}
//------------------------------------------
// pMissionEval config block

ProcessConfig = pMissionEval
{
  AppTick   = 4
  CommsTick = 4
}

\end{verbatim}
\end{listing}
\normalsize

\end{document}

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