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

package/CHANGELOG.md

@@ -6,14 +6,18 @@
 
 # CHANGELOG
 
-**Version 6.0.12** - July 2026<br/>
+**Version 6.1.0** - July 2026<br/>
 
+- **Matter Controller — QR pairing-code reader**: the pairing editor can now fill the existing `MT:…` field by scanning a QR code with the local webcam or reading it from a selected image, including inverted white-on-dark QR codes used by some device web interfaces. Decoding remains entirely in the browser and never uploads the image or video; after a valid QR is read, pairing starts automatically, while manually typed codes still require **PAIR**. The optional device name is positioned before the scanner, the decoded code remains visible underneath it and fabric backup controls have moved to the bottom of the editor. A prominent blocking progress overlay prevents further editor interactions until commissioning succeeds or fails. When live camera access is unavailable because the editor is not open over HTTPS/`localhost`, permission was denied or the browser lacks camera support, the editor explains the reason and keeps image loading available.<br/>
+- **Matter Controller — commissioned-device status**: fixed the connection-state import for the installed matter.js API, so the associated-devices table now reports `connected`, `disconnected`, `reconnecting` or `waitingfordiscovery` instead of misleading values such as `unknown (0)`. The table has also been regression-tested to preserve every row returned by the controller without collapsing equal Node IDs.<br/>
+- **Matter Controller — per-device command isolation**: commands now remain ordered inside an independent execution lane for each commissioned Node ID instead of sharing one blocking serial queue. An offline, timing-out or removed device can no longer delay other Matter Controller nodes that react to the same KNX group address. Removed Node IDs are rejected before queueing, every Matter operation has a bounded timeout and pending commands are purged on removal. An unavailable Controller node latches its red status and ignores subsequent KNX/flow commands instead of accepting them optimistically; it resumes automatically when that specific Matter device reports `connected`, while opening the node editor explicitly enables a manual retry.<br/>
 - **Control Matter from KNX — Universal Mode**: a dedicated **Mode** selector now switches between a single Matter device and controller-wide Universal Mode. Its **Universal Battery Monitor** scans every commissioned node and endpoint for battery Power Source clusters, maintains a normalized cache, publishes an optional aggregate KNX alarm as DPT 1.005, cycles low-battery device names every 2 seconds as DPT 16.001, and answers `getAllBatteries` flow queries. The alternative **All Matter events** service preserves the generic attribute/event stream and dynamic read/write/command input.<br/>
 - **Universal Battery Monitor — KNX editor and diagnostics**: battery options now use the same vertical-tab and ETS/CSV group-address selectors as single-device profiles. Alarm and text mappings are aligned as Function/GA/DPT/Name rows, support editable names and KNX read responses, ignore wired Power Source endpoints, and show an aggregate battery status instead of per-device `unknown` states.<br/>
 - **Matter light capability refresh**: Color Control `featureMap` and the endpoint device type now drive the Tunable White and RGB/HSV tabs. New selections, changed devices and previously saved nodes normalize stale capabilities so Tunable White lights no longer retain unsupported colour mappings.<br/>
 - **Matter editor/help cleanup**: decorative animated light icons and duplicate localized help headings were removed from the Matter Controller, Matter Bridge and shared light editor where applicable.<br/>
 - **Matter Bridge — editor tab orientation**: the device editor now uses the same left-hand vertical tab layout as Matter Controller, keeping Mappings and Advanced options visually consistent without changing saved configuration.<br/>
-- **Control Matter from KNX — dedicated controller profiles**: Window Covering (`0x0102`), Thermostat (`0x0201`), Fan Control (`0x0202`) and Switch (`0x003B`) endpoints are now selected into explicit capability-driven profiles instead of the anonymous mapped fallback. They share the guarded mapping lifecycle while enforcing their native input/event cluster boundary and presenting semantic canvas status; Switch initial/long/multi-press events are filtered to the selected endpoint and exposed on the optional flow output. Simple actuators and sensors remain on the generic mapped profile.<br/>
+- **Control Matter from KNX — simple flow input and capability help**: non-light endpoints now accept the same human-readable `msg.payload = { function, value }` contract used by Matter Bridge. The selected node and endpoint are implicit; percentages, temperatures and measurements use human units, while omitting `value` reads a supported state. A capability-driven **Flow input** tab, consistent with the node's existing editor tabs, replaces the modal help button and provides copyable simple examples plus every advertised readable/writable attribute, command, cluster ID and advanced message. It remains available for flow-only nodes without a KNX gateway. Existing top-level `clusterId`/`command`/`attribute` inputs remain compatible, and Door Lock also accepts `{function:"lock",value:true|false}`.<br/>
+- **Control Matter from KNX — dedicated controller profiles**: Window Covering (`0x0102`), Thermostat (`0x0201`), Fan Control (`0x0202`) and Switch (`0x003B`) endpoints are now selected into explicit capability-driven profiles instead of the anonymous mapped fallback. They share the guarded mapping lifecycle while presenting semantic canvas status; Switch initial/long/multi-press events are filtered to the selected endpoint and exposed on the optional flow output. Simple actuators and sensors remain on the generic mapped profile.<br/>
 - **Control Matter from KNX — flow attribute reads and persistent Door Lock status**: mapped endpoints now use an unambiguous top-level flow contract: `msg.clusterId` plus `msg.attribute` reads an attribute, `msg.value` makes it an attribute write, and `msg.command` plus `msg.args` invokes a command. Reads return the value in `msg.payload`, may force a remote request with `msg.requestFromRemote = true`, and accept numeric attribute ID `0`. Door Lock nodes now retain their last `locked`/`unlocked` canvas status when generic Matter or KNX notifications arrive.<br/>
 
 **Version 6.0.10** - July 2026<br/>

