From c44d5959ad0836bcd88d998e6b6c969689a16758 Mon Sep 17 00:00:00 2001 From: znetsixe Date: Mon, 11 May 2026 15:17:39 +0200 Subject: [PATCH] P9.3: wiki/Home.md following 14-section visual-first template + wiki:* scripts Auto-generated topic-contract + data-model sections via shared wikiGen script. Hand-written Mermaid diagrams for position-in-platform, code map, child registration, lifecycle, configuration, state chart (where applicable). Co-Authored-By: Claude Opus 4.7 (1M context) --- package.json | 5 +- wiki/Home.md | 242 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 246 insertions(+), 1 deletion(-) create mode 100644 wiki/Home.md diff --git a/package.json b/package.json index 82efacf..82f8ece 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,10 @@ "description": "Valve group control module", "main": "valveGroupControl.js", "scripts": { - "test": "node --test test/basic/*.test.js test/integration/*.test.js test/edge/*.test.js" + "test": "node --test test/basic/*.test.js test/integration/*.test.js test/edge/*.test.js", + "wiki:contract": "node ../generalFunctions/scripts/wikiGen.js contract ./src/commands/index.js --write ./wiki/Home.md", + "wiki:datamodel": "node ../generalFunctions/scripts/wikiGen.js datamodel ./src/specificClass.js --write ./wiki/Home.md", + "wiki:all": "npm run wiki:contract && npm run wiki:datamodel" }, "repository": { "type": "git", diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 0000000..e23c809 --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,242 @@ +# valveGroupControl + +> **Reflects code as of `e02cd1a` · 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. + +## 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 -->|child.register| parent[upstream parent]:::unit + classDef unit fill:#50a8d9,color:#000 + classDef equip fill:#86bbdd,color:#000 +``` + +S88 colours: Unit `#50a8d9`, Equipment `#86bbdd`. Source of truth: `.claude/rules/node-red-flow-layout.md`. + +## 3. Capability matrix + +| 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. | + +## 4. Code map + +```mermaid +flowchart TB + subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"] + nc["buildDomainConfig()
static DomainClass, commands"] + end + subgraph domain["specificClass.js — orchestrator (BaseDomain)"] + sc["ValveGroupControl.configure()
registerChild dispatch
tick → calcValveFlows"] + end + subgraph concerns["src/ concern modules"] + gops["groupOps/
flowDistribution"] + srcs["sources/
fluidContract"] + cmds["commands/
topic registry + handlers"] + io["io/
output + status badge"] + end + nc --> sc + sc --> gops + sc --> srcs + sc --> io + nc --> cmds +``` + +| 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. | + +## 5. Topic contract + +> **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`. + + + +| Canonical topic | Aliases | Payload | Effect | +|---|---|---|---| +| `set.mode` | `setMode` | `string` | Replaces the named state value with the supplied payload. | +| `set.position` | `setpoint` | `any` | Replaces the named state value with the supplied payload. | +| `child.register` | `registerChild` | `string` | Parent/child plumbing — registers or unregisters a child node. | +| `cmd.execSequence` | `execSequence` | `object` | Triggers an action / sequence — not idempotent. | +| `data.totalFlow` | `totalFlowChange` | `any` | Pushes a value into the node's measurement stream. | +| `cmd.emergencyStop` | `emergencyStop`, `emergencystop` | `any` | Triggers an action / sequence — not idempotent. | +| `set.reconcileInterval` | `setReconcileInterval` | `any` | Replaces the named state value with the supplied payload. | + + + +## 6. Child registration + +```mermaid +flowchart LR + subgraph kids["accepted children (softwareType)"] + 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] + src -->|fluidContractChange| handler4[sources.refresh
aggregate contract] + classDef equip fill:#86bbdd,color:#000 + classDef unit fill:#50a8d9,color:#000 +``` + +| 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`. | +| `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. | + +## 7. Lifecycle — what one tick / event does + +```mermaid +sequenceDiagram + participant src as upstream source + participant vgc as VGC + participant v1 as valve A + participant v2 as valve B + participant out as Port-0 + + src->>vgc: flow.predicted.downstream (m3/s) + vgc->>vgc: _write flow.predicted.atEquipment + vgc->>vgc: calcValveFlows() + Note over vgc: solveFlowDistribution
(by Kv share) + 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) + 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() +``` + +## 8. Data model — `getOutput()` + +What lands on Port 0. Composed in `io/output`, then delta-compressed by `outputUtils.formatMsg`. + + + +| Key | Type | Unit | Sample | +|---|---|---|---| +| `maxDeltaP` | number | — | `0` | +| `mode` | string | — | `"auto"` | + + + +Measurement-derived keys follow the `__` shape (e.g. `atEquipment_predicted_flow`) and are emitted only when the container holds a finite value. + +## 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] + end + subgraph config["Domain config slice"] + c1[mode.current] + c2[sequences.] + c3[mode.allowedSources.] + c4[flowReconciliation (runtime)] + end + f1 --> c1 + f2 --> c2 + f3 --> c3 + f4 --> c4 +``` + +| 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` | + +## 10. State chart + +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. + +## 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) | ⭕ | + +Screenshots under `wiki/_partial-screenshots/valveGroupControl/` when produced. Docker compose snippet under `examples/README.md`. + +## 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` | + +> 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. + +## 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` |