aiohomematic 2025.8.8__tar.gz → 2025.8.10__tar.gz

{aiohomematic-2025.8.8 → aiohomematic-2025.8.10}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Daniel Perna, SukramJ
+Copyright (c) 2021-2025 Daniel Perna, SukramJ
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

aiohomematic-2025.8.10/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: aiohomematic
+Version: 2025.8.10
+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>
+License: MIT License
+Project-URL: Source Code, https://github.com/sukramj/aiohomematic
+Project-URL: Bug Reports, https://github.com/sukramj/aiohomematic/issues
+Project-URL: Docs: Dev, https://github.com/sukramj/aiohomematic
+Project-URL: Forum, https://github.com/sukramj/aiohomematic/discussions
+Keywords: home,automation,homematic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.13.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.10.0
+Requires-Dist: orjson>=3.10.0
+Requires-Dist: python-slugify>=8.0.0
+Requires-Dist: voluptuous>=0.14.0
+Dynamic: license-file
+
+# AIO Homematic (hahomematic)
+
+A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring [HomeMatic](https://www.eq-3.com/products/homematic.html) and [HomematicIP](https://www.homematic-ip.com/en/start.html) devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.
+
+This project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.
+
+## How it works
+
+Unlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:
+
+- Fetches and caches device paramsets (VALUES) for fast successive startups.
+- Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).
+- Includes helpers for robust operation, such as automatic reconnection after CCU restarts.
+
+## Key features
+
+- Automatic entity discovery from device/channel parameters.
+- Extensible via custom entity classes for complex devices.
+- Caching of paramsets to speed up restarts.
+- Designed to integrate with Home Assistant.
+
+## Quickstart for Home Assistant
+
+Use the Home Assistant custom integration "Homematic(IP) Local", which is powered by aiohomematic.
+
+1. Prerequisites
+   - Home Assistant 2024.6 or newer recommended.
+   - A CCU3, RaspberryMatic, or Homegear instance reachable from Home Assistant.
+   - For HomematicIP devices, ensure CCU firmware meets the minimum versions listed below.
+2. Install the integration
+   - Add the custom repository and install: https://github.com/sukramj/homematicip_local
+   - Follow the installation guide: https://github.com/sukramj/homematicip_local/wiki/Installation
+3. Configure via Home Assistant UI
+   - In Home Assistant: Settings → Devices & Services → Add Integration → search for "Homematic(IP) Local".
+   - Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable SSL and accept the certificate if self‑signed.
+   - Provide credentials if your CCU requires them.
+   - Choose which interfaces to enable (HM, HmIP, Virtual). Default ports are typically 2001 (HM), 2010 (HmIP), 9292 (Virtual).
+4. Network callbacks
+   - The integration needs to receive XML‑RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). The default callback port is 43439; you can adjust it in advanced options.
+5. Verify
+   - After setup, devices should appear under Devices & Services → Homematic(IP) Local. Discovery may take a few seconds after the first connection while paramsets are fetched and cached for faster restarts.
+
+If you need to use aiohomematic directly in Python, see the Public API and example below.
+
+## Requirements
+
+Due to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:
+
+- CCU2: 2.53.27
+- CCU3: 3.53.26
+
+See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other CCU‑like platforms using the buggy HmIPServer version are not supported.
+
+## Public API and imports
+
+- The public API of aiohomematic is explicitly defined via **all** in each module and subpackage.
+- Backwards‑compatible imports should target these modules:
+  - aiohomematic.central: CentralUnit, CentralConfig and related schemas
+  - aiohomematic.client: Client, InterfaceConfig, create_client, get_client
+  - aiohomematic.model: device/data point abstractions (see subpackages for details)
+  - aiohomematic.exceptions: library exception types intended for consumers
+  - aiohomematic.const: constants and enums (stable subset; see module **all**)
+- The top‑level package only exposes **version** to avoid import cycles and keep startup lean. Prefer importing from the specific submodules listed above.
+
+Example:
+
+    from aiohomematic.central import CentralConfig
+    from aiohomematic import client as hmcl
+
+    cfg = CentralConfig(
+        central_id="ccu-main",
+        host="ccu.local",
+        username="admin",
+        password="secret",
+        default_callback_port=43439,
+        interface_configs={hmcl.InterfaceConfig(interface=hmcl.Interface.HMIP, port=2010, enabled=True)},
+    )
+    central = cfg.create_central()
+
+## Useful links
+
+- Changelog: [see](changelog.md) for release history and latest changes.
+- Definition of calculated data points: [see](docs/calculated_data_points.md)
+- Homematic(IP) Local integration: https://github.com/sukramj/homematicip_local
+- Input select helper: [see](docs/input_select_helper.md) for an overview of how to use the input select helper.
+- Troubleshooting with Home Assistant: [see](docs/homeassistant_troubleshooting.md) for common issues and how to debug them.
+- Unignore mechanism: [see](docs/unignore.md) for how to unignore devices that are ignored by default.
+
+## Useful developer links
+
+- Architecture overview: [see](docs/architecture.md) for an overview of the architecture of the library.
+- Data flow: [see](docs/data_flow.md) for an overview of how data flows through the library.
+- Extending the model: [see](docs/extension_points.md) for adding custom device profiles and calculated data points.
+- Home Assistant lifecycle (discovery, updates, teardown): [see](docs/homeassistant_lifecycle.md) for details on how the integration works and how to debug issues.
+- RSSI fix: [see](docs/rssi_fix.md) for how RSSI values are fixed for Home Assistant.
+- Sequence diagrams: [see](docs/sequence_diagrams.md) for a sequence diagram of how the library works.

