EtherCAT Library API User Manual

2024.08.15, Version 2.2.

1. Introduction

1.1 About QEC Master

QEC Master is an EtherCAT Master System compatible with 86Duino Coding IDE 500+. It offers real-time EtherCAT communication between EtherCAT Master and EtherCAT slave devices. Except for the EtherCAT Library of 86Duino IDE, QEC Master also provides Modbus, Ethernet TCP/IP, CAN bus, etc. industrial communication protocols and uses a rich high-level C/C++ programming language for rapid application development.

1.1.1 What is 86Duino IDE?

The 86Duino integrated development environment (IDE) software makes it easy to write and upload code to 86Duino boards and QEC Master devices. It runs on Windows, Mac OS X, and Linux. The environment is written in Java and based on Arduino IDE, Processing, DJGPP, and other open-source software, which can be downloaded from https://www.qec.tw/software/.

QEC Master’s software, 86Duino IDE, also offers a configuration utility: 86EVA, a graphic user interface tool for users to edit parameters for the EtherCAT network; its functions are as follows:

• EtherCAT slave devices scanning
• Import ENI file
• Setting EtherCAT Master
• Configure EtherCAT slave devices

For other detailed functions, please refer to the 86EVA User Manual.

1.1.2 QEC EtherCAT Master Architecture

The EtherCAT Master software is primarily divided into two parts, each running on the respective systems of the Vortex86EX2 CPU. They are responsible for the following tasks:

• EtherCAT Master Library
  • Provides C/C++ application interfaces:
    • Initialization interface.
    • Configuration interface.
    • Process Data (PDO) access interface.
    • CAN application protocol over EtherCAT (CoE) access interface.
    • File access over EtherCAT (FoE) access interface.
    • Slave Information Interface (SII) access interface.
    • Distributed Clocks (DC) access interface.
• EtherCAT Master Firmware
  • Executes the EtherCAT Master Core.
  • Controls the Primary/Secondary Ethernet Driver, sending EtherCAT frames

The programs are designed to run on the FreeDOS operating system and have been compiled using the GCC compiler provided by the DJGPP environment.

1.1.3 Hardware Platform

The EtherCAT Master software only runs on the Vortex86EX2 CPU produced by DM&P, which features a dual-system architecture. It is divided into Master System and Slave System, each running its own operating system, with communication between systems facilitated by Dual-Port RAM and event interrupts. Their respective tasks are as follows:

• Master System
  • User’s EtherCAT application.
  • User’s HMI application.
  • User’s Ethernet application.
  • And so on.
• Slave System
  • Only responsible for running the EtherCAT Master Firmware.

As most applications run on the Master System, the EtherCAT Master Firmware running on the Slave System is free from interference by other applications. This setup allows it to focus on executing the EtherCAT Master Core, ensuring the synchronization and real-time capabilities of EtherCAT.

1.1.4 Dual-System Synchronization

The primary focus of this section is the synchronization of dual-system PDO data. As illustrated in the diagram below, the User Application and EtherCAT Master Library blocks run on the Master System, while the Real-Time EtherCAT Master Core runs on the Slave System.

When the EtherCAT Master Core reaches the Process Inputs stage, it receives all cyclic frames from the Ethernet Driver and copies Input PDO data to the DPRAM.

Upon reaching the User Application stage, the EtherCAT Master Core triggers a Cyclic Interrupt to the Master System. Upon receiving the Cyclic Interrupt, the Master System executes the interrupt handling procedure of the EtherCAT Master Library. It moves Input PDO data from DPRAM to Main Memory, calls the user-registered Cyclic Callback, transfers Output PDO data from Main Memory to DPRAM after the Cyclic Callback completes, processes acyclic commands, and concludes the interrupt handling procedure. At this point, both the EtherCAT Master Core’s User Application and the interrupt handling procedure are completed simultaneously.

When the EtherCAT Master Core reaches the Write Outputs stage, it copies Output PDO data from DPRAM to the Ethernet Driver’s DMA and sends frames.

These tasks are executed periodically in a cyclic manner, following the outlined procedural steps, ensuring the synchronization of dual-system PDO data.

1.2 Features

The EtherCAT Technology Group defined two classes of EtherCAT Master software implementation in ETG.1500. This specification defines Master Classes with a well-defined set of Master functionalities. In order to keep things simple only 2 Master Classes are defined:

• Class A: Standard EtherCAT Master Device
• Class B: Minimum EtherCAT Master Device

You will see the comparison among Class A, Class B, and our QEC Master as follows.

1.2.1 Feature Table

Word Usage:

• shall: equals is required to.
• should: equals is recommended that.
• may: equals is permitted to.
• O: equals supported.

1.3 Feature Packs

1.3.1 Cable Redundancy

EtherCAT Cable Redundancy refers to the capability of the EtherCAT communication system to maintain continuous and reliable communication even in the event of a cable failure. Cable Redundancy employs a ring topology, which is operated in both directions. If one cable fails or is disconnected, another cable path still works to ensure uninterrupted communication. Cable Redundancy enhances the fault tolerance of the EtherCAT network, minimizing downtime and improving overall system reliability.

Three scenarios are listed as below regarding whether the cable is broken or not in Cable Redundancy. The following you will see how to work for Cable Redundancy, and the differences for the EtherCAT Master Controller between these scenarios.

