From 8bb6bbbabc85f7bfb5889f1625fa939fb24e6e0b Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 10:54:46 +0200 Subject: [PATCH 1/9] Support filtering by `is_active` and `is_dry_run` statuses Fixes #58 Signed-off-by: Stefan Brus --- proto/frequenz/dispatch/v1/dispatch.proto | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proto/frequenz/dispatch/v1/dispatch.proto b/proto/frequenz/dispatch/v1/dispatch.proto index 3bf3774..3e0016c 100644 --- a/proto/frequenz/dispatch/v1/dispatch.proto +++ b/proto/frequenz/dispatch/v1/dispatch.proto @@ -226,6 +226,14 @@ message DispatchFilter { // If no interval is provided, all dispatches starting from the // current timestamp will be included. TimeIntervalFilter time_interval = 2; + + // Filter by active status + // If this field is not set, dispatches of any active status will be included. + optional bool is_active = 3; + + // Filter by dry run status + // If this field is not set, dispatches of any dry run status will be included. + optional bool is_dry_run = 4; } // A list of dispatches From 678a892e4185bd157ba6d093c220370d8aa19444 Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 10:58:19 +0200 Subject: [PATCH 2/9] Enhance documentation of `active` and `dry_run` statuses. Fixes #59 Signed-off-by: Stefan Brus --- proto/frequenz/dispatch/v1/dispatch.proto | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/proto/frequenz/dispatch/v1/dispatch.proto b/proto/frequenz/dispatch/v1/dispatch.proto index 3e0016c..148094b 100644 --- a/proto/frequenz/dispatch/v1/dispatch.proto +++ b/proto/frequenz/dispatch/v1/dispatch.proto @@ -71,9 +71,19 @@ message Dispatch { DispatchComponentSelector selector = 8; // The "active" status + // An active dispatch is eligible for processing, either immediately or at a scheduled + // time in the future, including recurring dispatches. If a dispatch is set to + // inactive, it won't be processed even if it matches all other conditions, allowing + // for temporary disabling of dispatches without deletion. bool is_active = 9; // The "dry run" status + // A dry run dispatch is executed for logging and monitoring purposes + // without affecting the microgrid components. This is useful, for example, + // in scenarios where a user may want to test dispatch behavior without + // actually affecting any component states. + // Notably, a dispatch can be both "dry run" and "active," allowing for + // the system to generate logs and observe behavior without making actual changes. bool is_dry_run = 10; // The dispatch payload From 6b9bb2781a6c02f0fba690e4bd16460b10e90d56 Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 11:02:08 +0200 Subject: [PATCH 3/9] Rename service to `MicrogridDispatchService` Fixes #60 Signed-off-by: Stefan Brus --- proto/frequenz/dispatch/v1/dispatch.proto | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/proto/frequenz/dispatch/v1/dispatch.proto b/proto/frequenz/dispatch/v1/dispatch.proto index 148094b..8720757 100644 --- a/proto/frequenz/dispatch/v1/dispatch.proto +++ b/proto/frequenz/dispatch/v1/dispatch.proto @@ -21,22 +21,27 @@ import "google/protobuf/timestamp.proto"; import "frequenz/api/common/components.proto"; -// Service providing operations related to dispatching microgrid components. -service DispatchService { +// The MicrogridDispatchService serves to automate the process of energy dispatches for various microgrids. +// In the context of the energy industry, a 'dispatch' refers to the act of routing electrical power +// or energy between different components within a microgrid or between a microgrid and the main grid. +// This could be for the purpose of supply (sending energy to the grid, or to components within the microgrid), +// or demand (drawing energy from the grid or from other components like batteries and solar arrays). +// The service allows for both one-off dispatches, and recurring dispatches. +service MicrogridDispatchService { // Returns a list of all dispatches - rpc ListDispatches(DispatchListRequest) returns (DispatchList); + rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList); // Create a new dispatch - rpc CreateDispatch(DispatchCreateRequest) returns (google.protobuf.Empty); + rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty); // Update a dispatch - rpc UpdateDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty); + rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty); // Get a single dispatch - rpc GetDispatch(DispatchGetRequest) returns (Dispatch); + rpc GetMicrogridDispatch(DispatchGetRequest) returns (Dispatch); // Delete a given dispatch - rpc DeleteDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty); + rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty); } // Message representing one dispatch From 050c2dafa83c16120f6e6cf809b19f796808e14f Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 13:27:22 +0200 Subject: [PATCH 4/9] Update the proto documentation header Fixes #60 Signed-off-by: Stefan Brus --- proto/frequenz/dispatch/v1/dispatch.proto | 37 ++++++++++++++++++----- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/proto/frequenz/dispatch/v1/dispatch.proto b/proto/frequenz/dispatch/v1/dispatch.proto index 8720757..b570f66 100644 --- a/proto/frequenz/dispatch/v1/dispatch.proto +++ b/proto/frequenz/dispatch/v1/dispatch.proto @@ -1,6 +1,32 @@ -// Frequenz Dispatch API +// Frequenz Dispatch Automation API // -// Frequenz gRPC API to propagate dispatches to microgrids +// Overview: +// The API serves to automate the process of electricity dispatches for microgrids. +// In the context of the energy industry, a 'dispatch' refers to the act of routing electrical power +// between different components within a microgrid or between a microgrid and the main grid. +// This could be for the purpose of supply (sending electricity to the grid or components within the microgrid), +// or demand (drawing electricity from the grid or from other components like batteries and solar arrays). +// +// Objective: +// The primary objective of this API is to streamline and automate the complex task of electricity dispatching, +// making it easier to manage local electricity supply and demand efficiently. +// +// Key Features: +// - Dispatching Electricity: Comprehensive CRUD operations for dispatching microgrid components. +// - Automation: Support for one-time as well as recurring dispatches based on flexible recurrence rules. +// - Fine-grained control: Dispatch individual microgrid components or entire component categories. +// +// Example Use Cases: +// - Charging or discharging a battery based on optimal time-of-use rates. +// - Limiting the output of a Photovoltaic (PV) array during periods of low demand. +// - Invoking Frequency Containment Reserves (FCR) or Automatic Frequency Restoration Reserves (aFRR) to +// support grid operations. +// - Adjusting the output of electric vehicle charging stations to match grid availability or to avoid peak pricing. +// +// Target Audience: +// This API is designed for application developers in the energy sector who focus on the tasks of optimizing microgrid +// electricity flows. Its design aims to be as developer-friendly as possible, requiring no prior knowledge in +// electrical engineering and systems. // // Copyright: // Copyright 2022 Frequenz Energy-as-a-Service GmbH @@ -21,12 +47,7 @@ import "google/protobuf/timestamp.proto"; import "frequenz/api/common/components.proto"; -// The MicrogridDispatchService serves to automate the process of energy dispatches for various microgrids. -// In the context of the energy industry, a 'dispatch' refers to the act of routing electrical power -// or energy between different components within a microgrid or between a microgrid and the main grid. -// This could be for the purpose of supply (sending energy to the grid, or to components within the microgrid), -// or demand (drawing energy from the grid or from other components like batteries and solar arrays). -// The service allows for both one-off dispatches, and recurring dispatches. +// Service providing operations related to dispatching microgrid components. service MicrogridDispatchService { // Returns a list of all dispatches rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList); From f850e7607aa2b536a1db2b84a5d1e5ca65f8d0e1 Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 11:07:04 +0200 Subject: [PATCH 5/9] Clarify timestamp docs, that timestamps are all in UTC. Fixes #61 Signed-off-by: Stefan Brus --- proto/frequenz/dispatch/v1/dispatch.proto | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/proto/frequenz/dispatch/v1/dispatch.proto b/proto/frequenz/dispatch/v1/dispatch.proto index b570f66..39ca86b 100644 --- a/proto/frequenz/dispatch/v1/dispatch.proto +++ b/proto/frequenz/dispatch/v1/dispatch.proto @@ -65,7 +65,10 @@ service MicrogridDispatchService { rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty); } -// Message representing one dispatch +// Message representing one dispatch. +// +// Timezone Note: Timestamps are in UTC. It is the responsibility of each microgrid to translate UTC +// to its local timezone. message Dispatch { // The dispatch identifier uint64 id = 1; @@ -79,18 +82,18 @@ message Dispatch { // understanding and processing this field. string type = 3; - // The creation time + // The creation time in UTC // This is set when a dispatch is created via the create request message google.protobuf.Timestamp create_time = 4; - // The update time + // The update time in UTC // This is set when a dispatch is modified via the update request message google.protobuf.Timestamp update_time = 5; - // The start time + // The start time in UTC google.protobuf.Timestamp start_time = 6; - // The end time + // The end time in UTC google.protobuf.Timestamp end_time = 7; // The component selector @@ -152,7 +155,10 @@ message DispatchComponentIDs { repeated uint64 component_ids = 1; } -// Ruleset governing when and how a dispatch should re-occur +// Ruleset governing when and how a dispatch should re-occur. +// +// Timezone Note: Timestamps are in UTC. It is the responsibility of each microgrid to translate UTC +// to its local timezone. // // This definition tries to adhere closely to the iCalendar specification (RFC 5545), // particularly for recurrence rules. For advanced use-cases or further clarifications, From 17a44a927f41bfdad7cec395086789d2b8b21aa5 Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 11:09:22 +0200 Subject: [PATCH 6/9] Rename DispatchComponentSelector & DispatchComponentIDs Fixes #62 Signed-off-by: Stefan Brus --- proto/frequenz/dispatch/v1/dispatch.proto | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proto/frequenz/dispatch/v1/dispatch.proto b/proto/frequenz/dispatch/v1/dispatch.proto index 39ca86b..0b1843b 100644 --- a/proto/frequenz/dispatch/v1/dispatch.proto +++ b/proto/frequenz/dispatch/v1/dispatch.proto @@ -97,7 +97,7 @@ message Dispatch { google.protobuf.Timestamp end_time = 7; // The component selector - DispatchComponentSelector selector = 8; + ComponentSelector selector = 8; // The "active" status // An active dispatch is eligible for processing, either immediately or at a scheduled @@ -139,18 +139,18 @@ message TimeIntervalFilter { // Parameter for controlling which components a dispatch applies to // Either a set of component IDs, or all components belonging to a category -message DispatchComponentSelector { +message ComponentSelector { oneof selector { // Set of component IDs - DispatchComponentIDs dispatch_component_ids = 1; + ComponentIDs component_ids = 1; // Component category - frequenz.api.common.components.ComponentCategory dispatch_component_category = 2; + frequenz.api.common.components.ComponentCategory component_category = 2; } } // Wrapper for controlling dispatches with a set of component IDs -message DispatchComponentIDs { +message ComponentIDs { // Set of component IDs repeated uint64 component_ids = 1; } @@ -262,7 +262,7 @@ message DispatchListRequest { // Parameters for filtering the dispatch list message DispatchFilter { // Filter by component ID or category - repeated DispatchComponentSelector selectors = 1; + repeated ComponentSelector selectors = 1; // Filter by time interval // If no interval is provided, all dispatches starting from the @@ -302,7 +302,7 @@ message DispatchCreateRequest { google.protobuf.Timestamp end_time = 4; // The component selector - DispatchComponentSelector selector = 5; + ComponentSelector selector = 5; // The "active" status bool is_active = 6; @@ -332,7 +332,7 @@ message DispatchUpdateRequest { google.protobuf.Timestamp end_time = 3; // The component selector - DispatchComponentSelector selector = 4; + ComponentSelector selector = 4; // The "active" status optional bool is_active = 5; From 6f4029c7a6fc195205d4e3035875222538aa55a7 Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 13:31:00 +0200 Subject: [PATCH 7/9] Move protolint directive to the top Signed-off-by: Stefan Brus --- proto/frequenz/dispatch/v1/dispatch.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proto/frequenz/dispatch/v1/dispatch.proto b/proto/frequenz/dispatch/v1/dispatch.proto index 0b1843b..50e159a 100644 --- a/proto/frequenz/dispatch/v1/dispatch.proto +++ b/proto/frequenz/dispatch/v1/dispatch.proto @@ -1,3 +1,5 @@ +// protolint:disable MAX_LINE_LENGTH + // Frequenz Dispatch Automation API // // Overview: @@ -34,8 +36,6 @@ // License: // MIT -// protolint:disable MAX_LINE_LENGTH - syntax = "proto3"; package frequenz.dispatch.v1; From bd765975231751acfbb1cca6664a870cb073fbb4 Mon Sep 17 00:00:00 2001 From: Stefan Brus Date: Fri, 8 Sep 2023 13:33:29 +0200 Subject: [PATCH 8/9] Update release notes Signed-off-by: Stefan Brus --- RELEASE_NOTES.md | 41 +++++------------------------------------ 1 file changed, 5 insertions(+), 36 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 14a5f52..4d95551 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,48 +2,17 @@ ## Summary -This release is mainly about creating a ruleset for recurring dispatches. +This release is mainly about updating the names of some objects, and improving documentation. ## Upgrading -- As part of introducing versioning, the protobuf definitions and generated python code now has the path `frequenz.dispatch.v1`. +- Service and its methods have been renamed to `MicrogridDispatchService` +- `DispatchComponentSelector` has been renamed to `ComponentSelector` +- `DispatchComponentIDs` has been renamed to `ComponentIDs` ## New Features -- Package-based versioning has been introduced. -- Rules for recurring dispatches have been added. - Examples: - Every 6 months: - ``` - message RecurrenceRule { - Frequency freq = FREQUENCY_MONTHLY; - uint32 interval = 6; - } - ``` - - Weekends only: - ``` - message RecurrenceRule { - Frequency freq = FREQUENCY_WEEKLY; - repeated Weekday byweekdays = [WEEKDAY_SATURDAY, WEEKDAY_SUNDAY]; - } - ``` - - Every day at midnight: - ``` - message RecurrenceRule { - Frequency freq = FREQUENCY_DAILY; - repeated uint32 byhours = [0]; - } - ``` - - Nightly, assuming "night" means from 8 PM to 6 AM: - ``` - message RecurrenceRule { - Frequency freq = FREQUENCY_DAILY; - repeated uint32 byhours = [20, 21, 22, 23, 0, 1, 2, 3, 4, 5]; - } - ``` +- `DispatchFilter` now supports filtering by `is_active` and `is_dry_run` ## Bug Fixes From 727c554f8a04ddde3eabe61e0ea70fcd91ebe270 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 8 Sep 2023 07:55:16 +0000 Subject: [PATCH 9/9] Bump pytest from 7.4.0 to 7.4.2 Bumps [pytest](https://github.com/pytest-dev/pytest) from 7.4.0 to 7.4.2. - [Release notes](https://github.com/pytest-dev/pytest/releases) - [Changelog](https://github.com/pytest-dev/pytest/blob/main/CHANGELOG.rst) - [Commits](https://github.com/pytest-dev/pytest/compare/7.4.0...7.4.2) --- updated-dependencies: - dependency-name: pytest dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index b685b6d..e5a8ce5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -74,7 +74,7 @@ dev-pylint = [ "frequenz-api-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]", ] dev-pytest = [ - "pytest == 7.4.0", + "pytest == 7.4.2", "frequenz-repo-config[extra-lint-examples] == 0.5.2", ] dev = [