dimplex-controller 0.2.0__tar.gz

dimplex_controller-0.2.0/LICENSE

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

dimplex_controller-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: dimplex-controller
+Version: 0.2.0
+Summary: Python client for Dimplex heating controllers (GDHV IoT)
+License: MIT
+License-File: LICENSE
+Keywords: dimplex,heating,control,iot,asyncio
+Author: Kieran Roper
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Dist: aiohttp (>=3.9.0,<4.0.0)
+Requires-Dist: beautifulsoup4 (>=4.14.3,<5.0.0)
+Requires-Dist: pydantic (>=2.0.0,<3.0.0)
+Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
+Project-URL: Homepage, https://github.com/KRoperUK/dimplex-controller-py
+Project-URL: Repository, https://github.com/KRoperUK/dimplex-controller-py
+Description-Content-Type: text/markdown
+
+# Dimplex Controller Python Client
+
+[![PyPI](https://img.shields.io/pypi/v/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
+[![Tests](https://github.com/KRoperUK/dimplex-controller-py/actions/workflows/tests.yml/badge.svg)](https://github.com/KRoperUK/dimplex-controller-py/actions)
+[![Downloads](https://img.shields.io/pypi/dm/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?logo=github)](https://github.com/KRoperUK/dimplex-controller-py)
+
+A Python asyncio client for controlling Dimplex heating systems (GDHV IoT).
+
+## Features
+
+- **Authentication**: Easy login flow and automatic token refresh (Azure B2C).
+- **Discovery**: List Hubs, Zones, and Appliances associated with your account.
+- **Detailed Status**: Fetch real-time data including room temperature, setpoints, comfort status, and active boost settings.
+- **Control**:
+  - Set operation modes (Manual, Timer, Frost Protection).
+  - Activate **Boost** and **Away** modes.
+  - Toggle **EcoStart** and **Open Window Detection**.
+  - Program heating schedules (Timer Periods).
+
+## Installation
+
+This project is managed with Poetry.
+
+```bash
+git clone <repo-url>
+cd dimplex-controller-py
+poetry install
+```
+
+## Getting Started
+
+### 1. Initial Authentication
+Due to the nature of the Azure B2C flow, you must perform the initial login manually to capture an authorization code.
+
+Run the demo script to guide you through the process:
+
+```bash
+poetry run python demo.py
+```
+
+Follow the on-screen instructions. Once successful, a `dimplex_tokens.json` file will be created, allowing the library to authenticate automatically in the future.
+
+### 2. Basic Usage
+
+```python
+import asyncio
+import aiohttp
+from dimplex_controller import DimplexControl
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        # Pass tokens from dimplex_tokens.json or just the refresh_token
+        client = DimplexControl(session, refresh_token="YOUR_REFRESH_TOKEN")
+
+        # Get Hubs
+        hubs = await client.get_hubs()
+        for hub in hubs:
+            print(f"Hub: {hub.Name}")
+
+            # Get Zones and Appliances
+            zones = await client.get_hub_zones(hub.HubId)
+            for zone in zones:
+                print(f"  Zone: {zone.ZoneName}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 3. Advanced Operations
+
+#### Get Real-time Status
+```python
+# Fetch status for a list of appliance IDs
+status_list = await client.get_appliance_overview(hub_id, ["appliance_id_1", "appliance_id_2"])
+
+for status in status_list:
+    print(f"Temp: {status.RoomTemperature}°C, Target: {status.ActiveSetPointTemperature}°C")
+    print(f"EcoStart: {status.EcoStartEnabled}")
+```
+
+#### Control Features
+```python
+from dimplex_controller.models import ApplianceModeSettings
+
+# Enable EcoStart
+await client.set_eco_start(hub_id, [appliance_id], True)
+
+# Enable Open Window Detection
+await client.set_open_window_detection(hub_id, [appliance_id], True)
+
+# Activate Boost (Mode 16, Status 1 = On)
+boost_settings = ApplianceModeSettings(ApplianceModes=16, Status=1, Temperature=25.0)
+await client.set_appliance_mode(hub_id, [appliance_id], boost_settings)
+```
+
+## Development & API Reference
+
+- **`openapi.yaml`**: This file contains the most complete technical specification of the API discovered so far. It includes all known endpoints, request bodies, and response schemas.
+- **Traffic Logs**: If you identify new features in the mobile app, capture the traffic and add the endpoints to `openapi.yaml` and the `DimplexControl` client.
+
+## Disclaimer
+
+This is an unofficial library and is not affiliated with or endorsed by Glen Dimplex Heating & Ventilation (GDHV). Use it at your own risk.
+

dimplex_controller-0.2.0/README.md

@@ -0,0 +1,106 @@
+# Dimplex Controller Python Client
+
+[![PyPI](https://img.shields.io/pypi/v/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
+[![Tests](https://github.com/KRoperUK/dimplex-controller-py/actions/workflows/tests.yml/badge.svg)](https://github.com/KRoperUK/dimplex-controller-py/actions)
+[![Downloads](https://img.shields.io/pypi/dm/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?logo=github)](https://github.com/KRoperUK/dimplex-controller-py)
+
+A Python asyncio client for controlling Dimplex heating systems (GDHV IoT).
+
+## Features
+
+- **Authentication**: Easy login flow and automatic token refresh (Azure B2C).
+- **Discovery**: List Hubs, Zones, and Appliances associated with your account.
+- **Detailed Status**: Fetch real-time data including room temperature, setpoints, comfort status, and active boost settings.
+- **Control**:
+  - Set operation modes (Manual, Timer, Frost Protection).
+  - Activate **Boost** and **Away** modes.
+  - Toggle **EcoStart** and **Open Window Detection**.
+  - Program heating schedules (Timer Periods).
+
+## Installation
+
+This project is managed with Poetry.
+
+```bash
+git clone <repo-url>
+cd dimplex-controller-py
+poetry install
+```
+
+## Getting Started
+
+### 1. Initial Authentication
+Due to the nature of the Azure B2C flow, you must perform the initial login manually to capture an authorization code.
+
+Run the demo script to guide you through the process:
+
+```bash
+poetry run python demo.py
+```
+
+Follow the on-screen instructions. Once successful, a `dimplex_tokens.json` file will be created, allowing the library to authenticate automatically in the future.
+
+### 2. Basic Usage
+
+```python
+import asyncio
+import aiohttp
+from dimplex_controller import DimplexControl
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        # Pass tokens from dimplex_tokens.json or just the refresh_token
+        client = DimplexControl(session, refresh_token="YOUR_REFRESH_TOKEN")
+
+        # Get Hubs
+        hubs = await client.get_hubs()
+        for hub in hubs:
+            print(f"Hub: {hub.Name}")
+
+            # Get Zones and Appliances
+            zones = await client.get_hub_zones(hub.HubId)
+            for zone in zones:
+                print(f"  Zone: {zone.ZoneName}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 3. Advanced Operations
+
+#### Get Real-time Status
+```python
+# Fetch status for a list of appliance IDs
+status_list = await client.get_appliance_overview(hub_id, ["appliance_id_1", "appliance_id_2"])
+
+for status in status_list:
+    print(f"Temp: {status.RoomTemperature}°C, Target: {status.ActiveSetPointTemperature}°C")
+    print(f"EcoStart: {status.EcoStartEnabled}")
+```
+
+#### Control Features
+```python
+from dimplex_controller.models import ApplianceModeSettings
+
+# Enable EcoStart
+await client.set_eco_start(hub_id, [appliance_id], True)
+
+# Enable Open Window Detection
+await client.set_open_window_detection(hub_id, [appliance_id], True)
+
+# Activate Boost (Mode 16, Status 1 = On)
+boost_settings = ApplianceModeSettings(ApplianceModes=16, Status=1, Temperature=25.0)
+await client.set_appliance_mode(hub_id, [appliance_id], boost_settings)
+```
+
+## Development & API Reference
+
+- **`openapi.yaml`**: This file contains the most complete technical specification of the API discovered so far. It includes all known endpoints, request bodies, and response schemas.
+- **Traffic Logs**: If you identify new features in the mobile app, capture the traffic and add the endpoints to `openapi.yaml` and the `DimplexControl` client.
+
+## Disclaimer
+
+This is an unofficial library and is not affiliated with or endorsed by Glen Dimplex Heating & Ventilation (GDHV). Use it at your own risk.

dimplex_controller-0.2.0/dimplex_controller/__init__.py

@@ -0,0 +1,18 @@
+"""Dimplex Controller Client."""
+
+from .client import DimplexControl
+from .exceptions import DimplexApiError, DimplexAuthError, DimplexConnectionError, DimplexError
+from .models import Appliance, ApplianceModeSettings, ApplianceStatus, Hub, Zone
+
+__all__ = [
+    "DimplexControl",
+    "Hub",
+    "Zone",
+    "Appliance",
+    "ApplianceStatus",
+    "ApplianceModeSettings",
+    "DimplexError",
+    "DimplexApiError",
+    "DimplexAuthError",
+    "DimplexConnectionError",
+]

dimplex_controller-0.2.0/dimplex_controller/auth.py

@@ -0,0 +1,304 @@
+import json
+import logging
+import os
+import re
+import time
+from typing import Dict, Optional
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import aiohttp
+from bs4 import BeautifulSoup
+
+from .const import (
+    AUTH_URL,
+    CLIENT_ID,
+    HTTP_OK,
+    REDIRECT_URI,
+    SCOPE,
+)
+from .exceptions import DimplexAuthError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AuthManager:
+    """Manages authentication for Dimplex Control."""
+
+    def __init__(self, session: aiohttp.ClientSession, token_data: Optional[Dict] = None):
+        """Initialize the auth manager."""
+        self._session = session
+        self._access_token: Optional[str] = token_data.get("access_token") if token_data else None
+        self._refresh_token: Optional[str] = token_data.get("refresh_token") if token_data else None
+        self._expires_at: float = token_data.get("expires_at", 0) if token_data else 0
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if we have a valid access token."""
+        return self._access_token is not None and time.time() < self._expires_at
+
+    async def get_access_token(self) -> str:
+        """Get a valid access token, refreshing if necessary."""
+        if not self._refresh_token:
+            raise DimplexAuthError("No refresh token available. User must authenticate first.")
+
+        if self.is_authenticated:
+            return self._access_token
+
+        # Token expired or missing, try refresh
+        await self.refresh_tokens()
+        return self._access_token
+
+    async def refresh_tokens(self) -> None:
+        """Refresh the access token using the refresh token."""
+        _LOGGER.debug("Refreshing access token")
+        payload = {
+            "client_id": CLIENT_ID,
+            "grant_type": "refresh_token",
+            "refresh_token": self._refresh_token,
+            "scope": SCOPE,
+            "client_info": "1",
+        }
+
+        async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
+            if resp.status != HTTP_OK:
+                text = await resp.text()
+                _LOGGER.error("Failed to refresh token: %s", text)
+                raise DimplexAuthError(f"Failed to refresh token: {resp.status} - {text}")
+
+            data = await resp.json()
+            self._update_tokens(data)
+
+    def _update_tokens(self, data: Dict) -> None:
+        """Update internal token state from API response."""
+        self._access_token = data.get("access_token")
+        self._refresh_token = data.get("refresh_token")
+        expires_in = data.get("expires_in", 3600)
+        self._expires_at = time.time() + expires_in - 60  # Buffer 60s
+
+    def get_login_url(self) -> str:
+        """Generate the login URL for the user to visit."""
+        # Note: This is a simplified URL generation.
+        # In a real app, we might need state, nonce, code_challenge (PKCE).
+        # Based on logs, iOS app uses standard OAuth2.
+        # Constructing a URL for manual copy-paste might be tricky if it strictly requires a custom scheme redirect.
+        # But we can try the standard authorize endpoint.
+
+        params = {
+            "client_id": CLIENT_ID,
+            "response_type": "code",
+            "redirect_uri": REDIRECT_URI,
+            "scope": SCOPE,
+            "response_mode": "query",
+        }
+        from urllib.parse import urlencode
+
+        return f"{AUTH_URL}/authorize?{urlencode(params)}"
+
+    async def exchange_code(self, code: str) -> None:
+        """Exchange authorization code for tokens."""
+        payload = {
+            "client_id": CLIENT_ID,
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": REDIRECT_URI,
+            "scope": SCOPE,
+        }
+
+        _LOGGER.info(f"Exchanging code for tokens at {AUTH_URL}/token")
+        client_id = payload["client_id"]
+        redirect_uri = payload["redirect_uri"]
+        code_preview = code[:10]
+        _LOGGER.info(f"Payload: client_id={client_id}, redirect_uri={redirect_uri}, " f"code={code_preview}...")
+
+        async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
+            _LOGGER.info(f"Token exchange response status: {resp.status}")
+            if resp.status != HTTP_OK:
+                text = await resp.text()
+                _LOGGER.error(f"Token exchange failed: {text}")
+                raise DimplexAuthError(f"Failed to exchange code: {text}")
+
+            data = await resp.json()
+            self._update_tokens(data)
+
+    async def headless_login(self, email, password) -> None:
+        """Perform a headless login to obtain tokens."""
+        # 1. Get the login page
+        params = {
+            "client_id": CLIENT_ID,
+            "response_type": "code",
+            "redirect_uri": REDIRECT_URI,
+            "scope": SCOPE,
+            "response_mode": "query",
+        }
+        start_url = f"{AUTH_URL}/authorize?{urlencode(params)}"
+        _LOGGER.debug(f"Fetching login page: {start_url}")
+
+        async with self._session.get(start_url) as resp:
+            html = await resp.text()
+            final_url = str(resp.url)
+
+        # 2. Extract SETTINGS and CSRF
+        match = re.search(r"SETTINGS\s*=\s*({.*?});", html, re.DOTALL | re.MULTILINE)
+        if not match:
+            raise DimplexAuthError("Could not find SETTINGS in login page")
+
+        try:
+            settings = json.loads(match.group(1))
+        except json.JSONDecodeError:
+            raise DimplexAuthError("Failed to parse SETTINGS JSON from login page")
+
+        csrf_token = settings.get("csrf")
+        trans_id = settings.get("transId")
+
+        if not csrf_token or not trans_id:
+            raise DimplexAuthError("Missing csrf or transId in login page SETTINGS")
+
+        # 3. Construct SelfAsserted URL
+        if "/oauth2/v2.0/authorize" in final_url:
+            base_url = final_url.split("/oauth2/v2.0/authorize")[0]
+        else:
+            base_url = "https://gdhvb2c.b2clogin.com/gdhvb2c.onmicrosoft.com/B2C_1A_DimplexControlSignupSignin"
+
+        post_url = f"{base_url}/SelfAsserted"
+
+        params = {
+            "tx": trans_id,
+            "p": "B2C_1A_DimplexControlSignupSignin",
+        }
+
+        post_url_with_params = f"{post_url}?{urlencode(params)}"
+
+        # 4. Submit Credentials
+        # Extract hidden fields from the form to ensure we aren't missing anything
+        soup = BeautifulSoup(html, "html.parser")
+        form = soup.find("form", {"id": "localAccountForm"}) or soup.find("form")
+
+        form_data = {}
+        if form:
+            for input_tag in form.find_all("input"):
+                name = input_tag.get("name")
+                value = input_tag.get("value", "")
+                if name:
+                    form_data[name] = value
+
+        # Overwrite with credentials
+        form_data.update(
+            {
+                "request_type": "RESPONSE",
+                "email": email,
+                "password": password,
+            }
+        )
+
+        headers = {
+            "X-CSRF-TOKEN": csrf_token,
+            "X-Requested-With": "XMLHttpRequest",
+            "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+            "Origin": "https://gdhvb2c.b2clogin.com",
+            "Referer": final_url,
+        }
+
+        _LOGGER.debug(f"Submitting credentials to {post_url_with_params}")
+        # _LOGGER.debug(f"Form data: {form_data}") # Security risk to log password
+
+        async with self._session.post(post_url_with_params, data=form_data, headers=headers) as resp:
+            resp_text = await resp.text()
+            _LOGGER.debug(f"Login response status: {resp.status}")
+
+            try:
+                resp_json = json.loads(resp_text)
+                _LOGGER.debug(f"Login response JSON: {resp_json}")
+            except json.JSONDecodeError:
+                _LOGGER.debug(f"Login response Text: {resp_text}")
+                raise DimplexAuthError(f"Login response was not valid JSON: {resp_text[:100]}")
+
+            if resp_json.get("status") != "200":
+                status = resp_json.get("status")
+                message = resp_json.get("message") or resp_json.get("reason", "Unknown reason")
+                raise DimplexAuthError(f"Login failed: {status} - {message}")
+
+        # 5. Follow the 'Confirmed' step to get the actual code
+        # After a successful SelfAsserted, we usually need to make a GET to
+        # the 'CombinedSigninAndSignup' or similar endpoint to finalize the
+        # flow and get the redirect to our app with the code.
+        # Or, sometimes the SelfAsserted response sets a cookie and we just
+        # need to hit the authorize endpoint again.
+
+        # Let's try hitting the original authorize URL again (or the one we were redirected to).
+        # Since cookies are in the session, it should now redirect us to the app with the code.
+
+        _LOGGER.debug("Credentials accepted. Fetching authorize URL again to get code.")
+
+        # We need to allow redirects to capture the final msauth:// url
+        # aiohttp generic session checks redirects.
+        # But since the scheme is custom (msal...), aiohttp might throw an error or stop.
+
+        try:
+            async with self._session.get(start_url, allow_redirects=True) as resp:
+                # If we are here, it means we didn't crash on custom scheme yet,
+                # or we are at a page that directs us.
+                # Check history
+                pass
+        except aiohttp.ClientError:
+            # This might happen if the redirect schema is not http/https
+            # We can inspect the error or just capture it from the history if possible
+            pass
+        except Exception:
+            # If it tries to redirect to msal..., it might fail if aiohttp doesn't support it.
+            # We can disable redirects and follow manually to catch it.
+            pass
+
+        # Manual redirect following to catch custom scheme
+        current_url = start_url
+        code = None
+
+        for _ in range(10):  # Max redirects
+            async with self._session.get(current_url, allow_redirects=False) as resp:
+                if resp.status in (302, 303, 301):
+                    location = resp.headers.get("Location")
+                    if not location:
+                        break
+
+                    if location.startswith(REDIRECT_URI) or "code=" in location:
+                        # Success!
+                        _LOGGER.debug(f"Found redirect with code: {location}")
+                        # Extract code
+                        parsed = urlparse(location)
+                        query = parse_qs(parsed.query)
+                        code = query.get("code", [""])[0]
+                        break
+
+                    current_url = location
+                else:
+                    break
+
+        if not code:
+            raise DimplexAuthError(
+                "Failed to obtain auth code after successful login. Redirect URI might have changed."
+            )
+
+        _LOGGER.debug(f"Got code: {code[:10]}...")
+        await self.exchange_code(code)
+
+    def save_tokens(self, file_path: str) -> None:
+        """Save current tokens to a JSON file."""
+        data = {
+            "access_token": self._access_token,
+            "refresh_token": self._refresh_token,
+            "expires_at": self._expires_at,
+        }
+        with open(file_path, "w") as f:
+            json.dump(data, f, indent=2)
+        _LOGGER.info("Tokens saved to %s", file_path)
+
+    @classmethod
+    def load_tokens(cls, file_path: str) -> Optional[Dict]:
+        """Load tokens from a JSON file."""
+        if not os.path.exists(file_path):
+            return None
+        try:
+            with open(file_path, "r") as f:
+                return json.load(f)
+        except Exception as e:
+            _LOGGER.error("Failed to load tokens from %s: %s", file_path, e)
+            return None

dimplex_controller-0.2.0/dimplex_controller/client.py

@@ -0,0 +1,176 @@
+import logging
+from typing import Dict, List, Optional
+
+import aiohttp
+
+from .auth import AuthManager
+from .const import (
+    BASE_URL,
+    HEADER_APP_NAME,
+    HEADER_APP_VERSION,
+    HEADER_DEVICE_MANUFACTURER,
+    HEADER_DEVICE_MODEL,
+    HEADER_DEVICE_OS,
+    HEADER_DEVICE_VERSION,
+    HEADER_USER_AGENT,
+    HTTP_OK,
+)
+from .exceptions import DimplexApiError, DimplexConnectionError
+from .models import (
+    ApplianceModeSettings,
+    ApplianceStatus,
+    Hub,
+    TimerModeSettings,
+    UserContext,
+    Zone,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class DimplexControl:
+    """Main client for Dimplex Control API."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        refresh_token: Optional[str] = None,
+        access_token: Optional[str] = None,
+        expires_at: float = 0,
+    ):
+        """Initialize the client."""
+        token_data = {}
+        if refresh_token:
+            token_data["refresh_token"] = refresh_token
+        if access_token:
+            token_data["access_token"] = access_token
+        if expires_at:
+            token_data["expires_at"] = expires_at
+
+        self._session = session
+        self.auth = AuthManager(session, token_data)
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if authenticated."""
+        return self.auth.is_authenticated
+
+    async def _request(self, method: str, endpoint: str, **kwargs) -> Dict:
+        """Make an authenticated request."""
+        token = await self.auth.get_access_token()
+        headers = kwargs.pop("headers", {})
+        headers.update(
+            {
+                "Authorization": f"Bearer {token}",
+                "app_name": HEADER_APP_NAME,
+                "app_version": HEADER_APP_VERSION,
+                "app_device_os": HEADER_DEVICE_OS,
+                "device_version": HEADER_DEVICE_VERSION,
+                "device_manufacturer": HEADER_DEVICE_MANUFACTURER,
+                "device_model": HEADER_DEVICE_MODEL,
+                "User-Agent": HEADER_USER_AGENT,
+                "api_version": "1.0",
+                "Accept": "*/*",
+                "Accept-Encoding": "gzip, deflate, br",
+                "Content-Type": "application/json",
+            }
+        )
+
+        url = f"{BASE_URL}{endpoint}"
+        try:
+            async with self._session.request(method, url, headers=headers, **kwargs) as resp:
+                if resp.status != HTTP_OK:
+                    text = await resp.text()
+                    _LOGGER.error("API request failed: %s - %s", resp.status, text)
+                    raise DimplexApiError(resp.status, text)
+
+                # API might return empty body for some calls
+                if resp.content_length == 0:
+                    return {}
+                return await resp.json()
+        except aiohttp.ClientError as e:
+            _LOGGER.error("Connection error during API request: %s", e)
+            raise DimplexConnectionError(f"Connection error: {e}") from e
+
+    async def get_hubs(self) -> List[Hub]:
+        """Get all hubs for the user."""
+        data = await self._request("GET", "/Hubs/GetUserHubs")
+        # Log analysis shows list of objects
+        return [Hub(**h) for h in data]
+
+    async def get_hub_zones(self, hub_id: str) -> List[Zone]:
+        """Get zones and appliances for a hub."""
+        data = await self._request("GET", "/Zones/GetZonesAndAppliancesForHubId", params={"HubId": hub_id})
+        return [Zone(**z) for z in data]
+
+    async def get_zone(self, hub_id: str, zone_id: str) -> Zone:
+        """Get details for a specific zone."""
+        payload = {"HubId": hub_id, "ZoneId": zone_id}
+        data = await self._request("POST", "/Zones/GetZone", json=payload)
+        return Zone(**data)
+
+    async def get_appliance_overview(self, hub_id: str, appliance_ids: List[str]) -> List[ApplianceStatus]:
+        """Get status overview for specific appliances."""
+        payload = {"HubId": hub_id, "ApplianceIds": appliance_ids}
+        data = await self._request("POST", "/RemoteControl/GetApplianceOverview", json=payload)
+        return [ApplianceStatus(**item) for item in data]
+
+    async def get_user_context(self) -> UserContext:
+        """Get user profile/context."""
+        data = await self._request("GET", "/Identity/GetUserContext")
+        return UserContext(**data)
+
+    async def get_appliance_features(self, hub_id: str, appliance_id: str) -> TimerModeSettings:
+        """Get timer details (and mode) for an appliance."""
+        # In the logs, this endpoint returns current mode and timer profiles
+        payload = {
+            "HubId": hub_id,
+            "ApplianceId": appliance_id,
+            "TimerMode": 0,  # Required field in request, value doesn't seem to matter for fetching?
+        }
+        data = await self._request("POST", "/RemoteControl/GetTimerModeDetailsForAppliance", json=payload)
+        return TimerModeSettings(**data)
+
+    async def set_mode(self, hub_id: str, appliance_id: str, mode: int) -> None:
+        """Set the operation mode.
+
+        Modes (inferred):
+        0: Manual? (User Timer?)
+        1: Manual
+        2: Frost Protection
+        3: Off?
+        """
+        # We need to fetch current settings first to preserve other fields if API requires full object
+        current = await self.get_appliance_features(hub_id, appliance_id)
+        current.TimerMode = mode
+
+        payload = {"TimerModeSettings": current.dict()}
+
+        await self._request("POST", "/RemoteControl/SetTimerMode", json=payload)
+
+    async def set_target_temperature(self, hub_id: str, appliance_id: str, temp: float) -> None:
+        """Set target temperature.
+
+        WARNING: The logs show setting temperature involves updating the 'TimerPeriods' for the current mode.
+        This client might need to be smarter about which period to update (current active one).
+        For now, this is a placeholder/advanced TODO.
+        """
+        _LOGGER.warning("set_target_temperature not fully implemented - requires complex schedule manipulation")
+        pass
+
+    async def set_appliance_mode(
+        self, hub_id: str, appliance_ids: List[str], mode_settings: ApplianceModeSettings
+    ) -> None:
+        """Set appliance mode (Boost, Away, etc.)."""
+        payload = {"Settings": mode_settings.dict(), "HubId": hub_id, "ApplianceIds": appliance_ids}
+        await self._request("POST", "/RemoteControl/SetApplianceMode", json=payload)
+
+    async def set_eco_start(self, hub_id: str, appliance_ids: List[str], enable: bool) -> None:
+        """Enable/Disable EcoStart."""
+        payload = {"Enable": enable, "HubId": hub_id, "ApplianceIds": appliance_ids}
+        await self._request("POST", "/RemoteControl/SetEcoStart", json=payload)
+
+    async def set_open_window_detection(self, hub_id: str, appliance_ids: List[str], enable: bool) -> None:
+        """Enable/Disable Open Window Detection."""
+        payload = {"Enable": enable, "HubId": hub_id, "ApplianceIds": appliance_ids}
+        await self._request("POST", "/RemoteControl/SetOpenWindowDetection", json=payload)

dimplex_controller-0.2.0/dimplex_controller/const.py

@@ -0,0 +1,21 @@
+"""Constants for Dimplex Controller."""
+
+HTTP_OK = 200
+
+# API Endpoints
+BASE_URL = "https://mobileapi.gdhv-iot.com/api"
+AUTH_URL = "https://gdhvb2c.b2clogin.com/tfp/gdhvb2c.onmicrosoft.com/B2C_1A_DimplexControlSignupSignin/oauth2/v2.0"
+
+# Headers
+HEADER_USER_AGENT = "Dimplex Control/79810 CFNetwork/3860.300.31 Darwin/25.2.0"
+HEADER_APP_NAME = "DimplexControl"
+HEADER_APP_VERSION = "2.21.0"
+HEADER_DEVICE_OS = "iOS"
+HEADER_DEVICE_VERSION = "26.2.1"
+HEADER_DEVICE_MANUFACTURER = "Apple"
+HEADER_DEVICE_MODEL = "iPhone18,1"
+
+# Auth
+CLIENT_ID = "6c983ca3-506e-4933-8993-0e18e6a24bbd"
+SCOPE = "https://gdhvb2c.onmicrosoft.com/Mobile/read offline_access openid profile"
+REDIRECT_URI = "msal6c983ca3-506e-4933-8993-0e18e6a24bbd://auth/"

dimplex_controller-0.2.0/dimplex_controller/exceptions.py

@@ -0,0 +1,22 @@
+"""Exceptions for Dimplex Controller."""
+
+
+class DimplexError(Exception):
+    """Base exception for Dimplex Controller."""
+
+
+class DimplexAuthError(DimplexError):
+    """Exception for authentication errors."""
+
+
+class DimplexApiError(DimplexError):
+    """Exception for API errors."""
+
+    def __init__(self, status: int, message: str):
+        self.status = status
+        self.message = message
+        super().__init__(f"API Error {status}: {message}")
+
+
+class DimplexConnectionError(DimplexError):
+    """Exception for connection errors."""

dimplex_controller-0.2.0/dimplex_controller/models.py

@@ -0,0 +1,99 @@
+from datetime import datetime, time
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Appliance(BaseModel):
+    ApplianceId: str
+    ApplianceType: str
+    ApplianceModel: Optional[str] = None
+    ZoneId: str
+    FriendlyName: str
+    ZoneName: str
+    Icon: Optional[str] = None
+    IconColor: Optional[str] = None
+    InstallationDate: Optional[datetime] = None
+    HasConnectivity: Optional[bool] = None
+
+
+class Zone(BaseModel):
+    ZoneId: str
+    ZoneName: str
+    HubId: str
+    ZoneType: str
+    Appliances: List[Appliance] = Field(default_factory=list)
+
+
+class Hub(BaseModel):
+    HubId: str
+    Name: Optional[str] = Field(None, alias="HubName")
+    FriendlyName: Optional[str] = None
+
+
+class TimerPeriod(BaseModel):
+    DayOfWeek: int
+    StartTime: str  # Kept as str for easy JSON serialization
+    EndTime: str
+    Temperature: float
+
+    @property
+    def start_time_obj(self) -> time:
+        return datetime.strptime(self.StartTime, "%H:%M:%S").time()
+
+    @property
+    def end_time_obj(self) -> time:
+        return datetime.strptime(self.EndTime, "%H:%M:%S").time()
+
+
+class TimerModeSettings(BaseModel):
+    HubId: str
+    ApplianceId: str
+    TimerMode: int
+    TimerPeriods: List[TimerPeriod] = Field(default_factory=list)
+
+
+class UserContext(BaseModel):
+    Id: str
+    EmailAddress: Optional[str] = None
+    Name: Optional[str] = None
+
+
+class ApplianceStatus(BaseModel):
+    """Represents the real-time status of an appliance as returned by GetApplianceOverview."""
+
+    HubId: str
+    ApplianceId: str
+    ZoneId: str
+    StatusTwo: Optional[int] = None
+    ApplianceModes: Optional[int] = None
+    RoomTemperature: Optional[float] = None
+    ActiveSetPointTemperature: Optional[int] = None
+    NormalTemperature: Optional[float] = None
+    AwayDateTime: Optional[str] = None
+    AwayTemperature: Optional[float] = None
+    BoostDuration: Optional[int] = None
+    BoostTemperature: Optional[float] = None
+    OpenWindowEnabled: Optional[bool] = None
+    EcoStartEnabled: Optional[bool] = None
+    SetbackEnabled: Optional[bool] = None
+    SetbackEnabledInStatusFrame: Optional[bool] = None
+    SetbackTemperature: Optional[float] = None
+    ComfortStatus: Optional[bool] = None
+    AvailableHotWater: Optional[float] = None
+    LockStatus: Optional[int] = None
+    ErrorCode: Optional[str] = None
+    WarningCode: Optional[str] = None
+
+
+class ApplianceModeSettings(BaseModel):
+    """Settings used to control appliance modes like Boost or Away."""
+
+    ApplianceModes: int
+    Status: int
+    Temperature: float = 23.0
+    Time: int = 0
+    Date: str = "0001-01-01T00:00:00"
+    StatusTwo: int = 0
+    NumberOfDays: int = 0
+    Frequency: int = 0

dimplex_controller-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[tool.poetry]
+name = "dimplex-controller"
+version = "0.2.0"
+description = "Python client for Dimplex heating controllers (GDHV IoT)"
+authors = ["Kieran Roper"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/KRoperUK/dimplex-controller-py"
+repository = "https://github.com/KRoperUK/dimplex-controller-py"
+keywords = ["dimplex", "heating", "control", "iot", "asyncio"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+]
+packages = [{ include = "dimplex_controller" }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+aiohttp = "^3.9.0"
+pydantic = "^2.0.0"
+beautifulsoup4 = "^4.14.3"
+python-dotenv = "^1.2.1"
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+aresponses = "^3.0.0"
+ruff = "^0.3.0"
+pre-commit = "^3.6.0"
+twine = "^6.2.0"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"