Add enum ElectricalComponentControlMode

RELEASE_NOTES.md

@@ -6,7 +6,7 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+- The `ElectricalComponentStatus` enum has ben removed in favour of the `ElectricalComponentControlMode` enum.
 
 ## New Features
 
@@ -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
 

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 {
@@ -182,6 +164,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
@@ -357,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;