Skip to content

sensor

frequenz.client.microgrid.sensor ¤

Microgrid sensors.

This package provides classes and utilities for working with different types of sensors in a microgrid environment. Sensors measure various physical metrics in the surrounding environment, such as temperature, humidity, and solar irradiance.

Sensor Telemetry¤

This package also provides several data structures for handling sensor readings and states:

Classes¤

frequenz.client.microgrid.sensor.Sensor dataclass ¤

A sensor that measures physical metrics in the microgrid's surroundings.

Sensors are not part of the electrical infrastructure but provide environmental data such as temperature, humidity, and solar irradiance.

Source code in frequenz/client/microgrid/sensor/_sensor.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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
@dataclass(frozen=True, kw_only=True)
class Sensor:
    """A sensor that measures physical metrics in the microgrid's surroundings.

    Sensors are not part of the electrical infrastructure but provide
    environmental data such as temperature, humidity, and solar irradiance.
    """

    id: SensorId
    """A unique identifier for the sensor."""

    microgrid_id: MicrogridId
    """Unique identifier of the parent microgrid."""

    name: str | None = None
    """An optional name for the sensor."""

    manufacturer: str | None = None
    """The sensor manufacturer."""

    model_name: str | None = None
    """The model name of the sensor."""

    operational_lifetime: Lifetime = field(default_factory=Lifetime)
    """The operational lifetime of the sensor."""

    @property
    def identity(self) -> tuple[SensorId, MicrogridId]:
        """The identity of this sensor.

        This uses the sensor ID and microgrid ID to identify a sensor
        without considering the other attributes, so even if a sensor state
        changed, the identity remains the same.
        """
        return (self.id, self.microgrid_id)

    def __str__(self) -> str:
        """Return a human-readable string representation of this instance.

        Returns:
            A string representation of this sensor.
        """
        name = f":{self.name}" if self.name else ""
        return f"<{type(self).__name__}:{self.id}{name}>"
Attributes¤
id instance-attribute ¤
id: SensorId

A unique identifier for the sensor.

identity property ¤
identity: tuple[SensorId, MicrogridId]

The identity of this sensor.

This uses the sensor ID and microgrid ID to identify a sensor without considering the other attributes, so even if a sensor state changed, the identity remains the same.

manufacturer class-attribute instance-attribute ¤
manufacturer: str | None = None

The sensor manufacturer.

microgrid_id instance-attribute ¤
microgrid_id: MicrogridId

Unique identifier of the parent microgrid.

model_name class-attribute instance-attribute ¤
model_name: str | None = None

The model name of the sensor.

name class-attribute instance-attribute ¤
name: str | None = None

An optional name for the sensor.

operational_lifetime class-attribute instance-attribute ¤
operational_lifetime: Lifetime = field(
    default_factory=Lifetime
)

The operational lifetime of the sensor.

Functions¤
__str__ ¤
__str__() -> str

Return a human-readable string representation of this instance.

RETURNS DESCRIPTION
str

A string representation of this sensor.
Source code in frequenz/client/microgrid/sensor/_sensor.py 
50
51
52
53
54
55
56
57
def __str__(self) -> str:
    """Return a human-readable string representation of this instance.

    Returns:
        A string representation of this sensor.
    """
    name = f":{self.name}" if self.name else ""
    return f"<{type(self).__name__}:{self.id}{name}>"

frequenz.client.microgrid.sensor.SensorDiagnostic dataclass ¤

Diagnostic information for a sensor warning or error.

Provides detailed information about issues affecting a sensor.

Source code in frequenz/client/microgrid/sensor/_state.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
@dataclass(frozen=True, kw_only=True)
class SensorDiagnostic:
    """Diagnostic information for a sensor warning or error.

    Provides detailed information about issues affecting a sensor.
    """

    diagnostic_code: SensorDiagnosticCode | int
    """The diagnostic code identifying the type of issue."""

    message: str | None = None
    """Optional human-readable message describing the issue."""

    vendor_diagnostic_code: str | None = None
    """Optional vendor-specific diagnostic code."""
Attributes¤
diagnostic_code instance-attribute ¤
diagnostic_code: SensorDiagnosticCode | int

The diagnostic code identifying the type of issue.

message class-attribute instance-attribute ¤
message: str | None = None

Optional human-readable message describing the issue.

vendor_diagnostic_code class-attribute instance-attribute ¤
vendor_diagnostic_code: str | None = None

Optional vendor-specific diagnostic code.

