EtherCAT Slave  1.06.01
Configuration of the Object Dictionary

The CANopen object dictionary interfaces the protocol and the application software. It contains references for all used data types and stores all communication and application parameters.

The Object Dictionary is structured in these areas:

Index Object Dictionary Area
0x1000 – 0x1FFF CoE Communication Area (Configured by the SDK).
0x2000 – 0x5FFF Manufacturer Specific Area (Configured by the end user).
0x6000 – 0xFFFF Profile Area such as CiA402, MPD… (Configured by the end user).

0x1000 - 0x1FFF: Communication area

These objects inform about the device identity, software and hardware version, SyncManager assignment, PDO mapping configuration among other settings. These objects are created automatically by the SDK using the information provided by API functions. The index number is divided into a main index and a subindex in order to mark and arrange associated parameters. The subindex is separated by a colon ":". For instance, typically the communication area looks like this. On the right column the API call can be found.

Index Name API Function
0x1000 Device Type EC_API_SLV_setDeviceType
0x1001 Error Register EC_API_SLV_setErrorRegister
0x1008 Manufacturer Device Name EC_API_SLV_setProductName
0x1009 Hardware Version EC_API_SLV_setHwVersion
0x100A Software Version EC_API_SLV_setSwVersion
0x100B Reserved
::::::: ::::::: :::::::
0x1017 Reserved
0x1018 Identity
0x1018:01 Vendor ID EC_API_SLV_setVendorId
0x1018:02 Product Code EC_API_SLV_setProductCode
0x1018:03 Revision Number EC_API_SLV_setRevisionNumber
0x1018:04 Serial Number EC_API_SLV_setSerialNumber
0x1019 Reserved
::::::: ::::::: :::::::
0x15FF Reserved
0x1600 1st RxPDO Generated automatically based on end user PDO configuration
0x1601 2nd RxPDO Generated automatically based on end user PDO configuration
::::::: ::::::: :::::::
0x17FF 512th RxPDO Generated automatically based on end user PDO configuration
0x1800 Reserved
::::::: ::::::: :::::::
0x19FF Reserved
0x1A00 1st TxPDO Generated automatically based on end user PDO configuration
0x1A01 2nd TxPDO Generated automatically based on end user PDO configuration
::::::: ::::::: :::::::
0x1BFF 512th TxPDO Generated automatically based on end user PDO configuration
0x1C00 Sync Manager Types Generated by the SDK
0x1C01 Reserved
::::::: ::::::: :::::::
0x1C0F Reserved
0x1C10 Sync Manager 0 PDO Assignment Generated by the SDK
0x1C11 Sync Manager 1 PDO Assignment Generated by the SDK
0x1C12 Sync Manager 2 PDO Assignment Generated by the SDK
0x1C13 Sync Manager 3 PDO Assignment Generated by the SDK
::::::: ::::::: :::::::
0x1C30 Sync Manager 0 Synchronization Generated by the SDK
0x1C31 Sync Manager 1 Synchronization Generated by the SDK
0x1C32 Sync Manager 2 Synchronization Generated by the SDK
0x1C33 Sync Manager 3 Synchronization Generated by the SDK
::::::: ::::::: :::::::
0x1FFF Reserved

0x2000 – 0x5FFF: Manufacturer area

Object types

These objects are customer specific and therefore are completely configurable. There are three* types of objects supported by the SDK:

  • Variable objects: These objects do not contain subindexes.
  • Array objects: These objects contain subindexes of the same type.
  • Record objects: These objects contain subindexes of different types.

Enumerators would be the fourth object type, but it is not supported by the SDK now.

Object parameters

The objects must be configured with a variety of parameters. These are listed below:

  • Index: From 0x2000 to 0x5FFF.
  • Subindex: Only for arrays and records. Maximum value is 255. SubIndex 0 configured by SDK.
  • Datatype: How data is intended to use. For more information refer to SDO Datatype Definition.
  • Bitlength: Length of the datatype.
  • Flags: Defines read and write access, capability to map object as PDO and other settings. For more information refer to SDO Access Rigths.
  • Callbacks: Functions called when the object is read or written by the Master.
  • Context: Data provided to the callbacks.

