Skip to content

Commit

Permalink
final tweaks to make upgrading from v2 easier
Browse files Browse the repository at this point in the history
  • Loading branch information
= committed Mar 7, 2021
1 parent 3639cd3 commit d81c246
Show file tree
Hide file tree
Showing 6 changed files with 58 additions and 49 deletions.
12 changes: 10 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,17 @@ and the resulting Sun events are output from this node at the appropriate time:
* dawn: dawn (morning nautical twilight ends, morning civil twilight starts)
* nadir: nadir (darkest moment of the night, sun is in the lowest position)

## Usage
<i>Please Note: The latest version (version 3) of this node works a little differently to previous versions and will require a change to your flow if you are upgrading from a previous version.</i>
## Upgrading from v2.x
The latest version (v3.0) of this node works a little differently to previous versions and will
require a change to your flow if you are upgrading from a previous version.

The latitude and longitude you defined in the node's configuration can be used to calculate
Sun events if no latitude and longitude coordinates
are passed in the <i>msg.payload</i>. You <b>must</b> still inject a payload at regular
intervals to recalculate the next 24 hour's events, but this payload can be any value.


## Usage
Each time this node receives a new `msg.payload` to it's input, it calculates up to 2 days worth of Sun events (depending on what time of day it is invoked). To have the node output events reliably every day, you should inject a latitude and longitude payload into the node at least once every 24 hours. The easiest way to do this is with the node-red Inject node.


Expand Down
62 changes: 37 additions & 25 deletions lib/sun-events-node.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
-->

<script type="text/x-red" data-template-name="sun-events">
<script type="text/x-red" data-template-name="sun events">

<!-- By convention, most nodes have a 'name' property. The following div -->
<!-- provides the necessary field. -->
Expand Down Expand Up @@ -48,8 +48,12 @@
<hr>
<div class="form-row">
<p><i class="fa fa-warning"></i> Latitude & Longitude</p>
<p>Please note: values for latitude and longitude are now supplied to this node via the <i>msg.payload</i> in latitude and longitude properties.
Please update your flow and refer to the documentation for more details.</p>
<p>Please note: since v3.0 the preferred way of providing values for latitude and longitude is
via properties in the <i>msg.payload</i>. These parameters below are provided for backwards
compatibility and to help make the upgrade to v3 easier. Parameters passed via
<i>msg.payload</i> take precedence over the values below. You <b>must</b> still inject a payload
at regular intervals to trigger event calculations (a dummy payload will work fine). Please
see the documentation for more details.
</div>
<div class="form-row">
<label for="node-input-latitude"><i class="fa fa-globe"></i> Latitude</label>
Expand All @@ -64,41 +68,49 @@


<!-- Next, some simple help text is provided for the node. -->
<script type="text/x-red" data-help-name="sun-events">
<p><i>node-red-contrib-sunevents</i></p>
<script type="text/x-red" data-help-name="sun events">
<p><i>node-red-contrib-sunevents v3.0</i></p>
<p>A node that generates events based on the location of the Sun at the appropriate time of day.
This node can be used to make something happen based on a particular period of the day, for example switching
on your lights at home at dusk every day or taking a photo a the darkest time of night ("nadir"). </p>
This node can be used to make something happen based on a particular period of the day, for example, switching
on your lights at dusk every day or taking a photo a the darkest time of night ("nadir"). </p>

<p>On receiving a msg.payload containing latitude and longitude coordinates (in decimal), this
node outputs a series of Sun event objects at the appropriate time for each.</p>

<p>Calculations are performed using the excellent <a href="https://github.com/mourner/suncalc">SunCalc module</a> and
the resulting sun events are output from this node at the appropriate time for each:</p>
the resulting Sun events are output from this node at the appropriate time for each:</p>

<ul>
<li>sunrise: sunrise (top edge of the sun appears on the horizon)</li>
<li>sunriseEnd: sunrise ends (bottom edge of the sun touches the horizon)</li>
<li>sunrise: sunrise (top edge of the Sun appears on the horizon)</li>
<li>sunriseEnd: sunrise ends (bottom edge of the Sun touches the horizon)</li>
<li>goldenHourEnd: morning golden hour (soft light, best time for photography) ends</li>
<li>solarNoon: solar noon (sun is in the highest position)</li>
<li>solarNoon: solar noon (Sun is in the highest position)</li>
<li>goldenHour: evening golden hour starts</li>
<li>sunsetStart: sunset starts (bottom edge of the sun touches the horizon)</li>
<li>sunset: sunset (sun disappears below the horizon, evening civil twilight starts)</li>
<li>sunsetStart: sunset starts (bottom edge of the Sun touches the horizon)</li>
<li>sunset: sunset (Sun disappears below the horizon, evening civil twilight starts)</li>
<li>dusk: dusk (evening nautical twilight starts)</li>
<li>nauticalDusk: nautical dusk (evening astronomical twilight starts)</li>
<li>night: night starts (dark enough for astronomical observations)</li>
<li>nightEnd: night ends (morning astronomical twilight starts)</li>
<li>nauticalDawn: nautical dawn (morning nautical twilight starts)</li>
<li>dawn: dawn (morning nautical twilight ends, morning civil twilight starts)</li>
<li>nadir: nadir (darkest moment of the night, sun is in the lowest position)</li>
<li>nadir: nadir (darkest moment of the night, Sun is in the lowest position)</li>
</ul>

