Skip to content

EtherCAT Device Service Component

The EtherCAT Device Service component acts as an EtherCAT master, communicating with EtherCAT slaves. For an introduction to the EtherCAT protocol, see The Ethernet Fieldbus.

The EtherCAT Device Service supports the following key features:

  • Single network interface operation
  • Double network interface operation to allow for redundancy in the network
  • Configurable cycle time, ranging from 250 μs to 50 ms
  • Distributed clock (DC) synchronization
  • Configurable boot-up state of all slaves to either Safe-Operational (SAFE-OP) or Operational (OP)
  • Initialize all EtherCAT slaves on the network with the choice of pre-configuring service data object (SDO) writes to occur when the device service starts
  • Initialize all EtherCAT slaves on the network with the choice of pre-configuring process data object (PDO) assignments to occur when the device service starts
  • Read slave states
  • Change slave states where the options for change are SAFE-OP and OP
  • Read/Write PDOs
  • Read/Write SDOs using CANopen Over EtherCAT (CoE)

System requirements for EtherCAT Device Service

In order for the device service to communicate with EtherCAT devices, it needs to have low-level access to the network interface. Enable this by running the following command:

sudo setcap cap_net_admin,cap_net_raw=eip /opt/iotech/xrt/bin/xrt

The permission granted by the setcap operation will remain in place until xrt is updated or re-installed.

Privileged executables do not access libraries specified via LD_LIBRARY_PATH, so it is necessary to configure the dynamic linker with the required paths. For standard installations, create a file /etc/ld.so.conf.d/xrt.conf with the following content:

/opt/iotech/iot/1.3/lib
/opt/iotech/xrt/2.0/lib

EtherCAT Device Service Configuration

Note

The core components required for running EtherCAT (and all other device services) are contained in Device Service Component Configuration. Please refer to this page to ensure the appropriate core components are assigned before continuing.

With those components assigned, there are also the following optional EtherCAT Driver options that can be used to configure the device service:

EtherCAT Driver Options

Parameter Type Description Default Value
NetworkInterface1 String The primary network interface name
This field is required
Empty
NetworkInterface2 String If used, the secondary, redundant, network interface name
This field is optional
Empty
CycleTime_us Unsigned int, range 50-50000 Defines the time between each cyclic update in microseconds
This field is required
Empty
FinalState String, either SAFE_OP or OP Defines the state that all slaves are to reach by the end of the initialization or reconfiguration of the device service
This field is required
Empty

A template of the EtherCAT Device Service configuration file is provided below where the driver options have been set to demonstrate their usage:

{
  "Library": "libxrt-ethercat-device-service.so",
  "Factory": "xrt_ethercat_device_service_factory",
  "Name": "ethercat",
  "TelemetryTopic": "xrt/devices/ethercat/telemetry",
  "RequestTopic": "xrt/devices/ethercat/request",
  "ReplyTopic": "xrt/devices/ethercat/reply",
  "DiscoveryTopic": "xrt/devices/ethercat/discovery",
  "ProfileDir": "deployment/profiles",
  "StateDir": "deployment/state",
  "Scheduler": "sched",
  "Logger": "logger",
  "ThreadPool": "pool",
  "Bus": "bus",
  "Driver": {
    "NetworkInterface1": "eno1",
    "CycleTime_us": 4000,
    "FinalState": "OP"
  }
}

EtherCAT Device Profile

Details on general profile usage can be found on the Device Profiles page

The following sections will cover how device resources are mapped to EtherCAT data objects.

Attributes

The attributes used in an EtherCAT device resource are described in the following table. All device resources require the type attribute, different combinations of the other attributes may be used depending on the type which are detailed in the table below:

Attribute Description Valid Values
type The type of resource being defined State, SDO, RxPDO, TxPDO, InitialSDO, AssignPDO
index For SDO and InitialSDO resources, index of the data object being addressed UInt16
subIndex For SDO and InitialSDO resources, sub-index of the data object being addressed UInt8
byteLength For InitialSDO resources, length of data to be read/written in bytes 1, 2, 4, 8
bitLength For PDO resources, length of data to be read/written in bits 0-8
offsetBits For PDO resources, offset of the data of interest within the value returned from the device, in bits 0-8
offsetBytes For PDO resources, offset of the data of interest within the value returned from the device, in bytes UInt8
value For InitialSDO resources, the value to be written to the SDO UInt64
RxPDO For AssignPDO resources, the Receive PDOs to assign Array of UInt16
TxPDO For AssignPDO resources, the Transmit PDOs to assign Array of UInt16

Data Types

The following table lists the EtherCAT data types used in the EtherCAT Slave Information (ESI) files and their equivalent XRT data type. Note that for BIT# data, the bitLength attribute should also be specified:

