node-red-contrib-knx-ultimate 4.3.2 → 4.3.5

package/CHANGELOG.md

@@ -6,6 +6,24 @@
 
 # CHANGELOG
 
+**Version 4.3.5** - April 2026<br/>
+
+- NEW: **KNX DEVICE** now supports explicit **`dpt = raw`** mode for incoming telegrams: decoding is skipped, `msg.payload` is `null`, and raw bytes remain available in `msg.knx.rawValue`.<br/>
+- FIX: **KNX DEVICE RAW write** now accepts both **`msg.bitlength`** and legacy **`msg.bitlenght`**, with `bitlength` preferred and old flows kept backward compatible.<br/>
+- CHANGE: **KNX DEVICE** in **`dpt = raw`** mode now accepts raw outgoing telegrams only via **`msg.writeraw`**, preventing accidental normal writes with an invalid datapoint.<br/>
+- Docs/help/wiki: updated **KNX DEVICE** help HTML and **Device** wiki pages in all supported languages (**EN/IT/DE/FR/ES/zh-CN**) to document **raw mode** and the preferred **`bitlength`** property.<br/>
+
+**Version 4.3.4** - April 2026<br/>
+
+- UI: **KNX Function** editor areas now have colored backgrounds (light green for *input→bus*, light yellow for *bus→output*) for easier visual distinction.<br/>
+- UI: **KNX Function** Monaco editor no longer shows red underlines for custom KNX functions (`getGAValue`, `setGAValue`, `toggle`, `self`).<br/>
+- NEW: **KNX Function** : **`let val = await getGAValue(...)`** now automatically sends a `GroupValue_Read` to the KNX bus when the requested group address has no cached value yet, and waits up to 3 seconds for the device to respond before returning `null`. Use `await getGAValue(...)` in your KNX Function code to benefit from this behaviour.<br/>
+
+**Version 4.3.3** - April 2026<br/>
+
+- UI: in the **KNX Function helper**, the **Search GA** field is now always visible; if the ETS CSV is not imported, the field is disabled and shows `To enable the search, IMPORT THE ETS FILE`.<br/>
+- In the KNX DEVICE NODE, added the "toggle with status" function snippet.<br/>
+
 **Version 4.3.2** - April 2026<br/>
 
 - Docs/help/wiki: updated **KNX AI** help HTML and wiki pages in all supported languages (EN/IT/DE/FR/ES/zh-CN) to reflect the latest LLM/Ollama UX changes.<br/>

package/nodes/knxUltimate-config.js

@@ -2066,6 +2066,8 @@ module.exports = (RED) => {
         }
       }
 
