WIP

Author: llucax

src/frequenz/client/microgrid/__init__.py

@@ -11,6 +11,7 @@
     DEFAULT_CHANNEL_OPTIONS,
     DEFAULT_GRPC_CALL_TIMEOUT,
     MicrogridApiClient,
+    Validity,
 )
 from ._delivery_area import DeliveryArea, EnergyMarketCodeType
 from ._exception import (
@@ -73,4 +74,5 @@
     "ServiceUnavailable",
     "UnknownError",
     "UnrecognizedGrpcStatus",
+    "Validity",
 ]

src/frequenz/client/microgrid/_client.py

@@ -5,13 +5,14 @@
 
 from __future__ import annotations
 
+import enum
 import math
 from collections.abc import Iterable
 from dataclasses import replace
 from datetime import datetime, timedelta
 from typing import assert_never
 
-from frequenz.api.common.v1.metrics import metric_sample_pb2
+from frequenz.api.common.v1.metrics import bounds_pb2, metric_sample_pb2
 from frequenz.api.common.v1.microgrid.components import components_pb2
 from frequenz.api.microgrid.v1 import microgrid_pb2, microgrid_pb2_grpc
 from frequenz.channels import Receiver
@@ -30,6 +31,7 @@
 from .component._connection_proto import component_connection_from_proto
 from .component._data_samples import ComponentDataSamples
 from .component._data_samples_proto import component_data_sample_from_proto
+from .metrics._bounds import Bounds
 from .metrics._metric import Metric
 
 DEFAULT_GRPC_CALL_TIMEOUT = 60.0
@@ -285,7 +287,7 @@ async def set_component_power_active(  # noqa: DOC502 (raises ApiClientError ind
 
         Returns:
             The timestamp until which the given power command will stay in effect, or
-                `None` if it was not provided.
+                `None` if it was not provided by the server.
 
         Raises:
             ApiClientError: If the are any errors communicating with the Microgrid API,
@@ -368,7 +370,7 @@ async def set_component_power_reactive(  # noqa: DOC502 (raises ApiClientError i
 
         Returns:
             The timestamp until which the given power command will stay in effect, or
-                `None` if it was not provided.
+                `None` if it was not provided by the server.
 
         Raises:
             ApiClientError: If the are any errors communicating with the Microgrid API,
@@ -398,6 +400,103 @@ async def set_component_power_reactive(  # noqa: DOC502 (raises ApiClientError i
 
         return None
 
+    async def add_component_bounds(  # noqa: DOC502 (Raises ApiClientError indirectly)
+        self,
+        component: ComponentId | Component,
+        target: Metric | int,
+        bounds: Iterable[Bounds],
+        *,
+        validity: Validity | None = None,
+    ) -> datetime | None:
+        """Add inclusion bounds for a given metric of a given component.
+
+        The bounds are used to define the acceptable range of values for a metric
+        of a component. The added bounds are kept only temporarily, and removed
+        automatically after some expiry time.
+
+        Inclusion bounds give the range that the system will try to keep the
+        metric within. If the metric goes outside of these bounds, the system will
+        try to bring it back within the bounds.
+        If the bounds for a metric are `[[lower_1, upper_1], [lower_2, upper_2]]`,
+        then this metric's `value` needs to comply with the constraints `lower_1 <=
+        value <= upper_1` OR `lower_2 <= value <= upper_2`.
+
+        If multiple inclusion bounds have been provided for a metric, then the
+        overlapping bounds are merged into a single bound, and non-overlapping
+        bounds are kept separate.
+
+        Example:
+            If the bounds are [[0, 10], [5, 15], [20, 30]], then the resulting bounds
+            will be [[0, 15], [20, 30]].
+
+            The following diagram illustrates how bounds are applied:
+
+            ```
+              lower_1  upper_1
+            <----|========|--------|========|-------->
+                                lower_2  upper_2
+            ```
+
+            The bounds in this example are `[[lower_1, upper_1], [lower_2, upper_2]]`.
+
+            ```
+            ---- values here are considered out of range.
+            ==== values here are considered within range.
+            ```
+
+        Note:
+            For power metrics, regardless of the bounds, 0W is always allowed.
+
+        Args:
+            component: The component to add bounds to.
+            target: The target metric whose bounds have to be added.
+            bounds: The bounds to add to the target metric. Overlapping pairs of bounds
+                are merged into a single pair of bounds, and non-overlapping ones are
+                kept separated.
+            validity: The duration for which the given bounds will stay in effect.
+                If `None`, then the bounds will be removed after some default time
+                decided by the server, typically 5 seconds.
+
+                The duration for which the bounds are valid. If not provided, the
+                bounds are considered to be valid indefinitely.
+
+        Returns:
+            The timestamp until which the given bounds will stay in effect, or `None` if
+                if it was not provided by the server.
+
+        Raises:
+            ApiClientError: If the are any errors communicating with the Microgrid API,
+                most likely a subclass of
+                [GrpcError][frequenz.client.microgrid.GrpcError].
+        """
+        extra_args = {}
+        if validity is not None:
+            extra_args["validity_duration"] = validity.value
+        response = await client.call_stub_method(
+            self,
+            lambda: self.stub.AddComponentBounds(
+                microgrid_pb2.AddComponentBoundsRequest(
+                    component_id=_get_component_id(component),
+                    target_metric=_get_metric_value(target),
+                    bounds=(
+                        bounds_pb2.Bounds(
+                            lower=bounds.lower,
+                            upper=bounds.upper,
+                        )
+                        for bounds in bounds
+                    ),
+                    **extra_args,
+                ),
+                timeout=int(DEFAULT_GRPC_CALL_TIMEOUT),
+            ),
+            method_name="AddComponentBounds",
+        )
+
+        if response.HasField("ts"):
+            return conversion.to_datetime(response.ts)
+
+        return None
+
     # noqa: DOC502 (Raises ApiClientError indirectly)
     async def receive_component_data_samples_stream(
         self,
@@ -461,6 +560,30 @@ async def receive_component_data_samples_stream(
         return broadcaster.new_receiver(maxsize=buffer_size)
 
 
+class Validity(enum.Enum):
+    """The duration for which a given list of bounds will stay in effect."""
+
+    FIVE_SECONDS = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_5_SECONDS
+    )
+    """The bounds will stay in effect for 5 seconds."""
+
+    ONE_MINUTE = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_1_MINUTE
+    )
+    """The bounds will stay in effect for 1 minute."""
+
+    FIVE_MINUTES = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_5_MINUTES
+    )
+    """The bounds will stay in effect for 5 minutes."""
+
+    FIFTEEN_MINUTES = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_15_MINUTES
+    )
+    """The bounds will stay in effect for 15 minutes."""
+
+
 def _get_component_id(component: ComponentId | Component) -> int:
     """Get the component ID from a component or component ID."""
     match component:

src/frequenz/client/microgrid/component/__init__.py

@@ -15,7 +15,12 @@
 )
 from ._category import ComponentCategory
 from ._chp import Chp
