Expose grid connection limits

[leandro-lucarella-frequenz]

We need to add a way to allow users to know the grid connection limits.

The base concept comes from the fact that a grid connection has a fuse, and we should avoid blowing that fuse.

The microgrid API already defines a COMPONENT_CATEGORY_GRID, so we probably should define a frequenz.sdk.microgrid.component.Grid class.

We should probably provide an abstraction at the level of the logical meter and *pools, so frequenz.sdk.microgrid.grid_connection maybe, and that should probably have a fuse attribute, which should have a max_current attribute for now.

So the end-user interface should be something like:

from frequenz.sdk import microgrid
max_current_receiver = microgrogrid.grid_connection.fuse.max_current.new_receiver()

Questions:

1. The Grid class should probably have a max_current attribute.
   The Grid class should be the one-to-one representation of what comes from the microgrid API. It shouldn't be normally exposed to the user unless they want to interact with the microgrid API directly.

   • Are there any other limits we need to expose? (max_power or anything else)
     Maybe in the future, but as long as we have the interface right it should be easy to add in the future.
   • Does it have only one phase or should we expose this for multiple phases?
     Only one value for now, as it is the fuse max current (it is an absolute value).

2. There should probably only be only one instance of a Grid object. It sounds like this should be initialized by the SDK and exposed like with logical_meter or battery_pool, so...

   • Should we have a singleton instance accessible through frequenz.sdk.microgrid.grid?
     YES, so it won't be an instance of the Grid object but another, higher-level, abstraction.

3. How often do these limits change?
   Only when the fuse is replaced, so it is a very low frequency change.

4. Do we need a task to keep this instance updated?
   No, the Grid object will be dumb and just a representation of what comes from the API. We will offer a channel-based interface like we do with the logical meter.

