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/2.1/bin/xrt

The permission granted by the setcap operation will remain in place until Edge 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.4/lib
/opt/iotech/xrt/2.1/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
CyclicProcessingLibrary	String	If set, defines the shared library that will be loaded in order to resolve the CyclicProcessingFunction - see below	Empty
CyclicProcessingFunction	String	If set, defines a function that will be called when scheduled cyclic data is available.	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,
    "CyclicProcessingLibrary":"libcyclic.so",
    "CyclicProcessingFunction":"process_cyclic",
    "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 and Binary PDO resources, length of data to be read/written in bytes	For InitialSDO 1, 2, 4, 8. For Binary PDO UInt16
bitLength	For UInt8 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

In addition, PDO resources support Binary data, which allows for read/write of an arbitrary number of bytes without processing.

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, as described in Perform PDO Assignment
• Create a PDO resource, as described in Create a PDO Resource

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 byteLength attribute must be set for Binary resources

The following attributes are optional:

• The offsetBits attribute may be set to the number of bits to offset for the resource within the offset byte
• The bitLength attribute may be set to limit the number of bits considered for Uint8 resources

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>"
  }
}

Cyclic Processing

The EtherCAT device service extends the scheduled read mechanism in Xrt to allow publishing of PDO data when it is received. If the Cyclic option on a schedule is set to true, the specified interval will be ignored, and instead the schedule will be synchronized to the PDO cycle defined by the CycleTime_us configuration parameter.

Note

In this configuration, readings are not grouped - there will be one message published for each resource specified.

Additionally, a mechanism is provided whereby cyclic data may be provided directly to an application function. If the CyclicProcessingFunction options are provided in the service configuration, then instead of publishing cyclic data via the Xrt bus, the device service will call the function specified. If the CyclicProcessingLibrary option is provided, the device service will load the specified library and resolve the application function from that. This function should conform to the following signature:

void cyclic_app_fn (const iot_data_t *d);

The data passed to this function is a map, the keys of which are device names (strings) and the values of which are also maps. The keys of these sub-maps are resource names, and the values are the PDO readings which have been received.

Note

In the current implementation, the processing function is called in the thread which controls the cyclic requests. It is therefore timing-critical; if it takes too long, the subsequent cycle will be delayed.

For best performance, Binary RxPDOs may be used. The data contained in the reading may be modified by the processing function, and it will be written back to the PDO on the next cycle.

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.