Skip to content

components

frequenz.client.common.microgrid.components ¤

Defines the components that can be used in a microgrid.

Classes¤

frequenz.client.common.microgrid.components.ComponentCategory ¤

Bases: Enum

Possible types of microgrid component.

Source code in frequenz/client/common/microgrid/components/__init__.py 
 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
@enum.unique
class ComponentCategory(enum.Enum):
    """Possible types of microgrid component."""

    UNSPECIFIED = PBComponentCategory.COMPONENT_CATEGORY_UNSPECIFIED
    """An unknown component category.

    Useful for error handling, and marking unknown components in
    a list of components with otherwise known categories.
    """

    GRID = PBComponentCategory.COMPONENT_CATEGORY_GRID
    """The point where the local microgrid is connected to the grid."""

    METER = PBComponentCategory.COMPONENT_CATEGORY_METER
    """A meter, for measuring electrical metrics, e.g., current, voltage, etc."""

    INVERTER = PBComponentCategory.COMPONENT_CATEGORY_INVERTER
    """An electricity generator, with batteries or solar energy."""

    CONVERTER = PBComponentCategory.COMPONENT_CATEGORY_CONVERTER
    """A DC-DC converter."""

    BATTERY = PBComponentCategory.COMPONENT_CATEGORY_BATTERY
    """A storage system for electrical energy, used by inverters."""

    EV_CHARGER = PBComponentCategory.COMPONENT_CATEGORY_EV_CHARGER
    """A station for charging electrical vehicles."""

    CRYPTO_MINER = PBComponentCategory.COMPONENT_CATEGORY_CRYPTO_MINER
    """A crypto miner."""

    ELECTROLYZER = PBComponentCategory.COMPONENT_CATEGORY_ELECTROLYZER
    """An electrolyzer for converting water into hydrogen and oxygen."""

    CHP = PBComponentCategory.COMPONENT_CATEGORY_CHP
    """A heat and power combustion plant (CHP stands for combined heat and power)."""

    RELAY = PBComponentCategory.COMPONENT_CATEGORY_RELAY
    """A relay.

    Relays generally have two states: open (connected) and closed (disconnected).
    They are generally placed in front of a component, e.g., an inverter, to
    control whether the component is connected to the grid or not.
    """

    PRECHARGER = PBComponentCategory.COMPONENT_CATEGORY_PRECHARGER
    """A precharge module.

    Precharging involves gradually ramping up the DC voltage to prevent any
    potential damage to sensitive electrical components like capacitors.

    While many inverters and batteries come equipped with in-built precharging
    mechanisms, some may lack this feature. In such cases, we need to use
    external precharging modules.
    """

    FUSE = PBComponentCategory.COMPONENT_CATEGORY_FUSE
    """A fuse."""

    VOLTAGE_TRANSFORMER = PBComponentCategory.COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER
    """A voltage transformer.

    Voltage transformers are used to step up or step down the voltage, keeping
    the power somewhat constant by increasing or decreasing the current.  If voltage is
    stepped up, current is stepped down, and vice versa.

    Note:
        Voltage transformers have efficiency losses, so the output power is
        always less than the input power.
    """

    HVAC = PBComponentCategory.COMPONENT_CATEGORY_HVAC
    """A Heating, Ventilation, and Air Conditioning (HVAC) system."""

    @classmethod
    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
    def from_proto(
        cls, component_category: PBComponentCategory.ValueType
    ) -> ComponentCategory:
        """Convert a protobuf ComponentCategory message to ComponentCategory enum.

        Args:
            component_category: protobuf enum to convert

        Returns:
            Enum value corresponding to the protobuf message.
        """
        if not any(t.value == component_category for t in ComponentCategory):
            return ComponentCategory.UNSPECIFIED
        return cls(component_category)

    def to_proto(self) -> PBComponentCategory.ValueType:
        """Convert a ComponentCategory enum to protobuf ComponentCategory message.

        Returns:
            Enum value corresponding to the protobuf message.
        """
        return self.value
Attributes¤
BATTERY class-attribute instance-attribute ¤
BATTERY = COMPONENT_CATEGORY_BATTERY

A storage system for electrical energy, used by inverters.

CHP class-attribute instance-attribute ¤
CHP = COMPONENT_CATEGORY_CHP

A heat and power combustion plant (CHP stands for combined heat and power).

CONVERTER class-attribute instance-attribute ¤
CONVERTER = COMPONENT_CATEGORY_CONVERTER

A DC-DC converter.

CRYPTO_MINER class-attribute instance-attribute ¤
CRYPTO_MINER = COMPONENT_CATEGORY_CRYPTO_MINER

A crypto miner.

ELECTROLYZER class-attribute instance-attribute ¤
ELECTROLYZER = COMPONENT_CATEGORY_ELECTROLYZER

An electrolyzer for converting water into hydrogen and oxygen.

EV_CHARGER class-attribute instance-attribute ¤
EV_CHARGER = COMPONENT_CATEGORY_EV_CHARGER

A station for charging electrical vehicles.

FUSE class-attribute instance-attribute ¤
FUSE = COMPONENT_CATEGORY_FUSE

A fuse.

GRID class-attribute instance-attribute ¤
GRID = COMPONENT_CATEGORY_GRID

The point where the local microgrid is connected to the grid.

HVAC class-attribute instance-attribute ¤
HVAC = COMPONENT_CATEGORY_HVAC

