Skip to content

Add power-source selection for hybrid inverter controls #382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tiyash-basu-frequenz merged 1 commit into from
Mar 4, 2026
+120 −5
Merged

Add power-source selection for hybrid inverter controls #382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions RELEASE_NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,34 @@ The `v1` API remains unchanged to ensure backward compatibility. All new feature

The `v1` API is stable and has **not** been changed in this release. Users currently on `v1` do not need to make any changes, beyond potentially updating python dependencies as described below.

## Stable `v1alpha18` Preview API

The previous preview version, `v1alpha18`, is stable. It has the following symbol additions as compared to the `v1.18.0` release:

| Type | Name |
| :------ | :--------------------------------------------------------------------------------- |
| Enum | `frequenz.api.microgrid.v1alpha18.PowerSource` |
| Field | `frequenz.api.microgrid.v1alpha18.SetElectricalComponentPowerRequest.power_source` |

-----

## New `v1alpha19` Preview API

A new package, `frequenz.api.microgrid.v1alpha19`, has been introduced to provide access to the latest features. The `v1alpha19` API introduces a more streamlined and robust interface compared to the stable `v1` API.
A new package, `frequenz.api.microgrid.v1alpha19`, has been introduced to provide access to the latest features. The `v1alpha19` API introduces a more streamlined and robust interface compared to the stable `v1` API. It builds on top of `v1alpha18` and incorporates all of its additions, including those listed in the [Stable `v1alpha18` Preview API](#stable-v1alpha18-preview-api) section above.

-----

## Upgrading to the `v0.19.0` release

### 1. Dependency Updates

Despite the `v1` API remaining unchanged, your project's dependencies may need to be updated, due to the following python dependency updates:
Despite the `v1` or `v1alpha18` APIs remaining backward-compatible, your project's dependencies may need to be updated, due to python dependency updates.

-----

## Upgrading to the `v1alpha19` API

Alongside upgrading to the `v0.19.0` release, you can also upgrade to the new `v1alpha19` API, which includes several significant changes and improvements.
Alongside upgrading to the `v0.19.0` release, you can also upgrade to the new `v1alpha19` API, which includes several changes and improvements over the `v1` and `v1alpha18` packages.

-----

Expand Down
53 changes: 53 additions & 0 deletions proto/frequenz/api/microgrid/v1alpha18/microgrid.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -497,6 +497,44 @@ enum PowerType {
POWER_TYPE_REACTIVE = 2;
}

// Enumerated power sources for an electrical component when issuing discharge
// commands.
//
// This is needed only for discharge commands for hybrid inverters, which
// typically have both PV and battery inputs added to them, and can use either
// of those inputs as the power source.
enum PowerSource {
// Default value.
//
// When used, the API service will automatically select
// `POWER_SOURCE_PV_PREFERRED` as the power source.
POWER_SOURCE_UNSPECIFIED = 0;

// When only the PV arrays should be used as the energy source.
// Commands will return an error if:
// - the requested power exceeds the limits of the PV arrays, or
// - the hybrid inverter does not have PV arrays added to it.
POWER_SOURCE_PV_ONLY = 1;

// When the PV arrays should be used as the preferred energy source,
// with any remaining power demand drawn from batteries.
// Commands will return an error if the requested power exceeds the limits of
// the PV arrays and batteries combined.
POWER_SOURCE_PV_PREFERRED = 2;

// When the batteries should be used as the preferred energy source,
// with any remaining power demand drawn from PV arrays where available.
// Commands will return an error if the requested power exceeds the limits of
// the batteries and PV arrays combined.
POWER_SOURCE_BATTERY_PREFERRED = 3;

// When only the batteries should be used as the energy source.
// Commands will return an error if:
// - the requested power exceeds the limits of the batteries, or
// - the hybrid inverter does not have batteries added to it.
POWER_SOURCE_BATTERY_ONLY = 4;
}

// Response codes for the `SetElectricalComponentPowerActive` and
// `SetElectricalComponentPowerReactive` RPCs. These codes indicate the ongoing
// status of the request to set the power of an electrical component.
Expand Down Expand Up @@ -562,6 +600,21 @@ message SetElectricalComponentPowerRequest {
// The requested power type.
PowerType power_type = 2;

// The power source for the electrical component.
//
// This field is used only if the following criteria are all met:
// - the requested power type is active power,
// - the requested power is negative, indicating discharge, and
// - the target electrical component is a hybrid inverter.
//
// If the above criteria are met, and this field is not specified and allowed
// to default, then the API service will use `POWER_SOURCE_PV_PREFERRED` as
// the power source.
//
// If the above criteria are not met, the API service will ignore this field
// and automatically select the power source.
PowerSource power_source = 5;

// The requested power output.
//
// For Active power:
Expand Down
57 changes: 55 additions & 2 deletions proto/frequenz/api/microgrid/v1alpha19/microgrid.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -497,6 +497,44 @@ enum PowerType {
POWER_TYPE_REACTIVE = 2;
}

// Enumerated power sources for an electrical component when issuing discharge
// commands.
//
// This is needed only for discharge commands for hybrid inverters, which
// typically have both PV and battery inputs added to them, and can use either
// of those inputs as the power source.
enum PowerSource {
// Default value.
//
// When used, the API service will automatically select
// `POWER_SOURCE_PV_PREFERRED` as the power source.
POWER_SOURCE_UNSPECIFIED = 0;

// When only the PV arrays should be used as the energy source.
// Commands will return an error if:
// - the requested power exceeds the limits of the PV arrays, or
// - the hybrid inverter does not have PV arrays added to it.
POWER_SOURCE_PV_ONLY = 1;

// When the PV arrays should be used as the preferred energy source,
// with any remaining power demand drawn from batteries.
// Commands will return an error if the requested power exceeds the limits of
// the PV arrays and batteries combined.
POWER_SOURCE_PV_PREFERRED = 2;

// When the batteries should be used as the preferred energy source,
// with any remaining power demand drawn from PV arrays where available.
// Commands will return an error if the requested power exceeds the limits of
// the batteries and PV arrays combined.
POWER_SOURCE_BATTERY_PREFERRED = 3;

// When only the batteries should be used as the energy source.
// Commands will return an error if:
// - the requested power exceeds the limits of the batteries, or
// - the hybrid inverter does not have batteries added to it.
POWER_SOURCE_BATTERY_ONLY = 4;
}

// Response codes for the `SetElectricalComponentPowerActive` and
// `SetElectricalComponentPowerReactive` RPCs. These codes indicate the ongoing
// status of the request to set the power of an electrical component.
Expand Down Expand Up @@ -562,6 +600,21 @@ message SetElectricalComponentPowerRequest {
// The requested power type.
PowerType power_type = 2;

// The power source for the electrical component.
//
// This field is used only if the following criteria are all met:
// - the requested power type is active power,
// - the requested power is negative, indicating discharge, and
// - the target electrical component is a hybrid inverter.
//
// If the above criteria are met, and this field is not specified and allowed
// to default, then the API service will use `POWER_SOURCE_PV_PREFERRED` as
// the power source.
//
// If the above criteria are not met, the API service will ignore this field
// and automatically select the power source.
PowerSource power_source = 3;

// The requested power output.
//
// For Active power:
Expand All @@ -579,13 +632,13 @@ message SetElectricalComponentPowerRequest {
// - Positive values indicate inductive reactive power, i.e., the current
// is lagging the voltage when viewed from the perspective of the
// electrical component.
float power = 3;
float power = 4;

// The duration, in seconds, until which the request will stay in effect.
// This duration has to be between 10 seconds and 15 minutes (including both
// limits), otherwise the request will be rejected.
// If not provided, it defaults to 60s.
optional uint64 request_lifetime = 4;
optional uint64 request_lifetime = 5;
}

// Response message for the RPC `SetElectricalComponentPower`.
Expand Down