<h2>Usage</h2>

<p><i>Please Note: The latest version (version 3) of this node works a little differently to previous versions and will
require a change to your flow if you are upgrading from a previous version.</i></p>
<h2>Upgrading from v2.x</h2>
<p>The latest version (v3.0) of this node works a little differently to previous versions and will
require a change to your flow if you are upgrading from a previous version.</p>
<p>The latitude and longitude you defined in the node's
configuration can be used to calculate Sun events if no latitude and longitude coordinates
are passed in the <i>msg.payload</i>. You <b>must</b> still inject a payload at regular
intervals to recalculate the next 24 hour's events, but this payload can be any value.
</p>


<h2>Usage</h2>

<p>Each time this node receives a new `msg.payload` to it's input, it calculates up to 2 days worth of
<p>Each time this node receives a new `msg.payload` to it's input, it calculates a minimum of 24 hours worth of
Sun events (depending on what time of day it is invoked). To have the node output events reliably every day, you should
inject a latitude and longitude payload into the node at least once every 24 hours. The easiest way to do this is with the node-red Inject node.</p>

Expand All @@ -115,10 +127,10 @@ <h3>Input</h3>
msg.payload.lng = -0.1440787
</pre>

<P>Calculations are performed using the Latitude and Longitude that are passed in via the payload. If you have a
<p>Calculations are performed using the Latitude and Longitude that are passed in via the payload. If you have a
frequently changing GPS position it will update the Sun event calculations every time it receives a new latitude
and longitude in the payload.</P>
and longitude in the payload.</p>

<h3>Output</h3>
<P>The Sun event name is output in msg.payload.sunevent, preserving any other payload values set earlier in the
flow. It also outputs the event name and date & time of the event in msg.sunevent object if you need a more complete
Expand Down Expand Up @@ -150,10 +162,10 @@ <h2>Example Flow</h2>
<p>There are two example flows provided, one for a fixed GPS positioned injected daily and one for a stream of GPS coordinates that continually updates with your position.
There is an example flow you can import supplied with this node.</p>

<p>Example 1: Fixed GPS position (<a href="./examples/sun-events-example-flows.json">Download</a>)
<p>Example 1: Fixed GPS position (<a href="https://raw.githubusercontent.com/freakent/node-red-contrib-sunevents/v3/examples/sun-events-example-flows.json" target="_blank">Download</a>)
<img src="https://raw.githubusercontent.com/freakent/node-red-contrib-sunevents/v3/docs/flow-diagram-1.png">

<p>Example 2: Stream of GPS positions (<a href="./examples/sun-events-gps-stream-example-flows.json">Download</a>)
<p>Example 2: Stream of GPS positions (<a href="https://raw.githubusercontent.com/freakent/node-red-contrib-sunevents/v3/examples/sun-events-gps-stream-example-flows.json" target="_blank">Download</a>)
<img src="https://raw.githubusercontent.com/freakent/node-red-contrib-sunevents/v3/docs/flow-diagram-2.png">

