node-red-contrib-knx-ultimate 6.1.0 → 6.2.0

package/nodes/knxUltimateMatterBridge.html

@@ -67,6 +67,28 @@
       robotvacuum: [] // Flow-only: no GA fields, controlled via the node PINs
     };
     const TYPE_ORDER = ['onofflight', 'dimmablelight', 'rgblight', 'colortemperaturelight', 'onoffplug', 'windowcovering', 'thermostat', 'fan', 'temperaturesensor', 'humiditysensor', 'lightsensor', 'occupancysensor', 'contactsensor', 'smokecoalarm', 'waterleakdetector', 'airqualitysensor', 'robotvacuum'];
+    const FLOW_HELP = {
+      onofflight: { input: [['onoff', true]], output: [['onoff', true]] },
+      onoffplug: { input: [['onoff', true]], output: [['onoff', true]] },
+      dimmablelight: { input: [['onoff', true], ['level', 50]], output: [['onoff', true], ['level', 50]] },
+      rgblight: { input: [['onoff', true], ['level', 50], ['rgb', { red: 255, green: 80, blue: 20 }]], output: [['onoff', true], ['level', 50], ['rgb', { red: 255, green: 80, blue: 20 }]] },
+      colortemperaturelight: { input: [['onoff', true], ['level', 50], ['colortemp', 3000]], output: [['onoff', true], ['level', 50], ['colortemp', 3000]] },
+      temperaturesensor: { input: [['temperature', 21.5]], output: [] },
+      humiditysensor: { input: [['humidity', 45]], output: [] },
+      lightsensor: { input: [['illuminance', 500]], output: [] },
+      occupancysensor: { input: [['occupancy', true]], output: [] },
+      contactsensor: { input: [['contact', true]], output: [] },
+      windowcovering: { input: [['position', 35]], output: [['updown', false], ['position', 35], ['stop', true]] },
+      thermostat: { input: [['currenttemp', 21.5], ['setpoint', 21], ['coolingsetpoint', 24]], output: [['setpoint', 21], ['coolingsetpoint', 24]] },
+      smokecoalarm: { input: [['smoke', true], ['co', true]], output: [] },
+      waterleakdetector: { input: [['leak', true]], output: [] },
+      airqualitysensor: { input: [['co2', 850]], output: [] },
+      fan: { input: [['fanspeed', 60]], output: [['fanspeed', 60]] },
+      robotvacuum: {
+        input: [['rvcstate', 'charging'], ['rvcmode', 'idle']],
+        output: [['rvccommand', 'gohome'], ['rvccommand', 'pause'], ['rvccommand', 'resume'], ['rvcmode', 'cleaning']]
+      }
+    };
 
     // Every GA/DPT key across all types, used to declare the node defaults.
     const ALL_KEYS = [];
@@ -167,6 +189,25 @@
                 border-top: 1px solid #ccc;
                 margin: 8px 0;
               }
