EtherCAT API 使用手冊

2024.08.15，版本2.2r1。

您可以下載EtherCAT函式庫API使用者手冊文件： 這裡.

1. 簡介

1.1 About QEC MDevice

QEC MDevice is an EtherCAT MDevice System compatible with 86Duino Coding IDE 500+. It offers real-time EtherCAT communication between EtherCAT MDevice and EtherCAT SubDevices. Except for the EtherCAT Library of 86Duino IDE, QEC MDevice 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 什麼是86Duino IDE？

The 86Duino integrated development environment (IDE) software makes it easy to write and upload code to 86Duino boards and QEC MDevice. 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/zh/software/.

QEC MDevice’s software, 86Duino IDE, also offers a configuration utility: 86EVA，一款圖型化組態工具，供使用者設定 EtherCAT 網路參數；其功能如下：

• EtherCAT SubDevices scanning
• 導入 ENI 文件
• Setting EtherCAT MDevice
• Configure EtherCAT SubDevices

其他詳細功能請參考 86EVA 使用手冊.

1.1.2 QEC EtherCAT MDevice Architecture

The EtherCAT MDevice 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 MDevice Library
  • 提供 C/C++ 語法應用功能
    • 初始化功能
    • 組態配置功能
    • Process Data (PDO) 存取功能
    • CAN application protocol over EtherCAT (CoE) 存取功能
    • File access over EtherCAT (FoE) 存取功能
    • SubDevice Information Interface (SII) access interface.
    • Distributed Clocks (DC) 存取功能
• EtherCAT MDevice Firmware
  • Executes the EtherCAT MDevice Core.
  • 控制主/從的乙太網路驅動程序，發送 EtherCAT 封包

這些程式設計為在 FreeDOS 作業系統上執行，並使用 DJGPP 環境提供的 GCC 編譯器進行編譯。

1.1.3 硬體平台

The EtherCAT MDevice 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:

• 主站系統
  • 使用者的 EtherCAT application
  • 使用者的 HMI application
  • 使用者的 Ethernet application
  • ...等等
• 從核心系統
  • Only responsible for running the EtherCAT MDevice Firmware.

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

1.1.4 雙系統同步

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 MDevice Library blocks run on the Master System, while the Real-Time EtherCAT MDevice Core runs on the Slave System.

When the EtherCAT MDevice Core reaches the Process Inputs 階段時，它會從乙太網路驅動程式接收所有循環封包，並將 Input PDO 資料複製到 DPRAM 中。

當運行到 User Application stage, the EtherCAT MDevice 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 MDevice 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 MDevice Core’s User Application 和中斷處理程序同時完成。

When the EtherCAT MDevice Core reaches the Write Outputs 階段，它將 Output PDO 資料從 DPRAM 複製到乙太網路驅動程式的 DMA 並發送封包。

這些任務依照概述的程序步驟以循環方式定期執行，確保雙系統 PDO 資料的同步。

1.2 特點

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

• Class A: Standard EtherCAT MDevice
• Class B: Minimum EtherCAT MDevice

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

1.2.1 特性表

詞語用法：

• shall： 要求支持。
• should： 建議支持。
• may： 允許支持。
• O： QEC 支持。

1.3 功能包

1.3.1 電纜冗餘

EtherCAT 電纜冗餘是指 EtherCAT 通訊系統即使在電纜故障的情況下也能保持連續可靠的通訊的能力。電纜冗餘採用環形拓撲，可在兩個方向上運行。如果一條電纜發生故障或斷開連接，另一條電纜路徑仍可運作以確保通訊不間斷。電纜冗餘增強了 EtherCAT 網路的容錯能力，最大限度地減少停機時間並提高整體系統可靠性。

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 MDevice Controller between these scenarios.

• 無電纜破損
• Cable Broken between two SubDevices
• Cable broken between MDevice and SubDevice

為了便於解釋，這裡做一些假設：

