dohertj2/3yearplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integrate Round 3 OtOpcUa corrections into the plan files (goal-state.md, roadmap.md) and append a Round 3 addendum to the corrections doc for audit trail.

Browse Source 
goal-state.md: schemas-repo seed paragraph (line 574) now reflects the `_base` equipment-class template (universal cross-machine baseline that every other class extends), explicit alignment to OPC UA Companion Spec OPC 40010 (Machinery) for the Identification component + MachineryOperationMode enum, OPC UA Part 9 for alarm-summary fields (HasActiveAlarms, ActiveAlarmCount, HighestActiveAlarmSeverity), ISO 22400 for lifetime counters (TotalRunSeconds, TotalCycles) that feed Availability + Performance KPIs, the canonical state vocabulary declared in `_base.stateModel`, and the OtOpcUa central config DB extension with 9 nullable OPC 40010 identity columns (Manufacturer, Model, SerialNumber, HardwareRevision, SoftwareRevision, YearOfConstruction, AssetLocation, ManufacturerUri, DeviceManualUri). Updated format-decisions count from 8 to 10 (added D9 _base+extends inheritance, D10 category→folder mapping). Multi-identifier section (line 156) gains a paragraph describing the OPC 40010 fields as additional first-class metadata beyond the five identifiers, with the operator-set / driver-dynamic-override pattern documented.

roadmap.md: OtOpcUa Year 1 cell (line 66) gains the universal `_base` equipment-class template seeded by the OtOpcUa team, with explicit OPC 40010 / OPC UA Part 9 / ISO 22400 references and the rationale ("avoids per-class drift in identity / state / alarm field naming and ensures every machine in the estate exposes the same baseline metadata regardless of vendor").

handoffs/otopcua-corrections-2026-04-17.md: appended a Round 3 addendum capturing the four follow-on additions (ACL design closing B1, dev-environment two-tier model, cutover scope removal closing C5, `_base` template + OPC 40010 columns building on B2). Updated summary table marks B1 / C1 / C5 as CLOSED, B2 as PARTIALLY CLOSED. Round 3 additions are committed in lmxopcua at `4903a19` and `d8fa3a0`, and in 3yearplan at `5953685` and `cd85159`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-04-17 13:04:18 -04:00
parent cd85159951
commit 8704f9e455
3 changed files with 44 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
goal-state.md
View File

@@ -165,6 +165,8 @@ The plan commits to a **multi-identifier model** — the v2 implementation desig
**Three operator-set fields** (MachineCode, ZTag, SAPID), **two system-generated** (EquipmentUuid, EquipmentId). CSV imports match by `EquipmentUuid` for updates; rows without UUID create new equipment with system-generated identifiers.
Equipment also carries **OPC UA Companion Spec OPC 40010 (Machinery) Identification fields** as first-class metadata — Manufacturer, Model, SerialNumber, HardwareRevision, SoftwareRevision, YearOfConstruction, AssetLocation (free-text supplementary to the UNS path), ManufacturerUri, DeviceManualUri. These are operator-set static metadata (Manufacturer + Model required, the rest optional) exposed on the OPC UA equipment node under the OPC 40010-standard `Identification` sub-folder. Drivers that can read these dynamically (FANUC `cnc_sysinfo()`, Beckhoff `TwinCAT.SystemInfo`, etc.) override the static value at runtime. The full universal cross-machine signal set lives in the `_base` equipment-class template in the schemas repo; every other class extends it.
**`ExternalIdReservation` table — fleet-wide uniqueness for ZTag and SAPID across rollback and re-enable.** Fleet-wide uniqueness for external identifiers cannot be expressed within generation-versioned tables because old generations and disabled equipment can still hold the same values — rollback or re-enable would silently reintroduce duplicates that corrupt downstream ERP/SAP joins. A dedicated `ExternalIdReservation` table sits **outside generation versioning**; `sp_PublishGeneration` reserves IDs atomically at publish; FleetAdmin-only `sp_ReleaseExternalIdReservation` (audit-logged, requires reason) is the only path to free a value for reuse. This is a precedent: some cross-generation invariants need their own non-versioned tables. When ACL design is scoped (see OtOpcUa → Authorization model), check whether any ACL grant has a similar rollback-reuse hazard.
**Path** (the 5-level UNS hierarchy address) is a **sixth** identifier but is **not** stored on the equipment node as a flat property — it is the node's **browse path** by construction. Path can change (equipment moves, area renamed); UUID and EquipmentId cannot.
@@ -571,12 +573,21 @@ The plan already delivers the infrastructure for a cross-system canonical model
This subsection makes that declaration. It is the plan's answer to **Digital Twin Use Cases 1 and 3** (see **Strategic Considerations → Digital twin**) and — independent of digital twin framing — is load-bearing for pillar 2 (analytics/AI enablement) because a canonical model is what makes "not possible before" cross-domain analytics possible at all.
> **Schemas-repo dependency — partially resolved.** The OtOpcUa team has contributed an initial seed at [`schemas/`](../schemas/) (temporary location in the 3-year-plan repo until the dedicated `schemas` repo is created — Gitea push-to-create is disabled). The seed includes: JSON Schema format definitions (`format/equipment-class.schema.json`, `format/tag-definition.schema.json`, `format/uns-subtree.schema.json`), the **FANUC CNC pilot equipment class** (`classes/fanuc-cnc.json` — 16 signals + 3 alarm definitions + state-derivation notes), a worked UNS subtree example (`uns/example-warsaw-west.json`), and documentation (`docs/overview.md`, `docs/format-decisions.md` with 8 numbered decisions, `docs/consumer-integration.md`). The **UNS hierarchy snapshot** (a per-site equipment-instance walk) feeds the initial hierarchy definition. Core driver scope is already resolved by the v2 implementation team's committed driver list.
> **Schemas-repo dependency — partially resolved.** The OtOpcUa team has contributed an initial seed at [`schemas/`](../schemas/) (temporary location in the 3-year-plan repo until the dedicated `schemas` repo is created — Gitea push-to-create is disabled). The seed includes:
> - JSON Schema format definitions (`format/equipment-class.schema.json` with an `extends` field for class inheritance, `format/tag-definition.schema.json`, `format/uns-subtree.schema.json`)
> - A **`_base` equipment-class template** (`classes/_base.json` — the universal cross-machine baseline that every other class extends, providing 27 signals across Identity / Status / Alarm / Diagnostic / Counter / Process categories + 2 universal alarms + the canonical state vocabulary). Aligned with **OPC UA Companion Spec OPC 40010 (Machinery)** for the Identification component (Manufacturer, Model, ProductInstanceUri, SerialNumber, HardwareRevision, SoftwareRevision, YearOfConstruction, ManufacturerUri, DeviceManual, AssetLocation) and MachineryOperationMode enum, **OPC UA Part 9** for alarm-summary fields (HasActiveAlarms, ActiveAlarmCount, HighestActiveAlarmSeverity), **ISO 22400** for lifetime counters that feed Availability + Performance KPIs (TotalRunSeconds, TotalCycles), and the canonical state vocabulary (Running / Idle / Faulted / Starved / Blocked) declared in `_base.stateModel`
> - The **FANUC CNC pilot equipment class** (`classes/fanuc-cnc.json`, `extends: "_base"` — adds 14 CNC-specific signals on top of the inherited base) + 3 FANUC-specific alarm definitions
> - A worked UNS subtree example (`uns/example-warsaw-west.json`)
> - Documentation: `docs/overview.md`, `docs/format-decisions.md` with 10 numbered decisions (the original 8 plus D9 covering `_base` + `extends` inheritance and D10 covering the signal `category` → OPC UA folder placement table), `docs/consumer-integration.md`
>
> The **UNS hierarchy snapshot** (a per-site equipment-instance walk) feeds the initial hierarchy definition. Core driver scope is already resolved by the v2 implementation team's committed driver list.
>
> **OtOpcUa central config DB extended** (per lmxopcua decisions #138 + #139): the Equipment table gains 9 nullable columns for the OPC 40010 Identification fields (Manufacturer, Model, SerialNumber, HardwareRevision, SoftwareRevision, YearOfConstruction, AssetLocation, ManufacturerUri, DeviceManualUri) so operator-set static identity has a first-class home; drivers that can read these dynamically (FANUC `cnc_sysinfo()`, Beckhoff `TwinCAT.SystemInfo`, etc.) override the static value at runtime. Exposed on the OPC UA equipment node under the OPC 40010-standard `Identification` sub-folder per the `category` → folder mapping in `schemas/docs/format-decisions.md` D10.
>
> **Still needs cross-team ownership:**
> - Name an owner team for the schemas content (it's consumed by OT and IT systems alike — OtOpcUa, Redpanda, dbt)
> - Decide whether to move to a dedicated `gitea.dohertylan.com/dohertj2/schemas` repo (proposed) or keep as a 3-year-plan sub-tree
> - Ratify or revise the 8 format decisions in `schemas/docs/format-decisions.md`
> - Ratify or revise the 10 format decisions in `schemas/docs/format-decisions.md`
> - Establish the CI gate for JSON Schema validation
> - Decide on consumer-integration plumbing for Redpanda Protobuf code-gen and dbt macro generation per `schemas/docs/consumer-integration.md`