homesmartlink 0.1.0__tar.gz

homesmartlink-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Raw traffic captures and secrets: never commit
+captures/
+*.har
+.mitmproxy/
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build output
+dist/

homesmartlink-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michaël Fery
+
+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.

homesmartlink-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: homesmartlink
+Version: 0.1.0
+Summary: Async client for the Home-SmartLink (Carrera) heating cloud API
+Project-URL: Source, https://github.com/michaelfery/home-smartlink-ha
+Author-email: Michaël Fery <fery.michael@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.10
+Description-Content-Type: text/markdown
+
+# Home-SmartLink for Home Assistant
+
+Custom integration for **Carrera Home-SmartLink** pilot-wire thermostats (fil pilote
+adapters for electric heaters), through the Home-SmartLink cloud used by the mobile app.
+
+```text
+thermostats ──(BLE mesh)── Home-SmartLink box ──(Wi-Fi)── Home-SmartLink cloud ── Home Assistant
+```
+
+> [!WARNING]
+> **Unofficial.** Not affiliated with or endorsed by Carrera or Texas de France. The cloud
+> API is undocumented. It was reverse-engineered from the Android app (see
+> [docs/API.md](docs/API.md)) and may change without notice.
+
+This repository contains two parts:
+
+- [`custom_components/home_smartlink`](custom_components/home_smartlink): the Home Assistant
+  integration (installable with HACS);
+- [`homesmartlink`](homesmartlink): an async Python client for the cloud API, with no Home
+  Assistant dependency, published on PyPI.
+
+## Features
+
+For each room with a thermostat:
+
+| Entity | Content |
+|---|---|
+| `climate.<room>_thermostat` | Mode, presets, target temperature, measured temperature |
+| `sensor.<room>_thermostat_temperature` | Measured temperature |
+
+For the box (diagnostic entities): last connection to the cloud, and time of the last
+thermostat status update.
+
+### Modes
+
+| Home Assistant | Home-SmartLink app |
+|---|---|
+| `heat` | Manual (**M**) at the target temperature |
+| `auto` | Program (clock), the weekly program set in the app |
+| `off` | Stop (power button) |
+| preset `comfort` | Manual at the room's comfort temperature (sun button) |
+| preset `eco` | Manual at the room's eco temperature (moon button) |
+| preset `away` | Antifreeze (snowflake) |
+
+Target temperature: 13.5 to 30 °C, in 0.5 °C steps (the app's range). Setting a temperature
+switches the room to Manual, like the app's dial.
+
+## Requirements
+
+- Home Assistant **2026.10** or later.
+- A Home-SmartLink box connected to the cloud, and the e-mail and password of the mobile app.
+
+## Installation
+
+### HACS (recommended)
+
+1. HACS → ⋮ → **Custom repositories** → add `https://github.com/michaelfery/home-smartlink-ha`,
+   category **Integration**.
+2. Install **Home-SmartLink**, then restart Home Assistant.
+
+### Manual
+
+Copy `custom_components/home_smartlink` into the `custom_components` folder of your Home
+Assistant configuration, then restart Home Assistant.
+
+## Configuration
+
+**Settings → Devices & services → Add integration → Home-SmartLink**, then sign in with the
+app's e-mail and password. If the account has access to several homes, choose one; add the
+integration again for each other home.
+
+Options (**Configure** on the integration):
+
+| Option | Default | Range | Effect |
+|---|---|---|---|
+| Polling interval | 60 s | 30–3600 s | How often modes and set points are read from the cloud |
+| Diagnosis interval | 15 min | 0 (off), 5–120 min | How often the box is asked to poll the thermostats, which refreshes measured temperatures |
+
+If the password changes, Home Assistant asks you to sign in again (re-authentication).
+
+## How data is refreshed
+
+- **Modes and set points** are read from the cloud at every poll. Commands are shown
+  immediately, then confirmed by a refresh.
+- **Measured temperatures** are only reported by the thermostats during a *diagnosis*.
+  The app runs one each time it opens. The integration runs one at start-up and then at the
+  diagnosis interval. Results arrive about 1–2 minutes after the request, so a measured
+  temperature can be up to the diagnosis interval (+2 min) old. The
+  *Thermostat status update* sensor shows when it was collected.
+- When the cloud cannot be reached, polling backs off (doubling, up to 10 minutes) and
+  returns to normal at the first success.
+
+## Known limitations
+
+- **Cloud only.** No local control: the box and thermostats are only reachable through
+  the vendor cloud.
+- **No refresh token.** The API has none, so the integration stores your app password in
+  the Home Assistant configuration and signs in again when the session expires.
+- **Measured temperatures are not live** (see above).
+- **Whole-document writes.** Each command saves the whole home document (that is what the
+  app does). A change made in the app at the same moment can be overwritten.
+- **In `auto`, the target temperature is not shown.** The API does not say which program
+  slot (comfort/eco) is active.
+- **Antifreeze temperature is not shown.** The device value is not exposed.
+- **Not supported:** editing the weekly program, eco/comfort temperatures, vacation mode,
+  geofencing, ecopilot, open-window detection, consumption counters. Use the app for these.
+- Program mode on a room relies on a frame rule checked on 3 rooms
+  ([docs/API.md](docs/API.md) §5.1). Rooms with more than 9 program events are refused
+  rather than guessed.
+- Error responses of the cloud (wrong password, expired session, box offline) were never
+  observed. They are handled generically.
+
+## Privacy and security
+
+- Credentials are stored in the Home Assistant config entry (like any cloud integration).
+  They are only sent to the Home-SmartLink cloud.
+- Neither the password nor the session token is ever logged.
+- Raw traffic captures used to study the API are never committed. Test fixtures are
+  anonymized, and a test fails if one contains personal data.
+
+## Python library
+
+```python
+import aiohttp
+from homesmartlink import HeaterMode, HomeSmartLinkClient
+
+async with aiohttp.ClientSession() as session:
+    client = HomeSmartLinkClient(session, "email", "password")
+    home_id = (await client.login())[0].home_id
+    home = await client.get_home(home_id)
+    status = await client.get_device_status(home_id)  # measured temperatures
+    await client.set_room_state(home_id, room_number=0, mode=HeaterMode.MANUAL, manual_value=19.5)
+```
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/). Home Assistant 2026.10 needs Python 3.14.
+
+```bash
+uv sync --all-groups
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run pytest                              # client tests
+uv run pytest -o addopts= tests/components # integration tests (Home Assistant plugin)
+```
+
+Fixtures in `tests/fixtures/` are generated from local captures (kept out of git) with
+`scripts/build_fixtures.py`, which anonymizes them and refuses to write if anything leaks.
+`scripts/har_extract.py` turns captures into readable, anonymized JSON for analysis.
+
+### Release
+
+1. Bump the version in `pyproject.toml`, `homesmartlink/__init__.py` and
+   `custom_components/home_smartlink/manifest.json` (version and requirement).
+2. Tag `vX.Y.Z` and push the tag. The release workflow checks the versions and publishes
+   `homesmartlink` to PyPI (Trusted Publishing).
+3. Create a GitHub release for HACS.
+
+## License
+
+[MIT](LICENSE)

