Beckhoff ADS Symbolic Structure Transfer Between TwinCAT PLCs

Overview: Symbolic ADS for Inter-PLC Data Exchange

Passing a user-defined STRUCT between two Beckhoff TwinCAT PLCs by symbolic name (e.g., Main.receivedTrayData) eliminates the brittle practice of reserving overlapping %MB ranges or hard-coding byte offsets. The mechanism relies on the ADS symbol table being generated on the target PLC, the TwinCAT router being reachable, and the symbolic access function blocks resolving the variable by name at runtime.

This approach mirrors how the Beckhoff ADS .NET client and Node libraries such as jisotalo/ads-client resolve symbols via the ADS router. The same rules apply in-plc: the pointer supplied to the FB must address a variable inside the target PLC, and the symbol must exist in the compiled symbol description. See the Beckhoff Information System — pointer and symbol requirements.

Prerequisites

1. TwinCAT 3 XAE on the engineering PC; TwinCAT 3 PLC build 4024 or later is recommended for the tc2_dataexchange library functions.
2. Library reference to Tc2_DataExchange on both the source and target PLC projects.
3. Static, routable TwinCAT AmsNetId for the target (example: 192.168.0.2.1.1) and the target's ADS port for the PLC runtime (851 for the first PLC instance, 852 for the second, and so on). Port mapping is documented in the Tc2_DataExchange reference.
4. Symbol table generation enabled on the target PLC (Project → Properties → Compile Options → TwinCAT PLC): set Create symbol file / download symbol description to enabled. Without this file, FB_ReadAdsSymByName returns bError := TRUE with ADS error code 0x704 (symbol not found).
5. Firewall rules: TCP/UDP 48898 (ADS) and UDP 8016 (broadcast) reachable between both controllers.

Function Blocks: FB_WriteAdsSymByName and FB_ReadAdsSymByName

The two FBs that perform name-based ADS read and write are documented in the Tc2_DataExchange library — FB_ReadAdsSymByName and FB_WriteAdsSymByName.

Structured Text Example: Writing a Tray Structure to a Peer PLC

The pattern below shows a four-state machine (IDLE → WRITE → BUSY → ERROR) modeled on the original discussion. The same pattern applies for FB_ReadAdsSymByName.

PROGRAM MAIN
VAR
    trigger           : BOOL;
    adsWriteStatus    : (IDLE, WRITE, BUSY, ERROR);

    adsWrite : FB_WriteAdsSymByName := (
        sNetId    := '192.168.0.2.1.1',
        nPort     := 851,
        eComMode  := E_AdsComMode.eAdsComModeSecureCom,
        tTimeout  := DEFAULT_ADS_TIMEOUT
    );

    sendTrayData      : MyTrayStructure;   (* payload, defined identically on both PLCs *)
    adsWriteBusyEdge  : BOOL;
END_VAR

CASE adsWriteStatus OF

    IDLE :
        IF trigger THEN
            trigger := FALSE;
            adsWriteStatus := WRITE;
        END_IF

    WRITE :
        adsWrite(bWrite := FALSE);
        adsWrite(
            sVarName  := 'Main.receivedTrayData',
            nLen      := SIZEOF(sendTrayData),
            nSrcAddr  := ADR(sendTrayData),
            bWrite    := TRUE
        );
        adsWriteStatus := BUSY;

    BUSY :
        adsWrite(bWrite := FALSE);
        IF NOT adsWrite.bBusy THEN
            IF NOT adsWrite.bError THEN
                adsWriteStatus := IDLE;
            ELSE
                adsWriteStatus := ERROR;
            END_IF;
        END_IF

    ERROR :
        (* Latch nErrId, raise alarm, retry after backoff *)

END_CASE

Struct Definitions Must Match on Both PLCs

ADS is a byte-stream protocol. The layout, padding, and __attribute__((packed)) status of MyTrayStructure on the sender must match the receiver or the receiver will interpret shifted data. If alignment is critical, declare the STRUCT with {attribute 'pack_mode' := '0'} on both sides, and confirm via the TwinCAT symbol table that Size matches SIZEOF() on each side.

Verification

1. Set a breakpoint in the target PLC on the line that writes receivedTrayData; trigger from the sender; confirm the value updates.
2. Use the TwinCAT 3 ADS Monitor on the engineering PC: filter on AmsNetId, watch for ReadWrite index-group 0xF005 (symbol info by name). Each transfer should produce one round-trip.
3. Check adsWrite.nErrId after a transaction. Common codes:
   • 0x0 — no error.
   • 0x704 — symbol not found (case mismatch, missing namespace, or symbol table not downloaded).
   • 0x705 — symbol size mismatch; ensure SIZEOF() matches receiver layout.
   • 0x702 — target port unreachable; verify AmsNetId and that TwinCAT router is running on the target.
4. For a third-party test, use the jisotalo/ads-client Node tool to read Main.receivedTrayData from the target and diff against the sender's sendTrayData.

When to Use EAP Instead

EtherCAT Automation Protocol (EAP) is appropriate when the second controller is a slave of the same EtherCAT segment and you need deterministic, cyclic transfer with protocol-level timestamping. ADS is preferable for ad-hoc, triggered transfers such as a tray hand-off. The trade-offs are covered in the plccoder ADS write-up and the TwinCAT 3 ADS introduction video.

Cross-Vendor Integration Notes

When a non-Beckhoff controller (e.g., Siemens S7-1500 or Allen-Bradley CompactLogix) must read the same tag symbolically, the Beijer Beckhoff ADS Symbolic v4.14 driver or the Siemens LCCF ADSCom block provide symbol-driven HMI/PLC access without manual offset calculation. The symbol table becomes the single source of truth across vendors.

FAQ