178 lines
8.6 KiB
Markdown
178 lines
8.6 KiB
Markdown
# AB Legacy test fixture
|
|
|
|
Coverage map + gap inventory for the AB Legacy (PCCC) driver — SLC 500 /
|
|
MicroLogix / PLC-5 / LogixPccc-mode.
|
|
|
|
**TL;DR:** Docker integration-test scaffolding lives at
|
|
`tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/` (task #224),
|
|
reusing the AB CIP `ab_server` image in PCCC mode with per-family
|
|
compose profiles (`slc500` / `micrologix` / `plc5`). Scaffold passes
|
|
the skip-when-absent contract cleanly. **Wire-level round-trip against
|
|
`ab_server` PCCC mode currently fails** with `BadCommunicationError`
|
|
on read/write (verified 2026-04-20) — ab_server's PCCC server-side
|
|
coverage is narrower than libplctag's PCCC client expects. The smoke
|
|
tests target the correct shape for real hardware + should pass when
|
|
`AB_LEGACY_ENDPOINT` points at a real SLC 5/05 / MicroLogix. Unit tests
|
|
via `FakeAbLegacyTag` still carry the contract coverage.
|
|
|
|
## What the fixture is
|
|
|
|
**Integration layer** (task #224, scaffolded with a known ab_server
|
|
gap):
|
|
`tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/` with
|
|
`AbLegacyServerFixture` (TCP-probes `localhost:44818`) + three smoke
|
|
tests (parametric read across families, SLC500 write-then-read). Reuses
|
|
the AB CIP `otopcua-ab-server:libplctag-release` image via a relative
|
|
`build:` context in `Docker/docker-compose.yml` — one image, different
|
|
`--plc` flags. See `Docker/README.md` §Known limitations for the
|
|
ab_server PCCC round-trip gap + resolution paths.
|
|
|
|
**Unit layer**: `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/` is
|
|
still the primary coverage. All tests tagged `[Trait("Category", "Unit")]`.
|
|
The driver accepts `IAbLegacyTagFactory` via ctor DI; every test
|
|
supplies a `FakeAbLegacyTag`.
|
|
|
|
## What it actually covers (unit only)
|
|
|
|
- `AbLegacyAddressTests` — PCCC address parsing for SLC / MicroLogix / PLC-5
|
|
/ LogixPccc-mode (`N7:0`, `F8:12`, `B3:0/5`, etc.)
|
|
- `AbLegacyArrayTests` — PR 7 array contiguous-block addressing: parser
|
|
positives + rejects for `,N` / `[N]` suffixes, options-override
|
|
(`ArrayLength`), driver `IsArray` discovery, and array decoding for N / F /
|
|
L / B files (Rockwell convention: one BOOL per word for `B3:0,10`). Latency
|
|
benchmark against the Docker fixture is a perf-flagged integration case in
|
|
`AbLegacyArrayReadTests` — runs only when ab_server is reachable.
|
|
- `AbLegacyCapabilityTests` — data type mapping, read-only enforcement
|
|
- `AbLegacyReadWriteTests` — read + write happy + error paths against the fake
|
|
- `AbLegacyBitRmwTests` — bit-within-DINT read-modify-write serialization via
|
|
per-parent `SemaphoreSlim` (mirrors the AB CIP + FOCAS PMC-bit pattern from #181)
|
|
- `AbLegacyHostAndStatusTests` — probe + host-status transitions driven by
|
|
fake-returned statuses
|
|
- `AbLegacyDriverTests` — `IDriver` lifecycle
|
|
- `AbLegacyDiagnosticsTests` — PR ablegacy-10 / #253 per-device diagnostic
|
|
counters: 5 reads (3 ok / 2 fail) → `RequestCount=5`, `ResponseCount=3`,
|
|
`ErrorCount=2`; `LastErrorCode` reflects the most recent libplctag status;
|
|
`RetryCount` increments per retry attempt beyond the first; counters reset
|
|
on `ReinitializeAsync`; discovery emits exactly 7 diagnostic variables per
|
|
device under `_Diagnostics/`; collision rejection at `InitializeAsync` for
|
|
user tags shadowing reserved names or `_Diagnostics/` addresses; the
|
|
`_Diagnostics/<host>/<name>` short-circuit returns the live snapshot through
|
|
`ReadAsync` without bumping `RequestCount`; two devices keep counters
|
|
independent.
|
|
- `AbLegacyDeadbandTests` — PR 8 per-tag deadband / change filter:
|
|
absolute-only suppression sequence `[10.0, 10.5, 11.5, 11.6] -> [10.0, 11.5]`,
|
|
percent-only suppression with a zero-prev short-circuit, both-set logical-OR
|
|
semantics (Kepware), Boolean edge-only publish, string change-only publish,
|
|
status-change always-publish, first-seen always-publish, ReinitializeAsync
|
|
cache wipe, JSON DTO round-trip.
|
|
|
|
Capability surfaces whose contract is verified: `IDriver`, `IReadable`,
|
|
`IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`,
|
|
`IPerCallHostResolver`.
|
|
|
|
## What it does NOT cover
|
|
|
|
### 1. Wire-level PCCC
|
|
|
|
No PCCC frame is sent by the test suite. libplctag's PCCC subset (DF1,
|
|
ControlNet-over-EtherNet, PLC-5 native EtherNet) is untested here;
|
|
driver-side correctness depends on libplctag being correct.
|
|
|
|
### 2. Family-specific behavior
|
|
|
|
- SLC 500 timeout + retry thresholds (SLC's comm module has known slow-response
|
|
edges) — unit fakes don't simulate timing.
|
|
- MicroLogix 1100 / 1400 max-connection-count limits — not stressed.
|
|
- PLC-5 native EtherNet connection setup (PCCC-encapsulated-in-CIP vs raw
|
|
CSPv4) — routing covered at parse level only.
|
|
|
|
### 3. Multi-device routing
|
|
|
|
`IPerCallHostResolver` contract is verified; real PCCC wire routing across
|
|
multiple gateways is not.
|
|
|
|
### 4. Alarms / history
|
|
|
|
PCCC has no alarm object + no history object. Driver doesn't implement
|
|
`IAlarmSource` or `IHistoryProvider` — no test coverage is the correct shape.
|
|
|
|
### 5. File-type coverage
|
|
|
|
PCCC has many file types (N, F, B, T, C, R, S, ST, A) — the parser tests
|
|
cover the common ones but uncommon ones (`R` counters, `S` status files,
|
|
`A` ASCII strings) have thin coverage.
|
|
|
|
## When to trust AB Legacy tests, when to reach for a rig
|
|
|
|
| Question | Unit tests | Real PLC |
|
|
| --- | --- | --- |
|
|
| "Does `N7:0/5` parse correctly?" | yes | - |
|
|
| "Does bit-in-word RMW serialize concurrent writers?" | yes | yes |
|
|
| "Does the driver lifecycle hang / crash?" | yes | yes |
|
|
| "Does a real read against an SLC 500 return correct bytes?" | no | yes (required) |
|
|
| "Does MicroLogix 1100 respect its connection-count cap?" | no | yes (required) |
|
|
| "Do PLC-5 ST-files round-trip correctly?" | no | yes (required) |
|
|
|
|
## Follow-up candidates
|
|
|
|
1. **Expand ab_server PCCC coverage** — the smoke suite passes today
|
|
for N (Int16), F (Float32), and L (Int32) files across SLC500 /
|
|
MicroLogix / PLC-5 modes with the `/1,0` cip-path workaround in
|
|
place. Known residual gap: bit-file writes (`B3:0/5`) surface
|
|
`0x803D0000`. Contributing a patch to `libplctag/libplctag` to close
|
|
this + documenting ab_server's empty-path rejection in its README
|
|
would remove the last Docker-vs-hardware divergences.
|
|
2. **Rockwell RSEmulate 500 golden-box tier** — Rockwell's real emulator
|
|
for SLC/MicroLogix/PLC-5. Would close UDT-equivalent (integer-file
|
|
indirection), timer/counter decomposition, and real ladder execution
|
|
gaps. Costs: RSLinx OEM license, Windows-only, Hyper-V conflict
|
|
matching TwinCAT XAR + Logix Emulate, no clean PR-diffable project
|
|
format (SLC/ML save as binary `.RSS`). Scaffold like the Logix
|
|
Emulate tier when operationally worth it.
|
|
3. **Lab rig** — used SLC 5/05 or MicroLogix 1100 on a dedicated
|
|
network; parts are end-of-life but still available. PLC-5 +
|
|
LogixPccc-mode behaviour + DF1 serial need specific controllers.
|
|
|
|
## Per-device options (`AbLegacyDeviceOptions`)
|
|
|
|
Each entry in `AbLegacyDriverOptions.Devices` carries:
|
|
|
|
| Field | Type | Default | Notes |
|
|
|---|---|---|---|
|
|
| `HostAddress` | string | required | `ab://host[:port]/cip-path` |
|
|
| `PlcFamily` | enum | `Slc500` | Slc500 / MicroLogix / Plc5 / LogixPccc |
|
|
| `DeviceName` | string | null | Friendly label used in browse + diagnostics |
|
|
| `Timeout` | TimeSpan? | null → driver-wide default | **PR 9 / #252** — wins over the driver-wide `Timeout`. Mix-and-match: SLC 5/01 ≈ 5 s, SLC 5/05 ≈ 2 s, MicroLogix 1100 ≈ 3 s |
|
|
| `Retries` | int? | null → driver-wide default → 0 | **PR 9 / #252** — retries on transient `BadCommunicationError`; terminal errors surface on the first attempt |
|
|
|
|
JSON shape (mirrored on `AbLegacyDeviceDto`):
|
|
|
|
```json
|
|
{
|
|
"HostAddress": "ab://192.168.1.10/1,0",
|
|
"PlcFamily": "Slc500",
|
|
"DeviceName": "slc-5-01-line-A",
|
|
"TimeoutMs": 5000,
|
|
"Retries": 1
|
|
}
|
|
```
|
|
|
|
Per-device overrides also flow into the probe loop — slow chassis won't be
|
|
falsely marked Stopped just because the driver-wide probe timeout is tight.
|
|
|
|
## Key fixture / config files
|
|
|
|
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyServerFixture.cs`
|
|
— TCP probe + skip attributes + env-var parsing
|
|
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyReadSmokeTests.cs`
|
|
— wire-level smoke tests; pass against the ab_server Docker fixture
|
|
with `AB_LEGACY_COMPOSE_PROFILE` set to the running container
|
|
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml`
|
|
— compose profiles reusing AB CIP Dockerfile
|
|
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/README.md`
|
|
— known-limitations write-up + resolution paths
|
|
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/FakeAbLegacyTag.cs` —
|
|
in-process fake + factory
|
|
- `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — scope remarks
|
|
at the top of the file
|