S7 integration fixture — python-snap7 server closes the wire-level coverage gap (#216) + per-driver fixture coverage docs for every driver in the fleet. Closes #216. Two shipments in one PR because the docs landed as I surveyed each driver's fixture + the S7 work is the first wire-level-gap closer pulled from that survey.
S7 integration — AbCip/Modbus already have real-simulator integration suites; S7 had zero wire-level coverage despite being a Tier-A driver (all unit tests mocked IS7Client). Picked python-snap7's `snap7.server.Server` over raw Snap7 C library because `pip install` beats per-OS binary-pin maintenance, the package ships a Python __main__ shim that mirrors our existing pymodbus serve.ps1 + *.json pattern structurally, and the python-snap7 project is actively maintained. New project `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/` with four moving parts: (a) `Snap7ServerFixture` — collection-scoped TCP probe on `localhost:1102` that sets `SkipReason` when the simulator's not running, matching the `ModbusSimulatorFixture` shape one directory over (same S7_SIM_ENDPOINT env var override convention for pointing at a real S7 CPU on port 102); (b) `PythonSnap7/` — `serve.ps1` wrapper + `server.py` shim + `s7_1500.json` seed profile + `README.md` documenting install / run / known limitations; (c) `S7_1500/S7_1500Profile.cs` — driver-side `S7DriverOptions` whose tag addresses map 1:1 to the JSON profile's seed offsets (DB1.DBW0 u16, DB1.DBW10 i16, DB1.DBD20 i32, DB1.DBD30 f32, DB1.DBX50.3 bool, DB1.DBW100 scratch); (d) `S7_1500SmokeTests` — three tests proving typed reads + write-then-read round-trip work through real S7netplus + real ISO-on-TCP + real snap7 server. Picked port 1102 default instead of S7-standard 102 because 102 is privileged on Linux + triggers Windows Firewall prompt; S7netplus 0.20 has a 5-arg `Plc(CpuType, host, port, rack, slot)` ctor that lets the driver honour `S7DriverOptions.Port`, but the existing driver code called the 4-arg overload + silently hardcoded 102. One-line driver fix (S7Driver.cs:87) threads `_options.Port` through — the S7 unit suite (58/58) still passes unchanged because every unit test uses a fake IS7Client that never sees the real ctor. Server seed-type matrix in `server.py` covers u8 / i8 / u16 / i16 / u32 / i32 / f32 / bool-with-bit / ascii (S7 STRING with max_len header). register_area takes the SrvArea enum value, not the string name — a 15-minute debug after the first test run caught that; documented inline. Per-driver test-fixture coverage docs — eight new files in `docs/drivers/` laying out what each driver's harness actually benchmarks vs. what's trusted from field deployments. Pattern mirrors the AbServer-Test-Fixture.md doc that shipped earlier in this arc: TL;DR → What the fixture is → What it actually covers → What it does NOT cover → When-to-trust table → Follow-up candidates → Key files. Ugly truth the survey made visible: Galaxy + Modbus + (now) S7 + AB CIP have real wire-level coverage; AB Legacy / TwinCAT / FOCAS / OpcUaClient are still contract-only because their libraries ship no fake + no open-source simulator exists (AB Legacy PCCC), no public simulator exists (FOCAS), the vendor SDK has no in-process fake (TwinCAT/ADS.NET), or the test wiring just hasn't happened yet (OpcUaClient could trivially loopback against this repo's own server — flagged as #215). Each doc names the specific follow-up route: Snap7 server for S7 (done), TwinCAT 3 developer-runtime auto-restart for TwinCAT, Tier-C out-of-process Host for FOCAS, lab rigs for AB Legacy + hardware-gated bits of the others. `docs/drivers/README.md` gains a coverage-map section linking all eight. Tracking tasks #215-#222 filed for each PR-able follow-up. Build clean (driver + integration project + docs); S7.Tests 58/58 (unchanged); S7.IntegrationTests 3/3 (new, verified end-to-end against a live python-snap7 server: `driver_reads_seeded_u16_through_real_S7comm`, `driver_reads_seeded_typed_batch`, `driver_write_then_read_round_trip_on_scratch_word`). Next fixture follow-up is #215 (OpcUaClient loopback against own server) — highest ROI of the remaining set, zero external deps. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,110 @@
|
||||
# python-snap7 server profiles
|
||||
|
||||
JSON-driven seed profiles for `snap7.server.Server` from
|
||||
[python-snap7](https://github.com/gijzelaerr/python-snap7) (MIT). Shape
|
||||
mirrors the pymodbus profiles under
|
||||
`tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Pymodbus/` — a
|
||||
PowerShell launcher + per-family JSON + a Python shim that the launcher
|
||||
exec's.
|
||||
|
||||
| File | What it seeds | Test category |
|
||||
|---|---|---|
|
||||
| [`s7_1500.json`](s7_1500.json) | DB1 (1024 bytes) with smoke values at known offsets (i16 @ DBW10, i32 @ DBD20, f32 @ DBD30, bool @ DBX50.3, scratch word @ DBW100, STRING "Hello" @ 200) + MB (256 bytes) with probe marker at MW0. | `Trait=Integration, Device=S7_1500` |
|
||||
|
||||
Default port **1102** (non-privileged; sidesteps Windows Firewall prompt +
|
||||
Linux's root-required bind on port 102). The fixture
|
||||
(`Snap7ServerFixture`) defaults to `localhost:1102`. Override via
|
||||
`S7_SIM_ENDPOINT` to point at a real S7 CPU on port 102. The S7 driver
|
||||
threads `_options.Port` through to S7netplus's 5-arg `Plc` ctor, so the
|
||||
non-standard port works end-to-end.
|
||||
|
||||
## Install
|
||||
|
||||
```powershell
|
||||
pip install "python-snap7>=2.0"
|
||||
```
|
||||
|
||||
`python-snap7` wraps the upstream `snap7` C library; the install pulls
|
||||
platform-specific binaries automatically. Requires Python ≥ 3.10.
|
||||
Windows Firewall will prompt on first bind; allow Private network.
|
||||
|
||||
## Run
|
||||
|
||||
Foreground (Ctrl+C to stop):
|
||||
|
||||
```powershell
|
||||
.\serve.ps1 -Profile s7_1500
|
||||
```
|
||||
|
||||
Non-default port:
|
||||
|
||||
```powershell
|
||||
.\serve.ps1 -Profile s7_1500 -Port 102
|
||||
```
|
||||
|
||||
Or invoke the Python shim directly:
|
||||
|
||||
```powershell
|
||||
python .\server.py .\s7_1500.json --port 1102
|
||||
```
|
||||
|
||||
## Run the integration tests
|
||||
|
||||
In a separate shell with the simulator running:
|
||||
|
||||
```powershell
|
||||
cd C:\Users\dohertj2\Desktop\lmxopcua
|
||||
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests
|
||||
```
|
||||
|
||||
Tests auto-skip with a clear `SkipReason` when `localhost:1102` isn't
|
||||
reachable within 2 seconds.
|
||||
|
||||
## What's encoded in `s7_1500.json`
|
||||
|
||||
| Address | Type | Seed | Purpose |
|
||||
|---|---|---|---|
|
||||
| `DB1.DBW0` | u16 | `4242` | read-back probe |
|
||||
| `DB1.DBW10` | i16 | `-12345` | smoke i16 read |
|
||||
| `DB1.DBD20` | i32 | `1234567890` | smoke i32 read |
|
||||
| `DB1.DBD30` | f32 | `3.14159` | smoke f32 read (big-endian) |
|
||||
| `DB1.DBX50.3` | bool | `true` | smoke bool read at bit 3 |
|
||||
| `DB1.DBW100` | u16 | `0` | scratch for write-then-read |
|
||||
| `DB1.STRING[200]` | S7 STRING | `"Hello"` (max 32, cur 5) | smoke string read |
|
||||
| `MW0` | u16 | `1` | `S7ProbeOptions.ProbeAddress` default |
|
||||
|
||||
Seed types supported by `server.py`: `u8`, `i8`, `u16`, `i16`, `u32`,
|
||||
`i32`, `f32`, `bool` (with `"bit": 0..7`), `ascii` (S7 STRING type with
|
||||
configurable `max_len`).
|
||||
|
||||
## Known limitations (python-snap7 upstream)
|
||||
|
||||
The `snap7.server.Server` docstring admits:
|
||||
|
||||
> "Legacy S7 server implementation. Emulates a Siemens S7 PLC for testing
|
||||
> and development purposes. [...] pure Python emulator implementation that
|
||||
> simulates PLC behaviour for protocol compliance testing rather than
|
||||
> full industrial-grade functionality."
|
||||
|
||||
What that means in practice — things this fixture does NOT cover:
|
||||
|
||||
- **S7-1500 Optimized-DB symbolic access** — the real S7-1500 with TIA Portal
|
||||
optimization enabled uses symbolic addressing that's wire-incompatible with
|
||||
absolute DB addressing. Our driver targets non-optimized DBs; so does
|
||||
snap7's server. Rig test required to verify against an Optimized CPU.
|
||||
- **PG / OP / S7-Basic session types** — S7netplus uses OP session; the
|
||||
simulator accepts whatever session type is requested, unlike real CPUs
|
||||
that allocate session slots differently.
|
||||
- **SCL variant-specific behaviour** — e.g. S7-1200 missing certain PDU
|
||||
types, S7-300's older handshake, S7-400 multi-CPU racks with non-zero
|
||||
slot. Simulator collapses all into one generic CPU emulation.
|
||||
- **PUT/GET-disabled-by-default** — real S7-1200/1500 CPUs refuse reads
|
||||
when PUT/GET is off in TIA Portal hardware config; the driver maps that
|
||||
to `BadDeviceFailure`. Simulator has no such toggle + always accepts.
|
||||
|
||||
## References
|
||||
|
||||
- [python-snap7 GitHub](https://github.com/gijzelaerr/python-snap7) — source + install
|
||||
- [snap7.server API](https://python-snap7.readthedocs.io/en/latest/API/server.html) — `Server` class reference
|
||||
- [`docs/drivers/S7-Test-Fixture.md`](../../../docs/drivers/S7-Test-Fixture.md) — coverage map + gap inventory
|
||||
- [`docs/v2/s7.md`](../../../docs/v2/s7.md) — driver-side addressing + family notes
|
||||
Reference in New Issue
Block a user