4.10. CAN application protocol over EtherCAT (CoE)

4.10.1. esExtendSlaveCoeObjectDictionary

EC_T_DWORD esExtendSlaveCoeObjectDictionary(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress, struct _EC_T_COE_DICTIONARY_DESC *pDict)

Add data types and / or objects to slave’s CoE object dictionary.

Parameters
  • dwInstanceId – [in] Simulator Instance ID

  • wCfgFixedAddress – [in] Slave’s station address

  • pDict – [in] Pointer to dictionary descriptor

Returns

EC_E_NOERROR or error code

4.10.2. esDeleteSlaveCoeObject

EC_T_DWORD esDeleteSlaveCoeObject(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress, EC_T_WORD wObjectIndex)

Delete object from slave’s CoE object dictionary.

Parameters
  • dwInstanceId – [in] Simulator Instance ID

  • wCfgFixedAddress – [in] Slave’s station address

  • wObjectIndex – [in] Object index

Returns

EC_E_NOERROR or error code

4.10.3. esClearSlaveCoeObjectDictionary

EC_T_DWORD esClearSlaveCoeObjectDictionary(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress)

Delete all objects from slave’s CoE object dictionary.

Parameters
  • dwInstanceId – [in] Simulator Instance ID

  • wCfgFixedAddress – [in] Slave’s station address

Returns

EC_E_NOERROR or error code

4.10.4. esResetSlaveCoeObjectDictionary

EC_T_DWORD esResetSlaveCoeObjectDictionary(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress)

Reset all objects from slave’s CoE object dictionary to default.

Parameters
  • dwInstanceId – [in] Simulator Instance ID

  • wCfgFixedAddress – [in] Slave’s station address

Returns

EC_E_NOERROR or error code

4.10.5. esSetSlaveCoeObjectTransferCallbacks

EC_T_DWORD esSetSlaveCoeObjectTransferCallbacks(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress, EC_T_WORD wObjectIndex, EC_T_BYTE (*pfRead)(EC_T_VOID *pvContext, EC_T_WORD wCfgFixedAddress, EC_T_WORD wObjectIndex, EC_T_BYTE bySubindex, EC_T_DWORD dwSize, EC_T_BYTE *pbyData, EC_T_BOOL bCompleteAccess), EC_T_BYTE (*pfWrite)(EC_T_VOID *pvContext, EC_T_WORD wCfgFixedAddress, EC_T_WORD wObjectIndex, EC_T_BYTE bySubindex, EC_T_DWORD dwSize, EC_T_BYTE *pbyData, EC_T_BOOL bCompleteAccess), EC_T_VOID *pvContext)

Set SDO upload / download callbacks.

Parameters
  • dwInstanceId – [in] Simulator Instance ID

  • wCfgFixedAddress – [in] Slave’s station address. 0: all slaves

  • wObjectIndex – [in] Object index. 0xffff: all objects

  • pfRead – [in] Upload callback function

  • pfWrite – [in] Download callback function

  • pvContext – [in] pointer to context passed as first parameters to callback functions

Returns

EC_E_NOERROR or error code

4.10.6. esCoeSdoDownload

EC_T_DWORD esCoeSdoDownload(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 dwTimeout, EC_T_DWORD dwFlags)

Execute a CoE SDO download to an EtherCAT slave device.

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 – [in] Buffer containing transfered data

  • dwDataLen – [in] Buffer length [bytes]

  • 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

4.10.7. esCoeSdoUpload

EC_T_DWORD esCoeSdoUpload(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

4.10.8. esCoeGetODList

EC_T_DWORD esCoeGetODList(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

4.10.9. esCoeGetObjectDesc

EC_T_DWORD esCoeGetObjectDesc(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_DWORD dwTimeout)

Determines the description of a specific object.

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 object

  • dwSlaveId – [in] Slave ID

  • wObIndex – [in] Object index

  • 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

struct EC_T_COE_OBDESC

Public Members

EC_T_WORD wObIndex

Index in the object dictionary

EC_T_WORD wDataType

Data type of the object

EC_T_BYTE byObjCode

Object code, see Table 62, ETG.1000 section 6

EC_T_BYTE byObjCategory

Object category

EC_T_BYTE byMaxNumSubIndex

Maximum sub index number

EC_T_WORD wObNameLen

Length of the object name

EC_T_CHAR *pchObName

Object name (not NULL terminated!)

4.10.10. esCoeGetEntryDesc

EC_T_DWORD esCoeGetEntryDesc(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_BYTE byObSubIndex, EC_T_BYTE byValueInfo, EC_T_DWORD dwTimeout)

Determines the description of a specific object entry.

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 object

  • dwSlaveId – [in] Slave ID

  • wObIndex – [in] Object index

  • byObSubIndex – [in] Object sub-index

  • byValueInfo – [in] value info selection

  • 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

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 to define which information is available

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

EC_T_BOOL bRxPdoMapping

Is the object PDO-mappable?

EC_T_BOOL bTxPdoMapping

Can the PDO be changed

EC_T_BOOL bObCanBeUsedForBackup

Parameter may be back upped

EC_T_BOOL bObCanBeUsedForSettings

Parameter may be used for Settings

EC_T_WORD wReserved

Unit

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)

See szUnitType, szDefaultValue, szMinValue, szMaxValue, szDescription in CoeReadObjectDictionary in EcSdoServices.cpp as an example for evaluating EC_T_COE_ENTRYDESC.pbyData.

4.11. File access over EtherCAT (FoE)

By default EC-Simulator supports basic file upload and download.

The following examples demonstrate how to customize FoE simulation using esSetSlaveSscApplication() .

4.12. Vendor specific access over EtherCAT (VoE)

4.12.1. esVoeSend

EC_T_DWORD esVoeSend(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress, EC_T_WORD wDstFixedAddress, EC_T_VOID *pvData, EC_T_DWORD dwDataLen)

Fill “Mailbox In” (SM1) with VoE data to be polled by Master. The slave must have VoE enabled, see ESI: /EtherCATInfo/Descriptions/Devices/Device/Mailbox/VoE, ENI/EXI: /EtherCATConfig/Config/Slave/Mailbox/Protocol/VoE.

Returns

EC_E_NOERROR or error code

4.12.2. esSetVoeReceiveCallback

EC_T_DWORD esSetVoeReceiveCallback(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress, EC_T_BYTE (*pfVoeReceive)(EC_T_VOID *pvContext, EC_T_WORD wFixedAddress, EC_T_WORD wSrcFixedAddress, EC_T_VOID *pvData, EC_T_DWORD dwDataLen), EC_T_VOID *pvContext)

Set VoE data received callback for “Mailbox Out” (SM0) Within the callback, no EC-Simulator API may be called. The slave must have VoE enabled, see ESI: /EtherCATInfo/Descriptions/Devices/Device/Mailbox/VoE, ENI/EXI: /EtherCATConfig/Config/Slave/Mailbox/Protocol/VoE.

Returns

EC_E_NOERROR or error code

The following examples demonstrate how to register a handler for VoE writes from the Master or from other slaves.