lmxopcua/docs/Driver.FOCAS.Cli.md

# `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, added alongside the Tier-C isolation
work tracked in task #220.

## Architecture note

FOCAS is a Tier-C driver: `Fwlib32.dll` is a proprietary 32-bit Fanuc library
with a documented habit of crashing its hosting process on network errors.
The target runtime deployment splits the driver into an in-process
`FocasProxyDriver` (.NET 10 x64) and an out-of-process `Driver.FOCAS.Host`
(.NET 4.8 x86 Windows service) that owns the DLL — see
[v2/implementation/focas-isolation-plan.md](v2/implementation/focas-isolation-plan.md)
and
[v2/implementation/phase-6-1-resilience-and-observability.md](v2/implementation/phase-6-1-resilience-and-observability.md)
for topology + supervisor / respawn / back-pressure design.

The CLI skips the proxy and loads `FocasDriver` directly (via
`FwlibFocasClientFactory`, which P/Invokes `Fwlib32.dll` in the CLI's own
process). There is **no public simulator** for FOCAS; a meaningful probe
requires a real CNC + a licensed `Fwlib32.dll` on `PATH` (or next to the
executable). On a dev box without the DLL, every wire call surfaces as
`BadCommunicationError` — still useful as a "CLI wire-up is correct" signal.

## 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.

**"Is the Fwlib32 DLL wired up?"** → `probe` against any host. A
`DllNotFoundException` surfacing as `BadCommunicationError` with a
matching `Last error` line means the driver is loading but the DLL is
missing; anything else means a transport-layer problem.