From ce33d9189f91786d42b04b39f906e30f30244169 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 16:06:37 +0200 Subject: [PATCH 01/10] Remove `rated_bounds` from `Metric` and `MetricAggregation` `rated_bounds` contain mostly static information, which do not need to be sent with every metric. These will now be available when listing descriptions for components. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 3 +++ proto/frequenz/api/common/v1/metrics.proto | 10 ---------- 2 files changed, 3 insertions(+), 10 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 43bf2a4b..94890c60 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -8,6 +8,9 @@ - `lower` and `upper` bounds fields in the `Bounds` message are now `optional` +- `rated_bounds` field has been removed from the messages `Metric` and + `MetricAggregation` + ## New Features diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index bd6d14d8..e398804e 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -27,11 +27,6 @@ message Metric { // The current value of the metric. float value = 1; - // The manufacturer's rated bounds of the metric. This may differ from - // `system_bounds` as it does not take into account the current state of the - // overall system. - Bounds rated_bounds = 2; - // The current bounds of the metric, as imposed by the component this metric // originates from. Bounds component_bounds = 3; @@ -113,11 +108,6 @@ message MetricAggregation { // The array of all the metric values. repeated float raw_values = 12; - // The manufacturer's rated bounds of the metric. This may differ from - // `system_bounds` as it does not take into account the current state of the - // overall system. - frequenz.api.common.v1.metrics.Bounds rated_bounds = 13; - // The current bounds of the metric, as imposed by the component this metric // originates from. frequenz.api.common.v1.metrics.Bounds component_bounds = 14; From 00d79976e8cef0f022cbd2679f0efe7e4a397245 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 16:09:00 +0200 Subject: [PATCH 02/10] Remove `component_bounds` from `Metric` and `MetricAggregation` The information contained in these bounds is redundant, since these are supposed to be incorporated into the `system_inclusion_bounds` field. Hence the `component_bounds` field has been removed from the messages. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 3 +++ proto/frequenz/api/common/v1/metrics.proto | 8 -------- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 94890c60..deb61fd5 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -11,6 +11,9 @@ - `rated_bounds` field has been removed from the messages `Metric` and `MetricAggregation` +- `component_bounds` field has been removed from the messages `Metric` and + `MetricAggregation` + ## New Features diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index e398804e..a6ddb286 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -27,10 +27,6 @@ message Metric { // The current value of the metric. float value = 1; - // The current bounds of the metric, as imposed by the component this metric - // originates from. - Bounds component_bounds = 3; - // These bounds indicate the range of values that are disallowed for the // metric. // If these bounds for a metric are [`lower`, `upper`], then this metric's @@ -108,10 +104,6 @@ message MetricAggregation { // The array of all the metric values. repeated float raw_values = 12; - // The current bounds of the metric, as imposed by the component this metric - // originates from. - frequenz.api.common.v1.metrics.Bounds component_bounds = 14; - // These bounds indicate the range of values that are disallowed for the // metric. // If these bounds for a metric are [`lower`, `upper`], then this metric's From 1688a14f61077ecbf3968086d6ea8ae66eaa756e Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 16:48:46 +0200 Subject: [PATCH 03/10] Replace inclusion and exclusion bounds with a single array of bounds This commit removes the `system_inclusion_bounds` and `system_exclusion_bounds` fields from the `Metric` and `MetricAggregation` messages. These fields have been replaced with a single array of `Bounds` in both messages. This simplifies the message definition, and removes the requirement of clients having to check if a parameter is _not_ in a given pair of bounds. This also extends the possibility of having more than 2 pairs bounds for a given metric. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 6 + proto/frequenz/api/common/v1/metrics.proto | 134 ++++++--------------- 2 files changed, 44 insertions(+), 96 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index deb61fd5..3240cd9d 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -14,6 +14,12 @@ - `component_bounds` field has been removed from the messages `Metric` and `MetricAggregation` +- Inclusion and exclusion bounds have been removed from the metric definitions. + These have been replaced with an array of inclusion bounds. This simplifies + the message definition, and removes the requirement of clients having to check + if a parameter is _not_ in a given pair of bounds. This also extends the + possibility of having more than 2 pairs bounds for a given metric. + ## New Features diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index a6ddb286..91eb50c1 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -27,61 +27,32 @@ message Metric { // The current value of the metric. float value = 1; - // These bounds indicate the range of values that are disallowed for the - // metric. - // If these bounds for a metric are [`lower`, `upper`], then this metric's - // `value` needs to comply with the constraints - // `value <= lower` OR `upper <= value`. + // List of bounds that apply to the metric sample. // - // It is important to note that these bounds work together with - // `system_inclusion_bounds`. + // These bounds adapt in real-time to reflect the operating conditions at the + // time of sampling. // - // E.g., for the system to accept a charge command, - // clients need to request power values within the bounds - // `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`. - // This means that clients can only request charge commands with values that - // are within the `system_inclusion_bounds`, but not within - // `system_exclusion_bounds`. - // Similarly, for the system to accept a discharge command, - // clients need to request power values within the bounds - // `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`. + // ### Multiple Bounds // - // The following diagram illustrates the relationship between the bounds. - // ``` - // inclusion.lower inclusion.upper - // <-------|============|------------------|============|---------> - // exclusion.lower exclusion.upper - // ``` - // ---- values here are disallowed and wil be rejected - // ==== vales here are allowed and will be accepted - Bounds system_exclusion_bounds = 4; - - // These bounds indicate the range of values that are allowed for the metric. - // If these bounds for a metric are [`lower`, `upper`], then this metric's - // `value` needs to comply with the constraint `lower <= value <= upper` - // - // It is important to note that these bounds work together with - // `system_exclusion_bounds`. - // - // E.g., for the system to accept a charge command, - // clients need to request power values within the bounds - // `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`. - // This means that clients can only request charge commands with values that - // are within the `system_inclusion_bounds`, but not within - // `system_exclusion_bounds`. - // Similarly, for the system to accept a discharge command, - // clients need to request power values within the bounds - // `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`. + // In the case of certain components like batteries, multiple bounds might + // exist. These multiple bounds collectively extend the range of allowable + // values, effectively forming a union of all given bounds. In such cases, + // the value of the metric must be within at least one of the bounds. + // In accordance with the passive sign convention, bounds that limit discharge + // would have negative numbers, while those limiting charge, such as for the + // State of Power (SoP) metric, would be positive. Hence bounds can have + // positive and negative values depending on the metric they represent. // - // The following diagram illustrates the relationship between the bounds. + // Example: + // The diagram below illustrates the relationship between the bounds. // ``` - // inclusion.lower inclusion.upper + // bound[0].lower bound[1].upper // <-------|============|------------------|============|---------> - // exclusion.lower exclusion.upper + // bound[0].upper bound[1].lower // ``` - // ---- values here are disallowed and wil be rejected - // ==== vales here are allowed and will be accepted - Bounds system_inclusion_bounds = 5; + // ---- values here are disallowed and will be rejected + // ==== values here are allowed and will be accepted + repeated Bounds bounds = 3; } // Metrics depicted as a collection of statistical summaries. @@ -104,59 +75,30 @@ message MetricAggregation { // The array of all the metric values. repeated float raw_values = 12; - // These bounds indicate the range of values that are disallowed for the - // metric. - // If these bounds for a metric are [`lower`, `upper`], then this metric's - // `value` needs to comply with the constraints - // `value <= lower` OR `upper <= value`. + // List of bounds that apply to the metric sample. // - // It is important to note that these bounds work together with - // `system_inclusion_bounds`. - // - // E.g., for the system to accept a charge command, - // clients need to request power values within the bounds - // `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`. - // This means that clients can only request charge commands with power values - // that are within the `system_inclusion_bounds`, but not within - // `system_exclusion_bounds`. - // Similarly, for the system to accept a discharge command, - // clients need to request power values within the bounds - // `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`. - // - // The following diagram illustrates the relationship between the bounds. - // ``` - // inclusion.lower inclusion.upper - // <-------|============|------------------|============|---------> - // exclusion.lower exclusion.upper - // ``` - // ---- values here are disallowed and wil be rejected - // ==== vales here are allowed and will be accepted - frequenz.api.common.v1.metrics.Bounds system_exclusion_bounds = 4; - - // These bounds indicate the range of values that are allowed for the metric. - // If these bounds for a metric are [`lower`, `upper`], then this metric's - // `value` needs to comply with the constraint `lower <= value <= upper` + // These bounds adapt in real-time to reflect the operating conditions at the + // time of aggregation or derivation. // - // It is important to note that these bounds work together with - // `system_exclusion_bounds`. + // ### Multiple Bounds // - // E.g., for the system to accept a charge command, - // clients need to request power values within the bounds - // `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`. - // This means that clients can only request charge commands with power values - // that are within the `system_inclusion_bounds`, but not within - // `system_exclusion_bounds`. - // Similarly, for the system to accept a discharge command, - // clients need to request power values within the bounds - // `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`. + // In the case of certain components like batteries, multiple bounds might + // exist. These multiple bounds collectively extend the range of allowable + // values, effectively forming a union of all given bounds. In such cases, + // the value of the metric must be within at least one of the bounds. + // In accordance with the passive sign convention, bounds that limit discharge + // would have negative numbers, while those limiting charge, such as for the + // State of Power (SoP) metric, would be positive. Hence bounds can have + // positive and negative values depending on the metric they represent. // - // The following diagram illustrates the relationship between the bounds. + // Example: + // The diagram below illustrates the relationship between the bounds. // ``` - // inclusion.lower inclusion.upper + // bound[0].lower bound[1].upper // <-------|============|------------------|============|---------> - // exclusion.lower exclusion.upper + // bound[0].upper bound[1].lower // ``` - // ---- values here are disallowed and wil be rejected - // ==== vales here are allowed and will be accepted - frequenz.api.common.v1.metrics.Bounds system_inclusion_bounds = 5; + // ---- values here are disallowed and will be rejected + // ==== values here are allowed and will be accepted + repeated Bounds bounds = 6; } From acc0d6745e5c946661d9c96fa86d4c46e5768cfe Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 17:00:20 +0200 Subject: [PATCH 04/10] Rename fields in `MetricAggregation` message This commit renames the fields in the `MetricAggregation` message to make them consistent with the `Metric` message. The following renames have been done: - `avg` -> `avg_value` - `min` -> `min_value` - `max` -> `max_value` Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 3 +++ proto/frequenz/api/common/v1/metrics.proto | 16 ++++++++-------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 3240cd9d..cf3a8352 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -20,6 +20,9 @@ if a parameter is _not_ in a given pair of bounds. This also extends the possibility of having more than 2 pairs bounds for a given metric. +- Fields in `MetricAggregation` message have been suffixed with `_value`, to + make them consistent with the `Metric` message. + ## New Features diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index 91eb50c1..858d1ba2 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -63,17 +63,17 @@ message Metric { // by all these sensors, like, min, max, avg, etc., and if possible, the entire // array of temperature values. message MetricAggregation { - // The average value of the metric. - float avg = 1; + // The derived average value of the metric. + float avg_value = 2; - // The minimum value of the metric. - optional float min = 2; + // The minimum measured value of the metric. + optional float min_value = 3; - // The maximum value of the metric. - optional float max = 3; + // The maximum measured value of the metric. + optional float max_value = 4; - // The array of all the metric values. - repeated float raw_values = 12; + // Optional array of all the raw individual values. + repeated float raw_values = 5; // List of bounds that apply to the metric sample. // From 706249dcef431fc5a8941620d60eae3e630c9446 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 17:02:35 +0200 Subject: [PATCH 05/10] Add timestamps to metric messages The `sampled_at` field has been added to both the `Metric` and `MetricAggregation` messages. This makes it easier to use these messages in a timeseries context, where each metric sample is associated with a timestamp. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 3 +++ proto/frequenz/api/common/v1/metrics.proto | 13 +++++++++++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index cf3a8352..1f896e08 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -23,6 +23,9 @@ - Fields in `MetricAggregation` message have been suffixed with `_value`, to make them consistent with the `Metric` message. +- Timestamps have been introduced in the metric messages. This makes it easier + to use these messages in a timeseries context. + ## New Features diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index 858d1ba2..a48df699 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -10,6 +10,8 @@ syntax = "proto3"; package frequenz.api.common.v1.metrics; +import "google/protobuf/timestamp.proto"; + // A set of lower and upper bounds for any metric. // The units of the bounds are always the same as the related metric. message Bounds { @@ -24,8 +26,11 @@ message Bounds { // A metric's value, with optional limits. message Metric { - // The current value of the metric. - float value = 1; + // The UTC timestamp of when the data was either measured or derived. + google.protobuf.Timestamp sampled_at = 1; + + // The value of the metric, which could be either measured or derived. + float value = 2; // List of bounds that apply to the metric sample. // @@ -63,6 +68,10 @@ message Metric { // by all these sensors, like, min, max, avg, etc., and if possible, the entire // array of temperature values. message MetricAggregation { + // The UTC timestamp indicating the period over which the data was aggregated + // or derived. + google.protobuf.Timestamp sampled_at = 1; + // The derived average value of the metric. float avg_value = 2; From d866d1d934bdf5d946845d4870350691e701d8d5 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 17:04:17 +0200 Subject: [PATCH 06/10] Rename `Metric` and `MetricAggregation` messages This commit renames the `Metric` and `MetricAggregation` messages to `SimpleMetricSample` and `AggregatedMetricSample` respectively. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 4 ++ proto/frequenz/api/common/v1/metrics.proto | 40 ++++++++++++++----- .../api/common/v1/metrics/electrical.proto | 40 +++++++++---------- 3 files changed, 55 insertions(+), 29 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 1f896e08..1f6b16aa 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -26,6 +26,10 @@ - Timestamps have been introduced in the metric messages. This makes it easier to use these messages in a timeseries context. +- Renamed `Metric` message to `SimpleMetricSample` + +- Renamed `MetricAggregation` message to `AggregatedMetricSample` + ## New Features diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index a48df699..f6468d5a 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -24,8 +24,21 @@ message Bounds { optional float upper = 2; } -// A metric's value, with optional limits. -message Metric { +// Represents a simple metric sample with an array of real-time system-defined +// bounds. +// +// This represents a single sample of a specific metric, the value of which is +// either measured or derived at a particular time. +// The real-time system-defined bounds are optional and may not always be +// present or set. +// +// ### Interplay Between Bounds and Metric Samples +// +// Consider a scenario where a metric sample for battery charging power is +// registered at `10kW`. If there is a request to change the battery's charging +// power, the proposed power level must align with the existing bounds. Failure +// to do so will result in the command being rejected. +message SimpleMetricSample { // The UTC timestamp of when the data was either measured or derived. google.protobuf.Timestamp sampled_at = 1; @@ -60,14 +73,23 @@ message Metric { repeated Bounds bounds = 3; } -// Metrics depicted as a collection of statistical summaries. +// Encapsulates derived statistical summaries of a single metric. +// +// The message allows for the reporting of statistical summaries—minimum, +// maximum, and average values - as well as the complete list of individual +// samples if available. +// +// This message represents derived metrics and contains fields for statistical +// summaries—minimum, maximum, and average values. Individual measurements and +// bounds are optional, accommodating scenarios where only subsets of this +// information are available. +// +// ### Relationship Between Bounds and Metric Samples // -// Useful when a component has to report multiple values for the same metric. -// E.g., a battery is a collection of several blocks, and each block has a -// temperature sensor. The battery can report a summary of the values provided -// by all these sensors, like, min, max, avg, etc., and if possible, the entire -// array of temperature values. -message MetricAggregation { +// Suppose a metric sample for current has an average value of `10A`. For the +// system to accept a charge command, clients need to request current values +// within the bounds. +message AggregatedMetricSample { // The UTC timestamp indicating the period over which the data was aggregated // or derived. google.protobuf.Timestamp sampled_at = 1; diff --git a/proto/frequenz/api/common/v1/metrics/electrical.proto b/proto/frequenz/api/common/v1/metrics/electrical.proto index 1e69b130..36acdc22 100644 --- a/proto/frequenz/api/common/v1/metrics/electrical.proto +++ b/proto/frequenz/api/common/v1/metrics/electrical.proto @@ -16,21 +16,21 @@ import "frequenz/api/common/v1/metrics.proto"; message DC { // The DC voltage across the component. // In Volt (V). - metrics.Metric voltage = 1; + metrics.SimpleMetricSample voltage = 1; // The DC current flowing away from the grid connection. // In passive sign convention: // +ve current means consumption, away from the grid. // -ve current means supply into the grid. // In Ampere (A). - metrics.Metric current = 2; + metrics.SimpleMetricSample current = 2; // The DC power flowing away from the grid connection. // In passive sign convention: // +ve power means consumption, away from the grid. // -ve power means supply into the grid. // In Watt (W). - metrics.Metric power = 3; + metrics.SimpleMetricSample power = 3; } // The current state and metrics of the electrical connections to the @@ -42,15 +42,15 @@ message AC { // This is a signed value in passive sign convention: if more energy is // consumed than delivered, this is a -ve number, otherwise +ve. // In Watt-hour (Wh). - metrics.Metric energy = 1; + SimpleMetricSample energy = 1; // The consumed energy. // In Watt-hour (Wh). - metrics.Metric energy_consumed = 2; + SimpleMetricSample energy_consumed = 2; // The delivered energy. // In Watt-hour (Wh). - metrics.Metric energy_delivered = 3; + SimpleMetricSample energy_delivered = 3; } // The reactive energy the inverter is consuming or generating. @@ -59,15 +59,15 @@ message AC { // This is a signed value. If more energy is capacitive than inductive, // this is a -ve number, otherwise +ve. // In Volt-Ampere-hour (VArh). - metrics.Metric energy = 1; + SimpleMetricSample energy = 1; // The capacitive energy. // In Volt-Ampere-hour (VArh). - metrics.Metric energy_capacitive = 2; + SimpleMetricSample energy_capacitive = 2; // The inductive energy. // In Volt-Ampere-hour (VArh). - metrics.Metric energy_inductive = 3; + SimpleMetricSample energy_inductive = 3; } // The harmonics of the fast Fourier transform of the instantaneous values @@ -91,30 +91,30 @@ message AC { message ACPhase { // The AC voltage between the line and the neutral wire. // In Volt (V). - metrics.Metric voltage = 1; + SimpleMetricSample voltage = 1; // AC current. // +ve current means consumption, away from the grid. // -ve current means supply into the grid. // In Ampere (A). - metrics.Metric current = 2; + SimpleMetricSample current = 2; // AC active power. // +ve power means consumption, away from the grid. // -ve power means supply into the grid. // In Watt (W). - metrics.Metric power_active = 3; + SimpleMetricSample power_active = 3; // AC reactive power. // +ve power means inductive (leading). // -ve power means capacitive (lagging). // In Volt-Ampere reactive (VAr). - metrics.Metric power_reactive = 4; + SimpleMetricSample power_reactive = 4; // The total apparent energy. A Positive value represents the net apparent // energy supplied to the grid connection, and vice versa. // In Volt-Ampere-hour (VAh). - metrics.Metric energy_apparent = 5; + SimpleMetricSample energy_apparent = 5; // The total active energy counters for the underlying component's // consumption and supply. @@ -140,34 +140,34 @@ message AC { // The AC frequency. // In Hertz (Hz). - metrics.Metric frequency = 1; + SimpleMetricSample frequency = 1; // The apparent 3-phase AC current. Positive values represent apparent energy // flowing towards the grid connection, and vice versa. // In Ampere (A). - metrics.Metric current = 2; + SimpleMetricSample current = 2; // The apparent 3-phase AC power. Positive values represent apparent energy // flowing towards the grid connection, and vice versa. // In Volt-Ampere (VA). - metrics.Metric power_apparent = 3; + SimpleMetricSample power_apparent = 3; // The total active 3-phase AC active power. // +ve power means consumption, away from the grid. // -ve power means supply into the grid. // In Watt (W). - metrics.Metric power_active = 4; + SimpleMetricSample power_active = 4; // The reactive 3-phase AC power. // +ve power means inductive (leading). // -ve power means capacitive (lagging). // In Volt-Ampere reactive (VAr). - metrics.Metric power_reactive = 5; + SimpleMetricSample power_reactive = 5; // The total 3-phase apparent energy. A positive value represents the net // apparent energy supplied to the grid connection, and vice versa. // In Volt-Ampere-hour (VAh). - metrics.Metric energy_apparent = 6; + SimpleMetricSample energy_apparent = 6; // The total 3-phase active energy counters for the underlying component's // consumption and supply. From aa6e48a57860eb749f5e1bba23a8078315ec7ae9 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 17:06:55 +0200 Subject: [PATCH 07/10] Add a new message `MetricSampleVariant` This message can encapsulate either a `SimpleMetricSample` or an `AggregatedMetricSample`. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 3 +++ proto/frequenz/api/common/v1/metrics.proto | 18 ++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 1f6b16aa..82d6ddb1 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -30,6 +30,9 @@ - Renamed `MetricAggregation` message to `AggregatedMetricSample` +- Added a union type message `MetricSampleVariant` to represent both + `SimpleMetricSample` and `AggregatedMetricSample` + ## New Features diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index f6468d5a..f00c2e52 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -133,3 +133,21 @@ message AggregatedMetricSample { // ==== values here are allowed and will be accepted repeated Bounds bounds = 6; } + +// MetricSampleVariant serves as a union type that can encapsulate either a +// `SimpleMetricSample` or an `AggregatedMetricSample`. +// +// This message is designed to offer flexibility in capturing different +// granularities of metric samples—either a simple single-point measurement +// or an aggregated set of measurements for a metric. +// +// A `MetricSampleVariant`` can hold either a `SimpleMetricSample` or an +// `AggregatedMetricSample`, but not both simultaneously. Setting one will +// nullify the other. +// +message MetricSampleVariant { + oneof metric_return_type { + SimpleMetricSample simple_metric = 1; + AggregatedMetricSample aggregated_metric = 2; + } +} From 52ebc13e5f5aaecc86d7f500f3d5f5bb773fe85e Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Fri, 20 Oct 2023 17:44:34 +0200 Subject: [PATCH 08/10] Add an enum containing valid metrics that can be streamed Signed-off-by: Tiyash Basu --- proto/frequenz/api/common/v1/metrics.proto | 92 ++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index f00c2e52..ee6b1621 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -151,3 +151,95 @@ message MetricSampleVariant { AggregatedMetricSample aggregated_metric = 2; } } + +// List of supported metrics. +enum Metric { + // Default value. + METRIC_UNSPECIFIED = 0; + + // DC electricity metrics + METRIC_DC_VOLTAGE = 1; + METRIC_DC_CURRENT = 2; + METRIC_DC_POWER = 3; + + // General AC electricity metrics + METRIC_AC_FREQUENCY = 10; + METRIC_AC_VOLTAGE = 11; + METRIC_AC_VOLTAGE_PHASE_1 = 12; + METRIC_AC_VOLTAGE_PHASE_2 = 13; + METRIC_AC_VOLTAGE_PHASE_3 = 14; + METRIC_AC_APPARENT_CURRENT = 15; + METRIC_AC_APPARENT_CURRENT_PHASE_1 = 16; + METRIC_AC_APPARENT_CURRENT_PHASE_2 = 17; + METRIC_AC_APPARENT_CURRENT_PHASE_3 = 18; + + // AC power metrics + METRIC_AC_APPARENT_POWER = 20; + METRIC_AC_APPARENT_POWER_PHASE_1 = 21; + METRIC_AC_APPARENT_POWER_PHASE_2 = 22; + METRIC_AC_APPARENT_POWER_PHASE_3 = 23; + METRIC_AC_ACTIVE_POWER = 24; + METRIC_AC_ACTIVE_POWER_PHASE_1 = 25; + METRIC_AC_ACTIVE_POWER_PHASE_2 = 26; + METRIC_AC_ACTIVE_POWER_PHASE_3 = 27; + METRIC_AC_REACTIVE_POWER = 28; + METRIC_AC_REACTIVE_POWER_PHASE_1 = 29; + METRIC_AC_REACTIVE_POWER_PHASE_2 = 30; + METRIC_AC_REACTIVE_POWER_PHASE_3 = 31; + + // AC Power factor + METRIC_AC_POWER_FACTOR = 40; + METRIC_AC_POWER_FACTOR_PHASE_1 = 41; + METRIC_AC_POWER_FACTOR_PHASE_2 = 42; + METRIC_AC_POWER_FACTOR_PHASE_3 = 43; + + // AC energy metrics + METRIC_AC_APPARENT_ENERGY = 50; + METRIC_AC_APPARENT_ENERGY_PHASE_1 = 51; + METRIC_AC_APPARENT_ENERGY_PHASE_2 = 52; + METRIC_AC_APPARENT_ENERGY_PHASE_3 = 53; + METRIC_AC_ACTIVE_ENERGY = 54; + METRIC_AC_ACTIVE_ENERGY_PHASE_1 = 55; + METRIC_AC_ACTIVE_ENERGY_PHASE_2 = 56; + METRIC_AC_ACTIVE_ENERGY_PHASE_3 = 57; + METRIC_AC_ACTIVE_ENERGY_CONSUMED = 58; + METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_1 = 59; + METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_2 = 60; + METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_3 = 61; + METRIC_AC_ACTIVE_ENERGY_DELIVERED = 62; + METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_1 = 63; + METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_2 = 64; + METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_3 = 65; + METRIC_AC_REACTIVE_ENERGY = 66; + METRIC_AC_REACTIVE_ENERGY_PHASE_1 = 67; + METRIC_AC_REACTIVE_ENERGY_PHASE_2 = 69; + METRIC_AC_REACTIVE_ENERGY_PHASE_3 = 70; + + // AC harmonics + METRIC_AC_THD_CURRENT = 80; + METRIC_AC_THD_CURRENT_PHASE_1 = 81; + METRIC_AC_THD_CURRENT_PHASE_2 = 82; + METRIC_AC_THD_CURRENT_PHASE_3 = 83; + + // General BMS metrics. + METRIC_BATTERY_CAPACITY = 101; + METRIC_BATTERY_SOC_PCT = 102; + METRIC_BATTERY_SOP_CHARGE = 103; + METRIC_BATTERY_SOP_DISCHARGE = 104; + METRIC_BATTERY_TEMPERATURE = 105; + + // General inverter metrics. + METRIC_INVERTER_TEMPERATURE = 120; + + // EV charging station metrics. + METRIC_EV_CHARGER_TEMPERATURE = 140; + + //General sensor metrics + METRIC_SENSOR_WIND_SPEED = 160; + METRIC_SENSOR_WIND_DIRECTION = 162; + METRIC_SENSOR_TEMPERATURE = 163; + METRIC_SENSOR_RELATIVE_HUMIDITY = 164; + METRIC_SENSOR_DEW_POINT = 165; + METRIC_SENSOR_AIR_PRESSURE = 166; + METRIC_SENSOR_IRRADIANCE = 167; +} From 7297c153ad1c610f6985f97367596f9eb10d2e60 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Mon, 23 Oct 2023 16:48:36 +0200 Subject: [PATCH 09/10] Improve documentation style in metrics.proto Signed-off-by: Tiyash Basu --- proto/frequenz/api/common/v1/metrics.proto | 45 +++++++++++----------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/proto/frequenz/api/common/v1/metrics.proto b/proto/frequenz/api/common/v1/metrics.proto index ee6b1621..8ed8ed5e 100644 --- a/proto/frequenz/api/common/v1/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics.proto @@ -27,17 +27,17 @@ message Bounds { // Represents a simple metric sample with an array of real-time system-defined // bounds. // -// This represents a single sample of a specific metric, the value of which is -// either measured or derived at a particular time. -// The real-time system-defined bounds are optional and may not always be -// present or set. +// !!! note +// This represents a single sample of a specific metric, the value of which +// is either measured or derived at a particular time. The real-time +// system-defined bounds are optional and may not always be present or set. // -// ### Interplay Between Bounds and Metric Samples -// -// Consider a scenario where a metric sample for battery charging power is -// registered at `10kW`. If there is a request to change the battery's charging -// power, the proposed power level must align with the existing bounds. Failure -// to do so will result in the command being rejected. +// !!! usage +// ### Interplay Between Bounds and Metric Samples +// Consider a scenario where a metric sample for battery charging power is +// registered at `10kW`. If there is a request to change the battery's +// charging power, the proposed power level must align with the existing +// bounds. Failure to do so will result in the command being rejected. message SimpleMetricSample { // The UTC timestamp of when the data was either measured or derived. google.protobuf.Timestamp sampled_at = 1; @@ -50,7 +50,7 @@ message SimpleMetricSample { // These bounds adapt in real-time to reflect the operating conditions at the // time of sampling. // - // ### Multiple Bounds + // #### Multiple Bounds // // In the case of certain components like batteries, multiple bounds might // exist. These multiple bounds collectively extend the range of allowable @@ -61,7 +61,8 @@ message SimpleMetricSample { // State of Power (SoP) metric, would be positive. Hence bounds can have // positive and negative values depending on the metric they represent. // - // Example: + // #### Example + // // The diagram below illustrates the relationship between the bounds. // ``` // bound[0].lower bound[1].upper @@ -75,7 +76,7 @@ message SimpleMetricSample { // Encapsulates derived statistical summaries of a single metric. // -// The message allows for the reporting of statistical summaries—minimum, +// The message allows for the reporting of statistical summaries — minimum, // maximum, and average values - as well as the complete list of individual // samples if available. // @@ -84,11 +85,11 @@ message SimpleMetricSample { // bounds are optional, accommodating scenarios where only subsets of this // information are available. // -// ### Relationship Between Bounds and Metric Samples -// -// Suppose a metric sample for current has an average value of `10A`. For the -// system to accept a charge command, clients need to request current values -// within the bounds. +// !!! note +// ### Relationship Between Bounds and Metric Samples +// Suppose a metric sample for current has an average value of `10A`. For +// the system to accept a charge command, clients need to request current +// values within the bounds. message AggregatedMetricSample { // The UTC timestamp indicating the period over which the data was aggregated // or derived. @@ -111,7 +112,7 @@ message AggregatedMetricSample { // These bounds adapt in real-time to reflect the operating conditions at the // time of aggregation or derivation. // - // ### Multiple Bounds + // #### Multiple Bounds // // In the case of certain components like batteries, multiple bounds might // exist. These multiple bounds collectively extend the range of allowable @@ -122,7 +123,8 @@ message AggregatedMetricSample { // State of Power (SoP) metric, would be positive. Hence bounds can have // positive and negative values depending on the metric they represent. // - // Example: + // #### Example + // // The diagram below illustrates the relationship between the bounds. // ``` // bound[0].lower bound[1].upper @@ -141,10 +143,9 @@ message AggregatedMetricSample { // granularities of metric samples—either a simple single-point measurement // or an aggregated set of measurements for a metric. // -// A `MetricSampleVariant`` can hold either a `SimpleMetricSample` or an +// A `MetricSampleVariant` can hold either a `SimpleMetricSample` or an // `AggregatedMetricSample`, but not both simultaneously. Setting one will // nullify the other. -// message MetricSampleVariant { oneof metric_return_type { SimpleMetricSample simple_metric = 1; From 4fd1c73112f6b589f37fd8fefd1146034af51fa0 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Mon, 23 Oct 2023 17:51:34 +0200 Subject: [PATCH 10/10] Add a message to represent metrics sampled from components The newly added message `frequenz.api.common.v1.components.data.ComponentData` represents metrics, states, and errors sampled from components. Each such message contains a list of `MetricSample` messages, each of which represents a sampled metric along with its value. The message also contains a list of `State` messages, each of which represents a component state and errors sampled at a specific time. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 2 + .../api/common/v1/components/data.proto | 334 ++++++++++++++++++ .../api/common/v1/components/__init__.py | 4 + 3 files changed, 340 insertions(+) create mode 100644 proto/frequenz/api/common/v1/components/data.proto create mode 100644 py/frequenz/api/common/v1/components/__init__.py diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 82d6ddb1..7601527a 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -33,6 +33,8 @@ - Added a union type message `MetricSampleVariant` to represent both `SimpleMetricSample` and `AggregatedMetricSample` +- Added a message to represent metrics sampled from components. + ## New Features diff --git a/proto/frequenz/api/common/v1/components/data.proto b/proto/frequenz/api/common/v1/components/data.proto new file mode 100644 index 00000000..9c919ae6 --- /dev/null +++ b/proto/frequenz/api/common/v1/components/data.proto @@ -0,0 +1,334 @@ +// Data format definitions for components. +// +// Copyright: +// Copyright 2023 Frequenz Energy-as-a-Service GmbH +// +// License: +// MIT + +syntax = "proto3"; + +package frequenz.api.common.v1.components.data; + +import "frequenz/api/common/v1/metrics.proto"; + +import "google/protobuf/timestamp.proto"; + + +// ComponentData message aggregates multiple metrics, operational states, and +// errors, related to a specific microgrid component. +// +// !!! example +// Example output structure: +// ``` +// { +// "metric_samples": [ +// { +// "metric": "DC_VOLTAGE_V", +// "value": { +// "simple_metric": { +// "sampled_at": "2023-10-19T14:15:22.123456789Z", +// "value": 48.2, +// "bounds": [{ "lower": 45.0, "upper": 50.0 }] +// } +// } +// }, +// { +// "metric": "DC_CURRENT_A", +// "value": { +// "aggregated_metric": { +// "sampled_at": "2023-10-19T14:15:22.123456789Z", +// "avg_value": 10.2, +// "min_value": 9.8, +// "max_value": 10.6, +// "list_values": [9.8, 10.1, 10.6], +// "bounds": [ +// { "lower": -20.0, "upper": -5.0 }, +// { "lower": 5.0, "upper": 20.0 } +// ] +// } +// } +// } +// ], +// "states": [ +// { +// "sampled_at": "2023-10-19T14:15:22.123456789Z", +// "state": ["COMPONENT_STATE_CHARGING"], +// "errors": [] +// }, +// { +// "sampled_at": "2023-10-19T14:00:00.000000000Z", +// "state": ["COMPONENT_STATE_ERROR"], +// "errors": ["COMPONENT_ERROR_CODE_BATTERY_RELAY_ERROR"] +// } +// ] +// } +// ``` +message ComponentData { + // Representation of a sampled metric along with its value. + message MetricSample { + // The metric that was sampled. + frequenz.api.common.v1.metrics.Metric metric = 1; + + // The value of the sampled metric. + frequenz.api.common.v1.metrics.MetricSampleVariant sample = 2; + } + + // Representation of a component state and errors. + message State { + // The time at which the state was sampled. + google.protobuf.Timestamp sampled_at = 1; + + // List if states of the microgrid component. + // + // !!! note + // The list will contain unique members. No state will exist twice in + // this list. + repeated ComponentState states = 2; + + // List of errors for the microgrid component. + // + // !!! note + // The list of errors is supposed to be populated only if the component + // is in an error state. + // + // !!! note + // The list will contain unique members. No error will exist twice in + // this list. + repeated ComponentError errors = 4; + } + + // List of measurements for a metric of the specific microgrid component. + repeated MetricSample metric_samples = 1; + + // List of states of a specific microgrid component. + repeated State states = 2; +} + +// Enum to represent the various states that a component can be in. +// This enum is unified across all component categories for consistency. +enum ComponentState { + // Default value when the component state is not explicitly set. + // This is the zero value of the enum. + COMPONENT_STATE_UNSPECIFIED = 0; + + // State when the component is in an unknown or undefined condition. + // This is used when the sender is unable to classify the component into any + // other state. + COMPONENT_STATE_UNKNOWN = 1; + + // State when the component is temporarily unavailable for operation. + COMPONENT_STATE_UNAVAILABLE = 2; + + // State when the component is in the process of switching off. + COMPONENT_STATE_SWITCHING_OFF = 3; + + // State when the component has successfully switched off. + COMPONENT_STATE_OFF = 4; + + // State when the component is in the process of switching on from an off + // state. + COMPONENT_STATE_SWITCHING_ON = 5; + + // State when the component is in standby mode, and not immediately ready for + // immediate operations. + COMPONENT_STATE_STANDBY = 6; + + // State when the component is fully operational and ready for use. + COMPONENT_STATE_READY = 7; + + // State when the component is actively consuming energy. + COMPONENT_STATE_CHARGING = 8; + + // State when the component is actively producing or releasing energy. + COMPONENT_STATE_DISCHARGING = 9; + + // State when the component is in an error state and may need attention. + COMPONENT_STATE_ERROR = 10; + + // The Electric Vehicle (EV) charging cable is unplugged from the charging + // station. + COMPONENT_STATE_EV_CHARGING_CABLE_UNPLUGGED = 20; + + // The EV charging cable is plugged into the charging station. + COMPONENT_STATE_EV_CHARGING_CABLE_PLUGGED_AT_STATION = 21; + + // The EV charging cable is plugged into the vehicle. + COMPONENT_STATE_EV_CHARGING_CABLE_PLUGGED_AT_EV = 22; + + // The EV charging cable is locked at the charging station end, indicating + // readiness for charging. + COMPONENT_STATE_EV_CHARGING_CABLE_LOCKED_AT_STATION = 23; + + // The EV charging cable is locked at the vehicle end, indicating that + // charging is active. + COMPONENT_STATE_EV_CHARGING_CABLE_LOCKED_AT_EV = 24; + + // The relay is in an open state, meaning no current can flow through. + COMPONENT_STATE_RELAY_OPEN = 30; + + // The relay is in a closed state, allowing current to flow. + COMPONENT_STATE_RELAY_CLOSED = 31; + + // The precharger circuit is open, meaning it's not currently active. + COMPONENT_STATE_PRECHARGER_OPEN = 40; + + // The precharger is in a precharging state, preparing the main circuit for + // activation. + COMPONENT_STATE_PRECHARGER_PRECHARGING = 41; + + // The precharger circuit is closed, allowing full current to flow to the main + // circuit. + COMPONENT_STATE_PRECHARGER_CLOSED = 42; +} + +// A representation of all possible errors that can occur across all component +// categories. +enum ComponentErrorCode { + // Default value. No specific error is specified. + COMPONENT_ERROR_CODE_UNSPECIFIED = 0; + + // The component is reporting an unknown or an undefined error, and the sender + // cannot parse the component error to any of the variants below. + COMPONENT_ERROR_CODE_UNKNOWN = 1; + + // Error indicating that the component could not be switched on. + COMPONENT_ERROR_CODE_SWITCH_ON_FAULT = 2; + + // Error indicating that the component is operating under the minimum rated + // voltage. + COMPONENT_ERROR_CODE_UNDERVOLTAGE = 3; + + // Error indicating that the component is operating over the maximum rated + // voltage. + COMPONENT_ERROR_CODE_OVERVOLTAGE = 4; + + // Error indicating that the component is drawing more current than the + // maximum rated value. + COMPONENT_ERROR_CODE_OVERCURRENT = 5; + + // Error indicating that the component's consumption current is over the + // maximum rated value during charging. + COMPONENT_ERROR_CODE_OVERCURRENT_CHARGING = 6; + + // Error indicating that the component's production current is over the + // maximum rated value during discharging. + COMPONENT_ERROR_CODE_OVERCURRENT_DISCHARGING = 7; + + // Error indicating that the component is operating over the maximum rated + // temperature. + COMPONENT_ERROR_CODE_OVERTEMPERATURE = 8; + + // Error indicating that the component is operating under the minimum rated + // temperature. + COMPONENT_ERROR_CODE_UNDERTEMPERATURE = 9; + + // Error indicating that the component is exposed to high humidity levels over + // the maximum rated value. + COMPONENT_ERROR_CODE_HIGH_HUMIDITY = 10; + + // Error indicating that the component's fuse has blown. + COMPONENT_ERROR_CODE_FUSE_ERROR = 11; + + // Error indicating that the component's precharge unit has failed. + COMPONENT_ERROR_CODE_PRECHARGE_ERROR = 12; + + // Error indicating plausibility issues within the system involving this + // component. + COMPONENT_ERROR_CODE_PLAUSIBILITY_ERROR = 13; + + // Error indicating system shutdown due to undervoltage involving this + // component. + COMPONENT_ERROR_CODE_UNDERVOLTAGE_SHUTDOWN = 14; + + // Error indicating unexpected pilot failure in an electric vehicle (EV) + // component. + COMPONENT_ERROR_CODE_EV_UNEXPECTED_PILOT_FAILURE = 15; + + // Error indicating fault current detected in the component. + COMPONENT_ERROR_CODE_FAULT_CURRENT = 16; + + // Error indicating a short circuit detected in the component. + COMPONENT_ERROR_CODE_SHORT_CIRCUIT = 17; + + // Error indicating a configuration error related to the component. + COMPONENT_ERROR_CODE_CONFIG_ERROR = 18; + + // Error indicating an illegal state requested for the component. + COMPONENT_ERROR_CODE_ILLEGAL_COMPONENT_STATE_REQUESTED = 19; + + // Error indicating that the hardware of the component is inaccessible. + COMPONENT_ERROR_CODE_HARDWARE_INACCESSIBLE = 20; + + // Error indicating an internal error within the component. + COMPONENT_ERROR_CODE_INTERNAL = 21; + + // Error indicating that the component is unauthorized to perform the + // last requested action. + COMPONENT_ERROR_CODE_UNAUTHORIZED = 22; + + // Error indicating electric vehicle (EV) cable was abruptly unplugged from + // the charging station. + COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION = 40; + + // Error indicating electric vehicle (EV) cable was abruptly unplugged from + // the vehicle. + COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_EV = 41; + + // Error indicating electric vehicle (EV) cable lock failure. + COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_LOCK_FAILED = 42; + + // Error indicating an invalid electric vehicle (EV) cable. + COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_INVALID = 43; + + // Error indicating an incompatible electric vehicle (EV) plug. + COMPONENT_ERROR_CODE_EV_CONSUMER_INCOMPATIBLE = 44; + + // Error indicating a battery system imbalance. + COMPONENT_ERROR_CODE_BATTERY_IMBALANCE = 50; + + // Error indicating a low state of health (SOH) detected in the battery. + COMPONENT_ERROR_CODE_BATTERY_LOW_SOH = 51; + + // Error indicating a battery block error. + COMPONENT_ERROR_CODE_BATTERY_BLOCK_ERROR = 52; + + // Error indicating a battery controller error. + COMPONENT_ERROR_CODE_BATTERY_CONTROLLER_ERROR = 53; + + // Error indicating a battery relay error. + COMPONENT_ERROR_CODE_BATTERY_RELAY_ERROR = 54; + + // Error indicating that battery calibration is needed. + COMPONENT_ERROR_CODE_BATTERY_CALIBRATION_NEEDED = 56; + + // Error indicating that the relays have been cycled for the maximum number of + // times. + COMPONENT_ERROR_CODE_RELAY_CYCLE_LIMIT_REACHED = 60; +} + +// A representation of all possible error levels that an error can have. +enum ErrorLevel { + // Default value. No specific error-level is specified. + ERROR_LEVEL_UNSPECIFIED = 0; + + // The associated error is a warning. + // Users are advised to take action to prevent the error from becoming + // critical. + ERROR_LEVEL_WARN = 1; + + // The associated error is critical. + // The associated component is very likely out-of-order, and needs immediate + // attention. + ERROR_LEVEL_CRITICAL = 2; +} + +// ComponentError message represents an error that occurred in a microgrid +// component. +message ComponentError { + // The error code. + ComponentErrorCode code = 1; + + // THe error level, indicating if it is a warning or a critical error + ErrorLevel level = 2; +} diff --git a/py/frequenz/api/common/v1/components/__init__.py b/py/frequenz/api/common/v1/components/__init__.py new file mode 100644 index 00000000..8301a69d --- /dev/null +++ b/py/frequenz/api/common/v1/components/__init__.py @@ -0,0 +1,4 @@ +# License: MIT +# Copyright © 2023 Frequenz Energy-as-a-Service GmbH + +"""Frequenz Common API definitions for metrics."""