6.7. Diagnosis, error detection, error notifications

In case of errors on the bus or in one or multiple SubDevices the EtherCAT® MainDevice stack will notify the application about such an event. The MainDevice automatically detects unexpected SubDevice states by evaluating the AL Status event interrupt. If the interrupt is set, the MainDevice reads the state of each SubDevice and compares it to the expected (required) state. In case of a state mismatch the MainDevice generates the notification emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE. The application will then have to enter an error handling procedure.

The error notifications can be separated into two classes:

  1. SubDevice unrelated errors

  2. SubDevice related errors

A SubDevice related error notification will also contain the information about which SubDevice has generated an error. If for example a SubDevice could not be set into the requested state the application will get the emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR error notification including SubDevice related information. A SubDevice unrelated error does not contain this information even if one specific SubDevice caused the error. For example if one or multiple SubDevices are powered off the working counter of the cyclic commands would be wrong. In that case the emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR error notification will be generated.

Example Error Scenario

SubDevice is powered off or disconnected while bus is operational

If the MainDevice is operational it cyclically sends EtherCAT® commands to read and write the SubDevice’s process data. It expects the working counter to be incremented to the appropriate value. If one SubDevice is powered off the MainDevice will generate the emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR to indicate such an event. Also the MainDevice detects a DL status event and performs a bus scan as reaction on this. For the not reachable SubDevices (powered off or disconnected) the MainDevice generates the notification emNotify - EC_NOTIFY_SLAVE_PRESENCE.

A possible error recovery scenario would be to stay operational and in parallel wait until the SubDevice is powered on again. The next step would be to determine the SubDevice’s state and set it operational again:

MainDevice calls emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR

  • Application gets informed

  • WKC State in Diagnosis Image changes

See also

Working Counter (WKC) State in Diagnosis Image

Use cases

  1. SubDevice is disconnected or powered off:
  2. SubDevice state is not OPERATIONAL anymore
  3. SubDevice is re-connected or powered on:

6.7.1. emSetLogParms

static EC_T_DWORD ecatSetLogParms(EC_T_LOG_PARMS *pLogParms)
EC_T_DWORD emSetLogParms(EC_T_DWORD dwInstanceID, EC_T_LOG_PARMS *pLogParms)

Sets log parameters. Used to change the parameters provided by emInitMaster().

Parameters

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

  • pLogParms – [in] New Log parameters

6.7.2. emEthDbgMsg

static EC_T_DWORD ecatEthDbgMsg(EC_T_BYTE byEthTypeByte0, EC_T_BYTE byEthTypeByte1, EC_T_CHAR *szMsg)
EC_T_DWORD emEthDbgMsg(EC_T_DWORD dwInstanceID, EC_T_BYTE byEthTypeByte0, EC_T_BYTE byEthTypeByte1, EC_T_CHAR *szMsg)

Send a debug message to the EtherCAT Link Layer.

This feature can be used for debugging purposes.

Parameters

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

  • byEthTypeByte0 – [in] Ethernet type byte 0

  • byEthTypeByte1 – [in] Ethernet type byte 1

  • szMsg – [in] Message to send to link layer

Returns

EC_E_NOERROR or error code

emEthDbgMsg() Example
EC_T_CHAR* szMsg = (EC_T_CHAR*)"Hello World";
EC_T_BYTE byEthTypeByte0 = 6;
EC_T_BYTE byEthTypeByte1 = 6;
/* send message as frame, validate given EtherType: 
   >= 1536: EtherType (supported as parameter), 
   <= 1500: size of payload (not supported as parameter), 
      1501-1535: undefined */
/* send debug message to EtherCAT Link Layer */
dwRes = emEthDbgMsg(dwInstanceId, byEthTypeByte0, byEthTypeByte1, szMsg);

6.7.3. emIoCtl - EC_IOCTL_GET_SLVSTATISTICS

EC_IOCTL_GET_SLVSTATISTICS

Get slave statistics showing errors on Ethernet layer for slave id. Statistics are read on a regular basis (default: off).

Note

See also EC_IOCTL_SET_SLVSTAT_PERIOD, EC_IOCTL_FORCE_SLVSTAT_COLLECTION, EC_IOCTL_GET_SLVSTAT_PERIOD

Parameters

  • pbyInBuf – [in] Pointer to an EC_T_DWORD type variable containing the slave id

  • dwInBufSize – [in] Size of the input buffer provided at pbyInBuf in bytes

  • pbyOutBuf – [out] Pointer to struct EC_T_SLVSTATISTICS_DESC

  • dwOutBufSize – [in] Size of the output buffer provided at pbyOutBuf in bytes

  • pdwNumOutData – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.

Returns

EC_E_NOERROR or error code

struct EC_T_SLVSTATISTICS_DESC

Public Members

EC_T_BYTE abyInvalidFrameCnt[ESC_PORT_COUNT]

[out] Invalid Frame Counters per Slave Port

EC_T_BYTE abyRxErrorCnt[ESC_PORT_COUNT]

[out] RX Error Counters per Slave Port

EC_T_BYTE abyFwdRxErrorCnt[ESC_PORT_COUNT]

[out] Forwarded RX Error Counters per Slave Port

EC_T_BYTE byProcessingUnitErrorCnt

[out] Processing Unit Error Counter

EC_T_BYTE byPdiErrorCnt

[out] PDI Error Counter

EC_T_WORD wAlStatusCode

[out] AL Status Code

EC_T_BYTE abyLostLinkCnt[ESC_PORT_COUNT]

[out] Lost Link Counters per Slave Port

EC_T_UINT64 qwReadTime

[out] Timestamp of the last read [ns]

EC_T_UINT64 qwChangeTime

[out] Timestamp of the last counter change [ns]

See also

6.7.4. emGetSlaveStatistics

static EC_T_DWORD ecatGetSlaveStatistics(EC_T_DWORD dwSlaveId, EC_T_SLVSTATISTICS_DESC *pSlaveStatisticsDesc)
EC_T_DWORD emGetSlaveStatistics(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_SLVSTATISTICS_DESC *pSlaveStatisticsDesc)

Get Slave’s statistics counter.

Parameters

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

  • dwSlaveId – [in] Slave id

  • pSlaveStatisticsDesc – [out] Pointer to structure EC_T_SLVSTATISTICS_DESC

Returns

EC_E_NOERROR or error code

emGetSlaveStatistics() Example
/* get slave's statistics counters */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_SLVSTATISTICS_DESC oSlaveStatisticsDesc;
OsMemset(&oSlaveStatisticsDesc, 0, sizeof(EC_T_SLVSTATISTICS_DESC));
dwRes = dwSlaveId;
dwRes = emGetSlaveStatistics(dwInstanceId, dwSlaveId, &oSlaveStatisticsDesc);

See also

