EtherCAT入門教程 ---- Kithara RTS

本文翻譯了kithara官方文檔，也加入了一些理解，暫時做得還不夠完美，后續補充修正。2014.06.06

EtherCAT

This tutorial describes the following topics using the EtherCAT API

本向導描述了使用EtherCAT API的功能說明

• Creating a EtherCAT master assigned to a network adapter

• Creating slaves assigned to the master

• Real-time process data exchange with datasets and assigned PDOs

• Real-time up/download of service data objects (SDO)

• Real-time mailbox communication

• State control for master and slaves

• Getting information for master, slaves, data objects, variable objects

中文說明

• 創建EtherCAT主站使用的網卡

• 創建連接主站的從站

• 使用dataset和PDO進行實時過程數據交互

Master related functions----主站相關功能

Opening a network adapter----打開網卡

Before we can create a master, it is necessary to open a network adapter first. This is done by using the function KS_openAdapter. As parameters an adapter name, a receive and a send pool size is needed. The adapter name is usually the name of a network device. The function KS_enumDevices enumerates all devices. To only get network devices the parameter deviceType is set to “NET”.

在創建主站之前，必須打開網卡。使用KS_openAdapter函數打開網卡，需要的參數包括網卡名稱，收發數據池大小等。可以使用KS_enumDevices枚舉設備獲取網卡名稱，使用該函數時參數deviceType應該設置為“NET”

Mind that the function KS_openAdapter must be called with the flag KSF_REALTIME_EXEC.

使用KS_openAdapter時需要將標志位flag設置為KSF_REALTIME_EXEC，表明網卡運行在實時模式。

1. ksError = KS_enumDevices(  //枚舉設備
2. "NET",                  // Searches for network devices
3.             deviceIndex,            // Count, starting with zero
4.             pDeviceName,            // Buffer for device name
5.             0);                     // Flags
6. if (ksError) 
7. // ...
9. ksError = KS_openAdapter(  //打開網卡
10.             &hAdapter,              // Adapter handle pointer
11.             pDeviceName,            // Hardware ID of the Controller
12.             256,                    // Receive Pool Length
13.             256,                    // Send Pool Length
14.             KSF_REALTIME_EXEC);     // Flags
15. if (ksError) 
16. // ...

For further details see How to look up for devices.

Creating a master----創建主站

To create a master the function KS_createEcatMaster can be used. As parameters a network adapter handle and a path to device description XML files are needed. A name of a topology file (*.ktp) is optional. The device description XML files can be found with a developer installation in the XML directory or can be downloaded from the slave manufacturer website. A topology file can be created with the Kithara »Master Monitor«.

使用KS_createEcatMaster創建主站，需要傳入網卡句柄參數和從站XML設備描述文件路徑，也可以加入一個拓撲文件ktp參數。設備描述文件可以從設備制造商的網站上獲取。拓撲文件可以用Master Monitor生成。

The Kithara »Master Monitor« is a tool for e.g. configuration, diagnostics and saving XML configuration files for graphically viewing slaves, objects and variables or comparing a given topology with a target topology.

Master Monitor是一個用於配置、調試和保存xml配置文件的圖形化工具，可以查看從站、對象、變量和對比拓撲文件。

Closing a master----關閉主站

To close a master and free all its resources the function KS_closeEcatMaster must be used.

使用KS_closeEcatMaster關閉從站

State change for a master----主站的狀態切換

To query and change the master's state the functions KS_queryEcatMasterState and KS_changeEcatStatecan be used.

用KS_queryEcatMasterState查詢主站狀態。

用KS_changeEcatState改變主站狀態。

The function KS_queryEcatMasterState needs a master handle, a pointer to the structureKSEcatMasterState and flags. Be sure to initialize the structure member structSize to the actual size of the structure KSEcatMasterState before calling the function.

 

The function KS_changeEcatState needs a master handle, the requested state and flags as parameters. The state of all assigned slaves which are online is changed. Slaves are assigned using the functionKS_createEcatSlave or KS_createEcatSlaveIndirect.

 

Nearly every EtherCAT API function has special requirements regarding the state (see the APIdocumentation of the specific function). For further information about the state machine see The EtherCAT state machine.

幾乎每一個EtherCAT的API函數都需要主站在特定的狀態才能使用。

Slave related functions----從站相關函數

Enumerating all online slaves----枚舉所有在線從站