homesmartlink-0.1.0/README.md

@@ -0,0 +1,160 @@
+# Home-SmartLink for Home Assistant
+
+Custom integration for **Carrera Home-SmartLink** pilot-wire thermostats (fil pilote
+adapters for electric heaters), through the Home-SmartLink cloud used by the mobile app.
+
+```text
+thermostats ──(BLE mesh)── Home-SmartLink box ──(Wi-Fi)── Home-SmartLink cloud ── Home Assistant
+```
+
+> [!WARNING]
+> **Unofficial.** Not affiliated with or endorsed by Carrera or Texas de France. The cloud
+> API is undocumented. It was reverse-engineered from the Android app (see
+> [docs/API.md](docs/API.md)) and may change without notice.
+
+This repository contains two parts:
+
+- [`custom_components/home_smartlink`](custom_components/home_smartlink): the Home Assistant
+  integration (installable with HACS);
+- [`homesmartlink`](homesmartlink): an async Python client for the cloud API, with no Home
+  Assistant dependency, published on PyPI.
+
+## Features
+
+For each room with a thermostat:
+
+| Entity | Content |
+|---|---|
+| `climate.<room>_thermostat` | Mode, presets, target temperature, measured temperature |
+| `sensor.<room>_thermostat_temperature` | Measured temperature |
+
+For the box (diagnostic entities): last connection to the cloud, and time of the last
+thermostat status update.
+
+### Modes
+
+| Home Assistant | Home-SmartLink app |
+|---|---|
+| `heat` | Manual (**M**) at the target temperature |
+| `auto` | Program (clock), the weekly program set in the app |
+| `off` | Stop (power button) |
+| preset `comfort` | Manual at the room's comfort temperature (sun button) |
+| preset `eco` | Manual at the room's eco temperature (moon button) |
+| preset `away` | Antifreeze (snowflake) |
+
+Target temperature: 13.5 to 30 °C, in 0.5 °C steps (the app's range). Setting a temperature
+switches the room to Manual, like the app's dial.
+
+## Requirements
+
+- Home Assistant **2026.10** or later.
+- A Home-SmartLink box connected to the cloud, and the e-mail and password of the mobile app.
+
+## Installation
+
+### HACS (recommended)
+
+1. HACS → ⋮ → **Custom repositories** → add `https://github.com/michaelfery/home-smartlink-ha`,
+   category **Integration**.
+2. Install **Home-SmartLink**, then restart Home Assistant.
+
+### Manual
+
+Copy `custom_components/home_smartlink` into the `custom_components` folder of your Home
+Assistant configuration, then restart Home Assistant.
+
+## Configuration
+
+**Settings → Devices & services → Add integration → Home-SmartLink**, then sign in with the
+app's e-mail and password. If the account has access to several homes, choose one; add the
+integration again for each other home.
+
+Options (**Configure** on the integration):
+
+| Option | Default | Range | Effect |
+|---|---|---|---|
+| Polling interval | 60 s | 30–3600 s | How often modes and set points are read from the cloud |
+| Diagnosis interval | 15 min | 0 (off), 5–120 min | How often the box is asked to poll the thermostats, which refreshes measured temperatures |
+
+If the password changes, Home Assistant asks you to sign in again (re-authentication).
+
+## How data is refreshed
+
+- **Modes and set points** are read from the cloud at every poll. Commands are shown
+  immediately, then confirmed by a refresh.
+- **Measured temperatures** are only reported by the thermostats during a *diagnosis*.
+  The app runs one each time it opens. The integration runs one at start-up and then at the
+  diagnosis interval. Results arrive about 1–2 minutes after the request, so a measured
+  temperature can be up to the diagnosis interval (+2 min) old. The
+  *Thermostat status update* sensor shows when it was collected.
+- When the cloud cannot be reached, polling backs off (doubling, up to 10 minutes) and
+  returns to normal at the first success.
+
+## Known limitations
+
+- **Cloud only.** No local control: the box and thermostats are only reachable through
+  the vendor cloud.
+- **No refresh token.** The API has none, so the integration stores your app password in
+  the Home Assistant configuration and signs in again when the session expires.
+- **Measured temperatures are not live** (see above).
+- **Whole-document writes.** Each command saves the whole home document (that is what the
+  app does). A change made in the app at the same moment can be overwritten.
+- **In `auto`, the target temperature is not shown.** The API does not say which program
+  slot (comfort/eco) is active.
+- **Antifreeze temperature is not shown.** The device value is not exposed.
+- **Not supported:** editing the weekly program, eco/comfort temperatures, vacation mode,
+  geofencing, ecopilot, open-window detection, consumption counters. Use the app for these.
+- Program mode on a room relies on a frame rule checked on 3 rooms
+  ([docs/API.md](docs/API.md) §5.1). Rooms with more than 9 program events are refused
+  rather than guessed.
+- Error responses of the cloud (wrong password, expired session, box offline) were never
+  observed. They are handled generically.
+
+## Privacy and security
+
+- Credentials are stored in the Home Assistant config entry (like any cloud integration).
+  They are only sent to the Home-SmartLink cloud.
+- Neither the password nor the session token is ever logged.
+- Raw traffic captures used to study the API are never committed. Test fixtures are
+  anonymized, and a test fails if one contains personal data.
+
+## Python library
+
+```python
+import aiohttp
+from homesmartlink import HeaterMode, HomeSmartLinkClient
+
+async with aiohttp.ClientSession() as session:
+    client = HomeSmartLinkClient(session, "email", "password")
+    home_id = (await client.login())[0].home_id
+    home = await client.get_home(home_id)
+    status = await client.get_device_status(home_id)  # measured temperatures
+    await client.set_room_state(home_id, room_number=0, mode=HeaterMode.MANUAL, manual_value=19.5)
+```
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/). Home Assistant 2026.10 needs Python 3.14.
+
+```bash
+uv sync --all-groups
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run pytest                              # client tests
+uv run pytest -o addopts= tests/components # integration tests (Home Assistant plugin)
+```
+
+Fixtures in `tests/fixtures/` are generated from local captures (kept out of git) with
+`scripts/build_fixtures.py`, which anonymizes them and refuses to write if anything leaks.
+`scripts/har_extract.py` turns captures into readable, anonymized JSON for analysis.
+
+### Release
+
+1. Bump the version in `pyproject.toml`, `homesmartlink/__init__.py` and
+   `custom_components/home_smartlink/manifest.json` (version and requirement).
+2. Tag `vX.Y.Z` and push the tag. The release workflow checks the versions and publishes
+   `homesmartlink` to PyPI (Trusted Publishing).
+3. Create a GitHub release for HACS.
+
+## License
+
+[MIT](LICENSE)

