docs(wiki): full 5-page wiki matching the rotatingMachine reference format
Replaces the prior stub/partial wiki with a Home + Reference-{Architecture,
Contracts,Examples,Limitations} + _Sidebar structure. Topic-contract and
data-model sections wrapped in AUTOGEN markers for the future wiki-gen tool.
Source-vs-spec contradictions surfaced and flagged inline (not silently
fixed). Pending-review notes mark sections that need a full node review.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
339
wiki/Home.md
339
wiki/Home.md
@@ -1,260 +1,153 @@
|
||||
# valveGroupControl
|
||||
|
||||
> **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
|
||||
A `valveGroupControl` (VGC) coordinates a group of `valve` children that share a common manifold — selector-valve banks, dosing-valve trains, mixing manifolds. It accepts a group-level total flow target, splits the flow proportional to each valve's Kv rating, runs a residual-reconciliation pass against what every valve actually accepted, and aggregates max delta-P across the group. It also reconciles upstream-source fluid-contract advertisements (`liquid` / `gas`) into one group-level service-type view that downstream consumers can read.
|
||||
|
||||
**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.
|
||||
> [!NOTE]
|
||||
> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
|
||||
|
||||
## 2. Position in the platform
|
||||
---
|
||||
|
||||
## At a glance
|
||||
|
||||
| Thing | Value |
|
||||
|:---|:---|
|
||||
| What it represents | A parallel valve manifold — 2 + valves sharing a header, distributing one total flow target |
|
||||
| S88 level | Unit |
|
||||
| Use it when | You have 2 + parallel valves that should share an upstream flow target proportional to their Kv |
|
||||
| Don't use it for | A single valve (wire `valve` directly), series valves (the Kv-share solver assumes parallel branches), or a manifold whose upstream already publishes per-branch setpoints |
|
||||
| Children it accepts | `valve` (group members) + upstream sources (`machine` / `rotatingmachine` / `machinegroup` / `machinegroupcontrol` / `pumpingstation` / `valvegroupcontrol`) |
|
||||
| Parents it talks to | Any upstream node — typically `pumpingStation`, `reactor`, or another VGC; VGC registers via Port 2 |
|
||||
|
||||
---
|
||||
|
||||
## How it fits
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
src[machine / MGC / PS<br/>upstream source]:::unit -.flow.predicted.-> vgc[valveGroupControl<br/>Unit]:::unit
|
||||
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
|
||||
src[machine / MGC /<br/>pumpingStation<br/>upstream source]:::unit -.flow.predicted.*.-> vgc[valveGroupControl<br/>Unit]:::unit
|
||||
vgc -->|updateFlow predicted<br/>downstream| v1[valve A]:::equip
|
||||
vgc -->|updateFlow predicted<br/>downstream| v2[valve B]:::equip
|
||||
v1 -->|positionChange<br/>deltaPChange| vgc
|
||||
v2 -->|positionChange<br/>deltaPChange| vgc
|
||||
vgc -->|child.register| parent[upstream parent]:::pc
|
||||
classDef pc fill:#0c99d9,color:#fff
|
||||
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`.
|
||||
S88 colours are anchored in `.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 | ✅ | 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. |
|
||||
## Try it — 3-minute demo
|
||||
|
||||
## 4. Code map
|
||||
Import the basic example flow, deploy, and drive a 2-valve group with an injected total-flow setpoint.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"]
|
||||
nc["buildDomainConfig()<br/>static DomainClass, commands"]
|
||||
end
|
||||
subgraph domain["specificClass.js — orchestrator (BaseDomain)"]
|
||||
sc["ValveGroupControl.configure()<br/>router.onRegister: valve + sources<br/>tick() → calcValveFlows()"]
|
||||
end
|
||||
subgraph concerns["src/ concern modules"]
|
||||
gops["groupOps/<br/>flowDistribution + calcMaxDeltaP"]
|
||||
srcs["sources/<br/>fluidContract registration"]
|
||||
cmds["commands/<br/>topic registry + handlers"]
|
||||
io["io/<br/>getOutput + getStatusBadge"]
|
||||
end
|
||||
nc --> sc
|
||||
sc --> gops
|
||||
sc --> srcs
|
||||
sc --> io
|
||||
nc --> cmds
|
||||
```bash
|
||||
curl -X POST -H 'Content-Type: application/json' \
|
||||
--data @nodes/valveGroupControl/examples/basic.flow.json \
|
||||
http://localhost:1880/flow
|
||||
```
|
||||
|
||||
| Module | Owns | Read first if you're changing… |
|
||||
|---|---|---|
|
||||
| `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. |
|
||||
What to click after deploy (the inject buttons map to canonical topics in [Reference — Contracts](Reference-Contracts#topic-contract)):
|
||||
|
||||
## 5. Topic contract
|
||||
1. `child.register` for each `valve` — or rely on Port-2 wiring to auto-register.
|
||||
2. `set.mode = auto` — lets the parent source drive the group.
|
||||
3. `data.totalFlow = 80` (with `unit: 'm3/h'`) — VGC splits 80 m³/h across the available valves by Kv share; runs up to `maxPasses: 2` residual passes; writes back `atEquipment_predicted_flow` = sum of accepted per-valve flows.
|
||||
4. `cmd.execSequence` with `{action: "startup"}` — runs the group-wide startup sequence through `executeSequence`, transitioning the group state machine through each step.
|
||||
5. `cmd.emergencyStop` — runs the `emergencystop` sequence on all valves (`[emergencystop, off]`).
|
||||
6. `set.reconcileInterval = 2` — re-tunes the periodic tick to 2 s (`reconcileIntervalChange` event triggers the adapter to restart its tick loop; minimum 100 ms).
|
||||
|
||||
> **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`.
|
||||
> [!IMPORTANT]
|
||||
> **GIF needed.** Demo recording of steps 1–6 with the live status panel. Save as `wiki/_partial-gifs/valveGroupControl/01-basic-demo.gif`, target ≤ 1 MB after `gifsicle -O3 --lossy=80`.
|
||||
|
||||
The **Unit** column reflects the descriptor's `units: { measure, default }` declaration, rendered as `<measure> (default <unit>)`. Topics without a `units` field show `—`. The **Effect** column is sourced from the descriptor's `description` field.
|
||||
---
|
||||
|
||||
<!-- BEGIN AUTOGEN: topic-contract -->
|
||||
## The seven things you'll send
|
||||
|
||||
| Canonical topic | Aliases | Payload | Unit | Effect |
|
||||
|---|---|---|---|---|
|
||||
| `set.mode` | `setMode` | `string` | — | Switch the valve group between auto / manual control modes. |
|
||||
| `set.position` | `setpoint` | `any` | — | Set the group-level valve position (currently a no-op pending Phase 7). |
|
||||
| `child.register` | `registerChild` | `string` | — | Register a child valve with this group. |
|
||||
| `cmd.execSequence` | `execSequence` | `object` | — | Run a group-wide sequence (startup / shutdown / emergencystop). |
|
||||
| `data.totalFlow` | `totalFlowChange` | `any` | — | Notify the group that the total flow setpoint has changed. |
|
||||
| `cmd.emergencyStop` | `emergencyStop`, `emergencystop` | `any` | — | Trigger an emergency stop across all valves in the group. |
|
||||
| `set.reconcileInterval` | `setReconcileInterval` | `any` | — | Update the reconciliation interval (seconds). |
|
||||
| Topic | Aliases | Payload | What it does |
|
||||
|:---|:---|:---|:---|
|
||||
| `set.mode` | `setMode` | `"auto"` \| `"virtualControl"` \| `"fysicalControl"` \| `"maintenance"` | Switch operational mode. Each mode has its own allow-list of sources (`mode.allowedSources`). |
|
||||
| `set.position` | `setpoint` | any | **No-op pending Phase 7.** Reserved for future per-valve positional override. Debug-logged only. |
|
||||
| `child.register` | `registerChild` | `string` (child node id) | Manually register a child via `RED.nodes.getNode`; Port 2 wiring does this automatically in most flows. |
|
||||
| `cmd.execSequence` | `execSequence` | `{ source, action, parameter }` | Forward to `source.handleInput(source, action, parameter)` — runs a group-wide sequence (`startup` / `shutdown` / `emergencystop` / `boot`). |
|
||||
| `data.totalFlow` | `totalFlowChange` | number, `{ value, position?, variant?, unit? }`, or `{ source, action, ... }` | Update the total measured/predicted flow at the configured position; triggers `calcValveFlows` to re-distribute across valves. |
|
||||
| `cmd.emergencyStop` | `emergencyStop`, `emergencystop` | optional `{ source }` | Run the `emergencystop` sequence on all valves. |
|
||||
| `set.reconcileInterval` | `setReconcileInterval` | number — seconds (> 0) | Re-tune the periodic flow-reconciliation interval. Min clamp 100 ms. |
|
||||
|
||||
<!-- END AUTOGEN: topic-contract -->
|
||||
Aliases log a one-time deprecation warning the first time they fire.
|
||||
|
||||
## 6. Child registration
|
||||
---
|
||||
|
||||
## What you'll see come out
|
||||
|
||||
Sample Port 0 message (delta-compressed, after a `data.totalFlow = 80` split across two valves):
|
||||
|
||||
```json
|
||||
{
|
||||
"topic": "valveGroupControl#VGC1",
|
||||
"payload": {
|
||||
"mode": "auto",
|
||||
"maxDeltaP": 1450,
|
||||
"atEquipment_measured_flow": 80,
|
||||
"atEquipment_predicted_flow": 80,
|
||||
"deltaMax_predicted_pressure": 1450
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Key shape: **`<position>_<variant>_<type>`** — same as MGC's key shape (inverse of `rotatingMachine`'s per-measurement form). The output reflects the group aggregate, not per-valve snapshots; per-valve detail comes off each valve's own Port 0.
|
||||
|
||||
| Field | Meaning |
|
||||
|:---|:---|
|
||||
| `mode` | Current operational mode (`auto` / `virtualControl` / `fysicalControl` / `maintenance`). |
|
||||
| `maxDeltaP` | Max delta-P across registered valves — refreshed whenever a child emits `deltaPChange`. Also surfaced as `deltaMax_predicted_pressure` via the measurement container. |
|
||||
| `atEquipment_measured_flow` | Total measured flow at the group inlet (from an upstream source's `flow.measured.*` event). |
|
||||
| `atEquipment_predicted_flow` | Sum of per-valve accepted flows after the Kv-share + residual pass. |
|
||||
| `deltaMax_predicted_pressure` | Max delta-P across the group, written via the measurement container at position `delta` / variant `predicted` / type `pressure`. |
|
||||
|
||||
---
|
||||
|
||||
## Flow-distribution loop — what one event does
|
||||
|
||||
When a `data.totalFlow` arrives (or an upstream source publishes `flow.predicted.*` / `flow.measured.*`), VGC re-distributes by Kv share:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph kids["accepted children (softwareType)"]
|
||||
v["valve"]:::equip
|
||||
src["machine / rotatingmachine /<br/>machinegroup / pumpingstation /<br/>valvegroupcontrol"]:::unit
|
||||
end
|
||||
v -->|positionChange| handler1[onPositionChange<br/>→ calcValveFlows]
|
||||
v -->|deltaPChange| handler2[onDeltaPChange<br/>→ calcMaxDeltaP]
|
||||
src -->|flow.predicted.*<br/>flow.measured.*| handler3[updateFlow<br/>atEquipment]
|
||||
src -->|fluidContractChange| handler4[sources.refresh<br/>aggregate contract]
|
||||
classDef equip fill:#86bbdd,color:#000
|
||||
classDef unit fill:#50a8d9,color:#000
|
||||
src[data.totalFlow /<br/>upstream source event] --> upd[updateFlow<br/>predicted/measured atEquipment]
|
||||
upd --> avail[getAvailableValves<br/>state ≠ off/maintenance, kv > 0]
|
||||
avail --> solve[solveFlowDistribution<br/>share by Kv / totalKv]
|
||||
solve --> push[valve.updateFlow predicted<br/>downstream]
|
||||
push --> readback[read accepted from<br/>flow.predicted.downstream]
|
||||
readback --> residual[residual = target − sum(accepted)]
|
||||
residual -->|residual > tol & passes < max| solve
|
||||
residual --> writeback[write flow.predicted.atEquipment<br/>= sum(accepted)]
|
||||
writeback --> dp[calcMaxDeltaP]
|
||||
dp --> emit[notifyOutputChanged]
|
||||
```
|
||||
|
||||
| softwareType | onRegister side-effect | Subscribed events |
|
||||
|---|---|---|
|
||||
| `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` | Cascaded VGC; accepted by router. Not exercised in production. | Same as machine. |
|
||||
Reconciliation defaults (`flowReconciliation`):
|
||||
|
||||
## 7. Lifecycle — what one tick / event does
|
||||
| Field | Default | Notes |
|
||||
|:---|:---:|:---|
|
||||
| `maxPasses` | `2` | Max iterations of the residual-correction loop. |
|
||||
| `residualTolerance` | `0.001` | Stops the loop when `|residual| <` tolerance (canonical units — m³/s for flow). |
|
||||
|
||||
```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
|
||||
A valve is **available** if: `state.getCurrentState() !== 'off'` and `!== 'maintenance'`, `currentMode !== 'maintenance'`, and `kv > 0`. Unavailable valves are skipped and receive `updateFlow('predicted', 0, 'downstream')`.
|
||||
|
||||
src->>vgc: flow.predicted.downstream (m³/h)
|
||||
vgc->>vgc: updateFlow('predicted', value, 'atEquipment')
|
||||
vgc->>vgc: calcValveFlows()
|
||||
Note over vgc: solveFlowDistribution<br/>by Kv share (≤ maxPasses)
|
||||
vgc->>v1: updateFlow('predicted', shareA, 'downstream')
|
||||
vgc->>v2: updateFlow('predicted', shareB, 'downstream')
|
||||
v1-->>vgc: positionChange / deltaPChange
|
||||
v2-->>vgc: positionChange / deltaPChange
|
||||
vgc->>vgc: calcMaxDeltaP
|
||||
vgc->>vgc: notifyOutputChanged()
|
||||
vgc->>out: msg{topic, payload (delta-compressed)}
|
||||
```
|
||||
VGC has **no FSM of its own** — state semantics belong to the child valves. `specificClass` instantiates a state object internally and stamps it `operational` at boot for sequence dispatch; the group's only coordination loop is the Kv-share solver above.
|
||||
|
||||
## 8. Data model — `getOutput()`
|
||||
---
|
||||
|
||||
What lands on Port 0. Composed in `io/output.getOutput()`, then delta-compressed by `outputUtils.formatMsg`.
|
||||
## Need more?
|
||||
|
||||
<!-- BEGIN AUTOGEN: data-model -->
|
||||
| Page | What you'll find |
|
||||
|:---|:---|
|
||||
| [Reference — Contracts](Reference-Contracts) | Topic registry, config schema, child-registration filters |
|
||||
| [Reference — Architecture](Reference-Architecture) | Code map, flow-distribution loop, source aggregation, output ports |
|
||||
| [Reference — Examples](Reference-Examples) | Shipped flows, debug recipes |
|
||||
| [Reference — Limitations](Reference-Limitations) | When not to use, known issues, open questions |
|
||||
|
||||
| Key | Type | Unit | Sample |
|
||||
|---|---|---|---|
|
||||
| `maxDeltaP` | number | — | `0` |
|
||||
| `mode` | string | — | `"auto"` |
|
||||
|
||||
<!-- END AUTOGEN: data-model -->
|
||||
|
||||
Measurement-derived keys follow the `<position>_<variant>_<type>` 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 (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 (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 | 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. |
|
||||
|
||||
> 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.
|
||||
|
||||
## 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/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 | ⭕ |
|
||||
|
||||
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 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 `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 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` |
|
||||
[EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home) · [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) · [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions)
|
||||
|
||||
Reference in New Issue
Block a user