After a master was created, all online slaves can be enumerated using the function KS_enumEcatSlaves. As parameters a master handle, a enumeration index and a pointer to the structure KSEcatSlaveState are needed. Be sure to initialize the structure member structSize to the actual size of the structureKSEcatSlaveState before calling the function.

主站創建之后，則可以使用KS_enumEcatSlaves枚舉所有從站.需要的參數包括主站句柄、枚舉順序、一個KSEcatSlaveState結構體的指針。在使用前應當初始化結構體的成員變量structSize大小。

If the enumeration index is greater than the number of online slaves, the error codeKSERROR_DEVICE_NOT_FOUND is returned. Otherwise, a pointer to the structure KSEcatSlaveState is returned which contains information about the slave's state.

 

Using the function KS_enumEcatSlaves the slaves are enumerated by their absolute position.

Creating a slave----創建從站

To create a slave, one of the functions KS_createEcatSlaveIndirect or KS_createEcatSlave can be used. The function KS_createEcatSlaveIndirect makes use of the structure KSEcatSlaveState which can be obtained using the function KS_enumEcatSlaves.

The function KS_createEcatSlave needs additional parameters like slave id, position, vendor id and revision number. With the parameter slave id a relative position can be provided, too.

The parameters are unique to a slave type. This information can be found in the slave's manual, using the method above with the structure KSEcatSlaveState or can be displayed with the Kithara »Master Monitor«.

If a slave is already assigned and the function KS_createEcatSlave is called with the same vendor ID, product ID, revision number and position, an error KSERROR_DEVICE_ALREADY_USED is returned together with a slave handle to the already assigned slave.

Deleting a slave----刪除從站

A slave can be deleted using the function KS_deleteEcatSlave.

Getting information from slaves----獲取從站信息

To query information from a slave the function KS_queryEcatSlaveInfo can be used. It delivers a pointer to the structure KSEcatSlaveInfo. If information about process data objects (PDO), service data objects (SDO) or both are needed, the flags KSF_SDO and KSF_PDO can be passed to the function. The function is time consuming (up to 30 seconds) and the state PREOP or higher is needed for online slaves.

Within the structure KSEcatSlaveInfo there is an array of KSEcatDataObjInfo and within this structure there is an array of KSEcatDataVarInfo.

If using languages like C# these structured cannot be accessed. Alternatively, the functionsKS_queryEcatDataObjInfo, KS_queryEcatDataVarInfo, KS_enumEcatDataObjInfo andKS_enumEcatDataVarInfo can be used instead.

State changes for slaves----從站狀態機改變，與主站類似

To query and change the slave's state the functions KS_queryEcatSlaveState and KS_changeEcatState can be used.

查詢和改變從站狀態可以用以上兩個函數，改變狀態的函數與改變主站的相同

The function KS_queryEcatSlaveState needs a slave handle, a pointer to the structure KSEcatSlaveStateand flags. Be sure to initialize the structure member structSize to the actual size of the structureKSEcatSlaveState before calling the function.

查詢從站狀態函數，需要一個從站句柄、指向KSEcatSlaveState結構體的指針和標志位。使用前請初始化結構體內部的structSize變量。

For further information concerning the state machine see The EtherCAT state machine.

更多的信息可以查看此章節

Other operations on slaves----從站的其他操作

Using the function KS_writeEcatSlaveId it is possible to write a unique ID to any slave. The ID is written to non-volatile memory and will be persistent. Within a connected real topology the IDs must be unique. Mind that the slave must be in INIT state.

使用KS_writeEcatSlaveId函數可以給從站寫入唯一的ID。ID必須是唯一的，注意此時從站的狀態必須是INIT

Dataset related functions----Dataset相關函數

A dataset is a collection of sync managers, a sync manager can contain several PDOs (process data objects) and a PDO can be mapped to multiple SDO (service data object) variables. A sync manager is a slave internal mechanism to keep data consistent.

dataset是同步管理器的一個數據收集，可以包含多個PDO，一個PDO可以映射多個SDO。

It is necessary to create at least one data set to establish the process data exchange. Data is cyclically transferred between the master and the slaves.

建立過程數據通信至少需要一個dataset，數據是在主站和從站之間循環傳送的。

Creating and assigning a dataset----創建和分配一個dataset

To prepare the process data exchange a dataset can be created with the function KS_createEcatDataSet. As parameters a master handle is needed. Optional parameters are an application and a system pointer to access shared memory of the dataset directly. If the program was called from ring3 then the application pointer can be used and on ring0 the system pointer.

