diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 43b2a262..a86fcdee 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -73,6 +73,8 @@ - The file `location.proto` has been moved to the `types` package, moving the message `Location` to `types.Location`. +- The type of the field `metrics.MetricSample.connection` has been changed from `string` to `metrics.MetricConnection`. The latter is a newly added message that provides a better categorization of the connection type. + ## New Features Added many new messages and enum values: diff --git a/proto/frequenz/api/common/v1/metrics/metrics.proto b/proto/frequenz/api/common/v1/metrics/metrics.proto index e014e3a2..f8688f13 100644 --- a/proto/frequenz/api/common/v1/metrics/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics/metrics.proto @@ -172,6 +172,50 @@ enum Metric { METRIC_SENSOR_IRRADIANCE = 166; } +// Enumerated categories of connections from which metrics can be obtained for a +// given electrical component or sensor. +enum MetricConnectionCategory { + // Default value. + // Do not use this value. + METRIC_CONNECTION_CATEGORY_UNSPECIFIED = 0; + + // A generic connection for metrics that do not fit into any other category. + METRIC_CONNECTION_CATEGORY_OTHER = 1; + + // A connection to a metric representing a battery. + METRIC_CONNECTION_CATEGORY_BATTERY = 2; + + // A connection to a metric representing a photovoltaic (PV) array or string. + METRIC_CONNECTION_CATEGORY_PHOTOVOLTAIC = 3; + + // A connection to a metric representing ambient conditions. + METRIC_CONNECTION_CATEGORY_AMBIENT = 10; + + // A connection to a metric representing a cabinet or an enclosure. + METRIC_CONNECTION_CATEGORY_CABINET = 11; + + // A connection to a metric representing a heatsink. + METRIC_CONNECTION_CATEGORY_HEATSINK = 12; + + // A connection to a metric representing a transformer. + METRIC_CONNECTION_CATEGORY_TRANSFORMER = 13; +} + +// A connection to a metric representing from which a metric was obtained. +message MetricConnection { + // The category of the connection from which the metric was obtained. + MetricConnectionCategory category = 1; + + // A string that can be used to identify the specific connection from which + // the metric was obtained. + // + // This is expected to be populated when the same `Metric` variant can be + // obtained from multiple distinct inputs or connection points on the + // component. Knowing the connection for the metric can help in certain + // control and monitoring applications. + string name = 2; +} + // Representation of a sampled metric along with its value. // // !!! note @@ -222,7 +266,7 @@ message MetricSample { // ==== values here are allowed and will be accepted repeated Bounds bounds = 4; - // An optional string that can be used to identify the specific connection + // An optional field that can be used to identify the specific connection // from which the metric was obtained. // // This is expected to be populated when the same `Metric` variant can be @@ -239,10 +283,20 @@ message MetricSample { // to determine the SoC of the battery using its voltage, identifying the // `dc_battery_0` connection is important. // - A sensor unit might report temperature from different connected probes - // (e.g., `temp_sensor_outdoor`, `temp_sensor_indoor`). + // (e.g., `temp_sensor_outdoor`, `temp_sensor_transformer`). + // + // !!! note "Default Connection Behavior" + // If this field is unset, it is implicitly assumed that the component + // only has a single connection for this metric, and the connection is + // uniquely identified by the component itself. // - // In cases where the component has just one such connection for a metric, - // or the context is otherwise unambiguous, this field is not expected to - // be present, because the connection is implicit. - optional string connection = 5; + // !!! example + // ``` + // // DC power from battery string 0 in a hybrid inverter + // source { + // category: METRIC_CONNECTION_CATEGORY_BATTERY + // name: "dc_battery_0" + // } + // ``` + optional MetricConnection connection = 5; }