Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Name changes & documentation updates #64

Merged
merged 9 commits into from
Sep 11, 2023
Merged

Name changes & documentation updates #64

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
8bb6bbb
Support filtering by `is_active` and `is_dry_run` statuses
stefan-brus-frequenz Sep 8, 2023
678a892
Enhance documentation of `active` and `dry_run` statuses.
stefan-brus-frequenz Sep 8, 2023
6b9bb27
Rename service to `MicrogridDispatchService`
stefan-brus-frequenz Sep 8, 2023
050c2da
Update the proto documentation header
stefan-brus-frequenz Sep 8, 2023
f850e76
Clarify timestamp docs, that timestamps are all in UTC.
stefan-brus-frequenz Sep 8, 2023
17a44a9
Rename DispatchComponentSelector & DispatchComponentIDs
stefan-brus-frequenz Sep 8, 2023
6f4029c
Move protolint directive to the top
stefan-brus-frequenz Sep 8, 2023
bd76597
Update release notes
stefan-brus-frequenz Sep 8, 2023
727c554
Bump pytest from 7.4.0 to 7.4.2
dependabot[bot] Sep 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 29 additions & 8 deletions proto/frequenz/dispatch/v1/dispatch.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to emphasize this, sadly the file-level documentation is not rendered at all. Since this is very important info it would be nice to include it somewhere else. Maybe as part of the service MicrogridDispatchService block documentation?

@thomas-nicolai-frequenz FYI for when you create new issues with specs for new APIs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created a separate issue for this: #67

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool, thanks!

//
// Copyright:
// Copyright 2022 Frequenz Energy-as-a-Service GmbH
Expand All @@ -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);
Expand Down