Dynamic PDOs in EtherCAT Terminals

This document explains the concept of dynamic PDO (Process Data Object) configurations in Beckhoff EtherCAT terminals, why they exist, and how catio-terminals handles them.

Background: Static vs Dynamic PDOs

Most EtherCAT terminals have a static PDO configuration - the process data structure is fixed and predictable. For example, an EL2024 (4-channel digital output) always has exactly 4 boolean outputs, and an EL3202 (2-channel PT100 input) always has the same structure per channel.

However, some terminals have dynamic PDO configurations that depend on:

• TwinCAT project settings

• Selected operation mode

• Oversampling factor

• PDO assignment choices

For these terminals, the exact PDO layout cannot be determined from the ESI XML alone - it varies based on how the terminal is configured in the TwinCAT project.

Types of Dynamic PDO Configurations

Type 1: Configuration Variants

Some terminals offer alternative PDO structures for the same function. For example, the EL1502 (2-channel up/down counter) can be configured as:

Configuration	PDO Names	Symbol Pattern
Per-channel	CNT Inputs Channel 1, CNT Inputs Channel 2	CNT Inputs Channel {n}.Counter value
Combined	CNT Inputs	CNT Inputs.Counter value

The XML defines both configurations, but only one will be active at runtime.

Type 2: Standard vs Compact PDO Selection

Analog input terminals like EL3104, EL3124, EP3174-0002, and EP4374-0002 offer two PDO formats per channel:

Format	PDO Name Pattern	Contents
Standard	AI Standard Channel {n}	Status word (underrange, overrange, limits, error) + Value
Compact	AI Compact Channel {n}	Value only (no status)

The TwinCAT project selects one format per channel. Both are defined in XML as optional.

Type 3: Multi-Format Terminals

Terminals like the EL3356-0010 (precision resistor bridge) offer multiple data formats:

Format	PDO Name	Data Type
INT32	RMB Value (INT32)	DINT (32-bit signed)
Real	RMB Value (Real)	REAL (32-bit float)
Standard Ch1/Ch2	AI Standard Channel {n}	Status + DINT value
Compact Ch1/Ch2	AI Compact Channel {n}	DINT value only

Additionally, there are optional PDOs for RMB Status, RMB Timestamp, and RMB Control.

Type 4: Oversampling Terminals

Oversampling terminals like EL3702, EL4732, and ELM3704-0000 have a configurable number of samples per channel (1-100). The XML shows only a template, but the actual symbol count depends on the configured oversampling factor.

The ELM3704-0000 is particularly complex - each of its 4 channels can have:

• Different data formats: INT16, INT32 (DINT), or REAL32

• Different oversampling factors: 1, 2, 4, 5, 8, 10, 16, 20, 25, 32, 40, 50, 64, 80, or 100 samples

The XML defines 192 TxPDOs (48 per channel) to cover all combinations.

How Dynamic PDOs are Defined in ESI XML

Beckhoff’s ESI XML files indicate dynamic PDO configurations using the <AlternativeSmMapping> element within the <VendorSpecific>/<TwinCAT> section.

The AlternativeSmMapping Element

Each <AlternativeSmMapping> element defines a mutually exclusive PDO configuration. The Default="1" attribute marks which configuration is active by default.

Example from EL3104:

<VendorSpecific>
  <TwinCAT>
    <AlternativeSmMapping Default="1">
      <Name>Standard</Name>
      <Sm No="3">
        <Pdo>#x1a00</Pdo> <!-- AI Standard Channel 1 -->
        <Pdo>#x1a02</Pdo> <!-- AI Standard Channel 2 -->
        <Pdo>#x1a04</Pdo> <!-- AI Standard Channel 3 -->
        <Pdo>#x1a06</Pdo> <!-- AI Standard Channel 4 -->
      </Sm>
    </AlternativeSmMapping>
    <AlternativeSmMapping>
      <Name>Compact</Name>
      <Sm No="3">
        <Pdo>#x1a01</Pdo> <!-- AI Compact Channel 1 -->
        <Pdo>#x1a03</Pdo> <!-- AI Compact Channel 2 -->
        <Pdo>#x1a05</Pdo> <!-- AI Compact Channel 3 -->
        <Pdo>#x1a07</Pdo> <!-- AI Compact Channel 4 -->
      </Sm>
    </AlternativeSmMapping>
  </TwinCAT>
