Merge v0.6.3 into v0.6.x (#286)

Author: tiyash-basu-frequenz

.github/workflows/ci.yaml

@@ -37,13 +37,13 @@ jobs:
         # Only use hashes here, as we are passing the github token, we want to
         # make sure updates are done consciously to avoid security issues if the
         # action repo gets hacked
-        uses: yoheimuta/action-protolint@a7c658b971a0874e120e046edb6fd137fdbc92a7 # v1.1.0
+        uses: yoheimuta/action-protolint@e62319541dc5107df5e3a5010acb8987004d3d25 # v1.3.0
         with:
           fail_on_error: true
           filter_mode: nofilter
           github_token: ${{ secrets.github_token }}
           protolint_flags: proto/
-          protolint_version: "0.45.0"
+          protolint_version: "0.50.5"
           reporter: github-check
 
   nox:

.github/workflows/release-notes-check.yml

@@ -20,7 +20,7 @@ jobs:
     steps:
       - name: Check for a release notes update
         if: github.event_name == 'pull_request'
-        uses: brettcannon/check-for-changed-files@4170644959a21843b31f1181f2a1761d65ef4791 # v1.2.0
+        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1
         with:
           file-pattern: "RELEASE_NOTES.md"
           prereq-pattern: "{proto,py}/**"

MANIFEST.in

@@ -6,7 +6,7 @@ exclude CODEOWNERS
 exclude CONTRIBUTING.md
 exclude mkdocs.yml
 exclude noxfile.py
-exclude src/conftest.py
+exclude py/frequenz/api/common/conftest.py
 recursive-exclude .github *
 recursive-exclude benchmarks *
 recursive-exclude docs *

RELEASE_NOTES.md

@@ -4,6 +4,23 @@
 
 - Added message linking microgrid and sensor IDs.
 
+- Update of the `PaginationParams` struct.
+
+## Upgrading
+
+- `PaginationParams` has been changed so that the `page_size` and `page_token`
+  fields are now mutually exclusive.
+
+- A new component category `COMPONENT_CATEGORY_HVAC` has been added to the API
+  to represent HVAC (Heating, Ventilation, and Air Conditioning) systems.
+
+- Additional information for energy metric
+
+- Generalize Energy message documentation for broader market use
+
+- Add Power message to represent Power in MW
+
 ## Bug Fixes
 
 - Fix a dependency issue by pinning the `grpcio` version and related libraries.
+- Fixed a wrong documentation comment for `COMPONENT_CATEGORY_UNSPECIFIED`.

proto/frequenz/api/common/v1/market/energy.proto

@@ -1,4 +1,4 @@
-// Frequenz definitions of energy for electricity trading.
+// Frequenz definitions of energy.
 //
 // Copyright 2023 Frequenz Energy-as-a-Service GmbH
 //
@@ -14,11 +14,11 @@ import "frequenz/api/common/v1/types/decimal.proto";
 // Represents a single unit of electricity.
 //
 // !!! note
-//     In these trading orders, the unit of energy is denominated in MWh
-//     (Megawatt-hours) as opposed to MW (Megawatts).  MWh is a unit of energy
-//     representing total output over a period, while MW is a unit of power that
-//     represents the rate of energy production or consumption.
+//     The unit of energy is denominated in MWh, which is a unit of energy
+//     representing total output over a period.(Megawatt-hours). This differs
+//     from MW (Megawatts), a unit of power representing the rate of energy
+//     production or consumption.
 message Energy {
-  // Represents energy unit in Megawatthours (MWh).
+  // Energy unit in Megawatthours (MWh).
   frequenz.api.common.v1.types.Decimal mwh = 1;
 }

proto/frequenz/api/common/v1/market/power.proto

@@ -0,0 +1,30 @@
+// Frequenz definitions of power.
+//
+// Copyright 2024 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.market;
+
+import "frequenz/api/common/v1/types/decimal.proto";
+
+// Represents a single unit of power.
+//
+// !!! note
+//     The power unit is denominated in MW (Megawatts), which is a unit of
+//     power representing the rate of energy production or consumption at any
+//     given moment. This differs from MWh (Megawatt-hours), which measures
+//     the total amount of energy delivered or consumed over a period.
+//
+// Example:
+//     A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
+//
+// This message standardizes the representation of power in MW across all
+// market applications.
+message Power {
+  // Power amount in Megawatts (MW).
+  frequenz.api.common.v1.types.Decimal mw = 1;
+}

proto/frequenz/api/common/v1/metrics/metric_sample.proto

@@ -63,6 +63,20 @@ message MetricValueVariant {
 }
 
 // List of supported metrics.
+//
+// !!! note
+// AC energy metrics information:
+//
+// * This energy metric is reported directly from the component, and not a
+//  result of aggregations in our systems. If a component does not have this
+//  metric, this field cannot be populated.
+//
+//  * Components that provide energy metrics reset this metric from time to
+//  time. This behaviour is specific to each component model. E.g., some
+//  components reset it on UTC 00:00:00.
+//
+//  * This energy metric does not specify the timestamp since when the energy
+//  was being accumulated, and therefore can be inconsistent.
 enum Metric {
   // Default value.
   METRIC_UNSPECIFIED = 0;

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

@@ -24,8 +24,7 @@ import "google/protobuf/timestamp.proto";
 
 // Enumrated component categories.
 enum ComponentCategory {
-  // An unknown component categories, useful for error handling, and marking
-  // unknown components in a list of components with otherwise known categories.
+  // The component category is unspecified. This should not be used.
   COMPONENT_CATEGORY_UNSPECIFIED = 0;
 
   // The point where the local microgrid is connected to the grid.

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

@@ -15,14 +15,27 @@ import "google/protobuf/timestamp.proto";
 // a microgrid asset, such as a component, connection, sensor, or any other
 // entity with a limited operational lifetime.
 //
-// !!! warning "Permanent Deletion"
-//     The `end_timestamp` indicates that the asset has been permanently removed
-//     from the system.
+// It is normally used to track the historical evolution of assets, and it
+// determines the validity period for the asset's data.
 //
+// If the `start_timestamp` is not set, the asset is considered to be in
+// operation since the beginning of the system's operational history.
+//
+// If the `end_timestamp` is not set, the asset is considered to be in
+// operation indefinitely into the future.
+//
+// If the Lifetime message is completely missing, it means both timestamps are
+// not set, which means the asset is considered to be in operation since the
+// beginning of the system's operational history and indefinitely into the
+// future.
 message Lifetime {
   // The timestamp when the asset became operationally active.
+  // If not set, the asset is considered to be in operation since the beginning
+  // of the system's operational history.
   google.protobuf.Timestamp start_timestamp = 1;
 
   // Optional timestamp when the asset's operational activity ceased.
+  // If not set, the asset is considered to be in operation indefinitely into
+  // the future.
   google.protobuf.Timestamp end_timestamp = 2;
 }

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

@@ -51,9 +51,15 @@ message Microgrid {
 
   // The delivery area where the microgrid is located, as identified by a
   // specific code.
+  //
+  // If a microgrid is not connected to the grid (it is an island) it does not
+  // belong to any delivery area and this field will be missing, but it could
+  // be missing for other reasons as well.
   frequenz.api.common.v1.grid.DeliveryArea delivery_area = 4;
 
   // Physical location of the microgrid, in geographical co-ordinates.
+  //
+  // If the location is not known, this field will be missing.
   frequenz.api.common.v1.Location location = 5;
 
   // The current status of the microgrid.