dohertj2/lmxopcua
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add component-level documentation for all 14 server subsystems

Browse Source 
Provides technical documentation covering OPC UA server, address space,
Galaxy repository, MXAccess bridge, data types, read/write, subscriptions,
alarms, historian, incremental sync, configuration, dashboard, service
hosting, and CLI tool. Updates README with component documentation table.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-03-26 15:47:59 -04:00
parent ce0b291664
commit 965e430f48
16 changed files with 1840 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
README.md
View File

@@ -12,19 +12,21 @@ OPC UA server on .NET Framework 4.8 (x86) that exposes AVEVA System Platform (Wo
| Galaxy Repo DB |---->| OPC UA Server |<--->| MXAccess Client |
| (SQL Server) | | (address space) | | (STA + COM) |
+-----------------+ +------------------+ +-----------------+
|
+-------+--------+
| Status Dashboard|
| (HTTP/JSON) |
+----------------+
| |
+-------+--------+ +---------+---------+
| Status Dashboard| | Historian Runtime |
| (HTTP/JSON) | | (SQL Server) |
+----------------+ +-------------------+
```
**Galaxy Repository** queries the ZB database for the deployed object hierarchy and attribute definitions, building the OPC UA address space at startup and rebuilding on deploy changes.
**Galaxy Repository** queries the ZB database for the deployed object hierarchy and attribute definitions, building the OPC UA address space at startup and incrementally syncing on deploy changes.
**MXAccess Client** connects to the Galaxy runtime via COM interop on a dedicated STA thread with a Win32 message pump. Handles subscriptions, read/write, reconnection, and probe-based health monitoring.
**OPC UA Server** exposes the hierarchy as browse nodes (folders for areas, objects for containers) with variable nodes for each attribute. Clients browse using contained names but reads/writes translate to `tag_name.AttributeName` for MXAccess.
**Historian Runtime** provides historical data access via SQL queries against the Wonderware Historian `Runtime` database, serving OPC UA `HistoryRead` requests for raw and aggregate data.
## Contained Name vs Tag Name
| Browse Path (contained names) | Runtime Reference (tag name) |
@@ -40,8 +42,9 @@ OPC UA server on .NET Framework 4.8 (x86) that exposes AVEVA System Platform (Wo
- AVEVA System Platform with ArchestrA Framework installed
- Galaxy repository database (SQL Server, Windows Auth)
- MXAccess COM registered (`LMXProxy.LMXProxyServer`)
- Wonderware Historian (optional, for historical data access)
### Build & Run
### Build and run
```bash
dotnet restore ZB.MOM.WW.LmxOpcUa.slnx
@@ -51,7 +54,7 @@ dotnet run --project src/ZB.MOM.WW.LmxOpcUa.Host
The server starts on `opc.tcp://localhost:4840/LmxOpcUa` with SecurityPolicy None.
### Install as Windows Service
### Install as Windows service
```bash
cd src/ZB.MOM.WW.LmxOpcUa.Host/bin/Debug/net48
@@ -59,7 +62,7 @@ ZB.MOM.WW.LmxOpcUa.Host.exe install
ZB.MOM.WW.LmxOpcUa.Host.exe start
```
### Test with CLI Tool
### Test with CLI tool
```bash
# Connect
@@ -76,60 +79,78 @@ dotnet run --project tools/opcuacli-dotnet -- write -u opc.tcp://localhost:4840/
# Subscribe to changes
dotnet run --project tools/opcuacli-dotnet -- subscribe -u opc.tcp://localhost:4840/LmxOpcUa -n "ns=1;s=TestChildObject.TestInt" -i 500
# Read historical data
dotnet run --project tools/opcuacli-dotnet -- historyread -u opc.tcp://localhost:4840/LmxOpcUa -n "ns=1;s=TestMachine_001.TestHistoryValue" --start "2026-03-25" --end "2026-03-30"
# Subscribe to alarm events
dotnet run --project tools/opcuacli-dotnet -- alarms -u opc.tcp://localhost:4840/LmxOpcUa -n "ns=1;s=TestMachine_001" --refresh
```
### Run Tests
### Run tests
```bash
dotnet test ZB.MOM.WW.LmxOpcUa.slnx
```
## Security Classification
Galaxy attributes carry a `security_classification` that controls OPC UA write access. The server maps these to `AccessLevel` on each variable node:
| Classification | Galaxy Level | OPC UA Access |
|---|---|---|
| 0 | FreeAccess | ReadWrite |
| 1 | Operate | ReadWrite |
| 2 | SecuredWrite | ReadOnly |
| 3 | VerifiedWrite | ReadOnly |
| 4 | Tune | ReadWrite |
| 5 | Configure | ReadWrite |
| 6 | ViewOnly | ReadOnly |
See `gr/data_type_mapping.md` for the full mapping table.
## Alarm Tracking
When `AlarmTrackingEnabled` is true, the server creates `AlarmConditionState` nodes for Galaxy attributes with `AlarmExtension` primitives. It auto-subscribes to each alarm's `InAlarm` tag and reports OPC UA alarm events on state transitions:
- `InAlarm` TRUE → alarm active event (severity from `Priority`, message from `DescAttrName`)
- `InAlarm` FALSE → alarm cleared event
- Condition refresh reports all currently retained alarms to newly subscribing clients
## Historical Data Access
When `Historian.Enabled` is true, the server handles OPC UA `HistoryRead` requests by querying the Wonderware Historian `Runtime` database:
- **Raw reads** query `Runtime.dbo.History` with time range and max values
- **Processed reads** query `Runtime.dbo.AnalogSummaryHistory` with aggregates (Average, Minimum, Maximum, Count)
- Historized variables advertise `Historizing=true` and `AccessLevel` includes `HistoryRead`
## Incremental Address Space Sync
When the Galaxy detects a new deployment, the server compares the previous hierarchy and attributes against the new snapshot. Only changed gobject subtrees are torn down and rebuilt — unchanged nodes, subscriptions, and alarm tracking remain intact. See `partial_update.md` for details.
## Configuration
All settings in `appsettings.json`, overridable via environment variables:
| Section | Key | Default | Description |
|---------|-----|---------|-------------|
| OpcUa | Port | 4840 | OPC UA server port |
| OpcUa | EndpointPath | /LmxOpcUa | Endpoint path |
| OpcUa | GalaxyName | ZB | Galaxy name (used in namespace URI) |
| OpcUa | MaxSessions | 100 | Maximum concurrent sessions |
| MxAccess | ClientName | LmxOpcUa | MXAccess registration name |
| MxAccess | AutoReconnect | true | Auto-reconnect on disconnect |
| MxAccess | ProbeTag | null | Tag for connection health probing |
| GalaxyRepository | ConnectionString | Server=localhost;Database=ZB;... | ZB database connection |
| GalaxyRepository | ChangeDetectionIntervalSeconds | 30 | Deploy change polling interval |
| Dashboard | Enabled | true | Enable HTTP status dashboard |
| Dashboard | Port | 8081 | Dashboard port |
## Project Structure
```
src/ZB.MOM.WW.LmxOpcUa.Host/
Configuration/ Config binding and validation
Domain/ Interfaces, DTOs, enums, mappers
Metrics/ Performance tracking (rolling P95)
MxAccess/ STA thread, COM interop, subscriptions
GalaxyRepository/ SQL queries, change detection
OpcUa/ Server, node manager, address space
Status/ HTTP dashboard, health checks
OpcUaService.cs Service wiring (startup/shutdown)
Program.cs TopShelf entry point
tests/ZB.MOM.WW.LmxOpcUa.Tests/
Configuration/ Config binding tests
Domain/ Type mapping, quality, error code tests
Metrics/ Performance metrics tests
MxAccess/ STA thread, connection, subscription, R/W tests
GalaxyRepository/ Change detection tests
OpcUa/ Address space build/rebuild, data conversion tests
Status/ Health check, dashboard, web server tests
Wiring/ Component integration tests
EndToEnd/ Full data flow smoke test
tools/opcuacli-dotnet/ OPC UA CLI test tool
gr/ Galaxy repository docs, SQL queries, schema
```
| `OpcUa` | `Port` | `4840` | OPC UA server port |
| `OpcUa` | `EndpointPath` | `/LmxOpcUa` | Endpoint path |
| `OpcUa` | `GalaxyName` | `ZB` | Galaxy name (namespace URI) |
| `OpcUa` | `MaxSessions` | `100` | Maximum concurrent sessions |
| `OpcUa` | `AlarmTrackingEnabled` | `false` | Enable alarm condition tracking |
| `MxAccess` | `ClientName` | `LmxOpcUa` | MXAccess registration name |
| `MxAccess` | `AutoReconnect` | `true` | Auto-reconnect on disconnect |
| `MxAccess` | `ProbeTag` | `null` | Tag for connection health probing |
| `GalaxyRepository` | `ConnectionString` | `Server=localhost;Database=ZB;...` | ZB database connection |
| `GalaxyRepository` | `ChangeDetectionIntervalSeconds` | `30` | Deploy change polling interval |
| `GalaxyRepository` | `ExtendedAttributes` | `false` | Include primitive/system attributes |
| `Historian` | `Enabled` | `false` | Enable OPC UA historical data access |
| `Historian` | `ConnectionString` | `Server=localhost;Database=Runtime;...` | Historian Runtime database connection |
| `Historian` | `MaxValuesPerRead` | `10000` | Maximum values per HistoryRead request |
| `Dashboard` | `Enabled` | `true` | Enable HTTP status dashboard |
| `Dashboard` | `Port` | `8081` | Dashboard port |
## Data Type Mapping
@@ -148,6 +169,35 @@ gr/ Galaxy repository docs, SQL queries, schema
Array attributes use `ValueRank=1` with `ArrayDimensions` from the Galaxy attribute definition.
## Project Structure
```
src/ZB.MOM.WW.LmxOpcUa.Host/
Configuration/ Config binding and validation
Domain/ Interfaces, DTOs, enums, mappers
Historian/ Wonderware Historian data source
Metrics/ Performance tracking (rolling P95)
MxAccess/ STA thread, COM interop, subscriptions
GalaxyRepository/ SQL queries, change detection
OpcUa/ Server, node manager, address space, alarm conditions, diff
Status/ HTTP dashboard, health checks
OpcUaService.cs Service wiring (startup/shutdown)
Program.cs TopShelf entry point
tests/ZB.MOM.WW.LmxOpcUa.Tests/
Domain/ Type mapping, security classification, quality tests
Historian/ Historian quality mapping tests
Integration/ Access levels, historizing, alarm events, incremental sync
Metrics/ Performance metrics tests
MxAccess/ STA thread, connection, subscription, R/W tests
GalaxyRepository/ Change detection tests
OpcUa/ Address space build/rebuild, diff, data conversion tests
Wiring/ Component integration tests
tools/opcuacli-dotnet/ OPC UA CLI test tool (connect, browse, read, write, subscribe, historyread, alarms)
gr/ Galaxy repository docs, SQL queries, schema
```
## Startup Sequence
1. Load and validate configuration
@@ -158,8 +208,37 @@ Array attributes use `ValueRank=1` with `ArrayDimensions` from the Galaxy attrib
6. Test Galaxy database connection
7. Start OPC UA server with programmatic config
8. Query hierarchy + attributes, build address space
9. Start change detection polling (rebuilds on deploy)
10. Start status dashboard (HTML + JSON + health endpoint)
9. Create alarm condition nodes and auto-subscribe to InAlarm tags (if enabled)
10. Start change detection polling (incremental sync on deploy)
11. Start status dashboard (HTML + JSON + health endpoint)
## Component Documentation
| Component | Description |
|---|---|
| [OPC UA Server](docs/OpcUaServer.md) | Endpoint, sessions, security policy, server lifecycle |
| [Address Space](docs/AddressSpace.md) | Hierarchy nodes, variable nodes, primitive grouping, NodeId scheme |
| [Galaxy Repository](docs/GalaxyRepository.md) | SQL queries, deployed package chain, change detection |
| [MXAccess Bridge](docs/MxAccessBridge.md) | STA thread, COM interop, subscriptions, reconnection |
| [Data Type Mapping](docs/DataTypeMapping.md) | Galaxy → OPC UA types, arrays, security classification |
| [Read/Write Operations](docs/ReadWriteOperations.md) | Value reads, writes, access level enforcement, array element writes |
| [Subscriptions](docs/Subscriptions.md) | Ref-counted MXAccess subscriptions, data change dispatch |
| [Alarm Tracking](docs/AlarmTracking.md) | AlarmConditionState nodes, InAlarm monitoring, event reporting |
| [Historical Data Access](docs/HistoricalDataAccess.md) | Historian data source, HistoryReadRaw, HistoryReadProcessed |
| [Incremental Sync](docs/IncrementalSync.md) | Diff computation, subtree teardown/rebuild, subscription preservation |
| [Configuration](docs/Configuration.md) | appsettings.json binding, feature flags, validation |
| [Status Dashboard](docs/StatusDashboard.md) | HTTP server, health checks, metrics reporting |
| [Service Hosting](docs/ServiceHosting.md) | TopShelf, startup/shutdown sequence, error handling |
| [CLI Tool](docs/CliTool.md) | Connect, browse, read, write, subscribe, historyread, alarms commands |
## Related Documentation
- [Galaxy Repository Queries](gr/CLAUDE.md) — SQL queries for hierarchy, attributes, and change detection
- [Data Type Mapping](gr/data_type_mapping.md) — Galaxy to OPC UA type mapping with security classification
- [Alarm Plan](hda_plan.md) — Alarm detection and OPC UA alarm condition design
- [Historian Plan](historian_plan.md) — Historical data access via Wonderware Historian
- [Incremental Sync Plan](partial_update.md) — Subtree-level address space sync design
- [Galaxy Security](gr_security.md) — Users, roles, and permissions in the Galaxy repository
## License