Add communication component state codes and snapshot message

RELEASE_NOTES.md

@@ -20,6 +20,7 @@
 - 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.
+- Added new message `CommunicationComponentStateSnapshot` to represent the state of communication components.
 - Added new message definitions for streaming events (Deleted, Created, Updated)
 
 ## Bug Fixes

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

@@ -12,6 +12,36 @@ syntax = "proto3";
 
 package frequenz.api.common.v1.microgrid.communication_components;
 
+import "google/protobuf/timestamp.proto";
+
+// Defines the high-level operational state of a communication component.
+// These codes can be used in a one-shot snapshot to show its current condition.
+enum CommunicationComponentStateCode {
+  // Default unset value.
+  COMMUNICATION_COMPONENT_STATE_CODE_UNSPECIFIED = 0;
+
+  // The component's internal status is unknown.
+  COMMUNICATION_COMPONENT_STATE_CODE_UNKNOWN = 1;
+
+  // The component is powered on and responding to network traffic.
+  COMMUNICATION_COMPONENT_STATE_CODE_ONLINE = 2;
+
+  // The component is powered off, unreachable, or administratively disabled.
+  COMMUNICATION_COMPONENT_STATE_CODE_OFFLINE = 3;
+
+  // The component is in the process of establishing connections.
+  COMMUNICATION_COMPONENT_STATE_CODE_CONNECTING = 4;
+
+  // The component is in the process of shutting down connections.
+  COMMUNICATION_COMPONENT_STATE_CODE_DISCONNECTING = 5;
+
+  // The component is undergoing maintenance (e.g., firmware upgrade).
+  COMMUNICATION_COMPONENT_STATE_CODE_MAINTENANCE = 6;
+
+  // The component is up but experiencing degraded performance (e.g., high packet loss).
+  COMMUNICATION_COMPONENT_STATE_CODE_DEGRADED = 7;
+}
+
 // Enumerated diagnostic codes for communication components.
 //
 // These codes indicate common network- or device-level faults that may affect
@@ -23,17 +53,59 @@ enum CommunicationComponentDiagnosticCode {
   // Component is unreachable (e.g., no heartbeat from device, network down).
   COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_UNREACHABLE = 1;
 
+  // Communication component is unknown. This could happen in cases where the
+  // status could be read from the component, but it could not be identified
+  // as a known state.
+  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_UNKNOWN = 2;
+
+  // Authentication error (e.g., invalid credentials, certificate issues).
+  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_AUTHENTICATION_ERR = 3;
+
   // Configuration error detected (e.g., invalid VLAN, IP conflict).
-  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_CONFIGURATION_ERR = 2;
+  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_CONFIGURATION_ERR = 4;
 
   // High packet loss detected over a sustained period.
-  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_PACKET_LOSS = 3;
+  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_PACKET_LOSS = 5;
 
   // Excessive latency observed (e.g., ping time above threshold).
-  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_HIGH_LATENCY = 4;
+  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_HIGH_LATENCY = 6;
 
   // Hardware fault reported by device (e.g., port error, cable disconnected).
-  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_HARDWARE_FAULT = 5;
+  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_HARDWARE_GENERIC_FAULT = 7;
+
+  // Hardware fault due to overheating.
+  COMMUNICATION_COMPONENT_DIAGNOSTIC_CODE_OVER_TEMPERATURE = 8;
+}
+
+// A single snapshot of a communication component's state, diagnostics, and timing.
+//
+// !!! note "snapshot semantics"
+//     all fields in this message represent the component's view at one point
+//     in time, so there is only a single `snapshot_time`. any parallel reads
+//     happening to produce this data are collapsed under that timestamp.
+message CommunicationComponentStateSnapshot {
+  // the utc time when this snapshot was taken.
+  google.protobuf.Timestamp snapshot_time = 1;
+
+  // one or more high-level state codes active at snapshot_time.
+  //
+  // !!! note
+  //     typical usage is a single state (e.g., online), but multiple may
+  //     apply (e.g., connecting + degraded) if that makes sense.
+  repeated CommunicationComponentStateCode states = 2;
+
+  // non-critical warnings detected for the component.
+  //
+  // !!! note
+  //     warnings may coexist with an online state, indicating potential
+  //     issues that do not prevent basic operation.
+  repeated CommunicationComponentDiagnostic warnings = 3;
+
+  // critical errors currently affecting the component.
+  //
+  // !!! note
+  //     an error state code should accompany entries here.
+  repeated CommunicationComponentDiagnostic errors = 4;
 }
 
 // Represents an error or warning condition reported by a microgrid