feat: add TCP keepalive and heartbeat_read() for redundant PLC support

- Enable SO_KEEPALIVE with aggressive probes (KEEPIDLE=2s, KEEPINTVL=1s,
  KEEPCNT=2) on all TCP connections for fast dead-peer detection (~4s)
- Add Client.heartbeat_read(timeout_ms) for lightweight liveness checks
  reading 1 byte from M0 with independent short timeout
- Update README with documentation for all optimization features:
  parallel dispatch, plan caching, TCP keepalive, heartbeat read,
  and model-specific tuning table

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: QuakeString

README.rst

@@ -52,11 +52,89 @@ New modules:
 - Extended ``snap7/server/__init__.py`` — Server-side multi-item read support for testing.
 
 
+Parallel Packet Dispatch
+========================
+
+For PLCs that support it (S7-1200, S7-400, S7-1500), multiple optimized read
+packets are dispatched back-to-back on the single TCP connection. Responses are
+matched by S7 sequence number as they arrive, maximizing throughput.
+
+- Auto-tuned ``max_parallel`` based on PLC capabilities (CP info or PDU heuristic).
+- Stale-packet detection with automatic retry.
+- S7-300 / LOGO / S7-200 automatically fall back to sequential dispatch.
+
+
+Optimization Plan Caching
+=========================
+
+The optimization pipeline result (sort → merge → packetize) is cached across
+repeated ``read_multi_vars()`` calls with the same item list. This eliminates
+re-computation overhead during cyclic polling — only the first call pays the
+optimization cost; subsequent calls reuse the cached plan.
+
+
+TCP Keepalive for Fast Dead-Peer Detection
+==========================================
+
+All TCP connections enable ``SO_KEEPALIVE`` with aggressive probe settings:
+
+- **Linux**: ``TCP_KEEPIDLE=2s``, ``TCP_KEEPINTVL=1s``, ``TCP_KEEPCNT=2``
+  — detects dead connections within ~4 seconds.
+- **macOS**: ``TCP_KEEPALIVE=2s``.
+
+This catches network-level failures (cable pull, PLC power loss, OS crash)
+far faster than the default TCP timeout (typically 30–120 seconds), which is
+critical for industrial applications where data gaps must be minimized.
+
+
+Heartbeat Read for Redundant PLC Monitoring
+===========================================
+
+New ``Client.heartbeat_read(timeout_ms=500)`` method provides a lightweight
+liveness check designed for monitoring standby PLCs in redundant S7 systems
+(S7-300H, S7-400H, S7-1500R/H).
+
+.. code-block:: python
+
+    client = snap7.Client()
+    client.connect("192.168.1.11", 0, 1)
+
+    # Fast liveness check — reads 1 byte from M0
+    if client.heartbeat_read(timeout_ms=300):
+        print("Standby PLC is alive")
+    else:
+        print("Standby PLC is unreachable")
+
+- Reads 1 byte from Merker area (M0) — negligible PLC scan cycle impact.
+- Uses a short, independent timeout (default 500 ms) without affecting the
+  client's normal socket timeout.
+- Returns ``True`` / ``False`` — no exceptions on timeout or connection error.
+- Designed for background heartbeat threads monitoring the inactive CPU in
+  a dual-connection redundancy setup.
+
+
+Model-Specific Tuning
+=====================
+
+Read optimization respects PLC-specific limits:
+
+==============================  ==================  ===============
+PLC Model                       Max Read Block      Max Parallel
+==============================  ==================  ===============
+S7-200 / S7-200 Smart / LOGO   100 bytes           1 (sequential)
+S7-300                          200 bytes           1 (sequential)
+S7-400                          200 bytes           4
+S7-1200                         1000 bytes          8
+S7-1500                         1000 bytes          8
+==============================  ==================  ===============
+
+
 Installation
 ============
 
 Install using pip::
 
-   $ pip install python-snap7
+   $ pip install snap7-optimized
 
-No native libraries or platform-specific dependencies are required - python-snap7 is a pure Python package that works on all platforms.
+No native libraries or platform-specific dependencies are required - this is a
+pure Python package that works on all platforms (Linux, Windows, macOS).

snap7/client.py

@@ -5,6 +5,7 @@
 """
 
 import logging
+import socket
 import struct
 import time
 from typing import List, Any, Optional, Tuple, Union, Callable, cast
@@ -337,6 +338,38 @@ def get_connected(self) -> bool:
             return False
         return self.connection.check_connection()
 
+    def heartbeat_read(self, timeout_ms: int = 500) -> bool:
+        """Fast liveness check — reads 1 byte from Merker area with short timeout.
+
+        Designed for redundant PLC heartbeat monitoring. Reads M0 (1 byte)
+        which has negligible impact on PLC scan cycle. Uses a short timeout
+        to detect dead connections quickly.
+
+        Args:
+            timeout_ms: Timeout in milliseconds for this single read (default 500ms).
+
+        Returns:
+            True if PLC responded, False if timeout/error occurred.
+        """
+        if not self.connected or self.connection is None:
+            return False
+
+        original_timeout = self.connection.socket.gettimeout() if self.connection.socket else None
+        try:
+            self.connection.socket.settimeout(timeout_ms / 1000.0)
+            self.read_area(Area.MK, 0, 0, 1)
+            return True
+        except (S7TimeoutError, S7ConnectionError, socket.timeout, socket.error, OSError):
+            return False
+        except Exception:
+            return False
+        finally:
+            if self.connection and self.connection.socket and original_timeout is not None:
+                try:
+                    self.connection.socket.settimeout(original_timeout)
+                except OSError:
+                    pass
+
     def db_read(self, db_number: int, start: int, size: int) -> bytearray:
         """
         Read data from DB.

snap7/connection.py

@@ -197,13 +197,25 @@ def receive_data(self) -> bytes:
             raise S7ConnectionError(f"Receive failed: {e}")
 
     def _tcp_connect(self) -> None:
-        """Establish TCP connection."""
+        """Establish TCP connection with TCP keepalive for fast dead-peer detection."""
         self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         self.socket.settimeout(self.timeout)
 
         try:
             self.socket.connect((self.host, self.port))
-            logger.debug(f"TCP connected to {self.host}:{self.port}")
+
+            # Enable TCP keepalive for fast detection of dead connections.
+            # This catches network-level failures (cable pull, OS crash)
+            # within ~4 seconds instead of waiting for the default TCP timeout.
+            self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+            if hasattr(socket, 'TCP_KEEPIDLE'):  # Linux
+                self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 2)
+                self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 1)
+                self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 2)
+            elif hasattr(socket, 'TCP_KEEPALIVE'):  # macOS
+                self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPALIVE, 2)
+
+            logger.debug(f"TCP connected to {self.host}:{self.port} (keepalive enabled)")
         except socket.error as e:
             raise S7ConnectionError(f"TCP connection failed: {e}")