Skip to content

Commit 23a4bb7

Browse files
llucaxllucax
committed
Add backwards compatibility with v0.3.x
This release includes the top-level files present in the v0.3.x release, so the Microgrid API v0.15.x can depend on a newer version of the Common API. Signed-off-by: Leandro Lucarella <[email protected]>
1 parent 7997835 commit 23a4bb7

File tree

7 files changed

+589
-0
lines changed

7 files changed

+589
-0
lines changed

‎RELEASE_NOTES.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
## New Features
44

55
- Add a energy message for electricity trading markets
6+
- Add backwards compatibility with v0.3.x
7+
8+
This release includes the top-level files present in the v0.3.x release, so the Microgrid API v0.15.x can depend on a newer version of the Common API.

‎proto/frequenz/api/common/components.proto‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// Frequenz microgrid components definitions.
2+
//
3+
// Copyright:
4+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
5+
//
6+
// License:
7+
// MIT
8+
9+
syntax = "proto3";
10+
11+
package frequenz.api.common.components;
12+
13+
// Enumrated component categories.
14+
enum ComponentCategory {
15+
// An unknown component categories, useful for error handling, and marking
16+
// unknown components in a list of components with otherwise known categories.
17+
COMPONENT_CATEGORY_UNSPECIFIED = 0;
18+
19+
// The point where the local microgrid is connected to the grid.
20+
COMPONENT_CATEGORY_GRID = 1;
21+
22+
// A meter, for measuring electrical metrics, e.g., current, voltage, etc.
23+
COMPONENT_CATEGORY_METER = 2;
24+
25+
// An electricity generator, with batteries or solar energy.
26+
COMPONENT_CATEGORY_INVERTER = 3;
27+
28+
// A DC-DC converter.
29+
COMPONENT_CATEGORY_CONVERTER = 4;
30+
31+
// A storage system for electrical energy, used by inverters.
32+
COMPONENT_CATEGORY_BATTERY = 5;
33+
34+
// A station for charging electrical vehicles.
35+
COMPONENT_CATEGORY_EV_CHARGER = 6;
36+
37+
// A sensor for measuring ambient metrics, e.g., temperature, humidity, etc.
38+
COMPONENT_CATEGORY_SENSOR = 7;
39+
40+
// A crypto miner.
41+
COMPONENT_CATEGORY_CRYPTO_MINER = 8;
42+
43+
// An electrolyzer for converting water into hydrogen and oxygen.
44+
COMPONENT_CATEGORY_ELECTROLYZER = 9;
45+
46+
// A heat and power combustion plant (CHP stands for combined heat and power).
47+
COMPONENT_CATEGORY_CHP = 10;
48+
49+
// A relay.
50+
// Relays generally have two states: open (connected) and closed
51+
// (disconnected).
52+
// They are generally placed in front of a component, e.g., an inverter, to
53+
// control whether the component is connected to the grid or not.
54+
COMPONENT_CATEGORY_RELAY = 11;
55+
56+
// A precharge module.
57+
// Precharging involves gradually ramping up the DC voltage to prevent any
58+
// potential damage to sensitive electrical components like capacitors.
59+
// While many inverters and batteries come equipped with in-built precharging
60+
// mechanisms, some may lack this feature. In such cases, we need to use
61+
// external precharging modules.
62+
COMPONENT_CATEGORY_PRECHARGE_MODULE = 12;
63+
}
64+
65+
// Enumerated battery types.
66+
enum BatteryType {
67+
// Unspecified.
68+
BATTERY_TYPE_UNSPECIFIED = 0;
69+
70+
// Li-ion batteries.
71+
BATTERY_TYPE_LI_ION = 1;
72+
73+
// Sodium-ion batteries
74+
BATTERY_TYPE_NA_ION = 2;
75+
}
76+
77+
// Enumerated inverter types.
78+
enum InverterType {
79+
// Unspecified.
80+
INVERTER_TYPE_UNSPECIFIED = 0;
81+
82+
// Battery inverter.
83+
INVERTER_TYPE_BATTERY = 1;
84+
85+
// Solar inverter.
86+
INVERTER_TYPE_SOLAR = 2;
87+
88+
// Hybrid inverter.
89+
INVERTER_TYPE_HYBRID = 3;
90+
}
91+
92+
// Enumerated EV charger types.
93+
enum EvChargerType {
94+
// Default type.
95+
EV_CHARGER_TYPE_UNSPECIFIED = 0;
96+
97+
// The EV charging station supports AC charging only.
98+
EV_CHARGER_TYPE_AC = 1;
99+
100+
// The EV charging station supports DC charging only.
101+
EV_CHARGER_TYPE_DC = 2;
102+
103+
// The EV charging station supports both AC and DC.
104+
EV_CHARGER_TYPE_HYBRID = 3;
105+
}
106+
107+
// Enumerated sensor types.
108+
enum SensorType {
109+
// Unspecified
110+
SENSOR_TYPE_UNSPECIFIED = 0;
111+
112+
// Thermometer (temperature sensor)
113+
SENSOR_TYPE_THERMOMETER = 1;
114+
115+
// Hygrometer (humidity sensor)
116+
SENSOR_TYPE_HYGROMETER = 2;
117+
118+
// Barometer (pressure sensor).
119+
SENSOR_TYPE_BAROMETER = 3;
120+
121+
// Pyranometer (solar irradiance sensor).
122+
SENSOR_TYPE_PYRANOMETER = 4;
123+
124+
// Anemometer (wind velocity and direction sensor).
125+
SENSOR_TYPE_ANEMOMETER = 5;
126+
127+
// Accelerometers (acceleration sensor).
128+
SENSOR_TYPE_ACCELEROMETER = 6;
129+
130+
// General sensors, which do not fall in any of the above categories
131+
SENSOR_TYPE_GENERAL = 7;
132+
}

