pumpingStation/wiki/Reference-Examples.md

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	Tabs	What it shows
examples/01-Basic.json	1	Process Plant	Single pumpingStation driven by inject nodes — 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 → Import.
3. Drag-and-drop the JSON file, or paste its contents.
4. Click Deploy.

Via the Admin API

curl -X POST -H 'Content-Type: application/json' \
  --data @nodes/pumpingStation/examples/01-Basic.json \
  http://localhost:1880/flow

---

Example 01 — 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 × 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 × 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 — for level-based, the controller decides demand from level).

Important

GIF needed. Record steps 1–4. Target 15–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 — 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 — 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–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:

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

---

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.
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	Intuitive overview
Reference — Contracts	Topic + config + child filters
Reference — Architecture	Code map, state chart, lifecycle
Reference — Limitations	Known limitations and open questions
EVOLV — Topology Patterns	Where this node fits in a larger plant