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

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

@@ -0,0 +1,26 @@
+{
+  "matter-config": {
+    "properties": {
+      "title": "Matter 控制器",
+      "intro": "此节点是一个 Matter 控制器（拥有自己的 fabric）。在此配对您的 Matter 设备，然后使用 \"Matter Device\" 节点将其映射到 KNX 组地址。请先部署该节点，然后回到这里配对设备。",
+      "node-config-input-name": "名称",
+      "fabric_label": "Fabric 标签",
+      "pairing_title": "配对新设备",
+      "pairing_help": "输入 11 位手动配对码（例如 3497-011-2332）或二维码内容（MT:....）。设备必须可通过 IP 网络访问（WiFi/以太网或通过边界路由器的 Thread）。如果设备已与其他控制器（Alexa、Google、Apple）配对，请使用其\"与其他中枢共享/配对\"功能获取新的配对码。",
+      "pairing_code": "配对码",
+      "pair_button": "配对",
+      "devices_title": "已配对设备",
+      "col_name": "名称",
+      "col_product": "产品",
+      "col_state": "状态",
+      "no_devices": "尚未配对任何设备。",
+      "unpair_confirm": "移除（解除配对）设备",
+      "unpair_ok": "设备已移除。",
+      "deploy_first": "请先部署此配置节点，然后重试。",
+      "pairing_code_missing": "请输入配对码。",
+      "pairing_wait": "正在配对，最多可能需要一分钟...",
+      "pairing_failed": "配对失败",
+      "pairing_ok": "设备配对成功！"
+    }
+  }
+}

package/nodes/matter-config.html

