Skip to content

Protocol Documentation¤

Table of Contents¤

Top

frequenz/api/common/metrics.proto¤

Bounds¤

A set of lower and upper bounds for any metric. The units of the bounds are always the same as the related metric.

Field Type Label Description
lower float The lower bound.
upper float The upper bound.

Metric¤

A metric's value, with optional limits.

Field Type Label Description
value float The current value of the metric.
rated_bounds Bounds The manufacturer's rated bounds of the metric. This may differ from system_bounds as it does not take into account the current state of the overall system.
component_bounds Bounds The current bounds of the metric, as imposed by the component this metric originates from.
system_exclusion_bounds Bounds These bounds indicate the range of values that are disallowed for the metric. If these bounds for a metric are [lower, upper], then this metric's value needs to comply with the constraints value <= lower OR upper <= value.

It is important to note that these bounds work together with system_inclusion_bounds.

E.g., for the system to accept a charge command, clients need to request power values within the bounds [system_inclusion_bounds.lower, system_exclusion_bounds.lower]. This means that clients can only request charge commands with values that are within the system_inclusion_bounds, but not within system_exclusion_bounds. Similarly, for the system to accept a discharge command, clients need to request power values within the bounds [system_exclusion_bounds.upper, system_inclusion_bounds.upper].

The following diagram illustrates the relationship between the bounds. inclusion.lower inclusion.upper <-------|============|------------------|============|---------> exclusion.lower exclusion.upper ---- values here are disallowed and wil be rejected ==== vales here are allowed and will be accepted | | system_inclusion_bounds | Bounds | | These bounds indicate the range of values that are allowed for the metric. If these bounds for a metric are [lower, upper], then this metric's value needs to comply with the constraint lower <= value <= upper

It is important to note that these bounds work together with system_exclusion_bounds.

E.g., for the system to accept a charge command, clients need to request power values within the bounds [system_inclusion_bounds.lower, system_exclusion_bounds.lower]. This means that clients can only request charge commands with values that are within the system_inclusion_bounds, but not within system_exclusion_bounds. Similarly, for the system to accept a discharge command, clients need to request power values within the bounds [system_exclusion_bounds.upper, system_inclusion_bounds.upper].

The following diagram illustrates the relationship between the bounds. inclusion.lower inclusion.upper <-------|============|------------------|============|---------> exclusion.lower exclusion.upper ---- values here are disallowed and wil be rejected ==== vales here are allowed and will be accepted |

MetricAggregation¤

Metrics depicted as a collection of statistical summaries.

Useful when a component has to report multiple values for the same metric. E.g., a battery is a collection of several blocks, and each block has a temperature sensor. The battery can report a summary of the values provided by all these sensors, like, min, max, avg, etc., and if possible, the entire array of temperature values.

Field Type Label Description
avg float The average value of the metric.
min float optional The minimum value of the metric.
max float optional The maximum value of the metric.
raw_values float repeated The array of all the metric values.
rated_bounds Bounds The manufacturer's rated bounds of the metric. This may differ from system_bounds as it does not take into account the current state of the overall system.
component_bounds Bounds The current bounds of the metric, as imposed by the component this metric originates from.
system_exclusion_bounds Bounds These bounds indicate the range of values that are disallowed for the metric. If these bounds for a metric are [lower, upper], then this metric's value needs to comply with the constraints value <= lower OR upper <= value.

It is important to note that these bounds work together with system_inclusion_bounds.

E.g., for the system to accept a charge command, clients need to request power values within the bounds [system_inclusion_bounds.lower, system_exclusion_bounds.lower]. This means that clients can only request charge commands with power values that are within the system_inclusion_bounds, but not within system_exclusion_bounds. Similarly, for the system to accept a discharge command, clients need to request power values within the bounds [system_exclusion_bounds.upper, system_inclusion_bounds.upper].

The following diagram illustrates the relationship between the bounds. inclusion.lower inclusion.upper <-------|============|------------------|============|---------> exclusion.lower exclusion.upper ---- values here are disallowed and wil be rejected ==== vales here are allowed and will be accepted | | system_inclusion_bounds | Bounds | | These bounds indicate the range of values that are allowed for the metric. If these bounds for a metric are [lower, upper], then this metric's value needs to comply with the constraint lower <= value <= upper

It is important to note that these bounds work together with system_exclusion_bounds.

E.g., for the system to accept a charge command, clients need to request power values within the bounds [system_inclusion_bounds.lower, system_exclusion_bounds.lower]. This means that clients can only request charge commands with power values that are within the system_inclusion_bounds, but not within system_exclusion_bounds. Similarly, for the system to accept a discharge command, clients need to request power values within the bounds [system_exclusion_bounds.upper, system_inclusion_bounds.upper].

The following diagram illustrates the relationship between the bounds. inclusion.lower inclusion.upper <-------|============|------------------|============|---------> exclusion.lower exclusion.upper ---- values here are disallowed and wil be rejected ==== vales here are allowed and will be accepted |

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)