mygrid-voltbridge 0.3.0__tar.gz

mygrid_voltbridge-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+coverage.xml
+htmlcov/
+*.egg-info/
+dist/
+build/

mygrid_voltbridge-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mygrid-voltbridge contributors
+
+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.

mygrid_voltbridge-0.3.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: mygrid-voltbridge
+Version: 0.3.0
+Summary: Typed async HTTP client for the MyGrid VoltBridge P1 meter
+Project-URL: Source, https://github.com/tjorim/python-mygrid-voltbridge
+Project-URL: Issues, https://github.com/tjorim/python-mygrid-voltbridge/issues
+Author: mygrid-voltbridge contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,dsmr,mygrid,p1,voltbridge
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp<4,>=3.10
+Description-Content-Type: text/markdown
+
+# mygrid-voltbridge
+
+A small typed async Python client for the local HTTP API of the **MyGrid VoltBridge** P1 meter adapter. Requires Python **3.12+** and `aiohttp`. Version 0.1.0 has not been published to PyPI.
+
+The API is not documented by the manufacturer. It was reverse-engineered from the device's own status page and verified against one device (firmware `voltbridge` build 15.6); see [docs/api.md](docs/api.md). It may change between firmware versions.
+
+## Query a meter
+
+The helper is read-only:
+
+```sh
+uv sync
+uv run mygrid-voltbridge 192.168.0.45
+uv run mygrid-voltbridge 192.168.0.45 --power
+```
+
+## Library
+
+```python
+import asyncio
+
+import aiohttp
+
+from mygrid_voltbridge import VoltBridgeClient
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        client = VoltBridgeClient("192.168.0.45", session)
+        power = await client.async_get_power()  # W, positive = import
+        print(power.net_power, power.tariff)
+        data = await client.async_get_p1_data()  # full snapshot
+        print(data.energy_import_t1, data.phases[1].voltage)
+
+
+asyncio.run(main())
+```
+
+| API | Contract |
+| --- | --- |
+| `async_get_power()` | `PowerReading` from `/api/power`; cheap, suitable for ~1 s polling |
+| `async_get_p1_data()` | `P1Data` from `/api/p1data`; poll every few seconds at most |
+| `async_listen(callback, host=...)` | Push updates: UDP broadcasts on 49491, about once a second; see below |
+| `parse_datagram(bytes)` | Decode one UDP datagram into a `P1Broadcast` |
+| `VoltBridgeInfo.from_properties(txt)` | Identify a device from its `_mygrid._tcp` mDNS TXT record (`device_id` is the MAC) |
+| `async_get_telegram()` | `Telegram` from `/api/telegram`: M-Bus devices (gas, **water**), breaker, limiter, monthly peak history, CRC check |
+| `async_get_telegram_text()` | The raw telegram string |
+| `async_reboot()` | `POST /reboot`; never retried |
+
+## Push updates
+
+The device also broadcasts its telegram over UDP roughly once per second, so you do not have to poll:
+
+```python
+from mygrid_voltbridge import async_listen
+
+transport = await async_listen(lambda b: print(b.data.net_power), host="192.168.0.45")
+# ...
+transport.close()
+```
+
+`host` filters by the device's IP; invalid datagrams are dropped. Use `port=49492` for the one-minute average stream. `uv run mygrid-voltbridge 192.168.0.45 --watch` prints the live stream as JSON lines. The broadcast carries no gas reading; use `async_get_p1_data()` for that. Broadcasts must reach the host, so a container or VLAN may need host networking or a broadcast relay. See [docs/api.md](docs/api.md) for the format.
+
+Power is in **W**, energy in **Wh**, voltage in **V**, current in **A**; the device reports kW/kWh and the library converts. Fields the meter does not report are `None`. Errors derive from `VoltBridgeError`: `VoltBridgeConnectionError`, `VoltBridgeResponseError` and `VoltBridgeNoDataError` (no P1 telegram received yet).
+
+Pass your own `aiohttp` session, or omit it: the client then creates one limited to a single connection (the device has very little memory) and closes it in `close()` or when leaving `async with VoltBridgeClient(host) as client`. Reads are retried twice with exponential backoff; the reboot is never retried. `VoltBridgeUnsupportedError` means the firmware lacks an endpoint (HTTP 404). There is no authentication or TLS on the device; keep it on the trusted LAN. Per-phase fields other than L1, and export power/energy on the UDP stream, are unverified.

mygrid_voltbridge-0.3.0/README.md

@@ -0,0 +1,66 @@
+# mygrid-voltbridge
+
+A small typed async Python client for the local HTTP API of the **MyGrid VoltBridge** P1 meter adapter. Requires Python **3.12+** and `aiohttp`. Version 0.1.0 has not been published to PyPI.
+
+The API is not documented by the manufacturer. It was reverse-engineered from the device's own status page and verified against one device (firmware `voltbridge` build 15.6); see [docs/api.md](docs/api.md). It may change between firmware versions.
+
+## Query a meter
+
+The helper is read-only:
+
+```sh
+uv sync
+uv run mygrid-voltbridge 192.168.0.45
+uv run mygrid-voltbridge 192.168.0.45 --power
+```
+
+## Library
+
+```python
+import asyncio
+
+import aiohttp
+
+from mygrid_voltbridge import VoltBridgeClient
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        client = VoltBridgeClient("192.168.0.45", session)
+        power = await client.async_get_power()  # W, positive = import
+        print(power.net_power, power.tariff)
+        data = await client.async_get_p1_data()  # full snapshot
+        print(data.energy_import_t1, data.phases[1].voltage)
+
+
+asyncio.run(main())
+```
+
+| API | Contract |
+| --- | --- |
+| `async_get_power()` | `PowerReading` from `/api/power`; cheap, suitable for ~1 s polling |
+| `async_get_p1_data()` | `P1Data` from `/api/p1data`; poll every few seconds at most |
+| `async_listen(callback, host=...)` | Push updates: UDP broadcasts on 49491, about once a second; see below |
+| `parse_datagram(bytes)` | Decode one UDP datagram into a `P1Broadcast` |
+| `VoltBridgeInfo.from_properties(txt)` | Identify a device from its `_mygrid._tcp` mDNS TXT record (`device_id` is the MAC) |
+| `async_get_telegram()` | `Telegram` from `/api/telegram`: M-Bus devices (gas, **water**), breaker, limiter, monthly peak history, CRC check |
+| `async_get_telegram_text()` | The raw telegram string |
+| `async_reboot()` | `POST /reboot`; never retried |
+
+## Push updates
+
+The device also broadcasts its telegram over UDP roughly once per second, so you do not have to poll:
+
+```python
+from mygrid_voltbridge import async_listen
+
+transport = await async_listen(lambda b: print(b.data.net_power), host="192.168.0.45")
+# ...
+transport.close()
+```
+
+`host` filters by the device's IP; invalid datagrams are dropped. Use `port=49492` for the one-minute average stream. `uv run mygrid-voltbridge 192.168.0.45 --watch` prints the live stream as JSON lines. The broadcast carries no gas reading; use `async_get_p1_data()` for that. Broadcasts must reach the host, so a container or VLAN may need host networking or a broadcast relay. See [docs/api.md](docs/api.md) for the format.
+
+Power is in **W**, energy in **Wh**, voltage in **V**, current in **A**; the device reports kW/kWh and the library converts. Fields the meter does not report are `None`. Errors derive from `VoltBridgeError`: `VoltBridgeConnectionError`, `VoltBridgeResponseError` and `VoltBridgeNoDataError` (no P1 telegram received yet).
+
+Pass your own `aiohttp` session, or omit it: the client then creates one limited to a single connection (the device has very little memory) and closes it in `close()` or when leaving `async with VoltBridgeClient(host) as client`. Reads are retried twice with exponential backoff; the reboot is never retried. `VoltBridgeUnsupportedError` means the firmware lacks an endpoint (HTTP 404). There is no authentication or TLS on the device; keep it on the trusted LAN. Per-phase fields other than L1, and export power/energy on the UDP stream, are unverified.

mygrid_voltbridge-0.3.0/pyproject.toml

