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

package/nodes/ha-mqtt-config.html

@@ -0,0 +1,233 @@
+<!-- ============================================================
+     ha-mqtt-config — Config Node Editor
+     Package: node-red-contrib-dmx-for-ha
+     Author:  DeSwaggy — Discord: @deswaggy
+     ============================================================ -->
+
+<script type="text/javascript">
+    RED.nodes.registerType('ha-mqtt-config', {
+        category: 'config',
+        defaults: {
+            name:            { value: '',             required: true },
+            siteId:          { value: '',             required: true },
+            zone:            { value: '',             required: true },
+            broker:          { value: '',             type: 'mqtt-broker', required: true },
+            discoveryPrefix: { value: 'homeassistant' },
+            qos:             { value: '0' },
+            retain:          { value: 'false' },
+            configTopic:     { value: 'config' },
+            stateTopic:      { value: 'state' },
+            commandTopic:    { value: 'cmd' },
+            availTopic:      { value: 'avty' },
+            enabledDefault:  { value: 'true' },
+            diskDelay:       { value: '10' },
+            flashShort:      { value: '1' },
+            flashLong:       { value: '10' },
+        },
+        label: function () {
+            return this.name || 'HA MQTT Config';
+        },
+        oneditprepare: function () {
+            // Zone is free text — no population needed
+            // Sanitisation happens in runtime .js
+        },
+    });
+</script>
+
+<!-- ============================================================
+     Editor Panel Template
+     ============================================================ -->
+<script type="text/html" data-template-name="ha-mqtt-config">
+
+    <!-- NAME -->
+    <div class="form-row">
+        <label for="node-config-input-name">
+            <i class="fa fa-tag"></i> Name
+        </label>
+        <input type="text" id="node-config-input-name"
+               placeholder="e.g. Master Zone, Guest Wing" />
+    </div>
+
+    <hr/>
+
+    <!-- SITE -->
+    <div class="form-row">
+        <label style="width:100%; font-weight:bold; color:#999; font-size:0.85em; text-transform:uppercase; letter-spacing:0.05em;">
+            <i class="fa fa-home"></i> Site
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-siteId">
+            <i class="fa fa-id-badge"></i> Site ID
+        </label>
+        <input type="text" id="node-config-input-siteId"
+               placeholder="e.g. home, unit4, smithresidence"
+               style="width:60%" />
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            Used in MQTT topic construction
+        </span>
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-zone">
+            <i class="fa fa-location-arrow"></i> Zone
+        </label>
+        <input type="text" id="node-config-input-zone"
+               placeholder="e.g. Master, BnB, GuestWing"
+               style="width:60%" />
+        <div style="margin-left:106px; margin-top:4px; color:#999; font-size:0.85em;">
+            Used in MQTT topics — no spaces or special characters ( # + / ).
+            Spaces are automatically converted to underscores.
+        </div>
+    </div>
+
+    <hr/>
+
+    <!-- MQTT BROKER -->
+    <div class="form-row">
+        <label style="width:100%; font-weight:bold; color:#999; font-size:0.85em; text-transform:uppercase; letter-spacing:0.05em;">
+            <i class="fa fa-exchange"></i> MQTT Broker
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-broker">
+            <i class="fa fa-server"></i> Broker
+        </label>
+        <input type="text" id="node-config-input-broker" />
+    </div>
+
+    <hr/>
+
+    <!-- HOME ASSISTANT -->
+    <div class="form-row">
+        <label style="width:100%; font-weight:bold; color:#999; font-size:0.85em; text-transform:uppercase; letter-spacing:0.05em;">
+            <i class="fa fa-home"></i> Home Assistant
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-discoveryPrefix">
+            <i class="fa fa-search"></i> Discovery prefix
+        </label>
+        <input type="text" id="node-config-input-discoveryPrefix"
+               placeholder="homeassistant" style="width:40%" />
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-qos">
+            <i class="fa fa-signal"></i> QoS
+        </label>
+        <select id="node-config-input-qos" style="width:80px">
+            <option value="0">0</option>
+            <option value="1">1</option>
+            <option value="2">2</option>
+        </select>
+        &nbsp;&nbsp;
+        <label for="node-config-input-retain" style="width:auto">
+            <i class="fa fa-thumb-tack"></i> Retain
+        </label>
+        <select id="node-config-input-retain" style="width:80px">
+            <option value="false">false</option>
+            <option value="true">true</option>
+        </select>
+    </div>
+
+    <hr/>
+
+    <!-- DEFAULTS -->
+    <div class="form-row">
+        <label style="width:100%; font-weight:bold; color:#999; font-size:0.85em; text-transform:uppercase; letter-spacing:0.05em;">
+            <i class="fa fa-sliders"></i> Defaults
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-enabledDefault">
+            <i class="fa fa-toggle-on"></i> Enabled by default in HA
+        </label>
+        <select id="node-config-input-enabledDefault" style="width:80px">
+            <option value="true">true</option>
+            <option value="false">false</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-diskDelay">
+            <i class="fa fa-clock-o"></i> Disk save delay (s)
+        </label>
+        <input type="number" id="node-config-input-diskDelay"
+               min="1" max="60" style="width:70px" />
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            Debounce delay before writing state to disk
+        </span>
+    </div>
+
+    <div class="form-row">
+        <label style="margin-left:106px; color:#999; font-size:0.85em;">
+            Flash durations (seconds):
+        </label>
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-flashShort">
+            <i class="fa fa-clock-o"></i> Flash Short
+        </label>
+        <input type="number" id="node-config-input-flashShort"
+               min="0.1" step="0.1" style="width:70px" />
+        &nbsp;&nbsp;
+        <label for="node-config-input-flashLong" style="width:auto">
+            Flash Long
+        </label>
+        <input type="number" id="node-config-input-flashLong"
+               min="1" style="width:70px" />
+    </div>
+
+</script>
+
+<!-- ============================================================
+     Help Panel
+     ============================================================ -->
+<script type="text/html" data-help-name="ha-mqtt-config">
+    <p>
+        Shared configuration node for the <strong>DMX for HA</strong> package.
+        Create one config node per zone. All DMX, Relay, Button and PIR nodes
+        reference this config to inherit site-wide settings.
+    </p>
+
+    <h3>Setup</h3>
+    <ol>
+        <li>Set a meaningful <strong>Name</strong> — e.g. "Master Zone", "Guest Wing"</li>
+        <li>Enter your <strong>Site ID</strong> — a short slug used in MQTT topic construction (e.g. <code>home</code>)</li>
+        <li>Select your <strong>Zone</strong></li>
+        <li>Select your <strong>MQTT Broker</strong> from the dropdown</li>
+        <li>Leave HA defaults as-is unless you have a custom HA MQTT setup</li>
+    </ol>
+
+    <h3>Multi-zone deployments</h3>
+    <p>
+        Create one <code>ha-mqtt-config</code> node per zone. Each DMX, Relay,
+        Button or PIR node picks its zone via the Config dropdown in its own
+        editor panel.
+    </p>
+
+    <h3>MQTT topic format</h3>
+    <p>Topics are constructed as:</p>
+    <pre>{siteId}/{zone}/{controller}/...</pre>
+    <p>Example with Site ID <code>home</code> and Zone <code>Master</code>:</p>
+    <pre>home/Master/dmx/1</pre>
+
+    <h3>Details</h3>
+    <dl class="message-properties">
+        <dt>Site ID <span class="property-type">string</span></dt>
+        <dd>Short slug identifying this installation. Used in MQTT topic construction. No spaces.</dd>
+        <dt>Zone <span class="property-type">string</span></dt>
+        <dd>Physical zone of this config node. Becomes part of the MQTT topic.</dd>
+        <dt>Broker <span class="property-type">mqtt-broker</span></dt>
+        <dd>The MQTT broker all nodes in this zone connect to.</dd>
+        <dt>Discovery prefix <span class="property-type">string</span></dt>
+        <dd>HA MQTT discovery prefix. Default: <code>homeassistant</code></dd>
+        <dt>Disk save delay <span class="property-type">number</span></dt>
+        <dd>Seconds to debounce before writing fixture state to disk context store. Default: 10.</dd>
+    </dl>
+</script>

package/nodes/ha-mqtt-config.js

@@ -0,0 +1,81 @@
+// ============================================================
+// ha-mqtt-config — Config Node Runtime
+// Package: node-red-contrib-dmx-for-ha
+// Author:  DeSwaggy — Discord: @deswaggy
+//
+// Shared configuration node. Holds site-wide settings and
+// exposes the MQTT broker connection to all child nodes
+// (ha-mqtt-dmx, ha-mqtt-dmx-group, ha-mqtt-relay,
+//  ha-mqtt-button, ha-mqtt-pir).
+//
+// Child nodes access config via:
+//   const config = RED.nodes.getNode(this.config);
+//   config.broker    → MQTT broker node
+//   config.siteId    → site ID string
+//   config.zone      → zone string
+//   config.settings  → all other settings
+// ============================================================
+
+module.exports = function (RED) {
+
+    function HaMqttConfigNode(config) {
+        RED.nodes.createNode(this, config);
+
+        // Site
+        // Sanitise siteId — same rules as zone
+        this.siteId = (config.siteId || '')
+            .trim()
+            .replace(/\s+/g, '_')
+            .replace(/[#\+\/]/g, '')
+            .replace(/_+/g, '_');
+        // Sanitise zone — strip characters invalid in MQTT topics
+        // Spaces → underscores, remove # + / and other special chars
+        this.zone = (config.zone || '')
+            .trim()
+            .replace(/\s+/g, '_')
+            .replace(/[#\+\/]/g, '')
+            .replace(/_+/g, '_');
+
+        // MQTT broker — child nodes subscribe/publish via this
+        this.broker = config.broker;
+        this.brokerNode = RED.nodes.getNode(config.broker);
+
+        // HA MQTT topic segments
+        this.discoveryPrefix = config.discoveryPrefix || 'homeassistant';
+        this.configTopic     = config.configTopic     || 'config';
+        this.stateTopic      = config.stateTopic      || 'state';
+        this.commandTopic    = config.commandTopic    || 'cmd';
+        this.availTopic      = config.availTopic      || 'avty';
+
+        // MQTT settings
+        this.qos    = parseInt(config.qos)    || 0;
+        this.retain = config.retain === 'true';
+
+        // HA defaults
+        this.enabledDefault = config.enabledDefault !== 'false';
+
+        // Timing defaults
+        this.diskDelay  = parseInt(config.diskDelay)  || 10;
+        this.flashShort = parseFloat(config.flashShort) || 1;
+        this.flashLong  = parseFloat(config.flashLong)  || 10;
+
+        // Expose a convenience settings object for child nodes
+        this.settings = {
+            siteId:          this.siteId,
+            zone:            this.zone,
+            discoveryPrefix: this.discoveryPrefix,
+            configTopic:     this.configTopic,
+            stateTopic:      this.stateTopic,
+            commandTopic:    this.commandTopic,
+            availTopic:      this.availTopic,
+            qos:             this.qos,
+            retain:          this.retain,
+            enabledDefault:  this.enabledDefault,
+            diskDelay:       this.diskDelay,
+            flashShort:      this.flashShort,
+            flashLong:       this.flashLong,
+        };
+    }
+
+    RED.nodes.registerType('ha-mqtt-config', HaMqttConfigNode);
+};