APIs, concepts, guides, and more

◆ NetworkSyncGroupRecover()

void NetworkSyncGroupRecover ( int32_t groupId,
uint32_t timeoutMilliseconds = NetworkSyncGroupRecoverTimeoutMillisecondsDefault )
Description:
Acknowledges any AL error on each of the group's non-Operational nodes and drives them through the EtherCAT AL state machine (PreOp/SafeOp -> Op) using DL-layer register access, then waits for the master to confirm the group's Working Counter matches again (DataValid), which is the recovery-success signal. Members already in OP are skipped. This never calls NetworkShutdown/NetworkStart; cyclic I/O for group 0 and all other groups continues throughout. Recovery typically completes in tens to a few hundred milliseconds (a member serving as the Distributed Clocks reference takes the longest, as DC resynchronization dominates). It handles everything that kept its ESC configuration: commanded state drops, sync manager watchdog trips, and cable disconnect/reconnect.

Recovery raises an error instead of guessing when it cannot succeed:

  • the network is not OPERATIONAL,
  • groupId is 0 (the mandatory default group cannot be recovered),
  • the group is ABSENT (no member responding on the wire; reconnect the hardware first),
  • the group is already RECOVERING (another recovery for the same group is in progress), or
  • a member lost its ESC configuration (e.g. it was power cycled): it no longer answers at its configured station address, and only a full network restart can reclaim it.

If recovery fails (an exception, or a logged error with ThrowExceptions(false)), the method returns with the group's prior state restored so the failure remains visible.

The call blocks until the recovery succeeds or fails. timeoutMilliseconds is a wall-clock deadline for each AL transition of each member node, so the worst case is roughly (member nodes) x 2 x timeoutMilliseconds, plus a fixed 2 s wait for the Working Counter confirmation; size the timeout accordingly. Each individual service-channel operation can overshoot a deadline by up to twice the SDO timeout (see SDOTimeoutMillisecondsDefault) under service-channel contention.

Concurrency: the method does not hold the controller lock while it polls. Recovering different groups from different threads is allowed; calling it again for the same group while a recovery is in flight raises an error. That same-group protection is per process (calls from separate processes attached to the same controller are not serialized). While any recovery is in flight, Reset and Refresh raise an error instead of deleting the node objects the recovery is using; do not Delete the controller during a recovery. See Sync Groups for the full concept.

Parameters
groupIdNon-zero sync group to recover, in the range (0, NetworkSyncGroupCountMaximum).
timeoutMillisecondsPer-node AL-transition timeout in milliseconds. (Default: NetworkSyncGroupRecoverTimeoutMillisecondsDefault)
See also
NetworkSyncGroupStatus, NetworkSyncGroupStatusGet, Axis::SyncGroupFaultActionSet