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

package/LICENSE

@@ -0,0 +1,28 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+node-red-contrib-dmx-for-ha
+Copyright (C) 2024-2026 DeSwaggy
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+Full licence text: https://www.gnu.org/licenses/gpl-3.0.txt
+
+ADDITIONAL NOTE:
+This package was built from 6+ years of real-world professional 
+installation experience. If you use it, improve it, or build on it —
+please contribute your changes back to the community. That's the spirit
+of this licence and the spirit in which it was written.

package/README.md

@@ -64,6 +64,16 @@ Most DMX implementations require either expensive proprietary hardware or comple
 - 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
 
+## Licence
+
+This package is licensed under **[GPL v3](https://www.gnu.org/licenses/gpl-3.0.txt)**.
+
+You are free to use, modify, and distribute this package. Any derivative works must be distributed under the same GPL v3 licence. This package may not be taken proprietary, rebranded as closed source, or distributed without crediting the original author.
+
+This package was built from 6+ years of real-world professional installation experience. If you use it, improve it, or build on it — please contribute your changes back to the community.
+
+---
+
 > **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.
 
 ---
@@ -290,6 +300,45 @@ Entity IDs in HA are locked to the fixture ID and survive friendly name changes.
 
 ---
 
+## Retain discovery — why the default is false
+
+If you search "MQTT discovery retain" you will find HA community posts and documentation recommending `retain=true` for discovery messages. **This advice is correct for ESP and battery-powered IoT devices — but not for Node-RED.**
+
+### Why ESP devices need retain=true
+
+An ESP sensor runs independently of HA. When HA restarts or updates, the ESP device has no way of knowing — it thinks it already discovered itself and won't re-send the discovery payload. Without `retain=true`, the device disappears from HA permanently until the ESP reboots.
+
+```
+ESP device                    Home Assistant
+──────────                    ──────────────
+Sends discovery once    →     HA restarts
+Doesn't know HA restarted     Retained message restores device ✓
+```
+
+### Why Node-RED is different
+
+Node-RED sits on the same server stack as HA. They are tightly coupled — if one goes down the other knows immediately via the websocket connection. When HA restarts, NR reconnects and re-discovers every device automatically. If NR goes down, HA *should* show nothing — because nothing is working.
+
+```
+Node-RED + Home Assistant (same server):
+  NR down  → no devices in HA  → client sees fault immediately ✓
+  HA restart → NR reconnects   → re-discovers everything      ✓
+  retain=true → ghost devices  → client confused, support call ✗
+```
+
+### The config node setting
+
+The `Retain discovery` setting on the config node controls this behaviour:
+
+| Setting | Behaviour | Recommended for |
+|---|---|---|
+| `false` (default) | Devices disappear if NR stops | Professional installs — clear fault indication |
+| `true` | Devices persist if NR stops | Standalone IoT, voice assistant integrations where entity persistence matters |
+
+**Default is `false`** — if a client opens their HA dashboard and sees no lights, they know something is wrong with Node-RED. This is the correct behaviour for a professionally installed system where NR and HA live on the same hardware.
+
+---
+
 ## MQTT topic formats
 
 | Node | Topic |

package/node-red-contrib-dmx-for-ha/LICENSE

@@ -0,0 +1,28 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+node-red-contrib-dmx-for-ha
+Copyright (C) 2024-2026 DeSwaggy
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+Full licence text: https://www.gnu.org/licenses/gpl-3.0.txt
+
+ADDITIONAL NOTE:
+This package was built from 6+ years of real-world professional 
+installation experience. If you use it, improve it, or build on it —
+please contribute your changes back to the community. That's the spirit
+of this licence and the spirit in which it was written.