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

package/nodes/ha-mqtt-dmx-group.html

@@ -0,0 +1,392 @@
+<!-- ============================================================
+     ha-mqtt-dmx-group — DMX Group Node Editor
+     Package: node-red-contrib-dmx-for-ha
+     Author:  DeSwaggy — Discord: @deswaggy
+     ============================================================ -->
+
+<script type="text/javascript">
+
+    RED.nodes.registerType('ha-mqtt-dmx-group', {
+        category:     'DMX for HA',
+        color:        '#9b3fd4',
+        icon:         'font-awesome/fa-object-group',
+        inputs:       1,
+        outputs:      1,
+        outputLabels: ['Link'],
+        inputLabels:  ['Input'],
+        paletteLabel: 'DMX Group',
+
+        defaults: {
+            name:         { value: '' },
+            config:       { value: '', type: 'ha-mqtt-config', required: true },
+            // Group identity
+            groupName:    { value: '' },
+            uid:          { value: '',    required: true },
+            uidPostfix:   { value: '' },
+            deviceType:   { value: 'Downlight' },
+            colorMode:    { value: 'rgbw' },
+            // Location
+            area:         { value: 'Area 52' },
+            situation:    { value: 'in' },
+            subLocation:  { value: '' },
+            // Options
+            haIcon:       { value: 'mdi:lightbulb-group' },
+            showEffects:  { value: true },
+            transitions:  { value: true },
+            defaultState: { value: 'OFF' },
+            // Advanced
+            maxDepth:     { value: '10' },
+        },
+
+        label: function () {
+            if (this.name) return this.name;
+            const id      = this.uid      || '?';
+            const postfix = this.uidPostfix || '';
+            return 'LG-' + id + postfix;
+        },
+
+        labelStyle: function () {
+            return this.name ? 'node_label_italic' : '';
+        },
+
+        oneditprepare: function () {
+            // Reuse area/sub-area lists from ha-mqtt-dmx if loaded,
+            // otherwise define inline
+            const areas = typeof HA_DMX_AREAS !== 'undefined' ? HA_DMX_AREAS : [
+                { v: 'Area 52',             l: 'TBC' },
+                { v: 'Attic Roof',          l: 'Attic Roof' },
+                { v: 'Backyard',            l: 'Backyard' },
+                { v: 'Balcony',             l: 'Balcony' },
+                { v: 'Bathroom',            l: 'Bathroom' },
+                { v: 'Bedroom 1',           l: 'Bedroom 1' },
+                { v: 'Bedroom 2',           l: 'Bedroom 2' },
+                { v: 'Bedroom 3',           l: 'Bedroom 3' },
+                { v: 'Bedroom 4',           l: 'Bedroom 4' },
+                { v: 'Carport',             l: 'Carport' },
+                { v: 'Cellar',              l: 'Cellar' },
+                { v: 'Dining',              l: 'Dining' },
+                { v: 'Driveway',            l: 'Driveway' },
+                { v: 'Entry',               l: 'Entry' },
+                { v: 'Garage',              l: 'Garage' },
+                { v: 'Gym',                 l: 'Gym' },
+                { v: 'Hallway',             l: 'Hallway' },
+                { v: 'Kitchen',             l: 'Kitchen' },
+                { v: 'Laundry',             l: 'Laundry' },
+                { v: 'Link Bridge (Upper)', l: 'Link Bridge Upper' },
+                { v: 'Link Bridge (Lower)', l: 'Link Bridge Lower' },
+                { v: 'Living',              l: 'Living' },
+                { v: 'Media',               l: 'Media' },
+                { v: 'Office',              l: 'Office' },
+                { v: 'Pantry',              l: 'Pantry' },
+                { v: 'Pass Over',           l: 'Pass Over' },
+                { v: 'Pass Under',          l: 'Pass Under' },
+                { v: 'Passageway',          l: 'Passageway' },
+                { v: 'Pool',                l: 'Pool' },
+                { v: 'Portico',             l: 'Portico' },
+                { v: 'PowderRoom',          l: 'PowderRoom' },
+                { v: 'Reading',             l: 'Reading' },
+                { v: 'Rumpus',              l: 'Rumpus' },
+                { v: 'Spa',                 l: 'Spa' },
+                { v: 'Stairs',              l: 'Stairs' },
+                { v: 'Store',               l: 'Store' },
+                { v: 'SubFloor',            l: 'SubFloor' },
+                { v: 'Terrace',             l: 'Terrace' },
+            ];
+
+            const subAreas = typeof HA_DMX_SUB_AREAS !== 'undefined' ? HA_DMX_SUB_AREAS : [
+                { v: '',              l: 'None' },
+                { v: 'Balcony',       l: 'Balcony' },
+                { v: 'Bed (North)',   l: 'Bed North' },
+                { v: 'Bed (South)',   l: 'Bed South' },
+                { v: 'Bed (East)',    l: 'Bed East' },
+                { v: 'Bed (West)',    l: 'Bed West' },
+                { v: 'Ceiling',       l: 'Ceiling' },
+                { v: 'Dress',         l: 'Dress' },
+                { v: 'Ensuite',       l: 'Ensuite' },
+                { v: 'Exterior',      l: 'Exterior' },
+                { v: 'Ground Floor',  l: 'Ground Floor' },
+                { v: '1st Floor',     l: '1st Floor' },
+                { v: 'Landing',       l: 'Landing' },
+                { v: 'Office',        l: 'Office' },
+                { v: 'Stairs',        l: 'Stairs' },
+                { v: 'WIR',           l: 'WIR' },
+                { v: '(North)',        l: 'North' },
+                { v: '(South)',        l: 'South' },
+                { v: '(East)',         l: 'East' },
+                { v: '(West)',         l: 'West' },
+                { v: 'Void',          l: 'Void' },
+            ];
+
+            // Populate dropdowns
+            const node = this;
+
+            const areaEl = $('#node-input-area');
+            areaEl.empty();
+            areas.forEach(function (a) {
+                areaEl.append($('<option>').val(a.v).text(a.l)
+                    .prop('selected', a.v === node.area));
+            });
+
+            const subEl = $('#node-input-subLocation');
+            subEl.empty();
+            subAreas.forEach(function (s) {
+                subEl.append($('<option>').val(s.v).text(s.l)
+                    .prop('selected', s.v === node.subLocation));
+            });
+        },
+    });
+
+</script>
+
+<!-- ============================================================
+     Editor Panel Template
+     ============================================================ -->
+<script type="text/html" data-template-name="ha-mqtt-dmx-group">
+
+    <!-- NAME -->
+    <div class="form-row">
+        <label for="node-input-name">
+            <i class="fa fa-tag"></i> Name
+        </label>
+        <input type="text" id="node-input-name"
+               placeholder="Optional — defaults to LG-992 on canvas" />
+    </div>
+
+    <!-- CONFIG -->
+    <div class="form-row">
+        <label for="node-input-config">
+            <i class="fa fa-cog"></i> Config
+        </label>
+        <input type="text" id="node-input-config" />
+    </div>
+
+    <hr/>
+
+    <!-- ── GROUP (* Required) ────────────────────────────────── -->
+    <div class="form-row">
+        <label style="width:100%; font-weight:bold; color:#999; font-size:0.85em; text-transform:uppercase; letter-spacing:0.05em;">
+            <i class="fa fa-object-group"></i> Group &nbsp;<span style="color:#e74c3c">* Required</span>
+        </label>
+    </div>
+
+    <!-- Group Name -->
+    <div class="form-row">
+        <label for="node-input-groupName">
+            <i class="fa fa-object-group"></i> Group Name
+        </label>
+        <input type="text" id="node-input-groupName"
+               placeholder="e.g. Bedroom 1 Downlights"
+               style="width:55%" />
+        <div style="margin-left:106px; margin-top:4px; color:#999; font-size:0.85em;">
+            Shown as the HA entity friendly name
+        </div>
+    </div>
+
+    <!-- Group ID -->
+    <div class="form-row">
+        <label for="node-input-uid">
+            <i class="fa fa-tv"></i> Group ID
+        </label>
+        <span style="margin-right:4px; font-weight:bold;">LG -</span>
+        <input type="text" id="node-input-uid"
+               placeholder="992" style="width:70px"
+               title="Cable/plan ID number — prefix LG is fixed for groups" />
+        &nbsp;
+        <select id="node-input-uidPostfix" style="width:65px">
+            <option value="">(none)</option>
+            <option value="-A">-A</option>
+            <option value="-B">-B</option>
+            <option value="-C">-C</option>
+            <option value="-D">-D</option>
+        </select>
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            Plan ID — Channel (if applicable)
+        </span>
+    </div>
+
+    <!-- Device Type -->
+    <div class="form-row">
+        <label for="node-input-deviceType">
+            <i class="fa fa-lightbulb-o"></i> Device Type
+        </label>
+        <input type="text" id="node-input-deviceType"
+               placeholder="e.g. Downlight, Strip light, Panel"
+               style="width:55%" />
+    </div>
+
+    <!-- Colour Mode -->
+    <div class="form-row">
+        <label for="node-input-colorMode">
+            <i class="fa fa-sliders"></i> Colour Mode
+        </label>
+        <select id="node-input-colorMode" style="width:55%">
+            <option value="rgbw">RGBW</option>
+            <option value="rgbww">RGBWW</option>
+            <option value="rgb">RGB</option>
+            <option value="color_temp">Colour Temperature (CCT)</option>
+            <option value="brightness">Brightness only</option>
+            <option value="onoff">On/Off only</option>
+        </select>
+    </div>
+
+    <!-- Area -->
+    <div class="form-row">
+        <label for="node-input-area">
+            <i class="fa fa-map-marker"></i> Area
+        </label>
+        <select id="node-input-area" style="width:55%"></select>
+    </div>
+
+    <!-- Situation -->
+    <div class="form-row">
+        <label for="node-input-situation">
+            <i class="fa fa-compass"></i> Situation
+        </label>
+        <select id="node-input-situation" style="width:55%">
+            <option value="in">in</option>
+            <option value="above">above</option>
+            <option value="below">below</option>
+            <option value="outside">outside</option>
+            <option value="throughout">throughout</option>
+            <option value="under">under</option>
+            <option value="over">over</option>
+        </select>
+    </div>
+
+    <!-- Sub-Area -->
+    <div class="form-row">
+        <label for="node-input-subLocation">
+            <i class="fa fa-map-marker"></i> Sub-Area
+        </label>
+        <select id="node-input-subLocation" style="width:55%"></select>
+    </div>
+
+    <hr/>
+
+    <!-- ── OPTIONS ───────────────────────────────────────────── -->
+    <div class="form-row">
+        <label style="width:100%; font-weight:bold; color:#999; font-size:0.85em; text-transform:uppercase; letter-spacing:0.05em;">
+            <i class="fa fa-sliders"></i> Options
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-haIcon">
+            <i class="fa fa-image"></i> HA Icon
+        </label>
+        <input type="text" id="node-input-haIcon"
+               placeholder="mdi:lightbulb-group" style="width:55%" />
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-defaultState">
+            <i class="fa fa-toggle-off"></i> Default state
+        </label>
+        <select id="node-input-defaultState" style="width:100px">
+            <option value="OFF">OFF</option>
+            <option value="ON">ON</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-showEffects"
+               style="width:auto; margin-right:8px" />
+        <label for="node-input-showEffects" style="width:auto">
+            Show effects in HA
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-transitions"
+               style="width:auto; margin-right:8px" />
+        <label for="node-input-transitions" style="width:auto">
+            Enable transitions
+        </label>
+    </div>
+
+    <hr/>
+
+    <!-- ── ADVANCED ──────────────────────────────────────────── -->
+    <div class="form-row">
+        <label style="width:100%; font-weight:bold; color:#999; font-size:0.85em; text-transform:uppercase; letter-spacing:0.05em;">
+            <i class="fa fa-wrench"></i> Advanced
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-maxDepth">
+            <i class="fa fa-sort-numeric-asc"></i> Max group depth
+        </label>
+        <input type="number" id="node-input-maxDepth"
+               min="0" max="20" style="width:70px" />
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            0 = disable loop detection
+        </span>
+    </div>
+
+</script>
+
+<!-- ============================================================
+     Help Panel
+     ============================================================ -->
+<script type="text/html" data-help-name="ha-mqtt-dmx-group">
+    <p>
+        Virtual DMX group. Appears as a single light entity in Home Assistant.
+        Commands received from HA are forwarded via the <strong>Link</strong>
+        output to all downstream DMX and Relay nodes.
+    </p>
+
+    <h3>Setup</h3>
+    <ol>
+        <li>Select your <strong>Config</strong> node</li>
+        <li>Set a <strong>Group Name</strong> — shown as the HA entity friendly name</li>
+        <li>Set <strong>Group ID</strong> — matches the plan ID (prefix LG is fixed)</li>
+        <li>Wire the <strong>Link</strong> output to the input of each DMX or Relay node in the group</li>
+        <li>Deploy — the group entity appears in HA</li>
+    </ol>
+
+    <h3>Group ID</h3>
+    <p>
+        The <code>LG</code> prefix is fixed for all group nodes — it matches the
+        electrical plan convention where <code>L-992-A</code>, <code>L-992-B</code>
+        and <code>L-992-C</code> form group <code>LG-992</code>.
+    </p>
+
+    <h3>Link output</h3>
+    <p>
+        Wire the Link output to one or more DMX or Relay node inputs.
+        You can also wire it to another DMX Group Node input to create
+        a nested group hierarchy.
+    </p>
+
+    <h3>Loop detection</h3>
+    <p>
+        The node tracks the cascade path in <code>msg.dmx_trace</code> and
+        fires a warning if a loop is detected. Max group depth sets the
+        maximum number of hops before a loop is assumed. Set to 0 to disable.
+    </p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>device:add <span class="property-type">msg.device = "add"</span></dt>
+        <dd>Run MQTT discovery and forward device:add to child nodes via Link.</dd>
+        <dt>device:remove <span class="property-type">msg.device = "remove"</span></dt>
+        <dd>Remove entity from HA and forward device:remove to child nodes.</dd>
+        <dt>HA command <span class="property-type">msg.payload.state</span></dt>
+        <dd>Handled internally via MQTT — forwarded to children via Link.</dd>
+        <dt>Cascade <span class="property-type">msg.dmx_trace</span></dt>
+        <dd>Command from an upstream Group Node — forwarded deeper into hierarchy.</dd>
+    </dl>
+
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>Link <span class="property-type">object</span></dt>
+        <dd>
+            Forwards commands to child nodes. Message includes
+            <code>msg.dmx_trace</code> (source, path, depth) and
+            the original <code>msg.payload</code> unchanged.
+        </dd>
+    </dl>
+</script>