</VendorSpecific>

This structure indicates that:

1. The terminal has two exclusive modes: “Standard” and “Compact”

2. “Standard” is the default (marked with Default="1")

3. Each mode uses different PDO indices

PDO Exclude Elements

Some terminals (like EL1502) use a different approach to define mutually exclusive PDOs - the <Exclude> element within each PDO. This is more commonly used for per-channel vs combined mode selection.

Example from EL1502:

<TxPdo Fixed="1">
  <Index>#x1a00</Index>
  <Name>CNT Inputs Channel 1</Name>
  <Exclude>#x1a02</Exclude>  <!-- Excludes the combined PDO -->
</TxPdo>
<TxPdo Fixed="1">
  <Index>#x1a01</Index>
  <Name>CNT Inputs Channel 2</Name>
  <Exclude>#x1a02</Exclude>  <!-- Excludes the combined PDO -->
</TxPdo>
<TxPdo Fixed="1" Sm="3">
  <Index>#x1a02</Index>
  <Name>CNT Inputs</Name>
  <Exclude>#x1a00</Exclude>  <!-- Excludes channel 1 -->
  <Exclude>#x1a01</Exclude>  <!-- Excludes channel 2 -->
</TxPdo>

This exclusion graph defines two groups:

• Per-Channel: #x1a00 + #x1a01 (each channel separate)

• Combined: #x1a02 (both channels in one PDO)

