Joseph Doherty
8f5b265db8
Re-review of 3de2cc3b/454775c6: - AlarmTransitions could not reach (inactive, unacked): (active,acked)->(inactive,unacked) emitted Clear (host stayed acked) and a first-seen cleared-unacked condition emitted nothing. The table is now total; an exhaustive test replays every (prior, target) pair through the projector's semantics. - The per-RawPath read-compute-emit was a lock-free TryGetValue/set across SDK publish threads; it now runs under one lock with the projection and emission. - Condition BRANCH events (non-null BranchId) were projected (flipping the trunk) and remembered as the ack target (acking the branch); they are dropped. BranchId is select clause 9. - EventId is copied, not aliased from the decoded notification. - An unchanged state re-emitted Unspecified; it now emits nothing unless message/severity changed (an Unspecified projects from the host projector's default after a redeploy reset it). - Exact upstream severity rides OpcUaSeverity (#626) instead of being re-bucketed. - ShutdownAsync no longer forgets the last-told state: a reinit re-subscribes the same set and the refresh would otherwise re-raise every acked alarm. A CHANGED set (host rebuilt) forgets it. ConditionRefresh: called after the alarm event item is created, after an in-place reconnect (subscriptions found on the new session by display name, since a recreate clones them) and on RefreshRequired. Refresh markers are never projected. BadNotSupported/BadMethodInvalid/... logs once. Wire test: a condition already active before subscribe is reported Raise; a release+resubscribe refresh re-raises nothing (falsified by disabling the refresh call). Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
211 lines
13 KiB
Markdown
211 lines
13 KiB
Markdown
# OPC UA Client (Gateway) Driver
|
|
|
|
Getting-started guide for the OPC UA Client driver. This is the short path — for
|
|
the full per-field spec read [`docs/v2/driver-specs.md §8`](../v2/driver-specs.md),
|
|
and for the test-harness map read [OpcUaClient-Test-Fixture.md](OpcUaClient-Test-Fixture.md).
|
|
|
|
## What it talks to
|
|
|
|
A **remote OPC UA server**. This driver runs the *opposite* direction from the
|
|
usual "server exposes PLC data" flow: it acts as an OPC UA **client**, opens a
|
|
`Session` against an upstream server, and re-exposes that server's address space
|
|
through the local OtOpcUa server. Browse, read, write, subscribe, alarm, and
|
|
history calls are passed through to the upstream endpoint.
|
|
|
|
It is built on the OPC Foundation UA .NET Standard reference SDK and runs
|
|
in-process in the OtOpcUa server's .NET 10 AnyCPU host — pure managed, no
|
|
out-of-process isolation.
|
|
|
|
> There is **no standalone driver CLI** for the OPC UA Client driver. To exercise
|
|
> a remote OPC UA endpoint by hand, point the general-purpose
|
|
> [Client CLI](../Client.CLI.md) at it directly.
|
|
|
|
## Project split
|
|
|
|
| Project | Target | Role |
|
|
|---------|--------|------|
|
|
| `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/` | net10.0 | In-process driver — session lifetime, read / write / subscribe / alarm / history passthrough |
|
|
| `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser/` | net10.0 | `IDriverBrowser` — live address-picker browse used by the AdminUI |
|
|
| `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Contracts/` | net10.0 | Config records + enums bound from `DriverConfig` JSON |
|
|
|
|
## Minimum deployment
|
|
|
|
```jsonc
|
|
"Drivers": {
|
|
"upstream-1": {
|
|
"Type": "OpcUaClient",
|
|
"Config": {
|
|
"EndpointUrl": "opc.tcp://plc.internal:4840",
|
|
"SecurityPolicy": "None",
|
|
"SecurityMode": "None",
|
|
"AuthType": "Anonymous",
|
|
"TargetNamespaceKind": "Equipment"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
`EndpointUrls` (a list) takes precedence over the single-URL `EndpointUrl` and
|
|
provides ordered **failover** — the driver tries each candidate in turn at init
|
|
and on session drop, and the first to connect wins (e.g. a hot-standby pair on
|
|
4840 / 4841). See
|
|
`src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Contracts/OpcUaClientDriverOptions.cs`
|
|
for every field (security policy/mode, auth type, session timeout, keep-alive,
|
|
reconnect period, browse root, node/depth caps).
|
|
|
|
### Session lifetime
|
|
|
|
A single `Session` per driver instance; subscriptions multiplex onto it. The
|
|
SDK reconnect handler takes the session down and brings it back on remote-server
|
|
restart, re-sending subscriptions on reconnect so monitored-item handles don't
|
|
dangle. Stored NodeIds embed the server-stable namespace **URI** (not the
|
|
session-relative `ns=N` index) so a remote namespace-table reorder across a
|
|
restart doesn't silently re-point references at the wrong namespace.
|
|
|
|
### Namespace assignment
|
|
|
|
This is the only driver that gateways into **either** namespace kind, decided
|
|
per instance via `TargetNamespaceKind`:
|
|
|
|
- `Equipment` — the remote server exposes raw equipment data; remote browse
|
|
paths are remapped to UNS via a required `UnsMappingTable`.
|
|
- `SystemPlatform` — the remote server exposes processed/derived data; the
|
|
remote hierarchy is preserved with no UNS conversion (and the mapping table
|
|
must be empty).
|
|
|
|
The choice is enforced at startup so a misconfiguration fails draft validation
|
|
rather than surfacing as a runtime surprise.
|
|
|
|
## Capability surface
|
|
|
|
`OpcUaClientDriver : IDriver, ITagDiscovery, IReadable, IWritable, ISubscribable, IHostConnectivityProbe, IAlarmSource, IHistoryProvider`
|
|
(`src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriver.cs:31`).
|
|
|
|
| Capability | Path | Notes |
|
|
|------------|------|-------|
|
|
| `ITagDiscovery` | `DiscoverAsync` (recursive browse) | Mirrors the upstream tree from `BrowseRoot` (default `ObjectsFolder` i=85), bounded by `MaxDiscoveredNodes` / `MaxBrowseDepth` |
|
|
| `IReadable` | `ReadAsync` → `Session.ReadAsync` | Upstream `StatusCode`s pass through verbatim (cascading-quality rule) |
|
|
| `IWritable` | `WriteAsync` → `Session.WriteAsync` | Passthrough write |
|
|
| `ISubscribable` | native OPC UA subscriptions / monitored items | The remote server pushes data changes |
|
|
| `IHostConnectivityProbe` | session keep-alive | Host key is the endpoint URL actually connected to after the failover sweep |
|
|
| `IAlarmSource` | `SubscribeAlarmsAsync` (EventFilter) + `AcknowledgeAsync` | Subscribes to upstream alarm/condition events and forwards acks |
|
|
| `IHistoryProvider` | `ReadRawAsync` / `ReadProcessedAsync` / `ReadAtTimeAsync` → `Session.HistoryReadAsync` | **Unique to this driver** — passthrough history read against the upstream server |
|
|
|
|
> **Native alarms (#619).** An alarm raw tag is `TagConfig` `{ "nodeId": "<upstream SourceNode>", "alarm": {...} }`.
|
|
> The host subscribes with RawPaths and routes on (driver, RawPath), so the driver matches each
|
|
> event's `ConditionId` (then its `SourceNode`) against the tag's authored `nodeId` and reports the **RawPath** as
|
|
> `ConditionId`. Author `nodeId` as the upstream **condition** node for a 1:1 mapping (required when one source carries
|
|
> several conditions, e.g. Hi + HiHi); authoring the **source** node folds every condition of that source into one
|
|
> tag. `Acknowledge` is called on the condition node of the last event seen for the RawPath **with that event's
|
|
> EventId** (Part 9 §5.7.3). The event's `ActiveState/Id` + `AckedState/Id` are selected and turned into the
|
|
> `Raise`/`Acknowledge`/`Clear`/`Retrigger` kinds the host projector consumes (without a kind no upstream alarm could ever
|
|
> show active); the kinds are emitted from the state **last told to the host** per RawPath, so an identical re-delivery
|
|
> emits nothing (no re-raise, which would un-ack). Condition **branch** events (non-null `BranchId`) are ignored.
|
|
> **`ConditionRefresh`** is called after the event item is created, after every in-place reconnect, and on a
|
|
> `RefreshRequired` event, so a condition already active upstream is reported at subscribe; `RefreshStart`/`RefreshEnd`
|
|
> markers are dropped. A server without it (`BadNotSupported`/`BadMethodInvalid`/…) is logged once and tolerated.
|
|
> Last-told state survives a re-initialise (the host re-subscribes the same set over nodes it did not rebuild) and is
|
|
> forgotten when the subscribed set changes (the host rebuilt, recreating the nodes inactive). Index keys are server-stable (`nsu=`), so a namespace reorder across a reconnect keeps
|
|
> matching. docker-dev seeds an opc-plc driver (`MAIN-opcua`); the alarm tag is
|
|
> created only when `@OpcPlcAlarmSourceNodeId` is set in `docker-dev/seed/seed-clusters.sql`.
|
|
|
|
> This driver does **not** implement `IRediscoverable` — there is no
|
|
> push-driven rediscovery signal from a remote OPC UA server in this driver.
|
|
> `IHistoryProvider` is implemented by no other driver; history reads for every
|
|
> other source route server-side through `IHistoryRouter`.
|
|
|
|
### History passthrough
|
|
|
|
`IHistoryProvider` forwards `HistoryRead` to the upstream server's own historian.
|
|
Raw, processed (the full `HistoryAggregateType` set — Average / Minimum / Maximum / Total / Count plus
|
|
Interpolative, TimeAverage, Start, End, Delta, Range, Min/Max ActualTime, Start/EndBound, DeltaBounds,
|
|
DurationGood/Bad, PercentGood/Bad, WorstQuality, NumberOfTransitions, AnnotationCount and the
|
|
population StandardDeviation/Variance — each mapped to its OPC UA Part 13 standard aggregate NodeId; #285),
|
|
and at-time reads are supported; each
|
|
returned `DataValue` keeps its upstream `StatusCode` and timestamps verbatim.
|
|
Event-history (`ReadEventsAsync`) is left at the interface default — the
|
|
interface doesn't yet carry the EventFilter surface needed to forward it.
|
|
|
|
### Certificate trust
|
|
|
|
`AutoAcceptCertificates` accepts any self-signed / untrusted server certificate.
|
|
It is **dev-only** — leave it `false` in production so a MITM against the
|
|
opc.tcp channel fails closed. The SDK rejects a **revoked** certificate
|
|
(`BadCertificateRevoked` / `BadCertificateIssuerRevoked`) before the auto-accept handler runs, and the handler
|
|
also refuses them explicitly — defence in depth (#277), not a behaviour change.
|
|
|
|
`CertificateValidation` (defaults change nothing):
|
|
|
|
| Key | Default | Meaning |
|
|
|---|---|---|
|
|
| `rejectUnknownRevocationStatus` | `false` | Reject a server certificate whose revocation status cannot be determined (no CRL for its issuer, or a stale one). Leave `false` for brownfield sites without CRL infrastructure. **Only effective with `autoAcceptCertificates` off** — the auto-accept handler accepts every suppressible error, including revocation-unknown. |
|
|
| `issuerStorePath` | `null` (= `%LocalAppData%/OtOpcUa/pki/issuers`) | Directory used as the trusted-issuer store. The SDK reads issuer CRLs (`*.crl`) from its `crl/` sub-folder, so this is how an operator points the driver at a managed CRL set. |
|
|
|
|
### Subscription tuning (#273)
|
|
|
|
The per-subscription parameters that used to be hardcoded are driver options; the defaults are the old values.
|
|
|
|
| Key | Default | Notes |
|
|
|---|---|---|
|
|
| `subscriptionPublishingInterval` | `null` | A .NET `TimeSpan` string (`"00:00:02"`), not a number. `null` = the interval the runtime requests per subscribe (floored at 50 ms). When set it overrides that value (floor still applies); monitored-item sampling follows it. |
|
|
| `subscriptionKeepAliveCount` | `10` | `>= 1`. |
|
|
| `subscriptionLifetimeCount` | `1000` | Must be `>= 3 x` keep-alive count (Part 4 §5.13.2). |
|
|
| `subscriptionMaxNotificationsPerPublish` | `0` | `0` = server decides. |
|
|
| `subscriptionPriority` | `0` | `0`-`255`. |
|
|
|
|
Out-of-range values (and a non-absolute `discoveryUrl`) are rejected when the options are loaded — driver creation / `InitializeAsync` fails once with a clear message rather than the driver faulting and retrying forever. The alarm subscription uses the same counts.
|
|
*Per-tag* tuning (deadband / sampling interval / queue size, #274) is not implemented — it needs an
|
|
`ISubscribable` signature change on Core.
|
|
|
|
### Server OperationLimits (#275)
|
|
|
|
Nothing driver-side: the SDK session already honours the remote server's
|
|
`ServerCapabilities/OperationLimits`. `Opc.Ua.Client.Session` derives from `Opc.Ua.SessionClientBatched`,
|
|
fetches the limits on open (`FetchOperationLimitsAsync`) and splits Read / Write / CreateMonitoredItems / Browse /
|
|
HistoryRead requests that exceed them (a limit of `0` = unlimited). The driver issues one logical call per
|
|
operation and a unit test pins the `Session : SessionClientBatched` relationship so an SDK change that dropped
|
|
it is caught. (A driver-side splitter was tried and removed: it duplicated the SDK and, on a stalled link, held
|
|
the driver gate for chunks x timeout.)
|
|
|
|
### Discovery URL (#278)
|
|
|
|
`discoveryUrl` (default `null`, e.g. `opc.tcp://lds:4840`): at `InitializeAsync` the driver runs `FindServers` on it
|
|
and `GetEndpoints` on every returned server, keeping the endpoints matching `securityPolicy` + `securityMode`.
|
|
Discovered URLs are tried **after** `endpointUrls`/`endpointUrl` (case-insensitive de-dup) — discovery can add
|
|
fallbacks but never outranks or replaces the configured server. Because an LDS commonly registers several servers
|
|
(identical line PLCs, a gateway plus a historian) and the first to accept a connection would be bound silently:
|
|
|
|
- `discoveryServerUri` set: only endpoints of the server with that ApplicationUri are used.
|
|
- unset and exactly one distinct server discovered: that server is used.
|
|
- unset and more than one: the connect attempt **fails** with an error naming the discovered ApplicationUris and
|
|
telling the operator to set `discoveryServerUri`.
|
|
|
|
A discovery *network* failure (LDS down) is logged and non-fatal — the static list is used (note it is retried on
|
|
every `InitializeAsync`, including comms-loss reconnects). The discovery channel itself is always unsecured (spec).
|
|
|
|
### Diagnostics counters (#276)
|
|
|
|
Session/publish events are published on the shared OTel meter as the counter
|
|
`otopcua.driver.opcuaclient.events`, tagged `driver_instance` (the driver instance id) and `event` =
|
|
`publish_response`, `notification` (items), `data_change`, `bad_status_value`, `publish_error`,
|
|
`keepalive_miss`, `reconnect_attempt`, `reconnect_success`, `reconnect_exhausted`. A climbing `keepalive_miss` /
|
|
`reconnect_attempt` rate is the signature of a flapping upstream. They are not part of `DriverHealth` or the
|
|
`/hosts` panel.
|
|
|
|
## Testing
|
|
|
|
- **Unit tests** — `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/`
|
|
cover the session lifecycle, namespace remapping, alarm/history passthrough,
|
|
and config binding against a faked SDK session.
|
|
- **Integration fixture** — exercises the driver against a reference OPC UA
|
|
server (opc-plc) on the shared docker host; see
|
|
[OpcUaClient-Test-Fixture.md](OpcUaClient-Test-Fixture.md) for the coverage map.
|
|
|
|
## Further reading
|
|
|
|
- [`docs/v2/driver-specs.md §8`](../v2/driver-specs.md) — full per-field spec,
|
|
namespace-assignment rules, and cascading-quality detail
|
|
- [OpcUaClient-Test-Fixture.md](OpcUaClient-Test-Fixture.md) — test-harness map
|
|
- [Client.CLI.md](../Client.CLI.md) — general-purpose OPC UA client CLI for
|
|
ad-hoc browsing of any endpoint
|