wrps-demo-kit/01-design/WRPS-CTL-003_OpenPLC_Implementation_Brief.md

WRPS-CTL-003 — Waterloo Road Pump Station, OpenPLC implementation brief

Target: OpenPLC Runtime v4 on Windows, feeding Yokogawa CI Server over Modbus TCP. Source documents: WRPS-CTL-001 (Control Philosophy), WRPS-CTL-002 (Functional Design Specification), WRPS-PRO-001 (Process Basis of Design), WRPS-DRG-001 (P&ID), WRPS-INS-001 (Instrument index). Status: subordinate to WRPS-CTL-002. Where this brief and the FDS disagree, the FDS governs. Deliverable: a single IEC 61131-3 Structured Text file, uploadable directly through the OpenPLC Runtime web interface.

---

Amendments — 2026-09-02

This document is retained as issued. The body below is unchanged. The corrections here were found during the repo audit, by checking the document against the system that was actually built and is running.

§2 (the Modbus address map) was verified line by line against the generated 03-plc/register-map.csv and is correct in full. So are §3–§8. The errors are confined to the build system described in §1 and §9, which was superseded before any code was written.

#	Where	As issued	Correction
A1	Header	"OpenPLC Runtime v4 on Windows"	Linux, in Docker, on yau-sls-poc-lin001 (10.0.0.17). See 02-environment/.
A2	§1, §9	"OpenPLC's MatIEC compiler takes one flat .st file"	Runtime v4 removed MatIEC and rejects its output. It requires STruC++ codegen, which ships only inside the OpenPLC Editor GUI. The flat-file build system this section specifies does not exist on v4.
A3	Header, §1	Uploadable "through the OpenPLC Runtime web interface … Programs → Upload Program"	Runtime v4 has no browser UI. A program reaches it either through the Editor (compile + upload) or through the REST API on port 8443. See 03-plc/DEPLOY.md.
A4	§1	"Do not attempt to generate OpenPLC Editor PLCopen XML"	This is now the required route. gen_project.py generates the Editor project from src/, because it is the only path that reaches a v4 runtime.
A5	Header, §10	"Deliverable: a single … Structured Text file"	The deliverable is a generated OpenPLC Editor project. build.py's flat build/wrps.st survives as a single-file review artefact only; nothing consumes it.
A6	§1, §7	A tests/ directory in the source tree	Never created. The verification that exists is 05-tests/verify_modbus.py, which proves the register map against the running PLC — not the control behaviour.
A7	§9	"Port 502 may already be bound on that Windows server"	Applies to the Linux host. 502 and 8443 are published on 10.0.0.17 only — see 02-environment/README.md.
A8	§9, §10	"docs/register-map.csv"	The file is 03-plc/register-map.csv, generated by build.py.
A9	§10	Definition of done requires all 14 pass-1 and 6 pass-2 tests "documented with actual observed values"	Not met. None of the 20 acceptance tests have been run. The program compiles, is loaded, and publishes its registers correctly, but its control behaviour is unverified. This is the largest open item in the project.

A2, A3 and A4 share one cause: this brief was written before the deploy spike established that Runtime v4 had dropped MatIEC. §1 therefore specifies a build system that never existed on the target, and §4 of §1 forbids the method actually used. Read §1 and §9 as historical intent; read 03-plc/README.md for how the program is really built.

A9 is not a documentation defect. It is real outstanding work, recorded here so it is not mistaken for done.

---

0. How to use this brief

Build in two passes, in this order, and do not start pass 2 until pass 1 passes its acceptance tests:

• Pass 1 — control logic only. The PLC reads level, flow and status from located input variables. Nothing simulates them. Test by writing values into the input image manually.
• Pass 2 — simulation. Add a separate program that models the wet well and pumps, and switch the control logic's inputs from the located variables to the simulated ones through a single mux layer.

The control logic must never contain simulation code, and must never be edited to accommodate the simulator. If pass 2 requires a change inside a control POU, that is a design error in the mux layer — fix the mux, not the control.

