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

package/README.md

@@ -43,3 +43,13 @@ Search for the package name and add to your project.
 - $ npm install node-red-contrib-buildingblocks-control
 # then restart node-red
 ```
+
+## Testing
+Tests use [Mocha](https://mochajs.org/) and [node-red-node-test-helper](https://github.com/node-red/node-red-node-test-helper) to run nodes in an isolated, in-memory Node-RED runtime. Your live Node-RED instance is never touched.
+
+```bash
+npm install   # install dev dependencies (mocha, test helper)
+npm test      # run all tests
+```
+
+Test files live in `test/` and follow the naming convention `*_spec.js`. Shared utilities are in `test/test-helpers.js`.

package/nodes/alarm-collector.html

@@ -96,6 +96,7 @@
     <div class="form-row">
         <label for="node-input-message"><i class="fa fa-comment"></i> Message</label>
         <input type="text" id="node-input-message" placeholder="Zone exceeds setpoint">
+        <input type="hidden" id="node-input-messageType">
     </div>
 
     <div class="form-row">
@@ -131,6 +132,7 @@
             topic: { value: "Alarms_Default" },
             title: { value: "Alarm" },
             message: { value: "Condition triggered" },
+            messageType: { value: "str" },
             tags: { value: "" },
             units: { value: "°F" }
         },
@@ -197,6 +199,15 @@
                 typeField: "#node-input-inputFieldType"
             }).typedInput("type", node.inputFieldType || "msg").typedInput("value", node.inputField || "payload");
 
+            // Setup message typedInput: static string or from msg property
+            $("#node-input-message").typedInput({
+                types: [
+                    "str",
+                    "msg"
+                ],
+                typeField: "#node-input-messageType"
+            }).typedInput("type", node.messageType || "str").typedInput("value", node.message || "Condition triggered");
+
             // Show/hide sections based on inputMode
             const updateDisplay = () => {
                 let mode = $("#node-input-inputMode").val();

package/nodes/alarm-collector.js

@@ -20,6 +20,7 @@ module.exports = function(RED) {
         node.topic = config.topic || "Alarms_Default";
         node.title = config.title || "Alarm";
         node.message = config.message || "Condition triggered";
+        node.messageType = config.messageType || "str";
         node.tags = config.tags || "";
         node.units = config.units || "";
 
@@ -257,6 +258,18 @@ module.exports = function(RED) {
                     }
                 }
 
+                // Resolve message dynamically if configured as msg property
+                if (node.messageType === "msg") {
+                    try {
+                        const resolved = await utils.evaluateNodeProperty(config.message, "msg", node, msg);
+                        if (resolved !== undefined && resolved !== null) {
+                            node.message = String(resolved);
+                        }
+                    } catch (e) {
+                        // Keep existing message on error
+                    }
+                }
+
                 evaluateAndEmit(inputValue);
             } catch (err) {
                 utils.setStatusError(node, `Error reading input: ${err.message}`);

package/nodes/alarm-service.js

@@ -48,7 +48,7 @@ module.exports = function(RED) {
 
                 // Send alarm message with status
                 const msg = {
-                    payload: eventData,
+                    alarm: eventData,
                     status: { state: "triggered", transition: eventData.transition },
                     activeAlarmCount: activeCount,
                     alarmKey: key
@@ -71,7 +71,7 @@ module.exports = function(RED) {
 
                     // Send clear message with status
                     const msg = {
-                        payload: eventData,
+                        alarm: eventData,
                         status: { state: "cleared", transition: eventData.transition },
                         activeAlarmCount: activeCount,
                         alarmKey: key

package/nodes/and-block.js

@@ -48,7 +48,7 @@ module.exports = function(RED) {
                     node.inputs[slotVal.index - 1] = Boolean(msg.payload);
                     const result = node.inputs.every(v => v === true);
                     const isUnchanged = result === lastResult && node.inputs.every((v, i) => v === lastInputs[i]);
-                    const statusText = `in: [${node.inputs.join(", ")}], out: ${result}`;
+                    const statusText = `[${node.inputs.join(", ")}] -> ${result}`;
                     
                     // ================================================================
                     // Debounce: Suppress consecutive same outputs within 500ms

package/nodes/call-status-block.html

@@ -5,16 +5,22 @@
         <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">
+        <label for="node-input-callValue" title="Call (request) signal — typed input (bool, msg, flow, global)"><i class="fa fa-sign-in"></i> Call Value</label>
+        <input type="text" id="node-input-callValue" placeholder="payload">
+        <input type="hidden" id="node-input-callValueType">
     </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">
+        <label for="node-input-statusValue" title="Status (response) signal — typed input (bool, msg, flow, global)"><i class="fa fa-sign-out"></i> Status Value</label>
+        <input type="text" id="node-input-statusValue" placeholder="status">
+        <input type="hidden" id="node-input-statusValueType">
     </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">
+        <label for="node-input-statusTimeout" title="Time to wait for initial status response after call activates (seconds, 0=disabled)"><i class="fa fa-clock-o"></i> Status Timeout</label>
+        <input type="number" id="node-input-statusTimeout" placeholder="30" 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-heartbeat"></i> Heartbeat Timeout</label>
+        <input type="number" id="node-input-heartbeatTimeout" placeholder="0" min="0" step="any">
     </div>
     <div class="form-row">
         <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>
@@ -22,27 +28,31 @@
     </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">
+        <input type="number" id="node-input-debounce" placeholder="0" 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">
+        <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-runLostStatus" title="Alarm if status is lost 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;">
+        <label for="node-input-statusWithoutCall" title="Alarm if equipment status is active without a call signal (boolean)"><i class="fa fa-exclamation-triangle"></i> Status Without Call</label>
+        <input type="checkbox" id="node-input-statusWithoutCall" style="width: auto; vertical-align: middle;">
+    </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>
     <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">
+        <label for="node-input-statusWithoutCallMessage" title="Message for status without call alarm (string)"><i class="fa fa-comment"></i> Without Call Message</label>
+        <input type="text" id="node-input-statusWithoutCallMessage" placeholder="Status active without call">
     </div>
 </script>
 
@@ -53,16 +63,20 @@
         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; } },
+            callValue: { value: "payload" },
+            callValueType: { value: "msg" },
+            statusValue: { value: "status" },
+            statusValueType: { value: "msg" },
+            statusTimeout: { value: 30, required: true, validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) >= 0; } },
+            heartbeatTimeout: { value: 0, 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; } },
+            debounce: { value: 0, required: true, validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) >= 0; } },
             runLostStatus: { value: false },
             noStatusOnRun: { value: true },
+            statusWithoutCall: { value: true },
             runLostStatusMessage: { value: "Status lost during run" },
-            noStatusOnRunMessage: { value: "No status received during run" }
+            noStatusOnRunMessage: { value: "No status received during run" },
+            statusWithoutCallMessage: { value: "Status active without call" }
         },
         inputs: 1,
         outputs: 1,
@@ -72,6 +86,24 @@
         paletteLabel: "call status",
         label: function() {
             return this.name || "call status";
+        },
+        oneditprepare: function() {
+            const node = this;
+            try {
+                $("#node-input-callValue").typedInput({
+                    default: "msg",
+                    types: ["msg", "flow", "global", "bool"],
+                    typeField: "#node-input-callValueType"
+                }).typedInput("type", node.callValueType || "msg").typedInput("value", node.callValue || "payload");
+
+                $("#node-input-statusValue").typedInput({
+                    default: "msg",
+                    types: ["msg", "flow", "global", "bool"],
+                    typeField: "#node-input-statusValueType"
+                }).typedInput("type", node.statusValueType || "msg").typedInput("value", node.statusValue || "status");
+            } catch(e) {
+                console.error("Error preparing call-status-block editor:", e);
+            }
         }
     });
 </script>
@@ -82,8 +114,11 @@ Monitors call and status signals to detect equipment faults, communication losse
 
 ### Inputs
 
-: 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.
+Both **Call Value** and **Status Value** are **typed inputs** — they can read from `msg` properties, `flow` variables, `global` variables, or static `bool` values.
+
+Every incoming message triggers the node to evaluate both values and process state transitions.
+
+: context (string) : Optional. Send `msg.context = "reset"` with `msg.payload = true` to reset all state and clear alarms.
 
 ### Outputs
 
@@ -93,60 +128,52 @@ Monitors call and status signals to detect equipment faults, communication losse
 
 ### Properties
 
-- 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"`.
+- **Call Value** (typed input) — Source of the call (request) signal. Default: `msg.payload`. Can be `msg`, `flow`, `global`, or `bool`.
+- **Status Value** (typed input) — Source of the status (response) signal. Default: `msg.status`. Can be `msg`, `flow`, `global`, or `bool`.
+- **Status Timeout** (number) — Seconds to wait for the *first* status=true after call activates (0=disabled). This is a one-shot timer for initial equipment response. Default: `30`.
+- **Heartbeat Timeout** (number) — Seconds for ongoing status freshness monitoring while running. Each status=true resets the timer. If it expires without a refresh, status is considered lost (0=disabled). Default: `0`.
+- **Clear Delay** (number) — Seconds to hold actual state after call deactivated (0=immediate). Default: `10`.
+- **Debounce** (number) — Milliseconds to filter status value changes (0=disabled). Default: `0`.
+- **No Status On Run** (checkbox) — Alarm if no status response within initial timeout. Default: checked.
+- **Run Lost Status** (checkbox) — Alarm if equipment status becomes false while call is true. Default: unchecked.
+- **Status Without Call** (checkbox) — Alarm if equipment status is active without a call signal. Default: checked.
+- **No Status Message** (string) — Alarm text for no status. Default: `"No status received during run"`.
+- **Run Lost Message** (string) — Alarm text for status lost. Default: `"Status lost during run"`.
+- **Without Call Message** (string) — Alarm text for status without call. Default: `"Status active without call"`.
 
 ### 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).
