pumpingStation/examples/README.md

# pumpingStation - Example Flows

Node-RED flows demonstrating the Phase-2 pumpingStation node on the
canonical topic API (`set.mode`, `set.inflow`, `set.outflow`, `set.demand`,
`cmd.calibrate.volume`, `cmd.calibrate.level`). Legacy aliases
(`changemode`, `q_in`, `q_out`, `Qd`, `calibratePredictedVolume`,
`calibratePredictedLevel`, `registerChild`) still work but log a
one-time deprecation warning; these fresh flows use the canonical names only.

## Files

| File | Tier | Tabs | Purpose |
|---|---|---|---|
| `01-Basic.json` | 1 | Process Plant | Single pumpingStation driven by inject nodes - no parent, no dashboard. |
| `02-Dashboard.json` | 2 | Process Plant + Dashboard UI | Same command surface as Basic, but driven by FlowFuse Dashboard 2.0 widgets — `ui-button` controls + `ui-text` live status panel. |

## Prerequisites

- Node-RED with the EVOLV package installed (so the `pumpingStation`,
  `measurement`, `machineGroupControl`, and `rotatingMachine` node
  types are registered).
- For `02-Dashboard.json`: `@flowfuse/node-red-dashboard` (Dashboard 2.0).

## How to load

```bash
# Drop a file into a running Node-RED instance using its Admin API.
curl -X POST -H 'Content-Type: application/json' \
  --data @nodes/pumpingStation/examples/01-Basic.json \
  http://localhost:1880/flows
```

Or in the editor: **Menu -> Import -> select file -> Import**. The flows
import into their own tabs and can be deployed immediately.

## 01-Basic - what to try

1. Deploy.
2. Inject `set.mode = manual`.
3. Inject `set.inflow = 60 m3/h` - the basin starts filling. Watch the
   formatted Port 0 payload in the debug sidebar.
4. Inject `set.demand = 40 %` - in manual mode this would feed any
   registered children; here there are no pump children so it is logged
   and shown on Port 0.
5. Inject `cmd.calibrate.volume = 25 m3` to jump the predicted-volume
   integrator to half-full.

## 02-Dashboard - what to try

1. Deploy.
2. Open the dashboard at `http://localhost:1880/dashboard/pumpingstation-basic`.
3. Click **Mode: Manual** or **Mode: Levelbased** in the Controls panel.
4. Click **Inflow 60 m³/h** to push wastewater into the basin — the Status
   panel on the right shows level / volume / volume % rising.
5. In manual mode, click **Demand 40 m³/h** — the value surfaces as
   `Manual demand` in the Status panel and in the node's status badge.
6. Use **Calibrate V = 25 m³** or **Calibrate L = 1.5 m** to snap the
   predicted-volume integrator.

All buttons fire the same canonical `msg.topic` as the Basic flow's inject
nodes; the only difference is the trigger. The Live status panel is fed by
Port 0 via a small fan-out function that caches last-known values so
delta-only updates never blank a row.

## Layout conventions

These flows follow the EVOLV layout rule set in
`.claude/rules/node-red-flow-layout.md`:

- Tabs split by **concern**: Process Plant (EVOLV nodes) / Dashboard UI
  (`ui-*` widgets) / Setup (once-true injects).
- Cross-tab wiring via **named link out / link in channels**:
  `setup:to-ps-mode`, `setup:to-ps-inflow`, `setup:to-mgc-mode`,
  `cmd:ps-mode`, `cmd:ps-demand`, `evt:flow`, `evt:level`,
  `evt:volpct`, `evt:state`, `evt:perc`, `evt:dir`, `evt:tempty`.
- **Lane positions** L0-L7 = `[120, 360, 600, 840, 1080, 1320, 1560, 1800]`,
  driven by each node's S88 level (Process Cell on L5, Unit on L4,
  Equipment on L3, Control Module on L2).
- **Group boxes** wrap each parent + its direct children, coloured by the
  parent's S88 level.

## Regenerating

The current example JSON files are hand-maintained. If you re-introduce a
generator, regenerate `01-Basic.json` and `02-Dashboard.json` from it
rather than editing the JSON directly.