# Programmer’s Guide

## emDcConfigure

### static EC_T_DWORD ecatDcConfigure(const [EC_T_DC_CONFIGURE](#_CPPv417EC_T_DC_CONFIGURE) \*pDcConfigure)

### EC_T_DWORD emDcConfigure(EC_T_DWORD dwInstanceID, const [EC_T_DC_CONFIGURE](#_CPPv417EC_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](#d4/df5/struct_e_c___t___d_c___c_o_n_f_i_g_u_r_e)
* **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 ( default:  12 sec   ) 

### 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” ( default:  2^10 - 1 = 1023 ns   ) 

### 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 ( default:  1000 msec   ). 

### 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”

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

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

## 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 will 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 

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

## emIoCtl - EC_IOCTL_DC_SLV_SYNC_STATUS_GET

### EC_IOCTL_DC_SLV_SYNC_STATUS_GET

Get the last generated emNotify - EC_NOTIFY_DC_SLV_SYNC notification. 

* **Parameters:**
  * **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](#dc/dc4/struct_e_c___t___d_c___s_y_n_c___n_t_f_y___d_e_s_c) 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 
* **Returns:**
  EC_E_NOERROR or error code 

#### SEE ALSO
- [emNotify - EC_NOTIFY_DC_SLV_SYNC](#emnotify-ec-notify-dc-slv-sync) describes [`EC_T_DC_SYNC_NTFY_DESC`](#_CPPv422EC_T_DC_SYNC_NTFY_DESC)
- `emIoCtl()` in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation

## emIoCtl - EC_IOCTL_DC_SETSYNCSTARTOFFSET

### EC_IOCTL_DC_SETSYNCSTARTOFFSET

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

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to [EC_T_DC_STARTCYCSAFETY_DESC](#d8/d1f/struct_e_c___t___d_c___s_t_a_r_t_c_y_c_s_a_f_e_t_y___d_e_s_c) 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 
* **Returns:**
  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

#### SEE ALSO
`emIoCtl()` in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation

## emIoCtl - EC_IOCTL_DC_FIRST_DC_SLV_AS_REF_CLOCK

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

* **Parameters:**
  * **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 
* **Returns:**
  EC_E_NOERROR or error code 

## 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()`](#_CPPv418emFindInpVarByName10EC_T_DWORDPK9EC_T_CHARP21EC_T_PROCESS_VAR_INFO) in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation
- `emIoCtl()` in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation

## emIoCtl - EC_IOCTL_DC_ENABLE_ALL_DC_SLV

### 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 [EC_IOCTL_DC_FIRST_DC_SLV_AS_REF_CLOCK](#d0/d35/_ec_io_ctl_8h_1a6cc6b13eabe68dd89ac8824bd0812ccd) is necessary to set the reference clock at an allowed position. 

* **Parameters:**
  * **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 
* **Returns:**
  EC_E_NOERROR or error code 

#### SEE ALSO
`emIoCtl()` in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation

## emNotify - EC_NOTIFY_REFCLOCK_PRESENCE

Distributed clocks reference clock presence notification. It will be received before [emNotify - EC_NOTIFY_DC_SLV_SYNC](#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
- emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals) documentation for how to control the activation
- `emIoCtl()` in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation

## emNotify - EC_NOTIFY_DC_STATUS

Distributed clocks status notification. It will be received after [emNotify - EC_NOTIFY_DC_SLV_SYNC](#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](#emnotify-ec-notify-dc-slv-sync) if SubDevices did not get out of sync.

If EC_E_NOERROR is returned and window monitoring is enabled, all SubDevices 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
- emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals) documentation for how to control the deactivation
- `emIoCtl()` in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation

## emNotify - EC_NOTIFY_DC_SLV_SYNC

DC SubDevice synchronization notification. Every time the SubDevices 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 SubDevices are configured. SubDevices can only be out of sync if [Sync Window Monitoring](dc_technical.html.md#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 [emDcConfigure()](#db/d74/_ec_master_api_8cpp_1aae993e04828f39a77feb3523bb4ef239). 

### 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
- [`emDcConfigure()`](#_CPPv413emDcConfigure10EC_T_DWORDPK17EC_T_DC_CONFIGURE)
- emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals) documentation for how to control the deactivation
- `emIoCtl()` in the [EC-Master Class B](https://developer.acontis.com/ec-master#manuals)  documentation