Distributed Clocks Configuration

Overview

EtherCAT Distributed Clocks (DC) synchronize all slave devices to a single reference clock with sub-microsecond accuracy. The first DC-capable slave in the ring becomes the reference clock; all others discipline their local clocks against it.

Configuring the DC Cycle

Distributed clocks are driven by the ethercat section of app_config.yml. The master handles reference clock selection, propagation delay measurement, and drift compensation automatically — you configure the cycle and the sync0 shift:

ethercat:
  esi_file_path: ESI/
  prioritize_esi_config: true
  cycle_time: 4000        # [us], only multiples of 250 us supported
  shift_time: 30          # [% of cycle time], master frame send to sync0 offset
  rx_frame_timeout: 12000 # [us], Unix only, 1/4 to 3x the cycle_time

cycle_time

The EtherCAT process data cycle, in microseconds. Only multiples of 250 µs are supported — 250, 500, 750, 1000, and so on.

shift_time

The offset between the master's frame send and the slaves' sync0 event, expressed as a percentage of cycle_time. Set it to your worst-case latency: the frame must arrive at every slave before sync0 fires. 5% is the practical floor; values that are too low will drop frames on a loaded system.

rx_frame_timeout

Receive frame timeout in microseconds, on Unix systems only. It must fall between one quarter and three times cycle_time.

Propagation Delay Measurement

The master automatically measures propagation delays during startup by sending frames and measuring the time difference at each slave port. This runs once at the PREOP → SAFEOP transition and repeats if topology changes are detected. No configuration is required.

Tuning Synchronization Quality

Raise shift_time if you see dropped or late frames — it buys the slaves processing margin at the cost of latency
Raise cycle_time before raising shift_time if the system simply cannot keep up
Keep background CPU load low; the library applies its own OS and thread real-time optimizations, but a non-deterministic OS will still introduce jitter