node-red-contrib-dmx-for-ha 0.4.3 → 0.4.8

package/README.md

@@ -1,6 +1,8 @@
 # node-red-contrib-dmx-for-ha
 
-DMX lighting control for Home Assistant via Node-RED and MQTT.
+**Professional DMX lighting control for Home Assistant via Node-RED and MQTT.**
+
+Built by a lighting integrator, for lighting integrators — and anyone else who needs serious DMX control inside Home Assistant.
 
 Place a node, fill in the settings, deploy. Your DMX fixture appears in Home Assistant automatically — ready to use in automations, dashboards, and scenes.
 
@@ -8,6 +10,43 @@ No YAML. No custom MQTT discovery config. No external wiring inside Node-RED.
 
 ---
 
+## Who this is for
+
+This package was designed for **professional AV and lighting integrators** working on large residential and commercial installations. If any of these sound familiar, this was built for you:
+
+- You have hundreds of DMX fixtures that each need individual HA entity management
+- You commission remotely — physically pressing every button on a large site is not practical
+- Your client's lights must come back to the correct state after any power cycle, every time
+- Your automation logic lives in HA, not hardcoded in the lighting controller
+- You have multiple DMX universes and controllers in a single zone
+- You've stood in a roof cavity at 11pm wondering why channel 47 isn't responding
+
+It also works perfectly for advanced home users who want proper DMX integration rather than a workaround.
+
+---
+
+## The architecture
+
+Node-RED acts as the **virtual lighting desk** — it owns the DMX channels, manages transitions, and handles hardware communication. Home Assistant is the **automation and UI layer** — it sees clean light entities and knows nothing about DMX channels, universes, or controllers.
+
+```
+Home Assistant          Node-RED               DMX Hardware
+──────────────          ────────               ────────────
+Automations      ←──→  ha-mqtt-dmx     ──→    EtherTen / 
+Dashboards              ha-mqtt-group           DMX decoder /
+Scenes                  ha-mqtt-relay           MQTT bridge
+Voice control           ha-mqtt-button  ←──    Wall buttons
+                        ha-mqtt-pir     ←──    PIR sensors
+```
+
+This separation means:
+- **HA stays clean** — light entities behave like any other HA light
+- **NR handles complexity** — DMX addressing, gamma correction, transitions, effects
+- **Hardware is abstracted** — swap controllers without touching HA config
+- **Remote commissioning** — every physical device has a software mirror in HA, testable from anywhere
+
+---
+
 ## What this package does
 
 Bridges the gap between DMX lighting hardware and Home Assistant.
@@ -18,9 +57,12 @@ Most DMX implementations require either expensive proprietary hardware or comple
 - RGBW, RGBWW, RGB, Colour Temperature, Brightness, and On/Off colour modes
 - Gamma-corrected DMX output
 - Transitions, effects, and group control
-- State persistence across reboots
-- Wall button and PIR motion sensor integration
+- State persistence across reboots — survives power cycles and HA updates
+- Wall button and PIR motion sensor integration with remote commissioning support
 - 230V relay switching
+- DMX channel conflict detection — warns on duplicate channel assignments
+- Configurable DMX floor value — prevents low-value flicker on hardware that needs it
+- Debug mode per node — 12hr auto-disable, safe to leave in production flows
 
 > **Note:** This is building automation DMX — fixtures, decoders, dimmers, relay switching. Not entertainment industry DMX (no movers, gobos, or fixture profiles). DMX is an open standard and this package works with any DMX controller that accepts MQTT payloads.
 
@@ -120,7 +162,20 @@ Fill in the node editor:
 1. **Fixture ID** — Prefix (`L`), Plan ID, optional channel letter e.g. `L` `992` `-A`
 2. **Colour Mode** — RGBW, RGB, CCT etc.
 3. **Device Type** — e.g. Downlight, Strip light
-4. **Situation** — in, above, throughout etc.
+4. **Situation** — describes where the fixture is relative to its area. Options:
+
+   | Situation | Example result |
+   |---|---|
+   | `in` | Downlight **in** Bedroom 1 |
+   | `at` | Spotlight **at** Entry Door |
+   | `near` | Strip light **near** Kitchen Bench |
+   | `above` | Flood **above** Garage Door |
+   | `below` | Step light **below** Handrail |
+   | `outside` | Rail light **outside** Media Room |
+   | `throughout` | Downlight **throughout** Living Area |
+
+   > **Tip:** Don't default to `in` for everything — `outside`, `near` and `above` are useful for fixtures in corridors, at thresholds, and above architectural features. On a large installation this makes fixture names immediately meaningful without opening a plan.
+
 5. **Config** — select your config node
 6. **Area** and **Sub-Area** — location on the property
 7. **DMX Channels** — channel numbers matching your fixture's DMX start address