The default group is determined by the Sm attribute. PDOs with an explicit Sm attribute are assigned to a Sync Manager by default, making their group the default. In EL1502, the Combined PDO (#x1a02) has Sm="3", so Combined is the default.

Sync Manager Assignment

The Sm attribute on PDO elements indicates the default Sync Manager assignment:

• SM2 (Sm=”2”): RxPDO outputs

• SM3 (Sm=”3”): TxPDO inputs

PDOs without an Sm attribute are not assigned by default and require explicit selection.

Terminals at Diamond Light Source

The following table categorizes terminals used at Diamond Light Source by their PDO type:

Terminal	Description	PDO Type
EK1100	EtherCAT Coupler	None
EK1122	2 Port EtherCAT Junction	None
EL1014	4Ch Digital Input 24V, 10us	Static
EL1084	4Ch Digital Input 24V, 3ms, negative	Static
EL1124	4Ch Digital Input 5V, 10us	Static
EL1502	2Ch Up/Down Counter 24V, 100kHz	Dynamic Type 1
EL2024	4Ch Digital Output 24V, 2A	Static
EL2124	4Ch Digital Output 5V, 20mA	Static
EL3104	4Ch Analog Input +/-10V Diff	Dynamic Type 2
EL3124	4Ch Analog Input 4-20mA Diff	Dynamic Type 2
EL3202	2Ch Analog Input PT100 (RTD)	Static
EL3314	4Ch Analog Input Thermocouple	Static
EL3356-0010	1Ch Resistor Bridge, 16bit High Precision	Dynamic Type 3
EL3602	2Ch Analog Input +/-10V Diff, 24bit	Static
EL3702	2Ch Analog Input +/-10V Oversample	Dynamic Type 4
EL4134	4Ch Analog Output +/-10V, 16bit	Static
EL4732	2Ch Analog Output +/-10V Oversample	Dynamic Type 4
ELM3704-0000	4Ch Universal Analog Input, 24bit	Dynamic Type 4
EP3174-0002	4Ch Analog Input configurable	Dynamic Type 2
EP4374-0002	2Ch AI + 2Ch AO configurable	Dynamic Type 2

Runtime Discovery

For terminals with dynamic PDOs, the actual configuration must be queried from the TwinCAT symbol table at runtime:

async with CatioClient(target_ip="192.168.1.100") as client:
    # Discover EtherCAT devices
    await client.get_ethercat_devices()

    # Get all symbols from the symbol table
    all_symbols = await client.get_all_symbols()

    # Symbols are keyed by device ID
    for device_id, symbols in all_symbols.items():
        for name, symbol in symbols.items():
            print(f"{name}: {symbol.type_name}")

Implementation in catio-terminals

The catio-terminals tool supports dynamic PDO configurations through a grouping mechanism that:

1. Parses AlternativeSmMapping from the ESI XML to identify PDO groups

2. Falls back to PDO Exclude elements for terminals like EL1502 that use exclusion-based grouping

3. Tracks which symbols belong to which PDO group

4. Provides a GUI selector to choose the active PDO group

5. Filters symbols based on the selected group

Data Model

The data models for PDO groups are defined in models.py:

• PdoGroup: Represents a group of mutually exclusive PDOs, storing the group name, default flag, PDO indices, and corresponding symbol indices.

• TerminalType: Extended with pdo_groups and selected_pdo_group fields, plus helper properties like has_dynamic_pdos and get_active_symbol_indices().

XML Parsing

The xml/pdo_groups.py module handles parsing of PDO group definitions using two methods:

Method 1: AlternativeSmMapping (preferred)

def parse_pdo_groups(device: _Element) -> list[PdoGroup]:
    """Parse PDO groups from device XML.

    Tries AlternativeSmMapping first, then falls back to Exclude elements.
    """
    # Find VendorSpecific/TwinCAT/AlternativeSmMapping elements
    # Extract group name, default flag, and PDO indices
    # Return list of PdoGroup instances

Method 2: PDO Exclude Elements (fallback)

For terminals like EL1502 that use <Exclude> elements instead of AlternativeSmMapping, the parser:

1. Builds an exclusion graph from all PDO Exclude elements

2. Identifies “Combined” PDOs (those that exclude 2+ other PDOs)

3. Identifies “Per-Channel” PDOs (those excluded by Combined PDOs)

4. Creates two PDO groups: “Per-Channel” (default) and “Combined”

def assign_symbols_to_groups(
    pdo_groups: list[PdoGroup],
    symbol_pdo_mapping: dict[int, int],
) -> None:
    """Assign symbol indices to their corresponding PDO groups."""
    # Maps each symbol to its source PDO index
    # Updates PdoGroup.symbol_indices accordingly

The PDO index is tracked during symbol node creation, allowing each symbol to be associated with its source PDO and thus its PDO group.

GUI Integration

When a terminal has dynamic PDOs, the catio-terminals editor displays:

1. A PDO Configuration dropdown showing available groups (e.g., “Standard”, “Compact”)

2. Filtered symbol tree showing only symbols in the selected group

3. Visual indicator of the default group

Changing the selected group updates which symbols are displayed and available for selection.

YAML Serialization

All symbols are saved in the YAML file with their selected state preserved. This allows toggling symbols on/off without needing to re-add them from XML:

EL3104:
  description: 4Ch Analog Input +/-10V Diff
  identity:
    vendor_id: 2
    product_code: 203427920
    revision_number: 1114112
  pdo_groups:
    - name: Standard
      is_default: true
      pdo_indices: [0x1a00, 0x1a02, 0x1a04, 0x1a06]
      symbol_indices: [0, 1, 2, 3]
    - name: Compact
      is_default: false
      pdo_indices: [0x1a01, 0x1a03, 0x1a05, 0x1a07]
      symbol_indices: [4, 5, 6, 7]
  selected_pdo_group: Standard
  symbol_nodes:
    - name_template: Standard_Ch1
      selected: true
    - name_template: Standard_Ch2
      selected: true
    - name_template: Compact_Ch1
      selected: false  # Not in active group
    # ... all symbols saved with their selection state

For terminals with dynamic PDOs, symbols not in the active group are saved with selected: false. This preserves the full terminal definition while tracking which symbols should be active in EPICS.

Default Group Selection

When loading a new terminal from XML:

1. Parse AlternativeSmMapping to find PDO groups

2. Identify the default group (marked with Default="1")

3. Set selected_pdo_group to the default group name

4. Pre-select only symbols belonging to the default group

This ensures new terminals start with a sensible default configuration matching what TwinCAT would use.

See Also

• Terminal YAML Definitions - How terminal definitions are structured

• Useful Notes on ADS and TwinCAT - Details on ADS access methods