<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{pDeadManPost: Arranging Posts in the Absence of Events}
\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\_pdeadmanpost} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PDeadManPost}
\wikidoc{bugz=pDeadManPost}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
\section{Overview}
%===================================================================
\wikisec{grp=utils,file=PDeadManPost,short=pDeadManPost}
\label{sec_pdman}
\index{pDeadManPost}

The \app{pDeadManPost} application allows the user to arrange
configured posts to the MOOSDB in the {\em absence} of another event.
There are many conceivable uses for this, but here are a few of the
ideas that motivated this app:

\begin{packed_itemize}
\item On a shoreside community, a dead-man post can be made to trigger
  an alert when a deployed vehicle is out of contact after some period
  of time. The alert could be a posting to trigger an alarm .wav file
  or a spoken alert message through \app{iSay}.

\item On a surface vehicle, a dead-man post can be made to put the
  vehicle in a station-keeping mode if comms to the shoreside
  command and control goes silent for some period of time.

\item On an underwater vehicle, a dead-man post can be made to put the
  vehicle in a return-to-home mode if it loses updates from navigation
  beacons for some period of time.
\end{packed_itemize}


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

The following parameters are defined for \app{pDeadManPost}. 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{pDeadManPost}}
\label{lst_params_isay}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 

  \pvar{heartbeat\_var}: &amp; Names the MOOS variable serving as the
  heartbeat. Section \ref{sec_pdman_heartvar}. \\

  \pvar{active\_at\_start}: &amp; if true then the hearbeat condition (timer)
  is active upon startup of the app. Otherwise the heartbeat condition
  is not active until the first heartbeat is received. The default is 
  heartbeat true. Section \ref{sec_pdman_heartvar}. \\

  \pvar{deadflag}: &amp; A MOOS variable-value pair to be posted when the
  heartbeat disappears. Section \ref{sec_pdman_dflags}. \\

  \pvar{max\_noheart}: &amp; The maximum amount of time, in seconds, a
  missing heartbeat is tolerated before the deadflags are
  posted. Default is 10. Section \ref{sec_pdman_heartvar}. \\

  \pvar{post\_policy}: &amp; Either \var{"once"}, \var{"repeat"}, or \var{"reset"}
  determines how the deadflags are posted once a heartbeat condition has
  failed. Section \ref{sec_pdman_dflags}.
\end{longtable}
\end{listing}
  

%===================================================================
\section{Publications and Subscriptions of pDeadManPost}
%===================================================================
\index{pDeadManPost!Publications and Subscriptions}
\index{Publications and Subscriptions!pDeadManPost}
\label{sec_pdman_interface}

The interface for \app{pDeadManPost}, 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}
 $ pDeadManPost --interface or -i
\end{consoleverb}
\vspace{0.05in}

%===================================================================
\subsection{Variables Published by pDeadManPost}
\label{sec_pdman_pubs}

The only output of \app{pDeadManPost} 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_pdman_appcast}.
\end{packed_itemize}

\noindent
The \app{pDeadManPost} app will also publish whatever MOOS variables
are identified in the \pvar{deadflag} parameter.

%===================================================================
\subsection{Variables Subscribed for by pDeadManPost}
\label{sec_pdman_subs}

The \app{pDeadManPost} 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. See the
  documentation on appcasting.
\end{packed_itemize}

\noindent
It will also subscribe for whatever MOOS variable is identified as serving
as the heartbeat variable in the \pvar{heartbeat\_var} parameter.

%===================================================================
\section{Configuring the Heartbeat Condition}
%===================================================================
\label{sec_pdman_heartvar}

The {\em hearbeat condition} stipulates that a named MOOS variable
must be continually written to by some other application, with a
specified frequency. If the heartbeat condition fails, deadflags are
posted. The heartbeat is monitored simply by monitory the mailbox in
\app{pDeadManPost} for incoming mail on the named MOOS variable. No
check is made as to the value or source of the incoming mail, only
that mail has been received. The monitored variable is set by
\pvar{heartbeat\_var} parameter. For example:

\vspace{0.1in}
\prevblue
\begin{verbatim}
 heartbeat_var = CONTINUE_MISSION
