CoE Parameters

This page explains how CANopen over EtherCAT (CoE) parameters work in fastcs-catio.

What are CoE Parameters?

CoE (CANopen over EtherCAT) is a protocol that allows access to device parameters on EtherCAT terminals. Unlike process data (PDOs) which update cyclically, CoE parameters are read/written on demand and typically contain configuration settings, device identification, and diagnostic information.

CoE Addressing

CoE parameters are addressed using an index and subindex:

• Index: A 16-bit value (4 hex digits, e.g., 0x1000)

• Subindex: An 8-bit value, but formatted as 4 hex digits for consistency (e.g., 0x0000)

Standard CoE Indices

Beckhoff terminals follow the CANopen standard for common indices:

Index	Name	Typical Type	Description
0x1000	Device Type	UDINT	Device type identifier
0x1008	Device Name	STRING	Human-readable device name (e.g., “EL1502”)
0x1009	Hardware Version	STRING	Hardware revision
0x100A	Firmware Version	STRING	Firmware/software revision
0x1018	Identification	Various	Vendor ID, product code, revision
0x8000+	Operational Settings	Various	Terminal-specific configuration

YAML Definition

CoE objects are defined in terminal YAML files under the coe_objects key:

coe_objects:
  - index: 4096          # 0x1000 in decimal
    name: Device type
    type_name: UDINT
    bit_size: 32
    access: ro           # "ro" = read-only, "rw" = read-write
    subindices: []
    fastcs_name: device_type

  - index: 4104          # 0x1008 in decimal
    name: Device name
    type_name: STRING(6)
    bit_size: 48
    access: ro
    subindices: []
    fastcs_name: device_name

Field Descriptions

• index: The CoE index as a decimal integer

• name: Human-readable name from Beckhoff documentation

• type_name: TwinCAT/IEC 61131-3 type (UDINT, UINT, STRING(n), etc.)

• bit_size: Size in bits (used for compound types)

• access: Access mode - “ro” (read-only) or “rw” (read-write)

• subindices: List of subindex definitions for complex objects

• fastcs_name: The attribute name exposed in FastCS (snake_case)

Implementation Architecture

The CoE parameter system uses several components:

        flowchart TD
    YAML[Terminal YAML] --> CoEAdsItem
    CoEAdsItem --> add_coe_attribute
    add_coe_attribute --> AttrR/AttrRW
    AttrR/AttrRW --> IORef[CATioControllerCoEAttributeIORef]
    IORef --> Query[COE_PARAM Query]
    Query --> get_coe_param
    get_coe_param --> read_io_coe_parameter
    read_io_coe_parameter --> ADS[ADS Protocol]
    

Key Classes

• CoEAdsItem: Dataclass holding CoE object metadata from YAML (index, subindex, type, access)

• CATioControllerCoEAttributeIORef: IO reference storing the CoE address and data type for FastCS

• AmsAddress: The EtherCAT device address obtained via client.get_coe_ams_address(terminal)

Type Mapping

TwinCAT types are mapped to numpy dtypes and FastCS datatypes:

TwinCAT Type	NumPy dtype	FastCS DataType
BOOL	bool	Int()
SINT, INT, DINT, LINT	int8, int16, int32, int64	Int()
USINT, UINT, UDINT, ULINT	uint8, uint16, uint32, uint64	Int()
REAL, LREAL	float32, float64	Float()
STRING(n)	S{n}	String(n+1)

Note: String types add +1 to accommodate the null terminator that CoE reads include.

Common Issues and Solutions

Index/Subindex Format

The check_coe_indices_format function expects both index and subindex as 4-character hex strings (after removing 0x prefix):

# Correct: Both are 4 hex digits
index_hex = "0x1000"      # -> "1000"
subindex_hex = "0x0001"   # -> "0001"

# Wrong: Subindex too short
subindex_hex = "0x01"     # -> "01" (only 2 chars - will fail!)

String Buffer Size

CoE string reads include a null terminator. The FastCS String datatype must account for this:

# For STRING(6), the response will be 7 bytes: "EL1502\0"
# So we create String(7), not String(6)
if dtype.kind == "S":
    return String(dtype.itemsize + 1)

Missing Query Methods

The client must have get_coe_param and set_coe_param methods to handle the COE_PARAM query command used by the attribute IO system. Without these, CoE reads fail silently and return empty strings.

Read vs Write Access

CoE parameters have access modes that determine whether they can be modified:

• Read-only (ro): Creates AttrR - value can only be read

• Read-write (rw): Creates AttrRW - value can be read and written

The access mode is determined by the readonly property on CoEAdsItem, which checks for patterns like “ro”, “Read-only” (readonly) vs “rw”, “Read/Write” (read-write).

Primitive vs Compound Types

CoE objects can have:

• Primitive types: UINT, DINT, STRING, etc. - these create FastCS attributes

• Compound types: DT8020, custom structures - these are skipped (no io_ref created)

The is_primitive_type property checks if the type is in the known TwinCAT type mapping or matches the STRING(n) pattern.