A Heating, Ventilation, and Air Conditioning (HVAC) system.

INVERTER class-attribute instance-attribute ¤
INVERTER = COMPONENT_CATEGORY_INVERTER

An electricity generator, with batteries or solar energy.

METER class-attribute instance-attribute ¤
METER = COMPONENT_CATEGORY_METER

A meter, for measuring electrical metrics, e.g., current, voltage, etc.

PRECHARGER class-attribute instance-attribute ¤
PRECHARGER = COMPONENT_CATEGORY_PRECHARGER

A precharge module.

Precharging involves gradually ramping up the DC voltage to prevent any potential damage to sensitive electrical components like capacitors.

While many inverters and batteries come equipped with in-built precharging mechanisms, some may lack this feature. In such cases, we need to use external precharging modules.

RELAY class-attribute instance-attribute ¤
RELAY = COMPONENT_CATEGORY_RELAY

A relay.

Relays generally have two states: open (connected) and closed (disconnected). They are generally placed in front of a component, e.g., an inverter, to control whether the component is connected to the grid or not.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = COMPONENT_CATEGORY_UNSPECIFIED

An unknown component category.

Useful for error handling, and marking unknown components in a list of components with otherwise known categories.

VOLTAGE_TRANSFORMER class-attribute instance-attribute ¤
VOLTAGE_TRANSFORMER = COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER

A voltage transformer.

Voltage transformers are used to step up or step down the voltage, keeping the power somewhat constant by increasing or decreasing the current. If voltage is stepped up, current is stepped down, and vice versa.

Note

Voltage transformers have efficiency losses, so the output power is always less than the input power.

Functions¤
from_proto classmethod ¤
from_proto(
    component_category: ValueType,
) -> ComponentCategory

Convert a protobuf ComponentCategory message to ComponentCategory enum.

PARAMETER DESCRIPTION
component_category

protobuf enum to convert

TYPE: ValueType

RETURNS DESCRIPTION
ComponentCategory

Enum value corresponding to the protobuf message.
Source code in frequenz/client/common/microgrid/components/__init__.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
@classmethod
@deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
def from_proto(
    cls, component_category: PBComponentCategory.ValueType
) -> ComponentCategory:
    """Convert a protobuf ComponentCategory message to ComponentCategory enum.

    Args:
        component_category: protobuf enum to convert

    Returns:
        Enum value corresponding to the protobuf message.
    """
    if not any(t.value == component_category for t in ComponentCategory):
        return ComponentCategory.UNSPECIFIED
    return cls(component_category)
to_proto ¤
to_proto() -> ValueType

Convert a ComponentCategory enum to protobuf ComponentCategory message.

RETURNS DESCRIPTION
ValueType

Enum value corresponding to the protobuf message.
Source code in frequenz/client/common/microgrid/components/__init__.py 
124
125
126
127
128
129
130
def to_proto(self) -> PBComponentCategory.ValueType:
    """Convert a ComponentCategory enum to protobuf ComponentCategory message.

    Returns:
        Enum value corresponding to the protobuf message.
    """
    return self.value

frequenz.client.common.microgrid.components.ComponentErrorCode ¤

Bases: Enum

All possible errors that can occur across all microgrid component categories.

