python-duco-connectivity 0.1.0__py3-none-any.whl

duco_connectivity/__init__.py

@@ -0,0 +1,49 @@
+"""Public package exports for python-duco-connectivity."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import DucoClient
+from .exceptions import DucoConnectionError, DucoError, DucoWriteLimitError
+from .models import (
+    ApiEndpoint,
+    ApiInfo,
+    BoardInfo,
+    DiagComponent,
+    DiagStatus,
+    LanInfo,
+    NetworkType,
+    Node,
+    NodeGeneralInfo,
+    NodeSensorInfo,
+    NodeType,
+    NodeVentilationInfo,
+    VentilationMode,
+    VentilationState,
+)
+
+try:
+    __version__ = version("python-duco-connectivity")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ApiEndpoint",
+    "ApiInfo",
+    "BoardInfo",
+    "DucoClient",
+    "DucoConnectionError",
+    "DucoError",
+    "DucoWriteLimitError",
+    "DiagComponent",
+    "DiagStatus",
+    "LanInfo",
+    "NetworkType",
+    "Node",
+    "NodeGeneralInfo",
+    "NodeSensorInfo",
+    "NodeType",
+    "NodeVentilationInfo",
+    "VentilationMode",
+    "VentilationState",
+    "__version__",
+]

duco_connectivity/client.py

@@ -0,0 +1,251 @@
+"""Async client for the local Duco HTTP API."""
+
+import json
+from typing import Any
+
+import aiohttp
+
+from .exceptions import DucoConnectionError, DucoError, DucoWriteLimitError
+from .models import (
+    ApiEndpoint,
+    ApiInfo,
+    BoardInfo,
+    DiagComponent,
+    DiagStatus,
+    LanInfo,
+    NetworkType,
+    Node,
+    NodeGeneralInfo,
+    NodeSensorInfo,
+    NodeType,
+    NodeVentilationInfo,
+    VentilationMode,
+    VentilationState,
+)
+
+
+class DucoClient:
+    """Client for a Duco box that exposes the local HTTP API."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        host: str,
+        *,
+        port: int | None = None,
+        request_timeout: float = 10.0,
+    ) -> None:
+        self._session = session
+        self._timeout = aiohttp.ClientTimeout(total=request_timeout)
+        if host.startswith("https://"):
+            msg = "HTTPS is not supported by this client"
+            raise ValueError(msg)
+        normalized_host = host.removeprefix("http://").removeprefix("https://").rstrip("/")
+        if "://" in host and not host.startswith("http://"):
+            msg = f"Unsupported scheme in host value: {host}"
+            raise ValueError(msg)
+        if port is None:
+            self._base_url = f"http://{normalized_host}"
+        else:
+            self._base_url = f"http://{normalized_host}:{port}"
+
+    @property
+    def base_url(self) -> str:
+        """Normalized base URL used for requests."""
+        return self._base_url
+
+    async def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        if "json" in kwargs:
+            payload = kwargs.pop("json")
+            kwargs["data"] = json.dumps(payload, separators=(",", ":")).encode()
+            kwargs.setdefault("headers", {})["Content-Type"] = "application/json"
+        kwargs.setdefault("timeout", self._timeout)
+
+        try:
+            request = self._session.request(method, f"{self._base_url}{path}", **kwargs)
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not reach Duco device at {self._base_url}: {err}"
+            raise DucoConnectionError(msg) from err
+
+        try:
+            async with request as response:
+                if response.status == 429:
+                    raise DucoWriteLimitError()
+
+                if response.status >= 400:
+                    body = await response.text()
+                    msg = f"Unexpected response {response.status} for {path}: {body}"
+                    raise DucoError(msg)
+
+                try:
+                    return await response.json(content_type=None)
+                except ValueError as err:
+                    msg = f"Expected JSON response from {path}: {err}"
+                    raise DucoError(msg) from err
+        except DucoError:
+            raise
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not reach Duco device at {self._base_url}: {err}"
+            raise DucoConnectionError(msg) from err
+
+    @staticmethod
+    def _read_wrapped_value(payload: dict[str, Any], key: str) -> Any:
+        return payload[key]["Val"]
+
+    @staticmethod
+    def _to_node_type(raw_value: str) -> NodeType:
+        try:
+            return NodeType(raw_value)
+        except ValueError:
+            return NodeType.UNKNOWN
+
+    @staticmethod
+    def _to_network_type(raw_value: str) -> NetworkType:
+        try:
+            return NetworkType(raw_value)
+        except ValueError:
+            return NetworkType.UNKNOWN
+
+    async def async_get_api_info(self) -> ApiInfo:
+        """Return API metadata advertised by the box."""
+        payload = await self._request_json("GET", "/api")
+        public_api_version = self._read_wrapped_value(payload, "PublicApiVersion")
+        reported_api_version = None
+        if "ApiVersion" in payload:
+            reported_api_version = self._read_wrapped_value(payload, "ApiVersion")
+        endpoints = [
+            ApiEndpoint(
+                url=item["Url"],
+                methods=list(item.get("Methods", [])),
+                query_parameters=list(item.get("QueryParameters", [])),
+                modules=list(item.get("Modules", [])),
+            )
+            for item in payload.get("ApiInfo", [])
+        ]
+        return ApiInfo(
+            public_api_version=public_api_version,
+            reported_api_version=reported_api_version,
+            endpoints=endpoints,
+        )
+
+    async def async_get_board_info(self) -> BoardInfo:
+        """Return identity and version details for the main unit."""
+        payload = await self._request_json(
+            "GET",
+            "/info",
+            params={"module": "General", "submodule": "Board"},
+        )
+        board = payload["General"]["Board"]
+        return BoardInfo(
+            box_name=self._read_wrapped_value(board, "BoxName"),
+            box_sub_type_name=self._read_wrapped_value(board, "BoxSubTypeName"),
+            serial_board_box=self._read_wrapped_value(board, "SerialBoardBox"),
+            serial_board_comm=self._read_wrapped_value(board, "SerialBoardComm"),
+            serial_duco_box=self._read_wrapped_value(board, "SerialDucoBox"),
+            serial_duco_comm=self._read_wrapped_value(board, "SerialDucoComm"),
+            time=self._read_wrapped_value(board, "Time"),
+            public_api_version=self._read_wrapped_value(board, "PublicApiVersion")
+            if "PublicApiVersion" in board
+            else None,
+            software_version=self._read_wrapped_value(board, "SwVersion")
+            if "SwVersion" in board
+            else None,
+        )
+
+    async def async_get_lan_info(self) -> LanInfo:
+        """Return LAN settings reported by the box."""
+        payload = await self._request_json(
+            "GET",
+            "/info",
+            params={"module": "General", "submodule": "Lan"},
+        )
+        lan = payload["General"]["Lan"]
+        return LanInfo(
+            mode=self._read_wrapped_value(lan, "Mode"),
+            ip=self._read_wrapped_value(lan, "Ip"),
+            net_mask=self._read_wrapped_value(lan, "NetMask"),
+            default_gateway=self._read_wrapped_value(lan, "DefaultGateway"),
+            dns=self._read_wrapped_value(lan, "Dns"),
+            mac=self._read_wrapped_value(lan, "Mac"),
+            host_name=self._read_wrapped_value(lan, "HostName"),
+            rssi_wifi=self._read_wrapped_value(lan, "RssiWifi") if "RssiWifi" in lan else None,
+        )
+
+    async def async_get_diagnostics(self) -> list[DiagComponent]:
+        """Return health states for diagnostic subsystems."""
+        payload = await self._request_json("GET", "/info", params={"module": "Diag"})
+        return [
+            DiagComponent(
+                component=item["Component"],
+                status=DiagStatus(item["Status"]),
+            )
+            for item in payload["Diag"]["SubSystems"]
+        ]
+
+    async def async_get_nodes(self) -> list[Node]:
+        """Return nodes reported by the local API."""
+        payload = await self._request_json("GET", "/info/nodes")
+        return [self._parse_node(item) for item in payload["Nodes"]]
+
+    async def async_get_write_requests_remaining(self) -> int:
+        """Return the remaining write budget reported by the box."""
+        payload = await self._request_json(
+            "GET",
+            "/info",
+            params={"module": "General", "submodule": "PublicApi"},
+        )
+        return int(self._read_wrapped_value(payload["General"]["PublicApi"], "WriteReqCntRemain"))
+
+    async def async_set_ventilation_state(
+        self, node_id: int, state: VentilationState | str
+    ) -> None:
+        """Request a ventilation state change for a node."""
+        state_value = state.value if isinstance(state, VentilationState) else state
+        await self._request_json(
+            "POST",
+            f"/action/nodes/{node_id}",
+            json={"Action": "SetVentilationState", "Val": state_value},
+        )
+
+    def _parse_node(self, payload: dict[str, Any]) -> Node:
+        general = payload["General"]
+        node_general = NodeGeneralInfo(
+            node_type=self._to_node_type(self._read_wrapped_value(general, "Type")),
+            sub_type=self._read_wrapped_value(general, "SubType"),
+            network_type=self._to_network_type(self._read_wrapped_value(general, "NetworkType")),
+            parent=self._read_wrapped_value(general, "Parent"),
+            asso=self._read_wrapped_value(general, "Asso"),
+            name=self._read_wrapped_value(general, "Name"),
+            identify=self._read_wrapped_value(general, "Identify"),
+        )
+
+        ventilation = None
+        if "Ventilation" in payload:
+            vent = payload["Ventilation"]
+            ventilation = NodeVentilationInfo(
+                state=VentilationState(self._read_wrapped_value(vent, "State")),
+                mode=VentilationMode(self._read_wrapped_value(vent, "Mode")),
+                time_state_remain=self._read_wrapped_value(vent, "TimeStateRemain"),
+                time_state_end=self._read_wrapped_value(vent, "TimeStateEnd"),
+                flow_lvl_tgt=self._read_wrapped_value(vent, "FlowLvlTgt")
+                if "FlowLvlTgt" in vent
+                else None,
+            )
+
+        sensor = None
+        if "Sensor" in payload:
+            sensor = payload["Sensor"]
+            sensor = NodeSensorInfo(
+                co2=self._read_wrapped_value(sensor, "Co2") if "Co2" in sensor else None,
+                iaq_co2=self._read_wrapped_value(sensor, "IaqCo2") if "IaqCo2" in sensor else None,
+                rh=self._read_wrapped_value(sensor, "Rh") if "Rh" in sensor else None,
+                iaq_rh=self._read_wrapped_value(sensor, "IaqRh") if "IaqRh" in sensor else None,
+                temp=self._read_wrapped_value(sensor, "Temp") if "Temp" in sensor else None,
+            )
+
+        return Node(
+            node_id=payload["Node"],
+            general=node_general,
+            ventilation=ventilation,
+            sensor=sensor,
+        )

