7.8. CAN application protocol over EtherCAT (CoE)

7.8.1. 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()

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

7.8.3. 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 are available in a slave.

A unique transfer ID must be written into EC_T_MBXTFER.dwTferId. EC_NOTIFY_MBOXRCV is given on completion. 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

enumerator eODListType_BCppDummy

7.8.4. emNotify - eMbxTferType_COE_GETODLIST

Object dictionary list upload transfer completion.

emNotify - eMbxTferType_COE_GETODLIST
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 corresponding transfer ID can be found in EC_T_MBXTFER::dwTferId. 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 *pwOdList

array containing object IDs

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

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

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