6.16. EtherCAT Bus Scan

The acontis EtherCAT Master stack supports scanning the EtherCAT Bus to determine which devices are available. If a configuration was provided the connected slaves are validated against the given ENI.

See also

emScanBus()

6.16.1. emIoControl - EC_IOCTL_SB_ENABLE

Enables Busscan support.

emIoControl - EC_IOCTL_SB_ENABLE

Parameter

pbyInBuf: [in] Pointer to Timeout Parameter Value in MSec (EC_T_DWORD). Timeout Parameter is used for timeout during Bus Topology determination.
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

The Scanbus support is enabled by default.

6.16.2. emIoControl - EC_IOCTL_SB_RESTART

This call will restart the bus scanning cycle. On completion the Notfication emNotify - EC_NOTIFY_SB_STATUS is given.

emIoControl - EC_IOCTL_SB_RESTART

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

The timeout value given by emIoControl - EC_IOCTL_SB_ENABLE will be used. This function may be called prior to running emConfigureMaster(). In such a case a first bus scan will be executed before master configuration. This feature may be used to dynamically create or adjust the XML configuration file. When issuing this IoControl, the application has to take care emExecJob() is called cyclically to trigger master state machines, timers, send acyc and receive frames accordingly.

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

6.16.4. emIoControl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAY

This call will set the topology changed delay value. The master will wait this duration in msec to react on appearing links in topology. The default value is 1000 ms.

emIoControl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAY

Parameter

pbyInBuf: [in] Pointer to EC_T_DWORD containing the delay information in msec
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

6.16.5. emIoControl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAYS

This call will set the topology changed delay values individually. The master will wait individual durations in msec (0 msec: disabled) for slave ports, main link and red link to react on appearing links in topology. The default value is 1000 ms.

emIoControl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAYS

Parameter

pbyInBuf: [in] Pointer to EC_T_TOPOLOGY_CHANGED_DELAYS containing the delay information in msec
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_TOPOLOGY_CHANGED_DELAYS

Public Members

EC_T_DWORD dwSlavePort: [in] Delay before opening slave port after link connection detected

EC_T_DWORD dwMainLine: [in] Delay before sending frames at main line after link connection detected

EC_T_DWORD dwRedLine: [in] Delay before sending frames at red line after link connection detected

EC_T_DWORD adwReserved[5]: reserved

6.16.6. emIoControl - EC_IOCTL_SB_SET_ERROR_ON_CROSSED_LINES

This call will enable or disable bus mismatch if IN and OUT connectors are swapped. If enabled the swapped IN and OUT connectors will lead to bus mismatch. By default swapped IN and OUT connectors will lead to bus mismatch.

emIoControl - EC_IOCTL_SB_SET_ERROR_ON_CROSSED_LINES

Parameter

