node-red-contrib-eskomsepush 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Victron Energy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+### EskomSePush API
+
+![EskomsePush API](img/eskomsepush-flow.png)
+
+A node for retrieving info from the EskomSePush API.
+
+The EskomSePush-API node gives the tools to make working with the load shedding in South Africa as easy as possible.
+
+First you need to configure the node by entering the license key and entering the correct area.
+
+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.
+
+### 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.
+
+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.
+
+Then you need to fill out which status to follow. This can be either _National_ (eskom) or _Capetown_.
+
+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.
+
+### 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:  
+```
+{
+  "payload":false,
+  "LoadShedding":{
+    "schedule":{
+       "next":{
+         "start":1683561600000,
+         "end":1683570600000,
+         "type":"schedule"
+       },
+       "active":false
+    },
+    "event":{
+      "next":{
+        "start":1683561600000,
+        "end":1683570600000
+      },
+      "active":false
+    },
+    "checked":"13:35",
+    "next":{
+      "start":1683561600000,
+      "end":1683570600000,
+      "type":"schedule"
+    },
+    "active":false
+  },
+  "stage":"5",
+  "statusselect":"capetown",
+  "api":{
+    "count":12,
+    "limit":50,
+    "lastStatusUpdate":"Mon May 08 2023 13:34:30 GMT+0200 (Central European Summer Time)",
+    "lastScheduleUpdate":"Mon May 08 2023 13:34:30 GMT+0200 (Central European Summer Time)"
+  },
+  "\_msgid":"6e77b593b7f9eda4"
+}
+```
+
+The start and end objects contain the time as unix timestamp 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.
+
+### Status
+
+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/examples/simple-api-query.flow

@@ -0,0 +1,56 @@
+[
+    {
+        "id": "d083105e39f8ba68",
+        "type": "debug",
+        "z": "614c1c00b0cf1810",
+        "name": "Load shedding",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 340,
+        "y": 60,
+        "wires": []
+    },
+    {
+        "id": "1d3e18f144e4911a",
+        "type": "debug",
+        "z": "614c1c00b0cf1810",
+        "name": "Schedule and events",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 360,
+        "y": 100,
+        "wires": []
+    },
+    {
+        "id": "854cb9223eb1d95f",
+        "type": "eskomsepush",
+        "z": "614c1c00b0cf1810",
+        "name": "",
+        "licensekey": "",
+        "area": "capetown-3-helderbergvillage",
+        "statusselect": "capetown",
+        "test": false,
+        "x": 130,
+        "y": 80,
+        "wires": [
+            [
+                "d083105e39f8ba68"
+            ],
+            [
+                "1d3e18f144e4911a"
+            ]
+        ]
+    }
+]

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "node-red-contrib-eskomsepush",
+  "version": "0.0.1",
+  "description": "Node-RED interface for the Eskomsepush API",
+  "main": "index.js",
+  "scripts": {
+    "test": "standard --fix"
+  },
+  "keywords": [
+    "node-red",
+    "eskomsepush",
+    "loadshedding",
+    "south africa",
+    "scheduled charging",
+    "victron",
+    "ess"
+  ],
+  "author": "Dirk-Jan Faber <dfaber@victronenergy.com>",
+  "license": "MIT",
+  "node-red": {
+    "nodes": {
+      "eskomepush": "./src/nodes/eskomsepush.js"
+    },
+    "version": ">=3.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dirkjanfaber/node-red-contrib-eskomepush"
+  },
+  "dependencies": {
+    "axios": "^1.3.5"
+  },
+  "devDependencies": {
+    "standard": "^17.0.0"
+  },
+  "engines": {
+    "node": ">=14.17.4"
+  }
+}

package/src/nodes/eskomsepush.html

