node-red-contrib-dmx-for-ha 0.1.0

package/subflow/relay_node_v4.0.2.js

@@ -0,0 +1,553 @@
+// 230V RELAY NODE — HOME ASSISTANT in NODE-RED
+// Discord: @deswaggy  |  Version: 4.0.2
+// Extensions: "BETTER COMMENTS", "TODO TREE"
+
+//! BIG & BRIGHT
+//@ Topic Headers
+//# Description / Explanations
+//$ Logic
+//^ Debug Comments
+//? Breaks / Headers
+
+// Naming conventions:
+//   <env_var>      = Sub-flow environmental  (Edit subflow template)
+//   <<flow_var>>   = RAM flow memory         (flow.set / flow.get, "memory")
+//   <<D_flow_var>> = Disk flow memory        (flow.set / flow.get, "disk_values")
+//   <<<flow_env>>> = Flow-level environmental (Tab → gear → flow envs)
+
+// Context stores:
+//   memory      = fast, lost on reboot  → used during live operation
+//   disk_values = persistent            → written after a debounce delay
+
+// Role of this node:
+//   Receives ON/OFF commands from HA via MQTT, translates them to integer
+//   payloads (1/0) and publishes to the physical relay controller's MQTT topic.
+//   Reports state back to HA. Handles HA MQTT discovery (add/remove).
+//
+//   This node has NO relationship to DMX. It is a completely separate control
+//   path for 230V relay switching hardware (relay controller boards, SSRs etc.).
+//   Do not reference DMX in this node's documentation or support material.
+//
+//   Relay MQTT topic format: {siteId}/{zone}/{controllerNum}/{mqttTopic}/{relayNum}
+//   Example:                  MW3D/Master/1/relay/23
+//   Relay payload:            1 (ON) or 0 (OFF) — integer, not string, not JSON
+
+//! IMPORTANT — NODE-RED FUNCTION NODE SETUP:
+//   This node requires EXACTLY 5 outputs configured in the NR function node settings.
+//   Output 1: HA MQTT (state topic + discovery config)       → wire to MQTT Out node
+//   Output 2: MQTT subscribe / unsubscribe actions           → wire to MQTT In node
+//   Output 3: Node status + debug                            → wire to Status / Debug node
+//   Output 5: Relay controller MQTT command (integer 1 or 0) → wire to MQTT Out node
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!@ CONFIG — all env reads in one place
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CFG = {
+    //@ HA identity
+    discoveryPrefix:    env.get("<HA_discovery_prefix>"),
+    siteId:             env.get("<HA_site_unique_id>"),
+    component:          env.get("<HA_component>"),
+    uidPrefix:          env.get("<HA_unique_id_prefix>"),
+    uid:                env.get("<HA_unique_id>"),
+    uidPostfix:         env.get("<HA_unique_id_postfix>"),
+
+    //@ MQTT — HA side
+    retain:             env.get("<HA_MQTT_retain_flag>"),
+    qos:                env.get("<HA_MQTT_QOS>"),
+    configTopic:        env.get("<HA_config_topic>"),
+    commandTopic:       env.get("<HA_command_topic>"),
+    stateTopic:         env.get("<HA_state_topic>"),
+
+    //@ HA features
+    schema:             env.get("<HA_schema>"),
+    optimistic:         env.get("<HA_optimistic>"),
+    enabledByDefault:   env.get("<HA_enabled_by_default>"),   //^ no trailing space — was a bug in v3.x
+    icon:               env.get("<HA_icon>"),
+    //^ supported_color_modes always ["onoff"] — relay is binary, hardcoded not env-driven
+    //^ brightness always false — binary device
+
+    //@ Effects — relay-appropriate only
+    //^ flash_short: single ON pulse for flashShort seconds then OFF
+    //^ flash_long:  single ON pulse for flashLong seconds then OFF
+    //^ strobe:      rapid toggling — 500ms minimum interval enforced for mechanical relay safety
+    //^              SSRs (solid state relays) do not have this mechanical wear limitation
+    effects:            env.get("<HA_effects>"),
+    flashShort:         env.get("<HA_effects_flash_time_Short_(seconds)>"),
+    flashLong:          env.get("<HA_effects_flash_time_Long_(seconds)>"),
+
+    //@ Relay controller — hardware side
+    //^ Intentionally separate MQTT settings from the HA side —
+    //^ relay controllers may require different QOS/retain to the HA broker.
+    relayZone:              env.get("<CONTROLLER_zone>"),
+    relayControllerNumber:  env.get("<CONTROLLER_number>"),
+    relayNumber:            env.get("<CONTROLLER_relay_number>"),
+    relayMqttTopic:         env.get("<CONTROLLER_mqtt_topic>") || "relay",
+    relayRetain:            env.get("<RELAY_MQTT_retain_flag>"),
+    relayQos:               env.get("<RELAY_MQTT_QOS>"),
+    controllerFw:           env.get("<CONTROLLER_fw_v>"),
+
+    //@ Device metadata
+    device: {
+        type:        env.get("<DEVICE_Type>"),
+        situation:   env.get("<DEVICE_situation>"),
+        area:        env.get("<DEVICE_area>"),
+        subLocation: env.get("<DEVICE_Sub_Location>"),
+    },
+
+    //@ Node metadata
+    nodeCode:   env.get("<NODE_code>") || "RELAY NODE",
+    nodeSw:     env.get("<NODE_sw_v>"),
+
+    //@ Persistence — same pattern as DMX Node
+    diskDelay:    env.get("<CONTEXT_STORE_values_to_disk_delay_in_seconds>"),
+    defaultState: env.get("<FIXTURE_Default_State>") || "OFF",
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ TOPIC BUILDERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** HA MQTT base topic for this relay entity. */
+const fixtureTopic = `${CFG.discoveryPrefix}/${CFG.component}/${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`;
+
+/** Physical relay controller MQTT command topic.
+ *  Format: {siteId}/{zone}/{controllerNumber}/{mqttTopic}/{relayNumber}
+ *  Example: MW3D/Master/1/relay/23 */
+const relayTopic = `${CFG.siteId}/${CFG.relayZone}/${CFG.relayControllerNumber}/${CFG.relayMqttTopic}/${CFG.relayNumber}`;
+
+/** Short fixture ID for NR node status messages — quick visual feedback on canvas. */
+const fixtureId = `${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ MEMORY HELPERS
+//# SHARED PATTERN WITH DMX NODE — extract to shared utility on node package build
+// ─────────────────────────────────────────────────────────────────────────────
+
+function recall(ramKey, diskKey, fallback) {
+    return flow.get(ramKey, "memory") || flow.get(diskKey, "disk_values") || fallback;
+}
+
+function rememberRam(values) {
+    Object.entries(values).forEach(([key, val]) => flow.set(key, val, "memory"));
+}
+
+function rememberDisk(values) {
+    Object.entries(values).forEach(([key, val]) => flow.set(key, val, "disk_values"));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ MQTT SEND HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Report relay state back to HA on output 1. */
+function sendState(payloadObj) {
+    node.send([{
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   `${fixtureTopic}/${CFG.stateTopic}`,
+        payload: payloadObj,
+    }, null, null, null, null]);
+}
+
+/** Send a Node-RED status + debug message on output 3. */
+function sendStatus(fill, shape, text) {
+    node.send([null, null, {
+        debug:  { node: fixtureId, message: text },
+        status: { fill, shape, text },
+    }, null, null]);
+}
+
+/**
+ * Send integer 1 or 0 to the physical relay controller on output 5.
+ * @param {0|1} value - 1 = ON, 0 = OFF
+ */
+function sendRelayCommand(value) {
+    node.send([null, null, null, null, {
+        retain:  CFG.relayRetain,
+        qos:     CFG.relayQos,
+        topic:   relayTopic,
+        payload: value,   //# integer — relay controllers expect numeric not string/JSON
+    }]);
+    console.log(`${fixtureId} relay command — topic:${relayTopic}  payload:${value}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DISK-SAVE TIMER
+//# SHARED PATTERN WITH DMX NODE — extract to shared utility on node package build
+// ─────────────────────────────────────────────────────────────────────────────
+
+function startDiskSaveTimer(onComplete) {
+    const existing = context.get('timer_diskSave');
+    if (existing) {
+        clearInterval(existing);
+        context.set('timer_diskSave', null);
+        context.set('timer_diskSave_count', 0);
+        console.log(`${fixtureId} disk-save timer reset by new input.`);
+    }
+
+    const maxLoops = CFG.diskDelay;
+    let count = 0;
+    sendStatus("green", "ring", `${fixtureId} disk-save timer running`);
+
+    const timer = setInterval(() => {
+        count++;
+        if (count >= maxLoops) {
+            clearInterval(timer);
+            context.set('timer_diskSave', null);
+            context.set('timer_diskSave_count', 0);
+            onComplete();
+            sendStatus("yellow", "ring", `${fixtureId} ready — awaiting HA commands`);
+        } else {
+            context.set('timer_diskSave_count', count);
+        }
+    }, 1000);
+
+    context.set('timer_diskSave', timer);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ SERIAL NUMBER BUILDER
+//# Carries forward the uuid compile + clean logic from the original v3.x node.
+//# Generates a sanitised unique identifier for the HA device serial_number field.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build a sanitised serial number from device attributes.
+ * Lowercase, underscores for spaces, no special characters.
+ * Example: "p_23_master_bedroom_1_ensuite_exhaust_fan"
+ */
+function buildSerialNumber() {
+    const raw = [
+        CFG.uidPrefix,
+        String(CFG.uid) + String(CFG.uidPostfix),
+        CFG.relayZone,
+        CFG.device.area,
+        CFG.device.subLocation,
+        CFG.device.type,
+    ].join('_');
+
+    return raw
+        .toLowerCase()
+        .replace(/\s+/g, '_')
+        .replace(/[#()]/g, '')
+        .replace(/-/g, '_')
+        .replace(/__+/g, '_');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ EFFECTS — relay-appropriate only
+//# Binary device — effects are simple ON/OFF pulse or toggle patterns.
+//# strobe has a 500ms minimum interval to protect mechanical relay contacts.
+//# SSRs (solid state relays) do not have this mechanical wear limitation.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Cancel any currently running effect timer. */
+function stopEffect() {
+    const t = context.get('timer_effect');
+    if (t) {
+        clearTimeout(t);
+        clearInterval(t);
+        context.set('timer_effect', null);
+    }
+}
+
+/** Restore relay to its last known RAM state after an effect ends. */
+function restoreAfterEffect() {
+    const prevState = recall("<<RELAY_State>>", "<<D_RELAY_State>>", CFG.defaultState);
+    sendRelayCommand(prevState === "ON" ? 1 : 0);
+    sendState({ state: prevState, color_mode: "onoff" });
+    sendStatus("yellow", "ring", `${fixtureId} effect complete — awaiting HA commands`);
+    console.log(`${fixtureId} restored to state: ${prevState}`);
+}
+
+/**
+ * Single ON pulse for durationSecs then restores to previous state.
+ * Used for flash_short and flash_long.
+ */
+function effectPulse(durationSecs, label) {
+    stopEffect();
+    sendStatus("blue", "dot", `${fixtureId} effect: ${label}`);
+    sendRelayCommand(1);
+    sendState({ state: "ON", color_mode: "onoff" });
+
+    const timer = setTimeout(() => {
+        context.set('timer_effect', null);
+        restoreAfterEffect();
+    }, durationSecs * 1000);
+
+    context.set('timer_effect', timer);
+}
+
+/**
+ * Rapid ON/OFF toggling.
+ * 500ms minimum interval enforced to protect mechanical relay contacts.
+ * @param {number} durationSecs - 0 = run indefinitely until next command
+ * @param {number} [intervalMs=500]
+ */
+function effectStrobe(durationSecs, intervalMs = 500) {
+    stopEffect();
+    const safeInterval = Math.max(500, intervalMs);
+    sendStatus("blue", "dot", `${fixtureId} effect: strobe`);
+
+    const endTime = durationSecs > 0 ? Date.now() + durationSecs * 1000 : Infinity;
+    let isOn = false;
+
+    const timer = setInterval(() => {
+        isOn = !isOn;
+        sendRelayCommand(isOn ? 1 : 0);
+        if (Date.now() >= endTime) {
+            clearInterval(timer);
+            context.set('timer_effect', null);
+            restoreAfterEffect();
+        }
+    }, safeInterval);
+
+    context.set('timer_effect', timer);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ EFFECT DISPATCH
+// ─────────────────────────────────────────────────────────────────────────────
+
+const EFFECT_MAP = {
+    "flash_short": () => effectPulse(CFG.flashShort, "flash short"),
+    "flash_long":  () => effectPulse(CFG.flashLong,  "flash long"),
+    "strobe":      () => effectStrobe(0),
+};
+
+function runEffect(effectName) {
+    const fn = EFFECT_MAP[effectName];
+    if (fn) {
+        console.log(`${fixtureId} running effect: "${effectName}"`);
+        fn();
+    } else {
+        node.warn(`${fixtureId} — unknown effect: "${effectName}"`);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ STATE HANDLERS
+//# Relay is binary — ON or OFF only.
+//# Each handler:
+//#   1. Sends integer command to physical relay controller (output 5)
+//#   2. Reports state back to HA (output 1)
+//#   3. Saves to RAM, queues disk write
+// ─────────────────────────────────────────────────────────────────────────────
+
+const RELAY_HANDLERS = {
+
+    ON(payload) {
+        stopEffect();
+        sendRelayCommand(1);
+        sendState({ state: "ON", color_mode: "onoff" });
+        rememberRam({ "<<RELAY_State>>": "ON" });
+        startDiskSaveTimer(() => {
+            rememberDisk({ "<<D_RELAY_State>>": "ON" });
+            console.log(`${fixtureId} disk saved — state:ON`);
+        });
+    },
+
+    OFF(payload) {
+        stopEffect();
+        sendRelayCommand(0);
+        sendState({ state: "OFF", color_mode: "onoff" });
+        rememberRam({ "<<RELAY_State>>": "OFF" });
+        startDiskSaveTimer(() => {
+            rememberDisk({ "<<D_RELAY_State>>": "OFF" });
+            console.log(`${fixtureId} disk saved — state:OFF`);
+        });
+    },
+};
+
+function dispatch(state, payload) {
+    console.log(`${fixtureId} dispatch — state:"${state}"`);
+    const handler = RELAY_HANDLERS[state];
+    if (!handler) {
+        node.warn(
+            `${fixtureId} dispatch error — unknown state "${state}". ` +
+            `Must be "ON" or "OFF". Check incoming payload from HA.`
+        );
+        return;
+    }
+    handler(payload);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DEVICE REQUEST HANDLERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+function initDefaultMemory() {
+    const existing = flow.get("<<RELAY_State>>", "memory")
+                  || flow.get("<<D_RELAY_State>>", "disk_values");
+    if (existing) {
+        console.log(`${fixtureId} initDefaultMemory: existing state found in memory, skipping defaults.`);
+        return;
+    }
+    rememberRam({ "<<RELAY_State>>": CFG.defaultState });
+    console.log(`${fixtureId} initDefaultMemory: default state "${CFG.defaultState}" written to RAM.`);
+}
+
+function clearAllMemory() {
+    flow.set("<<RELAY_State>>",   null, "memory");
+    flow.set("<<D_RELAY_State>>", null, "disk_values");
+    console.log(`${fixtureId} clearAllMemory: all relay memory cleared.`);
+}
+
+function buildRecoveryStatePayload() {
+    const state = recall("<<RELAY_State>>", "<<D_RELAY_State>>", CFG.defaultState);
+    console.log(`${fixtureId} recovery — state:${state}`);
+    return { state, color_mode: "onoff" };
+}
+
+function handleDeviceAdd() {
+    initDefaultMemory();
+
+    const cmdTopic = `${fixtureTopic}/${CFG.commandTopic}`;
+    const cfgTopic = `${fixtureTopic}/${CFG.configTopic}`;
+    const { device: dev } = CFG;
+
+    const discoveryPayload = {
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   cfgTopic,
+        payload: {
+            unique_id:             `${dev.type}(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix})`,
+            schema:                CFG.schema,
+            //^ object_id locks the HA entity_id to the plan ID: light.p_23
+            object_id:             `${CFG.uidPrefix}_${CFG.uid}${CFG.uidPostfix}`.toLowerCase().replace(/[^a-z0-9]/g, '_').replace(/__+/g, '_'),
+            name:                  `${dev.type} ${dev.situation} the ${CFG.relayZone} ${dev.area} ${dev.subLocation}`,
+            cmd_t:                 cmdTopic,
+            stat_t:                `${fixtureTopic}/${CFG.stateTopic}`,
+            optimistic:            CFG.optimistic,
+            enabled_by_default:    CFG.enabledByDefault,
+            icon:                  CFG.icon,
+            supported_color_modes: ["onoff"],
+            brightness:            false,
+            effect:                CFG.effects,
+            effect_list:           Object.keys(EFFECT_MAP),
+            flash_time_short:      CFG.flashShort,
+            flash_time_long:       CFG.flashLong,
+            device: {
+                identifiers:    `${CFG.component}-${CFG.uidPrefix}-${CFG.uid}`,
+                name:           `(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}) - ${dev.type}/s ${dev.situation} the ${CFG.relayZone} - ${dev.area} - ${dev.subLocation}`,
+                model:          `${dev.type}/s located ${dev.situation} the ${CFG.relayZone}-${dev.area} - ${dev.subLocation}`,
+                model_id:       `referenced on plan as: (${CFG.uidPrefix}-${CFG.uid}`,
+                suggested_area: `${CFG.relayZone} ${dev.area} ${dev.subLocation}`,
+                hw_version:     `Relay Controller in ${CFG.relayZone} Server Rack, firmware: ${CFG.controllerFw}. ` +
+                                `Publishes MQTT integer 1 (ON) or 0 (OFF) on topic: ${relayTopic}`,
+                serial_number:  buildSerialNumber(),
+                sw_version:     `${CFG.nodeCode}: ${CFG.nodeSw}`,
+                manufacturer:   "DeSwaggy — Discord: @deswaggy",
+            },
+        },
+    };
+
+    node.send([
+        discoveryPayload,
+        { retain: CFG.retain, qos: CFG.qos, topic: cmdTopic, action: "subscribe" },
+        { status: { fill: "green", shape: "ring", text: `${fixtureId} discovery sent — awaiting HA` } },
+        null,
+        null,
+    ]);
+    console.log(`${fixtureId} device added.`);
+
+    setTimeout(() => {
+        const recoveryPayload = buildRecoveryStatePayload();
+        sendState(recoveryPayload);
+        //# Also re-assert the physical relay state so hardware matches HA after reboot
+        sendRelayCommand(recoveryPayload.state === "ON" ? 1 : 0);
+        sendStatus("yellow", "ring", `${fixtureId} ready — awaiting HA commands`);
+        console.log(`${fixtureId} recovery state sent — state:${recoveryPayload.state}`);
+    }, 2000);
+}
+
+function handleDeviceRemove() {
+    stopEffect();
+    const existing = context.get('timer_diskSave');
+    if (existing) clearInterval(existing);
+    context.set('timer_diskSave', null);
+
+    clearAllMemory();
+
+    node.send([
+        { retain: CFG.retain, qos: CFG.qos, topic: `${fixtureTopic}/${CFG.configTopic}`, payload: "" },
+        { retain: CFG.retain, qos: CFG.qos, topic: `${fixtureTopic}/${CFG.commandTopic}`, action: "unsubscribe" },
+        { status: { fill: "red", shape: "ring", text: `${fixtureId} discovery removed — memory cleared` } },
+        null,
+        null,
+    ]);
+    console.log(`${fixtureId} device removed.`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!? ENTRY POINT
+// ─────────────────────────────────────────────────────────────────────────────
+
+//# Suppress passthrough for AUX messages — Group Node already passed it through
+const isAuxMessage = msg.dmx_trace != null;
+if (!isAuxMessage) {
+    node.send([null, null, null, msg, null]);
+}
+
+const prevState = recall("<<RELAY_State>>", "<<D_RELAY_State>>", CFG.defaultState);
+console.log(`${fixtureId}  prev state:${prevState}  isAux:${isAuxMessage}`);
+
+//? ── AUX — payload received from a parent Group Node ─────────────────────────
+if (isAuxMessage) {
+    console.log(
+        `${fixtureId} AUX — from:"${msg.dmx_trace.source}"  ` +
+        `path:[${msg.dmx_trace.path.join(' → ')}]  depth:${msg.dmx_trace.depth}`
+    );
+    if (msg.payload?.effect && CFG.effects) {
+        runEffect(msg.payload.effect);
+    } else if (msg.payload?.state != null) {
+        if (typeof msg.payload === 'string') {
+            node.warn(`${fixtureId} AUX — payload is a string not parsed JSON. Check MQTT In node output setting.`);
+            node.done(); return;
+        }
+        dispatch(msg.payload.state, msg.payload);
+    } else {
+        node.warn(`${fixtureId} AUX from "${msg.dmx_trace.source}" — no valid state or effect.`);
+    }
+
+//? ── DIRECT HA COMMAND — payload.state from MQTT In ─────────────────────────
+} else if (msg.payload?.state != null) {
+    if (typeof msg.payload === 'string') {
+        node.warn(
+            `${fixtureId} — msg.payload is a string not a parsed object. ` +
+            `Check MQTT In node is configured with Output: "a parsed JSON object".`
+        );
+        node.done(); return;
+    }
+    const { state, effect } = msg.payload;
+    if (effect && CFG.effects) {
+        console.log(`${fixtureId} effect received: "${effect}"`);
+        runEffect(effect);
+    } else {
+        dispatch(state, msg.payload);
+    }
+
+//? ── DEVICE REQUEST — add / remove / debug ───────────────────────────────────
+} else if (msg.device != null && (typeof msg.device === "string" || msg.device?.request != null)) {
+    const _devReq = typeof msg.device === "string" ? msg.device : msg.device.request;
+    console.log(`${fixtureId} device.request: ${_devReq}`);
+    switch (_devReq) {
+        case "add":    handleDeviceAdd();    break;
+        case "remove": handleDeviceRemove(); break;
+        case "debug":  console.log(`${fixtureId} DEBUG:`, JSON.stringify(msg)); break;
+        default:       node.warn(`${fixtureId} — unknown device.request: "${_devReq}"`);
+    }
+
+//? ── UNKNOWN MESSAGE ─────────────────────────────────────────────────────────
+} else {
+    node.warn(
+        `${fixtureId} — unrecognised message. ` +
+        `Expected: msg.dmx_trace (AUX from Group Node), ` +
+        `msg.payload.state (direct HA command), or msg.device.request (add/remove). ` +
+        `Message received and dropped — unrecognised format. See node documentation.`
+    );
+}
+
+node.done();
+return [null, null, null, msg, null];