duco_connectivity/exceptions.py

@@ -0,0 +1,20 @@
+"""Exceptions raised by the Duco client."""
+
+
+class DucoError(Exception):
+    """Base class for client errors."""
+
+
+class DucoConnectionError(DucoError):
+    """Raised when the client cannot reach the box."""
+
+
+class DucoWriteLimitError(DucoError):
+    """Raised when the box rejects writes because its budget is exhausted."""
+
+    def __init__(self, remaining: int | None = None) -> None:
+        self.remaining = remaining
+        detail = "Duco write capacity exhausted"
+        if remaining is not None:
+            detail = f"{detail} ({remaining} writes remaining)"
+        super().__init__(detail)

duco_connectivity/models.py

@@ -0,0 +1,165 @@
+"""Typed models for values exposed by the local Duco API."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class NodeType(StrEnum):
+    """Node categories reported by the box."""
+
+    BOX = "BOX"
+    UCCO2 = "UCCO2"
+    UCRH = "UCRH"
+    UCBAT = "UCBAT"
+    UC = "UC"
+    BSRH = "BSRH"
+    VLV = "VLV"
+    UNKNOWN = "UNKNOWN"
+
+
+class NetworkType(StrEnum):
+    """Transport types reported for node connectivity."""
+
+    VIRT = "VIRT"
+    RF = "RF"
+    WI = "WI"
+    UNKNOWN = "UNKNOWN"
+
+
+class VentilationMode(StrEnum):
+    """Control modes reported for node ventilation."""
+
+    AUTO = "AUTO"
+    MANU = "MANU"
+    NONE = "-"
+
+
+class VentilationState(StrEnum):
+    """State values accepted and reported for node ventilation."""
+
+    AUTO = "AUTO"
+    AUT1 = "AUT1"
+    AUT2 = "AUT2"
+    AUT3 = "AUT3"
+    MAN1 = "MAN1"
+    MAN2 = "MAN2"
+    MAN3 = "MAN3"
+    EMPT = "EMPT"
+    CNT1 = "CNT1"
+    CNT2 = "CNT2"
+    CNT3 = "CNT3"
+    MAN1x2 = "MAN1x2"
+    MAN2x2 = "MAN2x2"
+    MAN3x2 = "MAN3x2"
+    MAN1x3 = "MAN1x3"
+    MAN2x3 = "MAN2x3"
+    MAN3x3 = "MAN3x3"
+
+
+class DiagStatus(StrEnum):
+    """Health states returned by the diagnostics API."""
+
+    OK = "Ok"
+    DISABLE = "Disable"
+    ERROR = "Error"
+
+
+@dataclass(frozen=True, slots=True)
+class ApiEndpoint:
+    """Capabilities advertised for a single API endpoint."""
+
+    url: str
+    methods: list[str] = field(default_factory=list)
+    query_parameters: list[str] = field(default_factory=list)
+    modules: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class ApiInfo:
+    """Version and endpoint metadata returned by the API root."""
+
+    public_api_version: str
+    reported_api_version: str | None = None
+    endpoints: list[ApiEndpoint] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class BoardInfo:
+    """Identity and version fields for the main Duco unit."""
+
+    box_name: str
+    box_sub_type_name: str
+    serial_board_box: str
+    serial_board_comm: str
+    serial_duco_box: str
+    serial_duco_comm: str
+    time: int
+    public_api_version: str | None = None
+    software_version: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LanInfo:
+    """LAN settings reported by the main unit."""
+
+    mode: str
+    ip: str
+    net_mask: str
+    default_gateway: str
+    dns: str
+    mac: str
+    host_name: str
+    rssi_wifi: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class NodeSensorInfo:
+    """Sensor readings reported for a node."""
+
+    co2: int | None = None
+    iaq_co2: int | None = None
+    rh: float | None = None
+    iaq_rh: int | None = None
+    temp: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class NodeVentilationInfo:
+    """Ventilation state and timers reported for a node."""
+
+    state: VentilationState
+    mode: VentilationMode
+    time_state_remain: int
+    time_state_end: int
+    flow_lvl_tgt: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class NodeGeneralInfo:
+    """Static node metadata used to identify a device."""
+
+    node_type: NodeType
+    sub_type: int
+    network_type: NetworkType
+    parent: int
+    asso: int
+    name: str
+    identify: int
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """Node returned by the local Duco API."""
+
+    node_id: int
+    general: NodeGeneralInfo
+    ventilation: NodeVentilationInfo | None = None
+    sensor: NodeSensorInfo | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DiagComponent:
+    """Health state for a diagnostic subsystem."""
+
+    component: str
+    status: DiagStatus

python_duco_connectivity-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: python-duco-connectivity
+Version: 0.1.0
+Summary: Async HTTP client for the local Duco Connectivity API
+Author: Ronald van der Meer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ronaldvdmeer/python-duco-connectivity
+Project-URL: Repository, https://github.com/ronaldvdmeer/python-duco-connectivity
+Project-URL: Issues, https://github.com/ronaldvdmeer/python-duco-connectivity/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Dynamic: license-file
+
+# python-duco-connectivity
+
+Async Python client for the local Duco HTTP API.
+
+`python-duco-connectivity` is a small async client for the unauthenticated
+local Duco HTTP endpoints that were validated during initial development. The
+library keeps its public models close to the API payload shape and is intended
+to stay reusable outside Home Assistant.
+
+## Installation
+
+Until the first PyPI release is published, install directly from GitHub:
+
+```bash
+pip install git+https://github.com/ronaldvdmeer/python-duco-connectivity.git
+```
+
+After the package is published on PyPI, install it with:
+
+```bash
+pip install python-duco-connectivity
+```
+
+## Current scope
+
+- HTTP only
+- asynchronous communication via `aiohttp`
+- typed models that stay close to the API response shape
+
+## Public API surface
+
+The current client exposes:
+
+- `async_get_api_info()` for `GET /api`
+- `async_get_board_info()` for `GET /info?module=General&submodule=Board`
+- `async_get_lan_info()` for `GET /info?module=General&submodule=Lan`
+- `async_get_nodes()` for `GET /info/nodes`
+- `async_get_diagnostics()` for `GET /info?module=Diag`
+- `async_get_write_requests_remaining()` for `GET /info?module=General&submodule=PublicApi`
+- `async_set_ventilation_state()` for `POST /action/nodes/{node}` with `SetVentilationState`
+
+The model layer includes `ApiInfo`, `BoardInfo`, `LanInfo`, `Node`,
+`NodeGeneralInfo`, `NodeVentilationInfo`, and `NodeSensorInfo`.
+
+## Development
+
+Install the development dependencies and run the same checks as CI:
+
+```bash
+pip install ".[dev]"
+pytest
+ruff check src tests
+ruff format --check src tests
+mypy src
+bandit -r src -ll
+pip-audit --desc on
+```
+
+## Validation
+
+The current API surface was validated against a real Duco box during the first
+development pass, covering:
+
+- `GET /api`
+- `GET /info?module=General&submodule=Board`
+- `GET /info?module=General&submodule=Lan`
+- `GET /info/nodes`
+- `GET /info?module=General&submodule=PublicApi`
+- `POST /action/nodes/{node}` with a no-op `SetVentilationState`
+

python_duco_connectivity-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+duco_connectivity/__init__.py,sha256=nV81Rmq4633lA5PDACkbTmhQnIiHoizppNkMSde4HWE,1005
+duco_connectivity/client.py,sha256=OLLBaxfH6_S64AbjoR9vty9jB49iqZdVE0u8HwjbAyA,10009
+duco_connectivity/exceptions.py,sha256=gTusGqE3diTu0upVi86mCTfgon27Tmn8XFbiO4teNpQ,605
+duco_connectivity/models.py,sha256=5KistlqS-0Igc7y96gbM74y-MCjjhk36qE0entmhHlk,3553
+duco_connectivity/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_duco_connectivity-0.1.0.dist-info/licenses/LICENSE,sha256=K58DA270jGV1XeBcFR2URo4j_DeAgq__4RcOizKwXc0,1075
+python_duco_connectivity-0.1.0.dist-info/METADATA,sha256=o5eqzL4VigNOfKMRJd-uK489PfFMqaZxu5XlDnw5PAE,3302
+python_duco_connectivity-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_duco_connectivity-0.1.0.dist-info/top_level.txt,sha256=BR24lfzAC5yMbBvnDtD2d4QJu5rPfW6cLloZdrOoBvE,18
+python_duco_connectivity-0.1.0.dist-info/RECORD,,

python_duco_connectivity-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_duco_connectivity-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronald van der Meer
+
+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.

python_duco_connectivity-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+duco_connectivity