EtherCAT Data Type XRT Data Type
BIT# UInt8
BOOL Bool
DINT Int32
INT Int16
LINT Int64
LREAL Float64
REAL Float32
SINT Int8
String(#) String
UDINT UInt32
UINT UInt16
ULINT UInt64
USINT UInt8

State Device Resources

When defining an EtherCAT device profile, IOTech recommends that the State device resource is included.

Including the State device resource allows you to do the following:

  • Read the current state of a device
  • Change the state of a device

A state resource requires no additional attributes, and its datatype is String.

The following extract from a device profile shows the definition of a State device resource:

{
  "name": "State",
  "description": "Write Options: SAFE_OP, OP",
  "attributes": {
    "type": "State"
  },
  "properties": {
    "valueType": "String",
    "readWrite": "RW"
    "units": "Slave State"
  }
}

Service Data Objects

For SDOs, you can do the following:

  • Configure an SDO so that it can be written to on initialization while in the Pre- operational state, as described in Configure an SDO
  • Create an SDO resource, as described in Create an SDO Resource

Configure an SDO

  • An SDO can be configured to allow it to be written to on initialization by setting the type attribute to InitialSDO in the device resources. The index, subIndex, byteLength and value attribute fields are required. The following extract illustrates a resource of this kind:
{
  "name": "<initial SDO resource name>",
  "description": "<description of resource>",
  "attributes": {
    "type": "InitialSDO",
    "index": 32786,
    "subIndex": 1,
    "byteLength": 1,
    "value": 3
  },
  "properties": {
    "valueType": "String",
    "readWrite": ""
  }
}

Note

index, subIndex, byteLength and value are all unsigned decimal integers.

Note

Resources with type InitialSDO are only used by the device service on start-up and are not readable by the user.

Create an SDO Resource

To create an SDO resource, check the address, index, sub-index and data type in the datasheet or EtherCAT Slave Information (ESI) file for the slave, then set the following in the device resource section of the device profile:

  • The type attribute must be set to SDO
  • The index attribute must be set to the decimal address of the SDO resource
  • the subIndex attribute must be set to the decimal sub-index of the SDO resource

The following extract provides a template for the creation of an SDO resource:

{
  "name": "<service data object resource name>",
  "description": "<description of resource>",
  "attributes": {
    "type": "SDO",
    "index": 7219,
    "subIndex": 32
  },
  "properties": {
    "valueType": "<XRT data type>",
    "readWrite": "<R/W/RW>"
  }
}

Note

If the SDO resource uses the BIT# data type in a Slave's ESI file, the UInt8 data type

must be used in the device resource definition and the bitLength attribute must define the length in bits of the value. For further information on the equivalent data types, see EtherCAT Data Types.

Process Data Objects

For PDOs, you can do the following:

Perform PDO Assignment

To perform PDO Assignment on a slave, you must include a device resource with the type attribute set to AssignPDO. This resource is used only by the device service on start-up to perform PDO assignment of a particular device and is not readable by the user.

The following attributes are also set in the device resource section of the device profile:

  • The RxPDO attribute must be set to the decimal address of the data input. Multiple addresses must be separated by a comma. The first sub-index of the RxPDO attribute assignment is reserved for diagnostic messages; in the example below, this is set to 3 - initialization
  • The TxPDO attribute must be set to the decimal address of the data output. Multiple addresses must be separated by a comma. The first sub-index of the TxPDO attribute assignment is reserved for diagnostic messages; in the example below, this is set to 2 - communication established

The following extract provides a template for PDO Assignment:

{
  "name": "<process data object assignment resource name>",
  "description": "<description of resource>",
  "attributes": {
    "type": "AssignPDO",
    "RxPDO": [ 3, 5633, 5634, 5635 ],
    "TxPDO": [ 2, 6657, 6659 ]
  },
  "properties": {
    "valueType": "String",
    "readWrite": ""
  }
}

Create a PDO Resource

To create a PDO resource, check the RxPDO and TxPDO elements in the ESI file for the slave. When a slave's process data is assigned on initialization, the RxPDOs and TxPDOs are mapped to separate pointers, each with a stating byte of zero (0).

The pointers set the start byte at 0. Where PDOs are assigned sequentially, the addressing starts from byte 0 and continues stacking the size of the PDOs for the slave. For example, if two TxPDOs are assigned, each 16 bits in length, any resource in the first TxPDO is addressed in byte 0 or byte 1 and the second TxPDO is addressed with a start byte of 2 or 3.

To create a PDO resource, you must set the following attributes:

  • The type attribute must be set to either RxPDO or TxPDO
  • The offsetBytes attribute must be set to the number of bytes to offset for the resource within the process data
  • The offsetBits attribute must be set to the number of bits to offset for the resource within the offset byte

The following extract provides a template for the creation of a PDO resource:

{
  "name": "<process data object resource name>",
  "description": "<description of resource>",
  "attributes": {
    "type": "RxPDO/TxPDO",
    "offsetBytes": 0,
    "offsetBits":2
  },
  "properties": {
    "valueType": "<XRT data type>",
    "readWrite": "<R/W/RW>"
  }
}

Device Commands

See the Device Profiles page for details on how to define device commands for grouping device resources for fewer requests.

EtherCAT Device Provisioning

Note

For information on dynamic device additions, removals and updates please see the MQTT API Guide.

To provision an EtherCAT device, the EtherCAT protocol must be used along with one of two identifying protocol properties, SerialNumber or NetworkIndex.

  • Using the serial number

This method searches the devices on the network for a matching serial number on start-up. Serial numbers are read using CoE, if available, and the Slave Information Interface located in EEPROM is also checked. If a match is found, the network index of the matching device is noted by the device service.

Note

In EtherCAT, serial numbers may not be unique.

  • Using the network index

The network index identifies the slaves by their connection to the master; the first connected slave has a network index of 1 and each subsequent connected slave has a network index of +1.

A basic example of an EtherCAT device provision within the devices.json file is provided below:

{
  "EL7037": {
    "name": "EL7037",
    "profileName": "EL7037-VelocityDirect",
    "protocols": {
      "EtherCAT": {
        "NetworkIndex": 1
      }
    }
  }
}

Device Protocol Properties

In addition to specifying a device by its network index or serial number, properties may be specified which control synchronization. The full list of available properties is as follows:

Parameter Type Description Default Value
SerialNumber UInt32 decimal The serial number of the device Empty
NetworkIndex UInt16 decimal The index on the network that identifies the slave Empty
SyncMode Int: 1, 2 or 3 The synchronization mode set for the device

If set to 1, the slave's local cycle is triggered on receipt of an SM2/3 event, which means that the slave activates its outputs and reads its inputs when a cyclic EtherCAT packet passes through (SM Synchronous)

If set to 2, the slave runs on a distributed clock where the Sync0Cycle property controls how large a Sync0 cycle time there is for the slave (DS Sync0)

If set to 3, the slave runs on a distributed clock where the Sync1Cycle property controls how large a Sync1 cycle time there is for the slave. The Sync01Cycle property is also used to control how small a Sync0 cycle time there is for the slave (DC Sync1)
1
SyncShift Int: -2000000 to +2000000 The shift time of the sync interrupts in μs 0
Sync0Cycle Int: 1 to 80 Sync0 cycle time as a multiple of the master cycle time Empty
Required for Sync mode 2
Sync1Cycle Int: 1 to 80 Sync1 cycle time as a multiple of the master cycle time Empty
Required for Sync mode 3
Sync01Cycle Int: 1 to 1000000000 Sync0 cycle time as a division of the Sync1 cycle time Empty
Required for Sync mode 3

Each synchronization method requires a different set of protocol properties to provision a device. The required and optional properties for each synchronization method are provided in the following table:

Mode Required Properties Optional Properties
SM Synchronous SerialNumber or NetworkIndex

SyncMode=1
None
DC Sync0 SerialNumber or NetworkIndex

SyncMode=2

Sync0Cycle
SyncShift
DC Sync1 SerialNumber or NetworkIndex

SyncMode=3

Sync1Cycle

Sync01Cycle
SyncShift

An example configuration for the EtherCAT Device Service component is provided below, for the following devices:

  • Beckhoff EK1100 Bus Coupler
    • Network Index: 1
    • Synchronization mode: SM Synchronous
  • Beckhoff EL7037 Stepper Motor Terminal in Velocity Direct Mode
    • Serial Number: 26279
    • Synchronization mode: DC Sync0
    • Sync0 cycle time: 8000 μs
    • Sync shift: 14 μs
  • Infineon XMC4800 Development Board 1
    • Network Index: 3
    • Synchronization mode: SM Synchronous
  • Infineon XMC 4800 Development Board 2
    • Network Index: 4
    • Synchronization mode: DCSync1
    • Sync1 cycle time 16000 μs

The configuration is as follows:

{
  "EK1100": {
    "name": "EK1100",
    "profileName": "EK1100",
    "protocols": {
      "EtherCAT": {
        "NetworkIndex": 1,
        "SyncMode": 1
      }
    }
  },
  "EL7037": {
    "name": "EL7037",
    "profileName": "EL7037-VelocityDirect",
    "protocols": {
      "EtherCAT": {
        "SerialNumber": 26279,
        "SyncMode": 2,
        "Sync0Cycle": 2,
        "SyncShift": 14
      }
    }
  },
  "XMC4800_1": {
    "name": "XMC4800_1",
    "profileName": "XMC4800_V3_1",
    "protocols": {
      "EtherCAT": {
        "NetworkIndex": 3,
        "SyncMode": 1
      }
    }
  }
  "XMC4800_2": {
    "name": "XMC4800_2",
    "profileName": "XMC4800_V3_1",
    "protocols": {
      "EtherCAT": {
        "NetworkIndex": 4,
        "SyncMode": 3,
        "Sync1Cycle": 4,
        "Sync01Cycle": 16,
        "SyncShift": 14
      }
    }
  }
}

EtherCAT Device Service Interaction

For information on how to dynamically execute reads, writes, setting up schedules, triggering device discovery and much more, please refer to the MQTT API Guide.

For interactive examples of the EtherCAT Device Services refer to EtherCAT XRT Example.

Run the EtherCAT Device Service

Find details on how to run the EtherCAT Device Service on the Run Device Services page.

Back to top