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

package/README.md

@@ -12,7 +12,7 @@ No YAML. No custom MQTT discovery config. No external wiring inside Node-RED.
 
 Bridges the gap between DMX lighting hardware and Home Assistant.
 
-Most DMX implementations require either expensive proprietary hardware or complex custom integrations. This package gives you a drop-in Node-RED node that handles everything:
+Most DMX implementations require either expensive proprietary hardware or complex custom integrations. This package gives you drop-in Node-RED nodes that handle everything:
 
 - Full Home Assistant MQTT discovery — entities appear automatically in HA
 - RGBW, RGBWW, RGB, Colour Temperature, Brightness, and On/Off colour modes
@@ -20,6 +20,7 @@ Most DMX implementations require either expensive proprietary hardware or comple
 - Transitions, effects, and group control
 - State persistence across reboots
 - Wall button and PIR motion sensor integration
+- 230V relay switching
 
 > **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.
 
@@ -27,14 +28,16 @@ Most DMX implementations require either expensive proprietary hardware or comple
 
 ## Nodes included
 
-| Node | Palette label | Purpose |
-|---|---|---|
-| `ha-mqtt-config` | *(config)* | Shared site config — broker, zone, HA settings |
-| `ha-mqtt-dmx` | DMX | Single DMX fixture |
-| `ha-mqtt-dmx-group` | DMX Group | Virtual group — fans commands to child nodes |
-| `ha-mqtt-relay` | Relay | 230V relay switching (not DMX) |
-| `ha-mqtt-button` | Button | Wall button receiver |
-| `ha-mqtt-pir` | PIR | Motion sensor receiver |
+| Node | Palette label | Colour | Purpose |
+|---|---|---|---|
+| `ha-mqtt-config` | *(config)* | — | Shared site config — broker, zone, HA settings |
+| `ha-mqtt-dmx` | DMX | Yellow | Single DMX fixture |
+| `ha-mqtt-dmx-group` | DMX Group | Gold | Virtual group — fans commands to child nodes |
+| `ha-mqtt-relay` | Relay | Red | 230V relay switching |
+| `ha-mqtt-button` | Button | Green | Wall button receiver |
+| `ha-mqtt-pir` | PIR | Purple | Motion sensor receiver |
+
+Node colours match the cable colour convention used on electrical plans.
 
 ---
 
@@ -49,60 +52,52 @@ Most DMX implementations require either expensive proprietary hardware or comple
 
 ## Installation
 
+### Via HA Node-RED Add-on config
+
+In HA → Settings → Add-ons → Node-RED → Configuration, add to the packages list:
+```
+node-red-contrib-dmx-for-ha
+```
+Restart the add-on. Nodes appear in the palette under **DMX for HA**.
+
+### Via Node-RED Palette Manager
+
+Node-RED → Menu → Manage Palette → Install → search `node-red-contrib-dmx-for-ha`
+
+### Via npm
+
 ```bash
 cd ~/.node-red
 npm install node-red-contrib-dmx-for-ha
 ```
 
-Restart Node-RED. The nodes appear in the palette under **DMX for HA**.
-
 ---
 
 ## ⚠️ Required: Configure Node-RED context storage
 
-This package stores fixture state (brightness, colour, on/off) so it survives Node-RED restarts. This requires a **disk context store** to be configured in Node-RED.
+This package stores fixture state so it survives Node-RED restarts. A **disk context store** must be configured in Node-RED.
 
 **Without this, fixture state resets to default every time Node-RED restarts.**
 
-### What this means
-
-Node-RED has a context store — a key/value store for saving data. By default it only stores in memory (lost on restart). To persist across restarts you need to add a disk-backed store.
-
 ### How to configure it
 
-1. Find your Node-RED `settings.js` file. Location depends on your setup:
-   - Home Assistant add-on: `/config/node-red/settings.js`
-   - Standard install: `~/.node-red/settings.js`
+Find your Node-RED settings file:
+- HA add-on: `/etc/node-red/config.js`
+- Standard install: `~/.node-red/settings.js`
 
-2. Find the `contextStorage` section (it may be commented out) and update it:
+Add or update the `contextStorage` section:
 
 ```javascript
 contextStorage: {
-    default: {
-        module: "memory"
-    },
-    disk: {
-        module: "localfilesystem"
-    }
+    default:     { module: 'memory' },
+    disk_values: { module: 'localfilesystem' },
 },
 ```
 
