# 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.

```bash
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:

```bash
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

```bash
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.