8.8. CAN application protocol over EtherCAT (CoE)

The EC-Monitor can forward CoE transfers to the application in real time via the notifications emNotify - eMbxTferType_COE_SDO_DOWNLOAD, emNotify - eMbxTferType_COE_SDO_UPLOAD and emNotify - eMbxTferType_COE_EMERGENCY.

There is also the option of storing the recorded data from the CoE transfers in an internal object dictionary. This object dictionary is structured analogously to that from the slaves and can be read out via the functions emCoeSdoUpload() / emCoeSdoUploadReq() and emCoeGetODList().

The notifications for CoE can be deactivated using the EC_T_MBX_PARMS::_EC_T_MBX_PARMS_COE::bDisableNotifications parameter if they are not required or to save computing time. In order to reduce memory consumption, the internal memory for the CoE data can be deactivated using the EC_T_MBX_PARMS::_EC_T_MBX_PARMS_COE::bDisableODStorage parameter.

If both parameters EC_T_MBX_PARMS::_EC_T_MBX_PARMS_COE::bDisableNotifications and EC_T_MBX_PARMS::_EC_T_MBX_PARMS_COE::bDisableODStorage are set, the CoE monitoring is completely deactivated.

8.8.1. emNotify - eMbxTferType_COE_SDO_DOWNLOAD

SDO download transfer completion.

emNotify - eMbxTferType_COE_SDO_DOWNLOAD
Parameter

  • pbyInBuf: [in] Pointer to a structure of type EC_T_MBXTFER, this structure contains the corresponding mailbox transfer object.

  • dwInBufSize: [in] Size of the transfer object pbyInBuf in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

The transfer result is stored in EC_T_MBXTFER::dwErrorCode. The request parameters stored in element EC_T_MBX_DATA::CoE of type EC_T_MBX_DATA_COE are part of EC_T_MBXTFER::MbxData. The SDO data stored in EC_T_MBXTFER::pbyMbxTferData.

struct EC_T_MBX_DATA_COE

Public Members

EC_T_WORD wStationAddress

Station address of the slave

EC_T_WORD wIndex

Object index

EC_T_BYTE bySubIndex

Object subindex

EC_T_BOOL bCompleteAccess

Complete access

8.8.2. emNotify - eMbxTferType_COE_SDO_UPLOAD

SDO upload transfer completion.

emNotify - eMbxTferType_COE_SDO_UPLOAD
Parameter

  • pbyInBuf: [in] Pointer to a structure of type EC_T_MBXTFER, contains the corresponding mailbox transfer object.

  • dwInBufSize: [in] Size of the transfer object in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

The transfer result is stored in EC_T_MBXTFER::dwErrorCode. The request parameters stored in element EC_T_MBX_DATA::CoE of type EC_T_MBX_DATA_COE are part of EC_T_MBXTFER::MbxData. The SDO data stored in EC_T_MBXTFER::pbyMbxTferData.

8.8.3. CoE Emergency (emNotify - eMbxTferType_COE_EMERGENCY)

Indication of a CoE emergency request. A emNotify - EC_NOTIFY_MBOXRCV is given with EC_T_MBXTFER::eMbxTferType = EC_T_MBXTFER_TYPE::eMbxTferType_COE_EMERGENCY.

emNotify - eMbxTferType_COE_EMERGENCY
Parameter

  • pbyInBuf: [in] Pointer to a structure of type EC_T_MBXTFER, contains the corresponding mailbox transfer object.

  • dwInBufSize: [in] Size of the transfer object in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

In case of an emergency notification all registered clients will get this notification. The corresponding mailbox transfer object will be created. EC_T_MBXTFER::dwTferId is undefined as it is not needed by the client. The transfer result is stored in EC_T_MBXTFER::dwErrorCode.

The emergency data stored in element EC_T_MBX_DATA::CoE_Emergency of type EC_T_COE_EMERGENCY is part of EC_T_MBXTFER::MbxData and may have to be buffered by the client. Access to the memory area EC_T_MBXTFER::MbxData outside of the notification caller context is illegal and the results are undefined.

