@bldgblocks/node-red-contrib-control 0.1.4

package/nodes/cache-block.js

@@ -0,0 +1,106 @@
+module.exports = function(RED) {
+    function CacheBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name,
+            operationMode: config.operationMode,
+            cachedMessage: null
+        };
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid message
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                if (done) done();
+                return;
+            }
+
+            // Validate context
+            if (!msg.hasOwnProperty("context") || typeof msg.context !== "string") {
+                node.status({ fill: "red", shape: "ring", text: "missing context" });
+                if (done) done();
+                return;
+            }
+
+            switch (msg.context) {
+                case "update":
+                    // Validate payload
+                    if (!msg.hasOwnProperty("payload")) {
+                        node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                        if (done) done();
+                        return;
+                    }
+
+                    node.runtime.cachedMessage = RED.util.cloneMessage(msg);
+                    node.status({
+                        fill: "green",
+                        shape: "dot",
+                        text: `update: ${typeof msg.payload === "number" ? msg.payload.toFixed(2) : JSON.stringify(msg.payload).slice(0, 20)}`
+                    });
+                    if (done) done();
+                    return;
+                case "execute":
+                    if (node.runtime.cachedMessage === null) {
+                        node.status({
+                            fill: "blue",
+                            shape: "dot",
+                            text: "execute: null"
+                        });
+                        send({ payload: null });
+                    } else {
+                        let outputMsg;
+                        if (node.runtime.operationMode === "clone") {
+                            outputMsg = RED.util.cloneMessage(node.runtime.cachedMessage);
+                        } else {
+                            outputMsg = { payload: node.runtime.cachedMessage.payload };
+                        }
+                        node.status({
+                            fill: "blue",
+                            shape: "dot",
+                            text: `execute: ${typeof outputMsg.payload === "number" ? outputMsg.payload.toFixed(2) : JSON.stringify(outputMsg.payload).slice(0, 20)}`
+                        });
+                        send(outputMsg);
+                    }
+                    if (done) done();
+                    return;
+                case "reset":
+                    // Validate payload
+                    if (!msg.hasOwnProperty("payload")) {
+                        node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                        if (done) done();
+                        return;
+                    }
+
+                    if (typeof msg.payload !== "boolean" || !msg.payload) {
+                        node.status({ fill: "red", shape: "ring", text: "invalid reset" });
+                        if (done) done();
+                        return;
+                    }
+                    
+                    node.runtime.cachedMessage = null;
+                    node.status({
+                        fill: "green",
+                        shape: "dot",
+                        text: "reset"
+                    });
+                    if (done) done();
+                    return;
+                default:
+                    node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                    if (done) done("Unknown context");
+                    return;
+            }
+        });
+
+        node.on("close", function(done) {
+            done();
+        });
+    }
+
+    RED.nodes.registerType("cache-block", CacheBlockNode);
+};

package/nodes/call-status-block.html

