node-red-contrib-eskomsepush 0.0.6 → 0.0.8

package/README.md

@@ -4,35 +4,59 @@
 
 A node for retrieving info from the [EskomSePush API](https://eskomsepush.gumroad.com/l/api).
 
-The EskomSePush-API node gives the tools to make working with the load shedding in South Africa as easy as possible.
+The EskomSePush-API node makes it easier for South African users to incorporate the load shedding schedules into their flows.
 
-First you need to configure the node by entering the license key and entering the correct area.
+### Summary
+
+The node must be configured by entering the license key and the correct area id (which needs to fetched from the API).
 
 Once deployed, the node will fetch the data from EskomSePush every hour. As every fetch from the API takes 2 calls, the 50 free queries per day on a free account should suffice. Every ten minutes the API status is checked to see how many queries you have left.
 
-Internally the node checks every minute if a schedule is currently active or not. It will also output a message on the first deployment.
+Internally, the node checks every minute if a schedule is currently active or not. It will also output a message on the first deployment.
 
 ![EskomsePush Victron MinSOC](img/eskomsepush-victron-minsoc.png)
 
-The node has been made to work well together with the [@victronenergy/node-red-contrib-victron](https://flows.nodered.org/node/@victronenergy/node-red-contrib-victron) nodes. One of the main ones being the
-ESS control node for setting the MinSoc, based on the currently active stage. You can find the
-example flow for this via importing the [victron-minsoc-stage-based.json](examples/victron-minsoc-stage-based.json) example.
+The node has been made to work well together with the [@victronenergy/node-red-contrib-victron](https://flows.nodered.org/node/@victronenergy/node-red-contrib-victron) nodes. The ESS control node for setting the Minimum State of Charge is an obvious combination to enable a user to change the MinSoC value based on the currently active loadshedding stage.
+
+You can find the example flow for this via importing the [victron-minsoc-stage-based.json](examples/victron-minsoc-stage-based.json) file.
 
 ### Configuration
 
-First you will need a _licence key_. You can get one from [here](https://eskomsepush.gumroad.com/l/api), by subsribing to the Free model. Note that this is for personal use only.
+First you will need a _licence key_. You can get one from [here](https://eskomsepush.gumroad.com/l/api), by subscribing to the Free model. Note that this is for personal use only.
 
 ![EskomsePush configuration](img/eskomsepush-configuration.png)
 
-Next you need to insert the correct area. Once you entered 5 characters (and a valid license is used), the API will be used for searching the correct area. Do note that this will cost some of the daily queries. If you don't want that and you already know the id of the area, fill out the area first and then the license key.
+Next you need to insert the correct area id.  This can be done by either:
+
+* making a manual API call to search for the area and paste the id from the API response into the area field in the node; or
+* by first entering a valid API license key into the node, and then entering at least 5 characters, the node will use the API to search for the area. Note that this will consume some of the daily API quota.
+
+If you don't want to use API quota by searching, and you already know the id of the area, fill out the area first and then the license key.
 
-Then you need to fill out which status to follow. This can be either _National_ (eskom) or _Capetown_.
+To fetch the area id manually, make an `areas_search` API call using your API license key `token`, a word of search `text`.  In the response returned by the API, copy the `id` value of the matching area.
 
-If the _test_ checkbox has been selected, test data for the area will be fetched instead of the actual schedule. This is useful when debugging.
+In the example below (on MacOS), `curl` is used to query the API and the search text value is 'ballito' (the license key token is invalid and must be replaced with a valid key).  The area id value that will be used from this example is `eskmo-15-ballitokwadukuzakwazulunatal`:
+
+```
+% curl --location --request GET 'https://developer.sepush.co.za/business/2.0/areas_search?text=ballito' --header 'token: 2DFB82AC-46254F6E-A68B26A4-8DF1303E'
+{
+  "areas":[
+      {"id":"eskmo-15-ballitokwadukuzakwazulunatal","name":"Ballito (15)","region":"Eskom Municipal, Kwadukuza, Kwazulu-Natal"},
+      {"id":"eskdo-15-ballitokwadukuzakwazulunatal","name":"Ballito (15)","region":"Eskom Direct, KwaDukuza, KwaZulu-Natal"}
+   ]
+}
+```
+
+Then you need to fill out which status to follow. This can be either _National_ (Eskom) or _Cape Town_.
+
+If the _test_ checkbox has been selected, test data for the specified area will be fetched instead of the actual schedule. This is useful when debugging.
 
 ### Outputs
 
-The first output of the node outputs a boolean value. When load shedding is active, the `msg.payload` will be _true_, otherwise it will be _false_. It also outputs some extra values:  
+The note has two outputs. In most cases, the first (upper) output will be used.
+
+The first output of the node outputs a boolean value and some related data. When load shedding is active, the `msg.payload` will be _true_, otherwise it will be _false_. It also outputs some extra values:
+
 ```
 {
   "payload":false,
@@ -72,7 +96,7 @@ The first output of the node outputs a boolean value. When load shedding is acti
 }
 ```
 
-The start and end objects contain the time as unix timestamp in the Javascript format (milliseconds after the epoch).
+The start and end objects contain the time of next load shedding period as unix timestamps in the Javascript format (milliseconds after the epoch).
 
 The second output shows `msg.stage` and `msg.schedule`, containing the latest information as retrieved from the API. This output is mainly useful when writing your own functions and logic.
 
@@ -82,12 +106,12 @@ The status will show the situation regarding the API calls and when the next
 shedding wil start or end.  It also shows the count of API calls that have been
 done and how many are left. This updates every 10 minutes.
 
-
 ### Documentation
 
 Documentation for the API can be found [here](https://documenter.getpostman.com/view/1296288/UzQuNk3E)
 
 When quota has been exceeded:
+
 ```
 {"error":"Quota Exceeded - Reminder: you can use the 'test' query param for development. Check the docs! \ud83d\ude05"}
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-eskomsepush",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Node-RED interface for the Eskomsepush API",
   "main": "index.js",
   "scripts": {

package/src/nodes/eskomsepush.js

@@ -5,11 +5,40 @@ module.exports = function (RED) {
   let EskomSePushAPI = null
   let Stage = null
   let Schedule = null
+  let LoadShedding = null
   let lastStatusUpdate = new Date()
   let lastStageUpdate = new Date()
   let lastScheduleUpdate = new Date()
-  let fill = 'green'
-  let shape = 'ring'
+
+
+  function updateStatus(node) {
+    let fill = 'green'
+    let shape = 'ring'
+    let statusText = ''
+    if (Stage && Stage.status && Stage.status[node.config.statusselect].stage) {
+      statusText += 'Stage '+Stage.status[node.config.statusselect].stage
+    }
+    if (LoadShedding && LoadShedding.active && LoadShedding.next && LoadShedding.next.end) {
+      statusText += ' - ' + new Date(LoadShedding.next.end).toLocaleTimeString()
+      fill = 'red'
+      if (LoadShedding.type === 'event') {
+        shape = 'dot'
+      }
+    } else {
+      if (LoadShedding && LoadShedding.next && LoadShedding.next.start) {
+        statusText += ' - ' + new Date(LoadShedding.next.start).toLocaleTimeString()
+      }
+    }
+    if (EskomSePushAPI) {
+      statusText += ` (API: ${EskomSePushAPI.allowance.count}/${EskomSePushAPI.allowance.limit})`
+      if (EskomSePushAPI.allowance.count >= EskomSePushAPI.allowance.limit) {
+        fill = 'red'    
+      }
+    }
+    node.status({
+      fill, shape, text: statusText
+    })
+  }
 
   function checkAllowance (node) {
     const options = {}
@@ -17,6 +46,7 @@ module.exports = function (RED) {
     axios.get('https://developer.sepush.co.za/business/2.0/api_allowance',
       { params: options, headers }).then(function (response) {
       EskomSePushAPI = response.data
+      updateStatus(node)
     })
       .catch(error => {
         node.warn({ error: error.message })
@@ -29,6 +59,7 @@ module.exports = function (RED) {
     axios.get('https://developer.sepush.co.za/business/2.0/status',
       { params: options, headers }).then(function (response) {
       Stage = response.data
+      updateSheddingStatus(node)
     })
       .catch(error => {
         node.warn({ error: error.message })
@@ -46,15 +77,15 @@ module.exports = function (RED) {
       { params: options, headers }).then(function (response) {
       Schedule = response.data
       Schedule.info.area = node.config.area
+      updateSheddingStatus(node)
     })
       .catch(error => {
         node.warn({ error: error.message })
       })
   }
 
-  function updateStatus (node) {
+  function updateSheddingStatus (node) {
     const now = new Date()
-    let statusText = ''
 
     if (EskomSePushAPI === null || (now.getTime() - lastStatusUpdate.getTime()) > 600000) {
       checkAllowance(node)
@@ -66,27 +97,24 @@ module.exports = function (RED) {
     }
 
     if (EskomSePushAPI && EskomSePushAPI.allowance.count >= EskomSePushAPI.allowance.limit) {
-      statusText += 'API quota reached'
-      fill = 'red'
-      shape = 'dot'
-    } else {
-      if (Stage === null || (now.getTime() - lastStageUpdate.getTime()) > 3600000) {
-        node.status({ fill: 'yellow', shape, text: 'Fetching stage' })
-        checkStage(node)
-        lastStageUpdate = now
-      }
+      updateStatus(node)
+      return
+    }
 
-      if (Schedule === null || (now.getTime() - lastScheduleUpdate.getTime()) > 3600000) {
-        node.status({ fill: 'yellow', shape, text: 'Fetching schedule' })
-        checkSchedule(node)
-        lastScheduleUpdate = now
-      }
+    if (Stage === null || (now.getTime() - lastStageUpdate.getTime()) > 3600000) {
+      checkStage(node)
+      lastStageUpdate = now
+    }
+
+    if (Schedule === null || (now.getTime() - lastScheduleUpdate.getTime()) > 3600000) {
+      checkSchedule(node)
+      lastScheduleUpdate = now
     }
 
     if (Stage && Schedule && EskomSePushAPI) {
       const stage = Stage.status[node.config.statusselect].stage
       const nowtime = now.toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit' })
-      const LoadShedding = {
+      LoadShedding = {
         schedule: {
           next: {},
           active: false
@@ -97,11 +125,12 @@ module.exports = function (RED) {
         },
         checked: nowtime
       }
-      fill = 'green'
       for (const schedule of Schedule.schedule.days[0].stages[stage - 1]) {
         if (nowtime >= schedule.split('-')[0] && nowtime <= schedule.split('-')[1]) {
           LoadShedding.schedule = {
-            active: true,
+            active: true
+          }
+          LoadShedding.schedule.next = {
             start: Date.parse(Schedule.schedule.days[0].date + ' ' + schedule.split('-')[0]),
             end: Date.parse(Schedule.schedule.days[0].date + ' ' + schedule.split('-')[1])
           }
@@ -113,7 +142,7 @@ module.exports = function (RED) {
           }
         }
       }
-      if (Object.keys(LoadShedding.schedule.next).length === 0) {
+      if (!LoadShedding.schedule.active && Object.keys(LoadShedding.schedule.next).length === 0) {
         const s = Schedule.schedule.days[1].stages[stage - 1][0]
         LoadShedding.schedule.next = {
           start: Date.parse(Schedule.schedule.days[1].date + ' ' + s.split('-')[0]),
@@ -124,13 +153,13 @@ module.exports = function (RED) {
         start: Date.parse(Schedule.events[0].start),
         end: Date.parse(Schedule.events[0].end)
       }
-      if (nowtime >= LoadShedding.event.start && nowtime < LoadShedding.event.end) {
+      if (now >= LoadShedding.event.next.start && now < LoadShedding.event.next.end) {
         LoadShedding.event.active = true
-        LoadShedding.start = LoadShedding.event.start
-        LoadShedding.end = LoadShedding.event.end
       }
 
-      if (!LoadShedding.schedule.next.start || !LoadShedding.event.next.start) {
+      if (!LoadShedding.schedule | !LoadShedding.schedule.next ||
+         !LoadShedding.event || !LoadShedding.event.next ||
+         !LoadShedding.schedule.next.start || !LoadShedding.event.next.start) {
         node.warn('Unable to find next scheduled event and/or schedule')
         node.warn(LoadShedding)
         return
@@ -143,14 +172,18 @@ module.exports = function (RED) {
         LoadShedding.next.type = 'event'
       }
 
-      statusText += 'Stage '+stage
       LoadShedding.active = (LoadShedding.schedule.active || LoadShedding.event.active)
-      if (LoadShedding.active) {
-        statusText += ' - ' + new Date(LoadShedding.next.end).toLocaleTimeString()
-        fill = 'red'
-      } else {
-        statusText += ' - ' + new Date(LoadShedding.next.start).toLocaleTimeString()
+      if (LoadShedding.schedule.active) {
+        LoadShedding.type = 'schedule'
+        LoadShedding.start = LoadShedding.schedule.next.start
+        LoadShedding.end = LoadShedding.schedule.next.end
+      }
+      if (LoadShedding.event.active) {
+        LoadShedding.type = 'event'
+        LoadShedding.start = LoadShedding.event.next.start
+        LoadShedding.end = LoadShedding.event.next.end
       }
+
       node.send([{
         payload: LoadShedding.active,
         LoadShedding,
@@ -168,13 +201,7 @@ module.exports = function (RED) {
       }])
     }
 
-    if (EskomSePushAPI) {
-      statusText += ` (API: ${EskomSePushAPI.allowance.count}/${EskomSePushAPI.allowance.limit})`
-    }
-
-    node.status({
-      fill, shape, text: (statusText || 'Ok')
-    })
+    updateStatus(node)
   }
 
   function EskomSePush (config) {
@@ -183,9 +210,9 @@ module.exports = function (RED) {
     const node = this
     node.config = config
 
-    updateStatus(node)
+    updateSheddingStatus(node)
     const intervalId = setInterval(function () {
-      updateStatus(node)
+      updateSheddingStatus(node)
     }, 60000)
 
     node.on('close', function () {