signalk-notification-injector v3.0.0

signalk-notification-injector

Signal K notification tree message interface.

This project implements a plugin for the Signal K Node server.

Reading the Alarm, alert and notification handling section of the Signal K documentation may provide helpful orientation.

signalk-notification-injector parses messages arriving on a named pipe (FIFO), UDP port or TCP websocket into keys in the Signal K host server's vessels.self.notifications tree.

Messages are single lines of text which conform to some simple formatting and security rules.

Processes on the Signal K host which are able to write to the named pipe can create a notification very simply:

$> echo "heating:alert Heating system fuel level < 10%" > /var/signalk-injector

Remote processes or network applications can achieve the same result by writing to the injector's UDP port or by making a TCP websocket connection. For example, on a remote Linux client, something like this could be used to send a message to the plugin's UDP interface.

$> echo "letmein@heating:alert Heating system fuel level < 10%" > /dev/udp/192.168.1.1:6543

System requirements

signalk-notification-injector requires that the node environment includes the 'ws' module.

Installation

You can download and install signalk-notification-injector using the Appstore link in your Signal K Node server console. Unfortunately, a limitation in the software packaging system means that the downloaded module will have some missing submodules. After the Appstore dowload completes you can add these by:

$> cd ~/.signalk/node_modules/signalk-notification-plugin
$> git submodule update --remote
$> systemctl restart signalk.service

Alternatively, the plugin can be downloaded directly from its project homepage on github.com:

$> cd ~/.signalk/node_modules
$> git clone --install-submodules https://github.com/preeve9534/signalk-notification-injector.git
$> systemctl restart signalk.service

If the server complains when restarted about a missing 'ws' library required by this plugin, you can install a local copy with:

$> cd ~/.signalk/node_modules/signalk-notification-injector
$> npm install ws
$> systemctl restart signalk.service

Configuration

signalk-notification-injector is configured through the Signal K Node server plugin configuration interface. Navigate to Server->Plugin config and select the Notification injector tab.

The Active checkbox tells the Signal K Node server whether or not to run the plugin: on first execution you should check this, before reviewing and amending the configuration options discussed below. Changes you make will only be saved and applied when you finally click the Submit button.

The plugin configuration properties are organised under three collapsible tabs.

Service interfaces

These settings define which, if any, of the implemented interfaces to the plugin are enabled and provides configuration details for each interface.

FIFO named pipe

Enabled? specifies whether or not to create and monitor a local named pipe. Required. Default is checked (create and monitor the named pipe).

Password protected? specifies whether or not messages to this interface must include a password in order to use the plugin. Required. Default is not checked (do not require a password).

Pathname specifies the absolute filesystem path of the named pipe. Required. Default is '/var/signalk-injector'.

UDP port

Enabled? specifies whether or not to provide service on a local UDP port. Required. Default is not checked (do not provide a UDP service).

Password protected? specifies whether or not messages to this interface must include a password in order to use the plugin. Required. Default is checked (require a password).

Port specifies the UDP port number on which to listen for connections. Required. Default is 6543.

TCP websocket

Enabled? specifies whether or not to provide a websocket service on a local TCP port. Required. Default is not checked (do not provide a websocket service).

Password protected? specifies whether or not messages to this interface must include a password in order to use the plugin. Required. Default is checked (require a password).

Port specifies the TCP port number on which to listen for websocket connections. Required. Default is 6543.

Default notification properties

These settings define default values which will be used by the plugin when it constructs a notification from a received message. Setting defaults can be a way of simplifying the content of incoming messages. Defaults can always be over-ridden on a per-message basis.

Default notification path specifies the root in the Signal K data tree where the plugin will place notifications derived from messages which do not themselves specify an absolute notification key (that is a key which begins with 'notifications...'). The supplied path must be absolute (i.e. must begin with 'notifications.'). Required. Default is 'notifications.injector'.

Default notification state specifies the value to be used for the state property of notifications derived from messages which do not themselves specify a notification state. Required. Default value is 'alert'.

Default notification methods specifies the values to be used for the method property of notifications derived from messages which do not themselves specify a notication method or methods. Required. The default is not to specify any methods.

Security settings

These settings configure the security measures which can be applied to the various plugin service interfaces.

