pyheltycloud 0.1.0__py3-none-any.whl

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/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),
+        )

pyheltycloud/client.py

@@ -0,0 +1,304 @@
+"""Async client for the Helty cloud (hcloud)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from types import TracebackType
+from typing import Any, Self
+
+import aiohttp
+
+from .auth import CognitoSrpAuth, Tokens
+from .const import (
+    API_BASE,
+    CLIENT_ID,
+    EP_COMMAND_LOGS,
+    EP_INSTALLATIONS,
+    EP_LAST_STATUS,
+    EP_SEND_COMMAND,
+    MODE_COMMANDS,
+    REGION,
+    USER_POOL_ID,
+    Command,
+    VmcMode,
+)
+from .exceptions import (
+    HeltyCloudAuthError,
+    HeltyCloudConnectionError,
+    HeltyCloudError,
+    HeltyCloudNoDataError,
+)
+from .models import HeltyDevice, HeltyState, is_telemetry
+
+_LOGGER = logging.getLogger(__name__)
+
+#: Overall timeout for each HTTP call to the API.
+TIMEOUT = aiohttp.ClientTimeout(total=15)
+
+#: How often to re-check the history while waiting for the board to answer.
+REFRESH_POLL_INTERVAL = 2.0
+
+#: How long to wait overall for the board to answer before falling back to
+#: the last available data.
+REFRESH_TIMEOUT = 15.0
+
+#: History search window when reading raw telemetry. Measured on 5334
+#: spontaneous reports: the board reports every 5.5 minutes at the median
+#: and every 33 at the 99th percentile, so two hours is wide enough to
+#: always find something without asking the cloud to scan a long window.
+DEFAULT_HISTORY_HOURS = 2
+
+#: Rows to ask for. Only the newest is used; a few spare ones cover the
+#: acks and other commands that share the history.
+HISTORY_PAGE_SIZE = 5
+
+
+class HeltyCloud:
+    """Session towards api.hcloud.heltyair.com.
+
+    The cloud keeps no device state: it returns the last message received
+    from the board, which pushes over its own AWS IoT connection. To get
+    current data the board must be asked to report (refresh()), otherwise
+    you read whatever is there.
+    """
+
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        """Without a session the client creates and closes its own.
+
+        The owned session is created on the first request, not here: aiohttp
+        needs a running event loop to create one.
+        """
+        self._email = email
+        self._password = password
+        self._session = session
+        self._owns_session = session is None
+        self._auth = (
+            None if session is None else CognitoSrpAuth(session, USER_POOL_ID, CLIENT_ID, REGION)
+        )
+        self._tokens: Tokens | None = None
+        self._lock = asyncio.Lock()
+
+    def _ensure_started(self) -> tuple[aiohttp.ClientSession, CognitoSrpAuth]:
+        """Session and auth, created lazily inside the current event loop."""
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        if self._auth is None:
+            self._auth = CognitoSrpAuth(self._session, USER_POOL_ID, CLIENT_ID, REGION)
+        return self._session, self._auth
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Exit the context, closing the session."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the HTTP session, if we created it ourselves."""
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+
+    # -- authentication ----------------------------------------------------
+
+    async def login(self) -> None:
+        """Authenticate and store the tokens. Useful to validate credentials."""
+        _, auth = self._ensure_started()
+        self._tokens = await auth.authenticate(self._email, self._password)
+
+    async def _id_token(self) -> str:
+        """Return a valid token, renewing it or logging in again if needed."""
+        _, auth = self._ensure_started()
+        async with self._lock:
+            if self._tokens is None:
+                self._tokens = await auth.authenticate(self._email, self._password)
+            elif self._tokens.expired:
+                try:
+                    self._tokens = await auth.refresh(self._tokens.refresh_token)
+                except HeltyCloudAuthError:
+                    # The refresh token expired or was revoked: start over.
+                    _LOGGER.debug("Refresh failed, retrying the full SRP login")
+                    self._tokens = await auth.authenticate(self._email, self._password)
+            return self._tokens.id_token
+
+    # -- transport ---------------------------------------------------------
+
+    async def _post(self, path: str, payload: dict[str, Any], *, allow_404: bool = False) -> Any:
+        session, _ = self._ensure_started()
+        headers = {
+            # The API validates the ID token: the access token gets a 401.
+            "Authorization": f"Bearer {await self._id_token()}",
+            "Accept": "application/json",
+        }
+        try:
+            async with session.post(
+                API_BASE + path, headers=headers, json=payload, timeout=TIMEOUT
+            ) as response:
+                status = response.status
+                text = await response.text()
+        except (TimeoutError, aiohttp.ClientError) as err:
+            raise HeltyCloudConnectionError(f"{path}: {err}") from err
+
+        if status == 401:
+            raise HeltyCloudAuthError(text)
+        if status == 404 and allow_404:
+            return None
+        if status >= 400:
+            raise HeltyCloudError(f"HTTP {status} on {path}: {text[:200]}")
+
+        # nginx sits in front of the API and answers with its own HTML pages,
+        # so a 200 is not a promise of JSON. Parsing here keeps a ValueError
+        # from escaping past the exceptions this library documents.
+        try:
+            return json.loads(text)
+        except ValueError as err:
+            raise HeltyCloudConnectionError(
+                f"{path}: the cloud answered HTTP {status} with a non-JSON body: {text[:200]}"
+            ) from err
+
+    # -- reading -----------------------------------------------------------
+
+    async def get_devices(self) -> list[HeltyDevice]:
+        """List the VMC units associated with the account."""
+        data = await self._post(EP_INSTALLATIONS, {})
+        return [HeltyDevice.from_json(item) for item in data]
+
+    async def get_state(self, serial_number: str) -> HeltyState:
+        """Last known state, from the fields already normalized by the cloud.
+
+        Raises HeltyCloudNoDataError if the board has not reported for over
+        an hour: in that case use refresh() or get_last_telemetry().
+        """
+        rows = await self._post(EP_LAST_STATUS, {"serialNumber": serial_number}, allow_404=True)
+        if rows is None:
+            raise HeltyCloudNoDataError(f"No recent telemetry for {serial_number}")
+        return HeltyState.from_last_status(rows)
+
+    async def get_last_telemetry(
+        self, serial_number: str, hours: int = DEFAULT_HISTORY_HOURS
+    ) -> HeltyState:
+        """Last state from the raw history: includes fans and alarms."""
+        now = int(time.time() * 1000)
+        page = await self._post(
+            EP_COMMAND_LOGS,
+            {
+                "serialNumber": serial_number,
+                "pageSize": HISTORY_PAGE_SIZE,
+                "pageNumber": 0,
+                "fromTs": now - hours * 3600 * 1000,
+                "toTs": now,
+            },
+        )
+        rows = [
+            row
+            for row in page.get("data", [])
+            if row.get("commandId") == Command.GET_STATUS and is_telemetry(row.get("data") or [])
+        ]
+        if not rows:
+            raise HeltyCloudNoDataError(
+                f"No telemetry for {serial_number} in the last {hours} hours"
+            )
+        # The cloud happens to return the newest first, but nothing documents
+        # it, and update() decides whether the board answered by comparing
+        # timestamps: pick the newest explicitly.
+        newest = max(rows, key=lambda row: row.get("timestamp") or 0)
+        return HeltyState.from_telemetry(newest["data"], newest.get("timestamp"))
+
+    async def update(self, device: HeltyDevice) -> HeltyState:
+        """Fetch the current state: ask the board to report, then read.
+
+        This is the method to use for polling. It waits for a telemetry
+        newer than the one already known (up to REFRESH_TIMEOUT seconds);
+        if the board does not answer it falls back to the last available
+        data, and raises HeltyCloudNoDataError only if there is nothing
+        to read at all.
+        """
+        try:
+            last = await self.get_last_telemetry(device.serial_number)
+        except HeltyCloudNoDataError:
+            last = None
+
+        await self.refresh(device.board_serial)
+
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + REFRESH_TIMEOUT
+        while loop.time() < deadline:
+            await asyncio.sleep(REFRESH_POLL_INTERVAL)
+            try:
+                state = await self.get_last_telemetry(device.serial_number)
+            except HeltyCloudNoDataError:
+                continue
+            if last is None or (state.timestamp or 0) > (last.timestamp or 0):
+                return state
+
+        if last is not None:
+            _LOGGER.debug(
+                "Board %s did not answer the refresh: using the last known data",
+                device.serial_number,
+            )
+            return last
+        raise HeltyCloudNoDataError(
+            f"No telemetry for {device.serial_number}, even after a refresh"
+        )
+
+    # -- writing -----------------------------------------------------------
+
+    async def send_command(self, board_serial: str, command: Command) -> None:
+        """Send an argument-less command to the board.
+
+        The cloud answers 200 as soon as it takes the command, before the
+        board has acted on it, and the answer says nothing about delivery.
+        Callers who need certainty should read the state back.
+
+        Commands that carry an argument are not supported: "values" has to
+        hold objects with "id" and "value" (the keys are in the app's own
+        code), but every combination tried against the live API was refused
+        with 400 "Malformed Command". The vendor places the only argument we
+        went looking for, the brightness level, on the lights of the Elite
+        version, so there may be nothing here to support on a FlowPLUS.
+        """
+        body: dict[str, Any] = {"commandId": int(command), "values": []}
+        await self._post(EP_SEND_COMMAND.format(board_serial=board_serial), body)
+
+    async def refresh(self, board_serial: str) -> None:
+        """Ask the board to report its state right away."""
+        await self.send_command(board_serial, Command.GET_STATUS)
+
+    async def set_mode(self, board_serial: str, mode: VmcMode) -> None:
+        """Set the VMC mode. Single send, no verification."""
+        await self.send_command(board_serial, MODE_COMMANDS[mode])
+
+    async def set_mode_verified(
+        self, device: HeltyDevice, mode: VmcMode, attempts: int = 3
+    ) -> HeltyState:
+        """set_mode() with verification: re-read the state and resend if lost.
+
+        Returns the state reflecting the requested mode. Raises
+        HeltyCloudError if after `attempts` sends the VMC has not applied it.
+        """
+        for attempt in range(1, attempts + 1):
+            await self.set_mode(device.board_serial, mode)
+            state = await self.update(device)
+            if state.mode is mode:
+                return state
+            _LOGGER.debug(
+                "Command %s not applied by %s (attempt %d/%d)",
+                mode.name,
+                device.serial_number,
+                attempt,
+                attempts,
+            )
+        raise HeltyCloudError(f"The VMC did not apply mode {mode.name} after {attempts} attempts")