+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 after previously being true).
 
-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.
+On every incoming message, the node evaluates both the call and status typed inputs simultaneously. This means a single message can carry both signals (e.g., `msg.payload` for call and `msg.status` for equipment feedback).
 
-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.
+**Heartbeat refresh**: Repeated status=true values refresh the heartbeat timer even though the value hasn't changed. This is critical — equipment that continuously reports `status: true` must keep the heartbeat alive.
 
-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.
+**Debounce** only delays processing of status *value changes*. Same-value status updates always refresh the heartbeat immediately.
 
 #### 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.
+1. **No Status Response** (hysteresis: statusTimeout seconds) — Triggered when call=true but no status arrives within initial timeout.
 
-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.
+2. **Status Lost During Run** (hysteresis: 100ms) — Triggered when call=true, status was true, but status goes false mid-cycle. Also triggered by heartbeat timeout if enabled.
 
-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.
+3. **Status Active Without Call** (hysteresis: 100ms) — Triggered when status=true but call=false (and no clearTimer running), indicating unexpected equipment activity.
 
-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.
+4. **Status Not Clearing** (hysteresis: clearDelay+1 seconds) — Triggered when call=false but status remains true beyond the clear delay window.
 
 #### 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.
+**Chiller with feedback**: Call Value = `msg.payload`, Status Value = `flow.chillerStatus`. Send `{payload: true}` to request. Chiller writes status to flow variable. Config: Status Timeout=30s, Heartbeat=30s, Run Lost Status=checked.
 
-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.
+**VAV box wireless**: Call Value = `msg.payload`, Status Value = `msg.status`. Config: Status Timeout=10s, Heartbeat=0 (disabled), No Status On Run=checked.
 
-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.
+**Pump with startup lag**: Call Value = `msg.payload`, Status Value = `global.pumpRunning`. Config: Status Timeout=8s, Heartbeat=15s, Clear Delay=3s, Debounce=200ms.
 
 ### Status
-- Green (dot): Configuration update
-- Blue (dot): State changed
-- Blue (ring): State unchanged
-- Red (ring): Error
-- Yellow (ring): Warning
+- Green (dot): Running normally (call=ON, status=ON)
+- Blue (ring): Idle (call=OFF, status=OFF)
+- Yellow (ring): Waiting/warning state
+- Red (ring): Alarm active
 
 ### References