Troubleshooting
Why CODESYS EtherCAT master xError stays false on cable pull
Short answer
`EtherCAT_Master.xError` stays FALSE because the master does not latch slave loss into the application variables when restart handling is off; the engineering tool reads device state directly, so it still shows the error. Tick `Automatically restart slaves` on the master and `Enable Diagnosis for Devices` for the extended instance, then pull-test: the loss reaches the program and the slave rejoins when the cable returns.
On this page
Tick Automatically restart slaves on the EtherCAT master. With that option off, the master retries a lost slave without latching the loss as a state, so EtherCAT_Master.xError never moves while the engineering tool reports the fault from its own online view. That single change is what made the status appear in the PLC program in the case below, and it also brought the slave back once the cable was reinserted. Pair it with Enable Diagnosis for Devices, which generates the extended diagnostic instance, and confirm the member is read in a task that cycles every scan. Three checks settle the whole problem: the restart option, the diagnosis option, and the reading code.
Why the tool reports the fault and the program does not #
The engineering tool and your program are fed from different places. The tool reads the master device's state online, straight from the driver. The program sees only the members the master latches into its instance, and what gets latched is decided by the master's recovery handling. Between the pulled cable and the variable there are four places the status can stop:
| Hop | What happens on a pull | Where it shows |
|---|---|---|
| Cable and port PHY | The link drops at the slave port | Port link LEDs |
| Master driver | The slave leaves OP, the operational state | The tool's online view |
| Recovery handling | Latches the loss as states, or retries silently | The application instance |
| Application | EtherCAT_Master.xError and the other members |
Watch list, PLC logic |
With Automatically restart slaves unchecked, the status dies in row three: the driver knows, the tool displays it, and nothing is handed to row four. Nothing is broken in the driver or in the variable; the handoff was never configured.
The two settings that gate the status #
Automatically restart slaves, on the EtherCAT master's configuration. Unchecked in this project, it left the loss unlatched: the master kept retrying the slave and never reported a state the application could read. Ticking it was the one change that made the loss reach the program, and the slave rejoined by itself after the cable went back in.Enable Diagnosis for Devices, on the device editor. This generates the extended function block instance, which carries more diagnostic members than the minimum status set. Without it you can still read the error member, but from the smallest member set the device offers.
One caution before you tick the first box: restart handling brings the slave back with no operator action, so its outputs can resume the moment the cable returns, and that change belongs in the machine's restart review before it runs on a live process.
Check the code that reads the member #
Two reading faults mimic a dead diagnostic. First, the instance takes its name from the master device in the project: if that device is not named EtherCAT_Master, the member sits at a different path, and a hand-typed reference either fails to compile or points somewhere stale. Second, the master's variables are only kept up to date where the application uses the instance, so a reference that executes in a rarely called POU or a slow task shows an old value. Read it every scan:
VAR
xMasterError : BOOL := FALSE; // your application copy
END_VAR
xMasterError := EtherCAT_Master.xError; // documented member, cyclic task
| Symptom | Meaning | Next check |
|---|---|---|
| Tool shows the error, member FALSE, restart option unchecked | The loss is never latched to the application | Tick Automatically restart slaves |
| Member TRUE during the pull, FALSE after the cable returns | The live-state path working as designed | Latch the loss in logic if anyone needs an alarm |
| Member never moves with both settings ticked | The reading is the suspect | Check the instance name and the calling task |
| Name not found at compile | Instance path mismatch | Insert the member through the engineering tool's picker |
xMasterError in the snippet is your own variable; EtherCAT_Master.xError is the documented member, so only the left side changes between projects.
Working the case: cable pull on the first EtherCAT link #
Inputs, each from the reported setup:
- Event: the EtherCAT cable between the master and the first slave is pulled.
Automatically restart slaves: unchecked.Enable Diagnosis for Devices: unchecked.- Reading:
EtherCAT_Master.xErrorreferenced in a cyclic program.
The rule in words: the application sees the loss only when the master tracks slave loss and recovery as states, and two settings gate that path. Restart handling decides whether those states exist; device diagnosis decides how many members expose them.
The arithmetic is counting the gates. Two settings gate the path; 0 of 2 were set, so 2 − 0 = 2 gates closed and the status stopped at the driver. After the change, 2 of 2 were set, so 2 − 2 = 0 gates closed and the status reached the program.
The result matched the count. Before, a pull left the tool showing the master in error with the member stuck at FALSE, and the reinserted cable produced no trace in the program. After, the pull drove the member TRUE in the application, and the returning cable brought the slave back into the network.
The decision, with its pass rule: 2 pulls × 2 observations each = 4 checks, and all 4 must pass. The member goes TRUE on a pull with the slave idle; the slave rejoins without a manual master restart; the member goes TRUE on a mid-cycle pull, made only when losing the slave is safe for the machine; and it clears when the cable returns. All 4 pass: the diagnostics are done, move on to latching. Both settings on and the member still never moves: the master is exonerated, fix the reading. Tool shows the error with the option off: tick the option before touching anything else.
Latch the loss or it disappears on recovery #
The member follows the live state of the master, so it clears as soon as the slave is back. If the alarm log or the operators need to know a loss happened, latch it on the rising edge into a retained bit and clear that bit only on an acknowledge. The two functions are complementary: restart handling recovers the link, your latch remembers it. If the operator display loses its values during the same outage, that is a comms timeout on the HMI side rather than an EtherCAT diagnostic, and why HMI values show question marks follows that separate path.
Questions asked
Can I see the loss in the program without accepting automatic restart?
In the case worked here, yes for this member: it never moved until the option was ticked, and ticking it was the confirmed fix. If automatic recovery is wrong for the process, leave the option off and read the loss from the extended members that Enable Diagnosis for Devices generates instead. That route was not confirmed here, so test it before relying on it.
Does the option catch slaves lost for reasons other than a cable pull?
The option governs slaves the master loses, however they are lost: a pulled cable, a slave that power-cycles, a device that leaves the operational state on its own. The case this article works proved the cable pull only, so give any other loss mode its own test before you trust the member for it.
Is this behavior the same in every CODESYS version?
The EtherCAT master is delivered as its own component with its own release notes, so recovery behavior can change between versions. Retest the pull after any update of the runtime or of the EtherCAT component, and read the master's help page for the installed version before you rely on the exact sequence of states.
A pull at the first link passed. Is the whole line proven?
No. A pull at the first link proves that segment only. In a line topology a break anywhere downstream drops every slave behind it, so pull the cable at a mid-line point too and hold the result to the same four checks before you call the diagnostics finished.
Do other masters in CODESYS have the same setting?
The principle transfers, the name does not. A Modbus master, for example, exposes its reconnect behavior as an auto-restart of the communication option on the master, and other masters carry equivalent settings in their own configuration. Check the master's own settings page for its reconnect option rather than searching for this exact name.