Refactor protobuffer to align with architecture discussion (#9)

## Description refactor protocol buffers to align with architecture discussion in zaphiro-technologies/architecture#113 ## Changes Made * grouped messages in `grid` and `platform`. * documented headers for RabbitMQ. * removed duplicated content from `platform` messages (that are never sent into sets) ## Related Issues Fixes #8 ## Checklist - [x] I have used a PR title that is descriptive enough for a release note. - [x] I have tested these changes locally. - [x] I have added appropriate tests or updated existing tests. - [ ] I have tested these changes on a dedicated VM or a customer VM [name of the VM] - [x] I have added appropriate documentation or updated existing documentation.
zaphiro-technologies · Oct 20, 2023 · 11cdb1c · 11cdb1c · kdevelleZ · Oct 27, 2023
1 parent 5b0e7ce
commit 11cdb1c
Show file tree

Hide file tree

Showing 17 changed files with 939 additions and 849 deletions.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,6 +1,6 @@
 # ProtoBuf Release Notes
 
-## 0.0.1-dev - 2023-10-17
+## 0.0.1-dev - 2023-10-20
 
 ### Features
 
@@ -13,5 +13,7 @@
 
 ### Refactoring
 
+- Refactor protobuffer to align with architecture discussion (PR #9 by
+  @chicco785)
 - Migrate existing protobuf from
   `https://github.com/zaphiro-technologies/rabbitmq-poc` (PR #2 by @chicco785)
diff --git a/docs/conf2.proto.md b/docs/conf2.proto.md
@@ -24,7 +24,13 @@
 classDiagram
 direction LR
 
-%% Configuration frame 2
+%% Configuration frame 2 
+%% Headers used in rabbitMQ:
+%% * `id`: id of the `Conf2Frame`
+%% * `type`: always `Conf2Frame`
+%% * `producerId`: the id of the producer (e.g. a PMU) linked to the configuration frame.
+%% * `timestampId`: related measurement timestamp (if any)
+%% 
 
 class Conf2Frame {
   + uint32 DATA_RATE
@@ -82,7 +88,7 @@ class Config {
 ## Message: Conf2Frame
 <div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: conf.v1.Conf2Frame</div>
 
-<div class="comment"><span>Configuration frame 2</span><br/></div>
+<div class="comment"><span>Configuration frame 2 </span><br/><span>Headers used in rabbitMQ:</span><br/><span>* `id`: id of the `Conf2Frame`</span><br/><span>* `type`: always `Conf2Frame`</span><br/><span>* `producerId`: the id of the producer (e.g. a PMU) linked to the configuration frame.</span><br/><span>* `timestampId`: related measurement timestamp (if any)</span><br/><span></span><br/></div>
 
 | Field     | Ordinal | Type        | Label    | Description                   |
 |-----------|---------|-------------|----------|-------------------------------|

diff --git a/docs/data.proto.md b/docs/data.proto.md
@@ -1,4 +1,4 @@
-# Package: data.v1
+# Package: grid.v1
 
 <div class="comment"><span><!-- markdownlint-disable --></span><br/><span>Messages to support data injection in the platform.</span><br/><span>The data injected may be originated from different sources (e.g. a PMU, RTU, an external service).</span><br/><span></span><br/><span>Data are grouped into sets, where each id identifies a specific measurement. The id does not identify the instance of measurement, but the class of measurement. Measurement ID can be used to retrieve additional medata about the measurement, from example, in the CIM OP profile associated to the monitored grid.</span><br/></div>
 
@@ -13,12 +13,12 @@
 
 | Name       | Value     | Description |
 |------------|-----------|-------------|
-| go_package | ./data/v1 |             |
+| go_package | ./grid/v1 |             |
 
 
 
 ## Enum: DataType
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: data.v1.DataType</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.DataType</div>
 
 <div class="comment"><span>The collection of Data Types defined so far. They are useful to map</span><br/><span>measurements to their rappresentation. Some of the descriptions are taken from [here](https://github.com/digin-energi/Grunnprofil/blob/develop/DIGIN10/docs/MeasurementType.adoc) This is important since all measurements</span><br/><span>are any how cast to UINT64 in the real time platform</span><br/></div>
 
@@ -136,10 +136,13 @@ class DataType{
 classDiagram
 direction LR
 
-%% A single data. It has:
-%% - a given data type,
-%% - a point in time of measurement (encoded as int64 using Unix Epoc),
-%% - a value (encoded as uint64)
+%% A single data.
+%% Headers used in rabbitMQ (only if not sent as part of `DataSet`):
+%% * `id`: id of the `Data`
+%% * `type`: always `Data`
+%% * `producerId`: the id of the producer (e.g. a PMU) linked to the dataset.
+%% * `timestampId`: related measurement Unix msec timestamp (if any)
+%% 
 
 class Data {
   + DataType dataType
@@ -155,9 +158,13 @@ Data --> `DataType`
 classDiagram
 direction LR
 
-%% A set of data:
-%% - the id of the procuder of the data
-%% - the map containing data
+%% A set of data.
+%% Headers used in rabbitMQ:
+%% * `id`: id of the `DataSet`
+%% * `type`: always `DataSet`
+%% * `producerId`: the id of the producer (e.g. a PMU) linked to the dataset.
+%% * `timestampId`: related measurement Unix msec timestamp (if any)
+%% 
 
 class DataSet {
   + Map~string,  Data~ data
@@ -168,21 +175,21 @@ DataSet .. ` Data`
 ```
 
 ## Message: Data
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: data.v1.Data</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.Data</div>
 
-<div class="comment"><span>A single data. It has:</span><br/><span>- a given data type,</span><br/><span>- a point in time of measurement (encoded as int64 using Unix Epoc),</span><br/><span>- a value (encoded as uint64)</span><br/></div>
+<div class="comment"><span>A single data.</span><br/><span>Headers used in rabbitMQ (only if not sent as part of `DataSet`):</span><br/><span>* `id`: id of the `Data`</span><br/><span>* `type`: always `Data`</span><br/><span>* `producerId`: the id of the producer (e.g. a PMU) linked to the dataset.</span><br/><span>* `timestampId`: related measurement Unix msec timestamp (if any)</span><br/><span></span><br/></div>
 
-| Field      | Ordinal | Type     | Label    | Description                                            |
-|------------|---------|----------|----------|--------------------------------------------------------|
-| dataType   | 1       | DataType |          | The type of data see `DataType` enum.                  |
-| measuredAt | 2       | int64    |          | The time of measurement (Unix Timestamp Nanoseconds).  |
-| value      | 3       | uint64   | Optional | The data value casted to uint64.                       |
+| Field      | Ordinal | Type     | Label    | Description                                     |
+|------------|---------|----------|----------|-------------------------------------------------|
+| dataType   | 1       | DataType |          | The type of data see `DataType` enum.           |
+| measuredAt | 2       | int64    |          | The time of measurement (Unix msec timestamp).  |
+| value      | 3       | uint64   | Optional | The data value casted to uint64.                |
 
 
 ## Message: DataSet
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: data.v1.DataSet</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.DataSet</div>
 
-<div class="comment"><span>A set of data:</span><br/><span>- the id of the procuder of the data</span><br/><span>- the map containing data</span><br/></div>
+<div class="comment"><span>A set of data.</span><br/><span>Headers used in rabbitMQ:</span><br/><span>* `id`: id of the `DataSet`</span><br/><span>* `type`: always `DataSet`</span><br/><span>* `producerId`: the id of the producer (e.g. a PMU) linked to the dataset.</span><br/><span>* `timestampId`: related measurement Unix msec timestamp (if any)</span><br/><span></span><br/></div>
 
 | Field      | Ordinal | Type         | Label | Description                                                 |
 |------------|---------|--------------|-------|-------------------------------------------------------------|

diff --git a/docs/fault.proto.md b/docs/fault.proto.md
@@ -1,4 +1,4 @@
-# Package: fault.v1
+# Package: grid.v1
 
 <div class="comment"><span><!-- markdownlint-disable --></span><br/><span>Messages describing faults.</span><br/><span></span><br/></div>
 
@@ -11,14 +11,14 @@
 
 ## Options
 
-| Name       | Value      | Description |
-|------------|------------|-------------|
-| go_package | ./fault/v1 |             |
+| Name       | Value     | Description |
+|------------|-----------|-------------|
+| go_package | ./grid/v1 |             |
 
 
 
 ## Enum: PhaseConnectedFaultKind
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: fault.v1.PhaseConnectedFaultKind</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.PhaseConnectedFaultKind</div>
 
 <div class="comment"><span></span><br/><span> The type of fault connection among phases.</span><br/><span></span><br/><span> This message is modeled after [CIM PhaseConnectedFaultKind](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/PhaseConnectedFaultKind).</span><br/><span></span><br/></div>
 
@@ -32,7 +32,7 @@
 
 
 ## Enum: PhaseCode
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: fault.v1.PhaseCode</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.PhaseCode</div>
 
 <div class="comment"><span></span><br/><span>An unordered enumeration of phase identifiers. Allows designation of phases for both transmission and distribution equipment, circuits and loads. The enumeration, by itself, does not describe how the phases are connected together or connected to ground. Ground is not explicitly denoted as a phase.</span><br/><span>Residential and small commercial loads are often served from single-phase, or split-phase, secondary circuits. For the example of s12N, phases 1 and 2 refer to hot wires that are 180 degrees out of phase, while N refers to the neutral wire. Through single-phase transformer connections, these secondary circuits may be served from one or two of the primary phases A, B, and C. For three-phase loads, use the A, B, C phase codes instead of s12N.</span><br/><span>The integer values are from IEC 61968-9 to support revenue metering applications.</span><br/><span></span><br/><span>This message is modeled after [CIM PhaseCode](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/PhaseCode/).</span><br/><span></span><br/></div>
 
@@ -140,9 +140,14 @@ direction LR
 %% 
 %% This message is modeled after [CIM Fault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/Fault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.
 %% 
+%% Headers used in rabbitMQ:
+%% * `id`: id of the `Fault`
+%% * `type`: always `Fault`
+%% * `producerId`: the id of the producer (e.g. a PMU) linked to the notification.
+%% 
 
 class Fault {
-  + string ID
+  + string Id
   + Optional~string~ description
   + Optional~float~ faultCurrent
   + Optional~string~ faultyEquipmentId
@@ -167,6 +172,11 @@ direction LR
 %% 
 %% This message is modeled after [CIM LineFault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/LineFault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.
 %% 
+%% Headers used in rabbitMQ:
+%% * `id`: id of the `Fault`
+%% * `type`: always `LineFault`
+%% * `producerId`: the id of the producer (e.g. a PMU) linked to the notification.
+%% 
 
 class LineFault {
   + Optional~string~ acLineSegmentID
@@ -187,6 +197,11 @@ direction LR
 %% 
 %% This message is modeled after [CIM EquipmentFault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/EquipmentFault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.
 %% 
+%% Headers used in rabbitMQ:
+%% * `id`: id of the `EquipmentFault`
+%% * `type`: always `LineFault`
+%% * `producerId`: the id of the producer (e.g. a PMU) linked to the notification.
+%% 
 
 class EquipmentFault {
   + Fault fault
@@ -197,28 +212,28 @@ EquipmentFault --> `Fault`
 ```
 
 ## Message: Fault
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: fault.v1.Fault</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.Fault</div>
 
-<div class="comment"><span>Abnormal condition causing current flow through conducting equipment, such as caused by equipment failure or short circuits from objects not typically modelled (for example, a tree falling on a line).</span><br/><span></span><br/><span>This message is modeled after [CIM Fault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/Fault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.</span><br/><span></span><br/></div>
+<div class="comment"><span>Abnormal condition causing current flow through conducting equipment, such as caused by equipment failure or short circuits from objects not typically modelled (for example, a tree falling on a line).</span><br/><span></span><br/><span>This message is modeled after [CIM Fault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/Fault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.</span><br/><span></span><br/><span>Headers used in rabbitMQ:</span><br/><span>* `id`: id of the `Fault`</span><br/><span>* `type`: always `Fault`</span><br/><span>* `producerId`: the id of the producer (e.g. a PMU) linked to the notification.</span><br/><span></span><br/></div>
 
 | Field                | Ordinal | Type                    | Label    | Description                                                                                                                 |
 |----------------------|---------|-------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
-| ID                   | 1       | string                  |          | The uuid of the fault.                                                                                                      |
+| Id                   | 1       | string                  |          | The uuid of the fault.                                                                                                      |
 | description          | 2       | string                  | Optional | The textual description of the fault.                                                                                       |
 | faultCurrent         | 8       | float                   | Optional | The current associated to the fault.                                                                                        |
 | faultyEquipmentId    | 6       | string                  | Optional | The equipment with the fault.                                                                                               |
 | impactedEquipmentIds | 10      | string                  | Repeated | The set of IDs of equipments impacted by the fault.                                                                         |
 | kind                 | 3       | PhaseConnectedFaultKind |          | The kind of phase fault.                                                                                                    |
 | located              | 9       | bool                    | Optional | Was the fault located.                                                                                                      |
 | locationTime         | 7       | int64                   | Optional | The time when the fault was located.                                                                                        |
-| occurredDateTime     | 5       | int64                   |          | The date and time at which the fault occurred.                                                                              |
+| occurredDateTime     | 5       | int64                   |          | The date and time at which the fault occurred (Unix msec timestamp).                                                        |
 | phases               | 4       | PhaseCode               |          | The phases participating in the fault. The fault connections into these phases are further specified by the type of fault.  |
 
 
 ## Message: LineFault
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: fault.v1.LineFault</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.LineFault</div>
 
-<div class="comment"><span>A fault that occurs on an AC line segment at some point along the length.</span><br/><span></span><br/><span>This message is modeled after [CIM LineFault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/LineFault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.</span><br/><span></span><br/></div>
+<div class="comment"><span>A fault that occurs on an AC line segment at some point along the length.</span><br/><span></span><br/><span>This message is modeled after [CIM LineFault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/LineFault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.</span><br/><span></span><br/><span>Headers used in rabbitMQ:</span><br/><span>* `id`: id of the `Fault`</span><br/><span>* `type`: always `LineFault`</span><br/><span>* `producerId`: the id of the producer (e.g. a PMU) linked to the notification.</span><br/><span></span><br/></div>
 
 | Field               | Ordinal | Type   | Label    | Description                                                                                                                    |
 |---------------------|---------|--------|----------|--------------------------------------------------------------------------------------------------------------------------------|
@@ -228,9 +243,9 @@ EquipmentFault --> `Fault`
 
 
 ## Message: EquipmentFault
-<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: fault.v1.EquipmentFault</div>
+<div style="font-size: 12px; margin-top: -10px;" class="fqn">FQN: grid.v1.EquipmentFault</div>
 
-<div class="comment"><span></span><br/><span>A fault applied at the terminal, external to the equipment. This class is not used to specify faults internal to the equipment.</span><br/><span></span><br/><span>This message is modeled after [CIM EquipmentFault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/EquipmentFault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.</span><br/><span></span><br/></div>
+<div class="comment"><span></span><br/><span>A fault applied at the terminal, external to the equipment. This class is not used to specify faults internal to the equipment.</span><br/><span></span><br/><span>This message is modeled after [CIM EquipmentFault](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Faults/EquipmentFault) according to the extensions defined in the [fault-data-storage](https://github.com/zaphiro-technologies/architecture/blob/main/features/31-fault-data-storage.md#data-structures) feature.</span><br/><span></span><br/><span>Headers used in rabbitMQ:</span><br/><span>* `id`: id of the `EquipmentFault`</span><br/><span>* `type`: always `LineFault`</span><br/><span>* `producerId`: the id of the producer (e.g. a PMU) linked to the notification.</span><br/><span></span><br/></div>
 
 | Field      | Ordinal | Type   | Label    | Description                                                        |
 |------------|---------|--------|----------|--------------------------------------------------------------------|