From 47cb5725a95e9da9298d981a35a1a5bc96a53549 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 12 Jun 2026 21:17:30 -0400 Subject: [PATCH] =?UTF-8?q?docs(galaxy):=20retire=20alias/SystemPlatform?= =?UTF-8?q?=20model=20=E2=80=94=20Galaxy=20tags=20are=20standard=20equipme?= =?UTF-8?q?nt=20tags?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 55 +++++++++++++++++++++++-------------------------- docs/Uns.md | 59 ++++++++++++++--------------------------------------- 2 files changed, 41 insertions(+), 73 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d91625c2..66aa8954 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,17 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Goal -Build an OPC UA server (.NET 10) that exposes AVEVA System Platform -(Wonderware) Galaxy tags. The server mirrors the Galaxy object -hierarchy as an OPC UA address space, translating between -contained-name browse paths and tag-name runtime references. Galaxy -access flows through the in-process `GalaxyDriver` -(`src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/`) talking gRPC to a separately -installed **mxaccessgw** gateway process. The gateway owns the -MXAccess COM bitness constraint (its worker is x86 net48); everything -in this repo is .NET 10. PR 7.2 retired the legacy in-process -`Galaxy.Host` / `Galaxy.Proxy` / `Galaxy.Shared` projects + the -`OtOpcUaGalaxyHost` Windows service. +Build an OPC UA server (.NET 10) that exposes industrial data sources — +including AVEVA System Platform (Wonderware) Galaxy — under a unified +Equipment-based address space. Galaxy access flows through the in-process +`GalaxyDriver` (`src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/`) talking gRPC +to a separately installed **mxaccessgw** gateway process. The gateway owns the +MXAccess COM bitness constraint (its worker is x86 net48); everything in this +repo is .NET 10. PR 7.2 retired the legacy in-process `Galaxy.Host` / +`Galaxy.Proxy` / `Galaxy.Shared` projects + the `OtOpcUaGalaxyHost` Windows +service. See `docs/v2/Galaxy.Performance.md` for the runtime perf surface (tracing, metrics, soak harness). @@ -32,27 +30,26 @@ See `docs/v2/Galaxy.Performance.md` for the runtime perf surface gRPC session. The gateway owns the COM apartment + STA pump server-side; the driver speaks `MxCommand` / `MxEvent` protos exclusively. -3. **OPC UA Server** — Exposes the hierarchy as browse nodes and - attributes as variable nodes. Clients browse via contained names - but reads/writes are translated to `tag_name.AttributeName` format - for MXAccess. +3. **OPC UA Server** — Exposes authored equipment tags as variable nodes. + Galaxy tags are bound by `TagConfig.FullName` (`tag_name.AttributeName`); + reads/writes/subscriptions are translated to that reference for MXAccess. -### Key Concept: Contained Name vs Tag Name +### Key Concept: Tag Name and FullName -Galaxy objects have two names: -- **contained_name** — human-readable name scoped to parent (used for OPC UA browse tree) -- **tag_name** — globally unique system name (used for MXAccess read/write) +Galaxy objects have a **tag_name** — a globally unique system name used for +MXAccess read/write — and attributes are referenced as `tag_name.AttributeName` +(e.g. `DelmiaReceiver_001.DownloadPath`). This dot-separated reference is what +`TagConfig.FullName` stores for a Galaxy equipment tag. The Galaxy address +picker browses the live hierarchy using contained names for navigation, then +resolves the selection to the `tag_name.AttributeName` form. -Example: browsing `TestMachine_001/DelmiaReceiver/DownloadPath` translates to MXAccess reference `DelmiaReceiver_001.DownloadPath`. - -**Alias tags** (`GalaxyMxGateway`-backed equipment `Tag`s) are a lighter -alternative to relay virtual tags: they store the Galaxy reference as -`TagConfig.FullName` (`tag_name.AttributeName`) and surface it under a UNS name -via a direct driver subscription, delivering native MX quality/timestamp with no -Roslyn script. They are authored on the equipment page's **Tags** tab via the -"Add alias (browse Galaxy)" button. A relay→alias converter runs per-equipment -(Tags-tab toolbar) or fleet-wide at `/uns/convert-relays` (FleetAdmin-gated), -with a dry-run preview before applying. +**Galaxy is a standard Equipment-kind driver.** Galaxy points are ordinary +equipment `Tag`s bound to `GalaxyMxGateway` via `TagConfig.FullName` +(`tag_name.AttributeName`), authored through the standard Tag modal + Galaxy +address picker on the equipment page's Tags tab — the same flow as Modbus or +S7. There is no alias machinery, no `SystemPlatform` namespace kind, and no +relay→alias converter. See +`docs/plans/2026-06-12-galaxy-standard-driver-design.md` for the full design. ### Data Type Mapping diff --git a/docs/Uns.md b/docs/Uns.md index 677718f1..79396f39 100644 --- a/docs/Uns.md +++ b/docs/Uns.md @@ -74,7 +74,7 @@ changed by editing the area's cluster in the Area modal, which moves the whole branch. There is no separate "served-by" concept and no migration — it is simply `UnsArea.ClusterId`. -### Tags vs. Galaxy / SystemPlatform tags +### Tags Tags created on the equipment page are **equipment-bound** and require a driver instance. The driver list on the Tags tab is scoped to the equipment's cluster @@ -82,11 +82,11 @@ and to drivers on an **Equipment-kind** namespace, so a driver-less equipment shows no eligible drivers until you bind one (edit the equipment on the Details tab and pick a driver). -**Galaxy / AVEVA System Platform tags are not shown in this tree.** They hang -off the driver's folder path and are auto-materialised from the Galaxy -browse rather than being equipment-bound, so they stay on the **Drivers** tab -of their cluster (`/clusters/{id}/drivers`), where the address picker browses -the live Galaxy hierarchy. +**Galaxy / AVEVA System Platform points are ordinary equipment tags** bound to +a `GalaxyMxGateway` driver instance. Author them on the Tags tab using the +standard Tag modal; the Galaxy address picker browses the live Galaxy hierarchy +so you can select the attribute and set `TagConfig.FullName`. There is no +separate alias concept or `SystemPlatform`-kind namespace. ### Virtual tags @@ -95,45 +95,16 @@ Add and edit virtual tags on the equipment page's **Virtual Tags** tab; the data type is chosen from the standard OPC UA type list and the Monaco script editor is available inline. -### Alias tags +### Galaxy tags -An **alias tag** surfaces a Galaxy attribute under a friendly UNS name without -requiring a Roslyn script. It is an ordinary equipment `Tag` bound to the -`GalaxyMxGateway` driver; the Galaxy reference is stored in `TagConfig` as -`{"FullName":"tag_name.AttributeName"}`. Because the value comes from a direct -driver subscription — not a script relay — quality and timestamp are native MX, -and there is no Roslyn overhead. - -**Adding an alias:** on the equipment **Tags** tab, click **Add alias (browse -Galaxy)**. A live Galaxy browse picker opens; navigate to the attribute you -want. After selecting it, set the tag **Name**, **DataType**, and **AccessLevel** -(default: read-only; opt in to write-through at your own discretion — writes go -through the Galaxy driver's security). The button is disabled when the -equipment's cluster has no `GalaxyMxGateway` driver instance. - -In the Tags list, alias tags show an **alias** badge and their Source as -`galaxy:`. There is no new entity type or schema -migration — the alias is just a `Tag` row with `DriverType = GalaxyMxGateway` -and the `FullName` field in its JSON config. - -**Relay → alias converter:** if you have existing "relay" virtual tags whose -scripts are nothing but `return ctx.GetTag("X").Value;`, a converter can -rewrite them as alias tags automatically: - -- **Per-equipment** — a toolbar action on the Tags tab opens a dry-run preview - (lists what will be converted and what will be skipped), then a confirm-apply - step. -- **Fleet-wide** — `/uns/convert-relays` (FleetAdmin-gated) runs the same - dry-run + apply across all equipment in the fleet. - -The converter skips and reports items it cannot safely migrate: -- virtual tags whose body is not a pure single-value relay -- virtual tags that are historized -- equipment whose cluster has no Galaxy gateway -- relay references containing `{{equip}}` tokens that cannot be resolved - -The converter edits the **draft config only** — deploy normally afterward to -activate the changes. +`GalaxyMxGateway` is an **Equipment-kind driver** — Galaxy points are ordinary +equipment tags authored through the standard Tag modal, exactly like Modbus or +S7 tags. The Galaxy reference is stored as `TagConfig.FullName` +(`tag_name.AttributeName`). The Galaxy address picker on the Tags tab lets you +browse the live Galaxy hierarchy to select an attribute; after selecting, set +the tag **Name**, **DataType**, and **AccessLevel** (default: read-only). There +is no alias concept, no `SystemPlatform`-kind namespace, and no relay→alias +converter. ## Bulk import