Skip to content

frequenz.api.dispatch.v1.dispatch_pb2 ¤

Generated protocol buffer code.

Attributes¤

frequenz.api.dispatch.v1.dispatch_pb2.SORT_FIELD_CREATE_TIME module-attribute ¤

SORT_FIELD_CREATE_TIME: ValueType

CREATE_TIME: Sort by creation time of the dispatch.

frequenz.api.dispatch.v1.dispatch_pb2.SORT_FIELD_LAST_UPDATE_TIME module-attribute ¤

SORT_FIELD_LAST_UPDATE_TIME: ValueType

UPDATE_TIME: Sort by last update time of the dispatch.

frequenz.api.dispatch.v1.dispatch_pb2.SORT_FIELD_START_TIME module-attribute ¤

SORT_FIELD_START_TIME: ValueType

START_TIME: Sort by start time of the dispatch.

frequenz.api.dispatch.v1.dispatch_pb2.SORT_FIELD_UNSPECIFIED module-attribute ¤

SORT_FIELD_UNSPECIFIED: ValueType

UNSPECIFIED: Default, unspecified sort field.

frequenz.api.dispatch.v1.dispatch_pb2.SORT_ORDER_ASCENDING module-attribute ¤

SORT_ORDER_ASCENDING: ValueType

ASCENDING: Results are returned in ascending order.

frequenz.api.dispatch.v1.dispatch_pb2.SORT_ORDER_DESCENDING module-attribute ¤

SORT_ORDER_DESCENDING: ValueType

DESCENDING: Results are returned in descending order.

frequenz.api.dispatch.v1.dispatch_pb2.SORT_ORDER_UNSPECIFIED module-attribute ¤

SORT_ORDER_UNSPECIFIED: ValueType

UNSPECIFIED: Default, unspecified sort order.

Classes¤

frequenz.api.dispatch.v1.dispatch_pb2.ComponentSelector ¤

Bases: Message

Parameter for controlling which components a dispatch applies to either a set of component IDs, or a set of component categories. Examples: - To dispatch to a set of component IDs: selector { component_ids { ids: [1, 2, 3] } } - To dispatch to a set of component categories: selector { component_categories { categories: [COMPONENT_CATEGORY_BATTERY, COMPONENT_CRYPTO_MINER] } }

Attributes¤
component_categories property ¤
component_categories: CategorySet

Component categories

component_ids property ¤
component_ids: IdSet

Set of component IDs

Classes¤
CategorySet ¤

Bases: Message

Wrapper for controlling dispatches with a set of component categories Required as we can't use repeated directly in a oneof

Attributes¤
categories property ¤ 
categories: RepeatedScalarFieldContainer[ValueType]

Set of component categories

IdSet ¤

Bases: Message

Wrapper for controlling dispatches with a set of component IDs Required as we can't use repeated directly in a oneof

Attributes¤
ids property ¤ 
ids: RepeatedScalarFieldContainer[int]

Set of component IDs

frequenz.api.dispatch.v1.dispatch_pb2.CreateMicrogridDispatchRequest ¤

Bases: Message

Message to create a new dispatch with the given attributes

Attributes¤
dispatch_data property ¤
dispatch_data: global___DispatchData

Content of the dispatch to be created

microgrid_id instance-attribute ¤
microgrid_id: int

The microgrid identifier

frequenz.api.dispatch.v1.dispatch_pb2.CreateMicrogridDispatchResponse ¤

Bases: Message

Response message for creating a new dispatch

Attributes¤
dispatch property ¤
dispatch: global___Dispatch

The created dispatch

frequenz.api.dispatch.v1.dispatch_pb2.DeleteMicrogridDispatchRequest ¤

Bases: Message

Message to delete a single dispatch by its ID

Attributes¤
dispatch_id instance-attribute ¤
dispatch_id: int

The dispatch identifier

microgrid_id instance-attribute ¤
microgrid_id: int

The microgrid ID that the dispatch belongs to

frequenz.api.dispatch.v1.dispatch_pb2.DeleteMicrogridDispatchResponse ¤

Bases: Message

Response message for deleting a single dispatch