+      const isRawMode = typeof _inputDpt === 'string' && _inputDpt.trim().toLowerCase() === 'raw'
+
       const errorMessage = {
         topic: _outputtopic,
         payload: 'UNKNOWN, PLEASE IMPORT THE ETS FILE!',
@@ -2088,83 +2090,18 @@ module.exports = (RED) => {
 
       // Resolve DPT and convert value if available
       if (_Rawvalue !== null) {
-        try {
-          sInputDpt = _inputDpt === null ? tryToFigureOutDataPointFromRawValue(_Rawvalue) : _inputDpt
-        } catch (error) {
-          // Here comes if no datapoint has beeen found
-          node.sysLogger?.error(
-            'buildInputMessage: Error returning from tryToFigureOutDataPointFromRawValue. Device ' +
-            _srcGA +
-            ' Destination ' +
-            _destGA +
-            ' Event ' +
-            _event +
-            " GA's Datapoint " +
-            (_inputDpt === null
-              ? "THE ETS FILE HAS NOT BEEN IMPORTED, SO I'M TRYING TO FIGURE OUT WHAT DATAPOINT BELONGS THIS GROUP ADDRESS. DON'T BLAME ME IF I'M WRONG, INSTEAD, IMPORT THE ETS FILE!"
-              : _inputDpt) +
-            ' Devicename ' +
-            _devicename +
-            ' Topic ' +
-            _outputtopic +
-            ' ' +
-            error.message
-          )
-          errorMessage.payload = 'UNKNOWN: ERROR tryToFigureOutDataPointFromRawValue:' + error.message
-          return errorMessage
-        }
-
-        try {
-          var dpt = dptlib.resolve(sInputDpt)
-        } catch (error) {
-          node.sysLogger?.error(
-            'buildInputMessage: Error returning from dptlib.resolve(sInputDpt). Device ' +
-            _srcGA +
-            ' Destination ' +
-            _destGA +
-            ' Event ' +
-            _event +
-            " GA's Datapoint " +
-            (_inputDpt === null
-              ? "THE ETS FILE HAS NOT BEEN IMPORTED, SO I'M TRYING TO FIGURE OUT WHAT DATAPOINT BELONGS THIS GROUP ADDRESS. DON'T BLAME ME IF I'M WRONG, INSTEAD, IMPORT THE ETS FILE!"
-              : _inputDpt) +
-            ' Devicename ' +
-            _devicename +
-            ' Topic ' +
-            _outputtopic +
-            ' ' +
-            error.message
-          )
-          errorMessage.payload = 'UNKNOWN: ERROR dptlib.resolve:' + error.messages
-          return errorMessage
-        }
-
-        if (dpt !== null && _Rawvalue !== null) {
+        if (isRawMode) {
+          sInputDpt = 'raw'
+          sPayloadmeasureunit = ''
+          sDptdesc = 'Raw value'
+          sPayloadsubtypevalue = ''
+        } else {
           try {
-            jsValue = dptlib.fromBuffer(_Rawvalue, dpt)
-            if (jsValue === null) {
-              node.sysLogger?.warn(
-                'buildInputMessage: received a wrong datagram form KNX BUS, from device ' +
-                _srcGA +
-                ' Destination ' +
-                _destGA +
-                ' Event ' +
-                _event +
-                " GA's Datapoint " +
-                (_inputDpt === null
-                  ? "THE ETS FILE HAS NOT BEEN IMPORTED, SO I'M TRYING TO FIGURE OUT WHAT DATAPOINT BELONGS THIS GROUP ADDRESS. DON'T BLAME ME IF I'M WRONG, INSTEAD, IMPORT THE ETS FILE!"
-                  : _inputDpt) +
-                ' Devicename ' +
-                _devicename +
-                ' Topic ' +
-                _outputtopic +
-                ' NodeID ' +
-                _oNode.id || ''
-              )
-            }
+            sInputDpt = _inputDpt === null ? tryToFigureOutDataPointFromRawValue(_Rawvalue) : _inputDpt
           } catch (error) {
+            // Here comes if no datapoint has beeen found
             node.sysLogger?.error(
-              'buildInputMessage: Error returning from DPT decoding. Device ' +
+              'buildInputMessage: Error returning from tryToFigureOutDataPointFromRawValue. Device ' +
               _srcGA +
               ' Destination ' +
               _destGA +
@@ -2179,34 +2116,112 @@ module.exports = (RED) => {
               ' Topic ' +
               _outputtopic +
               ' ' +
-              error.message +
-              ' NodeID ' +
-              _oNode.id || ''
+              error.message
             )
-            errorMessage.payload = 'UNKNOWN: ERROR dptlib.fromBuffer:' + error.stack
+            errorMessage.payload = 'UNKNOWN: ERROR tryToFigureOutDataPointFromRawValue:' + error.message
             return errorMessage
           }
-        }
 
-        // 19/01/2023 FORMATTING THE OUTPUT PAYLOAD (ROUND, ETC) BASED ON THE NODE CONFIG
-        //* ********************************************************
-        jsValue = payloadRounder.Manipulate(_oNode, jsValue)
-        //* ********************************************************
+          try {
+            var dpt = dptlib.resolve(sInputDpt)
+          } catch (error) {
+            node.sysLogger?.error(
+              'buildInputMessage: Error returning from dptlib.resolve(sInputDpt). Device ' +
+              _srcGA +
+              ' Destination ' +
+              _destGA +
+              ' Event ' +
+              _event +
+              " GA's Datapoint " +
+              (_inputDpt === null
+                ? "THE ETS FILE HAS NOT BEEN IMPORTED, SO I'M TRYING TO FIGURE OUT WHAT DATAPOINT BELONGS THIS GROUP ADDRESS. DON'T BLAME ME IF I'M WRONG, INSTEAD, IMPORT THE ETS FILE!"
+                : _inputDpt) +
+              ' Devicename ' +
+              _devicename +
+              ' Topic ' +
+              _outputtopic +
+              ' ' +
+              error.message
+            )
+            errorMessage.payload = 'UNKNOWN: ERROR dptlib.resolve:' + error.messages
+            return errorMessage
+          }
 
-        if (dpt.subtype !== undefined) {
-          sPayloadmeasureunit = dpt.subtype.unit !== undefined ? dpt.subtype.unit : 'unknown'
-          sDptdesc = dpt.subtype.desc !== undefined ? dpt.subtype.desc.charAt(0).toUpperCase() + dpt.subtype.desc.slice(1) : 'unknown'
-          if (dpt.subtype.enc !== undefined) {
+          if (dpt !== null && _Rawvalue !== null) {
             try {
-              if (!jsValue) sPayloadsubtypevalue = dpt.subtype.enc[0]
-              if (jsValue) sPayloadsubtypevalue = dpt.subtype.enc[1]
+              jsValue = dptlib.fromBuffer(_Rawvalue, dpt)
+              if (jsValue === null) {
+                node.sysLogger?.warn(
+                  'buildInputMessage: received a wrong datagram form KNX BUS, from device ' +
+                  _srcGA +
+                  ' Destination ' +
+                  _destGA +
+                  ' Event ' +
+                  _event +
+                  " GA's Datapoint " +
+                  (_inputDpt === null
+                    ? "THE ETS FILE HAS NOT BEEN IMPORTED, SO I'M TRYING TO FIGURE OUT WHAT DATAPOINT BELONGS THIS GROUP ADDRESS. DON'T BLAME ME IF I'M WRONG, INSTEAD, IMPORT THE ETS FILE!"
+                    : _inputDpt) +
+                  ' Devicename ' +
+                  _devicename +
+                  ' Topic ' +
+                  _outputtopic +
+                  ' NodeID ' +
+                  _oNode.id || ''
+                )
+              }
             } catch (error) {
-              // Don't care
+              node.sysLogger?.error(
+                'buildInputMessage: Error returning from DPT decoding. Device ' +
+                _srcGA +
+                ' Destination ' +
+                _destGA +
+                ' Event ' +
+                _event +
+                " GA's Datapoint " +
+                (_inputDpt === null
+                  ? "THE ETS FILE HAS NOT BEEN IMPORTED, SO I'M TRYING TO FIGURE OUT WHAT DATAPOINT BELONGS THIS GROUP ADDRESS. DON'T BLAME ME IF I'M WRONG, INSTEAD, IMPORT THE ETS FILE!"
+                  : _inputDpt) +
+                ' Devicename ' +
+                _devicename +
+                ' Topic ' +
+                _outputtopic +
+                ' ' +
+                error.message +
+                ' NodeID ' +
+                _oNode.id || ''
+              )
+              errorMessage.payload = 'UNKNOWN: ERROR dptlib.fromBuffer:' + error.stack
+              return errorMessage
+            }
+          }
+
+          // 19/01/2023 FORMATTING THE OUTPUT PAYLOAD (ROUND, ETC) BASED ON THE NODE CONFIG
+          //* ********************************************************
+          jsValue = payloadRounder.Manipulate(_oNode, jsValue)
+          //* ********************************************************
+
+          if (dpt.subtype !== undefined) {
+            sPayloadmeasureunit = dpt.subtype.unit !== undefined ? dpt.subtype.unit : 'unknown'
+            sDptdesc = dpt.subtype.desc !== undefined ? dpt.subtype.desc.charAt(0).toUpperCase() + dpt.subtype.desc.slice(1) : 'unknown'
+            if (dpt.subtype.enc !== undefined) {
+              try {
+                if (!jsValue) sPayloadsubtypevalue = dpt.subtype.enc[0]
+                if (jsValue) sPayloadsubtypevalue = dpt.subtype.enc[1]
+              } catch (error) {
+                // Don't care
+              }
             }
           }
         }
       } else {
         // Don't care, it's a READ REQUEST
+        if (isRawMode) {
+          sInputDpt = 'raw'
+          sPayloadmeasureunit = ''
+          sDptdesc = 'Raw value'
+          sPayloadsubtypevalue = ''
+        }
       }
 
       try {

package/nodes/knxUltimate.html

@@ -1,5 +1,25 @@
 <!-- <script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/jquery.searchableSelect.js"></script> -->
 
+<style>
+/* Monaco editor - first area (input to bus): light green */
+#sendMsgToKNXCode-editor .monaco-editor,
+#sendMsgToKNXCode-editor .monaco-editor-background,
+#sendMsgToKNXCode-editor .monaco-editor .margin,
+#sendMsgToKNXCode-editor .monaco-editor .overflow-guard,
+#sendMsgToKNXCode-editor .monaco-editor .lines-content,
+#sendMsgToKNXCode-editor .monaco-editor .editor-scrollable {
+    background-color: #e8f5e9 !important;
+}
+/* Monaco editor - second area (bus to output): light yellow */
+#receiveMsgFromKNXCode-editor .monaco-editor,
+#receiveMsgFromKNXCode-editor .monaco-editor-background,
+#receiveMsgFromKNXCode-editor .monaco-editor .margin,
+#receiveMsgFromKNXCode-editor .monaco-editor .overflow-guard,
+#receiveMsgFromKNXCode-editor .monaco-editor .lines-content,
+#receiveMsgFromKNXCode-editor .monaco-editor .editor-scrollable {
+    background-color: #fffde7 !important;
+}
+</style>
 
 <script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/htmlUtils.js"></script>
 <script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/KNXSendSnippets.js"></script>
@@ -225,6 +245,15 @@
                 }
             ];
             const globalScope = typeof window !== 'undefined' ? window : (typeof globalThis !== 'undefined' ? globalThis : {});
+            const rawDptOption = { value: 'raw', text: 'raw Raw telegram (no decode)' }
+
+            function appendRawDptOption($select) {
+                if (!$select || !$select.length) return
+                if ($select.find("option[value='raw']").length > 0) return
+                $select.prepend($("<option></option>")
+                    .attr("value", rawDptOption.value)
+                    .text(rawDptOption.text))
+            }
 
             function knxUltimateDptsGetHelp(_dpt, _forceClose) {
                 const detailsContainer = $("#dptDetailsContainer")
@@ -233,6 +262,39 @@
                 }
                 const serverId = $("#node-input-server").val()
                 if (serverId === "_ADD_" || serverId === '' || _dpt === null || _dpt === '') return
+                if (String(_dpt).trim().toLowerCase() === 'raw') {
+                    const helplinkContainer = $("#sampleCodeEditor")
+                    try {
+                        if (node.sampleEditor) {
+                            node.sampleEditor.destroy()
+                            delete node.sampleEditor
+                        }
+                    } catch (error) { }
+                    $("#example-editor").empty()
+                    helplinkContainer.empty()
+                    node.sampleEditor = RED.editor.createEditor({
+                        id: 'example-editor',
+                        mode: 'ace/mode/javascript',
+                        value: `// KNX-Ultimate set as RAW NODE
+// Incoming telegrams skip datapoint decoding.
+// msg.payload will be null and the raw telegram bytes are available in msg.knx.rawValue.
+// For outgoing telegrams, use msg.writeraw = Buffer.from("0730", "hex")
+// and optionally msg.bitlength for 1-bit / 2-bit / 4-bit datapoints.
+return msg;`
+                    })
+                    try {
+                        node.sampleEditor.setReadOnly(true)
+                        node.sampleEditor.setShowPrintMargin(false)
+                    } catch (error) { }
+                    $("<div>", {
+                        class: "dpt-details-link"
+                    })
+                        .append($("<span>").text("RAW mode keeps the telegram undecoded and exposes the bytes in "))
+                        .append($("<code>").text("msg.knx.rawValue"))
+                        .append($("<span>").text("."))
+                        .appendTo(helplinkContainer)
+                    return
+                }
                 $.getJSON("knxUltimateDptsGetHelp?dpt=" + _dpt + "&serverId=" + serverId + "&" + { _: new Date().getTime() }, (data) => {
                     const helplinkContainer = $("#sampleCodeEditor")
                     try {
@@ -336,15 +398,29 @@
                     }
                     if (typeof monaco !== 'undefined' && !globalScope.knxFunctionMonacoCompletionProvider) {
                         try {
-                            const suggestions = knxFunctionHelperItems.map(item => ({
+                            const functionSuggestions = knxFunctionHelperItems.map(item => ({
                                 label: item.label,
                                 kind: monaco.languages.CompletionItemKind.Function,
                                 insertText: item.snippet,
                                 insertTextRules: monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet,
                                 documentation: item.doc
                             }));
+
                             globalScope.knxFunctionMonacoCompletionProvider = monaco.languages.registerCompletionItemProvider('javascript', {
-                                provideCompletionItems: () => ({ suggestions })
+                                provideCompletionItems: () => ({ suggestions: functionSuggestions })
+                            });
+
+                            monaco.languages.typescript.javascriptDefaults.addExtraLib([
+                                '/** Read the cached value of a KNX group address. */',
+                                'declare function getGAValue(address: string, dpt?: string): any;',
+                                '/** Send a value to a KNX group address. */',
+                                'declare function setGAValue(address: string, value: any, dpt?: string): void;',
+                                '/** Toggle (invert) this node\'s current value on the KNX bus. */',
+                                'declare function toggle(): void;',
+                            ].join('\n'), 'knx-ultimate-globals.d.ts');
+                            monaco.languages.typescript.javascriptDefaults.setDiagnosticsOptions({
+                                noSemanticValidation: true,
+                                noSyntaxValidation: false
                             });
                         } catch (error) { }
                     }
@@ -499,6 +575,27 @@
                 value: node.receiveMsgFromKNXCode
             });
             applyEditorOptions(node.receiveMsgFromKNXCodeEditor);
+            if (typeof monaco !== 'undefined') {
+                try {
+                    if (!globalScope._knxEditorThemesDefined) {
+                        monaco.editor.defineTheme('knx-send-theme', {
+                            base: 'vs', inherit: true, rules: [],
+                            colors: { 'editor.background': '#e8f5e9', 'editorGutter.background': '#e8f5e9' }
+                        });
+                        monaco.editor.defineTheme('knx-receive-theme', {
+                            base: 'vs', inherit: true, rules: [],
+                            colors: { 'editor.background': '#fffde7', 'editorGutter.background': '#fffde7' }
+                        });
+                        globalScope._knxEditorThemesDefined = true;
+                    }
+                    if (typeof node.sendMsgToKNXCodeEditor.updateOptions === 'function') {
+                        node.sendMsgToKNXCodeEditor.updateOptions({ theme: 'knx-send-theme' });
+                    }
+                    if (typeof node.receiveMsgFromKNXCodeEditor.updateOptions === 'function') {
+                        node.receiveMsgFromKNXCodeEditor.updateOptions({ theme: 'knx-receive-theme' });
+                    }
+                } catch (e) { }
+            }
             node.activeCodeEditor = null;
             attachFocusHandlers(node.sendMsgToKNXCodeEditor);
             attachFocusHandlers(node.receiveMsgFromKNXCodeEditor);
@@ -516,6 +613,27 @@
                 insertTextIntoEditor(editor, sanitizedValue);
             });
 
+            const $knxFunctionHelperInput = $("#node-input-knxFunctionHelperGAList");
+            const $knxFunctionHelperInsertButton = $("#btn-insert-knxFunctionGA");
+            let knxFunctionHelperDefaultPlaceholder = $knxFunctionHelperInput.attr('placeholder') || '';
+            if (!knxFunctionHelperDefaultPlaceholder) {
+                try {
+                    knxFunctionHelperDefaultPlaceholder = RED._("node-red-contrib-knx-ultimate/knxUltimate:knxUltimate.placeholder.search") || '';
+                } catch (error) { }
+            }
+            const knxFunctionHelperNoEtsPlaceholder = 'To enable the search, IMPORT THE ETS FILE';
+            const refreshKnxFunctionHelperState = (hasEtsCsv) => {
+                $("#divknxFunctionHelperGAList").show();
+                $knxFunctionHelperInput.prop('disabled', !hasEtsCsv);
+                $knxFunctionHelperInsertButton.prop('disabled', !hasEtsCsv);
+                if (hasEtsCsv) {
+                    $knxFunctionHelperInput.attr('placeholder', knxFunctionHelperDefaultPlaceholder);
+                } else {
+                    $knxFunctionHelperInput.val('');
+                    $knxFunctionHelperInput.attr('placeholder', knxFunctionHelperNoEtsPlaceholder);
+                }
+            };
+
             const configureSnippetPicker = (snippets, inputSelector, datalistSelector, applySnippet) => {
                 const inputEl = $(inputSelector)
                 const datalistEl = $(datalistSelector)
@@ -628,15 +746,13 @@
                     try {
                         if (typeof oNodeServer.csv !== "undefined" && oNodeServer.csv !== "") {
                             $("#isETSFileLoaded").val("si");
-                            $("#divknxFunctionHelperGAList").show();
                         } else {
                             $("#isETSFileLoaded").val("no");
-                            $("#divknxFunctionHelperGAList").hide();
                         }
                     } catch (error) {
                         $("#isETSFileLoaded").val("no");
-                        $("#divknxFunctionHelperGAList").hide();
                     }
+                    refreshKnxFunctionHelperState($("#isETSFileLoaded").val() === "si");
                     if (oNodeServer.knxSecureSelected) {
                         $("#divknxsecure").show();
                     } else {
@@ -647,11 +763,13 @@
                         refreshSecureGAs();
                         $.getJSON("knxUltimateDpts?serverId=" + $("#node-input-server").val() + "&_=" + new Date().getTime(), (data) => {
                             $("#node-input-dpt").empty();
+                            appendRawDptOption($("#node-input-dpt"));
                             data.forEach(dpt => {
                                 $("#node-input-dpt").append($("<option></option>")
                                     .attr("value", dpt.value)
                                     .text(dpt.text))
                             });
+                            if (node.dpt === undefined || node.dpt === '') node.dpt = '1.001'
                             $("#node-input-dpt").val(node.dpt);
                             // Load help sample
                             knxUltimateDptsGetHelp(node.dpt, true);