homesmartlink-0.1.0/homesmartlink/__init__.py

@@ -0,0 +1,46 @@
+"""Async client for the Home-SmartLink (Carrera) heating cloud API."""
+
+from .client import HomeSmartLinkClient
+from .exceptions import (
+    AuthenticationError,
+    CannotConnectError,
+    CommandFailedError,
+    HomeSmartLinkError,
+    RateLimitError,
+    UnsupportedCommandError,
+)
+from .models import (
+    Accessory,
+    DeviceStatus,
+    Diagnosis,
+    Gateway,
+    HeaterMode,
+    HeaterSettings,
+    Home,
+    Invitation,
+    ProgramEvent,
+    Room,
+    RoomStatus,
+)
+
+__all__ = [
+    "Accessory",
+    "AuthenticationError",
+    "CannotConnectError",
+    "CommandFailedError",
+    "DeviceStatus",
+    "Diagnosis",
+    "Gateway",
+    "HeaterMode",
+    "HeaterSettings",
+    "Home",
+    "HomeSmartLinkClient",
+    "HomeSmartLinkError",
+    "Invitation",
+    "ProgramEvent",
+    "RateLimitError",
+    "Room",
+    "RoomStatus",
+    "UnsupportedCommandError",
+]
+__version__ = "0.1.0"

homesmartlink-0.1.0/homesmartlink/client.py