+              .matter-bridge-flow-help-table {
+                width: 100%;
+                border-collapse: collapse;
+                margin-bottom: 12px;
+              }
+              .matter-bridge-flow-help-table th,
+              .matter-bridge-flow-help-table td {
+                border-bottom: 1px solid #ddd;
+                padding: 7px 6px;
+                text-align: left;
+                vertical-align: top;
+              }
+              .matter-bridge-flow-help-table code {
+                white-space: pre-wrap;
+                word-break: break-word;
+              }
+              .matter-bridge-flow-help-copy {
+                white-space: nowrap;
+              }
             </style>`);
         }
         const $tabs = $('#mb-tabs');
@@ -217,6 +258,9 @@
         const $commandAdvancedRows = $('.mb-command-advanced-row');
         const $dimmerAdvancedRows = $('.mb-dimmer-advanced-row');
         const $coverAdvancedRows = $('.mb-cover-advanced-row');
+        const $pinSelect = $('#node-input-enableNodePINS');
+        const $flowHelp = $('#matter-bridge-flow-help');
+        const $nameInput = $('#node-input-name');
         const gaInputs = {};
 
         function createLabeledField(row, element, options = {}) {
@@ -272,6 +316,51 @@
           gaInputs[key] = { wrapper, $ga, $dpt, $labelSpan };
         });
 
+        const inputMessageCode = (fn, value) => `msg.payload = ${JSON.stringify({ function: fn, value }, null, 2)};\nreturn msg;`;
+        const outputMessageCode = (fn, value) => JSON.stringify({
+          topic: ($nameInput.val() || node.name || 'Matter device').toString(),
+          payload: value,
+          matter: { fn, value }
+        }, null, 2);
+        const appendFlowHelpRow = ($body, fn, code) => {
+          const $row = $('<tr></tr>');
+          $('<td><code></code></td>').find('code').text(fn).end().appendTo($row);
+          $('<td><code></code></td>').find('code').text(code).end().appendTo($row);
+          $('<td></td>').append(
+            $('<button type="button" class="red-ui-button matter-bridge-flow-help-copy"><i class="fa fa-copy"></i></button>')
+              .attr('title', node._('knxUltimateMatterBridge.flow_help.copy') || 'Copy')
+              .data('copy-text', code)
+          ).appendTo($row);
+          $body.append($row);
+        };
+        const copyFlowHelpText = (value) => {
+          const copied = () => RED.notify(node._('knxUltimateMatterBridge.flow_help.copied') || 'Message copied', 'success');
+          if (navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
+            navigator.clipboard.writeText(value).then(copied).catch(() => {
+              const $temporary = $('<textarea></textarea>').val(value).appendTo('body').select();
+              try { document.execCommand('copy'); copied(); } finally { $temporary.remove(); }
+            });
+            return;
+          }
+          const $temporary = $('<textarea></textarea>').val(value).appendTo('body').select();
+          try { document.execCommand('copy'); copied(); } finally { $temporary.remove(); }
+        };
+        const renderFlowHelp = () => {
+          const examples = FLOW_HELP[$type.val()] || { input: [], output: [] };
+          const $inputBody = $('#matter-bridge-flow-help-input-body').empty();
+          const $outputBody = $('#matter-bridge-flow-help-output-body').empty();
+          examples.input.forEach(([fn, value]) => appendFlowHelpRow($inputBody, fn, inputMessageCode(fn, value)));
+          examples.output.forEach(([fn, value]) => appendFlowHelpRow($outputBody, fn, outputMessageCode(fn, value)));
+          $('#matter-bridge-flow-help-input-empty').toggle(examples.input.length === 0);
+          $('#matter-bridge-flow-help-output-empty').toggle(examples.output.length === 0);
+          $('#matter-bridge-flow-help-output-table').toggle(examples.output.length > 0);
+        };
+        const updateFlowHelpVisibility = () => {
+          const visible = $pinSelect.val() === 'yes';
+          $flowHelp.toggle(visible);
+          if (visible) renderFlowHelp();
+        };
+
         function updateTypePresentation() {
           const selected = $type.val();
           const active = TYPE_FIELDS[selected] || [];
@@ -295,6 +384,7 @@
           $commandAdvancedRows.toggle(hasCommand);
           $dimmerAdvancedRows.toggle(hasLevel);
           $coverAdvancedRows.toggle(isCover);
+          updateFlowHelpVisibility();
         }
         $type.on('change', updateTypePresentation);
         updateTypePresentation();
@@ -312,7 +402,15 @@
         $('#node-input-coverUpdateMode').val(node.coverUpdateMode || 'optimistic');
         $('#node-input-coverStatusTimeoutMs').val(node.coverStatusTimeoutMs === undefined ? 3000 : node.coverStatusTimeoutMs);
         $('#node-input-readStatusAtStartup').val(node.readStatusAtStartup || 'yes');
-        $('#node-input-enableNodePINS').val(node.enableNodePINS || 'no');
+        $pinSelect.val(node.enableNodePINS || 'no');
+        $pinSelect.on('change.knxUltimateMatterBridge', updateFlowHelpVisibility);
+        $nameInput.on('change.knxUltimateMatterBridge input.knxUltimateMatterBridge', () => {
+          if ($flowHelp.is(':visible')) renderFlowHelp();
+        });
+        $flowHelp.off('click.knxUltimateMatterBridge').on('click.knxUltimateMatterBridge', '.matter-bridge-flow-help-copy', function () {
+          copyFlowHelpText($(this).data('copy-text') || '');
+        });
+        updateFlowHelpVisibility();
       },
       oneditsave() {
         try { RED.sidebar.show('info'); } catch (error) { /* empty */ }
@@ -479,18 +577,52 @@
         </select>
       </div>
 
-      <div class="form-row">
-        <label for="node-input-enableNodePINS" style="width:260px;">
-          <i class="fa fa-code"></i> <span data-i18n="knxUltimateMatterBridge.node_pins"></span>
-        </label>
-        <select id="node-input-enableNodePINS" style="width:220px;">
-          <option value="no" data-i18n="knxUltimateMatterBridge.node_pins_hide"></option>
-          <option value="yes" data-i18n="knxUltimateMatterBridge.node_pins_show"></option>
-        </select>
-      </div>
     </div>
   </div>
 
+  <div class="form-row" style="margin-top:12px;">
+    <label for="node-input-enableNodePINS" style="width:260px;">
+      <i class="fa fa-code"></i> <span data-i18n="knxUltimateMatterBridge.node_pins"></span>
+    </label>
+    <select id="node-input-enableNodePINS" style="width:220px;">
+      <option value="no" data-i18n="knxUltimateMatterBridge.node_pins_hide"></option>
+      <option value="yes" data-i18n="knxUltimateMatterBridge.node_pins_show"></option>
+    </select>
+  </div>
+
+  <div id="matter-bridge-flow-help" style="display:none; width:900px; margin-top:12px;">
+    <h4><i class="fa fa-code"></i> <span data-i18n="knxUltimateMatterBridge.flow_help.title"></span></h4>
+    <p data-i18n="knxUltimateMatterBridge.flow_help.intro"></p>
+
+    <h4 data-i18n="knxUltimateMatterBridge.flow_help.input_title"></h4>
+    <p data-i18n="knxUltimateMatterBridge.flow_help.input_hint"></p>
+    <table class="matter-bridge-flow-help-table">
+      <thead>
+        <tr>
+          <th data-i18n="knxUltimateMatterBridge.flow_help.function"></th>
+          <th data-i18n="knxUltimateMatterBridge.flow_help.message"></th>
+          <th></th>
+        </tr>
+      </thead>
+      <tbody id="matter-bridge-flow-help-input-body"></tbody>
+    </table>
+    <p id="matter-bridge-flow-help-input-empty" style="display:none;" data-i18n="knxUltimateMatterBridge.flow_help.no_input"></p>
+
+    <h4 data-i18n="knxUltimateMatterBridge.flow_help.output_title"></h4>
+    <p data-i18n="knxUltimateMatterBridge.flow_help.output_hint"></p>
+    <table id="matter-bridge-flow-help-output-table" class="matter-bridge-flow-help-table">
+      <thead>
+        <tr>
+          <th data-i18n="knxUltimateMatterBridge.flow_help.function"></th>
+          <th data-i18n="knxUltimateMatterBridge.flow_help.message"></th>
+          <th></th>
+        </tr>
+      </thead>
+      <tbody id="matter-bridge-flow-help-output-body"></tbody>
+    </table>
+    <p id="matter-bridge-flow-help-output-empty" style="display:none;" data-i18n="knxUltimateMatterBridge.flow_help.no_output"></p>
+  </div>
+
   <br/>
   <br/>
   <br/>
@@ -518,7 +650,8 @@ The advanced compatibility options are intentionally type-specific:
 
 The **KNX gateway is optional**: without it, enable the node PINs and drive the device from the flow.
 
-If you enable the **node PINs**:
+The PIN selector sits outside the tabs. Enabling it reveals a contextual **Flow input/output**
+section directly below, with copyable examples filtered to the selected device type:
 
 - input: `msg.payload = { function: "onoff", value: true }` updates the Matter state without the KNX bus
 - output: every command from a Matter controller is forwarded as `msg` (topic = device name, payload = value, `msg.matter` = raw command)

package/nodes/knxUltimateMatterControllerDevice.html

@@ -274,7 +274,7 @@
           const $refreshDevicesButton = $(".hue-refresh-devices");
           const $locateDeviceButton = $(".hue-locate-device");
           const $hueDevicesLoading = $(".hue-devices-loading");
-          const $inputHelpPanel = $("#tabs-input");
+          const $inputHelpPanel = $("#matter-flow-input-help");
           const UNIVERSAL_NODE_ID = '__UNIVERSAL__';
           const isUniversalMode = () => $matterControllerModeInput.val() === 'universal';
           $matterControllerModeInput.val(node.matterControllerMode || 'single');
@@ -921,9 +921,25 @@
             const caps = getEffectiveMatterCapabilities();
             const structure = inputStructureFor(caps);
             const endpointId = structure ? structure.endpointId : Number($matterEndpointInput.val() || node.matterEndpointId || 1);
+            const isMatterLight = !caps.profile;
             $('#matter-input-help-endpoint').text(String(endpointId));
             const $simpleBody = $('#matter-input-help-simple-body').empty();
-            if (caps.profile === 'doorLock') {
+            if (isMatterLight) {
+              const writeLabel = node._('knxUltimateMatterControllerDevice.input_help_write') || 'Write';
+              if (caps.onOff !== false) {
+                appendInputHelpRow($simpleBody, writeLabel, node._('knxUltimateMatterControllerDevice.input_functions.on') || 'On', 'msg.on = { on: true };\nreturn msg;');
+                appendInputHelpRow($simpleBody, writeLabel, node._('knxUltimateMatterControllerDevice.input_functions.off') || 'Off', 'msg.on = { on: false };\nreturn msg;');
+              }
+              if (caps.level !== false) {
+                appendInputHelpRow($simpleBody, writeLabel, node._('knxUltimateMatterControllerDevice.input_functions.brightness') || 'Brightness', 'msg.dimming = { brightness: 50 };\nreturn msg;');
+              }
+              if (caps.colorTemperature === true) {
+                appendInputHelpRow($simpleBody, writeLabel, node._('knxUltimateMatterControllerDevice.input_functions.color_temperature') || 'Colour temperature', 'msg.color_temperature = { mirek: 370 };\nreturn msg;');
+              }
+              if (caps.color === true) {
+                appendInputHelpRow($simpleBody, writeLabel, node._('knxUltimateMatterControllerDevice.input_functions.xy_color') || 'XY colour', 'msg.color = { xy: { x: 0.675, y: 0.322 } };\nreturn msg;');
+              }
+            } else if (caps.profile === 'doorLock') {
               if (caps.lockDoor !== false) appendInputHelpRow($simpleBody, node._('knxUltimateMatterControllerDevice.input_help_write') || 'Write', node._('knxUltimateMatterControllerDevice.input_functions.lock') || 'Lock', functionCode({ function: 'lock', value: true }));
               if (caps.unlockDoor !== false) appendInputHelpRow($simpleBody, node._('knxUltimateMatterControllerDevice.input_help_write') || 'Write', node._('knxUltimateMatterControllerDevice.input_functions.unlock') || 'Unlock', functionCode({ function: 'lock', value: false }));
             } else {
@@ -949,9 +965,19 @@
               });
             }
             $('#matter-input-help-simple-empty').toggle($simpleBody.children().length === 0);
+            $('#matter-input-help-simple-hint').attr(
+              'data-i18n',
+              isMatterLight
+                ? 'knxUltimateMatterControllerDevice.input_help_light_hint'
+                : 'knxUltimateMatterControllerDevice.input_help_simple_hint'
+            ).text(node._(
+              isMatterLight
+                ? 'knxUltimateMatterControllerDevice.input_help_light_hint'
+                : 'knxUltimateMatterControllerDevice.input_help_simple_hint'
+            ) || '');
 
             const $advancedBody = $('#matter-input-help-advanced-body').empty();
-            if (structure) {
+            if (structure && !isMatterLight) {
               structure.clusters.forEach((cluster) => {
                 (cluster.attributes || []).forEach((attribute) => {
                   const prefix = `${cluster.name || 'Cluster'} (${cluster.id}) · ${attribute.name} (${attribute.id})`;
@@ -967,6 +993,7 @@
               });
             }
             $('#matter-input-help-advanced-empty').toggle($advancedBody.children().length === 0);
+            $('#matter-input-help-advanced-details').toggle(!isMatterLight);
           };
           const copyInputHelpText = (text) => {
             const copied = () => RED.notify(node._('knxUltimateMatterControllerDevice.input_help_copied') || 'Message copied', 'success');
@@ -985,11 +1012,6 @@
           });
           $tabs.addClass('hue-vertical-tabs');
           $tabs.tabs(); // Tabs gestione KNX
-          $tabs.off('tabsactivate.matterInputHelp').on('tabsactivate.matterInputHelp', (event, ui) => {
-            if (ui && ui.newPanel && ui.newPanel.attr('id') === 'tabs-input') {
-              renderInputHelp();
-            }
-          });
           $tabs.find('ul').addClass('ui-tabs-nav');
           $tabs.find('li').removeClass('ui-corner-top').addClass('ui-corner-left');
           $universalTabs.addClass('hue-vertical-tabs');
@@ -1300,7 +1322,6 @@
             setMatterTabVisible('tabs-3', !isUniversal && knxSelected && supportsTemperature);
             setMatterTabVisible('tabs-4', !isUniversal && knxSelected && supportsColor);
             setMatterTabVisible('tabs-mapped', !isUniversal && knxSelected && isMapped);
-            setMatterTabVisible('tabs-input', !isUniversal && hasHueDevice && (isMapped || isDoorLock));
             setMatterTabVisible('tabs-6', !isUniversal && knxSelected && hasHueDevice);
             $('#matter-universal-description').toggle(isUniversal);
             $pinSelect.val(isUniversal ? 'yes' : $pinSelect.val()).prop('disabled', isUniversal);
@@ -1316,7 +1337,9 @@
             $('#matter-door-lock-pin-required').toggle(isDoorLock && caps.requirePinForRemoteOperation === true);
             $('#matter-mapped-profile').toggle(isMapped);
             if (isMapped) renderMappedProfile(caps.mappedTargets || []);
-            if (hasHueDevice && !isUniversal && (isMapped || isDoorLock)) renderInputHelp();
+            const showInputHelp = !isUniversal && hasHueDevice && $pinSelect.val() === 'yes';
+            $inputHelpPanel.toggle(showInputHelp);
+            if (showInputHelp) renderInputHelp();
             $('#matter-selected-device-type-value').text(deviceTypeDisplay);
             $('#matter-selected-device-type').toggle(hasHueDevice && deviceTypeDisplay !== '');
             try { $tabs.tabs('refresh'); } catch (error) { /* empty */ }
@@ -1440,6 +1463,7 @@
           });
 
           $hueDeviceInput.on('change.knxUltimateMatterControllerDevice input.knxUltimateMatterControllerDevice', updateTabsVisibility);
+          $pinSelect.on('change.knxUltimateMatterControllerDevice', updateTabsVisibility);
 
           if (($deviceNameInput.val() || '').trim() !== '') {
             applyHueDevicesPlaceholder(true);
@@ -2134,7 +2158,6 @@
         <li><a href="#tabs-3"><i class="fa-solid fa-temperature-quarter"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.tunable_white"></span></a></li>
         <li><a href="#tabs-4"><i class="fa-solid fa-palette"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.rgb_hsv"></span></a></li>
         <li><a href="#tabs-mapped"><i class="fa-solid fa-list-check"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.mappings"></span></a></li>
-        <li><a href="#tabs-input"><i class="fa-solid fa-code"></i> <span data-i18n="knxUltimateMatterControllerDevice.input_help_label"></span></a></li>
         <li><a href="#tabs-6"><i class="fa-solid fa-code-merge"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.behaviour"></span></a></li>
       </ul>
       <div id="tabs-mapped">
@@ -2142,46 +2165,6 @@
           <div id="matter-mapped-profile-body"></div>
         </div>
       </div>
-      <div id="tabs-input">
-        <p class="form-tips" data-i18n="knxUltimateMatterControllerDevice.input_help_pin_hint"></p>
-        <p>
-          <strong data-i18n="knxUltimateMatterControllerDevice.input_help_endpoint"></strong>:
-          <code id="matter-input-help-endpoint"></code>.
-          <span data-i18n="knxUltimateMatterControllerDevice.input_help_endpoint_hint"></span>
-        </p>
-        <h4 data-i18n="knxUltimateMatterControllerDevice.input_help_simple_title"></h4>
-        <p data-i18n="knxUltimateMatterControllerDevice.input_help_simple_hint"></p>
-        <table class="matter-input-help-table">
-          <thead>
-            <tr>
-              <th data-i18n="knxUltimateMatterControllerDevice.input_help_operation"></th>
-              <th data-i18n="knxUltimateMatterControllerDevice.input_help_function"></th>
-              <th data-i18n="knxUltimateMatterControllerDevice.input_help_message"></th>
-              <th></th>
-            </tr>
-          </thead>
-          <tbody id="matter-input-help-simple-body"></tbody>
-        </table>
-        <p id="matter-input-help-simple-empty" style="display:none;" data-i18n="knxUltimateMatterControllerDevice.input_help_no_simple"></p>
-        <details>
-          <summary><strong data-i18n="knxUltimateMatterControllerDevice.input_help_advanced_title"></strong></summary>
-          <p data-i18n="knxUltimateMatterControllerDevice.input_help_advanced_hint"></p>
-          <div class="matter-input-help-advanced">
-            <table class="matter-input-help-table">
-              <thead>
-                <tr>
-                  <th data-i18n="knxUltimateMatterControllerDevice.input_help_operation"></th>
-                  <th data-i18n="knxUltimateMatterControllerDevice.input_help_target"></th>
-                  <th data-i18n="knxUltimateMatterControllerDevice.input_help_message"></th>
-                  <th></th>
-                </tr>
-              </thead>
-              <tbody id="matter-input-help-advanced-body"></tbody>
-            </table>
-            <p id="matter-input-help-advanced-empty" style="display:none;" data-i18n="knxUltimateMatterControllerDevice.input_help_no_structure"></p>
-          </div>
-        </details>
-      </div>
       <div id="tabs-1">
         <p>
         <div class="form-row">
@@ -2623,6 +2606,46 @@
         <option value="yes" data-i18n="knxUltimateMatterControllerDevice.node_pins_show"></option>
       </select>
     </div>
+    <div id="matter-flow-input-help" style="display:none; width:900px; margin-top:12px;">
+      <h4><i class="fa-solid fa-code"></i> <span data-i18n="knxUltimateMatterControllerDevice.input_help_label"></span></h4>
+      <p>
+        <strong data-i18n="knxUltimateMatterControllerDevice.input_help_endpoint"></strong>:
+        <code id="matter-input-help-endpoint"></code>.
+        <span data-i18n="knxUltimateMatterControllerDevice.input_help_endpoint_hint"></span>
+      </p>
+      <h4 data-i18n="knxUltimateMatterControllerDevice.input_help_simple_title"></h4>
+      <p id="matter-input-help-simple-hint" data-i18n="knxUltimateMatterControllerDevice.input_help_simple_hint"></p>
+      <table class="matter-input-help-table">
+        <thead>
+          <tr>
+            <th data-i18n="knxUltimateMatterControllerDevice.input_help_operation"></th>
+            <th data-i18n="knxUltimateMatterControllerDevice.input_help_function"></th>
+            <th data-i18n="knxUltimateMatterControllerDevice.input_help_message"></th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody id="matter-input-help-simple-body"></tbody>
+      </table>
+      <p id="matter-input-help-simple-empty" style="display:none;" data-i18n="knxUltimateMatterControllerDevice.input_help_no_simple"></p>
+      <details id="matter-input-help-advanced-details">
+        <summary><strong data-i18n="knxUltimateMatterControllerDevice.input_help_advanced_title"></strong></summary>
+        <p data-i18n="knxUltimateMatterControllerDevice.input_help_advanced_hint"></p>
+        <div class="matter-input-help-advanced">
+          <table class="matter-input-help-table">
+            <thead>
+              <tr>
+                <th data-i18n="knxUltimateMatterControllerDevice.input_help_operation"></th>
+                <th data-i18n="knxUltimateMatterControllerDevice.input_help_target"></th>
+                <th data-i18n="knxUltimateMatterControllerDevice.input_help_message"></th>
+                <th></th>
+              </tr>
+            </thead>
+            <tbody id="matter-input-help-advanced-body"></tbody>
+          </table>
+          <p id="matter-input-help-advanced-empty" style="display:none;" data-i18n="knxUltimateMatterControllerDevice.input_help_no_structure"></p>
+        </div>
+      </details>
+    </div>
   </div>
 
   <br/>
@@ -2647,9 +2670,11 @@ optional flow output; simpler endpoints continue through the generic mapped fall
 
 **Flow input**
 
-For a selected non-light endpoint, open the **Flow input** tab in the editor.
-The capability-driven tab shows copyable simple examples plus the selected endpoint,
-all advertised readable/writable attributes and all accepted commands.
+Enable **Node Input/Output PINs** to reveal the **Flow input** section directly below
+the selector. Lights show copyable examples for supported top-level properties such as
+`msg.on`, `msg.dimming`, `msg.color_temperature` and `msg.color`. For non-light
+endpoints the section shows the selected endpoint, all advertised readable/writable
+attributes and all accepted commands.
 
 Use `msg.payload = {function:"position", value:35}` for a simple write. Omit `value`
 to read a supported state, for example `{function:"temperature"}`. Values use human
@@ -2779,7 +2804,7 @@ _Basic Matter effects_
 | Read status at startup | Read the Matter endpoint status at Node-RED startup or full deploy and send it to the KNX bus. |
 | KNX Brightness Status | Updates the KNX brightness status whenever the Matter light switches ON/OFF. It can send 0% while OFF and restore the previous value when ON, or leave the brightness status unchanged. |
 | Update local cached Matter state from KNX bus writes | When enabled, KNX writes immediately update the local Matter-state cache without waiting for the endpoint report. Disable it if the cache should follow only real Matter reports. |
-| Node Input/Output PINs | For mapped endpoints, use the simple `msg.payload = {function,value}` contract shown in the **Flow input** tab, or the advanced top-level Matter selectors. Read an attribute with `msg.clusterId` and `msg.attribute`; add `msg.requestFromRemote = true` to force a device read. Add `msg.value` to write, or use `msg.command` and `msg.args`. Door Lock accepts both `msg.payload = true/false` and `{function:"lock",value:true/false}`. |
+| Node Input/Output PINs | Reveals the **Flow input** section below the selector. Lights use the supported top-level state properties shown there (`msg.on`, `msg.dimming`, `msg.color_temperature`, `msg.color`). Mapped endpoints use `msg.payload = {function,value}` or the advanced Matter selectors. Door Lock accepts both `msg.payload = true/false` and `{function:"lock",value:true/false}`. |
 | Switch on behaviour | It sets the behaviour of your lights when switched on. You can choose from differents behaviours.<br/> **Select color: ** the light will be switched on with the color of your choice. To change color, just CLICK on the color selector (under the _Select color_ control).<br/>**Select temperature and brightness: ** the light will be switched on with the temperature (Kelvin) and brightness (0-100) of your choice.<br/>**None:** the light will retain its last status. In case you've enable the night lighting, after the night time ends, the lamp will resume the color/temperature/brightness state set at day time. |
 | Night Lighting | It allows to set a particular light color/brightness at nighttime. The options are the same as the daytime. You could select either a temperature/brightness or color. A cozy temperature of 2700 Kelvin, with a brightness of 10% or 20%, is a good choice for bathroom's night light.|
 | Day/Night | Select the group address used to set the day/night behaviour. The group address value is _true_ if daytime, _false_ if nighttime. |

package/nodes/locales/de/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 Dieser Node überwacht **alle KNX-Telegramme** des ausgewählten KNX-Ultimate-Gateways, erstellt Verkehrsstatistiken, erkennt Anomalien und kann optional ein LLM befragen.
 
+Die Editor-Bereiche verwenden dieselben vertikalen Tabs auf der linken Seite wie die Matter-Nodes. **Schnelleinrichtung** enthält nur die üblichen KI-Einstellungen (Aktivierung, Anbieter, Zugangsdaten, Modell, KNX-Zustandsabfrage/Aktorsteuerung und Bestätigung); technische Parameter sind thematisch in den übrigen Tabs gruppiert.
+
 ## Ausgänge
 1. **Zusammenfassung/Statistik** (`msg.payload` JSON)
 2. **Anomalien** (`msg.payload` JSON)
 3. **KI-Assistent** (`msg.payload` Text, mit `msg.summary`)
+4. **KNX-Operationen** (eine Universal-Mode-Nachricht je validierter Lese- oder Schreiboperation)
+
+Jede an den Ausgängen 3 und 4 ausgegebene Nachricht enthält außerdem eine Kopie der ursprünglichen Eingangsnachricht in `msg.inputMessage`. Dadurch bleiben der ursprüngliche Payload, das Topic, die Chat-Metadaten und alle weiteren Eingangseigenschaften für nachfolgende Nodes verfügbar. Fehler beim Klonen oder Ausgeben werden abgefangen und gemeldet, statt in die Node-RED-Laufzeit zu gelangen.
 
 ## Befehle (Eingang)
 Sende `msg.topic`:
 - `summary` (oder leer): Summary sofort senden
 - `reset`: internen Verlauf/Zähler zurücksetzen
 - `ask`: Frage an das konfigurierte LLM senden
+- `confirm` / `cancel`: ausstehende KNX-Befehle ohne erneuten LLM-Aufruf bestätigen oder abbrechen
+- `clear_chat`: Gesprächsspeicher der aktuellen Sitzung löschen
+
+Für `ask` die Frage in `msg.prompt` (empfohlen), `msg.payload` (String) oder den üblichen Telegram-Feldern `msg.payload.content` / `msg.payload.text` übergeben.
+
+Bei aktiviertem KNX-Steuern werden die letzten Gesprächsschritte im RAM nach `msg.knxAi.sessionId`, `msg.sessionId` oder erkannter Telegram-Chat-ID getrennt. Ausgang 3 mit dem Chat-Sender und Ausgang 4 mit einem KNX-Ultimate-Node im **Universalmodus** verbinden. Bei aktiver Bestätigung zeigt die erste Antwort GA, DPT und Payload, ohne Schreiboperationen auszugeben; dieselbe Sitzung muss innerhalb von 5 Minuten `BESTÄTIGEN` oder `ABBRECHEN` antworten. Eine neue Anfrage ersetzt einen älteren Plan. Jeder bestätigte Befehl enthält `msg.destination`, `msg.dpt`, `msg.payload` und `msg.event = "GroupValue_Write"`.
+Bei DPT-1.xxx-Schreibvorgängen werden die sicheren KI-Entsprechungen `true`/`false`, `1`/`0` und `on`/`off` vor der lokalen Validierung und Ausgabe in echte Boolesche Werte normalisiert.
+
+### Aktuelle KNX-Lesewerte
+Wenn der Benutzer ausdrücklich einen aktuellen oder aktualisierten Zustand anfordert, kann die KI exakte Objekte aus dem importierten ETS-Katalog abfragen, einschließlich Status- und anderer schreibgeschützter Objekte. Ausgang 4 gibt `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"` und `msg.readstatus = true` aus. Der Node wartet bis zu 6 Sekunden auf jede `GroupValue_Response` oder ein aktuelles Write-Telegramm, gibt anschließend die dekodierten Werte an Ausgang 3 zurück und stellt Details in `msg.knxAi.readResults` bereit. Leseoperationen erfordern keine Bestätigung und werden niemals in Schreiboperationen umgewandelt.
+
+### Bestätigungsanfrage für Chat-Schaltflächen
+Solange ein Plan aussteht, enthält Ausgang 3 `msg.knxAi.confirmationRequest`. Das Objekt enthält `required`, `status`, `sessionId`, `expiresAt`, `commandCount` und zwei Einträge in `actions`. Verwenden Sie `action.label` als Text der Telegram-Schaltfläche, `action.callbackData` als Callback und senden Sie `action.message` an KNX AI zurück, um ohne Texteingabe zu bestätigen oder abzubrechen.
+
+### Chat-Adapter-Vorlagen
+Der Tab **Chat-Adapter** lädt seine auswählbaren Zuordnungen aus `resources/KNXAIChatAdapterMappings.js`. Die Auswahl einer Vorlage fügt zwei bearbeitbare synchrone JavaScript-Zuordnungen in Textfeldern über die volle Breite ein: eine vor der Verarbeitung des Eingangs durch KNX AI und eine vor der Ausgabe an Ausgang 3. Geben Sie `msg` zurück, um fortzufahren, oder keinen Wert, um die Nachricht zu verwerfen. Syntax- und Laufzeitfehler werden abgefangen und gemeldet, ohne Node-RED anzuhalten.
+
+Die enthaltene Vorlage **windkh/node-red-contrib-telegrambot** folgt dem Receiver-/Sender-Vertrag des Pakets. Verbinden Sie einen `telegram receiver` direkt mit KNX AI und Ausgang 3 direkt mit einem `telegram sender`. Für Inline-Bestätigungsschaltflächen verbinden Sie zusätzlich einen als `callback_query` konfigurierten `telegram event` mit demselben KNX-AI-Eingang. Die Eingangszuordnung liest `msg.payload.content`, `msg.payload.chatId` und die Telegram-Sprache. Die Ausgangszuordnung erstellt `msg.payload.chatId`, `type` und `content` und ergänzt bei ausstehender Schreibbestätigung `options.reply_markup` aus `msg.knxAi.confirmationRequest`. Das Telegram-Paket bleibt eine separate optionale Abhängigkeit.
 
