fix(safety): overfill must keep pumps running, not shut them down

Two hard rules for the safety controller, matching sewer PS design:

1. BELOW stopLevel (dry-run): pumps CANNOT start.
   All downstream equipment shut down. safetyControllerActive=true
   blocks _controlLogic so level control can't restart pumps.
   Only manual override or emergency can change this.

2. ABOVE overflow level (overfill): pumps CANNOT stop.
   Only UPSTREAM equipment is shut down (stop more water coming in).
   Machine groups (downstream pumps) are NOT shut down — they must
   keep draining. safetyControllerActive is NOT set, so _controlLogic
   continues commanding pumps at the demand dictated by the level
   curve (which is >100% near overflow = all pumps at maximum).
   Only manual override or emergency stop can shut pumps during
   an overfill event.

Previously the overfill branch called turnOffAllMachines() on machine
groups AND set safetyControllerActive=true, which shut down the pumps
and blocked level control from restarting them — exactly backwards
for a sewer pumping station where the sewage keeps coming.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,23 @@
+# pumpingStation — Claude Code context
+
+Wet-well basin model and pump orchestration.
+Part of the [EVOLV](https://gitea.wbd-rd.nl/RnD/EVOLV) wastewater-automation platform.
+
+## S88 classification
+
+| Level | Colour | Placement lane |
+|---|---|---|
+| **Process Cell** | `#0c99d9` | L5 |
+
+## Flow layout rules
+
+When wiring this node into a multi-node demo or production flow, follow the
+placement rule set in the **EVOLV superproject**:
+
+> `.claude/rules/node-red-flow-layout.md` (in the EVOLV repo root)
+
+Key points for this node:
+- Place on lane **L5** (x-position per the lane table in the rule).
+- Stack same-level siblings vertically.
+- Parent/children sit on adjacent lanes (children one lane left, parent one lane right).
+- Wrap in a Node-RED group box coloured `#0c99d9` (Process Cell).

pumpingStation.html

@@ -24,6 +24,14 @@
       heightInlet:    { value: 0.8 }, // m, centre of inlet pipe above floor
       heightOutlet:   { value: 0.2 }, // m, centre of outlet pipe above floor
       heightOverflow: { value: 0.9 }, // m, overflow elevation
+      timeleftToFullOrEmptyThresholdSeconds:{value:0}, // time threshold to safeguard starting or stopping pumps in seconds
+      enableDryRunProtection: { value: true },
+      enableOverfillProtection: { value: true },
+      dryRunThresholdPercent: { value: 2 },
+      overfillThresholdPercent: { value: 98 },
+      minHeightBasedOn: { value: "outlet" }, // basis for minimum height check: inlet or outlet
+      processOutputFormat: { value: "process" },
+      dbaseOutputFormat: { value: "influxdb" },
 
       // Advanced reference information
       refHeight:      { value: "NAP" }, // reference height
@@ -47,7 +55,16 @@
       hasDistance: { value: false },
       distance: { value: 0 },
       distanceUnit: { value: "m" },
-      distanceDescription: { value: "" }
+      distanceDescription: { value: "" },
+
+      // control strategy
+      controlMode: { value: "none" },
+      startLevel: { value: null },
+      stopLevel: { value: null },
+      minFlowLevel: { value: null },
+      maxFlowLevel: { value: null },
+      flowSetpoint: { value: null },
+      flowDeadband: { value: null }
 
     },
 
@@ -86,6 +103,68 @@
         refHeightEl.value = this.refHeight || "NAP";
       }
 
