pumpingStation/wiki/Reference-Contracts.md

# Reference — Contracts

![code-ref](https://img.shields.io/badge/code--ref-a83a85e-blue) ![autogen](https://img.shields.io/badge/sections-autogenerated-orange)

> [!NOTE]
> Full topic contract, configuration schema, and child-registration filters for `pumpingStation`. The topic-contract and data-model sections are **regenerated by `npm run wiki:all`** — do not hand-edit between the `BEGIN AUTOGEN` / `END AUTOGEN` markers. Source of truth for everything on this page: the node's `src/commands/index.js`, `src/specificClass.js` `configure()`, and the schema at `generalFunctions/src/configs/pumpingStation.json`.
>
> For an intuitive overview, return to the [Home](Home).

---

## Topic contract

The **Unit** column reflects each descriptor's declared unit (via the `unit: 'm3/h'` shorthand or the legacy `units: { measure, default }`; the measure is derived from the unit). The default unit is what the commandRegistry coerces incoming values to before the handler runs.

**Command envelope (all EVOLV nodes).** Every command shares one envelope on top of `msg.topic`:
- **Value + unit** — send `msg.payload` as a number (with optional sibling `msg.unit`) **or** as `{ value, unit }`. The registry always converts the value to the descriptor's unit before the handler; numeric strings are converted too. A missing unit assumes the descriptor default.
- **`msg.origin`** — the control authority that issued the command: `parent` (automation/parent controller, the default), `GUI` (SCADA/HMI operator), or `fysical` (physical buttons). On nodes with a control mode, the mode's `allowedSources` decides which origins are accepted; releasing control is done by changing the mode.

<!-- BEGIN AUTOGEN: topic-contract -->

| Canonical topic | Aliases | Payload | Unit | Effect |
|---|---|---|---|---|
| `set.mode` | `changemode` | `string` | — | Switch the station between auto / manual control modes. |
| `child.register` | `registerChild` | `string` | — | Register a child node (machine group, measurement, …) with this station. |
| `cmd.calibrate.volume` | `calibratePredictedVolume` | any | `volume` (default `m3`) | Calibrate the predicted-volume integrator to a known basin volume. |
| `cmd.calibrate.level` | `calibratePredictedLevel` | any | `length` (default `m`) | Calibrate the predicted-volume integrator to a known basin level. |
| `set.inflow` | `q_in` | any | `volumeFlowRate` (default `m3/h`) | Push a measured inflow value into the basin balance. |
| `set.outflow` | `q_out` | any | `volumeFlowRate` (default `m3/h`) | Push a measured outflow value into the basin balance. |
| `set.demand` | `Qd` | any | `volumeFlowRate` (default `m3/h`) | Operator outflow demand setpoint for the station. |

<!-- END AUTOGEN: topic-contract -->

### Input message examples

One worked `msg` per accepted topic. Send these into **Port 0**. For unit-bearing
topics the commandRegistry converts `msg.unit` (or a `{ value, unit }` payload) to
the default unit *before* the handler runs &mdash; so the unit is optional and any
[compatible unit](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) is accepted.

```js
// 1. set.mode  — switch control strategy
msg = { topic: 'set.mode', payload: 'manual' };        // manual | levelbased | flowbased | none

// 2. child.register — register a child (usually arrives on Port 2 from the child;
//    this is the manual form). payload = the child node's Node-RED id.
msg = { topic: 'child.register', payload: 'a1b2c3d4.ef567', positionVsParent: 'upstream' };
//    positionVsParent: upstream | downstream | atequipment   (or in | out for predicted-flow children)

// 3. cmd.calibrate.volume — seed the predicted-volume integrator (default m³)
msg = { topic: 'cmd.calibrate.volume', payload: 12.5 };            // 12.5 m³
msg = { topic: 'cmd.calibrate.volume', payload: 12500, unit: 'L' }; // 12 500 L → auto-converted to 12.5 m³

// 4. cmd.calibrate.level — seed the predicted level (default m)
msg = { topic: 'cmd.calibrate.level', payload: 1.8 };  // 1.8 m

// 5. set.inflow — push a measured inflow (default m³/h)
msg = { topic: 'set.inflow', payload: 45 };                                       // 45 m³/h
msg = { topic: 'set.inflow', payload: 12.5, unit: 'L/s' };                        // 12.5 L/s → 45 m³/h
msg = { topic: 'set.inflow', payload: { value: 45, unit: 'm3/h' }, timestamp: 1716998400000 };

// 6. set.outflow — push a measured/forced outflow (default m³/h)
msg = { topic: 'set.outflow', payload: 30 };           // 30 m³/h drawn from the basin

// 7. set.demand — operator outflow setpoint (default m³/h); ignored unless mode === 'manual'
msg = { topic: 'set.demand', payload: 120 };           // 120 m³/h

// Built-in (every EVOLV node): query.units — ask which units each topic accepts.
// Replies on Port 0 with { topic:'query.units', payload:{ node, units } }.
msg = { topic: 'query.units', payload: null };
```

> Deprecated aliases behave identically and log a one-time warning, e.g.
> `{ topic: 'q_in', payload: 45 }` ≡ `set.inflow`, `{ topic: 'Qd', payload: 120 }` ≡ `set.demand`.

---

## Data model &mdash; `getOutput()` shape

Keys composed each tick by `specificClass.getOutput()` and emitted via `outputUtils.formatMsg` on Port 0. Delta-compressed: consumers see only the keys that changed.

<!-- BEGIN AUTOGEN: data-model -->

| Key | Type | Unit | Sample |
|---|---|---|---|
| `direction` | string | — | `"steady"` |
| `dryRunLevel` | number | — | `0.20400000000000001` |
| `dryRunSafetyVol` | number | — | `2.55` |
| `flowSource` | null | — | `null` |
| `heightBasin` | number | m | `4` |
| `highVolumeSafetyLevel` | number | — | `3.7239999999999998` |
| `highVolumeSafetyVol` | number | — | `46.55` |
| `inflowLevel` | number | m | `1.5` |
| `inletPipeDiameter` | number | — | `0.4` |
| `manualDemand` | null | — | `null` |
| `maxVol` | number | m3 | `50` |
| `maxVolAtOverflow` | number | m3 | `47.5` |
| `minHeightBasedOn` | string | — | `"outlet"` |
| `minVol` | number | m3 | `2.5` |
| `minVolAtInflow` | number | m3 | `18.75` |
| `minVolAtOutflow` | number | m3 | `2.5` |
| `mode` | string | — | `"levelbased"` |
| `outflowLevel` | number | m | `0.2` |
| `outletPipeDiameter` | number | — | `0.4` |
| `overflowLevel` | number | m | `3.8` |
| `percControl` | number | % | `0` |
| `predictedOverflowRate` | number | — | `0` |
| `predictedOverflowVolume` | number | — | `0` |
| `predictedUnderflowVolume` | number | — | `0` |
| `surfaceArea` | number | m2 | `12.5` |
| `timeleft` | null | s | `null` |
| `volEmptyBasin` | number | m3 | `50` |
| `volume.predicted.atequipment.wikigen-pumpingstation-id` | number | m3 | `2.5` |

<!-- END AUTOGEN: data-model -->

Sample values come from a stub instantiation in `wikiGen` &mdash; in a live deployment the volume key is shaped `volume.<variant>.<position>.<childId>` per the standard [Measurement Key Shape](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions#measurement-key-shape).

> [!NOTE]
> Two control-state keys carry the live operating mode rather than a measurement:
> - `mode` &mdash; string, the active control strategy (`levelbased` / `manual` / `flowbased` / `none`). Echoes the most recent `set.mode` input.
> - `manualDemand` &mdash; number (m³/h) or `null`. The operator outflow setpoint last accepted via `set.demand`; `null` outside `manual` mode.

### Output message examples

The node emits on three ports every tick (`outputUtils.formatMsg`). Port 0 / Port 1
fire only when at least one field changed (delta-compression); Port 2 fires once at
startup. `topic` is the station's configured name (here `"PS-Influent-01"`).

```js
// Port 0 — process data. payload = only the keys that changed this tick.
msg = {
  topic: 'PS-Influent-01',
  payload: {
    mode: 'levelbased',
    direction: 'filling',
    percControl: 25,
    'level.predicted.atequipment.default': 3.25,   // m
    'volume.predicted.atequipment.default': 32.5,  // m³
    timeleft: 400,                                  // s, or null when steady
    manualDemand: null                              // m³/h, or null outside manual mode
  }
};

// Port 1 — InfluxDB telemetry. Same changed fields, wrapped for the InfluxDB node.
msg = {
  topic: 'PS-Influent-01',
  payload: {
    measurement: 'PS-Influent-01',
    fields: { percControl: 25, 'volume.predicted.atequipment.default': 32.5 },
    tags: { id: 'a1b2c3d4.ef567', softwareType: 'pumpingstation', type: 'pumpingStation' },
    timestamp: '2026-05-29T10:00:00.000Z'           // Date
  }
};

// Port 2 — registration handshake, sent once at startup to the upstream parent.
msg = {
  topic: 'child.register',
  payload: 'a1b2c3d4.ef567',                         // this node's id
  positionVsParent: 'atEquipment',
  distance: null
};
```

> **Child-facing events** are not Port messages &mdash; they fire on
> `source.measurements.emitter` as `<type>.<variant>.<position>`, e.g. event
> `volume.predicted.atequipment` with payload `{ value: 32.5, unit: 'm3', timestamp }`.
> Parents subscribe by event name.

---

## Configuration schema &mdash; editor form to config keys

Source of truth: `generalFunctions/src/configs/pumpingStation.json`.

### Basin geometry (`config.basin`)

| Form field | Config key | Default | Unit | Notes |
|:---|:---|:---|:---|:---|
| Basin Volume | `basin.volume` | `1` | m3 | Total geometric storage from floor to rim |
| Basin Height | `basin.height` | `1` | m | Floor-to-rim wall height |
| Inlet Elevation | `basin.inflowLevel` | `2` | m | Bottom of incoming pipe, from floor |
| Outlet Elevation | `basin.outflowLevel` | `0.2` | m | Top of pump-suction pipe, from floor |
| Inlet Pipe Diameter | `basin.inletPipeDiameter` | `0.4` | m | For future hydraulic upgrades |
| Outlet Pipe Diameter | `basin.outletPipeDiameter` | `0.4` | m | For future hydraulic upgrades |
| Overflow Level | `basin.overflowLevel` | `2.5` | m | Physical overflow weir crest |

### Safety thresholds (`config.safety`)

| Form field | Config key | Default | Notes |
|:---|:---|:---|:---|
| High-Volume Safety % | `safety.highVolumeSafetyThresholdPercent` | `98` | Trigger high-volume safety at this fill % |
| Dry-Run Safety Level | `safety.dryRunLevel` | `0.2` | Below this level all pumps stop |
| Enable High-Volume Safety | `safety.enableHighVolumeSafety` | `true` | Master switch |

> [!WARNING]
> Earlier versions used `enableOverfillProtection` and `overfillThresholdPercent`. Those names are deprecated. The current canonical names are `enableHighVolumeSafety` and `highVolumeSafetyThresholdPercent`. See `.claude/refactor/OPEN_QUESTIONS.md` for the alias-removal timeline.

### Control mode (`config.control`)

| Form field | Config key | Default | Notes |
|:---|:---|:---|:---|
| Mode | `control.mode` | `"levelbased"` | One of `levelbased`, `manual`, `flowbased`*, `pressureBased`*, `percentageBased`*, `powerBased`*, `hybrid`*. Asterisked modes are placeholders in code. |
| Level Curve Type | `control.levelbased.curveType` | `"linear"` | `linear` or `log` |
| Log Curve Factor | `control.levelbased.logCurveFactor` | `0.5` | Slope tuning for log curve |
| Min Level | `control.levelbased.minLevel` | `0.3` | Demand hard-zero below this |
| Start Level | `control.levelbased.startLevel` | `0.5` | Falling-ramp returns to 0 % here |
| Stop Level | `control.levelbased.stopLevel` | `0.4` | Schmitt-trigger lower bound for pump-count keep-alive |
| Max Level | `control.levelbased.maxLevel` | `2.3` | Demand saturates at 100 % here |
| Enable Shifted Ramp | `control.levelbased.enableShiftedRamp` | `true` | Hysteresis-armed shift between rising / falling ramps |
| Manual Flow Setpoint | `control.manual.flowSetpoint` | `0` | Honoured in `manual` mode |

### General (`config.general`)

| Form field | Config key | Default | Notes |
|:---|:---|:---|:---|
| Time-left full / empty threshold | `general.timeleftToFullOrEmptyThresholdSeconds` | `120` | ETA below this triggers warning state |
| Flow dead-band | `general.flowThreshold` | `1e-4` m³/s | Net-flow below this is treated as steady |

---

## Child registration

Source: `nodes/pumpingStation/src/specificClass.js` `configure()`, lines 107&ndash;116.

| Software type | Filter | Wired to | Side-effect |
|:---|:---|:---|:---|
| `measurement` | any | `_subscribeMeasurement` | Subscribes to the measurement's emitter; updates basin balance |
| `machine` | only if no `machinegroup` parent is present | direct dispatch | Bypassed when an MGC is the predicted-flow source |
| `machinegroup` | any | `_subscribePredictedFlow` | Reads aggregated predicted flow from the MGC |
| `pumpingstation` | any | `_subscribePredictedFlow` | Cascaded PS &mdash; reads predicted outflow of upstream station |

The router only subscribes to the **highest-level aggregator** for predicted flow. If an MGC is present, direct `machine` children are not double-counted.

---

## Unit policy

Source: `nodes/pumpingStation/src/specificClass.js` lines 21&ndash;30.

| Quantity | Canonical (internal) | Output (rendered) |
|:---|:---|:---|
| Flow | `m3/s` | `m3/s` (also `netFlowRate`) |
| Level | `m` | `m` |
| Volume | `m3` | `m3` |
| Pressure | `Pa` | (not surfaced) |
| Power | `W` | (not surfaced) |
| Temperature | `K` | (not surfaced) |

`overflowVolume` and `underflowVolume` are explicitly listed in the policy output so the `MeasurementContainer` keeps the integrator's `m3` unit on those streams (`FlowAggregator` writes spill / underflow per tick).

---

## Related pages

| Page | Why |
|:---|:---|
| [Home](Home) | Intuitive overview |
| [Reference &mdash; Architecture](Reference-Architecture) | Code map, state chart, lifecycle |
| [Reference &mdash; Examples](Reference-Examples) | Shipped example flows |
| [Reference &mdash; Limitations](Reference-Limitations) | Known limitations and open questions |
| [EVOLV &mdash; Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) | Platform-wide topic rules |
| [EVOLV &mdash; Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) | Port 0 / 1 / 2 InfluxDB layout |