Source code in frequenz/client/common/microgrid/components/__init__.py 
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
@enum.unique
class ComponentErrorCode(enum.Enum):
    """All possible errors that can occur across all microgrid component categories."""

    UNSPECIFIED = PBComponentErrorCode.COMPONENT_ERROR_CODE_UNSPECIFIED
    """Default value. No specific error is specified."""

    UNKNOWN = PBComponentErrorCode.COMPONENT_ERROR_CODE_UNKNOWN
    """The component is reporting an unknown or an undefined error, and the sender
    cannot parse the component error to any of the variants below."""

    SWITCH_ON_FAULT = PBComponentErrorCode.COMPONENT_ERROR_CODE_SWITCH_ON_FAULT
    """Error indicating that the component could not be switched on."""

    UNDERVOLTAGE = PBComponentErrorCode.COMPONENT_ERROR_CODE_UNDERVOLTAGE
    """Error indicating that the component is operating under the minimum rated
    voltage."""

    OVERVOLTAGE = PBComponentErrorCode.COMPONENT_ERROR_CODE_OVERVOLTAGE
    """Error indicating that the component is operating over the maximum rated
    voltage."""

    OVERCURRENT = PBComponentErrorCode.COMPONENT_ERROR_CODE_OVERCURRENT
    """Error indicating that the component is drawing more current than the
    maximum rated value."""

    OVERCURRENT_CHARGING = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_OVERCURRENT_CHARGING
    )
    """Error indicating that the component's consumption current is over the
    maximum rated value during charging."""

    OVERCURRENT_DISCHARGING = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_OVERCURRENT_DISCHARGING
    )
    """Error indicating that the component's production current is over the
    maximum rated value during discharging."""

    OVERTEMPERATURE = PBComponentErrorCode.COMPONENT_ERROR_CODE_OVERTEMPERATURE
    """Error indicating that the component is operating over the maximum rated
    temperature."""

    UNDERTEMPERATURE = PBComponentErrorCode.COMPONENT_ERROR_CODE_UNDERTEMPERATURE
    """Error indicating that the component is operating under the minimum rated
    temperature."""

    HIGH_HUMIDITY = PBComponentErrorCode.COMPONENT_ERROR_CODE_HIGH_HUMIDITY
    """Error indicating that the component is exposed to high humidity levels over
    the maximum rated value."""

    FUSE_ERROR = PBComponentErrorCode.COMPONENT_ERROR_CODE_FUSE_ERROR
    """Error indicating that the component's fuse has blown."""

    PRECHARGE_ERROR = PBComponentErrorCode.COMPONENT_ERROR_CODE_PRECHARGE_ERROR
    """Error indicating that the component's precharge unit has failed."""

    PLAUSIBILITY_ERROR = PBComponentErrorCode.COMPONENT_ERROR_CODE_PLAUSIBILITY_ERROR
    """Error indicating plausibility issues within the system involving this
    component."""

    UNDERVOLTAGE_SHUTDOWN = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_UNDERVOLTAGE_SHUTDOWN
    )
    """Error indicating system shutdown due to undervoltage involving this
    component."""

    EV_UNEXPECTED_PILOT_FAILURE = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_EV_UNEXPECTED_PILOT_FAILURE
    )
    """Error indicating unexpected pilot failure in an electric vehicle (EV)
    component."""

    FAULT_CURRENT = PBComponentErrorCode.COMPONENT_ERROR_CODE_FAULT_CURRENT
    """Error indicating fault current detected in the component."""

    SHORT_CIRCUIT = PBComponentErrorCode.COMPONENT_ERROR_CODE_SHORT_CIRCUIT
    """Error indicating a short circuit detected in the component."""

    CONFIG_ERROR = PBComponentErrorCode.COMPONENT_ERROR_CODE_CONFIG_ERROR
    """Error indicating a configuration error related to the component."""

    ILLEGAL_COMPONENT_STATE_CODE_REQUESTED = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_ILLEGAL_COMPONENT_STATE_CODE_REQUESTED
    )
    """Error indicating an illegal state requested for the component."""

    HARDWARE_INACCESSIBLE = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_HARDWARE_INACCESSIBLE
    )
    """Error indicating that the hardware of the component is inaccessible."""

    INTERNAL = PBComponentErrorCode.COMPONENT_ERROR_CODE_INTERNAL
    """Error indicating an internal error within the component."""

    UNAUTHORIZED = PBComponentErrorCode.COMPONENT_ERROR_CODE_UNAUTHORIZED
    """Error indicating that the component is unauthorized to perform the
    last requested action."""

    EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION
    )
    """Error indicating electric vehicle (EV) cable was abruptly unplugged from
    the charging station."""

    EV_CHARGING_CABLE_UNPLUGGED_FROM_EV = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_EV
    )
    """Error indicating electric vehicle (EV) cable was abruptly unplugged from
    the vehicle."""

    EV_CHARGING_CABLE_LOCK_FAILED = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_LOCK_FAILED
    )
    """Error indicating electric vehicle (EV) cable lock failure."""

    EV_CHARGING_CABLE_INVALID = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_INVALID
    )
    """Error indicating an invalid electric vehicle (EV) cable."""

    EV_CONSUMER_INCOMPATIBLE = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_EV_CONSUMER_INCOMPATIBLE
    )
    """Error indicating an incompatible electric vehicle (EV) plug."""

    BATTERY_IMBALANCE = PBComponentErrorCode.COMPONENT_ERROR_CODE_BATTERY_IMBALANCE
    """Error indicating a battery system imbalance."""

    BATTERY_LOW_SOH = PBComponentErrorCode.COMPONENT_ERROR_CODE_BATTERY_LOW_SOH
    """Error indicating a low state of health (SOH) detected in the battery."""

    BATTERY_BLOCK_ERROR = PBComponentErrorCode.COMPONENT_ERROR_CODE_BATTERY_BLOCK_ERROR
    """Error indicating a battery block error."""

    BATTERY_CONTROLLER_ERROR = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_BATTERY_CONTROLLER_ERROR
    )
    """Error indicating a battery controller error."""

    BATTERY_RELAY_ERROR = PBComponentErrorCode.COMPONENT_ERROR_CODE_BATTERY_RELAY_ERROR
    """Error indicating a battery relay error."""

    BATTERY_CALIBRATION_NEEDED = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_BATTERY_CALIBRATION_NEEDED
    )
    """Error indicating that battery calibration is needed."""

    RELAY_CYCLE_LIMIT_REACHED = (
        PBComponentErrorCode.COMPONENT_ERROR_CODE_RELAY_CYCLE_LIMIT_REACHED
    )
    """Error indicating that the relays have been cycled for the maximum number of
    times."""

    @classmethod
    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
    def from_proto(
        cls, component_error_code: PBComponentErrorCode.ValueType
    ) -> ComponentErrorCode:
        """Convert a protobuf ComponentErrorCode message to ComponentErrorCode enum.

        Args:
            component_error_code: protobuf enum to convert

        Returns:
            Enum value corresponding to the protobuf message.
        """
        if not any(c.value == component_error_code for c in ComponentErrorCode):
            return ComponentErrorCode.UNSPECIFIED
        return cls(component_error_code)

    def to_proto(self) -> PBComponentErrorCode.ValueType:
        """Convert a ComponentErrorCode enum to protobuf ComponentErrorCode message.

        Returns:
            Enum value corresponding to the protobuf message.
        """
        return self.value
Attributes¤
BATTERY_BLOCK_ERROR class-attribute instance-attribute ¤
BATTERY_BLOCK_ERROR = (
    COMPONENT_ERROR_CODE_BATTERY_BLOCK_ERROR
)

