304df7f135
Registry's `set.outflow` (alias `q_out`) pushes a measured outflow into the basin balance. CONTRACT.md documented `set.inflow` but not its outflow twin; contract-verify required both. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
59 lines
3.6 KiB
Markdown
59 lines
3.6 KiB
Markdown
# pumpingStation — Contract
|
|
|
|
Hand-maintained for Phase 2; the `## Inputs` table is generated from
|
|
`src/commands/index.js` (see Phase 9 generator). Keep ≤ 80 lines.
|
|
|
|
## Inputs (msg.topic on Port 0)
|
|
|
|
| Canonical | Aliases (deprecated) | Payload | Effect |
|
|
|---|---|---|---|
|
|
| `set.mode` | `changemode` | `string` — one of `manual`, `levelbased`, `flowbased`, `none` | Switches the control strategy. |
|
|
| `child.register` | `registerChild` | `string` — the child node's Node-RED id | Resolves the child via `RED.nodes.getNode` and registers it through `childRegistrationUtils` at the supplied `msg.positionVsParent`. |
|
|
| `cmd.calibrate.volume` | `calibratePredictedVolume` | numeric (number or numeric string) — m³ | Resets the predicted-volume series and seeds it with the supplied value; recomputes level. |
|
|
| `cmd.calibrate.level` | `calibratePredictedLevel` | numeric — metres | Resets the predicted-level series and seeds it with the supplied value; recomputes volume. |
|
|
| `set.inflow` | `q_in` | number, numeric string, or `{ value, unit, timestamp }` | Pushes a manual inflow measurement onto the predicted-flow series. `unit` may be on the message (`msg.unit`) or inside the object payload. |
|
|
| `set.outflow` | `q_out` | number, numeric string, or `{ value, unit, timestamp }` | Pushes a measured outflow value into the basin balance. Same payload conventions as `set.inflow`. |
|
|
| `set.demand` | `Qd` | numeric — child setpoint demand | Forwards the demand to direct children (machineGroups / machines / stations). Only honoured in `manual` mode; in other modes the call is logged at `debug` and discarded. |
|
|
|
|
Aliases log a one-time deprecation warning the first time they fire.
|
|
|
|
## Outputs (msg.topic on Port 0/1/2)
|
|
|
|
- **Port 0 (process):** `msg.topic = config.general.name`. Payload built by
|
|
`outputUtils.formatMsg(..., 'process')` from `getOutput()` — delta-compressed
|
|
(only changed fields are emitted).
|
|
- **Port 1 (InfluxDB telemetry):** same shape as Port 0, formatted with the
|
|
`'influxdb'` formatter.
|
|
- **Port 2 (registration):** at startup the node sends one
|
|
`{ topic: 'registerChild', payload: <node.id>, positionVsParent, distance }`
|
|
to the upstream parent.
|
|
|
|
## Events emitted by `source.measurements.emitter`
|
|
|
|
The `MeasurementContainer` fires `<type>.<variant>.<position>` whenever
|
|
the corresponding series receives a new value. Parents subscribe via the
|
|
generic `child.measurements.emitter.on(eventName, ...)` handshake.
|
|
pumpingStation publishes:
|
|
|
|
- `volume.predicted.atequipment` — basin volume integrator output (m³).
|
|
- `level.predicted.atequipment` — basin level (m), recomputed from volume.
|
|
- `flow.predicted.in` (childed `manual-qin`) — manual inflow injections.
|
|
- `volume.measured.atequipment`, `level.measured.<position>`,
|
|
`pressure.measured.<position>`, `temperature.measured.atequipment`,
|
|
`flow.predicted.<in|out>` (childed by upstream child id) — when a
|
|
matching child measurement arrives.
|
|
|
|
The exact set is data-driven by which children register and what they
|
|
publish; downstream consumers should subscribe by event name, not assume
|
|
a fixed catalogue.
|
|
|
|
## Children registered by this node
|
|
|
|
pumpingStation acts as a parent for `measurement`, `machine`, `machinegroup`,
|
|
and `pumpingstation` software types. Position labels accepted from
|
|
children are `upstream`, `downstream`, `atequipment` (and the synonyms
|
|
`in` / `out` for predicted-flow children). Child-registration plumbing is
|
|
documented in `MODULE_SPLIT.md`; this node does not receive children
|
|
through Port 0 input — registration arrives on Port 2 from the child via
|
|
the standard `childRegistrationUtils` handshake.
|