\end{verbatim}
\postverb
\vspace{0.1in}

\noindent
The frequency at which the heartbeat must be received is determined by 
\pvar{max\_noheart} parameter, given in seconds. The default for this
parameter is 10 seconds. It can be set, for example, with:

\vspace{0.1in}
\prevblue
\begin{verbatim}
 max_noheart = 120
\end{verbatim}
\postverb
\vspace{0.1in}

\noindent
The user may further specify whether the heartbeat condition is active
immediately upon startup of the \app{pDeadManPost} app, or if it instead
becomes active only after receiving the first heartbeat message. This is
determined with the \pvar{active\_on\_start} parameter. For example:

\vspace{0.1in}
\prevblue
\begin{verbatim}
 active_on_start = false     // The default is true
\end{verbatim}
\postverb
\vspace{0.1in}

\noindent
The status of the heartbeat condition can be monitored in the appcasting output
of the app, by noting the line \var{"Time Remaining:"}. If this is zero, then
the heartbeat condition has failed. If it reads \var{"N/A"}, it means the heartbeat
condition is not in effect, likely because the app is configured to be not active
on start and no heartbeat message has yet been received. Otherwise, it should show
the time remaining in seconds before the heartbeat condition fails unless another
heartbeat message is received in the meanwhile.


%===================================================================
\section{Specifying DeadFlags}
%===================================================================
\label{sec_pdman_dflags}

A \pvar{deadflag} is a MOOS variable-value pair to be posted when or
if the heartbeat condition times out. Multiple dead flags may used.
An example:

\vspace{0.1in}
\prevblue
\begin{verbatim}
 deadflag = RETURN=true
 deadflag = DEAD_MAN_POST_INTERRUPT=true
\end{verbatim}
\postverb
\vspace{0.1in}

\noindent
When the heartbeat condition fails, and one or more deadman posts are
made, by default, these posts are made only \var{once}, regardless
of whether further heartbeat messages are received. The user has two
further options: the posts can be made to \var{repeat} on each
iteration of the \app{pDeadManPost} app by setting:

\vspace{0.1in}
\prevblue
\begin{verbatim}
 post_policy = repeat    // The default is "once"
\end{verbatim}
\postverb
\vspace{0.1in}

\noindent
The second option is to configure \app{pDeadManPost} to \var{reset} after
a posting is made. In this case the heartbeat timer is reset and if another
period of time elapses without a heartbeat, another posting is made. This
is configured with:

\vspace{0.1in}
\prevblue
\begin{verbatim}
 post_policy = reset    // The default is "once"
\end{verbatim}
\postverb
\vspace{0.1in}

\noindent
When the \pvar{post\_policy} parameter is set to \var{repeat}, the postings
will cease when a new heartbeat message is received.


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

The \app{pDeadManPost} application produces some useful information to
the terminal on every iteration of the application. An example is
shown in Listing \ref{lst_pdman_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 the documentation on \app{uMac} or
\app{uMacView} for more on appcasting and viewing appcasts.  The
counter on the end of line 2 is incremented on each iteration of
\app{pDeadManPost}, 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_pdman_example}.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{pDeadManPost}}
\label{lst_pdman_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  pDeadManPost alpha                                         0/0(362)
  3  ===================================================================
  4  Configuration:
  5  -------------------------------------
  6        heart_var: CONTINUE
  7      max_noheart: 60
  8  active_at_start: false
  9      post_policy: repeat
 10        deadflags: (1)
 11                   [1] RETURN=true
 12  
 13  State:
 14  -------------------------------------
 15    Elapsed Time: 23.0875
 16  Time Remaining: 36.9125
 17      Heartbeats: 2
 18  Total Postings: 0
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The first few lines (4-11) show the configuration settings for
\app{pDeadManPost}.  The status of \app{pDeadManPost} is shown in
Lines 13-18. In this case, the most recent heartbeat message was 
received 23 seconds prior, as shown in line 15, and no deadman
posts have been made as shown on line 18.

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

The \var{s1\_alpha\_deadman} example mission distributed with moos-ivp
provides a simple working example. More explanation to come...


\end{document}

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