-3. Restart Node-RED.
-
-### How to check it is working
-
-After restarting, open Node-RED → Menu → Context Data. You should see both `memory` and `disk` listed as available stores.
-
-If you only see `default` or `memory`, the disk store is not configured correctly.
-
-### What happens without it
-
-The nodes will still work — they fall back to memory storage gracefully. But:
-- All fixture states reset to their default (usually OFF) every time Node-RED restarts
-- Physical relays may not be re-asserted correctly after a reboot
-- DMX channels may not restore to their previous values
-
-For a production deployment, disk context storage is essential.
+Restart Node-RED. Verify in the startup log:
+```
+Context store : 'disk_values' [module=localfilesystem]
+```
 
 ---
 
@@ -110,58 +105,65 @@ For a production deployment, disk context storage is essential.
 
 ### 1. Create a config node
 
-Every node needs a config node. You create it once per zone.
-
-1. Drag a **DMX** node onto the canvas
-2. Open its editor and click the pencil icon next to **Config**
+1. Drag a **DMX** node onto the canvas and open its editor
+2. Click **Add new ha-mqtt-config...** next to the Config field
 3. Fill in:
-   - **Name** — e.g. `Master Zone`
-   - **Site ID** — a short slug for your MQTT topics, e.g. `home` (no spaces)
-   - **Zone** — e.g. `Master` (no spaces or special characters)
+   - **Config Label** — a friendly name e.g. "My House". Don't stress — this can be changed at any time.
+   - **Site ID** — short slug for MQTT topics e.g. `home` (no spaces)
+   - **Zone** — physical zone e.g. `Master`, `BnB`. Used in MQTT topics. This can be updated later if needed.
    - **Broker** — select your existing MQTT broker config
-4. Click **Add** — the config is saved and shared across all nodes
+4. Click **Add**
 
 ### 2. Add a DMX fixture
 
-1. Drag a **DMX** node onto the canvas
-2. Select your **Config** node
-3. Choose **Colour Mode** — RGBW, RGB, CCT etc.
-4. Set **Fixture ID** — Prefix (`L`), Plan ID number, optional channel letter
-5. Enter the **DMX channels** for this fixture
-6. Set the **Controller** and **Universe** numbers
-7. Deploy
+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.
+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
+8. **Controller** and **Universe** numbers
+9. **Discovery Mode** — Enabled, Hidden, or Disabled
 
-Your fixture appears in Home Assistant automatically under **Settings → Devices**.
+Deploy — the fixture appears in HA automatically.
 
-### 3. Wire the SYSTEM node
+### 3. Auto-discovery
 
-The SYSTEM node sends `device:add` on startup so nodes register with HA.
-Wire an inject node (set to fire on deploy + every X seconds) with:
+Nodes auto-discover when deployed if the MQTT broker is connected. No external inject nodes or SYSTEM node needed.
 
-```
-msg.device = "add"
-```
+---
+
+## Discovery Modes
+
+| Mode | Behaviour |
+|---|---|
+| **Enabled** | Discovered and visible in HA dashboard |
+| **Hidden** | Discovered and usable in automations, not auto-placed in dashboard |
+| **Disabled** | Not discovered — entity does not exist in HA |
 
-Wire it to the input of every node on your canvas.
+Use **Disabled** for fixtures not yet installed or wired.
+Use **Hidden** for fixtures installed but not ready for the homeowner.
 
 ---
 
-## Multi-zone deployments
+## Canvas button
+
+Each node has a clickable button on the right side of the canvas node. It toggles between `device:remove` and `device:add`:
 
-Create one `ha-mqtt-config` node per zone:
+- First press → `device:remove` — cleanly removes entity from HA
+- Second press → `device:add` — re-announces to HA
 
-- `Master Zone` → Site ID: `home`, Zone: `Master`
-- `Guest Wing`  → Site ID: `home`, Zone: `GuestWing`
+A toast notification confirms which action fired.
 
-Each DMX, Relay, Button and PIR node picks its zone via the Config dropdown.
-MQTT topics are built automatically: `{siteId}/{zone}/dmx/{universe}`.
+Typical workflow: Remove → update node settings → Deploy → node auto-discovers with new settings.
 
 ---
 
 ## DMX Group Node
 
-The DMX Group node appears as a single light entity in HA. Commands sent to it
-are forwarded to all nodes connected to its **Link** output.
+Appears as a single light entity in HA. Commands fan out to all nodes on its **Link** output.
 
 ```
 [DMX Group LG-992]
@@ -171,32 +173,38 @@ are forwarded to all nodes connected to its **Link** output.
       └──→ [DMX L-992-C]
 ```
 
