Commissioning an EtherCAT Servo in CODESYS: 7 Steps
From the ESI file to the first move: master, task cycle, Distributed Clocks, SoftMotion axis, scaling and the most common faults.
This content supports preliminary sizing and architecture decisions; it does not replace the selected product manual or machine risk assessment.
1. Install the ESI file in the device repository
The ESI (EtherCAT Slave Information) file tells the master the drive's process-data mapping, the modes it supports and its synchronisation settings. Download the file that matches the drive's full order code from the Document Centre and install it in the CODESYS Device Repository.
- The drive revision and the ESI revision must match
- Do not mix revisions of the same drive in a project
2. Add the EtherCAT Master and scan
Add an EtherCAT Master to the device tree and select the network interface the drives are connected to. A scan lists the devices in wiring order, and that order must match the physical one.
- Wire from IN to OUT on every device
- If a device is missing from the scan, check cables and ports first
3. Set the task and cycle time
Motion and EtherCAT communication must run in the highest-priority task with a fixed cycle, and that task must be selected as the bus cycle task. 1 ms is a good start for most servo applications; the task must finish every cycle without overrun.
- Move machine logic and HMI communication to lower-priority tasks
- Enable the task watchdog
4. Enable Distributed Clocks
In cyclic synchronous position mode (CSP), Distributed Clocks make every drive apply the command at the same instant. The SYNC0 period must equal the task cycle.
T_SYNC0 = T_task
5. SoftMotion axis and scaling
Create a SoftMotion axis for each drive. Scaling sets how many encoder counts one engineering unit (mm, degree) is worth. The typical sign of wrong scaling is an axis that goes the right way but the wrong distance.
- Example: 17-bit encoder (131,072 counts/rev), 1:1, 10 mm pitch → 13,107.2 counts/mm
counts/unit = (counts/rev × gear ratio) / (units/rev)
6. First move: MC_Power, MC_Jog, MC_Home
Power the axis with MC_Power first, confirm direction and limits at low speed with MC_Jog, then reference it with MC_Home. Watch every block's Error and ErrorID outputs.
- Do the first jog with a low torque limit
- Test hardware limits before software limits
7. The most common faults
If a slave stays in PRE-OP or SAFE-OP, the AL Status Code gives the reason: usually an ESI mismatch, the PDO mapping or the DC settings. Working-counter errors are almost always a cable, connector or shielding problem.
| Symptom | Likely cause | First check |
|---|---|---|
| Slave stays in PRE-OP | ESI / firmware mismatch | AL Status Code and revision |
| Will not go from SAFE-OP to OP | DC / SYNC0 settings, watchdog | SYNC0 = task cycle |
| Working-counter error | Cable, connector, noise | Per-port error counters |
| Axis goes the wrong distance | Scaling | Counts-per-unit calculation |
Frequently asked questions
Should Distributed Clocks always be on?
In cyclic synchronous position mode and coordinated multi-axis motion, yes. For independent axes in profile position mode it is not required.
How do I choose the cycle time?
By the shortest period in which the task always completes; start at 1 ms, shorten if needed, and watch the overrun counter.
Technical sources
Sources are publications from standards owners and manufacturers.