This chapter explains the configuration and usage of port's EtherCAT Library.
General Concept
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.
Figure: Directory layout of the EtherCAT library
Directory | Description |
|---|---|
ethercat | EtherCAT core functionality |
drivers | hardware specific functions (driver package) |
examples | sample application |
Table: 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 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 |
Table: Features of the EtherCAT library
Sample Applications
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.
Public API of 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.
Setting up and running the library
In order to initialize the library the following functions must be called:
Function | Description |
|---|---|
ec_initDevice() | initialize the hardware (GPIO, interface setup) |
ec_initTimer() | initialize the timer used by the library |
ec_init() | initialize the EtherCAT library |
Table: Setup functions
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
Process Data Watchdog expiration
EtherCAT state machine
mailbox protocol handler (and upper layer handlers)
process data handlers (if PDI interrupt is disabled)
EEPROM emulation commands
Data Link Layer change
Debugging
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 |
Table: Debug message levels
By default error messages, warnings and informational messages are printed.
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 |
Table: logging macros
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.
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.
Function | Description |
|---|---|
ec_odObjAttrGet() | get object attributes in current state |
ec_odObjAddrGet() | get a pointer to the object value |
ec_odObjEntryGet() | get the object value |
ec_odObjEntrySet() | set the object value |
ec_odObjDefValGet() | get default value of numeric object |
ec_odObjLimitsGet() | get minimum and maximum limit of numeric object |
ec_odObjNameGet() | get name of object |
ec_odEntryNameGet() | get name of object entry (sub-index) |
Table: OD Access API
Virtual Object Dictionary
The Virtual Object Dictionary is deprecated!
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 |
Table: Virtual Object API
Dynamic Library Configuration
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.
Function | Description |
|---|---|
ec_cfgEmergencyOn() | enable CoE EMergency Service |
ec_cfgNumEmergencyQueueSlots() | set size of CoE EMergency message queue |
ec_cfgFoeOn() | enable FoE service |
ec_cfgExplDevIdOn() | enable Explicit Device Identification |
ec_cfgBootstrapOn() | enable ESM state BOOTSTRAP |
ec_cfgDcRequiredOn() | make DC synchronization mandatory |
ec_cfgSizePdoStreamBuf() | set size of PDO bytestream buffer |
Table: Dynamic Configuration API
Dynamic Object Dictionary
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.
Function | Description |
|---|---|
ec_dynOdAddObject() | add a dynamic object as a managed variable or application variable |
ec_dynOdAddSubIndex | add a Sub-Index to an dynamic object |
ec_dynOdAddObjectName() | add a name to a dynamic object |
ec_dynOdAddSubIndexName() | add a name to a Sub-Index of a dynamic object |
ec_dynOdFinish() | indicate that object creation has finished |
Table: Dynamic Object API
CoE 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 |
Table: CoE Indication function
Function | Description |
|---|---|
ec_emcyReqWrite() | send a CoE emergency message |
ec_sdoRdIndFinish() | finish a delayed SDO Read access |
ec_sdoWrIndFinish() | finish a delayed SDO Write access |
Table: CoE API
EoE API
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 |
Table: EoE API
Function | Description |
|---|---|
ec_applEoeInitInd() | initialize EoE application |
ec_applEoeReceiveInd() | process/enqueue received Ethernet frame |
ec_applEoeTransmitInd() | EoE transmission is possible |
ec_applEoeIpParameterSet() | set IP parameter of TCP/IP stack |
ec_applEoeIpParameterGet() | get IP parameter of TCP/IP stack |
Table: EOE indication functions
FoE API
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 |
Table: FOE indication functions
EtherCAT State machine
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) |
Table: ESM API
EEPROM Access
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.
Function | Description |
|---|---|
ec_eepromReadSizeGet() | Get the minimum data size of one read access |
ec_eepromPdiRead() | read data from EEPROM |
ec_eepromPdiWrite() | write data to EEPROM |
Table: EEPROM Access API
EEPROM Emulation
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.
Function | Description |
|---|---|
ec_applEepromInitInd() | initialize EEPROM in RAM and pass it to library |
ec_applEepromCmdInd() | indicate executed command (e.g. save new data) |
Table: EEPROM Emulation API
Timer API
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".
Function | Description |
|---|---|
ec_tmrAdd() | add a timer event |
ec_tmrRemove() | remove a timer event |
ec_tmrIsActive() | check if timer is still active |
Table: Timer API
Data Layer indication functions
These functions are called by the EtherCAT library if a data layer event happened.
The application programmer must implement these functions.
Function | Description |
|---|---|
ec_applSmWatchdogInd() | process data reception timeout (Hardware Watchdog) |
ec_applNewDlStateInd() | port state change |
ec_applSmSyncFailInd() | process data reception timeout (Software Watchdog) |
Table: Data Link Event API
Distributed Clock API
If synchronization via Distributed Clocks is activated, the following functions are called by the library and must be implemented by the application programmer.
Function | Description |
|---|---|
ec_applNewDcSettingsInd() | check the synchronization settings, e.g. cycle time |
ec_applDcFailInd() | indicate loss of Sync0 interrupts |
Table: DC API
GPIO API
The ESC usually provides some GPIOs that can be accessed via ESC registers.
The functions listed below provide access to the GPIOs
Function | Description |
|---|---|
ec_gpoDataWrite() | set the ESC outputs |
ec_gpoDataRead() | get the ESC output states |
Table: GPIO API
MII Management (Phy Access)
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 |
Table: MII Management API