# `otopcua-twincat-cli` — Beckhoff TwinCAT test client

Ad-hoc probe / read / write / subscribe / browse tool for Beckhoff TwinCAT 2 /
TwinCAT 3 runtimes via ADS. Uses the **same** `TwinCATDriver` the OtOpcUa
server does (`Beckhoff.TwinCAT.Ads` package). Native ADS notifications by
default; `--poll-only` falls back to the shared `PollGroupEngine`.

Fifth of six driver test-client CLIs.

## Build + run

```powershell
dotnet run --project src/Drivers/Cli/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Cli -- --help
```

## Prerequisite: AMS router

The `Beckhoff.TwinCAT.Ads` library needs a reachable AMS router to open ADS
sessions. Pick one:

1. **Local TwinCAT XAR** — install the free TwinCAT 3 XAR Engineering install
   on the machine running the CLI; it ships the router.
2. **Beckhoff.TwinCAT.Ads.TcpRouter** — standalone NuGet router. Run in a
   sidecar process when no XAR is installed.
3. **Remote AMS route** — any Windows box with TwinCAT installed, with an AMS
   route authorised to the CLI host.

The CLI compiles + runs without a router, but every wire call fails with a
transport error until one is reachable.

## Common flags

| Flag | Default | Purpose |
|---|---|---|
| `-n` / `--ams-net-id` | **required** | AMS Net ID (e.g. `192.168.1.40.1.1`) |
| `-p` / `--ams-port` | `851` | AMS port (TwinCAT 3 PLC = 851, TwinCAT 2 = 801) |
| `--timeout-ms` | `5000` | Per-operation timeout |
| `--poll-only` | off | Disable native ADS notifications, use `PollGroupEngine` instead |
| `--verbose` | off | Serilog debug output |

## Data types

TwinCAT exposes the IEC 61131-3 atomic set: `Bool`, `SInt`, `USInt`, `Int`,
`UInt`, `DInt`, `UDInt`, `LInt`, `ULInt`, `Real`, `LReal`, `String`, `WString`,
`Time`, `Date`, `DateTime`, `TimeOfDay`. The four IEC time/date variants
marshal as `UDINT` on the wire — CLI takes a numeric raw value and lets the
caller interpret semantics.

## Commands

### `probe`

Per-command flags:

| Flag | Default | Purpose |
|---|---|---|
| `-s` / `--symbol` | **required** | Symbol path to probe (e.g. `MAIN.bRunning`) |
| `-t` / `--type` | `DInt` | Declared data type — see the [Data types](#data-types) list |

```powershell
# Local TwinCAT 3, probe a canonical global
otopcua-twincat-cli probe -n 127.0.0.1.1.1 -s "TwinCAT_SystemInfoVarList._AppInfo.OnlineChangeCnt"

# Remote, probe a project variable
otopcua-twincat-cli probe -n 192.168.1.40.1.1 -s MAIN.bRunning --type Bool
```

### `read`

```powershell
# Bool symbol
otopcua-twincat-cli read -n 192.168.1.40.1.1 -s MAIN.bStart -t Bool

# Counter
otopcua-twincat-cli read -n 192.168.1.40.1.1 -s GVL.Counter -t DInt

# Nested UDT member
otopcua-twincat-cli read -n 192.168.1.40.1.1 -s Motor1.Status.Running -t Bool

# Array element
otopcua-twincat-cli read -n 192.168.1.40.1.1 -s "Recipe[3]" -t Real

# WString
otopcua-twincat-cli read -n 192.168.1.40.1.1 -s GVL.sMessage -t WString
```

### `write`

```powershell
otopcua-twincat-cli write -n 192.168.1.40.1.1 -s MAIN.bStart -t Bool -v true
otopcua-twincat-cli write -n 192.168.1.40.1.1 -s GVL.Counter -t DInt -v 42
otopcua-twincat-cli write -n 192.168.1.40.1.1 -s GVL.sMessage -t WString -v "running"
```

Structure writes refused — drop to driver config JSON for those.

### `subscribe`

Per-command flags:

| Flag | Default | Purpose |
|---|---|---|
| `-s` / `--symbol` | **required** | Symbol path — same format as `read` |
| `-t` / `--type` | `DInt` | Declared data type |
| `-i` / `--interval-ms` | `1000` | Publishing interval in **milliseconds** — native mode passes this as the ADS `NotificationSettings.CycleTime` |

```powershell
# Native ADS notifications (default) — PLC pushes on its own cycle
otopcua-twincat-cli subscribe -n 192.168.1.40.1.1 -s GVL.Counter -t DInt -i 500

# Fall back to polling for runtimes where native notifications are constrained
otopcua-twincat-cli subscribe -n 192.168.1.40.1.1 -s GVL.Counter -t DInt -i 500 --poll-only
```

The subscribe banner announces which mechanism is in play — "ADS notification"
or "polling" — so it's obvious in screen-recorded bug reports.

### `browse`

Walks the controller's symbol table via ADS `SymbolLoaderFactory` (same path
`TwinCATDriver.DiscoverAsync` takes when `EnableControllerBrowse = true`).
Output filters to symbols whose type maps onto the driver's atomic surface —
UDTs / function-block instances don't appear.

| Flag | Default | Purpose |
|---|---|---|
| `--prefix` | _(none)_ | Case-sensitive instance-path prefix filter (e.g. `GVL_Fixture`) |
| `--max` | `500` | Max symbols to print. `0` = unbounded |

```powershell
# Everything under a single GVL
otopcua-twincat-cli browse -n 192.168.1.40.1.1 --prefix GVL_Fixture

# Full dump (beware: flat-mode walks on a real controller can top 10k symbols)
otopcua-twincat-cli browse -n 192.168.1.40.1.1 --max 0
```
