pyhelty 0.1.0__tar.gz

pyhelty-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test,dev]"
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest

pyhelty-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pyhelty-0.1.0/.gitignore

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

pyhelty-0.1.0/LICENSE

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

pyhelty-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: pyhelty
+Version: 0.1.0
+Summary: Async client library for Helty Flow VMC (mechanical ventilation) units with the smart Wi-Fi interface
+Project-URL: Homepage, https://github.com/ebaschiera/pyhelty
+Project-URL: Source, https://github.com/ebaschiera/pyhelty
+Project-URL: Issues, https://github.com/ebaschiera/pyhelty/issues
+Author-email: Ermanno Baschiera <ebaschiera@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: asyncio,helty,home-assistant,mvhr,ventilation,vmc
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pyhelty
+
+Async Python client for **Helty Flow** VMC (mechanical ventilation / MVHR) units
+equipped with the smart Wi-Fi interface, such as the *Flow Plus*.
+
+It speaks the unit's reverse-engineered TCP protocol (default port **5001**) and
+exposes a small, fully typed `asyncio` API. It is the device-communication layer
+behind the Home Assistant `helty` integration; it has **no** Home Assistant
+dependency and can be used standalone.
+
+> The protocol has no official specification. Behaviour is reverse-engineered
+> from a real Helty FlowPlus; your mileage may vary on other models.
+
+## Install
+
+```bash
+pip install pyhelty
+```
+
+## Usage
+
+```python
+import asyncio
+from pyhelty import HeltyClient, FanMode
+
+async def main() -> None:
+    client = HeltyClient("192.168.1.50")  # port defaults to 5001
+
+    data = await client.async_get_data()
+    print(data.name, data.fan_mode, data.indoor_temperature, data.indoor_humidity)
+
+    await client.async_set_fan_mode(FanMode.NIGHT)
+    await client.async_set_led(False)
+
+asyncio.run(main())
+```
+
+## API
+
+- `HeltyClient(host, port=5001, *, timeout=10.0)`
+- `async_get_name() -> str` — the user-assigned name (also used as a stable id)
+- `async_get_data() -> HeltyData` — name, fan mode, LED state, indoor/outdoor
+  temperature, indoor humidity, plus the raw `VMGI`/`VMGO` integer fields for
+  fields not yet decoded
+- `async_set_fan_mode(mode: FanMode)` — `OFF, LOW, MEDIUM, HIGH, MAX, BOOST,
+  NIGHT, FREE_COOLING`
+- `async_set_led(on: bool)`
+- `async_reset_filter()`
+
+Errors derive from `HeltyError`: `HeltyConnectionError`, `HeltyResponseError`,
+`HeltyCommandError`.
+
+## Protocol notes
+
+| Command | Purpose | Reply |
+|---|---|---|
+| `VMNM?` | device name | `VMNM <name>` |
+| `VMGI?` | sensors (15 fields, tenths) | `VMGI,<indoor_t>,<outdoor_t>,<indoor_rh>,...` |
+| `VMGH?` | status (15 fields) | `VMGO,<fan_mode>,<led>,...` |
+| `VMWH000000<n>` | set fan mode `n` (0-7) | `OK` |
+| `VMWH0100010` / `VMWH0100000` | LED on / off | `OK` |
+| `VMWH0417744` | reset filter counter | `OK` |
+
+The unit serves one command per TCP connection and then closes it; the client
+serialises commands with a lock.
+
+## Development
+
+```bash
+pip install -e ".[test,dev]"
+pytest
+ruff check .
+mypy src
+```
+
+## License
+
+MIT

pyhelty-0.1.0/README.md

