Skip to content

Commit e71a4de

Browse files
thomas-nicolai-frequenzthomas-nicolai-frequenz
authored
ListMicrogridElectricalComponentConnectionsRequest header doc changes (#95)
* Refined ListMicrogridElectricalComponentConnectionsRequest header documentation * Added new version v1alpha1 * Renamed service
2 parents 985d056 + 10ab710 commit e71a4de

3 files changed

Lines changed: 213 additions & 28 deletions

File tree

‎RELEASE_NOTES.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,15 @@
22

33
## Summary
44

5+
Documentation improvement
6+
Rename service
57

68
## Upgrading
79

8-
- Update the `frequenz-api-common` dependency
10+
- Improved ListMicrogridElectricalComponentConnectionsRequest header doc
11+
- Rename service
12+
- Introduced new version
913

1014
## New Features
1115

12-
16+
n/a

‎proto/frequenz/api/assets/v1/assets.proto‎

Lines changed: 25 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
// protolint:disable MAX_LINE_LENGTH
2-
31
// Frequenz Assets API
42
//
53
// Frequenz gRPC API to retrieval platform assets information.
@@ -14,25 +12,26 @@ syntax = "proto3";
1412

1513
package frequenz.api.assets.v1;
1614

15+
// protolint:disable:next MAX_LINE_LENGTH
1716
import "frequenz/api/common/v1alpha8/microgrid/electrical_components/electrical_components.proto";
1817
import "frequenz/api/common/v1alpha8/microgrid/microgrid.proto";
1918

20-
2119
// Service providing access to manage and retrieve information
2220
// related to gridpools and microgrids, and other platform assets.
2321
service PlatformAssets {
2422
// Returns details of a specific microgrid.
2523
rpc GetMicrogrid(GetMicrogridRequest) returns (GetMicrogridResponse);
2624

2725
// Returns list of a electrical components for a specific microgrid.
28-
rpc ListMicrogridElectricalComponents(ListMicrogridElectricalComponentsRequest)
26+
rpc ListMicrogridElectricalComponents(
27+
ListMicrogridElectricalComponentsRequest)
2928
returns (ListMicrogridElectricalComponentsResponse);
3029

3130
// Returns a list of the connections between electrical components for a
3231
// specific microgrid.
3332
rpc ListMicrogridElectricalComponentConnections(
34-
ListMicrogridElectricalComponentConnectionsRequest
35-
) returns (ListMicrogridElectricalComponentConnectionsResponse);
33+
ListMicrogridElectricalComponentConnectionsRequest)
34+
returns (ListMicrogridElectricalComponentConnectionsResponse);
3635
}
3736

3837
// GetMicrogridRequest is the input parameter for fetching details
@@ -59,7 +58,8 @@ message ListMicrogridElectricalComponentsRequest {
5958
repeated uint64 component_ids = 2;
6059

6160
// Return components that have the specified categories only.
62-
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.ElectricalComponentCategory categories = 3;
61+
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
62+
ElectricalComponentCategory categories = 3;
6363
}
6464

6565
// A message containing a list of electrical components.
@@ -68,31 +68,29 @@ message ListMicrogridElectricalComponentsResponse {
6868
uint64 microgrid_id = 1;
6969

7070
// List of electrical components matching the filter criteria.
71-
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.ElectricalComponent components = 2;
71+
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
72+
ElectricalComponent components = 2;
7273
}
7374