• 假設週期時間設定為 125 µs。
• Assume all SubDevices only with input PDO (without output PDO), the working counter (WKC) in process data frame will increase 1 when passing through every SubDevices.
• Assume only have 6 SubDevices on EtherCAT network, and the expected working counter (EWKC) is 6.
• 主端口和輔端口在每個週期同時發送過程資料幀。

有關電纜冗餘的更多詳細信息，請訪問 EtherCAT功能包：電纜冗餘.

1.4 基準測量

EtherCAT 是一種以其高同步能力而聞名的現場匯流排技術。在需要高同步性的應用中，往往需要即時效能和高控制頻率。這些場景中的用戶通常會考慮以下規格：

• 支援更短的周期時間
• 支援更多流程數據
• Support for more EtherCAT SubDevices

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

請看 EtherCAT MDevice Benchmark 了解更多詳情。

1.5 同步

The time synchronization among all slaves in an EtherCAT network relies on the Distributed Clocks (DC) unit within the EtherCAT SubDevice 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.

ESC 有三個同步輸出引腳： IRQ, SYNC0和 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 SubDevice does not have a µC, it does not support synchronization functionality.

EtherCAT 共有三種同步模式：

• Free Run
• SM-Synchronous
• DC-Synchronous

1.5.1 Free Run

The EtherCAT MDevice and all EtherCAT SubDevices 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 MDevice and SubDevice 1, SubDevice 2, SubDevice 3 to SubDevice n have their own Cycle Time, resulting in inconsistent Output Valid 以及 Input Latch。此場景不適合同步要求較高的應用。

1.5.2 SM-Synchronous

當 ESC 接收到循環幀時，IRQ 引腳會產生 SM 事件，該事件將觸發 µC 中本地應用程式的執行。如下圖所示，從站接收循環封包時，其抖動與主站發送時的抖動相同。即使假設零抖動，由於硬體有限制的 傳播延遲 the last SubDevices will receive the cyclic frames later with respect to the first ones.

由於傳播延遲，從裝置之間的 SM 事件時間存在偏移，導致 SM 同步精度達到微秒 水準。

如果每個從站裝置支援SyncManager 參數物件 (0x1C32.3/0x1C33.3) 中的Shift Time ，可以嘗試將所有從站的輸出有效和輸入鎖存調整為彼此接近。然而，由於無法計算傳播延遲，調整非常具有挑戰性。

1.5.3 DC-Synchronous

SYNC0 或 SYNC1 接腳根據 ESC 的 DC 相關暫存器中的組態循環產生 SYNC 事件，該事件將觸發 µC 中本機應用程式的執行。如下圖所示，抖動和傳播延遲仍然存在，接收到循環幀後仍然會觸發SM事件。然而，在這種 DC 同步方法中，SYNC0 事件是循環觸發的，不會受到抖動或傳播延遲的影響。

由於 SYNC0 事件是由 DC 單元觸發的，所有從機之間的 SYNC0 事件幾乎沒有偏移，透過週期性發送 APRW/FPRW 命令來同步所有從機的系統時間，精度可以達到奈秒等級。

如果從裝置支援SyncManager 參數物件(0x1C32.3/0x1C33.3) 中的Shift Time，則可以嘗試將這些從站的Output Valid和Input Latch調整為同一時間點。。

然而，圖中Global Shift Time的選擇至關重要，必須滿足以下條件：

• After the cyclic frames have been received by all SubDevices.
• 在發送下一個週期的循環封包之前。
• 根據不同 DC-Synchronous 方法，執行後可能需要選擇 Prepare Outputs:
  • 觸發 μC 執行 Prepare Outputs 當SM事件發生時。
  • 觸發 μC 執行 Output Valid 當 SYNC 事件發生時。

正確的Global Shift Time不是唯一的；可以在整個週期時間間隔內選擇。要了解有關各種DC-Synchronous方法的更多信息，請參閱 ETG.1020 EtherCAT Protocol Enhancements。

