node-red-contrib-knx-ultimate 3.0.10 → 3.1.0

package/CHANGELOG.md

@@ -6,6 +6,9 @@
 
 # CHANGELOG
 
+**Version 3.1.0** - August 2024<br/>
+- NEW: KNX Function code editor in the device node: you can now write you own script to handle inbound and outboud KNX messages.<br/>
+
 **Version 3.0.10** - August 2024<br/>
 - Warning: Node-Red version **equals or major than 3.1.1** is needed to run this node.<br/>
 - KNX Auto Responder node (BETA): fixed issue with unused saved values. Please be aware that until the node exits beta, there can be breaking changes.<br/>

package/nodes/knxUltimate-config.js

@@ -107,7 +107,7 @@ module.exports = (RED) => {
     // 15/12/2021
 
     // 05/12/2021 Set the protocol (this is undefined if coming from ild versions
-    if (config.hostProtocol === "Auto") {
+    if (node.hostProtocol === "Auto") {
       // Auto set protocol based on IP
       if (
         node.host.startsWith("224.") ||
@@ -790,8 +790,17 @@ module.exports = (RED) => {
       // 04/04/2021 Supergiovane: save value to node.exposedGAs
       if (typeof _dest === "string" && _rawValue !== undefined && (_evt === "GroupValue_Write" || _evt === "GroupValue_Response")) {
         try {
+          const ret = { ga: _dest, rawValue: _rawValue, dpt: undefined, devicename: undefined };
           node.exposedGAs = node.exposedGAs.filter((item) => item.ga !== _dest); // Remove previous
-          node.exposedGAs.push({ ga: _dest, rawValue: _rawValue }); // add the new
+          if (node.csv !== undefined && node.csv !== '' && node.csv.length !== 0) {
+            // Add the dpt
+            const found = node.csv.find(a => a.ga === _dest);
+            if (found !== undefined) {
+              ret.dpt = found.dpt;
+              ret.devicename = found.devicename;
+            }
+          }
+          node.exposedGAs.push(ret); // add the new
         } catch (error) { }
       }
 

package/nodes/knxUltimate.html

@@ -28,7 +28,9 @@
             formatmultiplyvalue: { value: 1 },
             formatnegativevalue: { value: "leave" },
             formatdecimalsvalue: { value: 999 },
-            passthrough: { value: "no" }
+            passthrough: { value: "no" },
+            outputFunctionCode: { value: "" },
+            inputFunctionCode: { value: "" }
         },
         inputs: 1,
         outputs: 1,
@@ -57,8 +59,6 @@
             var oNodeServer = RED.nodes.node($("#node-input-server").val()); // Store the config-node
             $("#tabs").tabs();
 
-
-
             // 15/09/2020 Supergiovane, set the help sample based on Datapoint
             function knxUltimateDptsGetHelp(_dpt, _forceClose) {
                 if ($("#node-input-server").val() !== "_ADD_" && $("#node-input-server").val() !== '' && _dpt !== null && _dpt !== '') {
@@ -76,7 +76,7 @@
                                     id: 'example-editor',
                                     mode: 'ace/mode/javascript',
                                     value: data.help//this.exampleText
-                                }).renderer.setShowGutter(false);//A.setReadOnly(true).setShowPrintMargin(false);                    
+                                })//.renderer.setShowGutter(false);//A.setReadOnly(true).setShowPrintMargin(false);                    
                                 if (data.helplink !== "") $("#sampleCodeEditor").html("&nbsp<i class=\"fa fa-question-circle\"></i>&nbsp<a target=\"_blank\" href=\"" + data.helplink + "\"><u>Link example of " + _dpt + "</u></a>");
                             } else {
                                 // No help avaiable
@@ -84,7 +84,7 @@
                                     id: 'example-editor',
                                     mode: 'ace/mode/javascript',
                                     value: "Currently, no sample payload is avaiable, sorry."
-                                }).renderer.setShowGutter(false);//B.setReadOnly(true).setShowPrintMargin(false);
+                                })//.renderer.setShowGutter(false);//B.setReadOnly(true).setShowPrintMargin(false);
                                 if (data.helplink !== "") $("#sampleCodeEditor").html("&nbsp<i class=\"fa fa-question-circle\"></i>&nbsp<a target=\"_blank\" href=\"" + data.helplink + "\"><u>Link to wiki</u></a>");
                             }
                         } catch (error) {
@@ -93,6 +93,63 @@
                 }
             }
 
