Files

Joseph Doherty a6be2f77b5 FOCAS version-matrix stabilization (PR 1 of #220 split) — ship the cheap half of the hardware-free stability gap ahead of the Tier-C out-of-process split. Without any CNC or simulator on the bench, the highest-leverage move is to catch operator config errors at init time instead of at steady-state per-read. Adds FocasCncSeries enum (Unknown/16i/0i-D/0i-F family/30i family/PowerMotion-i) + FocasCapabilityMatrix static class that encodes the per-series documented ranges for macro variables (cnc_rdmacro/wrmacro), parameters (cnc_rdparam/wrparam), and PMC letters + byte ceilings (pmc_rdpmcrng/wrpmcrng) straight from the Fanuc FOCAS Developer Kit. FocasDeviceOptions gains a Series knob (defaults Unknown = permissive so pre-matrix configs don't break on upgrade). FocasDriver.InitializeAsync now calls FocasAddress.TryParse on every tag + runs FocasCapabilityMatrix.Validate against the owning device's declared series, throwing InvalidOperationException with a reason string that names both the series and the documented limit ("Parameter #30000 is outside the documented range [0, 29999] for Thirty_i") so an operator can tell whether the mismatch is in the config or in their declared CNC model. Unknown series skips validation entirely. Ships 46 new theory cases in FocasCapabilityMatrixTests.cs — covering every boundary in the matrix (widen 16i->0i-F: macro ceiling 999->9999, param 9999->14999; widen 0i-F->30i: PMC letters +K+T; PMC-number 16i=999/0i-D=1999/0i-F=9999/30i=59999), permissive Unknown-series behavior, rejection-message content, and case-insensitive PMC-letter matching. Widening a range without updating docs/v2/focas-version-matrix.md fails a test because every InlineData cites the row it reflects. Full FOCAS test suite stays at 165/165 passing (119 existing + 46 new). Also authors docs/v2/focas-version-matrix.md as the authoritative range reference with per-function citations, CNC-series era context, error-surface shape, and the link back to the matrix code; docs/v2/implementation/focas-isolation-plan.md as the multi-PR plan for #220 Tier-C isolation (Shared contracts -> Host skeleton -> move Fwlib32 calls -> Supervisor+respawn -> MMF+ops glue, 2200-3200 LOC across 5 PRs mirroring the Galaxy Tier-C topology); and promotes docs/drivers/FOCAS-Test-Fixture.md from "version-matrix coverage = no" to explicit coverage via the new test file + cross-links to the matrix and isolation-plan docs. Leaves task #220 open since isolation itself (the expensive half) is still ahead.

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

2026-04-20 13:44:37 -04:00

5.3 KiB

Raw Blame History

FOCAS test fixture

Coverage map + gap inventory for the FANUC FOCAS2 CNC driver.

TL;DR: there is no integration fixture. Every test uses a FakeFocasClient injected via IFocasClientFactory. Fanuc's FOCAS library (Fwlib32.dll) is closed-source proprietary with no public simulator; CNC-side behavior is trusted from field deployments.

What the fixture is

Nothing at the integration layer. tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/ is unit-only. The driver ships as Tier C (process-isolated) per docs/v2/driver-stability.md because the FANUC DLL has known crash modes; tests can't replicate those in-process.

What it actually covers (unit only)

FocasCapabilityTests — data-type mapping (PMC bit / word / float, macro variable types, parameter types)
FocasCapabilityMatrixTests — per-CNC-series range validation (macro / parameter / PMC letter + number) across 16i / 0i-D / 0i-F / 30i / PowerMotion. See docs/v2/focas-version-matrix.md for the authoritative matrix. 46 theory cases lock every documented range boundary — widening a range without updating the doc fails a test.
FocasReadWriteTests — read + write against the fake, FOCAS native status → OPC UA StatusCode mapping
FocasScaffoldingTests — IDriver lifecycle + multi-device routing
FocasPmcBitRmwTests — PMC bit read-modify-write synchronization (per-byte SemaphoreSlim, mirrors the AB / Modbus pattern from #181)
FwlibNativeHelperTests — Focas32.dll → Fwlib32.dll bridge validation
- P/Invoke signature validation

Capability surfaces whose contract is verified: IDriver, IReadable, IWritable, ITagDiscovery, ISubscribable, IHostConnectivityProbe, IPerCallHostResolver.

Pre-flight validation runs in FocasDriver.InitializeAsync — configs referencing out-of-range addresses fail at load time with a diagnostic message naming the CNC series + documented limit. This closes the cheap half of the hardware-free stability gap; Tier-C process isolation (task #220) closes the expensive half — see docs/v2/implementation/focas-isolation-plan.md.

What it does NOT cover

1. FOCAS wire traffic

No FOCAS TCP frame is sent. Fwlib32.dll's TCP-to-FANUC-gateway exchange is closed-source; the driver trusts the P/Invoke layer per #193. Real CNC correctness is trusted from field deployments.

2. Alarm / parameter-change callbacks

FOCAS has no push model — the driver polls via the shared PollGroupEngine. There are no CNC-initiated callbacks to test; the absence is by design.

3. Macro / ladder variable types

FANUC has CNC-specific extensions (macro variables #100-#999, system variables #1000-#5000, PMC timers / counters / keep-relays) whose per-address semantics differ across 0i-F / 30i / 31i / 32i Series. Driver covers the common address shapes; per-model quirks are not stressed.

4. Model-specific behavior

Alarm retention across power cycles (model-specific CNC behavior)
Parameter range enforcement (CNC rejects out-of-range writes)
MTB (machine tool builder) custom screens that expose non-standard data

5. Tier-C process isolation behavior

Per driver-stability.md, FOCAS should run process-isolated because Fwlib32.dll has documented crash modes. The test suite runs in-process + only exercises the happy path + mapped error codes — a native access violation from the DLL would take the test host down. The process-isolation path (similar to Galaxy's out-of-process Host) has been scoped but not implemented.

When to trust FOCAS tests, when to reach for a rig

Question	Unit tests	Real CNC
"Does PMC address `R100.3` route to the right bit?"	yes	yes
"Does the FANUC status → OPC UA StatusCode map cover every documented code?"	yes (contract)	yes
"Does a real read against a 30i Series return correct bytes?"	no	yes (required)
"Does `Fwlib32.dll` crash on concurrent reads?"	no	yes (stress)
"Do macro variables round-trip across power cycles?"	no	yes (required)

Follow-up candidates

Nothing public — Fanuc's FOCAS Developer Kit ships an emulator DLL but it's under NDA + tied to licensed dev-kit installations; can't redistribute for CI.
Lab rig — used FANUC 0i-F simulator controller (or a retired machine tool) on a dedicated network; only path that covers real CNC behavior.
Process isolation first — before trusting FOCAS in production at scale, shipping the Tier-C out-of-process Host architecture (similar to Galaxy) is higher value than a CI simulator.

Key fixture / config files

tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FakeFocasClient.cs — in-process fake implementing IFocasClient
tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasCapabilityMatrixTests.cs — parameterized theories locking the per-series matrix
src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs — ctor takes IFocasClientFactory
src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs — per-CNC-series range validator (the matrix the doc describes)
docs/v2/focas-version-matrix.md — authoritative range reference
docs/v2/implementation/focas-isolation-plan.md — Tier-C isolation plan (task #220)
docs/v2/driver-stability.md — Tier C scope + process-isolation rationale

5.3 KiB Raw Blame History