dohertj2/lmxopcua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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.

Browse Source 
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>
This commit is contained in:
Joseph Doherty
2026-04-20 12:54:39 -04:00
parent 231148d7f0
commit 58a0cccc67
7 changed files with 424 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/drivers/AbServer-Test-Fixture.md
View File

@@ -116,38 +116,101 @@ No smoke test for:
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:
```powershell
$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`](../../tests/ZB.MOM.WW.OtOpcUa.Driver.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 | Lab rig |
| --- | --- | --- | --- |
| "Does the driver talk CIP at all?" | yes | - | - |
| "Is my atomic read path wired correctly?" | yes | yes | yes |
| "Does whole-UDT grouping work?" | no | yes | yes (required) |
| "Do ALMD alarms raise + clear?" | no | yes | yes (required) |
| "Is Micro800 unconnected-only enforced wire-side?" | no (emulated as CLX) | partial | yes (required) |
| "Does GuardLogix reject non-safety writes on safety tags?" | no | no | yes (required) |
| "Does CompactLogix refuse oversized ConnectionSize?" | no | partial | yes (required) |
| "Does BOOL-in-DINT RMW race against concurrent writers?" | no | yes | yes (stress) |
| 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:
1. **Extend `ab_server`** upstream — the project accepts PRs + already carries
a CIP framing layer that UDT emulation could plug into.
2. **Swap in a richer simulator** — e.g.
[OpenPLC](https://www.openplcproject.com/) or pycomm3's test harness, if
either exposes UDTs over EtherNet/IP in a way libplctag can consume.
3. **Stand up a lab rig** — physical `1756-L7x` / `5069-L3x` / `2080-LC30` /
`1756-L8xS` controllers running Rockwell Studio 5000 projects; wire into
CI via a self-hosted runner. The only path that covers safety + narrow
ConnectionSize + real ALMD execution.
1. **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.
2. **Extend `ab_server`** upstream — the project accepts PRs + already
carries a CIP framing layer that UDT emulation could plug into.
3. **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.
See also:
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerFixture.cs`
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerProfile.cs`
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerProfileGate.cs`
— `AB_SERVER_PROFILE` tier gate
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbCipReadSmokeTests.cs`
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/` — ab_server
image + compose
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Emulate/` — Logix
Emulate tier tests
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/LogixProject/README.md`
— L5X project state the Emulate tier expects
- `docs/v2/test-data-sources.md` §2 — the broader test-data-source picking
rationale this fixture slots into