pyheltycloud/const.py

@@ -0,0 +1,180 @@
+"""Constants of the Helty cloud (hcloud).
+
+Extracted from the "Helty Home" app 1.2.2 (Flutter + AWS Amplify) and
+verified against the real API. No official documentation exists.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum, IntFlag
+
+USER_POOL_ID = "eu-central-1_lejYSlqKZ"
+CLIENT_ID = "7k0c21g92bk3413frij8rso6rk"
+REGION = "eu-central-1"
+API_BASE = "https://api.hcloud.heltyair.com"
+
+EP_INSTALLATIONS = "/board/installation/all"
+EP_LAST_STATUS = "/log/commandlogs/laststatus"
+EP_COMMAND_LOGS = "/log/commandlogs/search"
+# The service prefix is doubled (like /user/user/...), and the parameter is
+# the serial of the BOARD, not the one of the VMC.
+EP_SEND_COMMAND = "/board/board/sendcommand/{board_serial}"
+
+# Physical quantities arrive multiplied by 10, as on the local protocol.
+SCALE = 10
+
+
+class VmcMode(IntEnum):
+    """VMC mode: same enum as the local protocol (port 5001)."""
+
+    OFF = 0
+    SPEED_1 = 1
+    SPEED_2 = 2
+    SPEED_3 = 3
+    SPEED_4 = 4
+    HYPERVENTILATION = 5
+    NIGHT = 6
+    FREE_COOLING = 7
+
+
+class Alarm(IntFlag):
+    """Bits of the alarm bitmap, from the table the vendor supplied.
+
+    The table stops at bit 8; every higher bit is undocumented. IntFlag
+    keeps unknown bits rather than rejecting them, so the raw value stays
+    readable through the flags.
+    """
+
+    ICE_RISK = 0x001
+    #: The vendor lists two humidity alarms (codes 7 and 8) and gives both
+    #: the same description, without saying what tells them apart.
+    HUMIDITY_1 = 0x002
+    HUMIDITY_2 = 0x004
+    TEMPERATURE_DELTA = 0x008
+    CO2_OVER_LIMIT = 0x010
+    FILTER = 0x020
+    #: Code 12 in the vendor's table, whose description column is empty.
+    UNDOCUMENTED_12 = 0x040
+    #: Not a fault: the machine reports that it went into free cooling by
+    #: itself. It sits in the alarm bitmap all the same.
+    FREE_COOLING_AUTO = 0x080
+    VOC_OVER_LIMIT = 0x100
+
+
+#: Bits that mean something is wrong. Free cooling is a state, not a fault,
+#: and the undocumented bits are left out on purpose: the only one ever seen
+#: on a real unit, 0x0000000C00000000, lasted two seconds while the fans were
+#: spinning up, so treating unknown bits as faults would fire a notification
+#: at every start.
+FAULT_MASK = (
+    Alarm.ICE_RISK
+    | Alarm.HUMIDITY_1
+    | Alarm.HUMIDITY_2
+    | Alarm.TEMPERATURE_DELTA
+    | Alarm.CO2_OVER_LIMIT
+    | Alarm.FILTER
+    | Alarm.VOC_OVER_LIMIT
+)
+
+
+class Command(IntEnum):
+    """commandId values accepted by EP_SEND_COMMAND.
+
+    Derived by watching the command log while operating the app: verified
+    by observation, not documented.
+    """
+
+    GET_STATUS = 0
+    GET_INFO = 1
+    OFF = 20
+    FREE_COOLING = 21
+    NIGHT = 22
+    HYPERVENTILATION = 23
+    SPEED_STEP_UP = 24
+    GET_PARAMETERS = 33
+    # Zeroes the partial filter counter after a filter change. Given by the
+    # vendor, who is not certain of it either ("dovrebbe essere il 37"), and
+    # never sent: trying it would destroy the only record of how old the
+    # filter is.
+    RESET_FILTER = 37
+    # The "Auto" toggle of the app ("auto_group" in its command switch).
+    # Write only: the vendor confirmed the commands take effect but that the
+    # setting cannot be read back from anywhere, which is why the app shows
+    # its own local idea of the toggle. In Auto the unit picks the speed from
+    # its humidity, VOC and CO2 sensors, but only while the outdoor
+    # temperature is at least 5 °C below the indoor one and indoor humidity
+    # is above 65%, so on a unit with humidity only nothing happens in summer.
+    AUTO_ON = 38
+    AUTO_OFF = 39
+    # Verified live: 40 switches the whole panel off, display and speed LEDs
+    # together, and 41 switches it back on. Neither takes an argument, and
+    # nothing in the telemetry reflects which of the two is in force.
+    PANEL_OFF = 40
+    PANEL_ON = 41
+    SPEED_1 = 44
+    SPEED_2 = 45
+    SPEED_3 = 46
+    SPEED_4 = 47
+    # Answers with [level]. The vendor says the level belongs to the lights
+    # of the Elite version, not to this panel, which would explain why it
+    # reads 100 whether the panel is lit or dark.
+    GET_PANEL_LEVEL = 48
+
+
+#: Command that sets each mode. All modes are covered.
+MODE_COMMANDS: dict[VmcMode, Command] = {
+    VmcMode.OFF: Command.OFF,
+    VmcMode.SPEED_1: Command.SPEED_1,
+    VmcMode.SPEED_2: Command.SPEED_2,
+    VmcMode.SPEED_3: Command.SPEED_3,
+    VmcMode.SPEED_4: Command.SPEED_4,
+    VmcMode.HYPERVENTILATION: Command.HYPERVENTILATION,
+    VmcMode.NIGHT: Command.NIGHT,
+    VmcMode.FREE_COOLING: Command.FREE_COOLING,
+}
+
+# Positions in the telemetry payload of Command.GET_STATUS.
+IDX_ALARMS = 0
+IDX_MODE = 1
+IDX_TEMP_INDOOR = 2
+IDX_TEMP_OUTDOOR = 3
+IDX_FAN_SUPPLY = 4
+IDX_FAN_EXHAUST = 5
+IDX_HUMIDITY = 10
+TELEMETRY_MIN_LEN = IDX_HUMIDITY + 1
+
+# Optional sensors, absent on most units: they read 0 when not installed.
+# The vendor calls them "A: anidride CO2" and "I: isobutene VOC" and gives
+# no unit, and this panel has neither, so the values are passed on as they
+# arrive rather than scaled on a guess.
+IDX_CO2 = 14
+IDX_VOC = 15
+SENSOR_MIN_LEN = IDX_VOC + 1
+
+# The two counters of treated air. The vendor confirmed that 16 is the
+# partial one, zeroed by the filter reset, and that 18 is the lifetime one:
+# their difference is constant and is what the machine had treated when the
+# filter was last changed.
+IDX_FILTER_PARTIAL = 16
+IDX_FILTER_TOTAL = 18
+FILTER_MIN_LEN = IDX_FILTER_TOTAL + 1
+
+#: Cubic metres per count. The vendor wrote "10e-1 mc", but the measured
+#: rates only make sense at ten: over 475 hours at speed 1 the counter grew
+#: 0.73 per hour, that is 7.3 m3/h, while a tenth of a cubic metre per count
+#: would mean 0.073 m3/h out of a machine rated for tens.
+FILTER_M3_PER_COUNT = 10
+
+#: Cubic metres after which the panel shows the filter alarm. The vendor
+#: gives this for the current firmware and warns that it can change with
+#: later ones, and it is in none of the 27 values of GET_PARAMETERS: it is a
+#: default to start from, not a reading.
+FILTER_ALARM_M3 = 90_000
+
+# EP_LAST_STATUS fields and the corresponding HeltyState attribute.
+LAST_STATUS_MAP = {
+    "VMCStatus": "mode",
+    "TemperaturaInterna": "temperature_indoor",
+    "TemperaturaEsterna": "temperature_outdoor",
+    "Humidity": "humidity",
+}

pyheltycloud/exceptions.py

@@ -0,0 +1,24 @@
+"""Exceptions of pyheltycloud."""
+
+from __future__ import annotations
+
+
+class HeltyCloudError(Exception):
+    """Generic Helty cloud error."""
+
+
+class HeltyCloudAuthError(HeltyCloudError):
+    """Credentials rejected, or session no longer renewable."""
+
+
+class HeltyCloudConnectionError(HeltyCloudError):
+    """The cloud is unreachable or misbehaved."""
+
+
+class HeltyCloudNoDataError(HeltyCloudError):
+    """The panel has not sent telemetry recently.
+
+    The cloud keeps no state: it only answers with the last message it
+    received from the board. If the board has been silent for a while there
+    is nothing to read until it is asked to report (see HeltyCloud.refresh).
+    """

pyheltycloud/models.py

@@ -0,0 +1,214 @@
+"""Data models of pyheltycloud."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .const import (
+    FAULT_MASK,
+    FILTER_M3_PER_COUNT,
+    FILTER_MIN_LEN,
+    IDX_ALARMS,
+    IDX_CO2,
+    IDX_FAN_EXHAUST,
+    IDX_FAN_SUPPLY,
+    IDX_FILTER_PARTIAL,
+    IDX_FILTER_TOTAL,
+    IDX_HUMIDITY,
+    IDX_MODE,
+    IDX_TEMP_INDOOR,
+    IDX_TEMP_OUTDOOR,
+    IDX_VOC,
+    LAST_STATUS_MAP,
+    SCALE,
+    SENSOR_MIN_LEN,
+    TELEMETRY_MIN_LEN,
+    Alarm,
+    VmcMode,
+)
+from .exceptions import HeltyCloudError, HeltyCloudNoDataError
+
+#: Value the cloud uses when an optional sensor is not installed.
+NO_SENSOR = 0
+
+
+@dataclass(slots=True)
+class HeltyDevice:
+    """A VMC unit as the cloud knows it."""
+
+    serial_number: str
+    """Serial of the machine: identifies the device in reads."""
+
+    board_serial: str
+    """Serial of the board (= MAC of the panel): needed to send commands."""
+
+    name: str
+    model: str
+    firmware: str
+    raw: dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> HeltyDevice:
+        """Build the device from the EP_INSTALLATIONS response."""
+        board = data.get("cloudBoard") or {}
+        installation = data.get("currentInstallation") or {}
+        product = data.get("productType") or {}
+        serial = data["serialNumber"]
+        return cls(
+            serial_number=serial,
+            board_serial=data.get("boardSerialNumber") or board.get("serialNumber", ""),
+            name=installation.get("name") or serial,
+            model=product.get("model", ""),
+            firmware=board.get("firmware", ""),
+            raw=data,
+        )
+
+
+@dataclass(slots=True)
+class HeltyState:
+    """State of the VMC at a point in time."""
+
+    mode: VmcMode
+    temperature_indoor: float | None = None
+    temperature_outdoor: float | None = None
+    humidity: float | None = None
+    fan_supply: int | None = None
+    """Supply fan percentage (only from raw telemetry)."""
+
+    fan_exhaust: int | None = None
+    """Exhaust fan percentage (only from raw telemetry)."""
+
+    alarms: str | None = None
+    """Hex alarm bitmap; "0000000000000000" means no alarms."""
+
+    co2: int | None = None
+    """CO2 reading, None when the sensor is not installed. Unit unknown."""
+
+    voc: int | None = None
+    """VOC reading, None when the sensor is not installed. Unit unknown."""
+
+    filter_partial_m3: int | None = None
+    """Cubic metres treated since the last filter reset."""
+
+    filter_total_m3: int | None = None
+    """Cubic metres treated over the life of the machine."""
+
+    timestamp: int | None = None
+    """Epoch milliseconds of the message this state derives from."""
+
+    @property
+    def is_on(self) -> bool:
+        """True when the machine is ventilating, in any mode."""
+        return self.mode is not VmcMode.OFF
+
+    @property
+    def alarm_flags(self) -> Alarm | None:
+        """Decode the alarm bitmap, or None when there is no raw telemetry."""
+        if not self.alarms:
+            return None
+        try:
+            return Alarm(int(self.alarms, 16))
+        except ValueError:
+            return None
+
+    @property
+    def has_alarm(self) -> bool:
+        """True when the machine reports a fault.
+
+        Only the documented fault bits count: free cooling reports itself in
+        the same bitmap without anything being wrong, and the undocumented
+        bits carry at least one start-up transient.
+        """
+        flags = self.alarm_flags
+        return flags is not None and bool(flags & FAULT_MASK)
+
+    @classmethod
+    def from_last_status(cls, rows: list[dict[str, Any]]) -> HeltyState:
+        """Build the state from the EP_LAST_STATUS response.
+
+        Each row is {"field": …, "value": …}; values are scaled integers.
+        Raises HeltyCloudNoDataError when VMCStatus is missing: "no data"
+        must not be mistaken for "machine off".
+        """
+        values: dict[str, float] = {}
+        for row in rows:
+            attribute = LAST_STATUS_MAP.get(row.get("field", ""))
+            if attribute is not None:
+                values[attribute] = row["value"]
+        if "mode" not in values:
+            raise HeltyCloudNoDataError("laststatus response without VMCStatus")
+        return cls(
+            mode=_mode(values["mode"]),
+            temperature_indoor=_scaled(values.get("temperature_indoor")),
+            temperature_outdoor=_scaled(values.get("temperature_outdoor")),
+            humidity=_humidity(values.get("humidity")),
+        )
+
+    @classmethod
+    def from_telemetry(cls, data: list[Any], timestamp: int | None = None) -> HeltyState:
+        """Build the state from the raw Command.GET_STATUS payload.
+
+        Richer than from_last_status(): adds fans and alarms.
+        """
+        return cls(
+            mode=_mode(data[IDX_MODE]),
+            temperature_indoor=_scaled(data[IDX_TEMP_INDOOR]),
+            temperature_outdoor=_scaled(data[IDX_TEMP_OUTDOOR]),
+            humidity=_humidity(data[IDX_HUMIDITY]),
+            fan_supply=int(data[IDX_FAN_SUPPLY]),
+            fan_exhaust=int(data[IDX_FAN_EXHAUST]),
+            alarms=str(data[IDX_ALARMS]),
+            timestamp=timestamp,
+            co2=_optional(data, IDX_CO2, SENSOR_MIN_LEN),
+            voc=_optional(data, IDX_VOC, SENSOR_MIN_LEN),
+            filter_partial_m3=_counter(data, IDX_FILTER_PARTIAL),
+            filter_total_m3=_counter(data, IDX_FILTER_TOTAL),
+        )
+
+
+def is_telemetry(data: list[Any]) -> bool:
+    """Return True when the payload is a full telemetry and not an empty ack."""
+    return len(data) >= TELEMETRY_MIN_LEN
+
+
+def _optional(data: list[Any], index: int, min_len: int) -> int | None:
+    """Read a field that may be absent, or zero because it is not installed.
+
+    Short payloads do not carry it, and a zero is not trusted: for the first
+    day it was online this panel returned telemetry with a whole block of
+    fields zeroed while the machine was running.
+    """
+    if len(data) < min_len or not data[index]:
+        return None
+    return int(data[index])
+
+
+def _counter(data: list[Any], index: int) -> int | None:
+    """Read a filter counter and convert it to cubic metres."""
+    counts = _optional(data, index, FILTER_MIN_LEN)
+    return None if counts is None else counts * FILTER_M3_PER_COUNT
+
+
+def _mode(value: Any) -> VmcMode:
+    """Decode the mode, refusing to guess at a value we do not know.
+
+    The vendor has no way of warning us before the API changes, so a mode
+    added by a future firmware must surface as a cloud error the caller
+    already handles, not as a ValueError out of a dataclass.
+    """
+    try:
+        return VmcMode(int(value))
+    except ValueError as err:
+        raise HeltyCloudError(f"Unknown VMC mode {value!r}") from err
+
+
+def _scaled(value: float | None) -> float | None:
+    return None if value is None else value / SCALE
+
+
+def _humidity(value: float | None) -> float | None:
+    """Like _scaled, but 0 becomes None: 0% is not a real humidity."""
+    if value is None or value == NO_SENSOR:
+        return None
+    return value / SCALE

