Update sensor error representation (#310)

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -15,6 +15,9 @@
 - Added new message definitions for communication 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.
+- Added new message `SensorDiagnostic` to represent warnings and errors in microgrid sensors.
+- The enum `SensorErrorCode` has now been renamed to `SensorDiagnosticCode` to better reflect its shared usage with warnings and errors.
+- Added warnings to sensor `SensorState`.
 
 ## Bug Fixes
 

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

@@ -149,6 +149,38 @@ message SensorData {
   repeated SensorState states = 3;
 }
 
+// Represents an error or warning condition reported by a microgrid sensor.
+//
+// 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 Sensor Error"
+//     ```json
+//     {
+//       "diagnosticCode":
+//           "SENSOR_DIAGNOSTIC_CODE_INTERNAL",
+//       "vendorErrorCode": 2003,
+//       "message": "Temperature sensor 3 reported 61.5°C (limit: 60°C)"
+//     }
+//     ```
+// !!! 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 SensorDiagnostic {
+  // A standardized error code representing the category of the issue.
+  SensorDiagnosticCode diagnostic_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 sensor state and errors.
 message SensorState {
   // The time at which the state was sampled.
@@ -161,6 +193,17 @@ message SensorState {
   //    this list.
   repeated SensorStateCode states = 2;
 
+  // List of warnings for the microgrid sensor.
+  //
+  // !!! note
+  //    This list is expected to have warnings if and only if the sensor is
+  //    reporting warnings.
+  //
+  // !!! note
+  //    The list will contain unique members. No warning will exist twice in
+  //    this list.
+  repeated SensorDiagnostic warnings = 3;
+
   // List of errors for the microgrid sensor.
   //
   // !!! note
@@ -170,7 +213,7 @@ message SensorState {
   // !!! note
   //    The list will contain unique members. No error will exist twice in
   //    this list.
-  repeated SensorErrorCode errors = 4;
+  repeated SensorDiagnostic errors = 4;
 }
 
 // Enum to represent the various states that a sensor can be in.
@@ -187,17 +230,18 @@ enum SensorStateCode {
   SENSOR_STATE_CODE_ERROR = 2;
 }
 
-// A representation of all possible errors that can occur in sensors.
-enum SensorErrorCode {
+// A representation of all possible warnings and errors that can occur in
+// sensors.
+enum SensorDiagnosticCode {
   // Default value. No specific error is specified.
-  SENSOR_ERROR_CODE_UNSPECIFIED = 0;
+  SENSOR_DIAGNOSTIC_CODE_UNSPECIFIED = 0;
 
   // The sensor is reporting an unknown or an undefined error, and the sender
   // cannot parse the sensor error to any of the variants below.
-  SENSOR_ERROR_CODE_UNKNOWN = 1;
+  SENSOR_DIAGNOSTIC_CODE_UNKNOWN = 1;
 
   // Error indicating an internal error within the sensor.
-  SENSOR_ERROR_CODE_INTERNAL = 2;
+  SENSOR_DIAGNOSTIC_CODE_INTERNAL = 2;
 }
 
 // Representation of a sampled sensor metric along with its value.