wrps-demo-kit/03-plc/README.md

03-plc — the PLC program

IEC 61131-3 Structured Text for the Waterloo Road Pump Station, implementing 01-design/WRPS-CTL-003. Control logic and a wet-well simulation, in separate POUs, from one source tree.

src/ is canonical. Everything else here is generated from it, or describes how it reaches the runtime.

GETTING-STARTED.md  start here - modify the program / build a new PLC / move it
VERSIONS.md         every version, read from the running system
src/*.st            the program - concatenated in lexical order
build.py            builds a flat .st AND generates register-map.csv
gen_project.py      generates the OpenPLC Editor v4 project (the deploy artefact)
register-map.csv    GENERATED - the PLC half of the Modbus contract
editor-devices/     the GUI-configured half of the Editor project (reference copy)
as-built/           what is ACTUALLY running, copied out of the container
DEPLOY.md           how a program reaches the runtime, and every gotcha hit

New here? Read GETTING-STARTED.md first — it answers "how do I change the program", "how do I stand up a new PLC" and "how do I move this one" in a page.

Build

python build.py       --mode field                  # control only
python build.py       --mode sim                    # control + PROGRAM SIMULATION
python gen_project.py --mode sim --out editor-project

build.py emits build/wrps.st (git-ignored) and regenerates register-map.csv. Never hand-edit the register map — change the REGISTERS table in build.py and rebuild. The build refuses to emit if any file other than src/10_globals.st or src/50_prog_io_mux.st references a located variable in code (CTL-003 §8.1, §10). Comments may mention them.

gen_project.py emits the Editor project, which is what actually gets deployed — see DEPLOY.md.

What is running right now

The simulation build, verified live on 2026-09-02 by polling the PLC:

level 2696 mm · inflow 74.3 L/s · discharge 75.0 L/s · 1 pump running · 40.1 Hz
run hours 113/107/100 h · vol to spill 396 m3 · state 2 (Pumping) · alarms 0x0000
%MW21 = 2 (wet weather scenario) · %MW23 = 1 (real time)

All %IW read zero — the mux is taking simulated values, as designed. Values move between polls; run hours accumulate.

The Modbus contract

%MW is not holding register 0. The v4 slave segments holding registers: %QW occupies HR 0–1023 and %MW starts at HR 1024. So %MW3 (level setpoint) is HR 1027. register-map.csv carries the resolved addresses — build the SCADA-side point list in 04-scada/modbus/ from that file, never from §2 of the brief.

%QW17 (alarm bitmask) must be read as unsigned 16-bit. Bit 15 does not fit a signed INT, so values ≥ 32768 fold into the negative half of the word. %QW7 (net accumulation) is genuinely signed — a live read returned 65532, which is −4.

Two conditions must both hold for port 502 to answer, and neither is a container setting: a program must be running, and the Editor project must define a Modbus Server so the runtime's modbus_slave plugin is enabled. See DEPLOY.md §A3.

Setpoints: seeded defaults vs live tuning

IO_MUX writes the %MW setpoint defaults once, on first scan, so CI Server sees real values rather than zeros after a restart. It is a one-shot write — anything CI Server writes afterwards survives (CTL-003 §2.3).

These are operator-adjustable. They are meant to be changed from demo to demo, and they are: the live station currently runs lower start levels than the seeded defaults, so it cycles faster and reads better on screen.

%MW	Seeded default (10_globals.st)	Live 2026-09-02
3 Level control setpoint	4200 mm	2700
4 Start duty level	4000 mm	1800
5 Start pump 2	4500 mm	3600
6 Start pump 3	5000 mm	4200
7 Stop all	1000 mm	900
8 High level alarm	5200 mm	4560
9 Minimum drive speed	380	380
10 Service interval	4000 h	4000

Important

Tuning lives only in the container's volume, not in this repo. Restart the runtime and every setpoint reverts to the seeded default, and the station will behave differently on stage. If a particular set of values is the one you want to demo, write them down — the repo cannot restore them for you.

Simulation

--mode sim adds PROGRAM SIMULATION, which models the wet well, the pumps and the field instruments. IO_MUX then feeds CONTROL from the model instead of %IW/%IX. No control POU changes between the two builds — that is the point of §8.1.

Register	HR	Meaning
%MW20	1044	Manual inflow, L/s × 10 (scenario 0 only)
%MW21	1045	Scenario: 0 manual · 1 diurnal · 2 wet weather · 3 demo reference
%MW22	1046	Write 1 to reset the scenario; self-clearing
%MW23	1047	Time scale 1–120, default 1

Scenarios (§8.2): 1 is a 40–110 L/s sinusoid over a 24 h simulated period; 2 ramps to 300 L/s over 20 simulated minutes, holds 40, decays over 90; 3 is the §7.3 demo reference — level starts at 4.00 m with 165 L/s inflow.

⚠️ Reset does not clear run hours or trip states. Those live in FB_PUMP, not in the simulation, and the simulation is forbidden from reaching into control state. Use the control commands: command 1 resets trips, command 5 resets run hours (%MW1/%MW2). Pass-2 test 5 asks for one reset that does all of it; here it takes two writes.

The time-scaling caveat

%MW23 scales simulation time only. CONTROL's timers stay in real seconds and must — FB_PUMP's no-flow trip is a T#20s TON, and scaling both time bases is what makes these demos impossible to debug.

The consequence is real and intended: at 60×, a 5-minute minimum-run timer covers 5 simulated hours. Wrong, but harmless for a demo — and obvious, rather than a subtly mis-tuned controller. For the same reason the per-pump start delay (3 s) runs on real time: scaled, at 60× it would elapse in 50 ms and the no-flow trip could never be demonstrated, which is the one thing §8.2 says the delay is for.

Use 1× while testing logic, 30–60× when presenting.

Reset between demos

Restart the runtime. Nothing is retained (§9), and IO_MUX re-seeds the %MW defaults on first scan — see the warning about tuning above.

---

Decisions and deviations

Everything below departs from a literal reading of the brief. Each is a judgement call, not an oversight.

FB_PUMP has three inputs the brief does not list. MinOffBypass (LSHH must override the min-off timer, §4.1), ServiceInterval (ServiceDue is defined against %MW10) and ResetHours (command 5). Each specified output is otherwise unreachable.

LSHH bypasses the start stagger as well as the min-off timers. §4.1 and §5 mention only min-off, but test 10 expects all available units at 50.0 Hz on LSHH, and a 30 s-per-unit stagger would take 60 s to get there. Treated as an emergency response.

The stagger is applied before duty selection, not after. §4.5 lists it as step 11. It limits how many units may start, which is an input to selection rather than a correction applied to its result.

No-flow is monitored continuously after the 20 s window, not sampled once at t = 20 s. Either reading satisfies test 8; this one also catches a loss of flow while running.

The dry-run lockout is reset by command 1 (reset all trips), and only once level has recovered above stop level, per §5. §3.3 defines no dedicated command.

Simulation deviations

%MW20–23 are declared in both builds, not "simulation build only" as §2 says. Located variables may only be declared in 10_globals.st, and splitting that file would need a second file with located-variable permission, weakening the §10 grep check. In the field build the registers are simply unused. register-map.csv marks them SIM ONLY.

Scenario 3 holds inflow at exactly 165 L/s rather than "then ramp slowly" (§8.2). The ramp rate is unspecified, and pass-2 test 2 pins the outcome precisely: spill at ~89 simulated minutes from 4.00 m. That figure only holds at a constant 165 L/s against one pump at 120 L/s — 240 m3 / 45 L/s = 5333 s = 88.9 min, which is also the %QW5 countdown the test expects. Any ramp makes both numbers wrong.

Plant health is constant (ThermalOK TRUE, SealLeak FALSE, MainsOK TRUE). Fault injection is not modelled because §8 does not ask for it. Test 4 needs PU-301 locked out, which is a control command rather than a simulated fault, so it is reachable. A thermal or seal-leak trip is not demonstrable without adding injection registers.

SIMULATION runs FIRST in the sim build, not after CONTROL as §8.2 says. Found by running it: with SIMULATION last, the first scan after every start has no simulated image, so IO_MUX falls back to the all-zero field inputs — ThermalOK FALSE and LSLL dry — and FB_PUMP latches a trip on all three units while the station enters dry-run lockout. Both latch until a reset command, so every demo would begin by clearing trips that never happened. Observed live 2026-08-14: %QW12 = 5, %QW17 = 116, all three trip coils true, until command 1 was issued by hand.

Running it first costs one scan of staleness — SIMULATION acts on the run commands and speed CONTROL published 100 ms earlier. That is the same lag IO_MUX already has on published outputs, and it is invisible beside a 3 s pump start delay.

FB_HEADROOM's inflow filter is primed with its first sample rather than ramping from zero. Without this, test 14's reference figure takes ~2 minutes to settle and cannot be reproduced on demand, which §7 requires.

Outputs are published one scan late. §8.1 requires IO_MUX to be the only POU touching located variables and to run before CONTROL, so the %QW/%QX values it writes are the previous scan's. 100 ms lag on published values only; no control decision is affected.

Three explicit FB_PUMP instances, not ARRAY[1..3] OF FB_PUMP — arrays of function blocks are the kind of construct §9 warns about.

SCAN_S := 0.1 is a constant inside each FB that uses scan time for integration (run hours, PI integral, inflow filter). It must match the TASK INTERVAL in the configuration file. Changing one without the other silently changes controller tuning and run-hour accumulation.

---

Status — 2026-09-02

Simulation build	Compiled, deployed and running on yau-sls-poc-lin001, polled live by CI Server on yau-poc-cicore1
Register map	69 points, reproduces byte-identically from build.py
Modbus contract	Verified against the live PLC — addresses, segmentation and signedness all as documented
Field build	Compiled and verified 2026-08-14 (65/65 points, 11/11 RW). Superseded by the sim build now running
Source integrity	src/ matches what is deployed. The container's program.st was compared against build/wrps.st on 2026-09-02: identical POU structure, zero differences in non-declaration lines. See as-built/README.md.

⚠️ Two things that are not done

1. None of the 20 acceptance tests have been run. CTL-003 §7 lists 14 pass-1 tests and §8.4 lists 6 pass-2 tests. The program compiles, runs, and publishes its registers correctly — which says nothing about whether the control logic is right. This is the single largest open item in the project, and CTL-003's own definition of done is unmet because of it.

2. There is currently no way to deploy a new program. The OpenPLC Editor lived only on the retired dev-ubuntu host and does not exist on yau-sls-poc-lin001. The running PLC is a committed image carrying an already-compiled program. Changing src/ today produces a project that cannot reach the runtime. See DEPLOY.md §0.