---

1. Build system

OpenPLC's MatIEC compiler takes one flat .st file. To keep control and simulation genuinely separate in the source tree while still producing one uploadable artefact, use a concatenating build.

wrps-plc/
├── src/
│   ├── 10_globals.st              # VAR_GLOBAL, located variables, constants
│   ├── 20_fb_pump.st              # FB_PUMP
│   ├── 21_fb_duty_selector.st     # FB_DUTY_SELECT
│   ├── 22_fb_level_control.st     # FB_LEVEL_CTRL
│   ├── 23_fb_headroom.st          # FB_HEADROOM (time-to-breach calculation)
│   ├── 30_prog_control.st         # PROGRAM CONTROL
│   ├── 40_prog_simulation.st      # PROGRAM SIMULATION   <-- pass 2 only
│   ├── 50_prog_io_mux.st          # PROGRAM IO_MUX
│   ├── 90_config_field.st         # CONFIGURATION, field build
│   └── 91_config_sim.st           # CONFIGURATION, simulation build
├── build.py                       # concatenates in order, emits build/wrps.st
├── build/
└── tests/

build.py requirements:

• python build.py --mode field → concatenates everything except 40_prog_simulation.st and 91_config_sim.st.
• python build.py --mode sim → concatenates everything except 90_config_field.st.
• Concatenation order is lexical by filename. Emit a header comment with the mode, git short hash and UTC timestamp.
• Fail loudly if any source file is missing, rather than silently emitting a short file.
• Do not attempt to generate OpenPLC Editor PLCopen XML. The .st file is uploaded directly through the Runtime web UI (Programs → Upload Program).

---

2. Modbus address map

OpenPLC's located-variable to Modbus mapping (verify against your runtime version before wiring CI Server — the offsets have changed between v3 and v4):

IEC	Modbus object	Access from CI Server
%IX0.0+	Discrete input	Read only
%QX0.0+	Coil	Read/write (PLC overwrites each scan)
%IW0+	Input register	Read only
%QW0+	Holding register	Read/write (PLC overwrites each scan)
%MW0+	Holding register	Read/write, PLC does not overwrite

Because the PLC rewrites %QX and %QW every scan, all commands from CI Server go into %MW only. Never expect a SCADA write to a coil to persist.

2.1 Field inputs — %IW / %IX

Used in field mode. In simulation mode these are left unwired and the mux takes the simulated values instead.

Address	Tag	Engineering value	Raw scaling
%IW0	LIT-101	Wet well level	mm, 0–7000
%IW1	FIT-201	Inlet flow	L/s × 10
%IW2	FIT-301	Discharge flow	L/s × 10
%IW3	PIT-302	Manifold pressure	kPa
%IW4/5/6	PIT-311/321/331	Pump discharge pressure	kPa
%IW7/8/9	VE-314/324/334	Bearing vibration	mm/s × 10
%IX0.0	LSHH-102	High high level	TRUE = wet
%IX0.1	LSLL-103	Low low level	TRUE = wet (fail-safe: FALSE = dry)
%IX0.2	LSH-104	Spill detected	TRUE = spilling
%IX0.3/4/5	TE-312/322/332	Motor thermal trip	TRUE = healthy
%IX0.6/7, %IX1.0	MSE-313/323/333	Seal leak	TRUE = leak
%IX1.1	XA-502	Mains healthy	TRUE = healthy

2.2 PLC outputs — %QX / %QW (read by CI Server)