5. Should this instance provide a direct interface or a channel based interface? (this is probably tied to how often it changes and if users are expected to subscribe to changes or if they will just query the current value when they need it.
   See above.

   • So grid.max_current is a float with the value? (for this we could just expose the frequenz.sdk.microgrid.component.Grid instance in frequenz.sdk.microgrid.grid, providing that we have an extra task that keeps it up to date)
   • Or should it provide a channel interface like logical_meter and battery pool, so users should get the value using grid.max_current.new_receiver()? (for this we would need a class that just uses frequenz.sdk.microgrid.component.Grid as mean to communicate to the microgrid API). In this case it might be better to call it frequenz.sdk.microgrid.grid_connection?

Coming from:

• Report grid connection point's current limit frequenz-api-microgrid#19

[thomas-nicolai-frequenz]

Are there any other limits we need to expose

not that I can think of @tiyash-basu-frequenz

[thomas-nicolai-frequenz]

Well, I tend to agree but right now we are talking about the max fuse limit of the grid connection itself. Thus I wonder if we should rename the parameter to include the term fuse. But I had the same thoughts on the grid consumption vs. production thing.

[tiyash-basu-frequenz]

Noted.

The Microgrid API is now supposed to call it max_grid_fuse_current according to the discussion here.

[leandro-lucarella-frequenz]

OK, since this will be a property of a Grid object, I would call it max_fuse_current, or we could even make the fuse another object here, so grid.fuse.max_current.

[tiyash-basu-frequenz]

Could be useful to have it as an object for the future, since we are considering adding a fuse component category to the API.

[matthias-wende-frequenz]

+1 for voltage and frequency. Not urgent but different countries have different defaults!

[thomas-nicolai-frequenz]

How often do these limits change?

Whenever someone entered a wrong value or did not yet provide a value or the grid connection has been extended. However, any change has to be picked up and exposed.

Do we need a task to keep this instance updated?

of course.

[tiyash-basu-frequenz]

How often do these limits change?

Whenever someone entered a wrong value or did not yet provide a value or the grid connection has been extended. However, any change has to be picked up and exposed.

Exactly. This is not a dynamic bound, but something that is a constant property of a fuse. This will change only if the fuse changes, and for that the installers/admins need to update the UI. Then cloud-sync will pick it up and update the nitrogen API endpoint to reflect the latest value.

This raises the question: how often do we want to pull this limit via cloud-sync? ATM the default is 60s, but given its criticality, we should increase this frequency to at least 10s. Alongside pulling from the UI, we could also look into pushing this limit from the UI to the edge.

[thomas-nicolai-frequenz]

how often do we want to pull this limit via cloud-sync? ATM the default is 60s

I think thats OK. A fuse change isn't any easy thing and once we have a stream in place this question will anyhow be gone for good.

[thomas-nicolai-frequenz]

Should this instance provide a direct interface or a channel based interface

most likely the PowerManager will be the main consumer of that limitation but other actors might need it too. So it "feels" more like a channel tbh.

[leandro-lucarella-frequenz]

it doesn't make any sense to provide a streaming interface to it

I agree, it is much lighter to just have a method.

IMHO if it can change without restarting the microgrid (i.e. re-initializing the SDK), then we should provide a streaming interface, as users should be notified of grid connection limits updates as soon as possible. If we make it a value (or a function call), then the user has not way to know when it changes.

If we need to restart the microgrid when the fuse changes (i.e. re-initialize the SDK), then we can just provide a value, that is loaded at SDK initialization and will be a constant throughout the live of the SDK/Apps.

[tiyash-basu-frequenz]

things there could change without needing to restart the whole microgrid?

No. At least not now.

The metadata returned here could change only if
a. the grid fuse limit changes, or
b. a new component gets added, or
c. an existing component gets removed.

All of these are fairly intrusive processes, and we restart the microgrid API when these happen.
We can look into streaming APIs for these in the future when we can do this without restarting the microgrid API service.

[leandro-lucarella-frequenz]

OK, so if we make this assumption, then things gets much easier and I wouldn't go for a streaming interface for any static data that can only change if the SDK is initialized. We can just retrieve this info during SDK initialization and make it available as a plain value and that's it.

[leandro-lucarella-frequenz]

@thomas-nicolai-frequenz can you confirm this is OK? If we agree on this I will update the description.

[thomas-nicolai-frequenz]

OK, so if we make this assumption, then things gets much easier and I wouldn't go for a streaming interface for any static data that can only change if the SDK is initialized.

I would suggest to implement a polling interface in the SDK tbh. This information can change and restarting the container isn't an route we should go down at all.

[leandro-lucarella-frequenz]

I updated the discussion text with the results of the current comments. @sahas-subramanian-frequenz it would be good to know your opinion here too, specially in terms of the channel-based interface.

[tiyash-basu-frequenz]

Only one value for now, as it is the fuse max current (it is an absolute value).

Right, and the same value will apply to all the three phases individually.

[leandro-lucarella-frequenz]

The PR introducing the fuse now has 3 phases, I'm not sure if I misunderstood this or if the PR is already outdated :D

• frequenz-floss/frequenz-api-microgrid@ca41154

@tiyash-basu-frequenz ?

[tiyash-basu-frequenz]

I am currently waiting for Niklas' input on this.

[thomas-nicolai-frequenz]

@tiyash-basu-frequenz no this doesn't make sense for a very simple reason: remember with the ev actor how Schulz switched the phases between inverters and thats even part of the VDE norm and thus no one knows whats connected to which phase. Thus the limit will always be the same for all three phases. there will never be an individual limit for each phase. It simply doesn't make sense and ignores reality on the ground.

[thomas-nicolai-frequenz]

There is no way knowing how and where the phases have been rotated in any given electrical installation.

[thomas-nicolai-frequenz]

Thus, the default hypothesis shall be that all phases have the same limits until anyone comes around and tell us the opposite. Until then we keep moving with that hypothesis to unblock the progress here.

[leandro-lucarella-frequenz]

To summarize the latest events and the merging of the changes in the microgrid API, this is what I propose to add to the SDK:

from frequenz.sdk import microgrid
max_current = microgrogrid.grid_connection.fuse_rate_current

Where microgrogrid.grid_connection.fuse_rate_current is queried and set once when the SDK is initialized and never changed (changes in the fuse will require a restart of the App/SDK, for now).

We could also add some utility methods for checking a current value is within the accepted limits. We could accept Sample and 3PhaseSample in this method too, for extra convenience:

if not microgrid.grid_connection.is_current_within_bounds(10):
    scream()
if not microgrid.grid_connection.is_current_within_bounds(sample):
    scream()
# With 3 phases
if not microgrid.grid_connection.is_current_within_bounds(10, 23, 12):
    scream()
tuple_3_phase = (10, 23, 12)
if not microgrid.grid_connection.is_current_within_bounds(*tuple_3_phase):
    scream()
if not microgrid.grid_connection.is_current_within_bounds(sample_3_phase):
    scream()

So the user doesn't have to think in low level terms, if the fuse rate applies to one phase or all of them...

Does this look good? @tiyash-basu-frequenz, @thomas-nicolai-frequenz , @sahas-subramanian-frequenz

[thomas-nicolai-frequenz]

If the actors will check the limit before performing an operation, then the interface doesn't need to be a stream, we just need to have a task and keep the rated_fuse_current updated

Ah I see. Well I guess the PowerArbitrator would check that.

[thomas-nicolai-frequenz]

I think supporting live component graph changes in general should be its own milestone and probably post v1.0, as it is a big topic in itself.

agreed.

[leandro-lucarella-frequenz]

Good, so since the PowerArbitrator will check the value only before performing an operation, we can have a non-streaming interface and a static value for now. In the future we can add a task to poll the microgrid API to keep it updated, so the PowerArbitrator (or anyone else that need to check it out) always see an updated value.

[leandro-lucarella-frequenz]

Closing again then, please reopen if I misunderstood.

[leandro-lucarella-frequenz]

Updated the issue to clarify things a bit more.

[leandro-lucarella-frequenz]

OK, I created an issue based on this discussion. Closing.

• Expose grid connection limits #360

[leandro-lucarella-frequenz]

Reopening because of #322 (reply in thread)