doc: add I/Q/M symbolic access caveats to API docstrings (#739) (#744)

Document hardware-observed limitations from S7-1200 FW V4.5 testing:
physical PAQ error at zero, TCP RST per I/Q/M connection, and stale
symbolic BOOL LIDs vs. physical PAQ byte.

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

Author: gijzelaerr

s7/_s7commplus_client.py

@@ -211,6 +211,21 @@ def read_symbolic(self, access_area: int, lids: list[int], symbol_crc: int = 0)
         between downloads. Symbolic access navigates the PLC's symbol tree
         using LIDs (Local IDs) discovered via :meth:`browse`.
 
+        .. note:: **I/Q/M area caveats** (observed on S7-1200 FW V4.5):
+
+           - **Physical PAQ LIDs return error when value is 0x00.**
+             Reading a physical Q-byte LID (e.g. QB0) when all outputs are
+             OFF raises ``RuntimeError`` instead of returning ``b"\\x00"``.
+             Callers should catch the exception and treat it as zero.
+           - **TCP RST after first I/Q/M read.** The PLC sends a TCP RST
+             after the first successful I/Q/M ``GetMultiVariables`` per
+             connection. DB reads are unaffected. Workaround: reconnect
+             before each I/Q/M read.
+           - **Symbolic BOOL LIDs can be stale vs. physical PAQ.** A
+             symbolic BOOL tag written via ``SetMultiVariables`` may not
+             reflect later forced writes to the physical address. For
+             reliable output state, read the physical byte LID instead.
+
         Args:
             access_area: Access area ID. For DBs this is
                 ``0x8A0E0000 + db_number``.
@@ -235,7 +250,13 @@ def write_symbolic(self, access_area: int, lids: list[int], data: bytes, symbol_
 
         .. warning:: This method is **experimental** and may change.
 
-        See :meth:`read_symbolic` for context on when to use symbolic access.
+        See :meth:`read_symbolic` for context on when to use symbolic access
+        and I/Q/M area caveats.
+
+        .. note:: Writing a symbolic BOOL tag does **not** update the
+           physical PAQ byte on some S7-1200 firmware versions. A
+           subsequent read of the physical byte LID may show a different
+           value than the symbolic BOOL LID.
 
         Args:
             access_area: Access area ID.

s7/client.py

@@ -310,6 +310,11 @@ def read_tag(self, tag: Any) -> Any:
         S7CommPlus LID-based access.  For classic tags (byte-offset),
         delegates to the legacy client.
 
+        .. note:: When reading symbolic I/Q/M tags on S7-1200 PLCs, see
+           :meth:`~s7._s7commplus_client.S7CommPlusClient.read_symbolic`
+           for known caveats (PAQ error at zero, TCP RST per connection,
+           stale BOOL LIDs).
+
         Args:
             tag: A :class:`~snap7.tags.Tag` instance or address string.