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>
146 lines
5.8 KiB
Markdown
146 lines
5.8 KiB
Markdown
# FOCAS version / capability matrix
|
|
|
|
Authoritative source for the per-CNC-series ranges that
|
|
[`FocasCapabilityMatrix`](../../src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs)
|
|
enforces at driver init time. Every row cites the Fanuc FOCAS Developer
|
|
Kit function whose documented input range determines the ceiling.
|
|
|
|
**Why this exists** — we have no FOCAS hardware on the bench and no
|
|
working simulator. FWLIB (Fwlib64, or Fwlib32 on legacy deployments) returns `EW_NUMBER` / `EW_PARAM` when you
|
|
hand it an address outside the controller's supported range; the
|
|
driver would map that to a per-read `BadOutOfRange` at steady state.
|
|
Catching at `InitializeAsync` with this matrix surfaces operator
|
|
typos + mismatched series declarations as config errors before any
|
|
session is opened, which is the only feedback loop available without
|
|
a live CNC to read against.
|
|
|
|
**Who declares the series** — `FocasDeviceOptions.Series` in
|
|
`appsettings.json`. Defaults to `Unknown`, which is permissive — every
|
|
address passes validation. Pre-matrix configs don't break on upgrade.
|
|
|
|
---
|
|
|
|
## Series covered
|
|
|
|
| Enum value | Controller family | Typical era |
|
|
| --- | --- | --- |
|
|
| `Unknown` | (legacy / not declared) | permissive fallback |
|
|
| `Sixteen_i` | 16i / 18i / 21i | 1997-2008 |
|
|
| `Zero_i_D` | 0i-D | 2008-2013 |
|
|
| `Zero_i_F` | 0i-F | 2013-present, general-purpose |
|
|
| `Zero_i_MF` | 0i-MF | 0i-F lathe variant |
|
|
| `Zero_i_TF` | 0i-TF | 0i-F turning variant |
|
|
| `Thirty_i` | 30i-A / 30i-B | 2007-present, high-end |
|
|
| `ThirtyOne_i` | 31i-A / 31i-B | 30i simpler variant |
|
|
| `ThirtyTwo_i` | 32i-A / 32i-B | 30i compact |
|
|
| `PowerMotion_i` | Power Motion i-A / i-MODEL A | motion-only controller |
|
|
|
|
## Macro variable range (`cnc_rdmacro` / `cnc_wrmacro`)
|
|
|
|
Common macros `1-33` + `100-199` + `500-999` are universal across all
|
|
series. Extended macros (`#10000+`) exist only on higher-end series.
|
|
The numbers below reflect the extended ceiling per series per the
|
|
DevKit range tables.
|
|
|
|
| Series | Min | Max | Notes |
|
|
| --- | ---: | ---: | --- |
|
|
| `Sixteen_i` | 0 | 999 | legacy ceiling — no extended |
|
|
| `Zero_i_D` | 0 | 999 | 0i-D still at legacy ceiling |
|
|
| `Zero_i_F` / `Zero_i_MF` / `Zero_i_TF` | 0 | 9999 | extended added on 0i-F |
|
|
| `Thirty_i` / `ThirtyOne_i` / `ThirtyTwo_i` | 0 | 99999 | full extended set |
|
|
| `PowerMotion_i` | 0 | 999 | atypical — limited macro coverage |
|
|
|
|
## Parameter range (`cnc_rdparam` / `cnc_wrparam`)
|
|
|
|
| Series | Min | Max |
|
|
| --- | ---: | ---: |
|
|
| `Sixteen_i` | 0 | 9999 |
|
|
| `Zero_i_D` / `Zero_i_F` / `Zero_i_MF` / `Zero_i_TF` | 0 | 14999 |
|
|
| `Thirty_i` / `ThirtyOne_i` / `ThirtyTwo_i` | 0 | 29999 |
|
|
| `PowerMotion_i` | 0 | 29999 |
|
|
|
|
## PMC letters (`pmc_rdpmcrng` / `pmc_wrpmcrng`)
|
|
|
|
Addresses are letter + number (e.g. `R100`, `F50.3`). Legacy
|
|
controllers omit the `F`/`G` signal groups that 30i-family ladder
|
|
programs use, and only the 30i-family exposes `K` (keep-relay) +
|
|
`T` (timer).
|
|
|
|
| Letter | 16i | 0i-D | 0i-F family | 30i family | Power Motion-i |
|
|
| --- | :-: | :-: | :-: | :-: | :-: |
|
|
| `X` | yes | yes | yes | yes | yes |
|
|
| `Y` | yes | yes | yes | yes | yes |
|
|
| `R` | yes | yes | yes | yes | yes |
|
|
| `D` | yes | yes | yes | yes | yes |
|
|
| `E` | — | yes | yes | yes | — |
|
|
| `A` | — | yes | yes | yes | — |
|
|
| `F` | — | — | yes | yes | — |
|
|
| `G` | — | — | yes | yes | — |
|
|
| `M` | — | — | yes | yes | — |
|
|
| `C` | — | — | yes | yes | — |
|
|
| `K` | — | — | — | yes | — |
|
|
| `T` | — | — | — | yes | — |
|
|
|
|
Letter match is case-insensitive. `FocasAddress.PmcLetter` is carried
|
|
as a string (not char) so the matrix can do ordinal-ignore-case
|
|
comparison.
|
|
|
|
## PMC address-number ceiling
|
|
|
|
PMC addresses are byte-addressed on read + bit-addressed on write;
|
|
`FocasAddress` carries the bit index separately, so these are byte
|
|
ceilings.
|
|
|
|
| Series | Max byte | Notes |
|
|
| --- | ---: | --- |
|
|
| `Sixteen_i` | 999 | legacy |
|
|
| `Zero_i_D` | 1999 | doubled since 16i |
|
|
| `Zero_i_F` family | 9999 | |
|
|
| `Thirty_i` family | 59999 | highest density |
|
|
| `PowerMotion_i` | 1999 | |
|
|
|
|
## Error surface
|
|
|
|
When a tag fails validation, `FocasDriver.InitializeAsync` throws
|
|
`InvalidOperationException` with a message of the form:
|
|
|
|
```
|
|
FOCAS tag '<name>' (<address>) rejected by capability matrix: <reason>
|
|
```
|
|
|
|
`<reason>` is the verbatim string from `FocasCapabilityMatrix.Validate`
|
|
and always names the series + the documented limit so the operator
|
|
can either raise the limit (if wrong) or correct the CNC series they
|
|
declared (if mismatched). Sample:
|
|
|
|
```
|
|
FOCAS tag 'X_axis_macro_ext' (MACRO:50000) rejected by capability
|
|
matrix: Macro variable #50000 is outside the documented range
|
|
[0, 9999] for Zero_i_F.
|
|
```
|
|
|
|
## How this matrix stays honest
|
|
|
|
- Every row is covered by a parameterized test in
|
|
[`FocasCapabilityMatrixTests.cs`](../../tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasCapabilityMatrixTests.cs)
|
|
— 46 cases across macro / parameter / PMC-letter / PMC-number
|
|
boundaries + unknown-series permissiveness + rejection-message
|
|
content + case-insensitivity.
|
|
- Widening or narrowing a range in the matrix without updating this
|
|
doc will fail a test, because the theories cite the specific row
|
|
they reflect in their `InlineData`.
|
|
- The matrix is not comprehensive — it encodes only the subset of
|
|
FOCAS surface the driver currently exposes (Macro / Parameter /
|
|
PMC). When the driver gains a new capability (e.g. tool management,
|
|
alarm history), add its series-specific range tables here + matching
|
|
tests at the same time.
|
|
|
|
## Follow-up
|
|
|
|
This validation closes the cheap half of the FOCAS hardware-free
|
|
stability gap — config errors now fail at load instead of per-read.
|
|
The expensive half is Tier-C process isolation so that a crashing
|
|
`Fwlib64.dll` doesn't take the main OPC UA server down with it. See
|
|
[`docs/v2/implementation/focas-isolation-plan.md`](implementation/focas-isolation-plan.md)
|
|
for that plan (task #220).
|