# 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 | What it shows |
|:---|:---:|:---|
| `examples/01-Basic.json` | 1 | Single pumpingStation driven by inject nodes &mdash; no parent, no dashboard. Numbered driver groups for Mode / Flow signals / Operator demand / Calibration. |
| `examples/02-Dashboard.json` | 2 | Same command surface as Basic, driven by a FlowFuse Dashboard 2.0 page (Controls + live Status rows + 4 trend charts + raw-output table). |

---

## 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

![Basic example flow in Node-RED editor](_partial-screenshots/pumpingStation/02-basic-flow.png)

### Nodes on the tab

| Type | Purpose |
|:---|:---|
| `comment` | Tab header / instructions |
| `inject` &times; 7 | Buttons to send `set.mode` (manual / levelbased), `set.inflow`, `set.outflow`, `set.demand`, `cmd.calibrate.volume`, `cmd.calibrate.level` |
| `pumpingStation` | The unit under test |
| `debug` &times; 3 | Port 0 (process), Port 1 (InfluxDB), Port 2 (parent reg) |

Driver injects are wrapped in four numbered groups: **1. Control mode**, **2. Flow signals (inflow / outflow)**, **3. Operator demand (manual mode only)**, **4. Calibration**. Debug nodes sit in a separate **Debug outputs (sidebar)** group on the right.

### What to do after deploy

1. (optional) Click `set.mode = manual` if you want `set.demand` to forward; otherwise leave it on the default `levelbased` and the ramp drives demand from level.
2. Click `set.inflow = 60 m³/h` &mdash; the basin starts filling. Watch Port 0 in the debug pane: `direction` flips to `filling`, `level` rises, predicted volume integrates.
3. In manual mode: click `set.demand = 40` &mdash; the value surfaces as `manualDemand` on Port 0/1 and in the node status badge.
4. Click `cmd.calibrate.volume = 25 m³` (or `cmd.calibrate.level = 1.5 m`) to snap the predicted-volume integrator.

> [!IMPORTANT]
> **GIF needed.** Demo recording of steps 1–4. Save as `wiki/_partial-gifs/pumpingStation/01-basic-demo.gif`, target ≤ 1 MB after `gifsicle -O3 --lossy=80`.

---

## Example 02 &mdash; Dashboard

> [!IMPORTANT]
> **Screenshot needed.** Two captures from `02-Dashboard.json`:
> 1. The editor tab (left controls column + pumpingStation + Live-status group on the right).
> 2. The rendered dashboard at `http://localhost:1880/dashboard/pumpingstation-basic`.
>
> Save as `wiki/_partial-screenshots/pumpingStation/05-ex02-editor.png` and `06-ex02-dashboard.png`.
> Replace this callout with both image links.

### What it adds vs Example 01

| Addition | Why |
|:---|:---|
| FlowFuse `ui-base` + `ui-theme` + `ui-page` setup | One dashboard page hosting four widget groups |
| `ui-button` &times; 7 (Controls group) | Replace the inject buttons one-for-one &mdash; each carries the canonical `msg.topic` directly |
| `ui-text` &times; 7 (Status group) | Live readouts: Mode, Direction, Level, Volume, Volume %, percControl, Manual demand |
| `ui-chart` &times; 4 (Trends group) | Level (m), Volume (m³), Volume % (0&ndash;100), Flow (m³/h, multi-series Inflow / Outflow / Net) |
| `ui-template` (Raw output group) | Full key/value table of the latest Port 0 cache &mdash; every field the node emits, sorted |
| Fan-out function | Caches last-known values so delta-only Port 0 updates never blank a status row, and forwards numeric values to the charts |

The buttons fire the **same canonical `msg.topic`** as the inject nodes in Example 01 &mdash; there is no separate dashboard command surface to learn.

Required: `@flowfuse/node-red-dashboard` (Dashboard 2.0) installed in the Node-RED instance.

### What to do after deploy

1. Open `http://localhost:1880/dashboard/pumpingstation-basic`.
2. Click `Mode: Manual` or `Mode: Levelbased`.
3. Click `Inflow 60 m³/h` &mdash; Status panel level / volume / vol% rise; the Level / Volume / Flow charts plot the trends.
4. In manual mode click `Demand 40 m³/h` &mdash; `Manual demand` row updates, node badge appends `Qd=40 m³/h`.
5. Inspect the **Raw output** table at the bottom of the page for the full Port 0 surface (basin geometry, dryRunLevel, highVolumeSafetyLevel, predictedOverflowVolume, &hellip;).

> [!IMPORTANT]
> **GIF needed.** Capture clicking through Mode &rarr; Inflow &rarr; Demand and the charts reacting. 20&ndash;30 s is enough.
>
> Save as `wiki/_partial-gifs/pumpingStation/02-ex02-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. |
| `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 |