• Without Cable Broken
• Cable Broken between two slaves
• Cable broken between master and slave

For ease of explanation, some assumptions will be made here:

• Assume Cycle Time is set to 125 µs.
• Assume all slaves only with input PDO (without output PDO), the working counter (WKC) in process data frame will increase 1 when passing through every slaves.
• Assume only have 6 slaves on EtherCAT network, and the expected working counter (EWKC) is 6.
• Primary Port and Secondary Port send process data frame in every cycle at the same time.

For more details on cable redundancy, please visit here.

1.4 Benchmark

EtherCAT is a fieldbus technology known for its high synchronization capabilities. In applications requiring high synchronization, there is often a demand for real-time performance and high control frequencies. Users in these scenarios typically consider specifications such as:

• Support for shorter cycle times
• Support for more process data
• Support for more EtherCAT slave devices

However, assessing whether an EtherCAT master meets the user’s application requirements often involves benchmark measurements as a primary consideration.

Please visit EtherCAT Master Benchmark for more details.

1.5 Synchronization

The time synchronization among all slaves in an EtherCAT network relies on the Distributed Clocks (DC) unit within the EtherCAT Slave Controller (ESC), ensuring consistency across the entire system. Typically, the first slave with DC serves as the system reference clock to synchronize other slaves with DC. For a more detailed explanation of DC, please refer to Distributed Clocks.

The ESC has three synchronization output pins: IRQ, SYNC0, and SYNC1. The IRQ pin generates a signal to the upper-layer microcontroller (µC) after the ESC receives EtherCAT Cyclic Frames. SYNC0 and SYNC1 pins cyclically generate signals to the µC based on the configuration in the DC related registers of ESC. Hence, if an EtherCAT slave does not have a µC, it does not support synchronization functionality.

There are three synchronization modes in EtherCAT:

• Free Run
• SM-Synchronous
• DC-Synchronous

1.5.1 Free Run

The EtherCAT master and all EtherCAT slaves each have their own local timer, and their cycle times are independent, so they are not synchronized. As shown in the diagram below, both the EtherCAT Master and Slave 1, Slave 2, Slave 3 to Slave n have their own Cycle Time, resulting in inconsistent Output Valid and Input Latch. This scenario is not suitable for applications with high synchronization requirements.

1.5.2 SM-Synchronous

The IRQ pin generates a SM event when the cyclic frame is received by ESC, this event will trigger the execution of the local application in µC. As shown in the diagram below, cyclic frames are received by slaves with the same jitter of master in sending them. Even assuming zero jitter, due to finite hardware Propagation Delay the last slaves will receive the cyclic frames later with respect to the first ones.

Due to the Propagation Delay, there is an offset in the timing of SM events between slaves, resulting in an accuracy of SM-Synchronous at the microsecond level.

If each slave supports the Shift Time in the SyncManager Parameter objects (0x1C32.3/0x1C33.3), it is possible to attempt to adjust the Output Valid and Input Latch of all slaves to be close to each other. However, due to the inability to calculate the propagation delays, the adjustment is quite challenging.

1.5.3 DC-Synchronous

The SYNC0 or SYNC1 pins generate SYNC events cyclically based on the configuration in the DC related registers of ESC, this event will trigger the execution of the local application in µC. As shown in the diagram below, jitters and propagation delays still exist, and SM events are still triggered after receiving cyclic frames. However, in this DC-Synchronous method, SYNC0 events are triggered cyclically, which does not suffer from jitter or propagation delays.

Because SYNC0 events are triggered by the DC unit and all SYNC0 events among the slaves have almost no offset, thanks to the periodic sending of APRW/FPRW commands to synchronize the system time of all slaves, the accuracy can reach the nanosecond level.

If the slaves support the Shift Time in SyncManager Parameter objects (0x1C32.3/0x1C33.3), it is possible to attempt to adjust the Output Valid and Input Latch timings of these slaves to the same time point.

However, the selection of the Global Shift Time in the diagram is crucial but must meet the following conditions:

• After the cyclic frames have been received by all slaves.
• Before sending the cyclic frames for the next cycle.
• According to different DC-Synchronous methods, it may need to be selected after executing Prepare Outputs:
  • Trigger µC to execute Prepare Outputs when the SM event occurs
  • Trigger µC to execute Output Valid when the SYNC event occurs.

The correct Global Shift Time is not unique; it can be chosen within the entire interval of the cycle time. To learn more about various DC-Synchronous methods, please refer to ETG.1020 EtherCAT Protocol Enhancements.

2. Functions

QEC EtherCAT Master Library.

EtherCAT is a real-time industrial Ethernet communication protocol widely used in automation and control systems. QEC-Master is an EtherCAT master library implemented in C/C++, which includes classes for the master, generic slave, CiA 402 slave, and dedicated classes for QEC series slaves. These classes not only have clearly defined responsibilities but also consider future extensibility.

These classes can be divided into three parts as follows:

• EtherCAT Master
  The EtherCAT Master part not only provides various and flexible master configuration and operation functions but also offers diverse EtherCAT slave operation functions for invocation by the EtherCAT Device part.

• EtherCAT Device
  The EtherCAT Device part provides generic EtherCAT slave device classes, which can operate functions such as PDOs, CoE, FoE, and also includes CiA 402 slave generic class.

• QEC Series Device
  The QEC Series Device part provides dedicated functions for ICOP’s QEC series slave devices, enabling users to code in a more user-friendly and concise manner.

2.1 EtherCAT Master

The EtherCAT Master part not only provides various and flexible master configuration and operation functions but also offers diverse EtherCAT slave operation functions for invocation by the EtherCAT Device part.

EthercatMaster is the only class in the EtherCAT Master part, it serves as a crucial communication bridge with the EtherCAT firmware. In the Dual-System communication aspect, its responsibilities include communication interface initialization, process data exchange cyclically, handling acyclic transfer interfaces, and managing interrupt events. In the API aspect, it provides functions related to master initialization, master control, and access to slave information.

The main class relationship between the EtherCAT Master part and the EtherCAT Device part is association, with the EtherCAT Device part depending on the EtherCAT Master part. The class relationships of EthercatMaster are illustrated in the following diagram:

• There is an association between EthercatMaster and _EthercatDevice_CommonDriver, with _EthercatDevice_CommonDriver depending on EthercatMaster.
• There is an association between EthercatMaster and EthercatDevice_CiA402, with EthercatMaster depending on EthercatDevice_CiA402.

EtherCAT Master Settings

This library offers a variety of configuration parameters for users to choose from, aiming to meet the diverse application needs of users. Below are the configuration parameters provided by this library.

typedef struct {

    EthercatDcSyncMode DcSyncMode;
    uint32_t StaticDriftCompensationFrames;

    uint32_t StateMachineTimeoutI2P;
    uint32_t StateMachineTimeoutP2S;
    uint32_t StateMachineTimeoutS2O;
    uint32_t ScanNetworkTimeout;
    uint32_t StartMasterTimeout;
    uint32_t StartDeviceTimeout;

    uint32_t ErrorDetectWkcMultipleFaultsThreshold;
    uint32_t ErrorDetectMultipleLostFramesThreshold;
    uint32_t EnableErrorBusReactionSyncUnitToSafeOp:1,
             EnableErrorBusReactionSyncUnitToSafeOpAutoRestart:1,
             IgnoreBiosOverride:1;

} EthercatMasterSettings;

DcSyncMode

Default: ECAT_MASTER_SHIFT
In DC-Synchronous mode, the first slave with DC serves as the system reference clock to synchronize other slaves with DC. However, this only involves synchronizing the system time of all slaves on the network and does not include the EtherCAT master. In applications with DC-Synchronous mode enabled, the master usually needs to precisely and periodically control the slaves, so the master must also synchronize its system time with all slaves on the network.
There are two methods for this synchronization:

• Master Shift Mode – ECAT_MASTER_SHIFT
  
  • The master system time is synchronized to the reference clock.
  • All DC slaves are synchronized to the reference clock.
• Bus Shift Mode – ECAT_BUS_SHIFT
  
  • The reference clock is synchronized to the master system time.
  • All DC slaves are synchronized to the reference clock.

StaticDriftCompensationFrames

Default: 30000
The EtherCAT master sends many separate ARMW or FRMW drift compensation frames to distribute the System Time of the reference clock to all DC slaves.

StateMachineTimeoutI2P

Default: 3000; Unit: milliseconds
Timeout for the transition from the Init state to the Pre-Operational state.

StateMachineTimeoutP2S

Default: 10000; Unit: milliseconds
Timeout for the transition from the Pre-Operational state to the Safe-Operational state.

StateMachineTimeoutS2O

Default: 10000; Unit: milliseconds
Timeout for the transition from the Safe-Operational state to the Operational state.

ScanNetworkTimeout

Default: 5000; Unit: milliseconds
Timeout for scan network. The scan network operation is executed within EthercatMaster::begin().

StartMasterTimeout

Default: 3000; Unit: milliseconds
Base timeout for start master, T~base~.
In EthercatMaster::start(), the firmware is requested to start EtherCAT, and the timeout for this request is referred to as startup timeout, T~startup~.
The startup timeout for EtherCAT is calculated as follows: $$ T_{startup} = T_{base} + ( T_{slave} × N_{slaves}) $$ Here, N~slaves~ is the number of slaves on the network.

StartDeviceTimeout

Default: 500; Unit: milliseconds
Timeout per slave for start master, T~slave~.

ErrorDetectWkcMultipleFaultsThreshold

Default: 3
The master should check the Working Counter of a received EtherCAT datagram. If the Working Counter does not match with the expected value an error is detected. When the number of consecutive errors exceeds this parameter, an ECAT_ERR_WKC_MULTIPLE_FAULTS error interrupt will be triggered.

ErrorDetectMultipleLostFramesThreshold

Default: 3
The master may use the index of the EtherCAT datagram header to check if all sent EtherCAT datagrams will be received. If EtherCAT datagrams are lost an error is detected. When the number of consecutive errors exceeds this parameter, an ECAT_ERR_MULTIPLE_LOST_FRAMES error interrupt will be triggered.

EnableErrorBusReactionSyncUnitToSafeOp

Default: 0
If this parameter is set to 1, the master will change the EtherCAT state of the slaves with an application controller and will disable the Sync Manager channels of the slaves which only support the EtherCAT state machine emulation.

EnableErrorBusReactionSyncUnitToSafeOpAutoRestart

