Update the metrics package (#114)

This PR refactors the metrics protobuf package to simplify and
generalise it further.

RELEASE_NOTES.md

@@ -8,6 +8,33 @@
 
 - `lower` and `upper` bounds fields in the `Bounds` message are now `optional`
 
+- `rated_bounds` field has been removed from the messages `Metric` and
+  `MetricAggregation`
+
+- `component_bounds` field has been removed from the messages `Metric` and
+  `MetricAggregation`
+
+- Inclusion and exclusion bounds have been removed from the metric definitions.
+  These have been replaced with an array of inclusion bounds. This simplifies
+  the message definition, and removes the requirement of clients having to check
+  if a parameter is _not_ in a given pair of bounds. This also extends the
+  possibility of having more than 2 pairs bounds for a given metric.
+
+- Fields in `MetricAggregation` message have been suffixed with `_value`, to
+  make them consistent with the `Metric` message.
+
+- Timestamps have been introduced in the metric messages. This makes it easier
+  to use these messages in a timeseries context.
+
+- Renamed `Metric` message to `SimpleMetricSample`
+
+- Renamed `MetricAggregation` message to `AggregatedMetricSample`
+
+- Added a union type message `MetricSampleVariant` to represent both
+  `SimpleMetricSample` and `AggregatedMetricSample`
+
+- Added a message to represent metrics sampled from components.
+
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->

proto/frequenz/api/common/v1/components/data.proto

@@ -0,0 +1,334 @@
+// Data format definitions for components.
+//
+// Copyright:
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.components.data;
+
+import "frequenz/api/common/v1/metrics.proto";
+
+import "google/protobuf/timestamp.proto";
+
+
+// ComponentData message aggregates multiple metrics, operational states, and
+// errors, related to a specific microgrid component.
+//
+// !!! example
+//     Example output structure:
+//     ```
+//     {
+//       "metric_samples": [
+//         {
+//           "metric": "DC_VOLTAGE_V",
+//           "value": {
+//             "simple_metric": {
+//               "sampled_at": "2023-10-19T14:15:22.123456789Z",
+//               "value": 48.2,
+//               "bounds": [{ "lower": 45.0, "upper": 50.0 }]
+//             }
+//           }
+//         },
+//         {
+//           "metric": "DC_CURRENT_A",
+//           "value": {
+//             "aggregated_metric": {
+//               "sampled_at": "2023-10-19T14:15:22.123456789Z",
+//               "avg_value": 10.2,
+//               "min_value": 9.8,
+//               "max_value": 10.6,
+//               "list_values": [9.8, 10.1, 10.6],
+//               "bounds": [
+//                 { "lower": -20.0, "upper": -5.0 },
+//                 { "lower": 5.0, "upper": 20.0 }
+//               ]
+//             }
+//           }
+//         }
+//       ],
+//       "states": [
+//         {
+//           "sampled_at": "2023-10-19T14:15:22.123456789Z",
+//           "state": ["COMPONENT_STATE_CHARGING"],
+//           "errors": []
+//         },
+//         {
+//           "sampled_at": "2023-10-19T14:00:00.000000000Z",
+//           "state": ["COMPONENT_STATE_ERROR"],
+//           "errors": ["COMPONENT_ERROR_CODE_BATTERY_RELAY_ERROR"]
+//         }
+//       ]
+//     }
+//    ```
+message ComponentData {
+  // Representation of a sampled metric along with its value.
+  message MetricSample {
+    // The metric that was sampled.
+    frequenz.api.common.v1.metrics.Metric metric = 1;
+
+    // The value of the sampled metric.
+    frequenz.api.common.v1.metrics.MetricSampleVariant sample = 2;
+  }
+
+  // Representation of a component state and errors.
+  message State {
+    // The time at which the state was sampled.
+    google.protobuf.Timestamp sampled_at = 1;
+
+    // List if states of the microgrid component.
+    //
+    // !!! note
+    //    The list will contain unique members. No state will exist twice in
+    //    this list.
+    repeated ComponentState states = 2;
+
+    // List of errors for the microgrid component.
+    //
+    // !!! note
+    //    The list of errors is supposed to be populated only if the component
+    //    is in an error state.
+    //
+    // !!! note
+    //    The list will contain unique members. No error will exist twice in
+    //    this list.
+    repeated ComponentError errors = 4;
+  }
+
+  // List of measurements for a metric of the specific microgrid component.
+  repeated MetricSample metric_samples = 1;
+
+  // List of states of a specific microgrid component.
+  repeated State states = 2;
+}
+
+// Enum to represent the various states that a component can be in.
+// This enum is unified across all component categories for consistency.
+enum ComponentState {
+  // Default value when the component state is not explicitly set.
+  // This is the zero value of the enum.
+  COMPONENT_STATE_UNSPECIFIED = 0;
+
+  // State when the component is in an unknown or undefined condition.
+  // This is used when the sender is unable to classify the component into any
+  // other state.
+  COMPONENT_STATE_UNKNOWN = 1;
+
+  // State when the component is temporarily unavailable for operation.
+  COMPONENT_STATE_UNAVAILABLE = 2;
+
+  // State when the component is in the process of switching off.
+  COMPONENT_STATE_SWITCHING_OFF = 3;
+
+  // State when the component has successfully switched off.
+  COMPONENT_STATE_OFF = 4;
+
+  // State when the component is in the process of switching on from an off
+  // state.
+  COMPONENT_STATE_SWITCHING_ON = 5;
+
+  // State when the component is in standby mode, and not immediately ready for
+  // immediate operations.
+  COMPONENT_STATE_STANDBY = 6;
+
+  // State when the component is fully operational and ready for use.
+  COMPONENT_STATE_READY = 7;
+
+  // State when the component is actively consuming energy.
+  COMPONENT_STATE_CHARGING = 8;
+
+  // State when the component is actively producing or releasing energy.
+  COMPONENT_STATE_DISCHARGING = 9;
+
+  // State when the component is in an error state and may need attention.
+  COMPONENT_STATE_ERROR = 10;
+
+  // The Electric Vehicle (EV) charging cable is unplugged from the charging
+  // station.
+  COMPONENT_STATE_EV_CHARGING_CABLE_UNPLUGGED = 20;
+
+  // The EV charging cable is plugged into the charging station.
+  COMPONENT_STATE_EV_CHARGING_CABLE_PLUGGED_AT_STATION = 21;
+
+  // The EV charging cable is plugged into the vehicle.
+  COMPONENT_STATE_EV_CHARGING_CABLE_PLUGGED_AT_EV = 22;
+
+  // The EV charging cable is locked at the charging station end, indicating
+  // readiness for charging.
+  COMPONENT_STATE_EV_CHARGING_CABLE_LOCKED_AT_STATION = 23;
+
+  // The EV charging cable is locked at the vehicle end, indicating that
+  // charging is active.
+  COMPONENT_STATE_EV_CHARGING_CABLE_LOCKED_AT_EV = 24;
+
+  // The relay is in an open state, meaning no current can flow through.
+  COMPONENT_STATE_RELAY_OPEN = 30;
+
+  // The relay is in a closed state, allowing current to flow.
+  COMPONENT_STATE_RELAY_CLOSED = 31;
+
+  // The precharger circuit is open, meaning it's not currently active.
+  COMPONENT_STATE_PRECHARGER_OPEN = 40;
+
+  // The precharger is in a precharging state, preparing the main circuit for
+  // activation.
+  COMPONENT_STATE_PRECHARGER_PRECHARGING = 41;
+
+  // The precharger circuit is closed, allowing full current to flow to the main
+  // circuit.
+  COMPONENT_STATE_PRECHARGER_CLOSED = 42;
+}
+
+// A representation of all possible errors that can occur across all component
+// categories.
+enum ComponentErrorCode {
+  // Default value. No specific error is specified.
+  COMPONENT_ERROR_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.
+  COMPONENT_ERROR_CODE_UNKNOWN = 1;
+
+  // Error indicating that the component could not be switched on.
+  COMPONENT_ERROR_CODE_SWITCH_ON_FAULT = 2;
+
+  // Error indicating that the component is operating under the minimum rated
+  // voltage.
+  COMPONENT_ERROR_CODE_UNDERVOLTAGE = 3;
+
+  // Error indicating that the component is operating over the maximum rated
+  //  voltage.
+  COMPONENT_ERROR_CODE_OVERVOLTAGE = 4;
+
+  // Error indicating that the component is drawing more current than the
+  // maximum rated value.
+  COMPONENT_ERROR_CODE_OVERCURRENT = 5;
+
+  // Error indicating that the component's consumption current is over the
+  // maximum rated value during charging.
+  COMPONENT_ERROR_CODE_OVERCURRENT_CHARGING = 6;
+
+  // Error indicating that the component's production current is over the
+  // maximum rated value during discharging.
+  COMPONENT_ERROR_CODE_OVERCURRENT_DISCHARGING = 7;
+
+  // Error indicating that the component is operating over the maximum rated
+  // temperature.
+  COMPONENT_ERROR_CODE_OVERTEMPERATURE = 8;
+
+  // Error indicating that the component is operating under the minimum rated
+  // temperature.
+  COMPONENT_ERROR_CODE_UNDERTEMPERATURE = 9;
+
+  // Error indicating that the component is exposed to high humidity levels over
+  // the maximum rated value.
+  COMPONENT_ERROR_CODE_HIGH_HUMIDITY = 10;
+
+  // Error indicating that the component's fuse has blown.
+  COMPONENT_ERROR_CODE_FUSE_ERROR = 11;
+
+  // Error indicating that the component's precharge unit has failed.
+  COMPONENT_ERROR_CODE_PRECHARGE_ERROR = 12;
+
+  // Error indicating plausibility issues within the system involving this
+  // component.
+  COMPONENT_ERROR_CODE_PLAUSIBILITY_ERROR = 13;
+
+  // Error indicating system shutdown due to undervoltage involving this
+  // component.
+  COMPONENT_ERROR_CODE_UNDERVOLTAGE_SHUTDOWN = 14;
+
+  // Error indicating unexpected pilot failure in an electric vehicle (EV)
+  // component.
+  COMPONENT_ERROR_CODE_EV_UNEXPECTED_PILOT_FAILURE = 15;
+
+  // Error indicating fault current detected in the component.
+  COMPONENT_ERROR_CODE_FAULT_CURRENT = 16;
+
+  // Error indicating a short circuit detected in the component.
+  COMPONENT_ERROR_CODE_SHORT_CIRCUIT = 17;
+
+  // Error indicating a configuration error related to the component.
+  COMPONENT_ERROR_CODE_CONFIG_ERROR = 18;
+
+  // Error indicating an illegal state requested for the component.
+  COMPONENT_ERROR_CODE_ILLEGAL_COMPONENT_STATE_REQUESTED = 19;
+
+  // Error indicating that the hardware of the component is inaccessible.
+  COMPONENT_ERROR_CODE_HARDWARE_INACCESSIBLE = 20;
+
+  // Error indicating an internal error within the component.
+  COMPONENT_ERROR_CODE_INTERNAL = 21;
+
+  // Error indicating that the component is unauthorized to perform the
+  // last requested action.
+  COMPONENT_ERROR_CODE_UNAUTHORIZED = 22;
+
+  // Error indicating electric vehicle (EV) cable was abruptly unplugged from
+  // the charging station.
+  COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION = 40;
+
+  // Error indicating electric vehicle (EV) cable was abruptly unplugged from
+  // the vehicle.
+  COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_EV = 41;
+
+  // Error indicating electric vehicle (EV) cable lock failure.
+  COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_LOCK_FAILED = 42;
+
+  // Error indicating an invalid electric vehicle (EV) cable.
+  COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_INVALID = 43;
+
+  // Error indicating an incompatible electric vehicle (EV) plug.
+  COMPONENT_ERROR_CODE_EV_CONSUMER_INCOMPATIBLE = 44;
+
+  // Error indicating a battery system imbalance.
+  COMPONENT_ERROR_CODE_BATTERY_IMBALANCE = 50;
+
+  // Error indicating a low state of health (SOH) detected in the battery.
+  COMPONENT_ERROR_CODE_BATTERY_LOW_SOH = 51;
+
+  // Error indicating a battery block error.
+  COMPONENT_ERROR_CODE_BATTERY_BLOCK_ERROR = 52;
+
+  // Error indicating a battery controller error.
+  COMPONENT_ERROR_CODE_BATTERY_CONTROLLER_ERROR = 53;
+
+  // Error indicating a battery relay error.
+  COMPONENT_ERROR_CODE_BATTERY_RELAY_ERROR = 54;
+
+  // Error indicating that battery calibration is needed.
+  COMPONENT_ERROR_CODE_BATTERY_CALIBRATION_NEEDED = 56;
+
+  // Error indicating that the relays have been cycled for the maximum number of
+  // times.
+  COMPONENT_ERROR_CODE_RELAY_CYCLE_LIMIT_REACHED = 60;
+}
+
+// A representation of all possible error levels that an error can have.
+enum ErrorLevel {
+  // Default value. No specific error-level is specified.
+  ERROR_LEVEL_UNSPECIFIED = 0;
+
+  // The associated error is a warning.
+  // Users are advised to take action to prevent the error from becoming
+  // critical.
+  ERROR_LEVEL_WARN = 1;
+
+  // The associated error is critical.
+  // The associated component is very likely out-of-order, and needs immediate
+  // attention.
+  ERROR_LEVEL_CRITICAL = 2;
+}
+
+// ComponentError message represents an error that occurred in a microgrid
+// component.
+message ComponentError {
+  // The error code.
+  ComponentErrorCode code = 1;
+
+  // THe error level, indicating if it is a warning or a critical error
+  ErrorLevel level = 2;
+}