Skip to content

Protocol Documentation¤

Table of Contents¤

Top

frequenz/api/common/metrics/electrical.proto¤

AC¤

The current state and metrics of the electrical connections to the inverter.

Field Type Label Description
frequency frequenz.api.common.metrics.Metric The AC frequency. In Hertz (Hz).
current frequenz.api.common.metrics.Metric The apparent 3-phase AC current. Positive values represent apparent energy flowing towards the grid connection, and vice versa. In Ampere (A).
power_apparent frequenz.api.common.metrics.Metric The apparent 3-phase AC power. Positive values represent apparent energy flowing towards the grid connection, and vice versa. In Volt-Ampere (VA).
power_active frequenz.api.common.metrics.Metric The total active 3-phase AC active power. +ve power means consumption, away from the grid. -ve power means supply into the grid. In Watt (W).
power_reactive frequenz.api.common.metrics.Metric The reactive 3-phase AC power. +ve power means capacitive (current leading w.r.t. voltage). -ve power means inductive (current lagging w.r.t. voltage). In Volt-Ampere reactive (VAr).
energy_apparent frequenz.api.common.metrics.Metric The total 3-phase apparent energy. A positive value represents the net apparent energy supplied to the grid connection, and vice versa. In Volt-Ampere-hour (VAh).
energy_active AC.ActiveEnergy The total 3-phase active energy counters for the underlying component's consumption and supply. In Watt-hour (Wh).
energy_reactive AC.ReactiveEnergy The total 3-phase reactive energy counters for the underlying component's capacitive and inductive energy values. In Volt-Ampere reactive hour (VArh). FIXME: ReactiveEnergy says Volt-Ampere-hour (VAh).
harmonics_power_active AC.Harmonics The sums of the harmonics of the instantaneous active power at the component across all 3 phases.
thd_power_active float The sums of the total harmonic distortion of the instantaneous active power at the component across all 3 phases.
phase_1 AC.ACPhase AC metrics for phase/line 1.
phase_2 AC.ACPhase AC metrics for phase/line 2.
phase_3 AC.ACPhase AC metrics for phase/line 3.

AC.ACPhase¤

AC metrics of a single phase.

Field Type Label Description
voltage frequenz.api.common.metrics.Metric The AC voltage between the line and the neutral wire. In Volt (V).
current frequenz.api.common.metrics.Metric AC current. +ve current means consumption, away from the grid. -ve current means supply into the grid. In Ampere (A).
power_active frequenz.api.common.metrics.Metric AC active power. +ve power means consumption, away from the grid. -ve power means supply into the grid. In Watt (W).
power_reactive frequenz.api.common.metrics.Metric AC reactive power. +ve power means inductive (leading). -ve power means capacitive (lagging). In Volt-Ampere reactive (VAr).
energy_apparent frequenz.api.common.metrics.Metric The total apparent energy. A Positive value represents the net apparent energy supplied to the grid connection, and vice versa. In Volt-Ampere-hour (VAh).
energy_active AC.ActiveEnergy The total active energy counters for the underlying component's consumption and supply. In Watt-hour (Wh).
energy_reactive AC.ReactiveEnergy The total reactive energy counters for the underlying component's capacitive and inductive energy values. In Volt-Ampere reactive hour (VArh).
harmonics_power_active AC.Harmonics Harmonics of the instantaneous active power at the component. In percent (%).
thd_power_active float Total harmonic distortion of the instantaneous active power at the component. In percent (%).

AC.ActiveEnergy¤

The active energy the inverter is consuming or generating.

Field Type Label Description
energy frequenz.api.common.metrics.Metric The sum of the consumed and delivered energy. This is a signed value in passive sign convention: if more energy is consumed than delivered, this is a -ve number, otherwise +ve. In Watt-hour (Wh).
energy_consumed frequenz.api.common.metrics.Metric The consumed energy. In Watt-hour (Wh).
energy_delivered frequenz.api.common.metrics.Metric The delivered energy. In Watt-hour (Wh).

AC.Harmonics¤

The harmonics of the fast Fourier transform of the instantaneous values and its total harmonic distortion. In percent (%).

Field Type Label Description
harmonic_1 float
harmonic_2 float
harmonic_3 float
harmonic_4 float
harmonic_5 float
harmonic_6 float
harmonic_7 float
harmonic_8 float
harmonic_9 float
harmonic_10 float
harmonic_11 float

AC.ReactiveEnergy¤

The reactive energy the inverter is consuming or generating.

Field Type Label Description
energy frequenz.api.common.metrics.Metric The sum of the capacitive and inductive energy. This is a signed value. If more energy is capacitive than inductive, this is a -ve number, otherwise +ve. In Volt-Ampere-hour (VArh).
energy_capacitive frequenz.api.common.metrics.Metric The capacitive energy. In Volt-Ampere-hour (VArh).
energy_inductive frequenz.api.common.metrics.Metric The inductive energy. In Volt-Ampere-hour (VArh).

DC¤

Metrics of a DC electrical connection.

Field Type Label Description
voltage frequenz.api.common.metrics.Metric The DC voltage across the component. In Volt (V).
current frequenz.api.common.metrics.Metric The DC current flowing away from the grid connection. In passive sign convention: +ve current means consumption, away from the grid. -ve current means supply into the grid. In Ampere (A).
power frequenz.api.common.metrics.Metric The DC power flowing away from the grid connection. In passive sign convention: +ve power means consumption, away from the grid. -ve power means supply into the grid. In Watt (W).

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)