‎proto/frequenz/api/common/location.proto‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Geographical co-ordinates of a place.
2+
//
3+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
4+
//
5+
// Licensed under the MIT License (the "License");
6+
// you may not use this file except in compliance with the License.
7+
8+
syntax = "proto3";
9+
10+
package frequenz.api.common.location;
11+
12+
// A pair of geographical co-ordinates, representing the location of a place.
13+
message Location {
14+
// Latitude ranges from -90 (South) to 90 (North)
15+
float latitude = 1;
16+
17+
// Longitude ranges from -180 (West) to 180 (East)
18+
float longitude = 2;
19+
20+
// Country ISO 3166-1 Alpha 2
21+
string country_code = 3;
22+
}

‎proto/frequenz/api/common/metrics.proto‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
// Metrics & bounds definitions.
2+
//
3+
// Copyright:
4+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
5+
//
6+
// License:
7+
// MIT
8+
9+
syntax = "proto3";
10+
11+
package frequenz.api.common.metrics;
12+
13+
// A set of lower and upper bounds for any metric.
14+
// The units of the bounds are always the same as the related metric.
15+
message Bounds {
16+
// The lower bound.
17+
float lower = 1;
18+
19+
// The upper bound.
20+
float upper = 2;
21+
}
22+
23+
// A metric's value, with optional limits.
24+
message Metric {
25+
// The current value of the metric.
26+
float value = 1;
27+
28+
// The manufacturer's rated bounds of the metric. This may differ from
29+
// `system_bounds` as it does not take into account the current state of the
30+
// overall system.
31+
Bounds rated_bounds = 2;
32+
33+
// The current bounds of the metric, as imposed by the component this metric
34+
// originates from.
35+
Bounds component_bounds = 3;
36+
37+
// These bounds indicate the range of values that are disallowed for the
38+
// metric.
39+
// If these bounds for a metric are [`lower`, `upper`], then this metric's
40+
// `value` needs to comply with the constraints
41+
// `value <= lower` OR `upper <= value`.
42+
//
43+
// It is important to note that these bounds work together with
44+
// `system_inclusion_bounds`.
45+
//
46+
// E.g., for the system to accept a charge command,
47+
// clients need to request power values within the bounds
48+
// `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`.
49+
// This means that clients can only request charge commands with values that
50+
// are within the `system_inclusion_bounds`, but not within
51+
// `system_exclusion_bounds`.
52+
// Similarly, for the system to accept a discharge command,
53+
// clients need to request power values within the bounds
54+
// `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`.
55+
//
56+
// The following diagram illustrates the relationship between the bounds.
57+
// ```
58+
// inclusion.lower inclusion.upper
59+
// <-------|============|------------------|============|--------->
60+
// exclusion.lower exclusion.upper
61+
// ```
62+
// ---- values here are disallowed and wil be rejected
63+
// ==== vales here are allowed and will be accepted
64+
Bounds system_exclusion_bounds = 4;
65+
66+
// These bounds indicate the range of values that are allowed for the metric.
67+
// If these bounds for a metric are [`lower`, `upper`], then this metric's
68+
// `value` needs to comply with the constraint `lower <= value <= upper`
69+
//
70+
// It is important to note that these bounds work together with
71+
// `system_exclusion_bounds`.
72+
//
73+
// E.g., for the system to accept a charge command,
74+
// clients need to request power values within the bounds
75+
// `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`.
76+
// This means that clients can only request charge commands with values that
77+
// are within the `system_inclusion_bounds`, but not within
78+
// `system_exclusion_bounds`.
79+
// Similarly, for the system to accept a discharge command,
80+
// clients need to request power values within the bounds
81+
// `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`.
82+
//
83+
// The following diagram illustrates the relationship between the bounds.
84+
// ```
85+
// inclusion.lower inclusion.upper
86+
// <-------|============|------------------|============|--------->
87+
// exclusion.lower exclusion.upper
88+
// ```
89+
// ---- values here are disallowed and wil be rejected
90+
// ==== vales here are allowed and will be accepted
91+
Bounds system_inclusion_bounds = 5;
92+
}
93+
94+
// Metrics depicted as a collection of statistical summaries.
95+
//
96+
// Useful when a component has to report multiple values for the same metric.
97+
// E.g., a battery is a collection of several blocks, and each block has a
98+
// temperature sensor. The battery can report a summary of the values provided
99+
// by all these sensors, like, min, max, avg, etc., and if possible, the entire
100+
// array of temperature values.
101+
message MetricAggregation {
102+
// The average value of the metric.
103+
float avg = 1;
104+
105+
// The minimum value of the metric.
106+
optional float min = 2;
107+
108+
// The maximum value of the metric.
109+
optional float max = 3;
110+
111+
// The array of all the metric values.
112+
repeated float raw_values = 12;
113+
114+
// The manufacturer's rated bounds of the metric. This may differ from
115+
// `system_bounds` as it does not take into account the current state of the
116+
// overall system.
117+
frequenz.api.common.metrics.Bounds rated_bounds = 13;
118+
119+
// The current bounds of the metric, as imposed by the component this metric
120+
// originates from.
121+
frequenz.api.common.metrics.Bounds component_bounds = 14;
122+
123+
// These bounds indicate the range of values that are disallowed for the
124+
// metric.
125+
// If these bounds for a metric are [`lower`, `upper`], then this metric's
126+
// `value` needs to comply with the constraints
127+
// `value <= lower` OR `upper <= value`.
128+
//
129+
// It is important to note that these bounds work together with
130+
// `system_inclusion_bounds`.
131+
//
132+
// E.g., for the system to accept a charge command,
133+
// clients need to request power values within the bounds
134+
// `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`.
135+
// This means that clients can only request charge commands with power values
136+
// that are within the `system_inclusion_bounds`, but not within
137+
// `system_exclusion_bounds`.
138+
// Similarly, for the system to accept a discharge command,
139+
// clients need to request power values within the bounds
140+
// `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`.
141+
//
142+
// The following diagram illustrates the relationship between the bounds.
143+
// ```
144+
// inclusion.lower inclusion.upper
145+
// <-------|============|------------------|============|--------->
146+
// exclusion.lower exclusion.upper
147+
// ```
148+
// ---- values here are disallowed and wil be rejected
149+
// ==== vales here are allowed and will be accepted
150+
frequenz.api.common.metrics.Bounds system_exclusion_bounds = 4;
151+
152+
// These bounds indicate the range of values that are allowed for the metric.
153+
// If these bounds for a metric are [`lower`, `upper`], then this metric's
154+
// `value` needs to comply with the constraint `lower <= value <= upper`
155+
//
156+
// It is important to note that these bounds work together with
157+
// `system_exclusion_bounds`.
158+
//
159+
// E.g., for the system to accept a charge command,
160+
// clients need to request power values within the bounds
161+
// `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`.
162+
// This means that clients can only request charge commands with power values
163+
// that are within the `system_inclusion_bounds`, but not within
164+
// `system_exclusion_bounds`.
165+
// Similarly, for the system to accept a discharge command,
166+
// clients need to request power values within the bounds
167+
// `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`.
168+
//
169+
// The following diagram illustrates the relationship between the bounds.
170+
// ```
171+
// inclusion.lower inclusion.upper
172+
// <-------|============|------------------|============|--------->
173+
// exclusion.lower exclusion.upper
174+
// ```
175+
// ---- values here are disallowed and wil be rejected
176+
// ==== vales here are allowed and will be accepted
177+
frequenz.api.common.metrics.Bounds system_inclusion_bounds = 5;
178+
}

0 commit comments

Comments
 (0)