Add an ElectricalComponentError message

RELEASE_NOTES.md

@@ -13,6 +13,7 @@
 - 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.
 
 ## Bug Fixes
 

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

@@ -461,37 +461,68 @@ enum ElectricalComponentErrorCode {
   ELECTRICAL_COMPONENT_ERROR_CODE_RELAY_CYCLE_LIMIT_REACHED = 60;
 }
 
+// Represents an error or warning condition reported by a microgrid electrical
+// component.
+//
+// This message extends a standardized error code with contextual information
+// useful for diagnostics, such as subsystem names, measured values, or
+// vendor-specific insights.
+//
+// !!! example "Typical Component Error"
+//     ```json
+//     {
+//       "errorCode": "ELECTRICAL_COMPONENT_ERROR_CODE_OVERTEMPERATURE",
+//       "vendorErrorCode": 2003,
+//       "message": "Temperature sensor 3 reported 61.5°C (limit: 60°C)"
+//     }
+//     ```
+//
+// !!! note "Component-Originated Diagnostics"
+//     This message is intended to reflect diagnostics originating from
+//     electrical components (e.g., inverters, batteries), either from internal
+//     firmware or via gateway logic.
+//
+// !!! note "Vendor-Specific Codes"
+//     When available, `vendor_error_code` will reflect manufacturer-defined
+//     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 {
+  // A standardized error code representing the category of the issue.
+  ElectricalComponentErrorCode error_code = 1;
+
+  // Optional vendor-provided error code for the error, for vendor-specific
+  // insights or more granular diagnostics.
+  optional uint32 vendor_error_code = 2;
+
+  // Optional human-readable message providing additional context.
+  string message = 3;
+}
+
 // Representation of a component state and errors.
 message ElectricalComponentState {
   // The time at which the state was sampled.
   google.protobuf.Timestamp sampled_at = 1;
 
-  // List of states of the microgrid component.
+
+  // List of operational states currently active for the component.
   //
   // !!! note
-  //    The list will contain unique members. No state will exist twice in
-  //    this list.
+  //     The list must not contain duplicate state codes.
   repeated ElectricalComponentStateCode states = 2;
 
-  // List of warnings for the microgrid component.
-  //
-  // !!! note
-  //    This list may have warnings even if the component state is not in an
-  //    error state.
+  // List of non-critical warnings detected for the component.
   //
   // !!! note
-  //    The list will contain unique members. No warning will exist twice in
-  //    this list.
-  repeated ElectricalComponentErrorCode warnings = 3;
+  //     Warnings may be reported even when the component is operational.
+  //     No duplicate warning codes allowed.
+  repeated ElectricalComponentError warnings = 3;
 
-  // List of errors for the microgrid component.
-  //
-  // !!! note
-  //    This list is expected to have errors if and only if the component is in
-  //    an error state.
+  // List of critical errors currently affecting the component.
   //
   // !!! note
-  //    The list will contain unique members. No error will exist twice in
-  //    this list.
-  repeated ElectricalComponentErrorCode errors = 4;
+  //     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;
 }