frequenz-api-common 0.7.0__tar.gz → 0.8.0__tar.gz

{frequenz_api_common-0.7.0/py/frequenz_api_common.egg-info → frequenz_api_common-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-api-common
-Version: 0.7.0
+Version: 0.8.0
 Summary: Frequenz common gRPC API and bindings
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -22,7 +22,7 @@ License-File: LICENSE
 Requires-Dist: protobuf<8,>=6.31.1
 Requires-Dist: grpcio<2,>=1.72.1
 Provides-Extra: dev-flake8
-Requires-Dist: flake8==7.2.0; extra == "dev-flake8"
+Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
 Requires-Dist: flake8-pyproject==1.2.3; extra == "dev-flake8"
 Requires-Dist: pydoclint==0.6.6; extra == "dev-flake8"
@@ -34,11 +34,11 @@ Provides-Extra: dev-mkdocs
 Requires-Dist: mike==1.1.2; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-material==9.6.14; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.6.15; extra == "dev-mkdocs"
 Requires-Dist: mkdocstrings[python]==0.29.1; extra == "dev-mkdocs"
 Requires-Dist: frequenz-repo-config[api]==0.13.5; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
-Requires-Dist: mypy==1.16.0; extra == "dev-mypy"
+Requires-Dist: mypy==1.16.1; extra == "dev-mypy"
 Requires-Dist: grpc-stubs==1.53.0.6; extra == "dev-mypy"
 Requires-Dist: frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
@@ -48,7 +48,7 @@ Provides-Extra: dev-pylint
 Requires-Dist: pylint==3.3.7; extra == "dev-pylint"
 Requires-Dist: frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
-Requires-Dist: pytest==8.3.5; extra == "dev-pytest"
+Requires-Dist: pytest==8.4.1; extra == "dev-pytest"
 Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.5; extra == "dev-pytest"
 Provides-Extra: dev
 Requires-Dist: frequenz-api-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"

frequenz_api_common-0.8.0/RELEASE_NOTES.md

@@ -0,0 +1,35 @@
+# Frequenz Common API Release Notes
+
+## Summary
+
+This release introduces the new `v1alpha8` version of the API, which includes several breaking changes compared to `v1alpha7`. The changes focus on improving consistency and clarity by renaming several symbols and removing unused components.
+
+## Upgrading
+
+- A new package `frequenz.api.common.v1alpha8` has been introduced, containing the following breaking changes from `v1alpha7`.
+
+- Removed:
+
+    + `electrical_components.Fuse`
+    + `InverterType.INVERTER_TYPE_WIND_TURBINE`
+
+- Renamed several symbols to increase consistency and clarity:
+
+    + `microgrid`:
+
+        * `MicrogridComponentIds` to `MicrogridElectricalComponentIds`
+        * `MicrogridComponentIDs.component_ids` to `MicrogridElectricalComponentIds.electrical_component_ids`
+
+    + `electrical_components`:
+
+        * `ElectricalComponentConnections.source_component_id` to `ElectricalComponentConnections.source_electrical_component_id`
+        * `ElectricalComponentConnections.destination_component_id` to `ElectricalComponentConnections.destination_electrical_component_id`
+        * `ElectricalComponentStateSnapshot.component_id` to `ElectricalComponentStateSnapshot.electrical_component_id`
+        * Transformer-related terms are renamed to align them with power transformers, which are more commonly used in electrical engineering:
+            * `electrical_components.VoltageTransformer` to `electrical_components.PowerTransformer`
+            * `ElectricalComponentCategorySpecificInfo.kind.voltage_transformer` to `ElectricalComponentCategorySpecificInfo.kind.power_transformer`
+            * `ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER` to `ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_POWER_TRANSFORMER`
+
+    + `types`:
+
+        * The whole package has been renamed to `types` to avoid using reserved keywords in programming languages.

frequenz_api_common-0.8.0/proto/frequenz/api/common/v1alpha8/grid/delivery_area.proto

@@ -0,0 +1,62 @@
+// Frequenz definitions of grids as entities participating in trading.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+// CodeType specifies the type of identification code used for uniquely
+// identifying various entities such as delivery areas, market participants, and
+// grid components within the energy market. This enumeration aims to offer
+// compatibility across different jurisdictional standards.
+//
+// !!! note "Understanding Code Types"
+//     Different regions or countries may have their own standards for uniquely
+//     identifying various entities within the energy market. For example, in
+//     Europe, the Energy Identification Code (EIC) is commonly used for this
+//     purpose.
+//
+// !!! info "Extensibility"
+//     New code types can be added to this enum to accommodate additional
+//     regional standards, enhancing the API's adaptability.
+//
+// !!! caution "Validation Required"
+//     The chosen code type should correspond correctly with the `code` field in
+//     the relevant message objects, such as `DeliveryArea` or `Counterparty`.
+//     Failure to match the code type with the correct code could lead to
+//     processing errors.
+//
+enum EnergyMarketCodeType {
+  // Unspecified type. This value is a placeholder and should not be used.
+  ENERGY_MARKET_CODE_TYPE_UNSPECIFIED = 0;
+
+  // European Energy Identification Code Standard.
+  ENERGY_MARKET_CODE_TYPE_EUROPE_EIC = 1;
+
+  // North American Electric Reliability Corporation identifiers.
+  ENERGY_MARKET_CODE_TYPE_US_NERC = 2;
+}
+
+// DeliveryArea represents the geographical or administrative region, usually
+// defined and maintained by a Transmission System Operator (TSO), where
+// electricity deliveries for a contract occur.
+//
+// The concept is important to energy trading as it delineates the agreed-upon
+// delivery location. Delivery areas can have different codes based on the//
+// jurisdiction in which they operate.
+//
+// !!! note "Jurisdictional Differences"
+//     This is typically represented by specific codes according to local
+//     jurisdiction. In Europe, this is represented by an EIC
+//     (Energy Identification Code).
+message DeliveryArea {
+  // Code representing the unique identifier for the delivery area.
+  string code = 1;
+
+  // Type of code used for identifying the delivery area itself.
+  EnergyMarketCodeType code_type = 2;
+}

frequenz_api_common-0.8.0/proto/frequenz/api/common/v1alpha8/grid/delivery_duration.proto

@@ -0,0 +1,61 @@
+// Frequenz definitions of the time increment used for electricity
+// deliveries and trading.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+import "google/protobuf/timestamp.proto";
+
+// DeliveryDuration represents the time increment, in minutes,
+// used for electricity deliveries and trading. These durations
+// serve as the basis for defining the delivery period in contracts,
+// and they dictate how energy is scheduled and delivered to meet
+// contractual obligations.
+//
+// !!! note "Compatibility Constraints"
+//     Not all delivery durations are universally
+//     compatible with all delivery areas or markets.
+//
+enum DeliveryDuration {
+  // Default value, indicates that the duration is unspecified.
+  DELIVERY_DURATION_UNSPECIFIED = 0;
+
+  // 5-minute duration
+  DELIVERY_DURATION_5 = 1;
+
+  // 15-minute contract duration.
+  DELIVERY_DURATION_15 = 2;
+
+  // 30-minute contract duration.
+  DELIVERY_DURATION_30 = 3;
+
+  // 1-hour contract duration.
+  DELIVERY_DURATION_60 = 4;
+}
+
+// DeliveryPeriod represents the time period during which the contract
+// is delivered. It is defined by a start timestamp and a duration.
+message DeliveryPeriod {
+  // Start UTC timestamp represents the beginning of the delivery period.
+  // This timestamp is inclusive, meaning that the delivery period starts
+  // from this point in time.
+  //
+  // !!! note
+  //     Delivery period start time constraints:
+  //     - 5-minute durations must start at times that are multiples of
+  //       5 minutes past the hour.
+  //     - 15-minute durations must start at :00, :15, :30, or
+  //       :45 past the hour.
+  //     - 30-minute durations must start at :00 or :30 past the hour.
+  //     - 60-minute durations must start at :00 past the hour.
+  google.protobuf.Timestamp start = 1;
+
+  // The length of the delivery period.
+  DeliveryDuration duration = 2;
+}

frequenz_api_common-0.8.0/proto/frequenz/api/common/v1alpha8/market/energy.proto

@@ -0,0 +1,24 @@
+// Frequenz definitions of energy.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.market;
+
+import "frequenz/api/common/v1alpha8/types/decimal.proto";
+
+// Represents a single unit of electricity.
+//
+// !!! note
+//     The unit of energy is denominated in MWh, which is a unit of energy
+//     representing total output over a period.(Megawatt-hours). This differs
+//     from MW (Megawatts), a unit of power representing the rate of energy
+//     production or consumption.
+message Energy {
+  // Energy unit in Megawatthours (MWh).
+  frequenz.api.common.v1alpha8.types.Decimal mwh = 1;
+}

frequenz_api_common-0.8.0/proto/frequenz/api/common/v1alpha8/market/power.proto

@@ -0,0 +1,30 @@
+// Frequenz definitions of power.
+//
+// Copyright 2024 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.market;
+
+import "frequenz/api/common/v1alpha8/types/decimal.proto";
+
+// Represents a single unit of power.
+//
+// !!! note
+//     The power unit is denominated in MW (Megawatts), which is a unit of
+//     power representing the rate of energy production or consumption at any
+//     given moment. This differs from MWh (Megawatt-hours), which measures
+//     the total amount of energy delivered or consumed over a period.
+//
+// Example:
+//     A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
+//
+// This message standardizes the representation of power in MW across all
+// market applications.
+message Power {
+  // Power amount in Megawatts (MW).
+  frequenz.api.common.v1alpha8.types.Decimal mw = 1;
+}

frequenz_api_common-0.8.0/proto/frequenz/api/common/v1alpha8/market/price.proto

@@ -0,0 +1,53 @@
+// Frequenz definitions of price for electricity trading.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.market;
+
+import "frequenz/api/common/v1alpha8/types/decimal.proto";
+
+// Represents a monetary price for electricity trading, including
+// the amount and currency. The currency used should align with the
+// delivery area's standard currency.
+//
+// !!! caution "Validation Required"
+//     It's essential to ensure that the currency aligns with the
+//     standard currency of the associated delivery area. Failure to
+//     do so may result in the API service rejecting the request due to currency
+//     mismatches.
+//
+// !!! info "Relation to Delivery Area"
+//     The currency specified is intrinsically related to the delivery area
+//     for the contract. Make sure the chosen currency is compatible with
+//     the delivery area's currency standards.
+//
+message Price {
+  // List of supported currencies.
+  //
+  // !!! info "Extensibility"
+  //     New currencies can be added to this enum to support additional markets.
+  enum Currency {
+    CURRENCY_UNSPECIFIED = 0;
+    CURRENCY_USD = 1;
+    CURRENCY_CAD = 2;
+    CURRENCY_EUR = 3;
+    CURRENCY_GBP = 4;
+    CURRENCY_CHF = 5;
+    CURRENCY_CNY = 6;
+    CURRENCY_JPY = 7;
+    CURRENCY_AUD = 8;
+    CURRENCY_NZD = 9;
+    CURRENCY_SGD = 10;
+  }
+
+  // The amount of the price.
+  frequenz.api.common.v1alpha8.types.Decimal amount = 1;
+
+  // The currency in which the price is denominated.
+  Currency currency = 2;
+}

frequenz_api_common-0.8.0/proto/frequenz/api/common/v1alpha8/metrics/bounds.proto

@@ -0,0 +1,23 @@
+// Definitions for bounds.
+//
+// Copyright:
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.metrics;
+
+// 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 {
+  // The lower bound.
+  // If absent, there is no lower bound.
+  optional float lower = 1;
+
+  // The upper bound.
+  // If absent, there is no upper bound.
+  optional float upper = 2;
+}