@@ -0,0 +1,111 @@
+<!-- UI Template Section: Defines the edit dialog -->
+<script type="text/html" data-template-name="call-status-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-statusTimeout" title="Time to wait for status response (seconds, positive number)"><i class="fa fa-clock-o"></i> Status Timeout</label>
+        <input type="number" id="node-input-statusTimeout" placeholder="30" min="0.01" step="any">
+    </div>
+    <div class="form-row">
+        <label for="node-input-clearDelay" title="Delay before clearing status and alarm after call ends (seconds, positive number)"><i class="fa fa-clock-o"></i> Clear Delay</label>
+        <input type="number" id="node-input-clearDelay" placeholder="10" min="0.01" step="any">
+    </div>
+    <div class="form-row">
+        <label for="node-input-normalOff" title="Expected status when call is off (boolean)"><i class="fa fa-power-off"></i> Normal Off</label>
+        <input type="checkbox" id="node-input-normalOff" style="width: auto; vertical-align: middle;">
+    </div>
+    <div class="form-row">
+        <label for="node-input-normalOn" title="Expected status when call is on (boolean)"><i class="fa fa-power-off"></i> Normal On</label>
+        <input type="checkbox" id="node-input-normalOn" style="width: auto; vertical-align: middle;">
+    </div>
+    <div class="form-row">
+        <label for="node-input-runLostStatus" title="Alarm if status doesn't match normalOn during call (boolean)"><i class="fa fa-exclamation-triangle"></i> Run Lost Status</label>
+        <input type="checkbox" id="node-input-runLostStatus" style="width: auto; vertical-align: middle;">
+    </div>
+    <div class="form-row">
+        <label for="node-input-noStatusOnRun" title="Alarm if no status received during call (boolean)"><i class="fa fa-exclamation-triangle"></i> No Status On Run</label>
+        <input type="checkbox" id="node-input-noStatusOnRun" style="width: auto; vertical-align: middle;">
+    </div>
+    <div class="form-row">
+        <label for="node-input-runLostStatusMessage" title="Message for run lost status alarm (string)"><i class="fa fa-comment"></i> Run Lost Message</label>
+        <input type="text" id="node-input-runLostStatusMessage" placeholder="Status lost during run">
+    </div>
+    <div class="form-row">
+        <label for="node-input-noStatusOnRunMessage" title="Message for no status on run alarm (string)"><i class="fa fa-comment"></i> No Status Message</label>
+        <input type="text" id="node-input-noStatusOnRunMessage" placeholder="No status received during run">
+    </div>
+</script>
+
+<!-- JavaScript Section: Registers the node and handles editor logic -->
+<script type="text/javascript">
+    RED.nodes.registerType("call-status-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            statusTimeout: { value: 30, required: true, validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) > 0; } },
+            clearDelay: { value: 10, required: true, validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) > 0; } },
+            normalOff: { value: false },
+            normalOn: { value: true },
+            runLostStatus: { value: false },
+            noStatusOnRun: { value: true },
+            runLostStatusMessage: { value: "Status lost during run" },
+            noStatusOnRunMessage: { value: "No status received during run" }
+        },
+        inputs: 1,
+        outputs: 2,
+        inputLabels: ["input"],
+        outputLabels: ["call", "diagnostics"],
+        icon: "font-awesome/fa-phone",
+        paletteLabel: "call status",
+        label: function() {
+            return this.name || "call status";
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="call-status-block">
+Issues calls to equipment with status and alarm diagnostics.
+
+### Inputs
+: context (string) : Configuration commands - (`"statusTimeout"`, `"clearDelay"`, `"normalOff"`, `"normalOn"`, `"runLostStatus"`, `"noStatusOnRun"`, `"runLostStatusMessage"`, `"noStatusOnRunMessage"`) or sets status (`"status"`). Unmatched values trigger error.
+: payload (boolean | number | string) : Boolean for call, status, or boolean configs; number for timeouts; string for messages.
+
+### Outputs
+: call (boolean) : Current call state.
+: diagnostics (object) : `{ call; boolean, status; boolean, alarm; boolean, alarmMessage; string, timeout; boolean }`.
+
+### Properties
+: name (string) : Display name in editor.
+: statusTimeout (number) : Time to wait for status response (seconds, > 0).
+: clearDelay (number) : Delay before clearing status and alarm after call ends (seconds, > 0).
+: normalOff (boolean) : Expected status when call is off.
+: normalOn (boolean) : Expected status when call is on.
+: runLostStatus (boolean) : Alarm if status doesn't match `normalOn` during call.
+: noStatusOnRun (boolean) : Alarm if no status received during call.
+: runLostStatusMessage (string) : Message for run lost status alarm.
+: noStatusOnRunMessage (string) : Message for no status on run alarm.
+
+### Details
+Issues a call (`true`) to equipment via output 1 and expects a status response matching `normalOn` within `statusTimeout` seconds. 
+
+Clears status and alarm after `clearDelay` seconds when call ends (`false`), checking against `normalOff`. 
+
+Generates alarms for `runLostStatus` (status mismatch during call) or `noStatusOnRun` (no status within `statusTimeout`) with custom messages. 
+
+Ignores status inputs without an active call.
+
+### Status
+- Green (dot): Configuration
+- Blue (dot): Output, no alarm
+- Red (dot): Output with alarm
+- Red (ring): Errors
+- Yellow (ring): Unknown context
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/call-status-block.js

@@ -0,0 +1,274 @@
+module.exports = function(RED) {
+    function CallStatusBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name || "",
+            statusTimeout: parseFloat(config.statusTimeout),
+            clearDelay: parseFloat(config.clearDelay),
+            normalOff: config.normalOff === true,
+            normalOn: config.normalOn === true,
+            runLostStatus: config.runLostStatus === true,
+            noStatusOnRun: config.noStatusOnRun === true,
+            runLostStatusMessage: config.runLostStatusMessage,
+            noStatusOnRunMessage: config.noStatusOnRunMessage,
+            call: false,
+            status: false,
+            alarm: false,
+            alarmMessage: "",
+            statusTimer: null,
+            clearTimer: null
+        };
+
+        // Validate initial config
+        if (isNaN(node.runtime.statusTimeout) || node.runtime.statusTimeout <= 0) {
+            node.runtime.statusTimeout = 30;
+            node.status({ fill: "red", shape: "ring", text: "invalid statusTimeout" });
+        }
+        if (isNaN(node.runtime.clearDelay) || node.runtime.clearDelay <= 0) {
+            node.runtime.clearDelay = 10;
+            node.status({ fill: "red", shape: "ring", text: "invalid clearDelay" });
+        }
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid message
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                if (done) done();
+                return;
+            }
+
+            // Handle context updates
+            if (msg.hasOwnProperty("context")) {
+                if (!msg.hasOwnProperty("payload")) {
+                    node.status({ fill: "red", shape: "ring", text: `missing payload for ${msg.context}` });
+                    if (done) done();
+                    return;
+                }
+
+                switch (msg.context) {
+                    case "statusTimeout":
+                    case "clearDelay":
+                        const value = parseFloat(msg.payload);
+                        if (isNaN(value) || value <= 0) {
+                            node.status({ fill: "red", shape: "ring", text: `invalid ${msg.context}` });
+                            if (done) done();
+                            return;
+                        }
+                        node.runtime[msg.context] = value;
+                        if (node.runtime.statusTimer) {
+                            clearTimeout(node.runtime.statusTimer);
+                            node.runtime.statusTimer = null;
+                            if (node.runtime.noStatusOnRun && node.runtime.call) {
+                                node.runtime.statusTimer = setTimeout(() => {
+                                    if (!node.runtime.status) {
+                                        node.runtime.alarm = true;
+                                        node.runtime.alarmMessage = node.runtime.noStatusOnRunMessage;
+                                        node.status({ fill: "red", shape: "dot", text: `no status on run, alarm: true` });
+                                        send(sendOutputs());
+                                    }
+                                    node.runtime.statusTimer = null;
+                                }, node.runtime.statusTimeout * 1000);
+                            }
+                        }
+                        node.status({
+                            fill: "green",
+                            shape: "dot",
+                            text: `${msg.context}: ${value.toFixed(2)}`
+                        });
+                        if (done) done();
+                        return;
+                    case "normalOff":
+                    case "normalOn":
+                    case "runLostStatus":
+                    case "noStatusOnRun":
+                        if (typeof msg.payload !== "boolean") {
+                            node.status({ fill: "red", shape: "ring", text: `invalid ${msg.context}` });
+                            if (done) done();
+                            return;
+                        }
+                        node.runtime[msg.context] = msg.payload;
+                        if (msg.context === "noStatusOnRun" && !msg.payload && node.runtime.statusTimer) {
+                            clearTimeout(node.runtime.statusTimer);
+                            node.runtime.statusTimer = null;
+                        } else if (msg.context === "noStatusOnRun" && msg.payload && node.runtime.call && !node.runtime.status) {
+                            node.runtime.statusTimer = setTimeout(() => {
+                                if (!node.runtime.status) {
+                                    node.runtime.alarm = true;
+                                    node.runtime.alarmMessage = node.runtime.noStatusOnRunMessage;
+                                    node.status({ fill: "red", shape: "dot", text: `no status on run, alarm: true` });
+                                    send(sendOutputs());
+                                }
+                                node.runtime.statusTimer = null;
+                            }, node.runtime.statusTimeout * 1000);
+                        }
+                        node.status({
+                            fill: "green",
+                            shape: "dot",
+                            text: `${msg.context}: ${msg.payload}`
+                        });
+                        send(checkStatusConditions());
+                        if (done) done();
+                        return;
+                    case "runLostStatusMessage":
+                    case "noStatusOnRunMessage":
+                        if (typeof msg.payload !== "string") {
+                            node.status({ fill: "red", shape: "ring", text: `invalid ${msg.context}` });
+                            if (done) done();
+                            return;
+                        }
+                        node.runtime[msg.context] = msg.payload;
+                        node.status({
+                            fill: "green",
+                            shape: "dot",
+                            text: `${msg.context} set`
+                        });
+                        if (node.runtime.alarm && node.runtime.alarmMessage === (msg.context === "runLostStatusMessage" ? node.runtime.noStatusOnRunMessage : node.runtime.runLostStatusMessage)) {
+                            node.runtime.alarmMessage = msg.payload;
+                            send(sendOutputs());
+                        }
+                        if (done) done();
+                        return;
+                    case "status":
+                        if (typeof msg.payload !== "boolean") {
+                            node.status({ fill: "red", shape: "ring", text: "invalid status" });
+                            if (done) done();
+                            return;
+                        }
+                        if (!node.runtime.call) {
+                            node.status({ fill: "red", shape: "ring", text: "status ignored" });
+                            if (done) done();
+                            return;
+                        }
+                        node.runtime.status = msg.payload;
+                        if (node.runtime.status && node.runtime.statusTimer) {
+                            clearTimeout(node.runtime.statusTimer);
+                            node.runtime.statusTimer = null;
+                            node.runtime.alarm = false;
+                            node.runtime.alarmMessage = "";
+                        }
+                        send(checkStatusConditions());
+                        if (done) done();
+                        return;
+                    default:
+                        node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                        if (done) done("Unknown context");
+                        return;
+                }
+            }
+
+            // Validate call input
+            if (typeof msg.payload !== "boolean") {
+                node.status({ fill: "red", shape: "ring", text: "invalid call" });
+                if (done) done();
+                return;
+            }
+
+            // Process call change
+            if (msg.payload !== node.runtime.call) {
+                node.runtime.call = msg.payload;
+
+                // Clear existing timers
+                if (node.runtime.statusTimer) {
+                    clearTimeout(node.runtime.statusTimer);
+                    node.runtime.statusTimer = null;
+                }
+                if (node.runtime.clearTimer) {
+                    clearTimeout(node.runtime.clearTimer);
+                    node.runtime.clearTimer = null;
+                }
+
+                if (node.runtime.call) {
+                    // Start call: reset status and alarm, set timeout
+                    node.runtime.status = false;
+                    node.runtime.alarm = false;
+                    node.runtime.alarmMessage = "";
+                    if (node.runtime.noStatusOnRun) {
+                        node.runtime.statusTimer = setTimeout(() => {
+                            if (!node.runtime.status) {
+                                node.runtime.alarm = true;
+                                node.runtime.alarmMessage = node.runtime.noStatusOnRunMessage;
+                                node.status({ fill: "red", shape: "dot", text: `no status on run, alarm: true` });
+                                send(sendOutputs());
+                            }
+                            node.runtime.statusTimer = null;
+                        }, node.runtime.statusTimeout * 1000);
+                    }
+                } else {
+                    // Stop call: schedule status and alarm clear
+                    node.runtime.clearTimer = setTimeout(() => {
+                        node.runtime.status = false;
+                        node.runtime.alarm = false;
+                        node.runtime.alarmMessage = "";
+                        send(sendOutputs());
+                        updateStatus();
+                        node.runtime.clearTimer = null;
+                    }, node.runtime.clearDelay * 1000);
+                }
+                send(checkStatusConditions());
+            } else {
+                updateStatus();
+            }
+
+            if (done) done();
+
+            function checkStatusConditions() {
+                if (node.runtime.call && node.runtime.runLostStatus) {
+                    if (node.runtime.status !== node.runtime.normalOn) {
+                        node.runtime.alarm = true;
+                        node.runtime.alarmMessage = node.runtime.runLostStatusMessage;
+                        node.status({ fill: "red", shape: "dot", text: `run lost, alarm: true` });
+                        return sendOutputs();
+                    }
+                }
+                if (!node.runtime.call && node.runtime.status !== node.runtime.normalOff) {
+                    node.runtime.alarm = true;
+                    node.runtime.alarmMessage = "Status mismatch when off";
+                    node.status({ fill: "red", shape: "dot", text: `off mismatch, alarm: true` });
+                    return sendOutputs();
+                }
+                if (!node.runtime.alarm || (node.runtime.status === node.runtime.normalOn && node.runtime.call) || (node.runtime.status === node.runtime.normalOff && !node.runtime.call)) {
+                    node.runtime.alarm = false;
+                    node.runtime.alarmMessage = "";
+                }
+                updateStatus();
+                return sendOutputs();
+            }
+
+            function sendOutputs() {
+                return [
+                    { payload: node.runtime.call },
+                    {
+                        payload: {
+                            call: node.runtime.call,
+                            status: node.runtime.status,
+                            alarm: node.runtime.alarm,
+                            alarmMessage: node.runtime.alarmMessage,
+                            timeout: !!node.runtime.statusTimer
+                        }
+                    }
+                ];
+            }
+
+            function updateStatus() {
+                node.status({
+                    fill: node.runtime.alarm ? "red" : "blue",
+                    shape: "dot",
+                    text: `call: ${node.runtime.call}, status: ${node.runtime.status}, alarm: ${node.runtime.alarm}`
+                });
+            }
+        });
+
+        node.on("close", function(done) {
+            if (node.runtime.statusTimer) clearTimeout(node.runtime.statusTimer);
+            if (node.runtime.clearTimer) clearTimeout(node.runtime.clearTimer);
+            done();
+        });
+    }
+
+    RED.nodes.registerType("call-status-block", CallStatusBlockNode);
+};