-from ._component import ComponentTypes
+from ._component import (
+    ComponentTypes,
+    ProblematicComponentTypes,
+    UnrecognizedComponentTypes,
+    UnspecifiedComponentTypes,
+)
 from ._connection import ComponentConnection
 from ._converter import Converter
 from ._crypto_miner import CryptoMiner
@@ -48,7 +53,6 @@
 from ._problematic import (
     MismatchedCategoryComponent,
     ProblematicComponent,
-    ProblematicComponentTypes,
     UnrecognizedComponent,
     UnspecifiedComponent,
 )
@@ -98,10 +102,12 @@
     "SolarInverter",
     "UnrecognizedBattery",
     "UnrecognizedComponent",
+    "UnrecognizedComponentTypes",
     "UnrecognizedEvCharger",
     "UnrecognizedInverter",
     "UnspecifiedBattery",
     "UnspecifiedComponent",
+    "UnspecifiedComponentTypes",
     "UnspecifiedEvCharger",
     "UnspecifiedInverter",
     "VoltageTransformer",

src/frequenz/client/microgrid/component/_base.py

@@ -5,6 +5,7 @@
 
 import dataclasses
 import logging
+from collections.abc import Mapping
 from functools import cached_property
 from typing import Any, Self
 
@@ -28,27 +29,68 @@ class Component:  # pylint: disable=too-many-instance-attributes
     microgrid_id: MicrogridId
     """The ID of the microgrid this component belongs to."""
 
-    name: str | None
-    """The name of this component."""
-
     category: ComponentCategory | int
-    """The category of this component."""
+    """The category of this component.
+
+    Note:
+        This should not be used normally, you should test if a component
+        [`isinstance`][] of a concrete component class instead.
+
+        It is only provided for using with a newer version of the API where the client
+        doesn't know about a new category yet (i.e. for use with
+        [`UnrecognizedComponent`][frequenz.client.microgrid.component.UnrecognizedComponent])
+        and in case some low level code needs to know the category of a component.
+        """
+
+    status: ComponentStatus | int = ComponentStatus.ACTIVE
+    """The status of this component.
 
-    manufacturer: str | None
+    Note:
+        This should not be used normally, you should test if a component is active
+        by checking the [`active`][frequenz.client.microgrid.component.Component.active]
+        property instead.
+    """
+
+    name: str | None = None
+    """The name of this component."""
+
+    manufacturer: str | None = None
     """The manufacturer of this component."""
 
-    model_name: str | None
+    model_name: str | None = None
     """The model name of this component."""
 
-    status: ComponentStatus | int
-    """The status of this component."""
-
-    operational_lifetime: Lifetime
+    operational_lifetime: Lifetime = dataclasses.field(default_factory=Lifetime)
     """The operational lifetime of this component."""
 
-    rated_bounds: dict[Metric | int, Bounds]
+    rated_bounds: Mapping[Metric | int, Bounds] = dataclasses.field(
+        default_factory=dict,
+        # dict is not hashable, so we don't use this field to calculate the hash. This
+        # shouldn't be a problem since it is very unlikely that two components with all
+        # other attributes being equal would have different category specific metadata,
+        # so hash collisions should be still very unlikely.
+        # TODO: Test hashing components
+        hash=False,
+    )
     """List of rated bounds present for the component identified by Metric."""
 
+    category_specific_metadata: Mapping[str, Any] = dataclasses.field(
+        default_factory=dict,
+        # dict is not hashable, so we don't use this field to calculate the hash. This
+        # shouldn't be a problem since it is very unlikely that two components with all
+        # other attributes being equal would have different category specific metadata,
+        # so hash collisions should be still very unlikely.
+        hash=False,
+    )
+    """The category specific metadata of this component.
+
+    Note:
+        This should not be used normally, it is only useful when accessing a newer
+        version of the API where the client doesn't know about the new metadata fields
+        yet (i.e. for use with
+        [`UnrecognizedComponent`][frequenz.client.microgrid.component.UnrecognizedComponent]).
+    """
+
     # pylint: disable-next=unused-argument
     def __new__(cls, *args: Any, **kwargs: Any) -> Self:
         """Prevent instantiation of this class."""