Skip to content

Protocol Documentation¤

Table of Contents¤

Top

frequenz/api/microgrid/v1/microgrid.proto¤

AckComponentErrorRequest¤

Request parameters for the RPC AckComponentError.

Field Type Label Description
component_id uint64 The component ID to acknowledge the error for.

AddComponentBoundsRequest¤

Request parameters for the RPC AddComponentBounds.

Field Type Label Description
component_id uint64 The ID of the target component.
target_metric frequenz.api.common.v1.metrics.Metric The target metric whose bounds have to be set.
bounds frequenz.api.common.v1.metrics.Bounds repeated A list of bounds for the target metric. While incorporating these bounds, the API will ensure that overlapping pairs of bounds are merged into a single pair of bounds, and non-overlapping ones are kept separated.
validity_duration ComponentBoundsValidityDuration The duration for which the given bounds will stay in effect. If this field is not provided, then the bounds will be removed after a default duration of 5 seconds.

AddComponentBoundsResponse¤

Response message for the RPC AddComponentBounds.

Field Type Label Description
ts google.protobuf.Timestamp The timestamp until which the given bounds will stay in effect.

GetMicrogridMetadataResponse¤

Metadata that describes a microgrid.

Field Type Label Description
microgrid frequenz.api.common.v1.microgrid.Microgrid The location of the microgrid, in geographical co-ordinates.

ListComponentsRequest¤

Request parameters for the RPC ListComponents. Contains filtering parameters for listing components.

Field Type Label Description
component_ids uint64 repeated Return components that have the specified IDs only.
categories frequenz.api.common.v1.microgrid.components.ComponentCategory repeated Return components that have the specified categories only.

ListComponentsResponse¤

A message containing a list of components. Used as the return type in the RPC ListComponents.

Field Type Label Description
components frequenz.api.common.v1.microgrid.components.Component repeated

ListConnectionsRequest¤

Request parameters for the RPC ListConnections. Contains filtering parameters for listing connections.

Field Type Label Description
starts uint64 repeated Only return connections that start from the specified component ID(s): if empty, connections with any start will be returned
ends uint64 repeated Only return connections that end at the specified component ID(s): if empty, connections with any end will be returned

ListConnectionsResponse¤

Response message for the RPC ListConnections. Contains a list of connections.

Field Type Label Description
connections frequenz.api.common.v1.microgrid.components.ComponentConnection repeated The list of connections.

ListSensorRequest¤

Request parameters for the RPC ListSensors. Contains filtering parameters for listing sensors.

Field Type Label Description
sensor_ids uint64 repeated Return sensors that have the specified IDs only.
categories frequenz.api.common.v1.microgrid.sensors.SensorCategory repeated Return sensors that have the specified categories only.

ListSensorsResponse¤

Response message for the RPC ListSensors. A message containing a list of sensors.

Field Type Label Description
sensors frequenz.api.common.v1.microgrid.sensors.Sensor repeated

PutComponentInStandbyRequest¤

Request parameters for the RPC PutComponentInStandby.

Field Type Label Description
component_id uint64 The component ID to set to standby.

ReceiveComponentDataStreamRequest¤

Request parameters for the RPC ReceiveComponentDataStream.

Field Type Label Description
component_id uint64 The component ID to subscribe to.
filter ReceiveComponentDataStreamRequest.ComponentDataStreamFilter The filter to apply to the stream.

This field is optional. If this is not provided, then the stream will return all metrics for the given component. If this is provided, then the stream will return only the metrics specified in the filter. |

ReceiveComponentDataStreamRequest.ComponentDataStreamFilter¤

A message for specifying a filter to apply to the stream.

Field Type Label Description
metrics frequenz.api.common.v1.metrics.Metric repeated List of metrics to return. Only the specified metrics will be returned.

!!! note At least one metric must be specified. If no metric is specified, then the stream will return an error.

!!! note Components may not support all metrics. If a component does not support a given metric, then the returned data stream will not contain that metric. |

