From 3d497c88caed519760bcda04f0d6dfd0ef094795 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Tue, 3 Mar 2026 16:31:46 +0100 Subject: [PATCH] Add power-source selection for hybrid inverter controls This commit adds the ability to specify a preferred power source when issuing discharge commands to hybrid inverters, which typically have both PV and battery inputs added to them, and can use either of those inputs as the power source. Signed-off-by: Tiyash Basu --- RELEASE_NOTES.md | 15 ++++- .../api/microgrid/v1alpha18/microgrid.proto | 53 +++++++++++++++++ .../api/microgrid/v1alpha19/microgrid.proto | 57 ++++++++++++++++++- 3 files changed, 120 insertions(+), 5 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 0220d963..1335047e 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -12,11 +12,20 @@ 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. ----- @@ -24,13 +33,13 @@ A new package, `frequenz.api.microgrid.v1alpha19`, has been introduced to provid ### 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. ----- diff --git a/proto/frequenz/api/microgrid/v1alpha18/microgrid.proto b/proto/frequenz/api/microgrid/v1alpha18/microgrid.proto index 8ecd5764..834100ae 100644 --- a/proto/frequenz/api/microgrid/v1alpha18/microgrid.proto +++ b/proto/frequenz/api/microgrid/v1alpha18/microgrid.proto @@ -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. @@ -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: diff --git a/proto/frequenz/api/microgrid/v1alpha19/microgrid.proto b/proto/frequenz/api/microgrid/v1alpha19/microgrid.proto index e6b2661c..f09a29bb 100644 --- a/proto/frequenz/api/microgrid/v1alpha19/microgrid.proto +++ b/proto/frequenz/api/microgrid/v1alpha19/microgrid.proto @@ -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. @@ -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: @@ -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`.