Connection watchdog / heartbeat

[gijzelaerr]

Summary

Implement a periodic heartbeat mechanism to detect stale or dead connections early, before an actual read/write fails.

Background

TCP connections to PLCs can go stale silently (e.g., a network switch reboots, PLC enters STOP mode, cable is unplugged). The client only discovers this when the next operation times out, which can take a long time. A periodic heartbeat would detect dead connections proactively.

What needs to be done

• Implement a lightweight periodic probe (e.g., read CPU state or send a small SZL request)
• Run heartbeat in a background thread with configurable interval
• Detect and report stale connections via callback or property
• Integrate with auto-reconnect feature (if enabled, trigger reconnect on heartbeat failure)
• Make heartbeat opt-in (disabled by default)
• Use TCP keepalive as an additional layer (SO_KEEPALIVE socket option)
• Add tests
• Add documentation

API Design Ideas

client = snap7.Client(
    heartbeat_interval=10.0,  # seconds, 0 to disable
)

client.connect("192.168.1.10", 0, 1)

# Check connection health
if not client.is_alive:
    print("Connection is stale")

# Callback on heartbeat failure
client.on_heartbeat_failure = lambda: logger.warning("Heartbeat failed")

Notes

• Heartbeat should be a very lightweight operation that doesn't interfere with normal traffic
• Consider using get_cpu_state() or a minimal SZL read as the probe
• Must be thread-safe — heartbeat thread must coordinate with main operations
• Related to auto-reconnect feature — these two features complement each other

[gijzelaerr]

Implementation submitted in #635 — auto-reconnect with exponential backoff and jitter is included alongside heartbeat monitoring in the same PR.