6e89e4916f
Re-adds the "GIF needed" callouts in Home.md and Reference-Examples.md so the missing media is tracked instead of a broken image link. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
148 lines
6.7 KiB
Markdown
148 lines
6.7 KiB
Markdown
# Reference — Examples
|
||
|
||
|
||
|
||
> [!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 — 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 → 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 — Basic standalone
|
||
|
||
|
||
|
||
### Nodes on the tab
|
||
|
||
| Type | Purpose |
|
||
|:---|:---|
|
||
| `comment` | Tab header / instructions |
|
||
| `inject` × 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` × 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` — 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` — 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 — 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` × 7 (Controls group) | Replace the inject buttons one-for-one — each carries the canonical `msg.topic` directly |
|
||
| `ui-text` × 7 (Status group) | Live readouts: Mode, Direction, Level, Volume, Volume %, percControl, Manual demand |
|
||
| `ui-chart` × 4 (Trends group) | Level (m), Volume (m³), Volume % (0–100), Flow (m³/h, multi-series Inflow / Outflow / Net) |
|
||
| `ui-template` (Raw output group) | Full key/value table of the latest Port 0 cache — 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 — 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` — Status panel level / volume / vol% rise; the Level / Volume / Flow charts plot the trends.
|
||
4. In manual mode click `Demand 40 m³/h` — `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, …).
|
||
|
||
> [!IMPORTANT]
|
||
> **GIF needed.** Capture clicking through Mode → Inflow → Demand and the charts reacting. 20–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` — 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 — Contracts](Reference-Contracts) | Topic + config + child filters |
|
||
| [Reference — Architecture](Reference-Architecture) | Code map, state chart, lifecycle |
|
||
| [Reference — Limitations](Reference-Limitations) | Known limitations and open questions |
|
||
| [EVOLV — Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where this node fits in a larger plant |
|