-Wire the **Link** output to the input of each child DMX or Relay node.
-You can also wire it to another DMX Group node for nested hierarchies.
+Wire **Link** to child DMX or Relay node inputs. Supports nested groups.
+
+Naming: `L-992-A`, `L-992-B`, `L-992-C` group naturally under `LG-992`.
 
 ---
 
 ## Wall buttons
 
-The Button node creates two HA entities per button:
-
+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 (press from HA frontend)
+- `button.s_10_a_btn` — dashboard UI mirror
 
-Build your automations using the `binary_sensor` entity. The `button` entity
-lets you test automations from the HA dashboard without physically pressing the wall button.
+Letters `I` and `O` are never used as suffixes — they look too similar to `1` and `0`.
 
 ---
 
 ## PIR sensors
 
-The PIR node goes **offline** in HA for a configurable warm-up period after
-Node-RED starts. HA ignores all motion triggers during this time.
+Goes **offline** in HA during a configurable warm-up period after NR starts — prevents false triggers during reboots. Default warm-up: 120s.
+
+---
+
+## Fixture ID conventions
 
-This prevents spurious motion events during controller reboot from triggering
-lights in the middle of the night.
+| Prefix | Meaning | Example |
+|---|---|---|
+| `L` | Light (DMX) | `L-992-A` |
+| `P` | Power (Relay) | `P-51` |
+| `LG` | Light Group | `LG-992` |
+| `S` | Sensor (Button/PIR) | `S-10-A` |
 
-Set the warm-up time to match your PIR hardware's stabilisation period (default 120s).
+Entity IDs in HA are locked to the fixture ID and survive friendly name changes.
 
 ---
 
@@ -205,71 +213,55 @@ Set the warm-up time to match your PIR hardware's stabilisation period (default
 | Node | Topic |
 |---|---|
 | DMX | `{siteId}/{zone}/dmx/{universe}` |
-| Relay controller | `{siteId}/{zone}/{controller}/relay/{relayNum}` |
+| Relay | `{siteId}/{zone}/{controller}/relay/{relayNum}` |
 | HA discovery | `homeassistant/light/{fixtureId}/config` |
-| HA state | `homeassistant/light/{fixtureId}/state` |
-| HA command | `homeassistant/light/{fixtureId}/cmd` |
+
+DMX payload format: `"212255"` = channel 212, value 255 (3 digits each).
 
 ---
 
-## DMX output format
+## Multi-zone deployments
 
-DMX values are published as a 6-character string:
+Create one `ha-mqtt-config` per zone. Each node selects its zone via the Config dropdown.
 
 ```
-"212255"  →  channel 212, value 255
-"201000"  →  channel 201, value 0
+Master Zone config → Zone: Master → topics: home/Master/dmx/1
+Guest Wing config  → Zone: GuestWing → topics: home/GuestWing/dmx/1
 ```
 
-Three digits for channel, three digits for value. Your DMX controller firmware
-must expect this format.
-
 ---
 
-## Fixture ID conventions
-
-Fixture IDs match your electrical plan cable IDs:
-
-| Prefix | Meaning | Example |
-|---|---|---|
-| `L` | Light (DMX) | `L-992-A` |
-| `P` | Power (Relay) | `P-51` |
-| `LG` | Light Group (DMX Group) | `LG-992` |
-| `S` | Sensor (Button / PIR) | `S-10-A` |
+## Troubleshooting
 
-The channel letter (`-A`, `-B`, `-C`, `-D`) identifies individual channels
-within a multi-channel cable. `L-992-A`, `L-992-B`, `L-992-C` are three
-separate fixtures on cable 992, grouped under `LG-992`.
+**Nodes don't appear in palette** — Restart Node-RED. Check log for errors.
 
----
+**Fixture doesn't appear in HA** — Check broker connection. Check canvas status. Use canvas button to manually trigger `device:add`.
 
-## Troubleshooting
+**State resets on restart** — Configure disk context storage. Check log for `disk_values` store confirmation.
 
-**Nodes don't appear in palette**
-Restart Node-RED. Check the NR log for install errors.
+**Node shows "Broker disconnected"** — Check config node broker settings.
 
-**Fixture doesn't appear in HA**
-- Check the MQTT broker connection in the config node
-- Confirm HA has the MQTT integration installed and configured
-- Send a `device:add` message manually via an inject node
-- Check Node-RED logs for error messages
+**Node shows "Disabled — not discovered"** — Change Discovery Mode to Enabled or Hidden and deploy.
 