@@ -182,8 +237,35 @@ Naming: `L-992-A`, `L-992-B`, `L-992-C` group naturally under `LG-992`.
 ## Wall buttons
 
 Creates two HA entities per button:
-- `binary_sensor.s_10_a` — automation trigger, auto-clears after hold time
-- `button.s_10_a_btn` — dashboard UI mirror
+
+- **`binary_sensor.s_10_a`** — physical state. ON = pressed/held, OFF = released. Use this for automations and dashboard display.
+- **`button.s_10_a_btn`** — momentary trigger. Simulates a physical press from the HA UI.
+
+### Why two entities?
+
+This package is designed for **professional installation** as well as home use. On large installations it is not practical to physically press every button every time you make a change — the building may be large, the button may be on the other side of the property, or you may be commissioning remotely.
+
+The `button` entity gives you a **virtual commissioning panel** — every physical wall button has a software mirror in HA that you can trigger from a laptop anywhere in the world without being on site.
+
+### Important — HA button entity behaviour
+
+The `button` domain in HA is **intentionally stateless** — it will never light up or show an active state. This is a HA platform design decision, not a bug. The `button` entity triggers and immediately resets with no persistent state.
+
+For visual feedback always use the `binary_sensor` entity.
+
+### Recommended dashboard setup
+
+Hide the `button` entity from the default dashboard to keep things clean — it remains fully accessible when needed:
+
+```
+Settings → Devices → (button device) → button entity → ⋮ → Hide from dashboard
+```
+
+This gives you:
+- **Dashboard** — clean, only `binary_sensor` shown
+- **Device page** — both entities visible, Press button accessible for commissioning
+- **Automations** — both entities fully available, nothing hidden from logic
+- **Remote commissioning** — navigate to device page, simulate press from anywhere
 
 Letters `I` and `O` are never used as suffixes — they look too similar to `1` and `0`.
 
@@ -270,6 +352,127 @@ Set to `0` to make all un-timed commands instant.
 
 ---
 