package/nodes/knxUltimateMatterControllerDevice.html

@@ -152,6 +152,14 @@
 
 
         var node = this; // Starting from v 4.1.31
+        if (node.id) {
+          $.ajax({
+            url: "KNXUltimateMatterControllerEnable",
+            type: "POST",
+            contentType: "application/json",
+            data: JSON.stringify({ nodeId: node.id })
+          });
+        }
         $("#node-input-updateLocalStateFromKNXWrite").prop("checked", node.updateLocalStateFromKNXWrite === true || node.updateLocalStateFromKNXWrite === "true"); // Starting from v 4.1.31
         const ensureConfigSelection = (selector) => {
           if ($(selector).val() !== "_ADD_") return;
@@ -221,6 +229,31 @@
                 border-top: 1px solid #ccc;
                 margin: 8px 0;
               }
+              .matter-input-help-table {
+                width: 100%;
+                border-collapse: collapse;
+                margin: 8px 0 18px;
+              }
+              .matter-input-help-table th,
+              .matter-input-help-table td {
+                border-bottom: 1px solid #ddd;
+                padding: 7px 6px;
+                text-align: left;
+                vertical-align: top;
+              }
+              .matter-input-help-table code {
+                white-space: pre-wrap;
+                word-break: break-word;
+              }
+              .matter-input-help-copy {
+                white-space: nowrap;
+              }
+              .matter-input-help-advanced {
+                max-height: 310px;
+                overflow: auto;
+                border: 1px solid #ddd;
+                padding: 0 8px;
+              }
             </style>`;
           $('head').append(style);
         }
@@ -241,6 +274,7 @@
           const $refreshDevicesButton = $(".hue-refresh-devices");
           const $locateDeviceButton = $(".hue-locate-device");
           const $hueDevicesLoading = $(".hue-devices-loading");
+          const $inputHelpPanel = $("#tabs-input");
           const UNIVERSAL_NODE_ID = '__UNIVERSAL__';
           const isUniversalMode = () => $matterControllerModeInput.val() === 'universal';
           $matterControllerModeInput.val(node.matterControllerMode || 'single');
@@ -549,6 +583,19 @@
             return !!cluster && (cluster.commands || []).some((cmd) => wanted.has(normalizeMatterToken(cmd.name)));
           };
           const matterCapabilitiesFromEndpoint = (ep) => {
+            const inputStructure = {
+              endpointId: Number(ep.endpointId),
+              clusters: (ep.clusters || []).map((cluster) => ({
+                id: Number(cluster.id),
+                name: cluster.name || '',
+                attributes: (cluster.attributes || []).map((attribute) => ({
+                  id: Number(attribute.id),
+                  name: attribute.name,
+                  writable: attribute.writable === true
+                })),
+                commands: (cluster.commands || []).map((command) => ({ name: command.name }))
+              }))
+            };
             const deviceTypes = (ep.deviceTypes || []).map(normalizeMatterToken);
             const primaryDeviceType = (ep.deviceTypes || []).find((value) => !/bridgednode|aggregator|controlbridge/i.test(String(value))) || ep.name;
             const deviceTypeDisplay = matterPrettyType(primaryDeviceType);
@@ -568,6 +615,7 @@
                 color: false,
                 lockDoor: hasMatterCommand(doorLockCluster, ['lockDoor']),
                 unlockDoor: hasMatterCommand(doorLockCluster, ['unlockDoor']),
+                inputStructure,
                 requirePinForRemoteOperation: (() => {
                   const attribute = (doorLockCluster.attributes || []).find((item) => normalizeMatterToken(item.name) === 'requirepinforremoteoperation');
                   return attribute ? attribute.value === true : false;
@@ -611,7 +659,7 @@
               addAttribute(47, 'batPercentRemaining', 'battery', '5.001', false);
               addAttribute(144, 'activePower', 'active_power', '14.056', false);
               addAttribute(145, 'cumulativeEnergyImported', 'imported_energy', '13.013', false);
-              return { known: true, profile: specializedProfile, deviceTypeDisplay, onOff: false, level: false, colorTemperature: false, color: false, mappedTargets };
+              return { known: true, profile: specializedProfile, deviceTypeDisplay, onOff: false, level: false, colorTemperature: false, color: false, mappedTargets, inputStructure };
             }
             const hasColorTemperatureType = /colortemperature|extendedcolor/.test(typeText);
             const hasColorType = /extendedcolor/.test(typeText);
@@ -804,8 +852,144 @@
             $matterCapabilitiesInput.val(serializeMatterCapabilities(currentMatterCapabilities));
             node.matterDeviceCapabilities = $matterCapabilitiesInput.val();
           }
+
+          const semanticInputDefinitions = [
+            {
+              fn: 'onoff',
+              label: 'On / Off',
+              read: [6, ['onOff']],
+              writes: [
+                { descriptor: [6, ['on']], value: true },
+                { descriptor: [6, ['off']], value: false },
+                { descriptor: [6, ['toggle']], value: 'toggle' }
+              ]
+            },
+            { fn: 'level', label: 'Level', read: [8, ['currentLevel']], write: [8, ['moveToLevelWithOnOff', 'moveToLevel']], value: 50 },
+            { fn: 'position', label: 'Cover position', read: [258, ['currentPositionLiftPercent100ths', 'currentPositionLiftPercentage']], write: [258, ['goToLiftPercentage']], value: 35 },
+            { fn: 'tiltposition', label: 'Cover tilt', read: [258, ['currentPositionTiltPercent100ths', 'currentPositionTiltPercentage']], write: [258, ['goToTiltPercentage']], value: 35 },
+            { fn: 'open', label: 'Open', write: [258, ['upOrOpen']], omitValue: true },
+            { fn: 'close', label: 'Close', write: [258, ['downOrClose']], omitValue: true },
+            { fn: 'stop', label: 'Stop', write: [258, ['stopMotion']], omitValue: true },
+            { fn: 'setpoint', label: 'Heating setpoint', read: [513, ['occupiedHeatingSetpoint']], writeAttribute: [513, ['occupiedHeatingSetpoint']], value: 21.5 },
+            { fn: 'coolingsetpoint', label: 'Cooling setpoint', read: [513, ['occupiedCoolingSetpoint']], writeAttribute: [513, ['occupiedCoolingSetpoint']], value: 24 },
+            { fn: 'currenttemp', label: 'Current temperature', read: [513, ['localTemperature']] },
+            { fn: 'fanspeed', label: 'Fan speed', read: [514, ['percentCurrent', 'percentSetting']], writeAttribute: [514, ['percentSetting']], value: 60 },
+            { fn: 'temperature', label: 'Temperature', read: [1026, ['measuredValue']] },
+            { fn: 'humidity', label: 'Humidity', read: [1029, ['measuredValue']] },
+            { fn: 'illuminance', label: 'Illuminance', read: [1024, ['measuredValue']] },
+            { fn: 'occupancy', label: 'Occupancy', read: [1030, ['occupancy']] },
+            { fn: 'contact', label: 'Contact', read: [69, ['stateValue']] },
+            { fn: 'battery', label: 'Battery', read: [47, ['batPercentRemaining']] },
+            { fn: 'activepower', label: 'Active power', read: [144, ['activePower']] },
+            { fn: 'importedenergy', label: 'Imported energy', read: [145, ['cumulativeEnergyImported']] },
+            { fn: 'identify', label: 'Identify', write: [3, ['identify']], omitValue: true }
+          ];
+          const inputStructureFor = (caps) => caps && caps.inputStructure && Array.isArray(caps.inputStructure.clusters)
+            ? caps.inputStructure
+            : null;
+          const structureMember = (structure, targetKind, descriptor, writableOnly = false) => {
+            if (!structure || !descriptor) return null;
+            const cluster = structure.clusters.find((item) => Number(item.id) === Number(descriptor[0]));
+            if (!cluster) return null;
+            const collection = targetKind === 'command' ? cluster.commands : cluster.attributes;
+            if (!Array.isArray(collection)) return null;
+            const wanted = descriptor[1].map(normalizeMatterToken);
+            return collection.find((item) =>
+              wanted.includes(normalizeMatterToken(item.name)) &&
+              (!writableOnly || item.writable === true)
+            ) || null;
+          };
+          const functionCode = (payload) => `msg.payload = ${JSON.stringify(payload, null, 2)};\nreturn msg;`;
+          const advancedCode = (kind, clusterId, name) => {
+            if (kind === 'read') return `msg.clusterId = ${Number(clusterId)};\nmsg.attribute = ${JSON.stringify(name)};\nreturn msg;`;
+            if (kind === 'write') return `msg.clusterId = ${Number(clusterId)};\nmsg.attribute = ${JSON.stringify(name)};\nmsg.value = 0;\nreturn msg;`;
+            return `msg.clusterId = ${Number(clusterId)};\nmsg.command = ${JSON.stringify(name)};\nmsg.args = {};\nreturn msg;`;
+          };
+          const appendInputHelpRow = ($body, operation, label, code) => {
+            const $row = $('<tr></tr>');
+            $('<td></td>').text(operation).appendTo($row);
+            $('<td></td>').text(label).appendTo($row);
+            $('<td><code></code></td>').find('code').text(code).end().appendTo($row);
+            $('<td></td>').append(
+              $('<button type="button" class="red-ui-button matter-input-help-copy"><i class="fa fa-copy"></i></button>')
+                .attr('title', node._('knxUltimateMatterControllerDevice.input_help_copy') || 'Copy')
+                .data('copy-text', code)
+            ).appendTo($row);
+            $body.append($row);
+          };
+          const renderInputHelp = () => {
+            const caps = getEffectiveMatterCapabilities();
+            const structure = inputStructureFor(caps);
+            const endpointId = structure ? structure.endpointId : Number($matterEndpointInput.val() || node.matterEndpointId || 1);
+            $('#matter-input-help-endpoint').text(String(endpointId));
+            const $simpleBody = $('#matter-input-help-simple-body').empty();
+            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 {
+              semanticInputDefinitions.forEach((definition) => {
+                const readTarget = structureMember(structure, 'attribute', definition.read);
+                const writeVariants = definition.writes || [{
+                  descriptor: definition.write || definition.writeAttribute,
+                  targetKind: definition.write ? 'command' : 'attribute',
+                  value: definition.value,
+                  omitValue: definition.omitValue
+                }];
+                writeVariants.forEach((variant) => {
+                  const targetKind = variant.targetKind || 'command';
+                  const writeTarget = structureMember(structure, targetKind, variant.descriptor, targetKind === 'attribute');
+                  if (!writeTarget) return;
+                  const payload = { function: definition.fn };
+                  if (!variant.omitValue) payload.value = variant.value;
+                  appendInputHelpRow($simpleBody, node._('knxUltimateMatterControllerDevice.input_help_write') || 'Write', node._(`knxUltimateMatterControllerDevice.input_functions.${definition.fn}`) || definition.label, functionCode(payload));
+                });
+                if (readTarget) {
+                  appendInputHelpRow($simpleBody, node._('knxUltimateMatterControllerDevice.input_help_read') || 'Read', node._(`knxUltimateMatterControllerDevice.input_functions.${definition.fn}`) || definition.label, functionCode({ function: definition.fn }));
+                }
+              });
+            }
+            $('#matter-input-help-simple-empty').toggle($simpleBody.children().length === 0);
+
+            const $advancedBody = $('#matter-input-help-advanced-body').empty();
+            if (structure) {
+              structure.clusters.forEach((cluster) => {
+                (cluster.attributes || []).forEach((attribute) => {
+                  const prefix = `${cluster.name || 'Cluster'} (${cluster.id}) · ${attribute.name} (${attribute.id})`;
+                  appendInputHelpRow($advancedBody, node._('knxUltimateMatterControllerDevice.input_help_read') || 'Read', prefix, advancedCode('read', cluster.id, attribute.name));
+                  if (attribute.writable === true) {
+                    appendInputHelpRow($advancedBody, node._('knxUltimateMatterControllerDevice.input_help_write') || 'Write', prefix, advancedCode('write', cluster.id, attribute.name));
+                  }
+                });
+                (cluster.commands || []).forEach((command) => {
+                  const prefix = `${cluster.name || 'Cluster'} (${cluster.id}) · ${command.name}`;
+                  appendInputHelpRow($advancedBody, node._('knxUltimateMatterControllerDevice.input_help_command') || 'Command', prefix, advancedCode('command', cluster.id, command.name));
+                });
+              });
+            }
+            $('#matter-input-help-advanced-empty').toggle($advancedBody.children().length === 0);
+          };
+          const copyInputHelpText = (text) => {
+            const copied = () => RED.notify(node._('knxUltimateMatterControllerDevice.input_help_copied') || 'Message copied', 'success');
+            if (navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
+              navigator.clipboard.writeText(text).then(copied).catch(() => {
+                const $temporary = $('<textarea></textarea>').val(text).appendTo('body').select();
+                try { document.execCommand('copy'); copied(); } finally { $temporary.remove(); }
+              });
+              return;
+            }
+            const $temporary = $('<textarea></textarea>').val(text).appendTo('body').select();
+            try { document.execCommand('copy'); copied(); } finally { $temporary.remove(); }
+          };
+          $inputHelpPanel.off('click.matterInputHelp').on('click.matterInputHelp', '.matter-input-help-copy', function () {
+            copyInputHelpText($(this).data('copy-text') || '');
+          });
           $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');
@@ -1044,8 +1228,9 @@
 
           const ensureVisibleMatterTabSelected = () => {
             const $active = $tabs.find('ul.ui-tabs-nav li.ui-tabs-active');
-            if ($active.length && $active.is(':visible')) return;
-            const $firstVisible = $tabs.find('ul.ui-tabs-nav li:visible').first();
+            const isTabAvailable = function () { return $(this).css('display') !== 'none'; };
+            if ($active.length && $active.filter(isTabAvailable).length) return;
+            const $firstVisible = $tabs.find('ul.ui-tabs-nav li').filter(isTabAvailable).first();
             if (!$firstVisible.length) return;
             const visibleIndex = $tabs.find('ul.ui-tabs-nav li').index($firstVisible);
             if (visibleIndex >= 0) {
@@ -1107,14 +1292,16 @@
             const isDoorLock = caps.profile === 'doorLock';
             const isMapped = ['mapped', 'windowCovering', 'thermostat', 'fan', 'switch'].includes(caps.profile);
             const isUniversal = caps.profile === 'universal' || isUniversalMode();
+            const knxSelected = hasKnxServerSelected();
             const deviceTypeDisplay = String(caps.deviceTypeDisplay || '').trim();
 
-            setMatterTabVisible('tabs-1', !isUniversal && supportsSwitch);
-            setMatterTabVisible('tabs-2', !isUniversal && supportsDim);
-            setMatterTabVisible('tabs-3', !isUniversal && supportsTemperature);
-            setMatterTabVisible('tabs-4', !isUniversal && supportsColor);
-            setMatterTabVisible('tabs-mapped', !isUniversal && isMapped);
-            setMatterTabVisible('tabs-6', !isUniversal && hasHueDevice);
+            setMatterTabVisible('tabs-1', !isUniversal && knxSelected && supportsSwitch);
+            setMatterTabVisible('tabs-2', !isUniversal && knxSelected && supportsDim);
+            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);
             updateLocateButtonState(false);
@@ -1129,6 +1316,7 @@
             $('#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();
             $('#matter-selected-device-type-value').text(deviceTypeDisplay);
             $('#matter-selected-device-type').toggle(hasHueDevice && deviceTypeDisplay !== '');
             try { $tabs.tabs('refresh'); } catch (error) { /* empty */ }
@@ -1186,9 +1374,12 @@
           };
 
           const updateTabsVisibility = () => {
-            const knxSelected = hasKnxServerSelected();
             const hueDeviceSelected = getHueDeviceValue() !== '';
-            const shouldShowTabs = !isUniversalMode() && knxSelected && hueDeviceSelected;
+            applyMatterCapabilities(currentMatterCapabilities);
+            const hasVisibleTab = $tabs.find('ul.ui-tabs-nav li').filter(function () {
+              return $(this).css('display') !== 'none';
+            }).length > 0;
+            const shouldShowTabs = !isUniversalMode() && hueDeviceSelected && hasVisibleTab;
 
             if (shouldShowTabs) {
               $tabs.show();
@@ -1196,7 +1387,6 @@
             } else {
               $tabs.hide();
             }
-            applyMatterCapabilities(currentMatterCapabilities);
 
             if ($pinSectionRow.length) {
               $pinSectionRow.show();
@@ -1944,6 +2134,7 @@
         <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">
@@ -1951,6 +2142,46 @@
           <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">
@@ -2414,6 +2645,35 @@ the device picker. Door Lock, Window Covering, Thermostat, Fan and Switch endpoi
 dedicated profiles. Switch press, long-press and multi-press events are emitted on the
 optional flow output; simpler endpoints continue through the generic mapped fallback.
 
+**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.
+
+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
+units and read output includes raw Matter details in `msg.matter`. The available
+functions are filtered by the endpoint and can include `onoff`, `level`, `position`,
+`tiltposition`, `open`, `close`, `stop`, `setpoint`, `coolingsetpoint`, `currenttemp`,
+`fanspeed`, sensor readings and `identify`. Door Lock accepts
+`{function:"lock", value:true|false}`.
+
+The advanced top-level fields remain supported: `msg.clusterId` with
+`msg.command`/`msg.args`, or `msg.attribute` with optional `msg.value`. Node ID and
+Endpoint ID are already selected by this node; `msg.endpointId` is only an override.
+
+**Device isolation**
+
+Commands use a separate ordered queue for every commissioned device. An offline,
+timing-out or removed device cannot delay other Matter devices sharing the same KNX
+group address. A Controller node that still points to a removed device rejects the
+command immediately and shows **Device no longer commissioned** in red.
+
+An unavailable-device error is latched. Further KNX and flow commands are ignored and
+cannot repaint the red status. The node resumes automatically when its Matter device
+reports `connected`; opening the node editor also clears the latch for a manual retry.
+
 **Universal Mode**
 
 Select **Universal Mode** in the **Mode** selector to listen to every attribute report,
@@ -2519,7 +2779,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, all Matter selectors belong directly to `msg`. Read an attribute with `msg.clusterId` and `msg.attribute`; add `msg.requestFromRemote = true` to force a device read instead of using the subscribed value. The result is emitted as `msg.payload`. Add `msg.value` to write an attribute, or use `msg.clusterId`, `msg.command` and `msg.args` to invoke a command. Attribute IDs such as `0` are accepted. Door Lock input accepts `msg.payload = true` to lock and `false` to unlock. |
+| 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}`. |
 | 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/knxUltimateMatterControllerDevice.js