Allowed network client addresses specifies a space separated list of client IP addresses from which connections to the UDP and TCP interfaces will be accepted. The wildcard '*' can be used in any part of an address. Required. Default value is '127.0.0.1' which will only allow access from the Signal K host. You should change this to reflect your local requirement: something like '127.0.0.1 192.168.*.*' will satisfy most use cases.

Access passwords specifies a space separated collection of passwords, one of which must be included in messages presented to plugin interfaces on which password protection is enabled. Required. Default value is 'letmein 0000'.
You may want to change this to reflect your local requirement.

Production example

The configuration used on my production system looks like this.

{
  "enabled": true,
  "enableLogging": false,
  "configuration": {
    "interfaces": {
      "fifo": {
        "enabled": true,
        "protected": false,
        "path": "/var/signalk-injector"
      },
      "udp": {
        "enabled": true,
        "protected": true,
        "port": 6543
      },
      "ws": {
        "enabled": true,
        "protected": true,
        "port": 6543
      }
    },
    "notification": {
      "defaultpath": "notifications.injected",
      "defaultstate": "alert",
      "defaultmethods": []
    },
    "security": {
      "clients": "127.0.0.1 192.168.1.*",
      "passwords": "flashbang 1958 447786123456"
    }
  }
}

Usage

Once signalk-notification-injector is configured and activated, you can inject a notification into the Signal K notification tree by writing a message to one or other of the configured interfaces.

Assuming that the default plugin configuration is unchanged, then the command:

$> echo "test:alert" > /var/signalk-injector

will issue an 'alert' notification on the key notifications.injected.test.

Similarly, the command:

$> echo "letmein@test:cancel" > /var/signalk-injector

will cancel this notification.

You can check this behaviour on your Signal K server by substituting your server address in a URL of the following form and reviewing browser output.

http://192.168.1.1:3000/signalk/v1/api/vessels/self/notifications/injected/

The examples above are an example of the minimum needed to trigger a plugin response. More generally, a message to the plugin must consist of a single line of text conforming to the formatting constraints described below.

Message format

Messages sent to the plugin must conform to one of the following patterns:

password@key[:state:method]] description

password@key:{off|cancel}

The first form is used to issue a notification, the second form to cancel (delete) any existing notification.

The optional password field is required if the interface used to deliver the message has its Protected? configuration property enabled. In this case, messages will only be processed if the supplied password has a value which is defined in the plugin's Access passwords configuration setting. If the interface being used is not protected, then password is optional and if a value is supplied it will be discarded.

key is the notification key to which the message applies and it should take the form of a simple name or a dotted pathname. If key includes an absolute notification path (i.e. one that begins '.notifications.'), then the value of key will be used as-is; otherwise, the Default notification path defined in the plugin configuration will be prepended to key.

The optional state field sets the state property of an issued notification. If state is omitted or left blank, then the Default notification state defined in the plugin configuration will be used. If state is supplied, then it should be one of the standard values defined in Signal K ('normal', 'alert', 'alarm' and 'emergency') or the special plugin value 'on' which is simply an alias for 'alert'.

The optional method field sets the method property of an issued notification. If method is omitted, then the Default notification method defined in the plugin configuration will be used. If method is left blank, then no method will be specified in the generated notification. The supplied value must be a comma-delimited list of notification methods (the standard methods in Signal K are 'visual' and 'sound').

description is arbitrary text which will be used as the descriptive contents of the issued notification.

Use cases

SMS control interface

On Beatrice I use signalk-notification-injector as part of an SMS based remote control system which allows me to do things like turn on lights and heating and so on.

Beatrice's cellular network interface is implemented by gammu-smsd(1) which periodically polls an attached GSM modem and acquires incoming texts. Received texts are passed by gammu-smsd to a simple shell script which parses the content into a message suitable for consumption by signalk-notification-injector.

The [smsd] stanza of my gammu-smsd configuration file includes the line:

RunOnReceive = /usr/local/bin/signalk-inject

which refers to the following bash(1) script.

#!/bin/bash
# signalk-inject
FIFO=/var/signalk-injector
PROGRAM=/bin/echo

for i in `seq ${SMS_MESSAGES}` ; do
    eval "$PROGRAM \"\${SMS_${i}_NUMBER}\"@\"\${SMS_${i}_TEXT}\"" > ${FIFO}
done