Default: 1
This parameter only takes effect if EnableErrorBusReactionSyncUnitToSafeOp is set to 1. If this parameter is set to 1, the master will automatically attempt to restart the Sync Unit according to the Restart Behavior of a Sync Unit in the Master as defined in ETG.1020 EtherCAT Protocol Enhancements, switching the EtherCAT state machine back to the Operational state.

IgnoreBiosOverride

Default: 0
QEC-Master has some EtherCAT configuration parameters in the BIOS. Setting this parameter to 1 means ignoring the EtherCAT configuration parameters in the BIOS; otherwise, they are not ignored.

2.1.1 Initialization Functions

Before starting the EtherCAT master, it must be initialized. This library offers a variety of configuration parameters for users to choose from, aiming to meet the diverse application needs of users.

• begin()
• end()
• isRedundancy()
• libraryVersion( )
• firmwareVersion( )
• readSettings()
• saveSettings()

2.1.2 Callback Functions

This library provides three types of callbacks as follows:

• Cyclic Callback
  The purpose of the Cyclic Callback is to allow users to implement periodic control systems such as motion control, CNC control, and robot control. The Real-Time EtherCAT Master Core triggers cyclic interrupts to the EtherCAT Master Library at specified cycle time, then waiting for an ACK to ensure process data synchronization. If a user has registered a Cyclic Callback, it will be invoked to achieve periodic control.
• Error Callback
  When the Real-Time EtherCAT Master Core detects an error, it will trigger an error interrupt and pass a 32-bit error code to the EtherCAT Master Library. If the user has registered an error callback, the system will invoke that callback to inform the user of the specific error.
  The error codes supported by the Error Callback are as follows:

• Event Callback
  When the Real-Time EtherCAT Master Core detects an event, it triggers an event interrupt and passes a 32-bit event code to the EtherCAT Master Library. If the user has registered an event callback, the system will invoke that callback to inform the user of the specific event.
  The event codes supported by the Event Callback are as follows:

• attachCyclicCallback()
• detachCyclicCallback()
• attachErrorCallback()
• detachErrorCallback()
• attachEventCallback()
• detachEventCallback()
• errGetCableBrokenLocation1()
• errGetCableBrokenLocation2()
• evtGetMasterState()

2.1.3 Slave Information Functions

This library provides functions to obtain information about EtherCAT slave devices on the network. It includes querying the number of slaves on the network, retrieving a slave’s Vendor ID, Product Code, Alias Address by its sequence number, and reverse querying the slave number using the aforementioned information. This is used to identify the type of slave device and to choose the appropriate EtherCAT slave device class to attach.

• getSlaveCount()
• getVendorID()
• getProductCode()
• getRevisionNumber()
• getSerialNumber()
• getAliasAddress()
• getSlaveNo()

2.1.4 Control Functions

The control functions provided by the EtherCAT master library are crucial for managing the state and operation of the EtherCAT network. By using these functions, users can ensure precise control over the network, achieving reliable and synchronized communication between the master and slave devices.

• start()
• stop()
• update()
• setShiftTime()
• getShiftTime()
• getSystemTime()
• getWorkingCounter()
• getExpectedWorkingCounter()

2.2 EthercatDevice

The EtherCAT Device part provides generic EtherCAT slave device classes, which can operate functions such as PDOs, CoE, FoE, and also includes CiA 402 slave generic class.

The main class relationship between the EtherCAT Device part and the EtherCAT Master part is association, with the EtherCAT Device part depending on the EtherCAT Master part. As shown in the diagram below, there is an association relationship between _EthercatDevice_CommonDriver and EthercatMaster.

• There is an association between EthercatMaster and _EthercatDevice_CommonDriver, with _EthercatDevice_CommonDriver depending on EthercatMaster.
• All other EtherCAT slave device classes inherit from _EthercatDevice_CommonDriver.

WARNING: Prohibited from declaring objects using this class.

2.2.1 _EthercatDevice_CommonDriver

_EthercatDevice_CommonDriver is an abstract class that not only features functions for accessing slave information but also provides various EtherCAT function access methods, including PDO, SII, CoE, FoE, DC, etc. All EtherCAT slave classes inherit from it.

The class relationships of _EthercatDevice_CommonDriver are illustrated in the following diagram:

• There is an association between EthercatMaster and _EthercatDevice_CommonDriver, with _EthercatDevice_CommonDriver depending on EthercatMaster.
• All other EtherCAT slave device classes inherit from _EthercatDevice_CommonDriver.

WARNING: Prohibited from declaring objects using this class.

Information Functions

The library provides functions for obtaining information about EtherCAT slave devices on the network. This includes essential details such as Vendor ID, Product Code, Alias Address, and Device Name, used for device identification. Moreover, it offers information on whether the EtherCAT slave device supports specific features like CoE, FoE, DC, etc. This slave information enables users to understand the characteristics and capabilities of devices within the network and perform corresponding configuration and control tasks.

• getVendorID()
• getProductCode()
• getRevisionNumber()
• getSerialNumber()
• getAliasAddress()
• getSlaveNo()
• getDeviceName()
• getMailboxProtocol()
• getCoEDetails()
• getFoEDetails()
• getEoEDetails()
• getSoEChannels()
• isSupportDC()

Distributed Clock (DC) Functions

