8.5. Diagnosis

In case of errors on the bus or in one or multiple slaves the EtherCAT monitor stack will notify the application about such an event.

The error notifications can be separated into two classes:

Slave unrelated errors

Notifications don’t contain this information even if one specific slave has caused an error. For example if one or multiple slaves 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.

Slave related errors

Notifications will also contain the information about which slave has generated an error.

Example Error Scenario

Slave is powered off or disconnected while bus is operational

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

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

Monitor calls emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR

  • Application gets informed

  • WKC State in Diagnosis Image changes

Use cases

  1. Slave is disconnected or powered off:
  2. Slave is re-connected or powered on:

8.5.1. emIoControl - EC_IOCTL_SB_STATUS_GET

This call will get the status of the last bus scan.

emIoControl - EC_IOCTL_SB_STATUS_GET
Parameter

  • pbyInBuf: [in] Should be set to EC_NULL

  • dwInBufSize: [in] Should be set to 0

  • pbyOutBuf: [out] Pointer to EC_T_SB_STATUS_NTFY_DESC.

  • dwOutBufSize: [in] Size of the output buffer in bytes.

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

Return

EC_E_NOERROR or error code

See also

emNotify - EC_NOTIFY_SB_STATUS

8.5.2. emIoControl - EC_IOCTL_GET_SLVSTATISTICS

Get Slave’s statistics counter. Counters are collected on a regularly base (default: off) and show errors on Ethernet Layer.

emIoControl - EC_IOCTL_GET_SLVSTATISTICS
Parameter

  • pbyInBuf: [in] Pointer to a 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.

Return

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]

8.5.3. emGetSlaveStatistics

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

See also

8.5.4. emIoControl - EC_IOCTL_CLR_SLVSTATISTICS

Clear all buffered error registers for all slaves. The actual counters on the slaves remain unchanged.

emIoControl - EC_IOCTL_CLR_SLVSTATISTICS
Parameter

  • 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

Return

EC_E_NOERROR or error code

8.5.5. emClearSlaveStatistics

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

Note

Only the buffered error register values are deleted. The actual counters on the slaves remain unchanged.

See also

emGetSlaveId()

8.5.6. emGetDiagnosisImagePtr

EC_T_BYTE *emGetDiagnosisImagePtr(EC_T_DWORD dwInstanceID)

Gets the diagnosis image pointer.

Parameters

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

Returns

Diagnosis image pointer

See also

8.5.7. emGetMasterSyncUnitInfoNumOf

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

8.5.8. emGetMasterSyncUnitInfo

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

Get information about 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 master 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

EC_T_DWORD dwBitOffsIn

[out] input bit offset of master sync unit in process data image

EC_T_DWORD dwBitSizeIn

[out] input bit size of master sync unit

EC_T_DWORD dwBitOffsOut

[out] output bit offset of master sync unit in process data image

EC_T_DWORD dwBitSizeOut

[out] output bit size of master sync unit

EC_T_WORD wWkcStateDiagOffsIn

[out] Offset of WkcState bit in diagnosis image WkcState bit values: 0 = Data Valid, 1 = Data invalid

EC_T_WORD wWkcStateDiagOffsOut

[out] Offset of WkcState bit in diagnosis image WkcState bit values: 0 = Data Valid, 1 = Data invalid

EC_T_DWORD adwReserved[16]

reserved

See also

emGetMasterSyncUnitInfoNumOf()