node-red-contrib-dmx-for-ha 0.2.3 → 0.3.0

package/README.md

@@ -231,6 +231,45 @@ Guest Wing config  → Zone: GuestWing → topics: home/GuestWing/dmx/1
 
 ---
 
+## Transition rate tuning
+
+The config node has two global transition settings that apply to all DMX nodes in the zone:
+
+### Transition rate limit
+
+Controls the tick rate multiplier for all transitions and effects:
+
+```
+ticksPerSec (per node) × rateLimit (config) = effectiveTicks/sec
+```
+
+| Rate Limit | Effective ticks/sec | MQTT msgs/sec (RGBW × 30 nodes) | Use case |
+|---|---|---|---|
+| 1.0 | 31 | ~3,700 | Small deployment, fast hardware |
+| 0.5 | 15 | ~1,800 | Medium deployment, balanced |
+| 0.25 | 7 | ~840 | Large deployment, light load |
+| 0.1 | 3 | ~360 | Maximum scale, minimal load |
+
+Reduce `transitionRateLimit` if you observe:
+- MQTT broker lag or dropped messages
+- NR event loop warnings
+- DMX controller missing channel updates
+- Sluggish HA response during scene changes
+
+### HA UI transition time
+
+Fallback transition duration (seconds) used when HA sends a command with no
+transition specified. Default 1 second.
+
+```
+HA sends transition=3 → use 3 seconds
+HA sends no transition → use haUiTime (default 1s)
+```
+
+Set to `0` to make all un-timed commands instant.
+
+---
+
 ## Troubleshooting
 
 **Nodes don't appear in palette** — Restart Node-RED. Check log for errors.

package/nodes/ha-mqtt-button.html

@@ -47,6 +47,7 @@
             haIcon:         { value: 'mdi:gesture-tap-button' },
             ledColor:       { value: 'Blue' },
             holdTime:       { value: '0.5' },
