@airnexus/node-red-contrib-matter-airnexus 0.2.4-airnexus.1

package/matter-bridge.js

@@ -0,0 +1,475 @@
+/**
+ * matter-bridge.js (AirNexus + robust refresh)
+ *
+ * Key:
+ * - Broadcast bridgeReset after server create and after server start (fixes stale endpoints after pairing reset)
+ * - Broadcast bridgeReset when commissioning becomes true (commissioned transition)
+ * - Poll commissioning state because it can change after start()
+ */
+
+const { Endpoint, Environment, ServerNode, Logger, VendorId, StorageService } = require("@matter/main");
+const { AggregatorEndpoint } = require("@matter/main/endpoints");
+const { NetworkCommissioning } = require("@matter/main/clusters");
+const { NetworkCommissioningServer } = require("@matter/main/behaviors");
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+const QRCode = require("qrcode");
+const { getMatterDeviceId, getMatterUniqueId } = require("./utils");
+
+// ============================================================================
+// UTILITY
+// ============================================================================
+
+function generatePasscode() {
+  let passcode = Math.floor(Math.random() * 99999997) + 1;
+  const invalidCodes = new Set([
+    11111111, 22222222, 33333333, 44444444, 55555555,
+    66666666, 77777777, 88888888, 12345678, 87654321
+  ]);
+  if (invalidCodes.has(passcode)) passcode += 1;
+  return +passcode.toString().padStart(8, "0");
+}
+
+function generateDiscriminator() {
+  return Math.floor(Math.random() * 4095);
+}
+
+function mkdirp(p) {
+  try { fs.mkdirSync(p, { recursive: true }); } catch (e) {}
+}
+
+// ============================================================================
+// BRIDGE CONFIG
+// ============================================================================
+
+class BridgeConfig {
+  constructor(config) {
+    this.name = config.name || "AirNexus Matter Bridge";
+    this.vendorId = +config.vendorId || 65521;
+    this.productId = +config.productId || 32768;
+    this.vendorName = config.vendorName || "AirNexus";
+    this.productName = config.productName || "AirNexus Dynamic Matter Bridge";
+
+    this.networkInterface = config.networkInterface || "";
+    this.storageLocation = config.storageLocation || "";
+    this.port = +config.port || 5540;
+    this.logLevel = config.logLevel || "WARN";
+
+    this.passcode = (config.passcode != null && String(config.passcode).trim() !== "")
+      ? +config.passcode
+      : generatePasscode();
+
+    this.discriminator = (config.discriminator != null && String(config.discriminator).trim() !== "")
+      ? +config.discriminator
+      : generateDiscriminator();
+  }
+
+  static setLogLevel(level) {
+    const logLevels = { FATAL: 5, ERROR: 4, WARN: 3, INFO: 1, DEBUG: 0 };
+    if (level in logLevels) Logger.defaultLogLevel = logLevels[level];
+  }
+}
+
+// ============================================================================
+// DEVICE MANAGER
+// ============================================================================
+
+class DeviceManager {
+  constructor(node) {
+    this.node = node;
+    this.registered = [];
+    this.pendingUsers = [];
+    this.failedDevices = new Set();
+  }
+
+  registerChild(child) {
+    this.node.log(`Registering device ${child.id}`);
+
+    if (this.registered.find(c => c.id === child.id)) {
+      this.node.warn(`Device ${child.id} already registered, skipping`);
+      return;
+    }
+
+    const idx = this.pendingUsers.indexOf(child.id);
+    if (idx > -1) this.pendingUsers.splice(idx, 1);
+
+    this.registered.push(child);
+    this.addToAggregator(child);
+
+    if (this.pendingUsers.length === 0 && this.node.serverReady) {
+      this.node.serverManager.start();
+    }
+  }
+
+  addToAggregator(child) {
+    const deviceId = getMatterDeviceId(child.id);
+    if (!this.node.aggregator) {
+      this.node.error("Aggregator not ready");
+      return;
+    }
+
+    const existing = this.node.aggregator.parts.get(deviceId);
+    if (existing) {
+      existing.nodeRed = child;
+      child.device = existing;
+      child.deviceAddedSuccessfully = true;
+      return;
+    }
+
+    try {
+      this.node.aggregator.add(child.device);
+      child.deviceAddedSuccessfully = true;
+      this.node.log(`Added device ${deviceId} to aggregator`);
+    } catch (e) {
+      this.handleDeviceError(child, e);
+    }
+  }
+
+  handleDeviceError(child, error) {
+    this.node.error(`Failed to add device ${child.id}: ${error.message}`);
+    child.error?.(`Device initialization failed: ${error.message}`);
+    child.status?.({ fill: "red", shape: "ring", text: "init failed" });
+    child.deviceAddedSuccessfully = false;
+    this.failedDevices.add(child.id);
+  }
+
+  notifyDevicesReady() {
+    setTimeout(() => {
+      this.registered.forEach(child => {
+        if (this.failedDevices.has(child.id) || child.deviceInitFailed) return;
+        try {
+          if (child.device?.state) {
+            void Object.keys(child.device.state);
+            child.emit("serverReady");
+          } else {
+            child.status?.({ fill: "red", shape: "ring", text: "init failed" });
+          }
+        } catch (e) {
+          child.status?.({ fill: "red", shape: "ring", text: "validation failed" });
+          this.failedDevices.add(child.id);
+        }
+      });
+    }, 800);
+  }
+
+  // ? Used by pairing reset + server recreate/start + commissioning
+  broadcastBridgeReset(meta = {}) {
+    setTimeout(() => {
+      this.registered.forEach(child => {
+        if (this.failedDevices.has(child.id) || child.deviceInitFailed || child._closed) return;
+        try { child.emit("bridgeReset", meta); } catch (e) {}
+      });
+    }, 500);
+  }
+}
+
+// ============================================================================
+// SERVER MANAGER
+// ============================================================================
+
+class ServerManager {
+  constructor(node, RED) {
+    this.node = node;
+    this.RED = RED;
+    this._createInProgress = false;
+  }
+
+  _getDefaultStorageLocation() {
+    const userDir = (this.RED?.settings?.userDir) ? this.RED.settings.userDir : process.cwd();
+    return path.join(userDir, "matter-storage", String(this.node.id));
+  }
+
+  _ensureStorageLocation() {
+    const cfg = this.node.bridgeConfig;
+    if (!cfg.storageLocation) cfg.storageLocation = this._getDefaultStorageLocation();
+    mkdirp(cfg.storageLocation);
+    return cfg.storageLocation;
+  }
+
+  async create() {
+    if (this._createInProgress) return;
+    this._createInProgress = true;
+
+    try {
+      if (this.node.matterServer) {
+        try { await this.node.matterServer.close(); } catch (e) {}
+      }
+
+      this.node.serverReady = false;
+      this.node.matterServer = null;
+      this.node.aggregator = null;
+
+      this.configureEnvironment();
+      const serverConfig = this.createServerConfig();
+
+      const matterServer = await ServerNode.create(
+        ServerNode.RootEndpoint.with(NetworkCommissioningServer.with("EthernetNetworkInterface")),
+        serverConfig
+      );
+
+      this.node.matterServer = matterServer;
+      this.node.aggregator = new Endpoint(AggregatorEndpoint, { id: "aggregator" });
+      this.node.matterServer.add(this.node.aggregator);
+
+      this.node.serverReady = true;
+      this.node.log("Bridge created");
+
+      // ? IMPORTANT: after recreate, force device nodes to rebuild endpoints
+      this.node.deviceManager.broadcastBridgeReset({ reason: "serverCreated" });
+
+      if (this.node.deviceManager.pendingUsers.length === 0) {
+        await this.start();
+      }
+    } catch (err) {
+      this.node.error("Failed to create Matter server: " + err.message);
+    } finally {
+      this._createInProgress = false;
+    }
+  }
+
+  configureEnvironment() {
+    const cfg = this.node.bridgeConfig;
+
+    if (cfg.networkInterface) {
+      Environment.default.vars.set("mdns.networkInterface", cfg.networkInterface);
+    }
+
+    const storageLoc = this._ensureStorageLocation();
+    const storageService = Environment.default.get(StorageService);
+    storageService.location = storageLoc;
+    Environment.default.set(StorageService, storageService);
+    this.node.log(`Using storage: ${storageService.location}`);
+  }
+
+  createServerConfig() {
+    const cfg = this.node.bridgeConfig;
+    const networkId = new Uint8Array(32);
+    const deviceId = getMatterDeviceId(this.node.id);
+
+    return {
+      id: this.node.id,
+      network: { port: cfg.port },
+      commissioning: { passcode: cfg.passcode, discriminator: cfg.discriminator },
+      productDescription: { name: cfg.name, deviceType: AggregatorEndpoint.deviceType },
+      basicInformation: {
+        vendorName: cfg.vendorName,
+        vendorId: VendorId(cfg.vendorId),
+        nodeLabel: cfg.name,
+        productName: cfg.productName,
+        productLabel: cfg.name,
+        productId: cfg.productId,
+        serialNumber: deviceId,
+        uniqueId: getMatterUniqueId(this.node.id),
+        hardwareVersion: 1,
+        softwareVersion: 1
+      },
+      networkCommissioning: {
+        maxNetworks: 1,
+        interfaceEnabled: true,
+        lastConnectErrorValue: 0,
+        lastNetworkId: networkId,
+        lastNetworkingStatus: NetworkCommissioning.NetworkCommissioningStatus.Success,
+        networks: [{ networkId, connected: true }]
+      }
+    };
+  }
+
+  async start() {
+    if (!this.node.serverReady || !this.node.matterServer) return;
+
+    if (this.node.matterServer.lifecycle?.isOnline) {
+      this.updateNodeStatus();
+      this.node.deviceManager.notifyDevicesReady();
+      return;
+    }
+
+    this.node.log("Starting Matter server...");
+    try {
+      await this.node.matterServer.start();
+      this.node.log("Matter server started");
+
+      this.updateNodeStatus();
+
+      // ? IMPORTANT: after start, force device nodes to rebuild endpoints (helps Alexa)
+      this.node.deviceManager.broadcastBridgeReset({ reason: "serverStarted" });
+
+      this.node.deviceManager.notifyDevicesReady();
+    } catch (err) {
+      this.node.error("Failed to start server: " + err.message);
+    }
+  }
+
+  // ? Broadcast refresh when we newly observe commissioned=true
+  updateNodeStatus() {
+    if (!this.node.matterServer) return;
+
+    const commissioned = !!this.node.matterServer.lifecycle?.isCommissioned;
+
+    if (commissioned && this.node._lastCommissioned !== true) {
+      this.node.log("Commissioned -> auto-refreshing bridged devices");
+      this.node.deviceManager.broadcastBridgeReset({ reason: "commissioned" });
+    }
+    this.node._lastCommissioned = commissioned;
+
+    if (!commissioned) {
+      const pairingData = this.node.matterServer.state.commissioning.pairingCodes;
+      this.node.status({ fill: "blue", shape: "dot", text: `QR: ${pairingData.manualPairingCode}` });
+      this.node.qrCode = pairingData.qrPairingCode;
+      this.node.manualCode = pairingData.manualPairingCode;
+    } else {
+      this.node.status({ fill: "green", shape: "dot", text: "commissioned" });
+    }
+  }
+}
+
+// ============================================================================
+// ERROR HANDLER
+// ============================================================================
+
+class ErrorHandler {
+  constructor(node) {
+    this.node = node;
+    this.handler = this.handleUnhandledRejection.bind(this);
+    process.on("unhandledRejection", this.handler);
+  }
+
+  handleUnhandledRejection(reason) {
+    if (!reason?.message?.includes("Behaviors have errors")) return;
+    this.node.error(`Matter.js initialization error: ${reason.message}`);
+  }
+
+  cleanup() {
+    process.removeListener("unhandledRejection", this.handler);
+  }
+}
+
+// ============================================================================
+// HTTP API HANDLER
+// ============================================================================
+
+class HttpApiHandler {
+  static setupEndpoints(RED) {
+    RED.httpAdmin.get("/_matterbridge/qrcode/:id",
+      RED.auth.needsPermission("admin.write"),
+      this.getQrCode.bind(this, RED)
+    );
+
+    RED.httpAdmin.get("/_matterbridge/commissioning/:id",
+      RED.auth.needsPermission("admin.write"),
+      this.getCommissioningInfo.bind(this, RED)
+    );
+
+    RED.httpAdmin.get("/_matterbridge/interfaces",
+      RED.auth.needsPermission("admin.write"),
+      this.getNetworkInterfaces.bind(this)
+    );
+  }
+
+  static async getQrCode(RED, req, res) {
+    const targetNode = RED.nodes.getNode(req.params.id);
+    if (!targetNode) return res.json({ error: "Bridge not found" });
+
+    try {
+      const data = await this.getQrCodeData(targetNode);
+      res.json(data);
+    } catch (err) {
+      res.json({ error: err.message });
+    }
+  }
+
+  static async getCommissioningInfo(RED, req, res) {
+    const targetNode = RED.nodes.getNode(req.params.id);
+    if (!targetNode?.matterServer) return res.sendStatus(404);
+
+    if (!targetNode.matterServer.lifecycle.isCommissioned) {
+      const pairingData = targetNode.matterServer.state.commissioning.pairingCodes;
+      res.json({
+        state: "ready",
+        qrPairingCode: pairingData.qrPairingCode,
+        manualPairingCode: pairingData.manualPairingCode
+      });
+    } else {
+      res.json({ state: "commissioned" });
+    }
+  }
+
+  static getNetworkInterfaces(req, res) {
+    const interfaces = os.networkInterfaces();
+    const output = [];
+    for (const iface in interfaces) {
+      for (const addr of interfaces[iface]) {
+        if (!addr.internal && addr.family === "IPv6") {
+          output.push(iface);
+          break;
+        }
+      }
+    }
+    res.json([...new Set(output)]);
+  }
+
+  static async getQrCodeData(node) {
+    if (node.qrCode) {
+      return { qrCode: node.qrCode, manualCode: node.manualCode, commissioned: node.matterServer?.lifecycle?.isCommissioned };
+    }
+
+    if (node.matterServer && !node.matterServer.lifecycle.isCommissioned) {
+      const pairingData = node.matterServer.state.commissioning.pairingCodes;
+      return { qrCode: pairingData.qrPairingCode, manualCode: pairingData.manualPairingCode, commissioned: false };
+    }
+
+    return { commissioned: true };
+  }
+}
+
+// ============================================================================
+// MAIN NODE
+// ============================================================================
+
+module.exports = function (RED) {
+  function MatterDynamicBridge(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.bridgeConfig = new BridgeConfig(config);
+    BridgeConfig.setLogLevel(node.bridgeConfig.logLevel);
+
+    node.deviceManager = new DeviceManager(node);
+    node.serverManager = new ServerManager(node, RED);
+    node.errorHandler = new ErrorHandler(node);
+
+    node.serverReady = false;
+    node.users = node.deviceManager.pendingUsers;
+    node.registered = node.deviceManager.registered;
+    node.registerChild = node.deviceManager.registerChild.bind(node.deviceManager);
+
+    node._lastCommissioned = null;
+
+    node.serverManager.create();
+
+    // poll commissioning state
+    node._commissionPoll = setInterval(() => {
+      try {
+        if (node.matterServer) node.serverManager.updateNodeStatus();
+      } catch (e) {}
+    }, 2000);
+
+    this.on("close", async function (removed, done) {
+      node.errorHandler.cleanup();
+
+      if (node._commissionPoll) {
+        clearInterval(node._commissionPoll);
+        node._commissionPoll = null;
+      }
+
+      if (node.matterServer) {
+        try { await node.matterServer.close(); } catch (e) {}
+      }
+
+      done();
+    });
+  }
+
+  RED.nodes.registerType("matter-dynamic-bridge", MatterDynamicBridge);
+  HttpApiHandler.setupEndpoints(RED);
+};

