1.4. Programmer’s Guide

1.4.1. emDcConfigure

static EC_T_DWORD ecatDcConfigure(struct _EC_T_DC_CONFIGURE *pDcConfigure)
EC_T_DWORD emDcConfigure(EC_T_DWORD dwInstanceID, EC_T_DC_CONFIGURE *pDcConfigure)

Configure the distributed clocks.

  • Set the DC synchronization settling time ([ms]).

  • Set the DC slave limit for the wire or’ed clock deviation value. This value determines whether the slave clocks are synchronized or not.

  • Configure the ARMW burst frames to compensate the static deviations of the clock speeds.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pDcConfigure – [in] Configuration parameter a pointer to a structure of type EC_T_DC_CONFIGURE.

Returns

EC_E_NOERROR or error code

struct EC_T_DC_CONFIGURE

Public Members

EC_T_DWORD dwClntId

[in] Reserved

EC_T_DWORD dwTimeout

[in] Timeout [ms] for the DC initialization in which time offsets and propagation delays are evaluated.

EC_T_DWORD dwDevLimit

[in] Maximum permissible deviation of the individual slave clock and the DC reference clock. The maximum deviation is determined by wire or’ed the deviations of the individual slave clocks with one another. The check against the limit is only active if “Sync Window Monitoring” is set in the configuration tool (EC Engineer), which generates a BRD command to read the slave register 0x092C in every cycle. The limit is calculated as follows:

2^n - 1 ns, e.g. a dwDevLimit of 4 corresponds to 14 ns.

A value of 0 disables the “Sync Window Monitoring”

EC_T_DWORD dwSettleTime

[in] Settle time [ms]. At the beginning of the synchronization the slave clocks oscillate strongly. To prevent multiple in-sync and out-of-sync notifications from being generated, a settling time can be set in which no notifications are generated.

EC_T_DWORD dwTotalBurstLength

[in] Overall amount of burst frames sent. Default 10000.

EC_T_DWORD dwBurstBulk

[in] Amount of burst frames per cycle during initialization burst. Default 12.

EC_T_BOOL bBulkInLinkLayer

[in] If EC_TRUE, bulk is realized by link layer, otherwise by master. The MAC needs to support the frame repeating function. In this case the link layer will repeat the DC burst frames itself, reducing the hardware accesses of the master to the MAC.

EC_T_BOOL bAcycDistributionDisabled

[in] If EC_TRUE, acyclic distribution is disabled

EC_T_DWORD dwDcStartTimeGrid

[in] Time grid [ns] to align DC start time. With the help of the grid, several EtherCAT networks can be synchronized without a random shift value between the SYNC signals.

EC_T_BOOL bDcInitBeforeSlaveStateChange

[in] If EC_TRUE, DC is initialized before slaves state change to PREOP

EC_T_DWORD dwReserved[4]

[in/out] Reserved

See also

Chapter “Drift Compensation” of the ETG Document “ESC Datasheet Section 1 - Technology”

1.4.2. emDcIsEnabled

static EC_T_DWORD ecatDcIsEnabled(EC_T_BOOL *pbDcIsEnabled)
EC_T_DWORD emDcIsEnabled(EC_T_DWORD dwInstanceID, EC_T_BOOL *pbDcIsEnabled)

Determines if DC is enabled and used.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pbDcIsEnabled – [out] EC_TRUE if DC is enabled

Returns

EC_E_NOERROR or error code

1.4.3. emGetBusTime

static EC_T_DWORD ecatGetBusTime(EC_T_UINT64 *pqwBusTime)
EC_T_DWORD emGetBusTime(EC_T_DWORD dwInstanceID, EC_T_UINT64 *pqwBusTime)

This function returns the actual bus time in nanoseconds.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pqwBusTime – [out] Bus time [ns]

Returns

EC_E_NOERROR or error code

1.4.4. emDcContDelayCompEnable

static EC_T_DWORD ecatDcContDelayCompEnable(EC_T_VOID)
EC_T_DWORD emDcContDelayCompEnable(EC_T_DWORD dwInstanceID)

Enable the continuous propagation delay compensation.

Calling this function generate a propagation delay measurement every 30s. The result of the measurement is used to correct the propagation delay values on the bus.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

EC_E_NOERROR or error code

1.4.5. emDcContDelayCompDisable

static EC_T_DWORD ecatDcContDelayCompDisable(EC_T_VOID)
EC_T_DWORD emDcContDelayCompDisable(EC_T_DWORD dwInstanceID)

Disable the continuous propagation delay compensation.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

EC_E_NOERROR or error code

1.4.6. emIoControl - EC_IOCTL_DC_SLV_SYNC_STATUS_GET

Get the last generated emNotify - EC_NOTIFY_DC_SLV_SYNC notification.

emIoControl - EC_IOCTL_DC_SLV_SYNC_STATUS_GET
Parameter

  • pbyInBuf: [in] Should be set to EC_NULL

  • dwInBufSize: [in] Should be set to 0

  • pbyOutBuf: [out] Pointer to EC_T_DC_SYNC_NTFY_DESC data type

  • dwOutBufSize: [in] Size of the output buffer in bytes

  • pdwNumOutData: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer pbyOutBuf