The Distributed Clocks (DC) is an essential functional unit within the EtherCAT Slave Controller (ESC). It is responsible for implementing a time synchronization mechanism across the EtherCAT network, ensuring that all slave devices synchronize their clocks according to a unified time reference, thus ensuring consistency of time across the entire system.

For system synchronization all slaves are synchronized to one Reference Clock. Typically, the first ESC with Distributed Clocks capability after the master within one segment holds the reference time (System Time). This System Time is used as the reference clock to synchronize the DC slave clocks of other devices and of the master. The propagation delays, local clock sources drift, and local clock offsets are taken into account for the clock synchronization.

The ESCs can generate SyncSignals for local applications to be synchronized to the EtherCAT System Time. SyncSignals can be used directly (e.g., as interrupts) or for Digital Output updating/Digital Input sampling. Additionally, LatchSignals can be time stamped with respect to the EtherCAT System Time.

The DC unit supports the generation of a base SyncSignal SYNC0 and a dependent SyncSignal SYNC1. The second SyncSignal (SYNC1) depends on SYNC0, it can be enerated with a predefined delay after SYNC0 pulses.

If the SYNC1 Cycle Time is larger than the SYNC0 Cycle Time, it will be generated as follows: when the Start Time Cyclic Operation is reached, a SYNC0 pulse is generated. The SYNC1 pulse is generated after the SYNC0 pulse with a delay of SYNC1 Cycle Time. The next SYNC1 pulse is generated when the next SYNC0 pulse was generated, plus the SYNC1 Cycle Time.
Some example configurations are shown in the following figure:

For more detailed information, please refer to ESC Hardware Data Sheet Section I.

• setDc()

Process Data Objects (PDO) Functions

Process Data refers to real-time communication data exchanged between the master and slaves in an EtherCAT network. This data includes information used for control, monitoring, and communication purposes. The EtherCAT master cyclically transmits process data to control and monitor all slaves, ensuring high synchronization and low latency.

The Fieldbus Memory Management Units (FMMU) in the EtherCAT Slave Controller (ESC) can mapping dual-port memory to logical address. All slave nodes check the EtherCAT frames sent by the EtherCAT master, comparing the logical address of the process data with the configured address in the FMMU. If a match is found, the output process data is transferred to dual-port memory, and the input process data is inserted into the EtherCAT frame.

Overall, process data is an essential part of EtherCAT technology and is suitable for real-time applications in robot control, CNC control, automation control, and other fields.

• pdoBitWrite()
• pdoBitRead()
• pdoGetOutputBuffer()
• pdoGetInputBuffer()
• pdoWrite()
• pdoWrite8()
• pdoWrite16()
• pdoWrite32()
• pdoWrite64()
• pdoRead()
• pdoRead8()
• pdoRead16()
• pdoRead32()
• pdoRead64()

CANopen over EtherCAT (CoE) Functions

CANopen is a high-level communication protocol based on the Controller Area Network (CAN) bus, commonly used for communication between control systems and devices in industrial applications. It defines a set of communication objects, data types, and network management functions to facilitate data exchange, configuration, and control between devices.

The CANopen protocol includes the following aspects:

• Object Dictionary
  Defines all data objects and parameters exchanged between devices. The object dictionary encompasses various types of objects such as variables, parameters, events, and functions.
• PDO (Process Data Object)
  Used for real-time data transmission. PDOs allow devices to transmit data between each other in a fixed or event-triggered manner, enabling real-time control and data exchange.
• SDO (Service Data Object)
  Used for configuring and managing device parameters. SDOs provide functionalities for reading, writing, and parameter configuration, allowing devices to dynamically exchange configuration information.

CoE (CAN application over EtherCAT) is a CANopen protocol based on the EtherCAT network. It enables communication using the CANopen protocol over EtherCAT networks. The Object Dictionary contains parameters, application data and the mapping information between process data interface and application date (PDO mapping). Its entries can be accessed via Service Data Objects (SDO).
The SDO services primarily consist of two types of commands. The SDO command is utilized for accessing objects stored in the Object Dictionary, while the SDO information command is employed to retrieve details about these objects.

SDO commands:

• sdoDownload()
• sdoDownload8()
• sdoDownload16()
• sdoDownload32()
• sdoDownload64()
• sdoUpload()
• sdoUpload8()
• sdoUpload16()
• sdoUpload32()
• sdoUpload64()

SDO Information commands:

• getODlist()
• getObjectDescription()
• getEntryDescription()

File over EtherCAT (FoE) Functions

File access over EtherCAT (FoE) is a protocol extension of EtherCAT that enables file transfer capabilities over the EtherCAT network. It specifies a standard way to download a firmware or any other files to the EtherCAT slave device or to upload a firmware or any other files from the EtherCAT slave device.

• readFoE()
• writeFoE()

SII EEPROM Functions

The following APIs are still under development and are not recommended for use.

EtherCAT slave controllers use a mandatory NVRAM, typically a serial EEPROM with I²C interface, to store EtherCAT Slave Information (ESI). This information includes Vendor ID, Product Code, Mailbox Configuration, FMMU, PDO, and so on. EEPROM sizes from 1 Kbit up to 4 Mbit are supported, depending on the ESC.

