From d81c2465b8135482c2ced5f9efd0fd9594080499 Mon Sep 17 00:00:00 2001
From: = <=>
Date: Sun, 7 Mar 2021 10:28:16 +0000
Subject: [PATCH] final tweaks to make upgrading from v2 easier

---
 README.md                    | 12 +++++--
 lib/sun-events-node.html     | 62 +++++++++++++++++++++---------------
 lib/sun-events-node.js       |  4 +--
 lib/sun-events.js            |  2 +-
 spec/sun-events-node-spec.js | 17 ++++------
 spec/sun-events-spec.js      | 10 ++----
 6 files changed, 58 insertions(+), 49 deletions(-)

diff --git a/README.md b/README.md
index 2b44c84..e4e4a5a 100644
--- a/README.md
+++ b/README.md
@@ -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.
 
 
diff --git a/lib/sun-events-node.html b/lib/sun-events-node.html
index 5836810..e1d902e 100644
--- a/lib/sun-events-node.html
+++ b/lib/sun-events-node.html
@@ -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.                                       -->
@@ -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>
@@ -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>
 
@@ -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 
@@ -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>
@@ -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"},
@@ -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";
diff --git a/lib/sun-events-node.js b/lib/sun-events-node.js
index ffbb800..2152480 100644
--- a/lib/sun-events-node.js
+++ b/lib/sun-events-node.js
@@ -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. 
  *
@@ -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" }
diff --git a/lib/sun-events.js b/lib/sun-events.js
index 67b8860..f217831 100644
--- a/lib/sun-events.js
+++ b/lib/sun-events.js
@@ -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. 
  *
diff --git a/spec/sun-events-node-spec.js b/spec/sun-events-node-spec.js
index bfa19e7..8420064 100644
--- a/spec/sun-events-node-spec.js
+++ b/spec/sun-events-node-spec.js
@@ -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")
@@ -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")
@@ -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");
@@ -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");
@@ -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");
diff --git a/spec/sun-events-spec.js b/spec/sun-events-spec.js
index 41f9fac..56a8d02 100644
--- a/spec/sun-events-spec.js
+++ b/spec/sun-events-spec.js
@@ -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')