Return

EC_E_NOERROR or error code

See also

emNotify - EC_NOTIFY_DC_SLV_SYNC describes EC_T_DC_SYNC_NTFY_DESC

1.4.7. emIoControl - EC_IOCTL_DC_SETSYNCSTARTOFFSET

Set the safety offset applied to the “set DC start time” InitCmd during the PS transition.

emIoControl - EC_IOCTL_DC_SETSYNCSTARTOFFSET
Parameter

  • pbyInBuf: [in] Pointer to EC_T_DC_STARTCYCSAFETY_DESC data type

  • 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_DC_STARTCYCSAFETY_DESC

Public Members

EC_T_DWORD dwStartCycSafetyLo

[in] Start SYNC Cyc Safety [ns] Lower 32 Bit

EC_T_DWORD dwStartCycSafetyHi

[in] Start SYNC Cyc Safety [ns] Upper 32 Bit

Default: 50000000ns

1.4.8. emIoControl - EC_IOCTL_DC_FIRST_DC_SLV_AS_REF_CLOCK

Enable or disable the usage of the first DC slave on bus overriding the configured reference clock.

emIoControl - EC_IOCTL_DC_FIRST_DC_SLV_AS_REF_CLOCK
Parameter

  • pbyInBuf: [in] pointer to EC_T_BOOL. EC_FALSE: disable, EC_TRUE: enable.

  • 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

1.4.9. emFindInpVarByName - “Inputs.BusTime”

The DC system time (written to ESC register 0x0910) is part of the process data with name “Inputs.BusTime”.

static EC_T_DWORD ecatFindInpVarByName(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)
EC_T_DWORD emFindInpVarByName(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)

See also

emFindInpVarByName() in the EC-Master Class B documentation

1.4.10. emIoControl - EC_IOCTL_DC_ENABLE_ALL_DC_SLV

Enable or disable the usage of DC at all supporting slaves on bus overriding the configured settings. Perhaps emIoControl - EC_IOCTL_DC_FIRST_DC_SLV_AS_REF_CLOCK is necessary to set the reference clock at an allowed position.

emIoControl - EC_IOCTL_DC_ENABLE_ALL_DC_SLV
Parameter

  • pbyInBuf: [in] pointer to EC_T_BOOL. EC_FALSE: disable, EC_TRUE: enable.

  • 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

1.4.11. emNotify - EC_NOTIFY_REFCLOCK_PRESENCE

Distributed clocks reference clock presence notification. It will be received before emNotify - EC_NOTIFY_DC_SLV_SYNC as soon as reference clock was found on bus or removed from bus.

This notification is disabled by default.

emNotify - EC_NOTIFY_REFCLOCK_PRESENCE
Parameter

  • pbyInBuf: [in] pointer to notification descriptor EC_T_REFCLOCK_PRESENCE_NTFY_DESC

  • dwInBufSize: [in] sizeof(EC_T_REFCLOCK_PRESENCE_NTFY_DESC)

  • 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_REFCLOCK_PRESENCE_NTFY_DESC

Public Members

EC_T_BOOL bPresent

[in] Reference clock present

EC_T_SLAVE_PROP SlaveProp

[in] Slave properties

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED in the EC-Master Class B documentation for how to control the activation

1.4.12. emNotify - EC_NOTIFY_DC_STATUS

Distributed clocks status notification. It will be received after emNotify - EC_NOTIFY_DC_SLV_SYNC as soon as DC is initialized or topology change was done . After topology was changed it may be received without emNotify - EC_NOTIFY_DC_SLV_SYNC if slaves did not get out of sync.

If EC_E_NOERROR is returned and window monitoring is enabled, all slaves are in SYNC

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

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED in the EC-Master Class B documentation for how to control the deactivation

1.4.13. emNotify - EC_NOTIFY_DC_SLV_SYNC

DC slave synchronization notification. Every time the slaves are coming in sync or getting out of sync the clients will be notified here. The notification is raised in any case if any DC slaves are configured. Slaves can only be out of sync if Sync Window Monitoring is enabled otherwise they are considered in sync

This notification is enabled by default.

emNotify - EC_NOTIFY_DC_SLV_SYNC
Parameter

  • pbyInBuf: [in] pointer to notification descriptor EC_T_DC_SYNC_NTFY_DESC

  • dwInBufSize: [in] sizeof(EC_T_DC_SYNC_NTFY_DESC)

  • 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_DC_SYNC_NTFY_DESC

Public Members

EC_T_DWORD IsInSync

[in] EC_TRUE : Wire or’ed deviation value meets limit requirements. EC_FALSE: Wire or’ed deviation value does not meet limit requirements.The limit is set by ecatDcConfigure()

EC_T_DWORD IsNegative

[in] EC_TRUE : deviation value is negative EC_FALSE: deviation value is positive

EC_T_DWORD dwDeviation

[in] Wire or’ed deviation value [ns] in case of in sync

EC_T_SLAVE_PROP SlaveProp

[in] Slave properties in case of out of sync

See also