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

package/nodes/ha-mqtt-pir.html

@@ -0,0 +1,343 @@
+<!-- ============================================================
+     ha-mqtt-pir — PIR Node Editor
+     Package: node-red-contrib-dmx-for-ha
+     Author:  DeSwaggy — Discord: @deswaggy
+     ============================================================ -->
+
+<script type="text/javascript">
+
+    RED.nodes.registerType('ha-mqtt-pir', {
+        category:     'DMX for HA',
+        color:        '#2980b9',
+        icon:         'font-awesome/fa-podcast',
+        inputs:       1,
+        outputs:      0,
+        inputLabels:  ['Input'],
+        paletteLabel: 'PIR',
+
+        defaults: {
+            name:           { value: '' },
+            config:         { value: '', type: 'ha-mqtt-config', required: true },
+            // Identity
+            uid:            { value: '',    required: true },
+            uidPostfix:     { value: '' },
+            // Location
+            area:           { value: 'Area 52' },
+            situation:      { value: 'in' },
+            subLocation:    { value: '' },
+            // PIR specifics
+            pirType:        { value: 'Ceiling' },
+            pirPayload:     { value: '',    required: true },
+            subscribeTopic: { value: '' },
+            // Options
+            haIcon:         { value: 'mdi:motion-sensor' },
+            cableColor:     { value: 'Purple' },
+            holdTime:       { value: '15' },
+            warmupTime:     { value: '120' },
+        },
+
+        label: function () {
+            if (this.name) return this.name;
+            const id      = this.uid        || '?';
+            const postfix = this.uidPostfix || '';
+            return 'S-' + id + postfix;
+        },
+
+        labelStyle: function () {
+            return this.name ? 'node_label_italic' : '';
+        },
+
+        oneditprepare: function () {
+            const node = this;
+            const areas = [
+                { v: 'Area 52',             l: 'TBC' },
+                { v: 'Attic Roof',          l: 'Attic Roof' },
+                { v: 'Backyard',            l: 'Backyard' },
+                { v: 'Balcony',             l: 'Balcony' },
+                { v: 'Bathroom',            l: 'Bathroom' },
+                { v: 'Bedroom 1',           l: 'Bedroom 1' },
+                { v: 'Bedroom 2',           l: 'Bedroom 2' },
+                { v: 'Bedroom 3',           l: 'Bedroom 3' },
+                { v: 'Bedroom 4',           l: 'Bedroom 4' },
+                { v: 'Carport',             l: 'Carport' },
+                { v: 'Cellar',              l: 'Cellar' },
+                { v: 'Dining',              l: 'Dining' },
+                { v: 'Driveway',            l: 'Driveway' },
+                { v: 'Entry',               l: 'Entry' },
+                { v: 'Garage',              l: 'Garage' },
+                { v: 'Gym',                 l: 'Gym' },
+                { v: 'Hallway',             l: 'Hallway' },
+                { v: 'Kitchen',             l: 'Kitchen' },
+                { v: 'Laundry',             l: 'Laundry' },
+                { v: 'Link Bridge (Upper)', l: 'Link Bridge Upper' },
+                { v: 'Link Bridge (Lower)', l: 'Link Bridge Lower' },
+                { v: 'Living',              l: 'Living' },
+                { v: 'Media',               l: 'Media' },
+                { v: 'Office',              l: 'Office' },
+                { v: 'Pantry',              l: 'Pantry' },
+                { v: 'Pass Over',           l: 'Pass Over' },
+                { v: 'Pass Under',          l: 'Pass Under' },
+                { v: 'Passageway',          l: 'Passageway' },
+                { v: 'Pool',                l: 'Pool' },
+                { v: 'Portico',             l: 'Portico' },
+                { v: 'PowderRoom',          l: 'PowderRoom' },
+                { v: 'Reading',             l: 'Reading' },
+                { v: 'Rumpus',              l: 'Rumpus' },
+                { v: 'Spa',                 l: 'Spa' },
+                { v: 'Stairs',              l: 'Stairs' },
+                { v: 'Store',               l: 'Store' },
+                { v: 'SubFloor',            l: 'SubFloor' },
+                { v: 'Terrace',             l: 'Terrace' },
+            ];
+            const subAreas = [
+                { v: '',              l: 'None' },
+                { v: 'Balcony',       l: 'Balcony' },
+                { v: 'Bed (North)',   l: 'Bed North' },
+                { v: 'Bed (South)',   l: 'Bed South' },
+                { v: 'Bed (East)',    l: 'Bed East' },
+                { v: 'Bed (West)',    l: 'Bed West' },
+                { v: 'Ceiling',       l: 'Ceiling' },
+                { v: 'Dress',         l: 'Dress' },
+                { v: 'Ensuite',       l: 'Ensuite' },
+                { v: 'Exterior',      l: 'Exterior' },
+                { v: 'Ground Floor',  l: 'Ground Floor' },
+                { v: '1st Floor',     l: '1st Floor' },
+                { v: 'Landing',       l: 'Landing' },
+                { v: 'Office',        l: 'Office' },
+                { v: 'Stairs',        l: 'Stairs' },
+                { v: 'WIR',           l: 'WIR' },
+                { v: '(North)',        l: 'North' },
+                { v: '(South)',        l: 'South' },
+                { v: '(East)',         l: 'East' },
+                { v: '(West)',         l: 'West' },
+                { v: 'Void',          l: 'Void' },
+            ];
+
+            const areaEl = $('#node-input-area');
+            areaEl.empty();
+            areas.forEach(function (a) {
+                areaEl.append($('<option>').val(a.v).text(a.l)
+                    .prop('selected', a.v === node.area));
+            });
+
+            const subEl = $('#node-input-subLocation');
+            subEl.empty();
+            subAreas.forEach(function (s) {
+                subEl.append($('<option>').val(s.v).text(s.l)
+                    .prop('selected', s.v === node.subLocation));
+            });
+        },
+    });
+
+</script>
+
+<script type="text/html" data-template-name="ha-mqtt-pir">
+
+    <div class="form-row">
+        <label for="node-input-name">
+            <i class="fa fa-tag"></i> Name
+        </label>
+        <input type="text" id="node-input-name"
+               placeholder="Optional — defaults to S-31 on canvas" />
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-config">
+            <i class="fa fa-cog"></i> Config
+        </label>
+        <input type="text" id="node-input-config" />
+    </div>
+
+    <hr/>
+
+    <!-- ── PIR (* Required) ──────────────────────────────────── -->
+    <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-podcast"></i> PIR &nbsp;<span style="color:#e74c3c">* Required</span>
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-uid">
+            <i class="fa fa-tv"></i> Cable ID
+        </label>
+        <span style="margin-right:4px; font-weight:bold;">S -</span>
+        <input type="text" id="node-input-uid"
+               placeholder="31" style="width:70px" />
+        &nbsp;
+        <select id="node-input-uidPostfix" style="width:65px">
+            <option value="">(none)</option>
+            <option value="-A">-A</option>
+            <option value="-B">-B</option>
+            <option value="-C">-C</option>
+            <option value="-D">-D</option>
+        </select>
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            Plan ID — Sensor group
+        </span>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-pirType">
+            <i class="fa fa-podcast"></i> PIR Type
+        </label>
+        <select id="node-input-pirType" style="width:55%">
+            <option value="Ceiling">Ceiling</option>
+            <option value="Cupboard">Cupboard</option>
+            <option value="Hidden">Hidden</option>
+            <option value="Wall">Wall</option>
+            <option value="External">External</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-area">
+            <i class="fa fa-map-marker"></i> Area
+        </label>
+        <select id="node-input-area" style="width:55%"></select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-situation">
+            <i class="fa fa-compass"></i> Situation
+        </label>
+        <select id="node-input-situation" style="width:55%">
+            <option value="in">in</option>
+            <option value="above">above</option>
+            <option value="below">below</option>
+            <option value="outside">outside</option>
+            <option value="throughout">throughout</option>
+            <option value="under">under</option>
+            <option value="over">over</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-subLocation">
+            <i class="fa fa-map-marker"></i> Sub-Area
+        </label>
+        <select id="node-input-subLocation" style="width:55%"></select>
+    </div>
+
+    <hr/>
+
+    <!-- ── CONTROLLER ────────────────────────────────────────── -->
+    <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> Controller
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-pirPayload">
+            <i class="fa fa-podcast"></i> Payload
+        </label>
+        <input type="text" id="node-input-pirPayload"
+               placeholder="e.g. 13-62" style="width:120px" />
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            panelId-GPIOpin
+        </span>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-subscribeTopic">
+            <i class="fa fa-exchange"></i> Subscribe topic
+        </label>
+        <input type="text" id="node-input-subscribeTopic"
+               placeholder="e.g. MW3D/Master/PIR_Sensors"
+               style="width:55%" />
+    </div>
+
+    <hr/>
+
+    <!-- ── OPTIONS ───────────────────────────────────────────── -->
+    <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> Options
+        </label>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-haIcon">
+            <i class="fa fa-image"></i> HA Icon
+        </label>
+        <input type="text" id="node-input-haIcon"
+               placeholder="mdi:motion-sensor" style="width:55%" />
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-cableColor">
+            <i class="fa fa-circle"></i> Cable Colour
+        </label>
+        <select id="node-input-cableColor" style="width:120px">
+            <option value="Purple">Purple</option>
+            <option value="Blue">Blue</option>
+            <option value="Green">Green</option>
+            <option value="Red">Red</option>
+            <option value="Yellow">Yellow</option>
+            <option value="Orange">Orange</option>
+            <option value="White">White</option>
+            <option value="Grey">Grey</option>
+            <option value="Black">Black</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-holdTime">
+            <i class="fa fa-clock-o"></i> Hold time (s)
+        </label>
+        <input type="number" id="node-input-holdTime"
+               min="1" style="width:80px" />
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            HA auto-clears motion after this delay
+        </span>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-warmupTime">
+            <i class="fa fa-clock-o"></i> Warm-up (s)
+        </label>
+        <input type="number" id="node-input-warmupTime"
+               min="0" style="width:80px" />
+        <span style="margin-left:8px; color:#999; font-size:0.85em;">
+            Offline delay after boot before PIR activates
+        </span>
+    </div>
+
+</script>
+
+<script type="text/html" data-help-name="ha-mqtt-pir">
+    <p>
+        PIR motion sensor receiver. Listens for hardware controller MQTT
+        payloads and publishes to HA as a <code>binary_sensor</code>
+        with <code>device_class: motion</code>.
+    </p>
+
+    <h3>Setup</h3>
+    <ol>
+        <li>Select your <strong>Config</strong> node</li>
+        <li>Set <strong>Cable ID</strong> — matches electrical plan</li>
+        <li>Set <strong>Payload</strong> — the <code>{panelId}-{GPIOpin}</code> string your controller publishes</li>
+        <li>Set <strong>Subscribe topic</strong> — the MQTT topic your PIR controller publishes to</li>
+        <li>Deploy — motion sensor appears in HA, offline during warm-up</li>
+    </ol>
+
+    <h3>Warm-up sequence</h3>
+    <p>
+        On deploy the PIR goes <code>offline</code> in HA for the warm-up period.
+        HA ignores all triggers during this time — prevents spurious motion events
+        during controller reboot from triggering lights at 3am.
+    </p>
+
+    <h3>Payload format</h3>
+    <p>
+        The controller publishes a plain string — e.g. <code>13-62</code>
+        meaning panel 13, GPIO pin 62. This node filters for its own
+        payload and silently ignores all others on the shared topic.
+    </p>
+
+    <h3>HA entity created</h3>
+    <ul>
+        <li><code>binary_sensor.s_31</code> — motion sensor, auto-clears via hold time</li>
+    </ul>
+</script>

