I want to find...

検索

Shares

Table of Content

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/.

86duinoIDE_500_Logo

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.

Vortex86EX2_Dualcore_diagram

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.

Vortex86EX2_Dualsystem

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.
Feature NameShort DescriptionQEC Master
Basic Features
Service CommandsSupport of all commandsO
Slaves with Device EmulationSupport Slaves with and without application controllerO
EtherCAT State MachineSupport of ESM special behaviorO
Error HandlingChecking of network or slave errors, e.g. Working CounterO
EtherCAT Frame TypesSupport EtherCAT FramesO
Process Data Exchange
Cyclic PDOCyclic process data exchangeO
Network Configuration
Online scanningNetwork configuration functionality included in EtherCAT MasterO
Reading ENINetwork Configuration taken from ENI fileO
Compare Network configurationCompare configured and existing network configuration during boot-upO
Explicit Device IdentificationIdentification used for Hot Connect and prevention against cable swappingO
Access to EEPROMSupport routines to access EEPROM via ESC registerO
Mailbox Support
Support MailboxMain functionality for mailbox transferO
Mailbox Resilient LayerSupport underlying resilient layerO
CAN application layer over EtherCAT (CoE)
SDO Up/DownloadNormal and expedited transferO
Segmented TransferSegmented transferO
Complete AccessTransfer the entire object (with all sub-indices) at onceO
SDO Info serviceServices to read object dictionaryO
FoE
FoE ProtocolSupport FoE ProtocolO
Firmware Up/DownloadPassword, FileName should be given by the applicationO
Synchronization with Distributed Clock (DC)
DC supportSupport of Distributed ClockO

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.

Ethercat_synchronization

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 ValidInput Latch. This scenario is not suitable for applications with high synchronization requirements.

Ethercat_free_run_diagram

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 ValidInput 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.

Ethercat_sm-synchronous_diagram

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 ValidInput 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.

Ethercat_dc-synchronous_diagram

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.

Ethercat_classes

These classes can be divided into three parts as follows:

  • EtherCAT マスタ
    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:

EthercatMaster_class_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
    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
    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.


2.1.2 Callback Functions

qec_callback_function_diagram

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:
DefinitionCode説明
ECAT_ERR_WKC_SINGLE_FAULT2000001Working counter fault occurred.
ECAT_ERR_WKC_MULTIPLE_FAULTS2000002Multiple working counter faults occurred.
ECAT_ERR_SINGLE_LOST_FRAME2000003Frame was lost.
ECAT_ERR_MULTIPLE_LOST_FRAMES2000004Frames were lost multiple times.
ECAT_ERR_CABLE_BROKEN2000007The cable is broken.
ECAT_ERR_WAIT_ACK_TIMEOUT2001000Firmware timeout waiting for cyclic interrupt ACK.
  • 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:
DefinitionCode説明
ECAT_EVT_STATE_CHANGED1000001The EtherCAT state of the master has changed.
ECAT_EVT_CABLE_RECONNECTED1000002The cable has been reconnected.

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.


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.


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.

Ethercat_device_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.


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:

_EthercatDevice_CommonDriver_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.

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.

Ethercat_dc_diagram

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:

Ethercat_dc_diagram-1

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

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.

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_diagram

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:

SDO Information commands:

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.

FoE_diagram
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.


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:

EthercatDevice_Generic_diagram
  • Relationship: EthercatDevice_Generic inherits from _EthercatDevice_CommonDriver.
  • Base Class: _EthercatDevice_CommonDriver
Initialization Functions

Initialization-related functions for the EthercatDevice_Generic class.


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_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.

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.

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.


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.

