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