@bldgblocks/node-red-contrib-control 0.1.34 → 0.1.37

package/nodes/boolean-to-number-block.html

@@ -4,6 +4,10 @@
         <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-inputProperty" title="Message property to read input from"><i class="fa fa-folder-open"></i> Input Property</label>
+        <input type="text" id="node-input-inputProperty" placeholder="payload">
+    </div>
     <div class="form-row">
         <label for="node-input-nullToZero"><i class="fa fa-cog"></i> Null Mapping</label>
         <input type="checkbox" id="node-input-nullToZero" style="width: auto; margin-left: 10px;"> Map null to 0
@@ -17,6 +21,7 @@
         color: "#301934",
         defaults: {
             name: { value: "" },
+            inputProperty: { value: "payload" },
             nullToZero: { value: false }
         },
         inputs: 1,
@@ -33,18 +38,26 @@
 
 <!-- Help Section -->
 <script type="text/markdown" data-help-name="boolean-to-number-block">
-Converts a boolean or null input payload to a numeric output.
+Converts a boolean or null input from a configured property to a numeric output.
 
 ### Inputs
-: payload (boolean | null) : Value to convert (`true`, `false`, `null`).
+: input-property (boolean | null) : Value to convert, read from the configured Input Property.
 
 ### Outputs
-: payload (number) : Converted value `null` to `0` (if `nullToZero`) or `-1`, `false` to `0`, `true` to `1`.
+: payload (number) : Converted value: `null` to `0` (if `nullToZero` is true) or `-1`, `false` to `0`, `true` to `1`.
+
+### Properties
+: name (string) : Display name in editor.
+: inputProperty (string) : Message property to read input from (default: `payload`). Supports nested properties (e.g., `data.value`).
+: nullToZero (boolean) : When checked, `null` maps to `0`; when unchecked, `null` maps to `-1`.
 
 ### Details
-Converts `msg.payload` (boolean or null) to a number `null` maps to `0` (if `nullToZero` is `true`) or `-1` (if `false`), `false` to `0`, `true` to `1`. 
+Converts boolean or null input (read from the configured **Input Property**, default: `msg.payload`) to a number:
+- `true` → `1`
+- `false` → `0`
+- `null` → `0` (if **Null Mapping** is checked) or `-1` (if unchecked)
 
-Passthrough all other input message properties
+Output is always written to `msg.payload`. All other input message properties are passed through unchanged.
 
 ### Status
 - Green (dot): Configuration update

package/nodes/boolean-to-number-block.js

