Auto: abcip-3.2 — symbolic vs logical addressing toggle

Closes #236

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriverOptions.cs

@@ -114,11 +114,58 @@ public sealed class AbCipDriverOptions
 ///     supported range [500..4002] at <c>InitializeAsync</c>; out-of-range values fault the
 ///     driver. <c>null</c> uses the family default — back-compat with deployments that haven't
 ///     touched the knob.</param>
+/// <param name="AddressingMode">PR abcip-3.2 — controls whether the driver addresses tags by
+///     ASCII symbolic path (the default), by CIP logical-segment instance ID, or asks the driver
+///     to pick. Logical addressing skips per-poll ASCII parsing on every read and unlocks
+///     symbol-table-cached scans for 500+-tag projects, but requires a one-time symbol-table
+///     walk at first read + is unsupported on Micro800 / SLC500 / PLC5 (their CIP firmware does
+///     not honour Symbol Object instance IDs). When the user picks <see cref="AbCip.AddressingMode.Logical"/>
+///     against an unsupported family the driver logs a warning + falls back to symbolic so
+///     misconfiguration does not fault the driver. <see cref="AbCip.AddressingMode.Auto"/> currently
+///     resolves to symbolic — a future PR will plumb a real auto-detection heuristic; the docs
+///     in <c>docs/drivers/AbCip-Performance.md</c> §"Addressing mode" call this out.</param>
 public sealed record AbCipDeviceOptions(
     string HostAddress,
     AbCipPlcFamily PlcFamily = AbCipPlcFamily.ControlLogix,
     string? DeviceName = null,
-    int? ConnectionSize = null);
+    int? ConnectionSize = null,
+    AddressingMode AddressingMode = AddressingMode.Auto);
+
+/// <summary>
+///     PR abcip-3.2 — how the AB CIP driver addresses tags on a given device. <see cref="Symbolic"/>
+///     is the historical default + matches every previous driver build: each read carries the tag
+///     name as ASCII bytes + the controller parses the path on every request. <see cref="Logical"/>
+///     uses CIP logical-segment instance IDs (Symbol Object class 0x6B) — the controller looks the
+///     tag up in its own symbol table once + the driver caches the resolved instance ID for
+///     subsequent reads, eliminating the per-poll ASCII parse step. <see cref="Auto"/> lets the
+///     driver pick (today: always Symbolic; a future PR fingerprints the controller and switches
+///     to Logical when supported).
+/// </summary>
+/// <remarks>
+///     Logical addressing requires a one-time symbol-table walk at the first read on the device
+///     (the driver issues an <c>@tags</c> read via <see cref="LibplctagTagEnumerator"/> and stores
+///     the name → instance-id map on the per-device <c>DeviceState</c>). It is unsupported on
+///     Micro800 / SLC500 / PLC5 — see <see cref="PlcFamilies.AbCipPlcFamilyProfile.SupportsLogicalAddressing"/>.
+///     The libplctag .NET wrapper (1.5.x) does not expose a public knob for instance-ID
+///     addressing, so the driver translates Logical → libplctag attribute via reflection on
+///     <c>NativeTagWrapper.SetAttributeString</c> — same best-effort fallback pattern as
+///     PR abcip-3.1's ConnectionSize plumbing.
+/// </remarks>
+public enum AddressingMode
+{
+    /// <summary>Driver picks. Currently resolves to <see cref="Symbolic"/>; future PR may
+    ///     auto-detect based on family + firmware + symbol-table size.</summary>
+    Auto = 0,
+
+    /// <summary>ASCII symbolic-path addressing — the libplctag default. Per-poll ASCII parse on
+    ///     the controller; works on every CIP family.</summary>
+    Symbolic = 1,
+
+    /// <summary>CIP logical-segment / instance-ID addressing. Requires a one-time
+    ///     symbol-table walk at first read; subsequent reads skip ASCII parsing on the
+    ///     controller. Unsupported on Micro800 / SLC500 / PLC5.</summary>
+    Logical = 2,
+}
 
 /// <summary>
 ///     One AB-backed OPC UA variable. Mirrors the <c>ModbusTagDefinition</c> shape.