6.11. CAN application protocol over EtherCAT (CoE)

6.11.1. emCoeSdoDownload

static EC_T_DWORD ecatCoeSdoDownload(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)

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

See also

emGetSlaveId()

6.11.2. emCoeSdoDownloadReq

static EC_T_DWORD ecatCoeSdoDownloadReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_BYTE byObSubIndex, EC_T_DWORD dwTimeout, EC_T_DWORD dwFlags)

EC_T_DWORD emCoeSdoDownloadReq(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 download to an EtherCAT slave device and returns immediately.

The length of the data to be downloaded 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

• 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

See also

• emNotify - eMbxTferType_COE_SDO_DOWNLOAD

• emMbxTferCreate()

• emGetSlaveId()

6.11.3. 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 corresponding transfer ID can be found in EC_T_MBXTFER::dwTferId. 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 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_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

6.11.4. emCoeSdoUpload

static EC_T_DWORD ecatCoeSdoUpload(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)

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

See also

emGetSlaveId()

6.11.5. emCoeSdoUploadReq

static EC_T_DWORD ecatCoeSdoUploadReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_BYTE byObSubIndex, EC_T_DWORD dwTimeout, EC_T_DWORD dwFlags)

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

Example

The following code demonstrates how to upload a CoE object from a slave using the non-blocking API emCoeSdoUploadReq().

In this example the mailbox transfer object state is polled. emNotify - EC_NOTIFY_MBOXRCV can be used as alternative to polling.

EC_T_DWORD CoeSdoUploadReqExample()
{
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes    = EC_E_ERROR;

    /* needed only for notifications, see
       - ecatRegisterClient(...)
       - pAppContext->pNotificationHandler->GetClientID() */
    EC_T_DWORD        dwClientId = 0;

    /* slave with station address 2002 used for CoE SDO upload */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);

    EC_T_MBXTFER*     pMbxTferObject = EC_NULL;
    EC_T_BYTE         abyObjectDataBuffer[] = { 0, 0, 0, 0 };
    EC_T_MBXTFER_DESC oObjectDataTferDesc;
    OsMemset(&oObjectDataTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));

    /* create mailbox transfer object */
    oObjectDataTferDesc.pbyMbxTferDescData = abyObjectDataBuffer;
    oObjectDataTferDesc.dwMaxDataLen = sizeof(abyObjectDataBuffer);
    pMbxTferObject = ecatMbxTferCreate(&oObjectDataTferDesc);
    if (EC_NULL == pMbxTferObject)
    {
        dwRes = EC_E_NOMEMORY;
        dwRetVal = dwRes;
        goto Exit;
    }

    /* create mailbox transfer object */
    pMbxTferObject->dwClntId = dwClientId;
    pMbxTferObject->dwTferId = 1; /* assigned by application. should be unique for each object */

    /* request upload of object index 0x1018, subindex 1, timeout 5s, no complete access */
    dwRes = ecatCoeSdoUploadReq(pMbxTferObject, dwSlaveId, 0x1018, 1, 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    /* wait for transfer finished */
    while (eMbxTferStatus_Pend == pMbxTferObject->eTferStatus)
    {
        OsSleep(10);

        /* transfer can be canceled using ecatMbxTferAbort(...) if it takes too long */
    }

    /* check transfer result */
    dwRes = pMbxTferObject->dwErrorCode;
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = EC_E_NOERROR;
Exit:
    if (EC_NULL != pMbxTferObject)
    {
        pMbxTferObject->eTferStatus = eMbxTferStatus_Idle;
        ecatMbxTferDelete(pMbxTferObject);
    }

    return dwRetVal;
}

See also

• emNotify - eMbxTferType_COE_SDO_UPLOAD

• emMbxTferCreate()

• emGetSlaveId()

6.11.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 corresponding transfer ID can be found in EC_T_MBXTFER::dwTferId. 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 may have to be buffered by the client. Access to the memory area referenced by EC_T_MBXTFER::pbyMbxTferData outside of the notification caller context is illegal and the results are undefined.

6.11.7. emCoeGetODList

static EC_T_DWORD ecatCoeGetODList(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_COE_ODLIST_TYPE eListType, EC_T_DWORD dwTimeout)

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

See also

• emNotify - eMbxTferType_COE_GETODLIST

• emMbxTferCreate()

• emGetSlaveId()

6.11.8. 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 wStationAddress

Station address of the slave

EC_T_WORD *pwOdList

array containing object IDs

6.11.9. emCoeGetObjectDesc

static EC_T_DWORD ecatCoeGetObjectDesc(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_DWORD dwTimeout)

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

See also

• emNotify - eMbxTferType_COE_GETOBDESC

• emMbxTferCreate()

• emGetSlaveId()

6.11.10. emNotify - eMbxTferType_COE_GETOBDESC

Completion of a SDO information service transfer to get a object description.

