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>
155 lines
5.0 KiB
Markdown
155 lines
5.0 KiB
Markdown
# `otopcua-focas-cli` — Fanuc FOCAS test client
|
|
|
|
Ad-hoc probe / read / write / subscribe tool for Fanuc CNCs via the FOCAS/2
|
|
protocol. Uses the **same** `FocasDriver` the OtOpcUa server does — PMC R/G/F
|
|
file registers, axis bits, parameters, and macro variables — all through
|
|
`FocasAddressParser` syntax.
|
|
|
|
Sixth of the driver test-client CLIs.
|
|
|
|
## Architecture note
|
|
|
|
FOCAS is an in-process driver. The pure-managed `WireFocasClient`
|
|
speaks the FOCAS2 binary protocol directly over TCP:8193, removing the
|
|
Tier-C process-isolation split that the historical P/Invoke + out-of-
|
|
process Host arrangement required. The CLI loads `FocasDriver` with
|
|
`WireFocasClientFactory` and talks to the CNC without any native
|
|
components.
|
|
|
|
A dev-friendly mock is available — start
|
|
`tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/Docker/docker-compose.yml`
|
|
and point `--cnc-host` at `localhost` for end-to-end CLI exercises
|
|
without a real CNC. See
|
|
[drivers/FOCAS-Test-Fixture.md](drivers/FOCAS-Test-Fixture.md).
|
|
|
|
## Build + run
|
|
|
|
```powershell
|
|
dotnet build src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Cli
|
|
dotnet run --project src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Cli -- --help
|
|
```
|
|
|
|
Or publish a self-contained binary:
|
|
|
|
```powershell
|
|
dotnet publish src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Cli -c Release -o publish/focas-cli
|
|
publish/focas-cli/otopcua-focas-cli.exe --help
|
|
```
|
|
|
|
## Common flags
|
|
|
|
Every command accepts:
|
|
|
|
| Flag | Default | Purpose |
|
|
|---|---|---|
|
|
| `-h` / `--cnc-host` | **required** | CNC IP address or hostname |
|
|
| `-p` / `--cnc-port` | `8193` | FOCAS TCP port (FOCAS-over-EIP default) |
|
|
| `-s` / `--series` | `Unknown` | CNC series — `Unknown` / `Zero_i_D` / `Zero_i_F` / `Zero_i_MF` / `Zero_i_TF` / `Sixteen_i` / `Thirty_i` / `ThirtyOne_i` / `ThirtyTwo_i` / `PowerMotion_i` |
|
|
| `--timeout-ms` | `2000` | Per-operation timeout |
|
|
| `--verbose` | off | Serilog debug output |
|
|
|
|
## Addressing
|
|
|
|
`FocasAddressParser` syntax — the same format the server + `FocasTagDefinition`
|
|
use. Common shapes:
|
|
|
|
| Address | Meaning |
|
|
|---|---|
|
|
| `R100` | PMC R-file word register 100 |
|
|
| `X0.0` | PMC X-file bit 0 of byte 0 |
|
|
| `G50.3` | PMC G-file bit 3 of byte 50 |
|
|
| `F1.4` | PMC F-file bit 4 of byte 1 |
|
|
| `PARAM:1815/0` | Parameter 1815, axis 0 |
|
|
| `MACRO:500` | Macro variable 500 |
|
|
|
|
## Data types
|
|
|
|
`Bit`, `Byte`, `Int16`, `Int32`, `Float32`, `Float64`, `String`. Default is
|
|
`Int16` (matches PMC R-file word width).
|
|
|
|
## Commands
|
|
|
|
### `probe` — is the CNC reachable?
|
|
|
|
Opens a FOCAS session, reads one sample address, prints driver health.
|
|
|
|
```powershell
|
|
# Default: read R100 as Int16
|
|
otopcua-focas-cli probe -h 192.168.1.50
|
|
|
|
# Explicit series + address
|
|
otopcua-focas-cli probe -h 192.168.1.50 -s ThirtyOne_i --address R200 --type Int16
|
|
```
|
|
|
|
### `read` — single address
|
|
|
|
```powershell
|
|
# PMC R-file word
|
|
otopcua-focas-cli read -h 192.168.1.50 -a R100 -t Int16
|
|
|
|
# PMC X-bit
|
|
otopcua-focas-cli read -h 192.168.1.50 -a X0.0 -t Bit
|
|
|
|
# Parameter (axis 0)
|
|
otopcua-focas-cli read -h 192.168.1.50 -a PARAM:1815/0 -t Int32
|
|
|
|
# Macro variable
|
|
otopcua-focas-cli read -h 192.168.1.50 -a MACRO:500 -t Float64
|
|
```
|
|
|
|
### `write` — single value
|
|
|
|
Values parse per `--type` with invariant culture. Booleans accept
|
|
`true` / `false` / `1` / `0` / `yes` / `no` / `on` / `off`.
|
|
|
|
```powershell
|
|
otopcua-focas-cli write -h 192.168.1.50 -a R100 -t Int16 -v 42
|
|
otopcua-focas-cli write -h 192.168.1.50 -a G50.3 -t Bit -v on
|
|
otopcua-focas-cli write -h 192.168.1.50 -a MACRO:500 -t Float64 -v 3.14
|
|
```
|
|
|
|
PMC G/R writes land on a running machine — be careful which file you hit.
|
|
Parameter writes may require the CNC to be in MDI mode with the
|
|
parameter-write switch enabled.
|
|
|
|
**Writes are non-idempotent by default** — a timeout after the CNC already
|
|
applied the write will NOT auto-retry (plan decisions #44 + #45).
|
|
|
|
### `subscribe` — watch an address until Ctrl+C
|
|
|
|
FOCAS has no push model; the shared `PollGroupEngine` handles the tick
|
|
loop.
|
|
|
|
```powershell
|
|
otopcua-focas-cli subscribe -h 192.168.1.50 -a R100 -t Int16 -i 500
|
|
```
|
|
|
|
## Output format
|
|
|
|
Identical to the other driver CLIs via `SnapshotFormatter`:
|
|
|
|
- `probe` / `read` emit a multi-line block: `Tag / Value / Status /
|
|
Source Time / Server Time`. `probe` prefixes it with `CNC`, `Series`,
|
|
`Health`, and `Last error` lines.
|
|
- `write` emits one line: `Write <address>: 0x... (Good |
|
|
BadCommunicationError | …)`.
|
|
- `subscribe` emits one line per change: `[HH:mm:ss.fff] <address> =
|
|
<value> (<status>)`.
|
|
|
|
## Typical workflows
|
|
|
|
**"Is the CNC alive?"** → `probe`.
|
|
|
|
**"Does my parameter write land?"** → `write` + `read` back against the
|
|
same address. Check the parameter-write switch + MDI mode if the write
|
|
fails.
|
|
|
|
**"Why did this macro flip?"** → `subscribe` to the macro, let the
|
|
operator reproduce the cycle, watch the HH:mm:ss.fff timeline.
|
|
|
|
**"Can I reach the CNC on TCP:8193?"** → `probe` against any host. A
|
|
`BadCommunicationError` means the wire client couldn't open a socket
|
|
(firewall / wrong host / FOCAS Ethernet option unlicensed on the CNC).
|
|
`BadDeviceFailure` after a successful connect means the CNC is rejecting
|
|
the session setup — check the CNC's FOCAS option and password settings.
|