package/matter-device.html

@@ -0,0 +1,138 @@
+<script type="text/javascript">
+    RED.nodes.registerType('matter-device', {
+        category: 'Matter',
+        color: '#ffffff',
+        defaults: {
+            name: {value: ""},
+            bridge: {type: "matter-dynamic-bridge", required: true},
+            autoConfirm: {value: false},
+            deviceConfig: {value: "{\n  \"deviceType\": \"OnOffLightDevice\"\n}", validate: function(v) {
+                try {
+                    JSON.parse(v);
+                    return true;
+                } catch(e) {
+                    return false;
+                }
+            }}
+        },
+        inputs: 1,
+        outputs: 3,
+        outputLabels: ["events", "commands", "debug"],
+        icon: "icons/matter-device-icon.svg",
+        label: function() {
+            return this.name || "Matter Device";
+        },
+        oneditprepare: function() {
+            // Create JSON editor
+            this.configEditor = RED.editor.createEditor({
+                id: 'node-input-deviceConfig-editor',
+                mode: 'ace/mode/json',
+                value: this.deviceConfig
+            });
+        },
+        oneditsave: function() {
+            this.deviceConfig = this.configEditor.getValue();
+            this.configEditor.destroy();
+            delete this.configEditor;
+        },
+        oneditcancel: function() {
+            this.configEditor.destroy();
+            delete this.configEditor;
+        }
+    });
+</script>
+
+<script type="text/x-red" data-template-name="matter-device">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-bridge"><i class="fa fa-server"></i> Bridge</label>
+        <input type="text" id="node-input-bridge">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-autoConfirm"><i class="fa fa-check-circle"></i> Auto Confirm</label>
+        <input type="checkbox" id="node-input-autoConfirm" style="display: inline-block; width: auto; vertical-align: top;">
+        <span style="margin-left: 10px; color: #999;">Automatically confirm command execution</span>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-deviceConfig"><i class="fa fa-code"></i> Config</label>
+        <div style="height: 250px; min-height:150px;" class="node-text-editor" id="node-input-deviceConfig-editor"></div>
+    </div>
+
+    <div class="form-tips">
+        Output 1 = events � Output 2 = commands � Output 3 = debug/diag
+    </div>
+</script>
+
+<script type="text/x-red" data-help-name="matter-device">
+    <p>Matter device node that can be configured via JSON.</p>
+
+    <h3>Configuration</h3>
+    <dl class="message-properties">
+        <dt>deviceType <span class="property-type">string</span></dt>
+        <dd>The Matter device type (e.g., "OnOffLightDevice", "ThermostatDevice")</dd>
+    </dl>
+
+    <h3>Inputs</h3>
+    <p>The payload must match Matter.js cluster structure exactly:</p>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd>Device state in Matter format. Examples:
+            <ul>
+                <li>OnOff Light: <code>{onOff: {onOff: true}}</code></li>
+                <li>Temperature: <code>{temperatureMeasurement: {measuredValue: 2000}}</code> (20�C * 100)</li>
+                <li>Thermostat: <code>{thermostat: {occupiedHeatingSetpoint: 2100}}</code></li>
+            </ul>
+        </dd>
+
+        <dt>topic <span class="property-type">string</span></dt>
+        <dd>Set to "state" to query current device state</dd>
+    </dl>
+
+    <h3>Outputs</h3>
+
+    <p><b>Output 1: State changes (events)</b></p>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd>State changes in same format as input</dd>
+        <dt>eventSource <span class="property-type">object</span></dt>
+        <dd>Source of the state change (local or network)</dd>
+    </dl>
+
+    <p><b>Output 2: Commands</b></p>
+    <dl class="message-properties">
+        <dt>payload.command <span class="property-type">string</span></dt>
+        <dd>Command name (e.g., "on", "off", "toggle")</dd>
+        <dt>payload.cluster <span class="property-type">string</span></dt>
+        <dd>Cluster name (e.g., "OnOff")</dd>
+        <dt>payload.data <span class="property-type">object</span></dt>
+        <dd>Command parameters</dd>
+    </dl>
+
+    <p><b>Output 3: Debug / Diagnostics</b></p>
+    <dl class="message-properties">
+        <dt>payload.type <span class="property-type">string</span></dt>
+        <dd>Diagnostic message type (e.g., <code>subscribe_start</code>, <code>event</code>, <code>write_attempt</code>, <code>write_error</code>, <code>bridgeReset</code>)</dd>
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd>Extra details depending on the type</dd>
+    </dl>
+
+    <h3>Auto Confirm</h3>
+    <p>When enabled, commands are automatically confirmed, preventing timeout issues with HomeKit/Alexa.
+    When disabled, you must manually send the state back to the input after executing the command on the real device.</p>
+
+    <h3>Examples</h3>
+    <p><b>Turn on a light:</b><br>
+    <code>msg.payload = {onOff: {onOff: true}}</code></p>
+
+    <p><b>Set temperature sensor:</b><br>
+    <code>msg.payload = {temperatureMeasurement: {measuredValue: 2150}}</code> // 21.5�C</p>
+
+    <p><b>Query device state:</b><br>
+    <code>msg.topic = "state"</code></p>
+</script>