Files

Joseph Doherty fdb268cee0 Docs + code-comment sweep — remove stale Pymodbus/ + PythonSnap7/ + LocateBinary references left behind by the native-fallback removal PR. Answer to "is the dev inventory + documentation updated": it was partial; this PR finishes the job.

Files touched — docs/drivers/Modbus-Test-Fixture.md dropped the key-files pointer at deleted Pymodbus/ + flipped "primary launcher is Docker, native fallback retained" framing to "Docker is the only supported launch path" (matching the code). docs/v2/dev-environment.md dropped the "skips both Docker + native-binary paths" parenthetical from AB_SERVER_ENDPOINT + flipped the "Native fallbacks" subsection to a one-liner that says Docker is the only supported path. docs/v2/modbus-test-plan.md rewrote §Harness from "pip install pymodbus + serve.ps1" setup pattern to "docker compose --profile <…> up" + updated the §PR 43 status bullet to point at Docker/profiles/. docs/v2/test-data-sources.md §"CI fixture (task #180)" rewrote the AB CIP section from "LocateBinary() picks binary off PATH" + GitHub Actions zip-download step to "Docker is the only supported reproducible build path" + docker compose GitHub Actions step; dropped the pinned-version SHA256 table + lock-file reference because the Dockerfile's LIBPLCTAG_TAG build-arg is the new pin.

Code docstrings + error messages — these are developer-facing operational text too. ModbusSimulatorFixture SkipReason strings (both branches) now point at `docker compose -f Docker/docker-compose.yml --profile standard up -d` instead of the deleted `Pymodbus\serve.ps1`; doc-comment at the top references Docker/docker-compose.yml. Snap7ServerFixture SkipReason strings + doc-comment point at Docker/docker-compose.yml instead of PythonSnap7/serve.ps1. S7_1500Profile.cs docstring updated. Modbus Dockerfile comment pointing at deleted tests/.../Pymodbus/README.md redirected to docs/drivers/Modbus-Test-Fixture.md. DL205Profile.cs + DL205StringQuirkTests.cs + S7_1500Profile.cs (in Modbus project) docstrings flipped from Pymodbus/*.json references to Docker/profiles/*.json.

Left untouched deliberately: docs/v2/implementation/exit-gate-phase-2-closed.md — that's a historical as-of-2026-04-18 snapshot documenting what was skipped at Phase 2 closure; rewriting would lose the date-stamped context. Its "oitc/modbus-server Docker container not started" + "ab_server binary not on PATH" lines describe the fixture landscape that existed at close time, not current operational guidance.

Final sweep confirms zero remaining `Pymodbus/` / `PythonSnap7/` / `LocateBinary` / `AbServerSeedTag` / `BuildCliArgs` / `AbServerPlcArg` mentions anywhere in tracked files outside that historical exit-gate doc. Whole-solution build still 0 errors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-20 12:36:19 -04:00

8.0 KiB

Raw Blame History

Modbus driver — test plan + device-quirk catalog

The Modbus TCP driver unit tests (PRs 21–24) cover the protocol surface against an in-memory fake transport. They validate the codec, state machine, and function-code routing against a textbook Modbus server. That's necessary but not sufficient: real PLC populations disagree with the spec in small, device-specific ways, and a driver that passes textbook tests can still misbehave against actual equipment.

This doc is the harness-and-quirks playbook. The project it describes lives at tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/ — scaffolded in PR 30 with the simulator fixture, DL205 profile stub, and one write/read smoke test. Each confirmed DL205 quirk lands in a follow-up PR as a named test in that project.

Harness

Chosen simulator: pymodbus 3.13.0 packaged as a pinned Docker image under tests/.../Modbus.IntegrationTests/Docker/. See that folder's README.md for image-build notes + compose profiles. Headline reasons:

Headless pure-Python CLI; no Java GUI, runs cleanly on a CI runner.
Maintained — current stable 3.13.0; ModbusPal 1.6b is abandoned.
All four standard tables (HR, IR, coils, DI) configurable; ModbusPal 1.6b only exposed HR + coils.
Built-in actions (increment, random, timestamp, uptime) + optional custom-Python actions for declarative dynamic behaviors.
Per-register raw uint16 seeding — encoding the DL205 string-byte-order / BCD / CDAB-float quirks stays explicit (the quirk math lives in the _quirk JSON-comment fields next to each register).
Dockerized — pinned image means the CI simulator surface is reproducible + no pip install step on the dev box.
Defaults to TCP 5020 (matches the compose port-map + the fixture default endpoint; sidesteps the Windows Firewall prompt on 502).

Setup pattern:

docker compose -f tests\...\Modbus.IntegrationTests\Docker\docker-compose.yml --profile <standard|dl205|mitsubishi|s7_1500> up -d.
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests — tests auto-skip when the endpoint is unreachable. Default endpoint is localhost:5020; override via MODBUS_SIM_ENDPOINT for a real PLC on its native port 502.
docker compose -f ... --profile <…> down when finished.

Per-device quirk catalog

AutomationDirect DL205 / DL260

First known target device family. Full quirk catalog with primary-source citations and per-quirk integration-test names lives at dl205.md — that doc is the reference; this section is the testing roadmap.

Confirmed quirks (priority order — top items are highest-impact for our driver and ship first as PR 41+):

Quirk	Driver impact	Integration-test name
String packing: 2 chars/register, first char in low byte (opposite of generic Modbus)	`ModbusDataType.String` decoder must be configurable per-device family — current code assumes high-byte-first	`DL205_String_low_byte_first_within_register`
Word order CDAB for Int32/UInt32/Float32	Already configurable via `ModbusByteOrder.WordSwap`; default per device profile	`DL205_Int32_word_order_is_CDAB`
BCD-as-default numeric storage (only IEEE 754 when ladder uses `R` type)	New decoder mode — register reads as `0x1234` for ladder value `1234`, not as decimal `4660`	`DL205_BCD_register_decodes_as_hex_nibbles`
FC16 capped at 100 registers (below the spec's 123)	Bulk-write batching must cap per-device-family	`DL205_FC16_101_registers_returns_IllegalDataValue`
FC03/04 capped at 128 (above the spec's 125)	Less impactful — clients that respect the spec's 125 stay safe	`DL205_FC03_129_registers_returns_IllegalDataValue`
V-memory octal-to-decimal addressing (V2000 octal → 0x0400 decimal)	New address-format helper in profile config so operators can write `V2000` instead of computing `1024` themselves	`DL205_Vmem_V2000_maps_to_PDU_0x0400`
C-relay → coil 3072 / Y-output → coil 2048 offsets	Hard-coded constants in DL205 device profile	`DL205_C0_maps_to_coil_3072`, `DL205_Y0_maps_to_coil_2048`
Register 0 is valid (rejects-register-0 rumour was DL05/DL06 relative-mode artefact)	None — current default is safe	`DL205_FC03_register_0_returns_V0_contents`
Max 4 simultaneous TCP clients on H2-ECOM100	Connect-time: handle TCP-accept failure with a clearer error message	`DL205_5th_TCP_connection_refused`
No TCP keepalive	Driver-side periodic-probe (already wired via `IHostConnectivityProbe`)	Covered by existing `ModbusProbeTests`
No mid-stream resync on malformed MBAP	Already covered — single-flight + reconnect-on-error	Covered by existing `ModbusDriverTests`
Write-protect exception code: `02` newer / `04` older	Translate either to `BadNotWritable`	`DL205_FC06_in_ProgramMode_returns_ServerFailure`

Operator-reported / unconfirmed — covered defensively in the driver but no integration tests until reproduced on hardware:

TxId drop under load (forum rumour; not reproduced).
Pre-2004 firmware ABCD word order (every shipped DL205/DL260 since 2004 is CDAB).

Future devices

One section per device class, same shape as DL205. Quirks that apply across multiple devices (e.g., "all AB PLCs use CDAB") can be noted in the cross-device patterns section below once we have enough data points.

Cross-device patterns

Once multiple device catalogs accumulate, quirks that recur across two or more vendors get promoted into driver defaults or opt-in options:

(empty — filled in as catalogs grow)

Test conventions

One named test per quirk. DL205_word_order_is_CDAB_for_Float32 is easier to diagnose on failure than a generic Float32_roundtrip. The DL205_ prefix makes filtering by device class trivial (--filter "DisplayName~DL205").
Skip with a clear SkipReason. Follow the pattern from GalaxyRepositoryLiveSmokeTests: check reachability in the fixture, capture a SkipReason string, and have each test call Assert.Skip(SkipReason) when it's set. Don't throw — skipped tests read cleanly in CI logs.
Use the real ModbusTcpTransport. Integration tests exercise the wire protocol end-to-end. The in-memory FakeTransport from the unit test suite is deliberately not used here — its value is speed + determinism, which doesn't help reproduce device-specific issues.
Don't depend on simulator state between tests. Each test resets the simulator's register bank or uses a unique address range. Avoid relying on "previous test left value at register 10" setups that flake when tests run in parallel or re-order. Either the test mutates the scratch ranges and restores on finally, or it uses pymodbus's REST API to reset state between facts.

Next concrete PRs

PR 30 — Integration test project + DL205 profile scaffold — DONE. Shipped tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests with ModbusSimulatorFixture (TCP-probe, skips with a clear SkipReason when the endpoint is unreachable), DL205/DL205Profile.cs (tag map stub), and DL205/DL205SmokeTests.cs (write-then-read round-trip).
PR 41 — DL205 quirk catalog doc — DONE. docs/v2/dl205.md documents every DL205/DL260 Modbus divergence with primary-source citations.
PR 42 — ModbusPal .xmpp profiles — SUPERSEDED by PR 43. Replaced with pymodbus JSON because ModbusPal 1.6b is abandoned, GUI-only, and only exposes 2 of the 4 standard tables.
PR 43 — pymodbus JSON profiles — DONE. Dockerized under Docker/profiles/ (standard.json, dl205.json, mitsubishi.json, s7_1500.json); compose file launches each via a named profile. All bind TCP 5020.
PR 44+: one PR per confirmed DL205 quirk, landing the named test + any driver-side adjustment (string byte order, BCD decoder, V-memory address helper, FC16 cap-per-device-family) needed to pass it. Each quirk's value is already pre-encoded in Docker/profiles/dl205.json.

8.0 KiB Raw Blame History Unescape Escape