Useful Notes on ADS and TwinCAT#

This document collects important insights about the ADS (Automation Device Specification) protocol and TwinCAT systems, particularly as they relate to terminal configuration.

1. Two Ways ADS Accesses Data#

1.1 By Symbol Name#

ADS can read/write data using symbolic names that match entries in TwinCAT’s symbol table. There are two ways to address symbols:

Full Name (using caret ^ separator)#

The complete path from the TwinCAT I/O tree root:

TIID^Device 1 (EtherCAT)^Term 53 (EK1100)^Term 55 (EL1014)^Channel 1^Input

This includes the full hierarchy: TIID (TwinCAT I/O ID) → EtherCAT device → parent coupler → terminal → PDO → Entry.

Symbol Info (using port and dot . separator)#

A shorter form using the AMS port number and a dot-separated path from the terminal:

Port: 27905, 'Term 55 (EL1014).Channel 1.Input'

This form uses:

  • Port number: Identifies the EtherCAT master/device

  • Terminal name: e.g., Term 55 (EL1014)

  • PDO name: e.g., Channel 1

  • Entry name: e.g., Input

Requirements:

  • The symbol name must exactly match what TwinCAT has in its symbol table

  • TwinCAT generates these names based on the project configuration

Advantages:

  • Self-documenting code

  • Easier to understand and maintain

  • Symbol table provides type information

Disadvantages:

  • Requires symbol table to be available

  • Names must match exactly - no flexibility

  • Symbol table lookup adds overhead

1.2 By Index Group + Offset#

ADS can also access data directly using numeric addresses:

  • Index Group: Identifies the memory region (e.g., 0xF020 for inputs, 0xF030 for outputs)

  • Index Offset: Byte offset within that region

Example:

# Read 2 bytes from input area at offset 0
client.read(index_group=0xF020, index_offset=0, length=2)

Advantages:

  • No symbol table required

  • Direct memory access - faster

  • Works even without TwinCAT project symbols

Disadvantages:

  • Harder to understand (magic numbers)

  • Must know exact memory layout

  • No automatic type checking

2. Constructing ADS Symbol Names from ESI XML#

The Beckhoff ESI (EtherCAT Slave Information) XML files contain PDO (Process Data Object) definitions that can be used to construct valid ADS symbol names.

XML Structure#

<TxPdo>
  <Name>Channel 1</Name>
  <Entry>
    <Name>Input</Name>
    <DataType>BOOL</DataType>
  </Entry>
</TxPdo>

Symbol Name Construction#

The ADS symbol name (Symbol Info form) can be constructed as:

{terminal_name}.{PDO_name}.{Entry_name}

Where:

  • terminal_name: Discovered at runtime from the EtherCAT chain (e.g., Term 55 (EL1014))

  • PDO_name: From XML <TxPdo><Name> or <RxPdo><Name> (e.g., Channel 1)

  • Entry_name: From XML <Entry><Name> (e.g., Input)

Example:

Term 55 (EL1014).Channel 1.Input

What catio-terminals Stores#

The terminal YAML files store the suffix portion (PDO name + Entry name) that gets combined with the runtime-discovered terminal name:

# The name_template stores: {PDO_name}.{Entry_name}
# with {channel} placeholder for multi-channel terminals
- name_template: Channel {channel}.Input
  type_name: BOOL
  channels: 4

At runtime, FastCS will:

  1. Discover the EtherCAT chain and terminal names

  2. Combine terminal name with the name_template to form the full symbol

  3. Use the AMS port to address the correct EtherCAT master

Why This Approach Works#

  1. XML provides the suffix - PDO name and Entry name are exactly what TwinCAT uses

  2. Runtime provides the prefix - Terminal name comes from discovering the chain

  3. YAML filters what we scan - Only selected symbols from XML end up in YAML

  4. No hardcoded offsets needed - We use symbol-based ADS access exclusively

3. Limitation: XML Does Not Determine Active PDO Configuration#

The Problem#

The ESI XML files define all possible PDO configurations for a terminal, but TwinCAT may use a different configuration than what we infer from the XML. This means we cannot reliably determine the actual ADS symbol names just from the terminal type.