frequenz.client.microgrid.sensor.SensorDiagnosticCode ¤

Bases: Enum

Sensor diagnostic code.

Provides additional diagnostic information about warnings or errors.

Source code in frequenz/client/microgrid/sensor/_state.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
@enum.unique
class SensorDiagnosticCode(enum.Enum):
    """Sensor diagnostic code.

    Provides additional diagnostic information about warnings or errors.
    """

    UNSPECIFIED = 0
    """Unspecified diagnostic code."""

    UNKNOWN = 1
    """Unknown diagnostic issue."""

    INTERNAL = 2
    """Internal sensor error."""
Attributes¤
INTERNAL class-attribute instance-attribute ¤
INTERNAL = 2

Internal sensor error.

UNKNOWN class-attribute instance-attribute ¤
UNKNOWN = 1

Unknown diagnostic issue.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = 0

Unspecified diagnostic code.

frequenz.client.microgrid.sensor.SensorStateCode ¤

Bases: Enum

Sensor state code.

Represents the operational state of a sensor.

Source code in frequenz/client/microgrid/sensor/_state.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@enum.unique
class SensorStateCode(enum.Enum):
    """Sensor state code.

    Represents the operational state of a sensor.
    """

    UNSPECIFIED = 0
    """Unspecified state."""

    OK = 1
    """Sensor is operating normally."""

    ERROR = 2
    """Sensor is in an error state."""
Attributes¤
ERROR class-attribute instance-attribute ¤
ERROR = 2

Sensor is in an error state.

OK class-attribute instance-attribute ¤
OK = 1

Sensor is operating normally.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = 0

Unspecified state.

frequenz.client.microgrid.sensor.SensorStateSnapshot dataclass ¤

A snapshot of a sensor's operational state at a specific time.

Contains the sensor's state codes and any associated diagnostic information.

Source code in frequenz/client/microgrid/sensor/_state.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@dataclass(frozen=True, kw_only=True)
class SensorStateSnapshot:
    """A snapshot of a sensor's operational state at a specific time.

    Contains the sensor's state codes and any associated diagnostic information.
    """

    origin_time: datetime
    """The timestamp when this state snapshot was recorded."""

    states: Set[SensorStateCode | int]
    """Set of state codes active at the snapshot time."""

    warnings: Sequence[SensorDiagnostic]
    """Sequence of active warnings with diagnostic information."""

    errors: Sequence[SensorDiagnostic]
    """Sequence of active errors with diagnostic information."""

    # Disable hashing for this class (mypy doesn't seem to understand assigining to
    # None, but it is documented in __hash__ docs).
    __hash__ = None  # type: ignore[assignment]
Attributes¤
errors instance-attribute ¤
errors: Sequence[SensorDiagnostic]

Sequence of active errors with diagnostic information.

origin_time instance-attribute ¤
origin_time: datetime

The timestamp when this state snapshot was recorded.

states instance-attribute ¤
states: Set[SensorStateCode | int]

Set of state codes active at the snapshot time.

warnings instance-attribute ¤
warnings: Sequence[SensorDiagnostic]

Sequence of active warnings with diagnostic information.

frequenz.client.microgrid.sensor.SensorTelemetry dataclass ¤

Telemetry data from a sensor.

Contains metric measurements and state snapshots for a specific sensor.

Source code in frequenz/client/microgrid/sensor/_telemetry.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
@dataclass(frozen=True, kw_only=True)
class SensorTelemetry:
    """Telemetry data from a sensor.

    Contains metric measurements and state snapshots for a specific sensor.
    """

    sensor_id: SensorId
    """The unique identifier of the sensor that produced this telemetry."""

    metric_samples: Sequence[MetricSample]
    """List of metric measurements from the sensor."""

    state_snapshots: Sequence[SensorStateSnapshot]
    """List of state snapshots indicating the sensor's operational status."""

    # Disable hashing for this class (mypy doesn't seem to understand assigining to
    # None, but it is documented in __hash__ docs).
    __hash__ = None  # type: ignore[assignment]
Attributes¤
metric_samples instance-attribute ¤
metric_samples: Sequence[MetricSample]

List of metric measurements from the sensor.

sensor_id instance-attribute ¤
sensor_id: SensorId

The unique identifier of the sensor that produced this telemetry.

state_snapshots instance-attribute ¤
state_snapshots: Sequence[SensorStateSnapshot]

List of state snapshots indicating the sensor's operational status.