# AbCip — ControlLogix HSBY paired-IP support

PR abcip-5.1 adds **non-transparent** HSBY (Hot-Standby) awareness to the AB
CIP driver. Each device may declare a partner gateway; when both gateways are
up the driver concurrently probes a role tag on each chassis and reports
which one is currently Active.

PR abcip-5.1 only **gathers + reports** the role. PR abcip-5.2 is the
follow-up that wires the resolved active address into
`AbCipDriver.ResolveHost` so reads and writes route to whichever chassis is
Active without operator intervention.

## When to use HSBY paired IPs

You have a redundant **ControlLogix** chassis pair (1756-RM redundancy
module, two CPUs, one acting + one standby) and the SCADA / OPC UA layer
needs to keep talking to *whichever chassis is currently Active* without an
operator manually re-pointing the connection.

Pre-5.1 the driver only knew about a single `HostAddress`. After a
hot-standby switch-over, the standby (now Active) carried a **different IP**
and the driver kept probing the dead-but-was-Active address until someone
edited the config.

PR abcip-5.1 closes the visibility half of that gap by reading the role tag
on both chassis. PR abcip-5.2 closes the routing half by re-pointing
`ResolveHost` at the Active address each tick.

## Configuration

```jsonc
{
    "Devices": [
        {
            "HostAddress": "ab://10.0.0.5/1,0",
            "PartnerHostAddress": "ab://10.0.0.6/1,0",
            "Hsby": {
                "Enabled": true,
                "RoleTagAddress": "WallClockTime.SyncStatus",
                "ProbeIntervalMs": 2000
            }
        }
    ]
}
```

