mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-26 04:19:53 +08:00
Marc SchierandCopilot
ca89ac85a7
# Description Adds a **Generators companion-specification sample** alongside the existing pump sample, and a **`SiteCompositionServer`** that composes several device servers into one OpenUSD scene at a supervisory level — demonstrating that servers can be aggregated without mirroring their address spaces. Three things, in dependency order: ### 1. `GeneratorServer` A self-contained server realising the draft Generators spec (`http://opcfoundation.org/UA/Generators/`) end to end: N simulated generating sets, DI + Machinery integration, a twelve-state operating state machine, four protection alarms per set, six control methods, and a per-set OpenUSD twin. The organising idea is that **load fraction is the only independent variable**. Everything else is a function of it: ``` V̇_f(x) = 3.67 + 100·x fuel rate [L/h] η(x) = P(x) / (V̇_f(x) · ρ · LHV) efficiency S = P / PF I = S / (√3·V_LL) f = N·p / 120 ``` This is not stylistic. When each measurement is an independent oscillator — as the pump sample's simulation once was — a server happily publishes a duty point no real machine could occupy, and no test can catch it because there is nothing for the values to be inconsistent *with*. Deriving them from one variable means `P = √3·V·I·PF` and `η = P/(V̇·ρ·LHV)` hold at every tick by construction. The published `DATASHEET.md`, the engineering ranges, the trip points and the simulation all read the same constants in `GeneratorDatasheet.cs`, so the document and the server cannot describe different machines. The machine is a fictitious **SimGen Systems GenX-500** (400 kW prime / 440 kW standby, 400/230 V, 50 Hz, four-pole). Figures are representative of a real industrial genset class; no vendor is named anywhere in the code or docs. ### 2. Cross-server composition in the connector `RemoteSessionFactory` already existed in the client library but the connector CLI never set it, so cross-server composition was unreachable. `--federate` wires it up: the connector opens a session to each server named by a component binding, discovers its representations and drives its bindings into the same stage. It is **opt-in** because the endpoint the connector dials comes from the server being rendered rather than from the operator, which makes honouring it a trust decision. Federation is best-effort per component — a subordinate that is down is logged and skipped, and the rest of the scene still renders — which is the only `src/` change in this PR. ### 3. `SiteCompositionServer` Owns no devices. It publishes a site stage plus one cross-server component binding per subordinate, carrying that server's `ComponentServerUri` and `ComponentEndpointUrl`. Nothing is mirrored, so there is no cache to invalidate and no second copy of the truth. ## Notes for reviewers **Everything interesting in this PR was found by running the servers, not by reading the code.** Six defects, none of which looked wrong in review: - `IsShutdown` and `SubsystemName` are *optional* on `GeneratorProtectionAlarmType`, so the generated factory does not materialise them. `CreateOrReplace` alone produces a child that exists, appears in `GetChildren` and holds the right value — but carries **no `ReferenceTypeId`**, so no browse can reach it. Every alarm was publishing its trip without saying whether the trip stops the machine or which subsystem to go to. `AddXxx(context)` first is what gives the child its `HasProperty` reference. - **The protections could never fire.** Every trip point sits outside the band the datasheet curves produce — that is what a datasheet *means* — so all four alarms, the shutdown class, `ResetFaults` and the whole `Fault` branch of the state machine were unreachable while the README documented them as observable. Overload was worse: the load clamp ceiling was set to exactly the trip point, making a strictly-greater-than comparison unsatisfiable. Faults are now injectable, and the first set — the one the hero camera frames — develops one on a slow rotation. - **A shutdown trip removes the condition that caused it**, because oil pressure and coolant temperature are only supervised while the engine turns. Each alarm went active for one tick and cleared, leaving an operator with a stopped machine and no indication of why. Shutdown-class alarms now latch until the set leaves the shutdown state. Every unit test that checked the *condition* passed throughout — the defect only appears when the trip and the supervision interact over time. - **`Synchronizing` and `Paralleled` were declared, drawn in the README and never entered.** The first set now energises a dead bus and closes onto it while every other set synchronises to a live one — both how a real plant parallels, and what makes the two states observable. - **The tick raced client method calls.** The simulation tick runs on a thread-pool thread while method calls arrive on request threads, and both transition sets and write the same nodes. A tick moving a set to `Cooldown` and a concurrent `EmergencyStop` could interleave the paired `CurrentState` / `CurrentState.Id` writes and leave a client with a state *name* from one transition and a state *node* from the other — the exact failure the paired write exists to prevent, reintroduced by the threading model. Both paths now take one gate. - Low oil pressure supervised from raw speed **tripped every set during cranking**, because pressure has not built yet. Now gated on `IsSpinning`, which is what a real start-up bypass does. Smaller fixes: shutdown trips are applied after the whole evaluation pass (stopping mid-loop made the remaining conditions read healthy, collapsing simultaneous trips to whichever came first in the table); `ResetFaults` reports its clears as events (a client learns of condition state changes only through events, so a silent clear leaves an alarm-list client showing it forever); the start counter moved into the transition so commanded starts are counted; the federated connector closes the remote session if the connector constructor throws between taking ownership and registering it; and `prepare_machinery_nodeset.py` now *asserts* the IA namespace is last before removing it rather than only claiming so in its docstring — removing any earlier entry would silently renumber every namespace after it and rebind their NodeIds. **A model limitation is left visible rather than papered over.** `GeneratorStateMachineType` declares an emergency stop only out of `Running`, `Loaded` and `Paralleled`, so the sample refuses `EmergencyStop` from `Starting` and `Warmup`. A real panel stops from anywhere. That is the specification's shape, not this sample's choice, so it is pinned by a test and named in the docs. **`Model/` vendors a reduced Machinery nodeset**, derived mechanically by whitelist. The full official nodeset does not survive the model source generator (`MODELGEN003`) and drags in IA through a single optional `Stacklight` member a generating set does not have. Deriving it by script keeps the provenance checkable; the whitelist is the only thing to edit when more types are needed. **Never hand-edit the generated output.** **The federated scene renders end to end.** Getting there surfaced three more defects, all of which produced a plausible-looking scene with nothing in it: the generator sample's plant aggregation was created under an already-registered `DeviceSet` and so was invisible to every client (it had *never* rendered geometry, standalone or federated); the connector's asset fetch ran on the primary session only, so composition referenced layers that were never downloaded; and both generator colour bindings wrote `primvars:displayColor` to prims that did not declare it, so the renderer rejected every update while the file still looked correct. Cross-server components compose under the subordinate's own root, so the site layer now *places* `/Plant` and `/Powerhouse` rather than leaving them stacked on the origin. **`OpenUsdRepresentation` is now mounted with `HasAddIn`, not `HasComponent`** (review feedback). The nodeset says so explicitly — *"Mounted with HasAddIn"* — but every server in the tree used plain `HasComponent`. It survived because `HasAddIn` is a *subtype* of `HasComponent`: the representation still browses, still aggregates and still drives a twin, so every functional test passed before the fix and after it, and only a conformance checker could tell. Seven mount sites corrected. `PumpDeviceIntegrationServer` and `MinimalRobotServer` had hand-rolled the mount instead of calling the shared `CreateRepresentation` helper, which is exactly how they drifted from it. Both sample E2E suites now assert the reference type across **every** discovered representation — a narrower check would have missed the plant-level representation that arrived later from master still carrying `HasComponent`. **Live colour is not achievable in the current OpenUSD viewer, and that is now documented rather than worked around.** Proven with a standalone probe: `primvars:displayColor` resolves as `color3f[]` from the `UsdGeomGprim` schema whatever the layer declares, and the `OpenUsd 0.4.0-alpha` managed API has no writer for that type. Bound `UsdPreviewSurface` materials are not shaded either, so geometry renders grey unless it also carries an explicit `displayColor` primvar. The **visibility** bindings carry no such caveat and are what the samples rely on to show state. Filed upstream as [openusd-dotnet#2](https://github.com/marcschier/openusd-dotnet/issues/2), [#3](https://github.com/marcschier/openusd-dotnet/issues/3) and [#4](https://github.com/marcschier/openusd-dotnet/issues/4), and linked from `docs/OpenUsd.md` so a reader can check whether they have since been fixed. ## Related Issues No tracking issue — this is additive sample and documentation work with a single small, self-contained change to `src/` (per-component error isolation and session-ownership hardening in `OpenUsdConnector.Composition.cs`). Happy to open one if maintainers would prefer it tracked. ## Checklist - [x] I have signed the [CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf) and read the [CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md) doc. - [x] I have added tests that prove my fix is effective or that my feature works and increased code coverage. - [x] I have added all necessary documentation. - [x] I have verified that my changes do not introduce (new) build or analyzer warnings. - [x] I ran **all** tests locally using the **UA.slnx** solution against at least .net **framework** and .net **10**, and all passed. - [ ] I fixed **all** failing and flaky tests in the CI pipelines and **all** CodeQL warnings. - [ ] I have addressed **all** PR feedback received. ### Testing The generator fixtures live in `tests/Opc.Ua.OpenUsd.Tests/Generator` — **82 tests**, no new project. `Opc.Ua.Di.Tests` would have been the natural home next to the pump fixtures, but both device samples source-generate their own reduced `Opc.Ua.Machinery` model and expose it via `InternalsVisibleTo`, so referencing both from one assembly makes every Machinery type ambiguous (CS0433); `Opc.Ua.OpenUsd.Tests` references no other sample and already hosts `RobotAssetContractTests`. The suite runs **870** on net10.0 and net48 (784 existing + 86) and **788** on net472, where the sample does not exist and only the framework-independent asset-contract tests run — forgetting exactly that exclusion broke CI on the sibling pump PR. The tests target the things in this sample that fail *quietly*: - **Datasheet conformance** holds the model to its own claim — rated speed is `120·f/p`, rated current follows from the rating, the fuel curve reproduces the published table, and `η = P/(V̇·ρ·LHV)` reconciles at every load. Efficiency is swept across the whole simulated range to show it stays inside (0,100) and rises monotonically; a fit that goes negative somewhere in its range is a coincidence that happens to look right at the duty point, not a model. A further test reads `DATASHEET.md` and checks the document quotes the figures the server actually serves. - **Drift between the two descriptions of the state machine** — the physics' `IsLegalTransition` and the model's `GeneratorStateMap` — is checked in *both* directions. A transition the physics permits but the map lacks moves a machine without telling a client; one the map holds but the physics refuses is dead weight that looks supported. - **Reachability at run time**, not just in the declared table — the test that catches states the model declares and nothing ever enters. - **That every protection can actually fire**, which is the half of the alarm contract that "a healthy set annunciates nothing" does not cover. A **hosted end-to-end fixture** connects a real client and asserts what the address space actually exposes — the aggregation at `/Powerhouse/Generators`, its component binding, and every per-set twin. That is the only kind of test that catches the registration defect above: the node object had the right browse name, binding and asset reference, so every test that inspected objects passed while no client could see it. **Every state-machine and protection fix was checked by mutation.** Restoring the clamp ceiling, the direct `Running → Loaded` path, the old start-counter placement, or removing the alarm opt-in each makes the corresponding test fail, naming the specific defect. A test that has never been seen to fail has not been shown to work. Verified against a running plant: `Synchronizing`, `Paralleled` and `Fault` all observed on a two-set server, with `HighCoolantTemperatureAlarm` seen active on the fault subject. Method behaviour verified separately — per-set distinct `CurrentState` nodes, `EmergencyStop` → `EmergencyStopped` with `Start` then refused as `BadInvalidState`, `ResetFaults` → `Off`, `SetOperatingMode(9999)` refused with the mode unchanged, and the other sets untouched throughout. Also verified as a three-server federated stage. 0 warnings on a clean Release rebuild of both samples, the client library, the connector and the tests, across every TFM. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: fe608993-f3c9-4779-a6b9-9a9eabfc24ba
OPC UA .NET Standard Stack
🆕 This is version 2.0 of the OPC UA .NET Standard Stack (current
master).Looking for the supported 1.x release? It lives on the
master378branch (last release:1.5.378). All new feature work happens here onmaster;master378continues to receive security and critical-bug fixes for the 1.x line.
The official OPC Foundation reference implementation of OPC UA for .NET — a certified, cross-platform stack with client, server, PubSub, GDS, complex types, and source-generated tooling. Used in production across industrial control, manufacturing, energy, and IoT systems.
📦 What it is
- A full-stack OPC UA implementation — Core / Client / Server / PubSub / GDS / LDS / Complex Types / Device Integration / Positioning libraries built on .NET, with UA-TCP and HTTPS transports.
- Cross-platform — runs on .NET 10, .NET 9, .NET 8 (LTS), .NET Framework 4.8, and .NET Standard 2.1; ships Native-AOT-friendly assemblies.
- Certified for compliance — the reference server has been certified through an OPC Foundation Certification Test Lab and is continuously verified against the latest Compliance Test Tool (CTT).
- Companion-spec coverage — Part 9 (Alarms & Conditions), Part 11 (Historical Access), Part 13 (Aggregates), Part 16 (State Machines), Part 17 (Alias Names), Part 18 (Role Management), Part 20 (File Transfer), Part 100 (Device Integration), Parts 210/211 (Relative Spatial Location and Global Positioning), OPC-10030 (ISA-95 Common Model) with OPC-10031-4 Job Control V1/V2, OPC 10100-1 (WoT Connectivity), OPC 40001-1 (Industrial Automation), OPC 40010-1 (Robotics).
- Modern developer surface — first-class
Microsoft.Extensions.DependencyInjectionhosting (services.AddOpcUa()), fluent server + client builders, source-generated NodeManagers and DataTypes, and an MCP server so LLMs / Copilot can drive an OPC UA client.
For the full feature breakdown see OPC UA Profiles and Facets and the What's New in 2.0 tour.
🚀 Getting started
You need the .NET 10 SDK to build the repo. From the repository root:
dotnet restore UA.slnx
dotnet build UA.slnx
For the supported target frameworks and platform notes see
the Developer Guide. The official NuGet packages
are published to nuget.org under the OPCFoundation.NetStandard
prefix — the meta package
OPCFoundation.NetStandard.Opc.Ua
pulls in everything, or pick the split
OPCFoundation.NetStandard.Opc.Ua.Core / .Client / .Server /
.Bindings.Https packages directly. Preview builds for every successful
master build are available in the
Azure DevOps opcua-preview feed.
Sample applications
Each sample has its own README.md with build and run instructions.
Reference applications
- Console Reference Server — the certified reference server (with Quickstarts, CTT, and Mono configs). Also ships as a Docker container.
- Console Reference Client — cross-platform reference client demonstrating sessions, subscriptions, browsing, and method calls.
- Console LDS Server — a standalone
Local Discovery Server built on
Opc.Ua.Lds.Server.
PubSub samples
- Console Reference PubSub Client —
one executable with
publisher,subscriber, andexternal(external-server adapter) modes across the supported transport profiles.
Minimal / Device-Integration samples
- Minimal Calc Server — minimal server built on the source-generated NodeManager pipeline (Calc model).
- Minimal Boiler Server — minimal Boiler-model server with the fluent state-machine builder; Native-AOT publishable.
- Pump Device Integration Server —
minimal Device Integration (Part 100) server using
Opc.Ua.Di.Server's fluent builder. - Minimal Robot Server — OPC 40010 Robotics with independently configurable RSL/GPOS motion and live OpenUSD transforms.
- Minimal ISA-95 Server — minimal server hosting the OPC-10030 ISA-95 Common Model together with OPC-10031-4 Job Control V1 and V2, using the typed common-model builder and the in-memory Job Control provider.
More sample projects are maintained in the companion OPC UA .NET Samples repository.
Developer tools
- OPC UA MCP Server — installable .NET tool and container that exposes OPC UA client operations as MCP tools for LLMs and Copilot.
🔧 Migrating from 1.5.378 to 2.0
The 2.0 release introduces breaking API changes, and comes with a full prescriptive migration guide that links to per-area documentation covering telemetry, packages, source generation, types, encoders, node states, identity, certificates, configuration, sessions / subscriptions, alarms / model change, and TimeProvider.
Most of the mechanical migration work is automated:
OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzerNuGet — install it in your project to get analyzer warnings (UA0001–UA0022)- one-click code fixes for the patterns in the guide. Setup steps are in the package's NugetREADME.md.
- Migration agent skill — the
opcua-v20-migrationskill walks Copilot / Claude / any coding agent through installing the NuGet, runningdotnet format analyzersto apply auto-fixes, and handling the small residual manual patterns. The skill knows which sub-doc to load for each symptom so it stays context-efficient.
If you are still on 1.x and not ready to upgrade, stay on the
master378
branch — it continues to receive security and critical-bug fixes.
🤝 Contributing and license
Community contributions are welcome. Fork the repository, make your changes on a branch, and open a pull request; see CONTRIBUTING.md for the contribution workflow.
Contributors must sign the OPC Foundation Contributor License Agreement (CLA). The CLA "I AGREE" gate is presented automatically on your first PR.
The project is licensed under the OPC Foundation MIT License. Report security vulnerabilities via the process documented in SECURITY.md.
📚 Further reading
- Documentation index — every per-feature doc with a one-line description.
- What's New in 2.0 — narrative tour of the 1.5.378 → 2.0 changes grouped by theme and layer.
- OPC UA Profiles and Facets — facets / transports / security policies the stack implements.
- Migration Guide — prescriptive
per-version migration reference (links to
docs/migrate/2.0.x/). - OPC UA Online Reference — the official OPC 10000 series specification index.
- OPC UA .NET Samples — companion repository with more sample applications.
- Preview NuGet feed — prerelease builds from Azure DevOps.