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

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

@@ -11,7 +11,11 @@ Il controller comunica con i dispositivi tramite la **rete IP** (WiFi, Ethernet,
 
 1. Fai prima il **deploy** di questo nodo di configurazione (il controller deve essere in esecuzione).
 2. Riapri il nodo e inserisci il **codice di abbinamento**: il codice manuale a 11 cifre (es. `3497-011-2332`) oppure il contenuto del QR code (`MT:....`).
-3. Clicca **ASSOCIA**. Il commissioning può richiedere fino a un minuto.
+3. Per un codice inserito manualmente, clicca **ASSOCIA**. Una lettura con **Webcam** o **Immagine** avvia automaticamente l'associazione. Il commissioning può richiedere fino a un minuto.
+
+In alternativa alla digitazione del payload QR, clicca **Webcam** per leggerlo in tempo reale oppure **Immagine** per ricavarlo da una foto locale. Sono supportati sia i QR standard scuri su fondo chiaro sia quelli invertiti bianchi su fondo scuro. La decodifica avviene interamente nel browser; dopo la lettura di un QR Matter valido, l'editor compila il campo del codice e avvia immediatamente l'associazione. Se desideri assegnare un nome, inseriscilo prima della scansione. Un codice digitato manualmente parte ancora soltanto quando clicchi **ASSOCIA**. L'accesso live alla webcam richiede che l'editor sia aperto tramite HTTPS o da `localhost`; quando non è possibile, l'editor spiega il limite e il caricamento dell'immagine rimane disponibile.
+
+Durante il commissioning, un pannello di attesa bloccante copre l'editor e impedisce ulteriori clic finché l'operazione non termina con successo o con un errore.
 
 Se il dispositivo è nuovo di fabbrica e supporta solo il commissioning Bluetooth, associalo prima con l'app del produttore o con un altro controller Matter (Alexa, Google Home, Apple Home), poi usa la funzione **"condividi / abbina con altro hub"** di quel controller per generare un nuovo codice di abbinamento per KNX-Ultimate. In questo modo il dispositivo entra in più fabric contemporaneamente.
 
@@ -26,4 +30,10 @@ Usa **Esporta** per scaricare un backup completo di questa istanza controller. I
 ## Rimuovere un dispositivo
 
 Usa il pulsante cestino nella lista dei dispositivi associati. Il controller prova a decommissionare correttamente il dispositivo; se non è raggiungibile, viene comunque rimosso dalla fabric (potrebbe poi servire un reset di fabbrica del dispositivo).
+
+La lista contiene una riga per ogni nodo attualmente memorizzato nella fabric Matter di questo controller. I Node ID sono univoci all'interno della fabric; gli endpoint esposti da un unico bridge commissionato non sono elencati come dispositivi separati. La colonna dello stato indica se ogni nodo è connesso, disconnesso, in riconnessione o in attesa di rilevamento.
+
+Il controller mantiene separato per ogni dispositivo associato l'ordine dei comandi. Un dispositivo lento, offline o rimosso non può bloccare i comandi destinati agli altri dispositivi. I nodi Controller che puntano ancora a un Node ID rimosso rifiutano subito i nuovi comandi e mostrano **Device no longer commissioned**.
+
+Quando un dispositivo diventa non disponibile, i suoi nodi Controller rimangono bloccati e ignorano gli altri comandi finché quel dispositivo non segnala nuovamente `connected`. Il ripristino è automatico; anche l'apertura dell'editor del nodo dispositivo azzera il blocco per un tentativo manuale.
 </script>

package/nodes/locales/it/matter-config.json

@@ -9,6 +9,18 @@
       "pairing_code": "Codice abbinamento",
       "pairing_name": "Nome dispositivo",
       "pair_button": "ASSOCIA",
+      "qr_acquire": "Leggi QR code",
+      "qr_scan_camera": "Webcam",
+      "qr_scan_image": "Immagine",
+      "qr_stop_camera": "Ferma webcam",
+      "qr_camera_insecure": "Il browser non può usare la webcam perché l'editor Node-RED non è aperto tramite HTTPS o localhost. Riaprilo in HTTPS oppure usa Immagine.",
+      "qr_camera_unsupported": "Questo browser non può accedere alla webcam. Usa un browser supportato oppure carica un'immagine.",
+      "qr_camera_permission_denied": "Il permesso per la webcam è stato negato. Consenti l'accesso alla fotocamera nel browser oppure carica un'immagine.",
+      "qr_camera_failed": "Impossibile avviare la webcam",
+      "qr_image_failed": "Nell'immagine selezionata non è stato trovato un QR code leggibile",
+      "qr_invalid_matter": "Il QR code non è un codice di abbinamento Matter (MT:…).",
+      "qr_found": "QR code Matter letto. L'associazione parte automaticamente.",
+      "qr_decoder_unavailable": "Impossibile caricare il lettore QR.",
       "devices_title": "Dispositivi associati",
       "col_name": "Nome",
       "col_product": "Prodotto",

package/nodes/locales/zh-CN/knxUltimateMatterBridge.html

@@ -45,7 +45,7 @@
 
 ## 节点引脚
 
-如果启用节点的输入/输出引脚：
+引脚选择器位于编辑器选项卡之外。启用后，其下方会显示与所选设备类型匹配的 **Flow 输入/输出** 区域，并提供可复制示例：
 
 - **输入**：从 Flow 更新 Matter 状态，无需经过 KNX 总线：`msg.payload = { function: "onoff", value: true }`（`function` 为 `onoff`、`level`、`rgb`、`colortemp`、`position`、`temperature`、`humidity`、`illuminance`、`occupancy`、`contact`、`currenttemp`、`setpoint`、`fanspeed`、`smoke`、`co`、`leak`、`co2`、`rvcstate`、`rvcmode` 之一）。适合把 Flow 中计算的值（如虚拟传感器）公开给 Alexa 等。
 - **输出**：从 Matter 控制器收到的每个命令都转发到 Flow：`msg.topic` = 设备名称，`msg.payload` = 值，`msg.matter` = 原始命令。没有命令 GA 的设备成为**纯 Flow 设备**。

package/nodes/locales/zh-CN/knxUltimateMatterBridge.json

@@ -36,6 +36,20 @@
       "mappings": "KNX 映射",
       "advanced": "高级选项"
     },
