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

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

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

Calls the notification callback functions of all registered clients.

Note

EC_E_ERROR and EC_E_INVALIDPARM from registered clients’ callback functions are ignored.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
dwCode – [in] Application specific notification code. dwCode must be <= EC_NOTIFY_APP_MAX_CODE. The callback functions get “EC_NOTIFY_APP | dwCode” as parameter.
pParms – [in] Parameter to all callback functions. Note: Output parameters are not transferred from RAS client to RAS server.

Returns

EC_E_ERROR or first error code different from EC_E_ERROR and EC_E_INVALIDPARM of registered clients’ callback functions

The maximum value for dwCode is defined by EC_NOTIFY_APP_MAX_CODE

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

EC_NOTIFY_SLAVE_REGISTER_TRANSFER

9.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 or EC_ALL_NOTIFICATIONS

EC_T_DWORD dwEnabled: [in] Enable, disable or reset to default notification. See EC_NOTIFICATION_ flags

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

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

9.4. Status notifications

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

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

9.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] Hot-Connect Identification command sent to slave but failed

EC_T_WORD oIdentCmdHdr[5]: [in] Last Hot-Connect 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

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

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

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

9.4.7. emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

This notification is triggered when a slave register transfer is completed.

To avoid excessive triggering of the notification, registers that are read by the EtherCAT master at regular intervals are not notified. These are the following registers:

AL-Status (0x0130)

RX Error Counter, Forwarded RX Error Counter, ECAT Processing Unit Error Counter, PDI Error Counter, PDI Error Code, Lost Link Counter (0x0300:0x0314)

SII EEPROM Interface (0x0500:0x050F)

Registers above 0x1000

This notification is disabled by default.

emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

Parameter

pbyInBuf: [in] Pointer to EC_T_SLAVEREGISTER_TRANSFER_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_SLAVEREGISTER_TRANSFER_NTFY_DESC

Public Members

EC_T_DWORD dwTferId: Transfer ID. For every new slave register transfer a unique ID has to be assigned. This ID can be used after completion to identify the transfer

EC_T_DWORD dwResult: Result of Slave register transfer

EC_T_BOOL bRead: EC_TRUE: Read register, EC_FALSE: Write register transfer

EC_T_WORD wFixedAddr: Station address of slave

EC_T_WORD wRegisterOffset: Register offset

EC_T_WORD wLen: Length of slave register transfer

EC_T_BYTE *pbyData: Pointer to the data read

EC_T_WORD wWkc: Received working counter

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

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

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

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

9.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]

9.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_CRC: Ethernet frame with CRC error received

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

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

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

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

9.5.10. emNotify - EC_NOTIFY_TAP_LINK_STATUS

This notification will be indicated if the link status between EC-Monitor and Ethernet TAP device has changed.

struct EC_T_TAP_LINK_STATUS_NTFY_DESC

Public Members

EC_T_BOOL bLinkConnected: Link status of EC-Monitor - Ethernet Tap connection