frequenz_api_common-0.8.0/proto/frequenz/api/common/v1alpha8/metrics/metrics.proto

@@ -0,0 +1,302 @@
+// Metrics definitions.
+//
+// Copyright:
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.metrics;
+
+import "frequenz/api/common/v1alpha8/metrics/bounds.proto";
+
+import "google/protobuf/timestamp.proto";
+
+// Represents a single sample of a specific metric, the value of which is either
+// measured or derived at a particular time.
+message SimpleMetricValue {
+  // The value of the metric, which could be either measured or derived.
+  float value = 2;
+}
+
+// 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 are
+// are optional, accommodating scenarios where only subsets of this information
+// are available.
+message AggregatedMetricValue {
+  // The derived average value of the metric.
+  float avg_value = 2;
+
+  // The minimum measured value of the metric.
+  optional float min_value = 3;
+
+  // The maximum measured value of the metric.
+  optional float max_value = 4;
+
+  // Optional array of all the raw individual values.
+  repeated float raw_values = 5;
+}
+
+// `MetricValueVariant` serves as a union type that can encapsulate either a
+// `SimpleMetricValue` or an `AggregatedMetricValue`.
+//
+// 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 `MetricValueVariant` can hold either a `SimpleMetricValue` or an
+// `AggregatedMetricValue`, but not both simultaneously. Setting one will
+// nullify the other.
+message MetricValueVariant {
+  oneof metric_value_variant {
+    SimpleMetricValue simple_metric = 1;
+    AggregatedMetricValue aggregated_metric = 2;
+  }
+}
+
+// List of supported metrics.
+//
+// !!! note
+// AC energy metrics information:
+//
+// * This energy metric is reported directly from the component, and not a
+//  result of aggregations in our systems. If a component does not have this
+//  metric, this field cannot be populated.
+//
+//  * Components that provide energy metrics reset this metric from time to
+//  time. This behaviour is specific to each component model. E.g., some
+//  components reset it on UTC 00:00:00.
+//
+//  * This energy metric does not specify the timestamp since when the energy
+//  was being accumulated, and therefore can be inconsistent.
+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_N = 12;
+  METRIC_AC_VOLTAGE_PHASE_2_N = 13;
+  METRIC_AC_VOLTAGE_PHASE_3_N = 14;
+  METRIC_AC_VOLTAGE_PHASE_1_PHASE_2 = 15;
+  METRIC_AC_VOLTAGE_PHASE_2_PHASE_3 = 16;
+  METRIC_AC_VOLTAGE_PHASE_3_PHASE_1 = 17;
+  METRIC_AC_CURRENT = 18;
+  METRIC_AC_CURRENT_PHASE_1 = 19;
+  METRIC_AC_CURRENT_PHASE_2 = 20;
+  METRIC_AC_CURRENT_PHASE_3 = 21;
+
+  // AC power metrics
+  METRIC_AC_POWER_APPARENT = 22;
+  METRIC_AC_POWER_APPARENT_PHASE_1 = 23;
+  METRIC_AC_POWER_APPARENT_PHASE_2 = 24;
+  METRIC_AC_POWER_APPARENT_PHASE_3 = 25;
+  METRIC_AC_POWER_ACTIVE = 26;
+  METRIC_AC_POWER_ACTIVE_PHASE_1 = 27;
+  METRIC_AC_POWER_ACTIVE_PHASE_2 = 28;
+  METRIC_AC_POWER_ACTIVE_PHASE_3 = 29;
+  METRIC_AC_POWER_REACTIVE = 30;
+  METRIC_AC_POWER_REACTIVE_PHASE_1 = 31;
+  METRIC_AC_POWER_REACTIVE_PHASE_2 = 32;
+  METRIC_AC_POWER_REACTIVE_PHASE_3 = 33;
+
+  // 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_ENERGY_APPARENT = 50;
+  METRIC_AC_ENERGY_APPARENT_PHASE_1 = 51;
+  METRIC_AC_ENERGY_APPARENT_PHASE_2 = 52;
+  METRIC_AC_ENERGY_APPARENT_PHASE_3 = 53;
+  METRIC_AC_ENERGY_ACTIVE = 54;
+  METRIC_AC_ENERGY_ACTIVE_PHASE_1 = 55;
+  METRIC_AC_ENERGY_ACTIVE_PHASE_2 = 56;
+  METRIC_AC_ENERGY_ACTIVE_PHASE_3 = 57;
+  METRIC_AC_ENERGY_ACTIVE_CONSUMED = 58;
+  METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_1 = 59;
+  METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_2 = 60;
+  METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_3 = 61;
+  METRIC_AC_ENERGY_ACTIVE_DELIVERED = 62;
+  METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_1 = 63;
+  METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_2 = 64;
+  METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_3 = 65;
+  METRIC_AC_ENERGY_REACTIVE = 66;
+  METRIC_AC_ENERGY_REACTIVE_PHASE_1 = 67;
+  METRIC_AC_ENERGY_REACTIVE_PHASE_2 = 68;
+  METRIC_AC_ENERGY_REACTIVE_PHASE_3 = 69;
+
+  // AC harmonics
+  METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT = 80;
+  METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1 = 81;
+  METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2 = 82;
+  METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3 = 83;
+
+  // General BMS metrics.
+  METRIC_BATTERY_CAPACITY = 100;
+  METRIC_BATTERY_SOC_PCT = 101;
+  METRIC_BATTERY_TEMPERATURE = 102;
+
+  // General inverter metrics.
+  METRIC_INVERTER_TEMPERATURE = 120;
+  METRIC_INVERTER_TEMPERATURE_CABINET = 121;
+  METRIC_INVERTER_TEMPERATURE_HEATSINK = 122;
+  METRIC_INVERTER_TEMPERATURE_TRANSFORMER = 123;
+
+  // EV charging station metrics.
+  METRIC_EV_CHARGER_TEMPERATURE = 140;
+
+  // General sensor metrics
+  METRIC_SENSOR_WIND_SPEED = 160;
+  METRIC_SENSOR_WIND_DIRECTION = 161;
+  METRIC_SENSOR_TEMPERATURE = 162;
+  METRIC_SENSOR_RELATIVE_HUMIDITY = 163;
+  METRIC_SENSOR_DEW_POINT = 164;
+  METRIC_SENSOR_AIR_PRESSURE = 165;
+  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 PV (photovoltaic) array or string.
+  METRIC_CONNECTION_CATEGORY_PV = 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
+//     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
+//     ### Relationship Between Bounds and Metric Samples
+//     Suppose a metric sample for active power has a lower-bound of -10,000 W,
+//     and an upper-bound of 10,000 W. For the system to accept a charge
+//     command, clients need to request current values within the bounds.
+message MetricSample {
+  // The UTC timestamp of when the metric was sampled.
+  google.protobuf.Timestamp sample_time = 1;
+
+  // The metric that was sampled.
+  Metric metric = 2;
+
+  // The value of the sampled metric.
+  MetricValueVariant value = 3;
+
+  // List of bounds that apply to the metric sample.
+  //
+  // These bounds adapt in real-time to reflect the operating conditions at the
+  // time of aggregation or derivation.
+  //
+  // #### Multiple Bounds
+  //
+  // 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.
+  //
+  // #### Example
+  //
+  // The diagram below illustrates the relationship between the bounds.
+  // ```
+  //      bound[0].lower                         bound[1].upper
+  // <-------|============|------------------|============|--------->
+  //                bound[0].upper      bound[1].lower
+  // ```
+  // ---- values here are disallowed and will be rejected
+  // ==== values here are allowed and will be accepted
+  repeated Bounds bounds = 4;
+
+  // 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
+  // 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 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_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.
+  //
+  // !!! 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;
+}