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

package/nodes/or-block.js

@@ -1,4 +1,6 @@
 module.exports = function(RED) {
+    const utils = require('./utils')(RED);
+
     function OrBlockNode(config) {
         RED.nodes.createNode(this, config);
         const node = this;
@@ -7,60 +9,87 @@ module.exports = function(RED) {
         node.inputs = Array(parseInt(config.slots) || 2).fill(false)
         node.slots = parseInt(config.slots);
 
-        node.status({ fill: "green", shape: "dot", text: `slots: ${node.slots}` });
+        utils.setStatusOK(node, `slots: ${node.slots}`);
 
         // Initialize logic fields
         let lastResult = null;
         let lastInputs = node.inputs.slice();
+        let lastOutputTime = 0;           // Track last output timestamp for debounce
+        let lastOutputValue = undefined;  // Track last output value for duplicate suppression
+        const DEBOUNCE_MS = 500;          // Debounce period in milliseconds
 
         node.on("input", function(msg, send, done) {
             send = send || function() { node.send.apply(node, arguments); };
 
             // Guard against invalid msg
             if (!msg) {
-                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                utils.setStatusError(node, "invalid message");
                 if (done) done();
                 return;
             }
 
             // Check required properties
             if (!msg.hasOwnProperty("context")) {
-                node.status({ fill: "red", shape: "ring", text: "missing context" });
+                utils.setStatusError(node, "missing context");
                 if (done) done();
                 return;
             }
 
             if (!msg.hasOwnProperty("payload")) {
-                node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                utils.setStatusError(node, "missing payload");
                 if (done) done();
                 return;
             }
 
             // Process input slot
             if (msg.context.startsWith("in")) {
-                let index = parseInt(msg.context.slice(2), 10);
-                if (!isNaN(index) && index >= 1 && index <= node.slots) {
-                    node.inputs[index - 1] = Boolean(msg.payload);
+                const slotVal = utils.validateSlotIndex(msg.context, node.slots);
+                if (slotVal.valid) {
+                    node.inputs[slotVal.index - 1] = Boolean(msg.payload);
                     const result = node.inputs.some(v => v === true);
                     const isUnchanged = result === lastResult && node.inputs.every((v, i) => v === lastInputs[i]);
-                    node.status({
-                        fill: "blue",
-                        shape: isUnchanged ? "ring" : "dot",
-                        text: `in: [${node.inputs.join(", ")}], out: ${result}`
-                    });
+                    const statusText = `in: [${node.inputs.join(", ")}], out: ${result}`;
+                    
+                    // ================================================================
+                    // Debounce: Suppress consecutive same outputs within 500ms
+                    // But always output if value is different or debounce time expired
+                    // ================================================================
+                    const now = Date.now();
+                    const timeSinceLastOutput = now - lastOutputTime;
+                    const isSameOutput = result === lastOutputValue;
+                    const shouldSuppress = isSameOutput && timeSinceLastOutput < DEBOUNCE_MS;
+                    
+                    if (shouldSuppress) {
+                        // Same output within debounce window - don't send, just update status
+                        utils.setStatusUnchanged(node, statusText);
+                    } else {
+                        // Different output or debounce period expired - send it
+                        if (isUnchanged) {
+                            utils.setStatusUnchanged(node, statusText);
+                        } else {
+                            utils.setStatusChanged(node, statusText);
+                        }
+                        
+                        // Record output for next debounce comparison
+                        lastOutputTime = now;
+                        lastOutputValue = result;
+                        
+                        // Send output to allow all downstream branches to update
+                        send({ payload: result });
+                    }
+                    
                     lastResult = result;
                     lastInputs = node.inputs.slice();
-                    send({ payload: result });
                     if (done) done();
                     return;
                 } else {
-                    node.status({ fill: "red", shape: "ring", text: `invalid input index ${index || "NaN"}` });
+                    utils.setStatusError(node, slotVal.error);
                     if (done) done();
                     return;
                 }
             }
 
-            node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+            utils.setStatusWarn(node, "unknown context");
             if (done) done();
         });
 

package/nodes/pid-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-kp" title="Proportional gain (number)"><i class="fa fa-sliders"></i> Kp</label>
         <input type="text" id="node-input-kp" placeholder="0" step="any">
@@ -29,6 +33,11 @@
         <input type="text" id="node-input-deadband" placeholder="0" step="any" min="0">
         <input type="hidden" id="node-input-deadbandType">
     </div>
+    <div class="form-row">
+        <label for="node-input-setpointRateLimit" title="Maximum setpoint change per second (non-negative number, 0 = no limit)"><i class="fa fa-arrow-right"></i> Setpoint Rate Limit</label>
+        <input type="text" id="node-input-setpointRateLimit" placeholder="0" step="any" min="0">
+        <input type="hidden" id="node-input-setpointRateLimitType">
+    </div>
     <div class="form-row">
         <label for="node-input-dbBehavior" title="Deadband behavior: ReturnToZero or HoldLastResult"><i class="fa fa-cog"></i> Deadband Behavior</label>
         <select id="node-input-dbBehavior">
@@ -69,6 +78,7 @@
         color: "#301934",
         defaults: {
             name: { value: "" },
+            inputProperty: { value: "payload" },
             kp: { value: 0, required: true },
             kpType: { value: "num" },
             ki: { value: 0, required: true },
@@ -79,6 +89,8 @@
             setpointType: { value: "num" },
             deadband: { value: 0, required: true },
             deadbandType: { value: "num" },
+            setpointRateLimit: { value: 0, required: true },
+            setpointRateLimitType: { value: "num" },
             dbBehavior: { value: "ReturnToZero" },
             outMin: { value: null },
             outMinType: { value: "num" },
@@ -134,6 +146,12 @@
                     typeField: "#node-input-deadbandType"
                 }).typedInput("type", node.deadbandType || "num").typedInput("value", node.deadband);
 
+                $("#node-input-setpointRateLimit").typedInput({
+                    default: "num",
+                    types: ["num", "msg", "flow", "global"],
+                    typeField: "#node-input-setpointRateLimitType"
+                }).typedInput("type", node.setpointRateLimitType || "num").typedInput("value", node.setpointRateLimit);
+
                 $("#node-input-outMin").typedInput({
                     default: "num",
                     types: ["num", "msg", "flow", "global"],
@@ -185,6 +203,7 @@ Implements a PID controller with deadband, output limits, and tuning.
 : kd (number) : Derivative gain. Default: 0.
 : setpoint (number) : Target setpoint. Default: 0.
 : deadband (number) : Deadband range around setpoint (non-negative). Default: 0.
+: setpointRateLimit (number) : Maximum setpoint change per second (non-negative, 0 = no limit). Default: 0.
 : dbBehavior (string) : Deadband behavior (`"ReturnToZero"`, `"HoldLastResult"`). Default: `"ReturnToZero"`.
 : outMin (number | null) : Minimum output limit (less than outMax). Default: null.
 : outMax (number | null) : Maximum output limit (greater than outMin). Default: null.
@@ -193,13 +212,44 @@ Implements a PID controller with deadband, output limits, and tuning.
 : run (boolean) : Enable (true) or disable (false) PID calculation. Default: true.
 
 ### Details
-Calculates PID control output based on numeric `msg.payload`, setpoint, and gains (`kp`, `ki`, `kd`). 
 
-Supports deadband, output limits, rate of change limit, direct/reverse action, integral clamping, and Ziegler-Nichols tuning. 
+**Core Algorithm**
+Calculates PID control output every cycle based on `msg.payload` (input), setpoint, and configurable gains (`kp`, `ki`, `kd`). Supports both **Direct Action** (cooling: error↑ → output↑) and **Reverse Action** (heating: error↑ → output↓) modes.
+
+**Error Calculation**
+- Reverse Action (heating): `error = setpoint - input`
+- Direct Action (cooling): `error = input - setpoint`
+
+**PID Terms**
+- **P (Proportional)**: Immediate response to error. `pGain = Kp × error`
+- **I (Integral)**: Removes steady-state offset by accumulating error over time with anti-windup clamping to prevent excessive accumulation when output limits are active.
+- **D (Derivative)**: Low-pass filtered to prevent noise amplification. Uses exponential smoothing (0.1 new + 0.9 old).
+
+**Setpoint Rate Limiting**
+Smoothly ramps setpoint changes at configured rate (units per second) to prevent integrator wind-up and thermal shock. With `setpointRateLimit = 0`, setpoint changes immediately.
+
+**Deadband**
+No output generated when input is within ±deadband of setpoint. Behavior controlled by `dbBehavior`: 
+- `ReturnToZero`: Output becomes 0
+- `HoldLastResult`: Output holds previous value
+
+**Output Limiting**
+Hard limits applied before output transmission. `maxChange` further limits rate of change to prevent abrupt jumps (units per second).
+
+**Relay Auto-Tuning (Ziegler-Nichols)**
+Send `{context: "tune", payload: true}` to start automatic tuning. Uses bang-bang relay control to oscillate the system and measure:
+- **Tu** (Ultimate Period): Time for one complete oscillation cycle
+- **Ku** (Ultimate Gain): Peak oscillation amplitude
+
+Calculates conservative "no overshoot" gains:
+- `Kp = 0.2 × Ku`
+- `Ki = 0.4 × Kp / Tu`
+- `Kd = 0.066 × Kp × Tu`
 
-Outputs `{ payload: number, diagnostics: object }` when output changes, or `{ tuneResult: object }` on tuning completion. 
+Tuning data persists across input messages but resets on flow restart. Progress shown in status bar during measurement.
 
-Ziegler-Nichols tuning sets `kp = 0.6*Ku`, `ki = 2*kp/Tu`, `kd = kp*Tu/8` after detecting oscillations. Outputs only on change.
+**Output**
+Sends every calculation cycle: `{ payload: number, diagnostics: {...} }` showing P/I/D breakdown and current state. On tuning completion: `{ tuneResult: {...} }` with calculated gains and oscillation count.
 
 ### Error Handling
 - Missing `msg`: No output, red status (`invalid message`).