+            debugMode:      { value: false },
         },
 
         label: function () {
@@ -275,6 +276,18 @@
         <span style="margin-left:8px; color:#999; font-size:0.85em;">HA auto-clears binary_sensor after this delay</span>
     </div>
 
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-debugMode"
+               style="width:auto; margin-right:8px" />
+        <label for="node-input-debugMode" style="width:auto">
+            Debug output to NR debug tab
+        </label>
+        <div style="margin-left:106px; margin-top:4px; color:#e74c3c; font-size:0.8em;">
+            ⚠ Disable in production — logs every MQTT publish
+        </div>
+    </div>
+
     <div style="margin-top:16px; padding-top:8px; border-top:1px solid #444; color:#666; font-size:0.8em; text-align:right;">
         node-red-contrib-dmx-for-ha &nbsp;v0.2.2
     </div>

package/nodes/ha-mqtt-button.js

@@ -5,6 +5,10 @@
 // ============================================================
 
 module.exports = function (RED) {
+    // Package version — read once at module load
+    const PKG_VERSION = require('path').join(__dirname, '../package.json');
+    const _pkgVer = (() => { try { return require(PKG_VERSION).version; } catch(e) { return '?'; } })();
+
 
     function HaMqttButtonNode(config) {
         RED.nodes.createNode(this, config);
@@ -79,12 +83,13 @@ module.exports = function (RED) {
             haIcon:         config.haIcon            || 'mdi:gesture-tap-button',
             ledColor:       config.ledColor          || 'Blue',
             holdTime:       parseFloat(config.holdTime) || 0.5,
+            debugMode:     config.debugMode === true,
         };
 
         const fixtureId    = `S-${S.uid}${S.uidPostfix}`;
         const objectId     = `s_${S.uid}${S.uidPostfix}`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
-        const fixtureTopic = `${cfg.discoveryPrefix}/binary_sensor/${fixtureId}`;
-        const uiBtnTopic   = `${cfg.discoveryPrefix}/button/${fixtureId}-BTN`;
+        const fixtureTopic = cfg.buildTopic(cfg.discoveryPrefix, 'binary_sensor', fixtureId);
+        const uiBtnTopic   = cfg.buildTopic(cfg.discoveryPrefix, 'button', fixtureId + '-BTN');
         const cfgTopic     = `${fixtureTopic}/${cfg.configTopic}`;
         const statTopic    = `${fixtureTopic}/${cfg.stateTopic}`;
         const uiBtnCfgTopic = `${uiBtnTopic}/${cfg.configTopic}`;
@@ -92,12 +97,14 @@ module.exports = function (RED) {
 
         // ── Helpers ───────────────────────────────────────────────
         function pub(topic, payload, retain) {
+            const strPayload = typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
             broker.publish({
                 topic,
-                payload: typeof payload === 'object' ? JSON.stringify(payload) : String(payload),
+                payload: strPayload,
                 qos:    cfg.qos,
                 retain: retain !== undefined ? retain : cfg.retain,
             });
+            if (S.debugMode) node.debug(`${fixtureId} → ${topic}  ${strPayload.substring(0, 120)}`);
         }
 
         function setStatus(fill, shape, text) {
@@ -117,20 +124,20 @@ module.exports = function (RED) {
             const bsDiscovery = {
                 unique_id:          fixtureId,
                 object_id:          objectId,
-                name:               `${S.buttonPosition} button ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                name:               `button ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                 stat_t:             statTopic,
                 off_delay:          S.holdTime,
                 enabled_by_default: true,
                 icon:               S.haIcon,
                 device: {
                     identifiers:    `binary_sensor-${fixtureId}`,
-                    name:           `(${fixtureId}) - Wall Button ${S.situation} the ${cfg.zone} - ${S.area} - ${S.subLocation}`,
+                    name:           `(${fixtureId}) - Wall Button ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                     model:          `Wall button located ${S.situation} the ${cfg.zone} - ${S.area}`,
                     model_id:       `referenced on plan as: (${fixtureId}`,
-                    suggested_area: discoveryMode !== 'hidden' ? `${cfg.zone} ${S.area} ${S.subLocation}` : undefined,
+                    suggested_area: discoveryMode !== 'hidden' ? buildLocation(cfg.zone, S.area, S.subLocation) : undefined,
                     hw_version:     `Wall button — ${S.ledColor} LED. Publishes "${S.buttonPayload}" on topic: ${S.subscribeTopic}`,
                     serial_number:  `(${fixtureId}) Payload: ${S.buttonPayload}`,
-                    sw_version:     'ha-mqtt-button: 0.1.0',
+                    sw_version:     `ha-mqtt-button: ${_pkgVer}`,
                     manufacturer:   'DeSwaggy — Discord: @deswaggy',
                 },
             };
@@ -139,7 +146,7 @@ module.exports = function (RED) {
             const uiDiscovery = {
                 unique_id:          `${fixtureId}-BTN`,
                 object_id:          `${objectId}_btn`,
-                name:               `${S.buttonPosition} (UI) ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                name:               `${S.buttonPosition} (UI) ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                 cmd_t:              uiBtnCmdTopic,
                 payload_press:      'PRESS',
                 enabled_by_default: true,
@@ -202,6 +209,19 @@ module.exports = function (RED) {
     }
 
 
+
+    // ── Location string helper ─────────────────────────────────────────────
+    function buildLocation(zone, area, subLoc) {
+        // Strip parentheses from sub-area values e.g. "(North)" → "North"
+        const sub = (subLoc || '').replace(/[()]/g, '').trim();
+        const areaClean = (area || '').trim();
+        // Skip sub-area if empty or same as area (prevents "Stairs - Stairs")
+        if (!sub || sub.toLowerCase() === areaClean.toLowerCase()) {
+            return `${zone} ${areaClean}`.trim();
+        }
+        return `${zone} ${areaClean} - ${sub}`.trim();
+    }
+
     // ── HTTP endpoint for canvas toggle button ───────────────────────────────
     RED.httpAdmin.post('/ha-mqtt-button/:id/toggle', RED.auth.needsPermission('ha-mqtt-button.write'), function(req, res) {
         const n = RED.nodes.getNode(req.params.id);

package/nodes/ha-mqtt-config.html

@@ -10,7 +10,7 @@
         defaults: {
             name:            { value: '',             required: true },
             siteId:          { value: '',             required: true },
-            zone:            { value: '',             required: true },
+            zone:            { value: '' },
             broker:          { value: '',             type: 'mqtt-broker', required: true },
             discoveryPrefix: { value: 'homeassistant' },
             qos:             { value: '0' },
@@ -80,11 +80,12 @@
             <i class="fa fa-location-arrow"></i> Zone
         </label>
         <input type="text" id="node-config-input-zone"
-               placeholder="e.g. Master, BnB, GuestWing"
+               placeholder="Optional — e.g. Master, BnB, GarageApt"
                style="width:60%" />
         <div style="margin-left:106px; margin-top:4px; color:#999; font-size:0.85em;">
-            Physical zone name used in your MQTT topics — e.g. <code>Master</code>, <code>BnB</code>, <code>GuestWing</code>.
-            Keep it short with no spaces. This can be updated later if needed.
+            <strong>Optional</strong> — leave blank for a single-zone home. Topics become <code>{siteId}/dmx/1</code>.<br/>
+            Use for multiple buildings or areas e.g. <code>Master</code>, <code>BnB</code>, <code>GarageApt</code>.
+            This can be updated later if needed.
         </div>
     </div>
 

package/nodes/ha-mqtt-config.js

@@ -61,6 +61,14 @@ module.exports = function (RED) {
         this.transitionRateLimit = parseFloat(config.transitionRateLimit) || 1;
         this.transitionHaUiTime  = parseFloat(config.transitionHaUiTime)  || 1;
 
+        // ── Topic builder — omits empty zone segment ─────────────────────────
+        this.buildTopic = function() {
+            const segments = Array.from(arguments).filter(function(s) {
+                return s !== null && s !== undefined && String(s).trim().length > 0;
+            });
+            return segments.join('/');
+        };
+
         // Expose a convenience settings object for child nodes
         this.settings = {
             siteId:          this.siteId,

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

@@ -49,6 +49,7 @@
             defaultState: { value: 'OFF' },
             // Advanced
             maxDepth:     { value: '10' },
+            debugMode:      { value: false },
         },
 
         label: function () {
@@ -303,6 +304,18 @@
         <span style="margin-left:8px; color:#999; font-size:0.85em;">0 = disable loop detection</span>
     </div>
 
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-debugMode"
+               style="width:auto; margin-right:8px" />
+        <label for="node-input-debugMode" style="width:auto">
+            Debug output to NR debug tab
+        </label>
+        <div style="margin-left:106px; margin-top:4px; color:#e74c3c; font-size:0.8em;">
+            ⚠ Disable in production — logs every MQTT publish
+        </div>
+    </div>
+
     <div style="margin-top:16px; padding-top:8px; border-top:1px solid #444; color:#666; font-size:0.8em; text-align:right;">
         node-red-contrib-dmx-for-ha &nbsp;v0.2.2
     </div>

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

@@ -8,6 +8,10 @@
 // ============================================================
 
 module.exports = function (RED) {
+    // Package version — read once at module load
+    const PKG_VERSION = require('path').join(__dirname, '../package.json');
+    const _pkgVer = (() => { try { return require(PKG_VERSION).version; } catch(e) { return '?'; } })();
+
 
     function HaMqttDmxGroupNode(config) {
         RED.nodes.createNode(this, config);
@@ -91,7 +95,7 @@ module.exports = function (RED) {
 
         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 groupTopic   = cfg.buildTopic(cfg.discoveryPrefix, 'light', groupId);
         const cfgTopic     = `${groupTopic}/${cfg.configTopic}`;
         const statTopic    = `${groupTopic}/${cfg.stateTopic}`;
         const cmdTopic     = `${groupTopic}/${cfg.commandTopic}`;
@@ -125,12 +129,14 @@ module.exports = function (RED) {
 
         // ── MQTT helpers ──────────────────────────────────────────
         function pub(topic, payload, retain) {
+            const strPayload = typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
             broker.publish({
                 topic,
-                payload: typeof payload === 'object' ? JSON.stringify(payload) : String(payload),
+                payload: strPayload,
                 qos:    cfg.qos,
                 retain: retain !== undefined ? retain : cfg.retain,
             });
+            if (S.debugMode) node.debug(`${groupId} → ${topic}  ${strPayload.substring(0, 120)}`);
         }
 
         function pubState(payload) {
@@ -200,7 +206,7 @@ module.exports = function (RED) {
             }
 
             const discovery = {
-                unique_id:           `group(${groupId})`,
+                unique_id:           groupId,
                 schema:              'json',
                 object_id:           objectId,
                 optimistic:          false,
@@ -217,15 +223,15 @@ module.exports = function (RED) {
                 max_mireds:          500,
                 stat_t:              statTopic,
                 cmd_t:               cmdTopic,
-                name:                S.groupName || `${S.deviceType} Group ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                name:                S.groupName || `${S.deviceType} Group ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                 device: {
                     identifiers:    `light-${groupId}`,
-                    name:           `(${groupId}) - ${S.deviceType} Group ${S.situation} the ${cfg.zone} - ${S.area} - ${S.subLocation}`,
+                    name:           `(${groupId}) - ${S.deviceType} Group ${S.situation} the ${buildLocation(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: discoveryMode !== 'hidden' ? `${cfg.zone} ${S.area} ${S.subLocation}` : undefined,
+                    suggested_area: discoveryMode !== 'hidden' ? buildLocation(cfg.zone, S.area, S.subLocation) : undefined,
                     hw_version:     'Virtual fixture — exists as a DMX Group Node in Node-RED',
-                    sw_version:     'ha-mqtt-dmx-group: 0.1.0',
+                    sw_version:     'ha-mqtt-dmx-group: ' + _pkgVer,
                     manufacturer:   'DeSwaggy — Discord: @deswaggy',
                 },
             };
@@ -323,6 +329,19 @@ module.exports = function (RED) {
     }
 
 
+
+    // ── Location string helper ─────────────────────────────────────────────
+    function buildLocation(zone, area, subLoc) {
+        // Strip parentheses from sub-area values e.g. "(North)" → "North"
+        const sub = (subLoc || '').replace(/[()]/g, '').trim();
+        const areaClean = (area || '').trim();
+        // Skip sub-area if empty or same as area (prevents "Stairs - Stairs")
+        if (!sub || sub.toLowerCase() === areaClean.toLowerCase()) {
+            return `${zone} ${areaClean}`.trim();
+        }
+        return `${zone} ${areaClean} - ${sub}`.trim();
+    }
+
     // ── HTTP endpoint for canvas toggle button ───────────────────────────────
     RED.httpAdmin.post('/ha-mqtt-dmx-group/:id/toggle', RED.auth.needsPermission('ha-mqtt-dmx-group.write'), function(req, res) {
         const n = RED.nodes.getNode(req.params.id);

package/nodes/ha-mqtt-dmx.html

@@ -171,6 +171,7 @@
             minOutput:      { value: '1' },
             brightBump:     { value: '50' },
             ticksPerSec:    { value: '31' },
+            debugMode:      { value: false },
         },
 
         label: function () {
@@ -539,6 +540,18 @@
         <span style="margin-left:8px; color:#999; font-size:0.85em;">Default 31</span>
     </div>
 
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-debugMode"
+               style="width:auto; margin-right:8px" />
+        <label for="node-input-debugMode" style="width:auto">
+            Debug output to NR debug tab
+        </label>
+        <div style="margin-left:106px; margin-top:4px; color:#e74c3c; font-size:0.8em;">
+            ⚠ Disable in production — logs every MQTT publish
+        </div>
+    </div>
+
     <div style="margin-top:16px; padding-top:8px; border-top:1px solid #444; color:#666; font-size:0.8em; text-align:right;">
         node-red-contrib-dmx-for-ha &nbsp;v0.2.2
     </div>

package/nodes/ha-mqtt-dmx.js

@@ -5,6 +5,10 @@
 // ============================================================
 
 module.exports = function (RED) {
+    // Package version — read once at module load
+    const PKG_VERSION = require('path').join(__dirname, '../package.json');
+    const _pkgVer = (() => { try { return require(PKG_VERSION).version; } catch(e) { return '?'; } })();
+
 
     // ── Gamma correction table ────────────────────────────────────
     // Pre-computed CIE 1931 gamma 2.2 lookup — 0..255 → 0..255
@@ -104,6 +108,10 @@ module.exports = function (RED) {
             minOutput:     parseInt(config.minOutput)   || 1,
             brightBump:    parseInt(config.brightBump)  || 50,
             ticksPerSec:   parseInt(config.ticksPerSec) || 31,
+            debugMode:     config.debugMode === true,
+            // Global transition controls from config node
+            rateLimit:     cfg.transitionRateLimit || 1,
+            haUiTime:      cfg.transitionHaUiTime  || 1,
             flashShort:    cfg.flashShort,
             flashLong:     cfg.flashLong,
             diskDelay:     cfg.diskDelay,
@@ -111,11 +119,11 @@ module.exports = function (RED) {
 
         const fixtureId    = `${S.uidPrefix}-${S.uid}${S.uidPostfix}`;
         const objectId     = `${S.uidPrefix}_${S.uid}${S.uidPostfix}`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
-        const fixtureTopic = `${cfg.discoveryPrefix}/light/${fixtureId}`;
+        const fixtureTopic = cfg.buildTopic(cfg.discoveryPrefix, 'light', fixtureId);
         const cfgTopic     = `${fixtureTopic}/${cfg.configTopic}`;
         const statTopic    = `${fixtureTopic}/${cfg.stateTopic}`;
         const cmdTopic     = `${fixtureTopic}/${cfg.commandTopic}`;
-        const dmxTopic     = `${cfg.siteId}/${cfg.zone}/dmx/${S.universe}`;
+        const dmxTopic     = cfg.buildTopic(cfg.siteId, cfg.zone, 'dmx', S.universe);
 
         // ── Context helpers ───────────────────────────────────────
         // Check disk store available once on startup
@@ -158,26 +166,45 @@ module.exports = function (RED) {
         }
 
         function buildDmxPayload(channel, value) {
-            if (channel == null || value == null) return null;
+            // Skip channels with no address configured (0 or null)
+            if (!channel || channel <= 0 || value == null) return null;
             return String(channel).padStart(3, '0') + String(value).padStart(3, '0');
         }
 
+        // Fix 2: Cache last sent value per channel — skip publish if unchanged
+        const _lastSent = {};
+
         function sendDmxChannels(channels) {
             channels.forEach(function ([ch, val]) {
                 const payload = buildDmxPayload(ch, val);
                 if (payload === null) return;
+                // Skip if value unchanged since last publish
+                if (_lastSent[ch] === val) {
+                    if (S.debugMode) node.debug(`${fixtureId} → SKIP ch${ch}=${val} (unchanged)`);
+                    return;
+                }
+                _lastSent[ch] = val;
                 broker.publish({ topic: dmxTopic, payload, qos: cfg.qos, retain: false });
+                if (S.debugMode) node.debug(`${fixtureId} → ${dmxTopic}  "${payload}"`);
             });
         }
 
+        function resetLastSent() {
+            // Clear cache so next send forces a full re-publish
+            // Used on device:add to ensure controller gets current state
+            Object.keys(_lastSent).forEach(k => delete _lastSent[k]);
+        }
+
         // ── MQTT helpers ──────────────────────────────────────────
         function pub(topic, payload, retain) {
+            const strPayload = typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
             broker.publish({
                 topic,
-                payload: typeof payload === 'object' ? JSON.stringify(payload) : String(payload),
+                payload: strPayload,
                 qos:    cfg.qos,
                 retain: retain !== undefined ? retain : cfg.retain,
             });
+            if (S.debugMode) node.debug(`${fixtureId} → ${topic}  ${strPayload.substring(0, 120)}`);
         }
 
         function pubState(payload) {
@@ -257,23 +284,40 @@ module.exports = function (RED) {
         // ── Transition ────────────────────────────────────────────
         function runTransition(fromChannels, toChannels, durationSecs) {
             stopEffect();
-            const totalTicks = Math.round(durationSecs * S.ticksPerSec);
-            const intervalMs = Math.round(1000 / S.ticksPerSec);
+            // Apply global rate limit from config node
+            // rateLimit < 1 = slower transitions, rateLimit > 1 = faster
+            const effectiveTicks = Math.max(1, Math.round(S.ticksPerSec * S.rateLimit));
+
+            // Fix 4: Skip micro-transitions — snap to target if too short to animate
+            const minDuration = 2 / effectiveTicks;
+            if (durationSecs < minDuration) {
+                sendDmxChannels(toChannels);
+                return;
+            }
+
+            const totalTicks = Math.round(durationSecs * effectiveTicks);
+            const intervalMs = Math.round(1000 / effectiveTicks);
             let tick = 0;
 
-            effectTimer = setInterval(function () {
-                tick++;
-                const progress = Math.min(1, tick / totalTicks);
-                const channels = fromChannels.map(function ([ch, from], i) {
-                    const to  = toChannels[i] ? toChannels[i][1] : 0;
-                    return [ch, Math.round(from + (to - from) * progress)];
-                });
-                sendDmxChannels(channels);
-                if (tick >= totalTicks) {
-                    stopEffect();
-                    sendDmxChannels(toChannels);
-                }
-            }, intervalMs);
+            // Fix 3: Random jitter (0 to 1 interval) to stagger NR event loop
+            // Prevents thundering herd when many nodes start transitions simultaneously
+            const jitter = Math.random() * intervalMs;
+            // Fix 3: Jitter delay spreads load across event loop
+            setTimeout(function () {
+                effectTimer = setInterval(function () {
+                    tick++;
+                    const progress = Math.min(1, tick / totalTicks);
+                    const channels = fromChannels.map(function ([ch, from], i) {
+                        const to  = toChannels[i] ? toChannels[i][1] : 0;
+                        return [ch, Math.round(from + (to - from) * progress)];
+                    });
+                    sendDmxChannels(channels);
+                    if (tick >= totalTicks) {
+                        stopEffect();
+                        sendDmxChannels(toChannels);
+                    }
+                }, intervalMs);
+            }, jitter);
         }
 
         // ── State persistence ─────────────────────────────────────
@@ -305,7 +349,12 @@ module.exports = function (RED) {
 
             const toChannels = buildColorChannels(brightness, r, g, b, w, ww);
 
-            if (S.transitions && payload.transition && payload.transition > 0) {
+            // Use HA UI time as fallback if HA sends no transition duration
+            const transitionDuration = (payload.transition && payload.transition > 0)
+                ? payload.transition
+                : (S.transitions ? S.haUiTime : 0);
+
+            if (S.transitions && transitionDuration > 0) {
                 const bump        = sendInitialBump(toChannels);
                 const prevBright  = recall('brightness', 'brightness_disk', 0);
                 const prevR       = recall('red',   'red_disk',   S.brightBump || r);
@@ -316,7 +365,7 @@ module.exports = function (RED) {
                 const fromChannels = buildColorChannels(
                     bump || prevBright, prevR, prevG, prevB, prevW, prevWW
                 );
-                runTransition(fromChannels, toChannels, payload.transition);
+                runTransition(fromChannels, toChannels, transitionDuration);
             } else {
                 sendInitialBump(toChannels);
                 sendDmxChannels(toChannels);
@@ -341,7 +390,7 @@ module.exports = function (RED) {
 
             if (S.transitions && payload && payload.transition && payload.transition > 0) {
                 const fromChannels = buildColorChannels(brightness, r, g, b, w, ww);
-                runTransition(fromChannels, toChannels, payload.transition);
+                runTransition(fromChannels, toChannels, transitionDuration);
             } else {
                 sendDmxChannels(toChannels);
             }
@@ -377,7 +426,7 @@ module.exports = function (RED) {
             // Rainbow
             if (effectName === 'rainbow') {
                 let deg = 0;
-                startEffect('Rainbow', Math.round(1000 / S.ticksPerSec), () => {
+                startEffect('Rainbow', Math.round(1000 / Math.max(1, S.ticksPerSec * S.rateLimit)), () => {
                     deg = (deg + 360 / (S.ticksPerSec * 3)) % 360;
                     const [r,g,b] = hsvToRgb(deg, 1, 1);
                     sendDmxChannels(buildColorChannels(255, r, g, b, 0, 0));
@@ -387,7 +436,7 @@ module.exports = function (RED) {
             // Rainbow RGBW
             if (effectName === 'rainbow_rgbw') {
                 let deg = 0;
-                startEffect('Rainbow RGBW', Math.round(1000 / S.ticksPerSec), () => {
+                startEffect('Rainbow RGBW', Math.round(1000 / Math.max(1, S.ticksPerSec * S.rateLimit)), () => {
                     deg = (deg + 360 / (S.ticksPerSec * 3)) % 360;
                     const [r,g,b] = hsvToRgb(deg, 1, 1);
                     const w = Math.round(255 * Math.abs(Math.sin(deg * Math.PI / 180)));
@@ -415,7 +464,7 @@ module.exports = function (RED) {
             // Twinkle
             if (effectName === 'twinkle') {
                 let dir = 1; let bright = 0;
-                startEffect('Twinkle', Math.round(1000 / S.ticksPerSec), () => {
+                startEffect('Twinkle', Math.round(1000 / Math.max(1, S.ticksPerSec * S.rateLimit)), () => {
                     bright = Math.max(0, Math.min(255, bright + dir * 8));
                     if (bright >= 255 || bright <= 0) dir = -dir;
                     sendDmxChannels(buildColorChannels(bright, 255, 255, 255, 255, 0));
@@ -458,7 +507,7 @@ module.exports = function (RED) {
             ] : [];
 
             const discovery = {
-                unique_id:              `${S.deviceType}(${fixtureId})`,
+                unique_id:              fixtureId,
                 schema:                 'json',
                 object_id:              objectId,
                 optimistic:             false,
@@ -475,21 +524,22 @@ module.exports = function (RED) {
                 max_mireds:             500,
                 stat_t:                 statTopic,
                 cmd_t:                  cmdTopic,
-                name:                   `${S.deviceType} ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                name:                   `${S.deviceType} ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                 device: {
                     identifiers:    `light-${fixtureId}`,
-                    name:           `(${fixtureId}) - ${S.deviceType} ${S.situation} the ${cfg.zone} - ${S.area} - ${S.subLocation}`,
-                    model:          `${S.colorMode} ${S.deviceType} located ${S.situation} the ${cfg.zone} - ${S.area}`,
+                    name:           `(${fixtureId}) - ${S.deviceType} ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
+                    model:          `${S.colorMode} ${S.deviceType} located ${S.situation} the ${cfg.zone} ${S.area}`,
                     model_id:       `referenced on plan as: (${fixtureId}`,
-                    suggested_area: discoveryMode !== 'hidden' ? `${cfg.zone} ${S.area} ${S.subLocation}` : undefined,
+                    suggested_area: discoveryMode !== 'hidden' ? buildLocation(cfg.zone, S.area, S.subLocation) : undefined,
                     hw_version:     `DMX Controller in ${cfg.zone}. MQTT: ${dmxTopic}`,
                     serial_number:  fixtureId,
-                    sw_version:     'ha-mqtt-dmx: 0.1.0',
+                    sw_version:     'ha-mqtt-dmx: ' + _pkgVer,
                     manufacturer:   'DeSwaggy — Discord: @deswaggy',
                 },
             };
 
             pub(cfgTopic, discovery, true);
+            resetLastSent(); // Force full state re-publish after discovery
 
             broker.subscribe(cmdTopic, cfg.qos, function (topic, rawPayload) {
                 let payload;
@@ -588,6 +638,19 @@ module.exports = function (RED) {
     }
 
 
+
+    // ── Location string helper ─────────────────────────────────────────────
+    function buildLocation(zone, area, subLoc) {
+        // Strip parentheses from sub-area values e.g. "(North)" → "North"
+        const sub = (subLoc || '').replace(/[()]/g, '').trim();
+        const areaClean = (area || '').trim();
+        // Skip sub-area if empty or same as area (prevents "Stairs - Stairs")
+        if (!sub || sub.toLowerCase() === areaClean.toLowerCase()) {
+            return `${zone} ${areaClean}`.trim();
+        }
+        return `${zone} ${areaClean} - ${sub}`.trim();
+    }
+
     // ── HTTP endpoint for canvas toggle button ───────────────────────────────
     RED.httpAdmin.post('/ha-mqtt-dmx/:id/toggle', RED.auth.needsPermission('ha-mqtt-dmx.write'), function(req, res) {
         const n = RED.nodes.getNode(req.params.id);

package/nodes/ha-mqtt-pir.html

@@ -47,6 +47,7 @@
             haIcon:         { value: 'mdi:motion-sensor' },
             cableColor:     { value: 'Purple' },
             holdTime:       { value: '15' },
+            debugMode:      { value: false },
             warmupTime:     { value: '120' },
         },
 
@@ -280,6 +281,18 @@
         <span style="margin-left:8px; color:#999; font-size:0.85em;">Offline delay after boot before PIR activates</span>
     </div>
 
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-debugMode"
+               style="width:auto; margin-right:8px" />
+        <label for="node-input-debugMode" style="width:auto">
+            Debug output to NR debug tab
+        </label>
+        <div style="margin-left:106px; margin-top:4px; color:#e74c3c; font-size:0.8em;">
+            ⚠ Disable in production — logs every MQTT publish
+        </div>
+    </div>
+
     <div style="margin-top:16px; padding-top:8px; border-top:1px solid #444; color:#666; font-size:0.8em; text-align:right;">
         node-red-contrib-dmx-for-ha &nbsp;v0.2.2
     </div>

package/nodes/ha-mqtt-pir.js

@@ -5,6 +5,10 @@
 // ============================================================
 
 module.exports = function (RED) {
+    // Package version — read once at module load
+    const PKG_VERSION = require('path').join(__dirname, '../package.json');
+    const _pkgVer = (() => { try { return require(PKG_VERSION).version; } catch(e) { return '?'; } })();
+
 
     function HaMqttPirNode(config) {
         RED.nodes.createNode(this, config);
@@ -80,11 +84,12 @@ module.exports = function (RED) {
             cableColor:     config.cableColor       || 'Purple',
             holdTime:       parseInt(config.holdTime)    || 15,
             warmupTime:     parseInt(config.warmupTime)  || 120,
+            debugMode:     config.debugMode === true,
         };
 
         const fixtureId   = `S-${S.uid}${S.uidPostfix}`;
         const objectId    = `s_${S.uid}${S.uidPostfix}`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
-        const fixtureTopic = `${cfg.discoveryPrefix}/binary_sensor/${fixtureId}`;
+        const fixtureTopic = cfg.buildTopic(cfg.discoveryPrefix, 'binary_sensor', fixtureId);
         const cmdTopic    = `${fixtureTopic}/${cfg.commandTopic}`;
         const cfgTopic    = `${fixtureTopic}/${cfg.configTopic}`;
         const statTopic   = `${fixtureTopic}/${cfg.stateTopic}`;
@@ -92,12 +97,14 @@ module.exports = function (RED) {
 
         // ── Helpers ───────────────────────────────────────────────
         function pub(topic, payload, retain) {
+            const strPayload = typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
             broker.publish({
                 topic,
-                payload: typeof payload === 'object' ? JSON.stringify(payload) : String(payload),
+                payload: strPayload,
                 qos:    cfg.qos,
                 retain: retain !== undefined ? retain : cfg.retain,
             });
+            if (S.debugMode) node.debug(`${fixtureId} → ${topic}  ${strPayload.substring(0, 120)}`);
         }
 
         function setStatus(fill, shape, text) {
@@ -154,7 +161,7 @@ module.exports = function (RED) {
             const discovery = {
                 unique_id:          fixtureId,
                 object_id:          objectId,
-                name:               `${S.pirType} PIR ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                name:               `${S.pirType} PIR ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                 stat_t:             statTopic,
                 avty_t:             avtyTopic,
                 payload_available:  'online',
@@ -165,13 +172,13 @@ module.exports = function (RED) {
                 icon:               S.haIcon,
                 device: {
                     identifiers:    `binary_sensor-${fixtureId}`,
-                    name:           `(${fixtureId}) - ${S.pirType} PIR ${S.situation} the ${cfg.zone} - ${S.area} - ${S.subLocation}`,
+                    name:           `(${fixtureId}) - ${S.pirType} PIR ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                     model:          `${S.pirType} PIR located ${S.situation} the ${cfg.zone} - ${S.area}`,
                     model_id:       `referenced on plan as: (${fixtureId}`,
-                    suggested_area: discoveryMode !== 'hidden' ? `${cfg.zone} ${S.area} ${S.subLocation}` : undefined,
+                    suggested_area: discoveryMode !== 'hidden' ? buildLocation(cfg.zone, S.area, S.subLocation) : undefined,
                     hw_version:     `${S.pirType} PIR — ${S.cableColor} Cat5 cable. Publishes "${S.pirPayload}" on topic: ${S.subscribeTopic}`,
                     serial_number:  `(${fixtureId}) Payload: ${S.pirPayload}`,
-                    sw_version:     `ha-mqtt-pir: ${RED.version ? RED.version() : '0.1.0'}`,
+                    sw_version:     `ha-mqtt-pir: ${_pkgVer}`,
                     manufacturer:   'DeSwaggy — Discord: @deswaggy',
                 },
             };
@@ -227,6 +234,19 @@ module.exports = function (RED) {
     }
 
 
+
+    // ── Location string helper ─────────────────────────────────────────────
+    function buildLocation(zone, area, subLoc) {
+        // Strip parentheses from sub-area values e.g. "(North)" → "North"
+        const sub = (subLoc || '').replace(/[()]/g, '').trim();
+        const areaClean = (area || '').trim();
+        // Skip sub-area if empty or same as area (prevents "Stairs - Stairs")
+        if (!sub || sub.toLowerCase() === areaClean.toLowerCase()) {
+            return `${zone} ${areaClean}`.trim();
+        }
+        return `${zone} ${areaClean} - ${sub}`.trim();
+    }
+
     // ── HTTP endpoint for canvas toggle button ───────────────────────────────
     RED.httpAdmin.post('/ha-mqtt-pir/:id/toggle', RED.auth.needsPermission('ha-mqtt-pir.write'), function(req, res) {
         const n = RED.nodes.getNode(req.params.id);

package/nodes/ha-mqtt-relay.html

@@ -48,6 +48,7 @@
             // Options
             haIcon:         { value: 'mdi:toggle-switch' },
             showEffects:    { value: false },
+            debugMode:      { value: false },
             defaultState:   { value: 'OFF' },
         },
 
@@ -276,6 +277,18 @@
         <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-debugMode"
+               style="width:auto; margin-right:8px" />
+        <label for="node-input-debugMode" style="width:auto">
+            Debug output to NR debug tab
+        </label>
+        <div style="margin-left:106px; margin-top:4px; color:#e74c3c; font-size:0.8em;">
+            ⚠ Disable in production — logs every MQTT publish
+        </div>
+    </div>
+
     <div style="margin-top:16px; padding-top:8px; border-top:1px solid #444; color:#666; font-size:0.8em; text-align:right;">
         node-red-contrib-dmx-for-ha &nbsp;v0.2.2
     </div>

package/nodes/ha-mqtt-relay.js

@@ -8,6 +8,10 @@
 // ============================================================
 
 module.exports = function (RED) {
+    // Package version — read once at module load
+    const PKG_VERSION = require('path').join(__dirname, '../package.json');
+    const _pkgVer = (() => { try { return require(PKG_VERSION).version; } catch(e) { return '?'; } })();
+
 
     function HaMqttRelayNode(config) {
         RED.nodes.createNode(this, config);
@@ -91,11 +95,11 @@ module.exports = function (RED) {
 
         const fixtureId    = `${S.uidPrefix}-${S.uid}${S.uidPostfix}`;
         const objectId     = `${S.uidPrefix}_${S.uid}${S.uidPostfix}`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
-        const fixtureTopic = `${cfg.discoveryPrefix}/light/${fixtureId}`;
+        const fixtureTopic = cfg.buildTopic(cfg.discoveryPrefix, 'light', fixtureId);
         const cfgTopic     = `${fixtureTopic}/${cfg.configTopic}`;
         const statTopic    = `${fixtureTopic}/${cfg.stateTopic}`;
         const cmdTopic     = `${fixtureTopic}/${cfg.commandTopic}`;
-        const relayTopic   = `${cfg.siteId}/${cfg.zone}/${S.controllerNum}/${S.mqttSegment}/${S.relayNum}`;
+        const relayTopic   = cfg.buildTopic(cfg.siteId, cfg.zone, S.controllerNum, S.mqttSegment, S.relayNum);
 
         // ── Context helpers ───────────────────────────────────────
         // Check disk store available once on startup
@@ -129,12 +133,14 @@ module.exports = function (RED) {
 
         // ── MQTT helpers ──────────────────────────────────────────
         function pub(topic, payload, retain) {
+            const strPayload = typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
             broker.publish({
                 topic,
-                payload: typeof payload === 'object' ? JSON.stringify(payload) : String(payload),
+                payload: strPayload,
                 qos:    cfg.qos,
                 retain: retain !== undefined ? retain : cfg.retain,
             });
+            if (S.debugMode) node.debug(`${fixtureId} → ${topic}  ${strPayload.substring(0, 120)}`);
         }
 
         function pubRelay(value) {
@@ -228,10 +234,10 @@ module.exports = function (RED) {
             }
 
             const discovery = {
-                unique_id:           `${S.deviceType}(${fixtureId})`,
+                unique_id:           fixtureId,
                 schema:              'json',
                 object_id:           objectId,
-                name:                `${S.deviceType} ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                name:                `${S.deviceType} ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                 cmd_t:               cmdTopic,
                 stat_t:              statTopic,
                 optimistic:          false,
@@ -245,13 +251,13 @@ module.exports = function (RED) {
                 flash_time_long:     S.flashLong,
                 device: {
                     identifiers:    `light-${fixtureId}`,
-                    name:           `(${fixtureId}) - ${S.deviceType} ${S.situation} the ${cfg.zone} - ${S.area} - ${S.subLocation}`,
+                    name:           `(${fixtureId}) - ${S.deviceType} ${S.situation} the ${buildLocation(cfg.zone, S.area, S.subLocation)}`,
                     model:          `${S.deviceType} located ${S.situation} the ${cfg.zone} - ${S.area}`,
                     model_id:       `referenced on plan as: (${fixtureId}`,
-                    suggested_area: discoveryMode !== 'hidden' ? `${cfg.zone} ${S.area} ${S.subLocation}` : undefined,
+                    suggested_area: discoveryMode !== 'hidden' ? buildLocation(cfg.zone, S.area, S.subLocation) : undefined,
                     hw_version:     `Relay Controller in ${cfg.zone}. Topic: ${relayTopic}`,
                     serial_number:  fixtureId,
-                    sw_version:     'ha-mqtt-relay: 0.1.0',
+                    sw_version:     'ha-mqtt-relay: ' + _pkgVer,
                     manufacturer:   'DeSwaggy — Discord: @deswaggy',
                 },
             };
@@ -340,6 +346,19 @@ module.exports = function (RED) {
     }
 
 
+
+    // ── Location string helper ─────────────────────────────────────────────
+    function buildLocation(zone, area, subLoc) {
+        // Strip parentheses from sub-area values e.g. "(North)" → "North"
+        const sub = (subLoc || '').replace(/[()]/g, '').trim();
+        const areaClean = (area || '').trim();
+        // Skip sub-area if empty or same as area (prevents "Stairs - Stairs")
+        if (!sub || sub.toLowerCase() === areaClean.toLowerCase()) {
+            return `${zone} ${areaClean}`.trim();
+        }
+        return `${zone} ${areaClean} - ${sub}`.trim();
+    }
+
     // ── HTTP endpoint for canvas toggle button ───────────────────────────────
     RED.httpAdmin.post('/ha-mqtt-relay/:id/toggle', RED.auth.needsPermission('ha-mqtt-relay.write'), function(req, res) {
         const n = RED.nodes.getNode(req.params.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-dmx-for-ha",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "DMX lighting control for Home Assistant via Node-RED and MQTT. Place a node, fill in the settings, deploy. Full HA device registry integration with RGBW/RGBWW/CCT/brightness colour modes, transitions, effects, and group control.",
   "keywords": [
     "node-red",