+## Context store — finding your files
+
+This is one of the most common questions with Node-RED on Home Assistant. The context store files are **not** where you expect them.
+
+### Where are the files?
+
+The NR add-on runs in its own Docker container with an isolated config directory. This is **separate** from the main HA config you see via Samba.
+
+| What you see | Actual path on host |
+|---|---|
+| Samba `\\{haip}\config\` | HA config — flows, automations etc. |
+| NR add-on config | `/addon_configs/a0d7b954_nodered/` |
+| Context store files | `/addon_configs/a0d7b954_nodered/nodeRED/context_stores/context/` |
+
+The NR add-on config directory is **not accessible via Samba** — this trips everyone up.
+
+### How to find your context files
+
+Use the **Studio Code Server** add-on (VS Code in HA):
+
+1. Install Studio Code Server from the add-on store if not already installed
+2. Open it: Settings → Add-ons → Studio Code Server → Open Web UI
+3. Open a terminal: Terminal → New Terminal
+4. Run:
+
+```bash
+find / -name "*.json" -path "*context*" 2>/dev/null | grep -v proc
+```
+
+You should see something like:
+```
+/addon_configs/a0d7b954_nodered/nodeRED/context_stores/context/7e2467f26a0693a0/dd6582b967f0314a.json
+/addon_configs/a0d7b954_nodered/nodeRED/context_stores/context/7e2467f26a0693a0/75b10249fcbfd224.json
+...
+```
+
+One `.json` file per node, named by node ID.
+
+### Reading a context file
+
+```bash
+cat "/addon_configs/a0d7b954_nodered/nodeRED/context_stores/context/{flowId}/{nodeId}.json"
+```
+
+A healthy file looks like:
+```json
+{
+    "state": "ON",
+    "brightness": 255,
+    "red": 255,
+    "green": 255,
+    "blue": 255,
+    "white": 255,
+    "warmWhite": 0
+}
+```
+
+### Important: NR adds a `/context/` subfolder
+
+When you set `dir` in your context store config, NR automatically appends `/context/` to it. So:
+
+```javascript
+// You set:
+config: { dir: '/config/nodeRED/context_stores' }
+
+// NR actually writes to:
+// /config/nodeRED/context_stores/context/
+```
+
+### Recommended config.js settings
+
+```javascript
+contextStorage: {
+    memory:      { module: 'memory' },
+    disk_values: { 
+        module: 'localfilesystem', 
+        config: { 
+            dir: '/config/nodeRED/context_stores',
+            flushInterval: 5   // Write to disk every 5 seconds (default is 30)
+        } 
+    },
+    disk_meta:   { 
+        module: 'localfilesystem', 
+        config: { 
+            dir: '/config/nodeRED/context_stores',
+            flushInterval: 5
+        } 
+    },
+    default:     { module: 'memory' },
+},
+```
+
+**Important:** Use an **absolute path** starting with `/config/`. A relative path will silently resolve to the wrong location and nothing will be saved.
+
+`flushInterval: 5` means NR writes to disk every 5 seconds instead of the default 30. This reduces the window of data loss on unexpected shutdown — after turning a light on, wait 5 seconds before restarting.
+
+### Verifying context store is working
+
+After saving a state and waiting 5+ seconds, check your files appeared:
+
+```bash
+ls "/addon_configs/a0d7b954_nodered/nodeRED/context_stores/context/"
+```
+
+If the directory is empty or doesn't exist — check your `config.js` path is absolute and restart NR.
+
+### NR startup log confirmation
+
+On every startup NR logs which context stores loaded:
+
+```
+Context store  : 'memory'      [module=memory]
+Context store  : 'disk_values' [module=localfilesystem]
+Context store  : 'disk_meta'   [module=localfilesystem]
+Context store  : 'default'     [module=memory]
+```
+
+If `disk_values` shows `[module=memory]` — your config.js change didn't take effect.
+
+---
+
 ## Troubleshooting
 
 **Nodes don't appear in palette** — Restart Node-RED. Check log for errors.
@@ -290,7 +493,15 @@ Set to `0` to make all un-timed commands instant.
 
 | Version | Changes |
 |---|---|
-| 0.3.6 | DMX channel conflict detection, jitter timer cancellable on teardown |
+| 0.4.4 | Recovery status shows actual state on canvas instead of "ready — awaiting HA" |
+| 0.4.3 | device:remove no longer clears disk state — state survives remove/add cycles |
+| 0.4.2 | Group node pubState includes color — fixes color wheel jitter in HA |
+| 0.4.1 | Group node status reflects ON/OFF correctly |
+| 0.4.0 | Group recovery no longer forwards state to children — each node recovers independently |
+| 0.3.9 | Four fixes: group device:add forward removed, cooldown warn suppressed, group status permanent, disk flush on close |
+| 0.3.8 | Restored missing variable declarations wiped by debug block corruption |
+| 0.3.7 | Fix _debugId computed from S (not fixtureId) to avoid ReferenceError on startup |
+| 0.3.6 | DMX channel conflict detection, jitter timer tracked and cancellable |
 | 0.3.5 | Fix debug mode block initialisation order (S before debug) |
 | 0.3.4 | Debug hint text updated — notes 12hr auto-disable |
 | 0.3.3 | Debug mode canvas warning + 12hr auto-disable safety net |

package/nodes/ha-mqtt-config.html

@@ -25,6 +25,7 @@
             transitionHaUiTime:   { value: '1' },
             flashShort:      { value: '1' },
             flashLong:       { value: '10' },
+            dmxFloor:        { value: '3' },
         },
         label: function () {
             return this.name || 'HA MQTT Config';
@@ -190,6 +191,21 @@
                min="1" style="width:70px" />
     </div>
 
+    <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> DMX Channel Limits
+        </label>
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-dmxFloor">
+            <i class="fa fa-arrow-down"></i> DMX Floor
+        </label>
+        <input type="number" id="node-config-input-dmxFloor"
+               min="0" max="20" step="1" style="width:70px" />
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            Min DMX value sent — below this snaps up (0=OFF always OFF). Default: 3
+        </span>
+    </div>
 </script>
 
 <!-- ============================================================

package/nodes/ha-mqtt-config.js

@@ -61,6 +61,9 @@ module.exports = function (RED) {
         this.transitionRateLimit = parseFloat(config.transitionRateLimit) || 1;
         this.transitionHaUiTime  = parseFloat(config.transitionHaUiTime)  || 1;
 
+        // DMX channel limits
+        this.dmxFloor = parseInt(config.dmxFloor) >= 0 ? parseInt(config.dmxFloor) : 3;
+
         // ── Topic builder — omits empty zone segment ─────────────────────────
         this.buildTopic = function() {
             const segments = Array.from(arguments).filter(function(s) {
@@ -86,6 +89,7 @@ module.exports = function (RED) {
             flashLong:            this.flashLong,
             transitionRateLimit:  this.transitionRateLimit,
             transitionHaUiTime:   this.transitionHaUiTime,
+            dmxFloor:             this.dmxFloor,
         };
     }
 

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

@@ -112,6 +112,7 @@ module.exports = function (RED) {
             flashShort:   cfg.flashShort,
             flashLong:    cfg.flashLong,
             diskDelay:    cfg.diskDelay,
+            debugMode:    config.debugMode === true,
         };
 
         // ── Debug mode safeguards ─────────────────────────────────────────

package/nodes/ha-mqtt-dmx.js

@@ -136,6 +136,7 @@ module.exports = function (RED) {
             flashShort:    cfg.flashShort,
             flashLong:     cfg.flashLong,
             diskDelay:     cfg.diskDelay,
+            dmxFloor:      cfg.dmxFloor !== undefined ? cfg.dmxFloor : 3,
         };
 
         // ── Debug mode safeguards ─────────────────────────────────────────
@@ -202,6 +203,9 @@ module.exports = function (RED) {
             if (gamma === 0 && colorValue > 0 && brightness > 0 && S.minOutput > 0) {
                 return S.minOutput;
             }
+            // DMX floor — snap up if above 0 but below hardware stable threshold
+            if (gamma > 0 && gamma < S.dmxFloor) return S.dmxFloor;
+            // Note: ceiling is handled by S.dmxLimiter in scaleToDmx above
             return gamma;
         }
 
@@ -285,12 +289,25 @@ module.exports = function (RED) {
             const p = preEffectState;
             preEffectState = null;
             const channels = buildColorChannels(
-                p.brightness || 255, p.red || 255, p.green || 255,
-                p.blue || 255, p.white || 255, p.warmWhite || 0
+                p.brightness !== undefined ? p.brightness : 255,
+                p.red        !== undefined ? p.red        : 255,
+                p.green      !== undefined ? p.green      : 255,
+                p.blue       !== undefined ? p.blue       : 255,
+                p.white      !== undefined ? p.white      : 255,
+                p.warmWhite  !== undefined ? p.warmWhite  : 0
             );
             sendDmxChannels(channels);
-            pubState({ state: p.state || 'OFF', color_mode: S.colorMode });
-            setStatus('yellow', 'ring', `${fixtureId} ready — awaiting HA`);
+            pubState({
+                state:      p.state || 'OFF',
+                color_mode: S.colorMode,
+                brightness: p.brightness,
+                color:      { r: p.red, g: p.green, b: p.blue, w: p.white, ww: p.warmWhite }
+            });
+            if (p.state === 'ON') {
+                setStatus('green', 'dot', `${fixtureId} ON  bright:${p.brightness}`);
+            } else {
+                setStatus('grey', 'ring', `${fixtureId} OFF`);
+            }
         }
 
         function startEffect(label, intervalMs, tickFn) {
@@ -670,7 +687,11 @@ module.exports = function (RED) {
                     sendDmxChannels(buildColorChannels(0, r, g, b, w, ww));
                 }
                 pubState({ state, color_mode: S.colorMode, brightness, color: { r, g, b, w, ww } });
-                setStatus('yellow', 'ring', `${fixtureId} ready — awaiting HA`);
+                if (state === 'ON') {
+                    setStatus('green', 'dot', `${fixtureId} ON  bright:${brightness}`);
+                } else {
+                    setStatus('grey', 'ring', `${fixtureId} OFF`);
+                }
                 node.log(`${fixtureId} recovery — state:${state}`);
             }, 2000);
         }

package/nodes/ha-mqtt-relay.js

@@ -112,6 +112,7 @@ module.exports = function (RED) {
             flashShort:    cfg.flashShort,
             flashLong:     cfg.flashLong,
             diskDelay:     cfg.diskDelay,
+            debugMode:     config.debugMode === true,
         };
 
         // ── Debug mode safeguards ─────────────────────────────────────────
@@ -323,7 +324,11 @@ module.exports = function (RED) {
                 const state = recall('state', 'state_disk', S.defaultState);
                 pubRelay(state === 'ON' ? 1 : 0);
                 pubState(state);
-                setStatus('yellow', 'ring', `${fixtureId} ready — awaiting HA`);
+                if (state === 'ON') {
+                    setStatus('green', 'dot', `${fixtureId} ON`);
+                } else {
+                    setStatus('grey', 'ring', `${fixtureId} OFF`);
+                }
                 node.log(`${fixtureId} recovery — state:${state}`);
             }, 2000);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-dmx-for-ha",
-  "version": "0.4.3",
+  "version": "0.4.8",
   "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",