EtherCAT bring-up for robot joint modules

By Tolerance Labs engineering team · Updated 18 October 2026

EtherCAT can run dozens of joints at a 1 ms cycle on one cable, but only after the master, the process data and the drive state machine all agree. This guide follows bring-up in the order that faults appear.

What you need before you start

• A master. On Linux, the two common open-source masters are SOEM (Simple Open EtherCAT Master), a library that runs in user space over a raw socket, and the IgH EtherCAT Master, a kernel module with its own drivers for some network chips and a generic driver for others. Commercial masters also exist. A ROS 2 hardware interface can wrap a master; see ros2_control for joint modules.
• A dedicated network port. EtherCAT uses Ethernet frames with its own EtherType, 0x88A4. Give it its own port, with no switch and no other traffic.
• ESI files. The EtherCAT Slave Information file is an XML description of each device: identity, objects, default PDO mapping, sync managers and distributed-clock modes. Each slave also holds a short form of it in its EEPROM.
• Cabling. Connect the master to the IN port of the first slave and chain OUT to IN. The last slave closes the loop internally.

Bus choice, and why EtherCAT suits many axes, is covered in CAN, CAN FD, EtherCAT or RS485.

The EtherCAT state machine

The master steps every slave through a state machine. A slave that refuses a transition reports an AL status code that gives the reason. Read it first.

A slave drops from OP to SAFE-OP when its sync manager watchdog sees no new outputs for too long. That usually means the master missed cycles, not that the slave failed. Updating robot joint firmware covers the BOOT state.

PDO mapping

Process data objects (PDOs) carry the cyclic data. RxPDOs carry outputs from the master to the slave, and TxPDOs carry inputs back. Under CANopen over EtherCAT (CoE), the mapping lives in objects from 0x1600 for RxPDOs and from 0x1A00 for TxPDOs, and the assignment of PDOs to sync managers lives in 0x1C12 and 0x1C13. Many drives let you write your own mapping in PRE-OP. A typical mapping for a joint in cyclic synchronous position mode:

• RxPDO: controlword (0x6040, 16 bits), target position (0x607A, 32 bits), torque offset (0x60B2, 16 bits) and modes of operation (0x6060, 8 bits). Total 9 bytes.
• TxPDO: statusword (0x6041, 16 bits), position actual value (0x6064, 32 bits), velocity actual value (0x606C, 32 bits), torque actual value (0x6077, 16 bits) and error code (0x603F, 16 bits). Total 14 bytes.

Map only what the loop uses each cycle, and read the rest by SDO. If the master’s process image does not match the slave’s mapping, the slave refuses SAFE-OP.

CiA 402: the drive state machine and modes

Most EtherCAT joint drives follow the CiA 402 drive profile. OP only starts communication. The drive has a second state machine, driven by the controlword and reported in the statusword, and the motor carries current only in Operation enabled.

• Switch on disabled → Ready to switch on: controlword 0x0006 (Shutdown).
• Ready to switch on → Switched on: 0x0007 (Switch on).
• Switched on → Operation enabled: 0x000F (Enable operation).
• Fault → Switch on disabled: a rising edge on bit 7 (0x0080, Fault reset), after the cause is cleared.

Modes of operation (0x6060) selects the control mode. For a host that closes the outer loops, the cyclic synchronous modes fit best: CSP (8), cyclic synchronous position; CSV (9), cyclic synchronous velocity; and CST (10), cyclic synchronous torque. In CSP the drive closes the position, velocity and current loops and takes a new target every cycle. In CST the host closes every loop above current. CiA 402 states torque in thousandths of rated torque (0x6076) and position in the drive’s own increments, so convert units in one place.

Before Enable operation in CSP, copy the actual position into the target position, or the joint jumps to whatever target was left there. Impedance control (MIT mode) gives a similar start-up sequence for CAN joints. If the drive stays in Switch on disabled, check its safe torque off input; see safe torque off for robot joints.

Distributed clocks and real-time Linux

Without synchronization, each slave applies its outputs as the frame passes, and each local clock drifts. Distributed clocks (DC) correct this. The first DC-capable slave is the reference clock. The master measures the propagation delay to each slave, sets the offsets, and sends the reference time around every cycle to correct drift. Each slave then raises a SYNC0 event at the same instant, typically within well under a microsecond, and latches inputs and applies outputs on it.

The master must deliver each frame before SYNC0, or the slave uses old outputs or flags a sync error.

That makes the master’s timing jitter the main limit. On Linux, use a kernel with PREEMPT_RT, run the cyclic thread at a real-time priority on an isolated CPU core, lock its memory, keep allocation and blocking calls out of the loop, and turn off deep CPU sleep states. Measure with cyclictest under load. A tuned PC commonly shows worst-case latencies of tens of microseconds; a standard desktop kernel can show milliseconds.

Worked example: cycle time

EtherCAT at 100 Mbit/s moves one byte every 80 ns. Example: 12 joints with the 9-byte RxPDO and 14-byte TxPDO above, written and read in one LRW datagram, plus one datagram that distributes DC time.

• Process data: 12 × (9 + 14) = 12 × 23 = 276 bytes.
• Datagram overhead: 2 datagrams × 12 bytes of header and working counter = 24 bytes, plus 8 bytes of DC time.
• EtherCAT header: 2 bytes. Ethernet overhead: 38 bytes for preamble, header, checksum and inter-frame gap.
• Frame: 276 + 24 + 8 + 2 + 38 = 348 bytes. On the wire: 348 × 80 ns ≈ 27.8 µs.
• Forwarding delay, typically under 1 µs per slave for both passes: 12 × 1 µs = 12 µs. Cable: 12 m out and back at about 5 ns/m adds 0.12 µs.
• Round trip: 27.8 + 12 + 0.1 ≈ 40 µs.

At a 1 ms cycle the wire is busy 40 ÷ 1,000 = 4% of the time, and at 250 µs, 16%. The limits are the master’s compute time and jitter, and the shortest cycle each drive supports. One drive that supports only 1 ms cycles sets the rate for the whole line.

Common bring-up faults

Checklist

• A master chosen, on a dedicated port, with the ESI file for every slave.
• All slaves found in cable order, reaching OP without AL status errors.
• PDO mapping limited to what the loop uses, and the same in master and slave.
• Distributed clocks on, with frames arriving before SYNC0.
• A real-time kernel, an isolated core and a measured worst-case latency.
• The CiA 402 sequence scripted, with the target copied from the actual value before enable.
• Mode, units and scaling for CSP, CSV or CST confirmed for each drive.
• A cycle time inside every drive’s supported range.

Compare robot joint modules and motor drivers by bus in Robot Parts, and check each datasheet for EtherCAT support and supported cycle times.