Address	Description	Units
%QX0.0/1/2	PU-301/302/303 run command
%QX0.3/4/5	PU-301/302/303 running
%QX0.6/7, %QX1.0	PU-301/302/303 available
%QX1.1	Station in auto
%QX1.2	High level alarm
%QX1.3	Spill active
%QX1.4/5/6	PU-301/302/303 tripped
%QW0	Wet well level	mm
%QW1	Inflow	L/s × 10
%QW2	Total discharge flow	L/s × 10
%QW3	Pumps running	count
%QW4	Common drive speed	Hz × 10
%QW5	Time to spill weir	seconds, 32767 = drawing down
%QW6	Time to LSHH	seconds, 32767 = drawing down
%QW7	Net accumulation	L/s × 10, signed
%QW8/9/10	PU-301/302/303 run hours	hours
%QW11	Volume remaining to spill	m³
%QW12	Station state	enum, §3.1
%QW13/14/15	Pump state	enum, §3.2
%QW16	Current duty pump	0 = none, 1–3
%QW17	Alarm bitmask	§6
%QW20	Command acknowledge	echoes %MW1 when executed

2.3 Commands and setpoints — %MW (written by CI Server)

Address	Description	Default
%MW0	Station mode: 1 = auto, 2 = off	1
%MW1	Command word, §3.3	0
%MW2	Command parameter (pump number, etc.)	0
%MW3	Level control setpoint	4200 mm
%MW4	Start duty level	4000 mm
%MW5	Start pump 2 level	4500 mm
%MW6	Start pump 3 level	5000 mm
%MW7	Stop all level	1000 mm
%MW8	High level alarm	5200 mm
%MW9	Minimum drive speed	380 (Hz × 10)
%MW10	Service interval	hours, default 4000
%MW11–19	Reserved
%MW20–29	Simulation control, §8 — simulation build only

Clamp every setpoint on read. If CI Server writes nonsense, hold the previous good value and raise an alarm rather than acting on it. A start level above the spill weir must never be accepted.

---

3. Enumerations

3.1 Station state (%QW12)

0 Off · 1 Idle · 2 Pumping · 3 High level · 4 Emergency (LSHH) · 5 Dry run lockout · 6 Fault

3.2 Pump state (%QW13/14/15)

0 Unavailable · 1 Available, stopped · 2 Start delay · 3 Running · 4 Min-run inhibit · 5 Min-off inhibit · 6 Tripped · 7 Maintenance lockout

3.3 Command word (%MW1)

0 None · 1 Reset all trips · 2 Reset trip on pump in %MW2 · 3 Lock out pump in %MW2 · 4 Release lockout on pump in %MW2 · 5 Reset run hours on pump in %MW2 (service done) · 6 Acknowledge alarms

Handshake: PLC executes on rising edge of a non-zero %MW1, writes the same value to %QW20, and takes no further action until %MW1 returns to 0. CI Server writes 0 after it sees the echo.

---

4. Control logic specification

Scan task: 100 ms, cyclic. All timers in TIME literals, never scan counts.

4.1 FB_PUMP

One instance per pump. Owns everything about a single unit.

Inputs: RunRequest : BOOL, SpeedRef : REAL (Hz), ThermalOK : BOOL, SealLeak : BOOL, Vibration : REAL, DischPressure : REAL, ResetTrip : BOOL, Lockout : BOOL

Outputs: RunCmd : BOOL, Running : BOOL, Available : BOOL, Tripped : BOOL, State : INT, RunHours : REAL, ServiceDue : BOOL

Behaviour:

• Available = ThermalOK AND NOT Tripped AND NOT Lockout. A seal leak does not remove availability — it raises an alarm only (per WRPS-PRO-001 §5.5).
• Minimum run 5 min: once Running, ignore a falling RunRequest until the timer expires.
• Minimum off 5 min: once stopped, block restart until expired. Overridden only by the LSHH emergency condition.
• No-flow trip: 20 s after RunCmd goes true, if DischPressure < 150 kPa, set Tripped, drop RunCmd, latch alarm. This is the condition that must cause the duty selector to promote the next available unit.
• Vibration: alarm above 7.1 mm/s, trip above 11.0 mm/s.
• RunHours accumulates only while Running, in scan-time increments. ServiceDue when RunHours >= %MW10.
• Trips latch. They clear only on the reset command, never automatically.

4.2 FB_DUTY_SELECT

Decides which units run, never how many.

Inputs: Available[1..3] : BOOL, RunHours[1..3] : REAL, ServiceDue[1..3] : BOOL, RunningNow[1..3] : BOOL, PumpsRequired : INT

