diffuser/wiki/Reference-Examples.md

# Reference — Examples

![code-ref](https://img.shields.io/badge/code--ref-4973a8b-blue)

> [!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

```bash
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:

```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 | 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](Home) | Intuitive overview |
| [Reference — Contracts](Reference-Contracts) | Topic + config + child registration |
| [Reference — Architecture](Reference-Architecture) | Code map, OTR / ΔP pipeline |
| [Reference — Limitations](Reference-Limitations) | Known issues and open questions |
| [reactor — Examples](https://gitea.wbd-rd.nl/RnD/reactor/wiki/Reference-Examples) | Parent-side example flows |
| [EVOLV — Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where diffuser fits in a larger plant |