Add power-source selection for hybrid inverter controls

[tiyash-basu-frequenz]

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.

Both the v1alpha18 and v1alpha19 APIs are updated in this PR. Since v0.19.0 is not yet released, I have renumbered the fields in the SetElectricalComponentPowerRequest message of the v1alpha19 package.

closes #258

[Copilot]

Pull request overview

Adds a way for clients to express a preferred DC power source when setting discharge active-power setpoints for hybrid inverters, updating both the v1alpha18 and v1alpha19 preview APIs and documenting the additions in release notes.

Changes:

• Introduce PowerSource enum to express PV/battery preferred/only behaviors for hybrid-inverter discharge commands.
• Add power_source to SetElectricalComponentPowerRequest (and renumber fields in v1alpha19 as noted in the PR description).
• Update RELEASE_NOTES.md to reflect v1alpha18 symbol additions and adjust upgrade notes wording.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
proto/frequenz/api/microgrid/v1alpha19/microgrid.proto	Adds PowerSource and power_source field; renumbers request fields to accommodate the new field.
proto/frequenz/api/microgrid/v1alpha18/microgrid.proto	Adds PowerSource and power_source field as a backward-compatible addition.
RELEASE_NOTES.md	Documents the v1alpha18 additions and adjusts upgrade guidance text.

Comments suppressed due to low confidence (6)

proto/frequenz/api/microgrid/v1alpha19/microgrid.proto:605

• The comment says “discharge power setpoint”, but the rest of this file consistently uses “set-point” (hyphenated). For consistency, consider changing this to “set-point”.

  // The preferred power source for the electrical component when setting a
  // discharge power setpoint. This is relevant for hybrid inverters which have
  // both PV and battery inputs added to them, and can use either of those

proto/frequenz/api/microgrid/v1alpha18/microgrid.proto:616

• power_source is a proto3 enum field, so callers can’t really “not provide” it in a distinguishable way (omitting it on the wire yields the default POWER_SOURCE_UNSPECIFIED). Consider updating the wording to reflect that POWER_SOURCE_UNSPECIFIED/omitted means PV-preferred, or make the field optional if presence needs to be detected.

  // If the above criteria are met, and this field is not provided, then the API
  // service will default to using `POWER_SOURCE_PV_PREFERRED` as the power
  // source.
  //

proto/frequenz/api/microgrid/v1alpha18/microgrid.proto:605

• The comment says “discharge power setpoint”, but the rest of this file consistently uses “set-point” (hyphenated). For consistency, consider changing this to “set-point”.

  // The preferred power source for the electrical component when setting a
  // discharge power setpoint. This is relevant for hybrid inverters which have
  // both PV and battery inputs added to them, and can use either of those

proto/frequenz/api/microgrid/v1alpha18/microgrid.proto:620

• In v1alpha18, power_source is field number 5 but it appears before fields 3 (power) and 4 (request_lifetime) in the message definition. Reordering the fields in the .proto to match numeric order would make the schema easier to read and less error-prone to maintain.

  PowerSource power_source = 5;

RELEASE_NOTES.md:18

• The release notes summary currently states that all new features are available exclusively in v1alpha19, but this PR also adds new API surface to the stable v1alpha18 package. Please update the earlier summary wording to avoid implying v1alpha18 is unchanged in this release.

## Stable `v1alpha18` Preview API

The `v1alpha18` API is also stable and has the following symbol additions:

proto/frequenz/api/microgrid/v1alpha19/microgrid.proto:616

• power_source is a proto3 enum field, so callers can’t really “not provide” it in a distinguishable way (omitting it on the wire yields the default POWER_SOURCE_UNSPECIFIED). Consider updating the wording to reflect that POWER_SOURCE_UNSPECIFIED/omitted means PV-preferred, or make the field optional if presence needs to be detected.

  // If the above criteria are met, and this field is not provided, then the API
  // service will default to using `POWER_SOURCE_PV_PREFERRED` as the power
  // source.
  //

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[florian-wagner-frequenz]

LGTM in general, but l don't think we should be doing a breaking update to the Microgrid API without increasing to v1alpha20

[florian-wagner-frequenz]

Nit: this is not just the preferred power source, as it also allows for "XYZ_ONLY".

[florian-wagner-frequenz]

Nit: this is not only preferred as it can also be directive.

[florian-wagner-frequenz]

I am not sure whether we want to bump the field order. This is a breaking change in my eyes and should correspond to a release of a new alpha version. Otherwise it might be hard to distinguish this from places where nitrogend is running with the "old" v1alpha19 vs. the "new" v1alpha19 (you see what this is doing?)