@@ -0,0 +1,237 @@
+"""Async client for the Home-SmartLink cloud API."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+import aiohttp
+
+from .const import APP_AGENT, APP_VERSION, BASE_URL, DEFAULT_TIMEOUT, SESSION_HEADER
+from .exceptions import (
+    AuthenticationError,
+    CannotConnectError,
+    CommandFailedError,
+    HomeSmartLinkError,
+    RateLimitError,
+)
+from .frame import build_tests, describe, encode_action_b64, validate_set_point
+from .models import (
+    DeviceStatus,
+    Diagnosis,
+    Gateway,
+    HeaterMode,
+    HeaterSettings,
+    Home,
+    Invitation,
+)
+from .status import parse_device_status
+
+_LOGGER = logging.getLogger(__name__)
+
+_AUTH_FAILURE_STATUSES = frozenset({401, 403})
+
+
+class HomeSmartLinkClient:
+    """Client for one Home-SmartLink account.
+
+    The API has no refresh token: when the session token is rejected, the client
+    signs in again with the stored credentials (once per request).
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        email: str,
+        password: str,
+        *,
+        base_url: str = BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._session = session
+        self._email = email
+        self._password = password
+        self._base_url = base_url
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._token: str | None = None
+        self._login_lock = asyncio.Lock()
+        self._write_lock = asyncio.Lock()
+
+    def __repr__(self) -> str:
+        # Never expose credentials or the session token.
+        return f"{type(self).__name__}(authenticated={self._token is not None})"
+
+    # -- authentication ----------------------------------------------------------
+
+    async def login(self) -> list[Invitation]:
+        """Sign in and return the homes the account can access."""
+        async with self._login_lock:
+            return await self._login()
+
+    async def _login(self) -> list[Invitation]:
+        data = await self._request(
+            "POST",
+            "api/1/signin",
+            json_body={
+                "email": self._email,
+                "password": self._password,
+                "agent": APP_AGENT,
+                "version": APP_VERSION,
+            },
+            authenticated=False,
+        )
+        token = data.get("token") if isinstance(data, dict) else None
+        if not isinstance(token, str) or not token:
+            raise AuthenticationError("Sign-in response did not contain a session token")
+        self._token = token
+        _LOGGER.debug("Signed in to Home-SmartLink")
+        invitation = data.get("invitation")
+        return [Invitation.from_dict(invitation)] if isinstance(invitation, dict) else []
+
+    async def _renew_session(self, rejected_token: str | None) -> None:
+        async with self._login_lock:
+            # Another request may already have renewed the session.
+            if self._token is None or self._token == rejected_token:
+                self._token = None
+                await self._login()
+
+    # -- read --------------------------------------------------------------------
+
+    async def get_invitations(self) -> list[Invitation]:
+        data = await self._request("GET", "api/1/auth", params={"version": str(APP_VERSION)})
+        return [Invitation.from_dict(i) for i in data.get("invitations", [])]
+
+    async def get_home(self, home_id: str) -> Home:
+        return Home.from_dict(await self._request("GET", f"api/1/homes/{home_id}"))
+
+    async def get_gateway(self, home_id: str) -> Gateway:
+        return Gateway.from_dict(await self._request("GET", f"api/1/device/{home_id}"))
+
+    async def get_device_status(self, home_id: str) -> DeviceStatus:
+        """Thermostat status (incl. ambient temperature) from the last diagnosis."""
+        return parse_device_status(await self._request("GET", f"api/1/deviceStatus/{home_id}"))
+
+    async def request_diagnosis(self, home_id: str) -> str:
+        """Ask the box to poll every thermostat; returns the diagnosis id."""
+        data = await self._request("POST", "api/1/diagnosys", json_body={"homeId": home_id})
+        _check_ok(data, "diagnosys")
+        return str(data["id"])
+
+    async def get_diagnosis(self, diagnosis_id: str) -> Diagnosis:
+        return Diagnosis.from_dict(await self._request("GET", f"api/1/diagnosys/{diagnosis_id}"))
+
+    # -- write -------------------------------------------------------------------
+
+    async def set_room_state(
+        self,
+        home_id: str,
+        room_number: int,
+        mode: HeaterMode,
+        manual_value: float | None = None,
+    ) -> Home:
+        """Change the mode (and optionally the manual set point) of one room.
+
+        Mirrors the app: re-read the home, send the command frame to the box,
+        then save the whole home document. Returns the home as written.
+        """
+        async with self._write_lock:
+            home = await self.get_home(home_id)
+            current = home.room(room_number).heater_settings
+            new_manual = current.manual_value if manual_value is None else manual_value
+            if manual_value is not None:
+                validate_set_point(new_manual, current.limitation_set_point)
+            settings = HeaterSettings(
+                current_mode=mode,
+                manual_value=new_manual,
+                economy_value=current.economy_value,
+                standard_value=current.standard_value,
+                limitation_set_point=current.limitation_set_point,
+            )
+            updated = home.with_room_settings(room_number, settings)
+            room = updated.room(room_number)
+
+            notify = {
+                "action": encode_action_b64(room),
+                "description": describe(room),
+                "homeId": home_id,
+                "tests": build_tests(updated.rooms),
+            }
+            _check_ok(
+                await self._request("POST", "api/1/device/notify", json_body=notify), "notify"
+            )
+            _check_ok(
+                await self._request("PUT", "api/1/homes/", json_body=updated.to_update_payload()),
+                "home update",
+            )
+            return updated
+
+    # -- transport ---------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, str] | None = None,
+        authenticated: bool = True,
+    ) -> Any:
+        if authenticated and self._token is None:
+            await self.login()
+
+        for attempt in (1, 2):
+            token = self._token
+            headers = {SESSION_HEADER: token} if authenticated and token else {}
+            try:
+                async with self._session.request(
+                    method,
+                    self._base_url + path,
+                    json=json_body,
+                    params=params,
+                    headers=headers,
+                    timeout=self._timeout,
+                ) as resp:
+                    if resp.status in _AUTH_FAILURE_STATUSES:
+                        if authenticated and attempt == 1:
+                            _LOGGER.debug(
+                                "Session rejected (HTTP %s), signing in again", resp.status
+                            )
+                            await self._renew_session(token)
+                            continue
+                        raise AuthenticationError(f"{method} {path}: HTTP {resp.status}")
+                    _raise_for_status(resp, method, path, authenticated)
+                    return await resp.json(content_type=None)
+            except TimeoutError as err:
+                raise CannotConnectError(f"{method} {path}: timeout") from err
+            except aiohttp.ClientError as err:
+                raise CannotConnectError(f"{method} {path}: {type(err).__name__}") from err
+            except ValueError as err:
+                raise HomeSmartLinkError(f"{method} {path}: invalid JSON") from err
+        raise AuthenticationError(f"{method} {path}: session rejected after sign-in")
+
+
+def _raise_for_status(
+    resp: aiohttp.ClientResponse, method: str, path: str, authenticated: bool
+) -> None:
+    status = resp.status
+    if status < 400:
+        return
+    if status == 429:
+        retry_after: float | None
+        try:
+            retry_after = float(resp.headers.get("Retry-After", ""))
+        except ValueError:
+            retry_after = None
+        raise RateLimitError(f"{method} {path}: rate limited", retry_after)
+    if status >= 500:
+        raise CannotConnectError(f"{method} {path}: HTTP {status}")
+    if not authenticated:
+        # Sign-in failures (wrong credentials were never captured: any 4xx).
+        raise AuthenticationError(f"{method} {path}: HTTP {status}")
+    raise HomeSmartLinkError(f"{method} {path}: HTTP {status}")
+
+
+def _check_ok(data: Any, what: str) -> None:
+    if not isinstance(data, dict) or data.get("status") != "OK":
+        raise CommandFailedError(f"Unexpected {what} response")