ReceiveComponentDataStreamResponse¤

A data sample from a component in the microgrid. Components belonging to all categories and types can be represented using this message.

Field Type Label Description
data frequenz.api.common.v1.microgrid.components.ComponentData

ReceiveSensorDataStreamRequest¤

Request parameters for the RPC ReceiveSensorDataStream.

Field Type Label Description
sensor_id uint64 The sensor ID to subscribe to.
filter ReceiveSensorDataStreamRequest.SensorDataStreamFilter The filter to apply to the stream.

This field is optional. If this is not provided, then the stream will return all metrics for the given component. If this is provided, then the stream will return only the metrics specified in the filter. |

ReceiveSensorDataStreamRequest.SensorDataStreamFilter¤

A message for specifying a filter to apply to the stream.

Field Type Label Description
metrics frequenz.api.common.v1.metrics.Metric repeated List of metrics to return. Only the specified metrics will be returned.

!!! note At least one metric must be specified. If no metric is specified, then the stream will return an error.

!!! note Sensors may not support all metrics. If a sensor does not support a given metric, then the returned data stream will not contain that metric. |

ReceiveSensorDataStreamResponse¤

A data sample from a sensor in the microgrid.

Field Type Label Description
data frequenz.api.common.v1.microgrid.sensors.SensorData The sensor data.

SetComponentPowerActiveRequest¤

Request parameters for the RPC SetComponentPowerActive.

Field Type Label Description
component_id uint64 The ID of the component to set the output active power of.
power float The output active power level, in watts. -ve values are for discharging, and +ve values are for charging.
request_lifetime uint64 optional The duration, in seconds, until which the request will stay in effect. This duration has to be between 10 seconds and 15 minutes (including both limits), otherwise the request will be rejected. If not provided, it defaults to 60s.

SetComponentPowerActiveResponse¤

Response message for the RPC SetComponentPowerActive.

Field Type Label Description
valid_until google.protobuf.Timestamp The timestamp until which the given power command will stay in effect. After this timestamp, the component power will be set to 0, if the API receives no further power commands. By default, this timestamp will be set to the current time plus 60 seconds.

SetComponentPowerReactiveRequest¤

Request parameters for the RPC SetComponentPowerReactive.

Field Type Label Description
component_id uint64 The ID of the component to set the output reactive power of.
power float The output reactive power level, in VAr.

The standard of polarity is as per the IEEE 1459-2010 standard definitions: - positive reactive is inductive (current is lagging the voltage) - negative reactive is capacitive (current is leading the voltage) | | request_lifetime | uint64 | optional | The duration, in seconds, until which the request will stay in effect. This duration has to be between 10 seconds and 15 minutes (including both limits), otherwise the request will be rejected. If not provided, it defaults to 60s. |

SetComponentPowerReactiveResponse¤

Response message for the RPC SetComponentPowerReactive.

Field Type Label Description
valid_until google.protobuf.Timestamp The timestamp until which the given power command will stay in effect. After this timestamp, the component power will be set to 0, if the API receives no further power commands. By default, this timestamp will be set to the current time plus 60 seconds.

StartComponentRequest¤

Request parameters for the RPC StartComponent.

Field Type Label Description
component_id uint64 The component ID to start.

StopComponentRequest¤

Request parameters for the RPC StopComponent.

Field Type Label Description
component_id uint64 The component ID to stop.

ComponentBoundsValidityDuration¤

The duration for which a given list of bounds will stay in effect.

Name Number Description
COMPONENT_BOUNDS_VALIDITY_DURATION_UNSPECIFIED 0
COMPONENT_BOUNDS_VALIDITY_DURATION_5_SECONDS 1
COMPONENT_BOUNDS_VALIDITY_DURATION_1_MINUTE 2
COMPONENT_BOUNDS_VALIDITY_DURATION_5_MINUTES 3
COMPONENT_BOUNDS_VALIDITY_DURATION_15_MINUTES 4