Before the process data exchange starts, a PDO should be assigned using the functionKS_assignEcatDataSet. As parameters a dataset handle, a slave handle, an index of a sync manager and a placement is needed.

在數據交互之前，應該分配PDO給sync管理器，使用KS_assignEcatDataSet。需要輸入dataset句柄，從站句柄，sync管理器序號

A slave can have several sync managers. There are readable/writeable sync managers and sync managers for the mailbox (if existing). A sync manager contains one ore more PDOs. It is possible to select a specific sync manager with the index parameter or select groups of sync managers (e.g. with KS_ECAT_SYNC_ALL,KS_ECAT_SYNC_INPUT).

一個從站可以有多個sync管理器。有可讀寫sync和郵箱式sync。一個sync擁有一個或多個PDO。通過index參數，可以選擇一個或一組特定的sync管理器

Several objects can be assigned to a dataset while no KSERROR_NOT_ENOUGH_MEMORY is returned. Per default a dataset has a size of 4 KB and can have up to 64 KB. Mind that the assigned slave must be in state PREOP. With the parameter placement an offset can be specified while assigning several objects.

一個dataset可以被分配多個對象，默認的dataset大小為4kb，最大為64kb。操作時的從站必須位於PREOP狀態。placement參數可以指定一個對象在pdo中的位置。

It is further possible to create more than one dataset. With multiple datasets each one can be updated with different frequencies or group PDOs with multiple datasets to logical units.

也可以創建多個dataset。多個dataset中，每一個dataset可以被更新不同頻率和不同組PDO更新。

Deleting a dataset----刪除dataset

To delete a dataset and free all its resources the function KS_deleteEcatDataSet must be used.

Posting and reading process data----發送和讀取pdo數據

To post and read process data the functions KS_postEcatDataSet and KS_readEcatDataSet can be used.

The process data exchanged is controlled by the user. So these functions should be placed inside of a timer callback or a dataset handler to ensure an update of the process data exchange in real-time. Both functions need a dataset handle as parameter. The function KS_postEcatDataSet has to be called before the function KS_readEcatDataSet.

過程數據交互由用戶控制。因此這些函數應該放在定時器回調函數或者dataset句柄中，以保證數據更新的實時性。

收發dataset的兩個函數都需要dataset句柄作為參數，post應該在read之前被調用（注：這是由於ecat的機制決定的）

The function KS_readEcatDataSet copies the context of an EtherCAT-frame to shared memory of the dataset. It is possible to accept incomplete datasets. This can be useful if a slave is not ready or does not answer, but data for other slaves should be received anyway.

讀取函數拷貝一個EtherCAT數據幀放入dataset的共享內存。可以接收非完成的dataset,如果有的從站沒有准備好或者應答，但是其他從站可以正常工作。

With the function KS_postEcatDataSet the current content of the dataset's shared memory is written to an EtherCAT-frame and the data exchange is started.

發送函數將dataset中的共享內存數據放入EtherCAT的一個數據幀中，然后執行數據交互。

Accessing data of a dataset----讀取dataset中的數據

Access to the variables of process data objects (PDOs) is done by direct memory access. The address of a particular variable can be retrieved using the function KS_getEcatDataObjAddress. As parameters the function need a dataset handle, a slave handle, an index of the data object and a subindex of the data object. Optional parameters are application and system pointers to the dataset's shared memory, a bit offset and a bit length.

通過直接讀取內存的方式獲取PDO中的數據。特定變量的內存地址可以用KS_getEcatDataObjAddress獲取，需要參數dataset句柄，從站句柄，數據對象序號和一個對象的子序號。可選參數是應用層和系統層指針，指向共享內存。

To get valid values for the data object's index and/or subindex the function KS_queryEcatSlaveInfo can be used. For further information see Getting information from slaves.

查詢數據對象的信息可以使用以上兩個函數。

With the optional parameters pBitOffset and pBitLength additional information about the pointer to shared memory is returned. If the data is given in bits, the correct placement can be found with bit offset and length.

State changes for datasets

If you are calling the function KS_changeEcatState and passing a dataset handle as first parameter, all slaves connected to that dataset will perform a state change.

Real-time up/download of service data objects (SDO)

For SDOs (service data objects) up/download the functions KS_readEcatDataObj and KS_postEcatDataObjcan be used. As parameters a slave handle, an object index, a variable index, a pointer to a data buffer and a size is needed. To get valid values for object and variable index the function KS_queryEcatSlaveInfo can be used (see Getting information from slaves).

 