2. 函式

QEC EtherCAT MDevice Library.

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

這些類別可分為以下三個部分：

• EtherCAT 主站
  The EtherCAT MDevice part not only provides various and flexible MDevice configuration and operation functions but also offers diverse EtherCAT SubDevice operation functions for invocation by the EtherCAT Device part.

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

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

2.1 EtherCAT MDevice

關於 EtherCAT MDevice part not only provides various and flexible MDevice configuration and operation functions but also offers diverse EtherCAT SubDevice operation functions for invocation by the EtherCAT Device part.

EthercatMaster 是唯一的類別在 EtherCAT MDevice 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 MDevice initialization, MDevice control, and access to SubDevice information.

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

• EthercatMaster 與 _EthercatDevice_CommonDriver 之間有關聯，而 _EthercatDevice_CommonDriver 取決於 EthercatMaster。
• EthercatMaster 與 EthercatDevice_CiA402 之間存在關聯，EthercatMaster 取決於 EthercatDevice_CiA402。

EtherCAT MDevice Settings

本函式庫中，提供多種組態參數供使用者選擇，目的在於滿足使用者多樣化的應用需求。以下是本函式庫提供的組態參數。

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

預設： ECAT_MASTER_SHIFT
In DC-Synchronous mode, the first SubDevice with DC serves as the system reference clock to synchronize other SubDevices with DC. However, this only involves synchronizing the system time of all SubDevices on the network and does not include the EtherCAT MDevice. In applications with DC-Synchronous mode enabled, the MDevice usually needs to precisely and periodically control the SubDevices, so the MDevice must also synchronize its system time with all SubDevices on the network.
此同步有兩種方法：

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

StaticDriftCompensationFrames

預設：30000
The EtherCAT MDevice sends many separate ARMW or FRMW drift compensation frames to distribute the System Time of the reference clock to all DC SubDevices.

StateMachineTimeoutI2P

預設：3000；單位：毫秒
從 Init 狀態轉換到 Pre-Operational 狀態的逾時時間。

StateMachineTimeoutP2S

預設：10000；單位：毫秒
從 Pre-Operational 狀態轉換到 Safe-Operational 狀態的逾時時間。

StateMachineTimeoutS2O

預設：10000；單位：毫秒
從 Safe-Operational 狀態轉換到 Operational 狀態的逾時時間。

ScanNetworkTimeout

預設：5000；單位：毫秒
掃描網路逾時。掃描網路操作在 EthercatMaster::begin()內執行。

StartMasterTimeout

預設：3000；單位：毫秒
啟動主站的基本逾時時間， T_base.
在 EthercatMaster::start(), the firmware is requested to start EtherCAT, and the timeout for this request is referred to as startup timeout, T_startup.
EtherCAT 的啟動逾時時間的計算如下： T_startup = T_base + (T_SubDevice × N_SubDevices) .
Here, N_SubDevices is the number of SubDevices on the network.

StartDeviceTimeout

預設：500；單位：毫秒
Timeout per SubDevice for start MDevice, T_SubDevice.

ErrorDetectWkcMultipleFaultsThreshold

預設：3
The MDevice 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 錯誤中斷。

ErrorDetectMultipleLostFramesThreshold

預設：3
The MDevice 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 錯誤中斷。

EnableErrorBusReactionSyncUnitToSafeOp

預設：0
If this parameter is set to 1, the MDevice will change the EtherCAT state of the SubDevices with an application controller and will disable the Sync Manager channels of the SubDevices which only support the EtherCAT state machine emulation.

EnableErrorBusReactionSyncUnitToSafeOpAutoRestart

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

IgnoreBiosOverride

預設：0
QEC-MDevice 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 初始化函式

Before starting the EtherCAT MDevice, 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 函式

此函式庫提供了三種類型的 callbacks，如下所示：