struct EC_T_COE_EMERGENCY

Public Members

EC_T_WORD wErrorCode

Error code according to EtherCAT specification

EC_T_BYTE byErrorRegister

Error register

EC_T_BYTE abyData[EC_COE_EMERGENCY_DATASIZE]

Error data

EC_T_WORD wStationAddress

Slave node address of the faulty slave

See also

A more detailed description of the values can be found in the EtherCAT specification ETG.1000, section 5.

8.8.4. emCoeSdoUpload

EC_T_DWORD emCoeSdoUpload(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_BYTE byObSubIndex, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD *pdwOutDataLen, EC_T_DWORD dwTimeout, EC_T_DWORD dwFlags)

Execute a CoE SDO upload from an EtherCAT slave device to the master.

This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwSlaveId – [in] Slave ID

  • wObIndex – [in] Object index.

  • byObSubIndex – [in] Object sub index. 0 or 1 if Complete Access.

  • pbyData – [out] Buffer receiving transfered data

  • dwDataLen – [in] Buffer length [bytes]

  • pdwOutDataLen – [out] Length of received data [byte]

  • dwTimeout – [in] Timeout [ms]

  • dwFlags – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE).

Returns

EC_E_NOERROR or error code

Limitation

  • Only CoE entries which have been received by the EcMonitor can be retrieved

  • CoE objects read via complete access, can only be retrieved as complete access.

  • When switching between complete access and access via subindexes the corresponding CoE object is overwritten.

See also

emGetSlaveId()

8.8.5. emCoeSdoUploadReq

EC_T_DWORD emCoeSdoUploadReq(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_BYTE byObSubIndex, EC_T_DWORD dwTimeout, EC_T_DWORD dwFlags)

Initiates a CoE SDO upload from an EtherCAT slave device to the master and returns immediately.

The length of the data to be uploaded must be set in EC_T_MBXTFER.dwDataLen. A unique transfer ID must be written into EC_T_MBXTFER.dwTferId. EC_NOTIFY_MBOXRCV is given on completion.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pMbxTfer – [in] Mailbox transfer object created with emMbxTferCreate

  • dwSlaveId – [in] Slave ID

  • wObIndex – [in] Object index

  • byObSubIndex – [in] Object sub index. 0 or 1 if Complete Access.

  • dwTimeout – [in] Timeout [ms]

  • dwFlags – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE).

Returns

Limitation

  • Only CoE entries which have been received by the EC-Monitor can be retrieved

  • CoE objects read via complete access, can only be retrieved as complete access.

  • When switching between complete access and access via subindexes, the corresponding CoE object is overwritten.

See also

8.8.6. emCoeGetODList

EC_T_DWORD emCoeGetODList(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_COE_ODLIST_TYPE eListType, EC_T_DWORD dwTimeout)

Gets a list of object IDs that have so far been transfered to a slave and received by the EC-Monitor. This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pMbxTfer – [in] Mailbox transfer

  • dwSlaveId – [in] Slave ID

  • eListType – [in] which object types shall be transferred

  • dwTimeout – [in] Timeout [ms] The function will block at most for this time. If the timeout value is set to EC_NOWAIT the function will return immediately.

enum EC_T_COE_ODLIST_TYPE

Values:

enumerator eODListType_Lengths

Lengths of each list type

enumerator eODListType_ALL

List contains all objects

enumerator eODListType_RxPdoMap

List with PDO mappable objects

enumerator eODListType_TxPdoMap

List with objects that can be changed

enumerator eODListType_StoredFRepl

Only stored for a device replacement objects

enumerator eODListType_StartupParm

Only startup parameter objects

See also

8.8.7. emNotify - eMbxTferType_COE_GETODLIST

Notification of a detected CoE SDO information service transfer for a object dictionary list.