Outputs: RunRequest[1..3] : BOOL, DutyPump : INT

Ranking rule, best first:

1. Unavailable units are excluded entirely.
2. Units not due for service rank above units due for service.
3. Within each group, lower accumulated run hours ranks first.
4. Ties break by ascending pump number, so the result is deterministic and repeatable in a demo.

Then: assign RunRequest to the top PumpsRequired ranked units.

Two rules that matter more than the ranking:

• Never stop a running unit to start a better-ranked one. If a unit is already running and is still available, it keeps its slot. Re-ranking applies only when a slot opens. Without this the station will churn pumps every time run hours cross over.
• Service-due is a preference, never a veto. If the only available unit is due for service, it runs. Rank 2 above must not be able to produce an empty selection while an available unit exists.

4.3 FB_LEVEL_CTRL

Inputs: Level : REAL (m), Setpoint : REAL, Enable : BOOL, MinSpeed, MaxSpeed : REAL

Output: Speed : REAL (Hz), common to all running units.

• PI control, no derivative term. Suggested starting gains: Kp = 12 Hz/m, Ti = 120 s. Expect to retune.
• Output clamped 38.0–50.0 Hz. Below 38 Hz the 22 m static lift means no delivery, so the clamp is a hard physical limit, not a preference.
• Anti-windup: freeze the integrator whenever the output is clamped.
• On Enable false, hold output at MinSpeed and reset the integrator, so a restart doesn't inherit stale integral action.

4.4 FB_HEADROOM

Pure calculation. No control action, no alarms. Publishes the quantity the demo narrative is built on.

NetInflow    = Inflow - TotalDischarge                    (L/s)
VolToSpill   = (6.000 - Level) * 120.0                    (m³)
VolToLSHH    = (5.500 - Level) * 120.0                    (m³)
TimeToSpill  = VolToSpill * 1000.0 / NetInflow            (s)

• If NetInflow <= 0.5 L/s, output 32767 — drawing down or holding, the figure is meaningless.
• Clamp outputs to 0 .. 32767. Never emit a negative time.
• Filter Inflow through a 30 s first-order lag before use. Raw flow-meter noise on a near-zero denominator produces wild swings, which on a demo screen looks broken.

4.5 PROGRAM CONTROL

Execution order per scan, and it matters:

1. Read and clamp setpoints from %MW.
2. Process the command word and write the acknowledge.
3. Determine PumpsRequired from level:
   • Level >= StartP3 → 3
   • Level >= StartP2 → 2
   • Level >= StartDuty → 1
   • Level <= StopAll → 0
   • otherwise hold the previous value (this hysteresis band is the whole point — do not recompute from scratch)
4. Override: if LSHH then PumpsRequired := 3 and bypass min-off timers.
5. Override: if LSLL then PumpsRequired := 0, latch dry-run lockout, require a manual reset.
6. Override: if station mode is off, PumpsRequired := 0.
7. Call FB_DUTY_SELECT.
8. Call FB_LEVEL_CTRL. On LSHH force 50.0 Hz.
9. Call each FB_PUMP.
10. Call FB_HEADROOM.
11. Stagger starts: when more than one unit is being started, hold the second and third by 30 s each, to limit the inrush and the hydraulic transient.
12. Publish all %QW / %QX.

---

5. Interlocks that must be provable

These map to the cause-and-effect table in WRPS-PRO-001 §5.5. Each needs a test in §7.

Initiator	Action	Reset
LSLL-103	Stop all, inhibit start	Manual, after level recovers above stop level
LSHH-102	Start all available at 50 Hz, bypass min-off	Automatic on level falling below LSHH
TE-31x	Trip that unit, promote next available	Manual
VE-31x > 11.0 mm/s	Trip that unit	Manual
PIT-31x low, 20 s after start	Trip that unit, promote next available	Manual
LIT-101 out of range or frozen	Alarm, fall back to LSHH/LSLL discrete control	Automatic

