innergrid 0.1.0__py3-none-any.whl

innergrid/__init__.py

@@ -0,0 +1,63 @@
+"""Asynchronous Python client for the energy data that Innergrid publishes."""
+
+from .const import CONNECTED_STATUSES, DEFAULT_PORT, Kind
+from .exceptions import (
+    InnergridAuthError,
+    InnergridConnectionError,
+    InnergridError,
+    InnergridTimeoutError,
+)
+from .innergrid import (
+    Innergrid,
+    Update,
+    parse_data,
+    parse_message,
+    topic_kind,
+    valid_topic_prefix,
+)
+from .models import (
+    Categories,
+    Category,
+    ChargePoint,
+    ChargePointEvent,
+    Circuit,
+    ElectricityMeter,
+    EnergyManager,
+    MilesightSensor,
+    Model,
+    Quantity,
+    Site,
+    SiteMeter,
+    Space,
+    SystemStatus,
+)
+
+__all__ = [
+    "CONNECTED_STATUSES",
+    "DEFAULT_PORT",
+    "Categories",
+    "Category",
+    "ChargePoint",
+    "ChargePointEvent",
+    "Circuit",
+    "ElectricityMeter",
+    "EnergyManager",
+    "Innergrid",
+    "InnergridAuthError",
+    "InnergridConnectionError",
+    "InnergridError",
+    "InnergridTimeoutError",
+    "Kind",
+    "MilesightSensor",
+    "Model",
+    "Quantity",
+    "Site",
+    "SiteMeter",
+    "Space",
+    "SystemStatus",
+    "Update",
+    "parse_data",
+    "parse_message",
+    "topic_kind",
+    "valid_topic_prefix",
+]

innergrid/const.py

@@ -0,0 +1,50 @@
+"""Constants for the Innergrid client."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+DEFAULT_PORT = 1883
+
+# The Milesight LoRaWAN sensors publish under their own fixed prefix.
+MILESIGHT_TOPIC = "milesight/uplink"
+
+
+class Kind(StrEnum):
+    """The kinds of data, derived from the topic."""
+
+    SITE = "site"
+    CATEGORIES = "categories"
+    METER = "meter"
+    CIRCUIT = "circuit"
+    CHARGE_POINT = "chargepoint"
+    ENERGY_MANAGER = "energymanager"
+    CHARGE_POINT_EVENT = "chargepointevent"
+    SPACE = "space"
+    SYSTEM = "system"
+    MILESIGHT = "milesight"
+
+
+# Charge point statuses (OCPP) in which a vehicle is connected.
+# THROTTLED_BY_EV: the vehicle charges, but limits the power itself.
+CONNECTED_STATUSES = frozenset(
+    {
+        "PREPARING",
+        "CHARGING",
+        "THROTTLED_BY_EV",
+        "SUSPENDED_BY_EV",
+        "SUSPENDED_BY_EVSE",
+        "FINISHING",
+    }
+)
+
+# Ranges outside which a climate value is not plausible. Some sensors report
+# impossible values, such as -1001.1 °C or 0% humidity, instead of an error.
+TEMPERATURE_RANGE = (-40.0, 80.0)
+HUMIDITY_RANGE = (0.1, 100.0)
+CO2_RANGE = (1.0, 10000.0)
+ILLUMINANCE_RANGE = (0.0, 200000.0)
+
+# CONNACK return codes (MQTT 3.1.1) and reason codes (MQTT 5) for a login
+# that the broker rejected.
+AUTH_FAILED_CODES = frozenset({4, 5, 134, 135})

innergrid/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions for the Innergrid client."""
+
+
+class InnergridError(Exception):
+    """Generic Innergrid exception."""
+
+
+class InnergridConnectionError(InnergridError):
+    """The connection to the MQTT broker failed or was lost."""
+
+
+class InnergridAuthError(InnergridConnectionError):
+    """The MQTT broker rejected the username or password."""
+
+
+class InnergridTimeoutError(InnergridError):
+    """No data arrived in time."""

innergrid/innergrid.py