Attributes¤
dispatch_id instance-attribute ¤
dispatch_id: int

The dispatch ID that was deleted

microgrid_id instance-attribute ¤
microgrid_id: int

The microgrid ID that the dispatch belonged to

frequenz.api.dispatch.v1.dispatch_pb2.Dispatch ¤

Bases: Message

Represents a dispatch, including its metadata

Attributes¤
data property ¤
data: global___DispatchData

The dispatch data

metadata property ¤
metadata: global___DispatchMetadata

Dispatch Metadata (id, create time, etc)

frequenz.api.dispatch.v1.dispatch_pb2.DispatchData ¤

Bases: Message

Represents a dispatches data, including its type, start time, duration, component selector,

Timezone Note: Timestamps are in UTC. It is the responsibility of each microgrid to translate UTC to its local timezone.

Attributes¤
duration instance-attribute ¤
duration: int

Duration in seconds

is_active instance-attribute ¤
is_active: bool

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.

is_dry_run instance-attribute ¤
is_dry_run: bool

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.

payload property ¤
payload: Struct

The dispatch payload.

Note!!! The payload field allows for flexible JSON data to be associated with this dispatch. The payload must adhere to the following constraints: - Maximum JSON nesting depth: 5 levels. - The data should not contain executable code or scripts. - Ensure all data is properly sanitized and encoded. - The total size of the payload should not exceed 50 KB.

recurrence property ¤
recurrence: global___RecurrenceRule

The recurrence rule

selector property ¤
selector: global___ComponentSelector

Dispatch microgrid component selector

start_time property ¤
start_time: Timestamp

The dispatch start time in UTC. For reoccuring dispatches this is when the first time execution occurs. 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.

type instance-attribute ¤
type: str

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.

frequenz.api.dispatch.v1.dispatch_pb2.DispatchFilter ¤

Bases: Message

Parameters for filtering the dispatch list

Attributes¤
end_time_interval property ¤
end_time_interval: global___TimeIntervalFilter

Optional filter by end time Filter dispatches based on their explicit end time.

filter property ¤
filter: RecurrenceFilter

Filter by recurrence details Examples: - To retrieve only recurring dispatches with a specific frequency: filter { recurrence { filter { freq: FREQUENCY_DAILY } } } - To retrieve recurring dispatches with a specific frequency and interval: filter { recurrence { filter { freq: FREQUENCY_HOURLY, interval: 2 } } } - To retrieve recurring dispatches that end after a specific criteria: filter { recurrence { filter { end_criteria: { count: 10 } } } } - To retrieve recurring dispatches at specific minutes of the hour: filter { recurrence { filter { byminutes: [0, 15, 30, 45] } } } - To retrieve recurring dispatches at specific hours of the day: filter { recurrence { filter { byhours: [8, 12, 16] } } } - To retrieve recurring dispatches on specific days of the week: filter { recurrence { filter { byweekdays: [WEEKDAY_MONDAY, WEEKDAY_WEDNESDAY] } } } - To retrieve recurring dispatches on specific days of the month: filter { recurrence { filter { bymonthdays: [1, 15, 30, -1] } } } - To retrieve recurring dispatches in specific months of the year: filter { recurrence { filter { bymonths: [1, 6, 12] } } }

is_active instance-attribute ¤
is_active: bool

Optional filter by active status. If this field is not set, dispatches of any active status will be included.

is_dry_run instance-attribute ¤
is_dry_run: bool

Optional filter by dry run status. If this field is not set, dispatches of any dry run status will be included.

is_recurring instance-attribute ¤
is_recurring: bool

Filter by recurring status True: Only recurring dispatches will be returned. False: Only non-recurring dispatches will be returned. Examples: - To retrieve only recurring dispatches: filter { recurrence { is_recurring: true } } - To retrieve only non-recurring dispatches: filter { recurrence { is_recurring: false } } - To retrieve all dispatches: filter { recurrence {} } For advanced recurrence filtering, use the filter field.

selectors property ¤
selectors: RepeatedCompositeFieldContainer[
    global___ComponentSelector
]

Optional filter by component ID or category.