The ESC Configuration Area (EEPROM word addresses 0 to 7) is automatically read by the ESC after power-on or reset. It contains the PDI configuration, DC settings, and the Configured Station Alias. The consistency of the ESC Configuration data is secured with a checksum. For more detailed information, please refer to ESC Hardware Data Sheet Section I.

• readSII()
• readSII8()
• readSII16()
• readSII32()
• writeSII()
• writeSII8()
• writeSII16()
• writeSII32()

2.2.2 EthercatDevice_Generic

EthercatDevice_Generic is a generic EtherCAT slave class that can be used to control all EtherCAT slaves, including accessing slave information, PDO, CoE, FoE, DC, and more.
The class relationships of EthercatDevice_Generic are illustrated in the following diagram:

• Relationship: EthercatDevice_Generic inherits from _EthercatDevice_CommonDriver.
• Base Class: _EthercatDevice_CommonDriver

Initialization Functions

Initialization-related functions for the EthercatDevice_Generic class.

• attach()
• detach()

2.3 QEC Series Device

The QEC-Series Device part provides dedicated functions for ICOP’s QEC series slave devices, enabling users to code in a more user-friendly and concise manner.

The main class relationship between the QEC-Series Device part and the EtherCAT Device part is association, with the QEC-Series Device part depending on the EtherCAT Device part. As shown in the diagram below, there is an association relationship between _EthercatDevice_DmpCommonDriver and _EthercatDevice_CommonDriver.

Classes:

• _EthercatDevice_DmpCommonDriver
• EthercatDevice_DmpDIQ_Generic
• EthercatDevice_DmpAIQ_Generic
• EthercatDevice_DmpHID_Generic
• EthercatDevice_DmpLCD_Generic
• EthercatDevice_DmpEM_Generic
• EthercatDevice_DmpStepper_Generic

2.3.1 _EthercatDevice_DmpCommonDriver

_EthercatDevice_DmpCommonDriver is an abstract class that provides dedicated access functions for EtherCAT slave-specific features developed by ICOP. These functions include system monitoring (temperature, voltage, current), order information, MTBF, etc.

The class relationships of _EthercatDevice_DmpCommonDriver are illustrated in the following diagram:

• _EthercatDevice_DmpCommonDriver inherits from _EthercatDevice_CommonDriver.

WARNING: Prohibited from declaring objects using this class.

System Monitoring Functions

The QEC series EtherCAT slave devices with MCU all provide CoE objects to obtain system monitoring information, including system temperature, system voltage, system current, peripheral voltage, and peripheral current. Therefore, this library provides functions to get system monitoring information, enabling users to promptly monitor the system and evaluate it for any signs of failure.

• getSystemTemperature()
• getSystemPowerVoltage()
• getSystemPowerCurrent()
• getPeripheralPowerVoltage()
• getPeripheralPowerCurrent()
• tryToGetSystemTemperature()
• tryToGetSystemPowerVoltage()
• tryToGetSystemPowerCurrent()
• tryToGetPeripheralPowerVoltage()
• tryToGetPeripheralPowerCurrent()

MTBF Functions

MTBF stands for Mean Time Between Failures. It is a reliability metric that measures the average time between failures of a system or component. It is calculated by dividing the total time of operation by the number of failures that occur during that time. The result is an average value that can be used to estimate the expected service life of the system or component. MTBF is a useful metric for tracking the reliability of systems and components, and for identifying potential design flaws or manufacturing defects. It can also be used to make decisions about preventive maintenance schedules.

The QEC series EtherCAT slave devices with MCU all provide CoE objects to obtain MTBF-related information. Therefore, this library provides functions to get these MTBF-related information, allowing users or users to provide it to the manufacturer to assess and judge the life and failure of the device.

• getWorkingHours()
• getBootTimes()
• tryToGetWorkingHours()
• tryToGetBootTimes()

Order Information Functions

The QEC series EtherCAT slave devices with MCU all provide CoE objects to obtain customer order-related information, which is pre-burned into the devices before shipment. Therefore, this library provides functions to get these customer order information, facilitating inquiries when necessary.

• getCustomer()
• getOrderNumber()
• getInvoiceNumber()
• getDeliveryDate()

2.3.2  EthercatDevice_DmpDIQ_Generic

EthercatDevice_DmpDIQ_Generic is an EtherCAT slave class specifically developed by ICOP for Digital I/O EtherCAT slave modules. It provides APIs for digital input, digital output, and other functionalities.

2.3.3  EthercatDevice_DmpAIQ_Generic

EthercatDevice_DmpAIQ_Generic is an EtherCAT slave class specifically developed by ICOP for Analog I/O EtherCAT slave modules. It provides APIs for analog input, analog output, and other functionalities.

2.3.4  EthercatDevice_DmpHID_Generic

EthercatDevice_DmpHID_Generic is an EtherCAT slave class specifically developed by ICOP for QEC EtherCAT slave HID modules. It encompasses RS232/RS485, 4×4 Keypad, 16×2 LCM, Manual Pulse Generator (MPG), and Buzzer functionalities.

2.3.5  EthercatDevice_DmpLCD_Generic

EthercatDevice_DmpLCD_Generic is an EtherCAT slave class specifically developed by ICOP for LCD EtherCAT slave modules. It provides a variety of drawing APIs.

2.3.6  EthercatDevice_DmpStepper_Generic

