node-red-contrib-knx-ultimate 6.2.3-beta.3 → 6.2.3-beta.4

package/CHANGELOG.md

@@ -6,8 +6,9 @@
 
 # CHANGELOG
 
-**Version 6.2.3-beta.3** - August 2026<br/>
+**Version 6.2.3-beta.4** - August 2026<br/>
 
+- **Matter Controller — live commissioning progress**: replaced the pairing overlay spinner with a milestone-based progress bar driven by the actual matter.js commissioning flow. The blocking panel now describes the active discovery, PASE, device-information, fail-safe, regulatory, time-sync, attestation, credential, access-control, CASE reconnect and completion phase in English; when exposed by the commissionee, its product name, Vendor ID and Product ID appear below the current operation. Progress polling is local to the Node-RED editor, stops with the pairing request and is isolated by operation ID across editor tabs.<br/>
 - **HUE Controller — unified Hue API v2 node**: added one controller node covering the complete set of existing Hue functions: lights and grouped lights, plugs, buttons, Tap dial, motion and camera motion, contacts, light level, temperature, humidity, scenes, battery, Zigbee connectivity and device software update. The compact device-function selector uses one third of the available width and opens the established dedicated editor with its localized labels; KNX mapping fields are hidden whenever no **KNX Gateway** is selected, including `none`, an empty value and **Add new...**. The YouTube tutorial playlist now appears once at the top of the editor, while routine inline `form-tips` are removed from the unified UI and a compact migration privacy disclaimer remains directly below the conversion button. The migration action runs entirely inside the browser and changes only the legacy HUE nodes requiring conversion, preserving every existing property, config reference, group, position and link; no flow or node data leaves the editor and the workspace remains undeployed for user review. After a successful conversion, an editable email draft addressed to the author opens without navigating the top-level Node-RED page and contains only the converted-node count and space for optional notes; the user decides whether to send it and nothing is sent automatically. The final Node-RED message offers an optional support button, and the PayPal donation page opens only when the user clicks it. Each profile executes the same mature runtime contract, preserving KNX telegram types, Hue event/status direction, flow pins and loop protection. Runtime implementations, editor definitions, templates and all six translation catalogs are embedded as package-internal HUE Controller profiles; registration order no longer matters, the KNX and Hue gateway fields remain real config-node selectors, and the controller has no runtime or editor dependency on deprecated node types. The original Hue Light node remains unchanged. Existing dedicated Hue nodes remain fully compatible and registered, use Node-RED's special `deprecated` category so they no longer appear in the palette, retain the lighter `#E7E9F6` color and `(deprecated)` canvas suffix without changing saved names, and show a localized HUE Controller migration notice at the top of their editors.<br/>
 - **HUE Controller — complete per-function help**: the established help of every dedicated Hue node is now incorporated under the corresponding HUE Controller function key, with an anchor index and automatic sidebar focus when the function changes. The same 15-section reference is included in the Controller wiki documentation in EN, IT, DE, FR, ES and zh-CN; legacy deprecation notices are deliberately excluded from the embedded copies.<br/>
 - **HUE Controller — legacy-independent maintenance boundary**: private runtime profiles and the private editor/template/translation sources are now the canonical implementation of HUE Controller. Its generator and consistency check read only those private sources and never inspect the frozen legacy nodes, so future Controller fixes remain isolated and the dedicated deprecated nodes can eventually be removed without breaking either runtime or UI. Added detailed architecture and lifecycle comments around runtime constructor capture, RED facades, editor mounting, profile drafts, dynamic pins, translations and the Hue Light bootstrap path.<br/>

package/nodes/commonFunctions.js

@@ -800,18 +800,51 @@ module.exports = (RED) => {
       }
     })
 
+    // MATTER: current commissioning milestone for the blocking editor overlay.
+    // The operation id keeps simultaneous editor tabs from displaying each other's progress.
+    RED.httpAdmin.get('/KNXUltimateMatterPairProgress', RED.auth.needsPermission('matter-config.read'), (req, res) => {
+      try {
+        const matterServer = RED.nodes.getNode(req.query.serverId)
+        if (matterServer === null || matterServer === undefined) {
+          res.json({ active: false, percent: 0, error: 'PLEASE DEPLOY FIRST: then try again.' })
+          return
+        }
+        res.json(matterServer.getCommissioningProgress(req.query.operationId))
+      } catch (error) {
+        RED.log.error(`Err KNXUltimateMatterPairProgress: ${error.message}`)
+        res.json({ active: false, percent: 0, error: error.message })
+      }
+    })
+
     // MATTER: commissions (pairs) a new Matter device using a pairing code or QR code string
     RED.httpAdmin.get('/KNXUltimateMatterPair', RED.auth.needsPermission('matter-config.write'), async (req, res) => {
+      let matterServer
+      const requestedOperationId = String(req.query.operationId || '').replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 80)
+      // Keep direct callers of the pre-progress endpoint backward compatible. The editor
+      // supplies its own id so it can poll; legacy callers receive a server-only id.
+      const operationId = requestedOperationId || `server-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
       try {
-        const matterServer = RED.nodes.getNode(req.query.serverId)
+        matterServer = RED.nodes.getNode(req.query.serverId)
         if (matterServer === null || matterServer === undefined) {
           res.json({ error: 'PLEASE DEPLOY FIRST: then try again.' })
           return
         }
-        const nodeId = await matterServer.commission(req.query.code, { targetHost: req.query.targetHost })
+        if (!matterServer.beginCommissioningProgress(operationId)) {
+          res.json({ error: 'Another Matter commissioning operation is already in progress.' })
+          return
+        }
+        const nodeId = await matterServer.commission(req.query.code, {
+          targetHost: req.query.targetHost,
+          onProgress: (progress) => matterServer.reportCommissioningProgress(operationId, progress)
+        })
         const requestedName = String(req.query.name || '').trim()
         let renameError = null
         if (requestedName !== '') {
+          matterServer.reportCommissioningProgress(operationId, {
+            phase: 'naming',
+            percent: 99,
+            message: 'Applying the requested device name…'
+          })
           try {
             await matterServer.renameCommissionedNode(nodeId, requestedName)
           } catch (error) {
@@ -823,8 +856,19 @@ module.exports = (RED) => {
         try {
           device = matterServer.getCommissionedNodesDetails().find((item) => String(item.nodeId) === String(nodeId)) || null
         } catch (error) { /* empty */ }
+        matterServer.endCommissioningProgress(operationId, {
+          phase: 'complete',
+          percent: 100,
+          message: 'Matter commissioning completed successfully.'
+        })
         res.json({ nodeId, name: device?.name, productName: device?.productName, vendorName: device?.vendorName, renameError })
       } catch (error) {
+        try {
+          matterServer?.endCommissioningProgress(operationId, {
+            phase: 'error',
+            message: `Commissioning failed: ${error.message}`
+          })
+        } catch (progressError) { /* empty */ }
         const targetHost = req.query.targetHost ? ` targetHost=${req.query.targetHost}` : ''
         RED.log.error(`Err KNXUltimateMatterPair:${targetHost} ${error.stack || error.message}`)
         res.json({ error: error.message })

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

@@ -15,7 +15,7 @@ Der Controller kommuniziert mit den Geräten über das **IP-Netzwerk** (WLAN, Et
 
 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.
+Während der Kommissionierung überdeckt ein blockierender Bildschirm den Editor und verhindert weitere Klicks, bis der Vorgang erfolgreich abgeschlossen wird oder fehlschlägt. Der Fortschrittsbalken folgt den tatsächlichen matter.js-Meilensteinen und zeigt den aktuellen Vorgang auf Englisch. Wenn das Gerät seine Produktidentität bereitstellt, werden außerdem Produktname, Vendor ID und Product ID angezeigt.
 
 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.
 

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

@@ -15,7 +15,7 @@ The controller talks to the devices over the **IP network** (WiFi, Ethernet, or
 
 Instead of typing the QR payload, click **Webcam** to scan it live or **Image** to read it from a local picture. Both standard dark-on-light and inverted white-on-dark QR codes are supported. Decoding takes place entirely in the browser; after a valid Matter QR is read, the editor fills the pairing-code field and immediately starts pairing. Enter the optional device name before scanning if desired. A manually typed code still starts only when you click **PAIR**. Live webcam access requires the editor to be opened over HTTPS or from `localhost`; when that is not possible, the editor explains the limitation and image loading remains available.
 
-While commissioning is in progress, a blocking wait panel covers the editor and prevents further clicks until the operation succeeds or fails.
+While commissioning is in progress, a blocking panel covers the editor and prevents further clicks until the operation succeeds or fails. Its progress bar follows the actual matter.js milestones and shows the current operation in English. When the device exposes its product identity, the panel also shows its product name, Vendor ID and Product ID.
 
 If the device is brand new and only supports Bluetooth commissioning, first pair it with its vendor app or another Matter controller (Alexa, Google Home, Apple Home), then use that controller's **"share / pair with another hub"** function to generate a new pairing code for KNX-Ultimate. This way the device joins multiple fabrics at once.
 

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

@@ -15,7 +15,7 @@ El controlador se comunica con los dispositivos a través de la **red IP** (WiFi
 
 En lugar de escribir el payload QR, pulsa **Webcam** para escanearlo en directo o **Imagen** para leerlo desde una foto local. Se admiten tanto los códigos QR estándar oscuros sobre fondo claro como los invertidos blancos sobre fondo oscuro. La decodificación se realiza íntegramente en el navegador; tras leer un QR Matter válido, el editor rellena el campo del código e inicia inmediatamente el emparejamiento. Introduce antes el nombre opcional del dispositivo si lo deseas. Un código escrito manualmente sigue iniciándose solo al pulsar **EMPAREJAR**. El acceso en directo a la webcam requiere que el editor se abra mediante HTTPS o desde `localhost`; si no es posible, el editor explica la limitación y la carga de imágenes sigue disponible.
 
-Durante el comisionado, un panel de espera bloqueante cubre el editor e impide más clics hasta que la operación finaliza correctamente o con un error.
+Durante el comisionado, un panel bloqueante cubre el editor e impide más clics hasta que la operación finaliza correctamente o con un error. La barra de progreso sigue los hitos reales de matter.js y muestra en inglés la operación actual. Cuando el dispositivo expone su identidad de producto, el panel también muestra el nombre del producto, Vendor ID y Product ID.
 
 Si el dispositivo es nuevo de fábrica y solo admite emparejamiento por Bluetooth, emparéjalo primero con la app del fabricante o con otro controlador Matter (Alexa, Google Home, Apple Home) y usa después su función **"compartir / emparejar con otro hub"** para generar un nuevo código para KNX-Ultimate. Así el dispositivo se une a varias fabrics a la vez.
 

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

@@ -15,7 +15,7 @@ Le contrôleur communique avec les appareils via le **réseau IP** (WiFi, Ethern
 
 Au lieu de saisir le payload QR, cliquez sur **Webcam** pour le scanner en direct ou sur **Image** pour le lire depuis une photo locale. Les QR codes standards sombres sur fond clair et les codes inversés blancs sur fond sombre sont pris en charge. Le décodage s'effectue entièrement dans le navigateur ; après la lecture d'un QR Matter valide, l'éditeur remplit le champ du code et démarre immédiatement l'appairage. Saisissez auparavant le nom facultatif de l'appareil si nécessaire. Un code saisi manuellement ne démarre toujours qu'après un clic sur **APPAIRER**. L'accès direct à la webcam exige que l'éditeur soit ouvert via HTTPS ou depuis `localhost` ; sinon l'éditeur explique cette limitation et le chargement d'une image reste disponible.
 
-Pendant le commissionnement, un panneau d'attente bloquant recouvre l'éditeur et empêche tout autre clic jusqu'à la réussite ou l'échec de l'opération.
+Pendant le commissionnement, un panneau bloquant recouvre l'éditeur et empêche tout autre clic jusqu'à la réussite ou l'échec de l'opération. La barre de progression suit les étapes réelles de matter.js et décrit l'opération en cours en anglais. Lorsque l'appareil expose son identité produit, le panneau affiche aussi le nom du produit, le Vendor ID et le Product ID.
 
 Si l'appareil est neuf et ne prend en charge que l'appairage Bluetooth, appairez-le d'abord avec l'app du fabricant ou un autre contrôleur Matter (Alexa, Google Home, Apple Home), puis utilisez sa fonction **« partager / appairer avec un autre hub »** pour générer un nouveau code pour KNX-Ultimate. L'appareil rejoint ainsi plusieurs fabrics à la fois.
 

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

@@ -15,7 +15,7 @@ Il controller comunica con i dispositivi tramite la **rete IP** (WiFi, Ethernet,
 
 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.
+Durante il commissioning, un pannello bloccante copre l'editor e impedisce ulteriori clic finché l'operazione non termina con successo o con un errore. La barra di avanzamento segue le fasi reali di matter.js e mostra in inglese l'operazione corrente. Quando il device espone la propria identità di prodotto, il pannello mostra anche nome prodotto, Vendor ID e Product ID.
 
 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.
 

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

@@ -15,7 +15,7 @@
 
 无需手动输入二维码 payload：点击**摄像头**可实时扫描，点击**图片**可从本地照片读取。支持浅色背景上的标准深色二维码以及深色背景上的反白二维码。解码完全在浏览器中进行；读取到有效的 Matter 二维码后，编辑器会填写配对码并立即自动开始配对。如需设置可选设备名称，请在扫描前填写。手动输入的配对码仍需点击**配对**才会开始。实时使用摄像头要求通过 HTTPS 或从 `localhost` 打开编辑器；若条件不满足，编辑器会说明此限制，而图片加载功能仍然可用。
 
-配对期间，阻塞式等待面板会覆盖编辑器并阻止进一步点击，直到操作成功完成或失败。
+配对期间，阻塞式面板会覆盖编辑器并阻止进一步点击，直到操作成功完成或失败。进度条跟随 matter.js 的实际阶段，并以英文显示当前操作。当设备公开产品身份时，面板还会显示产品名称、Vendor ID 和 Product ID。
 
 如果设备是全新的且仅支持蓝牙配对，请先用厂商 App 或其他 Matter 控制器（Alexa、Google Home、Apple Home）配对，然后使用其**"与其他中枢共享/配对"**功能为 KNX-Ultimate 生成新的配对码。这样设备可以同时加入多个 fabric。
 

package/nodes/matter-config.html

@@ -22,6 +22,11 @@
             var $devicesBody = $("#matter-devices-body");
             var $refreshDevices = $("#matterRefreshDevices");
             var $pairSpinner = $("#matterPairSpinner");
+            var $pairProgress = $("#matter-pairing-progress");
+            var $pairProgressBar = $("#matter-pairing-progress-bar");
+            var $pairProgressPercent = $("#matter-pairing-progress-percent");
+            var $pairProgressDescription = $("#matter-pairing-progress-description");
+            var $pairProgressDevice = $("#matter-pairing-progress-device");
             var $storageExport = $('#matter-storage-export');
             var $storageImport = $('#matter-storage-import');
             var $storageFile = $('#matter-storage-file');
@@ -35,6 +40,8 @@
             var qrScannerControls = null;
             var qrScannerStarting = false;
             var qrUtils = window.KNXUltimateMatterQrScanner;
+            var pairingProgressTimer = null;
+            var pairingOperationId = '';
 
             function qrText(key) {
                 return RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties." + key);
@@ -183,7 +190,10 @@
                 this.value = '';
                 scanQrImage(file);
             });
-            node._matterQrCleanup = stopQrCamera;
+            node._matterQrCleanup = function () {
+                stopQrCamera();
+                stopPairingProgress();
+            };
 
             function storageExportUrl() {
                 var adminRoot = (RED.settings && typeof RED.settings.httpAdminRoot === 'string') ? RED.settings.httpAdminRoot : '/';
@@ -209,6 +219,44 @@
                 });
             }
 
+            function setPairingProgress(data) {
+                if (!data) return;
+                var percent = Number(data.percent);
+                if (!isFinite(percent)) percent = 0;
+                percent = Math.max(0, Math.min(100, Math.round(percent)));
+                $pairProgress.attr('aria-valuenow', percent);
+                $pairProgressBar.css('width', percent + '%');
+                $pairProgressPercent.text(percent + '%');
+                if (data.message) $pairProgressDescription.text(data.message);
+                if (data.device && data.device.productName) {
+                    var details = data.device.productName;
+                    if (data.device.vendorId !== undefined) details += ' · VID ' + data.device.vendorId;
+                    if (data.device.productId !== undefined) details += ' · PID ' + data.device.productId;
+                    $pairProgressDevice.text(details).show();
+                }
+            }
+
+            function stopPairingProgress() {
+                if (pairingProgressTimer !== null) clearInterval(pairingProgressTimer);
+                pairingProgressTimer = null;
+                pairingOperationId = '';
+            }
+
+            function startPairingProgress(operationId) {
+                stopPairingProgress();
+                pairingOperationId = operationId;
+                $pairProgressDevice.empty().hide();
+                setPairingProgress({ percent: 2, message: 'Preparing Matter commissioning…' });
+                pairingProgressTimer = setInterval(function () {
+                    var activeOperationId = pairingOperationId;
+                    if (!activeOperationId) return;
+                    $.getJSON('KNXUltimateMatterPairProgress?serverId=' + encodeURIComponent(node.id) + '&operationId=' + encodeURIComponent(activeOperationId) + '&_=' + Date.now(), function (data) {
+                        if (activeOperationId !== pairingOperationId || !data || data.operationId !== activeOperationId) return;
+                        setPairingProgress(data);
+                    });
+                }, 400);
+            }
+
             function renderDevices(devices) {
                 $devicesBody.empty();
                 if (!Array.isArray(devices) || devices.length === 0) {
@@ -293,15 +341,20 @@
                     return;
                 }
                 $pairButton.prop('disabled', true);
+                var operationId = 'matter-' + Date.now() + '-' + Math.random().toString(36).slice(2, 10);
+                var pairingSucceeded = false;
+                startPairingProgress(operationId);
                 $pairSpinner.show();
                 $.ajax({
-                    url: 'KNXUltimateMatterPair?serverId=' + node.id + '&code=' + encodeURIComponent(code) + (desiredName !== '' ? '&name=' + encodeURIComponent(desiredName) : ''),
+                    url: 'KNXUltimateMatterPair?serverId=' + encodeURIComponent(node.id) + '&operationId=' + encodeURIComponent(operationId) + '&code=' + encodeURIComponent(code) + (desiredName !== '' ? '&name=' + encodeURIComponent(desiredName) : ''),
                     dataType: 'json',
                     timeout: 180000
                 }).done(function (data) {
                     if (data && data.error) {
                         notifyPairingError(data.error);
                     } else {
+                        pairingSucceeded = true;
+                        setPairingProgress({ percent: 100, message: 'Matter commissioning completed successfully.' });
                         var pairedName = data.name || data.productName || data.nodeId;
                         RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_ok") + ' ' + pairedName + ' (Node ID ' + data.nodeId + ')', { type: 'success' });
                         if (data.renameError) RED.notify(data.renameError, { type: 'warning', fixed: true });
@@ -314,8 +367,10 @@
                     try { msg = jqXHR.responseJSON.error; } catch (e) { msg = errorThrown || textStatus; }
                     notifyPairingError(msg);
                 }).always(function () {
+                    stopPairingProgress();
                     $pairButton.prop('disabled', false);
-                    $pairSpinner.hide();
+                    if (pairingSucceeded) setTimeout(function () { $pairSpinner.hide(); }, 350);
+                    else $pairSpinner.hide();
                 });
             });
 
@@ -496,9 +551,15 @@
 
   <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 style="position:absolute; top:50%; left:50%; transform:translate(-50%, -50%); width:460px; 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);">
+      <strong id="matter-pairing-overlay-message" data-i18n="matter-config.properties.pairing_wait" style="display:block; margin-bottom:18px; font-size:16px;"></strong>
+      <div id="matter-pairing-progress" role="progressbar" aria-label="Matter commissioning progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"
+           style="position:relative; width:100%; height:20px; overflow:hidden; border-radius:10px; background:#66717a; box-shadow:inset 0 1px 3px rgba(0,0,0,0.22);">
+        <div id="matter-pairing-progress-bar" style="width:0; height:100%; border-radius:10px; background:#1b7d33; transition:width 250ms ease;"></div>
+        <span id="matter-pairing-progress-percent" style="position:absolute; inset:0; color:#fff; font-size:12px; font-weight:bold; line-height:20px; text-shadow:0 1px 2px #000;">0%</span>
+      </div>
+      <div id="matter-pairing-progress-description" aria-live="polite" style="min-height:20px; margin-top:14px; font-size:14px; line-height:20px;">Preparing Matter commissioning…</div>
+      <div id="matter-pairing-progress-device" style="display:none; margin-top:7px; color:#666; font-size:12px;"></div>
     </div>
   </div>
 

package/nodes/matter-config.js

@@ -22,6 +22,13 @@ module.exports = (RED) => {
     node.matterManager = null
     node.timerMatterConfigCheckState = null
     node.storageOperation = null
+    node.commissioningProgress = {
+      active: false,
+      operationId: '',
+      sequence: 0,
+      percent: 0,
+      message: 'Waiting for commissioning to start.'
+    }
     try {
       node.sysLogger = loggerSetup({ loglevel: node.loglevel, setPrefix: 'matter-config.js' })
     } catch (error) { console.log(error.stack) }
@@ -247,6 +254,50 @@ module.exports = (RED) => {
       return node.matterManager.commission(_pairingCode, _options)
     }
 
+    node.beginCommissioningProgress = (_operationId) => {
+      if (node.commissioningProgress.active === true) return false
+      node.commissioningProgress = {
+        active: true,
+        operationId: String(_operationId || ''),
+        sequence: node.commissioningProgress.sequence + 1,
+        percent: 2,
+        phase: 'starting',
+        message: 'Preparing Matter commissioning…',
+        updatedAt: Date.now()
+      }
+      return true
+    }
+
+    node.reportCommissioningProgress = (_operationId, _progress = {}) => {
+      if (node.commissioningProgress.operationId !== String(_operationId || '')) return false
+      const numericPercent = Number(_progress.percent)
+      const previousPercent = Number(node.commissioningProgress.percent) || 0
+      node.commissioningProgress = {
+        ...node.commissioningProgress,
+        ..._progress,
+        active: true,
+        operationId: node.commissioningProgress.operationId,
+        sequence: node.commissioningProgress.sequence + 1,
+        percent: Number.isFinite(numericPercent) ? Math.max(previousPercent, Math.min(100, Math.max(0, numericPercent))) : previousPercent,
+        updatedAt: Date.now()
+      }
+      return true
+    }
+
+    node.endCommissioningProgress = (_operationId, _progress = {}) => {
+      if (node.commissioningProgress.operationId !== String(_operationId || '')) return false
+      node.reportCommissioningProgress(_operationId, _progress)
+      node.commissioningProgress.active = false
+      return true
+    }
+
+    node.getCommissioningProgress = (_operationId) => {
+      if (node.commissioningProgress.operationId !== String(_operationId || '')) {
+        return { active: false, percent: 0, message: 'Waiting for commissioning to start.' }
+      }
+      return { ...node.commissioningProgress }
+    }
+
     node.removeCommissionedNode = async (_nodeId) => {
       if (node.matterManager === null) throw new Error('Matter controller not started')
       return node.matterManager.removeNode(_nodeId)

package/nodes/utils/matterEngine.mjs

@@ -88,15 +88,95 @@ class classMatter extends EventEmitter {
     const { Environment, StorageService, Logger, LogLevel } = await import('@matter/main')
     const { Seconds } = await import('@matter/general')
     const { CommissioningController } = await import('@project-chip/matter.js')
+    const { ControllerCommissioningFlow } = await import('@matter/protocol')
     const { NodeStates } = await import('@project-chip/matter.js/device')
     const { ManualPairingCodeCodec, QrPairingCodeCodec, NodeId } = await import('@matter/main/types')
     const { BasicInformation, GeneralCommissioning } = await import('@matter/main/clusters')
     this._api = {
-      Environment, StorageService, Logger, LogLevel, Seconds, CommissioningController, NodeStates, ManualPairingCodeCodec, QrPairingCodeCodec, NodeId, BasicInformation, GeneralCommissioning
+      Environment, StorageService, Logger, LogLevel, Seconds, CommissioningController, ControllerCommissioningFlow, NodeStates, ManualPairingCodeCodec, QrPairingCodeCodec, NodeId, BasicInformation, GeneralCommissioning
     }
     return this._api
   }
 
+  _reportCommissioningProgress = (_callback, progress) => {
+    if (typeof _callback !== 'function') return
+    try {
+      _callback(progress)
+    } catch (error) {
+      this._log('warn', `classMatter: commissioning progress callback: ${error.message}`)
+    }
+  }
+
+  _createProgressCommissioningFlow = (_callback) => {
+    const BaseFlow = this._api.ControllerCommissioningFlow
+    const report = (progress) => this._reportCommissioningProgress(_callback, progress)
+    const descriptions = {
+      GetInitialData: { percent: 22, message: 'Reading commissioning information from the device…' },
+      'GeneralCommissioning.ArmFailsafe': { percent: 30, message: 'Arming the device fail-safe timer…' },
+      'GeneralCommissioning.ConfigureRegulatoryInformation': { percent: 36, message: 'Applying regulatory configuration…' },
+      'TimeSynchronization.SynchronizeTime': { percent: 42, message: 'Synchronizing the device clock…' },
+      'OperationalCredentials.DeviceAttestation': { percent: 50, message: 'Verifying device identity and attestation…' },
+      'OperationalCredentials.Certificates': { percent: 62, message: 'Installing operational credentials…' },
+      AccessControl: { percent: 72, message: 'Configuring Matter access control…' },
+      'NetworkCommissioning.Validate': { percent: 76, message: 'Checking the device network configuration…' },
+      'NetworkCommissioning.Wifi': { percent: 78, message: 'Connecting the device to the Wi-Fi network…' },
+      'NetworkCommissioning.Thread': { percent: 78, message: 'Connecting the device to the Thread network…' },
+      Reconnect: { percent: 84, message: 'Reconnecting through the operational CASE session…' },
+      'GeneralCommissioning.Complete': { percent: 92, message: 'Completing commissioning on the device…' },
+      'OperationalCredentials.UpdateFabricLabel': { percent: 96, message: 'Applying the Matter fabric label…' },
+      'AdditionalLogic.AddDefaultOtaProvider': { percent: 97, message: 'Configuring the default OTA provider…' }
+    }
+
+    return class ProgressCommissioningFlow extends BaseFlow {
+      constructor (...args) {
+        super(...args)
+        this.commissioningSteps.forEach((step) => {
+          const stepLogic = step.stepLogic
+          step.stepLogic = async () => {
+            const description = descriptions[step.name] || {
+              percent: 20,
+              message: `Running Matter commissioning step ${step.stepNumber}.${step.subStepNumber}: ${step.name}…`
+            }
+            const device = this.collectedCommissioningData?.productName
+              ? {
+                  productName: this.collectedCommissioningData.productName,
+                  vendorId: this.collectedCommissioningData.vendorId,
+                  productId: this.collectedCommissioningData.productId
+                }
+              : undefined
+            report({
+              phase: 'commissioning',
+              step: `${step.stepNumber}.${step.subStepNumber}`,
+              stepName: step.name,
+              percent: description.percent,
+              message: description.message,
+              device
+            })
+            const result = await stepLogic()
+            // GetInitialData is the first point where the commissionee may have exposed
+            // its product identity. Publish it immediately instead of waiting for the
+            // following step to make the editor show it.
+            if (step.name === 'GetInitialData' && this.collectedCommissioningData?.productName) {
+              report({
+                phase: 'commissioning',
+                step: `${step.stepNumber}.${step.subStepNumber}`,
+                stepName: step.name,
+                percent: 28,
+                message: 'Device identified. Preparing secure commissioning…',
+                device: {
+                  productName: this.collectedCommissioningData.productName,
+                  vendorId: this.collectedCommissioningData.vendorId,
+                  productId: this.collectedCommissioningData.productId
+                }
+              })
+            }
+            return result
+          }
+        })
+      }
+    }
+  }
+
   _resolveTargetHosts = async (_targetHost) => {
     const host = normalizeHostForCompare(_targetHost)
     if (host === '') return []
@@ -286,6 +366,12 @@ class classMatter extends EventEmitter {
     let passcode
     let identifierData
     const discoveryCapabilities = { onIpNetwork: true }
+    const onProgress = _options?.onProgress
+    this._reportCommissioningProgress(onProgress, {
+      phase: 'preparing',
+      percent: 5,
+      message: 'Validating the Matter pairing code…'
+    })
     if (code.toUpperCase().startsWith('MT:')) {
       const qr = api.QrPairingCodeCodec.decode(code)[0]
       passcode = qr.passcode
@@ -305,6 +391,11 @@ class classMatter extends EventEmitter {
       }
       const targetHost = (_options?.targetHost || '').toString().trim()
       if (targetHost !== '') {
+        this._reportCommissioningProgress(onProgress, {
+          phase: 'discovery',
+          percent: 10,
+          message: `Looking for the Matter device at ${targetHost}…`
+        })
         const commissionableDevice = await this._discoverCommissionableDeviceAtHost(identifierData, discoveryCapabilities, targetHost)
         discovery = commissionableDevice !== undefined
           ? {
@@ -319,6 +410,11 @@ class classMatter extends EventEmitter {
       let lastError
       for (const discoveryAttempt of discoveryAttempts) {
         try {
+          this._reportCommissioningProgress(onProgress, {
+            phase: 'pase',
+            percent: 15,
+            message: 'Discovering the device and establishing a secure PASE session…'
+          })
           nodeId = await this.controller.commissionNode({
             commissioning: {
               nodeId: commissioningNodeId,
@@ -326,7 +422,10 @@ class classMatter extends EventEmitter {
             },
             discovery: discoveryAttempt,
             passcode
-          }, { connectNodeAfterCommissioning: false })
+          }, {
+            connectNodeAfterCommissioning: false,
+            commissioningFlowImpl: this._createProgressCommissioningFlow(onProgress)
+          })
           lastError = undefined
           break
         } catch (error) {
@@ -355,12 +454,22 @@ class classMatter extends EventEmitter {
       throw error
     }
     try {
+      this._reportCommissioningProgress(onProgress, {
+        phase: 'attaching',
+        percent: 98,
+        message: 'Loading the commissioned device structure…'
+      })
       await this._attachNode(nodeId)
     } catch (error) {
       // Pairing succeeded: never report it as failed just because the first connection
       // attempt errored. The node will be attached again at the next controller start.
       this._log('warn', `classMatter: commission: node ${nodeId} paired but not yet attached: ${error.message}`)
     }
+    this._reportCommissioningProgress(onProgress, {
+      phase: 'complete',
+      percent: 100,
+      message: 'Matter commissioning completed successfully.'
+    })
     return nodeId.toString()
   }
 

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.2.3-beta.3",
+  "version": "6.2.3-beta.4",
   "description": "KNX Ultimate is the most advanced KNX integration for Node-RED, providing secure KNX/IP communication, routing, ETS project import, Philips Hue, Matter Controller and Matter Bridge (control matter device via KNX and expose KNX GA via Matter), MQTT, diagnostics with AI, virtual devices, and powerful automation nodes. Build professional, reliable, and scalable smart home and building automation projects with minimal effort.",
   "files": [
     "nodes/",