node-red-contrib-knx-ultimate 5.0.4 → 5.2.2

package/nodes/matter-config.js

@@ -0,0 +1,242 @@
+/* eslint-disable max-len */
+const path = require('path')
+
+// 10/09/2024 Setup the color logger
+const loggerSetup = (options) => {
+  const clog = require('node-color-log').createNamedLogger(options.setPrefix)
+  clog.setLevel(options.loglevel)
+  clog.setDate(() => (new Date()).toLocaleString())
+  return clog
+}
+
+module.exports = (RED) => {
+  function matterConfig (config) {
+    RED.nodes.createNode(this, config)
+    const node = this
+    node.nodeClients = [] // Stores the registered clients
+    node.loglevel = config.loglevel !== undefined ? config.loglevel : 'error'
+    node.sysLogger = null
+    node.matterManager = null
+    node.timerMatterConfigCheckState = null
+    try {
+      node.sysLogger = loggerSetup({ loglevel: node.loglevel, setPrefix: 'matter-config.js' })
+    } catch (error) { console.log(error.stack) }
+    node.name = config.name === undefined || config.name === '' ? 'Matter Controller' : config.name
+    node.fabricLabel = config.fabricLabel === undefined || config.fabricLabel === '' ? 'KNX-Ultimate' : config.fabricLabel
+    // Stable, filesystem-safe identity of the controller (fabric), bound to this config node.
+    node.matterInstanceId = `knxultimate-matter-${node.id.replace(/[^a-zA-Z0-9]/g, '')}`
+    node.matterStoragePath = path.join(RED.settings.userDir || '.', 'knxultimatestorage', 'matter')
+
+    // Helper like the hue-config one
+    Object.defineProperty(node, 'linkStatus', {
+      get: function () {
+        return node.matterManager?.matterConnectionStatus ?? 'disconnected'
+      }
+    })
+
+    const safeClientCall = (client, fn, label) => {
+      try {
+        if (!client || typeof fn !== 'function') return
+        fn()
+      } catch (error) {
+        node.sysLogger?.warn(`Matter client ${label} error: ${error.message}`)
+      }
+    }
+
+    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)
+      } catch (error) {
+        node.sysLogger?.error(`Errore matter-config: node.initMatterConnection: ${error.message}`)
+        throw (error)
+      }
+
+      // Attribute changes coming from the Matter devices
+      node.matterManager.on('event', (_event) => {
+        node.nodeClients.forEach((_oClient) => {
+          try {
+            if (_oClient.handleSendMatter !== undefined) _oClient.handleSendMatter(_event)
+          } catch (error) {
+            node.sysLogger?.error(`Errore node.matterManager.on(event): ${error.message}`)
+          }
+        })
+      })
+
+      // Cluster events (button presses etc.)
+      node.matterManager.on('matterEvent', (_event) => {
+        node.nodeClients.forEach((_oClient) => {
+          try {
+            if (_oClient.handleMatterClusterEvent !== undefined) _oClient.handleMatterClusterEvent(_event)
+          } catch (error) {
+            node.sysLogger?.error(`Errore node.matterManager.on(matterEvent): ${error.message}`)
+          }
+        })
+      })
+
+      // A paired node completed the initial sync: let the clients do their initial read
+      node.matterManager.on('nodeInitialized', (_nodeId) => {
+        node.nodeClients.forEach((_oClient) => {
+          if (_oClient.matterNodeId === _nodeId) {
+            safeClientCall(_oClient, () => _oClient.handleMatterNodeInitialized(), 'handleMatterNodeInitialized')
+          }
+        })
+      })
+
+      // Connection state of a single paired device changed
+      node.matterManager.on('nodeState', (_nodeId, _state) => {
+        node.nodeClients.forEach((_oClient) => {
+          if (_oClient.matterNodeId === _nodeId) {
+            safeClientCall(_oClient, () => _oClient.setNodeStatusMatter({
+              fill: _state === 'connected' ? 'green' : 'yellow',
+              shape: _state === 'connected' ? 'dot' : 'ring',
+              text: _state,
+              payload: ''
+            }), 'setNodeStatusMatter')
+            if (_state === 'connected') {
+              safeClientCall(_oClient, () => _oClient.handleMatterNodeInitialized(), 'handleMatterNodeInitialized')
+            }
+          }
+        })
+      })
+
+      node.matterManager.on('connected', () => {
+        node.nodeClients.forEach((_oClient) => {
+          safeClientCall(_oClient, () => _oClient.setNodeStatusMatter({
+            fill: 'green',
+            shape: 'ring',
+            text: 'Controller ready',
+            payload: ''
+          }), 'setNodeStatusMatter')
+        })
+      })
+
+      node.matterManager.on('disconnected', () => {
+        node.nodeClients.forEach((_oClient) => {
+          safeClientCall(_oClient, () => _oClient.setNodeStatusMatter({
+            fill: 'red',
+            shape: 'ring',
+            text: 'Matter Disconnected',
+            payload: ''
+          }), 'setNodeStatusMatter')
+        })
+      })
+
+      try {
+        await node.matterManager.Connect()
+      } catch (error) {
+        node.sysLogger?.error(`Errore matter-config: Connect: ${error.message}`)
+      }
+    }
+
+    node.startWatchdogTimer = async () => {
+      if (node.timerMatterConfigCheckState !== null) clearTimeout(node.timerMatterConfigCheckState)
+      node.timerMatterConfigCheckState = setTimeout(() => {
+        (async () => {
+          if (node.linkStatus === 'disconnected') {
+            try {
+              await node.initMatterConnection()
+            } catch (error) {
+              node.sysLogger?.error(`Errore matter-config: node.startWatchdogTimer: ${error.message}`)
+            }
+          }
+          await node.startWatchdogTimer()
+        })()
+      }, 60000)
+    }
+
+    setTimeout(() => {
+      (async () => {
+        try {
+          await node.initMatterConnection()
+        } catch (error) {
+          // Never let a failed startup (missing dependency, corrupted storage...) become
+          // an unhandled rejection: the watchdog will retry the connection later.
+          node.sysLogger?.error(`matter-config: startup error: ${error.message}`)
+        }
+        try {
+          node.startWatchdogTimer()
+        } catch (error) {
+          node.sysLogger?.error(`matter-config: watchdog start error: ${error.message}`)
+        }
+      })()
+    }, 5000)
+
+    // Functions called from the nodes and the admin endpoints ----------------------------------------
+    node.getCommissionedNodesDetails = () => {
+      if (node.matterManager === null) return []
+      return node.matterManager.getCommissionedNodesDetails()
+    }
+
+    node.getNodeStructure = (_nodeId) => {
+      if (node.matterManager === null) throw new Error('Matter controller not started')
+      return node.matterManager.getNodeStructure(_nodeId)
+    }
+
+    node.commission = async (_pairingCode) => {
+      if (node.matterManager === null) throw new Error('Matter controller not started')
+      return node.matterManager.commission(_pairingCode)
+    }
+
+    node.removeCommissionedNode = async (_nodeId) => {
+      if (node.matterManager === null) throw new Error('Matter controller not started')
+      return node.matterManager.removeNode(_nodeId)
+    }
+    // END functions called from the nodes -------------------------------------------------------------
+
+    node.addClient = (_Node) => {
+      try {
+        if (node.nodeClients.filter((x) => x.id === _Node.id).length !== 0) return
+        node.nodeClients.push(_Node)
+        if (node.linkStatus !== 'connected') {
+          safeClientCall(_Node, () => _Node.setNodeStatusMatter({
+            fill: 'grey',
+            shape: 'ring',
+            text: 'Waiting for Matter controller'
+          }), 'setNodeStatusMatter')
+          return
+        }
+        safeClientCall(_Node, () => _Node.setNodeStatusMatter({
+          fill: 'green',
+          shape: 'ring',
+          text: 'Ready'
+        }), 'setNodeStatusMatter')
+        // If the paired node already has values in cache, do the initial read straight away
+        safeClientCall(_Node, () => _Node.handleMatterNodeInitialized(), 'handleMatterNodeInitialized')
+      } catch (error) {
+        node.sysLogger?.error(`matter-config: addClient error: ${error.message}`)
+      }
+    }
+
+    node.removeClient = (_Node) => {
+      try {
+        node.nodeClients = node.nodeClients.filter((x) => x.id !== _Node.id)
+      } catch (error) {
+        /* empty */
+      }
+    }
+
+    node.on('close', (done) => {
+      try {
+        node.nodeClients = []
+        if (node.timerMatterConfigCheckState !== null) clearTimeout(node.timerMatterConfigCheckState);
+        (async () => {
+          try {
+            if (node.matterManager !== null) await node.matterManager.close()
+            node.matterManager = null
+            node.sysLogger = null
+            done()
+          } catch (error) {
+            done()
+          }
+        })()
+      } catch (error) {
+        done()
+      }
+    })
+  }
+  RED.nodes.registerType('matter-config', matterConfig)
+}