Error indicating a battery block error.

BATTERY_CALIBRATION_NEEDED class-attribute instance-attribute ¤
BATTERY_CALIBRATION_NEEDED = (
    COMPONENT_ERROR_CODE_BATTERY_CALIBRATION_NEEDED
)

Error indicating that battery calibration is needed.

BATTERY_CONTROLLER_ERROR class-attribute instance-attribute ¤
BATTERY_CONTROLLER_ERROR = (
    COMPONENT_ERROR_CODE_BATTERY_CONTROLLER_ERROR
)

Error indicating a battery controller error.

BATTERY_IMBALANCE class-attribute instance-attribute ¤
BATTERY_IMBALANCE = COMPONENT_ERROR_CODE_BATTERY_IMBALANCE

Error indicating a battery system imbalance.

BATTERY_LOW_SOH class-attribute instance-attribute ¤
BATTERY_LOW_SOH = COMPONENT_ERROR_CODE_BATTERY_LOW_SOH

Error indicating a low state of health (SOH) detected in the battery.

BATTERY_RELAY_ERROR class-attribute instance-attribute ¤
BATTERY_RELAY_ERROR = (
    COMPONENT_ERROR_CODE_BATTERY_RELAY_ERROR
)

Error indicating a battery relay error.

CONFIG_ERROR class-attribute instance-attribute ¤
CONFIG_ERROR = COMPONENT_ERROR_CODE_CONFIG_ERROR

Error indicating a configuration error related to the component.

EV_CHARGING_CABLE_INVALID class-attribute instance-attribute ¤
EV_CHARGING_CABLE_INVALID = (
    COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_INVALID
)

Error indicating an invalid electric vehicle (EV) cable.

EV_CHARGING_CABLE_LOCK_FAILED class-attribute instance-attribute ¤
EV_CHARGING_CABLE_LOCK_FAILED = (
    COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_LOCK_FAILED
)

Error indicating electric vehicle (EV) cable lock failure.

EV_CHARGING_CABLE_UNPLUGGED_FROM_EV class-attribute instance-attribute ¤
EV_CHARGING_CABLE_UNPLUGGED_FROM_EV = (
    COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_EV
)

Error indicating electric vehicle (EV) cable was abruptly unplugged from the vehicle.

EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION class-attribute instance-attribute ¤
EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION = COMPONENT_ERROR_CODE_EV_CHARGING_CABLE_UNPLUGGED_FROM_STATION

Error indicating electric vehicle (EV) cable was abruptly unplugged from the charging station.

EV_CONSUMER_INCOMPATIBLE class-attribute instance-attribute ¤
EV_CONSUMER_INCOMPATIBLE = (
    COMPONENT_ERROR_CODE_EV_CONSUMER_INCOMPATIBLE
)

Error indicating an incompatible electric vehicle (EV) plug.

EV_UNEXPECTED_PILOT_FAILURE class-attribute instance-attribute ¤
EV_UNEXPECTED_PILOT_FAILURE = (
    COMPONENT_ERROR_CODE_EV_UNEXPECTED_PILOT_FAILURE
)

Error indicating unexpected pilot failure in an electric vehicle (EV) component.

FAULT_CURRENT class-attribute instance-attribute ¤
FAULT_CURRENT = COMPONENT_ERROR_CODE_FAULT_CURRENT

Error indicating fault current detected in the component.

FUSE_ERROR class-attribute instance-attribute ¤
FUSE_ERROR = COMPONENT_ERROR_CODE_FUSE_ERROR

Error indicating that the component's fuse has blown.

HARDWARE_INACCESSIBLE class-attribute instance-attribute ¤
HARDWARE_INACCESSIBLE = (
    COMPONENT_ERROR_CODE_HARDWARE_INACCESSIBLE
)

Error indicating that the hardware of the component is inaccessible.

HIGH_HUMIDITY class-attribute instance-attribute ¤
HIGH_HUMIDITY = COMPONENT_ERROR_CODE_HIGH_HUMIDITY

Error indicating that the component is exposed to high humidity levels over the maximum rated value.

ILLEGAL_COMPONENT_STATE_CODE_REQUESTED class-attribute instance-attribute ¤
ILLEGAL_COMPONENT_STATE_CODE_REQUESTED = COMPONENT_ERROR_CODE_ILLEGAL_COMPONENT_STATE_CODE_REQUESTED

Error indicating an illegal state requested for the component.

INTERNAL class-attribute instance-attribute ¤
INTERNAL = COMPONENT_ERROR_CODE_INTERNAL

Error indicating an internal error within the component.

OVERCURRENT class-attribute instance-attribute ¤
OVERCURRENT = COMPONENT_ERROR_CODE_OVERCURRENT

Error indicating that the component is drawing more current than the maximum rated value.

OVERCURRENT_CHARGING class-attribute instance-attribute ¤
OVERCURRENT_CHARGING = (
    COMPONENT_ERROR_CODE_OVERCURRENT_CHARGING
)

Error indicating that the component's consumption current is over the maximum rated value during charging.

OVERCURRENT_DISCHARGING class-attribute instance-attribute ¤
OVERCURRENT_DISCHARGING = (
    COMPONENT_ERROR_CODE_OVERCURRENT_DISCHARGING
)

Error indicating that the component's production current is over the maximum rated value during discharging.

