diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index ed9c34d4..0843aa88 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -37,6 +37,7 @@ - Renamed `sampled_at` timestamps for metric samples to `sample_time`. - Remove `SensorMetricSample` in favour of using `MetricSample` for sensors. - Remove `SensorMetric` enum, since it was unused and redundant. +- Renamed `MetricSample.source` to `MetricSample.connection` to make it more specific as to what it refers to. ## Bug Fixes diff --git a/proto/frequenz/api/common/v1/metrics/metrics.proto b/proto/frequenz/api/common/v1/metrics/metrics.proto index cea6e14d..a45edcc7 100644 --- a/proto/frequenz/api/common/v1/metrics/metrics.proto +++ b/proto/frequenz/api/common/v1/metrics/metrics.proto @@ -222,19 +222,27 @@ message MetricSample { // ==== values here are allowed and will be accepted repeated Bounds bounds = 4; - // An optional string that can be used to identify the source of the metric. + // An optional 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 sensors in the component. Knowing the source of the - // metric can help in certain control and monitoring applications. + // 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. // - // E.g., a hybrid inverter can have a DC string for a battery and another DC - // string for a PV array. The source names could resemble, say, - // `dc_battery_0` and ``dc_pv_0`. A metric like DC voltage can be obtained - // from both sources. For an application to determine the SoC of the battery - // using the battery voltage, the source of the voltage metric is important. + // E.g., + // - A PV inverter might have multiple PV strings connected (e.g., + // `pv_string_1`, `pv_string_2`). + // - A hybrid inverter can have a DC connection for a battery (e.g., + // `dc_battery_0`) and another for a PV array (e.g., `dc_pv_0`). A metric + // like DC voltage can be obtained from both connections. For an application + // 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`). // - // In cases where the component has just one source for a metric, then this - // field is not expected to be present, because the source is implicit. - optional string source = 5; + // 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; } diff --git a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto b/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto index 64bb5287..da306542 100644 --- a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto +++ b/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto @@ -528,12 +528,14 @@ message ElectricalComponentStateSnapshot { // metric: "DC_VOLTAGE_V", // value: {}, // bounds: {}, +// connection: "battery_0" // }, // { // sample_time: "2023-10-01T00:00:00Z", // metric: "DC_VOLTAGE_V", // value: {}, // bounds: {}, +// connection: "pv_0" // } // ], // states: [ diff --git a/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto b/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto index a73a2744..8bf5f64a 100644 --- a/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto +++ b/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto @@ -182,14 +182,14 @@ message SensorStateSnapshot { // metric: "METRIC_SENSOR_TEMPERATURE", // value: metric_value_variant: {simple_metric: {value: 23.5}, // bounds: {} -// source: {} +// connection: {} // }, // { // sample_time: "2023-10-01T00:00:00Z", // metric: "METRIC_SENSOR_RELATIVE_HUMIDITY", // value: metric_value_variant: {simple_metric: {value: 23.5}, // bounds: {} -// source: "humidity_sensor_1" +// connection: "humidity_sensor_1" // } // ], // states: [ @@ -206,6 +206,10 @@ message SensorData { uint64 sensor_id = 1; // List of measurements for a metric of the specific microgrid sensor. + // + // Note that these metric samples will not necessarily contain bounds, since + // bounds are required for control operations, which are not applicable to + // sensors. repeated frequenz.api.common.v1.metrics.MetricSample metric_samples = 2; // List of states of a specific microgrid sensor.