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

package/subflow/README.md

@@ -0,0 +1,35 @@
+# Subflow Reference Implementation
+
+These files are the original Node-RED subflow implementation of the nodes.
+They predate the packaged node version and are kept here as a reference.
+
+## What these are
+
+Before the nodes were packaged as proper NR nodes (`ha-mqtt-*`), they ran
+as subflows — Node-RED function nodes with env var menus. The `.js` files
+here are the function node code that was pasted inside each subflow.
+
+## When to use these
+
+- As a reference for the business logic if you need to understand what the
+  packaged node `.js` files are doing
+- For debugging — the subflow version can be imported into NR without npm install
+- As a fallback if the packaged nodes are not available in your NR version
+
+## Import instructions
+
+1. Import `subflow_definitions.json` into NR — do NOT deploy yet
+2. Wire up instances and deploy
+3. Paste the relevant `.js` file contents into each function node
+
+See `/docs/nr_subflow_gotchas.md` for important NR import notes.
+
+## Versions
+
+| File | Version |
+|---|---|
+| dmx_node_v0.5.9.js | 0.5.9 |
+| dmx_group_node_v0.3.8.js | 0.3.8 |
+| relay_node_v4.0.2.js | 4.0.2 |
+| button_node_v5.0.3.js | 5.0.3 |
+| pir_node_v1.0.3.js | 1.0.3 |

package/subflow/button_node_v5.0.3.js

