261 lines
13 KiB
Markdown
261 lines
13 KiB
Markdown
# 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](https://github.com/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.
|
|
- **Symbolic vs Logical addressing wall-clock** (PR abcip-3.2,
|
|
`AbCipAddressingModeBenchTests`) — both modes complete + emit timing.
|
|
**Emulate-tier only**: `ab_server` does not currently honour the CIP Symbol
|
|
Object class 0x6B `cip_addr` attribute that Logical mode sets, so on the
|
|
fixture the two modes measure the same wire path. The bench scaffold
|
|
asserts both complete + records timing for human inspection; the actual
|
|
Symbolic-vs-Logical perf comparison requires a real ControlLogix /
|
|
CompactLogix on the network. See
|
|
[`docs/drivers/AbCip-Performance.md`](AbCip-Performance.md) §"Addressing
|
|
mode" for the full caveat.
|
|
|
|
## 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.
|
|
|
|
PR abcip-3.3 layers a per-device **`ReadStrategy`** selector on top
|
|
(`WholeUdt` / `MultiPacket` / `Auto`, see
|
|
[`AbCip-Performance.md`](AbCip-Performance.md) §"Read strategy"). Strategy
|
|
switching is planner-side: the dispatcher picks between
|
|
`AbCipUdtReadPlanner` (whole-UDT) and `AbCipMultiPacketReadPlanner`
|
|
(per-member, bundled per parent) per batch. The selector + per-batch Auto
|
|
heuristic + family-compat fall-back + per-device dispatch counters are
|
|
**unit-tested only** in `AbCipReadStrategyTests` — `ab_server` cannot host
|
|
a 50-member UDT to exercise the sparse case the strategy is designed for,
|
|
and the libplctag .NET wrapper (1.5.x) does not expose explicit
|
|
Multi-Service-Packet bundling, so wire-level coverage stays Emulate-tier
|
|
in `AbCipEmulateMultiPacketReadTests` (gated on `AB_SERVER_PROFILE=emulate`).
|
|
|
|
### 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.
|
|
|
|
PR abcip-3.1 layers the **per-device `ConnectionSize` override** on top
|
|
(`AbCipDeviceOptions.ConnectionSize`, range `[500..4002]`, see
|
|
[`AbCip-Performance.md`](AbCip-Performance.md)). Same gap — `ab_server`
|
|
happily honours an oversized override against the CompactLogix profile, so
|
|
the legacy-firmware warning + Forward Open rejection that real 5069-L1/L2/L3
|
|
parts emit are unit-tested only. Live coverage stays Emulate / rig-only
|
|
(connect against a real CompactLogix L2 with `ConnectionSize=1500` to
|
|
confirm the Forward Open fails with CIP error 0x01/0x113).
|
|
|
|
### 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` — atomic write coverage; PR abcip-4.2 added a
|
|
multi-write *suppression* smoke (jittery 5-write sequence with
|
|
`WriteDeadband: 1.0` against `ab_server`, asserting the driver's
|
|
diagnostics counter matches the expected suppression count) but pure
|
|
atomic-write coverage end-to-end is still unit-only.
|
|
- `ITagDiscovery.DiscoverAsync` (`@tags` walker)
|
|
- `ISubscribable.SubscribeAsync` (poll-group engine)
|
|
- ~~`IHostConnectivityProbe` state transitions under wire failure~~ —
|
|
covered as of PR abcip-4.3. `AbCipSystemTagDiscoveryTests` connects to
|
|
`ab_server`, drives the discovery + read path against the synthetic
|
|
`_System/_ConnectionStatus` variable, and asserts the live snapshot
|
|
reflects the probe-driven `HostState`. Wire-failure transitions still
|
|
rely on unit-level `ThrowOnRead` injection rather than a real wire pull,
|
|
but the end-to-end probe → snapshot → OPC UA address-space link is
|
|
exercised against `ab_server`.
|
|
- `IPerCallHostResolver` multi-device routing
|
|
|
|
The driver implements all of these + they have unit coverage, but the only
|
|
end-to-end paths `ab_server` validates today are atomic `ReadAsync` and
|
|
write-deadband / write-on-change suppression.
|
|
|
|
## 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 | 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. **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
|