Example: EL1502 Counter Terminal#

The EL1502 is a 2-channel counter terminal. Its ESI XML defines multiple PDO options:

<!-- Per-channel PDOs -->
<TxPdo>
  <Name>CNT Inputs Channel 1</Name>
  <Entry><Name>Output functions enabled</Name>...</Entry>
  <Entry><Name>Counter value</Name>...</Entry>
</TxPdo>
<TxPdo>
  <Name>CNT Inputs Channel 2</Name>
  ...
</TxPdo>

<!-- Combined PDO (no channel number) -->
<TxPdo>
  <Name>CNT Inputs</Name>
  <Entry><Name>Output functions enabled</Name>...</Entry>
  <Entry><Name>Counter value</Name>...</Entry>
</TxPdo>

Our XML parser sees “Channel 1” and “Channel 2” PDOs and infers symbols like:

CNT Inputs Channel {channel}.Output functions enabled

But TwinCAT may be configured to use the combined PDO, resulting in actual symbols like:

Term 92 (EL1502).CNT Inputs.Output functions enabled

Why This Happens#

  1. ESI XML is a capability description - It lists all PDO configurations the terminal supports

  2. TwinCAT project chooses the configuration - The actual PDO mapping is determined by the TwinCAT project settings

  3. Default configurations vary - Different terminals may default to different PDO variants

Implications for catio-terminals#

This limitation means:

  1. Symbol names from XML may not match TwinCAT - The symbols we generate may not exist in the actual TwinCAT symbol table

  2. Per-terminal verification needed - Users may need to verify/adjust symbol names against their actual TwinCAT configuration

  3. Future enhancement needed - A more robust solution would query the actual TwinCAT symbol table at runtime rather than inferring from XML

Example: EL3702 Oversampling Terminal#

The EL3702 is a 2-channel analog input terminal that supports oversampling - capturing multiple samples per cycle. The ESI XML reveals extensive configurability:

<TxPdo OSFac="20" OSMin="1" OSMax="100" OSIndexInc="16">
  <Name>AI Inputs Channel 1</Name>
  <Entry>
    <Name>Value</Name>
    <DataType>INT</DataType>
  </Entry>
</TxPdo>

The XML attributes indicate:

  • OSMin=”1” - Minimum 1 sample per cycle

  • OSMax=”100” - Maximum 100 samples per cycle

  • OSFac=”20” - Oversampling factor (internal timing)

Additionally, the XML defines multiple Operation Modes:

<OpMode>
  <Name>DcSync</Name>
  <Desc>DC-Synchronous with variable Oversampling</Desc>
</OpMode>
<OpMode>
  <Name>DcSync2</Name>
  <Desc>DC-Synchronous 2x Oversampling</Desc>
</OpMode>
<!-- DcSync3, DcSync4, DcSync5, DcSync8, DcSync10 also defined -->

And TwinCAT-specific vendor extensions:

<Oversampling DefaultFactor="10" MinCycleTime="10000"/>

The problem: Our XML parser only sees the template PDO with a single Value entry. But at runtime, TwinCAT will create symbols based on the configured sample count:

Configuration

Actual Symbols Created

1x (no oversampling)

Term 60 (EL3702).AI Inputs Channel 1.Value

10x oversampling

Term 60 (EL3702).AI Inputs Channel 1.Samples[0..9] (or similar)

100x oversampling

100 sample values per channel

The XML defines capabilities (1-100 samples), but the TwinCAT project determines actual configuration.

Workarounds#

  1. Manual verification - Compare generated YAML against TwinCAT’s symbol browser

  2. Runtime symbol discovery - Query TwinCAT’s symbol table to discover actual symbols

  3. User override - Allow users to manually edit symbol names in the YAML files

Common Index Groups for EtherCAT I/O#

Index Group

Hex

Description

61472

0xF020

Input process data (bytes)

61473

0xF021

Input process data (bits)

61488

0xF030

Output process data (bytes)

61489

0xF031

Output process data (bits)

References#