Microgrid¤

The Frequenz Microgrid API

Method Name Request Type Response Type Description
GetMicrogridMetadata .google.protobuf.Empty GetMicrogridMetadataResponse Returns the microgrid metadata The metadata consists of information that describes the overall microgrid, as opposed to its electrical components or sensors, e.g., the microgrid ID, location.
ListComponents ListComponentsRequest ListComponentsResponse List electrical components in the local microgrid, optionally filtered by a given list of component IDs and component categories.

Electrical components are a part of a microgrid's electrical infrastructure are can be connected to each other to form an electrical circuit, which can then be represented as a graph.

If provided, the filters for component IDs and categories have an AND relationship with one another, meaning that they are applied serially, but the elements within a single filter list have an OR relationship with each other. E.g., if ids = [1, 2, 3], and categories = [ ComponentCategory::COMPONENT_CATEGORY_INVERTER, ComponentCategory::COMPONENT_CATEGORY_BATTERY], then the results will consist of elements that have the IDs 1, OR 2, OR 3, AND are of the categories ComponentCategory::COMPONENT_CATEGORY_INVERTER OR ComponentCategory::COMPONENT_CATEGORY_BATTERY.

If a filter list is empty, then that filter is not applied. | | ListSensors | ListSensorRequest | ListSensorsResponse | Returns a list of sensors in the local microgrid, optionally filtered by a given list of sensor IDs and sensor categories.

Sensors measure physical metrics in the microgrid's surroundings, and are not classified as electrical components.

If provided, the filters for sensor IDs and categories have an AND relationship with one another, meaning that they are applied serially, but the elements within a single filter list have an OR relationship with each other. E.g., if ids = [1, 2, 3], and categories = [ SensorCategory::SENSOR_CATEGORY_THERMOMETER, SensorCategory::SENSOR_CATEGORY_HYGROMETER], then the results will consist of elements that have the IDs 1, OR 2, OR 3, AND are of the categories SensorCategory::SENSOR_CATEGORY_THERMOMETER OR SensorCategory::SENSOR_CATEGORY_HYGROMETER.

If a filter list is empty, then that filter is not applied. | | ListConnections | ListConnectionsRequest | ListConnectionsResponse | Electrical components are a part of a microgrid's electrical infrastructure are can be connected to each other to form an electrical circuit, which can then be represented as a graph.

This RPC return a list of the connections between two components, denoted by (start, end). The direction of a connection is always away from the grid endpoint, i.e. aligned with the direction of positive current according to the passive sign convention: https://en.wikipedia.org/wiki/Passive_sign_convention

The request may be filtered by start/end component(s) of individual connections. If provided, the start and end filters have an AND relationship between each other, meaning that they are applied serially, but an OR relationship with other elements in the same list. For example, if start = [1, 2, 3], and end = [4, 5, 6], then the result should have all the connections where * each start component ID is either 1, 2, OR 3, AND * each end component ID is either 4, 5, OR 6. | | ReceiveComponentDataStream | ReceiveComponentDataStreamRequest | ReceiveComponentDataStreamResponse stream | Returns a stream containing data from a component with a given ID. | | ReceiveSensorDataStream | ReceiveSensorDataStreamRequest | ReceiveSensorDataStreamResponse stream | Returns a stream containing data from a sensor with a given ID. | | AddComponentBounds | AddComponentBoundsRequest | AddComponentBoundsResponse | Adds inclusion bounds for a given metric of a given component. Returns the time at which the bounds will expire (as a timestamp (UTC)).

The request parameters allows users to select a duration until which the bounds will stay in effect. If no duration is provided, then the bounds will be removed after a default duration of 5 seconds.

Inclusion bounds give the range that the system will try to keep the metric within. If the metric goes outside of these bounds, the system will try to bring it back within the bounds. If the bounds for a metric are [[lower_1, upper_1], [lower_2, upper_2]], then this metric's value needs to comply with the constraints lower_1 <= value <= upper_1 OR lower_2 <= value <= upper_2.

