Add enum ElectricalComponentControlMode (#307)

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.

Thanks to @thomas-nicolai-frequenz for providing the original version.

Author: tiyash-basu-frequenz

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;