package/nodes/matterbridge-config.html

@@ -0,0 +1,121 @@
+<script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/htmlUtils.js"></script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('matterbridge-config', {
+        category: 'config',
+        defaults: {
+            name: { value: '' },
+            bridgeDeviceName: { value: 'KNX-Ultimate Bridge' },
+            bridgePort: { value: 5540, required: true, validate: RED.validators.number() }
+        },
+        oneditprepare: function () {
+            try { RED.sidebar.show('help'); } catch (error) { }
+
+            var node = this;
+            var $pairingBody = $('#mbc-pairing-body');
+            var $refreshPairing = $('#mbc-refresh-pairing');
+            var $resetButton = $('#mbc-factory-reset');
+
+            var t = function (key) {
+                return RED._('node-red-contrib-knx-ultimate/matterbridge-config:matterbridge-config.properties.' + key);
+            };
+
+            function loadPairingInfo() {
+                $pairingBody.html('<i class="fa fa-circle-notch fa-spin"></i>');
+                $.getJSON('KNXUltimateMatterBridgeInfo?configId=' + node.id + '&_=' + Date.now(), function (info) {
+                    $pairingBody.empty();
+                    if (info.error) {
+                        $pairingBody.append($('<p style="color:#999;"></p>').text(info.error));
+                        return;
+                    }
+                    if (!info.running) {
+                        $pairingBody.append($('<p style="color:#999;"></p>').text(t('not_running')));
+                        return;
+                    }
+                    if (info.commissioned) {
+                        $pairingBody.append($('<p style="color:#1b7d33;"></p>').text(t('commissioned') + ' (' + info.fabrics.length + ')'));
+                        info.fabrics.forEach(function (f) {
+                            $pairingBody.append($('<div style="margin-left:10px;"></div>').text('• ' + (f.label || 'Controller') + ' (vendor ' + f.vendorId + ')'));
+                        });
+                        $resetButton.show();
+                        return;
+                    }
+                    $pairingBody.append($('<p style="color:#b8860b;"></p>').text(t('awaiting')));
+                    if (info.manualPairingCode) {
+                        $pairingBody.append($('<p></p>').append($('<b style="font-size:18px; letter-spacing:2px;"></b>').text(info.manualPairingCode)));
+                    }
+                    if (info.qrAscii) {
+                        $pairingBody.append($('<pre style="font-family:monospace; line-height:1.05; font-size:7px; display:inline-block; padding:6px; background:#fff; color:#000;"></pre>').text(info.qrAscii));
+                    }
+                    if (info.qrPairingCode) {
+                        var url = 'https://project-chip.github.io/connectedhomeip/qrcode.html?data=' + encodeURIComponent(info.qrPairingCode);
+                        $pairingBody.append($('<p></p>').append($('<a target="_blank"></a>').attr('href', url).text(t('qr_link'))));
+                    }
+                    $resetButton.hide();
+                }).fail(function () {
+                    $pairingBody.empty();
+                    $pairingBody.append($('<p style="color:#999;"></p>').text(t('deploy_first')));
+                });
+            }
+
+            $refreshPairing.on('click', function () { loadPairingInfo(); });
+            $resetButton.on('click', function () {
+                if (!window.confirm(t('reset_confirm'))) return;
+                $resetButton.prop('disabled', true);
+                $.getJSON('KNXUltimateMatterBridgeReset?configId=' + node.id, function (data) {
+                    if (data && data.error) RED.notify(data.error, { type: 'error' });
+                    else RED.notify(t('reset_ok'), { type: 'success' });
+                    loadPairingInfo();
+                }).always(function () { $resetButton.prop('disabled', false); });
+            });
+
+            loadPairingInfo();
+        },
+        oneditsave: function () {
+            try { RED.sidebar.show('info'); } catch (error) { }
+        },
+        label: function () {
+            return this.name || this.bridgeDeviceName || 'Matter Bridge';
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="matterbridge-config">
+  <div class="form-row" style="margin-bottom:10px;">
+    <span style="color:#ff0000"><i class="fa fa-youtube"></i></span>&nbsp;<a target="_blank" href="https://www.youtube.com/playlist?list=PL9Yh1bjbLAYrU8PsVhW4xzEug2WtVFv3E"><b>KNX-Ultimate video tutorials (YouTube playlist)</b></a>
+  </div>
+
+  <div class="form-row">
+    <b><span data-i18n="matterbridge-config.properties.title"></span></b>
+    <p><span data-i18n="matterbridge-config.properties.intro"></span></p>
+  </div>
+
+  <div class="form-row">
+    <label for="node-config-input-name">
+      <i class="fa fa-tag"></i> <span data-i18n="matterbridge-config.properties.node-config-input-name"></span>
+    </label>
+    <input type="text" id="node-config-input-name">
+  </div>
+
+  <div class="form-row">
+    <label for="node-config-input-bridgeDeviceName" style="width:180px;">
+      <i class="fa fa-share-alt"></i> <span data-i18n="matterbridge-config.properties.bridge_name"></span>
+    </label>
+    <input type="text" id="node-config-input-bridgeDeviceName" style="width:220px;">
+    <label for="node-config-input-bridgePort" style="width:60px; text-align:right;"><span data-i18n="matterbridge-config.properties.port"></span></label>
+    <input type="number" id="node-config-input-bridgePort" style="width:90px;">
+  </div>
+
+  <hr/>
+
+  <div class="form-row">
+    <b><i class="fa fa-qrcode"></i>&nbsp;<span data-i18n="matterbridge-config.properties.pairing_title"></span></b>
+    <button type="button" id="mbc-refresh-pairing" class="red-ui-button" style="margin-left:6px; color:#1b7d33; border-color:#1b7d33;">
+      <i class="fa fa-refresh"></i>
+    </button>
+    <button type="button" id="mbc-factory-reset" class="red-ui-button" style="margin-left:6px; color:#c00; border-color:#c00; display:none;">
+      <i class="fa fa-trash"></i>&nbsp;<span data-i18n="matterbridge-config.properties.reset_button"></span>
+    </button>
+  </div>
+  <div class="form-row" id="mbc-pairing-body" style="text-align:center;"></div>
+</script>

package/nodes/matterbridge-config.js

@@ -0,0 +1,220 @@
+/* eslint-disable max-len */
+const path = require('path')
+
+// 10/09/2024 Setup the color logger
+const loggerSetup = (options) => {
+  const clog = require('node-color-log').createNamedLogger(options.setPrefix)
+  clog.setLevel(options.loglevel)
+  clog.setDate(() => (new Date()).toLocaleString())
+  return clog
+}
+
+// The running Matter servers, keyed by config node id. Kept OUTSIDE the node lifecycle:
+// a re-deploy must NOT restart the Matter server, otherwise the paired controllers
+// resume their session without re-reading the structure and never see device changes.
+// The devices are reconciled live instead; the server is closed only when the config
+// node is deleted/disabled.
+const runningBridges = new Map()
+
+module.exports = (RED) => {
+  function matterBridgeConfig (config) {
+    RED.nodes.createNode(this, config)
+    const node = this
+    node.loglevel = config.loglevel !== undefined ? config.loglevel : 'error'
+    node.sysLogger = null
+    try {
+      node.sysLogger = loggerSetup({ loglevel: node.loglevel, setPrefix: 'matterbridge-config.js' })
+    } catch (error) { console.log(error.stack) }
+
+    node.name = config.name === undefined || config.name === '' ? 'Matter Bridge' : config.name
+    node.bridgePort = Number(config.bridgePort) || 5540
+    node.bridgeDeviceName = config.bridgeDeviceName === undefined || config.bridgeDeviceName === '' ? 'KNX-Ultimate Bridge' : config.bridgeDeviceName
+    node.matterInstanceId = `knxultimate-bridge-${node.id.replace(/[^a-zA-Z0-9]/g, '')}`
+    node.matterStoragePath = path.join(RED.settings.userDir || '.', 'knxultimatestorage', 'matter')
+
+    node.matterBridge = null
+    node.deviceClients = new Map() // matterDeviceId -> device node
+    let startupTimer = null
+    let reconcileTimer = null
+    let closing = false
+
+    Object.defineProperty(node, 'linkStatus', {
+      get: function () {
+        return node.matterBridge?.bridgeStatus === 'running' ? 'running' : 'stopped'
+      }
+    })
+
+    const safeClientCall = (client, fn, label) => {
+      try {
+        if (!client || typeof fn !== 'function') return
+        fn()
+      } catch (error) {
+        node.sysLogger?.warn(`Matter bridge client ${label} error: ${error.message}`)
+      }
+    }
+
+    // Desired device definitions built from the currently registered device nodes.
+    const buildDeviceDefs = () => {
+      const defs = []
+      node.deviceClients.forEach((client) => {
+        try {
+          const def = typeof client.getMatterDef === 'function' ? client.getMatterDef() : undefined
+          if (def && def.id && def.type) defs.push(def)
+        } catch (error) { /* empty */ }
+      })
+      return defs
+    }
+
+    // Notify every registered device node that the bridge status changed.
+    const notifyClientsStatus = () => {
+      node.deviceClients.forEach((client) => {
+        safeClientCall(client, () => client.handleBridgeStatus(), 'handleBridgeStatus')
+      })
+    }
+
+    const bindEngineEvents = (engine) => {
+      engine.removeAllListeners()
+      // Matter -> KNX: a controller (Alexa...) sent a command to a bridged device.
+      // Route it to the device node that owns that Matter device.
+      engine.on('command', (command) => {
+        try {
+          const client = node.deviceClients.get(command.deviceId)
+          if (client === undefined) return
+          safeClientCall(client, () => client.handleMatterCommand(command), 'handleMatterCommand')
+        } catch (error) {
+          node.sysLogger?.warn(`matterbridge-config: command routing error: ${error.message}`)
+        }
+      })
+      engine.on('commissioned', () => notifyClientsStatus())
+      engine.on('decommissioned', () => notifyClientsStatus())
+      engine.on('fabricsChanged', () => notifyClientsStatus())
+      engine.on('online', () => notifyClientsStatus())
+    }
+
+    // Reconcile the exposed devices with the currently registered device nodes.
+    const scheduleReconcile = () => {
+      if (reconcileTimer !== null) clearTimeout(reconcileTimer)
+      reconcileTimer = setTimeout(() => {
+        (async () => {
+          try {
+            if (node.matterBridge === null || node.matterBridge.bridgeStatus !== 'running') return
+            await node.matterBridge.reconcileDevices(buildDeviceDefs())
+            notifyClientsStatus()
+          } catch (error) {
+            node.sysLogger?.warn(`matterbridge-config: reconcile error: ${error.message}`)
+          }
+        })()
+      }, 1500)
+    }
+
+    const ensureEngineStarted = async () => {
+      try {
+        const { classMatterBridge } = await import('./utils/matterBridgeEngine.mjs')
+        const existing = runningBridges.get(node.id)
+
+        if (existing !== undefined && existing.bridgeStatus === 'running' &&
+          Number(existing.options.port) === node.bridgePort &&
+          existing.options.deviceName === node.bridgeDeviceName) {
+          // Re-deploy: reuse the running Matter server and reconcile the devices live.
+          node.matterBridge = existing
+          bindEngineEvents(existing)
+          await existing.reconcileDevices(buildDeviceDefs())
+          notifyClientsStatus()
+          return
+        }
+
+        if (existing !== undefined) {
+          // Port or bridge name changed: a full restart is unavoidable.
+          try {
+            existing.removeAllListeners()
+            await existing.close()
+          } catch (error) { /* empty */ }
+          runningBridges.delete(node.id)
+        }
+
+        const engine = new classMatterBridge(node.matterStoragePath, node.matterInstanceId, {
+          info: (m) => node.sysLogger?.info(m),
+          warn: (m) => node.sysLogger?.warn(m),
+          error: (m) => node.sysLogger?.error(m),
+          debug: (m) => node.sysLogger?.debug(m)
+        }, { port: node.bridgePort, deviceName: node.bridgeDeviceName })
+        runningBridges.set(node.id, engine)
+        node.matterBridge = engine
+        bindEngineEvents(engine)
+        await engine.start(buildDeviceDefs())
+        notifyClientsStatus()
+      } catch (error) {
+        node.sysLogger?.error(`matterbridge-config: ensureEngineStarted error: ${error.message}`)
+      }
+    }
+
+    // The Matter server is started shortly after boot, giving the device nodes the
+    // time to register themselves during flow initialization.
+    startupTimer = setTimeout(() => {
+      (async () => {
+        if (closing) return
+        await ensureEngineStarted()
+      })()
+    }, 5000)
+
+    // Functions called from the device nodes -----------------------------------------
+    node.registerDevice = (client) => {
+      try {
+        if (!client || !client.matterDeviceId) return
+        node.deviceClients.set(client.matterDeviceId, client)
+        scheduleReconcile()
+      } catch (error) {
+        node.sysLogger?.warn(`matterbridge-config: registerDevice error: ${error.message}`)
+      }
+    }
+
+    node.unregisterDevice = (client) => {
+      try {
+        if (!client || !client.matterDeviceId) return
+        node.deviceClients.delete(client.matterDeviceId)
+        scheduleReconcile()
+      } catch (error) { /* empty */ }
+    }
+
+    node.setDeviceState = async (deviceId, fn, value) => {
+      if (node.matterBridge === null) return false
+      return node.matterBridge.setDeviceState(deviceId, fn, value)
+    }
+
+    node.getPairingInfo = () => {
+      if (node.matterBridge === null) return { running: false }
+      return node.matterBridge.getPairingInfo()
+    }
+
+    node.factoryResetBridge = async () => {
+      if (node.matterBridge === null) throw new Error('Matter bridge not started')
+      await node.matterBridge.factoryReset()
+      notifyClientsStatus()
+    }
+    // END functions called from the device nodes -------------------------------------
+
+    node.on('close', (removed, done) => {
+      closing = true
+      try {
+        if (startupTimer !== null) clearTimeout(startupTimer)
+        if (reconcileTimer !== null) clearTimeout(reconcileTimer)
+      } catch (error) { /* empty */ }
+      try {
+        if (node.matterBridge !== null) node.matterBridge.removeAllListeners()
+      } catch (error) { /* empty */ }
+      (async () => {
+        try {
+          if (removed === true && node.matterBridge !== null) {
+            await node.matterBridge.close()
+            runningBridges.delete(node.id)
+          }
+        } catch (error) { /* empty */ }
+        node.matterBridge = null
+        node.deviceClients.clear()
+        node.sysLogger = null
+        done()
+      })()
+    })
+  }
+  RED.nodes.registerType('matterbridge-config', matterBridgeConfig)
+}