OVERTEMPERATURE class-attribute instance-attribute ¤
OVERTEMPERATURE = COMPONENT_ERROR_CODE_OVERTEMPERATURE

Error indicating that the component is operating over the maximum rated temperature.

OVERVOLTAGE class-attribute instance-attribute ¤
OVERVOLTAGE = COMPONENT_ERROR_CODE_OVERVOLTAGE

Error indicating that the component is operating over the maximum rated voltage.

PLAUSIBILITY_ERROR class-attribute instance-attribute ¤
PLAUSIBILITY_ERROR = COMPONENT_ERROR_CODE_PLAUSIBILITY_ERROR

Error indicating plausibility issues within the system involving this component.

PRECHARGE_ERROR class-attribute instance-attribute ¤
PRECHARGE_ERROR = COMPONENT_ERROR_CODE_PRECHARGE_ERROR

Error indicating that the component's precharge unit has failed.

RELAY_CYCLE_LIMIT_REACHED class-attribute instance-attribute ¤
RELAY_CYCLE_LIMIT_REACHED = (
    COMPONENT_ERROR_CODE_RELAY_CYCLE_LIMIT_REACHED
)

Error indicating that the relays have been cycled for the maximum number of times.

SHORT_CIRCUIT class-attribute instance-attribute ¤
SHORT_CIRCUIT = COMPONENT_ERROR_CODE_SHORT_CIRCUIT

Error indicating a short circuit detected in the component.

SWITCH_ON_FAULT class-attribute instance-attribute ¤
SWITCH_ON_FAULT = COMPONENT_ERROR_CODE_SWITCH_ON_FAULT

Error indicating that the component could not be switched on.

UNAUTHORIZED class-attribute instance-attribute ¤
UNAUTHORIZED = COMPONENT_ERROR_CODE_UNAUTHORIZED

Error indicating that the component is unauthorized to perform the last requested action.

UNDERTEMPERATURE class-attribute instance-attribute ¤
UNDERTEMPERATURE = COMPONENT_ERROR_CODE_UNDERTEMPERATURE

Error indicating that the component is operating under the minimum rated temperature.

UNDERVOLTAGE class-attribute instance-attribute ¤
UNDERVOLTAGE = COMPONENT_ERROR_CODE_UNDERVOLTAGE

Error indicating that the component is operating under the minimum rated voltage.

UNDERVOLTAGE_SHUTDOWN class-attribute instance-attribute ¤
UNDERVOLTAGE_SHUTDOWN = (
    COMPONENT_ERROR_CODE_UNDERVOLTAGE_SHUTDOWN
)

Error indicating system shutdown due to undervoltage involving this component.

UNKNOWN class-attribute instance-attribute ¤
UNKNOWN = COMPONENT_ERROR_CODE_UNKNOWN

The component is reporting an unknown or an undefined error, and the sender cannot parse the component error to any of the variants below.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = COMPONENT_ERROR_CODE_UNSPECIFIED

Default value. No specific error is specified.

Functions¤
from_proto classmethod ¤
from_proto(
    component_error_code: ValueType,
) -> ComponentErrorCode

Convert a protobuf ComponentErrorCode message to ComponentErrorCode enum.

PARAMETER DESCRIPTION
component_error_code

protobuf enum to convert

TYPE: ValueType

RETURNS DESCRIPTION
ComponentErrorCode

Enum value corresponding to the protobuf message.
Source code in frequenz/client/common/microgrid/components/__init__.py 
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
@classmethod
@deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
def from_proto(
    cls, component_error_code: PBComponentErrorCode.ValueType
) -> ComponentErrorCode:
    """Convert a protobuf ComponentErrorCode message to ComponentErrorCode enum.

    Args:
        component_error_code: protobuf enum to convert

    Returns:
        Enum value corresponding to the protobuf message.
    """
    if not any(c.value == component_error_code for c in ComponentErrorCode):
        return ComponentErrorCode.UNSPECIFIED
    return cls(component_error_code)
to_proto ¤
to_proto() -> ValueType

Convert a ComponentErrorCode enum to protobuf ComponentErrorCode message.

RETURNS DESCRIPTION
ValueType

Enum value corresponding to the protobuf message.
Source code in frequenz/client/common/microgrid/components/__init__.py 
409
410
411
412
413
414
415
def to_proto(self) -> PBComponentErrorCode.ValueType:
    """Convert a ComponentErrorCode enum to protobuf ComponentErrorCode message.

    Returns:
        Enum value corresponding to the protobuf message.
    """
    return self.value

frequenz.client.common.microgrid.components.ComponentId ¤

Bases: BaseId

A unique identifier for a microgrid component.

Source code in frequenz/client/common/microgrid/components/__init__.py 
27
28
29
@final
class ComponentId(BaseId, str_prefix="CID"):
    """A unique identifier for a microgrid component."""
Attributes¤
str_prefix property ¤
str_prefix: str

The prefix used for the string representation of this ID.

Functions¤
__eq__ ¤
__eq__(other: object) -> bool

Check if this instance is equal to another object.

Equality is defined as being of the exact same type and having the same underlying ID.