+            node.outputFunctionCodeEditor = RED.editor.createEditor({
+                id: 'outputFunctionCode-editor',
+                mode: 'ace/mode/nrjavascript',
+                value: node.outputFunctionCode
+            });
+            node.inputFunctionCodeEditor = RED.editor.createEditor({
+                id: 'inputFunctionCode-editor',
+                mode: 'ace/mode/nrjavascript',
+                value: node.inputFunctionCode
+            });
+            // Snippets
+            $("#snippetOne").on("click", function (event) {
+                node.outputFunctionCodeEditor.session.setValue(`// @ts-nocheck
+// Replace 'x/x/x' with the real status group address.
+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. 
+    return; 
+}`);
+            });
+            $("#snippetTwo").on("click", function (event) {
+                node.inputFunctionCodeEditor.session.setValue(`// This is a sample of the msg received from the KNX BUS
+const inputMSG = {
+    topic: '0/0/10',
+        devicename: 'Plafoniera soggiorno [switch]',
+            payload: false,
+                payloadmeasureunit: 'unknown',
+                    payloadsubtypevalue: 'Off',
+                        gainfo: {
+        maingroupname: 'Attuatori luci',
+            middlegroupname: 'Luci primo piano',
+                ganame: 'Plafoniera soggiorno [switch]',
+                    maingroupnumber: '0',
+                        middlegroupnumber: '0',
+                            ganumber: '10'
+    },
+    knx: {
+        event: 'GroupValue_Write',
+            dpt: '1.001',
+                dptdesc: 'Switch',
+                    source: '15.15.22',
+                        destination: '0/0/10',
+                            rawValue: 'bufferValue'
+  },
+    previouspayload: false
+}
+return msg`);
+            });
+            $("#snippetThree").on("click", function (event) {
+                node.inputFunctionCodeEditor.session.setValue(`// @ts-nocheck
+// The current msg contains the internal temperature in the "msg.payload" property, but we want to emit the external temperature as well.
+msg.externalTemperature = getGAValue('0/0/10'); // In case the ETS file is missing, you must specify the dpt as well: getGAValue('0/0/10','9.001')
+return msg;`);
+            });
+
             function checkUI() {
 
                 // Backward compatibility
@@ -352,7 +409,8 @@
         },
         oneditsave: function () {
             var node = this;
-
+            this.outputFunctionCode = this.outputFunctionCodeEditor.getValue();
+            this.inputFunctionCode = this.inputFunctionCodeEditor.getValue();
             //this.propertyType = $("#node-input-property").typedInput('type');
 
             // 19/02/2020 Warn user that the node will node encode/decode datagram, if Listen All GA's if the config node doesn't contain the csv
@@ -378,14 +436,18 @@
                 // $("#GAandDPT").show()
                 // $("#divOutputRBE").show()
                 // $("#divInputRBE").show()
-                $("#helpallga").show()
+                //$("#helpallga").show()
             }
 
             // 15/09/2020 Supergiovane, Detele the sample help editor
             try {
                 node.sampleEditor.destroy();
-                RED.editor.destroy(); // 23/01/2024 added
                 delete node.sampleEditor;
+                node.outputFunctionCodeEditor.destroy();
+                delete node.outputFunctionCodeEditor;
+                node.inputFunctionCodeEditor.destroy();
+                delete node.inputFunctionCodeEditor;
+                //RED.editor.destroy(); // 23/01/2024 added  
             } catch (error) { }
 
         },
@@ -393,8 +455,12 @@
             // 15/09/2020 Supergiovane, Detele the sample help editor
             try {
                 node.sampleEditor.destroy();
-                RED.editor.destroy(); // 23/01/2024 added
                 delete node.sampleEditor;
+                node.outputFunctionCodeEditor.destroy();
+                delete node.outputFunctionCodeEditor;
+                node.inputFunctionCodeEditor.destroy();
+                delete node.inputFunctionCodeEditor;
+                RED.editor.destroy(); // 23/01/2024 added  
             } catch (error) { }
         }
     })
@@ -486,19 +552,17 @@
         </label>
         <!-- <div id="helpallga">Some Content Here</div> -->
     </div>
-
-
     <div id="tabs">
         <ul>
             <li><a href="#tabs-1"><i class="fa fa-braille"></i> Advanced options</a></li>