-Für `ask` die Frage in `msg.prompt` (empfohlen) oder `msg.payload` (String) übergeben.
+## Kurzer Ablauf: KNX-Steuerung
+1. Importieren Sie die ETS-CSV in das Gateway und konfigurieren Sie LLM-Anbieter, Modell und Zugangsdaten.
+2. Aktivieren Sie **LLM-Assistent** und **KNX-Zustände lesen und Aktoren steuern**; lassen Sie die Bestätigung aktiviert.
+3. Verbinden Sie den Chat-Eingang mit KNX AI und behalten Sie eine stabile Sitzungs-/Chat-ID bei.
+4. Verbinden Sie Ausgang 3 mit der Chat-Antwort und Ausgang 4 mit KNX Ultimate im **Universalmodus**.
+5. Der Benutzer sendet eine Anfrage; aktuelle Zustandsabfragen werden sofort gelesen, während Schreiboperationen zuerst GA, DPT und Wert ohne Bus-Schreibzugriff anzeigen.
+6. Innerhalb von 5 Minuten antwortet derselbe Chat exakt mit `BESTÄTIGEN` oder `ABBRECHEN`.
+7. Nur `BESTÄTIGEN` validiert erneut und gibt Befehle an Ausgang 4 aus; prüfen Sie die Ausführung über eine KNX-Status-GA.
 
 ## Konfigurationsfelder
 Hier sind alle Felder aufgeführt, wie sie im KNX-AI-Editor sichtbar sind.