@@ -0,0 +1,292 @@
+"""Asynchronous client for the data that Innergrid publishes over MQTT."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import aiomqtt
+
+from .const import (
+    AUTH_FAILED_CODES,
+    DEFAULT_PORT,
+    MILESIGHT_TOPIC,
+    Kind,
+)
+from .exceptions import (
+    InnergridAuthError,
+    InnergridConnectionError,
+    InnergridTimeoutError,
+)
+from .models import (
+    Categories,
+    ChargePoint,
+    ChargePointEvent,
+    Circuit,
+    ElectricityMeter,
+    EnergyManager,
+    MilesightSensor,
+    Site,
+    Space,
+    SystemStatus,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .models import Model
+
+_LOGGER = logging.getLogger(__name__)
+
+# Topics below the prefix and the kind of data they carry. The first group
+# is the ID of the device or site.
+TOPIC_KINDS: list[tuple[re.Pattern[str], Kind]] = [
+    (re.compile(r"customersites/(\d+)/live"), Kind.SITE),
+    (re.compile(r"categories/(\d+)/live"), Kind.CATEGORIES),
+    (re.compile(r"electricitymeters/(\d+)"), Kind.METER),
+    (re.compile(r"circuits/(\d+)/live"), Kind.CIRCUIT),
+    (re.compile(r"chargepoints/(\d+)"), Kind.CHARGE_POINT),
+    (re.compile(r"energymanagers/(\d+)/state"), Kind.ENERGY_MANAGER),
+    (re.compile(r"events/chargepoints/(\d+)/\w+"), Kind.CHARGE_POINT_EVENT),
+    (re.compile(r"spaces/(\d+)/live"), Kind.SPACE),
+    (re.compile(r"(system)"), Kind.SYSTEM),
+]
+MILESIGHT_PATTERN = re.compile(re.escape(MILESIGHT_TOPIC) + r"/([0-9a-fA-F]+)")
+
+PARSERS: dict[Kind, Callable[[dict[str, Any], str], Model]] = {
+    Kind.SITE: Site.from_dict,
+    Kind.CATEGORIES: Categories.from_dict,
+    Kind.METER: ElectricityMeter.from_dict,
+    Kind.CIRCUIT: Circuit.from_dict,
+    Kind.CHARGE_POINT: ChargePoint.from_dict,
+    Kind.ENERGY_MANAGER: EnergyManager.from_dict,
+    Kind.CHARGE_POINT_EVENT: ChargePointEvent.from_dict,
+    Kind.SPACE: Space.from_dict,
+    Kind.SYSTEM: SystemStatus.from_dict,
+    Kind.MILESIGHT: MilesightSensor.from_dict,
+}
+
+
+@dataclass(frozen=True)
+class Update:
+    """The data of a message.
+
+    The key ("<kind>/<id>", for example "meter/10005") identifies the topic;
+    the latest update of a key replaces the earlier ones.
+    """
+
+    kind: Kind
+    id: str
+    data: Model
+    raw: dict[str, Any]
+
+    @property
+    def key(self) -> str:
+        """Return the key of the topic."""
+        return f"{self.kind}/{self.id}"
+
+
+def valid_topic_prefix(prefix: str) -> bool:
+    """Return whether a topic prefix is valid: not empty, without wildcards."""
+    prefix = prefix.strip().strip("/")
+    return bool(prefix) and "#" not in prefix and "+" not in prefix
+
+
+def topic_kind(prefix: str, topic: str) -> tuple[Kind, str] | None:
+    """Return the kind and ID of a topic, or None for topics that are not used."""
+    if match := MILESIGHT_PATTERN.fullmatch(topic):
+        return Kind.MILESIGHT, match.group(1).lower()
+    if not topic.startswith(f"{prefix}/"):
+        return None
+    subtopic = topic.removeprefix(f"{prefix}/")
+    for pattern, kind in TOPIC_KINDS:
+        if match := pattern.fullmatch(subtopic):
+            return kind, match.group(1)
+    return None
+
+
+def parse_message(prefix: str, topic: str, payload: Any) -> Update | None:
+    """Parse a message, or return None if it is not used or not valid.
+
+    Args:
+    ----
+        prefix: The topic prefix, for example mysite.
+        topic: The topic the message was published on.
+        payload: The payload of the message, a JSON object.
+
+    Returns:
+    -------
+        The parsed data, or None.
+
+    """
+    if (kind_id := topic_kind(prefix, topic)) is None:
+        return None
+    kind, idx = kind_id
+    try:
+        data = json.loads(payload)
+    except (TypeError, ValueError):
+        _LOGGER.debug("Ignoring message on %s that is not JSON", topic)
+        return None
+    if not isinstance(data, dict):
+        _LOGGER.debug("Ignoring message on %s that is not a JSON object", topic)
+        return None
+    return parse_data(kind, idx, data)
+
+
+def parse_data(kind: Kind | str, idx: str, data: dict[str, Any]) -> Update:
+    """Parse the payload of a topic, for example one that was stored earlier.
+
+    Args:
+    ----
+        kind: The kind of data, as in Update.kind.
+        idx: The ID from the topic, as in Update.id.
+        data: The payload, as in Update.raw.
+
+    Returns:
+    -------
+        The parsed data.
+
+    """
+    kind = Kind(kind)
+    return Update(kind=kind, id=idx, data=PARSERS[kind](data, idx), raw=data)
+
+
+class Innergrid:
+    """Receive the energy and building data that Innergrid publishes over MQTT."""
+
+    def __init__(  # noqa: PLR0913 # pylint: disable=too-many-arguments
+        self,
+        host: str,
+        port: int = DEFAULT_PORT,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        topic_prefix: str,
+        timeout: float = 10.0,
+    ) -> None:
+        """Initialise the client.
+
+        Args:
+        ----
+            host: The MQTT broker.
+            port: The port of the MQTT broker.
+            username: The username, if the broker requires a login.
+            password: The password, if the broker requires a login.
+            topic_prefix: The first part of the topics: the customer site, for
+                example mysite.
+            timeout: Seconds to wait for the broker to respond.
+
+        Raises:
+        ------
+            ValueError: The topic prefix is empty or has MQTT wildcards.
+
+        """
+        self.host = host
+        self.port = port
+        self.username = username
+        self.password = password
+        self.topic_prefix = topic_prefix.strip().strip("/")
+        if not valid_topic_prefix(self.topic_prefix):
+            msg = f"Invalid topic prefix: {topic_prefix!r}"
+            raise ValueError(msg)
+        self.timeout = timeout
+
+    def _client(self) -> aiomqtt.Client:
+        """Create an MQTT client."""
+        return aiomqtt.Client(
+            self.host,
+            self.port,
+            username=self.username or None,
+            password=self.password or None,
+            timeout=self.timeout,
+        )
+
+    def _connection_error(self, err: aiomqtt.MqttError) -> InnergridConnectionError:
+        """Return the exception for an MQTT error."""
+        if isinstance(err, aiomqtt.MqttCodeError):
+            code = getattr(err.rc, "value", err.rc)
+            if code in AUTH_FAILED_CODES:
+                return InnergridAuthError(
+                    f"{self.host} rejected the username or password"
+                )
+        return InnergridConnectionError(f"Connection to {self.host} failed: {err}")
+
+    async def listen(
+        self,
+        callback: Callable[[Update], None],
+        on_connect: Callable[[], None] | None = None,
+    ) -> None:
+        """Connect and call the callback with the data of every message.
+
+        Runs until the connection fails or is lost, or the task is cancelled.
+
+        Args:
+        ----
+            callback: Called with the data of every message.
+            on_connect: Called after connecting and subscribing.
+
+        Raises:
+        ------
+            InnergridAuthError: The broker rejected the login.
+            InnergridConnectionError: The connection failed or was lost.
+
+        """
+        try:
+            async with self._client() as client:
+                await client.subscribe(f"{self.topic_prefix}/#")
+                await client.subscribe(f"{MILESIGHT_TOPIC}/#")
+                if on_connect is not None:
+                    on_connect()
+                async for message in client.messages:
+                    update = parse_message(
+                        self.topic_prefix, message.topic.value, message.payload
+                    )
+                    if update is not None:
+                        callback(update)
+        except aiomqtt.MqttError as err:
+            raise self._connection_error(err) from err
+        # The broker closed the connection without an error.
+        msg = f"Connection to {self.host} was closed"
+        raise InnergridConnectionError(msg)
+
+    async def wait_for_data(self, wait_seconds: float = 30.0) -> Update:
+        """Connect and wait for the first message below the topic prefix.
+
+        Use this to check the settings.
+
+        Args:
+        ----
+            wait_seconds: Seconds to wait for a message.
+
+        Returns:
+        -------
+            The data of the first message.
+
+        Raises:
+        ------
+            InnergridAuthError: The broker rejected the login.
+            InnergridConnectionError: The connection failed.
+            InnergridTimeoutError: No message arrived in time.
+
+        """
+        try:
+            async with self._client() as client:
+                await client.subscribe(f"{self.topic_prefix}/#")
+                async with asyncio.timeout(wait_seconds):
+                    async for message in client.messages:
+                        update = parse_message(
+                            self.topic_prefix, message.topic.value, message.payload
+                        )
+                        if update is not None:
+                            return update
+        except aiomqtt.MqttError as err:
+            raise self._connection_error(err) from err
+        except TimeoutError as err:
+            msg = f"No data below {self.topic_prefix}/ within {wait_seconds} seconds"
+            raise InnergridTimeoutError(msg) from err
+        msg = f"Connection to {self.host} was closed"
+        raise InnergridConnectionError(msg)

innergrid/models.py

@@ -0,0 +1,714 @@
+# pylint: disable=too-many-instance-attributes
+"""Models of the data that Innergrid publishes."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any, Self, TypeAlias
+
+from .const import (
+    CO2_RANGE,
+    CONNECTED_STATUSES,
+    HUMIDITY_RANGE,
+    ILLUMINANCE_RANGE,
+    TEMPERATURE_RANGE,
+)
+
+
+def get_path(data: Any, path: str) -> Any:
+    """Return the value at a dotted path, or None if a part is missing."""
+    value = data
+    for part in path.split("."):
+        if not isinstance(value, dict):
+            return None
+        value = value.get(part)
+    return value
+
+
+def _number(value: Any) -> float | None:
+    """Return the value if it is a finite number.
+
+    JSON payloads can hold NaN and Infinity, which are not valid values.
+    """
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return None
+    return value if math.isfinite(value) else None
+
+
+def _int(value: Any) -> int | None:
+    """Return the value if it is a whole number."""
+    number = _number(value)
+    return None if number is None else int(number)
+
+
+def _text(value: Any) -> str | None:
+    """Return a non-empty string, without surrounding whitespace."""
+    if not isinstance(value, str) or not (text := value.strip()):
+        return None
+    return text
+
+
+def _bool(value: Any) -> bool | None:
+    """Return a boolean, or a 0/1 number, as a boolean."""
+    if isinstance(value, bool | int):
+        return bool(value)
+    return None
+
+
+def _timestamp(value: Any) -> datetime | None:
+    """Parse an ISO 8601 timestamp."""
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+
+
+def _epoch(value: Any) -> datetime | None:
+    """Return a Unix timestamp as a datetime; 0 means never."""
+    if not (seconds := _number(value)):
+        return None
+    try:
+        return datetime.fromtimestamp(seconds, tz=UTC)
+    except (OverflowError, OSError, ValueError):
+        return None
+
+
+def _seconds(value: Any) -> timedelta | None:
+    """Return a number of seconds as a timedelta."""
+    if (seconds := _number(value)) is None:
+        return None
+    try:
+        return timedelta(seconds=seconds)
+    except OverflowError:
+        return None
+
+
+def plausible(value: Any, valid_range: tuple[float, float]) -> float | None:
+    """Return the value if it is a number within the range, otherwise None."""
+    number = _number(value)
+    if number is None or not valid_range[0] <= number <= valid_range[1]:
+        return None
+    return number
+
+
+def _id(data: dict[str, Any], default: str) -> str:
+    """Return the ID in the data, or the default (the ID from the topic)."""
+    value = data.get("id")
+    return default if value is None else str(value)
+
+
+@dataclass
+class SiteMeter:
+    """A meter of a site: the grid connection, production or consumption."""
+
+    id: str | None
+    name: str | None
+    active_power: float | None
+    energy_imported_24h: float | None
+    energy_exported_24h: float | None
+    max_power_quarter_hour_import: float | None
+    max_power_quarter_hour_export: float | None
+    continuous_import_limit: float | None
+    continuous_export_limit: float | None
+
+    @classmethod
+    def from_dict(cls, data: Any) -> SiteMeter | None:
+        """Return the meter, or None if the site does not have it."""
+        if not isinstance(data, dict):
+            return None
+        meter_id = data.get("id")
+        return cls(
+            id=None if meter_id is None else str(meter_id),
+            name=_text(data.get("name")),
+            active_power=_number(data.get("activePower")),
+            energy_imported_24h=_number(data.get("energyImported24h")),
+            energy_exported_24h=_number(data.get("energyExported24h")),
+            max_power_quarter_hour_import=_number(
+                data.get("maxActivePowerQuarterHourImport")
+            ),
+            max_power_quarter_hour_export=_number(
+                data.get("maxActivePowerQuarterHourExport")
+            ),
+            continuous_import_limit=_number(
+                data.get("continuousActivePowerImportLimit")
+            ),
+            continuous_export_limit=_number(
+                data.get("continuousActivePowerExportLimit")
+            ),
+        )
+
+
+@dataclass
+class Site:
+    """The overview of a customer site (customersites/<id>/live).
+
+    Energy and money are totals of the last 24 hours, which go up and down.
+    """
+
+    id: str
+    grid: SiteMeter | None
+    production: SiteMeter | None
+    consumption: SiteMeter | None
+    battery_storage: SiteMeter | None
+    expense_24h: float | None
+    revenue_24h: float | None
+    energy_price_import: float | None
+    energy_price_export: float | None
+    main_circuit_load_factor: float | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], site_id: str = "") -> Self:
+        """Parse the payload of a site."""
+        return cls(
+            id=_id(data, site_id),
+            grid=SiteMeter.from_dict(get_path(data, "electricityMeters.main")),
+            production=SiteMeter.from_dict(
+                get_path(data, "electricityMeters.production")
+            ),
+            consumption=SiteMeter.from_dict(
+                get_path(data, "electricityMeters.consumption")
+            ),
+            battery_storage=SiteMeter.from_dict(
+                get_path(data, "electricityMeters.batteryStorage")
+            ),
+            expense_24h=_number(data.get("expense24h")),
+            revenue_24h=_number(data.get("revenue24h")),
+            energy_price_import=_number(get_path(data, "energyPrices.import")),
+            energy_price_export=_number(get_path(data, "energyPrices.export")),
+            main_circuit_load_factor=_number(
+                get_path(data, "mainCircuit.currentLoadFactor1Minute")
+            ),
+        )
+
+
+@dataclass
+class Category:
+    """The energy of a category of a site, such as lighting or the kitchen."""
+
+    key: str
+    name: str
+    active_power: float | None
+    energy_imported_24h: float | None
+    energy_exported_24h: float | None
+    expense_24h: float | None
+    revenue_24h: float | None
+
+    @classmethod
+    def from_dict(cls, key: str, data: dict[str, Any]) -> Self:
+        """Parse a category."""
+        return cls(
+            key=key,
+            name=_text(data.get("name")) or key,
+            active_power=_number(data.get("activePower")),
+            energy_imported_24h=_number(data.get("energyImported24h")),
+            energy_exported_24h=_number(data.get("energyExported24h")),
+            expense_24h=_number(data.get("expense24h")),
+            revenue_24h=_number(data.get("revenue24h")),
+        )
+
+
+@dataclass
+class Categories:
+    """The energy categories of a site (categories/<id>/live)."""
+
+    site_id: str
+    categories: dict[str, Category]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], site_id: str = "") -> Self:
+        """Parse the payload of the categories of a site."""
+        categories = data.get("categories")
+        if not isinstance(categories, dict):
+            categories = {}
+        return cls(
+            site_id=site_id,
+            categories={
+                key: Category.from_dict(key, values)
+                for key, values in categories.items()
+                if isinstance(values, dict)
+            },
+        )
+
+
+@dataclass(frozen=True)
+class Quantity:
+    """A quantity that a meter measures, with its name and unit.
+
+    The unit is as the platform names it, for example power.watt.
+    """
+
+    name: str
+    unit: str
+
+
+@dataclass
+class ElectricityMeter:
+    """An electricity meter (electricitymeters/<id>).
+
+    The measurements are by quantity, for example activePower or
+    activePowerL1; the quantities describe their names and units.
+    """
+
+    id: str
+    name: str
+    module_name: str | None
+    location: str | None
+    circuit_id: str | None
+    is_three_phase: bool | None
+    measurements: dict[str, float | None]
+    quantities: dict[str, Quantity]
+
+    @property
+    def manufacturer(self) -> str | None:
+        """Return the manufacturer: the first word of the module name."""
+        return self.module_name.split()[0] if self.module_name else None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], meter_id: str = "") -> Self:
+        """Parse the payload of an electricity meter."""
+        measurements = data.get("measurements")
+        if not isinstance(measurements, dict):
+            measurements = {}
+        quantities = data.get("loggedQuantities")
+        if not isinstance(quantities, dict):
+            quantities = {}
+        circuit_id = data.get("circuitId")
+        meter_id = _id(data, meter_id)
+        return cls(
+            id=meter_id,
+            name=_text(data.get("name")) or meter_id,
+            module_name=_text(data.get("moduleName")),
+            location=_text(data.get("location")),
+            circuit_id=None if circuit_id is None else str(circuit_id),
+            is_three_phase=_bool(data.get("isThreePhase")),
+            measurements={key: _number(value) for key, value in measurements.items()},
+            quantities={
+                key: Quantity(
+                    name=_text(quantity.get("name")) or key,
+                    unit=str(quantity.get("unit") or ""),
+                )
+                for key, quantity in quantities.items()
+                if isinstance(quantity, dict) and key in measurements
+            },
+        )
+
+
+@dataclass
+class Circuit:
+    """A circuit, measured by an electricity meter (circuits/<id>/live).
+
+    Load factors are fractions of the circuit's limit, for example 0.25.
+    """
+
+    id: str
+    name: str
+    electricity_meter_id: str | None
+    is_three_phase: bool | None
+    active_power: float | None
+    current_l1: float | None
+    current_l2: float | None
+    current_l3: float | None
+    load_factor_1m: float | None
+    load_factor_5m: float | None
+    load_factor_15m: float | None
+    average_power_import_15m: float | None
+    average_power_export_15m: float | None
+    current_limit: float | None
+    warnings: int | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], circuit_id: str = "") -> Self:
+        """Parse the payload of a circuit."""
+        meter_id = data.get("electricityMeterId")
+        circuit_id = _id(data, circuit_id)
+        return cls(
+            id=circuit_id,
+            name=_text(data.get("name")) or circuit_id,
+            electricity_meter_id=None if meter_id is None else str(meter_id),
+            is_three_phase=_bool(data.get("isThreePhase")),
+            active_power=_number(data.get("activePower")),
+            current_l1=_number(data.get("currentL1")),
+            current_l2=_number(data.get("currentL2")),
+            current_l3=_number(data.get("currentL3")),
+            load_factor_1m=_number(get_path(data, "currentLoadFactor.1-minute")),
+            load_factor_5m=_number(get_path(data, "currentLoadFactor.5-minute")),
+            load_factor_15m=_number(get_path(data, "currentLoadFactor.15-minute")),
+            average_power_import_15m=_number(
+                get_path(data, "averageActivePower.15-minute.import")
+            ),
+            average_power_export_15m=_number(
+                get_path(data, "averageActivePower.15-minute.export")
+            ),
+            current_limit=_number(get_path(data, "instantaneousLimits.current")),
+            warnings=_int(data.get("warnings")),
+        )
+
+
+@dataclass
+class ChargePoint:
+    """A charge point and its (last) session (chargepoints/<id>).
+
+    The session fields keep the values of the last session after it ended.
+    """
+
+    id: str
+    name: str
+    status: str | None
+    charging_state: str | None
+    charge_strategy: str | None
+    username: str | None
+    started_at: datetime | None
+    finished_at: datetime | None
+    departure_at: datetime | None
+    target_energy: float | None
+    minimum_power: float | None
+    active_power: float | None
+    energy_charged: float | None
+    charge_current: float | None
+    phases_enabled: int | None
+    power_instruction: float | None
+
+    @property
+    def is_plugged_in(self) -> bool | None:
+        """Return whether a vehicle is connected."""
+        return None if self.status is None else self.status in CONNECTED_STATUSES
+
+    @property
+    def is_charging(self) -> bool | None:
+        """Return whether the vehicle is charging.
+
+        The charging state is CHARGING also while the vehicle limits the power
+        (status THROTTLED_BY_EV); without it, the status tells.
+        """
+        if self.charging_state is not None:
+            return self.charging_state == "CHARGING"
+        return None if self.status is None else self.status == "CHARGING"
+
+    @property
+    def current_user(self) -> str | None:
+        """Return who is charging; None when no vehicle is connected."""
+        return self.username if self.is_plugged_in else None
+
+    @property
+    def session_finished_at(self) -> datetime | None:
+        """Return the end of the session, unless a newer session started."""
+        if self.finished_at is None or (
+            self.started_at is not None and self.finished_at < self.started_at
+        ):
+            return None
+        return self.finished_at
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], charge_point_id: str = "") -> Self:
+        """Parse the payload of a charge point."""
+        charge_point_id = _id(data, charge_point_id)
+        return cls(
+            id=charge_point_id,
+            name=_text(data.get("name")) or charge_point_id,
+            status=_text(get_path(data, "session.status")),
+            charging_state=_text(get_path(data, "session.chargingState")),
+            charge_strategy=_text(get_path(data, "session.chargeStrategy")),
+            username=_text(get_path(data, "session.username")),
+            started_at=_timestamp(get_path(data, "session.startedAt")),
+            finished_at=_timestamp(get_path(data, "session.finishedAt")),
+            departure_at=_timestamp(get_path(data, "session.departureAt")),
+            target_energy=_number(get_path(data, "session.targetEnergyRequest")),
+            minimum_power=_number(get_path(data, "session.minimumPower")),
+            active_power=_number(get_path(data, "measurements.activePower")),
+            energy_charged=_number(get_path(data, "measurements.energyCharged")),
+            charge_current=_number(get_path(data, "powerManagement.chargeCurrent")),
+            phases_enabled=_int(get_path(data, "powerManagement.phasesEnabled")),
+            power_instruction=_number(
+                get_path(data, "powerManagement.powerInstruction")
+            ),
+        )
+
+
+@dataclass
+class EnergyManager:
+    """The state of the energy manager (energymanagers/<id>/state)."""
+
+    id: str
+    name: str
+    is_abnormal_condition: bool | None
+    is_temporary_over_limit_applied: bool | None
+    is_solar_charging_only: bool | None
+    grid_power: float | None
+    solar_power: float | None
+    charge_point_power: float | None
+    climate_power: float | None
+    baseload_power: float | None
+    inflexible_power: float | None
+    battery_power: float | None
+    optimized_import_power: float | None
+    flexible_power: float | None
+    continuous_import_limit: float | None
+    instantaneous_import_limit: float | None
+    continuous_export_limit: float | None
+    instantaneous_export_limit: float | None
+    peak_shaving_limit: float | None
+    optimization_goal: str | None
+    binding_limit: str | None
+    strategy: str | None
+    cheapest_period_start: datetime | None
+    cheapest_period_price: float | None
+    baseline_price: float | None
+    export_price: float | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], manager_id: str = "") -> Self:
+        """Parse the payload of the energy manager's state."""
+        manager = data.get("energyManager")
+        if not isinstance(manager, dict):
+            manager = {}
+        manager_id = _id(manager, manager_id)
+
+        def power(name: str) -> float | None:
+            return _number(get_path(manager, f"powerValues.{name}"))
+
+        def strategy(path: str) -> Any:
+            return get_path(manager, f"strategy.{path}")
+
+        return cls(
+            id=manager_id,
+            name=_text(manager.get("name")) or manager_id,
+            is_abnormal_condition=_bool(manager.get("isAbnormalCondition")),
+            is_temporary_over_limit_applied=_bool(
+                manager.get("isTemporaryOverLimitApplied")
+            ),
+            is_solar_charging_only=_bool(manager.get("isSolarChargingOnly")),
+            grid_power=power("gridActivePower"),
+            solar_power=power("solarPower"),
+            charge_point_power=power("chargePointPower"),
+            climate_power=power("climatePower"),
+            baseload_power=power("baseloadPower"),
+            inflexible_power=power("inflexiblePower"),
+            battery_power=power("batteryPower"),
+            optimized_import_power=power("optimizedImportPower"),
+            flexible_power=power("appliedFlexibleResourcePower"),
+            continuous_import_limit=power("continuousActivePowerImportLimit"),
+            instantaneous_import_limit=power("instantaneousActivePowerImportLimit"),
+            continuous_export_limit=power("continuousActivePowerExportLimit"),
+            instantaneous_export_limit=power("instantaneousActivePowerExportLimit"),
+            peak_shaving_limit=power("peakShavingResourcePowerLimit"),
+            optimization_goal=_text(strategy("optimizationGoal")),
+            binding_limit=_text(strategy("bindingLimit")),
+            strategy=_text(strategy("description")),
+            cheapest_period_start=_timestamp(
+                strategy("optimizationStrategy.cheapestPeriodStart")
+            ),
+            cheapest_period_price=_number(
+                strategy("optimizationStrategy.cheapestPeriodPrice")
+            ),
+            baseline_price=_number(strategy("optimizationStrategy.baselinePrice")),
+            export_price=_number(strategy("optimizationStrategy.currentExportPrice")),
+        )
+
+
+# The values of a space, by attribute name and name in the payload.
+SPACE_VALUES = {
+    "temperature": "temperature",
+    "humidity": "relativeHumidity",
+    "co2": "co2Concentration",
+    "illuminance": "illuminance",
+    "air_quality": "airQuality",
+    "presence": "presence",
+    "occupancy": "occupancy",
+}
+
+
+@dataclass
+class Space:
+    """The climate and presence of a space (spaces/<id>/live).
+
+    The payload does not include the space's name. Values that are stale or
+    not plausible (for example -1001.1 °C) are None. `measured` holds the
+    names of the values that the space has sensors for.
+    """
+
+    id: str
+    temperature: float | None
+    humidity: float | None
+    co2: float | None
+    illuminance: float | None
+    air_quality: str | None
+    presence: bool | None
+    occupancy: bool | None
+    low_battery_count: int | None
+    measured: frozenset[str] = field(default_factory=frozenset)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], space_id: str = "") -> Self:
+        """Parse the payload of a space."""
+        values = data.get("values")
+        if not isinstance(values, dict):
+            values = {}
+
+        def value(name: str, key: str = "value") -> Any:
+            entry = values.get(SPACE_VALUES[name])
+            if not isinstance(entry, dict) or entry.get("isStale"):
+                return None
+            return entry.get(key)
+
+        return cls(
+            id=_id(data, space_id),
+            temperature=plausible(value("temperature"), TEMPERATURE_RANGE),
+            humidity=plausible(value("humidity"), HUMIDITY_RANGE),
+            co2=plausible(value("co2"), CO2_RANGE),
+            illuminance=plausible(value("illuminance"), ILLUMINANCE_RANGE),
+            air_quality=(
+                None
+                if value("air_quality") is None
+                else _text(value("air_quality", "label"))
+            ),
+            presence=_bool(value("presence")),
+            occupancy=_bool(value("occupancy")),
+            low_battery_count=_int(data.get("lowBatteryCount")),
+            measured=frozenset(
+                name
+                for name, key in SPACE_VALUES.items()
+                if get_path(values, f"{key}.updatedAt") is not None
+            ),
+        )
+
+
+@dataclass
+class SystemStatus:
+    """The status of the server that publishes the data (system).
+
+    Memory and disk sizes are in MiB.
+    """
+
+    cpu_usage: float | None
+    memory_available: float | None
+    memory_total: float | None
+    disk_free: float | None
+    disk_total: float | None
+    last_backup_at: datetime | None
+    backup_file_count: int | None
+    system_uptime: timedelta | None
+    symcon_uptime: timedelta | None
+    symcon_version: str | None
+    module_library_version: str | None
+    io_connection_faults: int | None
+    instances_not_active: int | None
+    overdue_timers: int | None
+    api_request_count: int | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], _system_id: str = "") -> Self:
+        """Parse the payload of the system status."""
+        return cls(
+            cpu_usage=_number(data.get("cpuUsage")),
+            memory_available=_number(data.get("availableMemory")),
+            memory_total=_number(data.get("totalMemory")),
+            disk_free=_number(data.get("filesystemFreeSpace")),
+            disk_total=_number(data.get("filesystemTotalSpace")),
+            last_backup_at=_epoch(data.get("lastBackupAt")),
+            backup_file_count=_int(data.get("backupFileCount")),
+            system_uptime=_seconds(data.get("systemUptimeSeconds")),
+            symcon_uptime=_seconds(data.get("symconUptimeSeconds")),
+            symcon_version=_text(data.get("symconVersion")),
+            module_library_version=_text(data.get("moduleLibraryVersion")),
+            io_connection_faults=_int(data.get("ioConnectionFaults")),
+            instances_not_active=_int(data.get("instancesNotActive")),
+            overdue_timers=_int(data.get("overdueTimers")),
+            api_request_count=_int(data.get("apiRequestCount")),
+        )
+
+
+# The values of a Milesight sensor, by attribute name and name in the payload.
+MILESIGHT_VALUES = {
+    "temperature": "temperature",
+    "humidity": "humidity",
+    "co2": "co2",
+    "illuminance": "light",
+    "motion": "motion",
+    "battery_voltage": "vdd",
+}
+
+
+@dataclass
+class MilesightSensor:
+    """A Milesight LoRaWAN sensor (milesight/uplink/<devEUI>).
+
+    Values that are not plausible are None. `measured` holds the names of
+    the values in the payload, which depend on the sensor's model. The
+    illuminance is in lux and the battery voltage in mV. Motion is true when
+    the sensor counted any motion (the count can be higher than 1).
+    """
+
+    eui: str
+    temperature: float | None
+    humidity: float | None
+    co2: float | None
+    illuminance: float | None
+    motion: bool | None
+    battery_voltage: float | None
+    measured: frozenset[str] = field(default_factory=frozenset)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], eui: str = "") -> Self:
+        """Parse the payload of a Milesight sensor."""
+        return cls(
+            eui=eui,
+            temperature=plausible(data.get("temperature"), TEMPERATURE_RANGE),
+            humidity=plausible(data.get("humidity"), HUMIDITY_RANGE),
+            co2=plausible(data.get("co2"), CO2_RANGE),
+            illuminance=plausible(data.get("light"), ILLUMINANCE_RANGE),
+            motion=_bool(data.get("motion")),
+            battery_voltage=_number(data.get("vdd")),
+            measured=frozenset(
+                name for name, key in MILESIGHT_VALUES.items() if key in data
+            ),
+        )
+
+
+@dataclass
+class ChargePointEvent:
+    """An event of a charge point (events/chargepoints/<id>/<event>).
+
+    The charge point publishes `sessionchanged` when its session changes, for
+    example when charging starts or stops. `charge_point` holds the session
+    after the change; its other fields are None.
+    """
+
+    charge_point_id: str
+    event: str
+    time: datetime | None
+    charge_point: ChargePoint
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], charge_point_id: str = "") -> Self:
+        """Parse the payload of a charge point event."""
+        payload = data.get("payload")
+        if not isinstance(payload, dict):
+            payload = {}
+        return cls(
+            charge_point_id=charge_point_id,
+            event=_text(data.get("name")) or "",
+            time=_timestamp(data.get("time")),
+            charge_point=ChargePoint.from_dict(
+                {"session": payload.get("session")}, charge_point_id
+            ),
+        )
+
+
+# Python 3.11 does not support the type statement.
+Model: TypeAlias = (
+    Site
+    | Categories
+    | ElectricityMeter
+    | Circuit
+    | ChargePoint
+    | ChargePointEvent
+    | EnergyManager
+    | Space
+    | SystemStatus
+    | MilesightSensor
+)

