Files

Joseph Doherty 58a0cccc67 AB CIP Logix Emulate golden-box tier — scaffold the code + docs so the L5X + Emulate PC drop in without fixture-code changes. Closes the initial design question the user raised; the actual Emulate-side work (author project, commit L5X, install Emulate on the dev box) is tracked as #223 . Scaffolding ships everything that doesn't need the live Emulate instance: tier-gated test classes that skip cleanly when AB_SERVER_PROFILE is unset, the profile gate helper, the LogixProject/README.md documenting the exact project state the tests expect, the fixture coverage doc's new §Logix Emulate tier section with the when-to-trust table extended from 3 columns to 4, and the dev-environment.md integration-host row.

AbServerProfileGate — static helper that reads `AB_SERVER_PROFILE` env var (defaults to "abserver") + exposes `SkipUnless(params string[] requiredProfiles)` matching the MODBUS_SIM_PROFILE pattern the DL205StringQuirkTests uses one directory over. Emulate-only tests call `AbServerProfileGate.SkipUnless("emulate")` at the top of each fact body; ab_server-default runs see them skip with a clear message pointing at the Emulate setup steps.

AbCipEmulateUdtReadTests — one test proving the #194 whole-UDT read optimization works against the real Logix Template Object, not just the golden byte buffers the unit suite uses. Builds an `AbCipDriverOptions` with a Structure tag `Motor1 : Motor_UDT` that has three declared members (Speed : DINT, Torque : REAL, Status : DINT), reads them via the `.Speed / .Torque / .Status` dotted-tag syntax, asserts the driver gets the grouped whole-UDT path + decodes each at the right offset. Required seed values documented inline + in LogixProject/README.md: Speed=1800, Torque=42.5f, Status=0x0001.

AbCipEmulateAlmdTests — one test proving the #177 ALMD projection fires `OnAlarmEvent` when a real ALMD instruction's `In` edge rises, not just the fake `InFaulted` timer edges the unit suite drives. Needs a `SimulateAlarm : BOOL` tag routed through `MainRoutine` ladder (`XIC SimulateAlarm OTE HighTempAlarm.In`) so the test case can pulse the input via the existing `IWritable.WriteAsync` path instead of scripting Emulate via its own socket. Alarm-projection options carry `EnableAlarmProjection = true` + 200 ms poll interval; a `TaskCompletionSource` gates the raise-event assertion with a 5 s deadline. Cleanup writes SimulateAlarm=false so consecutive runs start from known state.

LogixProject/README.md — the Studio 5000 project state the Emulate-tier tests depend on. Explains why L5X over ACD (text diff, reproducible import, no per-install state), the UDT + tag + routine structure, how to bring it up on the Emulate PC. Ships as a stub pending actual author + L5X export + commit; the README itself keeps the requirements visible so the L5X author has a checklist.

docs/drivers/AbServer-Test-Fixture.md — new §Logix Emulate golden-box tier section with the coverage-promotion table (ab_server / Emulate / hardware per gap), the setup-env-var recipe, the costs to accept (license, Hyper-V conflict, manual lifecycle). "When to trust" table extended from 3 columns (ab_server / unit / rig) to 4 (ab_server / unit / Logix Emulate / rig); two new rows for EtherNet/IP embedded-switch + redundant-chassis failover that even Emulate can't help with. Follow-up candidates list gets Logix Emulate as option 1 ahead of the pre-existing "extend ab_server upstream" + "stand up a lab rig". See-also file list gains AbServerProfileGate.cs + Docker/ + Emulate/ + LogixProject/README.md entries.

