EtherCAT Library API User Manual

2024.08.15, Version 2.2r1.

You can download the EtherCAT Library API User Manual file ここ.

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/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 ユーザーマニュアルを参照してください。 86EVA User Manual.

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++ アプリケーション・インターフェイスを提供します：
    • 初期化インターフェイス
    • コンフィギュレーションインターフェイス
    • プロセス・データ (PDO)・アクセス・インターフェイス
    • EtherCATを介したCANアプリケーション・プロトコル（CoE）・アクセス・インターフェイス
    • EtherCATを介したファイル（FoE）・アクセス・インターフェイス
    • SubDevice Information Interface (SII) access interface.
    • 同期クロック (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アプリケーション
  • ユーザーのHMIアプリケーション
  • ユーザーのイーサネットアプリケーション
  • など。
• スレーブシステム
  • 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 、 イーサネットドライバからすべての循環フレームを受信し、入力PDOデータをDPRAMにコピーします。

ユーザー・アプリケーション・ステージに到達すると 、 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 、 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. 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: サポートされていることに相当します。

1.3 機能パック

1.3.1 ケーブルの冗長性

EtherCATケーブルの冗長性とは、ケーブル障害が発生した場合でも継続的に信頼性の高い通信を維持するEtherCAT通信システムの機能を指します。ケーブル冗長性では、両方向で動作するリングトポロジが採用されています。1つのケーブルに障害が発生するか、切断されても、別のケーブルパスが機能し通信が中断されません。ケーブル冗長性により、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μｓに設定されていると仮定します。
• 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.
• プライマリ・ポートとセカンダリ・ポートは、すべてのサイクルで同時にプロセス・データ・フレームを送信します。

更に詳しいケーブル冗長性は以下WEBをご参照下さい。 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.

詳細は以下のWEBをご参照ください。 EtherCAT MDevice Benchmark for more details.

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には3つの同期出力ピンがあります。 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 には 3つの同期モードがあります：

• Free run(フリーラン)
• SM同期
• DC同期

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

1.5.2 SM同期

IRQピンは、ESCが循環フレームを受信するとSMイベントを生成し、このイベントは µC 内のローカルアプリケーションの実行をトリガします。下の図に示すように、循環フレームは送信時にマスタと同じジッタでスレーブに受信されます。ジッタがゼロであると仮定しても、有限のハードウェア伝搬遅延により、最後のスレーブは最初のスレーブよりも遅く循環フレームを受信します。 Propagation Delay the last SubDevices will receive the cyclic frames later with respect to the first ones.

伝播遅延により、スレーブ間の SMイベントのタイミングにオフセットが生じ、SM同期の制度がマイクロ秒レベルになります。

各スレーブが SyncManagerパラメータオブジェクト (0x1C32.3/0x1C33.3) のシフト時間をサポートしている場合は、すべてのスレーブの出力有効と入力ラッチをお互いに近づくように調整することができます。ただし、伝播遅延を計算できないため、調整は非常に困難です。

1.5.3 DC同期

SYNC0またはSYNC1 ピンは、ESCのDC関連レジスタのコンフィギュレーションに基づいて SYNCイベントを周期的に生成し、このイベントにより µC 内のローカル・アプリケーションの実行をトリガします。下の図に示すように、ジッタと伝播遅延は依然として存在し、循環フレームを受信した後に SMイベントがトリガされます。ただし、このDC同期方式では、SYNC0イベントは周期的にトリガされるため、ジッタや伝播遅延の影響を受けません。

SYNC0イベントはDCユニットによってトリガされるため、スレーブ間のすべてのSYNC0イベントには、ほとんどオフセットがなく、すべてのスレーブのシステム時間を同期するためのAPRW/FPRWコマンドの定期的な送信により、精度はナノ秒レベルになります。

スレーブがSyncManagerパラメータ・オブジェクト (0x1C32.3/0x1C33.3) のシフト時間をサポートしている場合、これらのスレーブの出力有効タイミングと入力ラッチ ・タイミングを同じ時間点に調整することができます。

ただし、図に示すグローバル・シフト時間の選択は重要ですが、次の条件を満たす必要があります :

• After the cyclic frames have been received by all SubDevices.
• 次のサイクルの循環フレームを送信する前
• さまざまなDC同期方式に応じて、 DC同期 出力の準備を実行した後に選択する必要がある場合があります Prepare Outputs:
  • Trigger µC to execute Prepare Outputs SMイベントが発生したときに、 µCをトリガして出力準備を実行します
  • Trigger µC to execute Output Valid SYNC イベントが発生したときに、 µCをトリガして出力有効を実行します

修正されたグローバル・シフト時間は一意ではありません。サイクル時間の全間隔内で選択できます。さまざまな DC同期方式の詳細については、ETG.1020 EtherCATプロトコル拡張機能を参照してください。

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.

これらのクラスは、次の3つの部分に分けられます：

• EtherCAT Mデバイス
  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デバイス
  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 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.

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.
この同期には 2つの方法があります：

• マスタ・シフト・モード - ECAT_MASTER_SHIFT
  
  • The MDevice system time is synchronized to the reference clock.
  • All DC SubDevices are synchronized to the reference clock.
• バス・シフト・モード - 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.
In 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 error interrupt will be triggered.

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

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 コールバック関数

このライブラリは、次の 3 種類のコールバックを提供します:

• (循環コールバック、エラーコールバック、イベントコールバックなど)
  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.
  エラー・コールバックでサポートされているエラー・コードは次のとおりです：

• イベント・コールバック(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.
  イベント・コールバックでサポートされているイベント・コードは次のとおりです：

• 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 EtherCATデバイス

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の間には、 EthercatMasterに依存する_EthercatDevice_CommonDriverにより、関連性があります。
• 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の間には、 EthercatMasterに依存する_EthercatDevice_CommonDriverにより、関連性があります。
• 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)関数

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

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.

ESCは、ローカルアプリケーションをEtherCATシステム時間に同期させるためのSyncSignalを生成できます。SyncSignalは、直接 (たとえば、割り込みとして) 使用することも、デジタル出力の更新/デジタル入力のサンプリングに使用することもできます。さらに、LatchSignalに EtherCATシステム時間を基準としたタイム・スタンプを付けることができます。

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

SYNC1サイクル時間が SYNC0サイクル時間よりも長い場合、次のように生成されます： 循環オペレーションの開始時間に達すると、SYNC0パルスが生成されます。SYNC1パルスは、SYNC0パルスから SYNC1サイクル時間の遅延後に生成されます。次のSYNC1パルスは、次の SYNC0パルスが生成され、そしてSYNC1サイクル時間が経過したときに生成されます。
次の図に、いくつかのコンフィギュレーション例を示します：

詳細な情報については、 ESC Hardware Data Sheet Section I.を参照してください。

• setDc()

プロセス・データ・オブジェクト(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.

総体的に、プロセスデータは、EtherCATテクノロジの重要な部分であり、ロボット制御、CNC制御、オートメーション制御、その他の分野のリアルタイム・アプリケーションに適しています。

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

CANopen over EtherCAT (CoE) 関数

CANopenは、コントローラ・エリア・ネットワーク (CAN) バスに基づく高度な通信プロトコルで、産業用アプリケーションの制御システムとデバイス間の通信に一般的に使用されます。 これにはデバイス間のデータ交換、構成、制御を容易にするために、一連の通信オブジェクト、データ型、およびネットワーク管理機能を定義します。

CANopenプロトコルには次の側面が含まれます：

• オブジェクト・ディクショナリ
  デバイス間で交換されるすべてのデータ・オブジェクトと媒介変数を定義します。オブジェクト・ディクショナリには、変数、媒介変数、イベント、関数などの様々なタイプのオブジェクトが含まれます。
• PDO (プロセス・データ・オブジェクト)
  リアルタイムのデータ転送に使用されます。 PDOを使用すると、デバイスは、固定された、またはイベント・トリガの方法で相互にデータを転送できるようになり、リアルタイム制御とデータ交換が可能になります。
• SDO (サービス・データ・オブジェクト)
  デバイスの変数の設定と管理に使用されます。 SDOは、読み取り、書き込み、変数設定の機能を提供し、デバイスが設定情報を動的に交換できるようにします。

CoE （CAN application over EtherCAT ）は、 EtherCATネットワークに基づくCANopenプロトコルです。これにより、 EtherCATネットワーク上でCANopenプロトコルを使用した通信が可能になります。オブジェクト・ディクショナリには、変数、アプリケーションデータ、およびプロセス・データ・インターフェイスとアプリケーションデータ間のマッピング情報 (PDOマッピング) が含まれます。そのエントリには、サービス・データ・オブジェクト (SDO) を介してアクセスできます。 SDOサービスは、主に2種類のコマンドで構成されています。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

初期化関数

EthercatDevice_Genericクラスの初期化に関連した関数。

• attach()
• detach()

2.3 QECシリーズ・デバイス

. 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デバイス部分の間の主なクラス関係は関連付けされており、QECシリーズ・デバイス部分はEtherCATデバイス部分に依存しています。以下の図に示すように、_ EthercatDevice_DmpCommonDriverと_ EthercatDevice_CommonDriver間に関連した関係があります。

クラス：

• _EthercatDevice_DmpCommonDriveから継承します。
• 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 循環コールバック

#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 エラーリスト

ほとんどの関数では、返される値が0未満の場合、エラーであることを示し、その値はエラー・コードを表します。エラー・コードがある場合は、エラーの原因と修正処置を下記で確認できます。

A.2 エラーの説明と修正処置

エラーコードの詳細と修正処置

A.3 エラー・コールバック・コード

エラー・コールバック・コードのリスト：

A.4 イベント・コールバック・コード

イベント・コールバック・コードのリスト:

A.5 SDOアボート・コード

ETG.1000.6に定義されたCoE SDOアボート・コード：

Data Typeを参照ください

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
• 属性
  • 識別 : 値
• 目的
  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.