pyheltycloud 0.1.0__tar.gz

pyheltycloud-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.

pyheltycloud-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pyheltycloud
+Version: 0.1.0
+Summary: Async client for the Helty cloud (hcloud) of Helty Flow VMC units
+Author: Ermanno Baschiera
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ebaschiera/pyheltycloud
+Keywords: helty,vmc,hrv,home-assistant
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Dynamic: license-file
+
+# pyheltycloud
+
+Async Python client for the **hcloud** backend of [Helty](https://www.heltyair.com/), used by the
+recent control panels of Helty Flow VMC units and by the "Helty Home" app.
+
+Born as the foundation for a `helty_cloud` Home Assistant integration, next to
+[`helty`](https://www.home-assistant.io/integrations/helty/) which speaks the local protocol of the
+previous panels. The new panels expose no listening port: control necessarily goes through the
+manufacturer's cloud.
+
+> **Unofficial.** The API is undocumented: it has been reconstructed by observing the app and
+> verified on real hardware. Helty may change it at any time.
+
+## Installation
+
+```bash
+pip install pyheltycloud
+```
+
+## Usage
+
+```python
+import asyncio
+from pyheltycloud import HeltyCloud, VmcMode
+
+async def main() -> None:
+    async with HeltyCloud("me@example.com", "password") as helty:
+        for device in await helty.get_devices():
+            print(device.name, device.model)
+
+            # update() wakes the board and then reads: the method to use for polling.
+            state = await helty.update(device)
+            print(state.mode, state.temperature_indoor, state.humidity)
+
+            # set_mode_verified() re-reads the state and resends if the command is lost.
+            await helty.set_mode_verified(device, VmcMode.SPEED_2)
+
+asyncio.run(main())
+```
+
+## How it works
+
+Two separate channels. The panel runs no server: it holds an outbound connection to **AWS IoT Core**
+(eu-central-1), and Helty's backend relays to it. Clients never reach the panel directly — the app
+and this library call the REST API at `api.hcloud.heltyair.com`, authenticating against an **AWS
+Cognito** user pool with the account's own email and password (SRP, nothing to provision).
+
+That shape explains both surprises below: a read returns the last message the panel pushed, not the
+machine's current state, and a write is a message handed to the relay, so a `200` only means the
+backend took it.
+
+## Things to know before using it
+
+**Read, do not poke.** The board reports on its own every 5.5 minutes at the median and every 33
+at the 99th percentile, measured over 5334 spontaneous reports, because it reports on any
+significant change as well as on its timer. Reading the last message costs one call and the board
+never notices, so a poll should use `get_last_telemetry()`. `refresh()` instead wakes the board,
+and `update()` wakes it and waits up to ~15 seconds for the answer: keep those for right after a
+command, when confirmation is worth the round trip. The vendor asks not to solicit on a short
+timer.
+
+**Commands are acknowledged, not guaranteed.** The cloud answers `200` before the board has done
+anything. `set_mode()` is a single send; `set_mode_verified()` re-reads the state and retries,
+for callers that would rather pay a round trip than miss a command.
+
+**Two different serials.** Reads use `device.serial_number` (the machine), writes use
+`device.board_serial` (the board). They are not interchangeable.
+
+## What is covered
+
+| | |
+|---|---|
+| Reading | devices, mode, indoor and outdoor temperature, humidity, CO2 and VOC where installed, both fan percentages, alarms as named flags, the two counters of treated air |
+| Writing | all modes (off, speeds 1-4, night, hyperventilation, free cooling), optionally with verification and retries; report request |
+| Not mapped yet | commands that carry an argument: the API refuses every shape tried. The brightness level, the one argument worth having, belongs to the Elite version's lights, so a FlowPLUS may have nothing here |
+| Not mapped yet | the filter reset: the vendor gives command 37, unverified, and sending it would destroy the only record of how old the filter is |
+| Not available | whether the panel is lit, and whether Auto is on: 40, 41, 38 and 39 take effect, but the vendor states this generation of machines cannot report either state |
+| Not available | the unit of the CO2 and VOC readings, undocumented and untestable on a unit that has neither sensor |
+| Not available | the alarm threshold of the filter — 90000 m³ on the current firmware, by the vendor's word, and in none of the values the board reports |
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest --cov=pyheltycloud
+uv run ruff check src tests && uv run ruff format --check src tests
+uv run mypy
+```
+
+Tests never touch the network: they use a fake local HTTP backend.
+
+## License
+
+MIT.

pyheltycloud-0.1.0/README.md

@@ -0,0 +1,94 @@
+# pyheltycloud
+
+Async Python client for the **hcloud** backend of [Helty](https://www.heltyair.com/), used by the
+recent control panels of Helty Flow VMC units and by the "Helty Home" app.
+
+Born as the foundation for a `helty_cloud` Home Assistant integration, next to
+[`helty`](https://www.home-assistant.io/integrations/helty/) which speaks the local protocol of the
+previous panels. The new panels expose no listening port: control necessarily goes through the
+manufacturer's cloud.
+
+> **Unofficial.** The API is undocumented: it has been reconstructed by observing the app and
+> verified on real hardware. Helty may change it at any time.
+
+## Installation
+
+```bash
+pip install pyheltycloud
+```
+
+## Usage
+
+```python
+import asyncio
+from pyheltycloud import HeltyCloud, VmcMode
+
+async def main() -> None:
+    async with HeltyCloud("me@example.com", "password") as helty:
+        for device in await helty.get_devices():
+            print(device.name, device.model)
+
+            # update() wakes the board and then reads: the method to use for polling.
+            state = await helty.update(device)
+            print(state.mode, state.temperature_indoor, state.humidity)
+
+            # set_mode_verified() re-reads the state and resends if the command is lost.
+            await helty.set_mode_verified(device, VmcMode.SPEED_2)
+
+asyncio.run(main())
+```
+
+## How it works
+
+Two separate channels. The panel runs no server: it holds an outbound connection to **AWS IoT Core**
+(eu-central-1), and Helty's backend relays to it. Clients never reach the panel directly — the app
+and this library call the REST API at `api.hcloud.heltyair.com`, authenticating against an **AWS
+Cognito** user pool with the account's own email and password (SRP, nothing to provision).
+
+That shape explains both surprises below: a read returns the last message the panel pushed, not the
+machine's current state, and a write is a message handed to the relay, so a `200` only means the
+backend took it.
+
+## Things to know before using it
+
+**Read, do not poke.** The board reports on its own every 5.5 minutes at the median and every 33
+at the 99th percentile, measured over 5334 spontaneous reports, because it reports on any
+significant change as well as on its timer. Reading the last message costs one call and the board
+never notices, so a poll should use `get_last_telemetry()`. `refresh()` instead wakes the board,
+and `update()` wakes it and waits up to ~15 seconds for the answer: keep those for right after a
+command, when confirmation is worth the round trip. The vendor asks not to solicit on a short
+timer.
+
+**Commands are acknowledged, not guaranteed.** The cloud answers `200` before the board has done
+anything. `set_mode()` is a single send; `set_mode_verified()` re-reads the state and retries,
+for callers that would rather pay a round trip than miss a command.
+
+**Two different serials.** Reads use `device.serial_number` (the machine), writes use
+`device.board_serial` (the board). They are not interchangeable.
+
+## What is covered
+
+| | |
+|---|---|
+| Reading | devices, mode, indoor and outdoor temperature, humidity, CO2 and VOC where installed, both fan percentages, alarms as named flags, the two counters of treated air |
+| Writing | all modes (off, speeds 1-4, night, hyperventilation, free cooling), optionally with verification and retries; report request |
+| Not mapped yet | commands that carry an argument: the API refuses every shape tried. The brightness level, the one argument worth having, belongs to the Elite version's lights, so a FlowPLUS may have nothing here |
+| Not mapped yet | the filter reset: the vendor gives command 37, unverified, and sending it would destroy the only record of how old the filter is |
+| Not available | whether the panel is lit, and whether Auto is on: 40, 41, 38 and 39 take effect, but the vendor states this generation of machines cannot report either state |
+| Not available | the unit of the CO2 and VOC readings, undocumented and untestable on a unit that has neither sensor |
+| Not available | the alarm threshold of the filter — 90000 m³ on the current firmware, by the vendor's word, and in none of the values the board reports |
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest --cov=pyheltycloud
+uv run ruff check src tests && uv run ruff format --check src tests
+uv run mypy
+```
+
+Tests never touch the network: they use a fake local HTTP backend.
+
+## License
+
+MIT.

pyheltycloud-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyheltycloud"
+version = "0.1.0"
+description = "Async client for the Helty cloud (hcloud) of Helty Flow VMC units"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Ermanno Baschiera" }]
+keywords = ["helty", "vmc", "hrv", "home-assistant"]
+dependencies = ["aiohttp>=3.9"]
+
+[project.urls]
+Homepage = "https://github.com/ebaschiera/pyheltycloud"
+
+[dependency-groups]
+dev = ["pytest", "pytest-asyncio", "pytest-cov", "ruff", "mypy"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pyheltycloud = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF", "D"]
+ignore = ["D203", "D213"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests are documented by their name; docstrings only where the "why" needs explaining.
+"tests/*" = ["D100", "D101", "D102", "D103", "D104"]
+
+[tool.mypy]
+strict = true
+packages = ["pyheltycloud"]

pyheltycloud-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyheltycloud-0.1.0/src/pyheltycloud/__init__.py

@@ -0,0 +1,24 @@
+"""Async client for the Helty cloud (hcloud) of Helty Flow VMC units."""
+
+from .client import HeltyCloud
+from .const import Alarm, Command, VmcMode
+from .exceptions import (
+    HeltyCloudAuthError,
+    HeltyCloudConnectionError,
+    HeltyCloudError,
+    HeltyCloudNoDataError,
+)
+from .models import HeltyDevice, HeltyState
+
+__all__ = [
+    "Alarm",
+    "Command",
+    "HeltyCloud",
+    "HeltyCloudAuthError",
+    "HeltyCloudConnectionError",
+    "HeltyCloudError",
+    "HeltyCloudNoDataError",
+    "HeltyDevice",
+    "HeltyState",
+    "VmcMode",
+]

pyheltycloud-0.1.0/src/pyheltycloud/auth.py

@@ -0,0 +1,284 @@
+"""AWS Cognito authentication (USER_SRP_AUTH) on aiohttp.
+
+The Helty pool only accepts the SRP flow, so the password never travels:
+knowledge of it is proven by signing a challenge. Implemented here instead
+of using pycognito/boto3 because those libraries are synchronous and Home
+Assistant wants async I/O.
+
+Reference: SRP-6a with Cognito's specifics (key derived via HKDF and HMAC
+signature of the challenge block).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import os
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+import aiohttp
+
+from .exceptions import HeltyCloudAuthError, HeltyCloudConnectionError
+
+# 3072-bit prime and generator, fixed by the Cognito protocol.
+N_HEX = (
+    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74"
+    "020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F1437"
+    "4FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
+    "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3DC2007CB8A163BF05"
+    "98DA48361C55D39A69163FA8FD24CF5F83655D23DCA3AD961C62F356208552BB"
+    "9ED529077096966D670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
+    "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9DE2BCBF695581718"
+    "3995497CEA956AE515D2261898FA051015728E5A8AAAC42DAD33170D04507A33"
+    "A85521ABDF1CBA64ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
+    "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6BF12FFA06D98A0864"
+    "D87602733EC86A64521F2B18177B200CBBE117577A615D6C770988C0BAD946E2"
+    "08E24FA074E5AB3143DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF"
+)
+G_HEX = "2"
+INFO_BITS = b"Caldera Derived Key"
+
+# strftime is locale-dependent: Cognito wants the English names, so we spell
+# them out.
+_WEEKDAYS = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
+_MONTHS = (
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+)
+
+# Renew the token a bit before it expires, to avoid being caught mid-call.
+_EXPIRY_MARGIN = 60.0
+
+# Overall timeout for each call to Cognito.
+_TIMEOUT = aiohttp.ClientTimeout(total=30)
+
+
+def _hash_sha256(buf: bytes | bytearray) -> str:
+    digest = hashlib.sha256(buf).hexdigest()
+    return digest.rjust(64, "0")
+
+
+def _hex_hash(hex_string: str) -> str:
+    return _hash_sha256(bytearray.fromhex(hex_string))
+
+
+def _pad_hex(value: int | str) -> str:
+    """Normalize a hex string the way SRP expects.
+
+    Even length, and a leading zero byte if the first nibble has the high
+    bit set (it would otherwise be read as a negative number).
+    """
+    hex_str = value if isinstance(value, str) else f"{value:x}"
+    if len(hex_str) % 2 == 1:
+        return f"0{hex_str}"
+    if hex_str[0] in "89ABCDEFabcdef":
+        return f"00{hex_str}"
+    return hex_str
+
+
+def _compute_hkdf(ikm: bytes | bytearray, salt: bytes | bytearray) -> bytes:
+    prk = hmac.new(salt, ikm, hashlib.sha256).digest()
+    return hmac.new(prk, INFO_BITS + b"\x01", hashlib.sha256).digest()[:16]
+
+
+def _cognito_timestamp() -> str:
+    now = datetime.now(UTC)
+    return (
+        f"{_WEEKDAYS[now.weekday()]} {_MONTHS[now.month - 1]} {now.day} "
+        f"{now:%H:%M:%S} UTC {now.year}"
+    )
+
+
+@dataclass(slots=True)
+class Tokens:
+    """Cognito session tokens."""
+
+    id_token: str
+    access_token: str
+    refresh_token: str
+    expires_at: float
+
+    @property
+    def expired(self) -> bool:
+        """True when it is time to renew before the next call."""
+        return time.time() >= self.expires_at - _EXPIRY_MARGIN
+
+
+class CognitoSrpAuth:
+    """SRP login and token renewal against a Cognito user pool."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        user_pool_id: str,
+        client_id: str,
+        region: str,
+    ) -> None:
+        """Prepare the fixed SRP parameters of the pool."""
+        self._session = session
+        self._user_pool_id = user_pool_id
+        self._client_id = client_id
+        self._url = f"https://cognito-idp.{region}.amazonaws.com/"
+        self._big_n = int(N_HEX, 16)
+        self._g = int(G_HEX, 16)
+        self._k = int(_hex_hash(f"00{N_HEX}0{G_HEX}"), 16)
+        self._new_ephemeral()
+
+    def _new_ephemeral(self) -> None:
+        """Draw a fresh SRP secret and its public value.
+
+        One per login: reusing the pair across authentications is outside
+        what the protocol assumes of the ephemeral keys.
+        """
+        self._small_a = int(binascii.hexlify(os.urandom(128)), 16) % self._big_n
+        self._big_a = pow(self._g, self._small_a, self._big_n)
+
+    @property
+    def _pool_name(self) -> str:
+        """The pool id without the region prefix (needed in the signature)."""
+        return self._user_pool_id.split("_", 1)[1]
+
+    async def _call(self, target: str, payload: dict[str, Any]) -> dict[str, Any]:
+        headers = {
+            "Content-Type": "application/x-amz-json-1.1",
+            "X-Amz-Target": f"AWSCognitoIdentityProviderService.{target}",
+        }
+        try:
+            async with self._session.post(
+                self._url, headers=headers, json=payload, timeout=_TIMEOUT
+            ) as response:
+                status = response.status
+                text = await response.text()
+        except (TimeoutError, aiohttp.ClientError) as err:
+            raise HeltyCloudConnectionError(f"Cognito is unreachable: {err}") from err
+
+        # A proxy in front of Cognito answers with its own HTML error page,
+        # which json() would blow up on with a ValueError: not one of ours,
+        # and callers only guard against HeltyCloudError.
+        try:
+            body = json.loads(text)
+        except ValueError as err:
+            raise HeltyCloudConnectionError(
+                f"{target}: Cognito answered HTTP {status} with a non-JSON body: {text[:200]}"
+            ) from err
+        if not isinstance(body, dict):
+            raise HeltyCloudConnectionError(f"{target}: unexpected answer {text[:200]}")
+
+        if status != 200:
+            message = body.get("message") or body.get("__type") or str(body)
+            raise HeltyCloudAuthError(f"{target}: {message}")
+        return body
+
+    def _password_key(self, username: str, password: str, srp_b_hex: str, salt_hex: str) -> bytes:
+        big_b = int(srp_b_hex, 16)
+        if big_b % self._big_n == 0:
+            raise HeltyCloudAuthError("Invalid SRP_B returned by Cognito")
+
+        u_value = int(_hex_hash(_pad_hex(self._big_a) + _pad_hex(big_b)), 16)
+        if u_value == 0:
+            raise HeltyCloudAuthError("U parameter is zero in the SRP negotiation")
+
+        id_hash = _hash_sha256(f"{self._pool_name}{username}:{password}".encode())
+        x_value = int(_hex_hash(_pad_hex(salt_hex) + id_hash), 16)
+
+        g_mod_pow_xn = pow(self._g, x_value, self._big_n)
+        base = (big_b - self._k * g_mod_pow_xn) % self._big_n
+        s_value = pow(base, self._small_a + u_value * x_value, self._big_n)
+
+        return _compute_hkdf(
+            bytearray.fromhex(_pad_hex(s_value)),
+            bytearray.fromhex(_pad_hex(f"{u_value:x}")),
+        )
+
+    async def authenticate(self, username: str, password: str) -> Tokens:
+        """Run the full SRP login."""
+        self._new_ephemeral()
+        init = await self._call(
+            "InitiateAuth",
+            {
+                "AuthFlow": "USER_SRP_AUTH",
+                "ClientId": self._client_id,
+                "AuthParameters": {
+                    "USERNAME": username,
+                    "SRP_A": f"{self._big_a:x}",
+                },
+            },
+        )
+        challenge = init.get("ChallengeParameters", {})
+        if init.get("ChallengeName") != "PASSWORD_VERIFIER":
+            raise HeltyCloudAuthError(
+                f"Unexpected challenge from Cognito: {init.get('ChallengeName')}"
+            )
+
+        # Cognito may answer with an internal identifier different from the
+        # one we logged in with: from here on, that one must be used.
+        user_id = challenge["USER_ID_FOR_SRP"]
+        secret_block = challenge["SECRET_BLOCK"]
+        timestamp = _cognito_timestamp()
+
+        hkdf = self._password_key(user_id, password, challenge["SRP_B"], challenge["SALT"])
+        message = (
+            self._pool_name.encode()
+            + user_id.encode()
+            + base64.standard_b64decode(secret_block)
+            + timestamp.encode()
+        )
+        signature = base64.standard_b64encode(
+            hmac.new(hkdf, message, hashlib.sha256).digest()
+        ).decode()
+
+        result = await self._call(
+            "RespondToAuthChallenge",
+            {
+                "ChallengeName": "PASSWORD_VERIFIER",
+                "ClientId": self._client_id,
+                "ChallengeResponses": {
+                    "USERNAME": user_id,
+                    "TIMESTAMP": timestamp,
+                    "PASSWORD_CLAIM_SECRET_BLOCK": secret_block,
+                    "PASSWORD_CLAIM_SIGNATURE": signature,
+                },
+            },
+        )
+        return self._tokens_from(result)
+
+    async def refresh(self, refresh_token: str) -> Tokens:
+        """Renew the tokens without redoing the whole SRP dance."""
+        result = await self._call(
+            "InitiateAuth",
+            {
+                "AuthFlow": "REFRESH_TOKEN_AUTH",
+                "ClientId": self._client_id,
+                "AuthParameters": {"REFRESH_TOKEN": refresh_token},
+            },
+        )
+        # The refresh response does not repeat the refresh token: reuse it.
+        return self._tokens_from(result, refresh_token=refresh_token)
+
+    @staticmethod
+    def _tokens_from(payload: dict[str, Any], refresh_token: str = "") -> Tokens:
+        auth = payload.get("AuthenticationResult")
+        if not auth:
+            raise HeltyCloudAuthError("Cognito did not return the tokens")
+        return Tokens(
+            id_token=auth["IdToken"],
+            access_token=auth["AccessToken"],
+            refresh_token=auth.get("RefreshToken", refresh_token),
+            expires_at=time.time() + auth.get("ExpiresIn", 3600),
+        )