@@ -53,7 +83,13 @@ Hier sind alle Felder aufgeführt, wie sie im KNX-AI-Editor sichtbar sind.
 - **Endpoint URL**: URL des Chat/Completions-Endpunkts.
 - **API key**: API-Schlüssel (für lokales Ollama nicht erforderlich).
 - **Model**: Modell-ID/Name.
+- **Chatmodell-Kompatibilität**: Das ausgewählte Modell muss den konfigurierten Chat-Completions-Endpunkt unterstützen. Ältere reine Completions-Modelle wie `gpt-3.5-turbo-instruct` werden beim Aktualisieren der Modellliste ausgeschlossen. Lehnt der Anbieter einen benutzerdefinierten Temperaturwert oder den Token-Limit-Parameter ab, wiederholt KNX AI die Anfrage und entfernt oder ersetzt nur das inkompatible Feld.
 - **System prompt**: Globale Instruktion für KNX-Analyse (Advanced).
+- **KI darf KNX-Zustände lesen und Aktoren steuern**: Aktiviert Ausgang 4 und ist standardmäßig aus. Exakte ETS-Katalogobjekte dürfen gelesen werden; Schreiboperationen werden ausschließlich für Objekte mit Rolle `command` akzeptiert. Unbekannte, DPT-falsche, ungültige oder überzählige Operationen sowie Schreiboperationen auf Status-/Neutralobjekte werden lokal abgewiesen.
+- **Vor dem Senden von KNX-Befehlen bestätigen lassen**: Standardmäßig aktiv. Zeigt zuerst die validierten Änderungen und sendet nichts, bis dieselbe Chat-Sitzung bestätigt. Wenn Befehle auf Bestätigung warten, fügt die Antwort immer die genauen Anweisungen zum Bestätigen oder Abbrechen in der Sprache der aktuellen Anfrage hinzu. Vor der Ausgabe werden die Befehle erneut validiert.
+- **Adapter-Vorlage**: Lädt ein Paar aus Ein- und Ausgangszuordnung aus der mitgelieferten Chat-Adapter-Datei. Die Auswahl ersetzt bewusst beide Textfelder; der Code bleibt danach bearbeitbar.
+- **Eingangszuordnung (Chat → KNX AI)**: Synchrones JavaScript vor der Verarbeitung des Eingangsbefehls.
+- **Ausgangszuordnung (KNX AI → Chat)**: Synchrones JavaScript ausschließlich für Nachrichten an Ausgang 3.
 - Wenn das Festplattenarchiv aktiv ist, nutzt **Ask** standardmäßig dieses Archiv: explizite Datumsangaben/Zeitbereiche werden beachtet, sonst durchsucht der Assistent die letzten 24 Stunden plus aktuelle RAM-Events.
 - **Include raw payload hex**: Rohe Hex-Payload im Prompt einfügen.
 - **Node-RED-Projektinventar einbeziehen**: Nimmt das gesamte Node-RED-Projektinventar in den Prompt auf, einschließlich KNX-Nodes und anderer hilfreicher Nodes wie function/change/inject/template, wenn sie KNX-Logik oder Gruppenadressen enthalten.
