romanett
96c5ef1623
## Proposed changes Closes #4537. The configure pipeline now lives in `FluentNodeManagerBase`, so a hand-written fluent node manager only overrides `ConfigureAsync` and no longer writes `CreateAddressSpaceAsync` itself. `FluentNodeManagerBase.CreateAddressSpaceAsync` now: 1. loads the predefined nodes (as `AsyncCustomNodeManager` did before), 2. creates a builder for `NamespaceIndex` with `CreateFluentBuilder`, 3. awaits `ConfigureAsync(builder, ct)`, 4. runs `RegisterAuthoredNodesAsync` and then `CompleteConfigureAsync`, 5. finishes with `SealConfigurationAsync`, which seals the builder, replays `NotifyNodeAdded`, then activates behaviors and simulations. ### Breaking change (2.0) Some managers need a different order, for example a post-setup runner before sealing, a builder for another namespace, or work after sealing. They must stop calling `base.CreateAddressSpaceAsync`, because that would now run a second, empty pipeline and seal the manager-owned registries too early. These managers now call `LoadPredefinedNodesAsync(SystemContext, externalReferences, ct)` and keep driving their own pipeline: - the source-generated `NodeManager` template (the ordering test in `NodeManagerGeneratorTests` is updated) - `DiNodeManager`, `Isa95NodeManager`, `PositioningNodeManager`, `RobotIntentNodeManager`, `VisionNodeManager` - `samples/OpenUsd/SiteCompositionServer/SiteNodeManager` These now use the base pipeline: - `samples/FluentApi/BasicFluentApiServer/BasicFluentNodeManager` becomes a single `ConfigureAsync` override. Before this change it never sealed its builder. - the hosting `FluentNodeManager` (from `AddNodeManager(namespaceUri, build)`) becomes a `ConfigureAsync` override. It now seals through `SealConfigurationAsync`, so `OnNodeAdded` handlers wired in the build delegate fire. Before, it called `builder.SealAsync()` directly and they did not. Docs (`NodeManagers.md`, `DeviceIntegration.md`) are updated. `NodeManagers.md` gets a short hand-written `ConfigureAsync` example. ## Types of changes - [x] Breaking change (fix or feature that would cause existing functionality to change) - [x] Enhancement (non-breaking change which adds functionality) ## Checklist - [x] I have read the CONTRIBUTING doc. - [x] I have signed the CLA. - [x] I ran tests locally with my changes, all passed. - [x] I fixed all failing tests in the CI pipelines. - [x] I fixed all introduced issues with CodeQL and LGTM. - [x] I have added tests that prove my fix is effective or that my feature works. - [x] I have added necessary documentation (if appropriate). ## Tests New `FluentNodeManagerBasePipelineTests`: nodes authored in `ConfigureAsync` get registered, the Objects-folder reference is mirrored into `externalReferences`, `OnNodeAdded` fires once, and the builder is sealed afterwards. Local run on net10.0, all passing: - Opc.Ua.Server.Tests (Fluent/Hosting/StateMachine/RuntimeNodeSet filter): 1286 - Opc.Ua.SourceGeneration.Core.Tests (NodeManager filter): 40 - Opc.Ua.Di.Tests 426, ISA95 136, Positioning 69, Robotics 636, Robotics.Intent 22, Vision 484 (+1 skipped), Vision.Intent 14, OpenUsd 921 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
SiteCompositionServer
A supervisory OPC UA server that owns no devices and composes the machines of several subordinate servers into a single live 3D scene.
This is the SCADA-level counterpart to a device server. Where
PumpDeviceIntegrationServer and
GeneratorServer each
publish their own machines and their own twin, this server publishes a site and
says which server owns what.
What it demonstrates
flowchart TD
C["Opc.Ua.OpenUsd.Connector<br/>--federate"]
S["SiteCompositionServer<br/>site shell + camera<br/>owns no devices"]
P["PumpDeviceIntegrationServer<br/>pumps"]
G["GeneratorServer<br/>generator sets"]
C -->|"primary session"| S
S -.->|"ComponentEndpointUrl"| P
S -.->|"ComponentEndpointUrl"| G
C ==>|"federated session"| P
C ==>|"federated session"| G
C --> STAGE[["one live stage<br/>machines from three servers"]]
The site server declares one cross-server component binding per subordinate,
carrying that server's ComponentServerUri and ComponentEndpointUrl. A
connector run with --federate opens a session to each named server, discovers
its representations and drives its bindings into the same stage.
Nothing is mirrored. The site server never proxies a subordinate's address space: it only says where the machines are and lets the connector talk to each owner directly, so there is no cache to invalidate and no second copy of the truth.
Running it
The demo script builds the three servers, publishes the connector and viewport side by side, waits for every endpoint, and cleans up when the viewer closes:
pwsh samples/OpenUsd/SiteCompositionServer/run-site-composition-demo.ps1
Use -Renderer D3D12, -PumpCount, -GeneratorCount, or -Keep to override
the defaults. -ViewerBundlePath can point at an already published connector
and viewport directory.
To start each process manually, run:
Start the two device servers, then the site server:
dotnet run --project samples/DI/PumpDeviceIntegrationServer -- --host localhost --port 62542 --pumps 3
dotnet run --project samples/OpenUsd/GeneratorServer -- --host localhost --port 62543 --generators 2
dotnet run --project samples/OpenUsd/SiteCompositionServer -- --host localhost --port 62544
Then render the composed site:
dotnet run --project tools/Opc.Ua.OpenUsd.Connector -- \
--server opc.tcp://localhost:62544/SiteCompositionServer \
--insecure --federate --view
--pump-server and --generator-server override the subordinate endpoints.
Why --federate is opt-in
The endpoint the connector dials comes from the server being rendered, not from the operator, so honouring it is a trust decision — a server could name any endpoint it likes. The client library is fail-closed (no session factory, no federation) and the command-line connector mirrors that behind an explicit flag. Federated sessions are negotiated exactly the way the primary session is, so composing a subordinate cannot quietly downgrade security.
Federation is also best-effort per component: a subordinate that is down, unreachable or refuses the session is logged and skipped. The rest of the scene still renders and only that server's machines are missing, because one unreachable subordinate taking down the whole stage would be a poor trade.
What lands where
Each subordinate's machines compose at the prim paths that subordinate
publishes — the pump server's pumps under /Plant/..., the generator server's
sets under /Powerhouse/... — because the remote connector drives that server's
own representation. The /Site/PumpHall and /Site/Powerhouse scopes in
Site.usda are the site's own placeholders for those areas.
A verified run against three servers produces one override layer containing:
| From | In the stage |
|---|---|
| Pump server | /Plant/Pumps/… with live impeller rotation and casing colour |
| Generator server | /Powerhouse/Generators/GeneratorSet_1…N with frequency, power, engine hours, fan rotation and thermal colour |
| Site server | /Site/… shell, lighting and the control-room camera |
Files
| File | Purpose |
|---|---|
SiteNodeManager.cs |
Site topology, OpenUSD facility, cross-server component bindings |
Assets/Site.usda |
Ground, building slabs, lighting, control-room camera — deliberately no machine geometry |
Program.cs |
Host wiring and endpoint arguments |