6.7.5. emIoCtl - EC_IOCTL_CLR_SLVSTATISTICS

EC_IOCTL_CLR_SLVSTATISTICS

Clear slave statistics in slaves.

Parameters

  • pbyInBuf – [in] Should be set to EC_NULL

  • dwInBufSize – [in] Should be set to 0

  • pbyOutBuf – [out] Should be set to EC_NULL

  • dwOutBufSize – [in] Should be set to 0

  • pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

6.7.6. emClearSlaveStatistics

static EC_T_DWORD ecatClearSlaveStatistics(EC_T_DWORD dwSlaveId)
EC_T_DWORD emClearSlaveStatistics(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId)

Clears all error registers of a slave.

Parameters

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

  • dwSlaveId – [in] Slave Id, INVALID_SLAVE_ID clears all slaves

Returns

EC_E_NOERROR or error code

emClearSlaveStatistics() Example
/* clear all error counters at slave */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
dwRes = emClearSlaveStatistics(dwInstanceId, dwSlaveId);

See also

emGetSlaveId()

6.7.7. emIoCtl - EC_IOCTL_GET_SLVSTAT_PERIOD

EC_IOCTL_GET_SLVSTAT_PERIOD

Get Slave Statistics read period [ms] (EC_T_DWORD). 0: disable.

Note

See EC_IOCTL_SET_SLVSTAT_PERIOD.

Parameters

  • pbyInBuf – [in] Should be set to EC_NULL

  • dwInBufSize – [in] Should be set to 0

  • pbyOutBuf – [out] Slave Statistics read period [ms] (EC_T_DWORD)

  • dwOutBufSize – [in] Size of the output buffer provided at pbyOutBuf in bytes

  • pdwNumOutData – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.

Returns

EC_E_NOERROR or error code

6.7.8. emIoCtl - EC_IOCTL_SET_SLVSTAT_PERIOD

EC_IOCTL_SET_SLVSTAT_PERIOD

Set Slave Statistics read period [ms] (EC_T_DWORD). 0: disable.

Note

Triggers an immediate read.

Parameters

  • pbyInBuf – [in] Slave Statistics read period [ms] (EC_T_DWORD)

  • dwInBufSize – [in] Size of the input buffer 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

Returns

EC_E_NOERROR or error code

6.7.9. emIoCtl - EC_IOCTL_FORCE_SLVSTAT_COLLECTION

EC_IOCTL_FORCE_SLVSTAT_COLLECTION

Trigger slave statistics read.

Parameters

  • pbyInBuf – [in] Should be set to EC_NULL

  • dwInBufSize – [in] Should be set to 0

  • pbyOutBuf – [out] Should be set to EC_NULL

  • dwOutBufSize – [in] Should be set to 0

  • pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

6.7.10. emIoCtl - EC_IOCTL_CLEAR_MASTER_INFO_COUNTERS

EC_IOCTL_CLEAR_MASTER_INFO_COUNTERS

Reset Master Info Counters according to given bit masks.

Parameters

  • pbyInBuf – [in] Pointer to a value of EC_T_CLEAR_MASTER_INFO_COUNTERS_PARMS

  • dwInBufSize – [in] Size of the input buffer 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

Returns

EC_E_NOERROR or error code

struct EC_T_CLEAR_MASTER_INFO_COUNTERS_PARMS

Public Members

EC_T_DWORD dwClearBusDiagnosisCounters

[in] Bit 0..7: Clear corresponding Counter ID:

  • Bit 0: Clear all Counters

  • Bit 1: Clear Tx Frame Counter

  • Bit 2: Clear Rx Frame Counter

  • Bit 3: Clear Lost Frame Counter

  • Bit 4: Clear Cyclic Frame Counter

  • Bit 5: Clear Cyclic Datagram Counter

  • Bit 6: Clear Acyclic Frame Counter

  • Bit 7: Clear Acyclic DataGram Counter

  • Bit 8: Clear Cyclic Lost Frame Counter

  • Bit 9: Clear Acyclic Lost Frame Counter

EC_T_UINT64 qwMailboxStatisticsClearCounters

[in] Bit 0..56: Clear corresponding Counter ID.

  • Bit 0..7: Clear AoE statistics

    • Bit 0: Total Read Transfer Count

    • Bit 1: Read Transfer Count Last Second

    • Bit 2: Total Bytes Read

    • Bit 3: Bytes Read Last Second

    • Bit 4: Total Write Transfer Count

    • Bit 5: Write Transfer Count Last Second

    • Bit 6: Total Bytes Write

    • Bit 7: Bytes Write Last Second

  • Bit 8..15: Clear CoE statistics (same ordering as Bit 0..7, AoE)

  • Bit 16..23: Clear EoE statistics (same ordering as Bit 0..7, AoE)

  • Bit 24..31: Clear FoE statistics (same ordering as Bit 0..7, AoE)

  • Bit 32..39: Clear SoE statistics (same ordering as Bit 0..7, AoE)

  • Bit 40..47: Clear VoE statistics (same ordering as Bit 0..7, AoE)

  • Bit 48..55: Clear RawMbx statistics (same ordering as Bit 0..7, AoE) 

qwMailboxStatisticsClearCounters = 0x0000000100; //Clear CoE Total Read Transfer Count.

6.7.11. emIoCtl - EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK

EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK

Enable or disable EC_NOTIFY_FRAME_RESPONSE_ERROR for specific errors.

Note

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_DEFAULT: all errors except EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_NON_ECAT_FRAME enabled.

Parameters

  • pbyInBuf – [in] Error enable bit mask (EC_T_DWORD)

  • dwInBufSize – [in] Size of the input buffer 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

Returns

EC_E_NOERROR or error code

The following frame response error notification mask values exist:

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_UNDEFINED

Mask for eRspErr_UNDEFINED notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_NO_RESPONSE

Mask for eRspErr_NO_RESPONSE notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_WRONG_IDX

Mask for eRspErr_WRONG_IDX notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_UNEXPECTED

Mask for eRspErr_UNEXPECTED notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_FRAME_RETRY

Mask for eRspErr_FRAME_RETRY notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_RETRY_FAIL

Mask for eRspErr_RETRY_FAIL notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_FOREIGN_SRC_MAC

Mask for eRspErr_FOREIGN_SRC_MAC notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_NON_ECAT_FRAME

Mask for eRspErr_NON_ECAT_FRAME notifications

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_ALL

Mask for all notifications enabled except eRspErr_NON_ECAT_FRAME

EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_DEFAULT

Mask for all frame response error notifications

See also

emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR

6.7.12. emIoCtl - EC_IOCTL_SET_FRAME_LOSS_SIMULATION

Important

Do not activate this on shipped releases. Frameloss has significant influence on performance and reliablility of the application!