@@ -84,5 +120,5 @@ Hier sind alle Felder aufgeführt, wie sie im KNX-AI-Editor sichtbar sind.
 - Wenn Node-RED in Docker läuft, im Endpoint `host.docker.internal` statt `localhost` verwenden.
 
 ## Sicherheitshinweis
-Bei aktiviertem LLM kann KNX-Traffic-Kontext an den konfigurierten Endpoint gesendet werden. Für striktes On-Premise lokale Provider verwenden.
+Bei aktiviertem LLM kann KNX-Traffic-Kontext an den konfigurierten Endpoint gesendet werden. Für striktes On-Premise lokale Provider verwenden. Ein Befehl an Ausgang 4 hat die lokale Validierung bestanden und wurde an den Flow weitergegeben; dies bestätigt nicht die Ausführung durch den Aktor. Dafür eine KNX-Status-GA verwenden.
 </script>

package/nodes/locales/de/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Schnelleinrichtung",
       "capture": "Capture",
       "storage": "Speicher & Zusammenfassung",
       "detection": "Erkennung & Warnungen",
       "llmConnection": "KI-Assistent-Verbindung",
       "llmContext": "KI-Assistent-Kontext",
-      "advanced": "Erweiterte Einstellungen"
+      "chatAdapter": "Chat-Adapter",
+      "advanced": "Erweiterte KI"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Node-RED-Projektinventar einbeziehen",
+      "llmAllowKnxCommands": "KI darf KNX-Zustände lesen und Aktoren steuern",
+      "llmRequireCommandConfirmation": "Vor dem Senden von KNX-Befehlen bestätigen lassen",
+      "chatAdapterPreset": "Adapter-Vorlage",
+      "chatInputCode": "Eingangszuordnung (Chat → KNX AI)",
+      "chatOutputCode": "Ausgangszuordnung (KNX AI → Chat)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Zusammenfassung/Statistik",
       "anomalies": "Anomalien",