@@ -0,0 +1,78 @@
+# pyhelty
+
+Async Python client for **Helty Flow** VMC (mechanical ventilation / MVHR) units
+equipped with the smart Wi-Fi interface, such as the *Flow Plus*.
+
+It speaks the unit's reverse-engineered TCP protocol (default port **5001**) and
+exposes a small, fully typed `asyncio` API. It is the device-communication layer
+behind the Home Assistant `helty` integration; it has **no** Home Assistant
+dependency and can be used standalone.
+
+> The protocol has no official specification. Behaviour is reverse-engineered
+> from a real Helty FlowPlus; your mileage may vary on other models.
+
+## Install
+
+```bash
+pip install pyhelty
+```
+
+## Usage
+
+```python
+import asyncio
+from pyhelty import HeltyClient, FanMode
+
+async def main() -> None:
+    client = HeltyClient("192.168.1.50")  # port defaults to 5001
+
+    data = await client.async_get_data()
+    print(data.name, data.fan_mode, data.indoor_temperature, data.indoor_humidity)
+
+    await client.async_set_fan_mode(FanMode.NIGHT)
+    await client.async_set_led(False)
+
+asyncio.run(main())
+```
+
+## API
+
+- `HeltyClient(host, port=5001, *, timeout=10.0)`
+- `async_get_name() -> str` — the user-assigned name (also used as a stable id)
+- `async_get_data() -> HeltyData` — name, fan mode, LED state, indoor/outdoor
+  temperature, indoor humidity, plus the raw `VMGI`/`VMGO` integer fields for
+  fields not yet decoded
+- `async_set_fan_mode(mode: FanMode)` — `OFF, LOW, MEDIUM, HIGH, MAX, BOOST,
+  NIGHT, FREE_COOLING`
+- `async_set_led(on: bool)`
+- `async_reset_filter()`
+
+Errors derive from `HeltyError`: `HeltyConnectionError`, `HeltyResponseError`,
+`HeltyCommandError`.
+
+## Protocol notes
+
+| Command | Purpose | Reply |
+|---|---|---|
+| `VMNM?` | device name | `VMNM <name>` |
+| `VMGI?` | sensors (15 fields, tenths) | `VMGI,<indoor_t>,<outdoor_t>,<indoor_rh>,...` |
+| `VMGH?` | status (15 fields) | `VMGO,<fan_mode>,<led>,...` |
+| `VMWH000000<n>` | set fan mode `n` (0-7) | `OK` |
+| `VMWH0100010` / `VMWH0100000` | LED on / off | `OK` |
+| `VMWH0417744` | reset filter counter | `OK` |
+
+The unit serves one command per TCP connection and then closes it; the client
+serialises commands with a lock.
+
+## Development
+
+```bash
+pip install -e ".[test,dev]"
+pytest
+ruff check .
+mypy src
+```
+
+## License
+
+MIT

