node-red-contrib-knx-ultimate 4.0.24 → 4.0.25

package/CHANGELOG.md

@@ -6,6 +6,10 @@
 
 # CHANGELOG
 
+**Version 4.0.25** - November 2025<br/>
+- KNX Device node editor: repositioned the "Show manual command button in editor" option directly under the input passthrough setting so related controls stay together.<br/>
+- KNX Function helper: refreshed the send-side snippet library with ready-to-use home-automation templates (motion-triggered lighting, HVAC standby on window-open, night door alerts, bedtime all-off) and cleaned up placeholders for easier copy/paste.<br/>
+
 **Version 4.0.24** - October 2025<br/>
 - Hue config node: pairing now polls the bridge automatically and closes the dialog as soon as the link button is pressed, with a cancellable wait message and improved error feedback.<br/>
 - Hue config node: added "I ALREADY HAVE THE CREDENTIALS" button and restored bridge discovery so manual credentials can be entered immediately without running the registration flow.<br/>

package/nodes/knxUltimate.html

@@ -185,6 +185,38 @@
             $("#tabs").tabs();
 
             // 15/09/2020 Supergiovane, set the help sample based on Datapoint
+            const knxFunctionHelperItems = [
+                {
+                    id: 'getGAValue',
+                    label: 'getGAValue(address, dpt?)',
+                    aceValue: "getGAValue('1/1/1', '1.001')",
+                    snippet: "getGAValue('${1:1/1/1}', '${2:1.001}')",
+                    doc: 'Read the cached value of another group address. Provide the datapoint if the ETS import is not available.'
+                },
+                {
+                    id: 'setGAValue',
+                    label: 'setGAValue(address, value, dpt?)',
+                    aceValue: "setGAValue('1/1/1', true)",
+                    snippet: "setGAValue('${1:1/1/1}', ${2:true}, '${3:1.001}')",
+                    doc: 'Send a value to any KNX group address. The datapoint is optional when the ETS file is imported.'
+                },
+                {
+                    id: 'self',
+                    label: 'self(value)',
+                    aceValue: 'self(false)',
+                    snippet: 'self(${1:false})',
+                    doc: 'Set this node value and forward it to the KNX bus.'
+                },
+                {
+                    id: 'toggle',
+                    label: 'toggle()',
+                    aceValue: 'toggle()',
+                    snippet: 'toggle()',
+                    doc: 'Invert this node value and write it to the KNX bus.'
+                }
+            ];
+            const globalScope = typeof window !== 'undefined' ? window : (typeof globalThis !== 'undefined' ? globalThis : {});
+
             function knxUltimateDptsGetHelp(_dpt, _forceClose) {
                 const detailsContainer = $("#dptDetailsContainer")
                 if (_forceClose === true) {
@@ -257,6 +289,56 @@
                         editor.renderer.setShowGutter(false);
                     }
                     if (typeof editor.setShowPrintMargin === 'function') editor.setShowPrintMargin(false);
+                    if (typeof ace !== 'undefined' && ace.require) {
+                        try { ace.require('ace/ext/language_tools'); } catch (error) { }
+                    }
+                    if (typeof editor.setOptions === 'function') {
+                        editor.setOptions({
+                            enableBasicAutocompletion: true,
+                            enableLiveAutocompletion: true
+                        });
+                    }
+                    if (typeof editor.completers === 'undefined') {
+                        editor.completers = [];
+                    }
+                    if (Array.isArray(editor.completers) && !editor._knxHelperCompleter) {
+                        const aceCompletions = knxFunctionHelperItems.map(item => ({
+                            caption: item.label,
+                            value: item.aceValue,
+                            snippet: item.snippet,
+                            meta: 'KNX helper',
+                            doc: item.doc
+                        }));
+                        const helperCompleter = {
+                            getCompletions: function (_editor, _session, _pos, prefix, callback) {
+                                const search = (prefix || '').toLowerCase();
+                                const filtered = search
+                                    ? aceCompletions.filter(entry => entry.caption.toLowerCase().startsWith(search) || entry.value.toLowerCase().startsWith(search))
+                                    : aceCompletions;
+                                callback(null, filtered.length ? filtered : aceCompletions);
+                            },
+                            getDocTooltip: function (item) {
+                                if (!item || item.docHTML || !item.doc) return;
+                                item.docHTML = '<b>' + item.caption + '</b><hr />' + item.doc;
+                            }
+                        };
+                        editor.completers.push(helperCompleter);
+                        editor._knxHelperCompleter = helperCompleter;
+                    }
+                    if (typeof monaco !== 'undefined' && !globalScope.knxFunctionMonacoCompletionProvider) {
+                        try {
+                            const suggestions = 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 })
+                            });
+                        } catch (error) { }
+                    }
                 } catch (error) { }
             };
 
@@ -293,20 +375,104 @@
                 } catch (error) { }
             };
 
+            const sanitizeAutocompleteValue = (raw) => {
+                if (typeof raw !== 'string') return '';
+                return raw.replace(/['"]/g, '').trim();
+            };
+            const replaceLiteralAroundCursorAce = (editor, text) => {
+                try {
+                    const AceRange = (typeof ace !== 'undefined' && ace.require) ? ace.require('ace/range').Range : null;
+                    if (!AceRange) return false;
+                    const pos = editor.getCursorPosition();
+                    const line = editor.session.getLine(pos.row) || '';
+                    let left = pos.column - 1;
+                    while (left >= 0 && line[left] !== "'") left--;
+                    if (left < 0) return false;
+                    let right = pos.column;
+                    while (right < line.length && line[right] !== "'") right++;
+                    if (right >= line.length) return false;
+                    const newLiteral = "'" + text + "'";
+                    const range = new AceRange(pos.row, left, pos.row, right + 1);
+                    editor.session.replace(range, newLiteral);
+                    editor.moveCursorTo(pos.row, left + newLiteral.length);
+                    return true;
+                } catch (error) { }
+                return false;
+            };
+            const replaceLiteralAroundCursorMonaco = (editor, text) => {
+                try {
+                    const position = editor.getPosition();
+                    if (!position) return false;
+                    const model = typeof editor.getModel === 'function' ? editor.getModel() : null;
+                    if (!model) return false;
+                    const lineContent = model.getLineContent(position.lineNumber) || '';
+                    let leftIdx = position.column - 2;
+                    if (leftIdx >= lineContent.length) leftIdx = lineContent.length - 1;
+                    while (leftIdx >= 0 && lineContent[leftIdx] !== "'") leftIdx--;
+                    if (leftIdx < 0) return false;
+                    let rightIdx = position.column - 1;
+                    if (rightIdx < leftIdx) rightIdx = leftIdx + 1;
+                    while (rightIdx < lineContent.length && lineContent[rightIdx] !== "'") rightIdx++;
+                    if (rightIdx >= lineContent.length) return false;
+                    const newLiteral = "'" + text + "'";
+                    const range = new monaco.Range(
+                        position.lineNumber,
+                        leftIdx + 1,
+                        position.lineNumber,
+                        rightIdx + 2
+                    );
+                    editor.executeEdits('knxInsertGA', [{ range, text: newLiteral, forceMoveMarkers: true }]);
+                    editor.setPosition({ lineNumber: position.lineNumber, column: leftIdx + 1 + newLiteral.length });
+                    return true;
+                } catch (error) { }
+                return false;
+            };
+
             const insertTextIntoEditor = (editor, text) => {
                 if (!editor || !text) return;
                 try {
                     if (editor.session && typeof editor.session.insert === 'function') {
                         editor.focus();
-                        editor.session.insert(editor.getCursorPosition(), text);
+                        const selectionRange = editor.getSelection && typeof editor.getSelectionRange === 'function'
+                            ? editor.getSelectionRange()
+                            : null;
+                        if (selectionRange && !selectionRange.isEmpty()) {
+                            editor.session.replace(selectionRange, text);
+                            return;
+                        }
+                        const replaced = replaceLiteralAroundCursorAce(editor, text);
+                        if (!replaced) {
+                            const pos = editor.getCursorPosition();
+                            editor.session.insert(pos, text);
+                        }
                         return;
                     }
                     if (typeof editor.executeEdits === 'function' && typeof editor.getPosition === 'function' && typeof monaco !== 'undefined') {
+                        const selection = typeof editor.getSelection === 'function' ? editor.getSelection() : null;
+                        const hasSelection = selection && (selection.startLineNumber !== selection.endLineNumber || selection.startColumn !== selection.endColumn);
+                        if (selection && hasSelection) {
+                            const selectionRange = new monaco.Range(
+                                selection.startLineNumber,
+                                selection.startColumn,
+                                selection.endLineNumber,
+                                selection.endColumn
+                            );
+                            editor.executeEdits('knxInsertGA', [{ range: selectionRange, text, forceMoveMarkers: true }]);
+                            const targetLine = selectionRange.startLineNumber;
+                            const targetColumn = selectionRange.startColumn + text.length;
+                            editor.setPosition({ lineNumber: targetLine, column: targetColumn });
+                            editor.focus();
+                            return;
+                        }
                         const position = editor.getPosition();
                         if (!position) return;
-                        const range = new monaco.Range(position.lineNumber, position.column, position.lineNumber, position.column);
-                        editor.executeEdits('knxInsertGA', [{ range, text, forceMoveMarkers: true }]);
-                        editor.setPosition({ lineNumber: position.lineNumber, column: position.column + text.length });
+                        let replaced = replaceLiteralAroundCursorMonaco(editor, text);
+                        if (!replaced) {
+                            const range = new monaco.Range(position.lineNumber, position.column, position.lineNumber, position.column);
+                            const newColumn = position.column + text.length;
+                            editor.executeEdits('knxInsertGA', [{ range, text, forceMoveMarkers: true }]);
+                            editor.setPosition({ lineNumber: position.lineNumber, column: newColumn });
+                        }
                         editor.focus();
                     }
                 } catch (error) { }
@@ -329,14 +495,16 @@
             attachFocusHandlers(node.receiveMsgFromKNXCodeEditor);
 
             $("#btn-insert-knxFunctionGA").off('click').on('click', function () {
-                const value = $("#node-input-knxFunctionHelperGAList").val();
-                if (!value || value.trim() === '') {
+                const rawValue = $("#node-input-knxFunctionHelperGAList").val();
+                if (!rawValue || rawValue.trim() === '') {
                     $("#node-input-knxFunctionHelperGAList").focus();
                     return;
                 }
+                const sanitizedValue = sanitizeAutocompleteValue(rawValue);
                 const editor = node.activeCodeEditor || node.sendMsgToKNXCodeEditor || node.receiveMsgFromKNXCodeEditor;
                 if (!editor) return;
-                insertTextIntoEditor(editor, value);
+                if (!sanitizedValue) return;
+                insertTextIntoEditor(editor, sanitizedValue);
             });
 
             const configureSnippetPicker = (snippets, inputSelector, datalistSelector, applySnippet) => {
@@ -908,6 +1076,42 @@
                         <option value="yesownprop" data-i18n="knxUltimate.selectlists.passthrough_OwnProp"></option>
                     </select>
                 </div>
+                <div class="form-row">
+                    <input type="checkbox" id="node-input-buttonEnabled"
+                        style="display:inline-block; width:auto; vertical-align:top;" />
+                    <label style="width:85%" for="node-input-buttonEnabled">
+                        <i class="fa fa-mouse-pointer"></i> <span
+                            data-i18n="knxUltimate.button.enable"></span>
+                    </label>
+                </div>
+                <div id="knx-button-options" style="display:none">
+                    <div class="form-row">
+                        <label style="width:180px" for="node-input-buttonMode">
+                            <i class="fa fa-bolt"></i> <span data-i18n="knxUltimate.button.mode"></span>
+                        </label>
+                        <select id="node-input-buttonMode" style="width:220px;">
+                            <option value="read" data-i18n="knxUltimate.button.mode_read"></option>
+                            <option value="toggle" data-i18n="knxUltimate.button.mode_toggle"></option>
+                            <option value="value" data-i18n="knxUltimate.button.mode_value"></option>
+                        </select>
+                    </div>
+                    <div class="form-row knx-button-toggle-row">
+                        <label style="width:180px" for="node-input-buttonToggleInitial">
+                            <i class="fa fa-refresh"></i> <span data-i18n="knxUltimate.button.toggleInitial"></span>
+                        </label>
+                        <select id="node-input-buttonToggleInitial" style="width:220px;">
+                            <option value="true" data-i18n="knxUltimate.button.toggleInitial_true"></option>
+                            <option value="false" data-i18n="knxUltimate.button.toggleInitial_false"></option>
+                        </select>
+                    </div>
+                    <div class="form-row knx-button-value-row">
+                        <label style="width:180px" for="node-input-buttonStaticValue">
+                            <i class="fa fa-pencil"></i> <span data-i18n="knxUltimate.button.value"></span>
+                        </label>
+                        <input type="text" id="node-input-buttonStaticValue" style="width:220px;"
+                            placeholder="42, true, {\"red\":255}" />
+                    </div>
+                </div>
                 <hr>
                 <div class="form-row">
                     <dt>
@@ -988,42 +1192,6 @@
                             data-i18n="knxUltimate.properties.node-input-notifyreadrequest"></span>
                     </label>
                 </div>
-                <div class="form-row">
-                    <input type="checkbox" id="node-input-buttonEnabled"
-                        style="display:inline-block; width:auto; vertical-align:top;" />
-                    <label style="width:85%" for="node-input-buttonEnabled">
-                        <i class="fa fa-mouse-pointer"></i> <span
-                            data-i18n="knxUltimate.button.enable"></span>
-                    </label>
-                </div>
-                <div id="knx-button-options" style="display:none">
-                    <div class="form-row">
-                        <label style="width:180px" for="node-input-buttonMode">
-                            <i class="fa fa-bolt"></i> <span data-i18n="knxUltimate.button.mode"></span>
-                        </label>
-                        <select id="node-input-buttonMode" style="width:220px;">
-                            <option value="read" data-i18n="knxUltimate.button.mode_read"></option>
-                            <option value="toggle" data-i18n="knxUltimate.button.mode_toggle"></option>
-                            <option value="value" data-i18n="knxUltimate.button.mode_value"></option>
-                        </select>
-                    </div>
-                    <div class="form-row knx-button-toggle-row">
-                        <label style="width:180px" for="node-input-buttonToggleInitial">
-                            <i class="fa fa-refresh"></i> <span data-i18n="knxUltimate.button.toggleInitial"></span>
-                        </label>
-                        <select id="node-input-buttonToggleInitial" style="width:220px;">
-                            <option value="true" data-i18n="knxUltimate.button.toggleInitial_true"></option>
-                            <option value="false" data-i18n="knxUltimate.button.toggleInitial_false"></option>
-                        </select>
-                    </div>
-                    <div class="form-row knx-button-value-row">
-                        <label style="width:180px" for="node-input-buttonStaticValue">
-                            <i class="fa fa-pencil"></i> <span data-i18n="knxUltimate.button.value"></span>
-                        </label>
-                        <input type="text" id="node-input-buttonStaticValue" style="width:220px;"
-                            placeholder="42, true, {\"red\":255}" />
-                    </div>
-                </div>
                 <div id="divnotifyreadrequestautoreact">
                     <dd>
                         <div class="form-row">

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "4.0.24",
+  "version": "4.0.25",
   "description": "Control your KNX and KNX Secure 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",
@@ -88,4 +88,4 @@
     "chai": "^4.3.10",
     "mocha": "^10.4.0"
   }
-}
+}

package/resources/KNXSendSnippets.js

@@ -4,8 +4,8 @@
       id: 'status-ga-check',
       title: 'Status GA check',
       code: `// @ts-nocheck
-// Replace 'x/x/x' with the real status group address.
-const statusGA = getGAValue('x/x/x','1.001');
+// Replace '' with the real status group address.
+const statusGA = getGAValue('','1.001');
 if (msg.payload !== statusGA){ // " !==" means " not equal"
     return msg;
  }else{
@@ -42,6 +42,80 @@ return msg;`
 if (msg.payload === true){
     setGAValue('1/0/1',20,'5.001') 
 }
+return msg;`
+    },
+    {
+      id: 'motion-activated-light',
+      title: 'Turn on light on motion, auto off',
+      code: `// @ts-nocheck
+// This snippet expects a motion sensor boolean on msg.payload.
+// When motion is detected turn the light on, otherwise schedule an auto-off.
+if (msg.payload === true) {
+    // Turn on the light immediately.
+    setGAValue('', true, '1.001'); // Replace '' with your light GA.
+    // Cancel pending auto-off timers if any.
+    context.set('autoOffTimer', null);
+} else {
+    // Schedule auto-off after 90 seconds of no motion.
+    const timer = setTimeout(() => {
+        setGAValue('', false, '1.001'); // Replace '' with your light GA.
+    }, 90000);
+    context.set('autoOffTimer', timer);
+}
+return;`
+    },
+    {
+      id: 'window-hvac-standby',
+      title: 'HVAC standby when window open',
+      code: `// @ts-nocheck
+// msg.payload should contain the window contact state (true = open).
+// If the window is open, set the HVAC to standby, otherwise restore comfort.
+const hvacGa = ''; // Replace with your HVAC GA.
+const standbyValue = 'standby';
+const comfortValue = 'comfort';
+
+if (msg.payload === true) {
+    setGAValue(hvacGa, standbyValue, '20.102'); // HVAC mode DPT.
+    node.status({fill: 'yellow', shape: 'dot', text: 'HVAC standby'});
+} else {
+    setGAValue(hvacGa, comfortValue, '20.102');
+    node.status({fill: 'green', shape: 'dot', text: 'HVAC comfort'});
+}
+return;`
+    },
+    {
+      id: 'night-door-alert',
+      title: 'Night door alert',
+      code: `// @ts-nocheck
+// Send a KNX notification GA if a door opens between 22:00 and 06:00.
+const now = new Date();
+const hour = now.getHours();
+
+if (msg.payload === true && (hour >= 22 || hour < 6)) {
+    setGAValue('', true, '1.001'); // Replace '' with your alert GA.
+    node.status({fill: 'red', shape: 'ring', text: 'Door alert sent'});
+}
+return;`
+    },
+    {
+      id: 'bedtime-all-off',
+      title: 'Bedtime all off',
+      code: `// @ts-nocheck
+// Turn off a list of lights when a bedtime command is received.
+const lights = [
+    '', // Replace with GA of the first light
+    ''  // Replace with GA of the second light
+];
+
+if (msg.payload === 'bedtime') {
+    lights.forEach(ga => {
+        if (ga) {
+            setGAValue(ga, false, '1.001');
+        }
+    });
+    node.status({fill: 'blue', shape: 'dot', text: 'All lights off'});
+    return;
+}
 return msg;`
     }
   ]