Rename ElectricalComponentError to ElectricalComponentDiagnostic (#309)

This commit improves the naming of the `ElectricalComponentError`
message to `ElectricalComponentDiagnostic`, to better reflect its
purpose of representing both warnings and errors in microgrid electrical
components.

Followed up from this comment:
#308 (comment)

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -13,7 +13,8 @@
 - Renamed `components` to `electrical_components` and related messages, fields, enums.
 - Added message linking microgrid and sensor IDs.
 - Added new message definitions for communication components.
-- Added new message `ElectricalComponentError` to represent errors in microgrid electrical components.
+- Added new message `ElectricalComponentDiagnostic` to represent warnings and errors in microgrid electrical components.
+- The enum `ComponentErrorCode` has now been renamed to `ElectricalComponentDiagnosticCode` to better reflect its shared usage with warnings and errors.
 
 ## Bug Fixes
 

proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto

@@ -336,129 +336,123 @@ enum ElectricalComponentStateCode {
   ELECTRICAL_COMPONENT_STATE_CODE_PRECHARGER_CLOSED = 42;
 }
 
-// A representation of all possible errors that can occur across all component
-// categories.
-enum ElectricalComponentErrorCode {
+// 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
+// component.
+enum ElectricalComponentDiagnosticCode {
   // Default value. No specific error is specified.
-  ELECTRICAL_COMPONENT_ERROR_CODE_UNSPECIFIED = 0;
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_UNSPECIFIED = 0;
 
   // The component is reporting an unknown or an undefined error, and the sender
   // cannot parse the component error to any of the variants below.
-  ELECTRICAL_COMPONENT_ERROR_CODE_UNKNOWN = 1;
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_UNKNOWN = 1;
 
-  // Error indicating that the component could not be switched on.
-  ELECTRICAL_COMPONENT_ERROR_CODE_SWITCH_ON_FAULT = 2;
+  // The component could not be switched on.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_SWITCH_ON_FAULT = 2;
 
-  // Error indicating that the component is operating under the minimum rated
-  // voltage.
-  ELECTRICAL_COMPONENT_ERROR_CODE_UNDERVOLTAGE = 3;
+  // The component is operating under the minimum rated voltage.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_UNDERVOLTAGE = 3;
 
-  // Error indicating that the component is operating over the maximum rated
-  //  voltage.
-  ELECTRICAL_COMPONENT_ERROR_CODE_OVERVOLTAGE = 4;
+  // The component is operating over the maximum rated voltage.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_OVERVOLTAGE = 4;
 
-  // Error indicating that the component is drawing more current than the
-  // maximum rated value.
-  ELECTRICAL_COMPONENT_ERROR_CODE_OVERCURRENT = 5;
+  // The component is drawing more current than the maximum rated value.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_OVERCURRENT = 5;
 
-  // Error indicating that the component's consumption current is over the
-  // maximum rated value during charging.
-  ELECTRICAL_COMPONENT_ERROR_CODE_OVERCURRENT_CHARGING = 6;
+  // The component's consumption current is over the maximum rated value during
+  // charging.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_OVERCURRENT_CHARGING = 6;
 
-  // Error indicating that the component's production current is over the
-  // maximum rated value during discharging.
-  ELECTRICAL_COMPONENT_ERROR_CODE_OVERCURRENT_DISCHARGING = 7;
+  // The component's production current is over the maximum rated value during
+  // discharging.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_OVERCURRENT_DISCHARGING = 7;
 
-  // Error indicating that the component is operating over the maximum rated
-  // temperature.
-  ELECTRICAL_COMPONENT_ERROR_CODE_OVERTEMPERATURE = 8;
+  // The component is operating over the maximum rated temperature.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_OVERTEMPERATURE = 8;
 
-  // Error indicating that the component is operating under the minimum rated
-  // temperature.
-  ELECTRICAL_COMPONENT_ERROR_CODE_UNDERTEMPERATURE = 9;
+  // The component is operating under the minimum rated temperature.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_UNDERTEMPERATURE = 9;
 
-  // Error indicating that the component is exposed to high humidity levels over
-  // the maximum rated value.
-  ELECTRICAL_COMPONENT_ERROR_CODE_HIGH_HUMIDITY = 10;
+  // The component is exposed to high humidity levels over the maximum rated
+  // value.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_HIGH_HUMIDITY = 10;
 
-  // Error indicating that the component's fuse has blown.
-  ELECTRICAL_COMPONENT_ERROR_CODE_FUSE_ERROR = 11;
+  // The component's fuse has blown.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_FUSE_ERROR = 11;
 
-  // Error indicating that the component's precharge unit has failed.
-  ELECTRICAL_COMPONENT_ERROR_CODE_PRECHARGE_ERROR = 12;
+  // The component's precharge unit has failed.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_PRECHARGE_ERROR = 12;
 
-  // Error indicating plausibility issues within the system involving this
-  // component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_PLAUSIBILITY_ERROR = 13;
+  // There are plausibility issues within the component, causing its internal
+  // sanity checks to fail.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_PLAUSIBILITY_ERROR = 13;
 
-  // Error indicating system shutdown due to undervoltage involving this
-  // component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_UNDERVOLTAGE_SHUTDOWN = 14;
+  // There is or was a system shutdown due to undervoltage.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_UNDERVOLTAGE_SHUTDOWN = 14;
 
-  // Error indicating unexpected pilot failure in an electric vehicle (EV)
-  // component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_EV_UNEXPECTED_PILOT_FAILURE = 15;
+  // There is an unexpected pilot failure in an electric vehicle (EV) component.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_EV_UNEXPECTED_PILOT_FAILURE = 15;
 
-  // Error indicating fault current detected in the component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_FAULT_CURRENT = 16;
+  // A fault current has been detected in the component.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_FAULT_CURRENT = 16;
 
-  // Error indicating a short circuit detected in the component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_SHORT_CIRCUIT = 17;
+  // A short circuit has been detected in the component.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_SHORT_CIRCUIT = 17;
 
-  // Error indicating a configuration error related to the component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_CONFIG_ERROR = 18;
+  // The component has been configured incorrectly.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_CONFIG_ERROR = 18;
 
-  // Error indicating an illegal state requested for the component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_ILLEGAL_COMPONENT_STATE_CODE_REQUESTED = 19;
+  // A illegal state has been requested for the component.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_ILLEGAL_COMPONENT_STATE_CODE_REQUESTED
+    = 19;
 
-  // Error indicating that the hardware of the component is inaccessible.
-  ELECTRICAL_COMPONENT_ERROR_CODE_HARDWARE_INACCESSIBLE = 20;
+  // The hardware of the component is inaccessible.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_HARDWARE_INACCESSIBLE = 20;
 
-  // Error indicating an internal error within the component.
-  ELECTRICAL_COMPONENT_ERROR_CODE_INTERNAL = 21;
+  // There is an internal error within the component.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_INTERNAL = 21;
 
-  // Error indicating that the component is unauthorized to perform the
-  // last requested action.
-  ELECTRICAL_COMPONENT_ERROR_CODE_UNAUTHORIZED = 22;
+  // The component is unauthorized to perform the last requested action.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_UNAUTHORIZED = 22;
 
-  // Error indicating electric vehicle (EV) cable was abruptly unplugged from
-  // the charging station.
-  ELECTRICAL_COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION = 40;
+  // The electric vehicle (EV) cable was abruptly unplugged from the charging
+  // station.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION
+    = 40;
 
-  // Error indicating electric vehicle (EV) cable was abruptly unplugged from
-  // the vehicle.
-  ELECTRICAL_COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_EV = 41;
+  // The electric vehicle (EV) cable was abruptly unplugged from the vehicle.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_EV = 41;
 
-  // Error indicating electric vehicle (EV) cable lock failure.
-  ELECTRICAL_COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_LOCK_FAILED = 42;
+  // There is a cable lock failure with the electric vehicle (EV).
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_EV_CHARGING_CABLE_LOCK_FAILED = 42;
 
-  // Error indicating an invalid electric vehicle (EV) cable.
-  ELECTRICAL_COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_INVALID = 43;
+  // The electric vehicle (EV) charging cable is invalid.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_EV_CHARGING_CABLE_INVALID = 43;
 
-  // Error indicating an incompatible electric vehicle (EV) plug.
-  ELECTRICAL_COMPONENT_ERROR_CODE_EV_CONSUMER_INCOMPATIBLE = 44;
+  // The incompatible electric vehicle (EV) charging plug is invalid.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_EV_CONSUMER_INCOMPATIBLE = 44;
 
-  // Error indicating a battery system imbalance.
-  ELECTRICAL_COMPONENT_ERROR_CODE_BATTERY_IMBALANCE = 50;
+  // There is a battery system imbalance.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_BATTERY_IMBALANCE = 50;
 
-  // Error indicating a low state of health (SOH) detected in the battery.
-  ELECTRICAL_COMPONENT_ERROR_CODE_BATTERY_LOW_SOH = 51;
+  // The battery has a low state of health (SOH).
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_BATTERY_LOW_SOH = 51;
 
-  // Error indicating a battery block error.
-  ELECTRICAL_COMPONENT_ERROR_CODE_BATTERY_BLOCK_ERROR = 52;
+  // At least one of the battery blocks is in an error state.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_BATTERY_BLOCK_ERROR = 52;
 
-  // Error indicating a battery controller error.
-  ELECTRICAL_COMPONENT_ERROR_CODE_BATTERY_CONTROLLER_ERROR = 53;
+  // The battery controller is in an error state.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_BATTERY_CONTROLLER_ERROR = 53;
 
-  // Error indicating a battery relay error.
-  ELECTRICAL_COMPONENT_ERROR_CODE_BATTERY_RELAY_ERROR = 54;
+  // The battery's DC contactor or relay is in an error state.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_BATTERY_RELAY_ERROR = 54;
 
-  // Error indicating that battery calibration is needed.
-  ELECTRICAL_COMPONENT_ERROR_CODE_BATTERY_CALIBRATION_NEEDED = 56;
+  // The battery needs calibration.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_BATTERY_CALIBRATION_NEEDED = 56;
 
-  // Error indicating that the relays have been cycled for the maximum number of
-  // times.
-  ELECTRICAL_COMPONENT_ERROR_CODE_RELAY_CYCLE_LIMIT_REACHED = 60;
+  // The battery's DC contactor or relays have reached end of life.
+  ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_RELAY_CYCLE_LIMIT_REACHED = 60;
 }
 
 // Represents an error or warning condition reported by a microgrid electrical
@@ -471,7 +465,8 @@ enum ElectricalComponentErrorCode {
 // !!! example "Typical Component Error"
 //     ```json
 //     {
-//       "errorCode": "ELECTRICAL_COMPONENT_ERROR_CODE_OVERTEMPERATURE",
+//       "diagnosticCode":
+//           "ELECTRICAL_COMPONENT_DIAGNOSTIC_CODE_OVERTEMPERATURE",
 //       "vendorErrorCode": 2003,
 //       "message": "Temperature sensor 3 reported 61.5°C (limit: 60°C)"
 //     }
@@ -487,9 +482,9 @@ enum ElectricalComponentErrorCode {
 //     error identifiers, typically exposed via Modbus or similar interfaces.
 //     These codes are vendor- and firmware-specific and must be interpreted
 //     using the vendor's official documentation.
-message ElectricalComponentError {
+message ElectricalComponentDiagnostic {
   // A standardized error code representing the category of the issue.
-  ElectricalComponentErrorCode error_code = 1;
+  ElectricalComponentDiagnosticCode diagnostic_code = 1;
 
   // Optional vendor-provided error code for the error, for vendor-specific
   // insights or more granular diagnostics.
@@ -499,7 +494,7 @@ message ElectricalComponentError {
   string message = 3;
 }
 
-// Representation of a component state and errors.
+// Representation of a component state, warnings, and errors.
 message ElectricalComponentState {
   // The time at which the state was sampled.
   google.protobuf.Timestamp sampled_at = 1;
@@ -516,13 +511,13 @@ message ElectricalComponentState {
   // !!! note
   //     Warnings may be reported even when the component is operational.
   //     No duplicate warning codes allowed.
-  repeated ElectricalComponentError warnings = 3;
+  repeated ElectricalComponentDiagnostic warnings = 3;
 
   // List of critical errors currently affecting the component.
   //
   // !!! note
   //     This list is expected to be populated only when the component is in an
   //     error state.
   //     No duplicate error codes allowed.
-  repeated ElectricalComponentError errors = 4;
+  repeated ElectricalComponentDiagnostic errors = 4;
 }