• 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 MDevice Core triggers cyclic interrupts to the EtherCAT MDevice 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 MDevice Core detects an error, it will trigger an error interrupt and pass a 32-bit error code to the EtherCAT MDevice Library. If the user has registered an error callback, the system will invoke that callback to inform the user of the specific error.
  Error Callback 支援的錯誤代碼如下：

• Event Callback
  When the Real-Time EtherCAT MDevice Core detects an event, it triggers an event interrupt and passes a 32-bit event code to the EtherCAT MDevice Library. If the user has registered an event callback, the system will invoke that callback to inform the user of the specific event.
  Event Callback 支援的事件代碼如下：

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

2.1.3 從站資訊函式

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

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

2.1.4 控制函式

The control functions provided by the EtherCAT MDevice 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 MDevice and SubDevices.

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

2.2 EthercatDevice

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

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

• EthercatMaster 和 _EthercatDevice_CommonDriver 之間存在關聯，其中 _EthercatDevice_CommonDriver 取決於 EthercatMaster。
• All other EtherCAT SubDevice classes inherit from _EthercatDevice_CommonDriver.

警告：禁止使用此類聲明對象。

2.2.1 _EthercatDevice_CommonDriver

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

_EthercatDevice_CommonDriver 的類別關係如下圖所示：

• EthercatMaster 和 _EthercatDevice_CommonDriver 之間存在關聯，其中 _EthercatDevice_CommonDriver 取決於 EthercatMaster。
• All other EtherCATSubDevice classes inherit from _EthercatDevice_CommonDriver.

警告：禁止使用此類聲明對象。

資訊功能

The library provides functions for obtaining information about EtherCAT SubDevices 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 SubDevice 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()

分佈式時鐘 (DC) 功能

關於 分佈式時鐘 (DC) is an essential functional unit within the EtherCAT SubDevice Controller (ESC). It is responsible for implementing a time synchronization mechanism across the EtherCAT network, ensuring that all SubDevices 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 MDevice within one segment holds the reference time (System Time). This System Time is used as the reference clock to synchronize the DC SubDevice clocks of other devices and of the MDevice. The propagation delays, local clock sources drift, and local clock offsets are taken into account for the clock synchronization.

ESCs 可為本地應用程式產生同步信號，以便與 EtherCAT 系統時間同步。同步信號可直接使用（例如，作為中斷）或用於數位輸出更新/數位輸入取樣。此外，LatchSignals 可根據 EtherCAT 系統時間蓋上時間戳。

支持 DC 功能的裝置支援產生基本同步信號 SYNC0 和從站的同步信號 SYNC1。第二個同步信號 (SYNC1) 取決於 SYNC0，它可以在 SYNC0 脈衝之後以預先定義的延遲時間通電。

如果 SYNC1 循環時間大於 SYNC0 循環時間，則會如下產生：達到起始時間循環操作時，會產生 SYNC0 脈波。在 SYNC0 脈衝之後產生 SYNC1 脈衝，延遲 SYNC1 循環時間。下一個 SYNC1 脈衝在下一個 SYNC0 脈衝產生時加上 SYNC1 循環時間產生。
一些配置範例如下圖所示：

如需了解更多詳細信息，請參閱ESC Hardware Data Sheet Section I。

• setDc()

Process Data Objects (PDO) 函式

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

The Fieldbus Memory Management Units (FMMU) in the EtherCAT SubDevice Controller (ESC) can mapping dual-port memory to logical address. All SubDevice nodes check the EtherCAT frames sent by the EtherCAT MDevice, 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.

總體而言，process data 是 EtherCAT 技術的重要組成部分，適用於機器人控制、CNC 控制、自動化控制等領域的即時應用。

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

CANopen over EtherCAT (CoE) 函式

CANopen 是一種基於控制器區域網路 (CAN) 匯流排的高階通訊協議，通常用於工業應用中控制系統和設備之間的通訊。它定義了一組通訊物件、資料類型和網路管理功能，以方便設備之間的資料交換、配置和控制。

CANopen 通訊協定包括以下幾個方面：

