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

package/README.md

@@ -0,0 +1,282 @@
+# node-red-contrib-dmx-for-ha
+
+DMX lighting control for Home Assistant via Node-RED and MQTT.
+
+Place a node, fill in the settings, deploy. Your DMX fixture appears in Home Assistant automatically — ready to use in automations, dashboards, and scenes.
+
+No YAML. No custom MQTT discovery config. No external wiring inside Node-RED.
+
+---
+
+## What this package does
+
+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:
+
+- Full Home Assistant MQTT discovery — entities appear automatically in HA
+- 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
+
+> **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.
+
+---
+
+## 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 |
+
+---
+
+## Requirements
+
+- **Node-RED** 3.0.0 or later
+- **Home Assistant** with MQTT integration configured
+- **Mosquitto** (or any MQTT broker) accessible from Node-RED
+- **Node.js** 18.0.0 or later
+
+---
+
+## Installation
+
+```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.
+
+**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`
+
+2. Find the `contextStorage` section (it may be commented out) and update it:
+
+```javascript
+contextStorage: {
+    default: {
+        module: "memory"
+    },
+    disk: {
+        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.
+
+---
+
+## Quick start
+
+### 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**
+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)
+   - **Broker** — select your existing MQTT broker config
+4. Click **Add** — the config is saved and shared across all nodes
+
+### 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
+
+Your fixture appears in Home Assistant automatically under **Settings → Devices**.
+
+### 3. Wire the SYSTEM node
+
+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:
+
+```
+msg.device = "add"
+```
+
+Wire it to the input of every node on your canvas.
+
+---
+
+## Multi-zone deployments
+
+Create one `ha-mqtt-config` node per zone:
+
+- `Master Zone` → Site ID: `home`, Zone: `Master`
+- `Guest Wing`  → Site ID: `home`, Zone: `GuestWing`
+
+Each DMX, Relay, Button and PIR node picks its zone via the Config dropdown.
+MQTT topics are built automatically: `{siteId}/{zone}/dmx/{universe}`.
+
+---
+
+## 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.
+
+```
+[DMX Group LG-992]
+      │ Link
+      ├──→ [DMX L-992-A]
+      ├──→ [DMX L-992-B]
+      └──→ [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.
+
+---
+
+## Wall buttons
+
+The Button node 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)
+
+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.
+
+---
+
+## 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.
+
+This prevents spurious motion events during controller reboot from triggering
+lights in the middle of the night.
+
+Set the warm-up time to match your PIR hardware's stabilisation period (default 120s).
+
+---
+
+## MQTT topic formats
+
+| Node | Topic |
+|---|---|
+| DMX | `{siteId}/{zone}/dmx/{universe}` |
+| Relay controller | `{siteId}/{zone}/{controller}/relay/{relayNum}` |
+| HA discovery | `homeassistant/light/{fixtureId}/config` |
+| HA state | `homeassistant/light/{fixtureId}/state` |
+| HA command | `homeassistant/light/{fixtureId}/cmd` |
+
+---
+
+## DMX output format
+
+DMX values are published as a 6-character string:
+
+```
+"212255"  →  channel 212, value 255
+"201000"  →  channel 201, value 0
+```
+
+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` |
+
+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`.
+
+---
+
+## Troubleshooting
+
+**Nodes don't appear in palette**
+Restart Node-RED. Check the NR log for install errors.
+
+**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
+
+**State resets on restart**
+Configure disk context storage — see the [Required setup](#️-required-configure-node-red-context-storage) section above.
+
+**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
+
+**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}`
+
+---
+
+## Author
+
+DeSwaggy — Discord: @deswaggy
+
+## License
+
+Apache-2.0

package/docs/config_node_spec.md

@@ -0,0 +1,236 @@
+# ha-mqtt-config — Config Node Specification
+**Status:** Pre-packaging design spec  
+**Purpose:** Defines what moves to the shared config node vs stays per-node
+
+---
+
+## The Config Node: `ha-mqtt-config`
+
+Created once per site (or per zone). Referenced by all other nodes via dropdown.
+Replaces all site-wide repeated fields that were previously entered on every node.
+
+---
+
+## Config Node Fields
+
+### SITE
+| Field | Env var replaced | Notes |
+|---|---|---|
+| Site ID | `<HA_site_unique_id>` | e.g. `home`, `unit4`, `smithresidence` — used in MQTT topic construction |
+| MQTT Broker | (broker config node) | Dropdown picks existing NR MQTT broker config |
+
+### HA MQTT
+| Field | Env var replaced | Notes |
+|---|---|---|
+| Discovery prefix | `<HA_discovery_prefix>` | Default `homeassistant` — rarely changes |
+| QoS | `<HA_MQTT_QOS>` | Default `0` |
+| Retain | `<HA_MQTT_retain_flag>` | Default `false` |
+| Config topic | `<HA_config_topic>` | Default `config` |
+| State topic | `<HA_state_topic>` | Default `state` |
+| Command topic | `<HA_command_topic>` | Default `cmd` |
+| Availability topic | `<HA_availability_topic>` | Default `avty` — PIR only but lives here |
+
+### DEFAULTS (site-wide)
+| Field | Env var replaced | Notes |
+|---|---|---|
+| Enabled by default | `<HA_enabled_by_default>` | Default `true` — applies to all nodes |
+| Disk save delay (s) | `<CONTEXT_STORE_values_to_disk_delay_in_seconds>` | Default `10` |
+| Flash Short (s) | `<HA_effects_flash_time_Short_(seconds)>` | Default `1` |
+| Flash Long (s) | `<HA_effects_flash_time_Long_(seconds)>` | Default `10` |
+
+---
+
+## What Stays Per-Node
+
+Everything fixture-specific stays on the individual node editor panel.
+Dramatically shorter menus as a result.
+
+### ha-mqtt-dmx
+```
+FIXTURE (* Required)
+  Config:        [ My Home ▼ ]         ← config node picker
+  Colour Mode:   [ RGBW ▼ ]
+  Device Type:   [ Downlight ▼ ]
+  Prefix:        [ L ▼ ]   ID: [992]   Postfix: [ -A ▼ ]
+  Area:          [ Bedroom 1 ▼ ]
+  Situation:     [ in ▼ ]
+  Sub-Area:      [ Bed (North) ▼ ]
+
+DMX CHANNELS
+  Red:   [201]   Green: [202]
+  Blue:  [203]   White: [204]   Warm White: [205]
+
+DMX CONTROLLER
+  Controller: [1]   Universe: [1]
+
+OPTIONS
+  HA Icon:          [mdi:lightbulb]
+  Show effects      ☑
+  Enable transitions ☑
+  Sync via Group    ☐
+  Default state:    [ OFF ▼ ]
+
+ADVANCED
+  DMX limiter:      [255]
+  Min output:       [1]
+  Brightness bump:  [212]
+  Transition ticks: [31]
+```
+
+### ha-mqtt-dmx-group
+```
+GROUP (* Required)
+  Config:        [ My Home ▼ ]
+  Group Name:    [Bedroom 1 Downlights]
+  Group ID:      [992]   Postfix: [ (none) ▼ ]
+  Device Type:   [ Downlight ▼ ]
+  Colour Mode:   [ RGBW ▼ ]
+  Area:          [ Bedroom 1 ▼ ]
+  Situation:     [ in ▼ ]
+  Sub-Area:      [ (none) ▼ ]
+
+OPTIONS
+  HA Icon:          [mdi:lightbulb-group]
+  Show effects      ☑
+  Enable transitions ☑
+  Default state:    [ OFF ▼ ]
+
+ADVANCED
+  Max group depth:  [10]
+```
+
+### ha-mqtt-relay
+```
+RELAY (* Required)
+  Config:        [ My Home ▼ ]
+  Device Type:   [ Exhaust Fan ▼ ]
+  Prefix:        [ P ▼ ]   ID: [51]   Postfix: [ (none) ▼ ]
+  Area:          [ Bathroom ▼ ]
+  Situation:     [ in ▼ ]
+  Sub-Area:      [ (none) ▼ ]
+
+CONTROLLER
+  Controller: [15]   Relay: [25]
+  MQTT segment: [relay]
+
+OPTIONS
+  HA Icon:       [mdi:fan]
+  Show effects   ☑
+  Default state: [ OFF ▼ ]
+```
+
+### ha-mqtt-button
+```
+BUTTON (* Required)
+  Config:        [ My Home ▼ ]
+  Cable ID:      [10]   Letter: [ -A ▼ ]
+  Area:          [ Bedroom 1 ▼ ]
+  Situation:     [ in ▼ ]
+  Sub-Area:      [ Bed (North) ▼ ]
+  Position:      [ Top Left ▼ ]
+
+CONTROLLER
+  Payload (panelId-GPIOpin): [10-54]
+  Subscribe topic:           [buttons]
+
+OPTIONS
+  HA Icon:       [mdi:gesture-tap-button]
+  LED Colour:    [ Blue ▼ ]
+  Hold time (s): [0.5]
+```
+
+### ha-mqtt-pir
+```
+PIR (* Required)
+  Config:        [ My Home ▼ ]
+  Cable ID:      [31]   Sensor Group: [ (none) ▼ ]
+  Area:          [ Bedroom 1 ▼ ]
+  Situation:     [ in ▼ ]
+  Sub-Area:      [ Ceiling ▼ ]
+  PIR Type:      [ Ceiling ▼ ]
+
+CONTROLLER
+  Payload (panelId-GPIOpin): [13-62]
+  Subscribe topic:           [MW3D/Master/PIR_Sensors]
+
+OPTIONS
+  HA Icon:           [mdi:motion-sensor]
+  Cable Colour:      [ Purple ▼ ]
+  Hold time (s):     [15]
+  Warm-up time (s):  [120]
+```
+
+---
+
+## Fields Removed From Per-Node (now in config)
+
+These fields disappear entirely from individual node editors:
+
+| Field | Was in |
+|---|---|
+| `<HA_site_unique_id>` | DMX, DMX Group, Relay, Button, PIR |
+| `<HA_discovery_prefix>` | DMX, DMX Group, Relay, Button, PIR |
+| `<HA_MQTT_QOS>` | DMX, DMX Group, Relay, Button, PIR |
+| `<HA_MQTT_retain_flag>` | DMX, DMX Group, Relay, Button, PIR |
+| `<HA_config_topic>` | DMX, DMX Group, Relay, Button, PIR |
+| `<HA_state_topic>` | DMX, DMX Group, Relay, Button, PIR |
+| `<HA_command_topic>` | DMX, DMX Group, Relay, Button, PIR |
+| `<HA_availability_topic>` | PIR |
+| `<HA_enabled_by_default>` | DMX, DMX Group, Relay, Button, PIR |
+| `<CONTEXT_STORE_values_to_disk_delay_in_seconds>` | DMX, DMX Group, Relay |
+| `<HA_effects_flash_time_Short_(seconds)>` | DMX, DMX Group, Relay |
+| `<HA_effects_flash_time_Long_(seconds)>` | DMX, DMX Group, Relay |
+
+**12 fields removed from every node.** For a deployment with 50 DMX nodes, 
+10 relays, 20 buttons, 10 PIRs — that's 90 × 12 = 1,080 fields the user 
+never has to touch.
+
+---
+
+## Zone Decision
+
+Zone (`<CONTROLLER_zone>`) could go in the config node OR stay per-node.
+
+**Arguments for config node:**
+- Most deployments are single-zone (`Master`)
+- If all nodes are in the same zone, enter it once
+
+**Arguments for per-node:**
+- Multi-zone deployments (Master + Guest Wing) need per-node zone selection
+- A user might have two config nodes — one per zone — which also works
+
+**Recommendation:** Keep Zone in config node, allow multiple config nodes 
+for multi-zone deployments. A user with Master + Guest Wing creates:
+- `ha-mqtt-config` named "Master Zone" with zone=Master  
+- `ha-mqtt-config` named "Guest Wing" with zone=GuestWing
+
+Each node then picks the right config from the dropdown.
+This is cleaner than per-node zone selection.
+
+---
+
+## Relay-Specific MQTT Settings
+
+The relay node currently has separate QoS/retain for the relay controller 
+(separate from the HA-side MQTT settings). In the config node:
+
+- HA MQTT settings → main config node settings
+- Relay controller MQTT → either same config node with "Relay" section,
+  OR per-node (since relay controllers may differ from HA broker)
+
+**Recommendation:** Keep relay controller QoS/retain per-node under 
+CONTROLLER section. It's controller-hardware specific, not site-wide.
+
+---
+
+## Pre-packaging Checklist Update
+
+- [x] Config node concept agreed
+- [x] Config node fields defined  
+- [x] Per-node fields defined (trimmed menus)
+- [x] Zone goes in config node (multi-zone = multiple config nodes)
+- [ ] Config node name finalised: `ha-mqtt-config`
+- [ ] Agree on relay controller MQTT settings (per-node recommended)
+- [ ] Write config node .html editor file (first, before any other node)
+- [ ] Write config node .js runtime file
+- [ ] Then write ha-mqtt-dmx .html (references config node)