Source code in frequenz/core/id.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def __eq__(self, other: object) -> bool:
    """Check if this instance is equal to another object.

    Equality is defined as being of the exact same type and having the same
    underlying ID.
    """
    # pylint thinks this is not an unidiomatic typecheck, but in this case
    # it is not. isinstance() returns True for subclasses, which is not
    # what we want here, as different ID types should never be equal.
    # pylint: disable-next=unidiomatic-typecheck
    if type(other) is not type(self):
        return NotImplemented
    # We already checked type(other) is type(self), but mypy doesn't
    # understand that, so we need to cast it to Self.
    other_id = cast(Self, other)
    return self._id == other_id._id
__hash__ ¤
__hash__() -> int

Return the hash of this instance.

The hash is based on the exact type and the underlying ID to ensure that IDs of different types but with the same numeric value have different hashes.

Source code in frequenz/core/id.py 
183
184
185
186
187
188
189
def __hash__(self) -> int:
    """Return the hash of this instance.

    The hash is based on the exact type and the underlying ID to ensure
    that IDs of different types but with the same numeric value have different hashes.
    """
    return hash((type(self), self._id))
__init__ ¤
__init__(id_: int) -> None

Initialize this instance.

PARAMETER DESCRIPTION
id_

The numeric unique identifier.

TYPE: int

RAISES DESCRIPTION
ValueError

If the ID is negative.
Source code in frequenz/core/id.py 
133
134
135
136
137
138
139
140
141
142
143
144
def __init__(self, id_: int, /) -> None:
    """Initialize this instance.

    Args:
        id_: The numeric unique identifier.

    Raises:
        ValueError: If the ID is negative.
    """
    if id_ < 0:
        raise ValueError(f"{type(self).__name__} can't be negative.")
    self._id = id_
__init_subclass__ ¤
__init_subclass__(
    *,
    str_prefix: str,
    allow_custom_name: bool = False,
    **kwargs: Any
) -> None

Initialize a subclass, set its string prefix, and perform checks.

PARAMETER DESCRIPTION
str_prefix

The string prefix for the ID type (e.g., "MID"). Must be unique across all ID types.

TYPE: str

allow_custom_name

If True, bypasses the check that the class name must end with "Id". Defaults to False.

TYPE: bool DEFAULT: False

**kwargs

Forwarded to the parent's init_subclass.

TYPE: Any DEFAULT: {}

RAISES DESCRIPTION
TypeError

If allow_custom_name is False and the class name does not end with "Id".
Source code in frequenz/core/id.py 
 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
def __init_subclass__(
    cls,
    *,
    str_prefix: str,
    allow_custom_name: bool = False,
    **kwargs: Any,
) -> None:
    """Initialize a subclass, set its string prefix, and perform checks.

    Args:
        str_prefix: The string prefix for the ID type (e.g., "MID").
            Must be unique across all ID types.
        allow_custom_name: If True, bypasses the check that the class name
            must end with "Id". Defaults to False.
        **kwargs: Forwarded to the parent's __init_subclass__.

    Raises:
        TypeError: If `allow_custom_name` is False and the class name
            does not end with "Id".
    """
    super().__init_subclass__(**kwargs)

    if str_prefix in BaseId._registered_prefixes:
        # We want to raise an exception here, but currently can't due to
        # https://github.com/frequenz-floss/frequenz-repo-config-python/issues/421
        _logger.warning(
            "Prefix '%s' is already registered. ID prefixes must be unique.",
            str_prefix,
        )
    BaseId._registered_prefixes.add(str_prefix)

    if not allow_custom_name and not cls.__name__.endswith("Id"):
        raise TypeError(
            f"Class name '{cls.__name__}' for an ID class must end with 'Id' "
            "(e.g., 'SomeId'), or use `allow_custom_name=True`."
        )

    cls._str_prefix = str_prefix
__int__ ¤
__int__() -> int

Return the numeric ID of this instance.

Source code in frequenz/core/id.py 
151
152
153
def __int__(self) -> int:
    """Return the numeric ID of this instance."""
    return self._id
__lt__ ¤
__lt__(other: object) -> bool

Check if this instance is less than another object.

Comparison is only defined between instances of the exact same type.

Source code in frequenz/core/id.py 
172
173
174
175
176
177
178
179
180
181
def __lt__(self, other: object) -> bool:
    """Check if this instance is less than another object.

    Comparison is only defined between instances of the exact same type.
    """
    # pylint: disable-next=unidiomatic-typecheck
    if type(other) is not type(self):
        return NotImplemented
    other_id = cast(Self, other)
    return self._id < other_id._id
__new__ ¤
__new__(*_: Any, **__: Any) -> Self

Create a new instance of the ID class, only if it is a subclass of BaseId.

Source code in frequenz/core/id.py 
88
89
90
91
92
def __new__(cls, *_: Any, **__: Any) -> Self:
    """Create a new instance of the ID class, only if it is a subclass of BaseId."""
    if cls is BaseId:
        raise TypeError("BaseId cannot be instantiated directly. Use a subclass.")
    return super().__new__(cls)
__repr__ ¤
__repr__() -> str

Return the string representation of this instance.

Source code in frequenz/core/id.py 
191
192
193
def __repr__(self) -> str:
    """Return the string representation of this instance."""
    return f"{type(self).__name__}({self._id!r})"
__str__ ¤
__str__() -> str

Return the short string representation of this instance.

Source code in frequenz/core/id.py 
195
196
197
def __str__(self) -> str:
    """Return the short string representation of this instance."""
    return f"{self._str_prefix}{self._id}"

frequenz.client.common.microgrid.components.ComponentStateCode ¤

Bases: Enum

All possible states of a microgrid component.

