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

package/docs/node_contracts.md

@@ -0,0 +1,278 @@
+# Node Input / Output Contracts
+**Status:** Pre-packaging specification  
+**Purpose:** Blueprint for .html editor files and node .js runtime code  
+**Principle:** Simple by default. Zero outputs except where structurally required.
+
+---
+
+## Package Name (proposed)
+`node-red-contrib-dmx-for-ha`
+
+---
+
+## Shared Input Contract (all nodes)
+
+Every node accepts the following on its single input port:
+
+| Message type | Shape | Source | Action |
+|---|---|---|---|
+| Device add | `msg.device = "add"` | SYSTEM node inject | Run MQTT discovery, subscribe to HA cmd topic |
+| Device remove | `msg.device = "remove"` | SYSTEM node inject | Clear HA entities, unsubscribe, clear memory |
+| HA command | `msg.payload.state = "ON"/"OFF"` | MQTT In (internal) | Process state change |
+
+The MQTT broker connection, subscribe loop, and all publish operations are
+handled **internally** — no external MQTT In or MQTT Out nodes required.
+
+---
+
+## 1. DMX Group Node (v0.3.8)
+
+### Purpose
+Virtual fixture group. Receives a single HA command and fans it out to all
+downstream nodes. No physical hardware — exists only in Node-RED.
+
+### Input port (×1)
+| Message | Shape | Source |
+|---|---|---|
+| Device add/remove | `msg.device = "add"/"remove"` | SYSTEM node |
+| HA command | `msg.payload.state`, optional `brightness`, `color`, `transition`, `effect` | Internal MQTT (HA dashboard) |
+| Cascade (upstream) | `msg.dmx_trace = {source, path, depth}` + `msg.payload` | Upstream Group Node cascade output |
+
+### Output port (×1) — Link
+Fans the HA command payload downstream to child nodes.
+Wire to: DMX Node input, Relay Node input, or another Group Node input.
+
+Output message shape:
+```javascript
+{
+    dmx_trace: {
+        source: "LG-992",       // this group's ID
+        path:   ["LG-992"],     // breadcrumb trail for loop detection
+        depth:  1               // increments at each Group Node hop
+    },
+    payload: {                  // original HA command, passed through unchanged
+        state:      "ON",
+        brightness: 255,
+        color:      { r:255, g:128, b:0, w:255 },
+        transition: 1.5,
+        effect:     "rainbow"   // if applicable
+    }
+}
+```
+
+### Internal MQTT behaviour
+- Subscribes to: `homeassistant/light/LG-{id}/cmd`
+- Publishes discovery to: `homeassistant/light/LG-{id}/config`
+- Publishes state to: `homeassistant/light/LG-{id}/state`
+
+### Loop detection
+If `msg.dmx_trace.path` already contains this node's ID, the message is
+dropped and a `node.warn` fires. Prevents infinite loops in circular wiring.
+
+---
+
+## 2. DMX Node (v0.5.9)
+
+### Purpose
+Terminal fixture node. Receives commands from HA or a Group Node cascade,
+translates to DMX channel values and publishes via MQTT to the DMX controller.
+
+### Input port (×1)
+| Message | Shape | Source |
+|---|---|---|
+| Device add/remove | `msg.device = "add"/"remove"` | SYSTEM node |
+| HA command | `msg.payload.state`, optional `brightness`, `color`, `transition`, `effect` | Internal MQTT (HA dashboard) |
+| Cascade | `msg.dmx_trace` + `msg.payload` | Group Node cascade output |
+
+### Output ports
+**None.** Terminal node — DMX is the end of the signal chain.
+
+### Internal MQTT behaviour
+- Subscribes to: `homeassistant/light/{prefix}-{id}{postfix}/cmd`
+- Publishes discovery to: `homeassistant/light/{prefix}-{id}{postfix}/config`
+- Publishes state to: `homeassistant/light/{prefix}-{id}{postfix}/state`
+- Publishes DMX to: `MW3D/{zone}/dmx/{universe}` 
+  payload format: `"{channel3digits}{value3digits}"` e.g. `"212255"`
+
+### Supported colour modes
+`rgbw` `rgbww` `rgb` `cct` `brightness` `onoff`
+
+---
+
+## 3. Relay Node (v4.0.2)
+
+### Purpose
+Terminal 230V relay node. Receives ON/OFF commands from HA or a Group Node
+cascade, publishes integer relay commands via MQTT to the relay controller.
+
+**Not related to DMX.** Entirely separate control path and hardware.
+
+### Input port (×1)
+| Message | Shape | Source |
+|---|---|---|
+| Device add/remove | `msg.device = "add"/"remove"` | SYSTEM node |
+| HA command | `msg.payload.state = "ON"/"OFF"`, optional `effect` | Internal MQTT (HA dashboard) |
+| Cascade | `msg.dmx_trace` + `msg.payload` | Group Node cascade output |
+
+### Output ports
+**None.** Terminal node.
+
+### Internal MQTT behaviour
+- Subscribes to: `homeassistant/light/{prefix}-{id}{postfix}/cmd`
+- Publishes discovery to: `homeassistant/light/{prefix}-{id}{postfix}/config`
+- Publishes state to: `homeassistant/light/{prefix}-{id}{postfix}/state`
+- Publishes relay command to: `MW3D/{zone}/relay/{controller}/{relayNumber}`
+  payload: integer `1` (ON) or `0` (OFF)
+
+---
+
+## 4. Button Node (v5.0.3)
+
+### Purpose
+Wall button receiver. Listens for hardware controller MQTT payloads and
+publishes to HA as a `binary_sensor` (for automations) and a `button`
+entity (for dashboard UI mirror). HA automation logic handles everything
+downstream — no NR output required.
+
+### Input port (×1)
+| Message | Shape | Source |
+|---|---|---|
+| Device add/remove | `msg.device = "add"/"remove"` | SYSTEM node |
+| Physical press | `msg.payload = "{panelId}-{GPIOpin}"` plain string | Hardware controller via internal MQTT |
+| UI press | `msg.topic = HA button cmd topic` + `msg.payload = "PRESS"` | HA dashboard via internal MQTT |
+
+### Output ports
+**None.** HA receives the event via `binary_sensor` state topic.
+Automation logic lives in HA — not in Node-RED.
+
+### Internal MQTT behaviour
+- Subscribes to: `{controllerTopic}` (e.g. `buttons`) — plain string payloads
+- Subscribes to: `homeassistant/button/{prefix}-{id}{postfix}-BTN/cmd`
+- Publishes binary_sensor discovery to: `homeassistant/binary_sensor/{prefix}-{id}{postfix}/config`
+- Publishes button discovery to: `homeassistant/button/{prefix}-{id}{postfix}-BTN/config`
+- Publishes binary_sensor state to: `homeassistant/binary_sensor/{prefix}-{id}{postfix}/state`
+  payload: `"ON"` on press, HA `off_delay` handles auto-clear
+
+### Dual entity design
+Two HA entities per button:
+- `binary_sensor.s_10_a` — automation trigger, state changes ON then auto-clears
+- `button.s_10_a_btn` — dashboard UI mirror, press from HA frontend triggers same code path
+
+---
+
+## 5. PIR Node (v1.0.3)
+
+### Purpose
+PIR / motion sensor receiver. Listens for hardware controller MQTT payloads
+and publishes to HA as a `binary_sensor` with `device_class: motion`.
+Includes configurable warm-up delay on boot to prevent false automation
+triggers during system startup.
+
+### Input port (×1)
+| Message | Shape | Source |
+|---|---|---|
+| Device add | `msg.device = "add"` | SYSTEM node |
+| Device remove | `msg.device = "remove"` | SYSTEM node |
+| Availability toggle | `msg.device = "avty"` + `msg.payload = "online"/"offline"` | SYSTEM node or admin |
+| Motion detected | `msg.payload = "{panelId}-{GPIOpin}"` plain string | Hardware controller via internal MQTT |
+
+### Output ports
+**None.** HA receives motion events via `binary_sensor` state topic.
+Automation logic lives in HA — not in Node-RED.
+
+### Internal MQTT behaviour
+- Subscribes to: `{controllerTopic}` (e.g. `MW3D/Master/PIR_Sensors`) — plain string
+- Publishes discovery to: `homeassistant/binary_sensor/{prefix}-{id}{postfix}/config`
+- Publishes state to: `homeassistant/binary_sensor/{prefix}-{id}{postfix}/state`
+  payload: `"ON"` on motion, HA `off_delay` handles auto-clear
+- Publishes availability to: `homeassistant/binary_sensor/{prefix}-{id}{postfix}/avty`
+  payload: `"online"` / `"offline"`
+
+### Warm-up sequence
+On `device:add`:
+1. Immediately publishes `offline` to availability topic
+2. Starts configurable warm-up timer (default 120s)
+3. After timer: publishes `online` — PIR is now active
+4. Prevents false motion triggers during NR startup cascade
+
+---
+
+## Output Label — Group Node Cascade
+
+The single output on the Group Node needs a label that is:
+- Self-explanatory on first read
+- Not too technical
+- Accurate to what gets wired to it
+
+**Candidates:**
+| Label | Notes |
+|---|---|
+| `Cascade` | Accurate but slightly technical |
+| `Downstream` | Clear directional meaning |
+| `Link` | Simple, generic |
+| `To fixtures` | Descriptive but assumes only fixtures downstream |
+| `Output` | Generic but honest |
+
+**Output label: `Link`** ✓ Locked in.
+
+---
+
+## Canvas Topology (reference)
+
+```
+SYSTEM node
+    │  msg.device = "add"
+    ├──────────────────────────────────────────────────────┐
+    │                                                      │
+    ▼                                                      ▼
+[DMX Group Node LG-992]                          [Button Node S-10-A]
+    │  cascade output (Link)                      (no output — HA handles automation)
+    ├──────────────┬──────────────┐
+    ▼              ▼              ▼
+[DMX Node    [DMX Node    [Relay Node
+ L-992-A]    L-992-B]     P-51]
+(no output) (no output)  (no output)
+
+    ▼              ▼              ▼
+  MQTT           MQTT           MQTT
+DMX ctrl       DMX ctrl      Relay ctrl
+
+    └──────────────┴──────────────┘
+                   │
+                   ▼
+              MQTT Broker
+                   │
+                   ▼
+          Home Assistant
+       (all automation logic)
+```
+
+---
+
+## Pre-packaging Checklist
+
+- [ ] Agree on `Link` vs alternative for cascade output label
+- [x] Package name: `node-red-contrib-dmx-for-ha`
+- [x] Palette category: `DMX for HA`
+- [x] Display names: DMX, DMX Group, Relay, Button, PIR
+- [x] Internal types: ha-mqtt-dmx, ha-mqtt-dmx-group, ha-mqtt-relay, ha-mqtt-button, ha-mqtt-pir
+- [x] Cascade output label: `Link`
+- [x] Zero outputs on DMX, Relay, Button, PIR
+- [x] Passthrough output removed from all node code
+- [x] node.warn messages updated — no passthrough references
+- [x] Shared utility module decision: INLINE for v1, extract in v2
+- [x] MQTT broker via config node (Option 3)
+- [x] Config node: `ha-mqtt-config` — one per zone
+- [x] Zone in config node — multi-zone = multiple config nodes
+- [x] MQTT settings in config node, topics per node
+- [x] Relay controller MQTT: broker in config, topic built per node
+- [ ] Write ha-mqtt-config .html + .js (FIRST — all other nodes depend on it)
+- [ ] Write ha-mqtt-dmx .html + .js
+- [ ] Write ha-mqtt-dmx-group .html + .js
+- [ ] Write ha-mqtt-relay .html + .js
+- [ ] Write ha-mqtt-button .html + .js
+- [ ] Write ha-mqtt-pir .html + .js
+- [ ] Write package.json
+- [ ] Test packaged install end to end
+- [ ] Test all nodes reference config node correctly
+- [ ] Publish to flows.nodered.org