@@ -0,0 +1,116 @@
+[build-system]
+requires = ["hatchling>=1.27.0", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mygrid-voltbridge"
+dynamic = ["version"]
+description = "Typed async HTTP client for the MyGrid VoltBridge P1 meter"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "mygrid-voltbridge contributors"}]
+keywords = ["mygrid", "voltbridge", "p1", "dsmr", "asyncio"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.10,<4"]
+
+[project.scripts]
+mygrid-voltbridge = "mygrid_voltbridge.cli:main"
+
+[project.urls]
+Source = "https://github.com/tjorim/python-mygrid-voltbridge"
+Issues = "https://github.com/tjorim/python-mygrid-voltbridge/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9,<10",
+    "pytest-asyncio>=1.4,<2",
+    "pytest-cov>=7,<8",
+    "ruff>=0.17,<0.18",
+    "ty>=0.0.90",
+    "build>=1.3,<2",
+    "twine>=7,<8",
+]
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { fallback_version = "0.0.0" }
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/README.md", "/LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mygrid_voltbridge"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra -m 'not live' --strict-markers --strict-config"
+markers = ["live: smoke tests against a real device (set VOLTBRIDGE_HOST); excluded from ordinary runs"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["mygrid_voltbridge"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 95
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",
+    "COM812",
+    "CPY001",
+    "D203",
+    "D213",
+    "E501",
+    "ISC001",
+    "PLR0913",
+    "PLR0917",
+    "TC001",
+    "TC002",
+    "TC003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "ARG001",
+    "ARG005",
+    "D",
+    "INP001",
+    "PLC0415",
+    "PLR2004",
+    "S101",
+    "SLF001",
+]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+combine-as-imports = true
+split-on-trailing-comma = false
+
+[tool.ty.rules]
+all = "error"
+
+[tool.ty.analysis]
+strict-equality-semantics = true
+strict-generic-narrowing = true

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/__init__.py

@@ -0,0 +1,50 @@
+"""Typed async client for the MyGrid VoltBridge P1 meter."""
+
+from importlib.metadata import PackageNotFoundError, version
+import logging
+
+from .client import VoltBridgeClient
+from .discovery import SERVICE_TYPE, VoltBridgeInfo
+from .exceptions import (
+    VoltBridgeConnectionError,
+    VoltBridgeError,
+    VoltBridgeNoDataError,
+    VoltBridgeResponseError,
+    VoltBridgeUnsupportedError,
+)
+from .models import P1Data, PhaseData, PowerReading
+from .telegram import GAS, HEAT, WATER, MBusChannel, MonthlyPeak, Telegram, parse_telegram
+from .udp import BroadcastStream, P1Broadcast, async_listen, parse_datagram
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+try:
+    __version__ = version("mygrid-voltbridge")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = [
+    "GAS",
+    "HEAT",
+    "SERVICE_TYPE",
+    "WATER",
+    "BroadcastStream",
+    "MBusChannel",
+    "MonthlyPeak",
+    "P1Broadcast",
+    "P1Data",
+    "PhaseData",
+    "PowerReading",
+    "Telegram",
+    "VoltBridgeClient",
+    "VoltBridgeConnectionError",
+    "VoltBridgeError",
+    "VoltBridgeInfo",
+    "VoltBridgeNoDataError",
+    "VoltBridgeResponseError",
+    "VoltBridgeUnsupportedError",
+    "__version__",
+    "async_listen",
+    "parse_datagram",
+    "parse_telegram",
+]

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/cli.py

@@ -0,0 +1,67 @@
+"""Read-only command line helper: ``mygrid-voltbridge <host>``."""
+
+import argparse
+import asyncio
+import contextlib
+import dataclasses
+from datetime import datetime
+import json
+from typing import Any
+
+import aiohttp
+
+from .client import HTTP_PORT, VoltBridgeClient
+from .exceptions import VoltBridgeError
+from .udp import P1_PORT, P1Broadcast, async_listen
+
+
+def _default(value: Any) -> Any:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    raise TypeError(type(value))
+
+
+async def _run(host: str, port: int, *, power_only: bool) -> str:
+    async with aiohttp.ClientSession() as session:
+        client = VoltBridgeClient(host, session, port=port)
+        reading = await (client.async_get_power() if power_only else client.async_get_p1_data())
+    return json.dumps(dataclasses.asdict(reading), default=_default, indent=2)
+
+
+async def _watch(host: str, port: int) -> None:
+    queue: asyncio.Queue[P1Broadcast] = asyncio.Queue()
+    transport = await async_listen(queue.put_nowait, host=host, port=port)
+    try:
+        while True:
+            broadcast = await queue.get()
+            print(  # noqa: T201 - the CLI exists to print
+                json.dumps(dataclasses.asdict(broadcast), default=_default), flush=True
+            )
+    finally:
+        transport.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line helper and return the exit code."""
+    parser = argparse.ArgumentParser(description="Read a MyGrid VoltBridge (read-only).")
+    parser.add_argument("host")
+    parser.add_argument("--port", type=int, default=HTTP_PORT)
+    parser.add_argument("--watch", action="store_true", help="stream UDP broadcasts as JSON lines")
+    parser.add_argument("--power", action="store_true", help="only instantaneous power")
+    args = parser.parse_args(argv)
+    try:
+        if args.watch:
+            with contextlib.suppress(KeyboardInterrupt):
+                asyncio.run(_watch(args.host, args.port if args.port != HTTP_PORT else P1_PORT))
+            return 0
+        print(asyncio.run(_run(args.host, args.port, power_only=args.power)))  # noqa: T201
+    except BrokenPipeError:  # e.g. piped into head
+        return 0
+    except VoltBridgeError as err:
+        print(f"error: {err}")  # noqa: T201
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/client.py

@@ -0,0 +1,167 @@
+"""Async client for the VoltBridge's local, unauthenticated HTTP API."""
+
+import asyncio
+from http import HTTPStatus
+import json
+import logging
+import time
+from types import TracebackType
+from typing import Any, Self
+
+import aiohttp
+
+from .exceptions import VoltBridgeConnectionError, VoltBridgeResponseError, VoltBridgeUnsupportedError
+from .models import P1Data, PowerReading
+from .telegram import Telegram, parse_telegram
+
+_LOGGER = logging.getLogger(__name__)
+HTTP_PORT = 80
+DEFAULT_TIMEOUT = 5.0
+DEFAULT_RETRIES = 2
+# The device is a microcontroller with very little free memory: space requests out.
+DEFAULT_MIN_INTERVAL = 0.1
+
+
+class _ServerError(aiohttp.ClientError):
+    """HTTP 5xx, retried like a network failure."""
+
+
+class VoltBridgeClient:
+    """Talks to one VoltBridge.
+
+    Pass your own ``aiohttp`` session (Home Assistant's, for example) or let
+    the client create one; it then allows one connection at a time, because
+    the device is a small microcontroller with very little free memory, and
+    closes it in ``close()`` or when leaving ``async with``. Requests are
+    serialised and spaced at least ``min_request_interval`` seconds apart.
+    Reads are retried with exponential backoff after a network error, timeout
+    or HTTP 5xx; writes never are. Poll ``/api/p1data`` every few seconds at
+    most and prefer ``async_get_power`` or UDP for fast updates.
+
+    Raises ``ValueError`` for a negative ``retries`` or ``min_request_interval``
+    and for a ``timeout`` that is not positive.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        port: int = HTTP_PORT,
+        timeout: float = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        min_request_interval: float = DEFAULT_MIN_INTERVAL,
+    ) -> None:
+        """Create a client; see the class docstring for the arguments."""
+        if retries < 0:
+            msg = "retries must be 0 or greater"
+            raise ValueError(msg)
+        if timeout <= 0:
+            msg = "timeout must be greater than 0"
+            raise ValueError(msg)
+        if min_request_interval < 0:
+            msg = "min_request_interval must be 0 or greater"
+            raise ValueError(msg)
+        self._base = f"http://{host}:{port}"
+        self._session = session
+        self._owns_session = session is None
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._retries = retries
+        self._min_interval = min_request_interval
+        self._lock = asyncio.Lock()
+        self._last_request = 0.0
+
+    async def async_get_power(self) -> PowerReading:
+        """Read instantaneous power (``/api/power``)."""
+        return PowerReading.from_payload(await self._json("/api/power"))
+
+    async def async_get_p1_data(self) -> P1Data:
+        """Read the full P1 snapshot (``/api/p1data``)."""
+        return P1Data.from_payload(await self._json("/api/p1data"))
+
+    async def async_get_telegram_text(self) -> str:
+        """Read the raw DSMR telegram (``/api/telegram``), unmodified."""
+        return (await self._request("GET", "/api/telegram")).decode("latin-1")
+
+    async def async_get_telegram(self) -> Telegram:
+        """Read and decode the telegram: M-Bus devices, breaker, peak history."""
+        return parse_telegram(await self.async_get_telegram_text())
+
+    async def async_reboot(self) -> None:
+        """Reboot the device (``POST /reboot``). Not retried."""
+        await self._request("POST", "/reboot", retries=0)
+
+    async def close(self) -> None:
+        """Close the session if this client created it."""
+        if self._session is not None and self._owns_session:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context; the client is ready to use."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Leave the async context and close an owned session."""
+        await self.close()
+
+    async def _json(self, path: str) -> Any:
+        body = await self._request("GET", path)
+        try:
+            return json.loads(body)
+        except ValueError as err:
+            msg = f"{path} did not return JSON"
+            raise VoltBridgeResponseError(msg) from err
+
+    async def _request(self, method: str, path: str, *, retries: int | None = None) -> bytes:
+        attempts = (self._retries if retries is None else retries) + 1
+        for attempt in range(attempts):
+            try:
+                async with self._lock:
+                    await self._space_out()
+                    return await self._request_once(method, path)
+            except VoltBridgeConnectionError:
+                if attempt == attempts - 1:
+                    raise
+                delay = 0.25 * 2**attempt
+                _LOGGER.debug("%s %s failed, retrying in %.2fs", method, path, delay)
+                await asyncio.sleep(delay)
+        msg = "unreachable"
+        raise AssertionError(msg)  # pragma: no cover
+
+    async def _space_out(self) -> None:
+        """Wait until ``min_request_interval`` has passed since the last request."""
+        wait = self._last_request + self._min_interval - time.monotonic()
+        if wait > 0:
+            await asyncio.sleep(wait)
+        self._last_request = time.monotonic()
+
+    async def _request_once(self, method: str, path: str) -> bytes:
+        if self._session is None:
+            self._session = aiohttp.ClientSession(connector=aiohttp.TCPConnector(limit_per_host=1))
+        try:
+            async with self._session.request(method, self._base + path, timeout=self._timeout) as response:
+                if response.status == HTTPStatus.NOT_FOUND:
+                    msg = f"{path} is not available on this firmware"
+                    raise VoltBridgeUnsupportedError(msg)
+                if response.status >= HTTPStatus.INTERNAL_SERVER_ERROR:
+                    msg = f"HTTP {response.status}"
+                    raise _ServerError(msg)
+                if response.status != HTTPStatus.OK:
+                    msg = f"{path} returned HTTP {response.status}"
+                    raise VoltBridgeResponseError(
+                        msg,
+                        status=response.status,
+                    )
+                return await response.read()
+        except TimeoutError as err:
+            msg = f"{self._base} timed out"
+            raise VoltBridgeConnectionError(msg) from err
+        except aiohttp.ClientError as err:
+            msg = f"cannot reach {self._base}{path}: {err}"
+            raise VoltBridgeConnectionError(msg) from err

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/discovery.py

@@ -0,0 +1,58 @@
+"""Identify a VoltBridge from its mDNS record.
+
+The device advertises ``_mygrid._tcp`` with TXT properties such as
+``model=Voltbridge P1 Meter`` and ``device_id=907069D02D80`` (its MAC address).
+Resolving the service is left to the caller (for example Home Assistant's
+zeroconf integration), so this module needs no extra dependency.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+import re
+
+from .exceptions import VoltBridgeResponseError
+
+SERVICE_TYPE = "_mygrid._tcp.local."
+_DEVICE_ID = re.compile(r"[0-9A-Fa-f]{12}")
+
+
+@dataclass(frozen=True)
+class VoltBridgeInfo:
+    """Identity advertised over mDNS."""
+
+    device_id: str
+    model: str | None
+    firmware_version: str | None
+    hardware_version: str | None
+    api_path: str | None
+
+    @property
+    def mac_address(self) -> str:
+        """The device id formatted as a lower-case MAC address."""
+        return ":".join(self.device_id[i : i + 2] for i in range(0, 12, 2)).lower()
+
+    @classmethod
+    def from_properties(cls, properties: Mapping[str | bytes, str | bytes | None]) -> "VoltBridgeInfo":
+        """Build from mDNS TXT properties; raises if this is not a VoltBridge."""
+        text = {_str(key): _str(value) for key, value in properties.items()}
+        device_id = text.get("device_id") or ""
+        model = text.get("model")
+        if text.get("manufacturer") != "MyGrid" or not _DEVICE_ID.fullmatch(device_id):
+            msg = "not a MyGrid device advertisement"
+            raise VoltBridgeResponseError(msg)
+        if model is None or "voltbridge" not in model.lower():
+            msg = f"not a VoltBridge: {model!r}"
+            raise VoltBridgeResponseError(msg)
+        return cls(
+            device_id=device_id.upper(),
+            model=model,
+            firmware_version=text.get("firmware_version"),
+            hardware_version=text.get("hardware_version"),
+            api_path=text.get("api_path"),
+        )
+
+
+def _str(value: str | bytes | None) -> str | None:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return value

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/exceptions.py

@@ -0,0 +1,32 @@
+"""Errors raised by the VoltBridge client."""
+
+
+class VoltBridgeError(Exception):
+    """Base class for all VoltBridge errors."""
+
+
+class VoltBridgeConnectionError(VoltBridgeError):
+    """The device could not be reached, timed out or kept answering HTTP 5xx.
+
+    Raised only after every retry; the request may succeed later.
+    """
+
+
+class VoltBridgeResponseError(VoltBridgeError):
+    """The device answered with an unusable status or body.
+
+    ``status`` is the HTTP status when the failure is tied to one.
+    """
+
+    def __init__(self, message: str = "Invalid VoltBridge response", *, status: int | None = None) -> None:
+        """Create the error with an optional HTTP ``status``."""
+        super().__init__(message)
+        self.status = status
+
+
+class VoltBridgeNoDataError(VoltBridgeError):
+    """The device is up but has not received a P1 telegram yet."""
+
+
+class VoltBridgeUnsupportedError(VoltBridgeError):
+    """The firmware does not provide this endpoint (HTTP 404)."""

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/models.py

@@ -0,0 +1,157 @@
+"""Immutable readings in watts, watt-hours, volts and amperes.
+
+The device reports power in kW and energy in kWh; both are converted to
+integer W and Wh so values compare and sum exactly.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, cast
+
+from .exceptions import VoltBridgeNoDataError, VoltBridgeResponseError
+
+
+def _number(payload: Mapping[str, Any], key: str) -> float | None:
+    value = payload.get(key)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        msg = f"{key} is not a number: {value!r}"
+        raise VoltBridgeResponseError(msg)
+    return float(value)
+
+
+def _milli(payload: Mapping[str, Any], key: str) -> int | None:
+    """Convert a kW/kWh field to W/Wh."""
+    value = _number(payload, key)
+    return None if value is None else round(value * 1000)
+
+
+def _require_data(payload: object) -> Mapping[str, Any]:
+    if not isinstance(payload, dict):
+        msg = "response is not a JSON object"
+        raise VoltBridgeResponseError(msg)
+    if not payload.get("hasData"):
+        msg = "no P1 telegram received yet"
+        raise VoltBridgeNoDataError(msg)
+    return cast("Mapping[str, Any]", payload)
+
+
+@dataclass(frozen=True)
+class PowerReading:
+    """Instantaneous power from ``/api/power``; positive net power is import."""
+
+    net_power: int
+    import_power: int
+    export_power: int
+    tariff: int | None
+
+    @classmethod
+    def from_payload(cls, payload: object) -> "PowerReading":
+        """Build from a ``/api/power`` payload."""
+        data = _require_data(payload)
+        net = _milli(data, "netPowerW")
+        imported = _milli(data, "importPowerW")
+        exported = _milli(data, "exportPowerW")
+        if net is None or imported is None or exported is None:
+            msg = "power response is missing fields"
+            raise VoltBridgeResponseError(msg)
+        tariff = _number(data, "tariff")
+        return cls(
+            net_power=net,
+            import_power=imported,
+            export_power=exported,
+            tariff=None if tariff is None else int(tariff),
+        )
+
+
+@dataclass(frozen=True)
+class PhaseData:
+    """Per-phase values; any field the meter does not report is ``None``."""
+
+    import_power: int | None
+    export_power: int | None
+    voltage: float | None
+    current: float | None
+
+
+@dataclass(frozen=True)
+class P1Data:
+    """A full P1 snapshot from ``/api/p1data``; unreported fields are ``None``."""
+
+    meter_serial: str | None
+    meter_version: str | None
+    import_power: int | None
+    export_power: int | None
+    net_power: int | None
+    avg_import_1min: int | None
+    avg_export_1min: int | None
+    avg_demand: int | None
+    peak_demand: int | None
+    peak_demand_at: datetime | None
+    tariff: int | None
+    energy_import_t1: int | None
+    energy_import_t2: int | None
+    energy_export_t1: int | None
+    energy_export_t2: int | None
+    gas: float | None
+    phases: Mapping[int, PhaseData] = field(default_factory=dict)
+
+    @classmethod
+    def from_payload(cls, payload: object) -> "P1Data":
+        """Build from a ``/api/p1data`` payload."""
+        data = _require_data(payload)
+        tariff = _number(data, "tariff")
+        return cls(
+            meter_serial=_text(data, "meterSerial"),
+            meter_version=_text(data, "meterVersion"),
+            import_power=_milli(data, "importPower"),
+            export_power=_milli(data, "exportPower"),
+            net_power=_milli(data, "activePowerNet"),
+            avg_import_1min=_milli(data, "avgImport1min"),
+            avg_export_1min=_milli(data, "avgExport1min"),
+            avg_demand=_milli(data, "avgDemand"),
+            peak_demand=_milli(data, "peakDemand"),
+            peak_demand_at=_timestamp(data, "peakDemandAt"),
+            tariff=None if tariff is None else int(tariff),
+            energy_import_t1=_milli(data, "energyImportT1"),
+            energy_import_t2=_milli(data, "energyImportT2"),
+            energy_export_t1=_milli(data, "energyExportT1"),
+            energy_export_t2=_milli(data, "energyExportT2"),
+            gas=_number(data, "gasM3"),
+            phases=_phases(data),
+        )
+
+
+def _text(payload: Mapping[str, Any], key: str) -> str | None:
+    value = payload.get(key)
+    return None if value is None else str(value)
+
+
+def _timestamp(payload: Mapping[str, Any], key: str) -> datetime | None:
+    value = payload.get(key)
+    if value is None:
+        return None
+    try:
+        return datetime.fromisoformat(str(value))
+    except ValueError as err:
+        msg = f"{key} is not a timestamp: {value!r}"
+        raise VoltBridgeResponseError(msg) from err
+
+
+def _phases(payload: Mapping[str, Any]) -> dict[int, PhaseData]:
+    """Collect ``<field>L<n>`` keys. Only L1 is verified on real hardware."""
+    phases: dict[int, PhaseData] = {}
+    for number in (1, 2, 3):
+        suffix = f"L{number}"
+        keys = ("importPower", "exportPower", "voltage", "current")
+        if not any(f"{key}{suffix}" in payload for key in keys):
+            continue
+        phases[number] = PhaseData(
+            import_power=_milli(payload, f"importPower{suffix}"),
+            export_power=_milli(payload, f"exportPower{suffix}"),
+            voltage=_number(payload, f"voltage{suffix}"),
+            current=_number(payload, f"current{suffix}"),
+        )
+    return phases

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/telegram.py

@@ -0,0 +1,214 @@
+"""Parser for the raw DSMR/Fluvius P1 telegram served at ``/api/telegram``.
+
+The JSON API only exposes the electricity values and gas. The telegram also
+carries every M-Bus device (water, heat), the breaker and limiter state and
+the monthly peak history. Unknown OBIS codes stay available in ``objects``.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta, timezone
+import re
+
+from .exceptions import VoltBridgeResponseError
+
+_OBIS = re.compile(r"^(\d+-\d+:\d+\.\d+\.\d+)((?:\([^)]*\))*)$")
+_GROUP = re.compile(r"\(([^)]*)\)")
+_TIMESTAMP = re.compile(r"^(\d{12})([SW])$")
+_VALUE = re.compile(r"^(-?\d+(?:\.\d+)?)\*(\S+)$")
+_MBUS = re.compile(r"^0-(\d+):24\.(\d+)\.\d+$")
+
+# DSMR M-Bus device type codes.
+GAS = 3
+HEAT = 4
+WATER = 7
+
+
+@dataclass(frozen=True)
+class MBusChannel:
+    """One device on the meter's M-Bus (``0-n:24.*``)."""
+
+    channel: int
+    device_type: int | None
+    equipment_id: str | None
+    reading_at: datetime | None
+    reading: float | None
+    unit: str | None
+    valve_state: int | None
+
+    @property
+    def kind(self) -> str:
+        """Return ``gas``, ``water``, ``heat`` or ``unknown``."""
+        return {GAS: "gas", HEAT: "heat", WATER: "water"}.get(self.device_type or 0, "unknown")
+
+
+@dataclass(frozen=True)
+class MonthlyPeak:
+    """One entry of the monthly peak-demand history (OBIS ``0-0:98.1.0``)."""
+
+    month_end: datetime
+    peak_at: datetime
+    power: int
+
+
+@dataclass(frozen=True)
+class Telegram:
+    """A decoded telegram; power in W, current in A, volumes as reported."""
+
+    header: str
+    crc_valid: bool
+    timestamp: datetime | None
+    breaker_state: int | None
+    limiter_threshold: int | None
+    fuse_threshold: int | None
+    avg_demand: int | None
+    peak_demand: int | None
+    peak_demand_at: datetime | None
+    monthly_peaks: tuple[MonthlyPeak, ...]
+    channels: Mapping[int, MBusChannel]
+    objects: Mapping[str, tuple[tuple[str, ...], ...]] = field(default_factory=dict)
+
+    def channel_of(self, kind: str) -> MBusChannel | None:
+        """Return the first M-Bus device of a kind (``gas``, ``water``, ``heat``)."""
+        return next((c for _, c in sorted(self.channels.items()) if c.kind == kind), None)
+
+
+def _crc16(data: bytes) -> int:
+    crc = 0
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0xA001 if crc & 1 else crc >> 1
+    return crc
+
+
+def _timestamp(text: str) -> datetime | None:
+    """``YYMMDDhhmmssS|W``: local time with a summer/winter marker (CET/CEST)."""
+    match = _TIMESTAMP.match(text)
+    if not match:
+        return None
+    digits, season = match.groups()
+    zone = timezone(timedelta(hours=2 if season == "S" else 1))
+    try:
+        return datetime(
+            2000 + int(digits[0:2]),
+            int(digits[2:4]),
+            int(digits[4:6]),
+            int(digits[6:8]),
+            int(digits[8:10]),
+            int(digits[10:12]),
+            tzinfo=zone,
+        ).astimezone(UTC)
+    except ValueError:
+        return None
+
+
+def _quantity(text: str, unit: str) -> float | None:
+    """Return a value in the given unit, or ``None`` if absent or malformed."""
+    match = _VALUE.match(text)
+    return float(match.group(1)) if match and match.group(2) == unit else None
+
+
+def _kilo(text: str, unit: str) -> int | None:
+    value = _quantity(text, unit)
+    return None if value is None else round(value * 1000)
+
+
+def _first(objects: Mapping[str, tuple[tuple[str, ...], ...]], code: str) -> tuple[str, ...]:
+    return objects.get(code, ((),))[0]
+
+
+def _int(text: str | None) -> int | None:
+    return int(text) if text is not None and text.lstrip("-").isdigit() else None
+
+
+def _hex_text(text: str) -> str:
+    """Equipment ids are hex-encoded ASCII; fall back to the raw hex."""
+    try:
+        decoded = bytes.fromhex(text).decode("ascii")
+    except ValueError:
+        return text
+    return decoded if decoded.isprintable() else text
+
+
+def _peaks(groups: tuple[str, ...]) -> tuple[MonthlyPeak, ...]:
+    triples = groups[3:]
+    peaks = []
+    for index in range(0, len(triples) - 2, 3):
+        month_end = _timestamp(triples[index])
+        peak_at = _timestamp(triples[index + 1])
+        power = _kilo(triples[index + 2], "kW")
+        if month_end and peak_at and power is not None:
+            peaks.append(MonthlyPeak(month_end, peak_at, power))
+    return tuple(peaks)
+
+
+def _channels(
+    objects: Mapping[str, tuple[tuple[str, ...], ...]],
+) -> dict[int, MBusChannel]:
+    numbers = {int(m.group(1)) for code in objects if (m := _MBUS.match(code))}
+    channels = {}
+    for number in sorted(numbers):
+        reading_groups: tuple[str, ...] = ()
+        for code, values in objects.items():
+            match = _MBUS.match(code)
+            if match and int(match.group(1)) == number and match.group(2) == "2":
+                reading_groups = values[0]
+        reading_at = _timestamp(reading_groups[0]) if reading_groups else None
+        quantity = reading_groups[1] if len(reading_groups) > 1 else ""
+        match = _VALUE.match(quantity)
+        type_group = _first(objects, f"0-{number}:24.1.0")
+        id_group = _first(objects, f"0-{number}:96.1.1")
+        valve_group = _first(objects, f"0-{number}:24.4.0")
+        channels[number] = MBusChannel(
+            channel=number,
+            device_type=_int(type_group[0]) if type_group else None,
+            equipment_id=_hex_text(id_group[0]) if id_group and id_group[0] else None,
+            reading_at=reading_at,
+            reading=float(match.group(1)) if match else None,
+            unit=match.group(2) if match else None,
+            valve_state=_int(valve_group[0]) if valve_group else None,
+        )
+    return channels
+
+
+def parse_telegram(text: str) -> Telegram:
+    """Decode a telegram; raises ``VoltBridgeResponseError`` if it is not one."""
+    start, bang = text.find("/"), text.find("!")
+    if start < 0 or bang < start:
+        msg = "not a P1 telegram"
+        raise VoltBridgeResponseError(msg)
+    body = text[start : bang + 1]
+    expected = text[bang + 1 : bang + 5]
+    crc_valid = f"{_crc16(body.encode('latin-1')):04X}" == expected.upper()
+
+    lines = body.splitlines()
+    header = lines[0].strip()
+    objects: dict[str, tuple[tuple[str, ...], ...]] = {}
+    for line in lines[1:]:
+        match = _OBIS.match(line.strip())
+        if match:
+            code, rest = match.groups()
+            groups = tuple(_GROUP.findall(rest))
+            objects[code] = (*objects.get(code, ()), groups)
+
+    timestamp = _first(objects, "0-0:1.0.0")
+    peak = _first(objects, "1-0:1.6.0")
+    limiter = _first(objects, "0-0:17.0.0")
+    fuse = _first(objects, "1-0:31.4.0")
+    demand = _first(objects, "1-0:1.4.0")
+    history = _first(objects, "0-0:98.1.0")
+    return Telegram(
+        header=header,
+        crc_valid=crc_valid,
+        timestamp=_timestamp(timestamp[0]) if timestamp else None,
+        breaker_state=_int(_first(objects, "0-0:96.3.10")[0]) if "0-0:96.3.10" in objects else None,
+        limiter_threshold=_kilo(limiter[0], "kW") if limiter else None,
+        fuse_threshold=round(q) if fuse and (q := _quantity(fuse[0], "A")) is not None else None,
+        avg_demand=_kilo(demand[0], "kW") if demand else None,
+        peak_demand=_kilo(peak[1], "kW") if len(peak) > 1 else None,
+        peak_demand_at=_timestamp(peak[0]) if peak else None,
+        monthly_peaks=_peaks(history),
+        channels=_channels(objects),
+        objects=objects,
+    )

mygrid_voltbridge-0.3.0/src/mygrid_voltbridge/udp.py

@@ -0,0 +1,268 @@
+"""Decoder and listener for the VoltBridge's UDP broadcasts (push updates).
+
+Every datagram is ``P1`` + version + stream + flags + payload length + CRC-16
+(ARC, big endian) + a protobuf payload. Stream 0 (port 49491) carries the live
+telegram about once a second; stream 1 (port 49492) carries one-minute averages
+less often. The schema was reverse-engineered, so it is decoded by hand against
+a fixed field map instead of with generated protobuf code.
+"""
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import IntEnum
+import logging
+import struct
+from typing import Any, override
+
+from .exceptions import VoltBridgeResponseError
+from .models import P1Data, PhaseData
+
+_LOGGER = logging.getLogger(__name__)
+
+P1_PORT = 49491
+AGGREGATED_PORT = 49492
+_MAGIC = b"P1"
+_HEADER = 8
+_MAX_VARINT_SHIFT = 63
+_LENGTH_DELIMITED = 2  # protobuf wire type
+_PEAK_FIELD = 2  # field 2 of the demand message
+
+_Fields = dict[int, list[Any]]
+
+
+class BroadcastStream(IntEnum):
+    """The stream a datagram belongs to (header byte 3)."""
+
+    P1 = 0
+    AGGREGATED = 1
+
+
+@dataclass(frozen=True)
+class P1Broadcast:
+    """One decoded datagram.
+
+    ``data`` uses the same units as the HTTP client. On the aggregated stream
+    the import/export fields hold one-minute averages in ``avg_*`` and the
+    instantaneous fields are ``None``.
+    """
+
+    stream: BroadcastStream
+    timestamp: datetime
+    rssi: int | None
+    country: str | None
+    software_version: str | None
+    data: P1Data
+
+
+def _crc16_arc(data: bytes) -> int:
+    crc = 0
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0xA001 if crc & 1 else crc >> 1
+    return crc
+
+
+def _varint(buf: bytes, pos: int) -> tuple[int, int]:
+    result = shift = 0
+    while True:
+        if pos >= len(buf) or shift > _MAX_VARINT_SHIFT:
+            msg = "truncated varint"
+            raise VoltBridgeResponseError(msg)
+        byte = buf[pos]
+        pos += 1
+        result |= (byte & 0x7F) << shift
+        shift += 7
+        if not byte & 0x80:
+            return result, pos
+
+
+def _read(buf: bytes) -> _Fields:
+    """Split a protobuf message into ``{field: [value, ...]}`` (wire types 0, 1, 2, 5)."""
+    fields: _Fields = {}
+    pos = 0
+    value: Any
+    while pos < len(buf):
+        key, pos = _varint(buf, pos)
+        number, wire = key >> 3, key & 7
+        if wire == 0:
+            value, pos = _varint(buf, pos)
+        elif wire in (1, 5):
+            size = 8 if wire == 1 else 4
+            if pos + size > len(buf):
+                msg = "truncated fixed-width field"
+                raise VoltBridgeResponseError(msg)
+            fmt = "<d" if wire == 1 else "<f"
+            (value,) = struct.unpack_from(fmt, buf, pos)
+            pos += size
+        elif wire == _LENGTH_DELIMITED:
+            size, pos = _varint(buf, pos)
+            if pos + size > len(buf):
+                msg = "truncated length-delimited field"
+                raise VoltBridgeResponseError(msg)
+            value = buf[pos : pos + size]
+            pos += size
+        else:
+            msg = f"unsupported wire type {wire}"
+            raise VoltBridgeResponseError(msg)
+        fields.setdefault(number, []).append(value)
+    return fields
+
+
+def _msg(fields: _Fields, number: int) -> _Fields | None:
+    values = fields.get(number)
+    if values is None or not isinstance(values[-1], bytes):
+        return None
+    return _read(values[-1])
+
+
+def _num(fields: _Fields | None, number: int) -> float:
+    """Proto3 omits zero, so a missing scalar inside a present message is 0."""
+    if fields is None:
+        return 0.0
+    value = fields.get(number, [0.0])[-1]
+    if isinstance(value, bytes):
+        msg = f"field {number} is not a number"
+        raise VoltBridgeResponseError(msg)
+    return float(value)
+
+
+def _text(fields: _Fields | None, number: int) -> str | None:
+    values = ({} if fields is None else fields).get(number)
+    if values is None or not isinstance(values[-1], bytes):
+        return None
+    return values[-1].decode("utf-8", errors="replace") or None
+
+
+def _milli(value: float) -> int:
+    return round(value * 1000)
+
+
+def _phase(fields: _Fields | None) -> PhaseData | None:
+    if fields is None or len(fields) == 0:
+        return None
+    return PhaseData(
+        import_power=_milli(_num(fields, 1)),
+        export_power=_milli(_num(fields, 2)),
+        voltage=round(_num(fields, 3), 2),
+        current=round(_num(fields, 4), 2),
+    )
+
+
+def parse_datagram(datagram: bytes) -> P1Broadcast:
+    """Decode one UDP datagram, raising ``VoltBridgeResponseError`` if invalid."""
+    if len(datagram) < _HEADER or datagram[:2] != _MAGIC or datagram[2] != 1:
+        msg = "not a VoltBridge datagram"
+        raise VoltBridgeResponseError(msg)
+    try:
+        stream = BroadcastStream(datagram[3])
+    except ValueError as err:
+        msg = f"unknown stream {datagram[3]}"
+        raise VoltBridgeResponseError(msg) from err
+    payload = datagram[_HEADER:]
+    if datagram[5] != len(payload):
+        msg = "payload length mismatch"
+        raise VoltBridgeResponseError(msg)
+    if int.from_bytes(datagram[6:8], "big") != _crc16_arc(payload):
+        msg = "checksum mismatch"
+        raise VoltBridgeResponseError(msg)
+
+    envelope = _read(payload)
+    seconds = _num(_msg(envelope, 1), 1)
+    if not seconds:
+        msg = "missing timestamp"
+        raise VoltBridgeResponseError(msg)
+    rssi_raw = _msg(envelope, 5)
+    rssi = None
+    if rssi_raw is not None:
+        raw = rssi_raw.get(1, [0])[-1]
+        if not isinstance(raw, int):
+            msg = "rssi is not an integer"
+            raise VoltBridgeResponseError(msg)
+        rssi = raw - (1 << 64) if raw >= 1 << 63 else raw
+    meter = _msg(envelope, 6)
+    body = _msg(envelope, 10 if stream is BroadcastStream.P1 else 11) or {}
+
+    totals = _msg(body, 10)
+    demand = _msg(body, 11)
+    peak_at = _msg(demand, 3) if demand is not None else None
+    power = _msg(body, 1)
+    imported, exported = _milli(_num(power, 1)), _milli(_num(power, 2))
+    live = stream is BroadcastStream.P1
+    phases = {n: p for n in (1, 2, 3) if live and (p := _phase(_msg(body, n + 1)))}
+
+    data = P1Data(
+        meter_serial=_text(meter, 1),
+        meter_version=_text(meter, 2),
+        import_power=imported if live else None,
+        export_power=exported if live else None,
+        net_power=imported - exported if live else None,
+        avg_import_1min=None if live else imported,
+        avg_export_1min=None if live else exported,
+        avg_demand=_milli(_num(demand, 1)) if demand is not None else None,
+        peak_demand=_milli(_num(demand, 2)) if demand is not None and _PEAK_FIELD in demand else None,
+        peak_demand_at=(datetime.fromtimestamp(int(_num(peak_at, 1)), UTC) if peak_at is not None else None),
+        tariff=int(_num(totals, 5)) if totals is not None else None,
+        energy_import_t1=_milli(_num(totals, 1)) if totals is not None else None,
+        energy_import_t2=_milli(_num(totals, 2)) if totals is not None else None,
+        energy_export_t1=_milli(_num(totals, 3)) if totals is not None else None,
+        energy_export_t2=_milli(_num(totals, 4)) if totals is not None else None,
+        gas=None,
+        phases=phases,
+    )
+    return P1Broadcast(
+        stream=stream,
+        timestamp=datetime.fromtimestamp(int(seconds), UTC),
+        rssi=rssi,
+        country=_text(envelope, 4),
+        software_version=_text(envelope, 2),
+        data=data,
+    )
+
+
+class _Protocol(asyncio.DatagramProtocol):
+    def __init__(self, callback: Callable[[P1Broadcast], None], host: str | None) -> None:
+        self._callback = callback
+        self._host = host
+
+    @override
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        if self._host is not None and addr[0] != self._host:
+            return
+        try:
+            broadcast = parse_datagram(data)
+        except VoltBridgeResponseError as err:
+            _LOGGER.debug("Dropping datagram from %s: %s", addr[0], err)
+            return
+        self._callback(broadcast)
+
+
+async def async_listen(
+    callback: Callable[[P1Broadcast], None],
+    *,
+    host: str | None = None,
+    port: int = P1_PORT,
+    bind: str = "0.0.0.0",  # noqa: S104 - broadcasts arrive on any interface
+) -> asyncio.DatagramTransport:
+    """Listen for broadcasts; ``host`` filters by the device's IP.
+
+    Call ``close()`` on the returned transport to stop. Invalid datagrams are
+    dropped. ``callback`` runs in the event loop and must not block.
+    """
+    loop = asyncio.get_running_loop()
+    transport, _ = await loop.create_datagram_endpoint(
+        lambda: _Protocol(callback, host), local_addr=(bind, port), reuse_port=True
+    )
+    return transport
+
+
+__all__ = [
+    "AGGREGATED_PORT",
+    "P1_PORT",
+    "BroadcastStream",
+    "P1Broadcast",
+    "async_listen",
+    "parse_datagram",
+]