start_time_interval property ¤
start_time_interval: global___TimeIntervalFilter

Optional filter by start time. If no interval is provided, all dispatches will be returned.

update_time_interval property ¤
update_time_interval: global___TimeIntervalFilter

Optional filter by update time

Classes¤
RecurrenceFilter ¤

Bases: Message

Recurrence filters

The fields are left commented out for now as the exact definition and requirements for recurrence filtering are still being finalized. The frequency specifier of this recurring dispatch optional RecurrenceRule.Frequency freq = 1;

frequenz.api.dispatch.v1.dispatch_pb2.DispatchMetadata ¤

Bases: Message

Represents the metadata of a dispatch

Attributes¤
create_time property ¤
create_time: Timestamp

UTC Timestamp when the order was created.

dispatch_id instance-attribute ¤
dispatch_id: int

Unique identifier of the microgrid dispatch.

end_time property ¤
end_time: Timestamp

UTC Timestamp when the dispatch will stop working. Will be calculated internally based on the given: start_time, duration and RecurenceRule None if dispatch duration time is infinite and this value can't be calculated.

modification_time property ¤
modification_time: Timestamp

UTC Timestamp of the last update to the order.

frequenz.api.dispatch.v1.dispatch_pb2.GetMicrogridDispatchRequest ¤

Bases: Message

Message to get a single dispatch by its ID

Attributes¤
dispatch_id instance-attribute ¤
dispatch_id: int

The dispatch identifier

microgrid_id instance-attribute ¤
microgrid_id: int

The microgrid ID that the dispatch belongs to

frequenz.api.dispatch.v1.dispatch_pb2.GetMicrogridDispatchResponse ¤

Bases: Message

Response message for getting a single dispatch

Attributes¤
dispatch property ¤
dispatch: global___Dispatch

The dispatch

microgrid_id instance-attribute ¤
microgrid_id: int

The microgrid ID that the dispatch belongs to

frequenz.api.dispatch.v1.dispatch_pb2.ListMicrogridDispatchesRequest ¤

Bases: Message

Message for listing dispatches for a given microgrid.

Allows retrieval of dispatches for a specified microgrid with optional filtering and sorting. Sorting can be specified by setting 'sort_field' and 'sort_order'. If no sorting is specified, the results will be returned by their create time in a descending order.

Attributes¤
filter property ¤
filter: global___DispatchFilter

Optional filters to apply

microgrid_id instance-attribute ¤
microgrid_id: int

The microgrid ID

pagination_params property ¤
pagination_params: PaginationParams

Pagination Parameters page_size: Amount of items to return per page. Should only be provided in the first request. page_token: Cursor to specify which page to return. Should not be set in the first request. Should be populated in subsequent requests by the next_page_token found in the pagination_info in the response. The tokens stays valid indefinitely.

sort_options property ¤
sort_options: global___SortOptions

Sorting options for the result

frequenz.api.dispatch.v1.dispatch_pb2.ListMicrogridDispatchesResponse ¤

Bases: Message

A list of dispatches

Attributes¤
dispatches property ¤
dispatches: RepeatedCompositeFieldContainer[
    global___Dispatch
]

The dispatches

pagination_info property ¤
pagination_info: PaginationInfo

Pagination Info total_items: Total amount of entries found by the list request. next_page_token: Token that can be used to request the next page. Will be unset if no further pages exist.

frequenz.api.dispatch.v1.dispatch_pb2.RecurrenceRule ¤

Bases: Message

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.

Examples¤
Every 6 months¤
message RecurrenceRule {
  Frequency freq = FREQUENCY_MONTHLY;
  uint32 interval = 6;
}
Weekends only¤
message RecurrenceRule {
  Frequency freq = FREQUENCY_WEEKLY;
  repeated Weekday byweekdays = [WEEKDAY_SATURDAY, WEEKDAY_SUNDAY];
}
At midnight¤

Every day at midnight.

message RecurrenceRule {
  Frequency freq = FREQUENCY_DAILY;
  repeated uint32 byhours = [0];
}
Nightly¤

Assuming "night" means from 8 PM to 6 AM.