docs/v2/dev-environment.md — §C Integration host gains a Rockwell Studio 5000 Logix Emulate row: purpose (AB CIP golden-box tier closing UDT/ALMD/AOI/safety/ConnectionSize gaps), type (Windows-only, Hyper-V conflict matching TwinCAT XAR's constraint), port 44818, credentials note, owner split between integration-host admin for license+install and developer for per-session runtime start.

Verified: Emulate tests skip cleanly when AB_SERVER_PROFILE is unset — both `[SKIP]` with the operator-facing message pointing at the env-var setup. Whole-solution build 0 errors. Tests will transition from skip → pass once the L5X + Emulate PC land per #223.

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

2026-04-20 12:54:39 -04:00

10 KiB

Raw Blame History

ab_server test fixture

Coverage map + gap inventory for the AB CIP integration fixture backed by libplctag's ab_server simulator.

TL;DR: ab_server is a connectivity + atomic-read smoke harness for the AB CIP driver. It does not benchmark UDTs, alarms, or any family-specific quirk. UDT / alarm / quirk behavior is verified only by unit tests with FakeAbCipTagRuntime.

What the fixture is

Binary: ab_server — a C program in libplctag's src/tools/ab_server/ (libplctag/libplctag, MIT).
Launcher: Docker (only supported path). Docker/Dockerfile multi-stage-builds ab_server from source against a pinned libplctag tag + copies the binary into a slim runtime image. Docker/docker-compose.yml has per-family services (controllogix / compactlogix / micro800 / guardlogix); all bind :44818.
Lifecycle: AbServerFixture TCP-probes 127.0.0.1:44818 at collection init + records a skip reason when unreachable. Tests skip via [AbServerFact] / [AbServerTheory] which check the same probe.
Profiles: KnownProfiles.{ControlLogix, CompactLogix, Micro800, GuardLogix} in AbServerProfile.cs — thin Family + ComposeProfile + Notes records; the compose file is the canonical source of truth for which tags get seeded + which --plc mode the simulator boots in.
Tests: one smoke, AbCipReadSmokeTests.Driver_reads_seeded_DInt_from_ab_server, parametrized over all four profiles via [AbServerTheory] + [MemberData].
Endpoint override: AB_SERVER_ENDPOINT=host:port points the fixture at a real PLC instead of the local container.

What it actually covers

Read path: driver → libplctag → CIP-over-EtherNet/IP → simulator → back.
Atomic Logix types per seed: DINT, REAL, BOOL, SINT, STRING.
One DINT[16] array tag (ControlLogix profile only).
--plc controllogix and --plc compactlogix mode dispatch.
The skip-on-missing-binary behavior (AbServerFactAttribute) so a fresh clone without the simulator stays green.

What it does NOT cover

Each gap below is either stated explicitly in the profile's Notes field or inferable from the seed-tag set + smoke-test surface.

1. UDTs / CIP Template Object (class 0x6C)

ControlLogix profile Notes: "ab_server lacks full UDT emulation."

Unverified against ab_server:

PR 6 structured read/write (AbCipStructureMember fan-out)
#179 Template Object shape reader (CipTemplateObjectDecoder + FetchUdtShapeAsync)
#194 whole-UDT read optimization (AbCipUdtReadPlanner + AbCipUdtMemberLayout + the ReadGroupAsync path in AbCipDriver)

Unit coverage: AbCipFetchUdtShapeTests, CipTemplateObjectDecoderTests, AbCipUdtMemberLayoutTests, AbCipUdtReadPlannerTests, AbCipDriverWholeUdtReadTests — all with golden Template-Object byte buffers

offset-keyed FakeAbCipTag values.

2. ALMD / ALMA alarm projection (#177)

Depends on the ALMD UDT shape, which ab_server cannot emulate. The OnAlarmEvent raise/clear path + ack-write semantics are not exercised end-to-end.

Unit coverage: AbCipAlarmProjectionTests — fakes feed InFaulted / Severity via ValuesByOffset + assert the emitted AlarmEventArgs.

3. Micro800 unconnected-only path

Micro800 profile Notes: "ab_server has no --plc micro800 — falls back to controllogix emulation."

The empty routing path + unconnected-session requirement (PR 11) is unit-tested but never challenged at the CIP wire level. Real Micro800 (2080-series) on a lab rig would be the authoritative benchmark.

4. GuardLogix safety subsystem

GuardLogix profile Notes: "ab_server doesn't emulate the safety subsystem."

Only the _S-suffix naming classifier (PR 12, SecurityClassification.ViewOnly forced on safety tags) runs. Actual safety-partition write rejection — what happens when a non-safety write lands on a real 1756-L8xS — is not exercised.

5. CompactLogix narrow ConnectionSize cap

CompactLogix profile Notes: "ab_server lacks the narrower limit itself."

Driver-side AbCipPlcFamilyProfile caps ConnectionSize at the CompactLogix value per PR 10, but ab_server accepts whatever the client asks for — the cap's correctness is trusted from its unit test, never stressed against a simulator that rejects oversized requests.

6. BOOL-within-DINT read-modify-write (#181)

The AbCipDriver.WriteBitInDIntAsync RMW path + its per-parent SemaphoreSlim serialization is unit-tested only (AbCipBoolInDIntRmwTests). ab_server seeds a plain TestBOOL tag; the .N bit-within-DINT syntax that triggers the RMW path is not exercised end-to-end.

7. Capability surfaces beyond read

No smoke test for:

IWritable.WriteAsync
ITagDiscovery.DiscoverAsync (@tags walker)
ISubscribable.SubscribeAsync (poll-group engine)
IHostConnectivityProbe state transitions under wire failure
IPerCallHostResolver multi-device routing

The driver implements all of these + they have unit coverage, but the only end-to-end path ab_server validates today is atomic ReadAsync.

Logix Emulate golden-box tier

Rockwell Studio 5000 Logix Emulate sits above ab_server in fidelity + below real hardware. When an operator has Emulate running on a reachable Windows box + sets two env vars, the suite promotes several behaviours from unit-only to end-to-end wire-level coverage:

$env:AB_SERVER_PROFILE  = 'emulate'
$env:AB_SERVER_ENDPOINT = '<emulate-pc-ip>:44818'
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests

With AB_SERVER_PROFILE unset or abserver, the Emulate-tier classes skip cleanly + the ab_server Docker fixture runs as usual.

Gap this fixture doc calls out	ab_server	Logix Emulate	Real hardware
UDT / CIP Template Object (task #194)	no	yes	yes
ALMD alarm projection (task #177)	no	yes	yes
`@tags` Symbol Object walk with `Program:` scope	partial	yes	yes
Add-On Instructions	no	yes	yes
GuardLogix safety-partition write rejection	no	yes (Emulate 5580)	yes
CompactLogix narrow ConnectionSize enforcement	no	yes (5370 firmware)	yes
EtherNet/IP embedded-switch behaviour	no	no	yes
Redundant chassis failover (1756-RM)	no	no	yes
Motion control timing	no	no	yes

Tests that promote to Emulate (gated on AB_SERVER_PROFILE=emulate via AbServerProfileGate.SkipUnless):

AbCipEmulateUdtReadTests.WholeUdt_read_decodes_each_member_at_its_Template_Object_offset — #194 whole-UDT optimization, verified against real Template Object bytes
AbCipEmulateAlmdTests.Real_ALMD_raise_fires_OnAlarmEvent_through_the_driver_projection — #177 ALMD projection, verified against the real ALMD instruction

Required Studio 5000 project state is documented in tests/…/AbCip.IntegrationTests/LogixProject/README.md; the .L5X export lands there once the Emulate PC is on-site + the project is authored.

Costs to accept:

Rockwell TechConnect or per-seat license — not redistributable; not CI-runnable. Each operator licenses their own Emulate install.
Windows-only + Hyper-V conflict — Emulate can't coexist with Docker Desktop's WSL 2 backend on the same OS, same way TwinCAT XAR can't (see docs/v2/dev-environment.md §Integration host).
Manual lifecycle — no docker compose up equivalent; operator opens Emulate, loads the L5X, clicks Run. The L5X in the repo keeps project state reproducible, runtime-start is human.

When to trust ab_server, when to reach for a rig

Question	ab_server	Unit tests	Logix Emulate	Lab rig
"Does the driver talk CIP at all?"	yes	-	yes	-
"Is my atomic read path wired correctly?"	yes	yes	yes	yes
"Does whole-UDT grouping work?"	no	yes	yes	yes
"Do ALMD alarms raise + clear?"	no	yes	yes	yes
"Is Micro800 unconnected-only enforced wire-side?"	no (emulated as CLX)	partial	yes	yes (required)
"Does GuardLogix reject non-safety writes on safety tags?"	no	no	yes (Emulate 5580)	yes
"Does CompactLogix refuse oversized ConnectionSize?"	no	partial	yes (5370 firmware)	yes
"Does BOOL-in-DINT RMW race against concurrent writers?"	no	yes	partial	yes (stress)
"Does EtherNet/IP embedded-switch behave correctly?"	no	no	no	yes (required)
"Does redundant-chassis failover work?"	no	no	no	yes (required)

Follow-up candidates

If integration-level UDT / alarm / quirk proof becomes a shipping gate, the options are roughly:

Logix Emulate golden-box tier (scaffolded; see the section above) — highest-fidelity path short of real hardware. Closes UDT / ALMD / AOI / optimized-DB gaps in one license + one Windows PC.
Extend ab_server upstream — the project accepts PRs + already carries a CIP framing layer that UDT emulation could plug into.
Stand up a lab rig — physical 1756-L7x / 5069-L3x / 2080-LC30 / 1756-L8xS controllers. The only path that covers safety partitions across nodes, redundant chassis, embedded-switch behaviour, and motion timing.

10 KiB Raw Blame History