-            <li><a href="#tabs-2"><i class="fa fa-list-ol"></i> Format input</a></li>
-            <li><a href="#tabs-3"><i class="fa fa-code"></i> Payload Sample</a></li>
+            <li><a href="#tabs-2"><i class="fa fa-code"></i> KNX Function (BETA)</a></li>
+            <li><a href="#tabs-3"><i class="fa fa-medkit"></i> Payload Sample</a></li>
         </ul>
         <div id="tabs-1">
             <div class="form-row" style="padding:10px">
                 <div class="form-row">
                     <dt>
-                        <i class="fa fa-arrow-right"></i> SEND msg to KNX BUS
+                        <i class="fa fa-arrow-right"></i>| SEND msg to KNX BUS
                     </dt>
                 </div>
                 <div class="form-row">
@@ -521,7 +585,7 @@
                         <option value="false">Disable</option>
                     </select>
                 </div>
-                <br />
+                <hr>
                 <div class="form-row">
                     <dt>
                         |<i class="fa fa-arrow-right"></i> RECEIVE msg from KNX BUS
@@ -569,7 +633,6 @@
                         <i class="fa fa-sign-in"></i> React to read telegrams
                     </label>
                 </div>
-
                 <div id="divnotifyreadrequestautoreact">
                     <dd>
                         <div class="form-row">
@@ -591,23 +654,17 @@
                         </div>
                     </dd>
                 </div>
-            </div>
-        </div>
-
-        <div id="tabs-2">
-            <div class="form-row" style="padding:10px">
                 <div class="form-row">
                     <dt>
                         <i class="fa fa-sort-numeric-asc"></i> Format numeric values coming from the KNX BUS
                     </dt>
                 </div>
-
                 <div class="form-row">
-                    <label style="width:30%" for="node-input-formatmultiplyvalue">
+                    <label style="width:180px" for="node-input-formatmultiplyvalue">
                         <i class="fa fa-calculator"></i>
                         <span data-i18n="knxUltimate.properties.node-input-formatmultiplyvalue"></span>
                     </label>
-                    <select style="width:65%" id="node-input-formatmultiplyvalue">
+                    <select id="node-input-formatmultiplyvalue">
                         <option value=1 data-i18n="knxUltimate.selectlists.Multiply_leave"></option>
                         <option value=0.001 data-i18n="knxUltimate.selectlists.Multiply_divide1000"></option>
                         <option value=0.01 data-i18n="knxUltimate.selectlists.Multiply_divide100"></option>
@@ -618,11 +675,11 @@
                     </select>
                 </div>
                 <div class="form-row">
-                    <label style="width:30%" for="node-input-formatdecimalsvalue">
+                    <label style="width:180px" for="node-input-formatdecimalsvalue">
                         <i class="fa fa-expand"></i>
                         <span data-i18n="knxUltimate.properties.node-input-formatdecimalsvalue"></span>
                     </label>
-                    <select style="width:65%" id="node-input-formatdecimalsvalue">
+                    <select id="node-input-formatdecimalsvalue">
                         <option value=999 data-i18n="knxUltimate.selectlists.Decimals_leave"></option>
                         <option value=0 data-i18n="knxUltimate.selectlists.Decimals_roundint"></option>
                         <option value=1 data-i18n="knxUltimate.selectlists.Decimals_round1"></option>
@@ -632,29 +689,55 @@
                     </select>
                 </div>
                 <div class="form-row">
-                    <label style="width:30%" for="node-input-formatnegativevalue">
+                    <label style="width:180px" for="node-input-formatnegativevalue">
                         <i class="fa fa-minus-circle"></i>
                         <span data-i18n="knxUltimate.properties.node-input-formatnegativevalue"></span>
                     </label>
-                    <select style="width:65%" id="node-input-formatnegativevalue">
+                    <select id="node-input-formatnegativevalue">
                         <option value="leave" data-i18n="knxUltimate.selectlists.Negatives_leave"></option>
                         <option value="zero" data-i18n="knxUltimate.selectlists.Negatives_zero"></option>
                         <option value="abs" data-i18n="knxUltimate.selectlists.Negatives_abs"></option>
                     </select>
                 </div>
             </div>
+        </div>
 