homesmartlink-0.1.0/homesmartlink/const.py

@@ -0,0 +1,25 @@
+"""Constants of the Home-SmartLink cloud API (see docs/API.md)."""
+
+from __future__ import annotations
+
+from typing import Final
+
+BASE_URL: Final = "https://jcqzjjt6q5.execute-api.eu-west-3.amazonaws.com/Prod/"
+
+# Values the official Android app sends; the cloud may rely on them.
+APP_AGENT: Final = "Droid"
+APP_VERSION: Final = 103
+
+SESSION_HEADER: Final = "x-session"
+DEFAULT_TIMEOUT: Final = 20.0
+
+# Set point range accepted by the official app dial (capture 19), in °C.
+MIN_SET_POINT: Final = 13.5
+MAX_SET_POINT: Final = 30.0
+SET_POINT_STEP: Final = 0.5
+
+# Set point carried by Stop and Antifreeze frames, whatever the room settings.
+FROST_FRAME_SET_POINT: Final = 14.0
+
+# Longest program the 64-byte frame was observed with.
+MAX_PROGRAM_EVENTS: Final = 9

homesmartlink-0.1.0/homesmartlink/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions raised by the Home-SmartLink client."""
+
+from __future__ import annotations
+
+
+class HomeSmartLinkError(Exception):
+    """Base class for every error raised by this package."""
+
+
+class AuthenticationError(HomeSmartLinkError):
+    """Credentials were rejected, or the session could not be renewed."""
+
+
+class CannotConnectError(HomeSmartLinkError):
+    """The cloud could not be reached or answered with a server error."""
+
+
+class RateLimitError(HomeSmartLinkError):
+    """The cloud asked us to slow down (HTTP 429)."""
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class UnsupportedCommandError(HomeSmartLinkError):
+    """The requested state cannot be encoded safely (outside observed behavior)."""
+
+
+class CommandFailedError(HomeSmartLinkError):
+    """The cloud accepted the request but did not report success."""

homesmartlink-0.1.0/homesmartlink/frame.py

@@ -0,0 +1,129 @@
+"""Encoding of `device/notify` commands (docs/API.md §5).
+
+Every rule here was derived from captured frames; anything outside what was
+observed raises UnsupportedCommandError instead of guessing.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Iterable
+
+from .const import (
+    FROST_FRAME_SET_POINT,
+    MAX_PROGRAM_EVENTS,
+    MAX_SET_POINT,
+    MIN_SET_POINT,
+    SET_POINT_STEP,
+)
+from .exceptions import UnsupportedCommandError
+from .models import HeaterMode, ProgramEvent, Room
+
+FRAME_LENGTH = 64
+
+_MODE_NAMES = {
+    HeaterMode.STOP: "Stop",
+    HeaterMode.ANTIFREEZE: "Antifreeze",
+    HeaterMode.MANUAL: "Manual",
+    HeaterMode.PROGRAM: "Prog",
+}
+
+_TESTS_SUFFIX = "A[0-9]{1,3}J[0-9]{1,3}W[0-9]{1,3}M[0-9]{1,3}Y[0-9]{1,3}"
+# First alternative of C(..|..) in Manual mode; only ever observed as 26.
+_TESTS_MANUAL_LOW = 26
+
+
+def validate_set_point(value: float, limit: float = MAX_SET_POINT) -> float:
+    """Check a set point against the range and step the app allows."""
+    upper = min(MAX_SET_POINT, limit)
+    if not MIN_SET_POINT <= value <= upper:
+        raise UnsupportedCommandError(f"Set point {value} outside {MIN_SET_POINT}-{upper}")
+    if (value / SET_POINT_STEP) % 1:
+        raise UnsupportedCommandError(f"Set point {value} is not a multiple of {SET_POINT_STEP}")
+    return value
+
+
+def _mode(room: Room) -> HeaterMode:
+    mode = room.heater_settings.current_mode
+    if not isinstance(mode, HeaterMode):
+        raise UnsupportedCommandError(f"Unknown heater mode {mode}")
+    return mode
+
+
+def _encode_set_point(value: float) -> bytes:
+    return (((round(value * 2)) << 3) | 0b011).to_bytes(2, "little")
+
+
+def _encode_event(event: ProgramEvent) -> bytes:
+    fields = (event.event_id, event.recurrence, event.mode)
+    if not (0 <= event.event_id < 16 and 0 <= event.recurrence < 128 and 0 <= event.mode < 8):
+        raise UnsupportedCommandError(f"Program event fields out of range: {fields}")
+    start = event.start_hour * 6 + event.start_minute // 10
+    end = event.end_hour * 6 + event.end_minute // 10
+    if not (0 <= start <= 144 and 0 <= end <= 144):
+        raise UnsupportedCommandError(f"Program event time out of range: {fields}")
+    return bytes([0x80 | event.event_id << 3 | event.mode, 0x80 | event.recurrence, start, end])
+
+
+def encode_action(room: Room) -> bytes:
+    """Build the 64-byte frame that puts `room` in its `heater_settings` state."""
+    settings = room.heater_settings
+    mode = _mode(room)
+    if len(room.events) > MAX_PROGRAM_EVENTS:
+        raise UnsupportedCommandError(f"Rooms with {len(room.events)} program events")
+    if not 0 <= room.number < 256:
+        raise UnsupportedCommandError(f"Room number {room.number}")
+
+    if mode in (HeaterMode.STOP, HeaterMode.ANTIFREEZE):
+        set_point = FROST_FRAME_SET_POINT
+        state = 0x10 if mode is HeaterMode.STOP else 0x50
+        flags = 0x40
+    elif mode is HeaterMode.MANUAL:
+        set_point = validate_set_point(settings.manual_value, settings.limitation_set_point)
+        state, flags = 0xD0, 0x40
+    else:  # PROGRAM
+        set_point = validate_set_point(settings.standard_value, settings.limitation_set_point)
+        state = 0xD0 if room.ecopilot_enabled else 0x10
+        flags = 0xE1
+
+    frame = bytearray([0x01, state, flags])
+    frame += _encode_set_point(set_point)
+    frame += bytes([room.number, 0, 0])
+    for event in room.events:
+        frame += _encode_event(event)
+    frame.append(room.number)
+    return bytes(frame.ljust(FRAME_LENGTH, b"\x00"))
+
+
+def encode_action_b64(room: Room) -> str:
+    return base64.b64encode(encode_action(room)).decode("ascii")
+
+
+def describe(room: Room) -> str:
+    """Human-readable `description`, formatted like the app's."""
+    settings = room.heater_settings
+    return (
+        f"cockpit room {room.number} => mode {_MODE_NAMES[_mode(room)]}, "
+        f"manuelSP:{settings.manual_value:g})"
+    )
+
+
+def _room_tests(room: Room) -> str:
+    settings = room.heater_settings
+    mode = _mode(room)
+    if mode is HeaterMode.STOP:
+        device_mode, set_points = 0, "([0-9]{2})"
+    elif mode is HeaterMode.ANTIFREEZE:
+        device_mode, set_points = 1, "([0-9]{2})"
+    elif mode is HeaterMode.MANUAL:
+        device_mode = 3
+        set_points = f"({_TESTS_MANUAL_LOW}|{round(settings.manual_value * 2)})"
+    else:
+        device_mode = 7 if room.ecopilot_enabled else 4
+        set_points = f"({round(settings.economy_value * 2)}|{round(settings.standard_value * 2)})"
+    return f"R{room.number}D[0-9]M{device_mode}S[0-9]C{set_points}{_TESTS_SUFFIX}"
+
+
+def build_tests(rooms: Iterable[Room]) -> str:
+    """Expected status patterns of every room, as sent by the app with each command."""
+    return " ".join(_room_tests(room) for room in rooms)