package/nodes/ha-mqtt-pir.js

@@ -0,0 +1,183 @@
+// ============================================================
+// ha-mqtt-pir — PIR / Motion Sensor Node Runtime
+// Package: node-red-contrib-dmx-for-ha
+// Author:  DeSwaggy — Discord: @deswaggy
+// ============================================================
+
+module.exports = function (RED) {
+
+    function HaMqttPirNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // ── Config & broker ───────────────────────────────────────
+        const cfg = RED.nodes.getNode(config.config);
+        if (!cfg) { node.error('PIR: no config node selected'); return; }
+
+        const broker = RED.nodes.getNode(cfg.broker);
+        if (!broker) { node.error('PIR: no MQTT broker in config'); return; }
+
+        broker.register(node);
+
+        // ── Node settings ─────────────────────────────────────────
+        const S = {
+            uid:            config.uid            || '',
+            uidPostfix:     config.uidPostfix      || '',
+            pirType:        config.pirType         || 'Ceiling',
+            pirPayload:     String(config.pirPayload || ''),
+            subscribeTopic: config.subscribeTopic  || '',
+            area:           config.area            || '',
+            situation:      config.situation        || 'in',
+            subLocation:    config.subLocation      || '',
+            haIcon:         config.haIcon           || 'mdi:motion-sensor',
+            cableColor:     config.cableColor       || 'Purple',
+            holdTime:       parseInt(config.holdTime)    || 15,
+            warmupTime:     parseInt(config.warmupTime)  || 120,
+        };
+
+        const fixtureId   = `S-${S.uid}${S.uidPostfix}`;
+        const objectId    = `s_${S.uid}${S.uidPostfix}`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const fixtureTopic = `${cfg.discoveryPrefix}/binary_sensor/${fixtureId}`;
+        const cmdTopic    = `${fixtureTopic}/${cfg.commandTopic}`;
+        const cfgTopic    = `${fixtureTopic}/${cfg.configTopic}`;
+        const statTopic   = `${fixtureTopic}/${cfg.stateTopic}`;
+        const avtyTopic   = `${fixtureTopic}/${cfg.availTopic}`;
+
+        // ── Helpers ───────────────────────────────────────────────
+        function pub(topic, payload, retain) {
+            broker.publish({
+                topic,
+                payload: typeof payload === 'object' ? JSON.stringify(payload) : String(payload),
+                qos:    cfg.qos,
+                retain: retain !== undefined ? retain : cfg.retain,
+            });
+        }
+
+        function setStatus(fill, shape, text) {
+            node.status({ fill, shape, text });
+        }
+
+        // ── Timers ────────────────────────────────────────────────
+        let warmupTimer  = null;
+        let lastTrigger  = 0;
+
+        function cancelWarmup() {
+            if (warmupTimer) { clearTimeout(warmupTimer); warmupTimer = null; }
+        }
+
+        function startWarmup() {
+            cancelWarmup();
+            pub(avtyTopic, 'offline', true);
+            setStatus('orange', 'ring', `${fixtureId} warming up — ${S.warmupTime}s`);
+            warmupTimer = setTimeout(() => {
+                warmupTimer = null;
+                pub(avtyTopic, 'online', true);
+                setStatus('yellow', 'ring', `${fixtureId} ready — awaiting motion`);
+                node.log(`${fixtureId} warm-up complete`);
+            }, S.warmupTime * 1000);
+        }
+
+        // ── PIR trigger ───────────────────────────────────────────
+        function handleTrigger() {
+            const now   = Date.now();
+            const holdMs = S.holdTime * 1000;
+            if (now - lastTrigger < holdMs) return; // debounce
+            lastTrigger = now;
+            pub(statTopic, 'ON', false);
+            setStatus('blue', 'dot', `${fixtureId} motion detected`);
+            node.log(`${fixtureId} motion detected`);
+        }
+
+        // ── Availability ──────────────────────────────────────────
+        function handleAvailability(payload) {
+            const status = String(payload || '').toLowerCase();
+            cancelWarmup();
+            if (status === 'offline') {
+                pub(avtyTopic, 'offline', true);
+                setStatus('red', 'ring', `${fixtureId} offline`);
+            } else {
+                pub(avtyTopic, 'online', true);
+                lastTrigger = 0;
+                setStatus('yellow', 'ring', `${fixtureId} ready — awaiting motion`);
+            }
+        }
+
+        // ── Device add ────────────────────────────────────────────
+        function handleDeviceAdd() {
+            const discovery = {
+                unique_id:          fixtureId,
+                object_id:          objectId,
+                name:               `${S.pirType} PIR ${S.situation} the ${cfg.zone} ${S.area} ${S.subLocation}`,
+                stat_t:             statTopic,
+                avty_t:             avtyTopic,
+                payload_available:  'online',
+                payload_not_available: 'offline',
+                off_delay:          S.holdTime,
+                device_class:       'motion',
+                enabled_by_default: cfg.enabledDefault,
+                icon:               S.haIcon,
+                device: {
+                    identifiers:    `binary_sensor-${fixtureId}`,
+                    name:           `(${fixtureId}) - ${S.pirType} PIR ${S.situation} the ${cfg.zone} - ${S.area} - ${S.subLocation}`,
+                    model:          `${S.pirType} PIR located ${S.situation} the ${cfg.zone} - ${S.area}`,
+                    model_id:       `referenced on plan as: (${fixtureId}`,
+                    suggested_area: `${cfg.zone} ${S.area} ${S.subLocation}`,
+                    hw_version:     `${S.pirType} PIR — ${S.cableColor} Cat5 cable. Publishes "${S.pirPayload}" on topic: ${S.subscribeTopic}`,
+                    serial_number:  `(${fixtureId}) Payload: ${S.pirPayload}`,
+                    sw_version:     `ha-mqtt-pir: ${RED.version ? RED.version() : '0.1.0'}`,
+                    manufacturer:   'DeSwaggy — Discord: @deswaggy',
+                },
+            };
+
+            pub(cfgTopic, discovery, true);
+
+            // Subscribe to controller topic
+            broker.subscribe(S.subscribeTopic, cfg.qos, function (topic, payload) {
+                const str = payload.toString();
+                if (str === S.pirPayload) handleTrigger();
+            }, node.id);
+
+            setStatus('green', 'ring', `${fixtureId} discovery sent`);
+            node.log(`${fixtureId} device added`);
+            startWarmup();
+        }
+
+        // ── Device remove ─────────────────────────────────────────
+        function handleDeviceRemove() {
+            cancelWarmup();
+            pub(avtyTopic, 'offline', true);
+            pub(cfgTopic, '', true);
+            broker.unsubscribe(S.subscribeTopic, node.id);
+            setStatus('red', 'ring', `${fixtureId} removed`);
+            node.log(`${fixtureId} device removed`);
+        }
+
+        // ── NR input entry point ──────────────────────────────────
+        node.on('input', function (msg, send, done) {
+            const devReq = typeof msg.device === 'string'
+                ? msg.device
+                : (msg.device && msg.device.request);
+
+            if (devReq) {
+                switch (devReq) {
+                    case 'add':    handleDeviceAdd();              break;
+                    case 'remove': handleDeviceRemove();           break;
+                    case 'avty':   handleAvailability(msg.payload); break;
+                    default: node.warn(`${fixtureId} — unknown device.request: "${devReq}"`);
+                }
+            } else {
+                node.warn(`${fixtureId} — unrecognised message received and dropped. See node documentation.`);
+            }
+            done();
+        });
+
+        // ── Cleanup ───────────────────────────────────────────────
+        node.on('close', function (done) {
+            cancelWarmup();
+            broker.unsubscribe(S.subscribeTopic, node.id);
+            broker.deregister(node, done);
+        });
+    }
+
+    RED.nodes.registerType('ha-mqtt-pir', HaMqttPirNode);
+};