Real-time mailbox communication----實時郵箱通信

At the moment 4 protocols are supported to access the mailbox. These are

以下4中協議支持郵箱通信機制

• CanOpen over EtherCAT (CoE),

• File over EtherCAT (FoE),

• Ethernet over EtherCAT (EoE)

• and Safety over EtherCAT (SoE).

CanOpen over EtherCAT(CoE) and Safety over EtherCAT(SoE) are supported using the functionsKS_postEcatDataObj and KS_readEcatDataObj. With the flag KSF_SDO a CoE data object is specified and with the flag KSF_IDN a SoE data object is specified. If the flag KSF_PDO is used, the data is written in the dataset memory.

對於CoE和SoE，使用postdata和readdata。標志位是KSF_SDO表示一個CoE對象，標志位是KSF_IDN表示是一個SoE對象。如果標志位是KSF_PDO，說明是操作dataset內存。

File over EtherCAT(FoE) can be used with the functions KS_uploadEcatFile and KS_downloadEcatFile.

FoE使用KS_uploadEcatFile和KS_downloadEcatFile

The protocol Ethernet over EtherCAT(EoE) can be used with the function KS_openAdapterEx.

EoE可以使用KS_openAdapterEx函數

Installing a handler----安裝處理句柄

Handlers can be installed to take advantage of event triggered evaluation. A common EtherCAT handler can be installed for a master, slave or datatset using the function KS_installEcatHandler. As parameters an object handle, an event code and a callback handle is needed.

給一個對象安裝一個用於檢測某個事件的處理程序，需要的參數包括一個兌現個、一個事件代碼、一個回調函數。

Depending on the event code several handlers can be implemented, e.g. a handler for a topology change (event code KS_TOPOLOGY_CHANGE, Hot-plugging EtherCAT slaves), an error handler (event codeKS_ETHERCAT_ERROR) or a dataset handler (event code KS_DATASET_SIGNAL).

Each handler may have its own callback context, e.g. a dataset handler uses EcatDataSetUserContext.

每一個回調函數都有自己的處理上下文。

For information on how to create a callback see create callbacks.

Error handler----檢錯句柄

There are several options for error detection and diagnosis that can be interesting using the EtherCAT master.

有多個選擇用來檢測和調試錯誤代碼。

Cyclic topology check----拓撲結構檢測

Check the topology for errors after each cycle. If a handler (KS_installEcatHandler) with the event codeKS_TOPOLOGY_CHANGE is installed, a callback with the context structure EcatTopologyUserContext is signalized.

安裝拓撲錯誤檢測句柄

Cyclic slave error check----循環從站錯誤檢測

Check for slave errors after each cycle. If a handler (KS_installEcatHandler) with the event codeKS_ETHERCAT_ERROR is installed, a callback with the context structure EcatErrorUserContext is signalized. The error code of interest provided by the context structure is KSERROR_SLAVE_ERROR. There can be additional information in lower 16 bits of the error code (see Error code table below). A cyclic slave error can occur during the cyclic check or a state transition.

每個循環周期之后檢查錯誤句柄。

Process data completion check----檢查數據包是否完整

Check if datagrams are complete. This can be achieved using the function KS_readEcatDataSet. The error code KSERROR_DATA_INCOMPLETE indicates that the datagram reception is not complete.

由讀取函數反饋dataincomplete反饋。

檢查數據包是否完整。

Sync manager / PDI watchdogs----Sync管理器和PDI WDT

A Slaves can have a watchdog. The job of a watchdog is to ensure that the process data exchange is cyclic and with an exact timing. If an error handler is installed with the event code KS_ETHERCAT_ERROR, the error code of the context EcatErrorUserContext can provide an error KSERROR_SLAVE_ERROR caused by the watchdog. If the lower 16 bits are set to 0x001B then the watchdog caused an error (see Error code tablebelow).

從站可以具有WDT，這個WDT的工作是保證過程通信數據是循環執行，沒有超時。如果安裝了錯誤檢測句柄，將會檢測錯誤。如果低16位被設置為0x001b，即超時，那么wdt會觸發一個錯誤。

Emergency request----緊急請求

Emergency messages are triggered by occurrence of a device internal error situation. The aim is to report unexpected conditions. An installed error code handler can provide the error KSERROR_EMERGENCY_REQUESTafter a cyclic check.

Error code table----錯誤代碼表

This table shows additional information in the lower 16 bits of the error code KSERROR_SLAVE_ERROR.