wrps-demo-kit/05-tests/README.md

05-tests — Modbus verification harness

Two tools. One reads the PLC and checks it against the register map; the other is a PLC, serving deliberately distinctive values so the SCADA side can be tested on its own.

python verify_modbus.py --host 10.0.0.17 --port 502 --unit 1
python verify_modbus.py --write-test        # also prove the 15 RW points accept writes
python verify_modbus.py --quiet             # failures and summary only

Requires pymodbus (pip install pymodbus). Exit code is 0 only if everything passed, so it works as a gate.

verify_modbus.py reads every row of ../03-plc/register-map.csv from the live runtime, using the function code each object type implies — FC1 coils, FC2 discrete inputs, FC3 holding registers, FC4 input registers.

If you cannot reach 10.0.0.17

That address is only routable from inside the VNet or over the WireGuard VPN. From anywhere else, poll from a throwaway container on the host's own Docker network:

ssh lin001 "docker run --rm --network openplc-net python:3.12-alpine \
  sh -c 'pip install -q pymodbus && python - <<EOF
from pymodbus.client import ModbusTcpClient
c = ModbusTcpClient(\"openplc-runtime\", port=502, timeout=5); c.connect()
print(c.read_holding_registers(0, count=21, slave=1).registers)
EOF'"

The container resolves openplc-runtime by service name, so no IP is needed.

What a pass proves, and what it does not

Proves: the runtime honours the register map — every mapped address exists and responds, the %MW block really does start at holding register 1024, and the RW points accept writes.

Does not prove: that the control logic is correct. None of the 20 acceptance tests from 01-design/WRPS-CTL-003 (§7 and §8.4) are implemented here. A green run against a completely wrong control program looks identical to a green run against a right one.

That gap is the largest open item in the project. This harness verifies the contract, not the behaviour.

Reading the output

What you see depends on which build is running. The deployed PLC runs the simulation build, so expect the second column.

	Field build, nothing driving the inputs	Simulation build (deployed)
%IW / %IX	all 0 / False	all 0 / False — the mux takes simulated values instead
Pumps	tripped (%QX1.4-1.6 True) — thermal-healthy reads FALSE	running normally
%QW17 alarm word	16500 — thermals, mains and LSLL all reading unhealthy	0
%QW5 / %QW6	32767, the CFG_NO_TIME sentinel	32767 while drawing down, a real countdown while filling
%QW11	720 — 120 m² × 6.0 m, the plant geometry	falls as the well fills
%MW block	the seeded defaults	whatever was last written — operators retune these live

In the field build, tripped pumps and a non-zero alarm word are the program responding correctly to an all-zero field. It is not broken.

%MW is worth stressing: IO_MUX seeds the defaults once on first scan, and nothing overwrites them afterwards, so a live system shows the tuning someone last wrote — not the values in 03-plc/src/10_globals.st. See 03-plc/README.md.

fake_plc.py — testing the SCADA side without a PLC

python fake_plc.py --serve --port 502    # serve known values
python fake_plc.py --expect              # print what CI Server should show

Why it exists. Everything downstream of the register map — CI Server's Modbus configuration, the conversions, the item bindings, the display masks — had only ever been checked against the simulation, whose values are plausible. Plausible is exactly what you cannot verify: a level of 70% looks right whether it came from the correct register or the one beside it.

So it serves distinctive values instead. Every register gets a different one; none round, none equal to a neighbour, and the pattern is deterministic — the same seed gives the same numbers, so expected_readings.txt can be printed on a machine that cannot reach the server.

Stdlib only, deliberately: it writes the MBAP header by hand rather than requiring pymodbus on a host you may not want to install packages on.

Speaks FC01, FC02, FC03, FC04, FC06 and FC16. Writes are accepted and stored, so a setpoint written from CI Server reads back.

File	What
fake_values.json	the served values, so they can be regenerated or inspected
expected_readings.txt	what CI Server should display, item by item, seed 20260814

Caution

Do not run fake_plc.py on port 502 of the live host. The real PLC is serving there and CI Server is polling it. Use a spare port, or stop the container first and remember that stopping it stops the demo.

Notes

• %QW17 is decoded unsigned; bit 15 does not fit a signed INT. Every other register is treated as signed, per the map — including %QW7, which genuinely goes negative.
• --write-test writes each RW point back with the value it already holds. No value changes. See the caveat in the script docstring about %MW1, the command word — a non-zero value there is a live command.
• If everything fails to connect, the cause is usually not this harness. The runtime opens its Modbus slave only while a program is running, and only if the Editor project defines a Modbus Server. See 03-plc/DEPLOY.md §A3. A refusal looks like a firewall drop and is not: Docker DNATs to the container, which returns RST because nothing is bound inside.

Verified 2026-09-02

fake_plc.py served on a spare port and verify_modbus.py read it end to end:

read     : 69/69 points OK
writable : 15/15 RW points OK
PASS     : the runtime matches the register map

Both tools work against the current 69-point map.