message RecurrenceRule {
  Frequency freq = FREQUENCY_DAILY;
  repeated uint32 byhours = [20, 21, 22, 23, 0, 1, 2, 3, 4, 5];
}
Attributes¤
byhours property ¤
byhours: RepeatedScalarFieldContainer[int]

On which hour(s) of the day does the event occur

byminutes property ¤
byminutes: RepeatedScalarFieldContainer[int]

On which minute(s) of the hour does the event occur

bymonthdays property ¤
bymonthdays: RepeatedScalarFieldContainer[int]

On which day(s) of the month does the event occur. Valid values are 1 to 31 or -31 to -1.

For example, -10 represents the tenth to the last day of the month. The bymonthdays rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY.

bymonths property ¤
bymonths: RepeatedScalarFieldContainer[int]

On which month(s) of the year does the event occur

byweekdays property ¤
byweekdays: RepeatedScalarFieldContainer[ValueType]

On which day(s) of the week does the event occur

end_criteria property ¤
end_criteria: EndCriteria

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

freq instance-attribute ¤
freq: ValueType

The frequency specifier of this recurring dispatch

interval instance-attribute ¤
interval: int

How often this dispatch should recur, based on the frequency Example: - Every 2 hours: freq = FREQUENCY_HOURLY interval = 2 Valid values typically range between 1 and 10_000, depending on the implementation.

Classes¤
EndCriteria ¤

Bases: Message

Controls when a recurring dispatch should end

Attributes¤
count instance-attribute ¤ 
count: int

The number of times this dispatch should recur. If this field is set, the dispatch will recur the given number of times. Valid values are 1 to 4096.

until property ¤ 
until: Timestamp

The end time of this dispatch in UTC. If this field is set, the last recurrence event will start before this timestamp. Note that the duration of the event is not considered in this value, so the dispatch may end after the timestamp.

Frequency ¤

Bases: _Frequency

Enum representing the frequency of the recurrence

Weekday ¤

Bases: _Weekday

Enum representing the day of the week

frequenz.api.dispatch.v1.dispatch_pb2.SortField ¤

Bases: _SortField

Enum for the fields to by sorted by.

Source code in frequenz/api/dispatch/v1/dispatch_pb2.py 
50
51
_globals['_DISPATCHFILTER']._serialized_end=1957
_globals['_DISPATCHFILTER_RECURRENCEFILTER']._serialized_start=1896

frequenz.api.dispatch.v1.dispatch_pb2.SortOptions ¤

Bases: Message

Message defining parameters for sorting list requests.

Example Usage: To retrieve dispatches sorted by creation time in descending order: sort_options: { field: CREATE_TIME, order: DESCENDING }

Attributes¤
sort_field instance-attribute ¤
sort_field: ValueType

Optional field by which to sort the results.

sort_order instance-attribute ¤
sort_order: ValueType

Optional Order in which to sort the results.

frequenz.api.dispatch.v1.dispatch_pb2.SortOrder ¤

Bases: _SortOrder

Enum for sort order.

Source code in frequenz/api/dispatch/v1/dispatch_pb2.py 
76
77
_globals['_CREATEMICROGRIDDISPATCHRESPONSE']._serialized_end=3817
_globals['_UPDATEMICROGRIDDISPATCHREQUEST']._serialized_start=3820

frequenz.api.dispatch.v1.dispatch_pb2.StreamMicrogridDispatchesRequest ¤

Bases: Message

Subscribe to a stream of microgrid dispatch requests. This method provides real-time updates on newly or updated dispatch requests for edge-based realtime decision making.

Source code in frequenz/api/dispatch/v1/dispatch_pb2.py 
87
88
89
90
91
92
93
94
95
  _globals['_GETMICROGRIDDISPATCHRESPONSE']._serialized_start=4920
  _globals['_GETMICROGRIDDISPATCHRESPONSE']._serialized_end=5026
  _globals['_DELETEMICROGRIDDISPATCHREQUEST']._serialized_start=5028
  _globals['_DELETEMICROGRIDDISPATCHREQUEST']._serialized_end=5103
  _globals['_DELETEMICROGRIDDISPATCHRESPONSE']._serialized_start=5105
  _globals['_DELETEMICROGRIDDISPATCHRESPONSE']._serialized_end=5181
  _globals['_MICROGRIDDISPATCHSERVICE']._serialized_start=5407
  _globals['_MICROGRIDDISPATCHSERVICE']._serialized_end=6302
