pDeadManPost: Arranging Posts in the Absence of Events

Maintained by: mikerb@mit.edu         Get PDF

src: project-pavlab/appdocs/app_pdeadmanpost

1  Overview
2  Configuration Parameters for pDeadManPost
3  Publications and Subscriptions of pDeadManPost
     3.1 Variables Published by pDeadManPost
     3.2 Variables Subscribed for by pDeadManPost
4  Configuring the Heartbeat Condition
5  Specifying DeadFlags
6  Terminal and AppCast Output
7  A Simple Example

1   Overview

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

  • 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 iSay.
  • 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.
  • 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.

2   Configuration Parameters for pDeadManPost

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

Listing 2.1 - Configuration Parameters for pDeadManPost.

heartbeat_var:Names the MOOS variable serving as the heartbeat. .
active_at_start: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. .
deadflag:A MOOS variable-value pair to be posted when the heartbeat disappears. .
max_noheart:The maximum amount of time, in seconds, a missing heartbeat is tolerated before the deadflags are posted. Default is 10. .
post_policy:Either "once", "repeat", or "reset" determines how the deadflags are posted once a heartbeat condition has failed. .

3   Publications and Subscriptions of pDeadManPost

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

  $ pDeadManPost --interface or -i

3.1   Variables Published by pDeadManPost    [top]

The only output of pDeadManPost is:

  • 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. .

The pDeadManPost app will also publish whatever MOOS variables are identified in the deadflag parameter.

3.2   Variables Subscribed for by pDeadManPost    [top]

The pDeadManPost application will subscribe for the following four MOOS variables:

  • APPCAST_REQ: A request to generate and post a new apppcast report, with reporting criteria, and expiration. See the documentation on appcasting.

It will also subscribe for whatever MOOS variable is identified as serving as the heartbeat variable in the heartbeat_var parameter.

4   Configuring the Heartbeat Condition

The 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 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 heartbeat_var parameter. For example: 

  heartbeat_var = CONTINUE_MISSION

The frequency at which the heartbeat must be received is determined by max_noheart parameter, given in seconds. The default for this parameter is 10 seconds. It can be set, for example, with: 

  max_noheart = 120

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

  active_on_start = false     // The default is true

The status of the heartbeat condition can be monitored in the appcasting output of the app, by noting the line "Time Remaining:". If this is zero, then the heartbeat condition has failed. If it reads "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.

5   Specifying DeadFlags

A 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: 

  deadflag = RETURN=true
  deadflag = DEAD_MAN_POST_INTERRUPT=true

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

  post_policy = repeat    // The default is "once"

The second option is to configure pDeadManPost to 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: 

  post_policy = reset    // The default is "once"

When the post_policy parameter is set to repeat, the postings will cease when a new heartbeat message is received.

6   Terminal and AppCast Output

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

The output in the below example comes from the example described in .

Listing 6.1 - Example terminal or appcast output for pDeadManPost. 

   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

The first few lines (4-11) show the configuration settings for pDeadManPost. The status of 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.

7   A Simple Example

The s1_alpha_deadman example mission distributed with moos-ivp provides a simple working example. More explanation to come...

Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF