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 SubIndex. If Complete Access only 0 or 1 allowed

  • pbyData – [in] Buffer containing transferred data

  • dwDataLen – [in] Buffer length in bytes

  • dwTimeout – [in] Timeout [ms]

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

Returns

emCoeSdoDownload Example

The following code demonstrates how to download a CoE object to a slave using the API emCoeSdoDownload().

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

    /* slave with station address 2002 used for CoE SDO download */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);
    EC_T_BYTE         abyBuf[4];
    OsMemset(abyBuf, 0, sizeof(abyBuf));

    /* download value 123 to object index 0x40A2, subindex 2, timeout 5s, no complete access */
    EC_SET_FRM_DWORD(abyBuf, 123);
    dwRes = ecatCoeSdoDownload(dwSlaveId, 0x40A2, 2, abyBuf, (EC_T_DWORD)sizeof(abyBuf), 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = EC_E_NOERROR;
Exit:
    return dwRetVal;
}

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 SubIndex. If Complete Access only 0 or 1 allowed

  • dwTimeout – [in] Timeout [ms]

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

Returns

emCoeSdoDownloadReq Example

The following code demonstrates how to download a CoE object to a slave using the non-blocking API emCoeSdoDownloadReq().

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

EC_T_DWORD CoeSdoDownloadReqExample()
{
    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 download */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);

    EC_T_MBXTFER*     pMbxTferObject = EC_NULL;
    EC_T_BYTE         abyBuf[4];
    EC_T_MBXTFER_DESC oObjectDataTferDesc;
    OsMemset(abyBuf, 0, sizeof(abyBuf));
    OsMemset(&oObjectDataTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));

    /* create mailbox transfer object */
    oObjectDataTferDesc.pbyMbxTferDescData = abyBuf;
    oObjectDataTferDesc.dwMaxDataLen = sizeof(abyBuf);
    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 download of value 123 to object index 0x40A2, subindex 2, timeout 5s, no complete access */
    EC_SET_FRM_DWORD(abyBuf, 123);
    dwRes = ecatCoeSdoDownloadReq(pMbxTferObject, dwSlaveId, 0x40A2, 2, 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

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

    /* 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

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 SubIndex. If Complete Access only 0 or 1 allowed

  • pbyData – [out] Buffer receiving transferred data

  • dwDataLen – [in] Buffer length in bytes

  • pdwOutDataLen – [out] Length of received data in bytes

  • dwTimeout – [in] Timeout [ms]

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

Returns

emCoeSdoUpload Example

The following code demonstrates how to upload a CoE object from a slave using the API emCoeSdoUpload().

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

    /* slave with station address 2002 used for CoE SDO upload */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);
    EC_T_BYTE         abyBuf[4];
    OsMemset(abyBuf, 0, sizeof(abyBuf));

    /* upload object index 0x1018, subindex 1, timeout 5s, no complete access */
    dwRes = ecatCoeSdoUpload(dwSlaveId, 0x1018, 1, abyBuf, (EC_T_DWORD)sizeof(abyBuf), EC_NULL, 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = EC_E_NOERROR;
Exit:
    return dwRetVal;
}

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 SubIndex. If Complete Access only 0 or 1 allowed

  • dwTimeout – [in] Timeout [ms]

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

Returns

emCoeSdoUploadReq 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         abyBuf[4];
    EC_T_MBXTFER_DESC oObjectDataTferDesc;
    OsMemset(abyBuf, 0, sizeof(abyBuf));
    OsMemset(&oObjectDataTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));

    /* create mailbox transfer object */
    oObjectDataTferDesc.pbyMbxTferDescData = abyBuf;
    oObjectDataTferDesc.dwMaxDataLen = sizeof(abyBuf);
    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

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

static EC_T_DWORD ecatCoeGetODListReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_COE_ODLIST_TYPE eListType, EC_T_DWORD dwTimeout)
EC_T_DWORD emCoeGetODListReq(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.

Note

The mailbox transfer object will receive the slave response containing the list type followed by the list itself. Therefore the buffer must be 2 bytes bigger than the expected list size.

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

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

emCoeGetODListReq Example

The following code demonstrates how to get the list of objects that are available in a slave using the non-blocking API emCoeGetODListReq().

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

    EC_T_MBXTFER*     pMbxTfer = EC_NULL;
    EC_T_MBXTFER_DESC oMbxTferDesc;

    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));
    oMbxTferDesc.dwMaxDataLen = CROD_ODLTFER_SIZE;

    /* allocate payload memory */
    oMbxTferDesc.pbyMbxTferDescData = (EC_T_BYTE*)OsMalloc(oMbxTferDesc.dwMaxDataLen);
    if (EC_NULL == oMbxTferDesc.pbyMbxTferDescData)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    /* create mailbox transfer object */
    pMbxTfer = emMbxTferCreate(dwInstanceId, &oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    dwRes = emCoeGetODListReq(dwInstanceId, pMbxTfer, dwSlaveId, eODListType_ALL, 5000 /* timeout */);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "emCoeGetODList: %s (0x%lx))\n", ecatGetText(dwRes), dwRes));
        goto Exit;
    }

    /* wait for transfer finished, see also emMbxTferAbort(...) */
    while (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
    {
        OsSleep(10);
    }

    dwRetVal = pMbxTfer->dwErrorCode;
Exit:
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            emMbxTferAbort(dwInstanceId, pMbxTfer);
        }
        emMbxTferDelete(dwInstanceId, pMbxTfer);
    }

    SafeOsFree(oMbxTferDesc.pbyMbxTferDescData);