<h2><a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=R4Y63PPPD4CGG&source=url">Say Thanks</a></h2>
Expand All @@ -167,7 +179,7 @@ <h2><a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_i
<!-- Finally, the node type is registered along with all of its properties -->
<!-- The example below shows a small subset of the properties that can be set-->
<script type="text/javascript">
RED.nodes.registerType('sun-events',{
RED.nodes.registerType('sun events',{
category: 'input', // the palette category
defaults: { // defines the editable properties of the node
testmode: {value:"N"},
Expand All @@ -184,7 +196,7 @@ <h2><a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_i
outputs:1, // set the number of outputs - 0 to n
icon: "white_golden_sun.png", //"white-globe.png", // set the icon (held in public/icons)
label: function() { // sets the default label contents
return this.name||"sun-events";
return this.name||"sun events";
},
labelStyle: function() { // sets the class to apply to the label
return this.name ? "" : "node_label_italic";
Expand Down
4 changes: 2 additions & 2 deletions lib/sun-events-node.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Description:
* node-red-contrib-sunevents
* A node for node-red that generates events based on the location of the Sun
* at the appropriate time of day.
*
Expand Down Expand Up @@ -106,7 +106,7 @@ module.exports = function(RED) {
// Register the node by name. This must be called before overriding any of the
// Node functions.

RED.nodes.registerType("sun-events", SunEventsNode, {
RED.nodes.registerType("sun events", SunEventsNode, {
credentials: {
latitude: { type: "text" },
longitude: { type: "text" }
Expand Down
2 changes: 1 addition & 1 deletion lib/sun-events.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Description:
* node-red-contrib-sunevents
* A node for node-red that generates events based on the location of the Sun
* at the appropriate time of day.
*
Expand Down
17 changes: 6 additions & 11 deletions spec/sun-events-node-spec.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*
* This module provides a thin event emitting wrapper around the excellent SunCalc Module.
* node-red-contrib-sunevents
* This module provides a thin event emitting wrapper around the excellent SunCalc Module.
*
* Module Dependencies
* - node-red (https://nodered.org/)
* - SunCalc (https://github.com/mourner/suncalc)
* - Luxon (http://moment.github.io./luxon)
* - uuid (https://www.npmjs.com/package/uuid)
* - debug (https://www.npmjs.com/package/debug)
**/
const helper = require("node-red-node-test-helper")
const SunEventsNode = require("../lib/sun-events-node.js")
Expand All @@ -44,7 +39,7 @@ describe('sun-events Node', function () {
});

it('should be loaded', function (done) {
let flow = [{ id: "n1", type: "sun-events", name: "test name" }]
let flow = [{ id: "n1", type: "sun events", name: "test name" }]
helper.load(SunEventsNode, flow, function () {
try {
var n1 = helper.getNode("n1")
Expand All @@ -57,7 +52,7 @@ describe('sun-events Node', function () {
});

it('should initialise a set of sun events', function (done) {
var flow = [{ id: "n1", type: "sun-events", name: "test name", wires: [["n2"]] }, { id: "n2", type: "helper" }];
var flow = [{ id: "n1", type: "sun events", name: "test name", wires: [["n2"]] }, { id: "n2", type: "helper" }];
helper.load(SunEventsNode, flow, function () {
var n1 = helper.getNode("n1");
var n2 = helper.getNode("n2");
Expand All @@ -79,7 +74,7 @@ describe('sun-events Node', function () {
it('should initialise a set of sun events with lat and lng as strings', function (done) {
const test_lat_str = "51.501364"
const test_lng_str = "-0.1440787"
const flow = [{ id: "n1", type: "sun-events", name: "test name", wires: [["n2"]] }, { id: "n2", type: "helper" }];
const flow = [{ id: "n1", type: "sun events", name: "test name", wires: [["n2"]] }, { id: "n2", type: "helper" }];
helper.load(SunEventsNode, flow, function () {
let n2 = helper.getNode("n2");
let n1 = helper.getNode("n1");
Expand All @@ -100,7 +95,7 @@ describe('sun-events Node', function () {

it('should use lat and long from node configuration if none supplied in msg.payload', function(done) {
const test_credentials = { "n1": {'latitude': "51.501364", 'longitude': '-0.1440787' } }
const flow = [{ id: "n1", type: "sun-events", name: "test name", wires: [["n2"]] }, { id: "n2", type: "helper" }];
const flow = [{ id: "n1", type: "sun events", name: "test name", wires: [["n2"]] }, { id: "n2", type: "helper" }];
helper.load(SunEventsNode, flow, test_credentials, function () {
let n1 = helper.getNode("n1");
let n2 = helper.getNode("n2");
Expand Down
10 changes: 2 additions & 8 deletions spec/sun-events-spec.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,8 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*
* This module provides a thin event emitting wrapper around the excellent SunCalc Module.
*
* Module Dependencies
* - node-red (https://nodered.org/)
* - SunCalc (https://github.com/mourner/suncalc)
* - Luxon (http://moment.github.io./luxon)
* - uuid (https://www.npmjs.com/package/uuid)
* - debug (https://www.npmjs.com/package/debug)
* node-red-contrib-sunevents
* This module provides a thin event emitting wrapper around the excellent SunCalc Module.
**/

const { DateTime } = require('luxon')
Expand Down

0 comments on commit d81c246

Please sign in to comment.