Skip to content

Commit 95ccbde

Browse files
sandovalrrsandovalrr
authored
Merge pull request #9 from sandovalrr/docs/proto-draft-v1
feat(assets): defined the PlatformAssets service with microgrid and component APIs
2 parents e13b141 + 2f45586 commit 95ccbde

5 files changed

Lines changed: 134 additions & 29 deletions

File tree

‎RELEASE_NOTES.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,19 @@
22

33
## Summary
44

5-
<!-- Here goes a general summary of what this release is about -->
5+
- Setup the proto files for the Assets API.
6+
- Added the first version of the API, with the following RPCs:
7+
- `GetMicrogrid`
8+
- `ListMicrogridComponents`
9+
- `ListMicrogridComponentConnections`
610

711
## Upgrading
812

9-
<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
1013

1114
## New Features
1215

13-
<!-- Here goes the main new features and examples or instructions on how to use them -->
16+
- Added the first version of the Assets API.
17+
- Added the proto files to the Python package.
1418

1519
## Bug Fixes
1620

17-
<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

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

Lines changed: 0 additions & 23 deletions
This file was deleted.

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
// protolint:disable MAX_LINE_LENGTH
2+
3+
// Frequenz Assets API
4+
//
5+
// Frequenz gRPC API to retrieval platform assets information
6+
//
7+
// Copyright:
8+
// Copyright 2025 Frequenz Energy-as-a-Service GmbH
9+
//
10+
// License:
11+
// MIT
12+
13+
syntax = "proto3";
14+
15+
package frequenz.api.assets.v1;
16+
17+
import "frequenz/api/common/v1/microgrid/components/components.proto";
18+
import "frequenz/api/common/v1/microgrid/microgrid.proto";
19+
20+
// Service providing access to manage and retrieve information
21+
// related to gridpools and microgrids, and other platform assets.
22+
service PlatformAssets {
23+
// Returns details of a specific microgrid.
24+
rpc GetMicrogrid(GetMicrogridRequest) returns (GetMicrogridResponse);
25+
26+
// Returns list of a electrical components for a specific microgrid.
27+
rpc ListMicrogridComponents(ListMicrogridComponentsRequest)
28+
returns (ListMicrogridComponentsResponse);
29+
30+
31+
// Returns a list of the connections between electrical components for a
32+
// specific microgrid
33+
rpc ListMicrogridComponentConnections(
34+
ListMicrogridComponentConnectionsRequest
35+
) returns (ListMicrogridComponentConnectionsResponse);
36+
}
37+
38+
// GetMicrogridRequest is the input parameter for fetching details
39+
// given a specific microgrid.
40+
message GetMicrogridRequest {
41+
// The unique identifier of the microgrid for which to fetch details.
42+
uint64 microgrid_id = 1;
43+
}
44+
45+
// GetMicrogridResponse is the response for fetching details
46+
// given a specific microgrid.
47+
message GetMicrogridResponse {
48+
// Details of the requested microgrid.
49+
frequenz.api.common.v1.microgrid.Microgrid microgrid = 1;
50+
}
51+
52+
// Request parameters for the RPC `ListMicrogridComponents`.
53+
message ListMicrogridComponentsRequest {
54+
// Mandatory field. The ID of the microgrid for which components
55+
// are to be listed.
56+
uint64 microgrid_id = 1;
57+
58+
// Return components that have the specified IDs only.
59+
repeated uint64 component_ids = 2;
60+
61+
// Return components that have the specified categories only.
62+
repeated frequenz.api.common.v1.microgrid.components.ComponentCategory categories = 3;
63+
}
64+
65+
// A message containing a list of components.
66+
message ListMicrogridComponentsResponse {
67+
// Unique microgrid identifier used in the request.
68+
// Could be removed if the Component message would include the microgrid_id
69+
uint64 microgrid_id = 1;
70+
71+
// List of components matching the filter criteria.
72+
repeated frequenz.api.common.v1.microgrid.components.Component components = 2;
73+
}
74+
75+
// ListMicrogridComponentConnectionsRequest is used for filtering and listing
76+
// the electrical connections between components in a specific microgrid.
77+
// These connections can be used to construct a component graph of the
78+
// microgrid.
79+
//
80+
//
81+
// !!! note "Component Graph"
82+
// A component graph in the context of a microgrid refers to a directed graph
83+
// where the nodes represent electrical components (like generators, batteries,
84+
// or loads) and the edges represent electrical connections between them.
85+
// The edges are directional, pointing away from the grid-connection point
86+
// (or the root point for island microgrids).
87+
// This means that for each edge, the source component is towards the grid
88+
// connection point, and the destination component is pointing towards
89+
// an underlying component.
90+
// This graph provides a structured view of how electrical energy flows within
91+
// the microgrid.
92+
//
93+
// !!! note "Filtering"
94+
// Filtering can be done based on the source_component_id or
95+
// destination_component_id. If these fields are left empty, connections with
96+
// any source or destination will be returned.
97+
message ListMicrogridComponentConnectionsRequest {
98+
// Mandatory field. The ID of the microgrid
99+
// for which connections are to be listed.
100+
uint64 microgrid_id = 1;
101+
102+
// Only return connections that originate from these component IDs.
103+
// If empty, no filtering is applied.
104+
repeated uint64 source_component_ids = 2;
105+
106+
// Only return connections that terminate at these component IDs.
107+
// If empty, no filtering is applied.
108+
repeated uint64 destination_component_ids = 3;
109+
}
110+
111+
// ListMicrogridComponentConnectionsResponse
112+
// holds the list of electrical connections that match
113+
// the filter criteria specified in the ListConnectionsRequest.
114+
message ListMicrogridComponentConnectionsResponse {
115+
// The ID of the microgrid for which connections are to be listed.
116+
uint64 microgrid_id = 1;
117+
118+
// Contains the list of connections that match the filtering criteria.
119+
repeated frequenz.api.common.v1.microgrid.components.ComponentConnection connections =2;
120+
}

‎py/frequenz/api/assets/v1/__init__.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# License: MIT
2+
# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
3+
4+
"""Frequenz gRPC API to retrieval platform assets information.
5+
"""

‎pytests/test_assets.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@ def test_package_import() -> None:
1515
def test_module_import_components() -> None:
1616
"""Test that the modules can be imported."""
1717
# pylint: disable=import-outside-toplevel
18-
from frequenz.api.assets import assets_pb2
18+
from frequenz.api.assets.v1 import assets_pb2
1919

2020
assert assets_pb2 is not None
2121

2222
# pylint: disable=import-outside-toplevel
23-
from frequenz.api.assets import assets_pb2_grpc
23+
from frequenz.api.assets.v1 import assets_pb2_grpc
2424

2525
assert assets_pb2_grpc is not None

0 commit comments

Comments
 (0)