@@ -1,36 +1,44 @@
 module.exports = function(RED) {
+    const utils = require('./utils')(RED);
+
     function BooleanToNumberBlockNode(config) {
         RED.nodes.createNode(this, config);
         const node = this;
 
         // Initialize runtime for editor display
-        node.runtime = {
-            name: config.name,
-            nullToZero: Boolean(config.nullToZero)
-        };
+        // Initialize state
+        node.name = config.name;
+        node.inputProperty = config.inputProperty || "payload";
+        node.nullToZero = Boolean(config.nullToZero);
 
         node.on("input", function(msg, send, done) {
             send = send || function() { node.send.apply(node, arguments); };
 
-            // Check for missing payload
-            if (!msg.hasOwnProperty("payload")) {
-                node.status({ fill: "red", shape: "ring", text: "missing payload" });
+            // Check for missing input property
+            let inputValue;
+            try {
+                inputValue = RED.util.getMessageProperty(msg, node.inputProperty);
+            } catch (err) {
+                inputValue = undefined;
+            }
+            if (inputValue === undefined) {
+                utils.setStatusError(node, "missing or invalid input property");
                 if (done) done();
                 return;
             }
 
-            // Validate and convert payload
-            const inputDisplay = msg.payload === null ? "null" : String(msg.payload);
-            if (msg.payload === null) {
-                msg.payload = node.runtime.nullToZero ? 0 : -1;
-                node.status({ fill: "blue", shape: "dot", text: `in: ${inputDisplay}, out: ${msg.payload}` });
+            // Validate and convert input
+            const inputDisplay = inputValue === null ? "null" : String(inputValue);
+            if (inputValue === null) {
+                msg.payload = node.nullToZero ? 0 : -1;
+                utils.setStatusChanged(node, `in: ${inputDisplay}, out: ${msg.payload}`);
                 send(msg);
-            } else if (typeof msg.payload === "boolean") {
-                msg.payload = msg.payload ? 1 : 0;
-                node.status({ fill: "blue", shape: "dot", text: `in: ${inputDisplay}, out: ${msg.payload}` });
+            } else if (typeof inputValue === "boolean") {
+                msg.payload = inputValue ? 1 : 0;
+                utils.setStatusChanged(node, `in: ${inputDisplay}, out: ${msg.payload}`);
                 send(msg);
             } else {
-                node.status({ fill: "red", shape: "ring", text: "invalid payload" });
+                utils.setStatusError(node, "invalid input type");
             }
 
             if (done) done();

package/nodes/cache-block.js

@@ -1,28 +1,29 @@
 module.exports = function(RED) {
+    const utils = require('./utils')(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
-        };
+        // Initialize state
+        node.name = config.name;
+        node.operationMode = config.operationMode;
+        node.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" });
+                utils.setStatusError(node, "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" });
+                utils.setStatusError(node, "missing context");
                 if (done) done();
                 return;
             }
@@ -31,39 +32,29 @@ module.exports = function(RED) {
                 case "update":
                     // Validate payload
                     if (!msg.hasOwnProperty("payload")) {
-                        node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                        utils.setStatusError(node, "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)}`
-                    });
+                    node.cachedMessage = RED.util.cloneMessage(msg);
+                    const updateText = `update: ${typeof msg.payload === "number" ? msg.payload.toFixed(2) : JSON.stringify(msg.payload).slice(0, 20)}`;
+                    utils.setStatusOK(node, updateText);
                     if (done) done();
                     return;
                 case "execute":
-                    if (node.runtime.cachedMessage === null) {
-                        node.status({
-                            fill: "blue",
-                            shape: "dot",
-                            text: "execute: null"
-                        });
+                    if (node.cachedMessage === null) {
+                        utils.setStatusChanged(node, "execute: null");
                         send({ payload: null });
                     } else {
                         let outputMsg;
-                        if (node.runtime.operationMode === "clone") {
-                            outputMsg = RED.util.cloneMessage(node.runtime.cachedMessage);
+                        if (node.operationMode === "clone") {
+                            outputMsg = RED.util.cloneMessage(node.cachedMessage);
                         } else {
-                            outputMsg = { payload: node.runtime.cachedMessage.payload };
+                            outputMsg = { payload: node.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)}`
-                        });
+                        const executeText = `execute: ${typeof outputMsg.payload === "number" ? outputMsg.payload.toFixed(2) : JSON.stringify(outputMsg.payload).slice(0, 20)}`;
+                        utils.setStatusChanged(node, executeText);
                         send(outputMsg);
                     }
                     if (done) done();
@@ -71,27 +62,23 @@ module.exports = function(RED) {
                 case "reset":
                     // Validate payload
                     if (!msg.hasOwnProperty("payload")) {
-                        node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                        utils.setStatusError(node, "missing payload");
                         if (done) done();
                         return;
                     }
 
                     if (typeof msg.payload !== "boolean" || !msg.payload) {
-                        node.status({ fill: "red", shape: "ring", text: "invalid reset" });
+                        utils.setStatusError(node, "invalid reset");
                         if (done) done();
                         return;
                     }
                     
-                    node.runtime.cachedMessage = null;
-                    node.status({
-                        fill: "green",
-                        shape: "dot",
-                        text: "reset"
-                    });
+                    node.cachedMessage = null;
+                    utils.setStatusOK(node, "reset");
                     if (done) done();
                     return;
                 default:
-                    node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                    utils.setStatusWarn(node, "unknown context");
                     if (done) done("Unknown context");
                     return;
             }

package/nodes/call-status-block.html

@@ -4,13 +4,29 @@
         <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-inputProperty" title="Message property for call (request) signal"><i class="fa fa-sign-in"></i> Call Property</label>
+        <input type="text" id="node-input-inputProperty" placeholder="payload">
+    </div>
+    <div class="form-row">
+        <label for="node-input-statusInputProperty" title="Message property for status (response) signal"><i class="fa fa-sign-out"></i> Status Property</label>
+        <input type="text" id="node-input-statusInputProperty" placeholder="status">
+    </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">
+        <label for="node-input-clearDelay" title="Delay before clearing status and alarm after call ends (seconds, 0=immediate)"><i class="fa fa-hourglass"></i> Clear Delay</label>
+        <input type="number" id="node-input-clearDelay" placeholder="10" min="0" step="any">
+    </div>
+    <div class="form-row">
+        <label for="node-input-debounce" title="Debounce status flicker (milliseconds, 0=disabled)"><i class="fa fa-filter"></i> Debounce</label>
+        <input type="number" id="node-input-debounce" placeholder="100" min="0" step="any">
+    </div>
+    <div class="form-row">
+        <label for="node-input-heartbeatTimeout" title="Heartbeat window for continuous status monitoring (seconds, 0=disabled)"><i class="fa fa-pulse"></i> Heartbeat Timeout</label>
+        <input type="number" id="node-input-heartbeatTimeout" placeholder="30" min="0" step="any">
     </div>
     <div class="form-row">
         <label for="node-input-runLostStatus" title="Alarm if status is lost during call (boolean)"><i class="fa fa-exclamation-triangle"></i> Run Lost Status</label>
@@ -37,8 +53,12 @@
         color: "#301934",
         defaults: {
             name: { value: "" },
+            inputProperty: { value: "payload" },
+            statusInputProperty: { value: "status" },
             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; } },
+            clearDelay: { value: 10, required: true, validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) >= 0; } },
+            debounce: { value: 100, required: true, validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) >= 0; } },
+            heartbeatTimeout: { value: 30, required: true, validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) >= 0; } },
             runLostStatus: { value: false },
             noStatusOnRun: { value: true },
             runLostStatusMessage: { value: "Status lost during run" },
@@ -58,39 +78,78 @@
 
 <!-- Help Section -->
 <script type="text/markdown" data-help-name="call-status-block">
-Monitors call and status signals with alarm diagnostics.
+Monitors call and status signals to detect equipment faults, communication losses, and synchronization errors.
 
 ### Inputs
-- payload (boolean): Call activation/deactivation signal
-- status (boolean): Status response from equipment (only processed when call is active)
+
+: payload (boolean) : Requested equipment state (call signal). Default property name for sending call commands. When true, block expects equipment to respond with status=true within timeout period. Property name configurable via inputProperty setting.
+: status (boolean) : Equipment response signal. Updates actual equipment state and triggers state transitions. Default property name `msg.status`. Accepts `msg.context="status"` with `msg.payload` as fallback routing.
 
 ### Outputs
-- call (boolean): Current call state
-- status (object): `{ call: boolean, status: boolean, alarm: boolean, alarmMessage: string, timeout: boolean, neverReceivedStatus: boolean }`
+
+: payload (boolean) : Current call/requested state (true=on, false=off).
+: status (object) : State information object with properties: call (boolean), status (boolean), alarm (boolean), alarmMessage (string).
+: diagnostics (object) : Internal state for monitoring with properties: state (state machine state), initialTimeout (boolean), heartbeatActive (boolean), neverReceivedStatus (boolean), lastStatusTime (milliseconds or null), timeSinceLastStatus (milliseconds or null).
 
 ### 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)
-- runLostStatus (boolean): Alarm if status is lost during call
-- noStatusOnRun (boolean): Alarm if no status received during call
-- runLostStatusMessage (string): Message for status lost alarm
-- noStatusOnRunMessage (string): Message for no status alarm
-
-### Alarm Conditions
-1. Status without call: Status=true when call=false (immediate alarm)
-2. No status during call: No status received within timeout period (after statusTimeout)
-3. Lost status during call: Status=false when call=true and status was previously received (immediate alarm)
-
-### Behavior
-- When call is activated: Expects status=true response
-- Status is only processed when call is active
-- Clears all state after clearDelay when call ends
-- Timer acts as a blocking gate for status reception
-
-### Status Indicators
-- Green (ring): Configuration errors
-- Blue (dot): Normal operation, no alarms
-- Red (dot): Active alarm condition
-- Yellow (ring): Invalid input
+
+- name (string) - Display name in editor. Default: `"call status"`.
+- inputProperty (string) - Input message property for call signal. Default: `"payload"`.
+- statusInputProperty (string) - Input message property for status signal. Default: `"status"`.
+- statusTimeout (number) - Seconds to wait for initial status response (0.01–3600s). Default: `30`. If heartbeat monitoring is disabled, this is the only timeout check.
+- heartbeatTimeout (number) - Seconds for continuous status heartbeat monitoring while call=true (0–3600s). Default: `30`. Set to 0 to disable heartbeat monitoring.
+- clearDelay (number) - Seconds to hold actual state after call deactivated (0–3600s). Default: `10`.
+- debounce (number) - Milliseconds to filter status flicker (0–10000ms). Default: `100`.
+- runLostStatus (checkbox) - Alarm if equipment status becomes false while call is true. Default: checked.
+- noStatusOnRun (checkbox) - Alarm if no status response within initial timeout. Default: checked.
+- runLostStatusMessage (string) - Alarm text for status lost. Default: `"Status lost during run"`.
+- noStatusOnRunMessage (string) - Alarm text for no status. Default: `"No status received during run"`.
+
+### Details
+
+The block implements a 4-state controller: IDLE (call=false), WAITING_FOR_STATUS (call=true, status pending), RUNNING (call=true, status=true), and STATUS_LOST (call=true, status=false).
+
+When call=true, the block expects two things: (1) Initial status arrival within statusTimeout seconds, and (2) if heartbeatTimeout is enabled, continuous status updates at least once every heartbeatTimeout seconds. If either requirement is violated, an alarm is triggered.
+
+When call=false but status=true, the block monitors that status goes false within clearDelay + 1 second. If status remains true beyond this window, an alarm is triggered indicating the equipment did not respond to the deactivation.
+
+Input routing processes messages in priority order: Status Update (from `msg.status` or `msg.context="status"`), Call Request (from configured input property).
+
+Debounce collapses rapid status changes within the configured window into a single state transition, preventing false alarms from sensor noise. All alarm conditions include 100ms hysteresis to prevent false triggers.
+
+#### Heartbeat Monitoring
+
+When call=true and heartbeatTimeout > 0, the block continuously verifies that status updates arrive within the heartbeat window. This detects communication loss or equipment failures mid-cycle. Set heartbeatTimeout=0 to disable this feature.
+
+#### Alarm Conditions
+
+Status Active Without Call (Hysteresis 100ms): Triggered when status=true AND call=false, indicating potential equipment fault, check valve failure, or external signal interference.
+
+No Status Response on Run (Hysteresis: statusTimeout seconds): Triggered when call=true but no status arrives within initial timeout, indicating equipment not responding or wiring failure at call initiation.
+
+Status Lost During Run (Hysteresis 100ms): Triggered when call=true, status=true initially, but either: (1) status goes false mid-cycle, or (2) heartbeat monitoring detects no status update within heartbeatTimeout window. Indicates mid-cycle shutdown or communication loss.
+
+Status Not Clearing (Hysteresis 100ms): Triggered when call=false, status=true initially, but status does not go false within clearDelay + 1 second window. Indicates equipment failed to deactivate.
+
+#### HVAC Scenarios
+
+Scenario 1: Chiller with unloader valve feedback. Send `{payload: true}` to request call. Chiller responds with `{context: "status", payload: true}` within 30s. As long as call=true and status updates arrive every 30 seconds, no alarm. If 31 seconds elapse without update, heartbeat alarm triggers. Configuration: Status Timeout=30s, Heartbeat Timeout=30s, Run Lost Status=true.
+
+Scenario 2: VAV box with wireless controller. Send `{payload: true}` to activate damper. If wireless module not responding, No Status alarm triggers after 10s. Configuration: Status Timeout=10s, Heartbeat Timeout=0 (heartbeat disabled), No Status On Run=true.
+
+Scenario 3: Pump with 5-second startup lag. Send `{payload: true}` at t=0. Pump motor spins up for 5 seconds, status arrives at t=5s. Send `{payload: false}` at t=10s. Clear Delay holds actual state for 3 seconds. At t=13s, state fully cleared. Configuration: Status Timeout=8s, Heartbeat Timeout=15s, Clear Delay=3s, Debounce=200ms.
+
+Scenario 4: Equipment with 60-second status heartbeat. Enable heartbeat monitoring with 60-second window. Configuration: Status Timeout=30s, Heartbeat Timeout=60s. Status must arrive at least once every 60 seconds to avoid "Status Lost" alarm.
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
 </script>