| Field | Default | Notes |
|---|---|---|
| `PartnerHostAddress` | `null` | Canonical `ab://gateway[:port]/cip-path` of the partner chassis. `null` = no HSBY pair; the driver behaves exactly like every pre-5.1 build. |
| `Hsby.Enabled` | `false` | Master switch. When `false` (or `Hsby` omitted) no role probing happens, even if `PartnerHostAddress` is set. |
| `Hsby.RoleTagAddress` | `WallClockTime.SyncStatus` | Address of the role tag on each chassis. See [role-tag detection matrix](#role-tag-detection-matrix). |
| `Hsby.ProbeIntervalMs` | `2000` | How often each chassis is sampled. 2 s is a good default — tight enough to detect a switch-over within one Admin-UI refresh, loose enough to leave headroom for the regular probe loop. |

## Feature-flag gate (`Redundancy.Hsby.Enabled`)

`Hsby.Enabled = false` (the default) is the off-switch for the entire
feature. The role-probe loop never starts, the diagnostics keys are not
emitted, and the driver behaves identically to a pre-5.1 build. This is the
gate to flip when an operator wants to roll the feature out cautiously
across a fleet — set `Hsby.Enabled = true` per-device in driver config (no
build flag, no env var).

When the gate is on but the partner gateway is unreachable, the role-probe
loop reports `HsbyRole.Unknown` for the partner each tick. The primary's
role still drives the active-chassis resolution; the operator sees the
partner's role as Unknown in the Admin UI / driver diagnostics, which is the
correct surface for "we can't reach the standby chassis right now."

## Role-tag detection matrix

| Firmware / fronts | Address | Decode |
|---|---|---|
| **v20 / v24 / v32+ ControlLogix HSBY** | `WallClockTime.SyncStatus` (DINT) | `0` = Standby, `1` = Synchronized / Active, `2` = Disqualified, anything else = Unknown |
| **PLC-5 / SLC500 status-byte fallback** | `S:34` Module Status word | bit 0 = "this chassis is Active". Bit set → `Active`; clear → `Standby` |
| **Custom user role tag** | any DINT-typed CIP path | Same matrix as `WallClockTime.SyncStatus` (0 / 1 / 2). Out-of-range values → Unknown. |

`AbCipHsbyRoleProber.MapValueToRole` is the value-to-role mapper; unit tests
in `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests/AbCipHsbyTests.cs` pin every
row of the matrix.

## What gets reported

The driver surfaces three diagnostics counters per HSBY-enabled device
(visible via `driver-diagnostics` RPC + the Admin UI):

| Counter | Value |
|---|---|
| `AbCip.HsbyActive` | `1` if primary is Active, `2` if partner is Active, `0` if neither (or HSBY off) |
| `AbCip.HsbyPrimaryRole` | `(int)HsbyRole` — `0` = Unknown, `1` = Active, `2` = Standby, `3` = Disqualified |
| `AbCip.HsbyPartnerRole` | Same encoding as `HsbyPrimaryRole`, observed on the partner chassis |

When more than one HSBY pair is configured on the same driver instance the
flat keys are scoped per primary host: `AbCip.HsbyActive[ab://10.0.0.5/1,0]`,
etc.

The `DeviceState.ActiveAddress` field (internal; surfaced via
`HsbyActive` diagnostics) is the address PR 5.2 will route through
`ResolveHost`.

### Active-resolution rules

| Primary role | Partner role | `ActiveAddress` resolution |
|---|---|---|
| Active | Standby / Disqualified / Unknown | primary |
| Standby / Disqualified / Unknown | Active | partner |
| Active | Active (split-brain) | **primary wins**, warning logged |
| Standby + Standby | Standby + Standby | `null` (PR 5.2 will surface as `BadCommunicationError`) |
| Unknown + Unknown | Unknown + Unknown | `null` |

Split-brain (both chassis claim Active simultaneously) is a real
production failure mode — typically a redundancy-module misconfiguration or
a partial network split. The driver picks primary deterministically + emits
a warning through `AbCipDriverOptions.OnWarning` so operators see it in the
log.

## CLI flags

The `otopcua-abcip-cli` tool exposes the HSBY plumbing through two surfaces
(see [Driver.AbCip.Cli.md](../Driver.AbCip.Cli.md) for the full CLI guide):

- `--partner <gateway>` — global flag on every command. Sets
  `PartnerHostAddress` + auto-enables `Hsby.Enabled = true` so the role
  probe runs alongside any read / write / subscribe.
- `hsby-status` — dedicated command that prints which chassis is
  currently Active. Reads the role tag on both gateways for a few ticks +
  prints the `(primary, partner, active)` tuple.

```powershell
# Print which chassis is Active right now
otopcua-abcip-cli hsby-status -g ab://10.0.0.5/1,0 --partner ab://10.0.0.6/1,0

# Subscribe through the active chassis (PR 5.2 follow-up — today the
# subscribe stays pointed at the primary; the role probe runs alongside).
otopcua-abcip-cli subscribe -g ab://10.0.0.5/1,0 --partner ab://10.0.0.6/1,0 \
    -t Motor01_Speed --type Real -i 500
```

## Test coverage

- **Unit** (`tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests/AbCipHsbyTests.cs`):
    - Pure `MapValueToRole` matrix (WallClockTime.SyncStatus + S:34 bit
      mask + Unknown values).
    - End-to-end driver loop: primary Active / partner Standby resolves to
      primary; both Active resolves to primary with a warning; both
      Standby clears `ActiveAddress`; primary read failure routes to
      partner.
    - Diagnostics surface (`AbCip.HsbyActive` / `HsbyPrimaryRole` /
      `HsbyPartnerRole`).
    - DTO JSON round-trip (`PartnerHostAddress` + `Hsby.{Enabled,
      RoleTagAddress, ProbeIntervalMs}` survive deserialise → driver →
      `DeviceState`).
    - `Hsby.Enabled = false` → no role probing.
- **Integration** (`tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbCipHsbyRoleProberTests.cs`):
    - **Skipped by default** (`Assert.Skip`) — `ab_server` cannot emulate
      a ControlLogix HSBY pair (no `WallClockTime.SyncStatus`, no second
      chassis concept). The Docker `paired` profile (PR 5.1) brings up two
      `ab_server` instances + a stub `hsby-mux` sidecar so the topology is
      documented, but PR 5.2 follow-up needs a patched `ab_server` image
      that actually serves the role tag before the integration test can
      assert anything against the wire.
    - Trait `Category=Hsby` so `dotnet test --filter Category=Hsby` finds
      this test once it's promoted.

## Follow-ups (PR 5.2 + beyond)

- **PR 5.2** — wire `ActiveAddress` into `ResolveHost` so reads/writes
  route to the live chassis automatically. Today's PR only **gathers** the
  role.
- **Patched `ab_server` image** — add a writable `WallClockTime.SyncStatus`
  tag (or a separate Python shim) so the Docker `paired` profile can
  exercise the wire-level role probe.
- **`hsby-mux` REST endpoint** — `POST /flip {"active": "primary"}` writes
  `1` to the chosen chassis + `0` to the other so integration tests can
  drive switch-overs deterministically.
- **GuardLogix HSBY** — same role-tag plumbing applies; verify against a
  real 1756-L8xS pair when one is on-site.

## See also

- [`docs/Driver.AbCip.Cli.md`](../Driver.AbCip.Cli.md) — `--partner` flag +
  `hsby-status` command reference
- [`docs/drivers/AbServer-Test-Fixture.md`](AbServer-Test-Fixture.md) §"What
  it does NOT cover" — HSBY entry
- [`docs/Redundancy.md`](../Redundancy.md) — server-level (OPC UA-stack)
  redundancy; HSBY is the **driver-level** companion