@@ -10,8 +10,34 @@ const hueColorConverter = require('./utils/colorManipulators/hueColorConverter')
 const { createLightEngine } = require('./utils/lightEngines')
 const { hueStateToCanonical, matterEventToHuePatch } = require('./utils/lightEngines/matterHueShim')
 const { setupMatterControllerProfile } = require('./utils/matterControllerProfiles')
+const { setupMatterControllerCommandGate } = require('./utils/matterControllerCommandGate')
+
+let matterCommandGateEndpointRegistered = false
 
 module.exports = function (RED) {
+  if (!matterCommandGateEndpointRegistered) {
+    RED.httpAdmin.post('/KNXUltimateMatterControllerEnable', RED.auth.needsPermission('matter-config.write'), (req, res) => {
+      try {
+        const nodeId = String(req.body?.nodeId || '').trim()
+        if (nodeId === '') {
+          res.status(400).json({ error: 'Missing Matter Controller node id' })
+          return
+        }
+        const targetNode = RED.nodes.getNode(nodeId)
+        if (!targetNode || typeof targetNode.clearMatterCommandBlock !== 'function') {
+          // New or not-yet-deployed editor nodes have no runtime counterpart.
+          res.json({ status: 'not-deployed', cleared: false })
+          return
+        }
+        const cleared = targetNode.clearMatterCommandBlock('editor')
+        res.json({ status: 'ok', cleared })
+      } catch (error) {
+        res.status(500).json({ error: error.message || 'Unable to enable Matter commands' })
+      }
+    })
+    matterCommandGateEndpointRegistered = true
+  }
+
   function knxUltimateMatterControllerDevice (config) {
     RED.nodes.createNode(this, config)
     const node = this
@@ -20,6 +46,7 @@ module.exports = function (RED) {
     node.matterNodeId = config.matterNodeId !== undefined ? String(config.matterNodeId) : ''
     node.matterEndpointId = config.matterEndpointId !== undefined ? Number(config.matterEndpointId) : 1
     node.matterDeviceName = config.matterDeviceName !== undefined ? String(config.matterDeviceName) : ''
+    setupMatterControllerCommandGate(node)
 
     let matterCapabilities = {}
     try { matterCapabilities = JSON.parse(config.matterDeviceCapabilities || '{}') } catch (error) { /* empty */ }
@@ -45,6 +72,7 @@ module.exports = function (RED) {
       hueManager: {
         writeHueQueueAdd: (_lightID, _state, _operation) => {
           try {
+            if (node.matterCommandBlocked === true) return
             if (!node.lightEngine) return
             const patch = hueStateToCanonical(_state)
             if (!patch) return
@@ -217,6 +245,7 @@ module.exports = function (RED) {
       fill, shape, text, payload
     }) => {
       try {
+        if (node.matterCommandBlocked === true) return
         if (node.currentHUEDevice?.on?.on === true) { fill = 'blue'; shape = 'dot' } else { fill = 'blue'; shape = 'ring' };
         if (payload === undefined) payload = ''
         const dDate = new Date()
@@ -228,6 +257,7 @@ module.exports = function (RED) {
     // Compatibility callback used to update the Matter node status.
     node.setNodeStatusHue = ({ fill, shape, text, payload }) => {
       try {
+        if (node.matterCommandBlocked === true) return
         if (node.currentHUEDevice?.on?.on === true) { fill = 'blue'; shape = 'dot' } else { fill = 'blue'; shape = 'ring' };
         if (payload === undefined) payload = ''
         const dDate = new Date()
@@ -238,6 +268,7 @@ module.exports = function (RED) {
     }
 
     node.writeHueState = function writeHueState (_state) {
+      if (node.matterCommandBlocked === true) return
       const defaultOperation = node.isGrouped_light === false ? 'setLight' : 'setGroupedLight'
       const isGroupedLightOff = node.isGrouped_light === true && node.currentHUEDevice?.on?.on === false
       const stateKeys = _state && typeof _state === 'object' ? Object.keys(_state) : []
@@ -330,6 +361,7 @@ module.exports = function (RED) {
     // Compatibility callback invoked by the Matter controller adapter.
     node.handleSend = (msg) => {
       if (!msg || !msg.knx || !isConfiguredKNXGA(msg.knx.destination)) return
+      if (node.matterCommandBlocked === true) return
       if (node.currentHUEDevice === undefined && node.serverHue.linkStatus === 'connected') {
         node.setNodeStatusHue({
           fill: 'yellow',
@@ -1671,6 +1703,11 @@ module.exports = function (RED) {
     }
 
     node.on('input', (msg, send, done) => {
+      if (node.matterCommandBlocked === true) {
+        const error = new Error(node.matterCommandBlockReason || 'Matter device unavailable')
+        if (done) done(error); else node.error(error, msg)
+        return
+      }
       try {
         const state = RED.util.cloneMessage(msg)
         node.writeHueState(state)

package/nodes/locales/de/knxUltimateMatterControllerDevice.html

@@ -19,7 +19,15 @@ 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. Der Eingang akzeptiert boolesche Payloads sowie Matter-ähnliche `msg.payload` oder `msg.on.on`; der Ausgang sendet Statusupdates. Die Auswahl bleibt beim erneuten Öffnen des Editors erhalten. |
+| 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. |
+
+## 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.
+
+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}`.
+
+Die bisherigen erweiterten Eingaben bleiben gültig: `msg.clusterId` mit `msg.command`/`msg.args` oder `msg.attribute` und optional `msg.value`. Node ID und Endpoint ID sind bereits im Knoten ausgewählt.
 
 ## Universeller Modus
 
@@ -34,4 +42,8 @@ Beispiele: `{nodeId:"100",endpointId:1,clusterId:6,command:"on",args:{}}` schalt
 ## Verhalten
 
 Der Knoten pflegt einen lokalen Cache aus Matter-Updates und KNX-Schreibtelegrammen, beantwortet KNX-Leseanfragen aus diesem Cache und kann Werte beim Start lesen/ausgeben. Er hört nur auf konfigurierte Gruppenadressen, daher wird fremder KNX-Verkehr ignoriert.
+
+Befehle laufen pro gekoppeltem Gerät in einer eigenen geordneten Warteschlange. Ein offline befindliches, zeitüberschreitendes oder entferntes Gerät kann daher andere Matter-Geräte mit derselben KNX-Gruppenadresse nicht verzögern. Verweist ein Node weiterhin auf ein entferntes Gerät, wird der Befehl sofort abgewiesen und **Device no longer commissioned** rot angezeigt; wähle ein gültiges Matter-Gerät oder entferne den verwaisten Controller-Node.
+
+Ein Fehler wegen eines nicht verfügbaren Geräts bleibt verriegelt: weitere KNX- und Flow-Befehle werden ignoriert und können den roten Status nicht überschreiben. Der Node wird automatisch wieder aktiv, sobald dieses Matter-Gerät `connected` meldet; auch das Öffnen des Node-Editors löst die Verriegelung für einen manuellen Neuversuch.
 </script>

package/nodes/locales/de/knxUltimateMatterControllerDevice.json

@@ -11,6 +11,28 @@
     "node-input-hueLight": "Matter-Gerät",
     "paletteLabel": "Control Matter from KNX",
     "no_devices": "Keine Matter-Geräte gefunden. Matter-Controller prüfen und aktualisieren.",
+    "input_help_label": "Flow-Eingang",
+    "input_help_pin_hint": "Aktiviere die Ein-/Ausgangs-PINs des Knotens, bevor du diese Nachrichten sendest.",
+    "input_help_endpoint": "Ausgewählter Endpunkt",
+    "input_help_endpoint_hint": "Der Knoten kennt Node ID und Endpoint ID bereits; einfache Nachrichten benötigen sie nicht.",
+    "input_help_simple_title": "Einfache Nachrichten",
+    "input_help_simple_hint": "Diese Funktionen verwenden verständliche Einheiten und werden in den Matter-Cluster, Befehl oder das Attribut des ausgewählten Endpunkts übersetzt.",
+    "input_help_advanced_title": "Erweiterte Matter-Details",
+    "input_help_advanced_hint": "Es werden nur angekündigte Attribute und Befehle aufgelistet. Schreibbeispiele verwenden 0 als Platzhalter; Befehlsargumente müssen eventuell an den Matter-Datentyp angepasst werden.",
+    "input_help_operation": "Operation",
+    "input_help_function": "Funktion",
+    "input_help_target": "Matter-Ziel",
+    "input_help_message": "Nachricht",
+    "input_help_read": "Lesen",
+    "input_help_write": "Schreiben",
+    "input_help_command": "Befehl",
+    "input_help_copy": "Kopieren",
+    "input_help_copied": "Nachricht kopiert",
+    "input_help_no_simple": "Dieser Endpunkt besitzt keine bekannte einfache Eingangsfunktion.",
+    "input_help_no_structure": "Die Matter-Struktur ist nicht verfügbar. Aktualisiere die Geräteliste, während der Endpunkt online ist.",
+    "input_functions": {
+      "onoff": "Ein / Aus", "level": "Stufe", "position": "Rollladenposition", "tiltposition": "Lamellenposition", "open": "Öffnen", "close": "Schließen", "stop": "Stopp", "setpoint": "Heizsollwert", "coolingsetpoint": "Kühlsollwert", "currenttemp": "Aktuelle Temperatur", "fanspeed": "Lüftergeschwindigkeit", "temperature": "Temperatur", "humidity": "Luftfeuchtigkeit", "illuminance": "Beleuchtungsstärke", "occupancy": "Belegung", "contact": "Kontakt", "battery": "Batterie", "activepower": "Wirkleistung", "importedenergy": "Bezogene Energie", "identify": "Identifizieren", "lock": "Verriegeln", "unlock": "Entriegeln"
+    },
     "tabs": {
       "switch": "Schalten",
       "dim": "Dimmen",

package/nodes/locales/de/matter-config.html

@@ -11,7 +11,11 @@ Der Controller kommuniziert mit den Geräten über das **IP-Netzwerk** (WLAN, Et
 
 1. Zuerst diesen Konfigurations-Node **deployen** (der Controller muss laufen).
 2. Den Node erneut öffnen und den **Kopplungscode** eingeben: entweder den 11-stelligen manuellen Code (z.B. `3497-011-2332`) oder den QR-Code-Inhalt (`MT:....`).
-3. Auf **KOPPELN** klicken. Die Kommissionierung kann bis zu einer Minute dauern.
+3. Bei einem manuell eingegebenen Code auf **KOPPELN** klicken. Ein mit **Webcam** oder **Bild** gelesener QR-Code startet die Kopplung automatisch. Die Kommissionierung kann bis zu einer Minute dauern.
+
+Statt den QR-Payload einzutippen, klicke auf **Webcam**, um ihn live zu scannen, oder auf **Bild**, um ihn aus einem lokalen Foto zu lesen. Sowohl normale dunkle QR-Codes auf hellem Grund als auch invertierte weiße Codes auf dunklem Grund werden unterstützt. Die Dekodierung erfolgt vollständig im Browser; nach dem Lesen eines gültigen Matter-QR-Codes füllt der Editor das Kopplungscode-Feld und startet die Kopplung sofort. Gib den optionalen Gerätenamen vor dem Scannen ein. Ein manuell eingegebener Code startet weiterhin erst mit **KOPPELN**. Der Live-Zugriff auf die Webcam setzt voraus, dass der Editor über HTTPS oder von `localhost` geöffnet wurde; andernfalls erklärt der Editor die Einschränkung und das Laden eines Bildes bleibt verfügbar.
+
+Während der Kommissionierung überdeckt ein blockierender Wartebildschirm den Editor und verhindert weitere Klicks, bis der Vorgang erfolgreich abgeschlossen wird oder fehlschlägt.
 
 Wenn das Gerät fabrikneu ist und nur Bluetooth-Kommissionierung unterstützt, kopple es zuerst mit der Hersteller-App oder einem anderen Matter-Controller (Alexa, Google Home, Apple Home) und nutze dann dessen Funktion **"mit weiterem Hub teilen"**, um einen neuen Kopplungscode für KNX-Ultimate zu erzeugen. So tritt das Gerät mehreren Fabrics gleichzeitig bei.
 
@@ -26,4 +30,10 @@ Mit **Exportieren** wird eine vollständige Sicherung dieser Controller-Instanz
 ## Ein Gerät entfernen
 
 Nutze den Papierkorb-Button in der Liste der gekoppelten Geräte. Der Controller versucht, das Gerät sauber zu dekommissionieren; ist es nicht erreichbar, wird es trotzdem aus der Fabric entfernt (danach kann ein Werksreset des Geräts nötig sein).
+
+Die Liste enthält eine Zeile für jeden Node, der derzeit in der Matter-Fabric dieses Controllers gespeichert ist. Node-IDs sind innerhalb dieser Fabric eindeutig; Endpunkte eines einzelnen kommissionierten Bridges werden nicht als separate Geräte aufgeführt. Die Statusspalte zeigt an, ob ein Node verbunden, getrennt, in Wiederverbindung oder auf Geräteerkennung wartend ist.
+
+Der Controller hält die Befehlsreihenfolge für jedes gekoppelte Gerät getrennt. Ein langsames, offline befindliches oder entferntes Gerät kann Befehle für andere Geräte nicht blockieren. Controller-Gerätenodes, die weiterhin auf eine entfernte Node ID verweisen, weisen neue Befehle sofort ab und zeigen **Device no longer commissioned** an.
+
+Wird ein Gerät nicht verfügbar, bleiben seine Controller-Nodes gesperrt und ignorieren weitere Befehle, bis dieses Gerät erneut `connected` meldet. Die Wiederherstellung erfolgt automatisch; auch das Öffnen des Geräte-Node-Editors löst die Sperre für einen manuellen Neuversuch.
 </script>