Notifications

6.6. Notifications

6.6.1. Notification handler

The application can register a notification handler using esRegisterClient() for notifications as described below.

A further important rule exists due to the fact that this callback function is usually called in the context of the EC-Simulator stack timer thread. As the whole EtherCAT® operation is blocked while calling this function the notification handler must not use much CPU time or even call operating system functions that may block. Time consuming operations should be executed in separate application threads.

Data structure filled with detailed information about the according notification:

struct EC_T_NOTIFYPARMS

Data structure filled with detailed information about the according notification.

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 notification input parameters in bytes

EC_T_BYTE *pbyOutBuf: [out] Buffer for notification output (result)

EC_T_DWORD dwOutBufSize: [in] Size of buffer at pbyOutBuf in bytes

EC_T_DWORD *pdwNumOutData: [out] Amount of bytes written to pbyOutBuf by notification. EC_NULL: amount not set by notification.

6.6.2. EC_NOTIFY_SLAVE_PRESENCE

This notification is given when a SubDevice 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 SubDevice from the network, powering it off or a bad connection will generate 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

6.6.3. EC_NOTIFY_SLAVE_STATECHANGED

This notification is given when a SubDevice changed its EtherCAT® state.

emNotify - EC_NOTIFY_SLAVES_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

6.6.4. EC_NOTIFY_STATECHANGED

This notification is given when the MainDevice changes its EtherCAT® state.

emNotify - EC_NOTIFY_STATECHANGED

Parameter

pbyInBuf: [in] Pointer to data of type EC_T_STATECHANGE which contains the old and the new MainDevice 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

6.6.5. EC_NOTIFY_HC_TOPOCHGDONE

This notification is given by eUsrJob_SimulatorTimer when the topology changes.

emNotify - EC_NOTIFY_HC_TOPOCHGDONE

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

6.6.6. EC_NOTIFY_SLAVE_ERROR_STATUS_INFO

This notification is given when the Error bit on the specific SubDevice is set or cleared 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)

6.6.7. EC_NOTIFY_EEPROM_OPERATION

This notification is given, when a SubDevice EEPROM is written by the MainDevice.

emNotify - EC_NOTIFY_EEPROM_OPERATION

Parameter

pbyInBuf: [in] Pointer to EC_T_EEPROM_OPERATION_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_EEPROM_OPERATION_NTFY_DESC

Public Members

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

EC_T_EEPROM_OPERATION_TYPE eType: Type of EEPROM operation

EC_T_DWORD dwResult: Result of EEPROM operation

EC_T_SLAVE_PROP SlaveProp: Slave properties

union _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_ACTIVE

Public Members

EC_T_BOOL bSlavePDIAccessActive: EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_READ

Public Members

EC_T_WORD wEEPRomStartOffset: Start address of EEPRom operation. Given by API.

EC_T_WORD *pwData: Pointer to WORD array containing the data. Given by API.

EC_T_DWORD dwReadLen: Number of Words to be read. Given by API.

EC_T_DWORD dwNumOutData: Number of Words actually read from EEPRom

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_WRITE

Public Members

EC_T_WORD wEEPRomStartOffset: Start address of EEPRom operation. Given by API.

EC_T_WORD *pwData: Pointer to WORD array containing the data. Given by API.

EC_T_DWORD dwWriteLen: Number of Words to be written. Given by API.

enum EC_T_EEPROM_OPERATION_TYPE

Values:

enumerator eEEPRomOp_Unknown: Unknown EEPROM operation, only for internal use

enumerator eEEPRomOp_Assign: Assign slave EEPROM operation, used by emAssignSlaveEEPRomReq

enumerator eEEPRomOp_Active: Active slave EEPROM operation, used by emActiveSlaveEEPRomReq

enumerator eEEPRomOp_Read: Read slave EEPRom operation, used by emReadSlaveEEPRomReq

enumerator eEEPRomOp_Write: Write slave EEPRom operation, used by emWriteSlaveEEPRomReq

enumerator eEEPRomOp_Reload: Reload slave EEPRom operation, used by emReloadSlaveEEPRomReq

enumerator eEEPRomOp_Reset: Reset slave EEPRom operation, used by emResetSlaveController

6.6.8. EC_NOTIFY_FRAME_RESPONSE_ERROR

This notification is given, when a Ethernet pause frame (MAC control EtherType 0x8808, Control opcode 0x0001) is received. This may occur if any Flow Control mode is active within the network adapter’s native driver settings.

emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR

Parameter

pbyInBuf: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC
dwInBufSize: [in] SIZEOF_EC_T_ERROR_NOTIFICATION_FRAME_RSPERR
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_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.6.9. esNotifyApp

EC_T_DWORD esNotifyApp(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

Notifications

Contents

6.6. Notifications

6.6.1. Notification handler

6.6.2. EC_NOTIFY_SLAVE_PRESENCE

6.6.3. EC_NOTIFY_SLAVE_STATECHANGED

6.6.4. EC_NOTIFY_STATECHANGED

6.6.5. EC_NOTIFY_HC_TOPOCHGDONE

6.6.6. EC_NOTIFY_SLAVE_ERROR_STATUS_INFO

6.6.7. EC_NOTIFY_EEPROM_OPERATION

6.6.8. EC_NOTIFY_FRAME_RESPONSE_ERROR

6.6.9. esNotifyApp