# @@protoc_insertion_point(module_scope)
Attributes¤
microgrid_id instance-attribute ¤
microgrid_id: int

ID of the microgrid to subscribe to

frequenz.api.dispatch.v1.dispatch_pb2.StreamMicrogridDispatchesResponse ¤

Bases: Message

Response to a subscription request for a stream of microgrid dispatches. Real-time information on dispatches affecting a certain microgrid are pushed through this response.

Attributes¤
EVENT_CREATED instance-attribute ¤
EVENT_CREATED: ValueType

A new dispatch has been created

EVENT_DELETED instance-attribute ¤
EVENT_DELETED: ValueType

An existing dispatch has been deleted

EVENT_UNSPECIFIED instance-attribute ¤
EVENT_UNSPECIFIED: ValueType

Default, unspecified event

EVENT_UPDATED instance-attribute ¤
EVENT_UPDATED: ValueType

An existing dispatch has been updated

dispatch property ¤
dispatch: global___Dispatch

Dispatch record returned.

event instance-attribute ¤
event: ValueType

Which event this response was triggered by

frequenz.api.dispatch.v1.dispatch_pb2.TimeIntervalFilter ¤

Bases: Message

Filter parameter for specifying multiple time intervals

Attributes¤
to property ¤
to: Timestamp

Filter by time < this timestamp.

frequenz.api.dispatch.v1.dispatch_pb2.UpdateMicrogridDispatchRequest ¤

Bases: Message

Message to update the dispatch with the given ID, with the given attributes

Attributes¤
dispatch_id instance-attribute ¤
dispatch_id: int

The dispatch identifier

microgrid_id instance-attribute ¤
microgrid_id: int

ID of the microgrid

update property ¤
update: DispatchUpdate

The updated dispatch attributes

update_mask property ¤
update_mask: FieldMask

Field mask specifying which fields should be updated

Classes¤
DispatchUpdate ¤

Bases: Message

Message containing the updated dispatch attributes

Attributes¤
duration instance-attribute ¤ 
duration: int

Duration in seconds

is_active instance-attribute ¤ 
is_active: bool

The "active" status

payload property ¤ 
payload: Struct

The dispatch payload

recurrence property ¤ 
recurrence: RecurrenceRuleUpdate

The recurrence rule

selector property ¤ 
selector: global___ComponentSelector

The component selector

start_time property ¤ 
start_time: Timestamp

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.

Classes¤
RecurrenceRuleUpdate ¤

Bases: Message

Message containing the updated recurrence rule attributes

Attributes¤
byhours property ¤ 
byhours: RepeatedScalarFieldContainer[int]

On which hour(s) of the day does the event occur

byminutes property ¤ 
byminutes: RepeatedScalarFieldContainer[int]

On which minute(s) of the hour does the event occur

bymonthdays property ¤ 
bymonthdays: RepeatedScalarFieldContainer[int]

On which day(s) of the month does the event occur. Valid values are 1 to 31 or -31 to -1.

For example, -10 represents the tenth to the last day of the month. The bymonthdays rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY.

bymonths property ¤ 
bymonths: RepeatedScalarFieldContainer[int]

On which month(s) of the year does the event occur

byweekdays property ¤ 
byweekdays: RepeatedScalarFieldContainer[ValueType]

On which day(s) of the week does the event occur

end_criteria property ¤ 
end_criteria: EndCriteria

When this dispatch should end.

freq instance-attribute ¤ 
freq: ValueType

The frequency specifier of this recurring dispatch

interval instance-attribute ¤ 
interval: int

How often this dispatch should recur, based on the frequency

frequenz.api.dispatch.v1.dispatch_pb2.UpdateMicrogridDispatchResponse ¤

Bases: Message

Response message for updating a dispatch

Attributes¤
dispatch property ¤
dispatch: global___Dispatch

The updated dispatch