If multiple inclusion bounds have been provided for a metric, then the overlapping bounds are merged into a single bound, and non-overlapping bounds are kept separate. E.g. if the bounds are [[0, 10], [5, 15], [20, 30]], then the resulting bounds will be [[0, 15], [20, 30]].

The following diagram illustrates how bounds are applied: lower_1 upper_1 <----|========|--------|========|--------> lower_2 upper_2 The bounds in this example are [[lower_1, upper_1], [lower_2, upper_2]]. ---- values here are considered out of range. ==== values here are considered within range.

Note that for power metrics, regardless of the bounds, 0W is always allowed. | | SetComponentPowerActive | SetComponentPowerActiveRequest | SetComponentPowerActiveResponse | Sets the active power output of a component with a given ID, provided the component supports it. The power output is specified in watts.

The power output can be -ve or +ve, depending on whether the component is supposed to be discharging or charging, respectively.

The return value is the timestamp until which the given power command will stay in effect. After this timestamp, the component's active power will be set to 0, if the API receives no further command to change it before then. By default, this timestamp will be set to the current time plus 60 seconds.

Note that the target component may have a resolution of more than 1 W. E.g., an inverter may have a resolution of 88 W. In such cases, the magnitude of power will be floored to the nearest multiple of the resolution.

Performs the following sequence actions for the following component categories:

We follow the polarity specified in the IEEE 1459-2010 standard definitions, where - positive reactive is inductive (current is lagging the voltage) - negative reactive is capacitive (current is leading the voltage)

The return value is the timestamp until which the given power command will stay in effect. After this timestamp, the component's reactive power will be set to 0, if the API receives no further command to change it before then. By default, this timestamp will be set to the current time plus 60 seconds.

Note that the target component may have a resolution of more than 1 VAr. E.g., an inverter may have a resolution of 88 VAr. In such cases, the magnitude of power will be floored to the nearest multiple of the resolution. | | StartComponent | StartComponentRequest | .google.protobuf.Empty | Starts the component, and brings it into a state where it is immediately operational.

Performs the following sequence of actions for the following component categories:

  • Inverter: * closes DC relays, if the feature is available * closes AC relays * sets power output to 0

  • Battery: Checks if DC relays are open, then * closes DC relays

  • Relays: * closes relays

  • Precharge Modules: * starts the precharge process, and eventually closes the DC relays.

If any of the above mentioned actions for a given component has already been performed, then this method call effectively skips that action.

If a feature required to perform an action is missing, then that action is skipped. | | PutComponentInStandby | PutComponentInStandbyRequest | .google.protobuf.Empty | Sets the given component into a standby state, from which it can take a few minutes to return to an operational state. A transition to an operational state can be triggered by calling the StartComponent RPC, or the SetComponentPowerActive RPC.

Performs the following sequence actions for the following component categories:

  • Inverter: Checks if AC and DC relays are closed, then * sets power to 0, and * opens AC relays

If any of the checks mentioned above fails, then the method call returns an error.

If any of the above mentioned actions for a given component has already been performed, then this method call efffectively skips that action. | | StopComponent | StopComponentRequest | .google.protobuf.Empty | Stops the component completely, potentially disengaging its power electronics controller(s).

Performs the following sequence actions for the following component categories:

  • Inverter: * Brings component to the cold-standby state * opens DC relays

  • Battery: Checks if the power output is 0, then * opens DC relays

  • Relays: * opens relays

  • Precharge Modules: * opens the DC relays.

If any of the checks mentioned above fails, then the method call returns an error.

If any of the above mentioned actions for a given component has already been performed, then this method call effectively skips that action.

If a feature required to perform an action is missing, then that action is skipped. | | AckComponentError | AckComponentErrorRequest | .google.protobuf.Empty | Acknowledges any recoverable error reported by the component, and brings it back to the stopped or cold-standby state. |

Scalar Value Types¤

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)