aiohomematic-2025.8.10/README.md

@@ -0,0 +1,96 @@
+# AIO Homematic (hahomematic)
+
+A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring [HomeMatic](https://www.eq-3.com/products/homematic.html) and [HomematicIP](https://www.homematic-ip.com/en/start.html) devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.
+
+This project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.
+
+## How it works
+
+Unlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:
+
+- Fetches and caches device paramsets (VALUES) for fast successive startups.
+- Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).
+- Includes helpers for robust operation, such as automatic reconnection after CCU restarts.
+
+## Key features
+
+- Automatic entity discovery from device/channel parameters.
+- Extensible via custom entity classes for complex devices.
+- Caching of paramsets to speed up restarts.
+- Designed to integrate with Home Assistant.
+
+## Quickstart for Home Assistant
+
+Use the Home Assistant custom integration "Homematic(IP) Local", which is powered by aiohomematic.
+
+1. Prerequisites
+   - Home Assistant 2024.6 or newer recommended.
+   - A CCU3, RaspberryMatic, or Homegear instance reachable from Home Assistant.
+   - For HomematicIP devices, ensure CCU firmware meets the minimum versions listed below.
+2. Install the integration
+   - Add the custom repository and install: https://github.com/sukramj/homematicip_local
+   - Follow the installation guide: https://github.com/sukramj/homematicip_local/wiki/Installation
+3. Configure via Home Assistant UI
+   - In Home Assistant: Settings → Devices & Services → Add Integration → search for "Homematic(IP) Local".
+   - Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable SSL and accept the certificate if self‑signed.
+   - Provide credentials if your CCU requires them.
+   - Choose which interfaces to enable (HM, HmIP, Virtual). Default ports are typically 2001 (HM), 2010 (HmIP), 9292 (Virtual).
+4. Network callbacks
+   - The integration needs to receive XML‑RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). The default callback port is 43439; you can adjust it in advanced options.
+5. Verify
+   - After setup, devices should appear under Devices & Services → Homematic(IP) Local. Discovery may take a few seconds after the first connection while paramsets are fetched and cached for faster restarts.
+
+If you need to use aiohomematic directly in Python, see the Public API and example below.
+
+## Requirements
+
+Due to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:
+
+- CCU2: 2.53.27
+- CCU3: 3.53.26
+
+See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other CCU‑like platforms using the buggy HmIPServer version are not supported.
+
+## Public API and imports
+
+- The public API of aiohomematic is explicitly defined via **all** in each module and subpackage.
+- Backwards‑compatible imports should target these modules:
+  - aiohomematic.central: CentralUnit, CentralConfig and related schemas
+  - aiohomematic.client: Client, InterfaceConfig, create_client, get_client
+  - aiohomematic.model: device/data point abstractions (see subpackages for details)
+  - aiohomematic.exceptions: library exception types intended for consumers
+  - aiohomematic.const: constants and enums (stable subset; see module **all**)
+- The top‑level package only exposes **version** to avoid import cycles and keep startup lean. Prefer importing from the specific submodules listed above.
+
+Example:
+
+    from aiohomematic.central import CentralConfig
+    from aiohomematic import client as hmcl
+
+    cfg = CentralConfig(
+        central_id="ccu-main",
+        host="ccu.local",
+        username="admin",
+        password="secret",
+        default_callback_port=43439,
+        interface_configs={hmcl.InterfaceConfig(interface=hmcl.Interface.HMIP, port=2010, enabled=True)},
+    )
+    central = cfg.create_central()
+
+## Useful links
+
+- Changelog: [see](changelog.md) for release history and latest changes.
+- Definition of calculated data points: [see](docs/calculated_data_points.md)
+- Homematic(IP) Local integration: https://github.com/sukramj/homematicip_local
+- Input select helper: [see](docs/input_select_helper.md) for an overview of how to use the input select helper.
+- Troubleshooting with Home Assistant: [see](docs/homeassistant_troubleshooting.md) for common issues and how to debug them.
+- Unignore mechanism: [see](docs/unignore.md) for how to unignore devices that are ignored by default.
+
+## Useful developer links
+
+- Architecture overview: [see](docs/architecture.md) for an overview of the architecture of the library.
+- Data flow: [see](docs/data_flow.md) for an overview of how data flows through the library.
+- Extending the model: [see](docs/extension_points.md) for adding custom device profiles and calculated data points.
+- Home Assistant lifecycle (discovery, updates, teardown): [see](docs/homeassistant_lifecycle.md) for details on how the integration works and how to debug issues.
+- RSSI fix: [see](docs/rssi_fix.md) for how RSSI values are fixed for Home Assistant.
+- Sequence diagrams: [see](docs/sequence_diagrams.md) for a sequence diagram of how the library works.

