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

package/matter-pairing.html

@@ -0,0 +1,54 @@
+cat > /home/airnexus/.node-red/node-red-contrib-matter-airnexus/matter-pairing.html <<'HTML'
+<script type="text/javascript">
+RED.nodes.registerType('matter-pairing', {
+    category: 'Matter',
+    color: '#7bbcff',
+    defaults: {
+        name: { value: "" },
+        bridge: { value: "", type: "matter-dynamic-bridge", required: true },
+        timeoutMins: { value: 15, validate: RED.validators.number() },
+        includeSvg: { value: true }
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "font-awesome/fa-qrcode",
+    label: function() { return this.name || "matter-pairing"; }
+});
+</script>
+
+<script type="text/html" data-template-name="matter-pairing">
+    <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="matter-pairing">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-bridge"><i class="fa fa-sitemap"></i> Bridge</label>
+        <input type="text" id="node-input-bridge">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-timeoutMins"><i class="fa fa-clock-o"></i> Pairing timeout (mins)</label>
+        <input type="number" id="node-input-timeoutMins" min="0" step="1" style="width:120px;">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-includeSvg"><i class="fa fa-qrcode"></i> Include QR SVG</label>
+        <input type="checkbox" id="node-input-includeSvg" style="width:auto;">
+    </div>
+
+    <div class="form-tips">
+        <b>Commands</b><br/>
+        <code>get</code> ? output current pairing info<br/>
+        <code>pair</code> ? enable pairing mode (best-effort)<br/>
+        <code>reset</code>/<code>unpair</code>/<code>delete</code> ? factory reset bridge commissioning + new codes<br/>
+        <code>disable</code> ? best-effort stop advertising (offline)<br/><br/>
+        Optional payload: <code>{timeoutMins:15, includeSvg:true, forceReset:true}</code>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="matter-pairing">
+    <p>Outputs Matter commissioning info (manual pairing code + QR pairing string) and can reset commissioning to re-enter pairing mode.</p>
+    <p><b>Input commands</b>: <code>get</code>, <code>pair</code>, <code>reset</code>/<code>unpair</code>/<code>delete</code>, <code>disable</code></p>
+</script>
+HTML

package/matter-pairing.js

@@ -0,0 +1,275 @@
+/**
+ * matter-pairing.js (robust)
+ *
+ * Key improvement:
+ * ? After factory reset / recreate, broadcast bridgeReset so device nodes rebuild endpoints.
+ */
+
+module.exports = function (RED) {
+  const fs = require("fs");
+  const path = require("path");
+  let QRCode = null;
+  try { QRCode = require("qrcode"); } catch (e) {}
+
+  const INVALID_PASSCODES = new Set([
+    11111111, 22222222, 33333333, 44444444, 55555555,
+    66666666, 77777777, 88888888, 12345678, 87654321
+  ]);
+
+  function nowMs() { return Date.now(); }
+
+  function generatePasscode() {
+    let passcode = Math.floor(Math.random() * 99999997) + 1;
+    if (INVALID_PASSCODES.has(passcode)) passcode += 1;
+    return +passcode.toString().padStart(8, "0");
+  }
+
+  function generateDiscriminator() {
+    return Math.floor(Math.random() * 4095);
+  }
+
+  function isObject(x) { return x && typeof x === "object" && !Array.isArray(x); }
+
+  function parseAction(msg) {
+    const t = (msg.topic || "").toString().trim().toLowerCase();
+    if (t) return t;
+
+    const p = msg.payload;
+    if (typeof p === "string") return p.trim().toLowerCase();
+    if (isObject(p)) return String(p.action || p.command || "").trim().toLowerCase() || "get";
+    return "get";
+  }
+
+  function getTimeoutMins(node, msg) {
+    const p = msg.payload;
+    const v = isObject(p) && p.timeoutMins != null ? Number(p.timeoutMins) : Number(node.timeoutMins);
+    if (!Number.isFinite(v) || v < 0) return 15;
+    return v;
+  }
+
+  function getIncludeSvg(node, msg) {
+    const p = msg.payload;
+    if (isObject(p) && p.includeSvg != null) return !!p.includeSvg;
+    return !!node.includeSvg;
+  }
+
+  function ensureBridgeStorageLocation(bridge) {
+    if (bridge?.bridgeConfig?.storageLocation) return bridge.bridgeConfig.storageLocation;
+    const userDir = (RED.settings && RED.settings.userDir) ? RED.settings.userDir : process.cwd();
+    const loc = path.join(userDir, "matter-storage", String(bridge.id));
+    bridge.bridgeConfig = bridge.bridgeConfig || {};
+    bridge.bridgeConfig.storageLocation = loc;
+    return loc;
+  }
+
+  function rmrf(p) { try { fs.rmSync(p, { recursive: true, force: true }); } catch (e) {} }
+  function mkdirp(p) { try { fs.mkdirSync(p, { recursive: true }); } catch (e) {} }
+
+  async function bestEffortBringOffline(bridge) {
+    const ms = bridge?.matterServer;
+    if (!ms) return;
+    try { if (ms.lifecycle && typeof ms.lifecycle.bringOffline === "function") { await ms.lifecycle.bringOffline(); return; } } catch (e) {}
+    try { if (typeof ms.stop === "function") { await ms.stop(); return; } } catch (e) {}
+    try { if (typeof ms.close === "function") { await ms.close(); } } catch (e) {}
+  }
+
+  async function recreateServer(bridge) {
+    if (!bridge?.serverManager || typeof bridge.serverManager.create !== "function") {
+      throw new Error("Bridge does not expose serverManager.create()");
+    }
+    await bridge.serverManager.create();
+  }
+
+  async function startServerIfPossible(bridge) {
+    if (bridge?.serverManager && typeof bridge.serverManager.start === "function") {
+      await bridge.serverManager.start();
+    }
+  }
+
+  async function getPairingInfo(bridge, includeSvg) {
+    if (!bridge?.matterServer) return { state: "not_ready", commissioned: false };
+
+    const commissioned = !!bridge.matterServer.lifecycle?.isCommissioned;
+    if (commissioned) return { state: "commissioned", commissioned: true };
+
+    const pairingCodes = bridge.matterServer.state?.commissioning?.pairingCodes;
+    if (!pairingCodes) return { state: "no_pairing_codes", commissioned: false };
+
+    const out = {
+      state: "ready",
+      commissioned: false,
+      qrPairingCode: pairingCodes.qrPairingCode,
+      manualPairingCode: pairingCodes.manualPairingCode
+    };
+
+    if (includeSvg && QRCode) {
+      try {
+        out.qrSvg = await QRCode.toString(pairingCodes.qrPairingCode, { type: "svg", width: 200, margin: 1 });
+      } catch (e) {}
+    }
+    return out;
+  }
+
+  async function factoryResetBridge(bridge) {
+    await bestEffortBringOffline(bridge);
+
+    const storageLoc = ensureBridgeStorageLocation(bridge);
+    rmrf(storageLoc);
+    mkdirp(storageLoc);
+
+    if (bridge.bridgeConfig) {
+      bridge.bridgeConfig.passcode = generatePasscode();
+      bridge.bridgeConfig.discriminator = generateDiscriminator();
+    }
+
+    bridge.serverReady = false;
+    bridge.aggregator = null;
+    bridge.matterServer = null;
+
+    await recreateServer(bridge);
+    await startServerIfPossible(bridge);
+
+    // ? IMPORTANT: after reset, force devices to rebuild endpoints
+    if (bridge.deviceManager?.broadcastBridgeReset) {
+      bridge.deviceManager.broadcastBridgeReset({ reason: "factoryReset" });
+    }
+
+    return storageLoc;
+  }
+
+  function MatterPairingNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.name = config.name;
+    node.bridge = RED.nodes.getNode(config.bridge);
+
+    node.timeoutMins = Number(config.timeoutMins || 15);
+    node.includeSvg = config.includeSvg === true || /^true$/i.test(String(config.includeSvg));
+
+    node._pairingEnabled = false;
+    node._pairingUntil = 0;
+    let pairingTimer = null;
+
+    function setStatus(text, fill = "blue", shape = "dot") {
+      node.status({ fill, shape, text });
+    }
+
+    function clearTimer() {
+      if (pairingTimer) { clearTimeout(pairingTimer); pairingTimer = null; }
+    }
+
+    async function outputInfo(extra = {}, includeSvgOverride = null) {
+      const bridge = node.bridge;
+      const includeSvg = includeSvgOverride == null ? !!node.includeSvg : !!includeSvgOverride;
+      const info = await getPairingInfo(bridge, includeSvg);
+
+      node.send({
+        payload: {
+          bridgeId: bridge?.id,
+          pairingEnabled: node._pairingEnabled,
+          pairingUntil: node._pairingUntil ? new Date(node._pairingUntil).toISOString() : null,
+          ...info,
+          ...extra
+        }
+      });
+
+      if (info.state === "commissioned") setStatus("commissioned", "green");
+      else if (info.state === "ready") setStatus(`pairing: ${info.manualPairingCode}`, "blue");
+      else if (info.state === "not_ready") setStatus("bridge not ready", "yellow");
+      else setStatus(info.state, "yellow");
+    }
+
+    async function enablePairingFor(timeoutMins) {
+      clearTimer();
+      node._pairingEnabled = true;
+
+      if (timeoutMins > 0) {
+        node._pairingUntil = nowMs() + timeoutMins * 60 * 1000;
+        pairingTimer = setTimeout(async () => {
+          node._pairingEnabled = false;
+          node._pairingUntil = 0;
+          try { await bestEffortBringOffline(node.bridge); } catch (e) {}
+          setStatus("pairing disabled", "grey");
+        }, timeoutMins * 60 * 1000);
+      } else {
+        node._pairingUntil = 0;
+      }
+    }
+
+    this.on("input", async function (msg) {
+      const action = parseAction(msg);
+      const bridge = node.bridge;
+
+      if (!bridge) {
+        setStatus("no bridge", "red", "ring");
+        node.send({ payload: { error: "Bridge not configured" } });
+        return;
+      }
+
+      const timeoutMins = getTimeoutMins(node, msg);
+      const includeSvg = getIncludeSvg(node, msg);
+      const p = msg.payload;
+      const forceReset = isObject(p) ? !!p.forceReset : false;
+
+      try {
+        if (action === "get") {
+          await outputInfo({}, includeSvg);
+          return;
+        }
+
+        if (action === "pair" || action === "pairing" || action === "enable") {
+          if (bridge?.matterServer?.lifecycle?.isCommissioned && !forceReset) {
+            await outputInfo({ warning: "Bridge is commissioned. Use {forceReset:true} or 'reset' to re-enter pairing." }, includeSvg);
+            return;
+          }
+
+          if (bridge?.matterServer?.lifecycle?.isCommissioned && forceReset) {
+            const storageLoc = await factoryResetBridge(bridge);
+            await enablePairingFor(timeoutMins);
+            await outputInfo({ reset: true, storageLocation: storageLoc }, includeSvg);
+            return;
+          }
+
+          await startServerIfPossible(bridge);
+          await enablePairingFor(timeoutMins);
+          await outputInfo({}, includeSvg);
+          return;
+        }
+
+        if (action === "reset" || action === "unpair" || action === "delete") {
+          const storageLoc = await factoryResetBridge(bridge);
+          await enablePairingFor(timeoutMins);
+          await outputInfo({ reset: true, storageLocation: storageLoc }, includeSvg);
+          return;
+        }
+
+        if (action === "disable") {
+          clearTimer();
+          node._pairingEnabled = false;
+          node._pairingUntil = 0;
+          await bestEffortBringOffline(bridge);
+          setStatus("pairing disabled", "grey");
+          await outputInfo({}, includeSvg);
+          return;
+        }
+
+        await outputInfo({ warning: `Unknown action '${action}'. Use get/pair/reset/disable.` }, includeSvg);
+      } catch (err) {
+        setStatus("error", "red", "ring");
+        node.send({ payload: { error: err.message } });
+      }
+    });
+
+    this.on("close", function (removed, done) {
+      clearTimer();
+      node._pairingEnabled = false;
+      node._pairingUntil = 0;
+      done();
+    });
+
+    setStatus("ready", "green");
+  }
+
+  RED.nodes.registerType("matter-pairing", MatterPairingNode);
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@airnexus/node-red-contrib-matter-airnexus",
+  "version": "0.2.4-airnexus.1",
+  "description": "AirNexus Matter bridge + dynamic devices + pairing management for Node-RED",
+  "main": "matter-bridge.js",
+  "keywords": [
+    "node-red",
+    "node-red-contrib",
+    "airnexus",
+    "matter",
+    "matter-js",
+    "iot",
+    "smart-home",
+    "homekit",
+    "google-home",
+    "alexa",
+    "dynamic",
+    "bridge",
+    "pairing",
+    "commissioning"
+  ],
+  "author": "AirNexus",
+  "license": "MIT",
+  "dependencies": {
+    "@matter/main": "^0.13.0",
+    "qrcode": "^1.5.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "node-red": {
+    "version": ">=3.0.0",
+    "nodes": {
+      "matter-dynamic-bridge": "matter-bridge.js",
+      "matter-device": "matter-device.js",
+      "matter-pairing": "matter-pairing.js"
+    }
+  }
+}
+
+

package/utils.js

@@ -0,0 +1,30 @@
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Get Matter-compatible device ID from Node-RED node ID
+ * Removes hyphens from the node ID to create a valid Matter device identifier
+ *
+ * @param {string} nodeId - Node-RED node ID (e.g., "a1b2-c3d4-e5f6")
+ * @returns {string} Matter device ID (e.g., "a1b2c3d4e5f6")
+ */
+function getMatterDeviceId(nodeId) {
+    return nodeId.replace(/-/g, '');
+}
+
+/**
+ * Get Matter-compatible unique ID from Node-RED node ID
+ * Creates a reversed version of the device ID for uniqueness
+ *
+ * @param {string} nodeId - Node-RED node ID (e.g., "a1b2-c3d4-e5f6")
+ * @returns {string} Matter unique ID (reversed device ID, e.g., "6f5e4d3c2b1a")
+ */
+function getMatterUniqueId(nodeId) {
+    return getMatterDeviceId(nodeId).split("").reverse().join("");
+}
+
+module.exports = {
+    getMatterDeviceId,
+    getMatterUniqueId
+};