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

EC_E_NOERROR if successful
EC_E_INVALIDSTATE if master isn’t initialized
EC_E_INVALIDPARM if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
EC_E_NOMEMORY if the mailbox protocol queue of the slave if full
EC_E_SLAVE_NOT_PRESENT if slave not present
EC_E_NOTFOUND if no slave matching dwSlaveId can be found
EC_E_NO_MBX_SUPPORT if slave has no mailbox support
EC_E_INVALID_SLAVE_STATE if slave is in an invalid state for mailbox transfer
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive
EC_E_ADS_IS_RUNNING if ADS server is running

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

emNotify - eMbxTferType_COE_SDO_UPLOAD
emGetSlaveId()

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.

Returns

EC_E_NOERROR or error code

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.