6.16. EtherCAT® Bus Scan

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

See also

emScanBus()

6.16.1. emIoCtl - EC_IOCTL_SB_ENABLE

EC_IOCTL_SB_ENABLE

Enables Busscan support.

Parameters

pbyInBuf – [in] Pointer to Timeout Parameter Value [ms] (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

Returns

EC_E_NOERROR or error code

The bus scan support is enabled by default.

6.16.2. emIoCtl - EC_IOCTL_SB_RESTART

EC_IOCTL_SB_RESTART

This call will restart the bus scanning cycle. On completion the Notification EC_NOTIFY_SB_STATUS is given.

Parameters

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

Returns

EC_E_NOERROR or error code

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

6.16.3. emIoCtl - EC_IOCTL_SB_STATUS_GET

EC_IOCTL_SB_STATUS_GET

This call will get the status of the last bus scan.

Parameters

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.

Returns

EC_E_NOERROR or error code

See also

emNotify - EC_NOTIFY_SB_STATUS

6.16.4. emIoCtl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAY

EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAY

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

Parameters

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

Returns

EC_E_NOERROR or error code

6.16.5. emIoCtl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAYS

EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAYS

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

Parameters

pbyInBuf – [in] Pointer to EC_T_TOPOLOGY_CHANGED_DELAYS containing the delay information in ms
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

Returns

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. emIoCtl - EC_IOCTL_SB_SET_ERROR_ON_CROSSED_LINES

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.

Parameters

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

Returns

EC_E_NOERROR or error code

6.16.7. emIoCtl - EC_IOCTL_SB_SET_ERROR_ON_LINE_BREAK

EC_IOCTL_SB_SET_ERROR_ON_LINE_BREAK

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.

Note

EC_E_REDLINEBREAK: Line break in a cable redundant network.

Note

EC_E_JUNCTION_RED_LINE_BREAK: Line break in a junction redundant network.

Note

See EC_NOTIFY_SB_MISMATCH, EC_NOTIFY_SB_STATUS.

Parameters

pbyInBuf – [in] Pointer to value of EC_T_BOOL: EC_TRUE: Enable, EC_FALSE: Disable. Default: Enabled.
dwInBufSize – [in] Should be set to sizeof(EC_T_BOOL)
pbyOutBuf – [out] Should be set to EC_NULL
dwOutBufSize – [in] Should be set to 0
pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

6.16.8. emIoCtl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE

Warning

This documentation is preliminary and is subject to change

EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE

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

Parameters

pbyInBuf – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE the automatic 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

Returns

EC_E_NOERROR or error code

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

6.16.9. emIoCtl - EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE

Warning

This documentation is preliminary and is subject to change

EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE

This call will trigger a scan bus. On completion the Notification EC_NOTIFY_SB_STATUS is given.

Parameters

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

Returns

EC_E_NOERROR or error code

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

6.16.10. emNotify - EC_NOTIFY_SB_STATUS

Bus scan 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

emIoCtl - 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 a bus scan detects a mismatch of connected SubDevices and configuration, due to unexpected SubDevices or missing mandatory SubDevices.

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 SubDevices can be found although the SubDevices 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_BOOL bIdentificationError: [in] Identification command sent to slave but failed

EC_T_WORD wIdentificationAdo: [in] Identification register

EC_T_WORD wIdentificationVal: [in] Last identification value read from slave according to the last used identification method

EC_T_WORD wIdentificationValExpected: [in] Identification expected value

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

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.16.12. emNotify - EC_NOTIFY_SB_DUPLICATE_HC_NODE

A bus mismatch was detected during the scan due to duplicated SubDevice(s). The application receives this notification if there are two SubDevices 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 SubDevice (config) station Address
EC_T_SB_MISMATCH_DESC::wCfgAIncAddress Duplicated SubDevice (config) Auto-Increment Address.
EC_T_SB_MISMATCH_DESC::dwCfgVendorId Duplicated SubDevice (config) Vendor ID
EC_T_SB_MISMATCH_DESC::dwCfgProdCode Duplicated SubDevice (config) Product code
EC_T_SB_MISMATCH_DESC::dwCfgRevisionNo Duplicated SubDevice (config) Revision Number
EC_T_SB_MISMATCH_DESC::dwCfgSerialNo Duplicated SubDevice (config) Serial Number

6.16.13. emNotify - EC_NOTIFY_SLAVE_PRESENCE

This notification is given when a SubDevice 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 SubDevice 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

emIoCtl - 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 the MainDevice status is changed, whichever comes first. Disconnecting SubDevices 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 SubDevice’s port 0 must lead to MainDevice.

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 emConfigureNetwork() (GenOp/Preop) and a wrong category type is detected in the EEPROM. This notification should only print a log message or be ignored (EC-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 a port would lead to frame loss. This notification should only print a log message.

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. emIoCtl - EC_IOCTL_SB_NOTIFY_UNEXPECTED_BUS_SLAVES

EC_IOCTL_SB_NOTIFY_UNEXPECTED_BUS_SLAVES

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

Parameters

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

Returns

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 EtherCAT stack 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 a topology change was 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 SubDevices have been detected and DC initialized.

6.16.22. emIoCtl - EC_IOCTL_SB_SET_NO_DC_SLAVES_AFTER_JUNCTION

EC_IOCTL_SB_SET_NO_DC_SLAVES_AFTER_JUNCTION

Declares that no DC slaves are located after junction.

Parameters

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

Returns

EC_E_NOERROR or error code

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