signalk-sunphases v1.0.0

signalk-sunphases

Inject sunlight phase data into Signal K.

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-sunphases uses Vladimir Agafonkin's SunCalc library to calculate sunlight phases (times for sunrise, sunset, dusk, etc.) for the vessel's current location and injects the resulting time values into the Signal K state.

Using these values as a starting point, you can define as many simple rules as you need to raise and cancel notifications as sunlight phase events occur during the day.

A vanilla installation of signalk-sunphases manages two notifications, "notifications.daytime" and "notifications.nighttime".

System requirements

signalk-sunphases requires that the the 'baconjs' and 'suncalc' npm's are available in your Node server context. If the module claims they are not found, you can install them locally to the plugin by changing to the plugin directory and issuing the following commands.

$> npm install baconjs
$> npm install suncalc

Installation

Download and install signalk-sunphases using the "Appstore" menu option in your Signal K Node server console. The plugin can also be obtained from the project homepage and installed using these instructions.

The plugin is enabled by default: once installed you should find the keys it maintains under "environment.sunphases...." and "notifications....".

Using the plugin

signalk-sunphases operates autonomously.

The plugin can be configured using the Signal K Node server plugin configuration GUI, or you can just edit the plugin's JSON configuration file 'sunphases.json' using your preferred text editor.

The default configuration illustrates the general structure:

{
  "enabled": true,
  "enableLogging": false,
  "enableDebug": false,
  "configuration": {
    "interval": 600,
    "root": "environment.sunphases",
    "notifications": [
      {
        "rangelo": "dawn",
        "rangehi": "dusk",
        "inrangenotification": {
          "path": "notifications.daytime"
        },
        "outrangenotification": {
          "path": "notifications.nighttime"
        }
      }
    ]
  }
}

When signalk-sunphases starts, and shortly after midnight Zulu time it computes sun phase values for the current day and stores them in keys under the specified root (see below).

The required interval property introduces a natural number value that defines how many seconds should elapse between notification updates. The default value is 600 which will cause the plugin to check and if necessary update notifications every 10 minutes. Setting the interval value to 0 will cause the plugin to process notifications immediately that it is retsarted and then never again: useful for testing, but not much else.

The required root property introduces a string value that defines the path under which the plugin will store sun phase data. The default value is "environment.sunphases". The keys and the values that are inserted here are those defined as properties in the object returned by a call to SunCalc.getTimes(). You can get the plugin to log a list of the generated keys and their values by setting the debug key 'sunphases:keys'.

The required notifications property introduces an array that can contain an arbitrary number of notification definitions. Each definition identifies a time period and the notifications that should be raised when the current time of day is within and outside of this range. The time limits can be specified as SunCalc key names (optionally with some arithmetic tweaking) or as absolute Zulu times. Bear in mind that signalk-sunphases wass not designed to be a real-time scheduler and that its utility in this role is severely hampered by the time granularity implied by the value of interval.

Each object in the notifications array is defined in the following way.

The required rangelo property introduces a string value that specifies the time of the start of the notification period. The required format for value is "( key(+|-)n(h|m|s) | hh:mm:ss )", where key is the name of a SunCalc key (and may be all you need).

The required rangehi property introduces a string value that specifies the time of the end of the notification period. See rangelo above for the format considerations.

The optional inrangenotification property introduces an object that defines the notification that should be raised when the current time of day is within the range rangelo...rangehi.

The optional outrangenotification property introduces an object that defines the notification that should be raised when the current time of day is outside the range rangelo...rangehi.

The notification definition object specified by inrangenotification and outrangenotification is defined in the following way:

The required path property introduces a string which specifies the path of the desired notification.

The optional state property introduces a string that specifies the the value to be used for the state property of any raised notification. If state is omitted, then this value will default to "normal".

The optional method property introduces a string array thats specifies the value to be used for the method property of any raised notification. If method is omitted, then this value will default to [].

Debugging and logging

signalk-sunphases logs summary status information to the Signal K dashboard.

The plugin also responds in a more fulsome way to the following debug keys.