• 物件字典
  定義裝置之間交換的所有資料物件和參數。物件字典包含各種類型的物件，例如變數、參數、事件和函式。
• PDO (Process Data Object)
  用於即時資料傳輸。PDOs 允許裝置之間以固定或事件觸發的方式傳輸資料，實現即時控制和資料交換。
• SDO (Service Data Object)
  用於設定和管理裝置參數。SDOs 提供讀取、寫入和參數配置的功能，讓裝置可以動態交換配置資訊。

CoE (CAN application over EtherCAT)是基於 EtherCAT 網路的 CANopen 協定。它支援透過 EtherCAT 網路使用 CANopen 協定進行通訊。物件字典包含參數、應用程式資料以及流程資料介面和應用程式資料之間的對應資訊（PDO 映射）。可以透過服務資料物件 (SDO) 存取其條目。
SDO 命令用於存取儲存在物件字典中的對象，而 SDO 資訊命令用於檢索有關這些對象的詳細資訊。

SDO 指令：

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

SDO 資訊指令：

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

File over EtherCAT (FoE) 函式

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 EtherCATSubDevice or to upload a firmware or any other files from the EtherCAT SubDevice.

• readFoE()
• writeFoE()

SII EEPROM 函式

以下 API 仍在開發中，不建議使用。

EtherCAT SubDevice controllers use a mandatory NVRAM, typically a serial EEPROM with I²C interface, to store EtherCAT SubDevice 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.

ESC 配置區（EEPROM 字位址 0 至 7）在上電或重設後由 ESC 自動讀取。它包含 PDI 配置、DC 設定和配置的站別名。 ESC 配置資料的一致性透過校驗和來保證。有關更多詳細信息，請參閱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 SubDevice class that can be used to control all EtherCAT SubDevices, including accessing SubDevice information, PDO, CoE, FoE, DC, and more.
EthercatDevice_Generic 的類別關係如下圖所示：

• 關係： EthercatDevice_Generic 繼承自 _EthercatDevice_CommonDriver。
• 基底類別：_EthercatDevice_CommonDriver

初始化函式 ( Initialization Functions )

EthercatDevice_Generic class 的初始化相關函式。

• attach()
• detach()

2.3 QEC 系列裝置

關於 QEC 系列裝置部份 provides dedicated functions for ICOP’s QEC series SubDevices, enabling users to code in a more user-friendly and concise manner.

QEC 系列裝置部分和 EtherCAT Device 部分之間的主要類別關係是關聯關係，QEC 系列裝置部分依賴於 EtherCAT Device 部分。如下圖所示，_EthercatDevice_DmpCommonDriver 與 _EthercatDevice_CommonDriver 之間有關聯關係。

類別：

• _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 SubDevice specific features developed by ICOP. These functions include system monitoring (temperature, voltage, current), order information, MTBF, etc.

_EthercatDevice_DmpCommonDriver 的類別關係如下圖所示：

• _EthercatDevice_DmpCommonDriver 繼承自 _EthercatDevice_CommonDriver。

警告：禁止使用此類聲明對象。

系統監控函式

The QEC series EtherCAT SubDevices 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函式

MTBF 代表平均故障間隔時間 (Mean Time Between Failures)。它是衡量系統或元件平均故障間隔時間的可靠性指標。其計算方式是將總運作時間除以該時間內發生的故障次數。結果是一個平均值，可用於估計系統或元件的預期使用壽命。MTBF 是追蹤系統和元件的可靠性，以及識別潛在設計缺陷或製造缺陷的有用指標。它也可用於預防性維護計劃的決策。

The QEC series EtherCAT SubDevices 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()

訂購資訊函式

The QEC series EtherCAT SubDevices 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 SubDevice class specifically developed by ICOP for Digital I/O EtherCAT SubDevice modules. It provides APIs for digital input, digital output, and other functionalities.

2.3.3  EthercatDevice_DmpAIQ_Generic

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

