pumpingStation/CONTRACT.md

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.