EthercatDevice_DmpStepper_Generic is an EtherCAT slave class developed for the DM&P Group’s 3-axis stepper motor controller EtherCAT slave module. This module features motor drivers, encoder inputs, and other CNC-related functions. In the motor control section, it not only supports the CiA 402 mode but also the 3-axis synchronous G-code mode.

3. Examples

3.1 Slave Information

#include "Ethercat.h"

EthercatMaster master;

void setup(void) {
    uint16_t slavecount, i;
    
    Serial.begin(115200);
    while (!Serial);
    
    master.begin();
    
    slavecount = master.getSlaveCount();
    for (i = 0; i < slavecount; i++) {
        Serial.print("Slave");
        Serial.print(i);
        Serial.print(" => Vendor ID: 0x");
        Serial.print(master.getVendorID(i), HEX);
        Serial.print(", Product Code: 0x");
        Serial.println(master.getProductCode(i), HEX);
    }
}

void loop() {
  // ...
}

3.2 PDO Read/Write

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic slave;

void setup()
{
    Serial.begin(115200);

    master.begin();
    slave.attach(0, master);
    master.start();
}

void loop()
{
    /* Write value of byte offset 0 of slave's output process data. */
    slave.pdoWrite8(0, 0xFF);

    /* Read value of byte offset 0 of slave's input process data. */
    Serial.println(slave.pdoRead8(0), HEX);

    delay(100);
}

3.3 SDO Upload/Download

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic slave;

void setup()
{
    Serial.begin(115200);
    while (!Serial);

    master.begin();
    slave.attach(0, master);

    /* Write 0x08 to the object with index 0x6060. */
    slave.sdoDownload8(0x6060, 0x00, 0x08);
    /* Read value from the object with index 0x6061. */
    Serial.prinln(slave.sdoUpload8(0x6061, 0x00));

    master.start();
}

void loop() {
    // ...
}

3.4 Object Description Information

#include <Ethercat.h>

EthercatMaster master;
EthercatDevice_Generic slave;

uint16_t DataType;
uint8_t MaxSubindex, ObjectCode;
char ObjectName[64];

void setup() {
  Serial.begin(115200);
  master.begin();
  slave.attach(0, master);
  slave.getObjectDescription(0x1C12, DataType, MaxSubindex, ObjectCode, ObjectName, sizeof(ObjectName));

  Serial.print("Data Type       : ");
  Serial.print(DataType, HEX);
  Serial.println("h");

  Serial.print("Object Code     : ");
  Serial.print(ObjectCode, HEX);
  Serial.println("h");

  Serial.print("Max Subindex    : ");
  Serial.println(MaxSubindex);

  Serial.print("Object Name     : ");
  Serial.println(ObjectName);
}

void loop() {
  // ...
}

3.5 Cyclic Callback

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic slave;

void CyclicCallback() {
    // put your cyclic Callback function here.
}
void setup() {
    master.begin();
    slave.attach(0, master);
    slave.setDc(1000000); // 1000000 ns = 1 ms
    master.attachCyclicCallback(CyclicCallback);
    master.start(1000000, ECAT_SYNC);  // 1000000 ns = 1 ms
}

void loop() {
    // ...
}

3.6 QEC Slave: Digital Input/Output

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_QECR00DF0H slave;

void setup() {
  Serial.begin(115200);
  
  master.begin();
  slave.attach(0, master);
  master.start();
}

void loop() {
  Serial.println(slave.digitalReadAll());
  delay(4000);
}

3.7 QEC Slave: HID

#include "Ethercat.h" // Include the EtherCAT Library

EthercatMaster EcatMaster; // Create an EtherCAT Master Object
EthercatDevice_QECR11HU9S Slave1; // Create an EtherCAT Slave Object for QEC R11HU9S

int incomingByte = 0; // Variable for incoming serial data
char read_ch; // Variable for read serial data (char)

void setup() {
    Serial.begin(115200); // Initialize serial communication at 115200 baud rate

    // Initialize the EtherCAT Master. If successful, all slaves enter PRE OPERATIONAL state
    EcatMaster.begin();
    
    // Attach QECR11HU9S slave device to the EtherCAT Master at position 0
    Slave1.attach(0, EcatMaster);

    // Start the EtherCAT Master. If successful, all slaves enter OPERATIONAL state
    // FreenRun Mode, and the parameter 1000000 sets the cycle time in nanoseconds
    EcatMaster.start(1000000, ECAT_FREERUN); 
    
    // Configure UART settings for two COM ports of the slave device
    Slave1.uartSetBaud(COM1, 115200); // Set baud rate for COM1
    Slave1.uartSetFormat(COM1, SERIAL_8N1); // Set data format for COM1
    Slave1.uartSetBaud(COM2, 115200); // Set baud rate for COM2
    Slave1.uartSetFormat(COM2, SERIAL_8N1); // Set data format for COM2
}

void loop() {
    // send data only when you receive data:
    if (Serial.available() > 0) {
        // read the incoming byte:
        incomingByte = Serial.read();

        // Send the byte via UART COM1 of the slave device 
        Slave1.uartWrite(COM1, incomingByte);   
        
        while (Slave1.uartQueryRxQueue(COM2) <1) Slave1.update();// Because the function is non-blocking, so we need to call update(); by ourselves

        // Read the received character from slave's UART COM2
        if((read_ch = (char)Slave1.uartRead(COM2)) > 0) {
            // Print the received data to the serial monitor
            Serial.print("COM2 receive: ");
            Serial.println(read_ch);
        }
    } 
}