EC_IOCTL_SET_FRAME_LOSS_SIMULATION

This IO Control enables the application to simulate the loss of sent and/or received EtherCAT frames for testing purposes. Three modes of operation are possible: Random, periodic or random periodic frame loss simulation.

  • Random frame loss simulation: For each frame the dwFrameLossLikelihoodPpm parameter determines whether the frame will be discarded.

  • Periodic frame loss simulation: After dwFixedLossNumLostFrames discarded frames, dwFixedLossNumGoodFrames frames will be processed.

  • Random periodic frame loss simulation: The dwFrameLossLikelihoodPpm parameter determines whether a periodic frame loss sequence is triggered.

Parameters

  • pbyInBuf – [in] Array of four EC_T_DWORDs (arrDword)

  • dwInBufSize – [in] Size of the input buffer 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

Returns

EC_E_NOERROR or error code

The parameters configurable are :

  • arrDword [0] -> dwNumGoodFramesAfterStart

    Number of good frames before frame loss simulation starts

  • arrDword [1] -> dwFrameLossLikelihoodPpm

    Random loss simulation: frame loss likelihood (ppm)

  • arrDword [2] -> dwFixedLossNumGoodFrames

    Fixed loss simulation: number of good frames before frame loss

  • arrDword [3] -> dwFixedLossNumLostFrames

    Fixed loss simulation: number of lost frames after processing the good ones

6.7.13. emIoCtl - EC_IOCTL_SET_RXFRAME_LOSS_SIMULATION

EC_IOCTL_SET_RXFRAME_LOSS_SIMULATION

Same as EC_IOCTL_SET_FRAME_LOSS_SIMULATION but only enables receive direction frame losses.

Parameters

  • pbyInBuf – [in] Should be set to EC_NULL

  • dwInBufSize – [in] Should be set to 0

  • pbyOutBuf – [out] Should be set to EC_NULL

  • dwOutBufSize – [in] Should be set to 0

  • pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

6.7.14. emIoCtl - EC_IOCTL_SET_TXFRAME_LOSS_SIMULATION

EC_IOCTL_SET_TXFRAME_LOSS_SIMULATION

Same as EC_IOCTL_SET_FRAME_LOSS_SIMULATION but only enables transmit direction frame losses.

Parameters

  • pbyInBuf – [in] Should be set to EC_NULL

  • dwInBufSize – [in] Should be set to 0

  • pbyOutBuf – [out] Should be set to EC_NULL

  • dwOutBufSize – [in] Should be set to 0

  • pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

6.7.15. Error notifications - general information

For each error an error ID (error code) will be defined. This error ID will be used as the notification code when emNotify() is called. In addition to this notification code the second parameter given to emNotify() contains a pointer to an error notification descriptor of type EC_T_ERROR_NOTIFICATION_DESC. This error notification descriptor contains detailed information about the error.

struct EC_T_ERROR_NOTIFICATION_DESC

Public Members

EC_T_DWORD dwNotifyErrorCode

Error ID (same value as the notification code)

EC_T_CHAR achErrorInfo[MAX_ERRINFO_STRLEN]

Additional error string (may be empty)

union _EC_T_ERROR_NOTIFICATION_PARM

Public Members

EC_T_WKCERR_DESC WkcErrDesc

WKC error descriptor

EC_T_FRAME_RSPERR_DESC FrameRspErrDesc

Frame response error descriptor

EC_T_INITCMD_ERR_DESC InitCmdErrDesc

Master/Slave init command error descriptor

EC_T_SLAVE_ERROR_INFO_DESC SlaveErrInfoDesc

Slave Error Info Descriptor

EC_T_SLAVES_ERROR_DESC SlavesErrDesc

Slaves Error Descriptor

EC_T_MBOX_SDO_ABORT_DESC SdoAbortDesc

SDO Abort

EC_T_RED_CHANGE_DESC RedChangeDesc

Redundancy Descriptor

EC_T_MBOX_FOE_ABORT_DESC FoeErrorDesc

FoE error code and string

EC_T_MBXRCV_INVALID_DATA_DESC MbxRcvInvalidDataDesc

Invalid mailbox data received descriptor

EC_T_PDIWATCHDOG_DESC PdiWatchdogDesc

PDI watchdog expired

EC_T_SLAVE_NOTSUPPORTED_DESC SlaveNotSupportedDesc

Slave not supported

EC_T_SLAVE_UNEXPECTED_STATE_DESC SlaveUnexpectedStateDesc

Slave in unexpected state

EC_T_SLAVES_UNEXPECTED_STATE_DESC SlavesUnexpectedStateDesc

Slaves in unexpected state

EC_T_EEPROM_CHECKSUM_ERROR_DESC EEPROMChecksumErrorDesc

EEPROM checksum error

EC_T_JUNCTION_RED_CHANGE_DESC JunctionRedChangeDesc

Junction redundancy change descriptor

EC_T_FRAMELOSS_AFTER_SLAVE_NTFY_DESC FramelossAfterSlaveDesc

Frameloss after Slave descriptor

EC_T_S2SMBX_ERROR_DESC S2SMbxErrorDesc

S2S Mailbox Error descriptor

EC_T_BAD_CONNECTION_NTFY_DESC BadConnectionDesc

Bad connection descriptor

EC_T_COMMUNICATION_TIMEOUT_NTFY_DESC CommunicationTimeoutDesc

Communication timeout descriptor

EC_T_TAP_LINK_STATUS_NTFY_DESC TapLinkStatusDesc

Tap link status

If the pointer to this descriptor exists (is not set to EC_NULL) the detailed error information (e.g. information about the SubDevice) is stored in the appropriate structure of a union. These error information structures are described in the following sections.

The EtherCAT® MainDevice will call emNotify() every time an error is detected. In some cases this will lead to calling this function in every EtherCAT® cycle (e.g. if there is no physical connection to a SubDevice). Using the control interface emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED it is possible to determine which errors shall be signalled and which not.

6.7.16. emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR

To update the process data some EtherCAT® commands will be sent cyclically by the MainDevice. These commands will address one or multiple SubDevices. These EtherCAT® commands contain a working counter which has to be incremented by each SubDevice that is addressed. The working counter will be checked after the EtherCAT® command is received by the MainDevice. If the expected working counter does not match the working counter of the received command the error emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR will be indicated. The working counter value expected by the MainDevice is determined by the EtherCAT® configuration (XML) file for each cyclic EtherCAT® command (section Config/Cyclic/Frame/Cmd/Cnt). Detailed error information is stored in the structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.

This notification is enabled by default.

struct EC_T_WKCERR_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties, content is undefined in case of cyclic WKC_ERROR

EC_T_BYTE byCmd

EtherCAT command type

EC_T_DWORD dwAddr

Logical address or physical address (ADP/ADO)

