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

package/subflow/dmx_group_node_v0.3.8.js

@@ -0,0 +1,860 @@
+// DMX GROUP NODE — HOME ASSISTANT in NODE-RED
+// Discord: @deswaggy  |  Version: 0.3.8
+// 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:
+//   Sits between the MQTT in node and one or more DMX fixture nodes (or child Group Nodes).
+//   Appears as a single HA light entity (e.g. "Bedroom 1", "Ceiling").
+//   On command: updates own HA state, then fans the payload downstream via output 2 (AUX)
+//   to all wired children — each child handles its own DMX/HA state independently.
+//   No DMX channels. No gamma correction. No fixture-level concerns.
+//
+//   Star topology:  MQTT in → Group Node → [DMX Node AUX | Group Node AUX] × N
+//   Recursive:      Group Node → Group Node → Group Node → DMX Node (any depth)
+//
+//! 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: AUX fan-out → all child DMX / Group Nodes   → wire to children's input
+//   If outputs are misconfigured, state and fan-out messages will be silently dropped.
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!@ 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>"),
+
+    //@ Group UID prefix — used in MQTT topic and HA entity unique_id
+    //^ LG = Light Group (default), PG = Power Group
+    //^ This is intentionally separate from the DMX fixture node's <HA_unique_id_prefix>
+    //^ so group topics are always correctly prefixed without manual env var changes.
+    groupUidPrefix:     env.get("<GROUP_uid_prefix>") || "LG",
+
+    //@ MQTT
+    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>"),
+    icon:               env.get("<HA_icon>"),
+    colorModes:         env.get("<HA_supported_color_modes>"),
+    brightness:         env.get("<HA_brightness>"),
+    transitionsEnabled: env.get("<HA_Transitions_Enabled>") !== "false",
+
+    //@ Effects
+    //^ Group Node only supports synced group effects — forwarded downstream so all
+    //^ children receive the command simultaneously, keeping siblings in sync.
+    //^ Individual fixture effects (sleep_transition etc.) are intentionally excluded.
+    effects:            env.get("<HA_effects>"),
+    //^ <HA_group_effects_list> — comma-separated list of synced group effects.
+    //^ Set as "str" type in the subflow env menu (comma-separated, no spaces).
+    //^ Intentionally excludes sleep_transition and temperature_transition —
+    //^ those are intimate per-fixture effects, not group-level concerns.
+    //^ Recommended list (same regardless of color mode — group syncs all children):
+    //#   flash_short,flash_long,strobe,rainbow,rainbow_rgbw,fire,flicker,twinkle,
+    //#   color_chase,scan,random,police,christmas,halloween,calaveras,party,fireworks
+    groupEffectsList:   (env.get("<HA_group_effects_list>") ||
+                        "flash_short,flash_long,strobe,rainbow,rainbow_rgbw,fire,flicker,twinkle," +
+                        "color_chase,scan,random,police,christmas,halloween,calaveras," +
+                        "party,fireworks").split(','),
+    flashShort:         env.get("<HA_effects_flash_time_Short_(seconds)>"),
+    flashLong:          env.get("<HA_effects_flash_time_Long_(seconds)>"),
+
+    //@ Color temperature range — advertised to HA in discovery payload
+    minMireds:          env.get("<HA_ct_min_mireds>") || 153,
+    maxMireds:          env.get("<HA_ct_max_mireds>") || 500,
+
+    //@ Transition — flow-level globals (<<<...>>>)
+    transitionRateLimit:   env.get("<<<DMX_NODE_FLOW_Transition_Rate_Limit>>>") || 1,
+    transitionDefaultSecs: env.get("<<<DMX_NODE_FLOW_Transition_HA_UI_Time_(seconds)>>>") || 1,
+
+    //@ Group Node — identity
+    //^ Human-readable name used in dmx_trace for fault-finding and in HA device info.
+    //^ Always cast to string — <HA_unique_id> may be an integer (e.g. 992)
+    groupName: String(env.get("<GROUP_name>") || env.get("<HA_unique_id>") || ""),
+
+    //@ Group Node — loop detection
+    //^ Max AUX hop depth before dropping the message and warning.
+    //^ Protects against accidental circular wiring in the NR flow.
+    //^ Set to 0 to disable (not recommended in production).
+    //^ Default: 10
+    groupMaxDepth: (() => {
+        const raw = parseInt(env.get("<DMX_Group_Max_Depth>"));
+        return isNaN(raw) ? 10 : raw;
+    })(),
+
+    //@ DMX zone — used in discovery payload descriptions (matches DMX Node convention)
+    dmxZone:      env.get("<CONTROLLER_zone>"),
+
+    //@ 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>") || "DMX GROUP NODE",
+    nodeSw:      env.get("<NODE_sw_v>"),
+
+    //@ Persistence
+    diskDelay:    env.get("<CONTEXT_STORE_values_to_disk_delay_in_seconds>"),
+    defaultState: env.get("<GROUP_default_state>") || "OFF",
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ TOPIC BUILDER
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Base MQTT topic path for this group entity.
+ *  Uses CFG.groupUidPrefix (default "LG") — separate from fixture <HA_unique_id_prefix>
+ *  so a Group Node always produces e.g. "homeassistant/light/LG-992/cmd"
+ *  without requiring the user to manually set the prefix per node. */
+const groupTopic = `${CFG.discoveryPrefix}/${CFG.component}/${CFG.groupUidPrefix}-${CFG.uid}${CFG.uidPostfix}`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ MEMORY HELPERS
+//# SHARED WITH DMX NODE — extract to shared utility module on node package build
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read a value from RAM → disk → fallback, in that priority order.
+ * @param {string} ramKey
+ * @param {string} diskKey
+ * @param {*}      fallback
+ */
+function recall(ramKey, diskKey, fallback) {
+    return flow.get(ramKey, "memory") || flow.get(diskKey, "disk_values") || fallback;
+}
+
+/** Write a key/value map to RAM memory in one call. */
+function rememberRam(values) {
+    Object.entries(values).forEach(([key, val]) => flow.set(key, val, "memory"));
+}
+
+/** Write a key/value map to disk memory in one call. */
+function rememberDisk(values) {
+    Object.entries(values).forEach(([key, val]) => flow.set(key, val, "disk_values"));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ MQTT SEND HELPERS
+//# SHARED WITH DMX NODE — extract to shared utility module on node package build
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Report group state back to HA on output 1. */
+function sendState(payloadObj) {
+    node.send([{
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   `${groupTopic}/${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: `Group: ${CFG.groupName}`, message: text },
+        status: { fill, shape, text },
+    }, null, null]);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DISK-SAVE TIMER
+//# SHARED WITH DMX NODE — extract to shared utility module on node package build
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Debounced disk-write timer — resets on every new command.
+ * @param {Function} onComplete - called when the delay has elapsed
+ */
+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("Group disk-save timer reset by new input.");
+    }
+
+    const maxLoops = CFG.diskDelay;
+    let count = 0;
+    sendStatus("green", "ring", "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", "Disk-save complete — awaiting next HA command");
+        } else {
+            context.set('timer_diskSave_count', count);
+        }
+    }, 1000);
+
+    context.set('timer_diskSave', timer);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DMX TRACE — ancestry tracking and loop detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build a dmx_trace object to attach to every forwarded payload.
+ * Appends this Group Node to the ancestry path.
+ *
+ * @param {Object|null} incomingTrace - dmx_trace from upstream, or null if this is the origin
+ * @returns {Object} dmx_trace for the forwarded msg
+ *
+ * Example output at depth 2:
+ * {
+ *   source:  "DMX Group Node: Ceiling",
+ *   path:    ["Bedroom 1"],
+ *   depth:   2
+ * }
+ */
+function buildTrace(incomingTrace) {
+    const path  = incomingTrace ? [...incomingTrace.path, incomingTrace.source] : [];
+    const depth = incomingTrace ? incomingTrace.depth + 1 : 1;
+    return {
+        source: `DMX Group Node: ${CFG.groupName}`,
+        path,
+        depth,
+    };
+}
+
+/**
+ * Check if the incoming trace exceeds the configured max depth.
+ * Warns, sets node status red, and returns true if the message should be dropped.
+ *
+ * @param {Object} trace - dmx_trace from incoming msg
+ * @returns {boolean} true = drop the message
+ */
+function isLoopDetected(trace) {
+    if (CFG.groupMaxDepth === 0) return false;   //# 0 = disabled
+    if (trace.depth > CFG.groupMaxDepth) {
+        node.warn(
+            `DMX Group Node "${CFG.groupName}" — loop guard tripped! ` +
+            `Depth ${trace.depth} exceeds max ${CFG.groupMaxDepth}. ` +
+            `Payload dropped — check for circular wiring in your NR flow. ` +
+            `Ancestry path: [${trace.path.join(' → ')}]. ` +
+            `Adjust <DMX_Group_Max_Depth> to change the limit (0 = disabled).`
+        );
+        sendStatus("red", "ring", `Loop guard tripped — depth ${trace.depth} > max ${CFG.groupMaxDepth}`);
+        return true;
+    }
+    return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ FAN-OUT — forward payload to all wired children via output 2
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Forward a command payload downstream to all wired children.
+ * Attaches dmx_trace so children know where the command came from
+ * and can detect loops if they are also Group Nodes.
+ *
+ * @param {Object} payload      - HA command payload (state, brightness, color etc.)
+ * @param {Object} trace        - dmx_trace to attach
+ * @param {Object} originalMsg  - the original incoming msg (for _msgid passthrough)
+ */
+function fanOut(payload, trace, originalMsg) {
+    const forwardMsg = {
+        topic:     `${groupTopic}/${CFG.commandTopic}`,
+        dmx_trace: trace,
+        payload,
+        qos:       CFG.qos,
+        retain:    CFG.retain,
+        _msgid:    originalMsg._msgid,
+    };
+    //# Output 5 is the AUX fan-out output — wire this to children's input
+    node.send([null, null, null, null, forwardMsg]);
+    console.log(`Fan-out — group:"${CFG.groupName}"  depth:${trace.depth}  state:${payload.state || payload.effect || "effect"}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ COLOR RESOLVERS
+//# Group Node resolvers use G-prefixed memory keys to avoid collisions
+//# with sibling DMX fixture nodes in the shared flow context store.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function resolveGroupOnoff() {
+    return { white: recall("<<G_white>>", "<<GD_white>>", 255) };
+}
+
+function resolveGroupBrightness(payload) {
+    return { brightness: payload?.brightness || recall("<<G_bright>>", "<<GD_bright>>", 255) };
+}
+
+function resolveGroupRgb(payload) {
+    return {
+        brightness: payload?.brightness || recall("<<G_bright>>", "<<GD_bright>>", 255),
+        red:        payload?.color?.r   || recall("<<G_red>>",    "<<GD_red>>",    255),
+        green:      payload?.color?.g   || recall("<<G_green>>",  "<<GD_green>>",  255),
+        blue:       payload?.color?.b   || recall("<<G_blue>>",   "<<GD_blue>>",   255),
+    };
+}
+
+function resolveGroupRgbw(payload) {
+    return {
+        brightness: payload?.brightness || recall("<<G_bright>>", "<<GD_bright>>", 255),
+        red:        payload?.color?.r   || recall("<<G_red>>",    "<<GD_red>>",    255),
+        green:      payload?.color?.g   || recall("<<G_green>>",  "<<GD_green>>",  255),
+        blue:       payload?.color?.b   || recall("<<G_blue>>",   "<<GD_blue>>",   255),
+        white:      payload?.color?.w   || recall("<<G_white>>",  "<<GD_white>>",  255),
+    };
+}
+
+function resolveGroupRgbww(payload) {
+    return {
+        brightness: payload?.brightness  || recall("<<G_bright>>",    "<<GD_bright>>",    255),
+        red:        payload?.color?.r    || recall("<<G_red>>",        "<<GD_red>>",        255),
+        green:      payload?.color?.g    || recall("<<G_green>>",      "<<GD_green>>",      255),
+        blue:       payload?.color?.b    || recall("<<G_blue>>",       "<<GD_blue>>",       255),
+        white:      payload?.color?.w    || recall("<<G_white>>",      "<<GD_white>>",      255),
+        warmWhite:  payload?.color?.ww   || recall("<<G_warmWhite>>",  "<<GD_warmWhite>>",  0),
+    };
+}
+
+function resolveGroupColorTemp(payload) {
+    return {
+        brightness: payload?.brightness || recall("<<G_bright>>",    "<<GD_bright>>",    255),
+        colorTemp:  payload?.color_temp || recall("<<G_colorTemp>>", "<<GD_colorTemp>>", 300),
+    };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ STATE HANDLERS
+//# Each handler:
+//#   1. Resolves current values (payload → RAM → disk → default)
+//#   2. Reports own state to HA
+//#   3. Fans payload out to all wired children via output 2
+//#   4. Saves resolved values to RAM, queues disk write
+//#
+//# No DMX. No gamma. No channel maths. State + fan-out only.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const GROUP_HANDLERS = {
+
+    ON: {
+
+        onoff(payload, trace, originalMsg) {
+            const { white } = resolveGroupOnoff();
+            sendState({ state: "ON", color: { w: white }, color_mode: "onoff" });
+            fanOut({ state: "ON", color: { w: white }, color_mode: "onoff" }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "ON", "<<G_white>>": white });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "ON", "<<GD_white>>": white });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:ON`);
+            });
+        },
+
+        brightness(payload, trace, originalMsg) {
+            const { brightness } = resolveGroupBrightness(payload);
+            sendState({ state: "ON", brightness, color_mode: "brightness" });
+            fanOut({ state: "ON", brightness, color_mode: "brightness", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "ON", "<<G_bright>>": brightness });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "ON", "<<GD_bright>>": brightness });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:ON  bright:${brightness}`);
+            });
+        },
+
+        rgb(payload, trace, originalMsg) {
+            const { brightness, red, green, blue } = resolveGroupRgb(payload);
+            sendState({ state: "ON", brightness, color: { r: red, g: green, b: blue }, color_mode: "rgb" });
+            fanOut({ state: "ON", brightness, color: { r: red, g: green, b: blue }, color_mode: "rgb", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "ON", "<<G_bright>>": brightness, "<<G_red>>": red, "<<G_green>>": green, "<<G_blue>>": blue });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "ON", "<<GD_bright>>": brightness, "<<GD_red>>": red, "<<GD_green>>": green, "<<GD_blue>>": blue });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  R:${red} G:${green} B:${blue} bright:${brightness}`);
+            });
+        },
+
+        rgbw(payload, trace, originalMsg) {
+            const { brightness, red, green, blue, white } = resolveGroupRgbw(payload);
+            sendState({ state: "ON", brightness, color: { r: red, g: green, b: blue, w: white }, color_mode: "rgbw" });
+            fanOut({ state: "ON", brightness, color: { r: red, g: green, b: blue, w: white }, color_mode: "rgbw", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "ON", "<<G_bright>>": brightness, "<<G_red>>": red, "<<G_green>>": green, "<<G_blue>>": blue, "<<G_white>>": white });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "ON", "<<GD_bright>>": brightness, "<<GD_red>>": red, "<<GD_green>>": green, "<<GD_blue>>": blue, "<<GD_white>>": white });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  R:${red} G:${green} B:${blue} W:${white} bright:${brightness}`);
+            });
+        },
+
+        rgbww(payload, trace, originalMsg) {
+            const { brightness, red, green, blue, white, warmWhite } = resolveGroupRgbww(payload);
+            sendState({ state: "ON", brightness, color: { r: red, g: green, b: blue, w: white, ww: warmWhite }, color_mode: "rgbww" });
+            fanOut({ state: "ON", brightness, color: { r: red, g: green, b: blue, w: white, ww: warmWhite }, color_mode: "rgbww", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "ON", "<<G_bright>>": brightness, "<<G_red>>": red, "<<G_green>>": green, "<<G_blue>>": blue, "<<G_white>>": white, "<<G_warmWhite>>": warmWhite });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "ON", "<<GD_bright>>": brightness, "<<GD_red>>": red, "<<GD_green>>": green, "<<GD_blue>>": blue, "<<GD_white>>": white, "<<GD_warmWhite>>": warmWhite });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  R:${red} G:${green} B:${blue} W:${white} WW:${warmWhite} bright:${brightness}`);
+            });
+        },
+
+        color_temp(payload, trace, originalMsg) {
+            const { brightness, colorTemp } = resolveGroupColorTemp(payload);
+            sendState({ state: "ON", brightness, color_temp: colorTemp, color_mode: "color_temp" });
+            fanOut({ state: "ON", brightness, color_temp: colorTemp, color_mode: "color_temp", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "ON", "<<G_bright>>": brightness, "<<G_colorTemp>>": colorTemp });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "ON", "<<GD_bright>>": brightness, "<<GD_colorTemp>>": colorTemp });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  colorTemp:${colorTemp} bright:${brightness}`);
+            });
+        },
+
+        //# Combo modes — HA tells us which sub-mode is active via payload.color_mode
+        "rgb,color_temp"(payload, trace, originalMsg) {
+            payload.color_mode === "color_temp"
+                ? GROUP_HANDLERS.ON.color_temp(payload, trace, originalMsg)
+                : GROUP_HANDLERS.ON.rgb(payload, trace, originalMsg);
+        },
+
+        "rgbw,color_temp"(payload, trace, originalMsg) {
+            payload.color_mode === "color_temp"
+                ? GROUP_HANDLERS.ON.color_temp(payload, trace, originalMsg)
+                : GROUP_HANDLERS.ON.rgbw(payload, trace, originalMsg);
+        },
+
+        "rgbww,color_temp"(payload, trace, originalMsg) {
+            payload.color_mode === "color_temp"
+                ? GROUP_HANDLERS.ON.color_temp(payload, trace, originalMsg)
+                : GROUP_HANDLERS.ON.rgbww(payload, trace, originalMsg);
+        },
+
+        white(payload, trace, originalMsg) {
+            const { brightness } = resolveGroupBrightness(payload);
+            sendState({ state: "ON", brightness, color_mode: "white" });
+            fanOut({ state: "ON", brightness, color_mode: "white", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "ON", "<<G_bright>>": brightness });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "ON", "<<GD_bright>>": brightness });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:ON  bright:${brightness}`);
+            });
+        },
+    },
+
+    OFF: {
+
+        onoff(payload, trace, originalMsg) {
+            sendState({ state: "OFF", color_mode: "onoff" });
+            fanOut({ state: "OFF", color_mode: "onoff" }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "OFF" });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:OFF`);
+            });
+        },
+
+        brightness(payload, trace, originalMsg) {
+            sendState({ state: "OFF", color_mode: "brightness" });
+            fanOut({ state: "OFF", color_mode: "brightness", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "OFF" });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:OFF`);
+            });
+        },
+
+        rgb(payload, trace, originalMsg) {
+            sendState({ state: "OFF", color: { r: 0, g: 0, b: 0 }, color_mode: "rgb" });
+            fanOut({ state: "OFF", color: { r: 0, g: 0, b: 0 }, color_mode: "rgb", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "OFF" });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:OFF`);
+            });
+        },
+
+        rgbw(payload, trace, originalMsg) {
+            sendState({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0 }, color_mode: "rgbw" });
+            fanOut({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0 }, color_mode: "rgbw", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "OFF" });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:OFF`);
+            });
+        },
+
+        rgbww(payload, trace, originalMsg) {
+            sendState({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0, ww: 0 }, color_mode: "rgbww" });
+            fanOut({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0, ww: 0 }, color_mode: "rgbww", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "OFF" });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:OFF`);
+            });
+        },
+
+        color_temp(payload, trace, originalMsg) {
+            sendState({ state: "OFF", color_mode: "color_temp" });
+            fanOut({ state: "OFF", color_mode: "color_temp", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "OFF" });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:OFF`);
+            });
+        },
+
+        "rgb,color_temp"(payload, trace, originalMsg)   { GROUP_HANDLERS.OFF.rgb(payload, trace, originalMsg); },
+        "rgbw,color_temp"(payload, trace, originalMsg)  { GROUP_HANDLERS.OFF.rgbw(payload, trace, originalMsg); },
+        "rgbww,color_temp"(payload, trace, originalMsg) { GROUP_HANDLERS.OFF.rgbww(payload, trace, originalMsg); },
+
+        white(payload, trace, originalMsg) {
+            sendState({ state: "OFF", color_mode: "white" });
+            fanOut({ state: "OFF", color_mode: "white", transition: payload.transition }, trace, originalMsg);
+            rememberRam({ "<<G_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<GD_State>>": "OFF" });
+                console.log(`Disk saved — Group:"${CFG.groupName}"  state:OFF`);
+            });
+        },
+    },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DISPATCH
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Look up and invoke the correct group handler.
+ * @param {string} state        - "ON" or "OFF"
+ * @param {Object} payload      - msg.payload
+ * @param {Object} trace        - dmx_trace to attach to fan-out
+ * @param {Object} originalMsg  - original incoming msg
+ */
+function dispatch(state, payload, trace, originalMsg) {
+    console.log(`Group dispatch — group:"${CFG.groupName}"  state:"${state}"  colorMode:"${CFG.colorModes}"`);
+
+    const stateHandlers = GROUP_HANDLERS[state];
+    if (!stateHandlers) {
+        node.warn(
+            `Group "${CFG.groupName}" dispatch error — unknown state "${state}". ` +
+            `Must be "ON" or "OFF". Check incoming payload from HA.`
+        );
+        return;
+    }
+    const handler = stateHandlers[CFG.colorModes];
+    if (handler === undefined) {
+        node.warn(
+            `Group "${CFG.groupName}" dispatch error — unknown color mode "${CFG.colorModes}" ` +
+            `for state "${state}". Check <HA_supported_color_modes> env var matches ` +
+            `a supported value: onoff, brightness, rgb, rgbw, rgbww, color_temp, white, ` +
+            `rgb\,color_temp, rgbw\,color_temp, rgbww\,color_temp`
+        );
+        return;
+    }
+    handler(payload, trace, originalMsg);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ EFFECTS — synced group effects
+//# The Group Node forwards the effect name downstream so all children receive
+//# the command at the same NR tick, keeping siblings in sync.
+//# Individual fixture effects (sleep_transition, temperature_transition) are
+//# intentionally excluded from the group effects list.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate and forward an effect command to all children.
+ * @param {string} effectName
+ * @param {Object} payload
+ * @param {Object} trace
+ * @param {Object} originalMsg
+ */
+function dispatchGroupEffect(effectName, payload, trace, originalMsg) {
+    if (!CFG.groupEffectsList.includes(effectName.trim())) {
+        node.warn(
+            `Group "${CFG.groupName}" — effect "${effectName}" is not in the group effects list. ` +
+            `Check <HA_group_effects_list> env var.`
+        );
+        return;
+    }
+    console.log(`Group effect forwarding: "${effectName}"  group:"${CFG.groupName}"`);
+    fanOut({ ...payload, effect: effectName }, trace, originalMsg);
+    sendStatus("blue", "dot", `Group effect: ${effectName}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DEVICE REQUEST HANDLERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Write default values to RAM on startup if nothing is stored yet. */
+function initDefaultMemory() {
+    const existing = flow.get("<<G_State>>", "memory") || flow.get("<<GD_State>>", "disk_values");
+    if (existing) {
+        console.log(`initDefaultMemory: existing group state found for "${CFG.groupName}", skipping defaults.`);
+        return;
+    }
+    rememberRam({
+        "<<G_State>>":     CFG.defaultState,
+        "<<G_bright>>":    255,
+        "<<G_red>>":       255,
+        "<<G_green>>":     255,
+        "<<G_blue>>":      255,
+        "<<G_white>>":     255,
+        "<<G_warmWhite>>": 0,
+        "<<G_colorTemp>>": 300,
+    });
+    console.log(`initDefaultMemory: group defaults written for "${CFG.groupName}".`);
+}
+
+/** Clear all RAM and disk memory keys for this group on device remove. */
+function clearAllMemory() {
+    const ramKeys  = ["<<G_State>>",  "<<G_bright>>",  "<<G_red>>",  "<<G_green>>",  "<<G_blue>>",  "<<G_white>>",  "<<G_warmWhite>>",  "<<G_colorTemp>>"];
+    const diskKeys = ["<<GD_State>>", "<<GD_bright>>", "<<GD_red>>", "<<GD_green>>", "<<GD_blue>>", "<<GD_white>>", "<<GD_warmWhite>>", "<<GD_colorTemp>>"];
+    ramKeys.forEach(k  => flow.set(k, null, "memory"));
+    diskKeys.forEach(k => flow.set(k, null, "disk_values"));
+    console.log(`clearAllMemory: group memory cleared for "${CFG.groupName}".`);
+}
+
+/** Build the HA state recovery payload for this group's color mode. */
+function buildRecoveryStatePayload() {
+    const state      = recall("<<G_State>>",     "<<GD_State>>",     CFG.defaultState);
+    const brightness = recall("<<G_bright>>",    "<<GD_bright>>",    255);
+    const red        = recall("<<G_red>>",        "<<GD_red>>",        255);
+    const green      = recall("<<G_green>>",      "<<GD_green>>",      255);
+    const blue       = recall("<<G_blue>>",       "<<GD_blue>>",       255);
+    const white      = recall("<<G_white>>",      "<<GD_white>>",      255);
+    const warmWhite  = recall("<<G_warmWhite>>",  "<<GD_warmWhite>>",  0);
+    const colorTemp  = recall("<<G_colorTemp>>",  "<<GD_colorTemp>>",  300);
+
+    console.log(`Group recovery — "${CFG.groupName}"  state:${state}  bright:${brightness}`);
+
+    const rgb   = { r: red,  g: green, b: blue };
+    const rgbw  = { ...rgb,  w: white };
+    const rgbww = { ...rgbw, ww: warmWhite };
+
+    const map = {
+        "onoff":              { state, color_mode: "onoff" },
+        "brightness":         { state, brightness, color_mode: "brightness" },
+        "rgb":                { state, brightness, color: rgb,   color_mode: "rgb" },
+        "rgbw":               { state, brightness, color: rgbw,  color_mode: "rgbw" },
+        "rgbww":              { state, brightness, color: rgbww, color_mode: "rgbww" },
+        "color_temp":         { state, brightness, color_temp: colorTemp, color_mode: "color_temp" },
+        "white":              { state, brightness, color_mode: "white" },
+        "rgb,color_temp":     { state, brightness, color: rgb,   color_mode: "rgb" },
+        "rgbw,color_temp":    { state, brightness, color: rgbw,  color_mode: "rgbw" },
+        "rgbww,color_temp":   { state, brightness, color: rgbww, color_mode: "rgbww" },
+    };
+
+    return map[CFG.colorModes] ?? null;
+}
+
+function handleDeviceAdd() {
+    initDefaultMemory();
+
+    const colorModesArray = CFG.colorModes.split(',');
+    const cmdTopic        = `${groupTopic}/${CFG.commandTopic}`;
+    const cfgTopic        = `${groupTopic}/${CFG.configTopic}`;
+    const { device: dev } = CFG;
+
+    const discoveryPayload = {
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   cfgTopic,
+        payload: {
+            unique_id:             `group(${CFG.groupUidPrefix}-${CFG.uid}${CFG.uidPostfix})`,
+            schema:                CFG.schema,
+            //^ object_id locks the HA entity_id to the plan ID: light.lg_992
+            object_id:             `${CFG.groupUidPrefix}_${CFG.uid}${CFG.uidPostfix}`.toLowerCase().replace(/[^a-z0-9]/g, '_').replace(/__+/g, '_'),
+            name:                  CFG.groupName || `${dev.type} Group ${dev.situation} the ${CFG.dmxZone} ${dev.area} ${dev.subLocation}`,
+            cmd_t:                 cmdTopic,
+            stat_t:                `${groupTopic}/${CFG.stateTopic}`,
+            optimistic:            CFG.optimistic,
+            enabled_by_default:    CFG.enabledByDefault,
+            icon:                  CFG.icon,
+            supported_color_modes: colorModesArray,
+            brightness:            CFG.brightness,
+            transition:            CFG.transitionsEnabled,
+            effect:                CFG.effects,
+            effect_list:           CFG.groupEffectsList,
+            flash_time_short:      CFG.flashShort,
+            flash_time_long:       CFG.flashLong,
+            min_mireds:            CFG.minMireds,
+            max_mireds:            CFG.maxMireds,
+            device: {
+                identifiers:    `${CFG.component}-${CFG.groupUidPrefix}-${CFG.uid}`,
+                name:           `(${CFG.groupUidPrefix}-${CFG.uid}${CFG.uidPostfix}) - ${dev.type}/s Group ${dev.situation} the ${CFG.dmxZone} - ${dev.area} - ${dev.subLocation}`,
+                model:          `${colorModesArray} ${dev.type}/s Group located ${dev.situation} the ${CFG.dmxZone}-${dev.area} - ${dev.subLocation}`,
+                model_id:       `referenced on plan as: (${CFG.groupUidPrefix}-${CFG.uid}`,
+                suggested_area: `${CFG.dmxZone} ${dev.area} ${dev.subLocation}`,
+                hw_version:     `This is a virtual fixture — no physical hardware. It exists as a DMX Group Node in a Node-RED flow, grouping multiple DMX fixture nodes under a single Home Assistant entity. Changes made here are distributed to all child fixture nodes in the group.`,
+                sw_version:     `${CFG.nodeCode}: ${CFG.nodeSw}`,
+                manufacturer:   "DeSwaggy — Discord: @deswaggy",
+            },
+        },
+    };
+
+    //# Output 1: HA MQTT discovery payload
+    //# Output 2: MQTT subscribe action → MQTT In node
+    //# Output 3: Node status
+    //# Output 5: AUX — forward device:add to child DMX/Group Nodes so they self-discover
+    node.send([
+        discoveryPayload,
+        { retain: CFG.retain, qos: CFG.qos, topic: cmdTopic, action: "subscribe" },
+        { status: { fill: "green", shape: "ring", text: `Group "${CFG.groupName}" discovery sent — awaiting HA` } },
+        null,
+        { device: "add" },
+    ]);
+    console.log(`Group device added: "${CFG.groupName}"`);
+
+    //# Wait briefly before pushing recovery state — gives HA time to register
+    //# the discovery before we report the last-known state.
+    //# Simple setTimeout is correct here — we are not writing to disk, just
+    //# reporting state to HA. The disk save timer is reserved for command handling.
+    setTimeout(() => {
+        const recoveryPayload = buildRecoveryStatePayload();
+        if (recoveryPayload) {
+            sendState(recoveryPayload);
+            sendStatus("yellow", "ring", `Group "${CFG.groupName}" ready — awaiting HA commands`);
+            console.log(`Group recovery state sent — "${CFG.groupName}"  mode:${CFG.colorModes}`);
+        } else {
+            sendStatus("yellow", "ring", `Group "${CFG.groupName}" ready — awaiting HA commands`);
+        }
+    }, 2000);
+}
+
+function handleDeviceRemove() {
+    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: `${groupTopic}/${CFG.configTopic}`, payload: "" },
+        { retain: CFG.retain, qos: CFG.qos, topic: `${groupTopic}/${CFG.commandTopic}`, action: "unsubscribe" },
+        { status: { fill: "red", shape: "ring", text: `Group "${CFG.groupName}" removed — memory cleared` } },
+        null,
+        { device: "remove" },
+    ]);
+    console.log(`Group device removed: "${CFG.groupName}"`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!? ENTRY POINT
+// ─────────────────────────────────────────────────────────────────────────────
+
+//# Pass original message through on output 4 untouched
+node.send([null, null, null, msg, null]);
+
+const prevGroupState = recall("<<G_State>>", "<<GD_State>>", CFG.defaultState);
+console.log(`Group:"${CFG.groupName}"  prev state:${prevGroupState}  colorMode:${CFG.colorModes}`);
+
+//? ── AUX — payload received from a parent Group Node ─────────────────────────
+if (msg.dmx_trace != null) {
+    console.log(
+        `AUX received — from:"${msg.dmx_trace.source}"  ` +
+        `path:[${msg.dmx_trace.path.join(' → ')}]  depth:${msg.dmx_trace.depth}`
+    );
+
+    //# Loop detection — check BEFORE building a new trace
+    if (isLoopDetected(msg.dmx_trace)) {
+        node.done();
+        return;
+    }
+
+    //# Build updated trace — this node adds itself to the ancestry path
+    const trace = buildTrace(msg.dmx_trace);
+
+    if (msg.payload?.effect && CFG.effects) {
+        dispatchGroupEffect(msg.payload.effect, msg.payload, trace, msg);
+    } else if (msg.payload?.state != null) {
+        const wantTransition = msg.payload.transition && CFG.transitionsEnabled;
+        console.log(`AUX dispatch — state:${msg.payload.state}  transition:${wantTransition}`);
+        dispatch(msg.payload.state, msg.payload, trace, msg);
+    } else {
+        node.warn(
+            `Group "${CFG.groupName}" — AUX payload from "${msg.dmx_trace.source}" ` +
+            `had no valid state or effect — message dropped.`
+        );
+    }
+
+//? ── DIRECT HA COMMAND — payload.state from MQTT in ─────────────────────────
+} else if (msg.payload?.state != null) {
+    //# Guard: if payload is still a string, MQTT In node is not set to parse JSON
+    if (typeof msg.payload === 'string') {
+        node.warn(
+            `Group "${CFG.groupName}" — msg.payload is a string, not a parsed object. ` +
+            `Check the MQTT In node is configured with Output: "a parsed JSON object". ` +
+            `Raw payload: ${msg.payload}`
+        );
+        node.done();
+        return;
+    }
+
+    const { state, transition, effect } = msg.payload;
+
+    //# Origin node — build a fresh trace starting at depth 1
+    const trace = buildTrace(null);
+
+    if (effect && CFG.effects) {
+        console.log(`Group effect received: "${effect}"  group:"${CFG.groupName}"`);
+        dispatchGroupEffect(effect, msg.payload, trace, msg);
+    } else {
+        const wantTransition = transition && CFG.transitionsEnabled;
+        console.log(`Direct HA command — state:${state}  transition:${wantTransition}  mode:${CFG.colorModes}`);
+        dispatch(state, msg.payload, trace, msg);
+    }
+
+//? ── DEVICE REQUEST — add / remove / debug ───────────────────────────────────
+} else if (msg.device != null && (msg.device?.request != null || typeof msg.device === "string")) {
+    const _devReq = typeof msg.device === "string" ? msg.device : msg.device.request;
+    console.log(`device.request: ${_devReq}  group:"${CFG.groupName}"`);
+    switch (_devReq) {
+        case "add":    handleDeviceAdd();    break;
+        case "remove": handleDeviceRemove(); break;
+        case "debug":  console.log("DEBUG:", JSON.stringify(msg)); break;
+        default:       node.warn(`Group "${CFG.groupName}" — unknown device.request: "${msg.device.request}"`);
+    }
+
+//? ── UNKNOWN MESSAGE ─────────────────────────────────────────────────────────
+} else {
+    node.warn(
+        `DMX Group Node "${CFG.groupName}" — unrecognised message. ` +
+        `Expected: msg.dmx_trace (AUX from parent 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];