8. Generic notification interface

One of the parameters the client has to set when registering with the EC-Monitor is a generic notification callback function ( emNotify()). This function is called every time an event occurs about which the client needs to be informed.

Within this callback function the client must not call any active EtherCAT functions which finally would lead to send EtherCAT commands (e.g. initiation of mailbox transfers, starting/stopping the master, sending raw commands). In such cases the behavior is undefined. Only EtherCAT functions which are explicitly marked to be callable within emNotify() may be called.

This callback function is usually called in the context of the EC-Monitor timer thread or the EtherCAT Link Layer receiver thread. To avoid dead-lock situations the notification callback handler may not use mutex semaphores.

As the whole EtherCAT operation is blocked while calling this function the error handling must not use much CPU time or even call operating system functions that may block. Usually the error handling will be done in a separate application thread.

8.1. Notification callback

typedef EC_T_DWORD (*EC_PF_NOTIFY)(EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)
struct EC_T_NOTIFYPARMS

Public Members

EC_T_VOID *pCallerData

[in] Client depending caller data parameter. This pointer is one of the parameters when the client registers

EC_T_BYTE *pbyInBuf

[in] Notification input parameters

EC_T_DWORD dwInBufSize

[in] Size of input buffer in byte

EC_T_BYTE *pbyOutBuf

[out] Notification output (result)

EC_T_DWORD dwOutBufSize

[in] Size of output buffer in byte

EC_T_DWORD *pdwNumOutData

[out] Amount of bytes written to the output buffer

8.2. emNotifyApp

By calling this function the generic notification callback function setup by emRegisterClient() is called.

EC_T_DWORD emNotifyApp(EC_T_DWORD dwInstanceID, EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)

Notify application.

By calling this function the generic notification callback function setup by emRegisterClient() is called. The maximum value for dwCode is defined by EC_NOTIFY_APP_MAX_CODE.

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

  • dwCode – [in] Application specific notification code

  • pParms – [in] Parameters for application notification.

Returns

EC_E_NOERROR or error code

The maximum value for dwCode is defined by EC_NOTIFY_APP_MAX_CODE

8.3. Enable/Disable notifications

All notifications can be enabled or disabled. By default, all notifications are enabled except for:
  • EC_NOTIFY_SLAVE_STATECHANGED

  • EC_NOTIFY_SLAVES_STATECHANGED

  • EC_NOTIFY_SLAVES_PRESENCE

  • EC_NOTIFY_REFCLOCK_PRESENCE

  • EC_NOTIFY_SLAVES_UNEXPECTED_STATE

  • EC_NOTIFY_SLAVES_ERROR_STATUS

  • EC_NOTIFY_COE_INIT_CMD

8.3.1. emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED

Set notification enabled state. With EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwCode set to EC_ALL_NOTIFICATIONS, all notifications can be changed at once. EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwEnabled set to EC_NOTIFICATION_DEFAULT, resets to default.

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED
Parameter
  • pbyInBuf: [in] Pointer to EC_T_SET_NOTIFICATION_ENABLED_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

Return

EC_E_NOERROR or error code

struct EC_T_SET_NOTIFICATION_ENABLED_PARMS

Public Members

EC_T_DWORD dwClientId

[in] Client ID, 0: Master

EC_T_DWORD dwCode

[in] Notification code

EC_T_DWORD dwEnabled

[in] Enable, disable or reset to default notification

EC_NOTIFICATION_DISABLED

Disable notification

EC_NOTIFICATION_ENABLED

Enable notification

EC_NOTIFICATION_DEFAULT

Reset notification to default

EC_ALL_NOTIFICATIONS

Notification code to change all notifications

8.3.2. emIoControl - EC_IOCTL_GET_NOTIFICATION_ENABLED

Get notification enabled state.

emIoControl - EC_IOCTL_GET_NOTIFICATION_ENABLED
Parameter
  • pbyInBuf: [in] Pointer to EC_T_GET_NOTIFICATION_ENABLED_PARMS.

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

  • pbyOutBuf: [out] Pointer to EC_T_BOOL to carry out current enable set.

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

