Add messages describing microgrid entities (#127)

This change introduces messages to describe microgrid entities such as
sensors, components, electrical connections, and microgrids.

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -40,6 +40,23 @@
 
 - Added a message `SensorData` to represent metrics sampled from sensors.
 
+- Added a message `Lifetime` as a wrapper over the start and end timestamps of
+  an entity.
+
+- Added a message `Sensor` to represent sensors installed in a microgrid.
+
+- Added a message `Component` to represent components installed in a microgrid.
+
+- Added a message `ComponentCategoryMetadataVariant` to represent the different
+  types of sub-categories that can be associated with a component category.
+
+- Added a message `ComponentConnection` to represent electrical connection
+  between two components installed in a microgrid.
+
+- Added a message `DeliveryArea` to represent a market contract delivery area.
+
+- Added a message `Microgrid` to represent a microgrid.
+
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->

proto/frequenz/api/common/v1/grid/delivery_area.proto

@@ -0,0 +1,62 @@
+// Frequenz definitions of grids as entites participating in trading.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.grid;
+
+// CodeType specifies the type of identification code used for uniquely
+// identifying various entities such as delivery areas, market participants, and
+// grid components within the energy market. This enumeration aims to offer
+// compatibility across different jurisdictional standards.
+//
+// !!! note "Understanding Code Types"
+//     Different regions or countries may have their own standards for uniquely
+//     identifying various entities within the energy market. For example, in
+//     Europe, the Energy Identification Code (EIC) is commonly used for this
+//     purpose.
+//
+// !!! info "Extensibility"
+//     New code types can be added to this enum to accommodate additional
+//     regional standards, enhancing the API's adaptability.
+//
+// !!! caution "Validation Required"
+//     The chosen code type should correspond correctly with the `code` field in
+//     the relevant message objects, such as `DeliveryArea` or `Counterparty`.
+//     Failure to match the code type with the correct code could lead to
+//     processing errors.
+//
+enum EnergyMarketCodeType {
+  // Unspecified type. This value is a placeholder and should not be used.
+  ENERGY_MARKET_CODE_TYPE_UNSPECIFIED = 0;
+
+  // European Energy Identification Code Standard.
+  ENERGY_MARKET_CODE_TYPE_EUROPE_EIC = 1;
+
+  // North American Electric Reliability Corporation identifiers.
+  ENERGY_MARKET_CODE_TYPE_US_NERC = 2;
+}
+
+// DeliveryArea represents the geographical or administrative region, usually
+// defined and maintained by a Transmission System Operator (TSO), where
+// electricity deliveries for a contract occur.
+//
+// The concept is important to energy trading as it delineates the agreed-upon
+// delivery location. Delivery areas can have different codes based on the//
+// jurisdiction in which they operate.
+//
+// !!! note "Jurisdictional Differences"
+//     This is typically represented by specific codes according to local
+//     jurisdiction. In Europe, this is represented by an EIC
+//     (Energy Identification Code).
+message DeliveryArea {
+  // Code representing the unique identifier for the delivery area.
+  string code = 1;
+
+  // Type of code used for identifying the delivery area itself.
+  EnergyMarketCodeType code_type = 2;
+}

proto/frequenz/api/common/v1/microgrid/components/battery.proto

@@ -0,0 +1,29 @@
+// Frequenz definitions for batteries.
+//
+// Copyright:
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.microgrid.components;
+
+// Enumerated battery types.
+enum BatteryType {
+  // Unspecified.
+  BATTERY_TYPE_UNSPECIFIED = 0;
+
+  // Li-ion batteries.
+  BATTERY_TYPE_LI_ION = 1;
+
+  // Sodium-ion batteries
+  BATTERY_TYPE_NA_ION = 2;
+}
+
+// A representation of a battery.
+message Battery {
+  // The battery type.
+  BatteryType type = 1;
+}

proto/frequenz/api/common/v1/components.proto renamed to proto/frequenz/api/common/v1/microgrid/components/components.proto

@@ -8,9 +8,16 @@
 
 syntax = "proto3";
 
-package frequenz.api.common.v1.components;
+package frequenz.api.common.v1.microgrid.components;
 
 import "frequenz/api/common/v1/metrics.proto";
+import "frequenz/api/common/v1/microgrid/components/battery.proto";
+import "frequenz/api/common/v1/microgrid/components/ev_charger.proto";
+import "frequenz/api/common/v1/microgrid/components/fuse.proto";
+import "frequenz/api/common/v1/microgrid/components/grid.proto";
+import "frequenz/api/common/v1/microgrid/components/inverter.proto";
+import "frequenz/api/common/v1/microgrid/components/transformer.proto";
+import "frequenz/api/common/v1/microgrid/lifetime.proto";
 
 import "google/protobuf/timestamp.proto";
 
@@ -75,46 +82,102 @@ enum ComponentCategory {
   COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER = 14;
 }
 
-// Enumerated battery types.
-enum BatteryType {
-  // Unspecified.
-  BATTERY_TYPE_UNSPECIFIED = 0;
+// Metadata specific to a microgrid component.
+message ComponentCategoryMetadataVariant {
+  oneof metadata {
+    frequenz.api.common.v1.microgrid.components.Battery battery = 1;
+    frequenz.api.common.v1.microgrid.components.EvCharger ev_charger = 2;
+    frequenz.api.common.v1.microgrid.components.Fuse fuse = 3;
+    frequenz.api.common.v1.microgrid.components.GridConnectionPoint grid = 4;
+    frequenz.api.common.v1.microgrid.components.Inverter inverter = 5;
+    frequenz.api.common.v1.microgrid.components.VoltageTransformer
+      voltage_transformer = 6;
+  }
+}
+
+// ComponentStatus defines the possible statuses for a component.
+//
+// !!! note
+//     The status indicates the status set by the user via the user interface.
+//     The status is not yet included in the Component messages and should be
+//     added.
+//
+enum ComponentStatus {
+  // The status is unspecified. This should not be used.
+  COMPONENT_STATUS_UNSPECIFIED = 0;
 
-  // Li-ion batteries.
-  BATTERY_TYPE_LI_ION = 1;
+  // The component is active.
+  COMPONENT_STATUS_ACTIVE = 1;
 
-  // Sodium-ion batteries
-  BATTERY_TYPE_NA_ION = 2;
+  // The component is inactive.
+  COMPONENT_STATUS_INACTIVE = 2;
 }
 
-// Enumerated inverter types.
-enum InverterType {
-  // Unspecified.
-  INVERTER_TYPE_UNSPECIFIED = 0;
+// Microgrid electrical component details.
+message Component {
+  // The component ID.
+  uint64 id = 1;
 
-  // Battery inverter.
-  INVERTER_TYPE_BATTERY = 1;
+  // Unique identifier of the parent microgrid_id.
+  uint64 microgrid_id = 2;
 
-  // Solar inverter.
-  INVERTER_TYPE_SOLAR = 2;
+  // The component name.
+  string name = 3;
 
-  // Hybrid inverter.
-  INVERTER_TYPE_HYBRID = 3;
-}
+  // The component category. E.g., Inverter, Battery, etc.
+  ComponentCategory category = 4;
+
+  // The metadata specific to the component category type.
+  ComponentCategoryMetadataVariant category_type = 5;
 
-// Enumerated EV charger types.
-enum EvChargerType {
-  // Default type.
-  EV_CHARGER_TYPE_UNSPECIFIED = 0;
+  // The component manufacturer.
+  string manufacturer = 6;
 
-  // The EV charging station supports AC charging only.
-  EV_CHARGER_TYPE_AC = 1;
+  // The model name of the component.
+  string model_name = 7;
 
-  // The EV charging station supports DC charging only.
-  EV_CHARGER_TYPE_DC = 2;
+  // The status of the component.
+  ComponentStatus status = 8;
 
-  // The EV charging station supports both AC and DC.
-  EV_CHARGER_TYPE_HYBRID = 3;
+  // The operational lifetime of the component.
+  frequenz.api.common.v1.microgrid.Lifetime operational_lifetime = 9;
+}
+
+// ComponentConnection describes a single electrical link between two components
+// within a microgrid, effectively representing the physical wiring as viewed
+// from the grid connection point, if one exists, or from the islanding point,
+// in case of an islanded microgrids.
+//
+// !!! note "Physical Representation"
+//     This message is not about data flow but rather about the physical
+//     electrical connections between components. Therefore, the IDs for the
+//     source and destination components correspond to the actual setup within
+//     the microgrid.
+//
+// !!! note "Direction"
+//     The direction of the connection follows the flow of current away from the
+//     grid connection point, or in case of islands, away from the islanding
+//     point. This direction is aligned with positive current according to the
+//     [Passive Sign Convention]
+//     (https://en.wikipedia.org/wiki/Passive_sign_convention).
+//
+// !!! info "Historical Data"
+//     The timestamps of when a connection was created and terminated allows for
+//     tracking the changes over time to a microgrid, providing insights into
+//     when and how the microgrid infrastructure has been modified.
+//
+message ComponentConnection {
+  // Unique identifier of the component where the connection originates. This is
+  // aligned with the direction of current flow away from the grid connection
+  // point, or in case of islands, away from the islanding point.
+  uint64 source_component_id = 1;
+
+  // Unique ID of the component where the connection terminates. This is the
+  // component towards which the current flows.
+  uint64 destination_component_id = 2;
+
+  // The operational lifetime of the connection.
+  frequenz.api.common.v1.microgrid.Lifetime operational_lifetime = 3;
 }
 
 // ComponentData message aggregates multiple metrics, operational states, and

proto/frequenz/api/common/v1/microgrid/components/ev_charger.proto

@@ -0,0 +1,32 @@
+// Frequenz definitions for EV chargers.
+//
+// Copyright:
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.microgrid.components;
+
+// Enumerated EV charger types.
+enum EvChargerType {
+  // Default type.
+  EV_CHARGER_TYPE_UNSPECIFIED = 0;
+
+  // The EV charging station supports AC charging only.
+  EV_CHARGER_TYPE_AC = 1;
+
+  // The EV charging station supports DC charging only.
+  EV_CHARGER_TYPE_DC = 2;
+
+  // The EV charging station supports both AC and DC.
+  EV_CHARGER_TYPE_HYBRID = 3;
+}
+
+// A representation of an EV chaging station.
+message EvCharger {
+  // The EV charger type.
+  EvChargerType type = 1;
+}

proto/frequenz/api/common/v1/microgrid/components/fuse.proto

@@ -0,0 +1,26 @@
+// Frequenz definitions for electrical fuses.
+//
+// Copyright:
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.microgrid.components;
+
+// A representation of a fuse.
+// The fuse component represents a fuse in the microgrid. It is used to protect
+// components from overcurrents.
+message Fuse {
+  // The rated current of the fuse in amperes.
+  // This is the maximum current that the fuse can withstand for a long time.
+  // This limit applies to currents both flowing in or out of each of the 3
+  // phases individually.
+  //
+  // In other words, a current _i_ A at one of the phases of the node must
+  // comply with the following constraint:
+  // `-rated_fuse_current <= i <= rated_fuse_current`
+  uint32 rated_current = 1;
+}

proto/frequenz/api/common/v1/microgrid/components/grid.proto

@@ -0,0 +1,46 @@
+// Frequenz definitions for grid connection points.
+//
+// Copyright:
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.microgrid.components;
+
+// A representation of a grid connection point. This is the point where a
+// microgrid connects to the grid.
+//
+// The terms "Grid Connection Point" and "Point of Common Coupling" (PCC) are
+// commonly used in the context.
+//
+// While both terms describe a connection point to the grid, the
+// `GridConnectionPoint` is specifically the physical connection point of the
+// generation facility to the grid, often concerned with the technical and
+// ownership aspects of the connection.
+//
+// In contrast, the PCC is is more specific in terms of electrical engineering.
+// It refers to the point where a customer's local electrical system (such as a
+// microgrid) connects to the utility distribution grid in such a way that it
+// can affect other customers’ systems connected to the same network. It is the
+// point where the grid and customer's electrical systems interface and where
+// issues like power quality and supply regulations are assessed.
+//
+// The term `GridConnectionPoint` is used to make it clear that what is referred
+// to here is the physical connection point of the local facility to the grid.
+// Note that this may also be the PCC in some cases.
+message GridConnectionPoint {
+  // This refers to the maximum amount of electrical current, in amperes, that a
+  // fuse at the grid connection point is designed to safely carry under normal
+  // operating conditions.
+  //
+  // This limit applies to currents both flowing in or out of each of the 3
+  // phases individually.
+  //
+  // In other words, a current _i_ A at one of the phases of the grid connection
+  // point must comply with the following constraint:
+  // `-rated_fuse_current <= i <= rated_fuse_current`
+  uint32 rated_fuse_current = 1;
+}