Auto: ablegacy-9 — per-device timeout / retry overrides

Closes #252

docs/Driver.AbLegacy.Cli.md

@@ -19,7 +19,8 @@ dotnet run --project src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Cli -- --help
 |---|---|---|
 | `-g` / `--gateway` | **required** | Canonical `ab://host[:port]/cip-path` |
 | `-P` / `--plc-type` | `Slc500` | Slc500 / MicroLogix / Plc5 / LogixPccc |
-| `--timeout-ms` | `5000` | Per-operation timeout |
+| `--timeout-ms` | `5000` | Per-operation timeout — see precedence note below |
+| `--retries` | `0` | Retry count on transient `BadCommunicationError` (PR 9 / #252) |
 | `--verbose` | off | Serilog debug output |
 
 Family ↔ CIP-path cheat sheet:
@@ -29,6 +30,31 @@ Family ↔ CIP-path cheat sheet:
 - **LogixPccc** — `1,0` (Logix controller accessed via the PCCC compatibility
   layer; rare)
 
+### Per-device timeout / retry tuning (#252, PR 9)
+
+The CLI's `--timeout-ms` is the **driver-wide default** when launched as a
+one-shot test client. In production (server-side, multi-device deployment)
+each `AbLegacyDeviceOptions` row carries its own optional `Timeout` /
+`Retries` that override the driver-wide value.
+
+Precedence (highest → lowest): per-device override → driver-wide default →
+hard-coded fallback (2000 ms / 0 retries).
+
+Tuning cheat sheet — start here, measure, then trim:
+
+| Family | Recommended `Timeout` | Notes |
+|---|---|---|
+| SLC 5/01 (RS-232 / DH+ bridge) | **5000 ms** | Slowest of the bunch; serial round-trip plus DH+ hop |
+| SLC 5/02 / 5/03 (DH+) | 3000 ms | Bridged Ethernet → DH+ adds ~1 s |
+| **SLC 5/04 / 5/05** (Ethernet) | **2000 ms** | Fastest of the SLC family — direct EIP/PCCC |
+| MicroLogix 1100 / 1400 | **3000 ms** | Single-CPU, slow scan; no backplane |
+| PLC-5 (Ethernet I/F) | 2500 ms | Comparable to SLC 5/05 over EIP |
+| LogixPccc compat layer | 2000 ms | Logix CPU is fast; PCCC layer is the floor |
+
+A small `--retries 1` (or `2` for slow chassis) is generally safe — the retry
+loop only fires on transient `BadCommunicationError`; terminal errors
+(`BadNodeIdUnknown`, `BadTypeMismatch`, …) surface on the first attempt.
+
 ## PCCC address primer
 
 File letters imply data type; type flag still required so the CLI knows how to

docs/drivers/AbLegacy-Test-Fixture.md

@@ -123,6 +123,33 @@ cover the common ones but uncommon ones (`R` counters, `S` status files,
    network; parts are end-of-life but still available. PLC-5 +
    LogixPccc-mode behaviour + DF1 serial need specific controllers.
 
+## Per-device options (`AbLegacyDeviceOptions`)
+
+Each entry in `AbLegacyDriverOptions.Devices` carries:
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `HostAddress` | string | required | `ab://host[:port]/cip-path` |
+| `PlcFamily` | enum | `Slc500` | Slc500 / MicroLogix / Plc5 / LogixPccc |
+| `DeviceName` | string | null | Friendly label used in browse + diagnostics |
+| `Timeout` | TimeSpan? | null → driver-wide default | **PR 9 / #252** — wins over the driver-wide `Timeout`. Mix-and-match: SLC 5/01 ≈ 5 s, SLC 5/05 ≈ 2 s, MicroLogix 1100 ≈ 3 s |
+| `Retries` | int? | null → driver-wide default → 0 | **PR 9 / #252** — retries on transient `BadCommunicationError`; terminal errors surface on the first attempt |
+
+JSON shape (mirrored on `AbLegacyDeviceDto`):
+
+```json
+{
+  "HostAddress": "ab://192.168.1.10/1,0",
+  "PlcFamily": "Slc500",
+  "DeviceName": "slc-5-01-line-A",
+  "TimeoutMs": 5000,
+  "Retries": 1
+}
+```
+
+Per-device overrides also flow into the probe loop — slow chassis won't be
+falsely marked Stopped just because the driver-wide probe timeout is tight.
+
 ## Key fixture / config files
 
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyServerFixture.cs`