+        <div id="tabs-2">
+            <div class="form-row" style="padding:10px">
+                <div class="form-row">
+                    <dt>
+                        <i class="fa fa-arrow-right"></i>| SEND msg to KNX BUS
+                    </dt>
+                </div>
+                <div style="height:200px;min-height:150px;padding:0px;">
+                    <div style="height:100%;width:100%;padding:0px;" class="node-text-editor"
+                        id="outputFunctionCode-editor"></div>
+                </div>
+                <i class="fa fa-code"></i> Select a snippet to be inserted<br />
+                <button type="button" id="snippetOne" class="red-ui-button">Status GA check</button>
+                <hr>
+                <div class="form-row">
+                    <dt>
+                        |<i class="fa fa-arrow-right"></i> RECEIVE msg from KNX BUS
+                    </dt>
+                </div>
+                <div style="height:200px;min-height:150px;padding:0px;">
+                    <div style="height:100%;width:100%;padding:0px;" class="node-text-editor"
+                        id="inputFunctionCode-editor"></div>
+                </div>
+                <i class="fa fa-code"></i> Select a snippet to be inserted<br />
+                <button type="button" id="snippetTwo" class="red-ui-button">Show msg constructor</button>
+                <button type="button" id="snippetThree" class="red-ui-button">Add property to msg</button>
+
+            </div>
         </div>
+
         <div id="tabs-3">
             <div style="height:200px;min-height:150px;padding:0px;">
                 <div style="height:100%;width:100%;padding:0px;" class="node-text-editor" id="example-editor"></div>
             </div>
         </div>
     </div>
-
-
-
-
 </div>
 
 <div id="divDeployFirst">
@@ -681,6 +764,8 @@
 | Passthrough | If set, you can pass the input mgs to the output msg. |
 | Universal mode (listen to all Group Addresses) | By setting this, the node will read and control ALL group addresses. |
 
+<br/>
+<br/>
 
 **Advanced options**
 |Property|Description|
@@ -694,20 +779,76 @@
 | React to write telegrams | The node will react (will send a msg to the flow) each time it receives a *write* telegram from the KNX bus. Usually, you want that. |
 | React to response telegrams | The node will react (will send a msg to the flow) each time it receives a *response* telegram from the KNX bus. Usually, you want that for particular scenarios. |
 | React to read telegrams | The node will react (will send a msg to the flow) each time it receives a *read* telegram from the KNX bus. Usually, you want that if you're want to send a custom value to the KNX BUS. |
+| Multiply | Multiplies or divides the payload value. Works only if the value is a number. |
+| Decimals | Round or handle decimals in any way. Works only if the value is a number. |
+| Negatives | Handles the negative values. Works only if the value is a number. |
+
+<br/>
+<br/>
 
+**KNX Function**
 
