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

Detailed information about the according notification (EC_NOTIFY_…)

Public Members

EC_T_VOID *pCallerData

[in] Parameter arbitrarily defined by the application at client registration with the EtherCAT stack

EC_T_BYTE *pbyInBuf

[in] Notification input parameters

EC_T_DWORD dwInBufSize

[in] Size of the input parameter buffer

EC_T_BYTE *pbyOutBuf

[out] Notification output (result)

EC_T_DWORD dwOutBufSize

[in] Size of the output buffer

EC_T_DWORD *pdwNumOutData

[out] Actually used buffer size of the output buffer

6.6.2. EC_NOTIFY_SLAVE_PRESENCE

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

This notification is enabled by default.

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 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 slave changed its EtherCAT state. This notification is disabled by default.

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_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

See also

esPowerSlave() , esDisconnectPort() , esConnectPorts()

6.6.5. EC_NOTIFY_SLAVE_ERROR_STATUS_INFO

This notification is given, when the Error bit on the specific slave 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.6. EC_NOTIFY_EEPROM_OPERATION

This notification is given, when a slave EEPROM is written by the master.

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