EtherCAT slave stays in PRE-OP or SAFE-OP and will not reach OP: how do I find the cause?

Each state enables more communication. INIT: the master can only access the slave controller's registers; no mailbox and no process data. PRE-OP: mailbox communication works, so the master can read and write the object dictionary with CoE SDOs and configure the PDO mapping, but there is no process data. SAFE-OP: process data is exchanged and inputs are valid, but the slave keeps its outputs in a safe state. OP: inputs and outputs are both live. There is also a BOOT state, reachable from INIT, used for firmware updates.

At each transition the slave checks the configuration the master has written and refuses the change if something does not match.

When a slave refuses, it says why. It sets the error bit in its AL status register (0x0130) and puts a reason in the AL status code register (0x0134). Your master library can read both; print the code instead of only the state.

Frequently seen codes: 0x0016 invalid mailbox configuration (fails going to PRE-OP); 0x001D invalid output configuration and 0x001E invalid input configuration (fail going to SAFE-OP, because the sync manager sizes written by the master do not match the slave's PDO mapping); 0x001A synchronisation error; and 0x001B sync manager watchdog. After a refusal the master must acknowledge the error before another state request is accepted.

Reaching OP and dropping back to SAFE-OP after a while is typically the watchdog, code 0x001B. In OP the slave expects fresh output data regularly; if the process data frames stop or arrive too late for longer than the watchdog time (100 ms is a common default), it goes to SAFE-OP with its outputs safe.

Causes are a cyclic task that is not really cyclic (a blocking call, a print statement in the loop, a non-real-time thread being preempted) or a program that requests OP and only then starts sending process data. The correct order is to start the cyclic exchange first, keep it running, and then request OP.

For a servo drive, the other usual cause is distributed clocks. Many drives require DC synchronisation with a specific SYNC0 cycle time, and that cycle must equal your master's cycle and be one of the values the drive supports, for example 1 ms, 2 ms or 4 ms. If the master's send time jitters too much relative to the slave's clock, the drive reports a synchronisation error and leaves OP or refuses it. I/O couplers are usually free-running and tolerate what a drive does not, which matches what you see.

Check the drive manual for the supported cycle times and the required DC mode, run the cyclic task with real-time priority, on an isolated CPU core if possible, and measure the actual jitter of the cycle.