95c7e0b490
Replaced the "ab_server PCCC upstream-broken" skip gate with the actual
root cause: libplctag's ab_server rejects empty CIP routing paths at the
unconnected-send layer before the PCCC dispatcher runs. Real SLC/
MicroLogix/PLC-5 hardware accepts empty paths (no backplane); ab_server
does not. With `/1,0` in place, N (Int16), F (Float32), and L (Int32)
file reads + writes round-trip cleanly across all three compose profiles.
## Fixture changes
- `AbLegacyServerFixture.cs`:
- Drop `AB_LEGACY_TRUST_WIRE` env var + the reachable-but-untrusted
skip branch. Fixture now only skips on TCP unreachability.
- Add `AB_LEGACY_CIP_PATH` env var (default `1,0`) + expose `CipPath`
property. Set `AB_LEGACY_CIP_PATH=` (empty) against real hardware.
- Shorter skip messages on the `[AbLegacyFact]` / `[AbLegacyTheory]`
attributes — one reason: endpoint not reachable.
- `AbLegacyReadSmokeTests.cs`:
- Device URI built from `sim.CipPath` instead of hardcoded empty path.
- New `AB_LEGACY_COMPOSE_PROFILE` env var filters the parametric
theory to the running container's family. Only one container binds
`:44818` at a time, so cross-family params would otherwise fail.
- `Slc500_write_then_read_round_trip` skips cleanly when the running
profile isn't `slc500`.
## E2E + seed + docs
- `scripts/e2e/test-ablegacy.ps1` — drop the `AB_LEGACY_TRUST_WIRE`
skip gate; synopsis calls out the `/1,0` vs empty cip-path split
between the Docker fixture and real hardware.
- `scripts/e2e/e2e-config.sample.json` — sample gateway flipped from
the hardware placeholder (`192.168.1.10`) to the Docker fixture
(`127.0.0.1/1,0`); comment rewritten.
- `scripts/e2e/README.md` — AB Legacy expected-matrix row goes from
SKIP to PASS.
- `scripts/smoke/seed-ablegacy-smoke.sql` — default HostAddress points
at the Docker fixture + header / footer text reflect the new state.
- `tests/.../Docker/README.md` — "Known limitations" section rewritten
to describe the cip-path gate (not a dispatcher gap); env-var table
picks up `AB_LEGACY_CIP_PATH` + `AB_LEGACY_COMPOSE_PROFILE`.
- `docs/drivers/AbLegacy-Test-Fixture.md` + `docs/drivers/README.md`
+ `docs/DriverClis.md` — flip status from blocked to functional;
residual bit-file-write gap (B3:0/5 → 0x803D0000) documented.
## Residual gap
Bit-file writes (`B3:0/5` style) surface `0x803D0000` against
`ab_server --plc=SLC500`; bit reads work. Non-blocking for smoke
coverage — N/F/L round-trip is enough. Real hardware / RSEmulate 500
for bit-write fidelity. Documented in `Docker/README.md` §"Known
limitations" + the `AbLegacy-Test-Fixture.md` follow-ups list.
## Verified
- Full-solution build: 0 errors, 334 pre-existing warnings.
- Integration suite passes per-profile with
`AB_LEGACY_COMPOSE_PROFILE=<slc500|micrologix|plc5>` + matching
compose container up.
- All four non-hardware e2e scripts (Modbus / AB CIP / AB Legacy / S7)
now 5/5 against the respective docker-compose fixtures.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
152 lines
6.9 KiB
Markdown
152 lines
6.9 KiB
Markdown
# AB Legacy PCCC integration-test fixture — `ab_server` (Docker)
|
|
|
|
[libplctag](https://github.com/libplctag/libplctag)'s `ab_server` supports
|
|
both CIP (ControlLogix / CompactLogix / Micro800) and PCCC (SLC 500 /
|
|
MicroLogix / PLC-5) families from one binary. This fixture reuses the AB
|
|
CIP Docker image (`otopcua-ab-server:libplctag-release`) with different
|
|
`--plc` flags. No new Dockerfile needed — the compose file's `build:`
|
|
block points at the AB CIP `Docker/` folder so `docker compose build`
|
|
from here reuses the same multi-stage build.
|
|
|
|
**Docker is the only supported launch path**; a fresh clone needs Docker
|
|
Desktop and nothing else.
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| [`docker-compose.yml`](docker-compose.yml) | Three per-family services (`slc500` / `micrologix` / `plc5`); all bind `:44818` |
|
|
|
|
## Run
|
|
|
|
From the repo root:
|
|
|
|
```powershell
|
|
# SLC 500 family — widest PCCC coverage
|
|
docker compose -f tests\ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests\Docker\docker-compose.yml --profile slc500 up
|
|
|
|
# Per-family
|
|
docker compose -f tests\...\Docker\docker-compose.yml --profile micrologix up
|
|
docker compose -f tests\...\Docker\docker-compose.yml --profile plc5 up
|
|
```
|
|
|
|
Detached + stop:
|
|
|
|
```powershell
|
|
docker compose -f tests\...\Docker\docker-compose.yml --profile slc500 up -d
|
|
docker compose -f tests\...\Docker\docker-compose.yml --profile slc500 down
|
|
```
|
|
|
|
First run builds the `otopcua-ab-server:libplctag-release` image (~3-5
|
|
min — clones libplctag + compiles `ab_server`). If the AB CIP fixture
|
|
already built the image locally, docker reuses the cached layers + this
|
|
runs in seconds. Only one family binds `:44818` at a time; to switch
|
|
families stop the current service + start another.
|
|
|
|
## Endpoint
|
|
|
|
- Default: `localhost:44818` (EtherNet/IP standard)
|
|
- Override with `AB_LEGACY_ENDPOINT=host:port` to point at a real SLC /
|
|
MicroLogix / PLC-5 PLC on its native port.
|
|
|
|
## Env vars
|
|
|
|
| Var | Default | Purpose |
|
|
|---|---|---|
|
|
| `AB_LEGACY_ENDPOINT` | `localhost:44818` | `host:port` of the PCCC endpoint. |
|
|
| `AB_LEGACY_CIP_PATH` | `1,0` | CIP routing path portion of the `ab://host:port/<path>` URI. ab_server rejects empty paths at the CIP unconnected-send layer; real SLC/MicroLogix/PLC-5 hardware accepts empty (no backplane). Set to empty (`AB_LEGACY_CIP_PATH=`) when pointing at real hardware. |
|
|
| `AB_LEGACY_COMPOSE_PROFILE` | *unset* | When set (e.g. `slc500`), the parametric theory filters to that profile. Only one compose container binds `:44818` at a time; set this to the profile currently up so the suite doesn't try to hit e.g. the Slc500 family against the PLC-5 container. Leave unset for real-hardware runs (all 3 families parameterize). |
|
|
|
|
## Run the integration tests
|
|
|
|
In a separate shell with a container up, tell the suite which profile is
|
|
running so only the matching theory-parameterization executes:
|
|
|
|
```powershell
|
|
cd C:\Users\dohertj2\Desktop\lmxopcua
|
|
$env:AB_LEGACY_COMPOSE_PROFILE = "slc500" # or "micrologix" / "plc5"
|
|
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests
|
|
```
|
|
|
|
Against real SLC / MicroLogix / PLC-5 hardware, set the endpoint + an
|
|
empty cip-path + leave the profile unset so all 3 parameterizations
|
|
run (real PLCs answer any valid family):
|
|
|
|
```powershell
|
|
$env:AB_LEGACY_ENDPOINT = "10.0.1.50:44818"
|
|
$env:AB_LEGACY_CIP_PATH = "" # empty — real hardware has no backplane
|
|
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests
|
|
```
|
|
|
|
`AbLegacyServerFixture` TCP-probes the endpoint at collection init and
|
|
sets a skip reason when the listener isn't reachable. Tests use
|
|
`[AbLegacyFact]` / `[AbLegacyTheory]` which check the same gate.
|
|
|
|
## What each family seeds
|
|
|
|
PCCC tag format is `<file>[<size>]` without a type suffix — file letter
|
|
implies type:
|
|
|
|
- `N` = 16-bit signed integer
|
|
- `F` = 32-bit IEEE 754 float
|
|
- `B` = 1-bit boolean (stored as uint16, bit-addressable via `/n`)
|
|
- `L` = 32-bit signed integer (SLC 5/05 V15+ only)
|
|
- `ST` = 82-byte ASCII string (MicroLogix-specific extension)
|
|
|
|
| Family | Seeded tags | Notes |
|
|
|---|---|---|
|
|
| SLC 500 | `N7[10]`, `F8[10]`, `B3[10]`, `L19[10]` | Baseline; covers the four numeric file types a typical SLC project uses |
|
|
| MicroLogix | `B3[10]`, `N7[10]`, `L19[10]` | No `F8` — MicroLogix 1000 has no float file; use L19 when scaled integers aren't enough |
|
|
| PLC-5 | `N7[10]`, `F8[10]`, `B3[10]` | No `L` — PLC-5 predates the L file type; DINT equivalents went in integer files |
|
|
|
|
## Known limitations
|
|
|
|
### ab_server rejects empty CIP paths
|
|
|
|
libplctag's `ab_server` enforces a non-empty CIP routing path at the
|
|
unconnected-send layer before forwarding to the PCCC dispatcher; a
|
|
client-side `ab://host:port/` with nothing after the `/` surfaces as
|
|
`BadCommunicationError` (`0x80050000`) with no server-side log line.
|
|
|
|
Real SLC/PLC-5 hardware has no backplane routing, so an empty path is
|
|
how field devices are addressed. The fixture defaults to `/1,0`
|
|
(port-1/slot-0 — the conventional ControlLogix backplane path) which
|
|
the ab_server accepts; operators targeting real hardware set
|
|
`AB_LEGACY_CIP_PATH=` (empty) to exercise authentic wire semantics.
|
|
|
|
Previous versions of this README described PCCC as "upstream-broken" —
|
|
the root cause turned out to be the cip-path gate above, not a gap in
|
|
`pccc.c`. N-file (Int16), F-file (Float32), and L-file (Int32) round-
|
|
trip cleanly across SLC500, MicroLogix, and PLC-5 modes.
|
|
|
|
### Bit-file writes on ab_server
|
|
|
|
`B3:0/5`-style bit-in-boolean writes currently surface `0x803D0000`
|
|
against `ab_server --plc=SLC500`; bit reads work. Non-blocking for the
|
|
smoke suite (which targets N-file Int16 + F-file float reads), but
|
|
bit-write fidelity isn't simulator-verified — route operator-critical
|
|
bit writes to real hardware or RSEmulate 500 until upstream resolves.
|
|
|
|
### Other known gaps (unchanged from ab_server)
|
|
|
|
- **Timer / Counter file decomposition** — PCCC T4 / C5 files contain
|
|
three-field structs (`.ACC` / `.PRE` / `.DN`). Not in ab_server's
|
|
scope; tests targeting `T4:0.ACC` stay unit-only.
|
|
- **ST (ASCII string) files** — real MicroLogix ST files have a length
|
|
field plus CRLF-sensitive semantics that don't round-trip cleanly.
|
|
- **Indirect addressing** (`N7:[N10:5]`) — not in ab_server's scope.
|
|
- **DF1 serial wire behaviour** — the whole ab_server path is TCP;
|
|
DF1 radio / serial fidelity needs real hardware.
|
|
|
|
See [`docs/drivers/AbLegacy-Test-Fixture.md`](../../../docs/drivers/AbLegacy-Test-Fixture.md)
|
|
for the full coverage map.
|
|
|
|
## References
|
|
|
|
- [libplctag on GitHub](https://github.com/libplctag/libplctag) — `ab_server`
|
|
lives under `src/tools/ab_server/`
|
|
- [`docs/drivers/AbLegacy-Test-Fixture.md`](../../../docs/drivers/AbLegacy-Test-Fixture.md)
|
|
— coverage map + gap inventory
|
|
- [`docs/v2/dev-environment.md`](../../../docs/v2/dev-environment.md)
|
|
§Docker fixtures — full fixture inventory
|
|
- [`../../ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/`](../../ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/)
|
|
— the shared Dockerfile this compose file's `build:` block references
|