@@ -0,0 +1,185 @@
+<script type="text/javascript">
+    RED.nodes.registerType('eskomsepush',{
+        category: 'network',
+        color: '#ffffff',
+        defaults: {
+            name: {value:""},
+            licensekey: {value:"", validate: RED.validators.regex(/^[0-9A-F\-]{35}$/)},
+            area: {value:""},
+            statusselect: {value:"", validate: RED.validators.regex(/^(eskom|capetown)$/)},
+            test: { value: false }
+        },
+        inputs:0,
+        outputs:2,
+        icon: "eskomsepush.svg",
+        label: function() {
+            return this.name||"EskomSePush API";
+        },
+        oneditprepare: function oneditprepare() {
+
+        }
+    });
+
+    function searchArea() {
+        var input = document.getElementById("node-input-area");
+        var dropdown = document.getElementById("areaDropdown");
+        var licensekey = document.getElementById("node-input-licensekey");
+
+        if (!RED.validators.regex(licensekey.value, /^[0-9A-F\-]{35}$/)) {
+            return
+        }
+
+        if (input.value.length >= 5) {
+            dropdown.innerHTML = "";
+
+            $.ajax({
+                url: '/eskomsepush/search',
+                method: 'GET',
+                data: {
+                    token: licensekey.value,
+                    search: input.value
+                },
+                success: function(response) {
+                    for (var i = 0; i < response.areas.length; i++) {
+                        var option = document.createElement("option");
+                        option.text = response.areas[i].name;
+                        option.value = response.areas[i].id;
+                        dropdown.add(option);
+                    }
+                },
+                error: function(error) {
+                    node.warn(error)
+                }
+            })
+            dropdown.style.display = "block";
+            dropdown.addEventListener("change", function() {
+                input.value = dropdown.value;
+                dropdown.style.display = "none";
+            });
+            input.addEventListener("focusout", function() {
+                dropdown.style.display = "none"
+            })
+        } else {
+            dropdown.style.display = "none";
+        }
+    }
+</script>
+
+<script type="text/html" data-template-name="eskomsepush">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-licensekey"><i class="fa fa-user-secret"></i> License key</label>
+        <input type="password" id="node-input-licensekey" placeholder="License key" required>
+    </div>
+    <div class="form-row">
+        <label for="node-input-area"><i class="fa fa-tag"></i> Area</label>
+        <input type="text" id="node-input-area" placeholder="Area" onkeyup="searchArea()">
+        <select id="areaDropdown" style="display: none;"></select>
+    </div>
+    <div class="form-row">
+        <label style="min-width:190px" for="node-input-test"><i class="fa fa-volume-up"></i> Use test data</label>
+        <input type="checkbox" checked id="node-input-test" style="max-width:30px">
+    </div>
+    <div class="form-row">
+        <label for="node-input-statusselect"><i class="fa fa-location-arrow"></i> Status select</label>
+        <select id="node-input-statusselect" required>
+            <option value="eskom">National (eskom)</option>
+            <option value="capetown">Cape Town</option>
+        </select>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="eskomsepush">
+    <h3 id=""eskomsepushapi>EskomSePush API</h3>
+
+    <p>A node for retrieving info from the EskomSePush API.</p>
+
+<p>The EskomSePush-API node gives the tools to make working with the load shedding
+in South Africa as easy as possible.</p>
+<p>First you need to configure the node by entering the license key and entering
+the correct area.</p>
+<p>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.</p>
+<p>Internally the node checks every minute if a schedule is currently active or not. It
+    will also output a message on the first deployment.</p>
+
+<h3 id="configuration">Configuration</h3>
+
+<p>First you will need a <em>licence key</em>. You can get one from <a href="https://eskomsepush.gumroad.com/l/api">here</a>, by subsribing to the Free model. Note that this is for personal use only.</p>
+<p>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&#39;t want that and you already know the id of the area, fill out the area first and then the license
+key.</p>
+<p>Then you need to fill out which status to follow. This can be either <em>National</em> (eskom) or <em>Capetown</em>.</p>
+<p>If the <em>test</em> checkbox has been selected, test data for the area will be fetched instead of the actual schedule. This is useful when debugging.</p>
+
+<h3 id="outputs">Outputs</h3>
+
+<p>The first output of the node outputs a boolean value. When load shedding is active, the <code>msg.payload</code> will be <em>true</em>, otherwise it will be <em>false</em>. It also outputs some extra values:</p>
+
+<pre>
+{
+  "payload":false,
+  "LoadShedding":{
+    "schedule":{
+       "next":{
+         "start":1683561600000,
+         "end":1683570600000,
+         "type":"schedule"
+       },
+       "active":false
+    },
+    "event":{
+      "next":{
+        "start":1683561600000,
+        "end":1683570600000
+      },
+      "active":false
+    },
+    "checked":"13:35",
+    "next":{
+      "start":1683561600000,
+      "end":1683570600000,
+      "type":"schedule"
+    },
+    "active":false
+  },
+  "stage":"5",
+  "statusselect":"capetown",
+  "api":{
+    "count":12,
+    "limit":50,
+    "lastStatusUpdate":"Mon May 08 2023 13:34:30 GMT+0200 (Central European Summer Time)",
+    "lastScheduleUpdate":"Mon May 08 2023 13:34:30 GMT+0200 (Central European Summer Time)"
+  },
+  "_msgid":"6e77b593b7f9eda4"
+}
+</pre>
+
+<p>The <tt>start</tt> and <tt>end</tt> objects contain the time as unix timestamp in the Javascript format (milliseconds after the epoch).</p>
+
+<p>The second output shows <code>msg.stage</code> and <code>msg.schedule</code>, containing the latest information as retrieved from the API.
+This output is mainly useful when writing your own functions and logic.</p>
+
+<h3 id="status">Status</h3>
+
+<p>The status will show the situation regarding the API calls. It will show the count of API calls that have been done and
+how many are left. This updates every 10 minutes.</p>
+
+<h1 id="documentation">Documentation</h1>
+<p>Documentation for the API can be found <a href="https://documenter.getpostman.com/view/1296288/UzQuNk3E">here</a></p>
+
+</script>
+
+<style>
+input#node-input-area {
+  margin-bottom: 5px;
+}
+select#areaDropdown {
+  position: absolute;
+  left: 120px;
+}
+</style>

