Files

T

Joseph Doherty 7869494393 docs(audit): Driver.TwinCAT.Cli.md — verb/flag accuracy + ordinal fix

CODE-REALITY:
- Line 8: "Fifth (final)" → "Fifth of six"; TwinCAT is not the final CLI —
  FOCAS (sixth) follows it. The "final" label was stale ordinal drift
  from when there were fewer CLIs; 6 projects confirmed in
  src/Drivers/Cli/.
- probe per-command flag table: `--type` row was missing the `-t`
  shorthand.  ProbeCommand.cs:25 declares
  [CommandOption("type", 't', ...)] — same '-t' shorthand used by read,
  write, subscribe; the probe table was the only one that omitted it.
  Fixed to `-t` / `--type` for consistency.

STRUCTURAL: no rows in links-report.md for this doc.
STALE-STATUS: no state words found.
INLINE COMPLETENESS: no inventory-diff gaps for this doc.

2026-06-03 16:31:34 -04:00

4.7 KiB

Raw Permalink Blame History

`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

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:

Local TwinCAT XAR — install the free TwinCAT 3 XAR Engineering install on the machine running the CLI; it ships the router.
Beckhoff.TwinCAT.Ads.TcpRouter — standalone NuGet router. Run in a sidecar process when no XAR is installed.
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 list

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

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

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`

# 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

# 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

4.7 KiB Raw Permalink Blame History

otopcua-twincat-cli — Beckhoff TwinCAT test client