...
The EtherCAT Library is written in ANSI-C. It is strictly modularized.
The application modules and hardware modules are separated from the actual
EtherCAT modules. Thus the library is easily portable to new hardwares. It runs
both on bare metal and operating systems.
Like every EtherCAT slave the library requires an ESC, either as an external
ASIC, a FPGA IP core or as an internal module.
The EtherCAT library is able to run several instances. An instance is a variable
of the type EC_INSTANCE_T. Every API function requires a reference to an
instance. The instance can either by a static variable or a dynamically
allocated variable. In the later case the EtherCAT library only uses RAM if it
is needed. Thus the library is suitable for multiprotocol devices.
The EtherCAT Library is compatible to GOAL, port's Industrial Communication Framework. If the EtherCAT Library runs on GOAL a different API is available that must be used instead. It is described in a differnt chapter.
...
Figure: Directory layout of the EtherCAT library
...
It is recommended to keep this directory structure for your own development.
This way an update of the library can be easily applied to your software project.
The EtherCAT library requires the Industrial Communication Creator by port. This tool
is responsible for creating the configuration file, the object dictionary,
the ESI file, the EEPROM image and documentations. For further information please
refer to its manuals manual.
Feature | Support |
|---|---|
Mailbox protocol | yes |
CANopen over EtherCAT | yes |
EtherCAT State machine | yes |
Bootstrap Mode | yes |
CoE Object Dictionary | yes |
CoE SDO communication | yes |
SDO Expedited transfer | yes |
SDO Normal transfer | yes |
SDO Segmented transfer | yes |
SDO Complete Access | yes |
SDO Info Service | yes |
CoE Emergency Producer | yes |
File Access over EtherCAT | yes |
Ethernet over EtherCAT | yes |
Servodrive over EtherCAT | no |
Vendor Specific over EtherCAT | no |
ADS over EtherCAT | no |
Sync Manager | 4 |
Distributes clocks | yes |
SM-Synchronization | yes |
DC-Synchronization | yes |
EEPROM access | yes |
EEPROM Emulation | yes |
Transmit PDOs | 512 |
Receive PDOs | 512 |
PDO transmission over Sync Manager | yes |
...
The library comes with several sample applications that demonstrate the
functionalities of port's EtherCAT library. These sample application require
a driver package that is suited for the hardware and port's Industrial
Communication Creator. The directory ethercat/examples/XXX/s1_xxx_xxx contains
an project file (*.ect or *.iccproj) that must be used to generate all necessary
files for the EtherCAT library.
...
This chapter gives an overview on all public functions of the EtherCAT library.
For detailed information please refer to the Reference Manual.
There are normal functions that must be called by the application to trigger
events and there are indication functions that are called by the library. These
indication functions must be implemented by the application programmer.
...
After initialization is done the function ec_loop() must be called
cyclically to execute the EtherCAT Library.
This function cyclically checks the "AL Event" register of the ESC and calls
the appropriate event handlers
...
If the macro EC_CONFIG_EC_DEBUG is defined the printing of debug messages is
activated. The application can define which levels of debug messages are
printed. The function ec_dbgLevelSet() needs an OR combination of the
following macros:
Macro | Debug level |
|---|---|
EC_DBG_NONE | do not print any messages |
EC_DBG_ERR | print error messages |
EC_DBG_WARN | print warnings |
EC_DBG_INFO | print informational messages |
EC_DBG_DBG | print debug messages |
EC_DBG_ALL | print all kinds of messages |
...
The application can add its own messages by calling one of the following
macros:
Macro | Description |
|---|---|
ec_logDbg() | print a debug message |
ec_logInfo() | print an informational message |
ec_logWarn() | print a warning |
ec_logErr() | print an error message |
...
These macros expect a formatted string and optional arguments like printf().
Each message gets a header that contains a letter representing the debug message
level, the name of the calling function and the line within the source file.
| Note |
|---|
Activation of debugging is not recommended for release versions. Since the |
...
printing messages might block the device. |
A non-blocking variant is used if EC_CONFIG_DEBUG_NONBLOCK is defined.
The messages are buffered in a ring buffer and might get lost, if the buffer is
full.
Object Dictionary access
These functions enable the application to access managed variables of the object
dictionary. Application variables can be accessed directly since their variable
name is known to all modules.
...
Virtual Objects are fully controlled by the application. They can be used if an
object cannot be simply mapped to a variable, e.g. if it represents a hardware
register or an ADC value.
The EtherCAT Object Dictionary provides Application Variables that can be used
instead. In combination with the SDO Read and Write indication functions they
also allow the implementation of objects that must be updated by the application
for each access.
Virtual Objects are added by implementing the following functions in the
application.
Function | Description |
|---|---|
ec_getVirtualObjAddr() | get a pointer to a virtual object |
ec_getVirtualObjDesc() | get properties of an virtual object (data type,…) |
ec_getVirtualObjSubIdxDesc() | get properties of an virtual sub-index (data type,…) |
ec_getVirtualObjAttr() | get attributes of virtual object |
ec_getVirtualObjName() | get name of virtual object |
ec_getVirtualObjEntryName() | get name of virtual object entry (sub-index) |
ec_checkVirtualObjLimits() | check, if new value fits into limits |
ec_getVirtualObjList() | get a list of specified objects |
ec_getVirtualObjectLimits() | get maximum and minimum limits of virtual object |
ec_getVirtualObjectDefVal() | get default value for a virtual object |
...
These functions allow the configuration of the EtherCAT library at runtime
during initialization. These functions are available if the macro
EC_CONFIG_DYN_CFG is defined. In order to take effect they must be called
before ec_init() is called.
...
The Dynamic Object Dictionary is created at program startup. The following
functions allocate the required memory. Afterwards it behaves like a normal
object dictionary and can be accessed with the normal OD Access API.
...
The CoE module provides indication functions to connect the application to the
objects and the process data. There are also some API functions that trigger the
CoE and SDO module.
Function | Description |
|---|---|
ec_applSdoRdInd() | indicate SDO Read access to an object |
ec_applSdoWrInd() | indicate SDo Write access to an object |
ec_applSdoTestValue() | check an object’s new data before it is written |
ec_applPdoInd() | indicate reception of output process data (objects updated) |
ec_applSyncInd() | update input process data objects before they are mapped to Sync Manager |
...
These functions enable the reception and transmission of Ethernet frames. The
application can either process the frames directly or pass them to a TCP/IP
stack.
Function | Description |
|---|---|
ec_eoeTx() | send an Ethernet frame via EoE |
ec_eoeTxQueueAvailable() | check if an EoE send queue is available |
...
This module provides indication functions that must be implemented by the
application.
Function | Description |
|---|---|
ec_applFoeReadInd() | open a file for reading |
ec_applFoeWriteInd() | open a file for writing |
ec_applFoeAckInd() | get fragment of read file |
ec_applFoeDataInd() | write fragment of write file |
ec_applFoeErrorInd() | error occurred, close file |
...
These functions inform the application about a change in the EtherCAT state
machine.
Function | Description |
|---|---|
ec_esmStateGet() | get current ESM state |
ec_applNewEsmStateInd() | indicate new ESM state and possible error |
ec_applNewEsmStateReqInd() | indicate an ESM state change request |
ec_esmFinishTransition() | accept or reject a delayed ESM state change request |
ec_applGetDeviceIdInd() | get the Explicit Device ID (during state change) |
...
It is possible to access the EEPROM via ESC registers. However the access must
be enabled by the master. Thus these functions cannot be used to change the
EEPROM content before the slave goes online.
...
Some ESCs, usually IP cores, do not have an EEPROM. They use EEPROM Emulation
instead. This means that the EEPROM commands are not executed by the ESC. They
are passed to the EtherCAT library instead. The library automatically handles
the commands.
The application must provide a virtual EEPROM buffer in RAM that can be used by
the EtherCAT library. This buffer must be saved in non-volatile memory. This way
the virtual EEPROM behaves like a real one.
...
The EtherCAT library uses a software timer that can also be used by the
application. The function ec_tmrAdd() adds an event to the software timer.
If it expires the callback function is called. The event can be issued cyclically
by using the timer type "EC_TIMER_TYPE_CYCLIC".
...
If synchronization via Distributed Clocks is activated, the following functions
are called by the library and must be implemented by the application programmer.
...
The controls Ethernet Phys. However it allows to read and write Phy registers
via ESC registers. The EtherCAT Library provides an APO to simply read and write
Phy registers.
Function | Description |
|---|---|
ec_phyRead() | read a Phy register |
ec_phyWrite() | write a Phy register |
...