Source code in frequenz/client/common/microgrid/components/__init__.py 
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
@enum.unique
class ComponentStateCode(enum.Enum):
    """All possible states of a microgrid component."""

    UNSPECIFIED = PBComponentStateCode.COMPONENT_STATE_CODE_UNSPECIFIED
    """Default value when the component state is not explicitly set."""

    UNKNOWN = PBComponentStateCode.COMPONENT_STATE_CODE_UNKNOWN
    """State when the component is in an unknown or undefined condition.

    This is used when the sender is unable to classify the component into any
    other state.
    """
    SWITCHING_OFF = PBComponentStateCode.COMPONENT_STATE_CODE_SWITCHING_OFF
    """State when the component is in the process of switching off."""

    OFF = PBComponentStateCode.COMPONENT_STATE_CODE_OFF
    """State when the component has successfully switched off."""

    SWITCHING_ON = PBComponentStateCode.COMPONENT_STATE_CODE_SWITCHING_ON
    """State when the component is in the process of switching on from an off state."""

    STANDBY = PBComponentStateCode.COMPONENT_STATE_CODE_STANDBY
    """State when the component is in standby mode, and not immediately ready for operation."""

    READY = PBComponentStateCode.COMPONENT_STATE_CODE_READY
    """State when the component is fully operational and ready for use."""

    CHARGING = PBComponentStateCode.COMPONENT_STATE_CODE_CHARGING
    """State when the component is actively consuming energy."""

    DISCHARGING = PBComponentStateCode.COMPONENT_STATE_CODE_DISCHARGING
    """State when the component is actively producing or releasing energy."""

    ERROR = PBComponentStateCode.COMPONENT_STATE_CODE_ERROR
    """State when the component is in an error state and may need attention."""

    EV_CHARGING_CABLE_UNPLUGGED = (
        PBComponentStateCode.COMPONENT_STATE_CODE_EV_CHARGING_CABLE_UNPLUGGED
    )
    """The Electric Vehicle (EV) charging cable is unplugged from the charging station."""

    EV_CHARGING_CABLE_PLUGGED_AT_STATION = (
        PBComponentStateCode.COMPONENT_STATE_CODE_EV_CHARGING_CABLE_PLUGGED_AT_STATION
    )
    """The EV charging cable is plugged into the charging station."""

    EV_CHARGING_CABLE_PLUGGED_AT_EV = (
        PBComponentStateCode.COMPONENT_STATE_CODE_EV_CHARGING_CABLE_PLUGGED_AT_EV
    )
    """The EV charging cable is plugged into the vehicle."""

    EV_CHARGING_CABLE_LOCKED_AT_STATION = (
        PBComponentStateCode.COMPONENT_STATE_CODE_EV_CHARGING_CABLE_LOCKED_AT_STATION
    )
    """The EV charging cable is locked at the charging station end, indicating
    readiness for charging."""

    EV_CHARGING_CABLE_LOCKED_AT_EV = (
        PBComponentStateCode.COMPONENT_STATE_CODE_EV_CHARGING_CABLE_LOCKED_AT_EV
    )
    """The EV charging cable is locked at the vehicle end, indicating that charging is active."""

    RELAY_OPEN = PBComponentStateCode.COMPONENT_STATE_CODE_RELAY_OPEN
    """The relay is in an open state, meaning no current can flow through."""

    RELAY_CLOSED = PBComponentStateCode.COMPONENT_STATE_CODE_RELAY_CLOSED
    """The relay is in a closed state, allowing current to flow."""

    PRECHARGER_OPEN = PBComponentStateCode.COMPONENT_STATE_CODE_PRECHARGER_OPEN
    """The precharger circuit is open, meaning it's not currently active."""

    PRECHARGER_PRECHARGING = (
        PBComponentStateCode.COMPONENT_STATE_CODE_PRECHARGER_PRECHARGING
    )
    """The precharger is in a precharging state, preparing the main circuit for activation."""

    PRECHARGER_CLOSED = PBComponentStateCode.COMPONENT_STATE_CODE_PRECHARGER_CLOSED
    """The precharger circuit is closed, allowing full current to flow to the main circuit."""

    @classmethod
    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
    def from_proto(
        cls, component_state: PBComponentStateCode.ValueType
    ) -> ComponentStateCode:
        """Convert a protobuf ComponentStateCode message to ComponentStateCode enum.

        Args:
            component_state: protobuf enum to convert

        Returns:
            Enum value corresponding to the protobuf message.
        """
        if not any(c.value == component_state for c in ComponentStateCode):
            return ComponentStateCode.UNSPECIFIED
        return cls(component_state)

    def to_proto(self) -> PBComponentStateCode.ValueType:
        """Convert a ComponentStateCode enum to protobuf ComponentStateCode message.

        Returns:
            Enum value corresponding to the protobuf message.
        """
        return self.value
Attributes¤
CHARGING class-attribute instance-attribute ¤
CHARGING = COMPONENT_STATE_CODE_CHARGING

State when the component is actively consuming energy.

DISCHARGING class-attribute instance-attribute ¤
DISCHARGING = COMPONENT_STATE_CODE_DISCHARGING

State when the component is actively producing or releasing energy.

ERROR class-attribute instance-attribute ¤
ERROR = COMPONENT_STATE_CODE_ERROR

State when the component is in an error state and may need attention.

