signalk-threshold-notifier v3.1.1

signalk-threshold-notifier

Signal K Node Server plugin which raises notifications based on one or more path values.

The real-time values of one or more user-specified paths are compared against user-defined thresholds and Signal K notifications raised as these boundaries are encountered.

Thanks are due to Scott Bender for his signalk-simple-notifications plugin which this work simply elaborates.

System requirements

signalk-threshold-notifier has no special system requirements.

Installation

Download and install signalk-threshold-notifier using the Appstore link in your Signal K Node server console.

The plugin can also be downloaded from the project homepage and installed using these instructions.

Usage

signalk-threshold-notifier is configured through the Signal K Node server plugin configuration interface. Navigate to Server->Plugin config and select the Threshold notifier tab.

The plugin configuration consists of a list of rules, each of which specifies a Signal K path which should be monitored, upper and lower limits against which notifications should be raised and the attributes of such notifications. On first use the list of monitored paths will be empty.

New rules can be added by clicking the + button and any existing, unwanted, rules can be deleted by clicking their adjacent x button.

Each rule includes the following fields.

Monitored path
A required text value which specifies the Signal K Node server path which should be monitored. There is no default value.

Enter here the full Signal K path for the value which you would like to monitor, for example, "tanks.wasteWater.0.currentValue".

Options->Enabled?
Whether or not to process this rule. Default value is yes (checked).

Notification message
An optional text message which will be assigned to the message property of all notifications generated by the rule. The default value is a simple, automatically generated, message.

Enter here the text of the message you would like to be issued when the monitored path value crosses one of the defined thresholds. If the option is left blank then the plugin will insert just the monitored path text as an identifier when it raises a notification.

Any of the following tokens may be used in the supplied message text and these will be interpolated with the described value when the notification message is composed.

${path} will be replaced by the value of the Monitored path option.

${test} will be replaced by one of "above", "below" or "between" dependant upon the threshold being crossed and the direction of crossing.

${threshold} will be replaced with the value of the threshold triggering the rule or, in the case of the path value being between thresholds with the string "n and m" where n is the low threshold and m is the high threshold.

${value} will be replaced with the instantaneous value of the monitored path that triggered the rule.

${vessel} will be replaced with Signal K's idea of the vessel name.

An example message text might be "${vessel}: ${path} is ${test} ${threshold} (currently ${value})".

Path prefix
A notification path component which will be inserted after the "notifications." root and before the value of Monitored path. This allows semantic classification of notifications and supports overlapping notifications on the same monitored path. Default is "none" which places notifications directly under the "notifications." root.

Low threshold
An optional numerical value which sets the lower threshold against which the monitored path value will be compared. The default value is a blank entry which disables monitoring of the low threshold.

If a value is specified and the monitored path value falls below this limit then a notification of the type defined by Alarm state will be issued.

Alarm state
A required value which will be assigned to the notification state property which is used to signal the severity of the notification. Default is to set the alarm state to "alert".

Choose a value appropriate to the notification event. Remember that notifications in Signal K may be processed by downstream handlers and the chosen state could have significance elsewhere: an example is the signalk-switchbank plugin which treats "normal" and non-"normal" alarm states as part of a switching signal.

Suggested method
An optional value which will be assigned to the notification method property which is used to suggest to downstream notification handlers a preference for how a notification may be handled. Default is to express no preference.

Choose any values which you think appropriate, or none at all. Once again, some downstream notification handlers may require a particular value or combination of values in order to perform their function.

The cluster of options associated with defining a high threshold have similar semantics to those described above: the High threshold option itself, naturally, defines an upper threshold against which the monitored path value will be tested for a low-to-high transition.

Use cases

Managing Beatrice's waste tank

Once upon a time the black water tank on Beatrice overflowed: I had failed to take note of the tank gauge and had no audible alarm. I now use Signal K to implement an escalating response to waste tank filling which might ensure that there is never a repeat of this catastrophe.

My first line of defense is to raise a notification which is picked up by my helm annunciator and also detected by signalk-renotifier which forwards the notification to my cell phone via SMS.

{
    "path": "tanks.wasteWater.0.currentLevel",
    "message": "${vessel}: waste water level is ${test} ${threshold}",
    "highthreshold": {
        "value": 0.8,
        "state": "warning",
        "method": [ "visual" ]
    }
    "options": [ "enabled" ],
    "prefix": "none"
}

Notwithstanding this precaution, I have an end-stop strategy which should make sure that there is never again a problem: this environmentally unfriendly last-ditch solution automatically starts my discharge pump if the waste tank level becomes critical.

I use the signalk-switchbank plugin to operate the pump and this requires a notification to start the pump and a subsequent notification to stop it. The configuration file snippet for the rule I use looks like this:

{
    "path": "tanks.wasteWater.0.currentLevel",
    "message": "${vessel}: waste water automatic discharge: level is ${test} ${threshold} (${value})",
    "highthreshold": {
        "value": 0.9,
        "state": "alert",
        "method": [ ]
    },
    "lowthreshold": {
        "value": 0.01,
        "state": "normal",
        "method": [ ]
    },
    "options": [ "enabled" ],
    "prefix": "control."
}

The notification which starts the pump must have a state which is not equal to "normal" (in this case it is "alert") and the notification which stops the pump must have a state equal to "normal".

Messages

signalk-threshold-notifier issues the following message to the Signal K Node server console and system logging facility.

Monitoring n paths
The plugin has initialised and is monitoring n Signal K paths.

Additionally, the following messages are issued just to the system logging facility.

cancelling notification on 'path'
The monitored value has returned between the low and high thresholds and the notification on path is being removed.

issuing 'state' notification on 'path'
The monitored value has passed a threshold and a notification of type state has been issued on path.