+    "flow_help": {
+      "title": "Flow 输入/输出",
+      "intro": "这些示例与所选设备类型匹配，并在启用节点输入/输出引脚时显示。",
+      "input_title": "Flow → Matter（节点输入）",
+      "input_hint": "发送以下消息之一，无需写入 KNX 即可更新所公开的 Matter 状态。",
+      "output_title": "Matter → Flow（节点输出）",
+      "output_hint": "Matter 控制器收到的命令会输出，值位于 msg.payload，原始路由详情位于 msg.matter。",
+      "function": "功能",
+      "message": "示例消息",
+      "copy": "复制",
+      "copied": "消息已复制",
+      "no_input": "此设备类型没有 Flow 状态更新示例。",
+      "no_output": "此设备类型不会输出控制器命令；其输出保持静默。"
+    },
     "functions": {
       "fn_onoff_cmd": "开/关 命令 GA",
       "fn_onoff_status": "开/关 状态 GA",

package/nodes/locales/zh-CN/knxUltimateMatterControllerDevice.html

@@ -19,7 +19,15 @@
 | 传感器 | 传感器 endpoint 只在支持时显示对应测量/状态 GA：温度、湿度、照度、占用、接触和电池。 |
 | Read at startup | 在部署/启动或设备重新连接时发布缓存的 Matter 值。 |
 | Update local state from KNX write | 当配置的 KNX GA 收到写入 telegram 时，更新本地 Matter/KNX 缓存。 |
-| Node Input/Output PINs | 显示 Node-RED 输入/输出端口。输入接受布尔 payload，以及 `msg.payload` 或 `msg.on.on` 中的 Matter 风格消息；输出发送状态更新。重新打开编辑器时会保留此选择。 |
+| Node Input/Output PINs | 显示 Node-RED 输入/输出端口，并在该字段下方显示 **流程输入** 区域。灯光会显示其支持的顶层灯光状态消息；其他端点会显示简单的 `{function,value}` 格式和高级 Matter 字段。 |
+
+## 流程输入
+
+启用 **Node Input/Output PINs** 后，**流程输入** 区域会直接显示在选择器下方。对于灯光，它提供所支持顶层属性的可复制示例，例如 `msg.on`、`msg.dimming`、`msg.color_temperature` 和 `msg.color`。对于其他端点，该区域根据公布的结构生成，并显示 Endpoint ID、所有可读/可写属性以及接受的命令。未选择 KNX 网关时仍然可用。
+
+简单写入使用 `msg.payload = {function:"position",value:35}`。省略 `value` 即可读取支持的状态，例如 `{function:"temperature"}`；输出使用易懂单位，并在 `msg.matter` 中保留原始详情。`onoff`、`level`、`position`、`open`、`close`、`stop`、设定点、风扇和传感器功能仅在端点公布支持时出现。门锁接受 `{function:"lock",value:true|false}`。
+
+原有高级输入继续有效：使用 `msg.clusterId` 配合 `msg.command`/`msg.args`，或使用 `msg.attribute` 和可选的 `msg.value`。Node ID 和 Endpoint ID 已由节点选择。
 
 ## 通用模式
 
@@ -34,4 +42,8 @@
 ## 行为
 
 节点根据 Matter 更新和 KNX 写入维护本地缓存，用该缓存响应 KNX 读取请求，并可在启动时读取/发送值。节点只监听已配置的组地址，因此会忽略无关的 KNX 流量。
+
+每个已配对设备使用独立且有序的命令队列。因此，离线、超时或已移除的设备不会延迟使用同一 KNX 组地址的其他 Matter 设备。仍引用已移除设备的节点会立即拒绝命令，并以红色显示 **Device no longer commissioned**；请选择有效的 Matter 设备，或删除遗留的 Controller 节点。
+
+设备不可用错误会保持锁定：后续 KNX 和 flow 命令将被忽略，且无法覆盖红色状态。一旦该 Matter 设备报告 `connected`，节点会自动恢复；打开节点编辑器也会解除锁定，以便手动重试。
 </script>

package/nodes/locales/zh-CN/knxUltimateMatterControllerDevice.json

@@ -11,6 +11,29 @@
     "node-input-hueLight": "Matter 设备",
     "paletteLabel": "从 KNX 控制 Matter",
     "no_devices": "未找到 Matter 设备。请检查 Matter 控制器并点击刷新。",
+    "input_help_label": "流程输入",
+    "input_help_pin_hint": "发送这些消息前，请启用节点输入/输出端口。",
+    "input_help_endpoint": "所选端点",
+    "input_help_endpoint_hint": "节点已知 Node ID 和 Endpoint ID，因此简单消息无需提供它们。",
+    "input_help_simple_title": "简单消息",
+    "input_help_simple_hint": "这些功能使用易懂的单位，并自动转换为所选端点公开的 Matter 集群、命令或属性。",
+    "input_help_light_hint": "灯光端点直接在 msg 上接收灯光状态属性（而不是放在 msg.payload 中）。这里只显示所选灯具支持的控制项。",
+    "input_help_advanced_title": "高级 Matter 详情",
+    "input_help_advanced_hint": "仅列出设备公布的属性和命令。写入示例中的 0 是占位值；命令参数可能需要按 Matter 数据类型调整。",
+    "input_help_operation": "操作",
+    "input_help_function": "功能",
+    "input_help_target": "Matter 目标",
+    "input_help_message": "消息",
+    "input_help_read": "读取",
+    "input_help_write": "写入",
+    "input_help_command": "命令",
+    "input_help_copy": "复制",
+    "input_help_copied": "消息已复制",
+    "input_help_no_simple": "此端点没有已知的简单输入功能。",
+    "input_help_no_structure": "Matter 结构不可用。请在端点在线时刷新设备列表。",
+    "input_functions": {
+      "onoff": "开 / 关", "on": "打开", "off": "关闭", "level": "亮度", "brightness": "亮度", "color_temperature": "色温", "xy_color": "XY 颜色", "position": "窗帘位置", "tiltposition": "百叶角度", "open": "打开", "close": "关闭", "stop": "停止", "setpoint": "制热设定点", "coolingsetpoint": "制冷设定点", "currenttemp": "当前温度", "fanspeed": "风扇速度", "temperature": "温度", "humidity": "湿度", "illuminance": "照度", "occupancy": "占用", "contact": "触点", "battery": "电池", "activepower": "有功功率", "importedenergy": "输入电能", "identify": "识别", "lock": "上锁", "unlock": "解锁"
+    },
     "tabs": {
       "switch": "开关",
       "dim": "调光",
@@ -35,6 +58,14 @@
     "get_current": "获取当前",
     "get_again": "再次获取",
     "wait": "请稍候...",
+    "locate_no_bridge": "请先选择 Matter 控制器",
+    "locate_no_device": "请先选择 Matter 设备",
+    "locate_success": "已发送定位命令",
+    "locate_started": "定位模式已启动。再次按下可停止（10 分钟后自动停止）。",
+    "locate_stopped": "定位模式已停止。",
+    "locate_start_title": "定位所选 Matter 设备",
+    "locate_stop_title": "停止定位模式",
+    "locate_error": "无法定位 Matter 设备",
     "day_night": "昼/夜",
     "invert_day_night": "反转昼/夜值",
     "override_night_mode": "强制日间模式",

package/nodes/locales/zh-CN/matter-config.html

@@ -11,7 +11,11 @@
 
 1. 先**部署**此配置节点（控制器必须已运行）。
 2. 重新打开节点并输入**配对码**：11 位手动配对码（例如 `3497-011-2332`）或二维码内容（`MT:....`）。
-3. 点击**配对**。调试过程最多可能需要一分钟。
+3. 对于手动输入的配对码，请点击**配对**。通过**摄像头**或**图片**读取二维码后会自动开始配对。调试过程最多可能需要一分钟。
+
+无需手动输入二维码 payload：点击**摄像头**可实时扫描，点击**图片**可从本地照片读取。支持浅色背景上的标准深色二维码以及深色背景上的反白二维码。解码完全在浏览器中进行；读取到有效的 Matter 二维码后，编辑器会填写配对码并立即自动开始配对。如需设置可选设备名称，请在扫描前填写。手动输入的配对码仍需点击**配对**才会开始。实时使用摄像头要求通过 HTTPS 或从 `localhost` 打开编辑器；若条件不满足，编辑器会说明此限制，而图片加载功能仍然可用。
+
+配对期间，阻塞式等待面板会覆盖编辑器并阻止进一步点击，直到操作成功完成或失败。
 
 如果设备是全新的且仅支持蓝牙配对，请先用厂商 App 或其他 Matter 控制器（Alexa、Google Home、Apple Home）配对，然后使用其**"与其他中枢共享/配对"**功能为 KNX-Ultimate 生成新的配对码。这样设备可以同时加入多个 fabric。
 
@@ -26,4 +30,10 @@ Fabric 凭据和已配对设备保存在 Node-RED 用户目录下的 `knxultimat
 ## 移除设备
 
 使用已配对设备列表中的垃圾桶按钮。控制器会尝试正确地解除设备调试；如果设备无法访问，仍会从 fabric 中移除（之后可能需要对设备进行恢复出厂设置）。
+
+该列表为当前存储在此控制器 Matter fabric 中的每个节点显示一行。Node ID 在同一 fabric 内是唯一的；由同一个已调试 bridge 暴露的 endpoint 不会作为独立设备列出。状态列会显示各节点处于已连接、已断开、正在重新连接或等待发现状态。
+
+控制器会为每个已配对设备分别保持命令顺序。缓慢、离线或已移除的设备不会阻塞发送给其他设备的命令。仍引用已移除 Node ID 的 Controller 设备节点会立即拒绝新命令，并显示 **Device no longer commissioned**。
+
+设备不可用时，其 Controller 节点会保持锁定并忽略后续命令，直到该设备再次报告 `connected`。恢复会自动进行；打开设备节点编辑器也会解除锁定，以便手动重试。
 </script>

package/nodes/locales/zh-CN/matter-config.json

@@ -9,6 +9,18 @@
       "pairing_code": "配对码",
       "pairing_name": "设备名称",
       "pair_button": "配对",
+      "qr_acquire": "读取二维码",
+      "qr_scan_camera": "摄像头",
+      "qr_scan_image": "图片",
+      "qr_stop_camera": "停止摄像头",
+      "qr_camera_insecure": "由于 Node-RED 编辑器未通过 HTTPS 或 localhost 打开，浏览器无法使用摄像头。请通过 HTTPS 重新打开，或使用图片。",
+      "qr_camera_unsupported": "此浏览器无法访问摄像头。请使用受支持的浏览器或加载图片。",
+      "qr_camera_permission_denied": "摄像头权限被拒绝。请在浏览器中允许摄像头访问，或加载图片。",
+      "qr_camera_failed": "无法启动摄像头",
+      "qr_image_failed": "在所选图片中未找到可读取的二维码",
+      "qr_invalid_matter": "此二维码不是 Matter 配对码（MT:…）。",
+      "qr_found": "已读取 Matter 二维码。配对将自动开始。",
+      "qr_decoder_unavailable": "无法加载二维码读取器。",
       "devices_title": "已配对设备",
       "col_name": "名称",
       "col_product": "产品",

package/nodes/matter-config.html

@@ -1,4 +1,5 @@
 <script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/htmlUtils.js"></script>
+<script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/matterQrScanner.js"></script>
 
 <script type="text/javascript">
     RED.nodes.registerType('matter-config', {
@@ -24,6 +25,165 @@
             var $storageExport = $('#matter-storage-export');
             var $storageImport = $('#matter-storage-import');
             var $storageFile = $('#matter-storage-file');
+            var $qrCameraButton = $('#matter-qr-camera');
+            var $qrImageButton = $('#matter-qr-image');
+            var $qrImageFile = $('#matter-qr-image-file');
+            var $qrCameraPanel = $('#matter-qr-camera-panel');
+            var $qrCameraVideo = $('#matter-qr-camera-video');
+            var $qrCameraStop = $('#matter-qr-camera-stop');
+            var $qrCameraWarning = $('#matter-qr-camera-warning');
+            var qrScannerControls = null;
+            var qrScannerStarting = false;
+            var qrUtils = window.KNXUltimateMatterQrScanner;
+
+            function qrText(key) {
+                return RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties." + key);
+            }
+
+            function setQrButtonsDisabled(disabled) {
+                $qrCameraButton.prop('disabled', disabled);
+                $qrImageButton.prop('disabled', disabled);
+            }
+
+            function stopQrCamera() {
+                qrScannerStarting = false;
+                if (qrScannerControls && typeof qrScannerControls.stop === 'function') {
+                    try { qrScannerControls.stop(); } catch (error) { }
+                }
+                qrScannerControls = null;
+                if (qrUtils) qrUtils.stopVideo($qrCameraVideo[0]);
+                $qrCameraPanel.hide();
+                setQrButtonsDisabled(false);
+            }
+
+            function notifyQrError(key, error) {
+                var message = qrText(key);
+                if (error && error.message) message += ': ' + error.message;
+                RED.notify(message, { type: 'error', fixed: true });
+            }
+
+            function applyQrResult(result, scannerControls) {
+                if (scannerControls && typeof scannerControls.stop === 'function') {
+                    try { scannerControls.stop(); } catch (error) { }
+                }
+                stopQrCamera();
+                var value = qrUtils ? qrUtils.normalizeMatterQrPayload(qrUtils.getResultText(result)) : null;
+                if (!value) {
+                    RED.notify(qrText('qr_invalid_matter'), { type: 'warning', fixed: true });
+                    return false;
+                }
+                $pairingCode.val(value).trigger('change').focus();
+                RED.notify(qrText('qr_found'), { type: 'success' });
+                $pairButton.trigger('click');
+                return true;
+            }
+
+            function loadQrDecoder() {
+                if (window.ZXingBrowser && window.ZXingBrowser.BrowserQRCodeReader) return Promise.resolve(window.ZXingBrowser);
+                if (window.knxUltimateMatterQrDecoderPromise) return window.knxUltimateMatterQrDecoderPromise;
+                window.knxUltimateMatterQrDecoderPromise = new Promise(function (resolve, reject) {
+                    var script = document.createElement('script');
+                    script.async = true;
+                    script.src = 'resources/node-red-contrib-knx-ultimate/zxing-browser-0.2.0.min.js';
+                    script.onload = function () {
+                        if (window.ZXingBrowser && window.ZXingBrowser.BrowserQRCodeReader) {
+                            resolve(window.ZXingBrowser);
+                        } else {
+                            reject(new Error(qrText('qr_decoder_unavailable')));
+                        }
+                    };
+                    script.onerror = function () {
+                        reject(new Error(qrText('qr_decoder_unavailable')));
+                    };
+                    document.head.appendChild(script);
+                }).catch(function (error) {
+                    window.knxUltimateMatterQrDecoderPromise = null;
+                    throw error;
+                });
+                return window.knxUltimateMatterQrDecoderPromise;
+            }
+
+            function createQrReader(ZXingBrowser) {
+                return qrUtils.enableInvertedQrFallback(new ZXingBrowser.BrowserQRCodeReader());
+            }
+
+            function scanQrImage(file) {
+                if (!file) return;
+                stopQrCamera();
+                setQrButtonsDisabled(true);
+                loadQrDecoder().then(function (ZXingBrowser) {
+                    var imageUrl = URL.createObjectURL(file);
+                    var reader = createQrReader(ZXingBrowser);
+                    return reader.decodeFromImageUrl(imageUrl).then(function (result) {
+                        applyQrResult(result);
+                    }).finally(function () {
+                        URL.revokeObjectURL(imageUrl);
+                    });
+                }).catch(function (error) {
+                    notifyQrError('qr_image_failed', error);
+                }).finally(function () {
+                    setQrButtonsDisabled(false);
+                });
+            }
+
+            function startQrCamera() {
+                var cameraStatus = qrUtils ? qrUtils.getCameraStatus(window, navigator) : { available: false, reason: 'unsupported' };
+                if (!cameraStatus.available) {
+                    var warningKey = cameraStatus.reason === 'insecure' ? 'qr_camera_insecure' : 'qr_camera_unsupported';
+                    RED.notify(qrText(warningKey), { type: 'warning', fixed: true });
+                    return;
+                }
+                stopQrCamera();
+                qrScannerStarting = true;
+                setQrButtonsDisabled(true);
+                $qrCameraPanel.show();
+                loadQrDecoder().then(function (ZXingBrowser) {
+                    if (!qrScannerStarting) return null;
+                    var reader = createQrReader(ZXingBrowser);
+                    return reader.decodeFromConstraints({
+                        audio: false,
+                        video: { facingMode: { ideal: 'environment' } }
+                    }, $qrCameraVideo[0], function (result, error, controls) {
+                        if (error) { /* ZXing keeps trying while the QR is outside the frame. */ }
+                        if (result) applyQrResult(result, controls);
+                    });
+                }).then(function (controls) {
+                    if (!controls) return;
+                    if (!qrScannerStarting) {
+                        try { controls.stop(); } catch (error) { }
+                        return;
+                    }
+                    qrScannerControls = controls;
+                    qrScannerStarting = false;
+                    $qrCameraButton.prop('disabled', true);
+                    $qrImageButton.prop('disabled', false);
+                }).catch(function (error) {
+                    stopQrCamera();
+                    if (qrUtils && qrUtils.isCameraPermissionError(error)) {
+                        notifyQrError('qr_camera_permission_denied');
+                    } else {
+                        notifyQrError('qr_camera_failed', error);
+                    }
+                });
+            }
+
+            var initialCameraStatus = qrUtils ? qrUtils.getCameraStatus(window, navigator) : { available: false, reason: 'unsupported' };
+            if (!initialCameraStatus.available) {
+                $qrCameraWarning.text(qrText(initialCameraStatus.reason === 'insecure' ? 'qr_camera_insecure' : 'qr_camera_unsupported')).show();
+            }
+
+            $qrCameraButton.on('click', startQrCamera);
+            $qrCameraStop.on('click', stopQrCamera);
+            $qrImageButton.on('click', function () {
+                stopQrCamera();
+                $qrImageFile.trigger('click');
+            });
+            $qrImageFile.on('change', function () {
+                var file = this.files && this.files[0];
+                this.value = '';
+                scanQrImage(file);
+            });
+            node._matterQrCleanup = stopQrCamera;
 
             function storageExportUrl() {
                 var adminRoot = (RED.settings && typeof RED.settings.httpAdminRoot === 'string') ? RED.settings.httpAdminRoot : '/';
@@ -134,11 +294,6 @@
                 }
                 $pairButton.prop('disabled', true);
                 $pairSpinner.show();
-                var myNotification = RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_wait"), {
-                    modal: false,
-                    fixed: true,
-                    type: 'info'
-                });
                 $.ajax({
                     url: 'KNXUltimateMatterPair?serverId=' + node.id + '&code=' + encodeURIComponent(code) + (desiredName !== '' ? '&name=' + encodeURIComponent(desiredName) : ''),
                     dataType: 'json',
@@ -159,7 +314,6 @@
                     try { msg = jqXHR.responseJSON.error; } catch (e) { msg = errorThrown || textStatus; }
                     notifyPairingError(msg);
                 }).always(function () {
-                    if (myNotification) myNotification.close();
                     $pairButton.prop('disabled', false);
                     $pairSpinner.hide();
                 });
@@ -194,11 +348,21 @@
             });
         },
         oneditsave: function () {
+            if (typeof this._matterQrCleanup === 'function') this._matterQrCleanup();
+            delete this._matterQrCleanup;
             // Return to the info tab
             try {
                 RED.sidebar.show("info");
             } catch (error) { }
         },
+        oneditcancel: function () {
+            if (typeof this._matterQrCleanup === 'function') this._matterQrCleanup();
+            delete this._matterQrCleanup;
+        },
+        oneditdelete: function () {
+            if (typeof this._matterQrCleanup === 'function') this._matterQrCleanup();
+            delete this._matterQrCleanup;
+        },
         label: function () {
             return this.name || "Matter Controller";
         }
@@ -253,16 +417,38 @@
   <hr/>
 
   <div class="form-row">
-    <b><i class="fa fa-database"></i>&nbsp;<span data-i18n="matter-config.properties.storage_title"></span></b>
-    <button type="button" id="matter-storage-export" class="red-ui-button" style="margin-left:8px;"><i class="fa fa-download"></i>&nbsp;<span data-i18n="matter-config.properties.storage_export"></span></button>
-    <button type="button" id="matter-storage-import" class="red-ui-button"><i class="fa fa-upload"></i>&nbsp;<span data-i18n="matter-config.properties.storage_import"></span></button>
-    <input type="file" id="matter-storage-file" accept="application/json,.json" style="display:none;">
+    <b><i class="fa fa-qrcode"></i>&nbsp;<span data-i18n="matter-config.properties.pairing_title"></span></b>
   </div>
 
-  <hr/>
+  <div class="form-row">
+    <label for="matter-pairing-name">
+      <i class="fa fa-tag"></i>
+      <span data-i18n="matter-config.properties.pairing_name"></span>
+    </label>
+    <input type="text" id="matter-pairing-name" placeholder="Kitchen plug" style="width:250px;">
+  </div>
 
   <div class="form-row">
-    <b><i class="fa fa-qrcode"></i>&nbsp;<span data-i18n="matter-config.properties.pairing_title"></span></b>
+    <label>
+      <i class="fa fa-qrcode"></i>
+      <span data-i18n="matter-config.properties.qr_acquire"></span>
+    </label>
+    <button type="button" id="matter-qr-camera" class="red-ui-button">
+      <i class="fa fa-camera"></i>&nbsp;<span data-i18n="matter-config.properties.qr_scan_camera"></span>
+    </button>
+    <button type="button" id="matter-qr-image" class="red-ui-button">
+      <i class="fa fa-image"></i>&nbsp;<span data-i18n="matter-config.properties.qr_scan_image"></span>
+    </button>
+    <input type="file" id="matter-qr-image-file" accept="image/*" style="display:none;">
+  </div>
+
+  <div class="form-row" id="matter-qr-camera-warning" role="status" style="display:none; margin-left:105px; width:calc(100% - 105px); color:#b36b00;"></div>
+
+  <div class="form-row" id="matter-qr-camera-panel" style="display:none; margin-left:105px; width:calc(100% - 105px);">
+    <video id="matter-qr-camera-video" autoplay muted playsinline style="display:block; width:100%; max-width:430px; max-height:300px; background:#111; border-radius:4px; object-fit:cover;"></video>
+    <button type="button" id="matter-qr-camera-stop" class="red-ui-button" style="margin-top:6px;">
+      <i class="fa fa-stop"></i>&nbsp;<span data-i18n="matter-config.properties.qr_stop_camera"></span>
+    </button>
   </div>
 
   <div class="form-row">
@@ -274,17 +460,6 @@
     <button type="button" id="matterPairButton" class="red-ui-button" style="margin-left:6px; color:#1b7d33; border-color:#1b7d33;">
       <i class="fa fa-link"></i>&nbsp;<span data-i18n="matter-config.properties.pair_button"></span>
     </button>
-    <span id="matterPairSpinner" style="margin-left:6px; display:none; color:#1b7d33;">
-      <i class="fa fa-circle-notch fa-spin"></i>
-    </span>
-  </div>
-
-  <div class="form-row">
-    <label for="matter-pairing-name">
-      <i class="fa fa-tag"></i>
-      <span data-i18n="matter-config.properties.pairing_name"></span>
-    </label>
-    <input type="text" id="matter-pairing-name" placeholder="Kitchen plug" style="width:250px;">
   </div>
   <hr/>
 
@@ -310,6 +485,23 @@
     </table>
   </div>
 
+  <hr/>
+
+  <div class="form-row">
+    <b><i class="fa fa-database"></i>&nbsp;<span data-i18n="matter-config.properties.storage_title"></span></b>
+    <button type="button" id="matter-storage-export" class="red-ui-button" style="margin-left:8px;"><i class="fa fa-download"></i>&nbsp;<span data-i18n="matter-config.properties.storage_export"></span></button>
+    <button type="button" id="matter-storage-import" class="red-ui-button"><i class="fa fa-upload"></i>&nbsp;<span data-i18n="matter-config.properties.storage_import"></span></button>
+    <input type="file" id="matter-storage-file" accept="application/json,.json" style="display:none;">
+  </div>
+
+  <div id="matterPairSpinner" role="alertdialog" aria-modal="true" aria-labelledby="matter-pairing-overlay-message"
+       style="display:none; position:fixed; inset:0; z-index:100000; background:rgba(20, 24, 28, 0.72); cursor:wait;">
+    <div style="position:absolute; top:50%; left:50%; transform:translate(-50%, -50%); min-width:280px; max-width:80vw; padding:28px 34px; border-radius:8px; background:#fff; color:#333; text-align:center; box-shadow:0 8px 30px rgba(0,0,0,0.4);">
+      <i class="fa fa-circle-notch fa-spin" aria-hidden="true" style="display:block; margin-bottom:16px; color:#1b7d33; font-size:54px;"></i>
+      <strong id="matter-pairing-overlay-message" data-i18n="matter-config.properties.pairing_wait" style="font-size:16px;"></strong>
+    </div>
+  </div>
+
   <br/>
   <br/>
   <br/>

package/nodes/matter-config.js

@@ -53,14 +53,15 @@ module.exports = (RED) => {
       }
     }
     const clientMatchesNode = (client, nodeId) => client?.matterNodeId === '__UNIVERSAL__' || String(client?.matterNodeId) === String(nodeId)
+    const clientOwnsNode = (client, nodeId) => client?.matterNodeId !== '__UNIVERSAL__' && String(client?.matterNodeId) === String(nodeId)
 
     node.initMatterConnection = async () => {
       try {
         if (node.matterManager !== null) await node.matterManager.close()
       } catch (error) { /* empty */ }
       try {
-        const { classMatter } = await import('./utils/matterEngine.mjs')
-        node.matterManager = new classMatter(node.matterStoragePath, node.matterInstanceId, node.fabricLabel, node.sysLogger)
+        const { classMatter: MatterControllerEngine } = await import('./utils/matterEngine.mjs')
+        node.matterManager = new MatterControllerEngine(node.matterStoragePath, node.matterInstanceId, node.fabricLabel, node.sysLogger)
       } catch (error) {
         node.sysLogger?.error(`Errore matter-config: node.initMatterConnection: ${error.message}`)
         throw (error)
@@ -70,6 +71,7 @@ module.exports = (RED) => {
       node.matterManager.on('event', (_event) => {
         node.nodeClients.forEach((_oClient) => {
           try {
+            if (clientOwnsNode(_oClient, _event?.nodeId)) _oClient.clearMatterCommandBlock?.('connected')
             if (_oClient.handleSendMatter !== undefined) _oClient.handleSendMatter(_event)
           } catch (error) {
             node.sysLogger?.error(`Errore node.matterManager.on(event): ${error.message}`)
@@ -81,6 +83,7 @@ module.exports = (RED) => {
       node.matterManager.on('matterEvent', (_event) => {
         node.nodeClients.forEach((_oClient) => {
           try {
+            if (clientOwnsNode(_oClient, _event?.nodeId)) _oClient.clearMatterCommandBlock?.('connected')
             if (_oClient.handleMatterClusterEvent !== undefined) _oClient.handleMatterClusterEvent(_event)
           } catch (error) {
             node.sysLogger?.error(`Errore node.matterManager.on(matterEvent): ${error.message}`)
@@ -92,6 +95,9 @@ module.exports = (RED) => {
       node.matterManager.on('nodeInitialized', (_nodeId) => {
         node.nodeClients.forEach((_oClient) => {
           if (clientMatchesNode(_oClient, _nodeId)) {
+            if (clientOwnsNode(_oClient, _nodeId)) {
+              safeClientCall(_oClient, () => _oClient.clearMatterCommandBlock?.('connected'), 'clearMatterCommandBlock')
+            }
             safeClientCall(_oClient, () => _oClient.handleMatterNodeInitialized(_nodeId), 'handleMatterNodeInitialized')
           }
         })
@@ -101,6 +107,13 @@ module.exports = (RED) => {
       node.matterManager.on('nodeState', (_nodeId, _state) => {
         node.nodeClients.forEach((_oClient) => {
           if (clientMatchesNode(_oClient, _nodeId)) {
+            if (clientOwnsNode(_oClient, _nodeId)) {
+              if (_state === 'connected') {
+                safeClientCall(_oClient, () => _oClient.clearMatterCommandBlock?.('connected'), 'clearMatterCommandBlock')
+              } else {
+                safeClientCall(_oClient, () => _oClient.blockMatterCommands?.('Matter device unavailable'), 'blockMatterCommands')
+              }
+            }
             safeClientCall(_oClient, () => _oClient.setNodeStatusMatter({
               fill: _state === 'connected' ? 'green' : 'yellow',
               shape: _state === 'connected' ? 'dot' : 'ring',
@@ -114,6 +127,39 @@ module.exports = (RED) => {
         })
       })
 
+      node.matterManager.on('commandError', ({ item, error, code } = {}) => {
+        if (!item?.nodeId) return
+        const text = code === 'MATTER_NODE_NOT_COMMISSIONED'
+          ? 'Device no longer commissioned'
+          : code === 'MATTER_NODE_UNAVAILABLE' || code === 'MATTER_COMMAND_TIMEOUT'
+            ? 'Matter device unavailable'
+            : `Matter command error: ${error || 'unknown error'}`
+        const mustBlock = ['MATTER_NODE_NOT_COMMISSIONED', 'MATTER_NODE_UNAVAILABLE', 'MATTER_COMMAND_TIMEOUT'].includes(code)
+        if (mustBlock) {
+          const queued = node.matterManager.deleteMatterQueue(item.nodeId)
+          if (queued && typeof queued.catch === 'function') queued.catch((queueError) => node.sysLogger?.warn(`Matter queue purge error: ${queueError.message}`))
+        }
+        node.nodeClients.forEach((_oClient) => {
+          if (String(_oClient?.matterNodeId) !== String(item.nodeId)) return
+          safeClientCall(_oClient, () => {
+            if (mustBlock && typeof _oClient.blockMatterCommands === 'function') {
+              _oClient.blockMatterCommands(text)
+              return
+            }
+            const status = {
+              fill: 'red',
+              shape: 'ring',
+              text,
+              payload: ''
+            }
+            if (typeof _oClient.setNodeStatusMatter === 'function') return _oClient.setNodeStatusMatter(status)
+            // The legacy light profile's setNodeStatusHue deliberately recolours normal
+            // state updates blue, so use the Node-RED status API directly for errors.
+            if (typeof _oClient.status === 'function') return _oClient.status(status)
+          }, 'Matter command error status')
+        })
+      })
+
       node.matterManager.on('connected', () => {
         node.nodeClients.forEach((_oClient) => {
           safeClientCall(_oClient, () => _oClient.setNodeStatusMatter({

package/nodes/utils/matterControllerCommandGate.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const COMMAND_TIMER_KEYS = [
+  'timerBlink',
+  'timerColorCycle',
+  'timerStepDim',
+  'timerStepDimHSV_H',
+  'timerStepDimHSV_S',
+  'timerStepDimTunableWhite'
+]
+
+const setupMatterControllerCommandGate = (node) => {
+  node.matterCommandBlocked = false
+  node.matterCommandBlockReason = ''
+
+  node.isMatterCommandBlocked = () => node.matterCommandBlocked === true
+
+  node.blockMatterCommands = (reason = 'Matter device unavailable') => {
+    node.matterCommandBlocked = true
+    node.matterCommandBlockReason = String(reason || 'Matter device unavailable')
+    COMMAND_TIMER_KEYS.forEach((key) => {
+      if (node[key] !== undefined && node[key] !== null) clearInterval(node[key])
+      node[key] = undefined
+    })
+    node.status({
+      fill: 'red',
+      shape: 'ring',
+      text: node.matterCommandBlockReason
+    })
+  }
+
+  node.clearMatterCommandBlock = (source = 'editor') => {
+    if (node.matterCommandBlocked !== true) return false
+    node.matterCommandBlocked = false
+    node.matterCommandBlockReason = ''
+    node.status({
+      fill: source === 'connected' ? 'green' : 'yellow',
+      shape: 'ring',
+      text: source === 'connected' ? 'Matter device reconnected' : 'Matter retry enabled'
+    })
+    return true
+  }
+
+  return node
+}
+
+module.exports = { setupMatterControllerCommandGate }