2.3.4  EthercatDevice_DmpHID_Generic

EthercatDevice_DmpHID_Generic is an EtherCAT SubDevice class specifically developed by ICOP for QEC EtherCAT SubDevice 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 SubDevice class specifically developed by ICOP for LCD EtherCAT SubDevice modules. It provides a variety of drawing APIs.

2.3.6  EthercatDevice_DmpStepper_Generic

EthercatDevice_DmpStepper_Generic is an EtherCAT SubDevice class developed for the DM&P Group’s 3-axis stepper motor controller EtherCAT SubDevice 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. 範例

3.1 SubDevice 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 讀取/寫入

#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 上傳/下載

#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 物件資訊描述

#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 SubDevice: 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 SubDevice: 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 SubDevice: 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
}

附錄

A.1 錯誤代碼

對於大多數函式，回傳值小於零表示有錯誤，該值代表錯誤代碼。如果有錯誤代碼，您可以在下面找到錯誤原因和糾正措施。

A.2 錯誤描述與修正措施

關於錯誤代碼說明和糾正措施。

A.3 錯誤回傳代碼

Error Callback Code 清單：

A.4 事件回傳代碼

Event Callback Code 清單：

A.5 SDO 中止代碼

ETG.1000.6 中定義的 CoE SDO Abort Codes：

A.6 資料類型

ETG.1000.6 中定義的基本資料類型：

A.7 EtherCAT 網路資訊

The EtherCAT Network Information (ENI) contains the necessary settings to configure an EtherCAT network. The XML-based file contains general information about the MDevice and the configurations of every SubDevice connected to the MDevice. The EtherCAT Configuration Tool reads the ESI files or online scans the network for all SubDevices, 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 MDevice 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.

提取的資訊包括以下內容：

EtherCATConfig : Config : SubDevice : Info

• 元件
  • VendorId
  • ProductCode
• 屬性
  • Identification : Value
• 目的
  Used to check whether the EtherCAT SubDevices on the network match the SubDevices specified in the ENI file. The checking rules are as follows:
  • Check if the number of SubDevices in the ENI file matches the number of SubDevices on the network.
  • For SubDevices 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 SubDevices exist, it indicates a successful match.
  • For SubDevices with the Identification: Value attribute that fail to match, or those without this attribute, check if the Vendor ID and Product Code of the SubDevice with the same sequence number on the network match.

EtherCATConfig : Config : SubDevice : Mailbox

• 元件
  • Send : MailboxSendInfoType : Start
  • Recv : MailboxRecvInfoType : Start
• 目的
  Used to configure the mailbox Physical Start Address of an EtherCAT SubDevice.

EtherCATConfig : Config : SubDevice : Mailbox : CoE

• 元件
  • InitCmds : InitCmd : Index
  • InitCmds : InitCmd : SubIndex
  • InitCmds : InitCmd : Data
  • InitCmds : InitCmd : Timeout
• 屬性
  • InitCmds : InitCmd : CompleteAccess
• 目的
  After switching the EtherCAT state machine to the Pre-Operational state, execute the CoE initialization commands for the EtherCAT SubDevice in EthercatMaster::begin().

EtherCATConfig : Config : SubDevice : ProcessData

• 元件
  • Recv : BitLength
  • Send : BitLength
• 目的
  The bit length of the output process data and input process data of an EtherCAT SubDevice is provided to the firmware for relevant configuration.

EtherCATConfig : Config : SubDevice : ProcessData : Sm

• 元件
  • SyncManagerSettings : StartAddress
  • SyncManagerSettings : ControlByte
  • SyncManagerSettings : Enable
• 目的
  Used to configure the Sync Manager registers for the process data of an EtherCAT SubDevice.

EtherCATConfig : Config : SubDevice : DC

• 元件
  • CycleTime0
  • CycleTime1
  • ShiftTime
• 目的
  Used to configure the DC parameters of an EtherCAT SubDevice.