package/src/nodes/eskomsepush.js

@@ -0,0 +1,218 @@
+module.exports = function (RED) {
+  'use strict'
+
+  const axios = require('axios')
+  let EskomSePushAPI = null
+  let Stage = null
+  let Schedule = null
+  let lastStatusUpdate = new Date()
+  let lastStageUpdate = new Date()
+  let lastScheduleUpdate = new Date()
+  let LoadShedding = false
+  let fill = 'green'
+  let shape = 'ring'
+  
+  function checkAllowance (node) {
+    const options = {}
+    const headers = { token: node.config.licensekey }
+    axios.get('https://developer.sepush.co.za/business/2.0/api_allowance',
+      { params: options, headers }).then(function (response) {
+        EskomSePushAPI = response.data
+    })
+      .catch(error => {
+        node.warn({ error: error.message })
+      })
+  }
+
+  function checkStage (node) {
+    const options = {}
+    const headers = { token: node.config.licensekey }
+    axios.get('https://developer.sepush.co.za/business/2.0/status',
+      { params: options, headers }).then(function (response) {
+        Stage = response.data
+    })
+      .catch(error => {
+        node.warn({ error: error.message })
+      })
+  }
+
+  function checkSchedule (node) {
+    const options = { id: node.config.area }
+    const headers = { token: node.config.licensekey }
+    let url = 'https://developer.sepush.co.za/business/2.0/area'
+    if (node.config.test) {
+      options.test = 'current'
+    }
+    axios.get(url,
+      { params: options, headers }).then(function (response) {
+        Schedule = response.data
+        Schedule.info.area = node.config.area
+    })
+      .catch(error => {
+        node.warn({ error: error.message })
+      })
+  }
+
+  function updateStatus(node) {
+    const now = new Date();
+    let statusText = ''
+
+    if (EskomSePushAPI === null || (now.getTime() - lastStatusUpdate.getTime()) > 600000) {
+      checkAllowance(node)
+      lastStatusUpdate = now
+    }
+
+    if (Schedule && Schedule.info.area !== node.config.area) {
+      Schedule = null
+    }
+
+    if (EskomSePushAPI && EskomSePushAPI.allowance.count >= EskomSePushAPI.allowance.limit) {
+      statusText += 'API quota reached'
+      fill = 'red'
+      shape = 'dot'
+
+    } else {
+      if (Stage === null || (now.getTime() - lastStatusUpdate.getTime()) > 3600000) {
+        node.status({fill: 'yellow', shape, text: 'Fetching status'})
+        checkStage(node)
+        lastStageUpdate = now
+      }
+
+      if (Schedule === null || (now.getTime() - lastScheduleUpdate.getTime()) > 3600000) {
+        node.status({fill: 'yellow', shape, text: 'Fetching schedule'})
+        checkSchedule(node)
+        lastScheduleUpdate = now
+      }
+    }  
+
+    if (Stage && Schedule && EskomSePushAPI) {
+      let stage = Stage.status[node.config.statusselect].stage
+      let nowtime = now.toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit'})
+      let LoadShedding = {
+        schedule: {
+          next: {},
+          active: false
+        },
+        event: {
+          next: {},
+          active: false
+        },
+        checked: nowtime
+      }
+      fill = 'green'
+      for (let schedule of Schedule.schedule.days[0].stages[stage-1]) {
+        if ( nowtime >= schedule.split('-')[0] && nowtime <= schedule.split('-')[1] ) {
+          LoadShedding.schedule = {
+            active: true,
+            start: Date.parse(Schedule.schedule.days[0].date + ' ' + schedule.split('-')[0]),
+            end: Date.parse(Schedule.schedule.days[0].date + ' ' + schedule.split('-')[1])
+          }
+        }
+        if ( Object.keys(LoadShedding.schedule.next).length === 0 && nowtime < schedule.split('-')[0] ) {
+          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])
+          }
+        }
+      }
+      if (Object.keys(LoadShedding.schedule.next).length === 0) {
+        let s = Schedule.schedule.days[1].stages[stage-1][0]
+        LoadShedding.schedule.next = {
+          start: Date.parse(Schedule.sschedule.days[1].date + s.split('-')[0]),
+          end: Date.parse(Schedule.sschedule.days[1].date + s.split('-')[1])
+        }
+      }
+      LoadShedding.event.next = {
+        start: Date.parse(Schedule.events[0].start),
+        end: Date.parse(Schedule.events[0].end)
+      }
+      if ( nowtime >= LoadShedding.event.start && nowtime < LoadShedding.event.end ) {
+        LoadShedding.event.active = true
+        LoadShedding.start = LoadShedding.event.start
+        LoadShedding.end = LoadShedding.event.end
+      }
+
+      if (!LoadShedding.schedule.next.start || !LoadShedding.event.next.start) {
+        node.warn("Unable to find next scheduled event and/or schedule")
+        return
+      }
+      if (LoadShedding.schedule.next.start <= LoadShedding.event.next.start) {
+        LoadShedding.next = LoadShedding.schedule.next
+        LoadShedding.next.type = 'schedule'
+      } else {
+        LoadShedding.next = LoadShedding.event.next
+        LoadShedding.next.type = 'event'
+      }
+
+      LoadShedding.active = (LoadShedding.schedule.active || LoadShedding.event.active)
+      if (LoadShedding.active) {
+        statusText += 'Until: '+ new Date(LoadShedding.end).toLocaleTimeString()
+        fill = 'red'
+      } else {
+        statusText += 'Next: ' + new Date(LoadShedding.next.start).toLocaleTimeString()
+      }
+      node.send([{ 
+        payload: LoadShedding.active,
+        LoadShedding,
+        stage,
+        statusselect: node.config.statusselect,
+        api: {
+          count: EskomSePushAPI.allowance.count,
+          limit: EskomSePushAPI.allowance.limit,
+          lastStatusUpdate: lastStatusUpdate.toString(),
+          lastScheduleUpdate: lastScheduleUpdate.toString()
+        }
+      }, {
+        stage: Stage,
+        schedule: Schedule }])
+    }
+
+    if (EskomSePushAPI) {
+      statusText += ` (API: ${EskomSePushAPI.allowance.count}/${EskomSePushAPI.allowance.limit})`
+    }
+
+    node.status({
+      fill, shape, text: ( statusText || 'Ok' )
+    })
+  }
+
+  function EskomSePush (config) {
+    RED.nodes.createNode(this, config)
+
+    const node = this
+    node.config = config
+
+    updateStatus(node)
+    const intervalId = setInterval(function () {
+      updateStatus(node)
+    }, 60000)
+
+    node.on('close', function () {
+      clearInterval(intervalId)
+    })
+  }
+
+  RED.nodes.registerType('eskomsepush', EskomSePush)
+
+  RED.httpNode.get('/eskomsepush/search', (req, res) => {
+    if (!req.query || !req.query.token || !req.query.search) {
+      res.setHeader('Content-Type', 'application/json')
+      return res.send('invalid')
+    }
+    const headers = {
+      token: req.query.token
+    }
+    const options = {
+      text: req.query.search
+    }
+
+    res.setHeader('Content-Type', 'application/json')
+    axios.get('https://developer.sepush.co.za/business/2.0/areas_search',
+      { params: options, headers }).then(function (response) {
+      return res.send(response.data)
+    })
+      .catch(error => {
+        return res.send({ error: error.message })
+      })
+  })
+}

package/src/nodes/icons/eskomsepush.svg

@@ -0,0 +1,4 @@
+<svg width="1024" height="1024" viewBox="0 0 1024 1024" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="512" cy="512" r="512" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M418.116 126C396.51 208.249 354.298 358.268 354.298 358.268L469.894 412.544L412.096 568.21L496.587 594.526L430.541 807.246L609.333 568.21L527.504 541.414L655.131 358.268L548.085 318.998L653.067 140.876C803.266 197.97 910.002 343.27 910.002 513.499C910.002 733.585 731.587 912 511.501 912C291.415 912 113 733.585 113 513.499C113 325.573 243.082 168.03 418.116 126Z" fill="#FF4738"/>
+</svg>