pyhelty-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyhelty"
+version = "0.1.0"
+description = "Async client library for Helty Flow VMC (mechanical ventilation) units with the smart Wi-Fi interface"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Ermanno Baschiera", email = "ebaschiera@gmail.com" }]
+keywords = ["helty", "vmc", "mvhr", "ventilation", "home-assistant", "asyncio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ebaschiera/pyhelty"
+Source = "https://github.com/ebaschiera/pyhelty"
+Issues = "https://github.com/ebaschiera/pyhelty/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyhelty"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--cov=pyhelty --cov-report=term-missing"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "ASYNC", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true

pyhelty-0.1.0/src/pyhelty/__init__.py

@@ -0,0 +1,27 @@
+"""Async client library for Helty Flow VMC units with the smart Wi-Fi interface."""
+
+from __future__ import annotations
+
+from .client import HeltyClient
+from .const import DEFAULT_PORT, DEFAULT_TIMEOUT, FanMode
+from .exceptions import (
+    HeltyCommandError,
+    HeltyConnectionError,
+    HeltyError,
+    HeltyResponseError,
+)
+from .models import HeltyData
+
+__all__ = [
+    "DEFAULT_PORT",
+    "DEFAULT_TIMEOUT",
+    "FanMode",
+    "HeltyClient",
+    "HeltyCommandError",
+    "HeltyConnectionError",
+    "HeltyData",
+    "HeltyError",
+    "HeltyResponseError",
+]
+
+__version__ = "0.1.0"

pyhelty-0.1.0/src/pyhelty/client.py

@@ -0,0 +1,186 @@
+"""Async client for Helty Flow VMC units."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from .const import (
+    CMD_LED_OFF,
+    CMD_LED_ON,
+    CMD_NAME,
+    CMD_RESET_FILTER,
+    CMD_SENSORS,
+    CMD_STATUS,
+    DEFAULT_PORT,
+    DEFAULT_RETRIES,
+    DEFAULT_RETRY_DELAY,
+    DEFAULT_TIMEOUT,
+    LED_ON_VALUE,
+    PREFIX_NAME,
+    PREFIX_SENSORS,
+    PREFIX_STATUS,
+    RESPONSE_OK,
+    SENSOR_SCALE,
+    SIGNED_16_MODULUS,
+    SIGNED_16_THRESHOLD,
+    FanMode,
+)
+from .exceptions import (
+    HeltyCommandError,
+    HeltyConnectionError,
+    HeltyResponseError,
+)
+from .models import HeltyData
+
+_LOGGER = logging.getLogger(__name__)
+
+_READ_LIMIT = 4096
+
+
+class HeltyClient:
+    """Talks to a single Helty Flow unit over its TCP interface.
+
+    The unit serves one command per TCP connection and then closes it, so each
+    call opens a fresh connection. An internal lock serialises commands because
+    the unit does not reliably handle concurrent connections.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int = DEFAULT_PORT,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._timeout = timeout
+        self._retries = retries
+        self._retry_delay = retry_delay
+        self._lock = asyncio.Lock()
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def port(self) -> int:
+        return self._port
+
+    async def _execute_once(self, command: bytes) -> str:
+        """Open a connection, send one command and return the stripped reply."""
+        async with asyncio.timeout(self._timeout):
+            reader, writer = await asyncio.open_connection(self._host, self._port)
+            try:
+                writer.write(command)
+                await writer.drain()
+                payload = await reader.read(_READ_LIMIT)
+            finally:
+                writer.close()
+                await writer.wait_closed()
+        return payload.decode("ascii", errors="replace").strip()
+
+    async def _execute(self, command: bytes) -> str:
+        """Send one command, retrying transient failures and empty replies.
+
+        The unit serves a single command per connection and intermittently
+        accepts a connection but returns an empty payload (especially right
+        after an idle period or on rapid reconnection), so an empty reply is
+        treated as a retryable, transient condition.
+        """
+        last_error: Exception | None = None
+        async with self._lock:
+            for attempt in range(self._retries + 1):
+                if attempt:
+                    await asyncio.sleep(self._retry_delay)
+                try:
+                    reply = await self._execute_once(command)
+                except (TimeoutError, OSError) as err:
+                    last_error = err
+                    _LOGGER.debug(
+                        "Helty %s:%s command %r failed (attempt %d/%d): %s",
+                        self._host, self._port, command, attempt + 1, self._retries + 1, err,
+                    )
+                    continue
+                if reply:
+                    return reply
+                last_error = HeltyConnectionError("empty reply")
+                _LOGGER.debug(
+                    "Helty %s:%s returned empty reply to %r (attempt %d/%d)",
+                    self._host, self._port, command, attempt + 1, self._retries + 1,
+                )
+        raise HeltyConnectionError(
+            f"Failed to communicate with Helty at {self._host}:{self._port}: {last_error}"
+        )
+
+    @staticmethod
+    def _parse_fields(reply: str, prefix: str) -> tuple[int, ...]:
+        """Validate the reply prefix and parse the trailing CSV integer fields."""
+        parts = reply.split(",")
+        if not parts or parts[0] != prefix:
+            raise HeltyResponseError(f"Expected {prefix!r} reply, got {reply!r}")
+        try:
+            return tuple(int(value) for value in parts[1:])
+        except ValueError as err:
+            raise HeltyResponseError(f"Non-integer field in {reply!r}") from err
+
+    @staticmethod
+    def _to_temperature(raw: int) -> float:
+        """Scale a raw tenths-of-degree value, treating it as signed 16-bit."""
+        if raw >= SIGNED_16_THRESHOLD:
+            raw -= SIGNED_16_MODULUS
+        return raw / SENSOR_SCALE
+
+    async def async_get_name(self) -> str:
+        """Return the user-assigned device name (also used as a stable id)."""
+        reply = await self._execute(CMD_NAME)
+        if not reply.startswith(PREFIX_NAME):
+            raise HeltyResponseError(f"Expected {PREFIX_NAME!r} reply, got {reply!r}")
+        return reply[len(PREFIX_NAME) :].strip()
+
+    async def async_get_data(self) -> HeltyData:
+        """Fetch name, sensors and status in a single coordinated read."""
+        name = await self.async_get_name()
+        sensors = self._parse_fields(await self._execute(CMD_SENSORS), PREFIX_SENSORS)
+        status = self._parse_fields(await self._execute(CMD_STATUS), PREFIX_STATUS)
+
+        if len(sensors) < 3:
+            raise HeltyResponseError(f"Too few sensor fields: {sensors!r}")
+        if len(status) < 2:
+            raise HeltyResponseError(f"Too few status fields: {status!r}")
+
+        try:
+            fan_mode = FanMode(status[0])
+        except ValueError as err:
+            raise HeltyResponseError(f"Unknown fan mode {status[0]}") from err
+
+        return HeltyData(
+            name=name,
+            fan_mode=fan_mode,
+            leds_on=status[1] == LED_ON_VALUE,
+            indoor_temperature=self._to_temperature(sensors[0]),
+            outdoor_temperature=self._to_temperature(sensors[1]),
+            indoor_humidity=sensors[2] / SENSOR_SCALE,
+            raw_sensors=sensors,
+            raw_status=status,
+        )
+
+    async def _write(self, command: bytes) -> None:
+        reply = await self._execute(command)
+        if reply != RESPONSE_OK:
+            raise HeltyCommandError(f"Command {command!r} not acknowledged, got {reply!r}")
+
+    async def async_set_fan_mode(self, mode: FanMode) -> None:
+        """Select a fan speed or preset program."""
+        await self._write(mode.command)
+
+    async def async_set_led(self, on: bool) -> None:
+        """Turn the front LED panel on or off."""
+        await self._write(CMD_LED_ON if on else CMD_LED_OFF)
+
+    async def async_reset_filter(self) -> None:
+        """Reset the filter-life counter."""
+        await self._write(CMD_RESET_FILTER)

pyhelty-0.1.0/src/pyhelty/const.py

@@ -0,0 +1,90 @@
+"""Protocol constants for the Helty Flow VMC TCP interface.
+
+The protocol is reverse-engineered (no official specification). Commands are
+plain ASCII byte strings sent over a TCP socket; the unit replies with an ASCII
+payload and then closes the connection. One command is served per connection.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+#: Default TCP port exposed by the Helty smart Wi-Fi interface.
+DEFAULT_PORT = 5001
+
+#: Default per-command timeout, in seconds.
+DEFAULT_TIMEOUT = 10.0
+
+#: Default number of retries on a transient failure or empty reply.
+DEFAULT_RETRIES = 3
+
+#: Default delay between retries, in seconds.
+DEFAULT_RETRY_DELAY = 0.5
+
+# --- Read commands ---------------------------------------------------------
+#: Query the device name. Reply: ``VMNM <name>``.
+CMD_NAME = b"VMNM?"
+#: Query live sensor values. Reply: ``VMGI,<f1>,<f2>,...`` (15 fields).
+CMD_SENSORS = b"VMGI?"
+#: Query operating status/config. Reply: ``VMGO,<f1>,<f2>,...`` (15 fields).
+CMD_STATUS = b"VMGH?"
+
+# --- Reply prefixes --------------------------------------------------------
+PREFIX_NAME = "VMNM"
+PREFIX_SENSORS = "VMGI"
+PREFIX_STATUS = "VMGO"
+
+# --- Write commands --------------------------------------------------------
+#: Turn the front LED panel on / off.
+CMD_LED_ON = b"VMWH0100010"
+CMD_LED_OFF = b"VMWH0100000"
+#: Reset the filter-life counter.
+CMD_RESET_FILTER = b"VMWH0417744"
+
+#: Reply returned by the unit on a successful write command.
+RESPONSE_OK = "OK"
+
+#: Sensor scaling: raw integers are tenths of a unit (e.g. ``281`` -> ``28.1``).
+SENSOR_SCALE = 10
+
+#: Raw values at or above this are interpreted as signed 16-bit (negative temps).
+SIGNED_16_THRESHOLD = 32768
+SIGNED_16_MODULUS = 65536
+
+
+class FanMode(IntEnum):
+    """Operating mode reported by status field 1 and set via ``VMWH000000<n>``."""
+
+    OFF = 0
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    MAX = 4
+    BOOST = 5  # AirGuard "HyperVentilation"
+    NIGHT = 6
+    FREE_COOLING = 7
+
+    @property
+    def command(self) -> bytes:
+        """The ``VMWH`` write command that selects this mode."""
+        return f"VMWH000000{self.value}".encode("ascii")
+
+
+#: Modes that represent a discrete fan speed (as opposed to a preset program).
+SPEED_MODES: tuple[FanMode, ...] = (
+    FanMode.OFF,
+    FanMode.LOW,
+    FanMode.MEDIUM,
+    FanMode.HIGH,
+    FanMode.MAX,
+)
+
+#: Modes that represent a preset program.
+PRESET_MODES: tuple[FanMode, ...] = (
+    FanMode.BOOST,
+    FanMode.NIGHT,
+    FanMode.FREE_COOLING,
+)
+
+#: Raw value of status field 2 (LED) meaning "on".
+LED_ON_VALUE = 10

pyhelty-0.1.0/src/pyhelty/exceptions.py

@@ -0,0 +1,19 @@
+"""Exceptions raised by :mod:`pyhelty`."""
+
+from __future__ import annotations
+
+
+class HeltyError(Exception):
+    """Base class for all pyhelty errors."""
+
+
+class HeltyConnectionError(HeltyError):
+    """Raised when the unit cannot be reached or times out."""
+
+
+class HeltyResponseError(HeltyError):
+    """Raised when the unit returns a malformed or unexpected response."""
+
+
+class HeltyCommandError(HeltyError):
+    """Raised when a write command is not acknowledged with ``OK``."""

pyhelty-0.1.0/src/pyhelty/models.py

@@ -0,0 +1,33 @@
+"""Data models for :mod:`pyhelty`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .const import FanMode
+
+
+@dataclass(frozen=True, slots=True)
+class HeltyData:
+    """A snapshot of the unit's sensors and operating status.
+
+    ``raw_sensors`` and ``raw_status`` hold the full integer field lists from
+    the ``VMGI``/``VMGO`` replies so that callers can decode additional,
+    not-yet-identified fields without a library change.
+    """
+
+    name: str
+    fan_mode: FanMode
+    leds_on: bool
+    indoor_temperature: float | None
+    outdoor_temperature: float | None
+    indoor_humidity: float | None
+    raw_sensors: tuple[int, ...]
+    raw_status: tuple[int, ...]
+
+    @property
+    def is_preset(self) -> bool:
+        """True when the current mode is a preset program rather than a speed."""
+        from .const import PRESET_MODES
+
+        return self.fan_mode in PRESET_MODES

pyhelty-0.1.0/tests/conftest.py

@@ -0,0 +1,68 @@
+"""Test fixtures: a fake Helty TCP server."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+import pytest
+
+# Canonical replies captured from a real Helty FlowPlus.
+DEFAULT_REPLIES: dict[bytes, bytes] = {
+    b"VMNM?": b"VMNM VMC_soggiorn",
+    b"VMGI?": b"VMGI,00281,00312,00422,00000,16384,04516,00265,00099,04354,00124,00000,00265,00422,00001,00001",  # noqa: E501
+    b"VMGH?": b"VMGO,00001,00010,00015,00000,00000,00100,00000,01200,00200,00220,09000,00600,00000,00001,00000",  # noqa: E501
+    # Any VMWH... write command is acknowledged with OK.
+}
+
+
+class FakeHelty:
+    """A minimal TCP server emulating one command per connection."""
+
+    def __init__(self) -> None:
+        self.replies: dict[bytes, bytes] = dict(DEFAULT_REPLIES)
+        self.received: list[bytes] = []
+        #: Number of leading connections that should reply with an empty payload
+        #: (emulating the real unit's intermittent "busy" behaviour).
+        self.empty_replies = 0
+        self._server: asyncio.AbstractServer | None = None
+        self.host = "127.0.0.1"
+        self.port = 0
+
+    async def _handle(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        command = (await reader.read(64)).strip()
+        self.received.append(command)
+        if self.empty_replies > 0:
+            self.empty_replies -= 1
+            writer.close()
+            return
+        if command in self.replies:
+            reply = self.replies[command]
+        elif command.startswith(b"VMWH"):
+            reply = b"OK"
+        else:
+            reply = b""
+        writer.write(reply)
+        await writer.drain()
+        writer.close()
+
+    async def start(self) -> None:
+        self._server = await asyncio.start_server(self._handle, self.host, 0)
+        self.port = self._server.sockets[0].getsockname()[1]
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+
+
+@pytest.fixture
+async def fake_helty() -> AsyncIterator[FakeHelty]:
+    server = FakeHelty()
+    await server.start()
+    try:
+        yield server
+    finally:
+        await server.stop()

pyhelty-0.1.0/tests/test_client.py

@@ -0,0 +1,164 @@
+"""Tests for :class:`pyhelty.HeltyClient`."""
+
+from __future__ import annotations
+
+import pytest
+
+from pyhelty import (
+    FanMode,
+    HeltyClient,
+    HeltyCommandError,
+    HeltyConnectionError,
+    HeltyResponseError,
+)
+
+from .conftest import FakeHelty
+
+
+def _client(server: FakeHelty) -> HeltyClient:
+    return HeltyClient(server.host, server.port, timeout=2.0, retries=3, retry_delay=0.0)
+
+
+async def test_get_name(fake_helty: FakeHelty) -> None:
+    client = _client(fake_helty)
+    assert await client.async_get_name() == "VMC_soggiorn"
+
+
+async def test_get_data(fake_helty: FakeHelty) -> None:
+    client = _client(fake_helty)
+    data = await client.async_get_data()
+
+    assert data.name == "VMC_soggiorn"
+    assert data.fan_mode is FanMode.LOW
+    assert data.leds_on is True
+    assert data.indoor_temperature == pytest.approx(28.1)
+    assert data.outdoor_temperature == pytest.approx(31.2)
+    assert data.indoor_humidity == pytest.approx(42.2)
+    assert len(data.raw_sensors) == 15
+    assert len(data.raw_status) == 15
+    assert data.is_preset is False
+
+
+async def test_get_data_negative_outdoor_temperature(fake_helty: FakeHelty) -> None:
+    # -5.0 C encoded as signed 16-bit: 65536 - 50 = 65486.
+    fake_helty.replies[b"VMGI?"] = b"VMGI,00200,65486,00500"
+    client = _client(fake_helty)
+    data = await client.async_get_data()
+    assert data.outdoor_temperature == pytest.approx(-5.0)
+
+
+async def test_get_data_preset_mode(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMGH?"] = b"VMGO,00005,00000"
+    client = _client(fake_helty)
+    data = await client.async_get_data()
+    assert data.fan_mode is FanMode.BOOST
+    assert data.leds_on is False
+    assert data.is_preset is True
+
+
+@pytest.mark.parametrize(
+    ("mode", "expected"),
+    [
+        (FanMode.OFF, b"VMWH0000000"),
+        (FanMode.LOW, b"VMWH0000001"),
+        (FanMode.MAX, b"VMWH0000004"),
+        (FanMode.BOOST, b"VMWH0000005"),
+        (FanMode.FREE_COOLING, b"VMWH0000007"),
+    ],
+)
+async def test_set_fan_mode(fake_helty: FakeHelty, mode: FanMode, expected: bytes) -> None:
+    client = _client(fake_helty)
+    await client.async_set_fan_mode(mode)
+    assert fake_helty.received[-1] == expected
+
+
+async def test_set_led(fake_helty: FakeHelty) -> None:
+    client = _client(fake_helty)
+    await client.async_set_led(True)
+    assert fake_helty.received[-1] == b"VMWH0100010"
+    await client.async_set_led(False)
+    assert fake_helty.received[-1] == b"VMWH0100000"
+
+
+async def test_reset_filter(fake_helty: FakeHelty) -> None:
+    client = _client(fake_helty)
+    await client.async_reset_filter()
+    assert fake_helty.received[-1] == b"VMWH0417744"
+
+
+async def test_command_not_acknowledged(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMWH0100010"] = b"ERR"
+    client = _client(fake_helty)
+    with pytest.raises(HeltyCommandError):
+        await client.async_set_led(True)
+
+
+async def test_malformed_sensor_reply(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMGI?"] = b"GARBAGE"
+    client = _client(fake_helty)
+    with pytest.raises(HeltyResponseError):
+        await client.async_get_data()
+
+
+async def test_non_integer_field(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMGI?"] = b"VMGI,00281,abc,00422"
+    client = _client(fake_helty)
+    with pytest.raises(HeltyResponseError):
+        await client.async_get_data()
+
+
+async def test_unknown_fan_mode(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMGH?"] = b"VMGO,00099,00000"
+    client = _client(fake_helty)
+    with pytest.raises(HeltyResponseError):
+        await client.async_get_data()
+
+
+async def test_bad_name_reply(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMNM?"] = b"NOPE"
+    client = _client(fake_helty)
+    with pytest.raises(HeltyResponseError):
+        await client.async_get_name()
+
+
+async def test_connection_error() -> None:
+    # Nothing listening on this port.
+    client = HeltyClient("127.0.0.1", 1, timeout=1.0, retries=1, retry_delay=0.0)
+    with pytest.raises(HeltyConnectionError):
+        await client.async_get_name()
+
+
+async def test_empty_reply_is_retried(fake_helty: FakeHelty) -> None:
+    # The first two connections reply empty; the client should retry and succeed.
+    fake_helty.empty_replies = 2
+    client = _client(fake_helty)
+    assert await client.async_get_name() == "VMC_soggiorn"
+
+
+async def test_empty_reply_exhausts_retries(fake_helty: FakeHelty) -> None:
+    fake_helty.empty_replies = 99
+    client = HeltyClient(
+        fake_helty.host, fake_helty.port, timeout=2.0, retries=2, retry_delay=0.0
+    )
+    with pytest.raises(HeltyConnectionError):
+        await client.async_get_name()
+
+
+async def test_too_few_sensor_fields(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMGI?"] = b"VMGI,00281"
+    client = _client(fake_helty)
+    with pytest.raises(HeltyResponseError):
+        await client.async_get_data()
+
+
+async def test_too_few_status_fields(fake_helty: FakeHelty) -> None:
+    fake_helty.replies[b"VMGH?"] = b"VMGO,00001"
+    client = _client(fake_helty)
+    with pytest.raises(HeltyResponseError):
+        await client.async_get_data()
+
+
+def test_client_properties() -> None:
+    client = HeltyClient("1.2.3.4", 5001)
+    assert client.host == "1.2.3.4"
+    assert client.port == 5001