[![releasebadge]][release]
[![License][license-shield]](LICENSE.md)
[![GitHub Sponsors][sponsorsbadge]][sponsors]
# 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
- Use latest version of Home Assistant.
- A CCU3, OpenCCU, 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 TLS and don't use verify if self‑signed.
- Always enter credentials.
- 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). Callbacks are only required for special network setups.
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/OpenCCU/OpenCCU/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.central.event: display received events from the backend
- 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**)
- aiohomematic.performance: display some performance metrics (enabled when DEBUG is enabled)
- 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)
- Naming: [see](docs/naming.md) for how device, channel and data point names are created.
- 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.
[license-shield]: https://img.shields.io/github/license/SukramJ/aiohomematic.svg?style=for-the-badge
[release]: https://github.com/SukramJ/aiohomematic/releases
[releasebadge]: https://img.shields.io/github/v/release/SukramJ/aiohomematic?style=for-the-badge
[sponsorsbadge]: https://img.shields.io/github/sponsors/SukramJ?style=for-the-badge&label=GitHub%20Sponsors&color=green
[sponsors]: https://github.com/sponsors/SukramJ
Raw data
{
"_id": null,
"home_page": "https://github.com/sukramj/aiohomematic",
"name": "aiohomematic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "home, automation, homematic, openccu, homegear",
"author": null,
"author_email": "SukramJ <sukramj@icloud.com>, Daniel Perna <danielperna84@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/09/a2/2e6521f3e2eb36bcf946c0445e812e1a07768b01f54c01de69a7be2fac81/aiohomematic-2025.11.2.tar.gz",
"platform": null,
"description": "[![releasebadge]][release]\n[![License][license-shield]](LICENSE.md)\n[![GitHub Sponsors][sponsorsbadge]][sponsors]\n\n# AIO Homematic (hahomematic)\n\nA 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\u2011party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.\n\nThis project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.\n\n## How it works\n\nUnlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:\n\n- Fetches and caches device paramsets (VALUES) for fast successive startups.\n- Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).\n- Includes helpers for robust operation, such as automatic reconnection after CCU restarts.\n\n## Key features\n\n- Automatic entity discovery from device/channel parameters.\n- Extensible via custom entity classes for complex devices.\n- Caching of paramsets to speed up restarts.\n- Designed to integrate with Home Assistant.\n\n## Quickstart for Home Assistant\n\nUse the Home Assistant custom integration \"Homematic(IP) Local\", which is powered by aiohomematic.\n\n1. Prerequisites\n - Use latest version of Home Assistant.\n - A CCU3, OpenCCU, or Homegear instance reachable from Home Assistant.\n - For HomematicIP devices, ensure CCU firmware meets the minimum versions listed below.\n2. Install the integration\n - Add the custom repository and install: https://github.com/sukramj/homematicip_local\n - Follow the installation guide: https://github.com/sukramj/homematicip_local/wiki/Installation\n3. Configure via Home Assistant UI\n - In Home Assistant: Settings \u2192 Devices & Services \u2192 Add Integration \u2192 search for \"Homematic(IP) Local\".\n - Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable TLS and don't use verify if self\u2011signed.\n - Always enter credentials.\n - Choose which interfaces to enable (HM, HmIP, Virtual). Default ports are typically 2001 (HM), 2010 (HmIP), 9292 (Virtual).\n4. Network callbacks\n - The integration needs to receive XML\u2011RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). Callbacks are only required for special network setups.\n5. Verify\n - After setup, devices should appear under Devices & Services \u2192 Homematic(IP) Local. Discovery may take a few seconds after the first connection while paramsets are fetched and cached for faster restarts.\n\nIf you need to use aiohomematic directly in Python, see the Public API and example below.\n\n## Requirements\n\nDue to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:\n\n- CCU2: 2.53.27\n- CCU3: 3.53.26\n\nSee details here: https://github.com/OpenCCU/OpenCCU/issues/843. Other CCU\u2011like platforms using the buggy HmIPServer version are not supported.\n\n## Public API and imports\n\n- The public API of aiohomematic is explicitly defined via **all** in each module and subpackage.\n- Backwards\u2011compatible imports should target these modules:\n - aiohomematic.central: CentralUnit, CentralConfig and related schemas\n - aiohomematic.central.event: display received events from the backend\n - aiohomematic.client: Client, InterfaceConfig, create_client, get_client\n - aiohomematic.model: device/data point abstractions (see subpackages for details)\n - aiohomematic.exceptions: library exception types intended for consumers\n - aiohomematic.const: constants and enums (stable subset; see module **all**)\n - aiohomematic.performance: display some performance metrics (enabled when DEBUG is enabled)\n- The top\u2011level package only exposes **version** to avoid import cycles and keep startup lean. Prefer importing from the specific submodules listed above.\n\nExample:\n\n from aiohomematic.central import CentralConfig\n from aiohomematic import client as hmcl\n\n cfg = CentralConfig(\n central_id=\"ccu-main\",\n host=\"ccu.local\",\n username=\"admin\",\n password=\"secret\",\n default_callback_port=43439,\n interface_configs={hmcl.InterfaceConfig(interface=hmcl.Interface.HMIP, port=2010, enabled=True)},\n )\n central = cfg.create_central()\n\n## Useful links\n\n- Changelog: [see](changelog.md) for release history and latest changes.\n- Definition of calculated data points: [see](docs/calculated_data_points.md)\n- Naming: [see](docs/naming.md) for how device, channel and data point names are created.\n- Homematic(IP) Local integration: https://github.com/sukramj/homematicip_local\n- Input select helper: [see](docs/input_select_helper.md) for an overview of how to use the input select helper.\n- Troubleshooting with Home Assistant: [see](docs/homeassistant_troubleshooting.md) for common issues and how to debug them.\n- Unignore mechanism: [see](docs/unignore.md) for how to unignore devices that are ignored by default.\n\n## Useful developer links\n\n- Architecture overview: [see](docs/architecture.md) for an overview of the architecture of the library.\n- Data flow: [see](docs/data_flow.md) for an overview of how data flows through the library.\n- Extending the model: [see](docs/extension_points.md) for adding custom device profiles and calculated data points.\n- Home Assistant lifecycle (discovery, updates, teardown): [see](docs/homeassistant_lifecycle.md) for details on how the integration works and how to debug issues.\n- RSSI fix: [see](docs/rssi_fix.md) for how RSSI values are fixed for Home Assistant.\n- Sequence diagrams: [see](docs/sequence_diagrams.md) for a sequence diagram of how the library works.\n\n[license-shield]: https://img.shields.io/github/license/SukramJ/aiohomematic.svg?style=for-the-badge\n[release]: https://github.com/SukramJ/aiohomematic/releases\n[releasebadge]: https://img.shields.io/github/v/release/SukramJ/aiohomematic?style=for-the-badge\n[sponsorsbadge]: https://img.shields.io/github/sponsors/SukramJ?style=for-the-badge&label=GitHub%20Sponsors&color=green\n[sponsors]: https://github.com/sponsors/SukramJ\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Homematic interface for Home Assistant running on Python 3.",
"version": "2025.11.2",
"project_urls": {
"Bug Reports": "https://github.com/sukramj/aiohomematic/issues",
"Docs: Dev": "https://github.com/sukramj/aiohomematic",
"Forum": "https://github.com/sukramj/aiohomematic/discussions",
"Homepage": "https://github.com/sukramj/aiohomematic",
"Source Code": "https://github.com/sukramj/aiohomematic"
},
"split_keywords": [
"home",
" automation",
" homematic",
" openccu",
" homegear"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f7f55b844c8211a619acf8b865b202b35d589c52c2880974f3b0f9b007b022a5",
"md5": "aa6dc9cf2c57a206e30fba3689231e27",
"sha256": "969a43d3ed38896a285748b0bf953e06d834cc47f52f90ff71758f384f3bf748"
},
"downloads": -1,
"filename": "aiohomematic-2025.11.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa6dc9cf2c57a206e30fba3689231e27",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 224734,
"upload_time": "2025-11-02T17:22:44",
"upload_time_iso_8601": "2025-11-02T17:22:44.816781Z",
"url": "https://files.pythonhosted.org/packages/f7/f5/5b844c8211a619acf8b865b202b35d589c52c2880974f3b0f9b007b022a5/aiohomematic-2025.11.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "09a22e6521f3e2eb36bcf946c0445e812e1a07768b01f54c01de69a7be2fac81",
"md5": "52d61d1be3ff01783bd83fd80bf12b14",
"sha256": "8fc052a543872b4c3a629726c6785d891dd7e413e7632c3ed32137af8b2a01e1"
},
"downloads": -1,
"filename": "aiohomematic-2025.11.2.tar.gz",
"has_sig": false,
"md5_digest": "52d61d1be3ff01783bd83fd80bf12b14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 196047,
"upload_time": "2025-11-02T17:22:46",
"upload_time_iso_8601": "2025-11-02T17:22:46.479134Z",
"url": "https://files.pythonhosted.org/packages/09/a2/2e6521f3e2eb36bcf946c0445e812e1a07768b01f54c01de69a7be2fac81/aiohomematic-2025.11.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 17:22:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sukramj",
"github_project": "aiohomematic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.13.2"
]
]
},
{
"name": "orjson",
"specs": [
[
">=",
"3.11.4"
]
]
},
{
"name": "python-slugify",
"specs": [
[
">=",
"8.0.4"
]
]
},
{
"name": "voluptuous",
"specs": [
[
">=",
"0.15.2"
]
]
}
],
"lcname": "aiohomematic"
}
JSON