@@ -0,0 +1,324 @@
+// BUTTON NODE — HOME ASSISTANT in NODE-RED
+// Discord: @deswaggy  |  Version: 5.0.3
+// Extensions: "BETTER COMMENTS", "TODO TREE"
+
+//! BIG & BRIGHT
+//@ Topic Headers
+//# Description / Explanations
+//$ Logic
+//^ Debug Comments
+//? Breaks / Headers
+
+// Naming conventions:
+//   <env_var>      = Sub-flow environmental  (Edit subflow template)
+//   <<<flow_env>>> = Flow-level environmental (Tab → gear → flow envs)
+
+// Role of this node:
+//   Receives physical wall button press payloads from the button controller
+//   via MQTT, filters for its own payload, and reports the press to HA as
+//   a binary_sensor state change (ON → auto-clears via HA off_delay).
+//
+//   Also discovers a companion HA "button" entity so the physical wall button
+//   can be mirrored in the HA dashboard. Pressing the UI button follows the
+//   same code path as a physical press.
+//
+//   Physical press path:
+//     Controller MQTT → NR MQTT In → Button Node → binary_sensor ON → HA automation
+//
+//   UI mirror press path:
+//     HA UI button → HA publishes to cmd_t → NR MQTT In → Button Node → same path
+//
+//   NO websocket dependency. Pure MQTT throughout.
+//
+//   Controller payload format: "{panelId}-{GPIOpin}"  e.g. "10-54"
+//   Panel IDs: 10=Master B.Ctrl#1, 11=#2, 12=#3, 13=PIR#1, 14=PIR#2 etc.
+
+//! IMPORTANT — NODE-RED FUNCTION NODE SETUP:
+//   This node requires EXACTLY 4 outputs configured in the NR function node settings.
+//   Output 1: HA MQTT (binary_sensor state + discovery config)  → wire to MQTT Out node
+//   Output 2: MQTT subscribe / unsubscribe actions              → wire to MQTT In node
+//   Output 3: Node status + debug                               → wire to Status / Debug node
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!@ CONFIG — all env reads in one place
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CFG = {
+    //@ HA identity
+    discoveryPrefix:    env.get("<HA_discovery_prefix>"),
+    siteId:             env.get("<HA_site_unique_id>"),
+    //^ binary_sensor is always the automation trigger entity — hardcoded, not env-driven
+    component:          "binary_sensor",
+    uidPrefix:          env.get("<HA_unique_id_prefix>"),   //^ S = Switch (electrician convention)
+    uid:                env.get("<HA_unique_id>"),           //^ cable number from electrical plan
+    uidPostfix:         String(env.get("<HA_unique_id_postfix>") || ""), //^ button letter A/B/C/D
+
+    //@ MQTT — HA side
+    retain:             env.get("<HA_MQTT_retain_flag>"),
+    qos:                env.get("<HA_MQTT_QOS>"),
+    configTopic:        env.get("<HA_config_topic>"),
+    commandTopic:       env.get("<HA_command_topic>"),
+    stateTopic:         env.get("<HA_state_topic>"),
+
+    //@ HA features
+    enabledByDefault:   env.get("<HA_enabled_by_default>"),
+    icon:               env.get("<HA_icon>"),
+
+    //@ Button specific
+    //^ buttonPayload: the controller payload that identifies THIS button
+    //^ Format: "{panelId}-{GPIOpin}"  e.g. "10-54" = controller 10, GPIO pin 54
+    buttonPayload:      String(env.get("<BUTTON_Payload>")),
+    buttonPosition:     env.get("<BUTTON_Position>"),       //^ Top Left, Top Right, Bottom Left, Bottom Right etc.
+    buttonLedColor:     env.get("<BUTTON_Info_LED_Color>"), //^ Blue, Red, Green, White, Orange
+    //^ How long HA shows the button as ON before auto-clearing (seconds, float).
+    //^ Implemented via HA binary_sensor off_delay — HA manages the timer, not NR.
+    //^ Default 0.5s feels responsive without being too brief for automation edge detection.
+    holdTimeSecs:       parseFloat(env.get("<BUTTON_hold_time_seconds>")) || 0.5,
+
+    //@ Controller — physical button hardware side
+    controllerZone:           env.get("<CONTROLLER_zone>"),
+    controllerSubscribeTopic: env.get("<CONTROLLER_MQTT_subscribe_topic>"),
+    //^ Full topic path. New firmware: "MW3D/Master/10/buttons"
+    //^ Old firmware (translation layer): "buttons"
+    controllerFw:             env.get("<CONTROLLER_fw_v>"),
+
+    //@ Button type — default "Wall", kept for future controller/type flexibility
+    buttonType:     env.get("<BUTTON_Type>") || "Wall",
+
+    //@ Controller model — for hw_version documentation and future multi-controller support
+    controllerModel: env.get("<CONTROLLER_Model>") || "SuperHouse_ButtonController",
+
+    //@ Device metadata
+    device: {
+        situation:   env.get("<DEVICE_situation>"),
+        area:        env.get("<DEVICE_area>"),
+        subLocation: env.get("<DEVICE_Sub_Location>"),
+    },
+
+    //@ Node metadata
+    nodeCode:   env.get("<NODE_code>") || "BUTTON NODE",
+    nodeSw:     env.get("<NODE_sw_v>"),
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ TOPIC BUILDERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** HA MQTT base topic for this button's binary_sensor entity. */
+const fixtureTopic = `${CFG.discoveryPrefix}/${CFG.component}/${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`;
+
+/** HA MQTT base topic for the companion UI button entity (mirror of physical button). */
+const uiButtonTopic = `${CFG.discoveryPrefix}/button/${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}-BTN`;
+
+/** The command topic HA publishes to when the UI button is pressed. */
+const uiButtonCmdTopic = `${uiButtonTopic}/${CFG.commandTopic}`;
+
+/** Short fixture ID for NR node status messages. */
+const fixtureId = `${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ MQTT SEND HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Publish binary_sensor state to HA on output 1.
+ * @param {"ON"|"OFF"} state
+ */
+function sendState(state) {
+    node.send([{
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   `${fixtureTopic}/${CFG.stateTopic}`,
+        payload: state,
+    }, null, null, null]);
+}
+
+/** Send Node-RED status + debug message on output 3. */
+function sendStatus(fill, shape, text) {
+    node.send([null, null, {
+        debug:  { node: fixtureId, message: text },
+        status: { fill, shape, text },
+    }, null, null]);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ SERIAL NUMBER BUILDER
+//# SHARED PATTERN — extract to shared utility on node package build
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildSerialNumber() {
+    //# Human-readable format matching DMX Node convention.
+    //# Cable ID and payload are what a field tech needs — not a machine slug.
+    return `(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}) Payload: ${CFG.buttonPayload} — See ⓘ MQTT Info below.`;
+}
+
+/** Build a clean slug for the HA object_id (entity_id prefix). */
+function buildObjectId() {
+    //# object_id sets the HA entity_id: binary_sensor.s_33a
+    //# Matches plan ID directly — what electricians and techs expect.
+    return `${CFG.uidPrefix}_${CFG.uid}${CFG.uidPostfix}`.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ PRESS HANDLER
+//# Used for both physical button press and HA UI button press — identical path.
+//# HA auto-clears the binary_sensor via off_delay in the discovery payload.
+//# NR does not need a timer — HA manages the hold duration.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function handlePress(source) {
+    console.log(`${fixtureId} press — source:${source}  position:${CFG.buttonPosition}`);
+    sendState("ON");
+    sendStatus("blue", "dot", `${fixtureId} pressed — ${CFG.buttonPosition}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DEVICE REQUEST HANDLERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildSerialNumberStr() {
+    return buildSerialNumber();
+}
+
+function handleDeviceAdd() {
+    const { device: dev } = CFG;
+
+    //# Binary sensor discovery — the automation trigger entity
+    const binarySensorDiscovery = {
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   `${fixtureTopic}/${CFG.configTopic}`,
+        payload: {
+            unique_id:          `${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`,
+            //^ object_id sets the HA entity_id: binary_sensor.s_33a
+            //^ Locked to plan ID — survives user renaming the friendly name in HA UI.
+            object_id:          buildObjectId(),
+            name:               `${CFG.buttonPosition} button ${dev.situation} the ${CFG.controllerZone} ${dev.area} ${dev.subLocation}`,
+            stat_t:             `${fixtureTopic}/${CFG.stateTopic}`,
+            //^ off_delay: HA automatically clears the binary_sensor after this many seconds.
+            //^ NR publishes ON, HA manages the timer and publishes OFF itself.
+            //^ This removes the need for any NR-side timer logic.
+            off_delay:          CFG.holdTimeSecs,
+            enabled_by_default: CFG.enabledByDefault,
+            icon:               CFG.icon,
+            device: {
+                identifiers:    `${CFG.component}-${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`,
+                name:           `(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}) - Wall Button/s ${dev.situation} the ${CFG.controllerZone} - ${dev.area} - ${dev.subLocation}`,
+                model:          `Wall button/s located ${dev.situation} the ${CFG.controllerZone}-${dev.area} - ${dev.subLocation}`,
+                model_id:       `referenced on plan as: (${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`,
+                suggested_area: `${CFG.controllerZone} ${dev.area} ${dev.subLocation}`,
+                hw_version:     `${CFG.buttonType} button — ${CFG.buttonLedColor} LED indicator, Green Cat5 cable. ` +
+                                `Controller model: ${CFG.controllerModel} in ${CFG.controllerZone} Server Rack, firmware: ${CFG.controllerFw}. ` +
+                                `Publishes payload "${CFG.buttonPayload}" on topic: ${CFG.controllerSubscribeTopic}`,
+                serial_number:  buildSerialNumberStr(),
+                sw_version:     `${CFG.nodeCode}: ${CFG.nodeSw}`,
+                manufacturer:   "DeSwaggy — Discord: @deswaggy",
+            },
+        },
+    };
+
+    //# UI button discovery — the dashboard mirror entity
+    //# Pressing this in HA UI publishes "PRESS" to uiButtonCmdTopic.
+    //# NR receives it and follows the same path as a physical press.
+    //# Stateless in HA — no state topic. Just a command trigger.
+    const uiButtonDiscovery = {
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   `${uiButtonTopic}/${CFG.configTopic}`,
+        payload: {
+            unique_id:          `${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}-BTN`,
+            object_id:          `${buildObjectId()}_btn`,
+            name:               `${CFG.buttonPosition} (UI) ${dev.situation} the ${CFG.controllerZone} ${dev.area} ${dev.subLocation}`,
+            cmd_t:              uiButtonCmdTopic,
+            payload_press:      "PRESS",
+            enabled_by_default: CFG.enabledByDefault,
+            icon:               CFG.icon,
+            //# Same device as binary_sensor — one device, two entities in HA
+            device: {
+                identifiers:    `${CFG.component}-${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`,
+            },
+        },
+    };
+
+    //# Subscribe to controller topic (physical presses) AND UI button cmd topic
+    const subscribeController = {
+        retain: CFG.retain,
+        qos:    CFG.qos,
+        topic:  CFG.controllerSubscribeTopic,
+        action: "subscribe",
+    };
+    const subscribeUiButton = {
+        retain: CFG.retain,
+        qos:    CFG.qos,
+        topic:  uiButtonCmdTopic,
+        action: "subscribe",
+    };
+
+    //# Send binary_sensor discovery first, then UI button discovery
+    node.send([binarySensorDiscovery, subscribeController, { status: { fill: "green", shape: "ring", text: `${fixtureId} discovery sent — awaiting press` } }, null, null]);
+    node.send([uiButtonDiscovery, subscribeUiButton, null, null, null]);
+
+    console.log(`${fixtureId} device added — position:${CFG.buttonPosition}  payload:${CFG.buttonPayload}`);
+    console.log(`${fixtureId} subscribed to: ${CFG.controllerSubscribeTopic} and ${uiButtonCmdTopic}`);
+}
+
+function handleDeviceRemove() {
+    node.send([
+        { retain: CFG.retain, qos: CFG.qos, topic: `${fixtureTopic}/${CFG.configTopic}`,    payload: "" },
+        { retain: CFG.retain, qos: CFG.qos, topic: CFG.controllerSubscribeTopic, action: "unsubscribe" },
+        { status: { fill: "red", shape: "ring", text: `${fixtureId} removed` } },
+        null,
+        null,
+    ]);
+    //# Also remove UI button entity and unsubscribe from its cmd topic
+    node.send([
+        { retain: CFG.retain, qos: CFG.qos, topic: `${uiButtonTopic}/${CFG.configTopic}`, payload: "" },
+        { retain: CFG.retain, qos: CFG.qos, topic: uiButtonCmdTopic, action: "unsubscribe" },
+        null, null, null,
+    ]);
+    console.log(`${fixtureId} device removed.`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!? ENTRY POINT
+// ─────────────────────────────────────────────────────────────────────────────
+
+node.send([null, null, null, msg]);
+
+console.log(`${fixtureId}  payload:"${msg.payload}"  topic:"${msg.topic || ""}"`);
+
+//? ── DEVICE REQUEST — add / remove / debug ───────────────────────────────────
+if (msg.device != null && (typeof msg.device === "string" || msg.device?.request != null)) {
+    const _devReq = typeof msg.device === "string" ? msg.device : msg.device.request;
+    console.log(`${fixtureId} device.request: ${_devReq}`);
+    switch (_devReq) {
+        case "add":    handleDeviceAdd();    break;
+        case "remove": handleDeviceRemove(); break;
+        case "debug":  console.log(`${fixtureId} DEBUG:`, JSON.stringify(msg)); break;
+        default:       node.warn(`${fixtureId} — unknown device.request: "${_devReq}"`);
+    }
+
+//? ── UI BUTTON PRESS — from HA dashboard ─────────────────────────────────────
+} else if (msg.topic === uiButtonCmdTopic && msg.payload === "PRESS") {
+    handlePress("HA UI");
+
+//? ── PHYSICAL BUTTON PRESS — from controller MQTT ────────────────────────────
+} else if (String(msg.payload) === CFG.buttonPayload) {
+    handlePress("physical");
+
+//? ── UNKNOWN MESSAGE ─────────────────────────────────────────────────────────
+} else {
+    //# Payload didn't match — this button node is ignoring a press meant for another button.
+    //# This is normal and expected on the shared controller topic. No warn needed.
+    //# Only warn if the topic is the UI command topic but payload is unexpected.
+    if (msg.topic === uiButtonCmdTopic) {
+        node.warn(
+            `${fixtureId} — unexpected payload on UI button cmd topic. ` +
+            `Expected "PRESS", got: "${msg.payload}"`
+        );
+    }
+    //# Silently ignore all other payloads — they belong to sibling button nodes.
+}
+
+node.done();
+return [null, null, null, msg];