EC_T_WORD wWkcSet

Working counter set value

EC_T_WORD wWkcAct

Working counter actual value

EC_T_DWORD dwTaskId

Cyclic Task ID (ENI: Cyclic/TaskId)

EC_T_WORD wMsuId

Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd)

struct EC_T_SLAVE_PROP

Public Members

EC_T_WORD wStationAddress

Configured station address or INVALID_FIXED_ADDR

EC_T_WORD wAutoIncAddr

Configured auto increment address or INVALID_AUTO_INC_ADDR

EC_T_CHAR achName[MAX_STD_STRLEN]

Configured name of the slave device (NULL terminated string)

See also

6.7.17. emNotify - EC_NOTIFY_MASTER_INITCMD_WKC_ERROR

This error will be indicated in case of a working counter mismatch when sending MainDevice init commands. The working counter value expected by the MainDevice is determined by the EtherCAT® configuration (XML) file for each MainDevice init command (section Config/Master/InitCmds/InitCmd/Cnt). In case there is no “Cnt” entry in the XML file for this init command there will be no working counter verification. The working counter has to be incremented by all SubDevices which have to process this init command.

Detailed error information is stored in the structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.

6.7.18. emNotify - EC_NOTIFY_SLAVE_INITCMD_WKC_ERROR

This error will be indicated in case of a working counter mismatch when sending SubDevice init commands. The working counter value expected by the MainDevice is determined by the EtherCAT® configuration (XML) file for each SubDevice init command (section Config/Slave/InitCmds/InitCmd/Cnt). In case there is no “Cnt” entry in the XML file for this init command there will be no working counter verification.

Detailed error information is stored in the structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding SubDevice.

6.7.19. emNotify - EC_NOTIFY_FOE_MBSLAVE_ERROR

This error will be indicated in case a SubDevice notifies an error over FoE.

6.7.20. emNotify - EC_NOTIFY_EOE_MBXSND_WKC_ERROR

This error will be indicated in case the working counter of an EoE mailbox write command was not set to the expected value of 1.

Detailed error information is stored in the structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding SubDevice.

6.7.21. emNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR

This error will be indicated in case the working counter of a CoE mailbox write command was not set to the expected value of 1.

Detailed error information is stored in the structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding SubDevice.

6.7.22. emNotify - EC_NOTIFY_FOE_MBXSND_WKC_ERROR

This error will be indicated in case the working counter of an FoE mailbox write command was not set to the expected value of 1.

6.7.23. emNotify - EC_NOTIFY_VOE_MBXSND_WKC_ERROR

This error will be indicated in case the working counter of a VoE mailbox write command was not set to the expected value of 1.

Detailed error information is stored in the structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding SubDevice.

6.7.24. emNotify - EC_NOTIFY_S2SMBX_ERROR

This error will be indicated in case a SubDevice-To-SubDevice mailbox transfer fails.

See also

EC_E_S2SMBX_NOT_CONFIGURED

6.7.25. emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR

This error will be indicated if the received Ethernet frame does not match the frame expected or if an expected frame was not received.

This notification is enabled by default.

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation.

Missing response (timeout, eRspErr_NO_RESPONSE/ eRspErr_FRAME_RETRY) acyclic frames: Acyclic Ethernet frames are internally queued by the MainDevice and sent to the SubDevices at a later time (usually after sending cyclic frames). The MainDevice will monitor the time between queueing such a frame and receiving the result. If a maximum time is exceeded then this error will be indicated. This maximum time will be determined by the parameter dwEcatCmdTimeout when the MainDevice is initialized.

See also

emInitMaster()

The MainDevice will retry sending the frame if the MainDevice configuration parameter dwEcatCmdMaxRetries is set to a value greater than 1. In case of a retry the eRspErr_FRAME_RETRY error is signalled, if the number of retries has elapsed the eRspErr_NO_RESPONSE error is signalled.

Possible reasons:

  1. the frame was not received at all (due to bus problems)

    In this case the achErrorInfo member of the error notification descriptor will contain the string “L”.

  2. the frame was sent too late by the MainDevice due to an improper configuration.

    In this case the achErrorInfo member of the error notification descriptor will contain the string “T”.

    To avoid this error the configuration may be changed as follows:

    -> higher value for MainDevice configuration parameter dwMaxAcycCmdsPerCycle -> shorter MainDevice timer cycle, i.e. shorter period between two calls to

    emExecJob(eUsrJob_MasterTimer)

    -> higher timeout value (MainDevice configuration parameter dwEcatCmdTimeout)

If the frame was sent too late by the MainDevice (due to improper configuration values) it will also be received too late and the MainDevice then signals an eRspErr_WRONG_IDX or eRspErr_UNEXPECTED error (as the MainDevice then doesn’t expect to receive this frame).

Missing response (timeout, eRspErr_NO_RESPONSE) cyclic frames:

A response to all cyclic frames must occur until the next cycle starts. If the first cyclic frame is sent the MainDevice checks whether all cyclic frames of the last cycle were received. If there is one frame missing this error is indicated.

Possible reasons:

  1. the frame was not received (due to bus problems)

  2. too many or too long acyclic frames are sent in between sending cyclic frames by the MainDevice due to an improper configuration, to avoid these error notifications the configuration may be changed as follows:
  3. non-deterministic sending of acyclic frames.

    Sending acyclic frames by calling emExecJob() ( eUsrJob_SendAcycFrames) has to be properly scheduled with sending cyclic frames by calling emExecJob() ( eUsrJob_SendAllCycFrames).

Using the control interface emIoCtl - EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK it is possible to determine which response errors shall be signalled and which not.

Detailed error information is stored in the structure EC_T_FRAME_RSPERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.

struct EC_T_FRAME_RSPERR_DESC

Public Members

EC_T_BOOL bIsCyclicFrame

Indicates whether the lost frame was a cyclic frame

EC_T_FRAME_RSPERR_TYPE EErrorType

Frame response error type

EC_T_BYTE byEcCmdHeaderIdxSet

Expected IDX value, this value is valid only for acyclic frames in case EErrorType is not equal to eRspErr_UNEXPECTED

EC_T_BYTE byEcCmdHeaderIdxAct

Actually received IDX value, this value is only valid for acyclic frames in case of EErrorType is equal to: eRspErr_WRONG_IDX and eRspErr_UNEXPECTED

EC_T_WORD wCycFrameNum

Number of the lost cyclic frame from the ENI

EC_T_DWORD dwTaskId

Cyclic Task ID (ENI: Cyclic/TaskId). Only valid if bIsCyclicFrame is set

enum EC_T_FRAME_RSPERR_TYPE

Values:

enumerator eRspErr_UNDEFINED

Undefined

enumerator eRspErr_NO_RESPONSE

