diff --git a/wiki/Home.md b/wiki/Home.md index f25a8c2..b6e2cb3 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -1,21 +1,23 @@ # valveGroupControl -> **Reflects code as of `e02cd1a` · regenerated `2026-05-11` via `npm run wiki:all`** +> **Reflects code as of `ef34c82` · 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 -**valveGroupControl** (VGC) is an S88 Unit that distributes a group-level flow target across registered `valve` children proportional to their current Kv, aggregates the per-valve accepted flow back into a group total, and surfaces the maximum delta-P across the group. It also reconciles each child's fluid-contract advertisement into a single group-level service-type view. +**valveGroupControl** (VGC) is an S88 Unit coordinator for a group of `valve` children. It distributes a group-level flow target across registered valves proportional to their Kv rating, runs a residual-reconciliation pass to absorb per-valve acceptance limits, aggregates group max delta-P, and reconciles upstream fluid-contract advertisements into a single group-level service-type view. ## 2. Position in the platform ```mermaid flowchart LR src[machine / MGC / PS
upstream source]:::unit -.flow.predicted.-> vgc[valveGroupControl
Unit]:::unit - vgc -->|set.position| v1[valve A]:::equip - vgc -->|set.position| v2[valve B]:::equip - v1 -->|evt.deltaPChange| vgc - v2 -->|evt.deltaPChange| vgc + vgc -->|updateFlow predicted| v1[valve A]:::equip + vgc -->|updateFlow predicted| v2[valve B]:::equip + v1 -->|positionChange| vgc + v2 -->|positionChange| vgc + v1 -->|deltaPChange| vgc + v2 -->|deltaPChange| vgc vgc -->|child.register| parent[upstream parent]:::unit classDef unit fill:#50a8d9,color:#000 classDef equip fill:#86bbdd,color:#000 @@ -28,13 +30,15 @@ S88 colours: Unit `#50a8d9`, Equipment `#86bbdd`. Source of truth: `.claude/rule | Capability | Status | Notes | |---|---|---| | Proportional flow distribution by Kv | ✅ | `groupOps/flowDistribution.js`. | -| Two-pass residual reconciliation | ✅ | `maxPasses: 2`, `residualTolerance: 0.001`. | -| Periodic tick re-balance | ✅ | Runs each adapter tick; `set.reconcileInterval` re-tunes. | -| Group `maxDeltaP` aggregation | ✅ | Recomputed on any child `deltaPChange`. | -| Upstream fluid-contract aggregation | ✅ | `sources/fluidContract.js`. | -| Sequence dispatch to all valves | ✅ | `cmd.execSequence` → per-valve `handleInput`. | -| Per-valve positional override | ❌ | `set.position` reserved; no-op in current build. | -| Multi-source aggregation | ✅ | Multiple machines / MGCs may register as sources. | +| Two-pass residual reconciliation | ✅ | Default `maxPasses: 2`, `residualTolerance: 0.001`. | +| Periodic tick re-balance | ✅ | `tick()` calls `calcValveFlows()`; `set.reconcileInterval` re-tunes interval. | +| Group `maxDeltaP` aggregation | ✅ | Recomputed on any child `deltaPChange` event. | +| Upstream fluid-contract aggregation | ✅ | `sources/fluidContract.js`; emits `fluidContractChange`. | +| Group-wide sequence dispatch | ✅ | `cmd.execSequence` → `executeSequence` → per-state `transitionToState`. | +| Emergency stop | ✅ | `cmd.emergencyStop` → `emergencystop` sequence on all valves. | +| Per-valve positional override | ⚠️ | `set.position` is a debug-logged **no-op** pending Phase 7. See §14. | +| Multi-source aggregation | ✅ | Multiple machines / MGCs / PSs may register as upstream sources. | +| Cascaded VGC as upstream source | ⚠️ | Accepted by router but not exercised in production; test coverage absent. | ## 4. Code map @@ -44,13 +48,13 @@ flowchart TB nc["buildDomainConfig()
static DomainClass, commands"] end subgraph domain["specificClass.js — orchestrator (BaseDomain)"] - sc["ValveGroupControl.configure()
registerChild dispatch
tick → calcValveFlows"] + sc["ValveGroupControl.configure()
router.onRegister: valve + sources
tick() → calcValveFlows()"] end subgraph concerns["src/ concern modules"] - gops["groupOps/
flowDistribution"] - srcs["sources/
fluidContract"] + gops["groupOps/
flowDistribution + calcMaxDeltaP"] + srcs["sources/
fluidContract registration"] cmds["commands/
topic registry + handlers"] - io["io/
output + status badge"] + io["io/
getOutput + getStatusBadge"] end nc --> sc sc --> gops @@ -61,15 +65,17 @@ flowchart TB | Module | Owns | Read first if you're changing… | |---|---|---| -| `groupOps/` | Flow distribution, residual solver, max-deltaP aggregation | How the group divides flow. | -| `sources/` | Upstream-source registration, fluid-contract reconciliation | Service-type aggregation, source-event subscriptions. | -| `commands/` | Input-topic registry + per-topic handlers | New input topics, payload validation. | -| `io/` | Port-0 output shape + status badge | What lands on the wire. | +| `groupOps/` | Kv-share solver, residual pass, max-deltaP aggregation | How the group divides flow between valves. | +| `sources/` | Upstream-source registration, flow-event subscription, fluid-contract reconciliation | Service-type aggregation, source event wiring. | +| `commands/` | Input-topic registry + per-topic handlers | New input topics or payload validation rules. | +| `io/` | Port-0 output shape + status badge composition | What lands on the wire, badge text. | ## 5. Topic contract > **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`. +The **Unit** column reflects the descriptor's `units: { measure, default }` declaration, rendered as ` (default )`. Topics without a `units` field show `—`. The **Effect** column is sourced from the descriptor's `description` field. + | Canonical topic | Aliases | Payload | Unit | Effect | @@ -92,9 +98,9 @@ flowchart LR v["valve"]:::equip src["machine / rotatingmachine /
machinegroup / pumpingstation /
valvegroupcontrol"]:::unit end - v -->|positionChange| handler1[onPositionChange
calcValveFlows] - v -->|deltaPChange| handler2[onDeltaPChange
calcMaxDeltaP] - src -->|flow.predicted.*| handler3[updateFlow
at atEquipment] + v -->|positionChange| handler1[onPositionChange
→ calcValveFlows] + v -->|deltaPChange| handler2[onDeltaPChange
→ calcMaxDeltaP] + src -->|flow.predicted.*
flow.measured.*| handler3[updateFlow
atEquipment] src -->|fluidContractChange| handler4[sources.refresh
aggregate contract] classDef equip fill:#86bbdd,color:#000 classDef unit fill:#50a8d9,color:#000 @@ -102,11 +108,11 @@ flowchart LR | softwareType | onRegister side-effect | Subscribed events | |---|---|---| -| `valve` | Stored in `this.valves[id]`; binds `positionChange` + `deltaPChange`; triggers `calcValveFlows` + `calcMaxDeltaP`. | `positionChange`, `deltaPChange`. | -| `machine` / `rotatingmachine` | Stored as upstream source; reads `getFluidContract()` (or default `liquid`). | `flow.predicted.*`, `flow.measured.*`, `fluidContractChange`. | +| `valve` | Stored in `this.valves[id]`; binds `positionChange` (via `child.state.emitter`) + `deltaPChange` (via `child.emitter`); triggers `calcValveFlows` + `calcMaxDeltaP`. | `positionChange`, `deltaPChange`. | +| `machine` / `rotatingmachine` | Stored as upstream source; reads `getFluidContract()` or infers `liquid` by default. | `flow.predicted.*`, `flow.measured.*`, `fluidContractChange`. | | `machinegroup` / `machinegroupcontrol` | Same as machine. | Same as machine. | | `pumpingstation` | Same as machine. | Same as machine. | -| `valvegroupcontrol` | Allowed for cascaded VGCs; not exercised in production. | Same. | +| `valvegroupcontrol` | Cascaded VGC; accepted by router. Not exercised in production. | Same as machine. | ## 7. Lifecycle — what one tick / event does @@ -118,46 +124,22 @@ sequenceDiagram participant v2 as valve B participant out as Port-0 - src->>vgc: flow.predicted.downstream (m3/s) - vgc->>vgc: _write flow.predicted.atEquipment + src->>vgc: flow.predicted.downstream (m³/h) + vgc->>vgc: updateFlow('predicted', value, 'atEquipment') vgc->>vgc: calcValveFlows() - Note over vgc: solveFlowDistribution
(by Kv share) + Note over vgc: solveFlowDistribution
by Kv share (≤ maxPasses) vgc->>v1: updateFlow('predicted', shareA, 'downstream') vgc->>v2: updateFlow('predicted', shareB, 'downstream') - v1-->>vgc: accepted flow + deltaPChange - v2-->>vgc: accepted flow + deltaPChange - vgc->>vgc: residual pass (up to maxPasses) + v1-->>vgc: positionChange / deltaPChange + v2-->>vgc: positionChange / deltaPChange vgc->>vgc: calcMaxDeltaP - vgc->>out: msg{topic, payload (delta-compressed)} -``` - -## 11. Distribution loop — flow-share solver - -VGC has no FSM. The loop below replaces the state chart for this section. - -```mermaid -sequenceDiagram - participant tick as adapter tick / event - participant vgc as VGC - participant solver as solveFlowDistribution - participant valves as valve children - - tick->>vgc: calcValveFlows() - vgc->>vgc: read flow.measured / predicted .atEquipment - vgc->>solver: target=totalFlow, entries=availableValves - loop ≤ maxPasses while |residual| > tolerance - solver->>valves: updateFlow share by (Kv / totalKv) - valves-->>solver: accepted flow back - solver->>solver: residual = target - sum(accepted) - end - solver-->>vgc: { flowsById, residual, passes } - vgc->>vgc: write flow.predicted.atEquipment = assignedTotal vgc->>vgc: notifyOutputChanged() + vgc->>out: msg{topic, payload (delta-compressed)} ``` ## 8. Data model — `getOutput()` -What lands on Port 0. Composed in `io/output`, then delta-compressed by `outputUtils.formatMsg`. +What lands on Port 0. Composed in `io/output.getOutput()`, then delta-compressed by `outputUtils.formatMsg`. @@ -168,75 +150,111 @@ What lands on Port 0. Composed in `io/output`, then delta-compressed by `outputU -Measurement-derived keys follow the `__` shape (e.g. `atEquipment_predicted_flow`) and are emitted only when the container holds a finite value. +Measurement-derived keys follow the `__` shape and are emitted only when the container holds a finite value. + +| Example key | Unit | Description | +|---|---|---| +| `atEquipment_predicted_flow` | m³/h | Total group predicted flow (sum of per-valve assigned flows). | +| `atEquipment_measured_flow` | m³/h | Total group measured flow (from upstream source). | +| `deltaMax_predicted_pressure` | mbar | Max delta-P across registered valves. | + +> Delta compression: only changed fields are sent per tick. Consumers must cache and merge. See `outputUtils.formatMsg`. ## 9. Configuration — editor form ↔ config keys ```mermaid flowchart TB - subgraph editor["Node-RED editor form"] - f1[Mode] - f2[Sequences] - f3[Allowed sources per mode] - f4[Reconciliation interval] + subgraph editor["Node-RED editor form (vgc.html)"] + f1[Name] + f2[Process output format] + f3[Database output format] + f4[Position vs parent] + f5[Logger / log level] end - subgraph config["Domain config slice"] - c1[mode.current] - c2[sequences.] - c3[mode.allowedSources.] - c4[flowReconciliation (runtime)] + subgraph config["Domain config (runtime / schema)"] + c1[general.name] + c2[output.process] + c3[output.dbase] + c4[functionality.positionVsParent] + c5[logging.enableLog / logLevel] end f1 --> c1 f2 --> c2 f3 --> c3 f4 --> c4 + f5 --> c5 ``` -| Form field | Config key | Default | Range | Where used | -|---|---|---|---|---| -| Mode | `mode.current` | per schema | enum | `setMode` | -| Sequences | `sequences.` | per schema | Set of state names | `executeSequence` | -| Allowed sources | `mode.allowedSources.` | per schema | Set of source ids | `isValidSourceForMode` | -| Reconcile maxPasses | `flowReconciliation.maxPasses` | `2` | ≥ 1 | `solveFlowDistribution` | -| Reconcile tolerance | `flowReconciliation.residualTolerance` | `0.001` | ≥ 0 | `solveFlowDistribution` | -| Reconcile interval | (runtime, via `set.reconcileInterval`) | adapter default | ≥ 100 ms | `setReconcileIntervalSeconds` | +| Form field | Config key | Default | Where used | +|---|---|---|---| +| Name | `general.name` | `""` | Node label, InfluxDB tag, status badge. | +| Process output format | `output.process` | `"process"` | `outputUtils.formatMsg` Port-0 formatter. | +| Database output format | `output.dbase` | `"influxdb"` | `outputUtils.formatMsg` Port-1 formatter. | +| Position vs parent | `functionality.positionVsParent` | `""` | Child registration Port-2 message; read by upstream parent. | +| Enable log / log level | `logging.enableLog`, `logging.logLevel` | `false` / `"error"` | Logger verbosity. Never ship `debug` in demos. | -## 10. State chart +> Domain-level config (`mode.current`, `sequences`, `mode.allowedSources`, `flowReconciliation`) is loaded from the node's schema defaults and updated at runtime via `set.mode` / `set.reconcileInterval`. These fields are not exposed in the editor form. -Skipped — VGC has no FSM of its own. State semantics belong to the child valves; VGC is a coordinator. See section 11 for the flow-distribution loop. +## 10. Flow-distribution loop (replaces state chart) + +VGC has no FSM of its own — state semantics belong to the child valves. The core coordination loop is the Kv-share solver described below. + +```mermaid +sequenceDiagram + participant tick as adapter tick / incoming event + participant vgc as VGC + participant solver as solveFlowDistribution + participant valves as valve children + + tick->>vgc: calcValveFlows() + vgc->>vgc: read flow.measured (or predicted) .atEquipment + vgc->>solver: target=totalFlow, entries=availableValves + loop ≤ maxPasses while |residual| > tolerance + solver->>valves: updateFlow share by (Kv / totalKv) + valves-->>solver: accepted flow (read back from child.measurements) + solver->>solver: residual = target − sum(accepted) + end + solver-->>vgc: { flowsById, residual, passes } + vgc->>vgc: write flow.predicted.atEquipment = assignedTotal + vgc->>vgc: calcMaxDeltaP() + vgc->>vgc: notifyOutputChanged() +``` + +A valve is **available** if: `state ≠ off|maintenance`, `mode ≠ maintenance`, and `kv > 0`. Unavailable valves receive `updateFlow('predicted', 0)` and are excluded from the solver. ## 11. Examples | Tier | File | What it shows | Mandatory? | |---|---|---|---| -| Basic | `examples/01-Basic.flow.json` | Inject `data.totalFlow` + 2 valves + dashboard | ✅ | -| Integration | `examples/02-Integration.flow.json` | VGC + valves + upstream rotatingMachine | ✅ | -| Dashboard | `examples/03-Dashboard.flow.json` | Live FlowFuse charts (per-valve flow, max ΔP) | ⭕ | +| Basic | `examples/basic.flow.json` | Inject `data.totalFlow` + 2 valves (no parent) | ✅ | +| Integration | `examples/integration.flow.json` | VGC + valves + upstream rotatingMachine | ✅ | +| Edge | `examples/edge.flow.json` | Edge cases: no valves, residual non-convergence, cascaded VGC | ⭕ | -Screenshots under `wiki/_partial-screenshots/valveGroupControl/` when produced. Docker compose snippet under `examples/README.md`. +Tier-1 / Tier-2 / Tier-3 naming scheme pending when existing flows are validated on live Node-RED. Screenshots under `wiki/_partial-screenshots/valveGroupControl/` when produced. ## 12. Debug recipes | Symptom | First thing to check | Where to look | |---|---|---| -| All valves show `assigned flow = 0` | `getAvailableValves()` empty; check Kv > 0 and state ≠ `off` / `maintenance`. | `groupOps/flowDistribution.isValveAvailable` | -| Residual never converges | `flowReconciliation.maxPasses` too low for the valve curve shape. | `lastFlowSolve.residual` | -| Group `maxDeltaP` stale | Child `deltaPChange` not subscribed; valve emitter not exposed. | `_bindValveEvents` | -| Service-type stays `unknown` | No source registered yet or all sources advertise unknown. | `sources.refreshFluidContract` | -| `data.totalFlow` ignored | Mode rejects the source; check `mode.allowedSources`. | `isValidSourceForMode` | +| All valves receive `assigned flow = 0` | `getAvailableValves()` returns empty list; check Kv > 0 and child state ≠ `off` / `maintenance`. | `groupOps/flowDistribution.isValveAvailable` | +| Residual never converges | `flowReconciliation.maxPasses` too low for valve curve shape; check `lastFlowSolve.residual`. | `groupOps/flowDistribution.js` | +| Group `maxDeltaP` stale | Child `deltaPChange` not subscribed; valve emitter not exposed via `child.emitter`. | `specificClass._bindValveEvents` | +| Service-type stays `unknown` | No upstream source registered, or all advertise unknown type. | `sources/fluidContract.refreshFluidContract` | +| `data.totalFlow` silently ignored | Mode rejects the source id; check `mode.allowedSources` for the current mode. | `specificClass.isValidSourceForMode` | +| `set.position` has no effect | Known limitation — handler is a no-op. See §14. | `commands/handlers.setPosition` | > 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 VGC for **2+ parallel valves** sharing a header. For a single valve, wire `valve` directly under the upstream parent. -- Don't use VGC to coordinate series valves — the flow-distribution model assumes parallel branches with a shared upstream pressure. -- Skip VGC when the upstream source already publishes per-branch flow setpoints; route those straight to each valve. +- Use `valve` directly when you have a **single** valve under an upstream parent. VGC adds coordination overhead for no benefit with one child. +- Do NOT use VGC to coordinate **series** valves — the Kv-share solver assumes parallel branches sharing a common header pressure. +- Skip VGC when the upstream source already publishes **per-branch flow setpoints**; route those directly to each valve instead. ## 14. Known limitations / current issues | # | Issue | Tracked in | |---|---|---| -| 1 | `set.position` is reserved but currently a no-op — per-valve override is pending Phase 7. | CONTRACT.md `## Inputs` | -| 2 | Residual solver assumes Kv share is a good first estimate; pathological curves can need more passes than the default `2`. | `groupOps/flowDistribution.js` | -| 3 | Cascaded `valvegroupcontrol` registration accepted but not test-covered. | CONTRACT.md `## Children` | +| 1 | `set.position` is a debug-logged **no-op** — per-valve positional override is reserved, pending Phase 7 topic standardisation of valve setpoint payloads. The handler in `commands/handlers.setPosition` intentionally does nothing. | `CONTRACT.md §Inputs`; `OPEN_QUESTIONS.md` Phase 7 | +| 2 | Residual solver assumes Kv share is a valid first estimate. Pathological valve curves (e.g. very non-linear Kv vs position) may need more passes than the default `maxPasses: 2` to reach `residualTolerance`. | `groupOps/flowDistribution.js` | +| 3 | Cascaded `valvegroupcontrol` registration (VGC as upstream source of another VGC) is accepted by the router but has no test coverage and is not exercised in production. | `CONTRACT.md §Children` |