{aiohomematic-2025.8.8 → aiohomematic-2025.8.10}/aiohomematic/__init__.py

@@ -1,6 +1,10 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 AioHomematic: a Python 3 library to interact with HomeMatic and HomematicIP backends.
 
+Public API at the top-level package is defined by __all__.
+
 This package provides a high-level API to discover devices and channels, read and write
 parameters (data points), receive events, and manage programs and system variables.
 
@@ -23,7 +27,7 @@ import sys
 import threading
 from typing import Final
 
-from aiohomematic import central as hmcu
+from aiohomematic import central as hmcu, validator as _ahm_validator
 from aiohomematic.const import VERSION
 
 if sys.stdout.isatty():
@@ -43,5 +47,15 @@ def signal_handler(sig, frame):  # type: ignore[no-untyped-def]
         asyncio.run_coroutine_threadsafe(central.stop(), asyncio.get_running_loop())
 
 
+# Perform lightweight startup validation once on import
+try:
+    _ahm_validator.validate_startup()
+except Exception as _exc:  # pragma: no cover
+    # Fail-fast with a clear message if validation fails during import
+    raise RuntimeError(f"AioHomematic startup validation failed: {_exc}") from _exc
+
 if threading.current_thread() is threading.main_thread() and sys.stdout.isatty():
     signal.signal(signal.SIGINT, signal_handler)
+
+# Define public API for the top-level package
+__all__ = ["__version__"]

