Optional Features of the EtherCAT Library

In order to provide a library that is resource effective many features are optional and scalable. The options are activated by defining macros. These macros are generated by the Industrial Communication Creator and written to the file ecat_conf.h.

Macro	Description

Macro	Description
EC_CONFIG_16BIT_CPU	enable support for DSPs where RAM is accessed in 16 bit units
EC_CONFIG_ACK_BY_WRITE	acknowledge ESC events by writing registers (for ESC IP Cores)
EC_CONFIG_BIG_ENDIAN	use endian conversion for Big Endian devices
EC_CONFIG_BOOTSTRAP	support ESM state Bootstrap
EC_CONFIG_BSP	redirect ESC access to BSP functions
EC_CONFIG_COMPATIBILITY_MODE	support legacy API of older stack versions
EC_CONFIG_DC	support DC synchronization via Sync0 interrupt
EC_CONFIG_DC_REQUIRED	enforce DC synchronization
EC_CONFIG_DEBUG_NONBLOCK	non-blocking printing of debug messages
EC_CONFIG_DEVICE_IDENTIFICATION	support Explicit Device Identification
EC_CONFIG_DYN_CFG	support dynamic configuration of library during runtime
EC_CONFIG_DYNAMIC_OD	enable Dynamic Object Dictionary
EC_CONFIG_EC_DEBUG	activate debug messages
EC_CONFIG_EC_DEBUG_MBOX	print content of received Mailbox
EC_CONFIG_EEPROM_EMULATION	enable support for EEPROM Emulation
EC_CONFIG_EEPROM_PDI_ACCESS	enable support for PDI access for EEPROM
EC_CONFIG_EMERGENCY	enable CoE Emergency Service
EC_CONFIG_EMERGENCY_QUEUESIZE	set Emergency message queue size
EC_CONFIG_EOE	enable EoE protocol handler
EC_CONFIG_FOE	enable FoE protocol handler
EC_CONFIG_LARGE_TIMER	enable 64 bit timer
EC_CONFIG_LED_EMULATION	enable emulation of RUN and ERR LED (if LEDs are not connected to the ESC)
EC_CONFIG_LIMITS_CHECK	check limits before writing object
EC_CONFIG_MBX_RD_TIMEOUT	timeout in ms for the Read Mailbox (time for Master to read the mailbox)
EC_CONFIG_NMT_SPLIT	support delaying ESM state change requests
EC_CONFIG_NO_LOCAL_OD	do not use a precompiled object dictionary (use dynamic Object Dictionary only)
EC_CONFIG_PDI_INTERRUPT	handle process data in interrupt
EC_CONFIG_PDO_BYPASS_BUF_LEN	length of PDO bypass buffer
EC_CONFIG_PDO_CONS_MAP_CNT	size of RxPDO mapping table
EC_CONFIG_PDO_INPUT_BYPASS	do not map input objects to process data, get data directly from buffer
EC_CONFIG_PDO_OUTPUT_BYPASS	do not map process data to output objects, put data directly into buffer
EC_CONFIG_PDO_PROD_MAP_CNT	size of TxPDO mapping table
EC_CONFIG_PDO_RAM_BUF_SIZE	size of PDO RAM buffer (used to read/write PDO in one go instead of reading/writing each single mapping entry)
EC_CONFIG_SDO_INFO	support SDO Info Service
EC_CONFIG_SDO_SEG_BUF_LEN	set Segmented SDO Buffer size
EC_CONFIG_SEGMENTED_SDO	support Segmented SDO Transfer
EC_CONFIG_SPI	redirect ESC access to SPI functions
EC_CONFIG_SPLIT_INDICATION	enable the delay of SDO Read/Write requests
EC_CONFIG_SYNC0_MAPPED_TO_PDI_INTR	map Sync0 interrupt to PDI interrupt (only one IRQ line for process data and DC)
EC_CONFIG_TIMER_INC	timer increment in 1/10 ms, added each tick (must be bigger than or equal 10)
EC_CONFIG_VALUE_CHECK_FUNCTION	checking of a new object value before write by application
EC_CONFIG_VIRTUAL_OBJECTS	enable Virtual Objects (deprecated)
EC_CONFIG_MDP	enable Modular Device Profile

Table: EtherCAT Library Options

NMT Split

This option is enabled by defining EC_CONFIG_NMT_SPLIT. If it is active the function ec_applNewEsmStateReqInd() is called before a new ESM state is entered. This way an application can prepare for a new state. Additionally it can also delay the response and trigger the response at a later point by calling
ec_esmFinishTransition().

If this option is not used the application is only informed after a new ESM state was entered (via ec_applNewEsmStateInd()).

SDO Split

This option is enabled by defining EC_CONFIG_SPLIT_INDICATION. It enables the application to delay a SDO Read/Write request by returning EC_BUSY in ec_applSdoRdInd() or ec_applSdoWrInd(). This can be used if the object belongs to an independent hardware that is connected to the EtherCAT slave by other communication means. In that case the request can be forwarded to the actual target and after receiving a response the application can update the corresponding object. Now that the object is up to date the processing of the SDO Request can be continued by calling ec_sdoRdIndFinish() or ec_sdoWrIndFinish().

CoE Emergency Service

This option is enabled by defining EC_CONFIG_EMERGENCY. The application can send emergency messages to inform the master about a local error this can be done by calling ec_emcyReqWrite() This function needs an error code and error data as an argument. The messages can be queued.

The queue size is set by the macro EC_CONFIG_EMERGENCY_QUEUESIZE. Please refer to the EtherCAT specification ETG1000.6 for applicable error codes.

PDO Bypass

Normally Output process data is mapped to the objects in the object dictionary and input process data is mapped from the objects. This is achieved with by using the PDO Mapping objects and PDO Assignment Objects.
However it is possible to bypass the mapping and to directly call some application defined functions for handling the process data as byte streams. For output data the bypass function is called and the application must copy the data to its own puffer for later processing.
For input data the bypass function is called and the application must copy its data into the buffer provided by the bypass function. The actual names of the bypass functions can be configured in the
Industrial Communication Creator.

Compatibility Mode

If the macro EC_CONFIG_COMPATIBILITY_MODE is defined the legacy API of Library version 1.6.x can be used. However the old API for Dynamic Objects is not available anymore. It was not suitable to create entries that conform to the standards.

Dynamic Configuration

If the macro EC_CONFIG_DYN_CFG is set some configurations of the EtherCAT Library can be set during start up phase before ec_init() is called. This way a compiled library can be configured for different use cases.

LED emulation

This feature enables the EtherCAT Library to emulate the RUN and ERR LED of the ESC. This feature is enabled by setting EC_CONFIG_LED_EMULATION. The application has to periodically check pEcat->led.bLedRun and pEcat->led.bLedError. These variables indicate the state of the LEDs.

Running the EtherCAT Library without a precompiled object dictionary

In order to disable the local object dictionary the macro EC_CONFIG_NO_LOCAL_OD must be set. Now only the dynamic Object Dictionary is available.

Replacing Virtual Objects

Virtual Objects were used to implement objects purely in the application. The application was responsible to also manage the meta data of these objects. Alternatively the application can read or write the object's value within the functions ec_applSdoWrInd() and ec_applSdoRdInd(). This way the application can fully control the object's value and does not have to manage the object's meta data.

Modular Device Profile

The Modular Device Profile is used to describe slots and modules pluggable in these. In the stack implementation only one slot, but any number of modules can be supported. This feature is enabled by setting EC_CONFIG_MDP. This feature is necessary to implement FSoE using an external FSoE stack.