lmxopcua/tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/README.md

# 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_TRUST_WIRE` | *unset* | Opt-in promise that the endpoint is a real PLC or RSEmulate 500 golden-box (not ab_server). Required for integration tests to actually run; without it the tests skip with an upstream-gap message even when TCP reaches a listener. See the **Known limitations** section below. |

## Run the integration tests

In a separate shell with a container up:

```powershell
cd C:\Users\dohertj2\Desktop\lmxopcua
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests
```

Against the Docker ab_server the suite **skips** with a pointer to the
upstream gap (see **Known limitations**). Against real SLC / MicroLogix /
PLC-5 hardware or a RSEmulate 500 box:

```powershell
$env:AB_LEGACY_ENDPOINT = "10.0.1.50:44818"
$env:AB_LEGACY_TRUST_WIRE = "1"
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests
```

`AbLegacyServerFixture` TCP-probes the endpoint at collection init and sets
a skip reason that captures **both** cases: unreachable endpoint *and*
reachable-but-wire-untrusted. 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 PCCC dispatcher (confirmed upstream gap, verified 2026-04-21)

**ab_server accepts TCP at `:44818` but its PCCC dispatcher is not
functional.** Running with `--plc=SLC500 --debug=5` shows no request
logs when libplctag issues a read, and every read surfaces as
`BadCommunicationError` (libplctag status `0x80050000`). This matches
the libplctag docs' description of PCCC support as less-mature than
CIP in the bundled `ab_server` tool.

**Fixture behavior.** To avoid a loud row of failing tests on the
integration host every time someone `docker compose up`s the SLC500
profile, `AbLegacyServerFixture` gates on a second env var
`AB_LEGACY_TRUST_WIRE`. The matrix:

| Endpoint reachable? | `AB_LEGACY_TRUST_WIRE` set? | Result |
|---|---|---|
| No | — | Skip ("not reachable") |
| Yes | No | **Skip ("ab_server PCCC gap")** |
| Yes | `1` or `true` | **Run** |

The test bodies themselves are correct for real hardware — point
`AB_LEGACY_ENDPOINT` at a real SLC 5/05 / MicroLogix 1100/1400 /
PLC-5, set `AB_LEGACY_TRUST_WIRE=1`, and the smoke tests round-trip
cleanly.

Resolution paths (pick one):

1. **File an ab_server bug** in `libplctag/libplctag` to expand PCCC
   server-side coverage.
2. **Golden-box tier** via Rockwell RSEmulate 500 — closer to real
   firmware, but license-gated + RSLinx-dependent. Set
   `AB_LEGACY_TRUST_WIRE=1` when the endpoint points at an Emulate
   box.
3. **Lab rig** — used SLC 5/05 / MicroLogix 1100 on a dedicated
   network (task #222); the authoritative path.

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