diffuser/wiki/Reference-Examples.md

Reference — Examples

Note

Pending full node review (2026-05). Example flows under nodes/diffuser/examples/ are at the legacy basic / integration / edge filename tier — they predate the rotatingMachine 01 - … numbered convention and have not yet been re-validated against the current src/commands/index.js topic registry. examples/README.md is a one-line placeholder.

---

Shipped examples

File	Tier	Dependencies	What it shows
examples/basic.flow.json	1 (legacy)	EVOLV only	Single-diffuser flow driven by inject buttons — setter topics for flow, density, water height, header pressure, elements, alpha factor. Debug taps on the process port.
examples/integration.flow.json	2 (legacy)	EVOLV (+ reactor if you wire one)	Diffuser auto-registers with a parent (Port 2 child.register).
examples/edge.flow.json	3 (legacy)	EVOLV only	Edge cases: flow = 0 idle reset, very large flow (alarm band), missing curve fallback to default.

Important

TODO — upgrade to numbered tier set. Mirror rotatingMachine's convention:

New file	Tier	Replaces
01 - Basic Manual Control.json	1	basic.flow.json
02 - Integration with Reactor.json	2	integration.flow.json
03 - Dashboard Visualization.json	3	(new, requires @flowfuse/node-red-dashboard)

Keep the legacy files until the new tier set has been Docker-validated. Then update examples/README.md to per-tier descriptions.

---

Loading a flow

Via the editor

1. Open the Node-RED editor at http://localhost:1880.
2. Menu → Import → drag the JSON file.
3. Click Deploy.

Via the Admin API

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

(Use /flows to bulk-deploy all tabs.)

---

Example — Basic Manual Control (legacy basic.flow.json)

Single-diffuser flow with one inject per setter topic.

What to do after deploy

1. Click set.water-height = 5 — 5 m column above the diffuser. oPLoss updates to reflect static head.
2. Click set.elements = 100 — 100 elements. oFlowElement and oFluxPerM2 denominators update.
3. Click set.density = 15 — 15 % bottom coverage, the default curve key.
4. Click set.header-pressure = 600 — 600 mbar gauge. Air-density correction kicks in; nFlow shifts from iFlow.
5. Click set.alfa-factor = 0.7 — the α correction. Influences oKgo2H only.
6. Click data.flow = 200 — the model engages. Watch Port 0 in the debug pane: oOtr, oKgo2H, oFluxPerM2, efficiency, slope all populate; idle flips from true to false.
7. Click data.flow = 0 — idle flips back; derived outputs reset to zero. oPLoss falls to just the static head.

Important

GIF needed. Demo recording of steps 1–7 with the status badge progression. Save as wiki/_partial-gifs/diffuser/01-basic-demo.gif, target ≤ 1 MB after gifsicle -O3 --lossy=80.

Try the alarm band

After steps 1–6 above the diffuser is at oFluxPerM2 ≈ 12 Nm³/(h·m²). Push it past the curve's maxX:

1. Set set.elements = 10 (one tenth of the previous).
2. With the same data.flow = 200, oFluxPerM2 jumps roughly tenfold. The _checkLimits band fires; alarm becomes a non-empty array and the status badge turns red.
3. Restore set.elements = 100 — alarm clears.

---

Example — Integration with Reactor (legacy integration.flow.json)

Important

Screenshot needed. Editor capture of integration.flow.json. Save as wiki/_partial-screenshots/diffuser/02-integration.png.

A diffuser wired to a parent reactor. Demonstrates:

• Auto-registration via Port 2 at deploy (the diffuser emits child.register with positionVsParent='atEquipment').
• Reactor consumes oZoneOtr from the diffuser's Port 0 (legacy reactor-control port has been merged into Port 0 in Phase 6).

Note

The reactor's side of this contract has not been verified against the latest reactor submodule in this audit. Reactor wiki: https://gitea.wbd-rd.nl/RnD/reactor/wiki/Home

---

Example — Edge Cases (legacy edge.flow.json)

Drives the diffuser through:

• data.flow = 0 → idle reset path.
• Very large data.flow → alarm band on oFluxPerM2.
• Asset model id pointing at an unknown curve → fallback to gva-elastox-r (no constructor crash).

---

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	Where to look
oOtr stays at 0	iFlow is zero or negative → idle = true. Push a positive value via data.flow.	_recalculate early-return path.
oZoneOtr is 0 even though oKgo2H > 0	diffuser.zoneVolume is unset or non-positive. Set it in the editor or via config.	getReactorOtr(zoneVolumeM3).
warning / alarm always firing	oFluxPerM2 is outside the loaded curve's [minX, maxX] band ± hysteresis. Either the flow is wildly off the asset's design point or the wrong curve is loaded.	_checkLimits, _loadSpecs.
nFlow does not equal iFlow	Air-density correction. Header pressure and atmospheric pressure deviate from the standard baseline (T=20 °C, p=1.01325 bar, RH=0).	_calcAirDensityMbar.
efficiency is flat at 0	OTR or ΔP curve span is zero in the operating band. Inspect the supplier curve.	_combineEff.
Constructor throws curve '…' is missing otr_curve/p_curve	The asset.model field references a curve id that exists in the registry but lacks one of the required curves. Pick a complete model in the editor.	_loadSpecs.
Editor palette colour wrong	diffuser.html already declares color: '#86bbdd' (Equipment Module). If a stale palette shows otherwise, hard-refresh the editor or check the Node-RED version.	diffuser.html.
Alias warns spammed every tick	A consumer is sending the legacy alias on every tick instead of the canonical topic. Aliases warn once per deploy — if you're seeing repeats, something is re-creating the node.	src/commands/index.js alias list.

Never ship enableLog: 'debug' in a demo — fills the container log within seconds and obscures real errors.

---

Related pages

Page	Why
Home	Intuitive overview
Reference — Contracts	Topic + config + child registration
Reference — Architecture	Code map, OTR / ΔP pipeline
Reference — Limitations	Known issues and open questions
reactor — Examples	Parent-side example flows
EVOLV — Topology Patterns	Where diffuser fits in a larger plant