adce4e7727
Per-CLI runbooks (Driver.{Modbus,AbCip,AbLegacy,S7,TwinCAT}.Cli.md) shipped
with #249-#251 but docs/README.md's Client tooling table never grew entries
for them and there was no parent doc pulling the suite together.
Adds:
- docs/DriverClis.md — short parent. Index table, shared-commands callout
(probe / read / write / subscribe), Driver.Cli.Common infrastructure
note (what's shared, marginal cost of adding a sixth CLI), typical
cross-CLI workflows (commissioning, bug reproduction, recipe-write
validation, byte-order debugging), known gaps that cross-ref the
per-CLI docs (AB Legacy ab_server upstream gap, S7 PUT/GET enable,
TwinCAT AMS router, UDT-write refusal), tracking pointer to #249-251.
- docs/README.md — Client tooling table grows 6 rows (DriverClis parent
+ 5 per-CLI). Also corrects the Client.CLI.md row: it's otopcua-cli,
not lmxopcua-cli (renamed in #208).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
90 lines
6.2 KiB
Markdown
90 lines
6.2 KiB
Markdown
# OtOpcUa documentation
|
|
|
|
Two tiers of documentation live here:
|
|
|
|
- **Current reference** at the top level (`docs/*.md`) — describes what's shipped today. Start here for operator + integrator reference.
|
|
- **Implementation history + design notes** at `docs/v2/*.md` — the authoritative plan + decision log the current reference is built from. Start here when you need the *why* behind an architectural choice, or when a top-level doc says "see plan.md § X".
|
|
|
|
The project was originally called **LmxOpcUa** (a single-driver Galaxy/MXAccess OPC UA server) and has since become **OtOpcUa**, a multi-driver OPC UA server platform. Any lingering `LmxOpcUa`-string in a path you see in docs is a deliberate residual (executable name `lmxopcua-cli`, client PKI folder `{LocalAppData}/LmxOpcUaClient/`) — fixing those requires migration shims + is tracked as follow-ups.
|
|
|
|
## Platform overview
|
|
|
|
- **Core** owns the OPC UA stack, address space, session/security/subscription machinery.
|
|
- **Drivers** plug in via capability interfaces in `ZB.MOM.WW.OtOpcUa.Core.Abstractions`: `IDriver`, `IReadable`, `IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`, `IAlarmSource`, `IHistoryProvider`, `IPerCallHostResolver`. Each driver opts into whichever it supports.
|
|
- **Server** is the OPC UA endpoint process (net10, x64). Hosts every driver except Galaxy in-process; talks to Galaxy via a named pipe because MXAccess COM is 32-bit-only.
|
|
- **Admin** is the Blazor Server operator UI (net10, x64). Owns the Config DB draft/publish flow, ACL + role-grant authoring, fleet status + `/metrics` scrape endpoint.
|
|
- **Galaxy.Host** is a .NET Framework 4.8 x86 Windows service that wraps MXAccess COM on an STA thread for the Galaxy driver.
|
|
|
|
## Where to find what
|
|
|
|
### Architecture + data-path reference
|
|
|
|
| Doc | Covers |
|
|
|-----|--------|
|
|
| [OpcUaServer.md](OpcUaServer.md) | Top-level server architecture — Core, driver dispatch, Config DB, generations |
|
|
| [AddressSpace.md](AddressSpace.md) | `GenericDriverNodeManager` + `ITagDiscovery` + `IAddressSpaceBuilder` |
|
|
| [ReadWriteOperations.md](ReadWriteOperations.md) | OPC UA Read/Write → `CapabilityInvoker` → `IReadable`/`IWritable` |
|
|
| [Subscriptions.md](Subscriptions.md) | Monitored items → `ISubscribable` + per-driver subscription refcount |
|
|
| [AlarmTracking.md](AlarmTracking.md) | `IAlarmSource` + `AlarmSurfaceInvoker` + OPC UA alarm conditions |
|
|
| [DataTypeMapping.md](DataTypeMapping.md) | Per-driver `DriverAttributeInfo` → OPC UA variable types |
|
|
| [IncrementalSync.md](IncrementalSync.md) | Address-space rebuild on redeploy + `sp_ComputeGenerationDiff` |
|
|
| [HistoricalDataAccess.md](HistoricalDataAccess.md) | `IHistoryProvider` as a per-driver optional capability |
|
|
|
|
### Drivers
|
|
|
|
| Doc | Covers |
|
|
|-----|--------|
|
|
| [drivers/README.md](drivers/README.md) | Index of the seven shipped drivers + capability matrix |
|
|
| [drivers/Galaxy.md](drivers/Galaxy.md) | Galaxy driver — MXAccess bridge, Host/Proxy split, named-pipe IPC |
|
|
| [drivers/Galaxy-Repository.md](drivers/Galaxy-Repository.md) | Galaxy-specific discovery via the ZB SQL database |
|
|
|
|
For Modbus / S7 / AB CIP / AB Legacy / TwinCAT / FOCAS / OPC UA Client specifics, see [v2/driver-specs.md](v2/driver-specs.md).
|
|
|
|
### Operational
|
|
|
|
| Doc | Covers |
|
|
|-----|--------|
|
|
| [Configuration.md](Configuration.md) | appsettings bootstrap + Config DB + Admin UI draft/publish |
|
|
| [security.md](security.md) | Transport security profiles, LDAP auth, ACL trie, role grants, OTOPCUA0001 analyzer |
|
|
| [Redundancy.md](Redundancy.md) | `RedundancyCoordinator`, `ServiceLevelCalculator`, apply-lease, Prometheus metrics |
|
|
| [ServiceHosting.md](ServiceHosting.md) | Three-process deploy (Server + Admin + Galaxy.Host) install/uninstall |
|
|
| [StatusDashboard.md](StatusDashboard.md) | Pointer — superseded by [v2/admin-ui.md](v2/admin-ui.md) |
|
|
|
|
### Client tooling
|
|
|
|
| Doc | Covers |
|
|
|-----|--------|
|
|
| [Client.CLI.md](Client.CLI.md) | `otopcua-cli` — OPC UA command-line client |
|
|
| [Client.UI.md](Client.UI.md) | Avalonia desktop client |
|
|
| [DriverClis.md](DriverClis.md) | Driver test-client CLIs — index + shared commands |
|
|
| [Driver.Modbus.Cli.md](Driver.Modbus.Cli.md) | `otopcua-modbus-cli` — Modbus-TCP |
|
|
| [Driver.AbCip.Cli.md](Driver.AbCip.Cli.md) | `otopcua-abcip-cli` — ControlLogix / CompactLogix / Micro800 / GuardLogix |
|
|
| [Driver.AbLegacy.Cli.md](Driver.AbLegacy.Cli.md) | `otopcua-ablegacy-cli` — SLC / MicroLogix / PLC-5 (PCCC) |
|
|
| [Driver.S7.Cli.md](Driver.S7.Cli.md) | `otopcua-s7-cli` — Siemens S7-300 / S7-400 / S7-1200 / S7-1500 |
|
|
| [Driver.TwinCAT.Cli.md](Driver.TwinCAT.Cli.md) | `otopcua-twincat-cli` — Beckhoff TwinCAT 2/3 ADS |
|
|
|
|
### Requirements
|
|
|
|
| Doc | Covers |
|
|
|-----|--------|
|
|
| [reqs/HighLevelReqs.md](reqs/HighLevelReqs.md) | HLRs — numbered system-level requirements |
|
|
| [reqs/OpcUaServerReqs.md](reqs/OpcUaServerReqs.md) | OPC UA server-layer reqs |
|
|
| [reqs/ServiceHostReqs.md](reqs/ServiceHostReqs.md) | Per-process hosting reqs |
|
|
| [reqs/ClientRequirements.md](reqs/ClientRequirements.md) | Client CLI + UI reqs |
|
|
| [reqs/GalaxyRepositoryReqs.md](reqs/GalaxyRepositoryReqs.md) | Galaxy-scoped repository reqs |
|
|
| [reqs/MxAccessClientReqs.md](reqs/MxAccessClientReqs.md) | Galaxy-scoped MXAccess reqs |
|
|
| [reqs/StatusDashboardReqs.md](reqs/StatusDashboardReqs.md) | Pointer — superseded by Admin UI |
|
|
|
|
## Implementation history (`docs/v2/`)
|
|
|
|
Design decisions + phase plans + execution notes. Load-bearing cross-references from the top-level docs:
|
|
|
|
- [v2/plan.md](v2/plan.md) — authoritative v2 vision doc + numbered decision log (referenced as "decision #N" elsewhere)
|
|
- [v2/admin-ui.md](v2/admin-ui.md) — Admin UI spec
|
|
- [v2/acl-design.md](v2/acl-design.md) — data-plane ACL + permission-trie design (Phase 6.2)
|
|
- [v2/config-db-schema.md](v2/config-db-schema.md) — Config DB schema reference
|
|
- [v2/driver-specs.md](v2/driver-specs.md) — per-driver addressing + quirks for every shipped protocol
|
|
- [v2/dev-environment.md](v2/dev-environment.md) — dev-box bootstrap
|
|
- [v2/test-data-sources.md](v2/test-data-sources.md) — integration-test simulator matrix (includes the pinned libplctag `ab_server` version for AB CIP tests)
|
|
- [v2/implementation/phase-*-*.md](v2/implementation/) — per-phase execution plans with exit-gate evidence
|