ecohome 0.1.0__tar.gz

ecohome-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2026 Sjors Gielen
+
+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.

ecohome-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: ecohome
+Version: 0.1.0
+Summary: Open-source Python implementation of the New Energy (Batavia Heat) Eco-Home API
+Author: Sjors Gielen
+Author-email: Sjors Gielen <pypi@sjorsgielen.nl>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/sgielen/ecohome
+Project-URL: Issues, https://github.com/sgielen/ecohome/issues
+Description-Content-Type: text/markdown
+
+# ecohome
+
+Open-source Python client and CLI for the [New Energy
+Eco-Home](https://ehome.ne01.com/) heat pump API, which is used by Batavia Heat
+heat pumps in the Netherlands.
+
+## Installation
+
+Requires Python 3.14+. Older versions probably work fine, YMMV.
+
+```
+pip install ecohome
+```
+
+Or from source using [uv](https://github.com/astral-sh/uv):
+
+```
+uv sync
+```
+
+## CLI usage
+
+Credentials can be passed as flags or via environment variables:
+
+```
+export ECOHOME_USER=you@example.com
+export ECOHOME_PASSWORD=yourpassword
+```
+
+After the first successful login, credentials are saved to `~/.ecohome/credentials.json`
+(mode 0600) and reused automatically on subsequent calls.
+
+### Show status
+
+```
+pyecohome status
+```
+
+Example output:
+
+```
+Heating:   off  29.2℃ / 27.6℃  →  40.0℃  (Verwarming)
+Hot water: off  61.5℃  →  65.0℃
+```
+
+Add `--json` for machine-readable output:
+
+```
+pyecohome status --json
+```
+
+```json
+{
+  "heating": {
+    "on": false,
+    "current_temp_main": 29.2,
+    "current_temp_minor": 27.6,
+    "target_temp": 40.0,
+    "mode": "Verwarming"
+  },
+  "hot_water": {
+    "on": false,
+    "current_temp": 61.5,
+    "target_temp": 65.0
+  }
+}
+```
+
+### Control hot water
+
+```
+pyecohome hot-water on
+pyecohome hot-water off
+```
+
+Use `--dry-run` to print the request that would be sent without actually sending it:
+
+```
+pyecohome hot-water on --dry-run
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--username` | Login username (overrides `ECOHOME_USER`) |
+| `--password` | Login password (overrides `ECOHOME_PASSWORD`) |
+| `--device` | Device code to target (auto-selected when you have only one device) |
+| `--dry-run` | Print the outgoing request instead of sending it |
+
+## Python API
+
+```python
+from ecohome.client import EcoHomeClient
+
+client = EcoHomeClient.login("you@example.com", "yourpassword")
+
+# List devices
+devices = client.list_devices()
+device_code = devices[0]["device_code"]
+
+# Current state
+detail = client.get_device_detail(device_code)
+
+# Turn hot water on/off
+client.update_switch_state(device_code, address="1020", value=True)
+
+# Log out (also removes saved credentials)
+client.logout()
+```
+
+## Credentials storage
+
+Credentials (username, user ID, token, session cookie) are stored in
+`~/.ecohome/credentials.json` after a successful login. Pass
+`save_credentials=False` to `EcoHomeClient.login()` to opt out.
+
+## Development
+
+```
+uv sync
+uv run ruff check src/
+```

ecohome-0.1.0/README.md

@@ -0,0 +1,123 @@
+# ecohome
+
+Open-source Python client and CLI for the [New Energy
+Eco-Home](https://ehome.ne01.com/) heat pump API, which is used by Batavia Heat
+heat pumps in the Netherlands.
+
+## Installation
+
+Requires Python 3.14+. Older versions probably work fine, YMMV.
+
+```
+pip install ecohome
+```
+
+Or from source using [uv](https://github.com/astral-sh/uv):
+
+```
+uv sync
+```
+
+## CLI usage
+
+Credentials can be passed as flags or via environment variables:
+
+```
+export ECOHOME_USER=you@example.com
+export ECOHOME_PASSWORD=yourpassword
+```
+
+After the first successful login, credentials are saved to `~/.ecohome/credentials.json`
+(mode 0600) and reused automatically on subsequent calls.
+
+### Show status
+
+```
+pyecohome status
+```
+
+Example output:
+
+```
+Heating:   off  29.2℃ / 27.6℃  →  40.0℃  (Verwarming)
+Hot water: off  61.5℃  →  65.0℃
+```
+
+Add `--json` for machine-readable output:
+
+```
+pyecohome status --json
+```
+
+```json
+{
+  "heating": {
+    "on": false,
+    "current_temp_main": 29.2,
+    "current_temp_minor": 27.6,
+    "target_temp": 40.0,
+    "mode": "Verwarming"
+  },
+  "hot_water": {
+    "on": false,
+    "current_temp": 61.5,
+    "target_temp": 65.0
+  }
+}
+```
+
+### Control hot water
+
+```
+pyecohome hot-water on
+pyecohome hot-water off
+```
+
+Use `--dry-run` to print the request that would be sent without actually sending it:
+
+```
+pyecohome hot-water on --dry-run
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--username` | Login username (overrides `ECOHOME_USER`) |
+| `--password` | Login password (overrides `ECOHOME_PASSWORD`) |
+| `--device` | Device code to target (auto-selected when you have only one device) |
+| `--dry-run` | Print the outgoing request instead of sending it |
+
+## Python API
+
+```python
+from ecohome.client import EcoHomeClient
+
+client = EcoHomeClient.login("you@example.com", "yourpassword")
+
+# List devices
+devices = client.list_devices()
+device_code = devices[0]["device_code"]
+
+# Current state
+detail = client.get_device_detail(device_code)
+
+# Turn hot water on/off
+client.update_switch_state(device_code, address="1020", value=True)
+
+# Log out (also removes saved credentials)
+client.logout()
+```
+
+## Credentials storage
+
+Credentials (username, user ID, token, session cookie) are stored in
+`~/.ecohome/credentials.json` after a successful login. Pass
+`save_credentials=False` to `EcoHomeClient.login()` to opt out.
+
+## Development
+
+```
+uv sync
+uv run ruff check src/
+```

ecohome-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "ecohome"
+version = "0.1.0"
+description = "Open-source Python implementation of the New Energy (Batavia Heat) Eco-Home API"
+readme = "README.md"
+authors = [
+    { name = "Sjors Gielen", email = "pypi@sjorsgielen.nl" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.urls]
+Homepage = "https://github.com/sgielen/ecohome"
+Issues = "https://github.com/sgielen/ecohome/issues"
+
+[project.scripts]
+pyecohome = "ecohome.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.20",
+]
+
+[tool.ruff]
+line-length = 120

ecohome-0.1.0/src/ecohome/cli.py

@@ -0,0 +1,230 @@
+import argparse
+import json as json_module
+import os
+import sys
+
+from ecohome.client import EcoHomeClient, SessionExpiredError
+
+
+def _get_client(args: argparse.Namespace, force_relogin: bool = False) -> EcoHomeClient:
+    username = args.username or os.environ.get("ECOHOME_USER")
+    password = args.password or os.environ.get("ECOHOME_PASSWORD")
+    if not username or not password:
+        print(
+            "Error: provide --username/--password or set ECOHOME_USER/ECOHOME_PASSWORD",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return EcoHomeClient.login(username, password, force_relogin=force_relogin)
+
+
+def _auto_device_code(client: EcoHomeClient, args: argparse.Namespace) -> str:
+    if args.device:
+        return args.device
+    devices = client.list_devices()
+    if not devices:
+        print("Error: no devices found", file=sys.stderr)
+        sys.exit(1)
+    if len(devices) > 1:
+        lines = "\n".join(f"  {d['device_code']}  {d['device_nick_name']}" for d in devices)
+        print(f"Error: multiple devices found, use --device:\n{lines}", file=sys.stderr)
+        sys.exit(1)
+    return devices[0]["device_code"]
+
+
+def _find_card(card_list: list, *, has_modes: bool) -> dict | None:
+    for card in card_list:
+        if (card.get("modeList") is not None) == has_modes:
+            return card
+    return None
+
+
+def _flatten_params(param_list: list) -> list[dict]:
+    """Flatten paramListV3 result to a list of items. type=1 nests items inside modules."""
+    result = []
+    for item in param_list:
+        if "moduleContent" in item:
+            result.extend(item["moduleContent"])
+        else:
+            result.append(item)
+    return result
+
+
+def _usable_params(items: list[dict]) -> list[dict]:
+    """Return items with non-null, non-N/A values, with parsed value and stripped name."""
+    result = []
+    for item in items:
+        raw = item.get("addressValue")
+        if raw is None or raw == "N/A":
+            continue
+        try:
+            value: float | str = float(raw)
+        except (ValueError, TypeError):
+            value = str(raw)
+        result.append({
+            "address": item["address"],
+            "name": (item.get("pointName") or item["address"]).strip(),
+            "value": value,
+            "unit": item.get("unit") or "",
+        })
+    return result
+
+
+def _fmt_param(p: dict) -> str:
+    val = p["value"]
+    return f"{val:g}{p['unit']}" if isinstance(val, float) else f"{val}{p['unit']}"
+
+
+def cmd_status(client: EcoHomeClient, args: argparse.Namespace) -> int:
+    device_code = _auto_device_code(client, args)
+    detail = client.get_device_detail(device_code)
+    unit = detail.get("curUnit", "°C")
+
+    heating = _find_card(detail["cardList"], has_modes=True)
+    hot_water = _find_card(detail["cardList"], has_modes=False)
+
+    sensors = _usable_params(_flatten_params(client.get_param_list(device_code, 0)))
+    operational = _usable_params(_flatten_params(client.get_param_list(device_code, 1)))
+
+    if args.json:
+        output: dict = {}
+        if heating:
+            output["heating"] = {
+                "on": heating["curSwitch"],
+                "current_temp_main": float(heating["curTempMain"]) if heating.get("curTempMain") else None,
+                "current_temp_minor": float(heating["curTempMinor"]) if heating.get("curTempMinor") else None,
+                "target_temp": float(heating["settingTemp"]) if heating.get("settingTemp") else None,
+                "mode": heating["modeList"][0]["modeMeaning"] if heating.get("modeList") else None,
+            }
+        if hot_water:
+            output["hot_water"] = {
+                "on": hot_water["curSwitch"],
+                "current_temp": float(hot_water["curTempMain"]) if hot_water.get("curTempMain") else None,
+                "target_temp": float(hot_water["settingTemp"]) if hot_water.get("settingTemp") else None,
+            }
+        if sensors:
+            output["sensors"] = {
+                p["address"]: {"name": p["name"], "value": p["value"], "unit": p["unit"] or None}
+                for p in sensors
+            }
+        if operational:
+            output["operational"] = {
+                p["address"]: {"name": p["name"], "value": p["value"], "unit": p["unit"] or None}
+                for p in operational
+            }
+        print(json_module.dumps(output, indent=2))
+    else:
+        if heating:
+            state = "on" if heating["curSwitch"] else "off"
+            mode = heating["modeList"][0]["modeMeaning"] if heating.get("modeList") else "unknown"
+            t_main = heating.get("curTempMain", "?")
+            t_minor = heating.get("curTempMinor")
+            t_set = heating.get("settingTemp", "?")
+            temps = f"{t_main}{unit} / {t_minor}{unit}" if t_minor else f"{t_main}{unit}"
+            print(f"Heating:   {state:<3}  {temps}  →  {t_set}{unit}  ({mode})")
+        if hot_water:
+            state = "on" if hot_water["curSwitch"] else "off"
+            t_main = hot_water.get("curTempMain", "?")
+            t_set = hot_water.get("settingTemp", "?")
+            print(f"Hot water: {state:<3}  {t_main}{unit}  →  {t_set}{unit}")
+        if sensors:
+            print("Sensors:")
+            for p in sensors:
+                print(f"  {p['name']}: {_fmt_param(p)}")
+        if operational:
+            print("Operational:")
+            for p in operational:
+                print(f"  {p['name']}: {_fmt_param(p)}")
+
+    return 0
+
+
+def cmd_heating(client: EcoHomeClient, args: argparse.Namespace) -> int:
+    device_code = _auto_device_code(client, args)
+    detail = client.get_device_detail(device_code)
+    card = _find_card(detail["cardList"], has_modes=True)
+    if card is None:
+        print("Error: no heating card found on this device", file=sys.stderr)
+        sys.exit(1)
+    if args.heating_subcommand in ("on", "off"):
+        value = args.heating_subcommand == "on"
+        client.update_switch_state(device_code, card["switchAddress"], value, dry_run=args.dry_run)
+        if not args.dry_run:
+            print(f"Heating {'enabled' if value else 'disabled'}.")
+    elif args.heating_subcommand == "set-temp":
+        client.set_value(device_code, card["settingAddress"], args.value, dry_run=args.dry_run)
+        if not args.dry_run:
+            print(f"Heating target temperature set to {args.value}.")
+    return 0
+
+
+def cmd_hot_water(client: EcoHomeClient, args: argparse.Namespace) -> int:
+    device_code = _auto_device_code(client, args)
+    detail = client.get_device_detail(device_code)
+    card = _find_card(detail["cardList"], has_modes=False)
+    if card is None:
+        print("Error: no hot water card found on this device", file=sys.stderr)
+        sys.exit(1)
+    if args.hw_subcommand in ("on", "off"):
+        value = args.hw_subcommand == "on"
+        client.update_switch_state(device_code, card["switchAddress"], value, dry_run=args.dry_run)
+        if not args.dry_run:
+            print(f"Hot water {'enabled' if value else 'disabled'}.")
+    elif args.hw_subcommand == "set-temp":
+        client.set_value(device_code, card["settingAddress"], args.value, dry_run=args.dry_run)
+        if not args.dry_run:
+            print(f"Hot water target temperature set to {args.value}.")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="pyecohome",
+        description="Control your Eco-Home heat pump from the command line.",
+    )
+    parser.add_argument("--username", default=None, help="Login username (or set ECOHOME_USER)")
+    parser.add_argument("--password", default=None, help="Login password (or set ECOHOME_PASSWORD)")
+    parser.add_argument("--device", default=None, help="Device code (auto-selected if only one exists)")
+    parser.add_argument("--dry-run", action="store_true", help="Print the request instead of sending it")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    status_p = subparsers.add_parser("status", help="Show current temperatures and state")
+    status_p.add_argument("--json", action="store_true", help="Output as JSON")
+
+    h_p = subparsers.add_parser("heating", help="Control heating")
+    h_sub = h_p.add_subparsers(dest="heating_subcommand", required=True)
+    h_sub.add_parser("on", help="Enable heating")
+    h_sub.add_parser("off", help="Disable heating")
+    h_temp_p = h_sub.add_parser("set-temp", help="Set heating target temperature")
+    h_temp_p.add_argument("value", type=int, help="Target temperature")
+
+    hw_p = subparsers.add_parser("hot-water", help="Control hot water")
+    hw_sub = hw_p.add_subparsers(dest="hw_subcommand", required=True)
+    hw_sub.add_parser("on", help="Enable hot water")
+    hw_sub.add_parser("off", help="Disable hot water")
+    hw_temp_p = hw_sub.add_parser("set-temp", help="Set hot water target temperature")
+    hw_temp_p.add_argument("value", type=int, help="Target temperature")
+
+    args = parser.parse_args()
+
+    for attempt in range(2):
+        client = _get_client(args, force_relogin=(attempt > 0))
+        try:
+            if args.command == "status":
+                return cmd_status(client, args)
+            if args.command == "heating":
+                return cmd_heating(client, args)
+            if args.command == "hot-water":
+                return cmd_hot_water(client, args)
+            return 0
+        except SessionExpiredError:
+            if attempt == 0:
+                continue
+            raise
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ecohome-0.1.0/src/ecohome/client.py

@@ -0,0 +1,287 @@
+import asyncio
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+_CLOUDSERVICE_BASE_URL = "https://ehome.ne01.com/cloudservice/api/app"
+_CRM_BASE_URL = "https://ehome.ne01.com/crmservice/api/app"
+_CREDENTIALS_FILE = Path.home() / ".ecohome" / "credentials.json"
+
+_HEADERS = {
+    "Content-Type": "application/json;charset=UTF-8",
+    "Connection": "keep-alive",
+    "Accept": "*/*",
+    "app-id-type": "0",
+    "User-Agent": (
+        "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) "
+        "AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 "
+        "Html5Plus/1.0 (Immersed/20) uni-app"
+    ),
+    "time-zone": "Europe/Berlin",
+    "Accept-Language": "nl-NL,nl;q=0.9",
+}
+
+
+def _load_credentials() -> dict[str, Any]:
+    if not _CREDENTIALS_FILE.exists():
+        return {}
+    return json.loads(_CREDENTIALS_FILE.read_text())
+
+
+def _save_credentials(creds: dict[str, Any]) -> None:
+    _CREDENTIALS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _CREDENTIALS_FILE.write_text(json.dumps(creds, indent=2))
+    _CREDENTIALS_FILE.chmod(0o600)
+
+
+class SessionExpiredError(RuntimeError):
+    pass
+
+
+def _raise_on_error(data: dict[str, Any], endpoint: str) -> None:
+    if "errorCode" in data:  # crmservice: camelCase, int 200 for success
+        if data["errorCode"] != 200:
+            raise RuntimeError(f"{endpoint} failed: {data['errorCode']} {data.get('errorMsg', 'Unknown error')}")
+    elif "error_code" in data:  # cloudservice: snake_case, string "0" for success
+        if data["error_code"] != "0":
+            raise RuntimeError(f"{endpoint} failed: {data['error_code']} {data.get('error_msg', 'Unknown error')}")
+    elif "sub_code" in data:  # gateway/auth error, e.g. sub_code="-100" means session expired
+        if data["sub_code"] == "-100":
+            raise SessionExpiredError(f"{endpoint}: session expired")
+        raise RuntimeError(f"{endpoint} failed: sub_code={data['sub_code']} {data.get('sub_msg', 'Unknown error')}")
+    else:
+        raise RuntimeError(f"{endpoint} failed: unrecognized response format: {data}")
+
+
+class AsyncEcoHomeClient:
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        cookie: dict[str, str] | None = None,
+        user_id: str | None = None,
+        username: str | None = None,
+    ):
+        self._token = token
+        self._cookie: dict[str, str] = cookie or {}
+        self._user_id = user_id
+        self._username = username
+
+    @classmethod
+    async def login(
+        cls,
+        username: str,
+        password: str,
+        save_credentials: bool = True,
+        force_relogin: bool = False,
+    ) -> "AsyncEcoHomeClient":
+        """Return an authenticated client, reusing stored credentials when available."""
+        creds: dict[str, Any] = _load_credentials() if save_credentials else {}
+        if not force_relogin and username in creds:
+            stored = creds[username]
+            client = cls(
+                token=stored["x_token"],
+                cookie=stored["cookie"],
+                user_id=stored["user_id"],
+                username=username,
+            )
+            if await client.is_logged_in():
+                return client
+
+        password_md5 = hashlib.md5(password.encode()).hexdigest()
+
+        async with httpx.AsyncClient() as http:
+            response = await http.post(
+                f"{_CLOUDSERVICE_BASE_URL}/user/login.json",
+                params={"lang": "nl_NL"},
+                headers=_HEADERS,
+                json={"user_name": username, "password": password_md5, "type": 2},
+            )
+        response.raise_for_status()
+
+        data = response.json()
+        _raise_on_error(data, "login")
+
+        result = data["object_result"]
+        user_id = str(result["user_id"])
+        x_token = result["x-token"]
+        cookie = dict(response.cookies)
+
+        if save_credentials:
+            creds[username] = {
+                "user_id": user_id,
+                "x_token": x_token,
+                "cookie": cookie,
+            }
+            _save_credentials(creds)
+
+        return cls(token=x_token, cookie=cookie, user_id=user_id, username=username)
+
+    async def is_logged_in(self) -> bool:
+        """Do an API request to see if the user is logged in."""
+        async with self._http() as http:
+            response = await http.get(
+                f"{_CLOUDSERVICE_BASE_URL}/user/getUserInfo.json",
+                params={"lang": "nl_NL"},
+                headers=self._auth_headers(),
+            )
+        try:
+            response.raise_for_status()
+            _raise_on_error(response.json(), "getUserInfo")
+            return True
+        except (httpx.HTTPStatusError, RuntimeError):
+            return False
+
+    async def logout(self) -> None:
+        """Log out and remove stored credentials for this user."""
+        async with self._http() as http:
+            response = await http.post(
+                f"{_CLOUDSERVICE_BASE_URL}/user/logout.json",
+                params={"lang": "nl_NL"},
+                headers=self._auth_headers(),
+                json={"from_user": self._user_id},
+            )
+        response.raise_for_status()
+
+        if self._username:
+            creds = _load_credentials()
+            creds.pop(self._username, None)
+            _save_credentials(creds)
+
+        self._token = None
+        self._cookie = {}
+        self._user_id = None
+        self._username = None
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self._token is None:
+            raise RuntimeError("Not authenticated")
+        return {**_HEADERS, "x-token": self._token}
+
+    def _http(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(cookies=self._cookie)
+
+    async def list_devices(self, page_size: int = 1000) -> list[dict[str, Any]]:
+        async with self._http() as http:
+            response = await http.post(
+                f"{_CLOUDSERVICE_BASE_URL}/device/deviceList.json",
+                params={"lang": "nl_NL"},
+                headers=self._auth_headers(),
+                json={"page_index": "1", "page_size": str(page_size)},
+            )
+        response.raise_for_status()
+        data = response.json()
+        _raise_on_error(data, "deviceList")
+        return data["object_result"]
+
+    async def get_device_base_info(self, device_code: str) -> dict[str, Any]:
+        async with self._http() as http:
+            response = await http.post(
+                f"{_CLOUDSERVICE_BASE_URL}/deviceInfo/getDeviceBaseInfo.json",
+                params={"lang": "nl_NL"},
+                headers=self._auth_headers(),
+                json={"device_code": device_code},
+            )
+        response.raise_for_status()
+        data = response.json()
+        _raise_on_error(data, "getDeviceBaseInfo")
+        return data["object_result"]
+
+    async def get_device_detail(self, device_code: str) -> dict[str, Any]:
+        async with self._http() as http:
+            response = await http.post(
+                f"{_CRM_BASE_URL}/deviceInfo/getDeviceDetailV3",
+                params={"lang": "nl_NL"},
+                headers=self._auth_headers(),
+                json={"deviceCode": device_code},
+            )
+        response.raise_for_status()
+        data = response.json()
+        _raise_on_error(data, "getDeviceDetailV3")
+        return data["objectResult"]
+
+    async def get_param_list(self, device_code: str, param_type: int) -> list[dict[str, Any]]:
+        """Return paramListV3 for the given type: 0=sensors, 1=operational, 2=settings."""
+        async with self._http() as http:
+            response = await http.post(
+                f"{_CRM_BASE_URL}/deviceInfo/paramListV3",
+                params={"lang": "nl_NL"},
+                headers=self._auth_headers(),
+                json={"deviceCode": device_code, "type": param_type, "isAutoRefresh": False},
+            )
+        response.raise_for_status()
+        data = response.json()
+        _raise_on_error(data, "paramListV3")
+        return data["objectResult"]
+
+    async def update_switch_state(self, device_code: str, address: str, value: bool, dry_run: bool = False) -> None:
+        url = f"{_CLOUDSERVICE_BASE_URL}/deviceInfo/updateSwitchSate.json"
+        body = {"device_code": device_code, "address": address, "value": value}
+        if dry_run:
+            print(f"[dry-run] POST {url}?lang=nl_NL")
+            print(json.dumps(body, indent=2))
+            return
+        async with self._http() as http:
+            response = await http.post(url, params={"lang": "nl_NL"}, headers=self._auth_headers(), json=body)
+        response.raise_for_status()
+        data = response.json()
+        _raise_on_error(data, "updateSwitchState")
+
+    async def set_value(self, device_code: str, address: str, value: int, dry_run: bool = False) -> None:
+        url = f"{_CLOUDSERVICE_BASE_URL}/deviceInfo/controlOfValue.json"
+        body = {"device_code": device_code, "address": address, "value": value}
+        if dry_run:
+            print(f"[dry-run] POST {url}?lang=nl_NL")
+            print(json.dumps(body, indent=2))
+            return
+        async with self._http() as http:
+            response = await http.post(url, params={"lang": "nl_NL"}, headers=self._auth_headers(), json=body)
+        response.raise_for_status()
+        data = response.json()
+        _raise_on_error(data, "controlOfValue")
+
+
+class EcoHomeClient:
+    """Synchronous wrapper around AsyncEcoHomeClient."""
+
+    def __init__(self, async_client: AsyncEcoHomeClient):
+        self._async = async_client
+
+    @classmethod
+    def login(
+        cls,
+        username: str,
+        password: str,
+        save_credentials: bool = True,
+        force_relogin: bool = False,
+    ) -> "EcoHomeClient":
+        """Return an authenticated client, reusing stored credentials when available."""
+        return cls(asyncio.run(AsyncEcoHomeClient.login(username, password, save_credentials, force_relogin)))
+
+    def is_logged_in(self) -> bool:
+        return asyncio.run(self._async.is_logged_in())
+
+    def logout(self) -> None:
+        asyncio.run(self._async.logout())
+
+    def list_devices(self, page_size: int = 1000) -> list[dict[str, Any]]:
+        return asyncio.run(self._async.list_devices(page_size))
+
+    def get_device_base_info(self, device_code: str) -> dict[str, Any]:
+        return asyncio.run(self._async.get_device_base_info(device_code))
+
+    def get_device_detail(self, device_code: str) -> dict[str, Any]:
+        return asyncio.run(self._async.get_device_detail(device_code))
+
+    def get_param_list(self, device_code: str, param_type: int) -> list[dict[str, Any]]:
+        return asyncio.run(self._async.get_param_list(device_code, param_type))
+
+    def update_switch_state(self, device_code: str, address: str, value: bool, dry_run: bool = False) -> None:
+        asyncio.run(self._async.update_switch_state(device_code, address, value, dry_run))
+
+    def set_value(self, device_code: str, address: str, value: int, dry_run: bool = False) -> None:
+        asyncio.run(self._async.set_value(device_code, address, value, dry_run))