-**State resets on restart**
-Configure disk context storage — see the [Required setup](#️-required-configure-node-red-context-storage) section above.
+**PIR stuck offline** — Warm-up timer running. Wait for configured warm-up period.
 
-**PIR stuck offline**
-The warm-up timer is running. Wait for the configured warm-up period.
-Or send `msg.device = "avty"` with `msg.payload = "online"` to bring it online manually.
+---
 
-**Relay not switching**
-- Check the relay MQTT topic in the NR debug panel
-- Confirm your relay controller subscribes to `{siteId}/{zone}/{controller}/relay/{relayNum}`
-- Relay payload is `"1"` (ON) or `"0"` (OFF) as a string
+## Version history
 
-**DMX channels not responding**
-- Verify DMX channel numbers match your fixture's start address
-- Check the DMX MQTT topic in the NR debug panel
-- Confirm your DMX controller subscribes to `{siteId}/{zone}/dmx/{universe}`
+| Version | Changes |
+|---|---|
+| 0.2.2 | Group Node status updates, broker feedback, version in editor panel |
+| 0.2.1 | Hidden mode — entity not auto-placed in dashboard |
+| 0.2.0 | Canvas button toggles remove/add, auto-discovery on deploy |
+| 0.1.9 | Correct disk store name, auto-discovery fallback, node ordering |
+| 0.1.8 | Section reordering all nodes, Config picker position |
+| 0.1.7 | Discovery Mode, broker already-connected fix |
+| 0.1.6 | Canvas button fix |
+| 0.1.5 | Context store error suppressed |
+| 0.1.2 | Original subflow colours restored |
+| 0.1.1 | UI fixes, postfix alphabet, Config Label, Discovery Mode |
+| 0.1.0 | Initial release |
 
 ---
 

package/nodes/ha-mqtt-button.html

@@ -51,9 +51,11 @@
 
         label: function () {
             if (this.name) return this.name;
-            const id      = this.uid        || '?';
-            const postfix = this.uidPostfix || '';
-            return 'S-' + id + postfix;
+            const id  = `S-${this.uid || '?'}${this.uidPostfix || ''}`;
+            const pos = this.buttonPosition || '';
+            const sit = this.situation      || 'in';
+            const area = this.area          || '';
+            return `${id} · ${pos} button ${sit} ${area}`.trim();
         },
 
         labelStyle: function () {

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

@@ -53,9 +53,11 @@
 
         label: function () {
             if (this.name) return this.name;
-            const id      = this.uid      || '?';
-            const postfix = this.uidPostfix || '';
-            return 'LG-' + id + postfix;
+            const id   = `LG-${this.uid || '?'}${this.uidPostfix || ''}`;
+            const type = this.deviceType || '';
+            const sit  = this.situation  || 'in';
+            const area = this.area       || '';
+            return `${id} · ${type} Group ${sit} ${area}`.trim();
         },
 
         labelStyle: function () {

package/nodes/ha-mqtt-dmx.html

@@ -175,10 +175,11 @@
 
         label: function () {
             if (this.name) return this.name;
-            const prefix  = this.uidPrefix  || 'L';
-            const id      = this.uid        || '?';
-            const postfix = this.uidPostfix || '';
-            return prefix + '-' + id + postfix;
+            const id   = `${this.uidPrefix || 'L'}-${this.uid || '?'}${this.uidPostfix || ''}`;
+            const type = this.deviceType || '';
+            const sit  = this.situation  || 'in';
+            const area = this.area       || '';
+            return `${id} · ${type} ${sit} ${area}`.trim();
         },
 
         labelStyle: function () {

package/nodes/ha-mqtt-pir.html

@@ -52,9 +52,11 @@
 
         label: function () {
             if (this.name) return this.name;
-            const id      = this.uid        || '?';
-            const postfix = this.uidPostfix || '';
-            return 'S-' + id + postfix;
+            const id   = `S-${this.uid || '?'}${this.uidPostfix || ''}`;
+            const type = this.pirType   || 'PIR';
+            const sit  = this.situation || 'in';
+            const area = this.area      || '';
+            return `${id} · ${type} PIR ${sit} ${area}`.trim();
         },
 
         labelStyle: function () {

package/nodes/ha-mqtt-relay.html

@@ -53,10 +53,11 @@
 
         label: function () {
             if (this.name) return this.name;
-            const prefix  = this.uidPrefix  || 'P';
-            const id      = this.uid        || '?';
-            const postfix = this.uidPostfix || '';
-            return prefix + '-' + id + postfix;
+            const id   = `${this.uidPrefix || 'P'}-${this.uid || '?'}${this.uidPostfix || ''}`;
+            const type = this.deviceType || '';
+            const sit  = this.situation  || 'in';
+            const area = this.area       || '';
+            return `${id} · ${type} ${sit} ${area}`.trim();
         },
 
         labelStyle: function () {

package/package.json

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