Skip to content

Expose grid connection limits #360

@leandro-lucarella-frequenz

Description

What's needed?

We need to expose the new microgrid grid connection rated fuse maximum current.

For now this limit can be static (queried from the microgrid API and kept immutable). A change in the grid connection limit will need a SDK restart. In the future we want to support dynamically changing this limit.

Proposed solution

Low-level

Add a new Component that wraps the Grid object and its metadata, as it is done with other microgrid components.

High-level

  1. Add an object to represent the GridConnection and a read-only rated fuse current property
  2. Add a global instance exposed via frequenz.sdk.microgrid.grid_connection
  3. Initialize the global instance in the initialize() function
    a. Until the new version of the microgrid API is deployed, just fill the instance fuse.current.rate with None

We should probably also add some utility methods for checking and adjusting a current value to the accepted limits. We could accept multiple current values so it is easy to use even with 3-phase samples.

class Current:

    rate: float | None

    def is_within_bounds(self, *current: float) -> bool:
        ...

    @overload
    def adjust(self, /, current: float) -> float:
        ...

    @overload
    def adjust(self, /, current1: float, current2: float, *extra_currents: float) -> list[float]:
        ...

    def adjust(self, *current: float) -> float | list[float]:
        """Truncate any current above the rated_fuse_current."""

class Fuse:

    current: Current

class GridConnection:

    fuse: Fuse

Use cases

Probably the PowerManager/PowerArbitrator (#161) or the should check these limits when applying charge/discharge commands, but others might as well, like the EVChargerPool might want to check the limit before increasing the bounds to allow vehicles to charge with high power.

Example usage:

from frequenz.sdk import microgrid

desired_current = 18.5
grid_fuse = microgrid.grid_connection.fuse
if not grid_fuse.current.is_within_bounds(desired_current):
    rate = grid_fuse.current.rate
    _logger.warning("The desired current ({desired_current}) is out of bounds (the fuse is rated {rate}). Will be adjusted.")
good_current = grid_fuse.current.adjust(desired_current)
_logger.info("Using current: {good_current}")

Alternatives and workarounds

No response

Additional context

Design discussion:

Future work:

  • Initialize with the proper microgrid API calls after the new microgrid API exposing the limit is deployed

  • Support dynamically changing this limit. There are 2 main approaches for this:

    • Streaming interface: This means we need a streaming interface from the microgrid API and we should make the rated_fuse_current a channel that streams changes in this property, like the battery_pool(), etc.
    • Polling: We just add a task to keep the fuse.current.rate updated by polling the microgrid API (or uses a streaming gRPC call if available).

    It seems like for now the polling interface should be enough.

Metadata

Metadata

Labels

part:microgridAffects the interactions with the microgridtype:enhancementNew feature or enhancement visitble to users

Type

No type

Projects

Status

Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions