EtherCAT API 使用手冊

2024.08.15，版本2.2r1。

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

1. 簡介

1.1 關於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 主站軟體主要分為兩個部分，每個部分運行在 Vortex86EX2 CPU 的雙核心系統上。它們負責以下任務：

• EtherCAT 主站函式庫
  • 提供 C/C++ 語法應用功能
    • 初始化功能
    • 組態配置功能
    • Process Data (PDO) 存取功能
    • CAN application protocol over EtherCAT (CoE) 存取功能
    • File access over EtherCAT (FoE) 存取功能
    • Slave 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 主站核心則將會在從核心系統上運行。

當EtherCAT主站核心運行到Process Inputs階段時，它會從乙太網路驅動程式接收所有循環封包，並將 Input PDO 資料複製到 DPRAM 中。

當運行到User Application階段後，EtherCAT主站核心會觸發主核心系統中的循環中斷，而主核心系統收到循環中斷後，將會執行EtherCAT主站函式庫的中斷處理程序。它會將Input PDO資料從DPRAM移至主記憶體，呼叫使用者所設置的Cyclic Callback，在Cyclic Callback完成後，將Output PDO資料從主記憶體傳輸到DPRAM，處理非循環命令，並結束中斷處理程序。至此，EtherCAT主站核心的 User Application和中斷處理程序同時完成。

當EtherCAT主站核心運行到Write Outputs階段時，它將輸出 PDO 資料從 DPRAM 複製到乙太網路驅動程式的 DMA 並發送幀。

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

1.2 特點

EtherCAT 技術組定義了兩種 EtherCAT Master 軟體類別於 ETG.1500。此規範明確定義了的眾多主站功能，並為了簡單起見，分成了以下 2 個類別：

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

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

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 Benchmark

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

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

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

請造訪EtherCAT Master Benchmark以了解更多詳情。

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 Master 和 Slave 1、Slave 2、Slave 3 到 Slave n 都有各自的 Cycle Time，導致 Output Valid和Input Latch不一致。此場景不適合同步要求較高的應用。

1.5.2 SM-Synchronous

當 ESC 接收到循環幀時，IRQ 引腳會產生 SM 事件，該事件將觸發 µC 中本地應用程式的執行。如下圖所示，從站接收循環封包時，其抖動與主站發送時的抖動相同。即使假設零抖動，由於硬體有限制的傳播延遲，最後一個從站將比第一個從站稍後接收循環幀。

由於傳播延遲，從裝置之間的 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的選擇至關重要，必須滿足以下條件：

• 所有從站接收到循環封包後。
• 在發送下一個週期的循環封包之前。
• 根據不同 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 主站函式庫。

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

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

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

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

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

2.1 EtherCAT Master

EtherCAT Master part不僅提供豐富、靈活的主站配置和操作功能，還提供豐富的 EtherCAT 從站操作功能供 EtherCAT Device 部分呼叫。

EthercatMaster是EtherCAT Master部分中唯一的類別，它作為與EtherCAT韌體的重要通訊橋樑。在雙系統通訊方面，其職責包括通訊介面初始化、循環處理資料交換、處理非循環傳輸介面以及管理中斷事件。 API方面，提供了master初始化、master控制、存取slave資訊等相關功能。

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

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

EtherCAT 主站設定

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

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同步模式的應用中，主站通常需要精確且定期地控制從站，因此主站也必須與網路上的所有從站同步其系統時間。
此同步有兩種方法：

• Master 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

預設：3000；單位：毫秒
啟動主機的基本逾時，T~base~。
在EthercatMaster::start()中，請求韌體啟動 EtherCAT，此要求的逾時稱為啟動逾時 T~startup~。
EtherCAT的啟動逾時計算如下：$$ T_{startup} = T_{base} + ( T_{slave} × N_{slaves}) $$。
這裡，N~slaves~ 代表了網路上從站的數量。

StartDeviceTimeout

預設：500；單位：毫秒
主站啟動每個從站的逾時時間，T~slave~。

ErrorDetectWkcMultipleFaultsThreshold

預設：3
主站應檢查接收到的 EtherCAT 資料封包的工作計數器。如果工作計數器與預期值不匹配，則會偵測到錯誤。當連續錯誤數量超過此參數時，將觸發ECAT_ERR_WKC_MULTIPLE_FAULTS錯誤中斷。

ErrorDetectMultipleLostFramesThreshold

預設：3
主站可以使用 EtherCAT 資料標頭的索引來檢查是否會接收到所有發送的 EtherCAT 資料封包。如果 EtherCAT 資料報遺失，則會偵測到錯誤。當連續錯誤數量超過此參數時，將觸發ECAT_ERR_MULTIPLE_LOST_FRAMES錯誤中斷。

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
  Cyclic Callback 的目的是讓使用者實現運動控制、CNC 控制、機器人控制等週期性控制系統。Real-time EtherCAT 主站核心在指定的週期時間觸發 EtherCAT 主站函式庫的循環中斷，然後等待 ACK 以確保過程資料同步。如果使用者註冊了 Cyclic Callback，就會呼叫它來實現精準的週期控制。
• 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) 功能

Distributed Clocks (DC) 是 EtherCAT 從站控制器 (ESC) 內的重要功能單元。它負責在EtherCAT網路中實現時間同步機制，確保所有從設備按照統一的時間基準同步時鐘，從而確保整個系統時間的一致性。

對於系統同步，所有從站都同步至一個參考時鐘。通常，在一個區段內，主站之後的第一個具有分散式時鐘功能從站的 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)是 EtherCAT 的協定擴展，可實現透過 EtherCAT 網路的檔案傳輸功能。它指定了將韌體或任何其他檔案下載到 EtherCAT 從站設備或從 EtherCAT 從站設備上傳韌體或任何其他檔案的標準方法。

• 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.3 QEC 系列裝置

QEC系列設備部分為ICOP的QEC系列從設備提供專用功能，使用戶能夠以更用戶友好和簡潔的方式進行編寫程式碼。

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 從站訊息

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

附錄

A.1 錯誤代碼

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

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

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

A.3 Error Callback Code

Error Callback Code 清單：

A.4 Event Callback Code

Event Callback Code 清單：

A.5 SDO Abort Code

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

A.6 資料類型

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

A.7 EtherCAT Network Information

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

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

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

EtherCATConfig : Config : Slave : 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 : Slave : Mailbox

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

EtherCATConfig : Config : Slave : 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 slave in EthercatMaster::begin().

EtherCATConfig : Config : Slave : ProcessData

• 元件
  • Recv : BitLength
  • Send : BitLength
• 目的
  EtherCAT 從站的 output process data 和input process data 的位元長度會提供給韌體進行相關設定。

EtherCATConfig : Config : Slave : ProcessData : Sm

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

EtherCATConfig : Config : Slave : DC

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