8507ee4e02
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>
105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
# 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](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.
|
|
|
|
---
|
|
|
|
## Related pages
|
|
|
|
| Page | Why |
|
|
|:---|:---|
|
|
| [Home](Home) | Intuitive overview |
|
|
| [Reference — Contracts](Reference-Contracts) | Topic + config + child filters (alias map at the end) |
|
|
| [Reference — Architecture](Reference-Architecture) | Code map, state chart |
|
|
| [Reference — Examples](Reference-Examples) | Shipped flows |
|