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

package/docs/dmx_node_env_reference.md

@@ -0,0 +1,341 @@
+# DMX Node — Environmental Variable Reference
+**Version: 0.5.0**
+Samba: `\\HOMEASSISTANT\`
+
+---
+
+## Notation
+
+| Bracket style | Scope | Where to set |
+|---|---|---|
+| `<variable>` | **Node-level** subflow environmental | Double-click subflow node → Edit subflow template → double-click the tab → subflow env menu |
+| `<<<variable>>>` | **Flow-level** environmental (global to all nodes on the tab) | Double-click the tab → gear icon → flow envs |
+| `<<variable>>` | **RAM memory** — fast, lost on NR restart/reboot | Managed internally by the node. Do not set manually |
+| `<<D_variable>>` | **Disk memory** — persistent, survives restarts | Managed internally by the node. Written after the disk-save debounce delay |
+
+> **Rule of thumb:**
+> - Single brackets `<>` → one fixture
+> - Triple brackets `<<<>>>` → every DMX node on the flow simultaneously
+> - Double brackets `<<>>` → runtime RAM state (fast, temporary)
+> - Double brackets with `D_` prefix `<<D_>>` → persisted disk state (survives reboot/death)
+
+---
+
+## Flow-Level Globals `<<<...>>>`
+
+These are set once per deployment and apply to **every** DMX subflow node on the tab.
+
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `<<<DMX_NODE_FLOW_Transition_Rate_Limit>>>` | `float` | `1` | Global transition speed multiplier. `0.1` = potato/limp mode, `0.5` = half speed, `1` = normal, `2` = double speed (overclocked). Acts as a divisor on each node's tick rate — raise it to reduce total network/controller load across all fixtures. |
+| `<<<DMX_NODE_FLOW_Transition_HA_UI_Time_(seconds)>>>` | `float` | `1` | Fallback transition duration (seconds) used when HA does not include a `transition` value in the command payload. |
+
+---
+
+## Node-Level Subflow Envs `<...>`
+
+Set individually per fixture node in the subflow env menu.
+
+---
+
+### HA Identity
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<HA_discovery_prefix>` | `string` | `homeassistant` | MQTT discovery prefix — must match HA's configured discovery prefix. |
+| `<HA_site_unique_id>` | `string` | `site01` | Unique site identifier. Prefixes the DMX MQTT topic. |
+| `<HA_component>` | `string` | `light` | HA component type. Almost always `light`. |
+| `<HA_unique_id_prefix>` | `string` | `dmx` | Prefix for the fixture's unique ID. |
+| `<HA_unique_id>` | `string` | `lounge_spot_01` | The fixture's unique ID. Must be unique across the entire HA instance. |
+| `<HA_unique_id_postfix>` | `string` | _(empty)_ | Optional postfix appended to the unique ID. |
+
+---
+
+### MQTT
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<HA_MQTT_retain_flag>` | `bool` | `true` | Whether MQTT messages are published with the retain flag. |
+| `<HA_MQTT_QOS>` | `int` | `1` | MQTT Quality of Service level. `0`, `1`, or `2`. |
+| `<HA_config_topic>` | `string` | `config` | Topic segment for HA MQTT discovery config messages. |
+| `<HA_command_topic>` | `string` | `set` | Topic segment HA publishes commands to. |
+| `<HA_state_topic>` | `string` | `state` | Topic segment this node publishes state back to HA on. |
+
+---
+
+### HA Feature Flags
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<HA_schema>` | `string` | `json` | MQTT light schema. Use `json`. |
+| `<HA_optimistic>` | `bool` | `false` | Whether HA assumes commands succeed without waiting for a state report. Keep `false` — node reports state explicitly. |
+| `<HA_enabled_by_default>` | `bool` | `true` | Whether the entity is enabled by default in the HA UI. |
+| `<HA_icon>` | `string` | `mdi:lightbulb` | MDI icon shown in the HA dashboard. |
+| `<HA_supported_color_modes>` | `string` | `rgbw` | Comma-separated list of supported color modes. Drives the entire ON/OFF/transition dispatch table. See supported values below. |
+| `<HA_brightness>` | `bool` | `true` | Advertise brightness support to HA. |
+| `<HA_brightness_scale_and_dmx_limiter>` | `int` | `190` | **Required.** HA brightness scale AND DMX output limiter in one value. Sets the maximum DMX output (0–255). Use to protect fixtures on undersized transformers (e.g. `190` for 9V fixtures on 12V supply). Also baked into the gamma lookup table at startup. |
+| `<DMX_min_output>` | `int` | `1` | Minimum DMX output value when the fixture is ON. Prevents the gamma curve collapsing low brightness levels to DMX zero, which would cause the fixture to appear off while the HA slider is visibly above 0%. Default `1` guarantees something perceptible at any brightness above zero. Set to `0` to disable for pure gamma behaviour — recommended for lighting designers who want mathematically correct perceptual response and understand that sub-threshold values are genuinely imperceptible. OFF commands always send true 0 regardless of this setting. |
+| `<HA_Transitions_Enabled>` | `bool` | `true` | Whether this fixture supports transitions. Advertised in the HA discovery payload. Set to `false` for binary `onoff` fixtures — all transition commands will fall back to the instant handler regardless of what HA sends. |
+| `<HA_effects>` | `bool` | `true` | Advertise effects support to HA. |
+| `<HA_effects_list>` | `string` | `flash_short,flash_long,strobe,rainbow,fire,flicker,twinkle,color_chase,scan,random,police,christmas,halloween,calaveras,party,relaxing,temperature_transition,sleep_transition,fireworks` | Comma-separated list of effect names advertised to HA. Must match keys in `EFFECT_MAP`. |
+| `<DMX_Effects_Group_Controlled>` | `bool` | `true` | **ADVANCED.** Controls who triggers effects. `true` = fixture only accepts effects via AUX from a parent Group Node (siblings stay in sync). `false` = fixture accepts effects directly from HA payload (independent). Set to `false` for standalone fixtures with no Group Node parent. |
+| `<HA_effects_flash_time_Short_(seconds)>` | `float` | `0.5` | Duration of the `flash_short` effect in seconds. |
+| `<HA_effects_flash_time_Long_(seconds)>` | `float` | `2` | Duration of the `flash_long` effect in seconds. |
+
+#### Supported Color Modes
+| Value | Channels used |
+|---|---|
+| `onoff` | White only, no dimming |
+| `brightness` | White with brightness |
+| `rgb` | Red, Green, Blue |
+| `rgbw` | Red, Green, Blue, Cold White |
+| `rgbww` | Red, Green, Blue, Cold White, Warm White |
+| `color_temp` | Cold White + Warm White (mireds mapping) |
+| `white` | White with brightness only |
+| `rgb,color_temp` | RGB or CT, HA selects active sub-mode |
+| `rgbw,color_temp` | RGBW or CT |
+| `rgbww,color_temp` | RGBWW or CT |
+
+---
+
+### DMX Controller
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<DMX_controller_zone>` | `string` | `rack_a` | The zone/location label of the DMX controller. Used in MQTT topic and device description. |
+| `<DMX_universe>` | `int` | `1` | DMX universe number. Used in MQTT topic. |
+| `<CONTROLLER_fw_v>` | `string` | `2.1.4` | DMX controller firmware version. Informational only — shown in HA device info. |
+
+---
+
+### DMX Channels
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<DMX_ch_red>` | `int` | `1` | DMX channel for Red. |
+| `<DMX_ch_green>` | `int` | `2` | DMX channel for Green. |
+| `<DMX_ch_blue>` | `int` | `3` | DMX channel for Blue. |
+| `<DMX_ch_white>` | `int` | `4` | DMX channel for Cold White (also used as the single white channel for `brightness`, `onoff`, `white` modes). |
+| `<DMX_ch_warm_white>` | `int` | `5` | DMX channel for Warm White. Used by `rgbww` and `color_temp` modes. |
+| `<DMX_ch_color_temp>` | `int` | `6` | Dedicated CT channel if the fixture has one (uncommon). |
+
+---
+
+### Default ON Values
+
+Values sent when the fixture turns ON with no prior known state in memory.
+All values are raw 0–255 — gamma correction is applied automatically when sent to DMX.
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<DMX_default_on_v_brightness>` | `int` | `255` | Default brightness on first ON. |
+| `<DMX_default_on_v_red>` | `int` | `255` | Default Red channel value. |
+| `<DMX_default_on_v_green>` | `int` | `255` | Default Green channel value. |
+| `<DMX_default_on_v_blue>` | `int` | `255` | Default Blue channel value. |
+| `<DMX_default_on_v_white>` | `int` | `255` | Default Cold White channel value. |
+| `<DMX_default_on_v_warm_white>` | `int` | `0` | Default Warm White channel value. Defaults to `0` if not set. |
+| `<DMX_default_on_v_color_temp>` | `int` | `128` | Default color temperature in mireds. Defaults to `128` (midpoint between min/max) if not set. |
+| `<DMX_Brightness_Initial_on_value>` | `int` | `40` | **Head-start bump value (0–255).** Sent instantly to DMX at the very start of a transition when the fixture is coming from OFF, giving the room immediate usable light before the slow fade completes. Set to `0` to disable. Only fires when state was `OFF` — ignored mid-transition between two ON states. |
+
+---
+
+### Default OFF Values
+
+Values sent to DMX when the fixture turns OFF.
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<DMX_default_off_v_red>` | `int` | `0` | Red channel value when OFF. Defaults to `0`. |
+| `<DMX_default_off_v_green>` | `int` | `0` | Green channel value when OFF. Defaults to `0`. |
+| `<DMX_default_off_v_blue>` | `int` | `0` | Blue channel value when OFF. Defaults to `0`. |
+| `<DMX_off_v_white>` | `int` | `0` | White channel value when OFF. |
+
+---
+
+### Color Temperature
+
+Only relevant for `color_temp`, `rgbww`, `rgb,color_temp`, `rgbw,color_temp`, `rgbww,color_temp` modes.
+
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `<DMX_ct_min_mireds>` | `int` | `153` | Minimum mireds value the fixture supports (~6500K cool white). HA maps this to Cold White = 255, Warm White = 0. |
+| `<DMX_ct_max_mireds>` | `int` | `500` | Maximum mireds value the fixture supports (~2000K warm white). HA maps this to Cold White = 0, Warm White = 255. |
+
+> **Tip:** Check your fixture's spec sheet for the actual min/max. Common values: cool-only = 153–200, warm-only = 370–500, full range = 153–500.
+
+---
+
+### Transitions
+
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `<DMX_transition_ticks_ps>` | `int` | `31` | Transition interpolation steps per second for **this node only**. Higher = smoother fade but more DMX payloads per second from this fixture. 31 is a safe baseline. Tune up for premium fixtures, down for busy deployments. Multiplied by `<<<DMX_NODE_FLOW_Transition_Rate_Limit>>>` to get the effective tick rate. |
+
+---
+
+### Persistence
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<CONTEXT_STORE_values_to_disk_delay_in_seconds>` | `int` | `10` | How many seconds after the last command before RAM state is written to disk. Prevents excessive disk writes during rapid commands (e.g. dragging the colour wheel). Disk state survives NR restarts and HA reboots. |
+| `<FIXTURE_Default_State>` | `string` | `OFF` | State reported to HA on first boot before any command has been received and before disk memory is available. `ON` or `OFF`. |
+
+---
+
+### Device Metadata
+
+Informational only — populates the HA device info panel and MQTT discovery payload.
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<DEVICE_Type>` | `string` | `Spot` | Type of fixture (e.g. `Spot`, `Strip`, `Flood`, `Par`). |
+| `<DEVICE_situation>` | `string` | `above` | Positional description (e.g. `above`, `behind`, `under`). |
+| `<DEVICE_area>` | `string` | `Lounge` | Room or area the fixture is in. |
+| `<DEVICE_Sub_Location>` | `string` | `Couch` | More specific location within the area (e.g. `Couch`, `TV`, `Entry`). |
+
+---
+
+### Node Metadata
+
+| Variable | Type | Example | Description |
+|---|---|---|---|
+| `<NODE_code>` | `string` | `DMX-NODE` | Short identifier for this node type. Shown in HA device `sw_version` field. |
+| `<NODE_sw_v>` | `string` | `0.5.0` | Software version of this node. Shown in HA device `sw_version` field. |
+
+---
+
+## RAM & Disk Memory Keys
+
+These are not env vars — they are flow context store keys managed internally by the node.
+Listed here for debugging reference (visible in NR context store panel).
+
+| Key | Store | Description |
+|---|---|---|
+| `<<FIXTURE_RAM_Memory_State>>` | `memory` | Current state (`ON`/`OFF`) — fast access during operation. |
+| `<<FIXTURE_Disk_Memory_State>>` | `disk_values` | Persisted state — survives reboot. |
+| `<<bright>>` | `memory` | Current brightness (0–255). |
+| `<<D_bright>>` | `disk_values` | Persisted brightness. |
+| `<<red>>` | `memory` | Current Red value (0–255). |
+| `<<D_red>>` | `disk_values` | Persisted Red value. |
+| `<<green>>` | `memory` | Current Green value (0–255). |
+| `<<D_green>>` | `disk_values` | Persisted Green value. |
+| `<<blue>>` | `memory` | Current Blue value (0–255). |
+| `<<D_blue>>` | `disk_values` | Persisted Blue value. |
+| `<<white>>` | `memory` | Current Cold White value (0–255). |
+| `<<D_white>>` | `disk_values` | Persisted Cold White value. |
+| `<<warmWhite>>` | `memory` | Current Warm White value (0–255). |
+| `<<D_warmWhite>>` | `disk_values` | Persisted Warm White value. |
+| `<<colorTemp>>` | `memory` | Current color temperature (mireds). |
+| `<<D_colorTemp>>` | `disk_values` | Persisted color temperature. |
+| `timer_diskSave` | `node` | Handle for the debounced disk-write timer. |
+| `timer_transition` | `node` | Handle for the active transition `setInterval`. |
+| `timer_effect` | `node` | Handle for the active effect `setInterval`. |
+
+---
+
+## Quick Checklist — New Node Setup
+
+- [ ] Set `<HA_unique_id>` — must be unique across all HA entities
+- [ ] Set `<HA_supported_color_modes>` — drives everything else
+- [ ] Set `<HA_brightness_scale_and_dmx_limiter>` — **required**, node errors without it
+- [ ] Set `<DMX_min_output>` — default `1` (set to `0` for pure gamma, see note above)
+- [ ] Set `<HA_Transitions_Enabled>` — `false` for `onoff` fixtures, `true` (or leave unset) for everything else
+- [ ] Set DMX channels (`<DMX_ch_red>` etc.) for the fixture's mode
+- [ ] Set `<DMX_default_on_v_*>` values to match fixture's expected default colours
+- [ ] Set `<DMX_ct_min_mireds>` / `<DMX_ct_max_mireds>` if using any CT mode
+- [ ] Set `<DMX_Brightness_Initial_on_value>` — `0` to disable head-start bump, or a low value like `30`–`60` for rooms where instant light matters
+- [ ] Set `<FIXTURE_Default_State>` — usually `OFF`
+- [ ] Set `<CONTEXT_STORE_values_to_disk_delay_in_seconds>` — `10` is a safe starting point
+- [ ] Verify `<<<DMX_NODE_FLOW_Transition_Rate_Limit>>>` is set at flow level — `1` for normal
+- [ ] Verify `<<<DMX_NODE_FLOW_Transition_HA_UI_Time_(seconds)>>>` is set at flow level — fallback transition duration
+
+---
+
+## Group Node Env Variables `<...>`
+
+The Group Node uses mostly the same env keys as the DMX Node. Only the differences and additions are listed here.
+
+### Group Node — Differences from DMX Node
+
+| Variable | Notes |
+|---|---|
+| `<HA_brightness_scale_and_dmx_limiter>` | **Not used** — Group Node has no DMX output. Brightness scale is always 255 (full range) for HA reporting. Children apply their own limiter. |
+| `<DMX_ch_*>` | **Not used** — no DMX channels on a Group Node. |
+| `<DMX_default_on_v_*>` / `<DMX_default_off_v_*>` | **Not used** — replaced by `<GRP_default_on_v_*>` (see below). |
+| `<DMX_Brightness_Initial_on_value>` | **Not used** — initial bump lives at fixture level only. |
+| `<DMX_transition_ticks_ps>` | **Not used** — Group Node does not run a transition engine. It forwards transition time to children who handle their own stepping. |
+| `<HA_effects_list>` | Replaced by `<HA_group_effects_list>` — limited to group-safe effects only. |
+
+---
+
+### Group Node — Additions
+
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `<HA_group_effects_list>` | `string` | `flash_short,flash_long,strobe,rainbow,fire,flicker,twinkle,color_chase,scan,random,police,christmas,halloween,calaveras,party,fireworks` | Comma-separated list of effects the Group Node advertises to HA and forwards to children. Excludes `sleep_transition` and `temperature_transition` which are fixture-level only. |
+| `<DMX_Group_Max_Depth>` | `int` | `10` | Maximum AUX hop depth before a payload is dropped and `node.warn` is raised. Prevents infinite loops from accidental circular wiring. `0` = disabled (not recommended for production). Use the spinner in the Advanced env menu. |
+| `<GRP_default_on_v_brightness>` | `int` | `255` | Default brightness for the Group Node's own HA state recovery after reboot. |
+| `<GRP_default_on_v_red>` | `int` | `255` | Default Red for HA state recovery. |
+| `<GRP_default_on_v_green>` | `int` | `255` | Default Green for HA state recovery. |
+| `<GRP_default_on_v_blue>` | `int` | `255` | Default Blue for HA state recovery. |
+| `<GRP_default_on_v_white>` | `int` | `255` | Default Cold White for HA state recovery. |
+| `<GRP_default_on_v_warm_white>` | `int` | `0` | Default Warm White for HA state recovery. |
+| `<GRP_default_on_v_color_temp>` | `int` | `128` | Default color temperature (mireds) for HA state recovery. |
+
+---
+
+### Group Node — RAM & Disk Memory Keys
+
+| Key | Store | Description |
+|---|---|---|
+| `<<GRP_State>>` | `memory` | Current group state (`ON`/`OFF`). |
+| `<<D_GRP_State>>` | `disk_values` | Persisted group state. |
+| `<<bright>>` / `<<D_bright>>` | `memory` / `disk_values` | Same keys as DMX Node — shared naming convention. |
+| `<<red>>` / `<<D_red>>` etc. | `memory` / `disk_values` | Same keys as DMX Node. |
+| `timer_diskSave` | `node` | Debounced disk-write timer handle. |
+
+---
+
+### dmx_trace — AUX Payload Contract
+
+Every payload forwarded from a Group Node to its children includes a `dmx_trace` object:
+
+```javascript
+{
+    dmx_trace: {
+        source: "L-991-grp",           // ID of the immediate parent Group Node
+        path:   ["L-001-grp", "L-991-grp"],  // full ancestry from root to immediate parent
+        depth:  2                       // number of Group Node hops
+    },
+    payload: {                          // original HA command — unmodified
+        state: "ON",
+        brightness: 145,
+        transition: 3,
+        color: { r: 255, g: 58, b: 75 }
+    },
+    retain: false,
+    qos: 0
+}
+```
+
+- `source` — the immediate parent that sent this payload (useful for targeted fault-finding)
+- `path` — full chain from root group to immediate parent (visible in NR debug panel)
+- `depth` — compared against `<DMX_Group_Max_Depth>` on each hop; payload dropped if exceeded
+
+The DMX Node detects `msg.dmx_trace` at its entry point and routes via the AUX handler, which strips the trace and processes `msg.payload` identically to a direct HA command.
+
+---
+
+### Group Node Output Wiring
+
+| Output | Index | Use |
+|---|---|---|
+| 1 | `0` | MQTT — HA state topic + discovery config |
+| 2 | `1` | MQTT — subscribe / unsubscribe actions |
+| 3 | `2` | Node status + debug |
+| 4 | `3` | Original `msg` passthrough (untouched) |
+| **5** | **`4`** | **Fan-out to children — wire to DMX Node or child Group Node inputs** |
+| 6 | `5` | Spare |
+| 7 | `6` | Spare |
+
+> Output 5 is the key wire. Connect it to the input of every DMX Node or child Group Node that belongs to this group.