From 0b8cad1870508030e6da22e76d8c66dae3b5ff8b Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Sat, 6 Jun 2026 14:14:01 -0400 Subject: [PATCH] docs: scope Equipment-namespace materialization in the live deploy path Equipment-kind namespaces materialise only their Area/Line/Equipment folder skeleton on deploy, not the signals under them: EquipmentNodeWalker is fully built + unit-tested but has no production call site, the composition/artifact drops EquipmentId-bound tags, and no value source is wired (OpcUaClient driver factory missing; VirtualTag ITagUpstreamSource unregistered). Documents the gaps, workstreams, value-path options, and a structure-only-first sequencing. --- ...uipment-namespace-materialization-scope.md | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 docs/plans/2026-06-06-equipment-namespace-materialization-scope.md diff --git a/docs/plans/2026-06-06-equipment-namespace-materialization-scope.md b/docs/plans/2026-06-06-equipment-namespace-materialization-scope.md new file mode 100644 index 00000000..1ae31d59 --- /dev/null +++ b/docs/plans/2026-06-06-equipment-namespace-materialization-scope.md @@ -0,0 +1,201 @@ +# Scope: Equipment-Namespace Materialization in the Live Deploy Path + +**Status:** Scoping (not yet a task plan) +**Date:** 2026-06-06 +**Author:** investigation while building the Northwind UNS overlay (see `scadaproj/otopcua-uns-loader/`) +**Depends on:** the driver value-streaming fixes already on `master` (`c1ce583`, `b1b3f3f`) + +--- + +## 1. One-paragraph summary + +OtOpcUa can build a **SystemPlatform** namespace (the Galaxy mirror) into the live OPC UA +address space with streaming values, but it **cannot do the same for an `Equipment`-kind +namespace**. The canonical UNS (`Enterprise/Site/Area/Line/Equipment/Signal`) that an Equipment +namespace represents only ever materialises its **skeleton** (Area/Line/Equipment *folders*); the +**signals under equipment** (`Tag`, `VirtualTag`, `ScriptedAlarm` rows) never appear, because the +component that turns those rows into OPC UA variables — `EquipmentNodeWalker` — is **fully built +and unit-tested but never invoked in production**, and the live rebuild path doesn't carry the +data it needs. This document scopes the work to finish that pipeline. + +--- + +## 2. What works vs. what doesn't (verified 2026-06-06) + +**Works — SystemPlatform / Galaxy mirror (reference implementation):** +A deploy materialises one folder per Galaxy object and one variable per `Tag` row, and the driver +streams live values into them. Verified live: 396 tags across 40 machines, all `Good`, on +`opc.tcp://localhost:4840`. Path: +`OpcUaPublishActor.HandleRebuild` → `Phase7Applier.MaterialiseHierarchy` + +`Phase7Applier.MaterialiseGalaxyTags`, and values via the `DriverHostActor` SubscribeBulk pass +(`b1b3f3f`). + +**Doesn't work — Equipment namespace:** +Deploying an `Equipment` namespace + a `UnsArea`/`UnsLine`/`Equipment` + one `VirtualTag` produced: + +``` +Phase7Applier: hierarchy materialised (areas=1, lines=1, equipment=1) ← folders only +``` + +…and the equipment node had **zero child variables** — the VirtualTag never materialised. There +was no equipment-tag/virtual-tag log line at all. + +--- + +## 3. Root cause (precise) + +Three gaps, in order of how fundamental they are: + +### 3.1 `EquipmentNodeWalker` is built + tested but never wired (the core gap) + +- `src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/EquipmentNodeWalker.cs` — `Walk(IAddressSpaceBuilder, EquipmentNamespaceContent)` + materialises every `Equipment` row as a folder and every Equipment-bound `Tag` / `VirtualTag` / + `ScriptedAlarm` as a variable (NodeId = `DriverAttributeInfo.FullName`, i.e. the tag's + `TagConfig.FullName`; VirtualTag uses its `VirtualTagId`). +- **The only call sites are in `tests/Core/.../EquipmentNodeWalkerTests.cs`.** Nothing in `src` + ever calls `EquipmentNodeWalker.Walk`, and nothing builds its input record + `EquipmentNamespaceContent` (the record exists; no producer exists). +- The live rebuild — `src/Server/.../Runtime/OpcUa/OpcUaPublishActor.cs:HandleRebuild` — calls + `MaterialiseHierarchy` (the Area/Line/Equipment *folders*) and `MaterialiseGalaxyTags` + (SystemPlatform only). It never calls `EquipmentNodeWalker`. +- `OtOpcUaNodeManager` references `EquipmentNodeWalker` only in a header comment — not in + `CreateAddressSpace`. + +### 3.2 The deployment composition/artifact drops equipment signals + +- `Phase7CompositionResult` (`src/Server/.../OpcUaServer/Phase7Composer.cs`) carries + `UnsAreas`, `UnsLines`, `EquipmentNodes` *(EquipmentId, DisplayName, UnsLineId — no tags)*, + `DriverInstancePlans`, `ScriptedAlarmPlans`, `GalaxyTags`. **There is no equipment-tag or + virtual-tag list.** +- `DeploymentArtifact.ParseComposition` (`src/Server/.../Runtime/Drivers/DeploymentArtifact.cs`) + reads the artifact's `Tags` array but **`BuildGalaxyTagPlans` explicitly skips any tag with a + non-null `EquipmentId`** (line ~176). So even though equipment tags are serialised into the + artifact, the composition the node consumes throws them away. + +So even if `EquipmentNodeWalker` were wired into `HandleRebuild`, it would have no equipment-tag +data to walk. + +### 3.3 No value source for Equipment-namespace signals + +Equipment signals can be valued two ways; **neither is currently wired**: + +- **Driver-sourced `Tag` (e.g. an OPC UA Client remap of the Galaxy mirror):** the **OpcUaClient + driver has no factory registration** — `DriverFactoryBootstrap.Register` + (`src/Server/.../Host/Drivers/DriverFactoryBootstrap.cs`) wires AbCip/AbLegacy/FOCAS/Galaxy/ + Modbus/S7/TwinCAT but **not OpcUaClient**, so an `OpcUaClient` `DriverInstance` silently stubs → + no values. (The driver itself, `IDriver,ITagDiscovery,IReadable,IWritable,ISubscribable,…`, + exists and is otherwise complete; only the factory `Register` is missing.) +- **`VirtualTag` (script mirrors a live tag):** the `DependencyMuxActor` + a real + `IVirtualTagEvaluator` are registered (`Runtime/ServiceCollectionExtensions.cs:100`, + `Host/Program.cs:102`), and driver values now reach the mux (`DriverHostActor.ForwardToMux`, + `b1b3f3f`). But `VirtualTagContext.GetTag` reads from a per-evaluation cache fed by an + `ITagUpstreamSource`, and **no concrete `ITagUpstreamSource` is registered in the Host** — and + it is unverified whether a `VirtualTag` in an `Equipment` namespace can resolve a tag that lives + in the `SystemPlatform` namespace (cross-namespace `ctx.GetTag("/TestMachine_001/…")`). + +--- + +## 4. Goal / acceptance criteria + +A deploy that includes an `Equipment`-kind namespace results in, on `opc.tcp://…:4840`: + +1. **Structure:** browsable `…////` for every `UnsArea`/`UnsLine`/ + `Equipment`/`Tag`(+`VirtualTag`,`ScriptedAlarm`) row — folders **browse-named by their friendly + `Name`**, not their logical Id (see §6.4). +2. **Values:** each signal carries a live `Good` value (driver-sourced and/or VirtualTag-derived). +3. **Reload-safe:** survives a node restart with no re-deploy (must run on the `RestoreApplied` + bootstrap path added in `b1b3f3f`, not just on a fresh apply). +4. **Verifiable headlessly:** the `scadaproj/otopcua-uns-loader` tool's `verify` passes against the + company-shape namespace (extend it to browse the Equipment tree). + +--- + +## 5. Workstreams + +### WS-1 — Carry equipment signals through the composition (foundational) +Extend `Phase7CompositionResult` with equipment `Tag`/`VirtualTag`/`ScriptedAlarm` plans (or reuse +`EquipmentNamespaceContent`), populate them in `Phase7Composer.Compose`, serialise them in the +deployment artifact, and parse them in `DeploymentArtifact.ParseComposition` (stop discarding +`EquipmentId != null` tags). **Risk: medium** (touches composer + artifact format + planner; needs +a format-compat story for already-sealed artifacts). **Effort: ~1–2 days.** + +### WS-2 — Materialise equipment signals in the live rebuild (wire the existing component) +In `OpcUaPublishActor.HandleRebuild`, after `MaterialiseHierarchy`, build `EquipmentNamespaceContent` +from the composition and call the already-tested `EquipmentNodeWalker.Walk`. Make it idempotent and +diff-aware to match the existing Galaxy-tag pass. **Risk: low–medium** (component is tested; this is +wiring + an idempotency pass). **Effort: ~0.5–1 day.** + +### WS-3 — Value path (pick one or both; see §6.1) +- **3a VirtualTag route:** register a concrete `ITagUpstreamSource` in the Host that bridges the + `DependencyMuxActor`'s tag values into the VirtualTag read-cache; confirm/enable cross-namespace + `ctx.GetTag` resolution (Equipment VirtualTag reading a SystemPlatform mirror tag) and the + dependency-graph re-evaluation trigger. **Risk: high** (cross-namespace resolution + dependency + tracking are unproven end-to-end). **Effort: ~2–3 days.** +- **3b OpcUaClient route:** write+register `OpcUaClientDriverFactoryExtensions.Register` and add it + to `DriverFactoryBootstrap.Register`; extend the SubscribeBulk pass to also subscribe + Equipment-namespace `Tag` refs (`TagConfig.FullName`; NodeId == FullName, so the existing + `ForwardToMux` value routing already applies — a ~30-line generalisation prototyped and reverted + this session); decide the self-referential endpoint topology (a MAIN driver node OPC-UA-clienting + into its own `:4840` Galaxy mirror, vs a second cluster). **Risk: high** (unfinished driver + + self-loop topology). **Effort: ~2–4 days.** + +### WS-4 — Browse-name fix (cosmetic but required for a usable shape) +Today the UNS folder browse name is the logical **Id** (observed `nw-area-filling`), not the +friendly `Name` (`filling`). Confirm whether `Phase7Applier.MaterialiseHierarchy` / +`EquipmentNode.DisplayName` should use `UnsArea.Name`/`UnsLine.Name`/`Equipment.Name` for the +BrowseName (keeping the Id as the NodeId). **Risk: low.** **Effort: ~0.5 day.** + +### WS-5 — Tests + headless verification +Unit: composer carries equipment signals; `HandleRebuild` materialises them; round-trip artifact +parse. Integration: a docker-dev deploy of a small Equipment namespace browses + reads `Good`. +Extend `otopcua-uns-loader verify` to assert the Equipment tree. **Effort: ~1 day.** + +--- + +## 6. Design decisions / open questions + +1. **VirtualTag (3a) vs OpcUaClient (3b) for live values.** VirtualTags reuse the live Galaxy + mirror in-process (no second OPC UA session) but lean on unproven cross-namespace script + resolution; OpcUaClient is the documented "remote-equipment → UNS" pattern but needs an + unfinished driver factory and a self-referential session. **Recommendation:** prototype 3a first + (smaller surface, no new driver), fall back to 3b if cross-namespace resolution proves + intractable. A structure-only milestone (WS-1/2/4, no values) is independently shippable. +2. **Cross-namespace `ctx.GetTag`.** Does an Equipment-namespace VirtualTag resolve a + SystemPlatform Galaxy tag by browse path (`/TestMachine_001/TestChangingInt`) or by reference + (`TestMachine_001.TestChangingInt`)? Determines the script-authoring contract. Must be settled + before WS-3a. +3. **Artifact format compatibility.** Adding equipment signals to the artifact changes its shape; + ensure older sealed artifacts still parse (the parser is tolerant today — keep it so). +4. **Browse-name source** (WS-4) — `Name` vs `Id`. Picking `Name` makes the company shape readable; + confirm nothing keys off the Id-as-BrowseName. + +--- + +## 7. Recommended sequencing + +1. **WS-1 + WS-2 + WS-4 (structure-only):** Equipment namespaces browse the real + `…/area/line/equipment/signal` shape with `BadWaitingForInitialData` leaves. Independently + shippable; de-risks the composition/materialisation half. +2. **WS-3a (VirtualTag values):** lights the structure up by mirroring the live Galaxy tags. +3. **WS-3b (OpcUaClient driver):** only if a true remote-equipment driver path is wanted beyond the + Galaxy mirror. +4. **WS-5** throughout. + +**Rough total:** structure-only ≈ 2–3.5 days; +VirtualTag values ≈ +2–3 days. + +## 8. Out of scope +- Authoring the company UNS rows (the `scadaproj/otopcua-uns-loader` tool already generates them + from `company-uns.json`). +- Any change to the SystemPlatform/Galaxy path, which works. +- The AdminUI UNS editor. + +## 9. Key references +- Works (reference): `OpcUaPublishActor.HandleRebuild` + `Phase7Applier.MaterialiseGalaxyTags`; + SubscribeBulk in `DriverHostActor` (commits `c1ce583`, `b1b3f3f`). +- Built-but-unwired: `Core/OpcUa/EquipmentNodeWalker.cs` (+ `EquipmentNamespaceContent`), + tested only by `EquipmentNodeWalkerTests.cs`. +- Composition gap: `OpcUaServer/Phase7Composer.cs` (`Phase7CompositionResult`), + `Runtime/Drivers/DeploymentArtifact.cs` (`BuildGalaxyTagPlans` skips `EquipmentId != null`). +- Value gaps: `Host/Drivers/DriverFactoryBootstrap.cs` (no OpcUaClient registration); + `Core.VirtualTags/ITagUpstreamSource.cs` (no Host registration found). +- The consuming tool + the company model: `scadaproj/otopcua-uns-loader/`, `scadaproj/company-uns.json`.