74-
// ListMicrogridElectricalComponentConnectionsRequest is used for filtering and listing
75-
// the electrical connections between components in a specific microgrid.
76-
// These connections can be used to construct a component graph of the
77-
// microgrid.
78-
//
75+
// ListMicrogridElectricalComponentConnectionsRequest is used for listing
76+
// the electrical connections between components in a microgrid. Connections
77+
// define a directed graph of electrical energy flow.
7978
//
8079
// !!! note "Component Graph"
81-
// A component graph in the context of a microgrid refers to a directed graph
82-
// where the nodes represent electrical components (like generators, batteries,
83-
// or loads) and the edges represent electrical connections between them.
84-
// The edges are directional, pointing away from the grid-connection point
85-
// (or the root point for island microgrids).
80+
// A component graph in the context of a microgrid refers to a directed
81+
// graph where the nodes represent electrical components (like
82+
// generators, batteries, or loads) and the edges represent electrical
83+
// connections between them. The edges are directional, pointing away
84+
// from the grid-connection point (or the root point for island microgrids).
8685
// This means that for each edge, the source component is towards the grid
8786
// connection point, and the destination component is pointing towards
88-
// an underlying component.
89-
// This graph provides a structured view of how electrical energy flows within
90-
// the microgrid.
87+
// an underlying component. This graph provides a structured view of how
88+
// electrical energy flows within the microgrid.
9189
//
9290
// !!! note "Filtering"
9391
// Filtering can be done based on the source_component_id or
94-
// destination_component_id. If these fields are left empty, connections with
95-
// any source or destination will be returned.
92+
// destination_component_id. If these fields are left empty, connections
93+
// with any source or destination will be returned.
9694
//
9795
message ListMicrogridElectricalComponentConnectionsRequest {
9896
// Mandatory field. The ID of the microgrid
@@ -108,13 +106,14 @@ message ListMicrogridElectricalComponentConnectionsRequest {
108106
repeated uint64 destination_component_ids = 3;
109107
}
110108

111-
// ListMicrogridElectricalComponentConnectionsResponse holds the list of electrical
112-
// connections that match the filter criteria specified in the
109+
// ListMicrogridElectricalComponentConnectionsResponse holds the list of
110+
// electrical connections that match the filter criteria specified in the
113111
// ListMicrogridElectricalComponentConnectionsRequest.
114112
message ListMicrogridElectricalComponentConnectionsResponse {
115113
// The ID of the microgrid for which connections are returned.
116114
uint64 microgrid_id = 1;
117115

118116
// Contains the list of connections that match the filtering criteria.
119-
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.ElectricalComponentConnection connections =2;
117+
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
118+
ElectricalComponentConnection connections =2;
120119
}

‎proto/frequenz/api/platformassets/v1alpha1/platformassets.proto‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
// Frequenz Assets API
2+
//
3+
// Frequenz gRPC API to retrieval platform assets information.
4+
//
5+
// Copyright:
6+
// Copyright 2025 Frequenz Energy-as-a-Service GmbH
7+
//
8+
// License:
9+
// MIT
10+
11+
syntax = "proto3";
12+
13+
package frequenz.api.platformassets.v1alpha1;
14+
15+
// protolint:disable:next MAX_LINE_LENGTH
16+
import "frequenz/api/common/v1alpha8/microgrid/electrical_components/electrical_components.proto";
17+
import "frequenz/api/common/v1alpha8/microgrid/microgrid.proto";
18+
19+
// PlatformAssetsService provides read-only access to platform asset metadata.
20+
//
21+
// The service exposes technical asset information required by downstream
22+
// services and applications, including microgrid metadata, electrical
23+
// component inventories, and the directed electrical component graph within a
24+
// microgrid.
25+
//
26+
// Platform assets describe the technical structure of a deployed or planned
27+
// microgrid. They are commonly used by reporting, forecasting, monitoring,
28+
// trading, optimization, and operational tooling to resolve stable asset
29+
// identifiers into their associated metadata.
30+
//
31+
// !!! important "Authentication"
32+
// All requests to FlexMarketService must be signed. The key identifier and
33+
// signature must be included in the request metadata (gRPC metadata /
34+
// HTTP headers). The signature must be computed using the HMAC-SHA256
35+
// algorithm and secret key. All requests to this service must be made
36+
// over TLS (HTTPS).
37+
//
38+
service PlatformAssetsService {
39+
// Returns metadata for a specific microgrid.
40+
rpc GetMicrogrid(GetMicrogridRequest) returns (GetMicrogridResponse);
41+
42+
// Lists electrical components for a specific microgrid.
43+
rpc ListMicrogridElectricalComponents(
44+
ListMicrogridElectricalComponentsRequest)
45+
returns (ListMicrogridElectricalComponentsResponse);
46+
47+
// Lists directed electrical connections between components in a specific
48+
// microgrid.
49+
rpc ListMicrogridElectricalComponentConnections(
50+
ListMicrogridElectricalComponentConnectionsRequest)
51+
returns (ListMicrogridElectricalComponentConnectionsResponse);
52+
}
53+
54+
// Filters for selecting electrical component connections in a microgrid.
55+
//
56+
// A connection must match all specified filter fields to be included in the
57+
// response.
58+
//
59+
// !!! note "Filter Semantics"
60+
// Each repeated field is evaluated using logical OR.
61+
//
62+
// Different filter fields are combined using logical AND.
63+
//
64+
// If no filters are provided, all known electrical connections in the
65+
// microgrid are returned.
66+
//
67+
message MicrogridElectricalComponentConnectionsFilter {
68+
// Optional. Return only connections whose source component ID is included in
69+
// this list.
70+
//
71+
// If empty, connections from any source component are returned.
72+
repeated uint64 source_component_ids = 1;
73+
74+
// Optional. Return only connections whose destination component ID is
75+
// included in this list.
76+
//
77+
// If empty, connections to any destination component are returned.
78+
repeated uint64 destination_component_ids = 2;
79+
}
80+
81+
// Filters for selecting electrical components in a microgrid.
82+
//
83+
// An electrical component must match all specified filter fields to be
84+
// included in the response.
85+
//
86+
// !!! note "Filter Semantics"
87+
// Each repeated field is evaluated using logical OR.
88+
//
89+
// Different filter fields are combined using logical AND.
90+
//
91+
// If no filters are provided, all electrical components in the microgrid
92+
// are returned.
93+
//
94+
message MicrogridElectricalComponentsFilter {
95+
// Optional. Return only components whose IDs are included in this list.
96+
//
97+
// If empty, no component-ID filtering is applied.
98+
repeated uint64 component_ids = 1;
99+
100+
// Optional. Return only components whose categories are included in this
101+
// list.
102+
//
103+
// If empty, no category filtering is applied.
104+
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
105+
ElectricalComponentCategory categories = 2;
106+
}
107+
108+
// Request message for retrieving metadata for a specific microgrid.
109+
message GetMicrogridRequest {
110+
// The unique identifier of the microgrid for which to fetch details.
111+
uint64 microgrid_id = 1;
112+
}
113+
114+
// Response message containing metadata for a specific microgrid.
115+
message GetMicrogridResponse {
116+
// Details of the requested microgrid.
117+
frequenz.api.common.v1alpha8.microgrid.Microgrid microgrid = 1;
118+
}
119+
120+
// Request parameters for the RPC `ListMicrogridElectricalComponents`.
121+
message ListMicrogridElectricalComponentsRequest {
122+
// Mandatory field. The ID of the microgrid for which components
123+
// are to be listed.
124+
uint64 microgrid_id = 1;
125+
126+
// Optional. Filtering criteria for narrowing the returned components.
127+
//
128+
// If omitted, all electrical components in the microgrid are returned.
129+
MicrogridElectricalComponentsFilter filter = 2;
130+
}
131+
132+
// Response message containing electrical components for a microgrid.
133+
message ListMicrogridElectricalComponentsResponse {
134+
// The unique identifier of the microgrid the returned components belong to.
135+
uint64 microgrid_id = 1;
136+
137+
// Electrical components matching the request filters.
138+
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
139+
ElectricalComponent components = 2;
140+
}
141+
142+
// Request message for listing directed electrical connections between
143+
// components in a microgrid.
144+
//
145+
// Connections define the directed electrical component graph of a microgrid.
146+
// The source component is closer to the grid-connection point or logical root,
147+
// while the destination component is further downstream.
148+
//
149+
// !!! note "Component Graph"
150+
// A component graph in the context of a microgrid refers to a directed
151+
// graph where the nodes represent electrical components (like
152+
// generators, batteries, or loads) and the edges represent electrical
153+
// connections between them. The edges are directional, pointing away
154+
// from the grid-connection point (or the root point for island microgrids).
155+
// This means that for each edge, the source component is towards the grid
156+
// connection point, and the destination component is pointing towards
157+
// an underlying component. This graph provides a structured view of how
158+
// electrical energy flows within the microgrid.
159+
//
160+
message ListMicrogridElectricalComponentConnectionsRequest {
161+
// The unique identifier of the microgrid whose electrical component
162+
// connections should be listed.
163+
uint64 microgrid_id = 1;
164+
165+
// Optional filtering criteria for narrowing the returned connections.
166+
//
167+
// If omitted, all known electrical connections in the microgrid are returned.
168+
MicrogridElectricalComponentConnectionsFilter filter = 2;
169+
}
170+
171+
// Response message containing directed electrical connections for a microgrid.
172+
//
173+
// The response contains all connections matching the requested filters. If no
174+
// connection matches the filters, `connections` is empty.
175+
message ListMicrogridElectricalComponentConnectionsResponse {
176+
// The unique identifier of the microgrid the returned connections belong to.
177+
uint64 microgrid_id = 1;
178+
179+
// Electrical component connections matching the request filters.
180+
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
181+
ElectricalComponentConnection connections = 2;
182+
}

0 commit comments

Comments
 (0)