lmxopcua/docs/Driver.TwinCAT.Cli.md

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 (final) of the 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:

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)
--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