lmxopcua/tests/Drivers/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` on `:44819`, `micrologix` on `:44820`, `plc5` on `:44821`. Run them together; they no longer collide with each other or with the AB CIP fixture on `:44818`. |

## Run

From the repo root:

```powershell
# SLC 500 family — widest PCCC coverage
docker compose -f tests\Drivers\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. (Until 2026-08-01 every family bound `:44818`, so only one could run and the theory's other two cases always failed; each now has its own port.) To switch
families stop the current service + start another.

## Endpoint

- Default: `10.100.0.35:44819` / `:44820` / `:44821` per family (the shared Docker host)
- 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` | *unset* — per-family ports on `10.100.0.35` | `host:port` of a single PCCC device, pinning **every** family to it (real-hardware mode). |
| `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_SERVER_ALLOW_WRITES` | *unset* | **Write opt-in.** Every write-capable test (today: the SLC500 N7:5 write-then-read round trip) skips unless this is `1`. Set it for simulator runs; **never** set it when an endpoint variable points at production hardware. Write tests also refuse while `AB_DIFF_ENDPOINT` (the AbCip read-only differential) is set. |
| `AB_LEGACY_COMPOSE_PROFILE` | *unset* | Only consulted when `AB_LEGACY_ENDPOINT` pins an endpoint: names which family that one device is, so the SLC500-only write test skips against other hardware. When `AB_LEGACY_ENDPOINT` is set and this is not, only the `slc500` rows run (the family of a pinned device cannot be detected). Against the Docker fixture it is unnecessary — each family has its own port, and each test skips itself if its own port is down. |

## 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"
$env:AB_SERVER_ALLOW_WRITES = "1"           # simulator only: lets the write round-trip test run
dotnet test tests\Drivers\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\Drivers\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

Originally (May 2026, libplctag only, before the native transport) a `B3:0/5`
bit write surfaced `0x803D0000` against `ab_server --plc=SLC500`. **That does
not reproduce any more** (2026-10-09): `AbLegacyBitWriteTests` writes `B3:0`,
sets bit 5 and clears bit 3 and asserts the whole word each time, and passes
on SLC500 and MicroLogix on both libplctag and native, and on PLC-5 with
libplctag. The cause of the original failure was never determined (the
driver's parent-word read-modify-write and ab_server's PCCC handlers are
both unchanged in shape, so an older libplctag/driver path is the likely
difference). PLC-5 on the native transport returns `0x803D0000`
(`BadNotSupported`) for a different reason: all native PLC-5 writes are
refused before the wire (#571); the test pins that.

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