-**Format input**
-|Property|Description|
-|--|--|
-| Multiply | Multiplies or divides the payload value |
-| Decimals | Round or handle decimals in any way |
-| Negatives | Handles the negative values |
+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).  
+The script is called everytime the node receives a msg from the flow or a telegram from the KNX BUS.
+
+### SEND msg to KNX BUS
+
+List of object and functions you can use in the code
+
+: msg (object) : The current msg object received by the node from the flow. 
+: getGAValue (GA as string, DPT as string) : Function. Get the specified GA's value, for example '1/0/1'. **DPT** is optional if you've imported the ETS file, otherwise you must specify it, for example '1.001'. 
+: return (msg) : Mandatory `return msg;`, if you want to emit the msg to the KNX BUS. Otherwise, using `return;` will not emit any message. 
+
+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. 
+```javascript
+const statusGA = getGAValue('0/0/09','1.001');
+if (msg.payload !== statusGA){ // "!==" means "not equal"
+    return msg;
+}else{
+    // Both values are identical, so i don't send the msg.
+    return;
+}
+```
+
+### RECEIVE msg from KNX BUS
+
+List of object and functions you can use in the code
+
+: msg (object) : The current msg object received by the node from the KNX BUS. 
+: getGAValue (GA as string, DPT as string) : Function. Get the specified GA's value, for example '1/0/1'. **DPT** is optional if you've imported the ETS file, otherwise you must specify it, for example '1.001'. 
+: return (msg) : Mandatory `return msg;`, if you want to emit the msg to the flow. Otherwise, using `return;` will not emit any message. 
+
+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`  
+```javascript
+// The current msg contains the internal temperature in the "msg.payload" property, but we want to emit the external temperature as well.
+msg.externalTemperature = getGAValue('0/0/10'); // In case the ETS file is missing, you must specify the dpt as well: getGAValue('0/0/10','9.001')
+return msg;
+```
+
+In this other sample, we'll not emit a msg to the flow, in case msg.payload and another GA value are both false.  
+```javascript
+if (msg.payload === false && getGAValue('0/0/11','1.001') === false){
+    // Both false, don't emit the msg to the flow.
+    return;
+}else{
+    // Ok, emit it.
+    return msg;
+}
+```
+
+<br/>
+<br/>
 
 **Payload sample**
 |Property|Description|
 |--|--|
-| Sample | This will give it a hint on what to write in a function, if you want to control the node via a Node-Red function node. |
+| 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. |
 
+<br/>
+<br/>
 <br/>
 
 ### Inputs

package/nodes/knxUltimate.js

@@ -4,6 +4,7 @@ module.exports = function (RED) {
   const _ = require('lodash');
   const KNXUtils = require('knxultimate');
   const payloadRounder = require('./utils/payloadManipulation');
+  const dptlib = require('knxultimate').dptlib;
 
   function knxUltimate(config) {
     RED.nodes.createNode(this, config);
@@ -119,7 +120,10 @@ module.exports = function (RED) {
     node.inputmessage = {}; // Stores the input message to be passed through
     node.timerTTLInputMessage = null; // The stored node.inputmessage has a ttl.
     node.sysLogger = require('./utils/sysLogger.js').get({ loglevel: node.server.loglevel || 'error' }); // 08/04/2021 new logger to adhere to the loglevel selected in the config-window
-
+    node.outputFunctionCode = config.outputFunctionCode || undefined;
+    node.inputFunctionCode = config.inputFunctionCode || undefined;
+    if (node.outputFunctionCode === '') node.outputFunctionCode = undefined
+    if (node.inputFunctionCode === '') node.inputFunctionCode = undefined
 
     // Check if the node has a valid dpt
     if (node.listenallga === false) {
@@ -131,6 +135,23 @@ module.exports = function (RED) {
       }
     }
 
+    // Used in the KNX Function TAB
+    let getGAValue = function getGAValue(ga = undefined, _dpt = undefined) {
+      try {
+        if (ga === undefined) return;
+        // 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.');
+          return dptlib.fromBuffer(found.rawValue, dptlib.resolve(_dpt || found.dpt));
+        } else {
+          throw new Error('Group Address not yet read, try later.');
+        }
+      } catch (error) {
+        throw error;
+      }
+    }
+
     // This function is called by the knx-ultimate config node, to output a msg.payload.
     node.handleSend = (msg) => {
       // 27/03/2020 can i merge the last input msg arrived, with the output?
@@ -147,7 +168,23 @@ module.exports = function (RED) {
           node.inputmessage = {};
         }
       } catch (error) { }
-      node.send(msg);
+
+      // #region "Inject the msg to the JS code, then output msg to the flow"
+      // -+++++++++++++++++++++++++++++++++++++++++++
+      if (node.outputFunctionCode !== undefined) {
+        try {
+          let outputFunction = new Function('msg', 'getGAValue', node.outputFunctionCode)
+          msg = outputFunction(msg, getGAValue);
+        } catch (error) {
+          RED.log.error('knxUltimate: outputFunction: node ID:' + node.id + ' ' + error.message);
+          if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(`knxUltimate: outputFunction: node id ${node.id} ` || ' ' + error.stack);
+          return;
+        }
+      }
+      // -+++++++++++++++++++++++++++++++++++++++++++
+      //#endregion
+
+      if (msg !== undefined) node.send(msg);
     };
 
 
@@ -195,6 +232,22 @@ module.exports = function (RED) {
         node.inputmessage = RED.util.cloneMessage(msg); // 28/03/2020 Store the message to be passed through.
       }
 
+      // #region "Inject the msg to the JS code, then output msg to the flow"
+      // -+++++++++++++++++++++++++++++++++++++++++++
+      if (node.inputFunctionCode !== undefined) {
+        try {
+          let inputFunction = new Function('msg', 'getGAValue', node.inputFunctionCode)
+          msg = inputFunction(msg, getGAValue);
+          if (msg === undefined) return;
+        } catch (error) {
+          RED.log.error('knxUltimate: inputFunction: node ID:' + node.id + ' ' + error.message);
+          if (node.sysLogger !== undefined && node.sysLogger !== null) node.sysLogger.error(`knxUltimate: inputFunction: 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/nodes/knxUltimateAutoResponder.html

@@ -16,9 +16,9 @@
         outputs: 0,
         icon: "node-knx-icon.svg",
         label: function () {
-            return (this.name + ' (BETA)' || "Auto Responder (BETA)");
+            return (this.name || "KNX Auto Responder");
         },
-        paletteLabel: "Auto Responder (BETA)",
+        paletteLabel: "KNX Auto Responder",
         // button: {
         //     enabled: function() {
         //         // return whether or not the button is enabled, based on the current

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=16.0.0"
   },
-  "version": "3.0.10",
+  "version": "3.1.0",
   "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",