pbyInBuf: [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE swapped IN and OUT connectors will lead to bus mismatch, if set to EC_FALSE swapped IN and OUT connectors are tolerated.
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

6.16.7. emIoControl - EC_IOCTL_SB_SET_ERROR_ON_LINEBREAK

This call will enable or disable bus mismatch if a line is broken in a redundant network. If enabled, line breaks in cable or junction redundant networks will lead to bus mismatch.

emIoControl - EC_IOCTL_SB_SET_ERROR_ON_LINEBREAK

Parameter

pbyInBuf: [in] Pointer to EC_T_BOOL. EC_TRUE: Return error code, EC_FALSE: Return no error.
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

Default: No error on line break.

Error codes:

EC_E_REDLINEBREAK: Line break in a cable redundant network.
EC_E_JUNCTION_RED_LINE_BREAK: Line break in a junction redundant network.

6.16.8. emIoControl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE

Warning

This documentation is preliminary and is subject to change

This call will enable or disable the automatical topology change mode. By default the automatical mode is enabled.

emIoControl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE

Parameter

pbyInBuf: [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE the automatical mode is enabled.
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

In automatical mode, new slaves will be discovered automatically. In manual mode, after new slaves have been connected, a emNotify - EC_NOTIFY_HC_TOPOCHGDONE notification will be given without opening the ports of the slaves on bus. When the application is able to handle the new slaves, it should call emIoControl - EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE

6.16.9. emIoControl - EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE

Warning

This documentation is preliminary and is subject to change

This call will trigger a scan bus. On completion the Notfication emNotify - EC_NOTIFY_SB_STATUS is given.

emIoControl - EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE

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

This function may be called after a emNotify - EC_NOTIFY_HC_TOPOCHGDONE notification was given if the automatical topology change mode was previously disabled using emIoControl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE. During this scan bus the ports of the slaves will be (re)open and new slaves can be detected. The timeout value given by emIoControl - EC_IOCTL_SB_ENABLE will be used. When issuing this IoControl, the application has to take care emExecJob() is called cyclically to trigger master state machines, timers, send acyc and receive frames accordingly.

6.16.10. emNotify - EC_NOTIFY_SB_STATUS

Scan bus status notification.

This notification is enabled by default.

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

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.16.11. emNotify - EC_NOTIFY_SB_MISMATCH

This notification will be initiated if scan bus detects mismatch of connected slaves and configuration, due to unexpected slaves or missing mandatory slaves.

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

This notification is enabled by default. In case of permanent frame loss no slaves can be found although the slaves are connected.

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

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.16.12. emNotify - EC_NOTIFY_SB_DUPLICATE_HC_NODE

Scan bus mismatch was detected while scan because of a duplicated slave(s). An application get this notification if the there are two slaves on the network with the same product code, vendor ID and identification value (alias address or switch id).

emNotify - EC_NOTIFY_SB_DUPLICATE_HC_NODE

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

The members of EC_T_SB_MISMATCH_DESC have the following meaning:

EC_T_SB_MISMATCH_DESC::wCfgFixedAddress Duplicated slave (config) station Address
EC_T_SB_MISMATCH_DESC::wCfgAIncAddress Duplicated slave (config) Auto-Increment Address.
EC_T_SB_MISMATCH_DESC::dwCfgVendorId Duplicated slave (config) Vendor ID
EC_T_SB_MISMATCH_DESC::dwCfgProdCode Duplicated slave (config) Product code
EC_T_SB_MISMATCH_DESC::dwCfgRevisionNo Duplicated slave (config) Revision Number
EC_T_SB_MISMATCH_DESC::dwCfgSerialNo Duplicated slave (config) Serial Number

6.16.13. emNotify - 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 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

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.16.14. emNotify - EC_NOTIFY_SLAVES_PRESENCE

This notification collects notifications of the type emNotify - EC_NOTIFY_SLAVE_PRESENCE Notification is given either upon completion or when master status is changed, whichever comes first. Disconnecting slaves from the network, turning them off, or having a bad connection can lead to this notification.

This notification is disabled by default.

emNotify - EC_NOTIFY_SLAVES_PRESENCE

Parameter

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

struct EC_T_SLAVES_PRESENCE_NTFY_DESC

Public Members

EC_T_WORD wCount: Number of slave presence notifications

EC_T_SLAVE_PRESENCE_NTFY_DESC SlavePresence[MAX_SLAVES_PRESENCE_NTFY_ENTRIES]: slave presence descriptions

6.16.15. emNotify - EC_NOTIFY_LINE_CROSSED

Cable swapping detected. All slaves’ port 0 must lead to Master.

emNotify - EC_NOTIFY_LINE_CROSSED

Parameter

pbyInBuf: [in] Pointer to EC_T_LINE_CROSSED_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_LINE_CROSSED_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp: slave properties

EC_T_WORD wInputPort: port where frame was received

6.16.16. emNotify - EC_NOTIFY_SLAVE_NOTSUPPORTED

Is currently generated during Bus Scan if emConfigureMaster() (GenOp/Preop) and a wrong category type is detected in the EEPROM. This notification should only print a log message or be ignored (Master print log message itself).

emNotify - EC_NOTIFY_SLAVE_NOTSUPPORTED

Parameter

pbyInBuf: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC containing EC_T_SLAVE_NOTSUPPORTED_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_NOTSUPPORTED_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp: Slave properties

6.16.17. emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE

Is currently generated and automatically handled during emRescueScan() if opening port destroys communication (frameloss). This notification should only print a log message or be ignored.

emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE

Parameter

pbyInBuf: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC containing EC_T_FRAMELOSS_AFTER_SLAVE_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_FRAMELOSS_AFTER_SLAVE_NTFY_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp: slave properties

EC_T_WORD wPort: port

6.16.18. emNotify - Bus Scan notifications for Feature Packs

The notifications EC_NOTIFY_RED_LINEBRK, EC_NOTIFY_RED_LINEFIXED belong to the Feature Pack Redundancy. The notifications EC_NOTIFY_HC_DETECTADDGROUPS, EC_NOTIFY_HC_PROBEALLGROUPS belong to the Feature Pack Hot Connect.

6.16.19. emIoControl - EC_IOCTL_SB_NOTIFY_UNEXPECTED_BUS_SLAVES

Specifies if unexpected bus slaves must be notified as bus mismatch.

emIoControl - EC_IOCTL_SB_NOTIFY_UNEXPECTED_BUS_SLAVES

Parameter

pbyInBuf: [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE unexpected bus slaves on the network will be notified by EC_NOTIFY_SB_MISMATCH.
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

6.16.20. emIsTopologyChangeDetected

static EC_T_DWORD ecatIsTopologyChangeDetected(EC_T_BOOL *pbTopologyChangeDetected)

EC_T_DWORD emIsTopologyChangeDetected(EC_T_DWORD dwInstanceID, EC_T_BOOL *pbTopologyChangeDetected)

Returns whether topology change detected.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pbTopologyChangeDetected – [out] Pointer to EC_T_BOOL value: EC_TRUE if Topology Change Detected, EC_FALSE if not.

Returns

EC_E_NOERROR if successful
EC_E_INVALIDSTATE if master isn’t initialized
EC_E_INVALIDPARM if dwInstanceID is out of range
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

6.16.21. emNotify - EC_NOTIFY_HC_TOPOCHGDONE

This notification is raised 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

The notification is raised when the slaves have been detected and DC initialized.

6.16.22. emIoControl - EC_IOCTL_SB_SET_NO_DC_SLAVES_AFTER_JUNCTION

Declares that no DC slaves are located after junction

emIoControl - EC_IOCTL_SB_SET_NO_DC_SLAVES_AFTER_JUNCTION

Parameter

pbyInBuf: [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE the hidden slave detection and the junction redundancy specific propagation delay measurement are not executed
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

Calling this IOCTL if DC slaves are located in or after a junction redundancy segment will generate an undefined behavior.