Level signal failure detection: raise the fault if the raw value sits outside 0–7000 mm, or if it does not change by more than 1 mm for 10 minutes while a pump is running. A frozen transmitter reading a plausible value is the failure mode that actually causes spills, and it is invisible to a range check alone.

---

6. Alarm bitmask (%QW17)

bit0 High level · bit1 High high level · bit2 Low low level · bit3 Spill active · bit4–6 Pump 1/2/3 tripped · bit7–9 Pump 1/2/3 seal leak · bit10–12 Pump 1/2/3 high vibration · bit13 Level signal fault · bit14 Mains failure · bit15 Setpoint rejected

---

7. Pass 1 acceptance tests

Run these with the simulation absent, by writing directly into the input image. Automate them in tests/ if practical; otherwise document the manual procedure with expected %QW values.

1. Cold start. Level 2.0 m, no pumps. Expect: 0 pumps, state Idle.
2. Duty start. Raise level to 4.1 m. Expect: exactly 1 pump requested, lowest-run-hours unit selected, speed ramping.
3. Hysteresis. Fall to 3.9 m. Expect: still 1 pump. Fall to 0.9 m. Expect: 0 pumps.
4. Assist staging. Raise to 4.6 m then 5.1 m. Expect 2 then 3 pumps, each staged 30 s apart.
5. Rotation. Set PU-301 run hours to 500, others to 100. Trigger a duty start. Expect PU-302 (lowest hours, tie broken by number).
6. Service due. Set PU-302 run hours above the service interval. Expect PU-303 selected ahead of it, but PU-302 still selected if it is the only available unit.
7. No churn. With PU-302 running, set its run hours above PU-303's. Expect PU-302 keeps running.
8. No-flow trip. Start a pump, hold PIT-31x at 100 kPa. Expect trip after 20 s, next available unit promoted, alarm bit set.
9. Thermal trip. Drop TE-312. Expect PU-301 unavailable, promotion, trip latched through a level cycle, clears only on command 2.
10. LSHH. Assert LSHH-102. Expect all available units at 50.0 Hz regardless of min-off timers.
11. LSLL. Assert LSLL-103. Expect all stopped, lockout latched, and no restart until reset even after level recovers.
12. Frozen transmitter. Hold %IW0 constant for 10 minutes with a pump running. Expect the level fault alarm.
13. Setpoint rejection. Write 6500 mm to %MW4. Expect rejection, previous value retained, bit15 set.
14. Time to breach. Level 4.00 m, inflow 165 L/s, one pump at 120 L/s. Expect %QW5 ≈ 5333 s and %QW7 = 450.

Test 14 is the one the demo narrative rests on. It must reproduce the figure in WRPS-PRO-001 §7.3 exactly, or the Basis of Design and the running system disagree.

---

8. Pass 2 — simulation

Only start this once every test above passes.

8.1 The mux layer

Add PROGRAM IO_MUX, which runs before CONTROL in the task list and is the only place that touches located input variables.

• In the field build, IO_MUX copies %IW / %IX into the global process variables that CONTROL reads.
• In the simulation build, IO_MUX copies the simulation program's outputs into those same globals instead.
• CONTROL reads only the globals. It must contain no %IW, %IX reference at all. Grep for it as a build check.

8.2 PROGRAM SIMULATION

Runs on the same 100 ms task, after CONTROL, so it sees this scan's run commands.

Wet well integration:

dt          = 0.1 * TimeScale                         (simulated seconds this scan)
NetFlow     = Inflow - SumPumpFlow                    (L/s)
Volume      = Volume + NetFlow * dt / 1000.0          (m³)
Level       = Volume / 120.0                          (m)

Clamp Level to 0.0 .. 6.0. On reaching 6.00 m, spill: hold level at 6.00, set the spill flag, and discard the excess. The station must be seen to spill in the demo, not to have its level run off scale.

Per-pump flow model. For each unit with RunCmd true:

