EtherCAT API 使用手冊

2025.04.29，版本 v3.2r0。

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

1. 簡介

1.1 關於 QEC MDevice

QEC（Quicker, Easier Control with EtherCAT）是由 ICOP 開發的 EtherCAT 控制器。它具有高同步性和即時性，並且易於開發。下文我們將介紹 QEC 的架構、特性和效能。

QEC 主站是相容於 86Duino Coding IDE 500+ 的 EtherCAT 主站系統。它提供 EtherCAT 主站和 EtherCAT 從站設備之間的即時 EtherCAT 通訊。除了 86Duino IDE 的 EtherCAT 函式庫外，QEC 主站還提供 Modbus、Ethernet TCP/IP、CAN 匯流排等工業通訊協議，並使用豐富的高階 C/C++ 程式語言進行快速應用開發。

1.1.1 什麼是86Duino IDE？

86Duino 整合開發環境 (IDE) 軟體可以輕鬆編寫程式碼並上傳到 86Duino 開發板和 QEC 主站裝置。它可以在 Windows、Mac OS X 和 Linux 上運行。環境採用Java編寫，基於 Arduino IDE、Processing、DJGPP 等開源軟體，可從以下連結下載： https://www.qec.tw/zh/software/.

QEC 主站軟體，86Duino IDE，也提供組態工具： 86EVA，一款圖型化組態工具，供使用者設定 EtherCAT 網路參數；其功能如下：

• EtherCAT 從站掃描
• 導入 ENI 文件
• 設定 EtherCAT 主站
• 配置 EtherCAT 從站

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

1.1.2 QEC EtherCAT 主站架構

EtherCAT 主站軟體僅運作在 DM&P 生產的 Vortex86EX2 CPU 上，此 CPU 採用雙系統架構，EtherCAT 主站軟體主要分為兩部分，分別運作在 Vortex86EX2 CPU 的各自系統上。

它們負責以下任務：

• EtherCAT 主站函式庫
  • 提供 C/C++ 語法應用功能
    • 初始化功能
    • 組態配置功能
    • Process Data (PDO) 存取功能
    • CAN application protocol over EtherCAT (CoE) 存取功能
    • File access over EtherCAT (FoE) 存取功能
    • 從站 Information Interface (SII) 存取功能
    • Distributed Clocks (DC) 存取功能
• EtherCAT 主站韌體
  • 執行 EtherCAT 主站核心
  • 控制主/從的乙太網路驅動程序，發送 EtherCAT 封包

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

1.1.3 硬體平台

EtherCAT 主站軟體僅運行在 DM&P 生產的 Vortex86EX2 CPU 上，該 CPU 具有雙獨立核心系統架構。分為主核心和從核心，每個核心都將運行自己的作業系統，再透過 Dual-RAM 和事件中斷進行雙核心系統之間的通訊。

分別各自的任務如下：

• 主站系統
  • 使用者的 EtherCAT application
  • 使用者的 HMI application
  • 使用者的 Ethernet application
  • ...等等
• 從核心系統
  • 只負責運行 EtherCAT 主站韌體。

由於大多數應用程式在主核心系統上運行，因此在從核心系統上運行的 EtherCAT 主站韌體將不受其他應用程式的干擾。這種設定使其能夠專注於執行 EtherCAT 主站核心，確保EtherCAT 的同步和即時能力。

1.1.4 雙系統同步

本節主要關注雙獨立系統的 PDO 資料同步。如下圖所示，使用者的應用程式和 EtherCAT 主站函式庫區塊將會在主核心系統上運行，而即時 EtherCAT 主站核心則將會在從核心系統上運行。

When the EtherCAT MDevice 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 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 and the interrupt handling procedure are completed simultaneously.

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

這些任務依照概述的程序步驟以循環方式定期執行，確保雙系統 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.

為了簡單起見，僅定義了 2 個主站類別：

• Class A：標準 EtherCAT 主站
• Class B：最低標準的 EtherCAT MDevice

您將看到A類、B類和我們的 QEC 主站之間的比較如下。

1.2.1 特性表

詞語用法：

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

1.3 功能包

1.3.1 電纜冗餘

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

電纜冗餘中電纜是否斷線分為以下三種情況。以下您將了解如何實現電纜冗餘，以及這些場景之間 EtherCAT 主控制器的差異。

• 無電纜破損
• 兩個從站之間的電纜斷裂
• 主站和從站之間的電纜斷裂

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

• 假設週期時間設定為 125 µs。
• 假設所有從站只有輸入 PDO（沒有輸出PDO），則過程資料幀中的工作計數器（WKC）在經過每個從站時都會加1。
• 假設 EtherCAT 網路上只有 6 個從站，預期工作計數器 (EWKC) 為 6。
• 主端口和輔端口在每個週期同時發送過程資料幀。

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

1.4 基準測量

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

• 支援更短的周期時間
• 支援更多流程數據
• 支援更多 EtherCAT 從站

然而，評估 EtherCAT 主站是否滿足使用者的應用要求通常需要將基準測量作為主要考慮因素。

Please visit EtherCAT MDevice Benchmark for more details.

1.4.1 EtherCAT 主站循環幀抖動

從 EtherCAT 主站傳送循環幀時的抖動，以 DC SYNC0 為參考。

• 影片：https://youtu.be/O888jD4XUsY?si=NaI9gsafyA1D2DlK

1.5 同步

EtherCAT 網路中所有從站之間的時間同步都依賴 EtherCAT 從站控制器 (ESC) 內的分散式時鐘 (DC) 單元，確保整個系統的一致性。通常，第一個具有 DC 的從站用作系統參考時鐘，以將其他從站與 DC 同步。關於DC更詳細的解釋，請參考分散式時鐘。

