ECS V5 - CoE Custom OD example

About

This example illustrates the process of creating a custom object dictionary for an EtherCAT SubDevice. The object dictionary plays a vital role in EtherCAT communication by outlining the device's capabilities, parameters, and data structures. A standout feature of a customizable object dictionary is its ability to be tailored specifically to meet the unique requirements of the EtherCAT SubDevice.

Custom objects can encompass various data types, such as integers, booleans, floats, and strings, to accurately represent different forms of data. Furthermore, access levels—whether read-only, write-only, or read/write—can be established to regulate how other devices interact with the object dictionary.

Prerequisites

The actual distribution of the examples can be found here: EtherCAT Slave Examples.

The cifXApplicationDemo project with corresponding ECS_CustomOD example can be found in the netXStudio:

The active target corresponding to the netX90 use case can be selected as shown on the picture below:

In this example, the configuration and usage of custom object dictionary are demonstrated through the following basic steps:

Activation of CustomOD support
Create the Custom Object Dictionary
Extending ESI file

To conclude, we will demonstrate how to assess the behavior using TwinCAT and Conformance Test Tool.

Activation of CustomOD support

The support of CustomOD shall be activated in the configuration of EtherCAT SubDevice. The configuration of the EtherCAT SubDevice stack is carried out through a configuration packet that is sent from the application to the stack.

The usage of the EtherCAT SubDevice configuration packet is demonstrated in the ECS V5 - Simple Configuration Example.

The ECS configuration packet can be found in the file AppECS_DemoApplicationFuction.c.

In the CustomOD example, the definition ECAT_SET_CONFIG_COE is utilized to activate the evaluation of CoE configuration.

ptConfigReq->tData.tBasicCfg.ulComponentInitialization |= ECAT_SET_CONFIG_DEVICEINFO;
ptConfigReq->tData.tBasicCfg.ulComponentInitialization |= ECAT_SET_CONFIG_COE;

The configuration structure outlined below must be expanded to include the necessary parameters:

ECAT_SET_CONFIG_COE_T         *ptCoECfg     = &ptConfigReq->tData.tComponentsCfg.tCoECfg;
  ptConfigReq->tData.tBasicCfg.ulComponentInitialization |= ECAT_SET_CONFIG_COE;
  ptCoECfg->bCoeFlags = ECAT_SET_CONFIG_COEFLAGS_USE_CUSTOM_OD;
  ptCoECfg->bCoeDetails = ECAT_SET_CONFIG_COEDETAILS_ENABLE_SDO
                          | ECAT_SET_CONFIG_COEDETAILS_ENABLE_SDOINFO
                          | ECAT_SET_CONFIG_COEDETAILS_ENABLE_PDOASSIGN
                          | ECAT_SET_CONFIG_COEDETAILS_ENABLE_SDOCOMPLETEACCESS;
   ptCoECfg->ulOdIndicationTimeout = 1000;
   ptCoECfg->ulDeviceType          = 0;

The activation of the Custom OD is provided by ECAT_SET_CONFIG_COEFLAGS_USE_CUSTOM_OD.

As a result, the EtherCAT SubDevice stack will manage handling of the Object 0x1000 for the Device Type and Object 0x1018 for VendorID, Product code, Revision Number, and SerialNumber. The application is responsible for creating all other objects.

Create the Custom Object Dictionary

The file AppECS_DemoObjectDictionary.h provides the structures required for declaration of objects and subobjects. The full list of objects can be found in the file Includes/AppECS_DemoApplication_Config.h where OD_CUSTOM_OBJECT_T s_atCustomObjects[] holds the object table with the following indexes:

0x1600 -> RxPDO
0x1A00 -> TxPDO
0x1C00 -> Sync Manager Communication Type
0x1C12 -> Sync Manager 1 PDO Assignment
0x1C13 -> Sync Manager 1 PDO Assignment
0x2000 -> Outputs
0x3000 -> Inputs
0x4000 -> Object with enum type

Each object is derfined by following structure for objects, e.g. :

and subobjects:

The file AppECS_DemoApplication_OD_Handler.c provides the function

uint32_t AppECSCustomOd_CreateObjects( APP_ECS_CHANNEL_HANDLER_RSC_T *ptEcsRsc )

which implements the handling in order to create the defined objects/subobjects and register these on EtherCAT stack.

This example additionally provides the object with enumerated datatype:

This datatype requires an additional handling, so it has to be registered at the EtherCAT SubDevice stack with the help of the function AppECS_CreateDatatypeReq() in the file AppECS_DemoApplication_OD_Handler.c

The creation of the object dictionary is now considered complete.

Extending ESI file

The ESI file serves as a description of the object dictionary for the SubDevice, making it a valuable resource for offline engineering tasks. The example provide a basic corresponding ESI file (see DeviceDescription/Hilscher ECS V5 Host Example.xml).

The ESI file will be enhanced by incorporating descriptions of all objects in the designated sections, as illustrated below.

For datatypes :

For objects:

and for subobject

Checking the Custom OD with TwinCAT

After the custom object dictionary is created as explaned above, the result can be checked with the TwinCAT application. The “CoE Online” view of our SubDevice provides the list of the CoE objects consisting the default objects 0x1000 and 0x1018 as well as other custom objects created by the example:

The SubDevice CoE objects can be updated using the “Update List” button. The values will align with those specified in the example application.

Running the Conformance Test Tool (CTT)

To ensure that the slave can effectively communicate with an EtherCAT Main Device and accurately exchange data, we recommend running the Conformance Test Tool. The figure below provides a result of test tool run.

One error “TF-1300 EtherCAT Slave Information” relates to the fact, that the example application is using a “secondary vendor id”. Please ensure that the Vendor ID value is changed to your Vendor ID.

Conclusion

The implementation of Object Dictionary (OD) offers significant flexibility, allowing you to tailor the object dictionary to meet your unique application requirements. Additionally, it enhances efficiency by optimizing data transmission through PDOs and ensures compatibility with various EtherCAT devices. By adhering to this example, you can develop custom object dictionaries for your EtherCAT SubDevices and seamlessly integrate them into EtherCAT networks.