@@ -0,0 +1,226 @@
+<script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/htmlUtils.js"></script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('matter-config', {
+        category: 'config',
+        defaults: {
+            name: { value: "Matter Controller" },
+            fabricLabel: { value: "KNX-Ultimate" }
+        },
+        oneditprepare: function () {
+            // Go to the help panel
+            try {
+                RED.sidebar.show("help");
+            } catch (error) { }
+
+            var node = this;
+            var $pairButton = $("#matterPairButton");
+            var $pairingCode = $("#matter-pairing-code");
+            var $devicesBody = $("#matter-devices-body");
+            var $refreshDevices = $("#matterRefreshDevices");
+            var $pairSpinner = $("#matterPairSpinner");
+
+            function renderDevices(devices) {
+                $devicesBody.empty();
+                if (!Array.isArray(devices) || devices.length === 0) {
+                    $devicesBody.append('<tr><td colspan="5" style="text-align:center; color:#999;">' + RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.no_devices") + '</td></tr>');
+                    return;
+                }
+                devices.forEach(function (dev) {
+                    var stateColor = dev.connectionState === 'connected' ? '#1b7d33' : '#c00';
+                    var $tr = $('<tr></tr>');
+                    $tr.append($('<td></td>').text(dev.name || ''));
+                    $tr.append($('<td></td>').text((dev.vendorName || '') + (dev.productName ? ' ' + dev.productName : '')));
+                    $tr.append($('<td style="font-family:monospace;"></td>').text(dev.nodeId));
+                    $tr.append($('<td></td>').append($('<span></span>').css('color', stateColor).text(dev.connectionState)));
+                    var $unpair = $('<button type="button" class="red-ui-button" style="color:#c00; border-color:#c00;"><i class="fa fa-trash"></i></button>');
+                    $unpair.on('click', function () {
+                        var confirmMsg = RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.unpair_confirm") + ' "' + (dev.name || dev.nodeId) + '"?';
+                        if (!window.confirm(confirmMsg)) return;
+                        $unpair.prop('disabled', true);
+                        $.getJSON('KNXUltimateMatterUnpair?serverId=' + node.id + '&nodeId=' + encodeURIComponent(dev.nodeId), function (data) {
+                            if (data && data.error) {
+                                RED.notify(data.error, { type: 'error' });
+                            } else {
+                                RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.unpair_ok"), { type: 'success' });
+                            }
+                            loadDevices();
+                        }).fail(function (jqXHR, textStatus, errorThrown) {
+                            RED.notify('Unpair failed: ' + (errorThrown || textStatus), { type: 'error' });
+                            $unpair.prop('disabled', false);
+                        });
+                    });
+                    $tr.append($('<td style="text-align:right;"></td>').append($unpair));
+                    $devicesBody.append($tr);
+                });
+            }
+
+            function loadDevices() {
+                $devicesBody.empty();
+                $devicesBody.append('<tr><td colspan="5" style="text-align:center;"><i class="fa fa-circle-notch fa-spin"></i></td></tr>');
+                $.getJSON('KNXUltimateMatterGetNodes?serverId=' + node.id + '&_=' + Date.now(), function (data) {
+                    if (data && data.error) {
+                        $devicesBody.empty();
+                        $devicesBody.append('<tr><td colspan="5" style="text-align:center; color:#c00;">' + data.error + '</td></tr>');
+                        return;
+                    }
+                    renderDevices(data && data.devices ? data.devices : []);
+                }).fail(function () {
+                    $devicesBody.empty();
+                    $devicesBody.append('<tr><td colspan="5" style="text-align:center; color:#999;">' + RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.deploy_first") + '</td></tr>');
+                });
+            }
+
+            $refreshDevices.on('click', function () {
+                loadDevices();
+            });
+
+            $pairButton.on('click', function () {
+                var code = ($pairingCode.val() || '').trim();
+                if (code === '') {
+                    RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_code_missing"), { type: 'warning' });
+                    return;
+                }
+                $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),
+                    dataType: 'json',
+                    timeout: 180000
+                }).done(function (data) {
+                    if (data && data.error) {
+                        RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_failed") + ': ' + data.error, { type: 'error', timeout: 8000 });
+                    } else {
+                        RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_ok") + ' (Node ID ' + data.nodeId + ')', { type: 'success' });
+                        $pairingCode.val('');
+                        loadDevices();
+                    }
+                }).fail(function (jqXHR, textStatus, errorThrown) {
+                    var msg = '';
+                    try { msg = jqXHR.responseJSON.error; } catch (e) { msg = errorThrown || textStatus; }
+                    RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_failed") + ': ' + msg, { type: 'error', timeout: 8000 });
+                }).always(function () {
+                    if (myNotification) myNotification.close();
+                    $pairButton.prop('disabled', false);
+                    $pairSpinner.hide();
+                });
+            });
+
+            loadDevices();
+        },
+        oneditsave: function () {
+            // Return to the info tab
+            try {
+                RED.sidebar.show("info");
+            } catch (error) { }
+        },
+        label: function () {
+            return this.name || "Matter Controller";
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="matter-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="matter-config.properties.title"></span></b>
+    <p align="center" style="margin:8px 0;">
+      <svg width="70" height="77" viewBox="0 8 40 44" xmlns="http://www.w3.org/2000/svg" aria-label="Matter" style="vertical-align:middle;">
+        <g fill="currentColor" stroke="none">
+          <circle cx="20" cy="30" r="4.5"/>
+          <g>
+            <rect x="18.4" y="9" width="3.2" height="11"/>
+            <path d="M 14.5 18.5 L 25.5 18.5 L 20 25.5 Z"/>
+          </g>
+          <g transform="rotate(120 20 30)">
+            <rect x="18.4" y="9" width="3.2" height="11"/>
+            <path d="M 14.5 18.5 L 25.5 18.5 L 20 25.5 Z"/>
+          </g>
+          <g transform="rotate(240 20 30)">
+            <rect x="18.4" y="9" width="3.2" height="11"/>
+            <path d="M 14.5 18.5 L 25.5 18.5 L 20 25.5 Z"/>
+          </g>
+        </g>
+      </svg>
+      <br/>
+      <span style="font-size:18px; font-weight:600; letter-spacing:1px;">matter</span>
+    </p>
+    <p><span data-i18n="matter-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="matter-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-fabricLabel">
+      <i class="fa fa-id-card"></i>
+      <span data-i18n="matter-config.properties.fabric_label"></span>
+    </label>
+    <input type="text" id="node-config-input-fabricLabel" placeholder="KNX-Ultimate">
+  </div>
+
+  <hr/>
+
+  <div class="form-row">
+    <b><i class="fa fa-qrcode"></i>&nbsp;<span data-i18n="matter-config.properties.pairing_title"></span></b>
+    <p><span data-i18n="matter-config.properties.pairing_help"></span></p>
+  </div>
+
+  <div class="form-row">
+    <label for="matter-pairing-code">
+      <i class="fa fa-key"></i>
+      <span data-i18n="matter-config.properties.pairing_code"></span>
+    </label>
+    <input type="text" id="matter-pairing-code" placeholder="3497-011-2332 or MT:Y.K90...." style="width:250px;">
+    <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>
+
+  <hr/>
+
+  <div class="form-row">
+    <b><i class="fa fa-microchip"></i>&nbsp;<span data-i18n="matter-config.properties.devices_title"></span></b>
+    <button type="button" id="matterRefreshDevices" class="red-ui-button" style="margin-left:6px; color:#1b7d33; border-color:#1b7d33;">
+      <i class="fa fa-refresh"></i>
+    </button>
+  </div>
+
+  <div class="form-row">
+    <table style="width:100%; border-collapse:collapse;" class="red-ui-editableList">
+      <thead>
+        <tr style="border-bottom:1px solid #ccc; text-align:left;">
+          <th data-i18n="matter-config.properties.col_name"></th>
+          <th data-i18n="matter-config.properties.col_product"></th>
+          <th>Node ID</th>
+          <th data-i18n="matter-config.properties.col_state"></th>
+          <th></th>
+        </tr>
+      </thead>
+      <tbody id="matter-devices-body"></tbody>
+    </table>
+  </div>
+
+  <br/>
+   <br/>
+    <br/>
+    <br/>
+   <br/>
+    <br/>
+</script>

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)
+}