examples/README.md

# EVOLV — End-to-End Example Flows

Demo flows that show how multiple EVOLV nodes work together in a realistic wastewater-automation scenario. Each example is self-contained: its folder has a `flow.json` you can import directly into Node-RED plus a `README.md` that walks through the topology, control modes, and dashboard layout.

These flows complement the per-node example flows under `nodes/<name>/examples/` (which exercise a single node in isolation). Use the per-node flows for smoke tests during development; use the flows here when you want to see how a real plant section behaves end-to-end.

## Catalogue

| Folder | What it shows |
|---|---|
| [`pumpingstation-3pumps-dashboard/`](pumpingstation-3pumps-dashboard/) | Wet-well basin + machineGroupControl orchestrating 3 pumps (each with up/downstream pressure measurements), individual + auto control, process-demand input via dashboard slider or random generator, full FlowFuse dashboard. |

## How to import

1. Bring up the EVOLV stack: `docker compose up -d` from the superproject root.
2. Open Node-RED at `http://localhost:1880`.
3. Menu → **Import** → drop in the example's `flow.json` (or paste the contents).
4. Open the FlowFuse dashboard at `http://localhost:1880/dashboard`.

Each example uses a unique dashboard `path` so they can coexist in the same Node-RED runtime.

## Adding new examples

When you create a new end-to-end example:

1. Make a subfolder under `examples/` named `<scenario>-<focus>`.
2. Include `flow.json` (Node-RED export) and `README.md` (topology, control modes, dashboard map, things to try).
3. Test it on a fresh Dockerized Node-RED — clean import, no errors, dashboard loads.
4. Add a row to the catalogue table above.

## Wishlist for future examples

These are scenarios worth building when there's a session for it:

- **Pump failure + MGC re-routing** — kill pump 2 mid-run, watch MGC redistribute to pumps 1 and 3.
- **Energy-optimal vs equal-flow control** — same demand profile run through `optimalcontrol` and `prioritycontrol` modes side-by-side, energy comparison chart.
- **Schedule-driven demand** — diurnal flow pattern (low at night, peak at 7 am), MGC auto-tuning over 24 simulated hours.
- **Reactor + clarifier loop** — `reactor` upstream feeding `settler`, return sludge controlled by a small `pumpingStation`.
- **Diffuser + DO control** — aeration grid driven by a PID controller from a dissolved-oxygen sensor.
- **Digital sensor bundle** — MQTT-style sensor (BME280, ATAS, etc.) feeding a `measurement` node in digital mode + parent equipment node.
- **Maintenance window** — entermaintenance / exitmaintenance cycle with operator handover dashboard.
- **Calibration walk-through** — measurement node calibrate cycle with stable / unstable input demonstrations.
feat(examples): pumpingstation-3pumps-dashboard end-to-end demo + bump generalFunctions New top-level examples/ folder for end-to-end demos that show how multiple EVOLV nodes work together (complementing the per-node example flows under nodes/<name>/examples/). Future end-to-end demos will live as siblings. First demo: pumpingstation-3pumps-dashboard - 1 pumpingStation (basin model, manual mode for the demo so it observes rather than auto-shutting pumps; safety guards disabled — see README) - 1 machineGroupControl (optimalcontrol mode, absolute scaling) - 3 rotatingMachine pumps (hidrostal-H05K-S03R curve) - 6 measurement nodes (per pump: upstream + downstream pressure mbar, simulator mode for continuous activity) - Process demand input via dashboard slider (0-300 m3/h) AND auto random generator (3s tick, [40, 240] m3/h) — both feed PS q_in + MGC Qd - Auto/Manual mode toggle (broadcasts setMode to all 3 pumps) - Station-wide Start / Stop / Emergency-Stop buttons - Per-pump setpoint slider, individual buttons, full status text - Two trend charts (flow per pump, power per pump) - FlowFuse dashboard at /dashboard/pumping-station-demo build_flow.py is the source of truth — it generates flow.json deterministically and is the right place to extend the demo. Bumps: nodes/generalFunctions 43f6906 -> 29b78a3 Fix: childRegistrationUtils now aliases the production softwareType values (rotatingmachine, machinegroupcontrol) to the dispatch keys parent nodes check for (machine, machinegroup). Without this, MGC <-> rotatingMachine and pumpingStation <-> MGC wiring silently never matched in production even though tests passed. Demo confirms: MGC reports '3 machine(s) connected'. Verified end-to-end on Dockerized Node-RED 2026-04-13: pumps reach operational ~5s after deploy, MGC distributes random demand across them, basin tracks net flow direction, all dashboard widgets update each second. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> 2026-04-13 15:53:47 +02:00			`# EVOLV — End-to-End Example Flows`

			Demo flows that show how multiple EVOLV nodes work together in a realistic wastewater-automation scenario. Each example is self-contained: its folder has a `flow.json` you can import directly into Node-RED plus a `README.md` that walks through the topology, control modes, and dashboard layout.

			These flows complement the per-node example flows under `nodes/<name>/examples/` (which exercise a single node in isolation). Use the per-node flows for smoke tests during development; use the flows here when you want to see how a real plant section behaves end-to-end.

			`## Catalogue`

			`\| Folder \| What it shows \|`
			`\|---\|---\|`
			\| [`pumpingstation-3pumps-dashboard/`](pumpingstation-3pumps-dashboard/) \| Wet-well basin + machineGroupControl orchestrating 3 pumps (each with up/downstream pressure measurements), individual + auto control, process-demand input via dashboard slider or random generator, full FlowFuse dashboard. \|

			`## How to import`

			1. Bring up the EVOLV stack: `docker compose up -d` from the superproject root.
			2. Open Node-RED at `http://localhost:1880`.
			3. Menu → Import → drop in the example's `flow.json` (or paste the contents).
			4. Open the FlowFuse dashboard at `http://localhost:1880/dashboard`.

			Each example uses a unique dashboard `path` so they can coexist in the same Node-RED runtime.

			`## Adding new examples`

			`When you create a new end-to-end example:`

			1. Make a subfolder under `examples/` named `<scenario>-<focus>`.
			2. Include `flow.json` (Node-RED export) and `README.md` (topology, control modes, dashboard map, things to try).
			`3. Test it on a fresh Dockerized Node-RED — clean import, no errors, dashboard loads.`
			`4. Add a row to the catalogue table above.`

			`## Wishlist for future examples`

			`These are scenarios worth building when there's a session for it:`

			`- Pump failure + MGC re-routing — kill pump 2 mid-run, watch MGC redistribute to pumps 1 and 3.`
			- Energy-optimal vs equal-flow control — same demand profile run through `optimalcontrol` and `prioritycontrol` modes side-by-side, energy comparison chart.
			`- Schedule-driven demand — diurnal flow pattern (low at night, peak at 7 am), MGC auto-tuning over 24 simulated hours.`
			- Reactor + clarifier loop — `reactor` upstream feeding `settler`, return sludge controlled by a small `pumpingStation`.
			`- Diffuser + DO control — aeration grid driven by a PID controller from a dissolved-oxygen sensor.`
			- Digital sensor bundle — MQTT-style sensor (BME280, ATAS, etc.) feeding a `measurement` node in digital mode + parent equipment node.
			`- Maintenance window — entermaintenance / exitmaintenance cycle with operator handover dashboard.`
			`- Calibration walk-through — measurement node calibrate cycle with stable / unstable input demonstrations.`