-
Notifications
You must be signed in to change notification settings - Fork 5
/
dispatch.proto
428 lines (350 loc) · 12.8 KB
/
dispatch.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
// protolint:disable MAX_LINE_LENGTH
// Frequenz Dispatch Automation API
//
// Copyright:
// Copyright 2022 Frequenz Energy-as-a-Service GmbH
//
// License:
// MIT
syntax = "proto3";
package frequenz.api.dispatch.v1;
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "frequenz/api/common/v1/microgrid/components/components.proto";
// Service providing operations related to dispatching microgrid components.
//
// #### 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.
service MicrogridDispatchService {
// Returns a list of all dispatches
rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList);
// Create a new dispatch
rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);
// Update a dispatch
rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);
// Get a single dispatch
rpc GetMicrogridDispatch(DispatchGetRequest) returns (Dispatch);
// Delete a given dispatch
rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty);
}
// 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;
// The microgrid identifier
uint64 microgrid_id = 2;
// The dispatch type.
// Contains user-defined information about what "type" of dispatch this is.
// Downstream applications that consume the dispatch API are responsible for
// understanding and processing this field.
string type = 3;
// 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 in UTC
// This is set when a dispatch is modified via the update request message
google.protobuf.Timestamp update_time = 5;
// The start time in UTC
google.protobuf.Timestamp start_time = 6;
// Duration in seconds
uint32 duration = 7;
// The component selector
ComponentSelector 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
google.protobuf.Struct payload = 11;
// The recurrence rule
RecurrenceRule recurrence = 12;
}
// Filter parameter for specifying multiple time intervals
message TimeIntervalFilter {
// Filter by start_time >= this timestamp
google.protobuf.Timestamp start_from = 1;
// Filter by start_time < this timestamp
google.protobuf.Timestamp start_to = 2;
// Filter by recurrence.end_criteria.until >= this timestamp
google.protobuf.Timestamp end_from = 3;
// Filter by recurrence.end_criteria.until < this timestamp
google.protobuf.Timestamp end_to = 4;
}
// Parameter for controlling which components a dispatch applies to
// Either a set of component IDs, or all components belonging to a category
message ComponentSelector {
oneof selector {
// Set of component IDs
ComponentIDs component_ids = 1;
// Component category
frequenz.api.common.v1.microgrid.components.ComponentCategory component_category = 2;
}
}
// Wrapper for controlling dispatches with a set of component IDs
message ComponentIDs {
// Set of component IDs
repeated uint64 component_ids = 1;
}
// 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 ([RFC5545]),
// particularly for recurrence rules. For advanced use-cases or further clarifications,
// refer to [RFC5545].
//
// [RFC5545]: https://tools.ietf.org/html/rfc5545
//
// #### Examples
//
// ##### Every 6 months
//
// ```proto
// message RecurrenceRule {
// Frequency freq = FREQUENCY_MONTHLY;
// uint32 interval = 6;
// }
// ```
//
// ##### Weekends only
//
// ```proto
// message RecurrenceRule {
// Frequency freq = FREQUENCY_WEEKLY;
// repeated Weekday byweekdays = [WEEKDAY_SATURDAY, WEEKDAY_SUNDAY];
// }
// ```
//
// ##### At midnight
//
// Every day at midnight.
//
// ```proto
// message RecurrenceRule {
// Frequency freq = FREQUENCY_DAILY;
// repeated uint32 byhours = [0];
// }
// ```
//
// ##### Nightly
//
// Assuming "night" means from 8 PM to 6 AM.
//
// ```proto
// message RecurrenceRule {
// Frequency freq = FREQUENCY_DAILY;
// repeated uint32 byhours = [20, 21, 22, 23, 0, 1, 2, 3, 4, 5];
// }
// ```
message RecurrenceRule {
// Enum representing the day of the week
enum Weekday {
WEEKDAY_UNSPECIFIED = 0;
WEEKDAY_MONDAY = 1;
WEEKDAY_TUESDAY = 2;
WEEKDAY_WEDNESDAY = 3;
WEEKDAY_THURSDAY = 4;
WEEKDAY_FRIDAY = 5;
WEEKDAY_SATURDAY = 6;
WEEKDAY_SUNDAY = 7;
}
// Enum representing the frequency of the recurrence
enum Frequency {
FREQUENCY_UNSPECIFIED = 0;
FREQUENCY_MINUTELY = 1;
FREQUENCY_HOURLY = 2;
FREQUENCY_DAILY = 3;
FREQUENCY_WEEKLY = 4;
FREQUENCY_MONTHLY = 5;
}
// Controls when a recurring dispatch should end
message EndCriteria {
oneof count_or_until {
// The number of times this dispatch should recur.
// If this field is set, the dispatch will recur the given number of times.
uint32 count = 1;
// The end time of this dispatch in UTC.
// If this field is set, the dispatch will recur until the given timestamp.
google.protobuf.Timestamp until = 2;
}
}
// The frequency specifier of this recurring dispatch
Frequency freq = 1;
// How often this dispatch should recur, based on the frequency
// Example:
// - Every 2 hours:
// freq = FREQUENCY_HOURLY
// interval = 2
uint32 interval = 2;
// When this dispatch should end.
// A dispatch can either recur a fixed number of times, or until a given timestamp.
// If this field is not set, the dispatch will recur indefinitely.bool
EndCriteria end_criteria = 3;
// On which minute(s) of the hour does the event occur
repeated uint32 byminutes = 4;
// On which hour(s) of the day does the event occur
repeated uint32 byhours = 5;
// On which day(s) of the week does the event occur
repeated Weekday byweekdays = 6;
// On which day(s) of the month does the event occur
repeated uint32 bymonthdays = 7;
// On which month(s) of the year does the event occur
repeated uint32 bymonths = 8;
}
// Message for listing dispatches for a given microgrid, and an optional filter
message DispatchListRequest {
// The microgrid ID
uint64 microgrid_id = 1;
// Additional filter parameters
DispatchFilter filter = 2;
}
// Parameters for filtering the dispatch list
message DispatchFilter {
// Filter by component ID or category
repeated ComponentSelector selectors = 1;
// Filter by time interval
// 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
message DispatchList {
// The dispatches
repeated Dispatch dispatches = 1;
}
// Message to create a new dispatch with the given attributes
message DispatchCreateRequest {
// The microgrid identifier
uint64 microgrid_id = 1;
// The type of dispatch
string type = 2;
// The start time
// When creating a dispatch, ensure that the starting timestamp is set to
// the current time or any future time.
// Timestamps earlier than the current time are not allowed.
google.protobuf.Timestamp start_time = 3;
// Duration in seconds
uint32 duration = 4;
// The component selector
ComponentSelector selector = 5;
// The "active" status
bool is_active = 6;
// The "dry run" status
bool is_dry_run = 7;
// The dispatch payload
google.protobuf.Struct payload = 8;
// The recurrence rule
RecurrenceRule recurrence = 9;
}
// Message to update the dispatch with the given ID, with the given attributes
message DispatchUpdateRequest {
// Message containing the updated dispatch attributes
message DispatchUpdate {
// Message containing the updated recurrence rule attributes
message RecurrenceRuleUpdate {
// The frequency specifier of this recurring dispatch
optional RecurrenceRule.Frequency freq = 1;
// How often this dispatch should recur, based on the frequency
optional uint32 interval = 2;
// When this dispatch should end.
RecurrenceRule.EndCriteria end_criteria = 3;
// On which minute(s) of the hour does the event occur
repeated uint32 byminutes = 4;
// On which hour(s) of the day does the event occur
repeated uint32 byhours = 5;
// On which day(s) of the week does the event occur
repeated RecurrenceRule.Weekday byweekdays = 6;
// On which day(s) of the month does the event occur
repeated uint32 bymonthdays = 7;
// On which month(s) of the year does the event occur
repeated uint32 bymonths = 8;
}
// The type of dispatch
optional string type = 1;
// The start time
// When updating a dispatch, ensure that the starting timestamp is set to
// the current time or any future time.
// Timestamps earlier than the current time are not allowed.
google.protobuf.Timestamp start_time = 2;
// Duration in seconds
optional uint32 duration = 3;
// The component selector
ComponentSelector selector = 4;
// The "active" status
optional bool is_active = 5;
// The "dry run" status
optional bool is_dry_run = 6;
// The dispatch payload
google.protobuf.Struct payload = 7;
// The recurrence rule
RecurrenceRuleUpdate recurrence = 8;
}
// The dispatch identifier
uint64 id = 1;
// Field mask specifying which fields should be updated
google.protobuf.FieldMask update_mask = 2;
// The updated dispatch attributes
DispatchUpdate update = 3;
}
// Message to get a single dispatch by its ID
message DispatchGetRequest {
// The dispatch identifier
uint64 id = 1;
}
// Message to delete a single dispatch by its ID
message DispatchDeleteRequest {
// The dispatch identifier
uint64 id = 1;
}