ESC 有三個同步輸出引腳： IRQ, SYNC0和 SYNC1。ESC 接收到 EtherCAT 循環訊框後，IRQ 接腳會向上層微控制器（μC）產生訊號。 SYNC0 和 SYNC1 接腳根據 ESC 的 DC 相關暫存器中的配置循環產生訊號到 µC。因此，如果 EtherCAT 從站沒有 µC，則它不支援同步功能。

EtherCAT 共有三種同步模式：

• Free Run
• SM-Synchronous
• DC-Synchronous

1.5.1 Free Run

EtherCAT 主站和所有 EtherCAT 從站都有自己的本地定時器，並且它們的週期時間是獨立的，因此它們不同步。如下圖所示，EtherCAT 主站和從站 1、從站 2、從站 3 到 從站 n 都有各自的 Cycle Time，導致不一致 Output Valid 以及 Input Latch。此場景不適合同步要求較高的應用。

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 SubDevices with the same jitter of MDevice in sending them. Even assuming zero jitter, due to finite hardware Propagation Delay the last SubDevices 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 SubDevices, resulting in an accuracy of SM-Synchronous at the microsecond level.

If each SubDevice 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 SubDevices 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

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

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

If the SubDevices 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 SubDevices to the same time point.

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

• 所有從站接收到循環封包後。
• 在發送下一個週期的循環封包之前。
• 根據不同 DC-Synchronous 方法，執行後可能需要選擇 Prepare Outputs:
  • Trigger µC to execute Prepare Outputs when the SM event occurs
  • Trigger µC to execute Output Valid when the SYNC event occurs.

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

2. 函式

QEC EtherCAT 主站函式庫。

EtherCAT 是一種即時工業乙太網路通訊協定，廣泛應用於自動化和控制系統。QEC-MDevice 是以 C/C++ 實作的 EtherCAT 主站函式庫，其中包含主站、一般從站、CiA 402 從站的類別，以及 QEC 系列從站的專用類別。這些類別不但有明確定義的職責，也考慮到未來的擴充性。

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

• EtherCAT 主站
  EtherCAT MDevice 部分不僅提供多樣且彈性的主站組態與操作功能，也提供多樣化的 EtherCAT 從站操作功能供 EtherCAT Device 部分調用。

• EtherCAT 裝置
  EtherCAT Device 部分提供通用的 EtherCAT 從站設備類別，可操作 PDOs、CoE、FoE 等功能，也包括 CiA 402 從站通用類別。

• QEC 系列裝置
  QEC 系列裝置部分為 ICOP 的 QEC 系列從屬裝置提供專用功能，讓使用者能以更方便簡潔的方式進行編寫程式碼。

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

EthercatMaster is the only class in the 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.

EtherCAT Master 部分和 EtherCAT Device 部分之間的主要類別關係是關聯，EtherCAT Device 部分依賴於EtherCAT Master部分。EthercatMaster 的類別關係如下圖所示：

• 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
在直流同步模式下，第一個具有直流的從站作為系統參考時鐘，以同步其他具有直流的從站。然而，這只涉及到同步網路中所有從站的系統時間，並不包括 EtherCAT 主站。在啟用DC同步模式的應用中，主站通常需要精確且定期地控制從站，因此主站也必須與網路上的所有從站同步其系統時間。
此同步有兩種方法：

• MDevice Shift Mode – ECAT_MASTER_SHIFT
  
  • 主站系統時間與參考時鐘同步。
  • 所有 DC 從站都與參考時鐘同步。
• Bus Shift Mode – ECAT_BUS_SHIFT
  
  • 主站系統時間與參考時鐘同步。
  • 所有 DC 從站都與參考時鐘同步。

StaticDriftCompensationFrames

預設：30000
由 EtherCAT 主站發送許多單獨的 ARMW 或 FRMW 漂移補償封包，將參考時鐘的系統時間分配給所有 DC 從站。

StateMachineTimeoutI2P

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

StateMachineTimeoutP2S

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

StateMachineTimeoutS2O

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

ScanNetworkTimeout

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

StartMasterTimeout

Default: 3000; Unit: milliseconds
Base timeout for start MDevice, 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_SubDevice × N_SubDevices) .
Here, N_SubDevices is the number of SubDevices on the network.

StartDeviceTimeout

Default: 500; Unit: milliseconds
Timeout per SubDevice for start MDevice, T_SubDevice.

ErrorDetectWkcMultipleFaultsThreshold

Default: 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 error interrupt will be triggered.

ErrorDetectMultipleLostFramesThreshold

Default: 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 error interrupt will be triggered.

EnableErrorBusReactionSyncUnitToSafeOp

預設：0
如果此參數設定為 1，則主站將使用應用程式控制器變更從站的 EtherCAT 狀態，並停用僅支援 EtherCAT 狀態機模擬的從站的同步管理器通道。

EnableErrorBusReactionSyncUnitToSafeOpAutoRestart

預設：1
只有當 EnableErrorBusReactionSyncUnitToSafeOp 設定為 1 時，此參數才會生效。如果此參數設定為 1，則主站將根據 ETG.1020 EtherCAT 協定增強中定義的主站中同步單元的重新啟動行為自動嘗試重新啟動同步單元，將 EtherCAT 狀態機切換回操作狀態。

IgnoreBiosOverride

預設：0
QEC 主站在 BIOS 中有一些 EtherCAT 配置參數。設定參數為1表示忽略 BIOS 中的 EtherCAT 配置參數；否則，它們不會被忽略。

2.1.1 初始化函式

在啟動 EtherCAT 主站之前，必須先將其初始化。本函式庫中提供多種組態參數供使用者選擇，目的在於滿足使用者多樣化的應用需求。

