From b6493eb14bd7ea0be214f8c9ca77c8f256ba20eb Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Mon, 19 May 2025 15:05:19 +0200 Subject: [PATCH 1/2] Add enum `ElectricalComponentControlMode` This enum is used to explicitly define whether an electrical component is intended to be active (enabled) or inactive (disabled). This intention directly determines the component's availability to downstream services and applications. Note that this enum differs from the `ElectricalComponentStatus` enum, which is used to report the actual operational state of the component. Signed-off-by: Tiyash Basu # Conflicts: # RELEASE_NOTES.md # proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto --- RELEASE_NOTES.md | 1 + .../electrical_components.proto | 48 +++++++++++++++++++ 2 files changed, 49 insertions(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index cba778b8..d817ea63 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -24,6 +24,7 @@ - Added new message definitions for streaming events (Deleted, Created, Updated) - Remove unnecessary gap in numbering in the `ElectricalComponentCategory` enum. - Renumber variants in the `Metric` enum to remove unnecessary gaps. +- Added a new enum `ElectricalComponentControlMode` to define control modes for electrical components. ## Bug Fixes diff --git a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto b/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto index e1fe3726..50431438 100644 --- a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto +++ b/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto @@ -182,6 +182,54 @@ enum ElectricalComponentStateCode { ELECTRICAL_COMPONENT_STATE_CODE_PRECHARGER_CLOSED = 42; } +// `ElectricalComponentControlMode` explicitly defines whether an electrical +// component is intended to be active (enabled) or inactive (disabled). This +// intentional setting directly determines component availability to downstream +// agents, applications, and services. +// +// !!! note "Control Mode & Component Availability" +// The Control Mode explicitly represents the user's or automation's +// intention to make the component either ACTIVE or INACTIVE. This directly +// impacts availability: +// - ACTIVE indicates the component is intended to be available and usable +// by downstream agents and services. +// - INACTIVE indicates the component is intended to be unavailable for use +// by downstream agents and services. +// +// !!! note "Relationship with Operational State" +// Control Mode explicitly represents intention, distinct from the +// component's actual internal Operational State. +// Operational State is independently reported by the component hardware +// (e.g., READY, CHARGING, DISCHARGING, ERROR). +// +// !!! caution "Immediate Operational Impact" +// Changing the Control Mode of an electrical component (e.g., via the +// Microgrid API) takes immediate effect on its availability to downstream +// agents and services. Setting a component to `INACTIVE` can thus instantly +// interrupt ongoing operations or cause service disruptions. Setting a +// component to `ACTIVE` may immediately connect it with other components, +// potentially causing electrical damage. Therefore, ensure changes are +// coordinated or planned appropriately to avoid unintended impact and/or +// damages. +// +// !!! example "Control Mode Change Impact" +// If a battery component's Control Mode is switched from `ACTIVE` to +// `INACTIVE`, it immediately becomes unavailable to downstream +// services and agents, potentially disrupting scheduled +// charging/discharging cycles. +enum ElectricalComponentControlMode { + // The control mode is unspecified (should never be explicitly used). + ELECTRICAL_COMPONENT_CONTROL_MODE_UNSPECIFIED = 0; + + // The component is explicitly enabled and intended to be available for + // downstream usage. + ELECTRICAL_COMPONENT_CONTROL_MODE_ACTIVE = 1; + + // The component is explicitly disabled and intended to be unavailable for + // downstream usage. + ELECTRICAL_COMPONENT_CONTROL_MODE_INACTIVE = 2; +} + // A representation of all possible diagnostic codes that can occur for // electrical component, across all their categories. These diagnostic codes // can be used to refer to warnings or errors that are reported by the From 49ac7455026e1c59603282430c810c560244dd29 Mon Sep 17 00:00:00 2001 From: Tiyash Basu Date: Mon, 19 May 2025 15:07:14 +0200 Subject: [PATCH 2/2] Remove `ElectricalComponentStatus` enum The `ElectricalComponentStatus` enum has been removed in favour of the `ElectricalComponentControlMode` enum. Signed-off-by: Tiyash Basu # Conflicts: # proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto --- RELEASE_NOTES.md | 2 +- .../electrical_components.proto | 22 ++----------------- 2 files changed, 3 insertions(+), 21 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index d817ea63..d8a9f37e 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -6,7 +6,7 @@ ## Upgrading - +- The `ElectricalComponentStatus` enum has ben removed in favour of the `ElectricalComponentControlMode` enum. ## New Features diff --git a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto b/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto index 50431438..7c5a22b7 100644 --- a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto +++ b/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto @@ -87,24 +87,6 @@ enum ElectricalComponentCategory { ELECTRICAL_COMPONENT_CATEGORY_HVAC = 14; } -// ElectricalComponentStatus defines the possible statuses for a component. -// -// !!! note -// The status indicates the status set by the user via the user interface. -// The status is not yet included in the Component messages and should be -// added. -// -enum ElectricalComponentStatus { - // The status is unspecified. This should not be used. - ELECTRICAL_COMPONENT_STATUS_UNSPECIFIED = 0; - - // The component is active. - ELECTRICAL_COMPONENT_STATUS_ACTIVE = 1; - - // The component is inactive. - ELECTRICAL_COMPONENT_STATUS_INACTIVE = 2; -} - // Enum to represent the various states that a component can be in. // This enum is unified across all component categories for consistency. enum ElectricalComponentStateCode { @@ -405,8 +387,8 @@ message ElectricalComponent { // The model name of the component. string model_name = 7; - // The status of the component. - ElectricalComponentStatus status = 8; + // The control mode of the component. + ElectricalComponentControlMode control_mode = 8; // The operational lifetime of the component. frequenz.api.common.v1.microgrid.Lifetime operational_lifetime = 9;