DefinitionCode
ECAT_SUCCESS0
ECAT_ERR_MODULE_INIT_FAIL-100
ECAT_ERR_MODULE_GET_VERSION_FAIL-101
ECAT_ERR_MODULE_VERSION_MISMATCH-102
ECAT_ERR_MODULE_GENERIC_TRANSFER_INIT_FAIL-103
ECAT_ERR_MASTER_DOWNLOAD_SETTINGS_FAIL-200
ECAT_ERR_MASTER_SET_DEVICE_SETTINGS_FAIL-201
ECAT_ERR_MASTER_GET_GROUP_INFO_FAIL-202
ECAT_ERR_MASTER_GET_MASTER_INFO_FAIL-203
ECAT_ERR_MASTER_GET_DEVICE_INFO_FAIL-204
ECAT_ERR_MASTER_SET_GROUP_SETTINGS_FAIL-205
ECAT_ERR_MASTER_MAPPING_INIT_FAIL-206
ECAT_ERR_MASTER_INTERRUPT_INIT_FAIL-207
ECAT_ERR_MASTER_ACTIVE_FAIL-208
ECAT_ERR_MASTER_ENI_INITCMDS_FAIL-209
ECAT_ERR_MASTER_NO_DEVICE-210
ECAT_ERR_MASTER_ACYCLIC_INIT_FAIL-300
ECAT_ERR_MASTER_ACYCLIC_REQUEST_FAIL-301
ECAT_ERR_MASTER_ACYCLIC_BUSY-302
ECAT_ERR_MASTER_ACYCLIC_TIMEOUT-303
ECAT_ERR_MASTER_ACYCLIC_ERROR-304
ECAT_ERR_MASTER_ACYCLIC_WRONG_STATUS-405
ECAT_ERR_MASTER_GENERIC_SEND_FAIL-400
ECAT_ERR_MASTER_GENERIC_RECV_FAIL-401
ECAT_ERR_MASTER_NOT_BEGIN-1000
ECAT_ERR_MASTER_WRONG_BUFFER_SIZE-1001
ECAT_ERR_MASTER_REDUNDANCY_NO_DC-1002
ECAT_ERR_MASTER_MEMORY_ALLOCATION_FAIL-1003
ECAT_ERR_MASTER_OSLAYER_INIT_FAIL-1004
ECAT_ERR_MASTER_NIC_INIT_FAIL-1005
ECAT_ERR_MASTER_BASE_INIT_FAIL-1006
ECAT_ERR_MASTER_CIA402_INIT_FAIL-1007
ECAT_ERR_MASTER_SETUP_PDO_FAIL-1008
ECAT_ERR_MASTER_SCAN_NETWORK_FAIL-1009
ECAT_ERR_MASTER_START_MASTER_FAIL-1010
ECAT_ERR_MASTER_CYCLETIME_TOO_SMALL-1011
ECAT_ERR_MASTER_DUMP_OUTPUT_PDO_FAIL-1012
ECAT_ERR_MASTER_CONFIG_DEVICE_FAIL-1013
ECAT_ERR_MASTER_CONFIG_MAPPING_FAIL-1014
ECAT_ERR_MASTER_WAIT_BUS_SYNC_TIMEOUT-1015
ECAT_ERR_MASTER_WAIT_MASTER_SYNC_TIMEOUT-1016
ECAT_ERR_MASTER_CYCLIC_START_FAIL-1017
ECAT_ERR_MASTER_WRONG_BUFFER_POINTER-1018
ECAT_ERR_MASTER_ENI_INIT_FAIL-1050
ECAT_ERR_MASTER_ENI_MISMATCH-1051
ECAT_ERR_MASTER_STOPPED-1100
ECAT_ERR_MASTER_STARTED-1101
ECAT_ERR_MASTER_NOT_IN_PREOP-1102
ECAT_ERR_MASTER_NOT_IN_SAFEOP-1103
ECAT_ERR_MASTER_NOT_IN_OP-1104
ECAT_ERR_MASTER_II_TRANSITION_FAIL-1200
ECAT_ERR_MASTER_IP_TRANSITION_FAIL-1201
ECAT_ERR_MASTER_PS_TRANSITION_FAIL-1202
ECAT_ERR_MASTER_SO_TRANSITION_FAIL-1203
ECAT_ERR_DEVICE_NOT_EXIST-2000
ECAT_ERR_DEVICE_NOT_ATTACH-2001
ECAT_ERR_DEVICE_NO_MAILBOX-2002
ECAT_ERR_DEVICE_NO_DC-2003
ECAT_ERR_DEVICE_WRONG_INPUT-2004
ECAT_ERR_DEVICE_MEMORY_ALLOCATION_FAIL-2005
ECAT_ERR_DEVICE_VENDOR_ID_MISMATCH-2006
ECAT_ERR_DEVICE_PRODUCT_CODE_MISMATCH-2007
ECAT_ERR_DEVICE_NO_SUCH_FUNCTION-2008
ECAT_ERR_DEVICE_FUNCTION_NOT_INIT-2009
ECAT_ERR_DEVICE_BUSY-2010
ECAT_ERR_DEVICE_TIMEOUT-2011
ECAT_ERR_DEVICE_NO_DATA-2012
ECAT_ERR_DEVICE_SII_READ_FAIL-2100
ECAT_ERR_DEVICE_SII_WRITE_FAIL-2101
ECAT_ERR_DEVICE_PDO_NOT_EXIST-2200
ECAT_ERR_DEVICE_PDO_OUT_OF_RANGE-2201
ECAT_ERR_DEVICE_FOE_NOT_SUPPORT-2300
ECAT_ERR_DEVICE_FOE_REQUEST_FAIL-2310
ECAT_ERR_DEVICE_FOE_TIMEOUT-2311
ECAT_ERR_DEVICE_FOE_ERROR-2312
ECAT_ERR_DEVICE_FOE_BUFFER_TOO_SMALL-2313
ECAT_ERR_DEVICE_FOE_READ_FAIL-2314
ECAT_ERR_DEVICE_FOE_WRITE_FAIL-2315
ECAT_ERR_DEVICE_COE_SDO_NOT_SUPPORT-2400
ECAT_ERR_DEVICE_COE_SDO_INFO_NOT_SUPPORT-2401
ECAT_ERR_DEVICE_COE_BUSY-2410
ECAT_ERR_DEVICE_COE_REQUEST_FAIL-2411
ECAT_ERR_DEVICE_COE_TIMEOUT-2412
ECAT_ERR_DEVICE_COE_ERROR-2413
ECAT_ERR_DEVICE_CIA402_NOT_EXIST-2500
ECAT_ERR_DEVICE_CIA402_ADD_FAIL-2501
ECAT_ERR_DEVICE_CIA402_TYPE_MISMATCH-2502
ECAT_ERR_DEVICE_CIA402_NO_MODE_SUPPORT-2503
ECAT_ERR_DEVICE_CIA402_WRONG_MODE-2504
ECAT_ERR_DEVICE_CIA402_MODE_NOT_SUPPORT-2505
ECAT_ERR_DEVICE_CIA402_CHANGE_WRONG_STATE-2506
ECAT_ERR_DEVICE_CIA402_WRITE_OBJECT_FAIL-2507
ECAT_ERR_DEVICE_CIA402_NO_SUCH_TOUCH_PROBE-2580
ECAT_ERR_DEVICE_CIA402_NO_SUCH_TOUCH_PROBE_SOURCE-2581
ECAT_ERR_DEVICE_EOE_NOT_SUPPORT-2600
ECAT_ERR_DEVICE_EOE_NO_SUCH_PORT-2601
ECAT_ERR_DEVICE_EOE_TOO_MUCH_CONTENT-2602
ECAT_ERR_DEVICE_EOE_BUSY-2610
ECAT_ERR_DEVICE_EOE_REQUEST_FAIL-2611
ECAT_ERR_DEVICE_EOE_TIMEOUT-2612
ECAT_ERR_GROUP_WRONG_INPUT-3000
ECAT_ERR_GROUP_NOT_ATTACH-3001