+      const minHeightBasedOnEl = document.getElementById("node-input-minHeightBasedOn");
+      if (minHeightBasedOnEl) {
+        minHeightBasedOnEl.value = this.minHeightBasedOn;
+      }
+
+      const dryRunToggle = document.getElementById("node-input-enableDryRunProtection");
+      const dryRunPercent = document.getElementById("node-input-dryRunThresholdPercent");
+      const overfillToggle = document.getElementById("node-input-enableOverfillProtection");
+      const overfillPercent = document.getElementById("node-input-overfillThresholdPercent");
+
+      const toggleInput = (toggleEl, inputEl) => {
+        if (!toggleEl || !inputEl) { return; }
+        inputEl.disabled = !toggleEl.checked;
+        inputEl.parentElement.classList.toggle('disabled', inputEl.disabled);
+      };
+
+      if (dryRunToggle && dryRunPercent) {
+        dryRunToggle.checked = !!this.enableDryRunProtection;
+        dryRunPercent.value = Number.isFinite(this.dryRunThresholdPercent) ? this.dryRunThresholdPercent : 2;
+        dryRunToggle.addEventListener('change', () => toggleInput(dryRunToggle, dryRunPercent));
+        toggleInput(dryRunToggle, dryRunPercent);
+      }
+
+      if (overfillToggle && overfillPercent) {
+        overfillToggle.checked = !!this.enableOverfillProtection;
+        overfillPercent.value = Number.isFinite(this.overfillThresholdPercent) ? this.overfillThresholdPercent : 98;
+        overfillToggle.addEventListener('change', () => toggleInput(overfillToggle, overfillPercent));
+        toggleInput(overfillToggle, overfillPercent);
+      }
+
+      const timeLeftInput = document.getElementById("node-input-timeleftToFullOrEmptyThresholdSeconds");
+      if (timeLeftInput) {
+        timeLeftInput.value = Number.isFinite(this.timeleftToFullOrEmptyThresholdSeconds)
+          ? this.timeleftToFullOrEmptyThresholdSeconds
+          : 0;
+      }
+
+      // control mode toggle UI
+      const toggleModeSections = (val) => {
+        document.querySelectorAll('.ps-mode-section').forEach((el) => el.style.display = 'none');
+        const active = document.getElementById(`ps-mode-${val}`);
+        if (active) active.style.display = '';
+      };
+
+      const modeSelect = document.getElementById('node-input-controlMode');
+      if (modeSelect) {
+        modeSelect.value = this.controlMode || 'none';
+        toggleModeSections(modeSelect.value);
+        modeSelect.addEventListener('change', (e) => toggleModeSections(e.target.value));
+      }
+
+      const setNumberField = (id, val) => {
+        const el = document.getElementById(id);
+        if (el) el.value = Number.isFinite(val) ? val : '';
+      };
+
+      setNumberField('node-input-startLevel', this.startLevel);
+      setNumberField('node-input-stopLevel', this.stopLevel);
+      setNumberField('node-input-minFlowLevel', this.minFlowLevel);
+      setNumberField('node-input-maxFlowLevel', this.maxFlowLevel);
+      setNumberField('node-input-flowSetpoint', this.flowSetpoint);
+      setNumberField('node-input-flowDeadband', this.flowDeadband);
 
         //------------------- END OF CUSTOM config UI ELEMENTS ------------------- //
     },
@@ -98,14 +177,29 @@
 
       //node specific
       node.refHeight = document.getElementById("node-input-refHeight").value || "NAP";
+      node.minHeightBasedOn = document.getElementById("node-input-minHeightBasedOn").value || "outlet";
       node.simulator = document.getElementById("node-input-simulator").checked;
 
-      ["basinVolume","basinHeight","heightInlet","heightOutlet","heightOverflow","basinBottomRef"]
+      ["basinVolume","basinHeight","heightInlet","heightOutlet","heightOverflow","basinBottomRef","timeleftToFullOrEmptyThresholdSeconds","dryRunThresholdPercent","overfillThresholdPercent"]
         .forEach(field => {
           node[field] = parseFloat(document.getElementById(`node-input-${field}`).value) || 0;
         });
 
       node.refHeight = document.getElementById("node-input-refHeight").value || "";
+      node.enableDryRunProtection = document.getElementById("node-input-enableDryRunProtection").checked;
+      node.enableOverfillProtection = document.getElementById("node-input-enableOverfillProtection").checked;
+
+      // control strategy
+      node.controlMode = document.getElementById('node-input-controlMode').value || 'none';
+
+      const parseNum = (id) => parseFloat(document.getElementById(id)?.value);
+      node.startLevel = parseNum('node-input-startLevel');
+      node.stopLevel = parseNum('node-input-stopLevel');
+      node.minFlowLevel = parseNum('node-input-minFlowLevel');
+      node.maxFlowLevel = parseNum('node-input-maxFlowLevel');
+      node.flowSetpoint = parseNum('node-input-flowSetpoint');
+      node.flowDeadband = parseNum('node-input-flowDeadband');
+
     },
 
   });
@@ -115,7 +209,7 @@
 
 <script type="text/html" data-template-name="pumpingStation">
 
-  <!-- Simulator toggle -->
+  <h4>Simulation</h4>
   <div class="form-row">
     <label for="node-input-simulator"><i class="fa fa-play-circle"></i> Simulator</label>
     <input type="checkbox" id="node-input-simulator" style="width:20px;vertical-align:baseline;" />
@@ -124,7 +218,7 @@
 
   <hr>
   
