RnD/pumpingStation
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
znetsixe
2026-05-12 09:19:48 +02:00
parent b825ac1d6d
commit 8507ee4e02
17 changed files with 788 additions and 1150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
wiki/Reference-Examples.md Normal file
View File

@@ -0,0 +1,175 @@
# Reference &mdash; Examples
![code-ref](https://img.shields.io/badge/code--ref-b825ac1-blue)
> [!NOTE]
> Every example flow shipped under `nodes/pumpingStation/examples/`, plus how to load them, what they show, and the debug recipes that go with them. Live source: `nodes/pumpingStation/examples/`.
---
## Shipped examples
| File | Tier | Tabs | What it shows |
|:---|:---:|:---|:---|
| `examples/01-Basic.json` | 1 | Process Plant | Single pumpingStation driven by inject nodes &mdash; no parent, no dashboard. |
| `examples/02-Integration.json` | 2 | Process Plant + Setup | Adds a `measurement` level child and a `machineGroupControl` parent with two `rotatingMachine` pumps. Demonstrates the Phase-2 parent / child handshake. |
| `examples/03-Dashboard.json` | 3 | Process Plant + Dashboard + Setup | Tier-2 plumbing plus a FlowFuse Dashboard 2.0 page with 3 charts (flow / level / volume %), text widgets, and 2 controls (mode dropdown + demand slider). |
| `examples/basic-dashboard.flow.json` | legacy | mixed | Pre-refactor flow kept for reference. Use `03-Dashboard.json` instead. |
---
## Loading a flow
### Via the editor
1. Open the Node-RED editor at `http://localhost:1880`.
2. Menu &rarr; Import.
3. Drag-and-drop the JSON file, or paste its contents.
4. Click Deploy.
### Via the Admin API
```bash
curl -X POST -H 'Content-Type: application/json' \
--data @nodes/pumpingStation/examples/01-Basic.json \
http://localhost:1880/flow
```
---
## Example 01 &mdash; Basic standalone
> [!IMPORTANT]
> **Screenshot needed.** After importing `01-Basic.json`, capture the full Process Plant tab.
>
> Save as `wiki/_partial-screenshots/pumpingStation/05-ex01-basic.png`.
> Replace this callout with the image link.
### Nodes on the tab
| Type | Purpose |
|:---|:---|
| `comment` | Tab header / instructions |
| `inject` &times; 6 | Buttons to send `set.mode`, `set.inflow`, `set.demand`, `cmd.calibrate.volume`, `cmd.calibrate.level` |
| `pumpingStation` | The unit under test |
| `function` | Merge Port-0 deltas into a single rolling snapshot |
| `debug` &times; 3 | Port 0 (process), Port 1 (InfluxDB), Port 2 (parent reg) |
### What to do after deploy
1. Click `set.mode = levelbased`.
2. Click `cmd.calibrate.level = 1.5 m` to anchor the volume integrator.
3. Click `set.inflow = 60 m³/h`.
4. Watch the Port-0 debug pane: `direction` flips to `filling`, `level` rises, `demand` follows the level curve, `etaSeconds` decreases.
5. Click `set.demand = 40 %` (only honoured in manual mode &mdash; for level-based, the controller decides demand from level).
> [!IMPORTANT]
> **GIF needed.** Record steps 1&ndash;4. Target 15&ndash;25 s, ≤ 1 MB after `gifsicle -O3 --lossy=80`.
>
> Save as `wiki/_partial-gifs/pumpingStation/02-ex01-demo.gif`.
> Replace this callout with the image link.
---
## Example 02 &mdash; Integration with parent + children
> [!IMPORTANT]
> **Screenshot needed.** After importing `02-Integration.json`, capture the full Process Plant tab.
>
> Save as `wiki/_partial-screenshots/pumpingStation/06-ex02-integration.png`.
> Replace this callout with the image link.
### What it adds vs Example 01
| Addition | Why |
|:---|:---|
| `measurement` node feeding `level` | Replaces the inject-driven level path with a real measurement child |
| `machineGroupControl` (MGC) parent | Demand goes upward to the MGC instead of being applied directly |
| Two `rotatingMachine` pumps under the MGC | The MGC load-shares demand across them |
| `Setup` tab | Initial calibration injects fire once via `once: true` |
This exercises the Phase-2 parent / child handshake: `child.register` is sent on Port 2 of each child to its parent, and the parent's `commandRegistry` dispatches into `ChildRouter.onRegister(...)`.
### What to do after deploy
1. Setup tab fires once, calibrating volume and setting mode.
2. The MGC reports its predicted flow back to the pumpingStation.
3. Click any inject in the Process Plant tab to perturb the basin.
4. Watch all three Port-0 debug taps: PS, MGC, both pumps.
---
## Example 03 &mdash; Dashboard
> [!IMPORTANT]
> **Screenshot needed.** Two captures from `03-Dashboard.json`:
> 1. The editor tab (Dashboard UI) showing the dashboard widgets and trend-feeder functions.
> 2. The rendered dashboard at `http://localhost:1880/dashboard`.
>
> Save as `wiki/_partial-screenshots/pumpingStation/07-ex03-editor.png` and `08-ex03-dashboard.png`.
> Replace this callout with both image links.
### What it adds vs Example 02
| Addition | Why |
|:---|:---|
| FlowFuse ui-base + ui-page + ui-group setup | One page, multiple grouped widgets |
| 3 ui-chart widgets | flow / level / volume % trends |
| ui-text widgets | live mode, demand, direction display |
| ui-dropdown for mode | operator-facing mode switch |
| ui-slider for demand | manual setpoint |
| Trend-feeder function | splits Port-0 deltas into one msg per chart with `msg.topic` set as series label |
Required: `@flowfuse/node-red-dashboard` (Dashboard 2.0) installed in the Node-RED instance.
> [!IMPORTANT]
> **GIF needed.** Slide the demand control and watch the trend charts react. 20&ndash;30 s is enough.
>
> Save as `wiki/_partial-gifs/pumpingStation/03-ex03-dashboard.gif`.
> Replace this callout with the image link.
---
## Docker compose snippet
To bring up Node-RED + InfluxDB with EVOLV nodes pre-loaded:
```yaml
# docker-compose.yml (extract)
services:
nodered:
build: ./docker/nodered
ports: ['1880:1880']
volumes:
- ./docker/nodered/data:/data/evolv
influxdb:
image: influxdb:2.7
ports: ['8086:8086']
```
Full file: [EVOLV/docker-compose.yml](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/docker-compose.yml).
---
## Debug recipes
| Symptom | First thing to check |
|:---|:---|
| Status badge stuck on `no data` | Did the level `measurement` child register? Tap Port 2 of the measurement with a `debug` node and confirm a `child.register` msg fires once at init. |
| Level rises but `volume` stays at `minVol` | Volume integrator hasn't been calibrated. Send `cmd.calibrate.level = <real level>` once. |
| Demand stays at 0 % even though level is high | Mode might be `manual` &mdash; check `set.mode`. Or the safety layer is blocking (look at `safety.blocked` on Port 0). |
| Predicted volume drifts | Net-flow source is wrong. Look at `flowSource` on Port 0; it should match the highest-level aggregator you have wired in. |
| MGC and pumps don't see demand | `02-Integration.json` requires the MGC to register **before** the pumps. The Setup tab handles ordering. |
| `enableLog: 'debug'` floods the container log | Toggle it off in the node's config. Never ship a demo with debug logging enabled. |
---
## Related pages
| Page | Why |
|:---|:---|
| [Home](Home) | Intuitive overview |
| [Reference &mdash; Contracts](Reference-Contracts) | Topic + config + child filters |
| [Reference &mdash; Architecture](Reference-Architecture) | Code map, state chart, lifecycle |
| [Reference &mdash; Limitations](Reference-Limitations) | Known limitations and open questions |
| [EVOLV &mdash; Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where this node fits in a larger plant |