A.2  Error Description and Corrective Actions

For Error Code Description and Corrective Actions.


A.3 Error Callback Code

Error Callback Code list:

ECAT_ERR_WKC_SINGLE_FAULTWorking Counter Fault.2000001
ECAT_ERR_WKC_MULTIPLE_FAULTSWorking Counter Multiple Faults.2000002
ECAT_ERR_SINGLE_LOST_FRAMESingle Lost Frame.2000003
ECAT_ERR_MULTIPLE_LOST_FRAMESMultiple Lost Frames.2000004
ECAT_ERR_LOST_SLAVE      Lost Slave.2000005
ECAT_ERR_STATE_MISMATCHState Mismatch.2000006
ECAT_ERR_CABLE_BROKENCable Broken.2000007
ECAT_ERR_WAIT_ACK_TIMEOUT   Wait ACK Timeout.2001000

A.4 Event Callback Code

Event Callback Code list:

ECAT_EVT_STATE_CHANGEDState Changed.1000001
ECAT_EVT_CABLE_RECONNECTEDCable Reconnected.1000002

A.5  SDO Abort Code

The CoE SDO Abort Codes defined in ETG.1000.6:

ValueMeaning
0x05030000Toggle bit not changed.
0x05040000SDO protocol timeout.
0x05040001Client/Server command specifier not valid or unknown.
0x05040005Out of memory.
0x06010000Unsupported access to an object.
0x06010001Attempt to read to a write only object.
0x06010002Attempt to write to a read only object.
0x06010003Subindex cannot be written, SI0 must be 0 for write access.
0x06010004SDO Complete access not supported for objects of variable length such as ENUM object types.
0x06010005Object length exceeds mailbox size.
0x06010006Object mapped to RxPDO, SDO Download blocked.
0x06020000The object does not exist in the object directory.
0x06040041The object can not be mapped into the PDO.
0x06040042The number and length of the objects to be mapped would exceed the PDO length.
0x06040043General parameter incompatibility reason.
0x06040047General internal incompatibility in the device.
0x06060000Access failed due to a hardware error.
0x06070010Data type does not match, length of service parameter does not match.
0x06070012Data type does not match, length of service parameter too high.
0x06070013Data type does not match, length of service parameter too low.
0x06090011Subindex does not exist.
0x06090030Value range of parameter exceeded (only for write access).
0x06090031Value of parameter written too high.
0x06090032Value of parameter written too low.
0x06090036Maximum value is less than minimum value.
0x08000000General error.
0x08000020Data cannot be transferred or stored to the application.
NOTE: This is the general Abort Code in case no further detail on the reason can determined. It is recommended to use one of the more detailed Abort Codes. (0x08000021, 0x08000022)
0x08000021Data cannot be transferred or stored to the application because of local control.
NOTE: “local control” means an application specific reason. It does not mean the ESM-specific control.
0x08000022Data cannot be transferred or stored to the application because of the present device state.
NOTE: “device state” means the ESM state.
0x08000023Object dictionary dynamic generation fails or no object dictionary is present.

