EtherCAT Library

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. If the EtherCAT Library runs on GOAL a different API is available that must be used instead. It is described in a differnt chapter.

Open

Figure: Directory layout of the EtherCAT library

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.

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:

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:

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:

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.

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.

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.

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.

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.

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.

Table: CoE Indication function

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.

Table: EoE API

Table: EOE indication functions

FoE API

This module provides indication functions that must be implemented by the application.

Table: FOE indication functions

EtherCAT State machine

These functions inform the application about a change in the EtherCAT state machine.

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.

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.

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

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.

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.

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

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.

Table: MII Management API