Add a PumpX-2000 datasheet and render every configured pump in the OpenUSD twin

[marcschier]

Description

Two related improvements to the PumpDeviceIntegrationServer sample: an official-style product datasheet that the server is aligned to, and an OpenUSD twin that actually renders every configured pump.

Part 1 — the PumpX-2000 datasheet

The sample had no product documentation, a thin nameplate, and a duty point that was not physically self-consistent.

New: samples/PumpDeviceIntegrationServer/DATASHEET.md — a vendor-style datasheet for the fictitious SimPump Corp PumpX-2000 (clearly marked as a simulated device): nameplate mapped to OPC UA browse paths and namespaces, BEP duty point, characteristic curves, performance table, operating limits, motor/materials/dimensions, instrument list, trip points, simulation-profile formulas and a Mermaid process schematic.

Server aligned to it:

• PumpDatasheet.cs — the datasheet as compile-time constants.
• MaterialiseNameplate — 19 optional identification properties via generator-emitted AddXxx(context) helpers, so each carries the browse name, namespace and DataType declared by the model (21 nameplate fields per pump). Unit-level fields are derived from the pump number, so --pumps N yields a consistent nameplate per instance.
• Curve-based simulation. Volumetric flow is the only independent variable; Δp, mass flow, efficiency and shaft power follow from H(Q) = 32 − 0.0104·Q², η(Q) = 72·(1 − 0.6·((Q−25)/25)²) and P = ρ·g·Q·H/η, so P = Δp·Q/η holds at every tick. Previously each measurement was an independent sine and the sample published 5 kW of shaft power for 0.05 kg/s at 2 bar.
• EURange from the datasheet; OverTempAlarm sources BearingTemperature (the correct SourceNode for an alarm whose limits are in Kelvin); Cavitation and MotorOverheat derived from suction level and bearing temperature with hysteresis.
• PumpDatasheetConformanceTests pins nameplate, ranges, trip points, value envelope and hydraulic consistency against the document.

Part 2 — one OpenUSD twin per pump

The twin was hard-wired to a single machine. PumpPrimPath was the constant /Plant/Pumps/P101 and every pump's representation, component bindings and live bindings used it; the signal Variables lived in single fields each pump overwrote; ShaftAngle/AlarmActive both read the first pump's simulation; and only the first representation was organised into the discovery registry. --pumps 4 rendered one pump, spun by pump 1 and alarmed by pump 4.

• Each pump now owns a PumpTwin: its prim path /Plant/Pumps/<BrowseName>, its signal Variables, its representation and its simulation. Every representation is registered for discovery.
• A plant-level representation on the DeviceSet declares one Many component binding scoped to PumpType, so a connector composes one full-fidelity @pump.usda@</Pump> reference per configured pump. The arc is Reference, not Instance — an instanceable prim turns its descendants into a shared prototype, which cannot carry per-pump rotation or colour.
• Each pump publishes its bay as a ThreeDCartesianCoordinates value bound to xformOp:translate, so any N lays out in a row with no per-pump stage authoring.
• Binding set widened from 4 to 15 per pump: motor cooling fan, discharge-pressure and bearing-temperature gauge needles, a suction vessel whose liquid surface rides on the published Level, suction-line tint from fluid temperature, mass-flow/efficiency/start-count readouts, and distinct cavitation and overheat indications at the place on the machine where each fault is. Scales and offsets are derived from PumpDatasheet.
• The geometry those bindings need is authored into the P101 master and regenerated into pump.usda. The master stays in the layer but active = false — it is the generator's input, and rendering it too would show a phantom machine no OPC UA object drives.

The hall shows the pumps, and only the pumps

Three follow-up problems surfaced once the scene actually rendered N machines, all fixed here:

• Phantom pumps. A demo ProductionLine authored three empty pump bodies on the same aisle at a different pitch, and a RemotePump stood in for a machine on another server. Neither is simulated by the server you connect to, so the viewport showed more pumps than existed and the extras never moved. /Plant/Line1 and remote-pump.usda are gone; the production line still demonstrates aggregation, but over plain topology objects with no representation. The stage now serves two assets and renders exactly the set of pumps the server simulates.

• Phantom alarms. StatusLight defaulted to visibility = "inherited", so any machine without a live binding wore a permanent alarm halo. Indicator geometry now defaults to invisible and is only revealed by a binding.

• Error indication. The alarm light bulb is replaced by an alarm ring — a red annulus authored around the machine and made visible while that pump is in an error condition, so the fault reads at a glance from any angle instead of depending on a small emissive lamp. The bearing overheat halo moves onto the bearing bracket, where the heat actually is.

• Phantom placement. Only one pump was visible however many the server simulated. The bay positions were correct on the wire, but a connector accumulates Translation/Rotation/Scale into a single xformOp:transform matrix — it must, because xformOpOrder is uniform and an op order authored in the asset layer cannot be cleared from the stronger layer a connector edits — while USD evaluates only the ops named in xformOpOrder. The asset named xformOp:translate, and its root prim named nothing at all, so every matrix written to it was discarded in silence and all N pumps resolved to the origin. The two prims a Translation target drives (the pump root and the fluid surface) now declare xformOp:transform.

The stage camera is an operator viewpoint: standing in front of the row at eye height, angled 7° down, with the suction vessels behind the machines. It holds the whole row in frame for 1–8 pumps without moving.

Two deliberate non-changes, both explained in code and README:

• The OverTempAlarm condition is not bound. The fluent alarm builder leaves the condition's state children on their standard namespace-0 declaration NodeIds (which PumpInstanceNodeIdRegressionTests pins), so every pump's alarm shares one ActiveState/Severity/AckedState node — binding them would light every ring at once. The per-pump supervision states are the alarm indication instead, and they are what drives the condition through ActivatesAlarm.
• The plant aggregation is not dynamic. The pump set is fixed by --pumps at start-up, and declaring it dynamic made the connector's stale-prim sweep deactivate the Impeller and Bearing component prims that now live under /Plant/Pumps.

No changes to src/ — this is sample, test and documentation only.

Related Issues

No tracking issue; sample-quality and documentation improvements to the pump reference sample.

Checklist

• I have signed the CLA and read the CONTRIBUTING doc.
• I have added tests that prove my fix is effective or that my feature works and increased code coverage.
• I have added all necessary documentation.
• I have verified that my changes do not introduce (new) build or analyzer warnings.
• 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.

Verification

• dotnet build sample + tests (Release, net10.0): 0 warnings, 0 errors
• dotnet test tests/Opc.Ua.Di.Tests -f net10.0: 371/371 passed
• dotnet test tests/Opc.Ua.OpenUsd.Tests -f net10.0: 635/635 passed
• dotnet test tests/Opc.Ua.Di.Tests -f net48 --filter Pump: 63/63 passed
• dotnet build tests/Opc.Ua.Di.Tests -f net472 (Debug and Release): 0 warnings, 0 errors. PumpDeviceIntegrationServer matches AppTargetFrameworks and does not exist on net472, so the test project drops its project reference and every dependent Pump fixture there; PumpDatasheetConformanceTests is now on that list too.
• EveryConfiguredPumpIsAnIndependentTwinAsync asserts N distinct prims, no cross-pump binding targets, and N distinct shaft angles. OnlySimulatedPumpsAreComposedAsync asserts the composed set is exactly the simulated set.
• End-to-end against a running server with --pumps 5 and the 3D viewport: five referenced pumps compose at bays 0 / 2.4 / 4.8 / 7.2 / 9.6 m; sampling the live override layer twice, ~25 s apart, shows every shaft advancing independently (Δ 3255° / 3363° / 3463° / 3528° / 3542°), and only the pump in an error condition has its AlarmRing visible. No remote-pump, Line1 or P_20x references remain in the composed stage. Live read also confirms Δp·(ṁ/ρ)/η matches the published shaft power.
• Checked against real OpenUSD composition: composing five referenced pumps and authoring each bay as the matrix the sink writes, the previous asset resolves four of five to (0,0,0) while this one resolves each to its own bay. TransformBindingsTargetDeclaredXformOpsAsync pins the rule that produced it.
• Code review found two defects in the live-signal path, both fixed: signal registration walked every twin on a call made once per pump, so the publish set grew as N(N+1)/2 and the first pump was re-published once per later pump; and the publish set was a plain List appended to by the runtime-add path while the 250 ms tick enumerated it, which would throw on the timer thread and stop the simulation for every pump. EveryPumpPublishesItsShaftAngleExactlyOnce pins the first.

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

This PR adds an “official-style” PumpX-2000 datasheet to the PumpDeviceIntegrationServer sample and aligns the sample server + tests so the simulated address space, ranges, alarms, and hydraulics remain consistent with the published documentation.

Changes:

• Added a full PumpX-2000 datasheet (markdown + Mermaid diagrams) and updated sample docs to reference it.
• Rebuilt the sample simulation to derive all process values from datasheet curves and added compile-time datasheet constants (PumpDatasheet.cs).
• Added conformance/regression tests that pin nameplate fields, ranges, alarm trip points, and hydraulic consistency to the datasheet.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Opc.Ua.Di.Tests/PumpInstanceNodeIdRegressionTests.cs	Extends the node-surface baseline to include newly materialized Identification properties.
tests/Opc.Ua.Di.Tests/PumpDatasheetConformanceTests.cs	Adds deterministic conformance tests to prevent drift between datasheet and address space/simulation.
samples/PumpDeviceIntegrationServer/README.md	Adds datasheet link + diagrams and documents the new simulation/alarm behavior.
samples/PumpDeviceIntegrationServer/PumpNodeManager.cs	Materializes optional nameplate properties via generator helpers to match model-defined names/namespaces/datatypes.
samples/PumpDeviceIntegrationServer/PumpNodeManager.Configure.cs	Aligns nameplate values, EURanges, alarm source/limits, and simulation math with the datasheet.
samples/PumpDeviceIntegrationServer/PumpDatasheet.cs	Introduces a single source of truth for datasheet constants used by the sample and tests.
samples/PumpDeviceIntegrationServer/Program.cs	Updates the declarative Pump #2 identification wiring to match the datasheet across namespaces.
samples/PumpDeviceIntegrationServer/DATASHEET.md	Adds the vendor-style PumpX-2000 datasheet (nameplate, curves, ranges, alarms, simulation profile).
docs/SourceGeneratedNodeManagers.md	Updates docs examples to match new naming/ranges and correct property CLR types.
docs/DeviceIntegration.md	Links to the datasheet and updates the topology-element builder example identification wiring.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.91%. Comparing base (8a10139) to head (edb30f4).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4138      +/-   ##
==========================================
- Coverage   80.23%   79.91%   -0.32%     
==========================================
  Files        1515     1515              
  Lines      209980   209980              
  Branches    36213    36213              
==========================================
- Hits       168479   167811     -668     
- Misses      28867    29568     +701     
+ Partials    12634    12601      -33     

see 52 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.