No Ethernet frame received (timeout, frame loss)

enumerator eRspErr_WRONG_IDX

Wrong IDX value in acyclic frame

enumerator eRspErr_UNEXPECTED

Unexpected frame was received

enumerator eRspErr_FRAME_RETRY

Ethernet frame will be re-sent (timeout, frame loss)

enumerator eRspErr_RETRY_FAIL

All retry mechanism fails to re-sent acyclic frames

enumerator eRspErr_FOREIGN_SRC_MAC

Frame with MAC from other Master received

enumerator eRspErr_NON_ECAT_FRAME

Non EtherCAT frame received

enumerator eRspErr_CRC

Ethernet frame with CRC error received

enumerator eRspErr_ETHERNET_PAUSE_FRAME

Ethernet pause frame (flow control) received

6.7.26. emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR

This error code will be indicated if a SubDevice does not respond appropriately while sending SubDevice init commands. The SubDevice init commands are defined in the EtherCAT® configuration (XML) file (Config/Slave/InitCmds/InitCmd). A timeout value for these commands may also be defined in the configuration file (Config/Slave/InitCmds/InitCmd/Timeout). If there is no timeout value defined here the frame response is expected within one single cycle.

This notification is enabled by default.

Detailed error information is stored in the structure EC_T_INITCMD_ERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.

struct EC_T_INITCMD_ERR_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_CHAR achStateChangeName[MAX_SHORT_STRLEN]

State change description when the error occurred

EC_T_INITCMD_ERR_TYPE EErrorType

Init command error type

EC_T_CHAR szComment[MAX_STD_STRLEN]

Comment (ENI)

enum EC_T_INITCMD_ERR_TYPE

Values:

enumerator eInitCmdErr_NO_ERROR

No error

enumerator eInitCmdErr_NO_RESPONSE

No Ethernet frame received (timeout)

enumerator eInitCmdErr_VALIDATION_ERR

Validation error (invalid slave command response)

enumerator eInitCmdErr_FAILED

Init commands failed (state could not be reached)

enumerator eInitCmdErr_NOT_PRESENT

Slave not present on the bus

enumerator eInitCmdErr_ALSTATUS_ERROR

Error in AL Status Register

enumerator eInitCmdErr_MBXSLAVE_ERROR

Error at Mailbox Init Command

enumerator eInitCmdErr_PDI_WATCHDOG

PDI watchdog has been detected

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.7.27. emNotify - EC_NOTIFY_MBSLAVE_INITCMD_TIMEOUT

This error is identical to error code emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR but it will be indicated in case of timeouts when processing mailbox init commands.

The timeout value used for CoE mailbox SubDevice is defined in the EtherCAT® configuration (XML) file (Config/Slave/Mailbox/CoE/InitCmds/InitCmd/Timeout). In case this value is set to 0 a fixed timeout value of 500 ms will be used by the EtherCAT® MainDevice. The timeout value used for EoE mailbox SubDevices will be set to a fixed value of 5000 ms.

6.7.28. emNotify - EC_NOTIFY_MASTER_INITCMD_RESPONSE_ERROR

This error code will be indicated if a missing or wrong command response was detected while sending MainDevice init commands. The MainDevice init commands are defined in the EtherCAT® configuration (XML) file (Config/Master/InitCmds/InitCmd). A timeout value for these commands may also be defined in the configuration file (Config/Master/InitCmds/InitCmd/Timeout). If there is no timeout value defined here the frame response is expected within one single cycle.

Detailed error information is stored in the structure EC_T_INITCMD_ERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.

6.7.29. emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL

When processing cyclic frames the EtherCAT® MainDevice checks whether all SubDevices are still in OPERATIONAL state. If at least one SubDevice is not OPERATIONAL this error will be indicated.

6.7.30. emNotify - EC_NOTIFY_ALL_DEVICES_OPERATIONAL

When processing cyclic frames the EtherCAT® MainDevice checks whether all SubDevices are still in OPERATIONAL state. This will be notified after emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL and all the SubDevices are back in OPERATIONAL state.

6.7.31. emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR

When processing cyclic frames the EtherCAT® MainDevice checks if at least one SubDevice has the ERROR bit in the AL-STATUS register set. In that case this error will be indicated. The MainDevice will then automatically determine detailed error information of the SubDevice(s) indicating an error and acknowledge the error status. The application will get an emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO notification for each such SubDevice. Usually those SubDevices will enter safe-operational state in this case. It is the application’s response how to further handle such error cases.

This notification is enabled by default.

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.7.32. emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO

Every time the MainDevice detects a SubDevice error, the Error bit on the specific SubDevice is cleared and this error code will be signalled to the application. Detailed error information is stored in the structure EC_T_SLAVE_ERROR_INFO_DESC of EC_T_ERROR_NOTIFICATION_DESC. This notification is enabled by default.

struct EC_T_SLAVE_ERROR_INFO_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_WORD wStatus

Slave Status (AL Status)

EC_T_WORD wStatusCode

Error status code (AL STATUS CODE)

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.7.33. emNotify - EC_NOTIFY_SLAVES_ERROR_STATUS

This notification collects notifications of type emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO. Notification is given on either collection full or MainDevice state changed whatever comes first.

This notification is disabled by default.

struct EC_T_SLAVES_ERROR_DESC

Public Members

EC_T_WORD wCount

Number of slave errors

EC_T_SLAVES_ERROR_DESC_ENTRY SlaveError[MAX_SLAVES_ERROR_NTFY_ENTRIES]

Slave error descriptions

struct EC_T_SLAVES_ERROR_DESC_ENTRY

Public Members

EC_T_WORD wStationAddress

Slave station address

EC_T_WORD wStatus

Slave status (AL Status)

EC_T_WORD wStatusCode

Slave status code (AL Control Status)

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation

6.7.34. emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE

This error is signalized every time a SubDevice changes into an unexpected state. Detailed error information is stored in the structure EC_T_SLAVE_UNEXPECTED_STATE_DESC of EC_T_ERROR_NOTIFICATION_DESC. This notification is enabled by default.

struct EC_T_SLAVE_UNEXPECTED_STATE_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_STATE curState

Current state

EC_T_STATE expState

Expected state

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.7.35. emNotify - EC_NOTIFY_SLAVES_UNEXPECTED_STATE

This notification collects notifications of type emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE. Notification is given on either collection full or MainDevice state changed whatever comes first. This notification is disabled by default.

struct EC_T_SLAVES_UNEXPECTED_STATE_DESC

Public Members

EC_T_WORD wCount

Number of unexpected slave state changes

EC_T_SLAVES_UNEXPECTED_STATE_DESC_ENTRY SlaveStates[MAX_SLAVES_UNEXPECTED_STATE_NTFY_ENTRIES]

Slave state change descriptions