Examples

Create Variable object
EC_API_EError_t error = EC_API_eERR_INVALID;
EC_API_SLV_SHandle_t* ptSlave = pApplicationInstance->ptEcSlvApi;
error = (EC_API_EError_t)EC_API_SLV_CoE_odAddVariable(ptSlave, 0x2000, "Test variable object",
DEFTYPE_UNSIGNED32, 32, ACCESS_READWRITE,
EC_SLV_APP_setValueToMaster, pApplicationInstance,
EC_SLV_APP_getValueFromMaster, pApplicationInstance);
Create Array object
EC_API_EError_t error = EC_API_eERR_INVALID;
EC_API_SLV_SHandle_t* ptSlave = pApplicationInstance->ptEcSlvApi;
error = (EC_API_EError_t)EC_API_SLV_CoE_odAddArray(ptSlave, 0x2100, "Test array object", 128, DEFTYPE_UNSIGNED16,
16, ACCESS_READWRITE | OBJACCESS_RXPDOMAPPING | OBJACCESS_TXPDOMAPPING,
NULL, NULL, NULL, NULL);
Create Record object and entry
EC_API_EError_t error = EC_API_eERR_INVALID;
EC_API_SLV_SCoE_Object_t* ptRecObjOut = NULL;
EC_API_SLV_SHandle_t* ptSlave = pApplicationInstance->ptEcSlvApi;
error = (EC_API_EError_t)EC_API_SLV_CoE_odAddRecord(ptSlave, 0x2200, "Test record object",
NULL, NULL, NULL, NULL, &ptRecObjOut);
error = (EC_API_EError_t)EC_API_SLV_CoE_configRecordSubIndex(ptSlave, ptRecObjOut, 1, "SubIndex 1",
DEFTYPE_UNSIGNED32, 32,
ACCESS_READWRITE | OBJACCESS_RXPDOMAPPING | OBJACCESS_TXPDOMAPPING);

Help functions

The EtherCAT SDK provides with a set of functions to get some information of the object or read or write the object data. These help functions are available with the CoE suffix. For further information please refer to the documentation.

Function Description
EC_API_SLV_CoE_getObject Get object from Object Dictionary
EC_API_SLV_CoE_getObjectData Read object data
EC_API_SLV_CoE_setObjectData Write object data
EC_API_SLV_CoE_getObjectEntryCount Get number of object entries
EC_API_SLV_CoE_getObjectType Get object type from Beckhoff Stack
EC_API_SLV_CoE_getObjectEntry Get object entry from Object Dictionary
EC_API_SLV_CoE_getObjectEntryData Read object entry data
EC_API_SLV_CoE_setObjectEntryData Write object entry data
EC_API_SLV_CoE_subIdx0WrFlag Modify subindex 0 access flag

0x6000 – 0xFFFF: Profile area

This object area is reserved for profiles. There are several profiles supported by EtherCAT, such as CiA402, Modular Device Profiles, IO-Link Master, FSoE Master and so on. The EtherCAT SDK provides functions to configure CiA402 profile. However, normally the objects in this area must be configured by the end customer. Please refer to CiA 402 Example for motion control profile.

