Collector: Beckhoff ADS

Beckhoff TwinCAT (ADS)

Beckhoff TwinCAT PLCs (machine builders, test benches, packaging and motion) publish their variables over ADS. The collector is an ADS client: it reads variables by their symbol name (MAIN.fTemp) and, by default, asks the PLC to send each value when it changes (an ADS device notification), stamped with the PLC's own clock. Variables you prefer to sample on a timer are polled instead. It supports TwinCAT 3 and TwinCAT 2, and uses the pyads library (MIT).

Configuration

sources:
  - name: Packaging machine
    type: ads
    ams_net_id: 192.168.1.10.1.1   # the PLC's AMS Net Id
    host: 192.168.1.10             # its IP address
    ams_port: 851                  # 851 TwinCAT 3, 801 TwinCAT 2
    tags: ads_tags.csv

  - name: Test bench (everything numeric)
    type: ads
    ams_net_id: 10.0.0.5.1.1
    host: 10.0.0.5
    local_ams_net_id: 10.0.0.77.1.1   # Linux: this PC's Net Id (the PLC route points to it)

The tag list

name,symbol,type,unit,scale,offset,mode,cycle_ms,max_delay_ms,description
Oven temperature,MAIN.fTemp,,degC,,,,,,
Line speed,GVL.rSpeed,,m/min,,,notify,10,0,Every PLC cycle
Part count,MAIN.nParts,,,,,,,,
Fault code,GVL.eFault,INT,,,,,,,Enum stored as INT
Zone temps,MAIN.aZones,,degC,,,,,,Array of 8 REAL: becomes Zone temps[0] to [7]
Slow pressure,MAIN.fPressure,,bar,,,poll,5000,,Read every 5 s

Only symbol is required. The collector reads each variable's type from the PLC.

Arrays of numbers become one tag per element, named name[0], name[1]... (multi-dimensional arrays name[1,0]); arrays above 1024 elements are refused. Strings, structures and function-block instances are not collected as a whole: list the numeric members you want (MAIN.stDrive.rSpeed). With no tag list, discovery uploads the PLC's symbol table and keeps the numeric variables and arrays.

$ kymoscope-collector discover --config collector.yaml --source "Test bench" --out ads_tags.csv

A notification delivers the current value once at start and then only changes, so a variable that never changes yields one sample per connection; use mode: poll for a steady rate. Notification samples carry the PLC timestamp; poll samples carry the collector's clock.

Connecting: the AMS route

On the PLC (or from your engineering PC) add a route to the machine that runs the collector:

1. Open the TwinCAT XAE, SYSTEM, Route Settings (TwinCAT 3), or the TwinCAT system manager (TwinCAT 2) and add a static route: the collector PC's name or IP address and its AMS Net Id.
2. Linux or macOS collector: the Net Id is local_ams_net_id. Pick any unused one (for example the PC's IP address plus .1.1), put it in the PLC's route with the PC's IP, and set the same value in collector.yaml. No Beckhoff software is needed on the collector PC: the library speaks ADS over TCP port 48898 by itself. Open that port from the collector to the PLC.
3. Windows collector: the library needs the ADS router. Install TwinCAT, or the free Beckhoff TwinCAT 3 ADS package (it provides TcAdsDll.dll and the router), then add a route to the PLC in the router's settings with the PLC's IP and Net Id, and a route on the PLC back to this PC. The router's own Net Id is used; local_ams_net_id is ignored. If the collector runs on the PLC itself (a TwinCAT PC), use its own Net Id and no route.
4. Check with kymoscope-collector discover: it lists the variables when the route and port are right.

Install

pip install "kymoscope-collector[ads]"

On Linux the library is built when pip installs it, so a C++ compiler and make must be present (Debian and Ubuntu: apt install build-essential). On Windows it installs everywhere but loads only where the TwinCAT router is installed; otherwise the configuration check says so.

Health

connected, notifications_active, values_per_s, reconnects, ads_state (5 is RUN), bad_tags, polls, poll_errors, threads_abandoned, threads_hung and one counter per ADS error code, ads_errors_<code>. If the PLC leaves RUN (stop, config mode, a download) or stops answering, the collector reconnects with backoff (1 s, doubling to 60 s; it only drops back to 1 s after a connection that stayed up for a minute, so a flapping PLC is not hammered with symbol uploads) and registers the notifications again. A poll tag whose symbol no longer exists becomes a gap.

A call the PLC never answers is abandoned after timeout_s (threads_abandoned); the old connection and its notifications are closed as soon as that call returns, and nothing it still sends is stored. While 3 abandoned calls are still stuck (threads_hung) the source waits, up to 10 minutes, before trying again.

Troubleshooting