package/docs/nr_subflow_gotchas.md

@@ -0,0 +1,258 @@
+# Node-RED 4.1.x — Subflow Development Gotchas
+
+A collection of non-obvious issues discovered while building a production subflow
+library for a Home Assistant / MQTT lighting control system on Node-RED 4.1.6.
+Posting these here so others don't spend hours rediscovering them.
+
+---
+
+## 1. You Cannot Import a Subflow Definition and Its Instances in the Same JSON
+
+This is the big one. If you export a flow that contains both a subflow definition
+and instances of that subflow on a tab, and try to re-import it — NR will throw:
+
+```
+TypeError: Cannot read properties of undefined (reading 'length')
+```
+
+There is no helpful error message. It fails silently in a confusing way.
+
+### Why It Happens
+
+When NR processes a JSON import, it encounters the subflow instance
+(`"type": "subflow:abc123"`) and tries to look up the subflow definition to
+validate the port count. If the definition hasn't been fully registered yet
+(even if it appears earlier in the same JSON array), the lookup fails.
+
+### The Fix — Two-Step Import
+
+Split your flow into two separate JSON files:
+
+**File 1 — Subflow definitions only** (no tab, no instances):
+```json
+[
+  { "id": "abc123", "type": "subflow", "name": "My Node", ... },
+  { "id": "fn001",  "type": "function", "z": "abc123", ... },
+  { "id": "mq001",  "type": "mqtt out", "z": "abc123", ... }
+]
+```
+
+**File 2 — Tab and instances only** (no subflow definitions):
+```json
+[
+  { "id": "tab001", "type": "tab", ... },
+  { "id": "inst01", "type": "subflow:abc123", "z": "tab001", ... }
+]
+```
+
+**Import sequence:**
+1. Import File 1 — **do NOT deploy yet**
+2. Import File 2 immediately (while File 1 is still in memory)
+3. Deploy both together
+
+The key is step 2 must happen before deploying. Once you deploy File 1, NR
+registers the subflow definitions. You can then import File 2 separately and
+deploy again. Both sequences work — the important thing is the definition must
+be in NR's memory before the instance import is processed.
+
+### Bonus Gotcha — ID Conflicts
+
+If you re-import subflow definitions that already exist in NR (same IDs), NR
+will show a conflict warning and offer Import vs Copy. **Copy assigns new IDs**
+which then breaks File 2 (the instances still reference the old IDs). 
+
+Solution: bump the version and regenerate all node IDs each time you publish
+a new version of your subflow definitions. Every node in the file — subflow
+definition, internal function nodes, internal MQTT nodes, link nodes — needs
+a fresh ID. NR generates IDs as 16-character hex strings (`secrets.token_hex(8)`
+in Python).
+
+---
+
+## 2. The `tostatus: true` Debug Node Does Not Work Inside Subflows
+
+If you place a debug node inside a subflow with `tostatus: true` (the "Show
+as status" option), the status text will **not** appear under the subflow
+instance node on the canvas. It works fine for regular function nodes but
+does not propagate through the subflow boundary.
+
+### The Correct Solution — Subflow Status Port
+
+NR has a built-in mechanism for this that is easy to miss:
+
+1. Open your subflow definition (double-click the subflow in the palette)
+2. Click the **edit properties** button (pencil icon, top left)
+3. Tick the **"Status"** checkbox — this adds a special status input port
+
+In the subflow JSON this appears as a `status` field on the subflow definition:
+
+```json
+{
+  "id": "abc123",
+  "type": "subflow",
+  "name": "My Node",
+  "status": {
+    "x": 555,
+    "y": 195,
+    "wires": [{ "id": "fn001", "port": 2 }]
+  }
+}
+```
+
+The `port` value is **zero-indexed**, so `"port": 2` = output 3 of the function
+node. Wire your function node's status output to this port and status messages
+will correctly appear under the subflow instance on the canvas.
+
+### What the Function Node Should Send
+
+The status port expects the standard NR status object on `msg.status`:
+
+```javascript
+node.send([
+    null,           // output 1
+    null,           // output 2
+    {               // output 3 → status port
+        status: {
+            fill:  "green",
+            shape: "ring",
+            text:  "L-991 ready — awaiting HA commands"
+        }
+    },
+    null,           // output 4
+]);
+```
+
+Valid `fill` values: `"red"`, `"green"`, `"yellow"`, `"blue"`, `"grey"`
+Valid `shape` values: `"ring"`, `"dot"`
+
+---
+
+## 3. Subflow Env Var JSON — All Values Must Be Strings
+
+When hand-crafting subflow env var definitions in JSON, all `value` fields must
+be strings — even for `num` and `bool` types. NR will silently fail or behave
+unexpectedly if you pass integers or booleans.
+
+**Wrong:**
+```json
+{ "name": "<HA_MQTT_QOS>", "type": "num", "value": 0 }
+{ "name": "<HA_enabled>",  "type": "bool", "value": true }
+```
+
+**Correct:**
+```json
+{ "name": "<HA_MQTT_QOS>", "type": "num", "value": "0" }
+{ "name": "<HA_enabled>",  "type": "bool", "value": "true" }
+```
+
+---
+
+## 4. Font Awesome Icons on Env Var Labels
+
+You can add icons to env var labels in the subflow properties panel — they
+appear next to the label text and make the panel much easier to scan. Add an
+`icon` field to the `ui` object:
+
+```json
+{
+    "name": "<DEVICE_area>",
+    "type": "str",
+    "value": "",
+    "ui": {
+        "label": { "en-US": "Area:" },
+        "type": "select",
+        "icon": "font-awesome/fa-map-marker",
+        "opts": { "opts": [ ... ] }
+    }
+}
+```
+
+Useful icon mappings for home automation subflows:
+
+| Field type | Icon |
+|---|---|
+| Zone / Location | `font-awesome/fa-location-arrow` |
+| Area | `font-awesome/fa-map-marker` |
+| Sub-area | `font-awesome/fa-map-marker` |
+| Device type | `font-awesome/fa-lightbulb-o` |
+| Colour mode | `font-awesome/fa-sliders` |
+| ID / Prefix / Postfix | `font-awesome/fa-tv` |
+| Channel numbers | `font-awesome/fa-sort-numeric-asc` |
+| Timing fields | `font-awesome/fa-clock-o` |
+| MQTT topics | `font-awesome/fa-exchange` |
+| HA Icon field | `font-awesome/fa-image` |
+| Section headers | `font-awesome/fa-hand-spock-o` |
+
+Section separator entries (type `none`) also support icons and are useful for
+visually grouping related env vars:
+
+```json
+{
+    "name": "SETTINGS_Required",
+    "type": "str",
+    "value": "",
+    "ui": {
+        "label": { "en-US": "SETTINGS (*Required)" },
+        "type": "none",
+        "icon": "font-awesome/fa-hand-spock-o"
+    }
+}
+```
+
+---
+
+## 5. MQTT In Node Inside a Subflow — Plain String Payloads
+
+If your subflow's internal MQTT In node receives plain string payloads (e.g.
+from a hardware controller publishing `"10-54"` rather than a JSON object),
+set `datatype` to `"auto-detect"` not `"json"`.
+
+With `datatype: "json"`, NR will throw:
+```
+Failed to parse JSON string
+```
+
+For nodes that receive HA commands (which are always JSON), `"json"` is correct.
+For nodes that receive raw hardware controller payloads, use `"auto-detect"`.
+
+```json
+{
+    "type": "mqtt in",
+    "datatype": "auto-detect"
+}
+```
+
+---
+
+## 6. The MQTT In Node Can Subscribe to Multiple Topics
+
+An MQTT In node with `inputs: 1` can receive subscribe/unsubscribe commands
+from a function node. This lets one MQTT In node listen on multiple topics
+simultaneously — useful when a node needs to receive both hardware controller
+payloads AND HA dashboard command payloads.
+
+Pattern:
+```javascript
+// On device:add, send two subscribe messages on output 2
+node.send([discoveryPayload, { topic: "hardware/topic", action: "subscribe" }, ...]);
+node.send([uiDiscovery,      { topic: "ha/cmd/topic",   action: "subscribe" }, ...]);
+
+// Entry point — differentiate by topic
+if (msg.topic === "hardware/topic" && msg.payload === CFG.devicePayload) {
+    handlePhysicalPress();
+}
+if (msg.topic === "ha/cmd/topic" && msg.payload === "PRESS") {
+    handleUiPress();
+}
+```
+
+The same MQTT In node serves as receiver for both, and both routes execute
+identical code paths.
+
+---
+
+*Discovered during development of a Node-RED → Home Assistant DMX/relay/sensor
+lighting control system. NR version 4.1.6, HA 2026.x.*
+
+*If this saved you time, consider posting your own discoveries — future
+developers (and future AI models) will thank you.*