4b0664bd55
Migration closes the FOCAS Tier-C architecture. OtOpcUa previously had
`Driver.FOCAS.Host` (NSSM-wrapped Windows service loading Fwlib64.dll via
P/Invoke) + `Driver.FOCAS.Shared` (MessagePack IPC contracts) + a C shim
DLL stand-in for unit tests. All of it is deleted; the driver is now a
single in-process managed assembly talking the FOCAS/2 Ethernet binary
protocol directly on TCP:8193.
Architecture
- Pure-managed `FocasWireClient` inlined at `src/.../Driver.FOCAS/Wire/`
(owner-imported — see Wire/FocasWireClient.cs for the full surface).
Opens two TCP sockets, runs the initiate handshake, serialises requests
on socket 2 through a semaphore, closes cleanly with PDU + socket
teardown. Both sync `IDisposable` and async `IAsyncDisposable`.
- `WireFocasClient` (same folder) adapts the wire client to OtOpcUa's
`IFocasClient` surface — fixed-tree reads, PARAM/MACRO/PMC addresses,
alarms. Writes return `BadNotWritable` by design — OtOpcUa is read-only
against FOCAS.
- `FocasDriverFactoryExtensions` now accepts `"Backend": "wire"` (default)
and `"Backend": "unimplemented"`. Legacy `ipc` and `fwlib` backends are
rejected at startup with a diagnostic pointing at the migration doc.
Deletions
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/` — whole project + Ipc/,
Backend/, Stability/, Program.cs.
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/` — Contracts/, FrameReader,
FrameWriter, whole project.
- `tests/...Driver.FOCAS.Host.Tests/` + `.Shared.Tests/` — whole projects.
- `src/.../Driver.FOCAS/FwlibNative.cs` + `FwlibFocasClient.cs` — 21
P/Invokes + 7 `Pack=1` marshalling structs + the Fwlib-backed
`IFocasClient` implementation.
- `src/.../Driver.FOCAS/Ipc/` + `Supervisor/` — IPC client wrapper +
Host-process supervisor (backoff, circuit breaker, heartbeat, post-
mortem reader, process launcher).
- `scripts/install/Install-FocasHost.ps1` — NSSM service installer.
- `tests/.../Driver.FOCAS.Tests/{IpcFocasClientTests, IpcLoopback,
FwlibNativeHelperTests, PostMortemReaderCompatibilityTests,
SupervisorTests, FocasDriverFactoryExtensionsTests}.cs` — tests that
exercised the retired surfaces.
- `tests/.../Driver.FOCAS.IntegrationTests/Shim/` — the zig-built C shim
DLL that masqueraded as Fwlib64.dll.
Solution changes
- `ZB.MOM.WW.OtOpcUa.slnx` drops the 4 retired project refs.
- `src/.../Driver.FOCAS.csproj` drops the Shared ProjectReference, adds
`Microsoft.Extensions.Logging.Abstractions` for the optional `ILogger`
hook in `FocasWireClient`.
- `src/.../Driver.FOCAS.Cli.csproj` drops the six `<Content Include>`
entries that copied `vendor/fanuc/*.dll` into the CLI bin. CLI now uses
`WireFocasClient` directly.
- `FocasDriver` default factory flips to `Wire.WireFocasClientFactory`.
Integration tests
- New `tests/.../Driver.FOCAS.IntegrationTests/` project covering fixed-
tree reads (identity, axes, dynamic, program, operation mode, timers,
spindle load + max RPM, servo meters), user-authored PARAM / MACRO /
PMC reads, `DiscoverAsync` emission, `SubscribeAsync` + `OnDataChange`,
`IAlarmSource` raise/clear transitions, and `ProbeAsync` /
`OnHostStatusChanged`. 9 e2e tests against the focas-mock fixture
(Docker container with the vendored Python mock's native FOCAS/2
Ethernet responder).
- `scripts/integration/run-focas.ps1` orchestrates compose up → tests →
compose down. Dropped the shim-build stage + DLL-copy step + the split
testhost workaround (the latter only existed because of native-DLL
lifecycle bugs the shim tripped).
- Docker compose collapses from 11 per-series services to one `focas-sim`
service. Tests seed per-series state via `mock_load_profile` at test
start.
- Vendored focas-mock snapshot refreshed to pick up upstream's native
FOCAS/2 Ethernet responder (was 660 lines, now 1018) — the
pre-refresh snapshot only spoke the JSON admin protocol.
Tests
- 145/145 unit tests in `Driver.FOCAS.Tests` pass (was 208 pre-deletion;
63 removed tests exercised the retired IPC/shim/supervisor/Fwlib
surfaces).
- 9/9 integration tests pass against the refreshed mock.
- `FocasScaffoldingTests.Unimplemented_factory_throws_on_Create…` updated
to assert the new diagnostic message pointing at
`docs/drivers/FOCAS.md` rather than the now-gone `Fwlib64.dll`.
Docs
- `docs/drivers/FOCAS.md` rewritten for the managed wire topology —
deployment collapses to one `"Backend": "wire"` config block, no
separate service, no DLL deployment, no pipe ACL.
- `docs/drivers/FOCAS-Test-Fixture.md` updated — single TCP probe skip
gate instead of TCP + shim probe; fewer moving parts.
- `docs/drivers/README.md` row for FOCAS reflects the Tier-A managed
topology (previously listed Tier-C + `Fwlib64.dll` P/Invoke).
- `docs/Driver.FOCAS.Cli.md` drops the Tier-C architecture-note section.
- `docs/v2/implementation/focas-isolation-plan.md` marked historical —
the plan it documents was executed then superseded by the wire client.
- `docs/v2/v2-release-readiness.md` re-audited 2026-04-24. Phase 5
driver complement closed. FOCAS change-log entry added.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
95 lines
4.5 KiB
Markdown
95 lines
4.5 KiB
Markdown
# FOCAS Docker simulator — focas-mock + shim DLL
|
|
|
|
Hardware-free FOCAS fixture for OtOpcUa's integration test matrix. Runs
|
|
the vendored [`focas-mock`](focas-mock/VENDORED.md) Python server under
|
|
Docker and pairs it with the [shim DLL](../Shim/VENDORED.md) that
|
|
masquerades as `Fwlib64.dll` inside the .NET test process.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌────────────────────────────┐ cnc_allclibhndl3 / cnc_rdparam / ...
|
|
│ xunit test process │ (P/Invoke, __stdcall)
|
|
│ ├── Driver.FOCAS │
|
|
│ │ └── FwlibNative.cs ─┼─┐
|
|
│ └── FocasSimFixture │ │ resolves to...
|
|
└────────────────────────────┘ │
|
|
▼
|
|
┌────────────────────────────┐
|
|
│ Fwlib64.dll (shim) │ JSON over TCP
|
|
│ tests/.../Shim/focas_ │──────────────────────┐
|
|
│ shim.c compiled here │ │
|
|
└────────────────────────────┘ │
|
|
▼
|
|
┌─────────────────────────────┐
|
|
│ focas-mock (Docker) │
|
|
│ python:3.11-slim │
|
|
│ profile-aware responses │
|
|
│ mock_load_profile / │
|
|
│ mock_patch admin methods │
|
|
└─────────────────────────────┘
|
|
```
|
|
|
|
The shim bridges the binary ABI (C `__stdcall` exports with FOCAS struct
|
|
shapes) to the mock's newline-delimited JSON protocol. OtOpcUa's
|
|
`FocasSimFixture` seeds per-test state by sending `mock_load_profile` +
|
|
`mock_patch` admin calls on the same socket. Tests assert the managed
|
|
driver sees the seeded values through its normal P/Invoke path.
|
|
|
|
## Running
|
|
|
|
Pick one compose profile (they all publish 8193 — only one at a time):
|
|
|
|
```powershell
|
|
docker compose -f Docker/docker-compose.yml --profile thirtyone up -d
|
|
dotnet test tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests
|
|
docker compose -f Docker/docker-compose.yml --profile thirtyone down
|
|
```
|
|
|
|
Available profiles + their focas-mock target:
|
|
|
|
| compose --profile | focas-mock profile | Covers |
|
|
|---|---|---|
|
|
| `thirtyone` / `thirty` / `thirtytwo` | `fwlib30i64` | 30i / 31i / 32i series |
|
|
| `sixteen` | `FWLIB64` | 16i / 18i / 21i legacy family |
|
|
| `zerod` / `zerof` / `zeromf` / `zerotf` | `fwlib0iD64` | 0i-D / 0i-F / 0i-MF / 0i-TF |
|
|
| `powermotion` | `fwlib0DN64` | Power Motion i |
|
|
| `ethernet` | `fwlibe64` | Ethernet-variant DLL |
|
|
| `ncguide` | `fwlibNCG64` | NC Guide PC simulator |
|
|
|
|
## What this covers — and what it doesn't
|
|
|
|
**Covered:**
|
|
|
|
- All 10 FOCAS functions `FwlibNative.cs` P/Invokes
|
|
- Read-after-write round-trip for parameters, macros, PMC ranges
|
|
- PMC bit read-modify-write path (via the `pmc_wrpmcrng` seam)
|
|
- `IAlarmSource` raise + clear transitions (via `mock_schedule_alarms`)
|
|
- Per-series profile selection — tests can pin one and assert series-gated
|
|
behaviour
|
|
|
|
**Not covered** (still hardware-gated):
|
|
|
|
- Real FOCAS2 TCP wire protocol (this is a JSON mock; the shim hides
|
|
the real protocol entirely)
|
|
- CNC-specific firmware quirks (position scaling across power cycles,
|
|
edit-mode session locks, MTB custom screens)
|
|
- Concurrent-read behaviour on the real `Fwlib64.dll` — the shim is
|
|
single-threaded per connection
|
|
|
|
See [`docs/drivers/FOCAS-Test-Fixture.md`](../../../docs/drivers/FOCAS-Test-Fixture.md)
|
|
for the full coverage map.
|
|
|
|
## Skip behaviour
|
|
|
|
`FocasSimFixture` probes the mock at collection init time:
|
|
|
|
- Mock unreachable → tests skip with the compose-up command to run
|
|
- Mock reachable but shim DLL not loaded → tests skip with a pointer
|
|
at `Shim/build.ps1`
|
|
- Both available → tests run
|
|
|
|
This lets the same test assembly be green on a fresh CI box without
|
|
docker, green on a dev box with just the docker compose up, and
|
|
exercise the full wire path when the shim is built.
|