emNotify - eMbxTferType_COE_GETODLIST
Parameter

  • pbyInBuf: [in] Pointer to a structure of type EC_T_MBXTFER.

  • dwInBufSize: [in] Size of the transfer object in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

The transfer result is stored in EC_T_MBXTFER::dwErrorCode.

The object list stored in element EC_T_MBX_DATA::CoE_ODList of type EC_T_COE_ODLIST is part of EC_T_MBXTFER::MbxData and may have to be buffered by the client. Access to the memory area EC_T_MBXTFER::MbxData outside of the notification caller context is illegal and the results are undefined.

struct EC_T_COE_ODLIST

Public Members

EC_T_COE_ODLIST_TYPE eOdListType

list type

EC_T_WORD wLen

amount of object IDs

EC_T_WORD wStationAddress

Station address of the slave

EC_T_WORD *pwOdList

array containing object IDs

8.8.8. emNotify - eMbxTferType_COE_GETENTRYDESC

Notification of a detected CoE SDO information service transfer for a object entry description.

emNotify - eMbxTferType_COE_GETENTRYDESC
Parameter

  • pbyInBuf: [in] Pointer to a structure of type EC_T_MBXTFER.

  • dwInBufSize: [in] Size of the transfer object in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

The transfer result is stored in EC_T_MBXTFER::dwErrorCode.

The object entry description stored in element EC_T_MBX_DATA::CoE_EntryDesc of type EC_T_COE_ENTRYDESC is part of EC_T_MBXTFER::MbxData and may have to be buffered by the client. Access to the memory area EC_T_MBXTFER::MbxData outside of the notification caller context is illegal and the results are undefined.

struct EC_T_COE_ENTRYDESC

Public Members

EC_T_WORD wObIndex

Index in the object dictionary

EC_T_BYTE byObSubIndex

Sub index in the object dictionary

EC_T_BYTE byValueInfo

Bit mask which information is included in pbyData. See Value info flags

EC_T_WORD wDataType

Object data type according to ETG.1000

EC_T_WORD wBitLen

Object size (number of bits)

EC_T_BYTE byObAccess

Access rights. See Object access flags

EC_T_BOOL bRxPdoMapping

Object is mappable in a RxPDO

EC_T_BOOL bTxPdoMapping

Object is mappable in a TxPDO

EC_T_BOOL bObCanBeUsedForBackup

Object can be used for backup

EC_T_BOOL bObCanBeUsedForSettings

Object can be used for settings

EC_T_WORD wStationAddress

Station address of the slave

EC_T_WORD wDataLen

Size of the remaining object data

EC_T_BYTE *pbyData

Remaining object data: dwUnitType, pbyDefaultValue, pbyMinValue, pbyMaxValue, pbyDescription

(see ETG.1000.5 and ETG.1000.6)

Value info flags

group EC_COE_ENTRY_VALUEINFO

EtherCat CoE entry description value information bit definitions

Defines

EC_COE_ENTRY_ObjAccess

Object access

EC_COE_ENTRY_ObjCategory

Object category

EC_COE_ENTRY_PdoMapping

PDO mapping

EC_COE_ENTRY_UnitType

Unit type

EC_COE_ENTRY_DefaultValue

Default value

EC_COE_ENTRY_MinValue

Minimum value

EC_COE_ENTRY_MaxValue

Maximum value

Object access flags

group EC_COE_ENTRY_OBJACCESS

EtherCat CoE entry access bit definitions

Defines

EC_COE_ENTRY_Access_R_PREOP

Read access in Pre-Operational state

EC_COE_ENTRY_Access_R_SAFEOP

Read access in Safe-Operational state

EC_COE_ENTRY_Access_R_OP

Read access in Operational state

EC_COE_ENTRY_Access_W_PREOP

Write access in Pre-Operational state

EC_COE_ENTRY_Access_W_SAFEOP

Write access in Safe-Operational state

EC_COE_ENTRY_Access_W_OP

Write access in Operational state

See also

A more detailed description of the values can be found in the EtherCAT specification ETG.1000, section 5 and 6.