Merge pull request #701 from robbinjanssen/perf/wg5-zone-control

Fetch WG5 thermostat control data per zone

Author: robbinjanssen

ojmicroline_thermostat/wg5.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from copy import deepcopy
 from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Any
 
@@ -28,6 +29,9 @@
 # Renew the access token this long before it expires.
 TOKEN_REFRESH_MARGIN = timedelta(seconds=30)
 
+# Number of thermostats requested per page of a zone.
+ZONE_PAGE_SIZE = 100
+
 WG5_SCOPES = (
     "ugw.zones ugw.users ugw.profile ugw.buildings ugw.schedules "
     "ugw.thermostats ugw.firmware ugw.linking openid role offline_access"
@@ -152,12 +156,14 @@ async def _auth_request(
         uri: str,
         *,
         method: str = "GET",
+        params: dict[str, Any] | None = None,
         body: dict[str, Any] | None = None,
     ) -> Any:
         """Make an authenticated request with Bearer token."""
         return await self.request(
             uri,
             method=method,
+            params=params,
             body=body,
             headers={"Authorization": f"Bearer {self._access_token}"},
         )
@@ -167,28 +173,51 @@ async def _is_away_active(self, building_id: str) -> bool:
         data = await self._auth_request(f"awaymode/{building_id}")
         return "data" in data
 
+    async def _get_zone_control(self, zone_id: str) -> list[dict[str, Any]]:
+        """Fetch the control data of all thermostats in a zone.
+
+        This returns the same data as `thermostats/{id}/control` for every
+        thermostat in the zone, so a single request covers the whole zone.
+        """
+        thermostats: list[dict[str, Any]] = []
+        page_number = 0
+        while True:
+            data = await self._auth_request(
+                f"zones/{zone_id}/control/thermostats",
+                params={"pageNumber": page_number, "pageSize": ZONE_PAGE_SIZE},
+            )
+            thermostats.extend(data["data"])
+            page_number += 1
+            if page_number >= data.get("page", {}).get("totalPages", 1):
+                return thermostats
+
+    async def _get_schedule(
+        self,
+        schedule_id: str | None,
+        schedules: dict[str, dict[str, Any] | None],
+    ) -> dict[str, Any] | None:
+        """Fetch a schedule, once per update for thermostats sharing it."""
+        if not schedule_id:
+            return None
+        if schedule_id not in schedules:
+            resp = await self._auth_request(f"schedules/{schedule_id}")
+            schedules[schedule_id] = resp.get("data")
+        # Every thermostat gets its own copy of a shared schedule.
+        return deepcopy(schedules[schedule_id])
+
     async def _fetch_thermostat(
         self,
-        thermostat_id: str,
+        control_data: dict[str, Any],
         building_id: str,
         zone_name: str,
+        schedules: dict[str, dict[str, Any] | None],
         *,
         away_active: bool,
     ) -> Thermostat:
-        """Fetch and enrich a single thermostat."""
-        control_data = await self._auth_request(
-            f"thermostats/{thermostat_id}/control",
-        )
-        detail_data = await self._auth_request(
-            f"thermostats/{thermostat_id}",
-        )
-        schedule_id = control_data["data"].get("scheduleData", {}).get("scheduleId")
-        schedule_data = None
-        if schedule_id:
-            resp = await self._auth_request(f"schedules/{schedule_id}")
-            schedule_data = resp.get("data")
+        """Enrich the control data of a thermostat with its details."""
+        detail_data = await self._auth_request(f"thermostats/{control_data['id']}")
         thermostat = Thermostat.from_wg5_json(
-            control_data["data"],
+            control_data,
             building_id=building_id,
             zone_name=zone_name,
             away_active=away_active,
@@ -201,25 +230,30 @@ async def _fetch_thermostat(
         room = readouts.get("roomTemperature")
         if room is not None:
             thermostat.temperature_room = round(float(room) * 100)
-        thermostat.schedule = schedule_data
+        thermostat.schedule = await self._get_schedule(
+            control_data.get("scheduleData", {}).get("scheduleId"), schedules
+        )
         return thermostat
 
     async def get_thermostats(self) -> list[Thermostat]:
         """Fetch all thermostats across all buildings."""
         buildings_data = await self._auth_request("buildings")
         thermostats: list[Thermostat] = []
+        schedules: dict[str, dict[str, Any] | None] = {}
 
         for building in buildings_data["data"]:
             building_id = building["id"]
             away_active = await self._is_away_active(building_id)
             tree_data = await self._auth_request(f"buildings/{building_id}/tree")
             for zone in tree_data["data"]["zones"]:
-                zone_name = zone["name"]
-                for thermostat_stub in zone["thermostats"]:
+                if not zone["thermostats"]:
+                    continue
+                for control_data in await self._get_zone_control(zone["id"]):
                     thermostat = await self._fetch_thermostat(
-                        thermostat_stub["id"],
+                        control_data,
                         building_id,
-                        zone_name,
+                        zone["name"],
+                        schedules,
                         away_active=away_active,
                     )
                     thermostats.append(thermostat)

tests/fixtures/wg5_zone_thermostats.json

@@ -0,0 +1,48 @@
+{
+  "page": {
+    "total": 1,
+    "totalPages": 1,
+    "size": 100,
+    "number": 0
+  },
+  "data": [
+    {
+      "id": "2cb3e6c5-8cf8-4e7e-943a-42618c34a506",
+      "zoneId": "ae85d8fc-1b4a-445a-bdf1-05f970fc3da4",
+      "name": "Bathroom",
+      "createdDate": "2026-04-05T11:29:17Z",
+      "currentTemperature": 19,
+      "currentTemperatureFahrenheit": 66,
+      "minimumPossibleSetPoint": 5,
+      "maximumPossibleSetPoint": 40,
+      "isOnline": true,
+      "isAdaptiveHeatingActive": false,
+      "errorFlags": "NoErrors",
+      "hasError": false,
+      "isOpenWindowDetected": false,
+      "isHeatRelayActive": true,
+      "isFrostProtectionEnabled": true,
+      "frostProtectionTemperature": 5,
+      "isFollowingZone": false,
+      "mode": {
+        "isInStandby": false,
+        "isAwayActive": false,
+        "fallbackMode": "Manual",
+        "manualSetpoint": 27.78,
+        "changeTimestamp": "2026-04-13T23:40:43Z"
+      },
+      "scheduleData": {
+        "scheduleId": "f9aac20b-4e45-415b-9f56-e53014ee8639",
+        "scheduleName": "Default Schedule",
+        "currentSetPoint": 23
+      },
+      "sensorApplication": "Floor",
+      "setpoint": 27.78,
+      "changeTimestamp": "2026-04-13T23:40:43Z"
+    }
+  ],
+  "status": {
+    "code": "OK",
+    "traceId": "3bbdb398bee4254f0801119ffe38a07c"
+  }
+}

tests/test_wg5.py

@@ -138,7 +138,7 @@ async def test_login_skips_when_token_valid(aresponses: ResponsesMockServer) ->
 
 @pytest.mark.asyncio
 async def test_get_thermostats(aresponses: ResponsesMockServer) -> None:
-    """Test fetching thermostats through the buildings->tree->control flow."""
+    """Test fetching thermostats through the buildings->tree->zone flow."""
     _add_login_response(aresponses)
     aresponses.add(
         "ojmicroline.test.host",
@@ -172,12 +172,12 @@ async def test_get_thermostats(aresponses: ResponsesMockServer) -> None:
     )
     aresponses.add(
         "ojmicroline.test.host",
-        "/thermostats/2cb3e6c5-8cf8-4e7e-943a-42618c34a506/control",
+        "/zones/ae85d8fc-1b4a-445a-bdf1-05f970fc3da4/control/thermostats",
         "GET",
         Response(
             status=200,
             headers={"Content-Type": "application/json"},
-            text=load_fixtures("wg5_thermostat_control.json"),
+            text=load_fixtures("wg5_zone_thermostats.json"),
         ),
     )
     aresponses.add(
@@ -263,16 +263,16 @@ async def test_get_thermostats_no_schedule_no_readouts(
         ),
     )
     # Control data with no scheduleId
-    control_data = json.loads(load_fixtures("wg5_thermostat_control.json"))
-    control_data["data"]["scheduleData"] = {}
+    zone_data = json.loads(load_fixtures("wg5_zone_thermostats.json"))
+    zone_data["data"][0]["scheduleData"] = {}
     aresponses.add(
         "ojmicroline.test.host",
-        "/thermostats/2cb3e6c5-8cf8-4e7e-943a-42618c34a506/control",
+        "/zones/ae85d8fc-1b4a-445a-bdf1-05f970fc3da4/control/thermostats",
         "GET",
         Response(
             status=200,
             headers={"Content-Type": "application/json"},
-            text=json.dumps(control_data),
+            text=json.dumps(zone_data),
         ),
     )
     # Detail data with no readout temperatures
@@ -302,6 +302,134 @@ async def test_get_thermostats_no_schedule_no_readouts(
         assert thermostat.temperature_room is None
 
 
+ZONE_ID = "ae85d8fc-1b4a-445a-bdf1-05f970fc3da4"
+BUILDING_ID = "57dc7778-4ed3-4382-9e89-5cf2e0bc0f8a"
+SCHEDULE_ID = "f9aac20b-4e45-415b-9f56-e53014ee8639"
+
+
+def _json_response(data: object) -> Response:
+    """Return a JSON response for aresponses."""
+    return Response(
+        status=200,
+        headers={"Content-Type": "application/json"},
+        text=json.dumps(data),
+    )
+
+
+def _add_building_responses(
+    aresponses: ResponsesMockServer, tree: dict[str, object]
+) -> None:
+    """Add the login, buildings, away mode and tree responses."""
+    _add_login_response(aresponses)
+    aresponses.add(
+        "ojmicroline.test.host",
+        "/buildings",
+        "GET",
+        _json_response(json.loads(load_fixtures("wg5_buildings.json"))),
+    )
+    aresponses.add(
+        "ojmicroline.test.host",
+        f"/awaymode/{BUILDING_ID}",
+        "GET",
+        _json_response({"status": {"code": "OK"}}),
+    )
+    aresponses.add(
+        "ojmicroline.test.host",
+        f"/buildings/{BUILDING_ID}/tree",
+        "GET",
+        _json_response(tree),
+    )
+
+
+def _zone_thermostat(thermostat_id: str) -> dict[str, object]:
+    """Return the zone control data of a thermostat with the given ID."""
+    data: dict[str, object] = json.loads(load_fixtures("wg5_zone_thermostats.json"))[
+        "data"
+    ][0]
+    data["id"] = thermostat_id
+    return data
+
+
+@pytest.mark.asyncio
+async def test_get_thermostats_zone_pages_and_shared_schedule(
+    aresponses: ResponsesMockServer,
+) -> None:
+    """Test fetching a zone over multiple pages, with a shared schedule."""
+    tree = json.loads(load_fixtures("wg5_building_tree.json"))
+    _add_building_responses(aresponses, tree)
+
+    page_numbers: list[str] = []
+    pages = [["thermostat-1", "thermostat-2"], ["thermostat-3"]]
+
+    async def zone_handler(request: web.BaseRequest) -> Response:
+        assert request.query["pageSize"] == "100"
+        page_number = int(request.query["pageNumber"])
+        page_numbers.append(request.query["pageNumber"])
+        return _json_response(
+            {
+                "page": {"total": 3, "totalPages": 2, "size": 100},
+                "data": [_zone_thermostat(tid) for tid in pages[page_number]],
+                "status": {"code": "OK"},
+            }
+        )
+
+    for _ in pages:
+        aresponses.add(
+            "ojmicroline.test.host",
+            f"/zones/{ZONE_ID}/control/thermostats",
+            "GET",
+            zone_handler,
+        )
+    detail = json.loads(load_fixtures("wg5_thermostat_detail.json"))
+    for thermostat_id in ("thermostat-1", "thermostat-2", "thermostat-3"):
+        aresponses.add(
+            "ojmicroline.test.host",
+            f"/thermostats/{thermostat_id}",
+            "GET",
+            _json_response(detail),
+        )
+    # The thermostats share one schedule, which is only fetched once.
+    aresponses.add(
+        "ojmicroline.test.host",
+        f"/schedules/{SCHEDULE_ID}",
+        "GET",
+        _json_response(json.loads(load_fixtures("wg5_schedule.json"))),
+    )
+
+    async with aiohttp.ClientSession() as session:
+        client = OJMicroline(api=_make_api(), session=session)
+        thermostats = await client.get_thermostats()
+
+    # Every route was used exactly once and no other requests were made.
+    aresponses.assert_no_unused_routes()
+    aresponses.assert_all_requests_matched()
+    assert page_numbers == ["0", "1"]
+    assert [t.serial_number for t in thermostats] == [
+        "thermostat-1",
+        "thermostat-2",
+        "thermostat-3",
+    ]
+    assert all(t.schedule is not None for t in thermostats)
+    # Every thermostat has its own copy of the shared schedule.
+    assert thermostats[0].schedule is not thermostats[1].schedule
+
+
+@pytest.mark.asyncio
+async def test_get_thermostats_skips_empty_zone(
+    aresponses: ResponsesMockServer,
+) -> None:
+    """Test that zones without thermostats are not requested."""
+    tree = json.loads(load_fixtures("wg5_building_tree.json"))
+    tree["data"]["zones"][0]["thermostats"] = []
+    _add_building_responses(aresponses, tree)
+
+    async with aiohttp.ClientSession() as session:
+        client = OJMicroline(api=_make_api(), session=session)
+        assert await client.get_thermostats() == []
+
+    aresponses.assert_plan_strictly_followed()
+
+
 @pytest.mark.asyncio
 async def test_get_energy_usage_no_building_id() -> None:
     """Test energy usage returns empty list when building_id is missing."""