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`.