struct EC_T_SLAVES_UNEXPECTED_STATE_DESC_ENTRY

Public Members

EC_T_WORD wStationAddress

Slave station address

EC_T_STATE curState

Current state

EC_T_STATE expState

Expected state

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation

6.7.38. emNotify - EC_NOTIFY_CLIENTREGISTRATION_DROPPED

This notification will be indicated if the client registration was dropped because emConfigureNetwork() was called by another thread. The notification has the following parameter:

EC_T_DWORD dwDeinitForConfiguration; /* 0 = terminating MainDevice, 1 = restarting MainDevice */

6.7.39. emNotify - EC_NOTIFY_EEPROM_CHECKSUM_ERROR

This error is signalized every time an EEPROM checksum error is detected.

Detailed error information is stored in the structure EC_T_EEPROM_CHECKSUM_ERROR_DESC of EC_T_ERROR_NOTIFICATION_DESC.

struct EC_T_EEPROM_CHECKSUM_ERROR_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

6.7.40. emNotify - EC_NOTIFY_MBXRCV_INVALID_DATA

This error is signalized when invalid mailbox data have been received from SubDevice. Detailed error information is stored in structure EC_T_MBXRCV_INVALID_DATA_DESC of EC_T_ERROR_NOTIFICATION_DESC.

struct EC_T_MBXRCV_INVALID_DATA_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

6.7.41. emNotify - EC_NOTIFY_PDIWATCHDOG

This error is signalized every time a PDI watchdog error is detected. Detailed error information is stored in the structure EC_T_PDIWATCHDOG_DESC of EC_T_ERROR_NOTIFICATION_DESC.

struct EC_T_PDIWATCHDOG_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

6.7.42. ecatGetText

const EC_T_CHAR *ecatGetText(EC_T_DWORD dwTextId)

6.7.43. emLogFrameEnable

static EC_T_DWORD ecatLogFrameEnable(EC_T_PFLOGFRAME_CB pvLogFrameCallBack, EC_T_VOID *pvContext)
EC_T_DWORD emLogFrameEnable(EC_T_DWORD dwInstanceID, EC_T_PFLOGFRAME_CB pvLogFrameCallBack, EC_T_VOID *pvContext)

Setup a callback function to log the EtherCAT network traffic.

The callback function is called by the cyclic task. Therefore the code inside the callback has to be fast and non-blocking. The callback parameter dwLogFlags can be used as a filter to log just specific frames. The master discards the frame if the callback function modifies the Ethernet frame type at byte offset 12.

Parameters

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

  • pvLogFrameCallBack – [in] Pointer to frame logging callback function

  • pvContext – [in] Pointer to function specific context

Returns

EC_E_NOERROR or error code

typedef EC_T_VOID (*EC_T_PFLOGFRAME_CB)(EC_T_VOID *pvContext, EC_T_DWORD dwLogFlags, EC_T_DWORD dwFrameSize, EC_T_BYTE *pbyFrame)

Note

The master discards the frame if the callback function modifies the Ethernet frame type at byte offset 12.

Param pvContext

[in] Arbitrarily application-defined parameter passed to callback

Param dwLogFlags

[in] Frame logging flags, EC_LOG_FRAME_FLAG_…

Param dwFrameSize

[in] Size of frame in bytes

Param pbyFrame

[in] Pointer to frame data

EC_LOG_FRAME_FLAG_MASTERSTATE_MASK

Bit 0 to 15: Master state mask

EC_LOG_FRAME_FLAG_ACYC_FRAME

Bit 16 (0x00010000): 0=cyclic frame, 1=acyclic frame

EC_LOG_FRAME_FLAG_DBG_FRAME

Bit 17 (0x00020000): 0=EtherCAT frame, 1=debug frame

EC_LOG_FRAME_FLAG_RED_FRAME

Bit 18 (0x00040000): 0=main frame, 1=red frame

EC_LOG_FRAME_FLAG_RX_FRAME

Bit 19 (0x00080000): 0=TX frame, 1=RX frame

EC_LOG_FRAME_FLAG_MASTER_RED_FRAME

Bit 20 (0x00100000): 0=slave frame, 1=MasterMaster frame 

/********************************************************************************/
/** \brief  Handler to log frames.
*
*   CAUTION: Called by cyclic task!!! Do not consume to much CPU time!!!
*/
EC_T_VOID LogFrameHandler(EC_T_VOID* pvContext, EC_T_DWORD dwLogFlags, EC_T_DWORD dwFrameSize, EC_T_BYTE* pbyFrame)
{
    EC_T_STATE         eMasterState;

    /* get MainDevice state */
    eMasterState = (EC_T_STATE)(dwLogFlags & EC_LOG_FRAME_FLAG_MASTERSTATE_MASK);

    /* skip tx frame */
    if ((S_dwLogFrameLevel == 3) && !(dwLogFlags & EC_LOG_FRAME_FLAG_RX_FRAME))
        return;

    /* skip cyclic frame */
    if ((S_dwLogFrameLevel == 2) && !(dwLogFlags & EC_LOG_FRAME_FLAG_ACYC_FRAME))
        return;

    /* skip red frame */
    if (dwLogFlags & EC_LOG_FRAME_FLAG_RED_FRAME)
        return;

    /* do something with pbyFrame ... */
}

6.7.44. emLogFrameDisable

static EC_T_DWORD ecatLogFrameDisable(EC_T_VOID)
EC_T_DWORD emLogFrameDisable(EC_T_DWORD dwInstanceID)

Disable the frame logging callback.

Parameters

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

Returns

EC_E_NOERROR or error code

6.7.45. emGetMasterInfo

static EC_T_DWORD ecatGetMasterInfo(EC_T_MASTER_INFO *pMasterInfo)
EC_T_DWORD emGetMasterInfo(EC_T_DWORD dwInstanceID, EC_T_MASTER_INFO *pMasterInfo)

Get generic information about the Master.

Parameters

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

  • pMasterInfo – [out] Master information

Returns

struct EC_T_MASTER_INFO

Public Members

EC_T_DWORD dwMasterVersion

Master version

EC_T_BUS_DIAGNOSIS_INFO BusDiagnosisInfo

Bus diagnostics

EC_T_MAILBOX_STATISTICS MailboxStatistics

Mailbox statistics

EC_T_REDUNDANCY_DIAGNOSIS_INFO RedundancyDiagnosisInfo

Redundancy diagnosis info

EC_T_DWORD dwMasterStateSummary

Master state summary

EC_T_DWORD dwMasterVersionType

Master version type. See EC_VERSION_TYPE

EC_T_WORD wMasterStateSummaryDiagBitOffset

Bit offset of Master state summary in diagnosis image

EC_T_WORD wMasterStateSummaryDiagBitSize

Bit offset size of Master state summary in diagnosis image