-      "assistant": "KI-Assistent"
+      "assistant": "KI-Assistent",
+      "knxCommands": "KNX-Operationen"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "Kein Adapter"
       }
     },
     "placeholder": {
@@ -67,7 +78,9 @@
       "installedOllamaModel": "Ollama model installed",
       "installOllamaModelFailed": "Failed to install Ollama model",
       "ollamaInstallSteps": "1) Open the model library and copy the model name (for example llama3.1). 2) Put the name in the Model field and click Install it.",
-      "ollamaStartedAuto": "Ollama server started automatically."
+      "ollamaStartedAuto": "Ollama server started automatically.",
+      "chatAdapterIntro": "Wählen Sie eine Vorlage, um den Code für Ein- und Ausgang einzufügen. Die Liste wird aus der mitgelieferten Chat-Adapter-Datei geladen; der erzeugte Code bleibt bearbeitbar.",
+      "chatAdapterCodeHelp": "Zuordnungen laufen synchron. Geben Sie msg zurück, um fortzufahren, oder keinen Wert, um die Nachricht zu verwerfen. Fehler werden abgefangen und gemeldet, ohne Node-RED anzuhalten."
     },
     "sidebar": {
       "ui": {

package/nodes/locales/de/knxUltimateMatterBridge.html

@@ -45,7 +45,7 @@ Diese Optionen werden nur angezeigt, wenn sie zum gewählten Typ passen. Dimmbar
 
 ## Node-PINs
 
-Wenn du die Input/Output-PINs des Nodes aktivierst:
+Der PIN-Selektor befindet sich außerhalb der Editor-Tabs. Nach dem Aktivieren erscheint direkt darunter ein kontextbezogener Bereich **Flow-Eingang/-Ausgang** mit kopierbaren Beispielen für den ausgewählten Gerätetyp:
 
 - **Input**: aktualisiere den Matter-Zustand aus dem Flow, ohne den KNX-Bus: `msg.payload = { function: "onoff", value: true }` (`function` ist eine von `onoff`, `level`, `rgb`, `colortemp`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`, `fanspeed`, `smoke`, `co`, `leak`, `co2`, `rvcstate`, `rvcmode`). Nützlich, um im Flow berechnete Werte (z.B. einen virtuellen Sensor) für Alexa & Co. bereitzustellen.
 - **Output**: Jeder von einem Matter-Controller empfangene Befehl wird an den Flow weitergeleitet: `msg.topic` = Gerätename, `msg.payload` = Wert, `msg.matter` = der rohe Befehl. Ein Gerät ohne Befehls-GAs wird zum **Nur-Flow-Gerät**.

package/nodes/locales/de/knxUltimateMatterBridge.json

@@ -36,6 +36,20 @@
       "mappings": "KNX-Zuordnungen",
       "advanced": "Erweiterte Optionen"
     },
+    "flow_help": {
+      "title": "Flow-Eingang/-Ausgang",
+      "intro": "Diese Beispiele entsprechen dem ausgewählten Gerätetyp und sind verfügbar, solange die Ein-/Ausgangs-PINs aktiviert sind.",
+      "input_title": "Flow → Matter (Node-Eingang)",
+      "input_hint": "Sende eine dieser Nachrichten, um den bereitgestellten Matter-Zustand ohne KNX-Schreibvorgang zu aktualisieren.",
+      "output_title": "Matter → Flow (Node-Ausgang)",
+      "output_hint": "Befehle eines Matter-Controllers werden mit dem Wert in msg.payload und den Rohdetails in msg.matter ausgegeben.",
+      "function": "Funktion",
+      "message": "Beispielnachricht",
+      "copy": "Kopieren",
+      "copied": "Nachricht kopiert",
+      "no_input": "Für diesen Gerätetyp gibt es keine Beispiele für Flow-Zustandsupdates.",
+      "no_output": "Dieser Gerätetyp gibt keine Controller-Befehle aus; sein Ausgang bleibt inaktiv."
+    },
     "functions": {
       "fn_onoff_cmd": "Ein/Aus Befehls-GA",
       "fn_onoff_status": "Ein/Aus Status-GA",

package/nodes/locales/de/knxUltimateMatterControllerDevice.html

@@ -19,11 +19,11 @@ Er ersetzt die unveröffentlichten getrennten Matter-Controller-Nodes und behäl
 | Sensoren | Sensor-Endpunkte zeigen ihre Mess-/Status-GA nur bei Unterstützung: Temperatur, Feuchte, Helligkeit, Präsenz, Kontakt und Batterie. |
 | Read at startup | Veröffentlicht den gecachten Matter-Wert beim Deploy/Start oder wenn sich das Gerät erneut verbindet. |
 | Update local state from KNX write | Aktualisiert den lokalen Matter/KNX-Cache, wenn ein Telegramm auf eine konfigurierte KNX-GA geschrieben wird. |
-| Node Input/Output PINs | Zeigt Node-RED-Eingangs-/Ausgangspins. Nicht-Licht-Endpunkte akzeptieren das einfache `{function,value}`-Format und die erweiterten Matter-Felder; der Ausgang sendet Statusupdates. |
+| Node Input/Output PINs | Zeigt Node-RED-Eingangs-/Ausgangspins und direkt darunter den Bereich **Flow-Eingang**. Für Leuchten werden die unterstützten Lichtzustands-Nachrichten auf oberster Ebene angezeigt; andere Endpunkte zeigen das einfache `{function,value}`-Format und die erweiterten Matter-Felder. |
 
 ## Flow-Eingang
 
-Öffne bei einem ausgewählten Nicht-Licht-Endpunkt den Tab **Flow-Eingang**. Der Tab wird aus der angekündigten Endpunktstruktur aufgebaut und zeigt kopierbare Beispiele, die Endpoint ID sowie alle lesbaren/schreibbaren Attribute und akzeptierten Befehle. Er bleibt auch verfügbar, wenn der Knoten ohne KNX-Gateway nur im Flow verwendet wird.
+Aktiviere **Node Input/Output PINs**, um den Bereich **Flow-Eingang** direkt unter dem Auswahlfeld einzublenden. Für Leuchten zeigt er kopierbare Beispiele der unterstützten Eigenschaften auf oberster Ebene, etwa `msg.on`, `msg.dimming`, `msg.color_temperature` und `msg.color`. Für andere Endpunkte wird er aus der angekündigten Struktur aufgebaut und zeigt Endpoint ID sowie alle lesbaren/schreibbaren Attribute und akzeptierten Befehle. Er bleibt auch ohne KNX-Gateway verfügbar.
 
 Einfache Schreibvorgänge verwenden `msg.payload = {function:"position",value:35}`. Ohne `value` wird ein unterstützter Zustand gelesen, zum Beispiel `{function:"temperature"}`; die Ausgabe verwendet verständliche Einheiten und enthält Rohdetails in `msg.matter`. Funktionen wie `onoff`, `level`, `position`, `open`, `close`, `stop`, Sollwerte, Lüfter und Sensoren erscheinen nur bei Unterstützung. Türschlösser akzeptieren `{function:"lock",value:true|false}`.