• 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
  當 Real-time EtherCAT 主站核心偵測到錯誤時，它將觸發錯誤中斷，並將32位元錯誤代碼傳遞給 EtherCAT 主站函式庫。如果使用者註冊了 Error Callback，系統將呼叫 Error Callback 來通知使用者特定的錯誤。
  Error Callback 支援的錯誤代碼如下：

• Event Callback
  當 Real-time EtherCAT 主站核心偵測到事件時，它將觸發事件中斷，並將32位元事件代碼傳遞給 EtherCAT 主站函式庫。如果使用者註冊了 Event Callback，系統將呼叫 Event Callback 來通知使用者特定的事件。
  Event Callback 支援的事件代碼如下：

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

2.1.3 從站資訊函數

此函式庫提供了獲取網路上 EtherCAT 從站設備資訊的功能。包括了查詢網路上從站的數量，透過序號檢索從站的供應商 ID、產品代碼、別名地址，以及使用上述資訊反向查詢從站編號。這用於識別從站設備的類型，並選擇要連接的適當的 EtherCAT 從站設備類別。

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

2.1.4 控制函式

EtherCAT 主站函式庫提供的控制功能對於管理 EtherCAT 網路的狀態和操作至關重要。透過使用這些功能，使用者可以確保對網路的精確控制，實現主從設備之間可靠、同步的通訊。

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

2.2 EthercatDevice

EtherCAT Device 部分提供通用的 EtherCAT 從站設備類別，可操作 PDOs、CoE、FoE 等功能，也包括 CiA 402 從站通用類別。

EtherCAT Device 部分和 EtherCAT Master 部分之間的主要類別關係是關聯，EtherCAT Device 部分依賴 EtherCAT Master 部分。如下圖所示，_EthercatDevice_CommonDriver 和 EthercatMaster 之間存在的關係。

• EthercatMaster 和 _EthercatDevice_CommonDriver 之間存在關聯，其中 _EthercatDevice_CommonDriver 取決於 EthercatMaster。
• 所有其他 EtherCAT 從站裝置類別均繼承自 _EthercatDevice_CommonDriver。

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

2.2.1 _EthercatDevice_CommonDriver

_EthercatDevice_CommonDriver 是一個摘要類別，不僅具有存取從站資訊的功能，還提供各種 EtherCAT 功能存取方法，包括 PDO、SII、CoE、FoE、DC 等。所有的 EtherCAT 從屬類都繼承自它。

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

• EthercatMaster 和 _EthercatDevice_CommonDriver 之間存在關聯，其中 _EthercatDevice_CommonDriver 取決於 EthercatMaster。
• 所有其他 EtherCAT 從站裝置類別均繼承自 _EthercatDevice_CommonDriver。

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

資訊功能

該函式庫提供取得網路中 EtherCAT 從站設備資訊的功能。這包括用於設備識別的基本詳細資訊，如 Vendor ID、Product Code、Alias Address 和 Device Name。此外，它還能提供有關 EtherCAT 從站設備是否支援 CoE、FoE、DC 等特定功能的資訊。這些從站資訊可讓使用者瞭解網路內設備的特性和功能，並執行相應的組態和控制任務。

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

分佈式時鐘 (DC) 功能