Public Members

EC_T_DWORD dwClientId

[in] Client ID, 0: Master

EC_T_DWORD dwCode

[in] Notification code

8.4. Status notifications

8.4.1. emNotify - EC_NOTIFY_STATECHANGED

Notification about a change in the master’s operational state.

emNotify - EC_NOTIFY_STATECHANGED
Parameter
  • pbyInBuf: [in] Pointer to data of type EC_T_STATECHANGE which contains the old and the new master operational state.

  • 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

struct EC_T_STATECHANGE

Public Members

EC_T_STATE oldState

old operational state

EC_T_STATE newState

new operational state

8.4.2. emNotify - EC_NOTIFY_SB_STATUS

Scan bus status notification.

emNotify - EC_NOTIFY_SB_STATUS
Parameter
  • pbyInBuf: [in] Pointer to EC_T_SB_STATUS_NTFY_DESC

  • 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

struct EC_T_SB_STATUS_NTFY_DESC

Public Members

EC_T_DWORD dwResultCode

[in] EC_E_NOERROR: success EC_E_NOTREADY: no bus scan executed EC_E_BUSCONFIG_MISMATCH: bus configuration mismatch Result of scanbus

EC_T_DWORD dwSlaveCount

[in] number of slaves connected to the bus

8.4.3. emNotify - EC_NOTIFY_SB_MISMATCH

This notification is triggered when the bus scan detects a discrepancy between connected slaves and configuration due to unexpected slaves or missing mandatory slaves. In case of permanent frame loss no slaves can be found although the slaves are connected.

emNotify - EC_NOTIFY_SB_MISMATCH
Parameter
  • pbyInBuf: [in] Pointer to EC_T_SB_MISMATCH_DESC

  • 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

struct EC_T_SB_MISMATCH_DESC

Public Members

EC_T_WORD wPrevFixedAddress

[in] Previous slave station address

EC_T_WORD wPrevPort

[in] Previous slave station address

EC_T_WORD wPrevAIncAddress

[in] Previous slave auto-increment address

EC_T_WORD wBusAIncAddress

[in] Unexpected slave (bus) auto-inc address

EC_T_DWORD dwBusVendorId

[in] Unexpected slave (bus) vendor ID

EC_T_DWORD dwBusProdCode

[in] Unexpected slave (bus) product code

EC_T_DWORD dwBusRevisionNo

[in] Unexpected slave (bus) revision number

EC_T_DWORD dwBusSerialNo

[in] Unexpected slave (bus) serial number

EC_T_WORD wBusFixedAddress

[in] Unexpected slave (bus) station address

EC_T_WORD wIdentificationVal

[in] last identification value read from slave according to the last used identification method

EC_T_WORD wCfgFixedAddress

[in] Missing slave (config) station Address

EC_T_WORD wCfgAIncAddress

[in] Missing slave (config) Auto-Increment Address

EC_T_DWORD dwCfgVendorId

[in] Missing slave (config) Vendor ID

EC_T_DWORD dwCfgProdCode

[in] Missing slave (config) Product code

EC_T_DWORD dwCfgRevisionNo

[in] Missing slave (config) Revision Number

EC_T_DWORD dwCfgSerialNo

[in] Missing slave (config) Serial Number

EC_T_BOOL bIdentValidationError

[in] Hotconnect Identification command sent to slave but failed

EC_T_WORD oIdentCmdHdr[5]

[in] Last HotConnect Identification command header (if bIdentValidationError)

EC_T_DWORD dwCmdData

[in] First DWORD of Data portion of last identification command

EC_T_DWORD dwCmdVMask

[in] First DWORD of Validation mask of last identification command

EC_T_DWORD dwCmdVData

[in] First DWORD of Validation data of last identification command

8.4.4. emNotify - EC_NOTIFY_HC_TOPOCHGDONE