EV_CHARGING_CABLE_LOCKED_AT_EV class-attribute instance-attribute ¤
EV_CHARGING_CABLE_LOCKED_AT_EV = (
    COMPONENT_STATE_CODE_EV_CHARGING_CABLE_LOCKED_AT_EV
)

The EV charging cable is locked at the vehicle end, indicating that charging is active.

EV_CHARGING_CABLE_LOCKED_AT_STATION class-attribute instance-attribute ¤
EV_CHARGING_CABLE_LOCKED_AT_STATION = (
    COMPONENT_STATE_CODE_EV_CHARGING_CABLE_LOCKED_AT_STATION
)

The EV charging cable is locked at the charging station end, indicating readiness for charging.

EV_CHARGING_CABLE_PLUGGED_AT_EV class-attribute instance-attribute ¤
EV_CHARGING_CABLE_PLUGGED_AT_EV = (
    COMPONENT_STATE_CODE_EV_CHARGING_CABLE_PLUGGED_AT_EV
)

The EV charging cable is plugged into the vehicle.

EV_CHARGING_CABLE_PLUGGED_AT_STATION class-attribute instance-attribute ¤
EV_CHARGING_CABLE_PLUGGED_AT_STATION = COMPONENT_STATE_CODE_EV_CHARGING_CABLE_PLUGGED_AT_STATION

The EV charging cable is plugged into the charging station.

EV_CHARGING_CABLE_UNPLUGGED class-attribute instance-attribute ¤
EV_CHARGING_CABLE_UNPLUGGED = (
    COMPONENT_STATE_CODE_EV_CHARGING_CABLE_UNPLUGGED
)

The Electric Vehicle (EV) charging cable is unplugged from the charging station.

OFF class-attribute instance-attribute ¤
OFF = COMPONENT_STATE_CODE_OFF

State when the component has successfully switched off.

PRECHARGER_CLOSED class-attribute instance-attribute ¤
PRECHARGER_CLOSED = COMPONENT_STATE_CODE_PRECHARGER_CLOSED

The precharger circuit is closed, allowing full current to flow to the main circuit.

PRECHARGER_OPEN class-attribute instance-attribute ¤
PRECHARGER_OPEN = COMPONENT_STATE_CODE_PRECHARGER_OPEN

The precharger circuit is open, meaning it's not currently active.

PRECHARGER_PRECHARGING class-attribute instance-attribute ¤
PRECHARGER_PRECHARGING = (
    COMPONENT_STATE_CODE_PRECHARGER_PRECHARGING
)

The precharger is in a precharging state, preparing the main circuit for activation.

READY class-attribute instance-attribute ¤
READY = COMPONENT_STATE_CODE_READY

State when the component is fully operational and ready for use.

RELAY_CLOSED class-attribute instance-attribute ¤
RELAY_CLOSED = COMPONENT_STATE_CODE_RELAY_CLOSED

The relay is in a closed state, allowing current to flow.

RELAY_OPEN class-attribute instance-attribute ¤
RELAY_OPEN = COMPONENT_STATE_CODE_RELAY_OPEN

The relay is in an open state, meaning no current can flow through.

STANDBY class-attribute instance-attribute ¤
STANDBY = COMPONENT_STATE_CODE_STANDBY

State when the component is in standby mode, and not immediately ready for operation.

SWITCHING_OFF class-attribute instance-attribute ¤
SWITCHING_OFF = COMPONENT_STATE_CODE_SWITCHING_OFF

State when the component is in the process of switching off.

SWITCHING_ON class-attribute instance-attribute ¤
SWITCHING_ON = COMPONENT_STATE_CODE_SWITCHING_ON

State when the component is in the process of switching on from an off state.

UNKNOWN class-attribute instance-attribute ¤
UNKNOWN = COMPONENT_STATE_CODE_UNKNOWN

State when the component is in an unknown or undefined condition.

This is used when the sender is unable to classify the component into any other state.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = COMPONENT_STATE_CODE_UNSPECIFIED

Default value when the component state is not explicitly set.

Functions¤
from_proto classmethod ¤
from_proto(
    component_state: ValueType,
) -> ComponentStateCode

Convert a protobuf ComponentStateCode message to ComponentStateCode enum.

PARAMETER DESCRIPTION
component_state

protobuf enum to convert

TYPE: ValueType

RETURNS DESCRIPTION
ComponentStateCode

Enum value corresponding to the protobuf message.
Source code in frequenz/client/common/microgrid/components/__init__.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
@classmethod
@deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
def from_proto(
    cls, component_state: PBComponentStateCode.ValueType
) -> ComponentStateCode:
    """Convert a protobuf ComponentStateCode message to ComponentStateCode enum.

    Args:
        component_state: protobuf enum to convert

    Returns:
        Enum value corresponding to the protobuf message.
    """
    if not any(c.value == component_state for c in ComponentStateCode):
        return ComponentStateCode.UNSPECIFIED
    return cls(component_state)
to_proto ¤
to_proto() -> ValueType

Convert a ComponentStateCode enum to protobuf ComponentStateCode message.

RETURNS DESCRIPTION
ValueType

Enum value corresponding to the protobuf message.
Source code in frequenz/client/common/microgrid/components/__init__.py 
230
231
232
233
234
235
236
def to_proto(self) -> PBComponentStateCode.ValueType:
    """Convert a ComponentStateCode enum to protobuf ComponentStateCode message.

    Returns:
        Enum value corresponding to the protobuf message.
    """
    return self.value