本文翻译了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.