struct EC_T_BUS_DIAGNOSIS_INFO

Public Members

EC_T_DWORD dwCRC32ConfigCheckSum

CRC32 checksum of the loaded configuration

EC_T_DWORD dwNumSlavesFound

Number of slaves connected

EC_T_DWORD dwNumDCSlavesFound

Number of slaves with DC enabled connected

EC_T_DWORD dwNumCfgSlaves

Number of slaves in ENI

EC_T_DWORD dwNumMbxSlaves

Number of slaves in ENI with mailbox support

EC_T_DWORD dwTXFrames

Number of frames sent

EC_T_DWORD dwRXFrames

Number of frames received

EC_T_DWORD dwLostFrames

Number of lost frames

EC_T_DWORD dwCyclicFrames

Number of cyclic frames sent

EC_T_DWORD dwCyclicDatagrams

Number of cyclic datagrams / EtherCAT commands sent

EC_T_DWORD dwAcyclicFrames

Number of acyclic frames sent

EC_T_DWORD dwAcyclicDatagrams

Number of acyclic datagrams / EtherCAT commands sent

EC_T_DWORD dwClearCounters

Clear frame / datagram counter bit field

EC_T_DWORD dwCyclicLostFrames

Number of cyclic lost frames

EC_T_DWORD dwAcyclicLostFrames

Number of acyclic lost frames

struct EC_T_MAILBOX_STATISTICS

Public Members

EC_T_STATISTIC_TRANSFER_DUPLEX Aoe

AoE mailbox transfer statistics

EC_T_STATISTIC_TRANSFER_DUPLEX Coe

CoE mailbox transfer statistics

EC_T_STATISTIC_TRANSFER_DUPLEX Eoe

EoE mailbox transfer statistics

EC_T_STATISTIC_TRANSFER_DUPLEX Foe

FoE mailbox transfer statistics

EC_T_STATISTIC_TRANSFER_DUPLEX Soe

SoE mailbox transfer statistics

EC_T_STATISTIC_TRANSFER_DUPLEX Voe

VoE mailbox transfer statistics

EC_T_STATISTIC_TRANSFER_DUPLEX RawMbx

Raw mailbox transfer statistics

struct EC_T_STATISTIC_TRANSFER_DUPLEX

Public Members

EC_T_STATISTIC_TRANSFER Read

Number of read transfers

EC_T_STATISTIC_TRANSFER Write

Number of write transfers

struct EC_T_STATISTIC_TRANSFER

Public Members

EC_T_STATISTIC Cnt

Number of transfers

EC_T_STATISTIC Bytes

Number of bytes transferred

struct EC_T_STATISTIC

Public Members

EC_T_DWORD dwTotal

Total

EC_T_DWORD dwLast

Last

emGetMasterInfo() Example
EC_T_MASTER_INFO oMasterInfo;
OsMemset(&oMasterInfo, 0, sizeof(EC_T_MASTER_INFO));
dwRes = emGetMasterInfo(dwInstanceId, &oMasterInfo);

6.7.46. emGetMemoryUsage

static EC_T_DWORD ecatGetMemoryUsage(EC_T_DWORD *pdwCurrentUsage, EC_T_DWORD *pdwMaxUsage)
EC_T_DWORD emGetMemoryUsage(EC_T_DWORD dwInstanceID, EC_T_DWORD *pdwCurrentUsage, EC_T_DWORD *pdwMaxUsage)

Returns information about memory usage.

All calls to malloc/free and new/delete are monitored.

Parameters

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

  • pdwCurrentUsage – [out] Current memory usage in Bytes at the time where this function is called

  • pdwMaxUsage – [out] Maximum memory usage in Bytes since initialization at the time where this function is called

Returns

EC_E_NOERROR or error code

emGetMemoryUsage() Example
EC_T_DWORD dwCurrentUsage = EC_NULL;
EC_T_DWORD dwMaxUsage = EC_NULL;
dwRes = emGetMemoryUsage(dwInstanceId, &dwCurrentUsage, &dwMaxUsage);

6.7.47. emGetMasterDump

static EC_T_DWORD ecatGetMasterDump(EC_T_BYTE *pbyBuffer, EC_T_DWORD dwBufferSize, EC_T_DWORD *pdwDumpSize)
EC_T_DWORD emGetMasterDump(EC_T_DWORD dwInstanceID, EC_T_BYTE *pbyBuffer, EC_T_DWORD dwBufferSize, EC_T_DWORD *pdwDumpSize)

The dump contains relevant information about the master and slave status.

The dump is only intended for internal troubleshooting at acontis. Amongst others it contains the following descriptors:

The buffer is written until all relevant data have been dumped or the buffer size has been exceeded.

Parameters

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

  • pbyBuffer – [in] Preallocated buffer to dump log data

  • dwBufferSize – [in] Size of preallocated buffer

  • pdwDumpSize – [out] Size of master dump

Returns

emGetMasterDump() Example
EC_T_DWORD dwBufferSize = 8192;
EC_T_BYTE* byBuffer = (EC_T_BYTE*)OsMalloc(dwBufferSize);
EC_T_DWORD dwDumpSize = dwBufferSize;
dwRes = emGetMasterDump(dwInstanceId, byBuffer, dwBufferSize, &dwDumpSize);

6.7.48. emGetMasterSyncUnitInfoNumOf

static EC_T_DWORD ecatGetMasterSyncUnitInfoNumOf(EC_T_VOID)
EC_T_DWORD emGetMasterSyncUnitInfoNumOf(EC_T_DWORD dwInstanceID)

Get number of Master Sync Units info entries.

Parameters

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

Returns

Number of Master Sync Units info entries

emGetMasterSyncUnitInfoNumOf() Example
/* get Master Sync Units info entries count */
EC_T_DWORD dwSyncedUnitsCount = emGetMasterSyncUnitInfoNumOf(dwInstanceId);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, 
    "Units count: %d", dwSyncedUnitsCount));

6.7.49. emGetMasterSyncUnitInfo

static EC_T_DWORD ecatGetMasterSyncUnitInfo(EC_T_WORD wMsuId, EC_T_MSU_INFO *pMsuInfo)
EC_T_DWORD emGetMasterSyncUnitInfo(EC_T_DWORD dwInstanceID, EC_T_WORD wMsuId, EC_T_MSU_INFO *pMsuInfo)

Get information about a specific Master Sync Unit.

Parameters

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

  • wMsuId – [in] Master Sync Unit to get the information from

  • pMsuInfo – [out] Pointer to an EC_T_MSU_INFO structure receiving the Master Sync Unit information

Returns

EC_E_NOERROR or error code

MSU_ID_ALL_INFO_ENTRIES retrieves the information from all MainDevice sync units at once. The application must ensure that pMsuInfo is capable for all entries.