package/nodes/ha-mqtt-dmx-group.js

@@ -0,0 +1,265 @@
+// ============================================================
+// ha-mqtt-dmx-group — DMX Group Node Runtime
+// Package: node-red-contrib-dmx-for-ha
+// Author:  DeSwaggy — Discord: @deswaggy
+//
+// Virtual group node. Receives HA commands and forwards
+// them to child DMX/Relay nodes via the Link output port.
+// ============================================================
+
+module.exports = function (RED) {
+
+    function HaMqttDmxGroupNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // ── Config & broker ───────────────────────────────────────
+        const cfg = RED.nodes.getNode(config.config);
+        if (!cfg) { node.error('DMX Group: no config node selected'); return; }
+
+        const broker = RED.nodes.getNode(cfg.broker);
+        if (!broker) { node.error('DMX Group: no MQTT broker in config'); return; }
+
+        broker.register(node);
+
+        // ── Node settings ─────────────────────────────────────────
+        const S = {
+            groupName:    config.groupName    || '',
+            uid:          config.uid          || '',
+            uidPostfix:   config.uidPostfix    || '',
+            deviceType:   config.deviceType    || 'Downlight',
+            colorMode:    config.colorMode     || 'rgbw',
+            area:         config.area          || '',
+            situation:    config.situation      || 'in',
+            subLocation:  config.subLocation    || '',
+            haIcon:       config.haIcon         || 'mdi:lightbulb-group',
+            showEffects:  config.showEffects    !== false,
+            transitions:  config.transitions    !== false,
+            defaultState: config.defaultState   || 'OFF',
+            maxDepth:     parseInt(config.maxDepth) || 10,
+            flashShort:   cfg.flashShort,
+            flashLong:    cfg.flashLong,
+            diskDelay:    cfg.diskDelay,
+        };
+
+        const groupId      = `LG-${S.uid}${S.uidPostfix}`;
+        const objectId     = `lg_${S.uid}${S.uidPostfix}`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const groupTopic   = `${cfg.discoveryPrefix}/light/${groupId}`;
+        const cfgTopic     = `${groupTopic}/${cfg.configTopic}`;
+        const statTopic    = `${groupTopic}/${cfg.stateTopic}`;
+        const cmdTopic     = `${groupTopic}/${cfg.commandTopic}`;
+
+        // ── Context helpers ───────────────────────────────────────
+        function ctxGet(key, store) {
+            try { return node.context().get(key, store); }
+            catch(e) { return node.context().get(key); }
+        }
+        function ctxSet(key, val, store) {
+            try { node.context().set(key, val, store); }
+            catch(e) { node.context().set(key, val); }
+        }
+        function recall(ramKey, diskKey, fallback) {
+            return ctxGet(ramKey) || ctxGet(diskKey, 'disk') || fallback;
+        }
+
+        // ── Disk save timer ───────────────────────────────────────
+        let diskTimer = null;
+        function startDiskSave(onComplete) {
+            if (diskTimer) { clearTimeout(diskTimer); diskTimer = null; }
+            diskTimer = setTimeout(() => { diskTimer = null; onComplete(); }, S.diskDelay * 1000);
+        }
+
+        // ── MQTT helpers ──────────────────────────────────────────
+        function pub(topic, payload, retain) {
+            broker.publish({
+                topic,
+                payload: typeof payload === 'object' ? JSON.stringify(payload) : String(payload),
+                qos:    cfg.qos,
+                retain: retain !== undefined ? retain : cfg.retain,
+            });
+        }
+
+        function pubState(payload) {
+            pub(statTopic, JSON.stringify(payload), false);
+        }
+
+        function setStatus(fill, shape, text) {
+            node.status({ fill, shape, text });
+        }
+
+        // ── Loop detection ────────────────────────────────────────
+        function isLoop(trace) {
+            if (!trace || !trace.path) return false;
+            if (S.maxDepth > 0 && trace.depth >= S.maxDepth) return true;
+            return trace.path.includes(groupId);
+        }
+
+        function buildTrace(incomingTrace) {
+            if (incomingTrace) {
+                return {
+                    source: groupId,
+                    path:   [...incomingTrace.path, groupId],
+                    depth:  incomingTrace.depth + 1,
+                };
+            }
+            return { source: groupId, path: [groupId], depth: 1 };
+        }
+
+        // ── Forward to children via Link output ───────────────────
+        function forwardToChildren(payload, incomingTrace) {
+            if (isLoop(incomingTrace)) {
+                node.warn(`${groupId} — loop detected! path:[${incomingTrace && incomingTrace.path.join(' → ')}]`);
+                setStatus('red', 'dot', `${groupId} LOOP DETECTED`);
+                return;
+            }
+            const trace = buildTrace(incomingTrace);
+            node.send([{ dmx_trace: trace, payload }]);
+        }
+
+        // ── Effects ───────────────────────────────────────────────
+        const EFFECT_LIST = [
+            'none', 'flash_short', 'flash_long', 'strobe',
+            'rainbow', 'rainbow_rgbw', 'fire', 'flicker',
+            'twinkle', 'color_chase', 'scan', 'random',
+            'police', 'christmas', 'halloween', 'calaveras',
+            'party', 'fireworks',
+        ];
+
+        // ── Group state save ──────────────────────────────────────
+        function saveGroupState(payload) {
+            ctxSet('state',      payload.state);
+            ctxSet('brightness', payload.brightness);
+            ctxSet('color',      payload.color);
+            ctxSet('transition', payload.transition);
+            startDiskSave(() => {
+                ctxSet('state',      payload.state,      'disk');
+                ctxSet('brightness', payload.brightness, 'disk');
+                ctxSet('color',      payload.color,      'disk');
+                node.log(`${groupId} disk saved — state:${payload.state}`);
+            });
+        }
+
+        // ── Device add ────────────────────────────────────────────
+        function handleDeviceAdd(incomingTrace) {
+            if (!ctxGet('state') && !ctxGet('state', 'disk')) {
+                ctxSet('state', S.defaultState);
+            }
+
+            const discovery = {
+                unique_id:           `group(${groupId})`,
+                schema:              'json',
+                object_id:           objectId,
+                optimistic:          false,
+                enabled_by_default:  cfg.enabledDefault,
+                icon:                S.haIcon,
+                supported_color_modes: [S.colorMode],
+                brightness:          true,
+                transition:          S.transitions,
+                effect:              S.showEffects,
+                effect_list:         S.showEffects ? EFFECT_LIST : [],
+                flash_time_short:    S.flashShort,
+                flash_time_long:     S.flashLong,
+                min_mireds:          153,
+                max_mireds:          500,
+                stat_t:              statTopic,
+                cmd_t:               cmdTopic,
+                name:                S.groupName || `${S.deviceType} Group ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                device: {
+                    identifiers:    `light-${groupId}`,
+                    name:           `(${groupId}) - ${S.deviceType} Group ${S.situation} the ${cfg.zone} - ${S.area} - ${S.subLocation}`,
+                    model:          `${S.colorMode} ${S.deviceType} Group located ${S.situation} the ${cfg.zone} - ${S.area}`,
+                    model_id:       `referenced on plan as: (${groupId}`,
+                    suggested_area: `${cfg.zone} ${S.area} ${S.subLocation}`,
+                    hw_version:     'Virtual fixture — exists as a DMX Group Node in Node-RED',
+                    sw_version:     'ha-mqtt-dmx-group: 0.1.0',
+                    manufacturer:   'DeSwaggy — Discord: @deswaggy',
+                },
+            };
+
+            pub(cfgTopic, discovery, true);
+
+            broker.subscribe(cmdTopic, cfg.qos, function (topic, rawPayload) {
+                let payload;
+                try { payload = JSON.parse(rawPayload.toString()); }
+                catch(e) { node.warn(`${groupId} — failed to parse HA command`); return; }
+
+                saveGroupState(payload);
+                pubState({ state: payload.state, color_mode: S.colorMode, brightness: payload.brightness });
+                forwardToChildren(payload, null);
+            }, node.id);
+
+            setStatus('green', 'ring', `${groupId} discovery sent`);
+            node.log(`Group device added: "${S.groupName || groupId}"`);
+
+            // Children receive device:add directly from the SYSTEM node
+            // No forwarding needed via Link
+
+            // Recovery
+            setTimeout(() => {
+                const state      = recall('state',      'state_disk',      S.defaultState);
+                const brightness = recall('brightness', 'brightness_disk', 255);
+                const color      = recall('color',      'color_disk',      null);
+                pubState({ state, color_mode: S.colorMode, brightness, color });
+                forwardToChildren({ state, brightness, color }, null);
+                setStatus('yellow', 'ring', `${groupId} ready`);
+                node.log(`${groupId} recovery — state:${state}`);
+            }, 2000);
+        }
+
+        // ── Device remove ─────────────────────────────────────────
+        function handleDeviceRemove(incomingTrace) {
+            if (diskTimer) { clearTimeout(diskTimer); diskTimer = null; }
+            ctxSet('state', null); ctxSet('state', null, 'disk');
+            pub(cfgTopic, '', true);
+            broker.unsubscribe(cmdTopic, node.id);
+            forwardToChildren({ device: 'remove' }, incomingTrace);
+            setStatus('red', 'ring', `${groupId} removed`);
+            node.log(`${groupId} device removed`);
+        }
+
+        // ── NR input entry point ──────────────────────────────────
+        node.on('input', function (msg, send, done) {
+            // AUX cascade from upstream Group Node
+            if (msg.dmx_trace != null) {
+                if (isLoop(msg.dmx_trace)) {
+                    node.warn(`${groupId} — loop detected`);
+                    done(); return;
+                }
+                // Forward payload deeper
+                if (msg.payload) {
+                    saveGroupState(msg.payload);
+                    pubState({ state: msg.payload.state, color_mode: S.colorMode, brightness: msg.payload.brightness });
+                    forwardToChildren(msg.payload, msg.dmx_trace);
+                }
+            } else {
+                const devReq = typeof msg.device === 'string'
+                    ? msg.device
+                    : (msg.device && msg.device.request);
+
+                if (devReq) {
+                    switch (devReq) {
+                        case 'add':    handleDeviceAdd(null);    break;
+                        case 'remove': handleDeviceRemove(null); break;
+                        default: node.warn(`${groupId} — unknown device.request: "${devReq}"`);
+                    }
+                } else if (msg.payload && msg.payload.state != null) {
+                    saveGroupState(msg.payload);
+                    pubState({ state: msg.payload.state, color_mode: S.colorMode, brightness: msg.payload.brightness });
+                    forwardToChildren(msg.payload, null);
+                } else {
+                    node.warn(`${groupId} — unrecognised message received and dropped. See node documentation.`);
+                }
+            }
+            done();
+        });
+
+        // ── Cleanup ───────────────────────────────────────────────
+        node.on('close', function (done) {
+            if (diskTimer) clearTimeout(diskTimer);
+            broker.unsubscribe(cmdTopic, node.id);
+            broker.deregister(node, done);
+        });
+    }
+
+    RED.nodes.registerType('ha-mqtt-dmx-group', HaMqttDmxGroupNode);
+};