diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 40c54b96..0002cc67 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -19,6 +19,7 @@ - The enum `SensorErrorCode` has now been renamed to `SensorDiagnosticCode` to better reflect its shared usage with warnings and errors. - Added warnings to sensor `SensorState`. - Added a common `TimeIntervalFilter` message in `frequenz.api.common.v1.types` to standardize time interval filtering across APIs. This uses `start_time` (inclusive) and `end_time` (exclusive) fields, aligning with ISO 8601 and common programming conventions. +- Added new message `CommunicationComponentDiagnostic` to represent warnings and errors in microgrid communication components. ## Bug Fixes diff --git a/proto/frequenz/api/common/v1/microgrid/communication_components/communication_components.proto b/proto/frequenz/api/common/v1/microgrid/communication_components/communication_components.proto index b1e6aea1..32ceee36 100644 --- a/proto/frequenz/api/common/v1/microgrid/communication_components/communication_components.proto +++ b/proto/frequenz/api/common/v1/microgrid/communication_components/communication_components.proto @@ -1,3 +1,5 @@ +// protolint:disable MAX_LINE_LENGTH + // Frequenz microgrid communication components definitions. // // Copyright: @@ -10,6 +12,60 @@ syntax = "proto3"; package frequenz.api.common.v1.microgrid.communication_components; +// Enumerated diagnostic codes for communication components. +// +// These codes indicate common network- or device-level faults that may affect +// connectivity. +enum CommunicationComponentDiagnosticCode { + // Default value; no specific diagnostic is specified. + COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_UNSPECIFIED = 0; + + // Component is unreachable (e.g., no heartbeat from device, network down). + COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_UNREACHABLE = 1; + + // Configuration error detected (e.g., invalid VLAN, IP conflict). + COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_CONFIGURATION_ERR = 2; + + // High packet loss detected over a sustained period. + COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_PACKET_LOSS = 3; + + // Excessive latency observed (e.g., ping time above threshold). + COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_HIGH_LATENCY = 4; + + // Hardware fault reported by device (e.g., port error, cable disconnected). + COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_HARDWARE_FAULT = 5; +} + +// Represents an error or warning condition reported by a microgrid +// communication component. +// +// This message extends a standardized diagnostic code with optional +// vendor-specific codes and contextual information for troubleshooting. +// +// !!! example "Typical Communication Component Warning" +// ```json +// { +// "diagnosticCode": "COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_CONFIGURATION_ERR", +// "vendorErrorCode": 1002, +// "message": "VLAN mismatch detected on port 3" +// } +// ``` +// +// !!! note "Vendor-Specific Codes" +// When available, `vendor_error_code` reflects manufacturer-defined error +// identifiers. +// These codes are vendor- and firmware-specific and must be interpreted +// using the vendor's official documentation. +message CommunicationComponentDiagnostic { + // A standardized diagnostic code representing the category of the issue. + CommunicationComponentDiagnosticCode diagnostic_code = 1; + + // Optional vendor-provided error code for more granular diagnostics. + optional uint32 vendor_error_code = 2; + + // Human-readable message providing additional context. + string message = 3; +} // `CommunicationComponent` represents a communication component within a // microgrid.