See also

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

static EC_T_DWORD ecatCoeGetObjectDescReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_WORD wObIndex, EC_T_DWORD dwTimeout)
EC_T_DWORD emCoeGetObjectDescReq(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

emCoeGetObjectDescReq Example

The following code demonstrates how to determine the description of a specific object using the non-blocking API emCoeGetObjectDescReq().

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

    EC_T_MBXTFER*     pMbxTfer = EC_NULL;
    EC_T_MBXTFER_DESC oMbxTferDesc; /* mailbox transfer descriptor */

    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));
    oMbxTferDesc.dwMaxDataLen = CROD_OBDESC_SIZE;

    /* allocate payload memory */
    oMbxTferDesc.pbyMbxTferDescData = (EC_T_BYTE*)OsMalloc(oMbxTferDesc.dwMaxDataLen);
    if (EC_NULL == oMbxTferDesc.pbyMbxTferDescData)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    /* create mailbox transfer object */
    pMbxTfer = emMbxTferCreate(dwInstanceId, &oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }
    dwRes = emCoeGetObjectDescReq(dwInstanceId, pMbxTfer, dwSlaveId, 0x6411, 5000);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "emCoeGetObjectDescReq: %s (0x%lx))\n", ecatGetText(dwRes), dwRes));
        goto Exit;
    }

    /* wait for transfer finished, see also emMbxTferAbort(...) */
    while (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
    {
        OsSleep(10);
    }

    dwRetVal = pMbxTfer->dwErrorCode;
Exit:
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            emMbxTferAbort(dwInstanceId, pMbxTfer);
        }
        emMbxTferDelete(dwInstanceId, pMbxTfer);
    }

    SafeOsFree(oMbxTferDesc.pbyMbxTferDescData);

See also

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

static EC_T_DWORD ecatCoeGetEntryDescReq(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 emCoeGetEntryDescReq(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 SubIndex

  • 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

emCoeGetEntryDescReq Example

The following code demonstrates how to get the description of a specific object entry using the non-blocking API emCoeGetEntryDescReq().

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

    EC_T_MBXTFER*     pMbxTfer = EC_NULL;
    EC_T_MBXTFER_DESC oMbxTferDesc; /* mailbox transfer descriptor */

    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));
    oMbxTferDesc.dwMaxDataLen = CROD_ENTRYDESC_SIZE;
    oMbxTferDesc.pbyMbxTferDescData = (EC_T_BYTE*)OsMalloc(oMbxTferDesc.dwMaxDataLen);

    /* allocate payload memory */
    if (EC_NULL == oMbxTferDesc.pbyMbxTferDescData)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    /* create transfer object */
    pMbxTfer = emMbxTferCreate(dwInstanceId, &oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;

        goto Exit;
    }
    dwRes = emCoeGetEntryDescReq(dwInstanceId, pMbxTfer, dwSlaveId, 0x6411, 1, 0, 5000);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    /* wait for transfer finished, see also emMbxTferAbort(...) */
    while (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
    {
        OsSleep(10);
    }

    dwRetVal = pMbxTfer->dwErrorCode;
Exit:
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            emMbxTferAbort(dwInstanceId, pMbxTfer);
        }
        emMbxTferDelete(dwInstanceId, pMbxTfer);
    }

    SafeOsFree(oMbxTferDesc.pbyMbxTferDescData);

Value info flags

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

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

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

  • An 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

emCoeProfileGetChannelInfo Example

The following code demonstrates how to return information about a configured CoE profile channel from the ENI file using the non-blocking API emCoeProfileGetChannelInfo().

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

    /* get information about CoE profile channel configured in ENI */
    EC_T_PROFILE_CHANNEL_INFO oInfo;
    dwRes = emCoeProfileGetChannelInfo(dwInstanceId, EC_TRUE, wSlaveAddress, 0, &oInfo);

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

CoE Emergency Example
    /* send CoE Emergency */
    EC_T_BYTE abyEmergencyData[6] = { 0x01, 0x02, 0x03, 0x04, 0x05, 0x06 };
    dwRes = esSendSlaveCoeEmergency(dwSimulatorId, wSlaveAddress, 0x1234 /* code */, abyEmergencyData, 6 /* data length */);
    if (dwRes != EC_E_NOERROR)
    {
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "esSendSlaveCoeEmergency failed: %s (0x%lx))\n", esGetText(dwSimulatorId, dwRes), dwRes));
        goto Exit;
    }

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)

emConvertEcErrorToCoeError Example

The following code demonstrates how to convert master error code to CoE error code using the non-blocking API emConvertEcErrorToCoeError().

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

    dwCoeError = emConvertEcErrorToCoeError(dwInstanceId, EC_E_NOERROR);