83 lines
6.3 KiB
Markdown
83 lines
6.3 KiB
Markdown
# Address Space
|
|
|
|
The address space maps the Galaxy object hierarchy and attribute definitions into an OPC UA browse tree. `LmxNodeManager` builds the tree from data queried by `GalaxyRepositoryService`, while `AddressSpaceBuilder` provides a testable in-memory model of the same structure.
|
|
|
|
## Root ZB Folder
|
|
|
|
Every address space starts with a single root folder node named `ZB` (NodeId `ns=1;s=ZB`). This folder is added under the standard OPC UA `Objects` folder via an `Organizes` reference. The reverse reference is registered through `MasterNodeManager.AddReferences` because `BuildAddressSpace` runs after `CreateAddressSpace` has already consumed the external references dictionary.
|
|
|
|
The root folder has `EventNotifier = SubscribeToEvents` enabled so alarm events propagate up to clients subscribed at the root level.
|
|
|
|
## Area Folders vs Object Nodes
|
|
|
|
Galaxy objects fall into two categories based on `template_definition.category_id`:
|
|
|
|
- **Areas** (`category_id = 13`) become `FolderState` nodes with `FolderType` type definition and `Organizes` references. They represent logical groupings in the Galaxy hierarchy (e.g., production lines, cells).
|
|
- **Non-area objects** (AppEngine, Platform, UserDefined, etc.) become `BaseObjectState` nodes with `BaseObjectType` type definition and `HasComponent` references. These represent runtime automation objects that carry attributes.
|
|
|
|
Both node types use `contained_name` as the browse name. When `contained_name` is null or empty, `tag_name` is used as a fallback.
|
|
|
|
## Variable Nodes for Attributes
|
|
|
|
Each Galaxy attribute becomes a `BaseDataVariableState` node under its parent object. The variable is configured with:
|
|
|
|
- **DataType** -- Mapped from `mx_data_type` via `MxDataTypeMapper` (see [DataTypeMapping.md](DataTypeMapping.md))
|
|
- **ValueRank** -- `OneDimension` (1) for arrays, `Scalar` (-1) for scalars
|
|
- **ArrayDimensions** -- Set to `[array_dimension]` when the attribute is an array
|
|
- **AccessLevel** -- `CurrentReadOrWrite` or `CurrentRead` based on security classification, with `HistoryRead` added for historized attributes
|
|
- **Historizing** -- Set to `true` for attributes with a `HistoryExtension` primitive
|
|
- **Initial value** -- `null` with `StatusCode = BadWaitingForInitialData` until the first MXAccess callback delivers a live value
|
|
|
|
## Primitive Grouping
|
|
|
|
Galaxy objects can have primitive components (e.g., alarm extensions, history extensions) that attach sub-attributes to a parent attribute. The address space handles this with a two-pass approach:
|
|
|
|
### First pass: direct attributes
|
|
|
|
Attributes with an empty `PrimitiveName` are created as direct variable children of the object node. If a direct attribute shares its name with a primitive group, the variable node reference is saved for the second pass.
|
|
|
|
### Second pass: primitive child attributes
|
|
|
|
Attributes with a non-empty `PrimitiveName` are grouped by that name. For each group:
|
|
|
|
1. If a direct attribute variable with the same name already exists, the primitive's child attributes are added as `HasComponent` children of that variable node. This merges alarm/history sub-attributes (e.g., `InAlarm`, `Priority`) under the parent variable they describe.
|
|
2. If no matching direct attribute exists, a new `BaseObjectState` node is created with NodeId `ns=1;s={TagName}.{PrimitiveName}`, and the primitive's attributes are added under it.
|
|
|
|
This structure means that browsing `TestMachine_001/SomeAlarmAttr` reveals both the process value and its alarm sub-attributes (`InAlarm`, `Priority`, `DescAttrName`) as children.
|
|
|
|
## NodeId Scheme
|
|
|
|
All node identifiers use string-based NodeIds in namespace index 1 (`ns=1`):
|
|
|
|
| Node type | NodeId format | Example |
|
|
|-----------|---------------|---------|
|
|
| Root folder | `ns=1;s=ZB` | `ns=1;s=ZB` |
|
|
| Area folder | `ns=1;s={tag_name}` | `ns=1;s=Area_001` |
|
|
| Object node | `ns=1;s={tag_name}` | `ns=1;s=TestMachine_001` |
|
|
| Scalar variable | `ns=1;s={tag_name}.{attr}` | `ns=1;s=TestMachine_001.MachineID` |
|
|
| Array variable | `ns=1;s={tag_name}.{attr}` | `ns=1;s=MESReceiver_001.MoveInPartNumbers` |
|
|
| Primitive sub-object | `ns=1;s={tag_name}.{prim}` | `ns=1;s=TestMachine_001.AlarmPrim` |
|
|
|
|
For array attributes, the `[]` suffix present in `full_tag_reference` is stripped from the NodeId. The `full_tag_reference` (with `[]`) is kept internally for MXAccess subscription addressing. This means `MESReceiver_001.MoveInPartNumbers[]` in the Galaxy maps to NodeId `ns=1;s=MESReceiver_001.MoveInPartNumbers`.
|
|
|
|
## Topological Sort
|
|
|
|
The hierarchy query returns objects ordered by `parent_gobject_id, tag_name`, but this does not guarantee that a parent appears before all of its children in all cases. `LmxNodeManager.TopologicalSort` performs a depth-first traversal to produce a list where every parent is guaranteed to precede its children. This allows the build loop to look up parent nodes from `_nodeMap` without forward references.
|
|
|
|
## Platform Scope Filtering
|
|
|
|
When `GalaxyRepository.Scope` is set to `LocalPlatform`, the hierarchy and attributes passed to `BuildAddressSpace` are pre-filtered by `PlatformScopeFilter` inside `GalaxyRepositoryService`. The node manager receives only the local platform's objects and their ancestor areas, so the resulting browse tree is a subset of the full Galaxy. The filtering is transparent to `LmxNodeManager` — it builds nodes from whatever data it receives.
|
|
|
|
Clients browsing a `LocalPlatform`-scoped server will see only the areas and objects hosted by that platform. Areas that exist in the Galaxy but contain no local descendants are excluded. See [Galaxy Repository — Platform Scope Filter](GalaxyRepository.md#platform-scope-filter) for the filtering algorithm and configuration.
|
|
|
|
## Incremental Sync
|
|
|
|
On address space rebuild (triggered by a Galaxy deploy change), `SyncAddressSpace` uses `AddressSpaceDiff` to identify which `gobject_id` values have changed between the old and new snapshots. Only the affected subtrees are torn down and rebuilt, preserving unchanged nodes and their active subscriptions. Affected subscriptions are snapshot before teardown and replayed after rebuild.
|
|
|
|
If no previous state is cached (first build), the full `BuildAddressSpace` path runs instead.
|
|
|
|
## Key source files
|
|
|
|
- `src/ZB.MOM.WW.LmxOpcUa.Host/OpcUa/LmxNodeManager.cs` -- Node manager with `BuildAddressSpace`, `SyncAddressSpace`, and `TopologicalSort`
|
|
- `src/ZB.MOM.WW.LmxOpcUa.Host/OpcUa/AddressSpaceBuilder.cs` -- Testable in-memory model builder
|