innergrid-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: innergrid
+Version: 0.1.0
+Summary: Asynchronous Python client for the energy and building data that Innergrid publishes over MQTT.
+Keywords: async,client,energy,mqtt,innergrid
+Author: Robbin Janssen
+Author-email: Robbin Janssen <robbinjanssen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: aiomqtt>=2.0.0
+Maintainer: Robbin Janssen
+Maintainer-email: Robbin Janssen <robbinjanssen@gmail.com>
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/robbinjanssen/python-innergrid
+Project-URL: Repository, https://github.com/robbinjanssen/python-innergrid
+Project-URL: Documentation, https://github.com/robbinjanssen/python-innergrid
+Project-URL: Bug Tracker, https://github.com/robbinjanssen/python-innergrid/issues
+Project-URL: Changelog, https://github.com/robbinjanssen/python-innergrid/releases
+Description-Content-Type: text/markdown
+
+# Python: Innergrid
+
+Asynchronous Python client that reads the energy and building data that the
+Innergrid energy management platform publishes over MQTT for a customer site:
+the grid connection, energy categories, electricity meters and circuits,
+charge points, the energy manager, spaces, the server and Milesight LoRaWAN
+sensors.
+
+## Installation
+
+```sh
+pip install innergrid
+```
+
+## Usage
+
+```python
+import asyncio
+
+from innergrid import Innergrid, Update
+
+
+def on_update(update: Update) -> None:
+    print(update.key, update.data)
+
+
+async def main() -> None:
+    client = Innergrid("192.0.2.10", 1883, topic_prefix="mysite")
+    # Check the settings: wait for the first message below the prefix.
+    await client.wait_for_data()
+    # Runs until the connection is lost; connect again to continue.
+    await client.listen(on_update)
+
+
+asyncio.run(main())
+```
+
+`listen()` and `wait_for_data()` raise `InnergridAuthError` when the
+broker rejects the login and `InnergridConnectionError` when the connection
+fails or is lost. `wait_for_data()` raises `InnergridTimeoutError` when no
+data arrives in time.
+
+## Topics
+
+| Topic | Model |
+| --- | --- |
+| `<prefix>/customersites/<id>/live` | `Site` |
+| `<prefix>/categories/<id>/live` | `Categories` |
+| `<prefix>/electricitymeters/<id>` | `ElectricityMeter` |
+| `<prefix>/circuits/<id>/live` | `Circuit` |
+| `<prefix>/chargepoints/<id>` | `ChargePoint` |
+| `<prefix>/energymanagers/<id>/state` | `EnergyManager` |
+| `<prefix>/spaces/<id>/live` | `Space` |
+| `<prefix>/system` | `SystemStatus` |
+| `<prefix>/events/chargepoints/<id>/<event>` | `ChargePointEvent` |
+| `milesight/uplink/<devEUI>` | `MilesightSensor` |
+
+Every update has a key (`<kind>/<id>`, for example `meter/10005`); the
+latest update of a key replaces the earlier ones. The topics are not
+retained, so the data arrives as it is published, every 10 seconds to 3
+minutes.
+
+`parse_data(kind, id, raw)` parses a payload that was stored earlier, for
+example `update.raw`, into an `Update` again.
+
+Climate values that are not plausible, such as -1001.1 °C or 0% humidity,
+are `None`; some sensors report those instead of an error.
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) and
+[prek](https://github.com/j178/prek).
+
+```sh
+uv sync
+uv run prek install
+uv run pytest
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

innergrid-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+innergrid/__init__.py,sha256=I24Uv-RJEYhW0eTsbDN44EI40LPPEy5D0epMVwnyZn8,1190
+innergrid/const.py,sha256=cGRFie17dhWzauNR6F07QhW9Uo13gogXkrg6nflKPcQ,1346
+innergrid/exceptions.py,sha256=_8a2ldiENfbpcPpvAChryKREdvk1bEsn1p85TUDloyQ,428
+innergrid/innergrid.py,sha256=GpYIoM2GETG-1YfAIeh2fcMOv1gHO_DQWI0V3mpQvK4,9547
+innergrid/models.py,sha256=L_HgeSdc2z9i6gF3UmlAOGhuansXxx9tVBUpgzeBoH8,25174
+innergrid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+innergrid-0.1.0.dist-info/licenses/LICENSE,sha256=vl3VaKxSsSbvL4FwpSLQB8uLQACsbBGFgi4MCYk8mMo,1071
+innergrid-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+innergrid-0.1.0.dist-info/METADATA,sha256=cJ6Fy9EvzGNOp4UxUgBgdygx4pn3skT9aXg2OVvSV1U,3732
+innergrid-0.1.0.dist-info/RECORD,,

innergrid-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

innergrid-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robbin Janssen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.