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

docs: native alarm ingestion across component docs + CLAUDE.md

Browse Source
This commit is contained in:
Joseph Doherty
2026-05-31 02:55:00 -04:00
parent 2b7c765a58
commit 003e54c1fb
9 changed files with 265 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/requirements/Component-Communication.md
+26
View File
@@ -87,6 +87,32 @@ The streaming protocol is defined in `sitestream.proto` (`src/ZB.MOM.WW.ScadaBri
- The `oneof event` pattern is extensible — future event types (health metrics, connection state changes) are added as new fields without breaking existing consumers.
- Proto field numbers are never reused. Old clients ignore unknown `oneof` variants.
#### Enriched AlarmStateUpdate (Native Alarm Mirror)
`AlarmStateUpdate` carries the read-only native alarm mirror (Computed, native OPC UA, and native MxAccess Gateway alarms) to central over the **existing gRPC real-time stream** — no new transport, no command/control round-trip. The message was extended **additively**: existing fields 1–7 are unchanged, and fields 8–21 carry the enriched native-alarm state. Old clients that only read fields 1–7 continue to work; new fields are populated only where the source provides them.
| Field | # | Type | Meaning |
|-------|---|------|---------|
| `kind` | 8 | string | Alarm origin: `Computed`, `NativeOpcUa`, or `NativeMxAccess`. |
| `active` | 9 | bool | Alarm condition is active. |
| `acknowledged` | 10 | bool | Alarm has been acknowledged. |
| `confirmed` | 11 | bool | Alarm has been confirmed. The domain `Confirmed` (`bool?`) collapses to a definite bool on the wire. |
| `shelve_state` | 12 | string | `Unshelved`, `OneShotShelved`, `TimedShelved`, or `PermanentShelved`. |
| `suppressed` | 13 | bool | Alarm is suppressed by the source system. |
| `source_reference` | 14 | string | Source node / tag reference. |
| `alarm_type_name` | 15 | string | Native alarm type name. |
| `category` | 16 | string | Alarm category. |
| `operator_user` | 17 | string | User who last acted on the alarm. |
| `operator_comment` | 18 | string | Operator comment from the last action. |
| `original_raise_time` | 19 | Timestamp | First-raise time of the underlying condition (nullable on the wire). |
| `current_value` | 20 | string | Current process value associated with the alarm. |
| `limit_value` | 21 | string | Limit / setpoint value that the alarm evaluates against. |
- **Server-side mapping (`StreamRelayActor.HandleAlarmStateChanged`)**: maps the enriched domain `AlarmStateChanged` event — `Kind` + `AlarmConditionState` + native metadata — out to the proto `AlarmStateUpdate`. The nullable `original_raise_time` is emitted only when present, and `shelve_state` is mapped from the domain shelve enum to its wire string via a new **`AlarmShelveStateCodec`** (string↔enum, defaulting to `Unshelved`). The domain `Confirmed` (`bool?`) is collapsed to a definite bool for field 11.
- **Client-side mapping (`SiteStreamGrpcClient.ConvertToDomainEvent`)**: reconstructs the domain `AlarmStateChanged` from the proto — `Kind` is parsed via `ParseAlarmKind`, the `Condition` is rebuilt with `severity` taken from the existing wire `priority`, and native metadata is repopulated from fields 8–21 — so central-side consumers receive the same domain event the site emitted.
> **Regeneration is manual (macOS-only).** `sitestream.proto` is **not** auto-compiled: the `<Protobuf>` include is commented out in the `.csproj`, and the generated C# is **vendored** under `SiteStreamGrpc/`. To regenerate after editing the proto: toggle the `<Protobuf>` include on, build so `Grpc.Tools` regenerates the C#, copy the generated files into `SiteStreamGrpc/`, then re-comment the include. Adding fields 8–21 followed this process.
#### gRPC Connection Keepalive
Three layers of dead-client detection prevent orphan streams on site nodes: