diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index c9f11b18..b79ef59d 100644 --- a/RELEASE_NOTES.md +++ b/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 diff --git a/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto b/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto index 976b330e..81231673 100644 --- a/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto +++ b/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.