homesmartlink-0.1.0/homesmartlink/models.py

@@ -0,0 +1,274 @@
+"""Typed views over the Home-SmartLink API payloads."""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, replace
+from datetime import datetime
+from enum import IntEnum
+from typing import Any
+
+
+class HeaterMode(IntEnum):
+    """`heaterSettings.currentMode` values written by the app."""
+
+    STOP = 1
+    ANTIFREEZE = 2
+    MANUAL = 3
+    PROGRAM = 4
+
+
+def _parse_datetime(value: Any) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class Invitation:
+    """Access of the account to one home (`signin` / `auth` responses)."""
+
+    id: str
+    home_id: str
+    role: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Invitation:
+        return cls(id=str(data["_id"]), home_id=str(data["homeid"]), role=int(data["role"]))
+
+
+@dataclass(frozen=True, slots=True)
+class HeaterSettings:
+    """Heating configuration of one room."""
+
+    current_mode: HeaterMode | int
+    manual_value: float
+    economy_value: float
+    standard_value: float
+    limitation_set_point: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> HeaterSettings:
+        raw_mode = int(data["currentMode"])
+        try:
+            mode: HeaterMode | int = HeaterMode(raw_mode)
+        except ValueError:
+            mode = raw_mode
+        return cls(
+            current_mode=mode,
+            manual_value=float(data["manualValue"]),
+            economy_value=float(data["economyValue"]),
+            standard_value=float(data["standardValue"]),
+            limitation_set_point=float(data["limitationSetPoint"]),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "manualValue": self.manual_value,
+            "economyValue": self.economy_value,
+            "standardValue": self.standard_value,
+            "currentMode": int(self.current_mode),
+            "limitationSetPoint": self.limitation_set_point,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ProgramEvent:
+    """One slot of the weekly program of a room."""
+
+    event_id: int
+    recurrence: int
+    mode: int
+    start_hour: int
+    start_minute: int
+    end_hour: int
+    end_minute: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ProgramEvent:
+        return cls(
+            event_id=int(data["eventID"]),
+            recurrence=int(data["reccurency"]),
+            mode=int(data["mode"]),
+            start_hour=int(data["startHour"]),
+            start_minute=int(data["startMinute"]),
+            end_hour=int(data["endHour"]),
+            end_minute=int(data["endMinute"]),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Accessory:
+    """A device paired to a room (category 5 = thermostat)."""
+
+    id: str
+    category: int
+    software_version: str | None
+    created_at: datetime | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Accessory:
+        version = data.get("softwareVersion")
+        return cls(
+            id=str(data["header"]),
+            category=int(data["category"]),
+            software_version=None if version is None else str(version),
+            created_at=_parse_datetime(data.get("creationDate")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Room:
+    """A room and its heating configuration."""
+
+    number: int
+    name: str
+    area: int | None
+    ecopilot_enabled: bool
+    open_window_detection_enabled: bool
+    accessories: tuple[Accessory, ...]
+    heater_settings: HeaterSettings
+    events: tuple[ProgramEvent, ...]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Room:
+        area = data.get("area")
+        return cls(
+            number=int(data["roomNumber"]),
+            name=str(data.get("name", "")),
+            area=None if area is None else int(area),
+            ecopilot_enabled=bool(data.get("ecopilotEnabled", False)),
+            open_window_detection_enabled=bool(data.get("openWindowsDetectionEnabled", False)),
+            accessories=tuple(Accessory.from_dict(a) for a in data.get("accessories", [])),
+            heater_settings=HeaterSettings.from_dict(data["heaterSettings"]),
+            events=tuple(ProgramEvent.from_dict(e) for e in data.get("events", [])),
+        )
+
+    def with_settings(self, settings: HeaterSettings) -> Room:
+        return replace(self, heater_settings=settings)
+
+
+@dataclass(frozen=True, slots=True)
+class Home:
+    """A home document (`GET homes/{id}`).
+
+    The raw document is kept because writes must send the whole document back
+    (`PUT homes/`), including fields this package does not model.
+    """
+
+    id: str
+    has_gateway: bool
+    rooms: tuple[Room, ...]
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Home:
+        return cls(
+            id=str(data["_id"]),
+            has_gateway=bool(data.get("hasGateway", False)),
+            rooms=tuple(Room.from_dict(r) for r in data.get("rooms", [])),
+            raw=copy.deepcopy(data),
+        )
+
+    def room(self, number: int) -> Room:
+        for room in self.rooms:
+            if room.number == number:
+                return room
+        raise KeyError(f"No room {number} in home")
+
+    def with_room_settings(self, number: int, settings: HeaterSettings) -> Home:
+        """Return a copy of the home where one room has new heater settings."""
+        raw = copy.deepcopy(self.raw)
+        for room in raw.get("rooms", []):
+            if int(room["roomNumber"]) == number:
+                room["heaterSettings"] = {**room["heaterSettings"], **settings.to_dict()}
+                break
+        else:
+            raise KeyError(f"No room {number} in home")
+        return Home.from_dict(raw)
+
+    def to_update_payload(self) -> dict[str, Any]:
+        """Body of `PUT homes/`: the document without server-managed timestamps."""
+        payload = copy.deepcopy(self.raw)
+        payload.pop("_created_at", None)
+        payload.pop("_updated_at", None)
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class Gateway:
+    """The Home-SmartLink box (`GET device/{homeId}`)."""
+
+    home_id: str
+    identifier: str
+    version: str | None
+    installed_at: datetime | None
+    last_connection: datetime | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Gateway:
+        version = data.get("version")
+        return cls(
+            home_id=str(data["homeId"]),
+            identifier=str(data["identifier"]),
+            version=None if version is None else str(version),
+            installed_at=_parse_datetime(data.get("installation")),
+            last_connection=_parse_datetime(data.get("lastConnection")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RoomStatus:
+    """One status string reported by a thermostat during a diagnosis."""
+
+    room_number: int
+    device_mode: int
+    set_point: float
+    ambient_temperature: float
+    raw: str
+    unknown_d: int
+    unknown_s: int
+    counters: tuple[int, int, int, int]
+
+    @property
+    def heater_mode(self) -> HeaterMode | None:
+        """Map the device mode code (0, 1, 3, 4, 7) to the app mode."""
+        return DEVICE_MODE_TO_HEATER_MODE.get(self.device_mode)
+
+
+# Device mode codes seen in status strings and `tests` (docs/API.md §5.2).
+DEVICE_MODE_TO_HEATER_MODE: dict[int, HeaterMode] = {
+    0: HeaterMode.STOP,
+    1: HeaterMode.ANTIFREEZE,
+    3: HeaterMode.MANUAL,
+    4: HeaterMode.PROGRAM,
+    7: HeaterMode.PROGRAM,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceStatus:
+    """Result of the last diagnosis (`GET deviceStatus/{homeId}`)."""
+
+    created_at: datetime | None
+    rooms: dict[int, RoomStatus]
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnosis:
+    """A diagnosis request (`GET diagnosys/{id}`)."""
+
+    id: str
+    acknowledged: bool
+    updated_at: datetime | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Diagnosis:
+        return cls(
+            id=str(data["_id"]),
+            acknowledged=bool(data.get("acknowledge", False)),
+            updated_at=_parse_datetime(data.get("_updated_at")),
+        )

homesmartlink-0.1.0/homesmartlink/status.py

@@ -0,0 +1,44 @@
+"""Parsing of thermostat status strings (docs/API.md, deviceStatus)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .models import DeviceStatus, RoomStatus, _parse_datetime
+
+# Fields are positional: the letter M appears twice (mode, then a counter).
+_STATUS_RE = re.compile(
+    r"^R(?P<room>\d+)D(?P<d>\d+)M(?P<mode>\d+)S(?P<s>\d+)C(?P<c>\d+)A(?P<a>\d+)"
+    r"J(?P<j>\d+)W(?P<w>\d+)M(?P<m>\d+)Y(?P<y>\d+)$"
+)
+
+
+def parse_room_status(value: str) -> RoomStatus | None:
+    """Parse one status string, e.g. ``R0D0M3S0C38A42J0W0M0Y0``.
+
+    Returns None for strings that do not follow the observed format.
+    """
+    match = _STATUS_RE.match(value.strip())
+    if match is None:
+        return None
+    g = {k: int(v) for k, v in match.groupdict().items()}
+    return RoomStatus(
+        room_number=g["room"],
+        device_mode=g["mode"],
+        set_point=g["c"] / 2,
+        ambient_temperature=g["a"] / 2,
+        raw=value,
+        unknown_d=g["d"],
+        unknown_s=g["s"],
+        counters=(g["j"], g["w"], g["m"], g["y"]),
+    )
+
+
+def parse_device_status(data: dict[str, Any]) -> DeviceStatus:
+    """Parse a `GET deviceStatus/{homeId}` response, skipping unknown entries."""
+    rooms: dict[int, RoomStatus] = {}
+    for value in data.get("status") or []:
+        if isinstance(value, str) and (status := parse_room_status(value)) is not None:
+            rooms[status.room_number] = status
+    return DeviceStatus(created_at=_parse_datetime(data.get("_created_at")), rooms=rooms)

homesmartlink-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "homesmartlink"
+version = "0.1.0"
+description = "Async client for the Home-SmartLink (Carrera) heating cloud API"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Michaël Fery", email = "fery.michael@gmail.com" }]
+dependencies = ["aiohttp>=3.10"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Source = "https://github.com/michaelfery/home-smartlink-ha"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+]
+ha = [
+    "pytest-homeassistant-custom-component==0.13.373; python_full_version >= '3.14.2'",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["homesmartlink"]
+
+[tool.hatch.build.targets.sdist]
+include = ["homesmartlink", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+# Client tests run without the Home Assistant plugin (it blocks sockets);
+# integration tests: pytest -o addopts= tests/components
+addopts = "-p no:homeassistant"
+testpaths = ["tests/client"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+files = ["homesmartlink", "custom_components"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "ASYNC"]
+
+[[tool.mypy.overrides]]
+# Home Assistant re-exports its constants implicitly; core integrations rely on it.
+module = "homeassistant.*"
+implicit_reexport = true
+
+[tool.ruff.lint.per-file-ignores]
+# Home Assistant entities declare their _attr_* lists at class level.
+"custom_components/**" = ["RUF012"]