{aiohomematic-2025.8.8 → aiohomematic-2025.8.10}/aiohomematic/async_support.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module with support for loop interaction."""
 
 from __future__ import annotations
@@ -26,13 +28,24 @@ class Looper:
         self._tasks: Final[set[asyncio.Future[Any]]] = set()
         self._loop = asyncio.get_event_loop()
 
-    async def block_till_done(self) -> None:
-        """Block until all pending work is done."""
+    async def block_till_done(self, wait_time: float | None = None) -> None:
+        """
+        Block until all pending work is done.
+
+        If wait_time is set, stop waiting after the given number of seconds and log remaining tasks.
+        """
         # To flush out any call_soon_threadsafe
         await asyncio.sleep(0)
         start_time: float | None = None
+        deadline: float | None = (monotonic() + wait_time) if wait_time is not None else None
         current_task = asyncio.current_task()
         while tasks := [task for task in self._tasks if task is not current_task and not cancelling(task)]:
+            # If we have a deadline and have exceeded it, log remaining tasks and break
+            if deadline is not None and monotonic() >= deadline:
+                for task in tasks:
+                    _LOGGER.warning("Shutdown timeout reached; task still pending: %s", task)
+                break
+
             await self._await_and_log_pending(tasks)
 
             if start_time is None:

{aiohomematic-2025.8.8 → aiohomematic-2025.8.10}/aiohomematic/caches/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Cache packages for AioHomematic.
 

{aiohomematic-2025.8.8 → aiohomematic-2025.8.10}/aiohomematic/caches/dynamic.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Dynamic caches used at runtime by the central unit and clients.
 

{aiohomematic-2025.8.8 → aiohomematic-2025.8.10}/aiohomematic/caches/persistent.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Persistent caches used to persist HomeMatic metadata between runs.
 
@@ -208,9 +210,15 @@ class DeviceDescriptionCache(BasePersistentCache):
 
     def add_device(self, interface_id: str, device_description: DeviceDescription) -> None:
         """Add a device to the cache."""
+        # Fast-path: If the address is not yet known, skip costly removal operations.
+        if (address := device_description["ADDRESS"]) not in self._device_descriptions[interface_id]:
+            self._raw_device_descriptions[interface_id].append(device_description)
+            self._process_device_description(interface_id=interface_id, device_description=device_description)
+            return
+        # Address exists: remove old entries before adding the new description.
         self._remove_device(
             interface_id=interface_id,
-            addresses_to_remove=[device_description["ADDRESS"]],
+            addresses_to_remove=[address],
         )
         self._raw_device_descriptions[interface_id].append(device_description)
         self._process_device_description(interface_id=interface_id, device_description=device_description)
@@ -228,23 +236,22 @@ class DeviceDescriptionCache(BasePersistentCache):
 
     def _remove_device(self, interface_id: str, addresses_to_remove: list[str]) -> None:
         """Remove a device from the cache."""
+        # Use a set for faster membership checks
+        addresses_set = set(addresses_to_remove)
         self._raw_device_descriptions[interface_id] = [
-            device
-            for device in self._raw_device_descriptions[interface_id]
-            if device["ADDRESS"] not in addresses_to_remove
+            device for device in self._raw_device_descriptions[interface_id] if device["ADDRESS"] not in addresses_set
         ]
-        for address in addresses_to_remove:
-            try:
-                if ADDRESS_SEPARATOR not in address and self._addresses[interface_id].get(address):
-                    del self._addresses[interface_id][address]
-                if self._device_descriptions[interface_id].get(address):
-                    del self._device_descriptions[interface_id][address]
-            except KeyError:
-                _LOGGER.warning("REMOVE_DEVICE failed: Unable to delete: %s", address)
-
-    def get_addresses(self, interface_id: str) -> tuple[str, ...]:
-        """Return the addresses by interface."""
-        return tuple(self._addresses[interface_id].keys())
+        addr_map = self._addresses[interface_id]
+        desc_map = self._device_descriptions[interface_id]
+        for address in addresses_set:
+            # Pop with default to avoid KeyError and try/except overhead
+            if ADDRESS_SEPARATOR not in address:
+                addr_map.pop(address, None)
+            desc_map.pop(address, None)
+
+    def get_addresses(self, interface_id: str) -> frozenset[str]:
+        """Return the addresses by interface as a set."""
+        return frozenset(self._addresses[interface_id])
 
     def get_device_descriptions(self, interface_id: str) -> Mapping[str, DeviceDescription]:
         """Return the devices by interface."""
@@ -288,9 +295,10 @@ class DeviceDescriptionCache(BasePersistentCache):
         device_address = get_device_address(address)
         self._device_descriptions[interface_id][address] = device_description
 
-        if device_address not in self._addresses[interface_id][device_address]:
-            self._addresses[interface_id][device_address].add(device_address)
-        self._addresses[interface_id][device_address].add(address)
+        # Avoid redundant membership checks; set.add is idempotent and cheaper than check+add
+        addr_set = self._addresses[interface_id][device_address]
+        addr_set.add(device_address)
+        addr_set.add(address)
 
     async def load(self) -> DataOperationResult:
         """Load device data from disk into _device_description_cache."""
@@ -420,13 +428,12 @@ class ParamsetDescriptionCache(BasePersistentCache):
     def _add_address_parameter(self, channel_address: str, paramsets: list[dict[str, Any]]) -> None:
         """Add address parameter to cache."""
         device_address, channel_no = get_split_channel_address(channel_address)
+        cache = self._address_parameter_cache
         for paramset in paramsets:
             if not paramset:
                 continue
             for parameter in paramset:
-                if (device_address, parameter) not in self._address_parameter_cache:
-                    self._address_parameter_cache[(device_address, parameter)] = set()
-                self._address_parameter_cache[(device_address, parameter)].add(channel_no)
+                cache.setdefault((device_address, parameter), set()).add(channel_no)
 
     async def load(self) -> DataOperationResult:
         """Load paramset descriptions from disk into paramset cache."""