struct EC_T_MSU_INFO

Public Members

EC_T_WORD wMsuId

[out] Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd)

EC_T_DWORD dwBitOffsIn

[out] Process Data Image INPUTs bit offset

EC_T_DWORD dwBitSizeIn

[out] Process Data Image INPUTs bit length

EC_T_DWORD dwBitOffsOut

[out] Process Data Image OUTPUTs bit offset

EC_T_DWORD dwBitSizeOut

[out] Process Data Image OUTPUTs bit length

EC_T_WORD wWkcStateDiagOffsIn

[out] INPUTs WkcState bit offset in Diagnosis Image. (Bit values: 0 = Process Data valid, 1 = Process Data invalid)

EC_T_WORD wWkcStateDiagOffsOut

[out] OUTPUTs WkcState bit offset in Diagnosis Image. (Bit values: 0 = Process Data valid, 1 = Process Data invalid)

EC_T_DWORD adwReserved[16]

reserved

emGetMasterSyncUnitInfo() Example
/* get information about specific Master Sync Unit */
EC_T_WORD wMsuId = 0;
EC_T_MSU_INFO oMsuInfo;
OsMemset(&oMsuInfo, 0, sizeof(EC_T_MSU_INFO));
dwRes = emGetMasterSyncUnitInfo(dwInstanceId, wMsuId, &oMsuInfo);

See also

emGetMasterSyncUnitInfoNumOf()

6.7.50. emBadConnectionsDetect

static EC_T_DWORD ecatBadConnectionsDetect(EC_T_BOOL bRefreshSlaveStatistics, EC_T_DWORD dwTimeout)
EC_T_DWORD emBadConnectionsDetect(EC_T_DWORD dwInstanceID, EC_T_BOOL bRefreshSlaveStatistics, EC_T_DWORD dwTimeout)

Detects bad connections.

Analyzes the slave ESC error counters:

  • Invalid Frame Counter (0x0300),

  • RX Error Counter (0x0301),

  • Lost Link Counter (0x0310),

whether there is a problem in the area PHY - connector - cable - connector - PHY. If one of the above error counters shows a value not equal to zero, an EC_NOTIFY_BAD_CONNECTION is generated, which contains the exact position of the faulty connection.

It is recommended to call emBadConnectionsReset() on startup of EC-Master to ensure that all error counters of all slaves are in a defined state.

Parameters

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

  • bRefreshSlaveStatistics – [in] EC_TRUE: refresh ESC error counters, EC_FALSE: process current ESC error counters

  • dwTimeout – [in] Timeout [ms]. May not be EC_NOWAIT!

Returns

EC_E_NOERROR or error code

emBadConnectionsDetect() Example
dwRes = emBadConnectionsDetect(dwInstanceId, EC_TRUE, 5000 /* timeout */);

See also

emBadConnectionsReset()

6.7.51. emBadConnectionsReset

static EC_T_DWORD ecatBadConnectionsReset(EC_T_VOID)
static EC_T_DWORD emBadConnectionsReset(EC_T_DWORD dwInstanceID)

Clears all error counters (0x0300 - 0x0313) of all slaves.

Parameters

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

emBadConnectionsReset() Example
dwRes = emBadConnectionsReset(dwInstanceId);

6.7.52. emNotify - EC_NOTIFY_BAD_CONNECTION

This error is signalized every time a bad connection is detected within the call of emBadConnectionsDetect() or emSelfTestScan(). It contains the exact location of the bad connection between two SubDevices. This notification is enabled by default.

struct EC_T_BAD_CONNECTION_NTFY_DESC

Public Members

EC_T_SLAVE_PROP SlavePropParent

Slave properties of parent slave

EC_T_WORD wPortAtParent

Port at parent slave

EC_T_SLAVE_PROP SlavePropChild

Slave properties of child slave

EC_T_WORD wPortAtChild

Port at child slave

See also

6.7.53. emSelfTestScan

static EC_T_DWORD ecatSelfTestScan(EC_T_SELFTESTSCAN_PARMS *pParms)
EC_T_DWORD emSelfTestScan(EC_T_DWORD dwInstanceID, EC_T_SELFTESTSCAN_PARMS *pParms)

Self test scan.

Send a burst of numerous frames and analyze the slave connections. After deactivating the job task, frames will be sent as fast as the LinkLayer can send them. The size of the frames increases and decreases between the defined limits. Dependent on the parameters the BadConnectionsDetect API will analyze the slave connections.

Parameters

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

  • pParms – [in] Self-test scan parameters

Returns

struct EC_T_SELFTESTSCAN_PARMS

Public Members

EC_T_DWORD dwSize

[in] Set to sizeof(EC_T_SELFTESTSCAN_PARMS)

EC_T_DWORD dwTimeout

[in] Timeout [ms], 0 or EC_NOWAIT defaults to 500ms

EC_T_DWORD dwFrameCount

[in] Total number of frames sent during the self-test. Default value is 1500. A value of 0 sets the default value.

EC_T_DWORD dwFrameSizeMin

[in] Min frame size [bytes]. Default value is 60. A value of 0 sets the default value.

EC_T_DWORD dwFrameSizeMax

[in] Max frame size [bytes]. Default value is 1514. A value of 0 sets the default value.

EC_T_DWORD dwFrameSizeStep

[in] Size [bytes] by which the frame increases or decreases continuously during the self-test. Default value is 1. A value of 0 sets the default value.

EC_T_BOOL bDetectBadConnections

[in] Execute the bad connection detection after self-test

EC_T_UINT64 qwFrameRoundtripTimeAvg

[out] Roundtrip time average [us]. Time taken from sending to receiving the frame (master application level).

EC_T_UINT64 qwFrameRoundtripTimeMin

[out] Roundtrip time minimum [us]. Time taken from sending to receiving the frame (master application level).

EC_T_UINT64 qwFrameRoundtripTimeMax

[out] Roundtrip time maximum [us]. Time taken from sending to receiving the frame (master application level).

EC_T_BOOL bMeasureRoundtripTimeForSingleFrame

[in] Execute roundtrip time calculation for single frame

emSelfTestScan() Example
EC_T_SELFTESTSCAN_PARMS oParms;
OsMemset(&oParms, 0, sizeof(EC_T_SELFTESTSCAN_PARMS));
oParms.dwSize = sizeof(EC_T_SELFTESTSCAN_PARMS);
oParms.dwTimeout = 5000;
oParms.dwFrameCount = 1500;
oParms.dwFrameSizeMin = 60;
oParms.dwFrameSizeMax = 1514;
oParms.dwFrameSizeStep = 1;
oParms.bDetectBadConnections = EC_FALSE;
dwRes = emSelfTestScan(dwInstanceId, &oParms);

See also

emBadConnectionsDetect()