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

package/matter-device.js

@@ -0,0 +1,880 @@
+/**
+ * matter-device.js (OPTION 2 + PERSIST ENABLE/NAME + rich status)
+ *
+ * Output 1: events/state (attribute $Changed + thermostat diffs on interactionEnd)
+ * Output 2: commands (real Matter cluster commands) + optional pseudo-commands for attribute writes
+ * Output 3: debug/diagnostics
+ *
+ * OPTION 2:
+ * - Device is NOT registered to bridge/aggregator until enabled.
+ * - Once enabled, it registers and appears in Alexa.
+ * - Disabling sets reachable=false and suppresses outputs (does not unpublish).
+ *
+ * PERSISTENCE:
+ * - Persists enabled + name to node context so it survives Node-RED redeploy/restart.
+ * - On boot, if persisted enabled=true, auto-registers and becomes reachable.
+ *
+ * Status:
+ * - Disabled: grey ring "disabled (not registered)" or "disabled"
+ * - Enabled: green dot "Name | mode:X | H:xx.x C:xx.x | T:xx.x | last:<source>"
+ */
+
+const { Endpoint } = require("@matter/main");
+const matterBehaviors = require("@matter/main/behaviors");
+const { getMatterDeviceId, getMatterUniqueId } = require("./utils");
+
+// ============================================================================
+// BEHAVIOR PATCHING (Output 2 commands + Output 3 debug)
+// ============================================================================
+
+let behaviorsPatched = false;
+
+function patchBehaviors() {
+  if (behaviorsPatched) return;
+
+  Object.values(matterBehaviors).forEach((BehaviorClass) => {
+    if (!BehaviorClass?.cluster?.commands || typeof BehaviorClass !== "function") return;
+
+    Object.entries(BehaviorClass.cluster.commands).forEach(([cmd, def]) => {
+      const originalMethod = BehaviorClass.prototype[cmd];
+
+      BehaviorClass.prototype[cmd] = async function (request) {
+        const node = this.endpoint?.nodeRed;
+        if (node && !node._closed) {
+          const clusterName = BehaviorClass.cluster?.name || BehaviorClass.name || "unknown";
+          const payload = { command: cmd, cluster: clusterName, data: request };
+
+          try {
+            if (!node._enabled) {
+              node._dbg({ type: "command_rx_ignored_disabled", payload });
+            } else {
+              node.send([null, { payload }, null]);
+              node._dbg({ type: "command_rx", payload });
+            }
+          } catch (e) {}
+        }
+
+        if (originalMethod && !originalMethod.toString().includes("unimplemented")) {
+          return await originalMethod.call(this, request);
+        }
+
+        if (!def.responseSchema || def.responseSchema.name === "TlvNoResponse") return;
+        return { status: 0 };
+      };
+    });
+  });
+
+  behaviorsPatched = true;
+}
+
+patchBehaviors();
+
+// Load devices AFTER patching
+const matterDevices = require("@matter/main/devices");
+const { BridgedDeviceBasicInformationServer, IdentifyServer } = matterBehaviors;
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function isObject(x) {
+  return x && typeof x === "object" && !Array.isArray(x);
+}
+
+function c01_to_c(v) {
+  if (typeof v !== "number" || !Number.isFinite(v)) return null;
+  return Math.round(v) / 100;
+}
+
+const SYSTEM_MODE_LABEL = {
+  0: "off",
+  1: "auto",
+  3: "cool",
+  4: "heat",
+  5: "emHeat",
+  6: "preCool",
+  7: "fan",
+  8: "dry",
+  9: "sleep"
+};
+
+function formatThermoStatus(t) {
+  if (!t) return "";
+  const mode = (t.systemMode != null)
+    ? `${t.systemMode}${SYSTEM_MODE_LABEL[t.systemMode] ? ":" + SYSTEM_MODE_LABEL[t.systemMode] : ""}`
+    : "-";
+  const h = c01_to_c(t.occupiedHeatingSetpoint);
+  const c = c01_to_c(t.occupiedCoolingSetpoint);
+  const lt = c01_to_c(t.localTemperature);
+
+  const parts = [];
+  parts.push(`mode:${mode}`);
+  if (h != null) parts.push(`H:${h.toFixed(1)}`);
+  if (c != null) parts.push(`C:${c.toFixed(1)}`);
+  if (lt != null) parts.push(`T:${lt.toFixed(1)}`);
+
+  return parts.join(" ");
+}
+
+function cloneState(obj) {
+  if (!isObject(obj)) return obj;
+  try { return JSON.parse(JSON.stringify(obj)); } catch (e) { return { ...obj }; }
+}
+
+function diffObjects(prev, curr) {
+  if (!isObject(curr)) return null;
+  const out = {};
+  let changed = false;
+
+  const prevObj = isObject(prev) ? prev : {};
+
+  for (const k of Object.keys(curr)) {
+    const a = curr[k];
+    const b = prevObj[k];
+
+    const same = (typeof a === "object")
+      ? JSON.stringify(a) === JSON.stringify(b)
+      : a === b;
+
+    if (!same) { out[k] = a; changed = true; }
+  }
+
+  for (const k of Object.keys(prevObj)) {
+    if (!(k in curr)) { out[k] = null; changed = true; }
+  }
+
+  return changed ? out : null;
+}
+
+// ============================================================================
+// CUSTOM BEHAVIORS
+// ============================================================================
+
+class DynamicIdentifyServer extends IdentifyServer {
+  async triggerEffect(identifier, variant) {}
+}
+
+// ============================================================================
+// DEVICE FACTORY
+// ============================================================================
+
+class DeviceFactory {
+  static createBehaviorsWithFeatures(behaviors, behaviorFeatures = {}) {
+    return behaviors
+      .map((behavior) => {
+        if (typeof behavior === "string") {
+          const BehaviorClass = matterBehaviors[behavior];
+          if (!BehaviorClass) return null;
+
+          const clusterName = behavior.replace("Server", "");
+          if (behaviorFeatures[clusterName]) {
+            const clusters = require("@matter/main/clusters");
+            const cluster = clusters[clusterName];
+            const features = behaviorFeatures[clusterName]
+              .map((fname) => cluster?.Feature?.[fname])
+              .filter(Boolean);
+
+            if (features.length > 0) return BehaviorClass.with(...features);
+          }
+          return BehaviorClass;
+        }
+        return behavior;
+      })
+      .filter(Boolean);
+  }
+
+  static getMandatoryBehaviors(DeviceClass, behaviorFeatures = {}) {
+    const behaviors = [];
+
+    if (DeviceClass.requirements?.server?.mandatory) {
+      Object.entries(DeviceClass.requirements.server.mandatory).forEach(([key, BehaviorClass]) => {
+        if (!BehaviorClass) return;
+
+        const behaviorName = key.replace("Server", "");
+        if (behaviorFeatures[behaviorName]) {
+          const clusters = require("@matter/main/clusters");
+          const cluster = clusters[behaviorName];
+          const features = behaviorFeatures[behaviorName]
+            .map((fname) => cluster?.Feature?.[fname])
+            .filter(Boolean);
+
+          if (features.length > 0) behaviors.push(BehaviorClass.with(...features));
+          else behaviors.push(BehaviorClass);
+        } else {
+          behaviors.push(BehaviorClass);
+        }
+      });
+    }
+
+    return behaviors;
+  }
+
+  static createEndpoint(node, DeviceClass, behaviors, deviceConfig) {
+    const deviceId = getMatterDeviceId(node.id);
+
+    // Start reachable=false because we are hidden until enabled
+    const endpointConfig = {
+      id: deviceId,
+      bridgedDeviceBasicInformation: {
+        nodeLabel: node.name,
+        productName: node.name,
+        productLabel: node.name,
+        serialNumber: deviceId,
+        uniqueId: getMatterUniqueId(node.id),
+        reachable: false
+      }
+    };
+
+    if (deviceConfig.initialState) Object.assign(endpointConfig, deviceConfig.initialState);
+
+    const endpoint = new Endpoint(DeviceClass.with(...behaviors), endpointConfig);
+    endpoint.nodeRed = node;
+    return endpoint;
+  }
+
+  static createDevice(node, deviceConfig) {
+    const DeviceClass = matterDevices[deviceConfig.deviceType];
+    if (!DeviceClass) throw new Error(`Device type '${deviceConfig.deviceType}' not found`);
+
+    const behaviors = this.getMandatoryBehaviors(DeviceClass, deviceConfig.behaviorFeatures);
+    behaviors.push(BridgedDeviceBasicInformationServer, DynamicIdentifyServer);
+
+    if (deviceConfig.additionalBehaviors) {
+      const additionalBehaviors = this.createBehaviorsWithFeatures(
+        deviceConfig.additionalBehaviors,
+        deviceConfig.behaviorFeatures
+      );
+      behaviors.push(...additionalBehaviors);
+    }
+
+    return this.createEndpoint(node, DeviceClass, behaviors, deviceConfig);
+  }
+}
+
+// ============================================================================
+// EVENT MANAGER
+// ============================================================================
+
+class EventManager {
+  constructor(node) {
+    this.node = node;
+    this.eventsSubscribed = false;
+    this.eventHandlers = {};
+    this.lastClusterState = {};
+  }
+
+  subscribe() {
+    if (this.eventsSubscribed) return;
+    if (!this.node.device?.events) throw new Error("Device events not available");
+    if (!this.node.device?.state) throw new Error("Device state not available");
+
+    void Object.keys(this.node.device.state);
+
+    this.eventsSubscribed = true;
+
+    const clusters = Object.keys(this.node.device.events);
+    this.node._dbg({ type: "subscribe_start", clusters });
+
+    clusters.forEach((clusterName) => this.subscribeCluster(clusterName));
+    this.node._dbg({ type: "subscribe_done" });
+  }
+
+  subscribeCluster(clusterName) {
+    const clusterEvents = this.node.device.events[clusterName];
+    if (!clusterEvents) return;
+
+    Object.keys(clusterEvents)
+      .filter((eventName) => eventName.endsWith("$Changed"))
+      .forEach((eventName) => {
+        const ev = clusterEvents[eventName];
+        if (!ev || typeof ev.on !== "function") return;
+
+        const attributeName = eventName.slice(0, -"$Changed".length);
+        const handlerKey = `${clusterName}.${eventName}`;
+        if (this.eventHandlers[handlerKey]) return;
+
+        this.eventHandlers[handlerKey] = (value) => {
+          const prev = this.lastClusterState[clusterName] || {};
+          this.lastClusterState[clusterName] = { ...prev, [attributeName]: value };
+
+          if (!this.node._enabled) {
+            this.node._dbg({ type: "event_ignored_disabled", clusterName, attributeName, value });
+            return;
+          }
+
+          const msg = { payload: { [clusterName]: { [attributeName]: value } } };
+          this.node.send([msg, null, null]);
+          this.node._dbg({ type: "event_changed", clusterName, attributeName, value });
+
+          if (clusterName === "thermostat") {
+            this.node._mergeThermostat({ [attributeName]: value }, "changed");
+          }
+        };
+
+        try {
+          ev.on(this.eventHandlers[handlerKey]);
+          this.node._dbg({ type: "subscribed", clusterName, eventName });
+        } catch (e) {
+          this.node._dbg({ type: "subscribe_error", clusterName, eventName, error: String(e?.message || e) });
+        }
+      });
+
+    if (this.node.snapshotOnInteractionEnd && clusterName === "thermostat" && clusterEvents.interactionEnd?.on) {
+      const handlerKey = `${clusterName}.interactionEnd`;
+      if (this.eventHandlers[handlerKey]) return;
+
+      this.eventHandlers[handlerKey] = () => {
+        const curr = this.node.device?.state?.[clusterName];
+        if (!isObject(curr)) return;
+
+        const prev = this.lastClusterState[clusterName] || {};
+        const diff = diffObjects(prev, curr);
+
+        this.lastClusterState[clusterName] = cloneState(curr);
+
+        if (!diff) {
+          this.node._dbg({ type: "interactionEnd_nochange" });
+          return;
+        }
+
+        if (!this.node._enabled) {
+          this.node._dbg({ type: "snapshot_ignored_disabled", diff });
+          return;
+        }
+
+        this.node.send([{ payload: { thermostat: diff } }, null, null]);
+        this.node._dbg({ type: "snapshot_diff", keys: Object.keys(diff) });
+
+        this.node._mergeThermostat(diff, "interactionEnd");
+
+        if (this.node.emitPseudoCommands) {
+          this.node.send([null, { payload: { command: "attributeWrite", cluster: "thermostat", data: diff } }, null]);
+          this.node._dbg({ type: "pseudo_command_emitted" });
+        }
+      };
+
+      try {
+        clusterEvents.interactionEnd.on(this.eventHandlers[handlerKey]);
+        this.node._dbg({ type: "subscribed", clusterName: "thermostat", eventName: "interactionEnd" });
+      } catch (e) {
+        this.node._dbg({ type: "subscribe_error", clusterName: "thermostat", eventName: "interactionEnd", error: String(e?.message || e) });
+      }
+    }
+  }
+
+  async cleanup() {
+    if (!this.node.device?.events) return;
+
+    for (const [handlerKey, handler] of Object.entries(this.eventHandlers)) {
+      const [clusterName, eventName] = handlerKey.split(".");
+      const ev = this.node.device.events?.[clusterName]?.[eventName];
+      if (ev?.off) {
+        try { await ev.off(handler); } catch (e) {}
+      }
+    }
+
+    this.eventsSubscribed = false;
+    this.eventHandlers = {};
+    this.lastClusterState = {};
+  }
+}
+
+// ============================================================================
+// MAIN NODE
+// ============================================================================
+
+module.exports = function (RED) {
+  function MatterDevice(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    const nodeCtx = node.context();
+
+    node.bridge = RED.nodes.getNode(config.bridge);
+    node.name = config.name;
+    node.type = "matter-device";
+
+    node.emitPseudoCommands = /^true$/i.test(String(config.emitPseudoCommands || "false"));
+    node.snapshotOnInteractionEnd = (config.snapshotOnInteractionEnd == null)
+      ? true
+      : /^true$/i.test(String(config.snapshotOnInteractionEnd));
+
+    node._closed = false;
+
+    // Persisted state
+    const persisted = nodeCtx.get("persist") || {};
+    node._enabled = persisted.enabled === true;               // persists
+    node._pendingName = (typeof persisted.name === "string" && persisted.name.trim() !== "")
+      ? persisted.name.trim()
+      : null;
+
+    // Option 2: must re-register after deploy (node instance is new)
+    node._registeredToBridge = false;
+
+    node._isThermostat = false;
+    node._lastThermo = {
+      systemMode: null,
+      occupiedHeatingSetpoint: null,
+      occupiedCoolingSetpoint: null,
+      localTemperature: null
+    };
+    node._lastThermoSource = "none";
+
+    // Debug helper -> Output 3
+    node._dbg = (payload) => {
+      if (node._closed) return;
+      try { node.send([null, null, { payload }]); } catch (e) {}
+    };
+
+    function savePersist() {
+      nodeCtx.set("persist", {
+        enabled: !!node._enabled,
+        name: node._pendingName || ""
+      });
+    }
+
+    // Status helper
+    node._updateStatus = () => {
+      if (node._closed) return;
+
+      if (!node._registeredToBridge) {
+        node.status({ fill: "grey", shape: "ring", text: node._enabled ? "enabling..." : "disabled (not registered)" });
+        return;
+      }
+
+      if (!node._enabled) {
+        node.status({ fill: "grey", shape: "ring", text: "disabled" });
+        return;
+      }
+
+      const displayName = (node._pendingName && node._pendingName.trim())
+        ? node._pendingName.trim()
+        : (node.name || "device");
+
+      let text = displayName;
+
+      if (node._isThermostat) {
+        const thermo = formatThermoStatus(node._lastThermo);
+        if (thermo) text += ` | ${thermo}`;
+        text += ` | last:${node._lastThermoSource}`;
+      }
+
+      node.status({ fill: "green", shape: "dot", text });
+    };
+
+    node._mergeThermostat = (partial, source) => {
+      if (!partial || !isObject(partial)) return;
+      for (const k of Object.keys(partial)) {
+        if (k in node._lastThermo) node._lastThermo[k] = partial[k];
+      }
+      node._lastThermoSource = source || "update";
+      node._updateStatus();
+    };
+
+    // Init promise
+    node.initPromise = new Promise((resolve, reject) => {
+      node.resolveInit = resolve;
+      node.rejectInit = (err) => { try { reject(err); } catch (e) {} };
+    });
+    node._initResolved = false;
+
+    // Parse deviceConfig JSON
+    let deviceConfig;
+    try {
+      deviceConfig = typeof config.deviceConfig === "string" ? JSON.parse(config.deviceConfig) : config.deviceConfig;
+    } catch (e) {
+      node.error("Invalid device configuration JSON: " + e.message);
+      node._dbg({ type: "config_error", error: e.message });
+      return;
+    }
+
+    node._isThermostat = String(deviceConfig?.deviceType || "").toLowerCase().includes("thermostat");
+    if (config.snapshotOnInteractionEnd == null) node.snapshotOnInteractionEnd = node._isThermostat;
+
+    // Create endpoint immediately (but may not register until enabled)
+    try {
+      // Apply persisted name into node.name before creating endpoint so it becomes the default label
+      if (node._pendingName) node.name = node._pendingName;
+
+      node.device = DeviceFactory.createDevice(node, deviceConfig);
+    } catch (e) {
+      node.error("Failed to create device endpoint: " + e.message);
+      node._dbg({ type: "create_error", error: e.message });
+      return;
+    }
+
+    const eventManager = new EventManager(node);
+
+    // pending write retry ONLY after real write attempt
+    let pendingWrite = null;
+    let pendingTimer = null;
+    let writeAttempts = 0;
+
+    const WRITE_RETRY_DELAY_MS = Number(config.writeRetryDelayMs || 750);
+    const MAX_WRITE_RETRIES = Number(config.maxWriteRetries || 40);
+
+    function stageNamePreRegister(newName) {
+      const n = String(newName || "").trim();
+      if (!n) return;
+
+      node._pendingName = n;
+      node.name = n;
+      savePersist();
+
+      try {
+        const bdi = node.device?.state?.bridgedDeviceBasicInformation;
+        if (bdi && typeof bdi === "object") {
+          bdi.nodeLabel = n;
+          bdi.productName = n;
+          bdi.productLabel = n;
+        }
+      } catch (e) {}
+
+      node._dbg({ type: "rename_staged_pre_register", name: n });
+      node._updateStatus();
+    }
+
+    async function applyNamePostRegister(newName) {
+      const n = String(newName || "").trim();
+      if (!n) return;
+
+      node._pendingName = n;
+      node.name = n;
+      savePersist();
+
+      try {
+        if (node.device?.set) {
+          await node.device.set({
+            bridgedDeviceBasicInformation: {
+              nodeLabel: n,
+              productName: n,
+              productLabel: n
+            }
+          });
+        }
+        node._dbg({ type: "rename_ok", name: n });
+      } catch (e) {
+        node._dbg({ type: "rename_error", error: String(e?.message || e) });
+      } finally {
+        node._updateStatus();
+      }
+    }
+
+    async function applyReachable(reachable) {
+      try {
+        if (node.device?.set) {
+          await node.device.set({ bridgedDeviceBasicInformation: { reachable: !!reachable } });
+        }
+        node._dbg({ type: "reachable_set", reachable: !!reachable });
+      } catch (e) {
+        node._dbg({ type: "reachable_error", error: String(e?.message || e) });
+      }
+    }
+
+    async function registerToBridgeIfNeeded() {
+      if (node._registeredToBridge) return true;
+      if (!node.bridge || !node.bridge.serverReady) return false;
+      if (typeof node.bridge.registerChild !== "function") return false;
+
+      try {
+        node.bridge.registerChild(node);
+        node._registeredToBridge = true;
+        node._dbg({ type: "registered_to_bridge" });
+
+        // Apply staged name again for safety
+        if (node._pendingName) {
+          await applyNamePostRegister(node._pendingName);
+        }
+
+        return true;
+      } catch (e) {
+        node._dbg({ type: "registered_to_bridge_error", error: String(e?.message || e) });
+        return false;
+      }
+    }
+
+    function scheduleWriteRetry() {
+      if (pendingTimer) return;
+      pendingTimer = setTimeout(async () => {
+        pendingTimer = null;
+        if (node._closed || !pendingWrite || !node.device) return;
+
+        writeAttempts += 1;
+        node._dbg({ type: "write_retry", attempt: writeAttempts, payload: pendingWrite });
+
+        try {
+          await node.device.set(pendingWrite);
+          node._dbg({ type: "write_retry_ok", attempt: writeAttempts });
+          pendingWrite = null;
+          writeAttempts = 0;
+          node._updateStatus();
+        } catch (err) {
+          const msgText = String(err?.message || err);
+          node._dbg({ type: "write_retry_err", attempt: writeAttempts, error: msgText });
+
+          if (isClosed(msgText)) {
+            node.emit("bridgeReset", { reason: "closedOnWriteRetry", error: msgText });
+            pendingWrite = null;
+            writeAttempts = 0;
+            return;
+          }
+
+          if (isNotInitialized(msgText)) {
+            if (writeAttempts < MAX_WRITE_RETRIES) {
+              scheduleWriteRetry();
+              return;
+            }
+            node._dbg({ type: "write_retry_giveup", attempts: writeAttempts, dropped: pendingWrite, lastError: msgText });
+            pendingWrite = null;
+            writeAttempts = 0;
+            node._updateStatus();
+            return;
+          }
+
+          pendingWrite = null;
+          writeAttempts = 0;
+        }
+      }, WRITE_RETRY_DELAY_MS);
+    }
+
+    async function initAndSubscribe(source) {
+      if (node._closed) return;
+      if (!node._registeredToBridge) return;
+
+      try {
+        if (!node.device?.state || !node.device?.events) throw new Error("Device structure incomplete");
+        void Object.keys(node.device.state);
+        eventManager.subscribe();
+
+        node._dbg({ type: "init_ok", source });
+
+        if (!node._initResolved) {
+          node._initResolved = true;
+          try { node.resolveInit(); } catch (e) {}
+        }
+
+        node._updateStatus();
+      } catch (e) {
+        node._dbg({ type: "init_err", source, error: String(e?.message || e) });
+      }
+    }
+
+    // --------------------------------------------------------------------
+    // Auto-enable on deploy if persisted enabled=true
+    // --------------------------------------------------------------------
+    async function bootAutoRegisterLoop() {
+      if (node._closed) return;
+      if (!node._enabled) {
+        node._updateStatus();
+        return;
+      }
+
+      // Stage persisted name before register so discovery uses it
+      if (node._pendingName) stageNamePreRegister(node._pendingName);
+
+      const ok = await registerToBridgeIfNeeded();
+      if (!ok) {
+        // Bridge not ready yet; retry
+        node._updateStatus();
+        setTimeout(bootAutoRegisterLoop, 500);
+        return;
+      }
+
+      // Make reachable true
+      await applyReachable(true);
+
+      // Subscribe
+      await initAndSubscribe("boot-persisted-enable");
+
+      node._dbg({ type: "boot_persisted_enabled_ok" });
+      node._updateStatus();
+    }
+
+    // Starting status now (based on persisted enabled flag)
+    node._updateStatus();
+
+    // Kick auto registration if persisted enabled
+    setTimeout(bootAutoRegisterLoop, 500);
+
+    // ====================================================================
+    // INPUT HANDLER
+    // ====================================================================
+
+    this.on("input", async function (msg) {
+      const topic = String(msg.topic || "").trim().toLowerCase();
+
+      // Enable
+      if (topic === "enable") {
+        if (typeof msg.payload === "string") stageNamePreRegister(msg.payload);
+        if (isObject(msg.payload) && typeof msg.payload.name === "string") stageNamePreRegister(msg.payload.name);
+
+        node._enabled = true;
+        savePersist();
+
+        const ok = await registerToBridgeIfNeeded();
+        await applyReachable(true);
+        if (ok) await initAndSubscribe("enable");
+
+        node._dbg({ type: "enabled" });
+        node._updateStatus();
+        return;
+      }
+
+      // Disable
+      if (topic === "disable") {
+        node._enabled = false;
+        savePersist();
+        if (node._registeredToBridge) await applyReachable(false);
+        node._dbg({ type: "disabled" });
+        node._updateStatus();
+        return;
+      }
+
+      // Name
+      if (topic === "name") {
+        if (!node._registeredToBridge) stageNamePreRegister(msg.payload);
+        else await applyNamePostRegister(msg.payload);
+        node._updateStatus();
+        return;
+      }
+
+      // Config
+      if (topic === "config" && isObject(msg.payload)) {
+        const enabled = (msg.payload.enabled != null) ? !!msg.payload.enabled : null;
+        const name = (typeof msg.payload.name === "string") ? msg.payload.name : null;
+
+        if (name) {
+          if (!node._registeredToBridge) stageNamePreRegister(name);
+          else await applyNamePostRegister(name);
+        }
+
+        if (enabled === true) {
+          node._enabled = true;
+          savePersist();
+          const ok = await registerToBridgeIfNeeded();
+          await applyReachable(true);
+          if (ok) await initAndSubscribe("config-enable");
+          node._dbg({ type: "enabled" });
+          node._updateStatus();
+        } else if (enabled === false) {
+          node._enabled = false;
+          savePersist();
+          if (node._registeredToBridge) await applyReachable(false);
+          node._dbg({ type: "disabled" });
+          node._updateStatus();
+        }
+        return;
+      }
+
+      // State query
+      if (topic === "state") {
+        try {
+          if (!node._registeredToBridge) {
+            node.send([{ payload: { note: "not registered yet", enabled: node._enabled, name: node._pendingName || node.name } }, null, null]);
+            node._dbg({ type: "state_not_registered" });
+            return;
+          }
+
+          await node.initPromise;
+
+          const out = {};
+          if (node.device?.state) Object.keys(node.device.state).forEach((c) => (out[c] = { ...node.device.state[c] }));
+          node.send([{ payload: out }, null, null]);
+          node._dbg({ type: "state_dump", clusters: Object.keys(out) });
+
+          if (node._isThermostat && out.thermostat) node._mergeThermostat(out.thermostat, "state");
+        } catch (e) {
+          node._dbg({ type: "state_error", error: String(e?.message || e) });
+        }
+        return;
+      }
+
+      // Ignore normal writes unless enabled+registered
+      if (!node._registeredToBridge) {
+        node._dbg({ type: "write_ignored_not_registered", topic });
+        return;
+      }
+      if (!node._enabled) {
+        node._dbg({ type: "write_ignored_disabled", topic });
+        return;
+      }
+
+      // Regular writes
+      try {
+        await node.initPromise;
+        if (!node.device) return;
+
+        if (isObject(msg.payload)) {
+          node._dbg({ type: "write_attempt", payload: msg.payload });
+
+          try {
+            await node.device.set(msg.payload);
+
+            if (node._isThermostat && isObject(msg.payload.thermostat)) {
+              node._mergeThermostat(msg.payload.thermostat, "write");
+            }
+          } catch (err) {
+            const msgText = String(err?.message || err);
+            node._dbg({ type: "write_error", error: msgText });
+
+            if (isNotInitialized(msgText)) {
+              pendingWrite = msg.payload;
+              writeAttempts = 0;
+              node.status({ fill: "yellow", shape: "ring", text: "waiting init" });
+              scheduleWriteRetry();
+              return;
+            }
+
+            if (isClosed(msgText)) {
+              node.emit("bridgeReset", { reason: "closedOnSet", error: msgText });
+              return;
+            }
+          }
+        }
+      } catch (e) {
+        node._dbg({ type: "init_wait_error", error: String(e?.message || e) });
+      } finally {
+        node._updateStatus();
+      }
+    });
+
+    // Bridge reset (re-subscribe only)
+    this.on("bridgeReset", async function (meta) {
+      if (node._closed) return;
+      node._dbg({ type: "bridgeReset", meta });
+      if (!node._registeredToBridge) return;
+
+      try {
+        node.bridge = RED.nodes.getNode(config.bridge);
+        try { await eventManager.cleanup(); } catch (e) {}
+        await initAndSubscribe("bridgeReset");
+      } catch (e) {
+        node._dbg({ type: "bridgeReset_error", error: String(e?.message || e) });
+      }
+    });
+
+    // Bridge reference check
+    if (!node.bridge) {
+      node.status({ fill: "red", shape: "ring", text: "no bridge" });
+      node._dbg({ type: "no_bridge_config" });
+      return;
+    }
+
+    node._dbg({ type: "boot", persistedEnabled: node._enabled, persistedName: node._pendingName });
+
+    // CLEANUP
+    this.on("close", async function (removed, done) {
+      node._closed = true;
+      if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+      pendingWrite = null;
+
+      try { await eventManager.cleanup(); } catch (e) {}
+      try { if (node.device?.nodeRed) node.device.nodeRed = null; } catch (e) {}
+
+      node.device = null;
+      done();
+    });
+  }
+
+  RED.nodes.registerType("matter-device", MatterDevice);
+};