A.6 Data Type

The Basic Data Types defined in ETG.1000.6:

Index (hex)Object TypeName
0001DEFTYPEBOOLEAN
0002DEFTYPEINTEGER8
0003DEFTYPEINTEGER16
0004DEFTYPEINTEGER32
0005DEFTYPEUNSIGNED8
0006DEFTYPEUNSIGNED16
0007DEFTYPEUNSIGNED32
0008DEFTYPEREAL32
0009DEFTYPEVISIBLE_STRING
000ADEFTYPEOCTET_STRING
000BDEFTYPEUNICODE_STRING
000CDEFTYPETIME_OF_DAY
000DDEFTYPETIME_DIFFERENCE
000FDEFTYPEDOMAIN
0010DEFTYPEINTEGER24
0011DEFTYPEREAL64
0012DEFTYPEINTEGER40
0013DEFTYPEINTEGER48
0014DEFTYPEINTEGER56
0015DEFTYPEINTEGER64
0016DEFTYPEUNSIGNED24
0018DEFTYPEUNSIGNED40
0019DEFTYPEUNSIGNED48
001ADEFTYPEUNSIGNED56
001BDEFTYPEUNSIGNED64
001DDEFTYPEGUID
001EDEFTYPEBYTE
002DDEFTYPEBITARR8
002EDEFTYPEBITARR16
002FDEFTYPEBITARR32

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.

Ethercat_network_information

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.

コメントする

上部へスクロール