3.8 QEC Slave: Stepper Motor Controller

#include "Ethercat.h" // Include the EtherCAT Library

EthercatMaster EcatMaster; // Create an EtherCAT Master Object
EthercatDevice_QECR11MP3S Slave1; // Create an EtherCAT Slave Objects for QECR11MP3S

// Callback function for cyclic updates
void myCallback() {
  Slave1.update(); // Update the Ethercat slave
}

void setup() {
  Serial.begin(115200);
  // Initialize the EtherCAT Master. If successful, all slaves enter PRE OPERATIONAL state
  EcatMaster.begin();
  
  // Attach the QECR11MP3S to the EtherCAT Master at position 0
  Slave1.attach(0, EcatMaster);

  // Set a cyclic callback for the Ethercat Master
  EcatMaster.attachCyclicCallback(myCallback);

  // Start the EtherCAT Master. If successful, all slaves enter OPERATIONAL state
  // Sync Mode, and the parameter 1000000 sets the cycle time in nanoseconds
  EcatMaster.start(1000000, ECAT_SYNC);

  // Enable motor (G-code) to prepare the device for movement commands
  Slave1.machineServoOn();
}

void loop() {
  // Move to position X=100 at speed F=1000. This command moves the machine axis to position 100
  // at a feed rate of 1000. The operation will take some time to complete.
  Slave1.machineGcode("G1 X100 F1000");
  delay(6000); // Wait for the command to be processed
  
  // Move back to position X=0 at speed F=10000. This command returns the machine axis to the starting position
  // at a faster feed rate of 10000. This operation is quicker due to the higher feed rate.
  Slave1.machineGcode("G1 X0 F10000");
  delay(1000); // Wait for the command to be processed
}

Appendix

A.1 Error List

For most functions, a returned value less than zero indicates an error, and the value represents an error code. If there is an error code, you can find the error cause and corrective actions below.

A.2  Error Description and Corrective Actions

For Error Code Description and Corrective Actions.

A.3 Error Callback Code

Error Callback Code list:

A.4 Event Callback Code

Event Callback Code list:

A.5  SDO Abort Code

The CoE SDO Abort Codes defined in ETG.1000.6:

A.6 Data Type

The Basic Data Types defined in ETG.1000.6:

A.7  EtherCAT Network Information

The EtherCAT Network Information (ENI) contains the necessary settings to configure an EtherCAT network. The XML-based file contains general information about the master and the configurations of every slave device connected to the master. The EtherCAT Configuration Tool reads the ESI files or online scans the network for all slaves, then user can configures relevant EtherCAT settings, such as PDO mapping and enabling DC, and then export the ENI file.

The EtherCAT Technology Group specifies that the EtherCAT Master Software must support at least one of the following in the Network Configuration section: Online Scanning or Reading ENI. This library, however, supports both. In the case of Reading ENI, this library currently extracts only partial information from the ENI file for network configuration.

The extracted information includes the following:

EtherCATConfig : Config : Slave : Info

• Elements
  • VendorId
  • ProductCode
• Attribute
  • Identification : Value
• Purpose
  Used to check whether the EtherCAT slaves on the network match the slaves specified in the ENI file. The checking rules are as follows:
  • Check if the number of slaves in the ENI file matches the number of slaves on the network.
  • For slaves in the ENI file with the Identification: Value attribute, check if there are slaves on the network with matching Alias Address and Identification: Value attribute, as well as Vendor ID and Product Code. If such slaves exist, it indicates a successful match.
  • For slaves with the Identification: Value attribute that fail to match, or those without this attribute, check if the Vendor ID and Product Code of the slave with the same sequence number on the network match.

EtherCATConfig : Config : Slave : Mailbox

• Elements
  • Send : MailboxSendInfoType : Start
  • Recv : MailboxRecvInfoType : Start
• Purpose
  Used to configure the mailbox Physical Start Address of an EtherCAT slave.

EtherCATConfig : Config : Slave : Mailbox : CoE

• Elements
  • InitCmds : InitCmd : Index
  • InitCmds : InitCmd : SubIndex
  • InitCmds : InitCmd : Data
  • InitCmds : InitCmd : Timeout
• Attribute
  • InitCmds : InitCmd : CompleteAccess
• Purpose
  After switching the EtherCAT state machine to the Pre-Operational state, execute the CoE initialization commands for the EtherCAT slave in EthercatMaster::begin().

EtherCATConfig : Config : Slave : ProcessData

• Elements
  • Recv : BitLength
  • Send : BitLength
• Purpose
  The bit length of the output process data and input process data of an EtherCAT slave is provided to the firmware for relevant configuration.

EtherCATConfig : Config : Slave : ProcessData : Sm

• Elements
  • SyncManagerSettings : StartAddress
  • SyncManagerSettings : ControlByte
  • SyncManagerSettings : Enable
• Purpose
  Used to configure the Sync Manager registers for the process data of an EtherCAT slave.

EtherCATConfig : Config : Slave : DC

• Elements
  • CycleTime0
  • CycleTime1
  • ShiftTime
• Purpose
  Used to configure the DC parameters of an EtherCAT slave.