diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 3df2be0f..c9f11b18 100644 --- a/RELEASE_NOTES.md +++ b/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 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 d9baa0b5..f934f93e 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 @@ -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,7 +511,7 @@ 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. // @@ -524,5 +519,5 @@ message ElectricalComponentState { // 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; }