pyhelty 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyhelty/__init__.py,sha256=P0EoaBRd5gU-e7zKso5N5km1tGnQ3XNwoA1PeQh5Sag,587
+pyhelty/client.py,sha256=v1DMmKwTADOSmW_vqxrkqsozLDUP_PET8x5KUgAoWzA,6605
+pyhelty/const.py,sha256=3f_PpIdnkuf4-iPkmJ55FXg7QgahdHysrFtxIrDUt2U,2576
+pyhelty/exceptions.py,sha256=s4TdAvlIV6i7TOfinV9vawioNvtbPuUxwLU5E-hAjNk,485
+pyhelty/models.py,sha256=kc4YmXPF0wX-uxzKm3wzkqTokx8RSoJwfwLyI7ZVlZE,915
+pyhelty/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyhelty-0.1.0.dist-info/METADATA,sha256=rTm853IDzQUKXc54_Wbi6lqmwxhq7MoxvRblWhKpDmw,3519
+pyhelty-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pyhelty-0.1.0.dist-info/licenses/LICENSE,sha256=32Lok91VHOSzOcH_3yzT7o-OybwTYMAxHqyBzZZNh_8,1074
+pyhelty-0.1.0.dist-info/RECORD,,

pyhelty-0.1.0.dist-info/WHEEL

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

pyhelty-0.1.0.dist-info/licenses/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.