-  <!-- Basin geometry -->
+  <h4>Basin Geometry</h4>
   <div class="form-row">
     <label for="node-input-basinVolume"><i class="fa fa-cube"></i> Basin Volume (m³)</label>
     <input type="number" id="node-input-basinVolume" min="0" step="0.1" />
@@ -150,7 +244,58 @@
 
   <hr>
 
+  <h4>Control Strategy</h4>
+  <div class="form-row">
+    <label for="node-input-controlMode"><i class="fa fa-sliders"></i> Control mode</label>
+    <select id="node-input-controlMode">
+      <option value="none">None / Manual</option>
+      <option value="levelbased">Level-based</option>
+      <option value="flowbased">Flow-based</option>
+    </select>
+  </div>
+
+  <div id="ps-mode-levelbased" class="ps-mode-section">
+    <div class="form-row">
+      <label for="node-input-startLevel">startLevel</label>
+      <input type="number" id="node-input-startLevel" placeholder="m" />
+    </div>
+    <div class="form-row">
+      <label for="node-input-stopLevel">stopLevel</label>
+      <input type="number" id="node-input-stopLevel" placeholder="m" />
+    </div>
+      <div class="form-row">
+      <label for="node-input-minFlowLevel">Min flow (m)</label>
+      <input type="number" id="node-input-minFlowLevel" placeholder="m" />
+    </div>
+    <div class="form-row">
+      <label for="node-input-maxFlowLevel">Max flow (m)</label>
+      <input type="number" id="node-input-maxFlowLevel" placeholder="m" />
+    </div>
+  </div>
+
+  <div id="ps-mode-flowbased" class="ps-mode-section" style="display:none">
+    <div class="form-row">
+      <label for="node-input-flowSetpoint">Flow setpoint</label>
+      <input type="number" id="node-input-flowSetpoint" placeholder="m3/h" />
+    </div>
+    <div class="form-row">
+      <label for="node-input-flowDeadband">Deadband</label>
+      <input type="number" id="node-input-flowDeadband" placeholder="m3/h" />
+    </div>
+  </div>
+
+  <hr>
+
+  <h4>Reference</h4>
+
   <!-- Reference data -->
+  <div class="form-row">
+    <label for="node-input-minHeightBasedOn"><i class="fa fa-arrows-v"></i> Minimum Height Based On</label>
+    <select id="node-input-minHeightBasedOn" style="width:60%;">
+      <option value="inlet">Inlet Elevation</option>
+      <option value="outlet">Outlet Elevation</option>
+    </select>
+  </div>
   <div class="form-row">
     <label for="node-input-refHeight"><i class="fa fa-map-marker"></i> Reference height</label>
     <select id="node-input-refHeight" style="width:60%;">
@@ -163,6 +308,59 @@
     <input type="number" id="node-input-basinBottomRef" step="0.01" />
   </div>
 
+  <hr>
+
+  <h4>Safety</h4>
+
+  <!-- Safety settings -->
+  <div class="form-row">
+    <label for="node-input-timeleftToFullOrEmptyThresholdSeconds"><i class="fa fa-clock-o"></i> Time To Empty/Full (s)</label>
+    <input type="number" id="node-input-timeleftToFullOrEmptyThresholdSeconds" min="0" step="1" />
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-enableDryRunProtection">
+      <i class="fa fa-shield"></i> Dry-run Protection
+    </label>
+    <input type="checkbox" id="node-input-enableDryRunProtection" style="width:20px;vertical-align:baseline;" />
+    <span>Prevent pumps from running on low volume</span>
+  </div>
+  <div class="form-row">
+    <label for="node-input-dryRunThresholdPercent" style="padding-left:20px;">Low Volume Threshold (%)</label>
+    <input type="number" id="node-input-dryRunThresholdPercent" min="0" max="100" step="0.1" />
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-enableOverfillProtection">
+      <i class="fa fa-exclamation-triangle"></i> Overfill Protection
+    </label>
+    <input type="checkbox" id="node-input-enableOverfillProtection" style="width:20px;vertical-align:baseline;" />
+    <span>Stop filling when approaching overflow</span>
+  </div>
+  <div class="form-row">
+    <label for="node-input-overfillThresholdPercent" style="padding-left:20px;">High Volume Threshold (%)</label>
+    <input type="number" id="node-input-overfillThresholdPercent" min="0" max="100" step="0.1" />
+  </div>
+  <hr>
+
+  <h3>Output Formats</h3>
+  <div class="form-row">
+    <label for="node-input-processOutputFormat"><i class="fa fa-random"></i> Process Output</label>
+    <select id="node-input-processOutputFormat" style="width:60%;">
+      <option value="process">process</option>
+      <option value="json">json</option>
+      <option value="csv">csv</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-dbaseOutputFormat"><i class="fa fa-database"></i> Database Output</label>
+    <select id="node-input-dbaseOutputFormat" style="width:60%;">
+      <option value="influxdb">influxdb</option>
+      <option value="json">json</option>
+      <option value="csv">csv</option>
+    </select>
+  </div>
+
   <!-- Shared asset/logger/position menus -->
   <div id="asset-fields-placeholder"></div>
   <div id="logger-fields-placeholder"></div>