pyheltycloud-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,12 @@
+pyheltycloud/__init__.py,sha256=soLNiIrzmIsgf7G66GEG__E4oxlAl_ztkAJKlLfJ4oY,549
+pyheltycloud/auth.py,sha256=HBhJRV-xkema-5btF1itjGTAzwbNQh1jkM1HL69Bezg,10130
+pyheltycloud/client.py,sha256=n5e2llqor_45wMn4MVblwenAUBw2BAMFFHUm_G5Yb_U,11962
+pyheltycloud/const.py,sha256=5incKG14-oLJYMtfYHRDsInUMqX6NsI-O4LxQXAZ__o,6289
+pyheltycloud/exceptions.py,sha256=nyhzPgbN2PhzB9OaaiDMXsxfBagjrHqi3_lHOxwtcZY,686
+pyheltycloud/models.py,sha256=rSLCYVLFJtpwBgGf2j_4DvythO_rup3_esci4teDmrQ,7152
+pyheltycloud/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyheltycloud-0.1.0.dist-info/licenses/LICENSE,sha256=32Lok91VHOSzOcH_3yzT7o-OybwTYMAxHqyBzZZNh_8,1074
+pyheltycloud-0.1.0.dist-info/METADATA,sha256=wdevyfVd5lhCMuQyY7vk8dCD8V6WeCRMYMqzIkl3IV0,4854
+pyheltycloud-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyheltycloud-0.1.0.dist-info/top_level.txt,sha256=MODR7Lrix1kgpeerR0hil7NyujOh2wgEHiiW7RVjcE4,13
+pyheltycloud-0.1.0.dist-info/RECORD,,

pyheltycloud-0.1.0.dist-info/WHEEL

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

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

pyheltycloud-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyheltycloud