lmxopcua/docs/Driver.AbCip.Cli.md

# `otopcua-abcip-cli` — AB CIP test client

Ad-hoc probe / read / write / subscribe tool for ControlLogix / CompactLogix /
Micro800 / GuardLogix PLCs, talking to the **same** `AbCipDriver` the OtOpcUa
server uses (libplctag under the hood).

Second of four driver test-client CLIs (Modbus → AB CIP → AB Legacy → S7 →
TwinCAT). Shares `Driver.Cli.Common` with the others.

## Build + run

```powershell
dotnet run --project src/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Cli -- --help
```

## Common flags

| Flag | Default | Purpose |
|---|---|---|
| `-g` / `--gateway` | **required** | Canonical `ab://host[:port]/cip-path` |
| `-f` / `--family` | `ControlLogix` | ControlLogix / CompactLogix / Micro800 / GuardLogix |
| `--timeout-ms` | `5000` | Per-operation timeout |
| `--addressing-mode` | `Auto` | `Auto` / `Symbolic` / `Logical` — see [AbCip-Performance §Addressing mode](drivers/AbCip-Performance.md#addressing-mode). `Logical` against Micro800 silently falls back to Symbolic with a warning. |
| `--partner` | _(unset)_ | PR abcip-5.1 — partner gateway URI for a ControlLogix HSBY pair (e.g. `ab://10.0.0.6/1,0`). When set, the driver runs a second role-probe loop against the partner and the [`hsby-status`](#hsby-status--which-chassis-is-active-now) command can surface which chassis is currently Active. See [AbCip-HSBY.md](drivers/AbCip-HSBY.md) for the full guide. |
| `--verbose` | off | Serilog debug output |

Family ↔ CIP-path cheat sheet:
- **ControlLogix / CompactLogix / GuardLogix** — `1,0` (slot 0 of chassis)
- **Micro800** — empty path, just `ab://host/`
- **Sub-slot Logix** (rare) — `1,3` for slot 3

## Commands

### `probe` — is the PLC up?

```powershell
# ControlLogix — read the canonical libplctag system tag
otopcua-abcip-cli probe -g ab://10.0.0.5/1,0 -t @raw_cpu_type --type DInt

# Micro800 — point at a user-supplied global
otopcua-abcip-cli probe -g ab://10.0.0.6/ -f Micro800 -t _SYSVA_CLOCK_HOUR --type DInt
```

### `read` — single Logix tag

```powershell
# Controller scope
otopcua-abcip-cli read -g ab://10.0.0.5/1,0 -t Motor01_Speed --type Real

# Program scope
otopcua-abcip-cli read -g ab://10.0.0.5/1,0 -t "Program:Main.Counter" --type DInt

# Array element
otopcua-abcip-cli read -g ab://10.0.0.5/1,0 -t "Recipe[3]" --type Real

# UDT member (dotted path)
otopcua-abcip-cli read -g ab://10.0.0.5/1,0 -t "Motor01.Speed" --type Real
```

#### Diagnostic / system tags

PR abcip-4.3 exposes five read-only diagnostic variables per device under
`AbCip/<device>/_System/` in the OPC UA address space (see
[AbCip-Operability §System tags](drivers/AbCip-Operability.md#system-tags--_system-folder)
for the full table). These are not reachable through the AB CIP CLI — they
live on the OPC UA server side, not the libplctag wire — so to read one,
point the **OPC UA client** CLI at the running OtOpcUa server:

```powershell
# Read _ConnectionStatus for one device through the OPC UA server
otopcua-client-cli read -u opc.tcp://localhost:4840 \
    -n "ns=2;s=AbCip/ab://10.0.0.5/1,0/_System/_ConnectionStatus"
```

### `write` — single Logix tag

Same shape as `read` plus `-v`. Values parse per `--type` using invariant
culture. Booleans accept `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`.
Structure (UDT) writes need the member layout declared in a real driver config
and are refused by the CLI.

```powershell
otopcua-abcip-cli write -g ab://10.0.0.5/1,0 -t Motor01_Speed --type Real -v 3.14
otopcua-abcip-cli write -g ab://10.0.0.5/1,0 -t StartCommand --type Bool -v true
```

### `subscribe` — watch a tag until Ctrl+C

```powershell
otopcua-abcip-cli subscribe -g ab://10.0.0.5/1,0 -t Motor01_Speed --type Real -i 500
```

### `hsby-status` — which chassis is Active now?

PR abcip-5.1 — read the role tag (`WallClockTime.SyncStatus` by default,
`S:34` for legacy SLC500 / PLC-5 fronts) on a ControlLogix HSBY pair and
print which chassis is currently Active. Requires `--partner`.

```powershell
otopcua-abcip-cli hsby-status -g ab://10.0.0.5/1,0 --partner ab://10.0.0.6/1,0

# Custom role tag (legacy fronts) and more samples
otopcua-abcip-cli hsby-status -g ab://10.0.0.5/1,0 --partner ab://10.0.0.6/1,0 \
    --role-tag S:34 --samples 5
```

| Flag | Default | Purpose |
|---|---|---|
| `--role-tag` | `WallClockTime.SyncStatus` | Address of the role tag. Use `S:34` for SLC500 / PLC-5. |
| `--samples` | `3` | Number of role-probe ticks to wait for before printing. |

The output prints the resolved roles + the address of whichever chassis the
driver currently considers Active. PR abcip-5.1 only **reports** the role —
PR abcip-5.2 will land the routing change so reads / writes flow to the
Active chassis automatically.

See [AbCip-HSBY.md](drivers/AbCip-HSBY.md) for the role-tag detection matrix
+ active-resolution rules + the feature-flag gate.

### `rebrowse` — force a controller-side `@tags` re-walk

PR abcip-2.5 (issue #233) added `RebrowseAsync` to drop the cached UDT
template shapes and re-run the symbol-table enumerator without restarting
the driver. The CLI variant builds a transient driver against the supplied
gateway, runs the rebrowse, and prints the freshly discovered tag names —
useful after a controller program-download to confirm the new tags are
visible on the wire before wiring them through the OtOpcUa server.

```powershell
otopcua-abcip-cli rebrowse -g ab://10.0.0.5/1,0
```

## Refreshing the tag DB

Two operator-facing surfaces drive the same `RebrowseAsync` plumbing — pick
the one that matches your context:

| Surface | When to use | Command |
|---|---|---|
| **CLI `rebrowse`** | Off-server validation. Spins up a transient driver against the gateway, prints the discovered tag list, no shared state with the live OtOpcUa server. | `otopcua-abcip-cli rebrowse -g ab://10.0.0.5/1,0` |
| **OPC UA write to `_RefreshTagDb`** | Production / Admin-UI button (PR abcip-4.4). Forces the **live** driver to re-walk + clear its template cache. The `AbCip.RefreshTriggers` driver-diagnostics counter increments per truthy write. | `otopcua-client-cli write -u opc.tcp://localhost:4840 -n "ns=2;s=AbCip/ab://10.0.0.5/1,0/_System/_RefreshTagDb" -v true --type Boolean` |

Read-back semantics: `_RefreshTagDb` always reads back as `false` (Kepware-
style "latches to idle the moment the dispatch returns") so a subscribed
client sees a stable shape regardless of how many refreshes have fired.
Falsy / unparseable writes are no-ops that still report `Good` so a UI
template that resets the trigger flag after firing it doesn't see a phantom
error. See
[AbCip-Operability §System tags](drivers/AbCip-Operability.md#refreshing-the-tag-db-via-opc-ua-write)
for the full semantics + the diagnostics counter wiring.

## Typical workflows

- **"Is the PLC reachable?"** → `probe`.
- **"Did my recipe write land?"** → `write` + `read` back.
- **"Why is tag X flipping?"** → `subscribe`.
- **"Is this GuardLogix safety tag writable from non-safety?"** → `write` and
  read the status code — safety tags surface `BadNotWritable` / CIP errors,
  non-safety tags surface `Good`.
- **"Did my program download show up in the address space?"** → `rebrowse`
  (off-server) or write `true` to the live server's `_RefreshTagDb` system
  tag (in-server, PR abcip-4.4) — both drop the template cache + force a
  fresh `@tags` walk.

## Connection Size

PR abcip-3.1 introduced a per-device `ConnectionSize` override on the driver
side (`AbCipDeviceOptions.ConnectionSize`, range `500..4002`). The CLI does
not expose a flag for it — every CLI invocation uses the family-default
Connection Size (4002 / 504 / 488 depending on `--family`). When a Forward
Open is rejected with a CIP error like `0x01/0x113` ("connection request
size invalid"), the symptom is almost always a **mismatch between the chosen
family default and the controller firmware**:

- **v19-and-earlier ControlLogix** caps at 504 — pick `--family CompactLogix`
  on the CLI to fall back to that narrower default.
- **5069-L1/L2/L3 CompactLogix** narrow-buffer parts also cap at 504, which
  is the family default already.
- **FW20+ ControlLogix** accepts the full 4002.

For the warning *"AbCip device 'X' family 'Y' uses a narrow-buffer profile
(default ConnectionSize Z); the configured ConnectionSize N exceeds the
511-byte legacy-firmware cap..."* see
[`docs/drivers/AbCip-Performance.md`](drivers/AbCip-Performance.md) — that
warning is fired by the driver host, not the CLI.

## Related operability knobs

- [`docs/drivers/AbCip-Operability.md`](drivers/AbCip-Operability.md) — Phase 4
  per-tag knobs (per-tag scan rate, deadband, etc). The CLI does not expose
  these knobs directly; they're set in driver config JSON and consumed by the
  driver at subscribe time.