emNotify - eMbxTferType_COE_GETOBDESC

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 description stored in element EC_T_MBX_DATA::CoE_ObDesc of type EC_T_COE_OBDESC 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_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_WORD wStationAddress

Station address of the slave

EC_T_CHAR *pchObName

Object name (not NULL terminated!)

See also

A more detailed description of the values for data type, object code etc. can be found in the EtherCAT specification ETG.1000, section 5.

6.11.11. emCoeGetEntryDesc

static EC_T_DWORD ecatCoeGetEntryDesc(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_BYTE byObSubIndex, EC_T_BYTE byValueInfo, EC_T_DWORD dwTimeout)

EC_T_DWORD emCoeGetEntryDesc(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] The value info bit mask includes which elements shall be in the response. See Value info flags for available values.

• 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

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

See also

• emNotify - eMbxTferType_COE_GETENTRYDESC

• emMbxTferCreate()

• emGetSlaveId()

6.11.12. emNotify - eMbxTferType_COE_GETENTRYDESC

Completion of a SDO information service transfer to get a object entry description.

emNotify - eMbxTferType_COE_GETENTRYDESC

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 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)

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 example for the evaluation of EC_T_COE_ENTRYDESC::pbyData comes with EcMasterDemo.

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

6.11.13. emCoeProfileGetChannelInfo

static EC_T_DWORD ecatCoeProfileGetChannelInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_DWORD dwChannel, EC_T_PROFILE_CHANNEL_INFO *pInfo)

EC_T_DWORD emCoeProfileGetChannelInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwChannel, EC_T_PROFILE_CHANNEL_INFO *pInfo)

Return information about a configured CoE profile channel from the ENI file.

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• dwChannel – [in] Channel

• pInfo – [out] Channel info

Returns

EC_E_NOERROR or error code

struct EC_T_PROFILE_CHANNEL_INFO

Public Members

EC_T_WORD wProfileNo

[out] ProfileNo: “low word of CoE object 0x1000”

EC_T_WORD wAddInfo

[out] AddInfo : “high word of CoE object 0x1000”

EC_T_CHAR szDisplayName[ECAT_DEVICE_NAMESIZE]

[out] Display name

6.11.14. emNotify - EC_NOTIFY_COE_INIT_CMD

Indicates a COE mailbox transfer completion during slave state transition. This notification is disabled by default.

emNotify - EC_NOTIFY_COE_INIT_CMD

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 provided at 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 EC_T_MBX_DATA::CoE_InitCmd element of type EC_T_MBX_DATA_COE_INITCMD 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_MBX_DATA_COE_INITCMD

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_DWORD dwHandle

Handle passed by EC_IOCTL_ADD_COE_INITCMD, otherwise zero

EC_T_WORD wTransition

Transition, e.g. ECAT_INITCMD_I_P

EC_T_CHAR szComment[MAX_STD_STRLEN]

Comment (ENI)

EC_T_DWORD dwErrorCode

InitCmd result

EC_T_BOOL bFixed

Fixed flag (ENI)

EC_T_BYTE byCcs

Client command specifier (read or write access)

EC_T_BOOL bCompleteAccess

Complete access

EC_T_WORD wIndex

Object Index

EC_T_BYTE bySubIndex

Object SubIndex

EC_T_DWORD dwDataLen

InitCmd data length

EC_T_BYTE *pbyData

InitCmd data

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED

6.11.15. 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 inside the EtherCAT master. The content in EC_T_MBXTFER::dwTferId is undefined as it is not needed by the client and the master. 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.

6.11.16. CoE Abort (emNotify - EC_NOTIFY_MBSLAVE_COE_SDO_ABORT)

The application can abort asynchronous CoE Uploads and Downloads. The slave may abort CoE Uploads and Downloads which is indicated at the return code of emCoeSdoUpload(), … . This notification is given if an SDO transfer aborts while sending init commands.

emNotify - EC_NOTIFY_MBSLAVE_COE_SDO_ABORT

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

Detailed error information is stored in structure EC_T_MBOX_SDO_ABORT_DESC of the union element SdoAbortDesc.

struct EC_T_MBOX_SDO_ABORT_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_DWORD dwErrorCode

Error code

EC_T_WORD wObjIndex

SDO object index

EC_T_BYTE bySubIndex

SDO object sub index

See also

emMbxTferAbort()

6.11.17. emConvertEcErrorToCoeError

EC_T_DWORD ecatConvertEcErrorToCoeError(EC_T_DWORD dwErrorCode)

EC_T_DWORD emConvertEcErrorToCoeError(EC_T_DWORD dwInstanceID, EC_T_DWORD dwErrorCode)

Convert master error code to CoE error code.

Returns

CoE error code according to the following specifications:

• CoE Abort Codes defined in ETG.1000.6 V1.0.4, Table 41: SDO Abort Codes

• Additional codes defined in ETG.1020, V1.2.0, Table 21: CoE Abort Codes (extension)