• Start delay: 3 s from command to delivering flow, so the no-flow trip logic has something real to detect.
• Speed to flow, linear between the two physical anchors: 38 Hz → 65 L/s, 50 Hz → 120 L/s. Below 38 Hz, flow is 0 — this is the static-lift cutoff and must be modelled, or the level controller's clamp looks arbitrary.
• Parallel derating: with n units running, multiply each unit's flow by 1.00 / 0.94 / 0.88 for n = 1 / 2 / 3. Three units then give roughly 360 L/s at full speed, matching the design basis rather than a naive 3 × 120.
• Discharge pressure: 220 + 1.4 * PumpFlow kPa while delivering, 80 kPa otherwise. This is what makes the no-flow trip testable.

Inflow generator, selected by %MW21:

Mode	Behaviour
0	Manual — inflow held at %MW20 (L/s × 10)
1	Diurnal dry weather — sinusoid, 40–110 L/s, 24 h simulated period
2	Wet weather event — ramp from current to 300 L/s over 20 simulated minutes, hold 40 min, decay over 90 min
3	Demo reference — start at exactly 165 L/s with the level at 4.00 m and one pump running, then ramp slowly

Mode 3 must reproduce the §7.3 reference condition on demand, so the demo can be reset to a known state between audiences. Command %MW22 = 1 resets the simulation to the initial conditions of the selected mode.

Time scaling. %MW23 holds the time scale, 1–120, default 1. All simulation integration multiplies by it. The control logic must not know about it — its timers stay in real seconds. This means a 5-minute minimum-run timer at 60× covers 5 simulated hours, which is wrong but harmless for the demo. Note the discrepancy in the README rather than trying to scale the control timers; scaling both is what makes these demos impossible to debug.

Sensible defaults: 1× while testing logic, 30–60× when presenting.

8.3 Noise

Add small noise to the published measurements — ±0.5% on level, ±2% on flow — using a simple LCG, not a library call. Perfectly smooth trends are the giveaway that a plant screen is fake, and the inflow filter in FB_HEADROOM needs something to filter or you cannot show that it works.

8.4 Pass 2 acceptance tests

1. Dry weather mode for 24 simulated hours: expect ~7 start/stop cycles per unit and no high level alarm.
2. Demo reference mode: expect %QW5 to count down from ≈5333 s, and the spill to occur at ≈89 simulated minutes if no second pump starts.
3. Wet weather mode with all three available: expect the level to peak below 5.50 m and no spill.
4. Wet weather mode with PU-301 locked out: expect the level to reach LSHH and, with two units, to spill.
5. Reset command returns level, volume, run hours and trip states to initial conditions.
6. Time scale 60× produces the same level trajectory as 1×, sampled at the same simulated times.

Test 3 versus test 4 is the demonstration that firm capacity of 240 L/s is below PWWF of 300 L/s. That contrast is worth building the demo around.

---

9. Constraints

• OpenPLC's MatIEC is not a full IEC 61131-3 implementation. Stay on: BOOL, INT, DINT, REAL, TIME, one-dimensional ARRAY, TON, TOF, R_TRIG, F_TRIG, CTU. Avoid STRING manipulation, nested STRUCT, REF_TO, and VAR_IN_OUT on complex types.
• Everything the demo needs must survive a runtime restart being the reset mechanism. Do not rely on retained variables.
• Port 502 may already be bound on that Windows server. Check before assuming.
• No floating-point over Modbus. Every published value is a scaled 16-bit integer, per §2. Document the scaling in a docs/register-map.csv generated from the same source of truth as the ST, so CI Server tag configuration and the PLC cannot drift apart.

10. Definition of done

• python build.py --mode field and --mode sim both emit a file that OpenPLC Runtime compiles without warnings.
• All 14 pass-1 tests and all 6 pass-2 tests documented with actual observed values.
• docs/register-map.csv generated, matching §2.
• README.md covering: how to build, how to upload, how to select a scenario, how to reset between demos, and the time-scaling caveat in §8.2.
• Grep confirms no located variable reference outside 10_globals.st and 50_prog_io_mux.st.