Files

znetsixe 8507ee4e02 wiki: split per-node Home into Zone A (intuitive) + Reference-* siblings

New standard, pilot pass for pumpingStation. Sets the pattern the other
10 nodes will follow once we sign off on this one.

Zone A (wiki/Home.md, ~180 lines):
- one-sentence opener
- "at a glance" 5-row fact table
- "How it looks in Node-RED" — screenshot placeholder
- "What it models" — embeds the existing basin-model.drawio.svg
- "Try it" — 3-minute demo with curl-load command, click list,
  GIF placeholder
- "Typical wiring" — two placeholder screenshots (standalone +
  integrated), no mermaid (per user direction)
- "The five things you'll send" + sample Port-0 payload table
- "Need more?" footer linking to Reference-* siblings

Zone B (4 sibling pages):
- Reference-Contracts.md  — full topic contract + data model
  (AUTOGEN markers); config schema; child registration filters;
  unit policy
- Reference-Architecture.md — 3-tier code layout; safety FSM
  (stateDiagram-v2); tick lifecycle (sequenceDiagram); output ports
- Reference-Examples.md — 01-Basic / 02-Integration / 03-Dashboard
  walk-through with per-example screenshot + GIF placeholders;
  debug-recipes table
- Reference-Limitations.md — implemented vs schema-only modes;
  basin-shape constraint; net-flow source caveat; alias-removal map

Asset directory placeholders created:
- wiki/_partial-screenshots/pumpingStation/.gitkeep
- wiki/_partial-gifs/pumpingStation/.gitkeep
- wiki/_partial-flows/pumpingStation/.gitkeep

Abandoned per user direction (no longer linked, removed from source):
- wiki/README.md
- wiki/functional-description.md (377 lines retired)
- wiki/modes/*.md (5 files retired)

Diagrams kept in place (wiki/diagrams/*.drawio.svg) — referenced from
Home and Reference-Architecture.

package.json: wiki:contract + wiki:datamodel now target
Reference-Contracts.md instead of Home.md.

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

2026-05-12 09:19:48 +02:00

4.3 KiB

Raw Blame History

Reference — Limitations

Note

What pumpingStation does not do, current rough edges, and open questions tracked against the refactor. Live source for the open items: .claude/refactor/OPEN_QUESTIONS.md in the EVOLV superproject.

When you would not use this node

Scenario	Use instead
Pressurised distribution network without a basin	Cascade pumpingStations, or a `valveGroupControl` parented to a flow source
Single pump, no basin, no level sensor	Parent a `rotatingMachine` directly under a UI driver
Air manifold (compressor + valves)	A future `compressorStation` — not implemented
Open-channel flow without a wet-well	Out of scope for the current basin model (rectangular prismatic only)
Sludge thickening basin	Use a `settler` — different settling-velocity model required

Known limitations

Implemented modes vs schema modes

The schema's control.mode enum lists eight modes, but only two are implemented in code:

Mode	Status	Notes
`levelbased`	Implemented	Default; the most production-tested path
`manual`	Implemented	Operator's `set.demand` is forwarded unchanged
`flowbased`	Placeholder	Schema accepts it; runtime falls back to levelbased
`pressureBased`	Placeholder	Same as above
`percentageBased`	Placeholder	Same as above
`powerBased`	Placeholder	Same as above
`hybrid`	Placeholder	Same as above
`mpc`	Not in code	Reserved name

If you select an unimplemented mode in the editor, the basin runs but the controller stays in level-based. Tracked.

Basin shape

Only rectangular prismatic basins are supported. Cylindrical, frusto-conical, or stepped basins would need a new BasinGeometry implementation. The volume = level * surfaceArea relationship is hard-wired.

Net-flow source selection

When both an MGC parent and direct rotatingMachine children are wired, the station subscribes only to the MGC's predicted flow. If you intentionally have MGC + extra individual pumps, the extras are invisible to the volume integrator. The router protects against double-counting but does not warn about this edge case.

Aliases not yet removed

The following legacy aliases still work but log a deprecation warning on first use. They are scheduled for removal in Phase 7:

Canonical	Legacy alias
`set.mode`	`changemode`
`set.inflow`	`q_in`
`set.outflow`	`q_out`
`set.demand`	`Qd`
`cmd.calibrate.volume`	`calibratePredictedVolume`
`cmd.calibrate.level`	`calibratePredictedLevel`
`child.register`	`registerChild`

Update integrations now.

Open questions (tracked)

Pulled from .claude/refactor/OPEN_QUESTIONS.md. Last reviewed on the date in the badge above.

Question	Where it lives
`overfillVol` alias drop — same shape as the already-done `overfillLevel` drop	OPEN_QUESTIONS.md (pumpingStation entry)
Net-flow source warning when multiple aggregators are wired	Internal — not yet ticketed
Cylindrical basin geometry	Internal — not yet ticketed
Docker E2E sign-off (P2.14)	OPEN_QUESTIONS.md (Phase 6)

Migration notes

From pre-refactor

Pre-refactor	Now
`enableOverfillProtection`	`enableHighVolumeSafety`
`overfillThresholdPercent`	`highVolumeSafetyThresholdPercent`
Legacy topics (`changemode`, `q_in`, ...)	Canonical topics (see Reference — Contracts for the alias map)
`basic.flow.json` (legacy)	`01-Basic.json` (canonical-topic version)

Renamed safety thresholds

The safety layer used to expose threshold fields named overfill*. Those names suggested the layer prevents overflow specifically; in practice the rule handles high-volume conditions more broadly (high level + low inflow / outflow imbalance). The current names (highVolumeSafety*) reflect that.

Page	Why
Home	Intuitive overview
Reference — Contracts	Topic + config + child filters (alias map at the end)
Reference — Architecture	Code map, state chart
Reference — Examples	Shipped flows

4.3 KiB Raw Blame History