aiohomematic 2025.10.3__tar.gz → 2025.10.5__tar.gz

{aiohomematic-2025.10.3 → aiohomematic-2025.10.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiohomematic
-Version: 2025.10.3
+Version: 2025.10.5
 Summary: Homematic interface for Home Assistant running on Python 3.
 Home-page: https://github.com/sukramj/aiohomematic
 Author-email: SukramJ <sukramj@icloud.com>, Daniel Perna <danielperna84@gmail.com>

{aiohomematic-2025.10.3 → aiohomematic-2025.10.5}/aiohomematic/async_support.py

@@ -15,7 +15,8 @@ from typing import Any, Final, cast
 
 from aiohomematic.const import BLOCK_LOG_TIMEOUT
 from aiohomematic.exceptions import AioHomematicException
-from aiohomematic.support import debug_enabled, extract_exc_args
+import aiohomematic.support as hms
+from aiohomematic.support import extract_exc_args
 
 _LOGGER: Final = logging.getLogger(__name__)
 
@@ -46,7 +47,13 @@ class Looper:
                     _LOGGER.warning("Shutdown timeout reached; task still pending: %s", task)
                 break
 
-            await self._await_and_log_pending(pending=tasks)
+            pending_after_wait = await self._await_and_log_pending(pending=tasks, deadline=deadline)
+
+            # If deadline has been reached and tasks are still pending, log and break
+            if deadline is not None and monotonic() >= deadline and pending_after_wait:
+                for task in pending_after_wait:
+                    _LOGGER.warning("Shutdown timeout reached; task still pending: %s", task)
+                break
 
             if start_time is None:
                 # Avoid calling monotonic() until we know
@@ -63,16 +70,35 @@ class Looper:
                 for task in tasks:
                     _LOGGER.debug("Waiting for task: %s", task)
 
-    async def _await_and_log_pending(self, *, pending: Collection[asyncio.Future[Any]]) -> None:
-        """Await and log tasks that take a long time."""
-        wait_time = 0
-        while pending:
-            _, pending = await asyncio.wait(pending, timeout=BLOCK_LOG_TIMEOUT)
-            if not pending:
-                return
-            wait_time += BLOCK_LOG_TIMEOUT
-            for task in pending:
+    async def _await_and_log_pending(
+        self, *, pending: Collection[asyncio.Future[Any]], deadline: float | None
+    ) -> set[asyncio.Future[Any]]:
+        """
+        Await and log tasks that take a long time, respecting an optional deadline.
+
+        Returns the set of pending tasks if the deadline has been reached (or zero timeout),
+        allowing the caller to decide about timeout logging. Returns an empty set if no tasks are pending.
+        """
+        wait_time = 0.0
+        pending_set: set[asyncio.Future[Any]] = set(pending)
+        while pending_set:
+            if deadline is None:
+                timeout = BLOCK_LOG_TIMEOUT
+            else:
+                remaining = int(max(0.0, deadline - monotonic()))
+                if (timeout := min(BLOCK_LOG_TIMEOUT, remaining)) == 0.0:
+                    # Deadline reached; return current pending to caller for warning log
+                    return pending_set
+            done, still_pending = await asyncio.wait(pending_set, timeout=timeout)
+            if not (pending_set := set(still_pending)):
+                return set()
+            wait_time += timeout
+            for task in pending_set:
                 _LOGGER.debug("Waited %s seconds for task: %s", wait_time, task)
+            # If the deadline was reached during the wait, let caller handle warning
+            if deadline is not None and monotonic() >= deadline:
+                return pending_set
+        return set()
 
     def create_task(self, *, target: Coroutine[Any, Any, Any], name: str) -> None:
         """Add task to the executor pool."""
@@ -134,7 +160,12 @@ def cancelling(*, task: asyncio.Future[Any]) -> bool:
 
 
 def loop_check[**P, R](func: Callable[P, R]) -> Callable[P, R]:
-    """Annotation to mark method that must be run within the event loop."""
+    """
+    Annotation to mark method that must be run within the event loop.
+
+    Always wraps the function, but only performs loop checks when debug is enabled.
+    This allows tests to monkeypatch aiohomematic.support.debug_enabled at runtime.
+    """
 
     _with_loop: set = set()
 
@@ -143,17 +174,22 @@ def loop_check[**P, R](func: Callable[P, R]) -> Callable[P, R]:
         """Wrap loop check."""
         return_value = func(*args, **kwargs)
 
-        try:
-            asyncio.get_running_loop()
-            loop_running = True
-        except Exception:
-            loop_running = False
-
-        if not loop_running and func not in _with_loop:
-            _with_loop.add(func)
-            _LOGGER.warning("Method %s must run in the event_loop. No loop detected.", func.__name__)
+        # Only perform the (potentially expensive) loop check when debug is enabled.
+        if hms.debug_enabled():
+            try:
+                asyncio.get_running_loop()
+                loop_running = True
+            except Exception:
+                loop_running = False
+
+            if not loop_running and func not in _with_loop:
+                _with_loop.add(func)
+                _LOGGER.warning(
+                    "Method %s must run in the event_loop. No loop detected.",
+                    func.__name__,
+                )
 
         return return_value
 
     setattr(func, "_loop_check", True)
-    return cast(Callable[P, R], wrapper_loop_check) if debug_enabled() else func
+    return cast(Callable[P, R], wrapper_loop_check)

{aiohomematic-2025.10.3 → aiohomematic-2025.10.5}/aiohomematic/caches/dynamic.py

@@ -400,15 +400,15 @@ class PingPongCache:
 
     @property
     def low_pending_pongs(self) -> bool:
-        """Return the pending pong count is low."""
+        """Return True when pending pong count is at or below the allowed delta (i.e., not high)."""
         self._cleanup_pending_pongs()
-        return len(self._pending_pongs) < (self._allowed_delta / 2)
+        return len(self._pending_pongs) <= self._allowed_delta
 
     @property
     def low_unknown_pongs(self) -> bool:
-        """Return the unknown pong count is low."""
+        """Return True when unknown pong count is at or below the allowed delta (i.e., not high)."""
         self._cleanup_unknown_pongs()
-        return len(self._unknown_pongs) < (self._allowed_delta / 2)
+        return len(self._unknown_pongs) <= self._allowed_delta
 
     @property
     def pending_pong_count(self) -> int:
@@ -430,10 +430,14 @@ class PingPongCache:
     def handle_send_ping(self, *, ping_ts: datetime) -> None:
         """Handle send ping timestamp."""
         self._pending_pongs.add(ping_ts)
-        self._check_and_fire_pong_event(
-            event_type=InterfaceEventType.PENDING_PONG,
-            pong_mismatch_count=self.pending_pong_count,
-        )
+        # Throttle event emission to every second ping to avoid spamming callbacks,
+        # but always emit when crossing the high threshold.
+        count = self.pending_pong_count
+        if (count > self._allowed_delta) or (count % 2 == 0):
+            self._check_and_fire_pong_event(
+                event_type=InterfaceEventType.PENDING_PONG,
+                pong_mismatch_count=count,
+            )
         _LOGGER.debug(
             "PING PONG CACHE: Increase pending PING count: %s - %i for ts: %s",
             self._interface_id,
@@ -473,8 +477,8 @@ class PingPongCache:
         """Cleanup too old pending pongs."""
         dt_now = datetime.now()
         for pong_ts in list(self._pending_pongs):
-            delta = dt_now - pong_ts
-            if delta.seconds > self._ttl:
+            # Only expire entries that are actually older than the TTL.
+            if (dt_now - pong_ts).total_seconds() > self._ttl:
                 self._pending_pongs.remove(pong_ts)
                 _LOGGER.debug(
                     "PING PONG CACHE: Removing expired pending PONG: %s - %i for ts: %s",
@@ -487,8 +491,8 @@ class PingPongCache:
         """Cleanup too old unknown pongs."""
         dt_now = datetime.now()
         for pong_ts in list(self._unknown_pongs):
-            delta = dt_now - pong_ts
-            if delta.seconds > self._ttl:
+            # Only expire entries that are actually older than the TTL.
+            if (dt_now - pong_ts).total_seconds() > self._ttl:
                 self._unknown_pongs.remove(pong_ts)
                 _LOGGER.debug(
                     "PING PONG CACHE: Removing expired unknown PONG: %s - %i or ts: %s",
@@ -519,11 +523,20 @@ class PingPongCache:
             )
 
         if self.low_pending_pongs and event_type == InterfaceEventType.PENDING_PONG:
-            _fire_event(mismatch_count=0)
-            self._pending_pong_logged = False
+            # In low state:
+            # - If we previously logged a high state, emit a reset event (mismatch=0) exactly once.
+            # - Otherwise, throttle emission to every second ping (even counts > 0) to avoid spamming.
+            if self._pending_pong_logged:
+                _fire_event(mismatch_count=0)
+                self._pending_pong_logged = False
+                return
+            if pong_mismatch_count > 0 and pong_mismatch_count % 2 == 0:
+                _fire_event(mismatch_count=pong_mismatch_count)
             return
 
         if self.low_unknown_pongs and event_type == InterfaceEventType.UNKNOWN_PONG:
+            # For unknown pongs, only reset the logged flag when we drop below the threshold.
+            # We do not emit an event here since there is no explicit expectation for a reset notification.
             self._unknown_pong_logged = False
             return
 

{aiohomematic-2025.10.3 → aiohomematic-2025.10.5}/aiohomematic/caches/persistent.py

@@ -250,14 +250,24 @@ class DeviceDescriptionCache(BasePersistentCache):
                 addr_map.pop(address, None)
             desc_map.pop(address, None)
 
-    def get_addresses(self, *, interface_id: str) -> frozenset[str]:
+    def get_addresses(self, *, interface_id: str | None = None) -> frozenset[str]:
         """Return the addresses by interface as a set."""
-        return frozenset(self._addresses[interface_id])
+        if interface_id:
+            return frozenset(self._addresses[interface_id])
+        return frozenset(addr for interface_id in self.get_interface_ids() for addr in self._addresses[interface_id])
 
     def get_device_descriptions(self, *, interface_id: str) -> Mapping[str, DeviceDescription]:
         """Return the devices by interface."""
         return self._device_descriptions[interface_id]
 
+    def get_interface_ids(self) -> tuple[str, ...]:
+        """Return the interface ids."""
+        return tuple(self._raw_device_descriptions.keys())
+
+    def has_device_descriptions(self, *, interface_id: str) -> bool:
+        """Return the devices by interface."""
+        return interface_id in self._device_descriptions
+
     def find_device_description(self, *, interface_id: str, device_address: str) -> DeviceDescription | None:
         """Return the device description by interface and device_address."""
         return self._device_descriptions[interface_id].get(device_address)

{aiohomematic-2025.10.3 → aiohomematic-2025.10.5}/aiohomematic/central/__init__.py

@@ -92,6 +92,7 @@ from aiohomematic.const import (
     CONNECTION_CHECKER_INTERVAL,
     DATA_POINT_EVENTS,
     DATETIME_FORMAT_MILLIS,
+    DEFAULT_DELAY_NEW_DEVICE_CREATION,
     DEFAULT_ENABLE_DEVICE_FIRMWARE_CHECK,
     DEFAULT_ENABLE_PROGRAM_SCAN,
     DEFAULT_ENABLE_SYSVAR_SCAN,
@@ -136,6 +137,7 @@ from aiohomematic.const import (
     Parameter,
     ParamsetKey,
     ProxyInitState,
+    SourceOfDeviceCreation,
     SystemInformation,
 )
 from aiohomematic.decorators import inspector
@@ -164,6 +166,7 @@ from aiohomematic.support import (
     LogContextMixin,
     PayloadMixin,
     check_config,
+    extract_device_addresses_from_device_descriptions,
     extract_exc_args,
     get_channel_no,
     get_device_address,
@@ -506,7 +509,9 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         if self._config.start_direct:
             if await self._create_clients():
                 for client in self._clients.values():
-                    await self._refresh_device_descriptions(client=client)
+                    await self._refresh_device_descriptions_and_create_missing_devices(
+                        client=client, refresh_only_existing=False
+                    )
         else:
             self._clients_started = await self._start_clients()
             if self._config.enable_server:
@@ -576,11 +581,15 @@ class CentralUnit(LogContextMixin, PayloadMixin):
     async def refresh_firmware_data(self, *, device_address: str | None = None) -> None:
         """Refresh device firmware data."""
         if device_address and (device := self.get_device(address=device_address)) is not None and device.is_updatable:
-            await self._refresh_device_descriptions(client=device.client, device_address=device_address)
+            await self._refresh_device_descriptions_and_create_missing_devices(
+                client=device.client, refresh_only_existing=True, device_address=device_address
+            )
             device.refresh_firmware_data()
         else:
             for client in self._clients.values():
-                await self._refresh_device_descriptions(client=client)
+                await self._refresh_device_descriptions_and_create_missing_devices(
+                    client=client, refresh_only_existing=True
+                )
             for device in self._devices.values():
                 if device.is_updatable:
                     device.refresh_firmware_data()
@@ -595,9 +604,12 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         ]:
             await self.refresh_firmware_data(device_address=device.address)
 
-    async def _refresh_device_descriptions(self, *, client: hmcl.Client, device_address: str | None = None) -> None:
-        """Refresh device descriptions."""
+    async def _refresh_device_descriptions_and_create_missing_devices(
+        self, *, client: hmcl.Client, refresh_only_existing: bool, device_address: str | None = None
+    ) -> None:
+        """Refresh device descriptions and create missing devices."""
         device_descriptions: tuple[DeviceDescription, ...] | None = None
+
         if (
             device_address
             and (device_description := await client.get_device_description(device_address=device_address)) is not None
@@ -606,10 +618,25 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         else:
             device_descriptions = await client.list_devices()
 
+        if (
+            device_descriptions
+            and refresh_only_existing
+            and (
+                existing_device_descriptions := tuple(
+                    dev_desc
+                    for dev_desc in list(device_descriptions)
+                    if dev_desc["ADDRESS"]
+                    in self.device_descriptions.get_device_descriptions(interface_id=client.interface_id)
+                )
+            )
+        ):
+            device_descriptions = existing_device_descriptions
+
         if device_descriptions:
             await self._add_new_devices(
                 interface_id=client.interface_id,
                 device_descriptions=device_descriptions,
+                source=SourceOfDeviceCreation.REFRESH,
             )
 
     async def _start_clients(self) -> bool:
@@ -618,13 +645,15 @@ class CentralUnit(LogContextMixin, PayloadMixin):
             return False
         await self._load_caches()
         if new_device_addresses := self._check_for_new_device_addresses():
-            await self._create_devices(new_device_addresses=new_device_addresses)
+            await self._create_devices(new_device_addresses=new_device_addresses, source=SourceOfDeviceCreation.CACHE)
         await self._init_hub()
         await self._init_clients()
         # Proactively fetch device descriptions if none were created yet to avoid slow startup
         if not self._devices:
             for client in self._clients.values():
-                await self._refresh_device_descriptions(client=client)
+                await self._refresh_device_descriptions_and_create_missing_devices(
+                    client=client, refresh_only_existing=False
+                )
         return True
 
     async def _stop_clients(self) -> None:
@@ -934,7 +963,9 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         await self._data_cache.load()
         return True
 
-    async def _create_devices(self, *, new_device_addresses: Mapping[str, set[str]]) -> None:
+    async def _create_devices(
+        self, *, new_device_addresses: Mapping[str, set[str]], source: SourceOfDeviceCreation
+    ) -> None:
         """Trigger creation of the objects that expose the functionality."""
         if not self._clients:
             raise AioHomematicException(
@@ -988,6 +1019,7 @@ class CentralUnit(LogContextMixin, PayloadMixin):
                 system_event=BackendSystemEvent.DEVICES_CREATED,
                 new_data_points=new_dps,
                 new_channel_events=new_channel_events,
+                source=source,
             )
 
     async def delete_device(self, *, interface_id: str, device_address: str) -> None:
@@ -1014,15 +1046,45 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         for address in addresses:
             if device := self._devices.get(address):
                 self.remove_device(device=device)
-        await self.save_caches()
+        await self.save_caches(save_device_descriptions=True, save_paramset_descriptions=True)
 
     @callback_backend_system(system_event=BackendSystemEvent.NEW_DEVICES)
     async def add_new_devices(self, *, interface_id: str, device_descriptions: tuple[DeviceDescription, ...]) -> None:
         """Add new devices to central unit."""
-        await self._add_new_devices(interface_id=interface_id, device_descriptions=device_descriptions)
+        source = (
+            SourceOfDeviceCreation.NEW
+            if self._device_descriptions.has_device_descriptions(interface_id=interface_id)
+            else SourceOfDeviceCreation.INIT
+        )
+        await self._add_new_devices(interface_id=interface_id, device_descriptions=device_descriptions, source=source)
+
+    async def add_new_device_manually(self, *, interface_id: str, address: str) -> None:
+        """Add new devices manually triggered to central unit."""
+        if interface_id not in self._clients:
+            _LOGGER.warning(
+                "ADD_NEW_DEVICES_MANUALLY failed: Missing client for interface_id %s",
+                interface_id,
+            )
+            return
+        client = self._clients[interface_id]
+        if (device_descriptions := await client.get_all_device_description(device_address=address)) is None:
+            _LOGGER.warning(
+                "ADD_NEW_DEVICES_MANUALLY failed: No device description found for address %s on interface_id %s",
+                address,
+                interface_id,
+            )
+            return
+
+        await self._add_new_devices(
+            interface_id=interface_id,
+            device_descriptions=device_descriptions,
+            source=SourceOfDeviceCreation.MANUAL,
+        )
 
     @inspector(measure_performance=True)
-    async def _add_new_devices(self, *, interface_id: str, device_descriptions: tuple[DeviceDescription, ...]) -> None:
+    async def _add_new_devices(
+        self, *, interface_id: str, device_descriptions: tuple[DeviceDescription, ...], source: SourceOfDeviceCreation
+    ) -> None:
         """Add new devices to central unit."""
         if not device_descriptions:
             _LOGGER.debug(
@@ -1045,57 +1107,96 @@ class CentralUnit(LogContextMixin, PayloadMixin):
             return
 
         async with self._device_add_semaphore:
-            # Use mapping membership to avoid rebuilding known addresses and allow O(1) checks.
-            existing_map = self._device_descriptions.get_device_descriptions(interface_id=interface_id)
+            if not (
+                new_device_descriptions := self._identify_new_device_descriptions(
+                    device_descriptions=device_descriptions, interface_id=interface_id
+                )
+            ):
+                _LOGGER.debug("ADD_NEW_DEVICES: Nothing to add for interface_id %s", interface_id)
+                return
+
+            # Here we block the automatic creation of new devices, if required
+            if (
+                self._config.delay_new_device_creation
+                and source == SourceOfDeviceCreation.NEW
+                and (
+                    new_addresses := extract_device_addresses_from_device_descriptions(
+                        device_descriptions=new_device_descriptions
+                    )
+                )
+            ):
+                self.fire_backend_system_callback(
+                    system_event=BackendSystemEvent.DEVICES_DELAYED,
+                    new_addresses=new_addresses,
+                    interface_id=interface_id,
+                    source=source,
+                )
+                return
+
             client = self._clients[interface_id]
-            save_paramset_descriptions = False
-            save_device_descriptions = False
-            for dev_desc in device_descriptions:
+            save_descriptions = False
+            for dev_desc in new_device_descriptions:
                 try:
-                    address = dev_desc["ADDRESS"]
-                    # Check existence before mutating cache to ensure we detect truly new addresses.
-                    is_new_address = address not in existing_map
                     self._device_descriptions.add_device(interface_id=interface_id, device_description=dev_desc)
-                    save_device_descriptions = True
-                    if is_new_address:
-                        await client.fetch_paramset_descriptions(device_description=dev_desc)
-                        save_paramset_descriptions = True
+                    await client.fetch_paramset_descriptions(device_description=dev_desc)
+                    save_descriptions = True
                 except Exception as exc:  # pragma: no cover
-                    save_device_descriptions = False
-                    save_paramset_descriptions = False
+                    save_descriptions = False
                     _LOGGER.error(
-                        "ADD_NEW_DEVICES failed: %s [%s]",
+                        "UPDATE_CACHES_WITH_NEW_DEVICES failed: %s [%s]",
                         type(exc).__name__,
                         extract_exc_args(exc=exc),
                     )
 
             await self.save_caches(
-                save_device_descriptions=save_device_descriptions,
-                save_paramset_descriptions=save_paramset_descriptions,
+                save_device_descriptions=save_descriptions,
+                save_paramset_descriptions=save_descriptions,
             )
-            if new_device_addresses := self._check_for_new_device_addresses():
-                await self._device_details.load()
-                await self._data_cache.load()
-                await self._create_devices(new_device_addresses=new_device_addresses)
 
-    def _check_for_new_device_addresses(self) -> Mapping[str, set[str]]:
+        if new_device_addresses := self._check_for_new_device_addresses(interface_id=interface_id):
+            await self._device_details.load()
+            await self._data_cache.load(interface=client.interface)
+            await self._create_devices(new_device_addresses=new_device_addresses, source=source)
+
+    def _identify_new_device_descriptions(
+        self, *, device_descriptions: tuple[DeviceDescription, ...], interface_id: str | None = None
+    ) -> tuple[DeviceDescription, ...]:
+        """Identify devices whose ADDRESS isn't already known on any interface."""
+        known_addresses = self._device_descriptions.get_addresses(interface_id=interface_id)
+        return tuple(
+            dev_desc
+            for dev_desc in device_descriptions
+            if (dev_desc["ADDRESS"] if not (parent_address := dev_desc.get("PARENT")) else parent_address)
+            not in known_addresses
+        )
+
+    def _check_for_new_device_addresses(self, *, interface_id: str | None = None) -> Mapping[str, set[str]]:
         """Check if there are new devices that need to be created."""
         new_device_addresses: dict[str, set[str]] = {}
-        for interface_id in self.interface_ids:
-            if not self._paramset_descriptions.has_interface_id(interface_id=interface_id):
+
+        # Cache existing device addresses once to avoid repeated mapping lookups
+        existing_addresses = set(self._devices.keys())
+
+        def _check_for_new_device_addresses_helper(*, iid: str) -> None:
+            """Check if there are new devices that need to be created."""
+            if not self._paramset_descriptions.has_interface_id(interface_id=iid):
                 _LOGGER.debug(
                     "CHECK_FOR_NEW_DEVICE_ADDRESSES: Skipping interface %s, missing paramsets",
-                    interface_id,
+                    iid,
                 )
-                continue
-
+                return
             # Build the set locally and assign only if non-empty to avoid add-then-delete pattern
-            new_set: set[str] = set()
-            for device_address in self._device_descriptions.get_addresses(interface_id=interface_id):
-                if device_address not in self._devices:
-                    new_set.add(device_address)
-            if new_set:
-                new_device_addresses[interface_id] = new_set
+            # Use set difference for speed on large collections
+            addresses = set(self._device_descriptions.get_addresses(interface_id=iid))
+            # get_addresses returns an iterable (likely tuple); convert to set once for efficient diff
+            if new_set := addresses - existing_addresses:
+                new_device_addresses[iid] = new_set
+
+        if interface_id:
+            _check_for_new_device_addresses_helper(iid=interface_id)
+        else:
+            for iid in self.interface_ids:
+                _check_for_new_device_addresses_helper(iid=iid)
 
         if _LOGGER.isEnabledFor(level=DEBUG):
             count = sum(len(item) for item in new_device_addresses.values())
@@ -1670,12 +1771,31 @@ class _Scheduler(threading.Thread):
                 _LOGGER.debug("SCHEDULER: Waiting till central %s is started", self._central.name)
                 await asyncio.sleep(SCHEDULER_NOT_STARTED_SLEEP)
                 continue
+
+            any_executed = False
             for job in self._scheduler_jobs:
                 if not self._active or not job.ready:
                     continue
                 await job.run()
                 job.schedule_next_execution()
-            if self._active:
+                any_executed = True
+
+            if not self._active:
+                break  # type: ignore[unreachable]
+
+            # If no job was executed this cycle, we can sleep until the next job is due
+            if not any_executed:
+                now = datetime.now()
+                try:
+                    next_due = min(job.next_run for job in self._scheduler_jobs)
+                    # Sleep until the next task should run, but cap to 1s to remain responsive
+                    delay = max(0.0, (next_due - now).total_seconds())
+                    await asyncio.sleep(min(1.0, delay))
+                except ValueError:
+                    # No jobs configured; fallback to default loop sleep
+                    await asyncio.sleep(SCHEDULER_LOOP_SLEEP)
+            else:
+                # When work was done, yield briefly to the loop
                 await asyncio.sleep(SCHEDULER_LOOP_SLEEP)
 
     async def _check_connection(self) -> None:
@@ -1823,6 +1943,11 @@ class _SchedulerJob:
         """Return if the job can be executed."""
         return self._next_run < datetime.now()
 
+    @property
+    def next_run(self) -> datetime:
+        """Return the next scheduled run timestamp."""
+        return self._next_run
+
     async def run(self) -> None:
         """Run the task."""
         await self._task()
@@ -1848,6 +1973,7 @@ class CentralConfig:
         callback_host: str | None = None,
         callback_port: int | None = None,
         default_callback_port: int = PORT_ANY,
+        delay_new_device_creation: bool = DEFAULT_DELAY_NEW_DEVICE_CREATION,
         enable_device_firmware_check: bool = DEFAULT_ENABLE_DEVICE_FIRMWARE_CHECK,
         enable_program_scan: bool = DEFAULT_ENABLE_PROGRAM_SCAN,
         enable_sysvar_scan: bool = DEFAULT_ENABLE_SYSVAR_SCAN,
@@ -1876,6 +2002,7 @@ class CentralConfig:
         self.central_id: Final = central_id
         self.client_session: Final = client_session
         self.default_callback_port: Final = default_callback_port
+        self.delay_new_device_creation: Final = delay_new_device_creation
         self.enable_device_firmware_check: Final = enable_device_firmware_check
         self.enable_program_scan: Final = enable_program_scan
         self.enable_sysvar_scan: Final = enable_sysvar_scan

{aiohomematic-2025.10.3 → aiohomematic-2025.10.5}/aiohomematic/client/__init__.py

@@ -494,6 +494,29 @@ class Client(ABC, LogContextMixin):
             _LOGGER.warning("GET_DEVICE_DESCRIPTIONS failed: %s [%s]", bhexc.name, extract_exc_args(exc=bhexc))
         return None
 
+    @inspector(re_raise=False)
+    async def get_all_device_description(self, *, device_address: str) -> tuple[DeviceDescription, ...] | None:
+        """Get all device descriptions from the backend."""
+        all_device_description: list[DeviceDescription] = []
+        if main_dd := await self.get_device_description(device_address=device_address):
+            all_device_description.append(main_dd)
+        else:
+            _LOGGER.warning(
+                "GET_ALL_DEVICE_DESCRIPTIONS: No device description for %s",
+                device_address,
+            )
+
+        if main_dd:
+            for channel_address in main_dd["CHILDREN"]:
+                if channel_dd := await self.get_device_description(device_address=channel_address):
+                    all_device_description.append(channel_dd)
+                else:
+                    _LOGGER.warning(
+                        "GET_ALL_DEVICE_DESCRIPTIONS: No channel description for %s",
+                        channel_address,
+                    )
+        return tuple(all_device_description)
+
     @inspector
     async def add_link(self, *, sender_address: str, receiver_address: str, name: str, description: str) -> None:
         """Return a list of links."""

{aiohomematic-2025.10.3 → aiohomematic-2025.10.5}/aiohomematic/client/json_rpc.py

@@ -1259,7 +1259,16 @@ class JsonRpcAioHttpClient(LogContextMixin):
             response = await self._post_script(script_name=RegaScript.GET_SERIAL)
 
             if json_result := response[_JsonKey.RESULT]:
-                serial: str = json_result[_JsonKey.SERIAL]
+                # The backend may return a JSON string which needs to be decoded first
+                # or an already-parsed dict. Support both.
+                if isinstance(json_result, str):
+                    try:
+                        json_result = orjson.loads(json_result)
+                    except Exception:
+                        # Fall back to plain string handling; return last 10 chars
+                        serial_exc = str(json_result)
+                        return serial_exc[-10:] if len(serial_exc) > 10 else serial_exc
+                serial: str = str(json_result.get(_JsonKey.SERIAL) if isinstance(json_result, dict) else json_result)
                 if len(serial) > 10:
                     serial = serial[-10:]
                 return serial