EC_API_SLV_CoE_odAddArray
uint32_t EC_API_SLV_CoE_odAddArray(EC_API_SLV_SHandle_t *pEcSlaveApi_p, uint16_t index_p, char *pName_p, uint8_t arrayLen_p, uint16_t type_p, uint16_t bitLen_p, uint16_t flags_p, EC_API_SLV_CBObjRead_t cbRead_p, void *pReadCtxt_p, EC_API_SLV_CBObjWrite_t cbWrite_p, void *pWriteCtxt_p)
Definition: ecSlvApi_CoEStub.c:679
EC_API_SLV_CoE_odAddVariable
uint32_t EC_API_SLV_CoE_odAddVariable(EC_API_SLV_SHandle_t *pEcSlaveApi_p, uint16_t index_p, char *pName_p, uint16_t type_p, uint16_t bitLen_p, uint16_t flags_p, EC_API_SLV_CBObjRead_t cbRead_p, void *pReadCtxt_p, EC_API_SLV_CBObjWrite_t cbWrite_p, void *pWriteCtxt_p)
This function creates a Base Data Type Object for the Object Dictionary.
Definition: ecSlvApi_CoEStub.c:624
OBJACCESS_TXPDOMAPPING
#define OBJACCESS_TXPDOMAPPING
Mappable in TxPDOs.
Definition: ecApiDef.h:143
EC_API_EError_t
enum EC_API_EError EC_API_EError_t
ACCESS_READWRITE
#define ACCESS_READWRITE
Read/write in all states.
Definition: ecApiDef.h:132
EC_API_SLV_SCoE_Object_t
struct EC_API_SLV_SCoE_Object EC_API_SLV_SCoE_Object_t
TSdo describes an Object Dictionary Object.
Definition: ecSlvApi.h:132
EC_API_SLV_SHandle_t
struct EC_API_SLV_SHandle EC_API_SLV_SHandle_t
EC_API_SLV_SHandle_t describes the EtherCAT Slave API.
Definition: ecSlvApi.h:135
EC_API_eERR_INVALID
@ EC_API_eERR_INVALID
Definition: ecApiError.h:73
EC_API_SLV_CoE_configRecordSubIndex
uint32_t EC_API_SLV_CoE_configRecordSubIndex(EC_API_SLV_SHandle_t *pEcSlaveApi_p, EC_API_SLV_SCoE_Object_t *pObject_p, uint8_t subIndex_p, char *pName_p, uint16_t type_p, uint16_t bitLen_p, uint16_t flags_p)
This function creates a subIndex for the Record Object.
Definition: ecSlvApi_CoEStub.c:780
EC_SLV_APP_Sapplication::ptEcSlvApi
EC_API_SLV_SHandle_t * ptEcSlvApi
Definition: ecSlvSimple.h:97
DEFTYPE_UNSIGNED16
#define DEFTYPE_UNSIGNED16
UNSIGNED16.
Definition: ecApiDef.h:70
EC_API_SLV_CoE_odAddRecord
uint32_t EC_API_SLV_CoE_odAddRecord(EC_API_SLV_SHandle_t *pEcSlaveApi_p, uint16_t index_p, char *pName_p, EC_API_SLV_CBObjRead_t cbRead_p, void *pReadCtxt_p, EC_API_SLV_CBObjWrite_t cbWrite_p, void *pWriteCtxt_p, EC_API_SLV_SCoE_Object_t **pOutSdo_p)
This function creates a Record Object.
Definition: ecSlvApi_CoEStub.c:731
OBJACCESS_RXPDOMAPPING
#define OBJACCESS_RXPDOMAPPING
Mappable in RxPDOs.
Definition: ecApiDef.h:142
DEFTYPE_UNSIGNED32
#define DEFTYPE_UNSIGNED32
UNSIGNED32.
Definition: ecApiDef.h:71
EC_SLV_APP_getValueFromMaster
uint8_t EC_SLV_APP_getValueFromMaster(void *pApplicationCtxt_p, uint16_t index_p, uint8_t subindex_p, uint32_t size_p, uint16_t MBXMEM *pData_p, uint8_t completeAccess_p)
Read Process data (CoE) callback.
Definition: ecSlvSimple.c:217
EC_SLV_APP_setValueToMaster
uint8_t EC_SLV_APP_setValueToMaster(void *pApplicationCtxt_p, uint16_t index_p, uint8_t subindex_p, uint32_t size_p, uint16_t MBXMEM *pData_p, uint8_t completeAccess_p)
Write Process data (CoE) callback.
Definition: ecSlvSimple.c:272