diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 9a314d1f..3df2be0f 100644 --- a/RELEASE_NOTES.md +++ b/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 diff --git a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto b/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto index 9cc2aff9..d9baa0b5 100644 --- a/proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto +++ b/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; }