diff --git a/wiki/Home.md b/wiki/Home.md index 1513997..36a902f 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -1,62 +1,67 @@ # pumpingStation -> **Reflects code as of `d2384b1` · regenerated `` via `npm run wiki:all`** +> **Reflects code as of `530f84a` · regenerated `2026-05-11` via `npm run wiki:all`** > If this banner is stale, the page may be out of date. Treat as informative, not authoritative. ## 1. What this node is -**pumpingStation** is an S88 Process Cell that owns a wet-well basin and orchestrates the pumps that drain it. It tracks measured + predicted volume, evaluates safety interlocks (dry-run, overfill), and dispatches a control strategy that hands a demand setpoint to one or more downstream machine groups or individual pumps. +**pumpingStation** is an S88 Process Cell that owns a wet-well basin and orchestrates the pumps that drain it. It tracks measured and predicted volume, evaluates safety interlocks (dry-run, overfill), and dispatches a control strategy that hands a demand setpoint to one or more downstream machine groups or individual pumps. Stateful (control mode) and tick-driven (1 s integrator). See [`wiki/functional-description.md`](functional-description) for the full behaviour spec. ## 2. Position in the platform ```mermaid flowchart LR - ps[pumpingStation
Process Cell]:::pc meas_lvl[measurement
type=level
position=atequipment]:::ctrl meas_in[measurement
type=flow
position=upstream]:::ctrl + ps[pumpingStation
Process Cell]:::pc mgc[machineGroupControl
Unit]:::unit + pump[rotatingMachine
Equipment]:::equip - meas_lvl -.data.-> ps - meas_in -.data.-> ps - ps -->|set.demand| mgc - mgc -.evt.flow-predicted.-> ps + meas_lvl -->|level.measured.atequipment| ps + meas_in -->|flow.measured.upstream| ps + pump -->|child.register| mgc mgc -->|child.register| ps + mgc -->|flow.predicted.downstream| ps + ps -->|set.demand| mgc classDef pc fill:#0c99d9,color:#fff classDef unit fill:#50a8d9,color:#000 + classDef equip fill:#86bbdd,color:#000 classDef ctrl fill:#a9daee,color:#000 ``` -S88 colours: Process Cell `#0c99d9`, Unit `#50a8d9`, Control Module `#a9daee`. Source of truth: `.claude/rules/node-red-flow-layout.md`. +S88 colours: Process Cell `#0c99d9`, Unit `#50a8d9`, Equipment `#86bbdd`, Control Module `#a9daee`. Source of truth: `.claude/rules/node-red-flow-layout.md §10.1`. ## 3. Capability matrix | Capability | Status | Notes | |---|---|---| -| Predicts basin volume from net flow | ✅ | Integrator seeded from `basin.minVol`; recomputes level. | -| Accepts measured level / volume / pressure | ✅ | Routed via `measurementRouter` on child registration. | -| Level-based control strategy | ✅ | Linear or log ramp between `minLevel` and `maxLevel`. | +| Predicts basin volume from net flow | ✅ | Integrator seeded from `basin.minVol`; recomputes level each tick. | +| Accepts measured level / volume / pressure / flow | ✅ | Routed via `measurementRouter` on child registration. | +| Level-based control strategy | ✅ | Linear or log ramp between `startLevel` and `maxLevel`. | | Flow-based control strategy | ✅ | PID against `flowSetpoint`. | | Manual demand passthrough | ✅ | `set.demand` only honoured in `manual` mode. | -| Dry-run safety interlock | ✅ | Stops downstream pumps when volume < `minVol` while draining. | -| Overfill safety interlock | ✅ | Stops upstream equipment when volume crosses overfill threshold. | -| Cascaded children (sub-stations) | ⚠️ | Accepted via `pumpingstation` softwareType but not exercised in production. | +| Dry-run safety interlock | ✅ | Shuts downstream pumps when volume < `minVol` while draining. Blocks control. | +| Overfill safety interlock | ✅ | Shuts upstream equipment when volume > threshold while filling. Control keeps running. | +| No-data panic | ✅ | Shuts ALL machines and blocks control when no volume reading is available. | +| Cascaded sub-stations | ⚠️ | Accepted via `pumpingstation` softwareType but not exercised in production. | +| pressureBased / powerBased / hybrid modes | ❌ | Enumerated in schema but not dispatched — only `levelbased`, `flowbased`, `manual`. | ## 4. Code map ```mermaid flowchart TB subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"] - nc["buildDomainConfig()
static DomainClass, commands
static tickInterval = 1000ms"] + nc["buildDomainConfig()
static DomainClass, commands
static tickInterval = 1000 ms"] end subgraph domain["specificClass.js — orchestrator (BaseDomain)"] - sc["PumpingStation.configure()
declares ChildRouter rules
tick() → safety → control"] + sc["PumpingStation.configure()
declares ChildRouter rules
tick() → flowAggregator → safety → control"] end subgraph concerns["src/ concern modules"] - basin["basin/
BasinGeometry + thresholdValidator"] - measurement["measurement/
flowAggregator + router + calibration"] - control["control/
levelbased / flowbased / manual"] + basin["basin/
BasinGeometry · thresholdValidator"] + measurement["measurement/
flowAggregator · measurementRouter · calibration"] + control["control/
levelBased · flowBased · manual · dispatch"] safety["safety/
SafetyController"] - commands["commands/
topic registry + handlers"] + commands["commands/
topic registry · handlers"] end nc --> sc sc --> basin @@ -70,7 +75,7 @@ flowchart TB |---|---|---| | `basin/` | Geometry, volume↔level conversion, threshold ordering | Capacity, level↔volume math, fill %. | | `measurement/` | Net-flow aggregation, predicted-volume integrator, calibration | Predicted volume / time-to-full. | -| `control/` | Control strategy dispatch (`levelbased`, `flowbased`, `manual`) | Demand calculation, mode behaviour. | +| `control/` | Strategy dispatch (`levelbased`, `flowbased`, `manual`) | Demand calculation, mode behaviour. | | `safety/` | Dry-run + overfill rules, pump-shutdown side-effects | Safety envelope, alarm reactions. | | `commands/` | Input-topic registry and handlers | New input topics, payload validation. | @@ -101,14 +106,14 @@ flowchart LR subgraph kids["accepted children (softwareType)"] m["measurement"]:::ctrl mach["machine
(rotatingMachine)"]:::equip - mgc["machinegroup"]:::unit + mgc["machinegroup
(machineGroupControl)"]:::unit sub["pumpingstation
(sub-station)"]:::pc end - m -->|"<type>.measured.<position>"| route1[_subscribeMeasurement
routes to measurementRouter] - mach -->|flow.predicted.<in or out>| route2[_subscribePredictedFlow
+ flowAggregator] - mgc -->|flow.predicted.<in or out>| route2 - sub -->|flow.predicted.<in or out>| route2 - route1 --> tick[tick] + m -->|"<type>.measured.<position>"| route1[_subscribeMeasurement
→ measurementRouter] + mach -->|flow.predicted.out| route2[_subscribePredictedFlow
+ flowAggregator] + mgc -->|flow.predicted.out| route2 + sub -->|flow.predicted.out| route2 + route1 --> tick[tick / integrator] route2 --> tick classDef ctrl fill:#a9daee,color:#000 classDef equip fill:#86bbdd,color:#000 @@ -118,10 +123,10 @@ flowchart LR | softwareType | onRegister side-effect | Subscribed events | |---|---|---| -| `measurement` | `_subscribeMeasurement(child)` — registers in MeasurementContainer. | `.measured.` for any type (pressure, level, flow, …). | -| `machine` | Stored in `this.machines[id]`. **Skipped when a machineGroup parent is present** to avoid double-counting. | `flow.predicted.` per the child's `positionVsParent`. | -| `machinegroup` | Stored in `this.machineGroups[id]`. | `flow.predicted.`. | -| `pumpingstation` | Stored in `this.stations[id]`. | `flow.predicted.`. | +| `measurement` | `_subscribeMeasurement(child)` — writes to MeasurementContainer by type + position. | `.measured.` for any type (level, flow, pressure, …). | +| `machine` | Added to `this.machines`. **Skipped when a `machinegroup` is present** — avoids double-counting predicted flow. | `flow.predicted.` per `positionVsParent`. | +| `machinegroup` | Added to `this.machineGroups`. | `flow.predicted.`. | +| `pumpingstation` | Added to `this.stations`. | `flow.predicted.`. | ## 7. Lifecycle — what one tick does @@ -134,14 +139,22 @@ sequenceDiagram participant ctl as control strategy participant out as Port-0 output - child->>ps: data event (measured.level / flow.predicted.out) - ps->>ps: ChildRouter dispatches to handler - Note over ps: every 1000 ms (static tickInterval) - ps->>fa: tick() — net flow, ETA, predicted volume + child->>ps: data event (level.measured.atequipment / flow.predicted.out) + ps->>ps: ChildRouter dispatches to _subscribeMeasurement / _subscribePredictedFlow + Note over ps: every 1000 ms (static tickInterval = 1000) + ps->>fa: tick() — net flow · ETA · predicted volume integrator ps->>sf: evaluate({direction, secondsRemaining}) - alt safety blocked - sf-->>ps: blocked=true, reason - Note over ctl: skipped this tick + alt no-volume-data panic + sf-->>ps: blocked=true, reason='no-volume-data' + sf-->>ps: ALL machines shut down + else dry-run (vol < minVol AND draining) + sf-->>ps: blocked=true, reason='dry-run' + sf-->>ps: downstream machines + machineGroups shut down + else overfill (vol > threshold AND filling) + sf-->>ps: blocked=false, reason='overfill' + sf-->>ps: upstream machines + child stations shut down + ps->>ctl: dispatch(mode, ctx, controlState) + ctl-->>ps: percControl updated — pumps keep draining else safety clear ps->>ctl: dispatch(mode, ctx, controlState) ctl-->>ps: percControl updated @@ -150,6 +163,8 @@ sequenceDiagram ps->>out: msg{topic, payload (delta-compressed)} ``` +For control-strategy details see [`wiki/modes/`](modes/README). + ## 8. Data model — `getOutput()` What lands on Port 0. Built in `getOutput()`, then delta-compressed by `outputUtils.formatMsg`. @@ -197,15 +212,15 @@ flowchart TB f1[Basin: volume / height] f2[Levels: inflow / outflow / overflow] f3[Control mode] - f4[Level setpoints: min / start / max] - f5[Safety: dry-run % / overfill %] + f4[Level-based setpoints: startLevel / stopLevel / minLevel / maxLevel] + f5[Safety: dry-run % / high-volume %] end subgraph config["Domain config slice"] c1[basin.volume
basin.height] c2[basin.inflowLevel
basin.outflowLevel
basin.overflowLevel] c3[control.mode] - c4[control.levelbased.minLevel
control.levelbased.startLevel
control.levelbased.maxLevel] - c5[safety.dryRunThresholdPercent
safety.overfillThresholdPercent] + c4[control.levelbased.startLevel
control.levelbased.stopLevel
control.levelbased.minLevel
control.levelbased.maxLevel] + c5[safety.dryRunThresholdPercent
safety.highVolumeSafetyThresholdPercent] end f1 --> c1 f2 --> c2 @@ -218,78 +233,101 @@ flowchart TB |---|---|---|---|---| | `basinVolume` | `basin.volume` | `1` | > 0 (m³) | `BasinGeometry` | | `basinHeight` | `basin.height` | `1` | > 0 (m) | `BasinGeometry` | -| `inflowLevel` | `basin.inflowLevel` | `2` | ≥ 0 (m) | threshold validator, control | +| `inflowLevel` | `basin.inflowLevel` | `0.8` | ≥ 0 (m) | threshold validator, control ramp foot | | `outflowLevel` | `basin.outflowLevel` | `0.2` | ≥ 0 (m) | dead-volume floor | -| `overflowLevel` | `basin.overflowLevel` | `2.5` | > 0 (m) | overfill safety | +| `overflowLevel` | `basin.overflowLevel` | `0.9` | > 0 (m) | overfill safety ceiling | | `controlMode` | `control.mode` | `levelbased` | enum | `control/dispatch` | -| `minLevel` | `control.levelbased.minLevel` | `1` | ≥ 0 (m) | `levelBased.run` | -| `startLevel` | `control.levelbased.startLevel` | `1` | ≥ minLevel | ramp foot | -| `maxLevel` | `control.levelbased.maxLevel` | `4` | ≤ overflowLevel | ramp top | -| `enableDryRunProtection` | `safety.enableDryRunProtection` | `true` | bool | `SafetyController` | -| `dryRunThresholdPercent` | `safety.dryRunThresholdPercent` | `2` | 0–100 % | dry-run trip | -| `enableOverfillProtection` | `safety.enableOverfillProtection` | `true` | bool | overfill safety | -| `overfillThresholdPercent` | `safety.overfillThresholdPercent` | `98` | 0–100 % | overfill trip | +| `levelCurveType` | `control.levelbased.curveType` | `linear` | `linear` \| `log` | `levelBased.run` | +| `logCurveFactor` | `control.levelbased.logCurveFactor` | `9` | > 0 | log-curve steepness | +| `enableShiftedRamp` | `control.levelbased.enableShiftedRamp` | `false` | bool | hysteresis ramp | +| `startLevel` | `control.levelbased.startLevel` | `null` | ≥ 0 (m) | ramp zero-point | +| `stopLevel` | `control.levelbased.stopLevel` | `null` | ≥ 0 (m) | Schmitt-trigger off threshold | +| `minLevel` | `control.levelbased.minLevel` | `null` | ≥ 0 (m) | `levelBased.run` | +| `maxLevel` | `control.levelbased.maxLevel` | `null` | ≤ overflowLevel (m) | ramp 100 % point | +| `flowSetpoint` | `control.flowbased.setpoint` | `null` | ≥ 0 (m³/h) | flow-PID target | +| `enableDryRunProtection` | `safety.enableDryRunProtection` | `true` | bool | `SafetyController._dryRunRule` | +| `dryRunThresholdPercent` | `safety.dryRunThresholdPercent` | `2` | 0–100 % | dry-run trip volume | +| `enableHighVolumeSafety` | `safety.enableHighVolumeSafety` | `true` | bool | `SafetyController._overfillRule` | +| `highVolumeSafetyThresholdPercent` | `safety.highVolumeSafetyThresholdPercent` | `98` | 0–100 % | overfill trip volume | +| `timeleftToFullOrEmptyThresholdSeconds` | `safety.timeleftToFullOrEmptyThresholdSeconds` | `0` | ≥ 0 (s) | ETA-based pre-trip guard | + +> `enableOverfillProtection` and `overfillThresholdPercent` are **deprecated aliases** still accepted by `SafetyController` for back-compat. Use `enableHighVolumeSafety` and `highVolumeSafetyThresholdPercent` in new flows. See `OPEN_QUESTIONS.md` (B1.2 resolved). ## 10. State chart -Two orthogonal state vectors: **control mode** (operator-driven) and **safety state** (data-driven). The diagram shows them together — most transitions are independent. +pumpingStation has two orthogonal state vectors: **control mode** (operator-driven, persistent) and **safety state** (data-driven, evaluated every tick). The e-stop path is the no-volume-data panic that shuts all machines independently. ```mermaid stateDiagram-v2 state ControlMode { - [*] --> none - none --> levelbased: set.mode - levelbased --> flowbased: set.mode - flowbased --> manual: set.mode - manual --> levelbased: set.mode - levelbased --> none: set.mode + [*] --> levelbased + levelbased --> flowbased : set.mode + flowbased --> manual : set.mode + manual --> levelbased : set.mode + manual --> none : set.mode + levelbased --> none : set.mode + none --> levelbased : set.mode } + state SafetyState { [*] --> nominal - nominal --> dryRun: vol < minVol AND draining - nominal --> overfill: vol > overfillThreshold AND filling - dryRun --> nominal: vol ≥ minVol - overfill --> nominal: vol ≤ overfillThreshold + nominal --> dryRun : vol < minVol AND draining + nominal --> overfill : vol > highVolThreshold AND filling + nominal --> panic : no volume reading + dryRun --> nominal : vol ≥ minVol + overfill --> nominal : vol ≤ highVolThreshold + panic --> nominal : volume reading restored } ``` -While the safety state is `dryRun`, control dispatch is **skipped** entirely. While `overfill`, control still runs (pumps must keep draining) but upstream equipment is shut down. +| Safety state | `blocked` | Control dispatch | Side-effects | +|---|---|---|---| +| `nominal` | false | runs normally | — | +| `dryRun` | **true** | **skipped** | downstream machines + machineGroups shut down | +| `overfill` | false | runs (pumps must drain) | upstream machines + child stations shut down | +| `panic` | **true** | **skipped** | **ALL** machines shut down | + +`dryRun` is triggered when `direction='draining'` AND vol < `minVol × (1 + dryRunThresholdPercent/100)`. +`overfill` is triggered when `direction='filling'` AND vol > `maxVolAtOverflow × (highVolumeSafetyThresholdPercent/100)`. ## 11. Examples -Example flows live under `examples/` in the repo. The structured tier-1/2/3 flows for this node are still in progress; until they land, the standalone simulator demo is the only runnable artefact. +All three tiers are written and runnable. Import any file via the Node-RED editor or the Admin API. | Tier | File | What it shows | Status | |---|---|---|---| -| Basic | `examples/01-Basic.flow.json` | Inject + dashboard, single basin, no parent | ⏳ TBD | -| Integration | `examples/02-Integration.flow.json` | pumpingStation + MGC + 2 pumps + measurement children | ⏳ TBD | -| Dashboard | `examples/03-Dashboard.flow.json` | Live FlowFuse charts (level, net flow, ETA) | ⏳ TBD | -| Headless | `examples/standalone-demo.js` | Node.js-only simulator, no Node-RED | ✅ in repo | +| Basic | `examples/01-Basic.json` | Single pumpingStation driven by inject nodes — no parent, no dashboard. Try `set.inflow`, `set.mode`, `cmd.calibrate.volume`. | ✅ | +| Integration | `examples/02-Integration.json` | pumpingStation + `machineGroupControl` + 2 `rotatingMachine` pumps + level `measurement`. Demonstrates Phase-2 parent/child handshake and `levelbased` control driving real pumps. | ✅ | +| Dashboard | `examples/03-Dashboard.json` | Tier 2 plumbing + FlowFuse Dashboard 2.0 page — 3 charts (flow / level / volume %), mode dropdown, demand slider. | ✅ | +| Headless | `examples/standalone-demo.js` | Node.js-only simulator, no Node-RED required. | ✅ | + +See `examples/README.md` for layout conventions (link channels, lane positions, group boxes). ## 12. Debug recipes | Symptom | First thing to check | Where to look | |---|---|---| -| Status badge stuck on `❔ 0.0%` | Did any volume / level measurement register? Watch Port 2 + first-child event. | Editor debug tap on Port 2 + `_subscribeMeasurement` log line. | -| `direction` always `steady` | Net flow inside `general.flowThreshold` dead-band (default 0.0001 m³/s). | `flowAggregator.deriveDirection`. | -| `set.demand` ignored | Mode isn't `manual`. Check `set.mode` history. | `handlers.setDemand` debug log. | -| Predicted volume drifts off measured | Calibration needed — fire `cmd.calibrate.volume` with a known reading. | `measurement/calibration.js`. | -| Pumps don't stop on dry-run | `safety.enableDryRunProtection` must be `true` AND the orchestrator must see `direction='draining'`. | `SafetyController.evaluate`. | -| Threshold-ordering warnings on startup | `validateThresholdOrdering` printed `inflowLevel < overflowLevel` style violations. | `basin/thresholdValidator.js`. | +| Status badge stuck on `❔ 0.0%` | No volume/level measurement registered yet. Watch Port 2. | Editor debug tap on Port 2 + `_subscribeMeasurement` log line. | +| `direction` always `steady` | Net flow inside `general.flowThreshold` dead-band (default 0.0001 m³/s ≈ 0.36 m³/h). | `flowAggregator.deriveDirection`. | +| `set.demand` ignored | Mode isn't `manual`. Confirm with `set.mode=manual` first. | `handlers.setDemand` debug log. | +| Predicted volume drifts off measured | Integrator needs a calibration anchor. Fire `cmd.calibrate.volume` with a known basin volume. | `measurement/calibration.js`. | +| Pumps don't stop on dry-run | `safety.enableDryRunProtection` must be `true` AND `direction` must be `'draining'`. | `SafetyController._dryRunRule`. | +| Threshold-ordering warnings on startup | `validateThresholdOrdering` detected violations (e.g. `inflowLevel > overflowLevel`). | `basin/thresholdValidator.js`. | +| All machines shut down immediately | No volume reading reached the node — panic path in SafetyController. Check child registration sequence. | `SafetyController.evaluate` line 59. | > Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors. Use only for live debugging. ## 13. When you would NOT use this node -- Use pumpingStation for a **wet-well basin** that needs orchestrated drainage. For a single pump with no basin model, use `rotatingMachine` directly. -- Don't use pumpingStation to schedule a fixed pump rota — its modes are reactive (level / flow / manual). Use an external scheduler if you need a calendar-driven schedule. -- Skip pumpingStation if you don't need predicted volume / time-to-full. A bare `machineGroupControl` is lighter when the upstream basin is modelled elsewhere. +- Use `rotatingMachine` directly for a single pump with no basin model. pumpingStation adds overhead that pays off only when you need predicted volume, time-to-full, or multi-pump orchestration. +- Don't use pumpingStation to schedule a fixed pump rota. Its control modes are reactive (level / flow / manual demand), not calendar-driven. Use an external scheduler and wire it in via `set.demand`. +- Skip pumpingStation if you only need flow or pressure measurements with no wet-well state. A bare `machineGroupControl` is lighter when the basin is modelled elsewhere or not at all. ## 14. Known limitations / current issues | # | Issue | Tracked in | |---|---|---| -| 1 | Cascaded `pumpingstation` children accepted but not exercised in production — semantics of nested stations are not test-covered. | TBD | -| 2 | `pressureBased`, `percentageBased`, `powerBased`, and `hybrid` are in the config enum but not implemented as control strategies. | `control/index.js` — only `levelbased` / `flowbased` / `manual` dispatched. | -| 3 | Predicted-volume integrator can drift over long horizons without a measured-level calibration source. | `cmd.calibrate.volume` is operator-triggered, not automatic. | -| 4 | Tier 1/2/3 example flows not yet written — current `examples/` only contains the standalone simulator. | P2.14 (Docker E2E) + P9 wiki cleanup. | +| 1 | Cascaded `pumpingstation` children accepted but semantics of nested stations are not test-covered in production scenarios. | TBD — exercise in Docker E2E before promoting. | +| 2 | `pressureBased`, `percentageBased`, `powerBased`, and `hybrid` are listed in the config enum but not dispatched — only `levelbased`, `flowbased`, `manual` are implemented. | `control/index.js` | +| 3 | Predicted-volume integrator drifts over long horizons without a measured-level calibration source. `cmd.calibrate.volume` is operator-triggered, not automatic. | Operator procedure; auto-calibration from level sensor is future work. | +| 4 | `enableOverfillProtection` / `overfillThresholdPercent` deprecated aliases still accepted by `SafetyController` (back-compat). Remove after one release cycle. | B1.2 resolved in `OPEN_QUESTIONS.md`. |