This notification is triggered when topology change has completely processed.

emNotify - EC_NOTIFY_HC_TOPOCHGDONE
Parameter
  • pbyInBuf: [in] Pointer to EC_T_DWORD (EC_E_NOERROR on success, Error code otherwise)

  • dwInBufSize: [in] sizeof(EC_T_DWORD).

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

8.4.5. emNotify - EC_NOTIFY_SLAVE_PRESENCE

This notification is given, if slave appears or disappears from the network.

emNotify - EC_NOTIFY_SLAVE_PRESENCE
Parameter
  • pbyInBuf: [in] Pointer to EC_T_SLAVE_PRESENCE_NTFY_DESC

  • 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

Disconnecting the slave from the network, powering it off or a bad connection can produce this notification.

struct EC_T_SLAVE_PRESENCE_NTFY_DESC

Public Members

EC_T_WORD wStationAddress

Slave station address

EC_T_BYTE bPresent

EC_TRUE: present , EC_FALSE: absent

8.4.6. emNotify - EC_NOTIFY_SLAVE_STATECHANGED

This notification is triggered when a slave has changed its EtherCAT state. This notification is disabled by default.

emNotify - EC_NOTIFY_SLAVE_STATECHANGED
Parameter
  • pbyInBuf: [in] Pointer to EC_T_SLAVE_STATECHANGED_NTFY_DESC

  • 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

struct EC_T_SLAVE_STATECHANGED_NTFY_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_STATE newState

New slave state

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED to enable notification.

8.5. Error notifications

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 Watchodg 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 the detailed error information (e.g. information about the slave) is stored in the appropriate structure of a union. These error information structures are described in the following sections.

8.5.1. emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL

When processing cyclic frames the EtherCAT master checks whether all slaves are still in OPERATIONAL state. If at least one slave device is not OPERATIONAL this error will be indicated.

8.5.2. emNotify - EC_NOTIFY_ALL_DEVICES_OPERATIONAL

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

8.5.3. emNotify - EC_NOTIFY_CLIENTREGISTRATION_DROPPED

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

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

8.5.4. emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR

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

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

struct EC_T_SLAVE_PROP
EC_T_WORD wStationAddress
EC_T_WORD wAutoIncAddr
EC_T_CHAR achName[MAX_STD_STRLEN]

8.5.5. emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR

This notification will be indicated if the actually received Ethernet frame does not match to the frame expected or if a expected frame was not received.

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 from the ENI. 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_BCppDummy

8.5.6. emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR

When processing cyclic frames, the EC-Monitor checks whether the ERROR bit in the AL-STATUS register is set for at least one slave. In this case, this notification is triggered. If the EtherCAT master determines the error information of the slave(s) signal an error, another notification emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO with more precise error information is triggered.

8.5.7. emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO

This notification will be indicated if the EtherCAT master reads the AL-STATUS and AL-STATUS-CODE registers and the slave signals an error in them. Detailed error information is stored in structure EC_T_SLAVE_ERROR_INFO_DESC of EC_T_ERROR_NOTIFICATION_DESC.

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)

8.5.8. emNotify - EC_NOTIFY_PDIWATCHDOG

This notification will be indicated every time a PDI watchdog error is detected. Detailed error information is stored in 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

8.5.9. emNotify - EC_NOTIFY_COMMUNICATION_TIMEOUT

This notification will be indicated if the EC-Monitor does not detect any EtherCAT communication on the Ethernet tap for a parameterizable timeout. The descriptor of the notification contains information on which port of the Ethernet tap the timeout occurred.

struct EC_T_COMMUNICATION_TIMEOUT_NTFY_DESC

Public Members

EC_T_BOOL bMainTapPortIn

EC_TRUE: Timeout occurred at the input port of the Ethernet TAP for the EtherCAT main line

EC_T_BOOL bMainTapPortOut

EC_TRUE: Timeout occurred at the output port of the Ethernet TAP for the EtherCAT main line