The Distributed Clocks (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.

對於系統同步，所有從站都同步至一個參考時鐘。通常，在一個區段內，主站之後的第一個具有分散式時鐘功能從站的 ESC 會持有參考時間 (系統時間)。此系統時間用作參考時鐘，以同步其他裝置和主站的 DC 從站時鐘。時鐘同步時會考慮到傳播延遲、本地時鐘來源漂移和本地時鐘偏移。

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 是指 EtherCAT 網路中主站與從站之間交換的即時通訊資料。這些資料包括用於控制、監控和通訊目的的資訊。EtherCAT 主站週期性地傳輸製程資料，以控制和監控所有從站，確保高同步性和低延遲。

EtherCAT 從站控制器 (ESC) 中的現場總線記憶體管理單元 (FMMU) 可將雙埠記憶體映射為邏輯位址。所有從站節點都會檢查 EtherCAT 主站發送的 EtherCAT 訊框，比較過程資料的邏輯位址與 FMMU 中的設定位址。如果發現匹配，則 output process data 會傳輸至雙埠記憶體，而 input process data 則會插入 EtherCAT 封包。

總體而言，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 從站控制器使用強制性 NVRAM（通常是具有 I²C 介面的序列 EEPROM）來儲存 EtherCAT 從站資訊 (ESI)。這些資訊包括 Vendor ID、Product Code、Mailbox Configuration、FMMU、PDO 等。EEPROM 大小從 1 Kbit 到 4 Mbit 均可支援，視 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 是一個通用的 EtherCAT 從站類別，可用於控制所有的 EtherCAT 從站設備，包括存取從站設備的資訊、PDO、CoE、FoE、DC 等。
EthercatDevice_Generic 的類別關係如下圖所示：

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

初始化函式

EthercatDevice_Generic class 的初始化相關函式。

• attach()
• detach()

2.2.3 EthercatDevice_CiA402

EthercatDevice_CiA402 是一個通用的 CiA 402 EtherCAT SubDevice 類，旨在控制任何支援 CiA 402 標準的 EtherCAT 伺服驅動器。
它提供了常用的CiA 402物件的存取函數以及多種CiA 402操作模式和功能組的操作函數，包括：

• 操作模式
  • Profile Position (pp)
  • Profile Velocity (pv)
  • Profile Torque (tq)
  • Homing (hm)
  • Cyclic Synchronous Position (csp)
  • Cyclic Synchronous Velocity (csv)
  • Cyclic Synchronous Torque (CST)
• 功能組別
  • Touch Probe

CiA402 驅動設定檔的實施指令。
在基於 EtherCAT 的伺服驅動器中使用 IEC 61800-7-201 的指令。

有關 CiA 402 的更多詳細信息，請參閱以下文件：

• CiA 草案標準 402：CANopen 設備設定檔驅動器和運動控制
• CiA402 驅動設定檔的 ETG.6010 實作指令
• 目前使用的 CiA 402 驅動設備的使用手冊

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

• EthercatDevice_CiA402 繼承自 _EthercatDevice_CommonDriver.
• 基底類別：_EthercatDevice_CommonDriver

For more details on EthercatDevice_CiA402 class, please see EtherCAT CiA402 APIs.

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

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 是 ICOP 開發的摘要類別，為 EtherCAT 從站特定功能提供專用存取函式。這些功能包括系統監控（溫度、電壓、電流）、訂單資訊、MTBF等。

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

• _EthercatDevice_DmpCommonDriver 繼承自 _EthercatDevice_CommonDriver。

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

系統監控函式

含 MCU 的 QEC 系列 EtherCAT 從站設備均提供 CoE 物件以取得系統監控資訊，包括系統溫度、系統電壓、系統電流、週邊電壓及週邊電流。因此，本函式庫提供取得系統監控資訊的函式，讓使用者能及時監控系統，評估系統是否有故障的跡象。

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

MTBF函式

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

含 MCU 的 QEC 系列 EtherCAT 從站設備皆提供 CoE 物件以取得 MTBF 相關資訊。因此，本函式庫提供取得這些 MTBF 相關資訊的函式，讓使用者或用戶可以提供給製造商來評估與判斷裝置的壽命與故障。

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

訂購資訊函式

含 MCU 的 QEC 系列 EtherCAT 從站設備皆提供 CoE 物件以取得客戶訂單相關資訊，這些資訊在出貨前已預燒入設備中。因此，本函式庫提供取得這些客戶訂單資訊的功能，方便必要時進行查詢。

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

2.3.2  EthercatDevice_DmpDIQ_Generic

EthercatDevice_DmpDIQ_Generic 是專為 ICOP EtherCAT 從站數位 I/O 模組所開發的 EtherCAT 從站類別。它提供數位輸入、數位輸出及其他功能的 API。

2.3.3  EthercatDevice_DmpAIQ_Generic

EthercatDevice_DmpAIQ_Generic 是專為 ICOP EtherCAT 從站類比 I/O 模組所開發的 EtherCAT 從站類別。它提供類比輸入、類比輸出及其他功能的 API。

2.3.4  EthercatDevice_DmpHID_Generic

EthercatDevice_DmpHID_Generic 是專為 ICOP QEC EtherCAT 從站 HID 模組所開發的 EtherCAT 從站類別。它包含 RS232/RS485、4×4 Keypad、16×2 LCM、Manual Pulse Generator (MPG) 及 Buzzer 功能。

2.3.5  EthercatDevice_DmpLCD_Generic

EthercatDevice_DmpLCD_Generic 是專為 ICOP EtherCAT 從站 LCD 模組開發的 EtherCAT 從站類別。它提供了多種繪圖 API。

2.3.6  EthercatDevice_DmpStepper_Generic

EthercatDevice_DmpStepper_Generic 是專為 DM&P Group 的 EtherCAT 從站三軸步進馬達控制器模組所開發的 EtherCAT 從站類別。此模組具有馬達驅動器、編碼器輸入及其他 CNC 相關功能。在馬達控制部分，它不僅支援 CiA 402 模式，也支援三軸同步 G-code 模式。

3. 範例

3.1 從站裝置資訊範例

從站裝置資訊範例。

3.1.1 範例 1：使用 EthercatMaster 類別

透過 EthercatMaster 類別顯示從站裝置資訊。

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;

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

  master.begin(); // Initialize EtherCAT Master in Pre-OP state

  Serial.println("Starting EtherCAT Master...");

  // Print Out All Slave Information
  for (int i = 0; i < master.getSlaveCount(); i++) {
    Serial.print("Slave ");
    Serial.print(i);
    Serial.print(" VID: ");
    Serial.print(master.getVendorID(i), HEX);
    Serial.print(", PID: ");
    Serial.print(master.getProductCode(i), HEX);
    Serial.print(", Rev: ");
    Serial.print(master.getRevisionNumber(i), HEX);
    Serial.print(", Ser: ");
    Serial.print(master.getSerialNumber(i), HEX);
    Serial.print(", Alias: ");
    Serial.print(master.getAliasAddress(i));
    Serial.println();
  }
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.1.2 範例 2：使用 EthercatDevice_Generic 類別

透過 EthercatDevice_Generic 類別顯示從站裝置資訊。

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic slave;

char name[256];

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

  master.begin(); // Initialize EtherCAT Master in Pre-Operational state

  for (int i = 0; i < master.getSlaveCount(); i++) {
    slave.attach(i, master); // Attach the slave to the master
    Serial.print("Slave ");
    Serial.println(i);

    Serial.print("                Name: ");
    Serial.println(slave.getDeviceName(name, 256));

    Serial.print("           Vendor ID: 0x");
    Serial.println(slave.getVendorID(), HEX);

    Serial.print("        Product Code: 0x");
    Serial.println(slave.getProductCode(), HEX);

    Serial.print("     Revision Number: 0x");
    Serial.println(slave.getRevisionNumber(), HEX);

    Serial.print("       Serial Number: 0x");
    Serial.println(slave.getSerialNumber(), HEX);

    Serial.print("       Alias Address: ");
    Serial.println(slave.getAliasAddress());

    Serial.print("    Mailbox Protocol: 0x");
    Serial.println(slave.getMailboxProtocol(), HEX);

    Serial.print("         CoE Details: 0x");
    Serial.println(slave.getCoEDetails(), HEX);

    Serial.print("         FoE Details: 0x");
    Serial.println(slave.getFoEDetails(), HEX);

    Serial.print("         EoE Details: 0x");
    Serial.println(slave.getEoEDetails(), HEX);

    Serial.print("        SoE Channels: ");
    Serial.println(slave.getSoEChannels());

    Serial.print("        DC Supported: ");
    Serial.println(slave.isSupportDC());
  }
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.1.3 範例 3：使用 EthercatDevice_CiA402 類別

透過 EthercatDevice_CiA402 類別顯示子裝置資訊。

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_CiA402 slave;

char name[256];

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

  master.begin();  // Initialize EtherCAT Master in Pre-Operational state

  for (int i = 0; i < master.getSlaveCount(); i++) {
    // Attach the slave to the master
    if (slave.attach(i, master) < 0) {
      continue; // Skip this slave if attachment fails
    }

    Serial.print("Slave ");
    Serial.println(i);

    Serial.print("                Name: ");
    Serial.println(slave.getDeviceName(name, 256));

    Serial.print("           Vendor ID: 0x");
    Serial.println(slave.getVendorID(), HEX);

    Serial.print("        Product Code: 0x");
    Serial.println(slave.getProductCode(), HEX);

    Serial.print("     Revision Number: 0x");
    Serial.println(slave.getRevisionNumber(), HEX);

    Serial.print("       Serial Number: 0x");
    Serial.println(slave.getSerialNumber(), HEX);

    Serial.print("       Alias Address: ");
    Serial.println(slave.getAliasAddress());

    Serial.print("    Mailbox Protocol: 0x");
    Serial.println(slave.getMailboxProtocol(), HEX);

    Serial.print("         CoE Details: 0x");
    Serial.println(slave.getCoEDetails(), HEX);

    Serial.print("         FoE Details: 0x");
    Serial.println(slave.getFoEDetails(), HEX);

    Serial.print("         EoE Details: 0x");
    Serial.println(slave.getEoEDetails(), HEX);

    Serial.print("        SoE Channels: ");
    Serial.println(slave.getSoEChannels());

    Serial.print("        DC Supported: ");
    Serial.println(slave.isSupportDC());
  }
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2 SDO 上傳/下載範例

SDO 讀取/寫入範例。

3.2.1 範例 1：使用 sdoUpload8() 進行 SDO 讀取

The usage of sdoUpload16(), sdoUpload32(), and sdoUpload64() is similar to sdoUpload8(), except for the difference in the return value type.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

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

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

  Serial.print("1C12h.0 => ");
  Serial.println(device.sdoUpload8(0x1C12, 0x00));

  Serial.print("1C13h.0 => ");
  Serial.println(device.sdoUpload8(0x1C13, 0x00));
  // ...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2.2 範例 2：使用 sdoUpload() 進行 SDO 讀取

使用 sdoUpload() 函式來執行 SDO 讀取操作。

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

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

  uint8_t value;

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

  if (device.sdoUpload(0x1C12, 0x00, &value, sizeof(value)) >= 0) {
    Serial.print("1C12h.0 => ");
    Serial.println(value);
  }

  if (device.sdoUpload(0x1C13, 0x00, &value, sizeof(value)) >= 0) {
    Serial.print("1C13h.0 => ");
    Serial.println(value);
  }
  //...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2.3 範例 3：使用 sdoUpload() 進行 SDO 讀取並處理中止碼

SDO Upload using sdoUpload() with abort code.
Initiate an SDO Upload command to read a value from a non-existent object, expecting an abort code of 0x06020000. For more information about abort codes, please refer to SDO Abort Code.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

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

  uint32_t abortcode;
  uint8_t value;

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

  if (device.sdoUpload(0xFFFF, 0xFF, &value, sizeof(value), &abortcode) == ECAT_ERR_DEVICE_COE_ERROR) {
    Serial.print("Abort Code: 0x");
    Serial.println(abortcode, HEX);
  }
  //...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2.4 範例 4：使用 sdoDownload8() 進行 SDO 寫入

SDO Download using sdoDownload8().
The usage of sdoDownload16(), sdoDownload32(), and sdoDownload64() is similar to sdoDownload8(), except for the difference in the input parameter types.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

void setup() {
  master.begin();
  device.attach(0, master);

  device.sdoDownload8(0x1C12, 0x00, 0);
  device.sdoDownload8(0x1C13, 0x00, 0);
  //...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2.5 Example 5: SDO Download using sdoDownload()

SDO Download using sdoDownload().

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

void setup() {
  uint8_t value;

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

  value = 0;
  device.sdoDownload(0x1C12, 0x00, &value, sizeof(value));
  value = 0;
  device.sdoDownload(0x1C13, 0x00, &value, sizeof(value));
  //...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2.6 Example 6: SDO Download using sdoDownload() with abort code

SDO Download using sdoDownload() with abort code.
Initiate an SDO Download command to write a value to a non-existent object, expecting an abort code of 0x06020000. For more information about abort codes, please refer to SDO Abort Code.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

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

  uint32_t abortcode;
  uint8_t value = 0x01;

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

  if (device.sdoDownload(0xFFFF, 0xFF, &value, sizeof(value), &abortcode) == ECAT_ERR_DEVICE_COE_ERROR) {
    char buf[20];
    sprintf(buf, "Abort Code: 0x%08lX", abortcode);
    Serial.println(buf);
  }
  //...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2.7 Example 7: Print the PDO mapping configuration

Print the PDO mapping configuration.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

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

  uint8_t assign_nr, mapping_nr;
  uint16_t mapping;
  uint32_t entry;

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

  // RxPDO Mapping List
  assign_nr = device.sdoUpload8(0x1C12, 0x00);
  for (int m = 0; m < assign_nr; m++) {
    mapping = device.sdoUpload16(0x1C12, m + 1);
    Serial.print("  RxPDO");
    Serial.print(m + 1);
    Serial.print(" (");
    Serial.print(mapping, HEX);
    Serial.println("h)");

    mapping_nr = device.sdoUpload8(mapping, 0x00);
    for (int n = 0; n < mapping_nr; n++) {
      entry = device.sdoUpload32(mapping, n + 1);
      Serial.print("    ");
      char entryBuf[11];  // "XXXXXXXXh" + null
      sprintf(entryBuf, "%08lXh", entry);
      Serial.println(entryBuf);
    }
  }

  // TxPDO Mapping List
  assign_nr = device.sdoUpload8(0x1C13, 0x00);
  for (int m = 0; m < assign_nr; m++) {
    mapping = device.sdoUpload16(0x1C13, m + 1);
    Serial.print("  TxPDO");
    Serial.print(m + 1);
    Serial.print(" (");
    Serial.print(mapping, HEX);
    Serial.println("h)");

    mapping_nr = device.sdoUpload8(mapping, 0x00);
    for (int n = 0; n < mapping_nr; n++) {
      entry = device.sdoUpload32(mapping, n + 1);
      Serial.print("    ");
      char entryBuf[11];
      sprintf(entryBuf, "%08lXh", entry);
      Serial.println(entryBuf);
    }
  }
  //...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.2.8  Example 8: Change the PDO mapping configuration

Change the PDO mapping configuration.

Map the following objects to PDOs in a CiA 402 device that supports PDO mapping:

• Output PDO (RxPDO)
  • Object 6040_h: Controlword
  • Object 607A_h: Target position
  • Object 60FF_h: Target velocity
  • Object 6071_h: Target torque
  • Object 6060_h: Modes of operation
• Input PDO (TxPDO)
  • Object 6041_h: Statusword
  • Object 6064_h: Position actual value
  • Object 606C_h: Velocity actual value
  • Object 6077_h: Torque actual value
  • Object 6061_h: Modes of operation display

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

void setup() {
  master.begin();
  device.attach(0, master);
  // 1C12
  device.sdoDownload8(0x1C12, 0x00, 0);
  device.sdoDownload8(0x1601, 0x00, 0);
  device.sdoDownload32(0x1601, 0x01, 0x60400010);
  device.sdoDownload32(0x1601, 0x02, 0x607A0020);
  device.sdoDownload32(0x1601, 0x03, 0x60FF0020);
  device.sdoDownload32(0x1601, 0x04, 0x60710010);
  device.sdoDownload32(0x1601, 0x05, 0x60600008);
  device.sdoDownload8(0x1601, 0x00, 5);
  device.sdoDownload16(0x1C12, 0x1601, 1);
  device.sdoDownload8(0x1C12, 0x00, 1);
  // 1C13
  device.sdoDownload8(0x1C13, 0x00, 0);
  device.sdoDownload8(0x1A01, 0x00, 0);
  device.sdoDownload32(0x1A01, 0x01, 0x60410010);
  device.sdoDownload32(0x1A01, 0x02, 0x60640020);
  device.sdoDownload32(0x1A01, 0x03, 0x606C0020);
  device.sdoDownload32(0x1A01, 0x04, 0x60770010);
  device.sdoDownload32(0x1A01, 0x05, 0x60610008);
  device.sdoDownload8(0x1A01, 0x00, 5);
  device.sdoDownload16(0x1C13, 0x1A01, 1);
  device.sdoDownload8(0x1C13, 0x00, 1);
  //...
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.3 PDO Read/Write Examples

PDO Read/Write Examples.

3.3.1 Example 1: Read a bit data from Input PDO using pdoBitRead()

Read a bit from Input PDO using pdoBitRead().
A 16-channel digital input EtherCAT SubDevice has 2-byte Input PDOs, with each bit corresponding to a digital input channel. The states of channels 0 and 9 will be printed with a frequency of 1 Hz.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

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

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

void loop() {
  // Read and display the state of PDO bits
  Serial.print("Bit0 => ");
  Serial.print(device.pdoBitRead(0)); // Read PDO bit 0
  Serial.print(", Bit9 => ");
  Serial.println(device.pdoBitRead(9)); // Read PDO bit 9

  delay(1000);
}

3.3.2 Example 2: Read a byte data from Input PDO using pdoRead8()

Read data from Input PDO using pdoRead8().
Same as example 1.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

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

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

void loop() {
  // Read specific bits using pdoRead8 and print their values
  Serial.print("Bit0 => ");
  Serial.print((device.pdoRead8(0) >> 0) & 1);
  Serial.print(", Bit9 => ");
  Serial.println((device.pdoRead8(1) >> 1) & 1);

  delay(1000);
}

3.3.3 Example 3: Read data from Input PDO using pdoRead()

Read data from Input PDO using pdoRead().
Same as example 1.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

uint16_t value;

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

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

void loop() {
  device.pdoRead(0, &value, sizeof(value));

  Serial.print("Bit0 => ");
  Serial.print((value >> 0) & 1);
  Serial.print(", Bit9 => ");
  Serial.println((value >> 9) & 1);

  delay(1000);
}

3.3.4 Example 4: Write a bit data to Output PDO using pdoBitWrite()

Write a bit to Output PDO using pdoBitWrite().
A 16-channel digital output EtherCAT SubDevice has 2-byte Output PDOs, with each bit corresponding to a digital output channel. Channels 0 and 9 will be toggled at a frequency of 1 Hz.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

void setup() {
  master.begin();
  device.attach(0, master);
  master.start();
}

void loop() {
  device.pdoBitWrite(0, 1);
  device.pdoBitWrite(9, 1);
  delay(1000);

  device.pdoBitWrite(0, 0);
  device.pdoBitWrite(9, 0);
  delay(1000);
}

3.3.5 Example 5: Write a byte data to Output PDO using pdoWrite8()

Write data to Output PDO using pdoWrite8().
Same as example 4.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

void setup() {
  master.begin();
  device.attach(0, master);
  master.start();
}

void loop() {
  device.pdoWrite8(0, 0x01);
  device.pdoWrite8(1, 0x02);
  delay(1000);
  
  device.pdoWrite8(0, 0x00);
  device.pdoWrite8(1, 0x00);
  delay(1000);
}

3.3.6 Example 6: Write data to Output PDO using pdoWrite()

Write data to Output PDO using pdoWrite().
Same as examples 4.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

uint16_t value;

void setup() {
  master.begin();
  device.attach(0, master);
  master.start();
}

void loop() {
  value = 0x0201;
  device.pdoWrite(0, &value, sizeof(value));
  delay(1000);
  
  value = 0x0000;
  device.pdoWrite(0, &value, sizeof(value));
  delay(1000);
}

3.4 Callback Examples

Callback Examples.

3.4.1 Example 1: Cyclic callback

A 16-channel digital output EtherCAT SubDevice has 2-byte Output PDOs, with each bit corresponding to a digital output channel. Channels 0 and 9 will be toggled at a frequency of 1 Hz.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

int toggle = 0;
int cycle_count = 0;

void MyCyclicCallback()
{
  if (++cycle_count < 1000)
    return;

  cycle_count = 0;

  toggle = !toggle;
  device.pdoBitWrite(0, toggle);
  device.pdoBitWrite(9, toggle);
}

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

  master.begin();
  device.attach(0, master);
  master.attachCyclicCallback(MyCyclicCallback);
  master.start(1000000);  // 1ms cycle
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.4.2 Example 2: Cyclic callback with FPU-enabled

Cyclic callback with FPU-enabled.
If the callback function requires floating-point arithmetic, please use FPU-enabled callback function. For more detailed information, please refer to the function description below.

• attachCyclicCallback()
• attachErrorCallback()
• attachEventCallback()

以下是範例程式碼：

#include "Ethercat.h"

#define GRAVITY (9.80665)

EthercatMaster master;
EthercatDevice_Generic device;

int toggle = 0;
int cycle_count = 0;
double S = 0.0, T = 0.0;

double s = 0.0, t = 0.0;


void MyCyclicCallback()
{
  S = (GRAVITY * T * T) / 2.0;
  T += 0.001; 

  if (++cycle_count < 1000)
    return;
  cycle_count = 0;

  toggle = !toggle;
  device.pdoBitWrite(0, toggle);
  device.pdoBitWrite(9, toggle);
}

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

  master.begin();
  device.attach(0, master);
  master.attachCyclicCallback(MyCyclicCallback, true);
  master.start(1000000);
}

void loop() {
  s = (GRAVITY * t * t) / 2.0;
  t += 1.0;

  Serial.print("S = ");
  Serial.println(s, 6);

  delay(1000);
}

3.4.3 Example 3: Error callback

Print the count of each type of error once per second.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

// Error counters
int wkc_single_fault_cnt = 0;
int wkc_multiple_faults_cnt = 0;
int single_lost_frame_cnt = 0;
int multiple_lost_frames_cnt = 0;
int cable_broken_cnt = 0;
int wait_ack_timeout_cnt = 0;

// Error callback function
void myErroCallback(uint32_t errorcode) {
  switch (errorcode) {
    case ECAT_ERR_WKC_SINGLE_FAULT:
      wkc_single_fault_cnt++;
      break;
    case ECAT_ERR_WKC_MULTIPLE_FAULTS:
      wkc_multiple_faults_cnt++;
      break;
    case ECAT_ERR_SINGLE_LOST_FRAME:
      single_lost_frame_cnt++;
      break;
    case ECAT_ERR_MULTIPLE_LOST_FRAMES:
      multiple_lost_frames_cnt++;
      break;
    case ECAT_ERR_CABLE_BROKEN:
      cable_broken_cnt++;
      break;
    case ECAT_ERR_WAIT_ACK_TIMEOUT:
      wait_ack_timeout_cnt++;
      break;
  }
}

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

  master.attachErrorCallback(myErroCallback);
  master.begin(); 
  master.start(); 
}

void loop() {

  Serial.print("ECAT_ERR_WKC_SINGLE_FAULT     = ");
  Serial.println(wkc_single_fault_cnt);
  Serial.print("ECAT_ERR_WKC_MULTIPLE_FAULTS  = ");
  Serial.println(wkc_multiple_faults_cnt);
  Serial.print("ECAT_ERR_SINGLE_LOST_FRAME    = ");
  Serial.println(single_lost_frame_cnt);
  Serial.print("ECAT_ERR_MULTIPLE_LOST_FRAMES = ");
  Serial.println(multiple_lost_frames_cnt);
  Serial.print("ECAT_ERR_CABLE_BROKEN         = ");
  Serial.println(cable_broken_cnt);
  Serial.print("ECAT_ERR_WAIT_ACK_TIMEOUT     = ");
  Serial.println(wait_ack_timeout_cnt);

  delay(1000);
}

3.4.4 Example 4: Event callback

Print the count of each type of event once per second.

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

// Event counters
int state_changed_cnt = 0;
int cable_reconnected_cnt = 0;

// Event callback function
void myEventCallback(uint32_t eventcode) {
  switch (eventcode) {
    case ECAT_EVT_STATE_CHANGED:
      state_changed_cnt++;
      break;
    case ECAT_EVT_CABLE_RECONNECTED:
      cable_reconnected_cnt++;
      break;
  }
}

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

  master.attachEventCallback(myEventCallback);
  master.begin();
  master.start();
}

void loop() {
  Serial.print("ECAT_EVT_STATE_CHANGED     = ");
  Serial.println(state_changed_cnt);
  Serial.print("ECAT_EVT_CABLE_RECONNECTED = ");
  Serial.println(cable_reconnected_cnt);
  delay(1000);
}

3.5 DC Examples

DC Examples.

3.5.1  Example 1: Enable DC synchronization

Enable DC synchronization.
Implementing position control on a CiA 402 EtherCAT SubDevice using the EthercatDevice_Generic class. The CiA 402 control mode is set to cyclic synchronous position mode, and DC synchronization is enabled for precise timing.

The default PDO mapping is as follows:

• Output PDO (RxPDO)

• Input PDO (TxPDO)

以下是範例程式碼：

#include "Ethercat.h"

EthercatMaster master;
EthercatDevice_Generic device;

uint32_t position = 0;

// Cyclic callback function, executed every 1ms
void MyCyclicCallback() {
  // Check if the device is in "Operation Enable" state (0x27)
  if ((device.pdoRead8(0) & 0x6F) != 0x27)
    return;

  // Increment target position by 1000 and write it to PDO
  device.pdoWrite32(2, position += 1000);
}

void setup() {
  Serial.begin(115200);
  while (!Serial);  // Wait for Serial to be ready

  master.begin();

  device.attach(0, master);             // Attach slave device (slave ID 0)
  device.setDc(1000000);                // Enable Distributed Clock (1ms cycle)
  device.sdoDownload8(0x6060, 0x00, 8); // Set mode of operation to CSP (mode 8)

  // Register the cyclic callback function
  master.attachCyclicCallback(MyCyclicCallback);
  master.start(1000000, ECAT_SYNC);     // Start EtherCAT master with 1ms sync cycle

  // Read current position and set as initial target position
  position = device.pdoRead32(2);
  device.pdoWrite32(2, position);

  // Transition through CiA 402 state machine to reach "Operation Enable"
  device.pdoWrite8(0, 0x80); // Shutdown
  delay(1000);
  device.pdoWrite8(0, 0x06); // Switch On
  delay(1000);
  device.pdoWrite8(0, 0x07); // Enable Voltage
  delay(1000);
  device.pdoWrite8(0, 0x0F); // Operation Enable
  delay(1000);
}

void loop() {
  // put your main code here, to run repeatedly:

}

3.6 QEC 從站：數位輸入/輸出

#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 從站：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 從站：步進馬達控制器

#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 代碼清單：

A.4 事件回傳代碼

Event Callback 代碼清單：

A.5 SDO 中止代碼

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

A.6 資料類型

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

A.7 EtherCAT 網路資訊

EtherCAT Network Information (ENI) 包含配置 EtherCAT 網路的必要設定。這個以 XML 為基礎的檔案包含主站的一般資訊，以及連接至主站的每個從站設備的設定。EtherCAT 組態工具可讀取 ESI 檔案或線上掃描網路中的所有從站，之後使用者就可以設定相關的 EtherCAT 設定，例如 PDO 映射和啟用 DC，然後匯出 ENI 檔案。

EtherCAT Technology Group 規定 EtherCAT 主站軟體在網路組態部分必須至少支援下列其中一項： 線上掃描或讀取 ENI。而本函式庫則兩者皆支援。在讀取 ENI 的情況下，本程式庫目前僅從 ENI 檔案中擷取部分資訊用於網路組態。

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

EtherCATConfig : Config : SubDevice : Info

• 元件
  • VendorId
  • ProductCode
• 屬性
  • Identification : Value
• 目的
  用於檢查網路中的 EtherCAT 從站是否與 ENI 檔案中指定的從站相符。檢查規則如下：
  • 檢查 ENI 檔案中的從站數量是否與網路上的從站數量相符。
  • 對於 ENI 檔案中具有 Identification： 對於 ENI 檔案中具有 Identification: Value 屬性的從站，請檢查網路上是否有與 Alias Address 和 Identification： Value 屬性，以及 Vendor ID 和 Product Code 的從站。如果存在這樣的從站，則表示匹配成功。
  • 對於具有 Identification： Value 屬性無法匹配的從站，或沒有此屬性的從站，請檢查網路中序列號相同的從站的 Vendor ID 和 Product Code 是否匹配。

EtherCATConfig : Config : SubDevice : Mailbox

• 元件
  • Send : MailboxSendInfoType : Start
  • Recv : MailboxRecvInfoType : Start
• 目的
  用於設定 EtherCAT 從站的 mailbox Physical Start Address。

EtherCATConfig : Config : SubDevice : Mailbox : CoE

• 元件
  • InitCmds : InitCmd : Index
  • InitCmds : InitCmd : SubIndex
  • InitCmds : InitCmd : Data
  • InitCmds : InitCmd : Timeout
• 屬性
  • InitCmds : InitCmd : CompleteAccess
• Purpose
  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
• 目的
  EtherCAT 從站的 output process data 和input process data 的位元長度會提供給韌體進行相關設定。

EtherCATConfig : Config : SubDevice : ProcessData : Sm

• 元件
  • SyncManagerSettings : StartAddress
  • SyncManagerSettings : ControlByte
  • SyncManagerSettings : Enable
• 目的
  用於設定 EtherCAT 從站的 process data 同步管理暫存器。

EtherCATConfig : Config : SubDevice : DC

• 元件
  • CycleTime0
  • CycleTime1
  • ShiftTime
• 目的
  用於配置 EtherCAT 從站的 DC 參數。

86Duino 參考的文本是根據 知識共享署名-相同方式分享 3.0 許可證，部分文本是從 Arduino 參考 修改的。 參考中的代碼示例已發佈到公共領域。

For more info and sample requests, please write to info@icop.com.tw，致電離您最近的 ICOP分公司，或聯絡我們的 全球官方經銷商。