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

Architecture of the PLC program

What the program is made of, what each part does, and how data moves through it. Behaviour and the reasoning behind design choices are in README.md; addresses are in register-map.csv.

At a glance

Language	IEC 61131-3 Structured Text
Source files	10 (src/*.st), concatenated in lexical order
Function blocks	4
Programs	3
Tasks	1 — plc_task, 100 ms cyclic
Program instances	3, all on that one task
Located variables	69
Process-image globals	65
Modbus points	69 — 10 input reg · 10 discrete in · 15 coil · 34 holding reg
Writable from SCADA	15 holding registers (11 control + 4 simulation)
Comms interfaces	1 — Modbus TCP server (slave), port 502, unit 1

The one architectural rule

Control logic never touches hardware. Exactly two files may reference a located variable (%IW, %IX, %QW, %QX, %MW):

• 10_globals.st — declares them
• 50_prog_io_mux.st — reads and writes them

Everything else reads and writes process-image globals (g_*) only. build.py enforces this and refuses to build if any other file references a located variable in code.

That rule is what lets the identical control logic run against a simulated plant or a real one, with no change to a single control POU.

Layers

   ┌──────────────────────────────────────────────────────────────┐
   │  MODBUS TCP SLAVE  :502   (runtime plugin, not program code) │
   └──────────────────────────────────────────────────────────────┘
        ▲ %QW %QX published        ▼ %MW commands      ▼ %IW %IX field
   ┌──────────────────────────────────────────────────────────────┐
   │  IO_MUX          the ONLY POU that touches located variables │
   │                  field build : %IW/%IX  →  g_*               │
   │                  sim build   : SIMULATION outputs  →  g_*    │
   │                  both        : g_o_*  →  %QW/%QX             │
   │                  first scan  : seeds %MW setpoint defaults   │
   └──────────────────────────────────────────────────────────────┘
                          ▲ g_o_*            ▼ g_*
   ┌──────────────────────────────────────────────────────────────┐
   │  CONTROL         the control logic. Reads globals only.      │
   │    ├── FB_PUMP        × 3   one per unit                     │
   │    ├── FB_DUTY_SELECT × 1   which units run                  │
   │    ├── FB_LEVEL_CTRL  × 1   what speed                       │
   │    └── FB_HEADROOM    × 1   time and volume to breach        │
   └──────────────────────────────────────────────────────────────┘
                          ▲ run cmds, speed
   ┌──────────────────────────────────────────────────────────────┐
   │  SIMULATION      simulation build only. Models the wet well, │
   │                  the pumps and the instruments.              │
   └──────────────────────────────────────────────────────────────┘

The sections

Function blocks

File	POU	Lines	Owns
20_fb_pump.st	FB_PUMP	141	One pump, completely. Min-run and min-off timers, no-flow trip, thermal and vibration trips, availability, run-hour accumulation, service-due, pump state enum. Three instances. Trips latch and clear only on command.
21_fb_duty_selector.st	FB_DUTY_SELECT	128	Which units run — never how many. Ranks available units by service-due then run hours, ties by pump number. Two rules dominate the ranking: never stop a running unit to start a better-ranked one, and service-due is a preference, never a veto.
22_fb_level_control.st	FB_LEVEL_CTRL	74	Common drive speed. PI, no derivative, anti-windup, clamped 38–50 Hz. Below 38 Hz the 22 m static lift means no delivery, so the clamp is physical, not a preference.
23_fb_headroom.st	FB_HEADROOM	97	Pure calculation, no control action. Net inflow, volume and time to the spill weir and to LSHH. Inflow is filtered through a 30 s lag first — this is the number the demo narrative rests on.

Programs

File	POU	Lines	Does
30_prog_control.st	CONTROL	595	The control sequence. Clamps setpoints, processes the command word and acknowledge, derives how many pumps are required from level with hysteresis, applies the LSHH / LSLL / station-off overrides, staggers starts, calls the four function blocks in order, and publishes every output global. The largest file, and where the plant's behaviour lives.
50_prog_io_mux.st	IO_MUX	292	The hardware boundary. Copies located inputs (or the simulation's outputs) into the process image, copies published globals out to %QW/%QX, and seeds the %MW setpoint defaults once on first scan.
40_prog_simulation.st	SIMULATION	308	Simulation build only. Integrates the wet-well volume, models per-pump flow against speed with parallel derating, generates discharge pressure, drives four inflow scenarios, applies time scaling and adds measurement noise.

Declarations and configuration

File	Lines	Contents
10_globals.st	252	The only place located variables are declared: 69 of them, plus 65 process-image globals and the constants (plant geometry, speed limits, setpoint defaults).
90_config_field.st	23	CONFIGURATION for the field build — plc_task at 100 ms, instances inst_mux + inst_ctl.
91_config_sim.st	45	CONFIGURATION for the simulation build — the same, plus inst_sim.

Execution order — it is load-bearing

One task, plc_task, 100 ms cyclic. Declaration order in the CONFIGURATION sets execution order within it.

Field build (90_config_field.st): IO_MUX → CONTROL

Simulation build (91_config_sim.st): SIMULATION → IO_MUX → CONTROL

SIMULATION runs first, though CTL-003 §8.2 says it should run after CONTROL. With it last, the first scan after every start has no simulated image, so IO_MUX falls back to the all-zero field inputs — which means ThermalOK FALSE and LSLL dry — and all three pumps latch a trip while the station enters dry-run lockout. Every demo would begin by clearing trips that never happened. The cost of running it first is one scan of staleness, invisible beside a 3 s pump start delay.

The 100 ms interval is not adjustable on its own. FB_PUMP, FB_LEVEL_CTRL, FB_HEADROOM and SIMULATION all integrate against a hardcoded SCAN_S := 0.1. Change the task interval without changing those and you silently alter controller tuning and run-hour accumulation.

The two builds

Selected by build.py --mode; the difference is two files, and no control POU changes between them.

	Field	Simulation
40_prog_simulation.st	excluded	included
Configuration	90_config_field.st	91_config_sim.st
IO_MUX input source	%IW / %IX	SIMULATION outputs
%MW20–23	declared, unread	scenario control
Currently deployed		✅ this one

%MW20–23 are declared in both builds even though CTL-003 §2 says "simulation build only" — located variables may only be declared in 10_globals.st, and splitting that file would weaken the build's located-variable check. In the field build they are simply never read.

Comms interfaces

One. The runtime's modbus_slave plugin, Modbus TCP, port 502, unit id 1.

It is not program code — it is a runtime plugin, enabled by conf/modbus_slave.json, which the Editor only ships if the project defines a Modbus Server device. This is why port 502 can be published by Docker and still refuse connections. See DEPLOY.md §A3.

Not used	Why
modbus_master	Disabled. The PLC must never poll anyone — that would invert the architecture.
opcua, s7comm	Disabled.
ethercat	⚠️ Enabled, from an empty ethercat.json the Editor emits by default. Nothing uses it.

The REST API on 8443 is the runtime's control channel (upload, start/stop), not a process interface. CI Server never touches it.

The 69 Modbus points

Object	FC	Count	Direction	What
Input register %IW	04	10	PLC reads	Field analogues: level, flows, pressures, vibration
Discrete input %IX	02	10	PLC reads	Field digitals: level switches, thermals, seal leaks, mains
Coil %QX	01	15	PLC writes	Run commands, running, available, tripped, in-auto, alarms
Holding register %QW	03	19	PLC writes	Every published measurement, station and pump state, run hours, headroom
Holding register %MW	03/06	15	SCADA writes	11 setpoints and commands + 4 simulation controls

%QW occupies holding registers 0–1023; %MW starts at HR 1024. So %MW3, the level setpoint, is holding register 1027. This is a v4 change and it produces plausible-but-wrong values rather than an error. Use the resolved addresses in register-map.csv.

In the simulation build, do not poll %IW / %IX. Nothing writes them; they read zero forever. Every live value is published in the %QW block.

Where the numbers come from

The whole chain is generated from one table, so the two sides cannot drift:

src/*.st  ──build.py──►  register-map.csv  ──gen_scada_points.py──►  scada-points.csv
   ▲                          ▲                                            │
   │                    REGISTERS table                       gen_ciserver_qli.py
   │                    in build.py                                        ▼
 hand-written                                                     CI Server .qli

register-map.csv is generated — never hand-edit it. Change the REGISTERS table in build.py and rebuild, then regenerate the SCADA side.