src/nodeClass.js

@@ -50,7 +50,24 @@ class nodeClass {
       },
       hydraulics: {
         refHeight: uiConfig.refHeight,
+        minHeightBasedOn: uiConfig.minHeightBasedOn,
         basinBottomRef: uiConfig.basinBottomRef,
+      },
+      control:{
+        mode: uiConfig.controlMode,
+        levelbased:{
+          startLevel:uiConfig.startLevel,
+          stopLevel:uiConfig.stopLevel,
+          minFlowLevel:uiConfig.minFlowLevel,
+          maxFlowLevel:uiConfig.maxFlowLevel
+        }
+      },
+      safety:{
+        enableDryRunProtection: uiConfig.enableDryRunProtection,
+        dryRunThresholdPercent: uiConfig.dryRunThresholdPercent,
+        enableOverfillProtection: uiConfig.enableOverfillProtection,
+        overfillThresholdPercent: uiConfig.overfillThresholdPercent,
+        timeleftToFullOrEmptyThresholdSeconds: uiConfig.timeleftToFullOrEmptyThresholdSeconds
       }
     });
 
@@ -86,65 +103,60 @@ class nodeClass {
 
   _updateNodeStatus() {
     const ps = this.source;
-    try {
+
-      // --- Basin & measurements -------------------------------------------------
+    const pickVariant = (type, prefer = ['measured', 'predicted'], position = 'atEquipment', unit) => {
+      for (const variant of prefer) {
+        const chain = ps.measurements.type(type).variant(variant).position(position);
+        const value = unit ? chain.getCurrentValue(unit) : chain.getCurrentValue();
+        if (value != null) return { value, variant };
+      }
+      return { value: null, variant: null };
+    };
+
+    const vol = pickVariant('volume', ['measured', 'predicted'], 'atEquipment', 'm3');
+    const volPercent = pickVariant('volumePercent', ['measured','predicted'], 'atEquipment'); // already unitless
+    const level = pickVariant('level', ['measured', 'predicted'], 'atEquipment', 'm');
+    const netFlow = pickVariant('netFlowRate', ['measured', 'predicted'], 'atEquipment', 'm3/h');
+
     const maxVolBeforeOverflow = ps.basin?.maxVolOverflow ?? ps.basin?.maxVol ?? 0;
-      const volumeMeasurement = ps.measurements.type("volume").variant("measured").position("atEquipment");
+    const currentVolume = vol.value ?? 0;
-      const currentVolume = volumeMeasurement.getCurrentValue("m3") ?? 0;
+    const currentvolPercent = volPercent.value ?? 0;
-      const netFlowMeasurement = ps.measurements.type("netFlowRate").variant("predicted").position("atEquipment");
+    const netFlowM3h = netFlow.value ?? 0;
-      const netFlowM3s = netFlowMeasurement?.getCurrentValue("m3/s") ?? 0;
-      const netFlowM3h = netFlowM3s * 3600;
-      const percentFull = ps.measurements.type("volume").variant("procent").position("atEquipment").getCurrentValue() ?? 0;
 
-      // --- State information ----------------------------------------------------
+    const direction = ps.state?.direction ?? 'unknown';
-      const direction = ps.state?.direction || "unknown";
     const secondsRemaining = ps.state?.seconds ?? null;
+    const timeRemainingMinutes = secondsRemaining != null ? Math.round(secondsRemaining / 60) : null;
 
-      const timeRemaining = secondsRemaining ? `${Math.round(secondsRemaining / 60)}` : 0 + " min";
+    const badgePieces = [];
-
+    badgePieces.push(`${currentvolPercent.toFixed(1)}% `);
-      // --- Icon / colour selection ---------------------------------------------
+    badgePieces.push(
-      let symbol = "❔";
+      `V=${currentVolume.toFixed(2)} / ${maxVolBeforeOverflow.toFixed(2)} m³`
-      let fill = "grey";
+    );
-
+    badgePieces.push(`net: ${netFlowM3h.toFixed(0)} m³/h`);
-      switch (direction) {
+    if (timeRemainingMinutes != null) {
-        case "filling":
+      badgePieces.push(`t≈${timeRemainingMinutes} min)`);
-          symbol = "⬆️";
-          fill = "blue";
-          break;
-        case "draining":
-          symbol = "⬇️";
-          fill = "orange";
-          break;
-        case "stable":
-          symbol = "⏸️";
-          fill = "green";
-          break;
-        default:
-          symbol = "❔";
-          fill = "grey";
-          break;
     }
 
-      // --- Status text ----------------------------------------------------------
+    const { symbol, fill } = (() => {
-      const textParts = [
+      switch (direction) {
-        `${symbol} ${percentFull.toFixed(1)}%`,
+        case 'filling': return { symbol: '⬆️', fill: 'blue' };
-        `V=${currentVolume.toFixed(2)} / ${maxVolBeforeOverflow.toFixed(2)} m³`,
+        case 'draining': return { symbol: '⬇️', fill: 'orange' };
-        `net=${netFlowM3h.toFixed(1)} m³/h`,
+        case 'steady': return { symbol: '⏸️', fill: 'green' };
-        `t≈${timeRemaining}`
+        default: return { symbol: '❔', fill: 'grey' };
-      ];
+      }
+    })();
+
+    badgePieces[0] = `${symbol} ${badgePieces[0]}`;
 
     return {
       fill,
-        shape: "dot",
+      shape: 'dot',
-        text: textParts.join(" | ")
+      text: badgePieces.join(' | ')
     };
-    } catch (error) {
-      this.node.error("Error in updateNodeStatus: " + error.message);
-      return { fill: "red", shape: "ring", text: "Status Error" };
-    }
   }
 
 
+
   // any time based functions here
   _startTickLoop() {
     setTimeout(() => {
@@ -167,8 +179,8 @@ class nodeClass {
     //pumping station needs time based ticks to recalc level when predicted
     this.source.tick();
     const raw = this.source.getOutput();
-    const processMsg = this._output.formatMsg(raw, this.config, 'process');
+    const processMsg = this._output.formatMsg(raw, this.source.config, 'process');
-    const influxMsg  = this._output.formatMsg(raw, this.config, 'influxdb');
+    const influxMsg  = this._output.formatMsg(raw, this.source.config, 'influxdb');
 
     // Send only updated outputs on ports 0 & 1
     this.node.send([processMsg, influxMsg]);
@@ -181,18 +193,53 @@ class nodeClass {
     this.node.on('input', (msg, send, done) => {
       switch (msg.topic) {
         //example
-        /*case 'simulator':
+        case 'changemode':
-          this.source.toggleSimulation();      
+          this.source.changeMode(msg.payload);
           break;
-        default:
-          this.source.handleInput(msg);
-          break;
-          */
         case 'registerChild': {
           // Register this node as a child of the parent node
           const childId = msg.payload;
           const childObj = this.RED.nodes.getNode(childId);
-          this.source.childRegistrationUtils.registerChild(childObj.source ,msg.positionVsParent);
+          this.source.childRegistrationUtils.registerChild(childObj.source, msg.positionVsParent);
+          break;
+        }
+        case 'calibratePredictedVolume': {
+          const injectedVol = parseFloat(msg.payload);
+          this.source.calibratePredictedVolume(injectedVol);
+          break;
+        }
+        case 'calibratePredictedLevel': {
+          const injectedLevel = parseFloat(msg.payload);
+          this.source.calibratePredictedLevel(injectedLevel);
+          break;
+        }
+        case 'q_in': {
+          // payload can be number or { value, unit, timestamp }
+          const val = Number(msg.payload);
+          const unit = msg?.unit;
+          const ts = msg?.timestamp || Date.now();
+          this.source.setManualInflow(val, ts, unit);
+          break;
+        }
+        case 'Qd': {
+          // Manual demand: operator sets the target output via a
+          // dashboard slider. Only accepted when PS is in 'manual'
+          // mode — mirrors how rotatingMachine gates commands by
+          // mode (virtualControl vs auto).
+          const demand = Number(msg.payload);
+          if (!Number.isFinite(demand)) {
+            this.source.logger.warn(`Invalid Qd value: ${msg.payload}`);
+            break;
+          }
+          if (this.source.mode === 'manual') {
+            this.source.forwardDemandToChildren(demand).catch((err) =>
+              this.source.logger.error(`Failed to forward demand: ${err.message}`)
+            );
+          } else {
+            this.source.logger.debug(
+              `Qd ignored in ${this.source.mode} mode. Switch to manual to use the demand slider.`
+            );
+          }
           break;
         }
       }