node-red-contrib-knx-ultimate 3.1.5 → 3.1.6

package/CHANGELOG.md

@@ -6,6 +6,11 @@
 
 # CHANGELOG
 
+**Version 3.1.6** - August 2024<br/>
+- KNX Node: KNX Function: added "self", "toggle" and "setGAValue" function. See the help.<br/>
+- KNX Node: KNX Function: the code runs now in async/await mode.<br/>
+- The wiki has been revamped and will be implemented with HUE samples, in the upcoming release.<br/>
+
 **Version 3.1.5** - August 2024<br/>
 - KNX Node: fixed some UI glitches while switching from universal mode to 3-level group Group Address.<br/>
 - KNX Function code editor: exited BETA.<br/>

package/README.md

@@ -66,17 +66,12 @@ msg.payload = {red:255, green:200, blue:30} // Put some colors in our life
 
 <br/>
 
-## LESSONS FROM BEGINNER TO CERTIFIED KNX-ULTIMATE GURU STATUS
+## YOUTUBE CHANNEL
 
-* <a href="https://youtu.be/4rjrMqszhP8" target="_blank">Lesson 01 - Introduction to KNX Device<br/>
-<img width="200px" src="https://img.youtube.com/vi/4rjrMqszhP8/0.jpg" ></a>
-
-* <a href="https://youtu.be/sRW5sHPnYi0" target="_blank">Lesson 02 - Working with ETS file importer<br/>
-<img width="200px" src="https://img.youtube.com/vi/sRW5sHPnYi0/0.jpg" ></a>
-
-
-[More to come...](https://github.com/Supergiovane/node-red-contrib-knx-ultimate)
+<a href="https://www.youtube.com/playlist?list=PL9Yh1bjbLAYpfy1Auz6CKDfXUusgMwOQr" target="_blank"><br/>
+<img width="200px" src="https://raw.githubusercontent.com/Supergiovane/node-red-contrib-knx-ultimate/master/img/youtube-logo.jpeg" ></a>
 
+Please subscribe to the [Youtube channel](https://www.youtube.com/playlist?list=PL9Yh1bjbLAYpfy1Auz6CKDfXUusgMwOQr) and watch the node in action. 
 
 <br/>
 <br/>
@@ -84,7 +79,6 @@ msg.payload = {red:255, green:200, blue:30} // Put some colors in our life
 ## DOCUMENTATION
 
 * [Wiki and Help](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/wiki)
-* [Youtube channel](https://www.youtube.com/playlist?list=PL9Yh1bjbLAYpfy1Auz6CKDfXUusgMwOQr)
 * [FAQ + Troubleshoot](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/wiki/5.-FAQ-Troubleshoot)
 * [Security best practices](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/wiki/SECURITY)
 

package/nodes/knxUltimate.html

@@ -782,7 +782,8 @@
 <br/>
 <br/>
 
-**Advanced options**
+## TAB Advanced options
+
 |Property|Description|
 |--|--|
 ||**General properties**|
@@ -805,7 +806,7 @@
 <br/>
 <br/>
 
-**KNX Function**
+## TAB KNX Function
 
 You can use Javascript to modify the behaviour of the input msg coming from the flow and the output telegram sent to the KNX bus.  
 The embedded code editor provides useful objects and functions to retrieve the value of all group addresses, both with the imported ETS file and without (specifying the datapoint).  
@@ -818,15 +819,18 @@ If enabled, "f(x)" indication will be added to node's name.
 
 <br/>
 
-### From KNX BUS to node's OUTPUT PIN
-
-List of object and functions you can use in the code
+### List of common object and functions you can use in the code
 
-: msg (object) : The current msg object received by the node from the flow. 
-: getGAValue (string GA , optional string DPT) : The function to get the specified GA's value, for example **'1/0/1'**, or also **'1/0/1 Bed table light'** (All text after a blank space will be ignored by the function. This is useful if you want to add the GA name as a reminder. With the ETS file imported, you can also copy and paste the GA and GA Name directly from the **Search GA** field.). **DPT** is optional if you've imported the ETS file, otherwise you must specify it, for example '1.001'. 
+: msg (object) : The current msg object received by the node . 
+: getGAValue (string GA, optional string DPT) : Get the specified GA's value, for example **'1/0/1'**, or also **'1/0/1 Bed table light'** (All text after a blank space will be ignored by the function. This is useful if you want to add the GA name as a reminder. With the ETS file imported, you can also copy and paste the GA and GA Name directly from the **Search GA** field.). **DPT** is optional if you've imported the ETS file, otherwise you must specify it, for example '1.001'. 
+: setGAValue (string GA, any value, optional string DPT) : Set the specified GA's value. The GA con be wrote for example **'1/0/1'**, or also **'1/0/1 Bed table light'** (All text after a blank space will be ignored by the function. This is useful if you want to add the GA name as a reminder. With the ETS file imported, you can also copy and paste the GA and GA Name directly from the **Search GA** field.). The **value** is mandatory, can be a boolean or number or string, **DPT** is optional if you've imported the ETS file, otherwise you must specify it, for example '1.001'. 
+: self (any value) : Set the currend node's value and sends the value to the KNX BUS as well. For example, *self(false)*. Caution using **self** function in the *From KNX BUS to node's OUTPUT PIN* code, because the code will be executed everytime a KNX telegram is received, so you coud have recurrency loops.
+: toggle (nothing) : Toggle the currend node's value and sends the value to the KNX BUS as well. For example, *toggle()*. Caution using **toggle** function in the *From KNX BUS to node's OUTPUT PIN* code, because the code will be executed everytime a KNX telegram is received, so you coud have recurrency loops.
 : node (object) : The node object.
 : RED (Node-Red object) : The Node-Red's RED object.
-: return (msg) : Mandatory `return msg;`, if you want to emit the msg to the KNX BUS. Otherwise, using `return;` will not emit any message. 
+: return (msg) : Mandatory `return msg;`, if you want to emit the message. Otherwise, using `return;` will not emit any message. 
+
+### From KNX BUS to node's OUTPUT PIN
 
 In this sample, we'll send the input msg to the KNX BUS only if another GA has opposite value.  
 We'll turn on the light only if it's status GA is off, and vice versa. 
@@ -840,15 +844,18 @@ if (msg.payload !== statusGA){ // "!==" means "not equal"
 }
 ```
 
-### From KNX BUS to node's ouput PIN
-
-List of object and functions you can use in the code
+Here, if someone switches on the light, we turn on another light 0/1/8 and after 2 seconds we switch off the lamp connected to the node.  
+```javascript
+if (msg.payload){ 
+    setGAValue('0/1/8',true)
+    setTimeout(function() {
+        self(off);
+    }, 2000);
+}
+return msg;
+```
 
-: msg (object) : The current msg object received by the node from the KNX BUS. 
-: getGAValue (string GA , optional string DPT) : The function to get the specified GA's value, for example **'1/0/1'**, or also **'1/0/1 Bed table light'** (All text after a blank space will be ignored by the function. This is useful if you want to add the GA name as a reminder. With the ETS file imported, you can also copy and paste the GA and GA Name directly from the **Search GA** field.). **DPT** is optional if you've imported the ETS file, otherwise you must specify it, for example '1.001'. 
-: node (object) : The node object.
-: RED (Node-Red object) : The Node-Red's RED object.
-: return (msg) : Mandatory `return msg;`, if you want to emit the msg to the flow. Otherwise, using `return;` will not emit any message. 
+### From KNX BUS to node's ouput PIN
 
 In this sample, we'll emit the msg object to the flow, by appending the value of another GA to the output msg.  
 The ouput msg to the flow will have also the external temp in the property `msg.externalTemperature`  
@@ -872,7 +879,8 @@ if (msg.payload === false && getGAValue('0/0/11','1.001') === false){
 <br/>
 <br/>
 
-**Payload sample**
+## TAB Payload sample
+
 |Property|Description|
 |--|--|
 | Sample | This will give it a hint on what to write in an external function node, if you want to control the node via a Node-Red function node. |

package/nodes/knxUltimate.js

@@ -146,13 +146,76 @@ module.exports = function (RED) {
         // Is there a GA in the server's exposedGAs?
         const found = node.server.exposedGAs.find(a => a.ga === _ga);
         if (found !== undefined) {
-          if (_dpt === undefined && found.dpt === undefined) throw new Error('No CSV file imported. Please provide the dpt manually.');
+          if (_dpt === undefined && found.dpt === undefined) {
+            const errM = 'knxUltimate: getGaValue: node ID:' + node.id + ' ' + 'No CSV file imported. Please provide the dpt manually';
+            RED.log.error(errM);
+            if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(errM);
+            return;
+          };
           return dptlib.fromBuffer(found.rawValue, dptlib.resolve(_dpt || found.dpt));
         } else {
-          throw new Error('Group Address not yet read, try later.');
+          const errM = 'knxUltimate: getGaValue: node ID:' + node.id + ' ' + 'Group Address not yet read, try later.';
+          RED.log.error(errM);
+          if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(errM);
+          return;
+        }
+      } catch (error) {
+        const errM = 'knxUltimate: getGaValue: node ID:' + node.id + ' ' + error.stack;
+        RED.log.error(errM);
+        if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(errM);
+      }
+    }
+    // Used in the KNX Function TAB
+    let setGAValue = function setGAValue(_ga = undefined, _value = undefined, _dpt = undefined) {
+      try {
+        if (_ga === undefined) return;
+        // The GA can have the devicename as well, separated by a blank space (1/1/0 light table ovest),
+        // I must take the GA only
+        const blankSpacePosition = _ga.indexOf(" ");
+        if (blankSpacePosition > -1) _ga = _ga.substring(0, blankSpacePosition);
+        if (_dpt === undefined) {
+          // Try getting dpt from ETS CSV
+          const found = node.server.exposedGAs.find(a => a.ga === _ga);
+          if (found === undefined || found.dpt === undefined) {
+            const errM = 'knxUltimate: setGAValue: node ID:' + node.id + ' ' + 'No CSV file imported. Please provide the dpt manually';
+            RED.log.error(errM);
+            if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(errM);
+            return;
+          }
         }
+        node.server.writeQueueAdd({
+          grpaddr: _ga, payload: _value, dpt: _dpt, outputtype: 'write', nodecallerid: node.id,
+        });
+      } catch (error) {
+        const errM = 'knxUltimate: setGAValue: node ID:' + node.id + ' ' + error.stack;
+        RED.log.error(errM);
+        if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(errM);
+      }
+    }
+    // Used in the KNX Function TAB
+    let self = function self(_value) {
+      try {
+        node.server.writeQueueAdd({
+          grpaddr: node.topic, payload: _value, dpt: node.dpt, outputtype: 'write', nodecallerid: node.id,
+        });
       } catch (error) {
-        throw error;
+        const errM = 'knxUltimate: self: node ID:' + node.id + ' ' + error.stack;
+        RED.log.error(errM);
+        if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(errM);
+      }
+    }
+    // Used in the KNX Function TAB
+    let toggle = function toggle() {
+      if (node.currentPayload === true || node.currentPayload === false) {
+        try {
+          node.server.writeQueueAdd({
+            grpaddr: node.topic, payload: !node.currentPayload, dpt: node.dpt, outputtype: 'write', nodecallerid: node.id,
+          });
+        } catch (error) {
+          const errM = 'knxUltimate: toggle: node ID:' + node.id + ' ' + error.stack;
+          RED.log.error(errM);
+          if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(errM);
+        }
       }
     }
 
@@ -176,14 +239,16 @@ module.exports = function (RED) {
       // #region "Inject the msg to the JS code, then output msg to the flow"
       // -+++++++++++++++++++++++++++++++++++++++++++
       if (node.receiveMsgFromKNXCode !== undefined) {
-        try {
-          let receiveMsgFromKNXCode = new Function('msg', 'getGAValue', 'node', 'RED', node.receiveMsgFromKNXCode)
-          msg = receiveMsgFromKNXCode(msg, getGAValue, node, RED);
-        } catch (error) {
-          RED.log.error('knxUltimate: receiveMsgFromKNXCode: node ID:' + node.id + ' ' + error.message);
-          if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(`knxUltimate: receiveMsgFromKNXCode: node id ${node.id} ` || ' ' + error.stack);
-          return;
-        }
+        (async () => {
+          try {
+            let receiveMsgFromKNXCode = new Function('msg', 'getGAValue', 'node', 'RED', 'self', 'toggle', 'setGAValue', node.receiveMsgFromKNXCode)
+            msg = await receiveMsgFromKNXCode(msg, getGAValue, node, RED, self, toggle, setGAValue);
+          } catch (error) {
+            RED.log.error('knxUltimate: receiveMsgFromKNXCode: node ID:' + node.id + ' ' + error.message);
+            if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(`knxUltimate: receiveMsgFromKNXCode: node id ${node.id} ` || ' ' + error.stack);
+            return;
+          }
+        })();
       }
       // -+++++++++++++++++++++++++++++++++++++++++++
       //#endregion
@@ -239,19 +304,23 @@ module.exports = function (RED) {
       // #region "Inject the msg to the JS code, then output msg to the flow"
       // -+++++++++++++++++++++++++++++++++++++++++++
       if (node.sendMsgToKNXCode !== undefined) {
-        try {
-          let sendMsgToKNXCode = new Function('msg', 'getGAValue', 'node', 'RED', node.sendMsgToKNXCode)
-          msg = sendMsgToKNXCode(msg, getGAValue, node, RED);
-          if (msg === undefined) return;
-        } catch (error) {
-          RED.log.error('knxUltimate: sendMsgToKNXCode: node ID:' + node.id + ' ' + error.message);
-          if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(`knxUltimate: sendMsgToKNXCode: node id ${node.id} ` || ' ' + error.stack);
-          return;
-        }
+        (async () => {
+          try {
+            let sendMsgToKNXCode = new Function('msg', 'getGAValue', 'node', 'RED', 'self', 'toggle', 'setGAValue', node.sendMsgToKNXCode)
+            msg = await sendMsgToKNXCode(msg, getGAValue, node, RED, self, toggle, setGAValue);
+            if (msg === undefined) return;
+          } catch (error) {
+            RED.log.error('knxUltimate: sendMsgToKNXCode: node ID:' + node.id + ' ' + error.message);
+            if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(`knxUltimate: sendMsgToKNXCode: node id ${node.id} ` || ' ' + error.stack);
+            return;
+          }
+        })();
       }
       // -+++++++++++++++++++++++++++++++++++++++++++
       //#endregion
 
+
+
       // 25/07/2019 if payload is read or the Telegram type is set to "read", do a read, otherwise, write to the bus
       if ((msg.hasOwnProperty('readstatus') && msg.readstatus === true) || node.outputtype === 'read') {
         // READ: Send a Read request to the bus

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=16.0.0"
   },
-  "version": "3.1.5",
+  "version": "3.1.6",
   "description": "Control your KNX intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control and ETS group address importer. Easy to use and highly configurable.",
   "dependencies": {
     "binary-parser": "2.2.1",

package/resources/KNXFunctionCodeSnippets.js

@@ -6,7 +6,8 @@ const statusGA = getGAValue('x/x/x','1.001');
 if (msg.payload !== statusGA){ // " !==" means " not equal"
     return msg;
  }else{
-// Both values are identical, so i don't send the msg. 
+// Both values are identical, so i don't send the msg.
+    node.status({fill:"grey",shape:"dot",text:"Not sent"}); 
     return; 
 }`;