AIO Homematic (hahomematic)
A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring Homematic and HomematicIP devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.
This project is the modern successor to 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.
- 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.
- 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
- 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).
- 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.
- 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 for release history and latest changes.
- Definition of calculated data points: see
- Naming: see for how device, channel and data point names are created.
- Homematic(IP) Local integration: https://github.com/sukramj/homematicip_local
- Input select helper: see for an overview of how to use the input select helper.
- Troubleshooting with Home Assistant: see for common issues and how to debug them.
- Unignore mechanism: see for how to unignore devices that are ignored by default.
Useful developer links
- Architecture overview: see for an overview of the architecture of the library.
- Data flow: see for an overview of how data flows through the library.
- Extending the model: see for adding custom device profiles and calculated data points.
- Home Assistant lifecycle (discovery, updates, teardown): see for details on how the integration works and how to debug issues.
- RSSI fix: see for how RSSI values are fixed for Home Assistant.
- Sequence diagrams: see for a sequence diagram of how the library works.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file aiohomematic-2025.9.8.tar.gz.
File metadata
- Download URL: aiohomematic-2025.9.8.tar.gz
- Upload date:
- Size: 211.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8a6256de62b4fe86f89265ea60d95996ba6cb9b1bb366913f65eb816b98287f4
|
|
| MD5 |
48b0ec52cc5ec5152f70b2776cc9b2c3
|
|
| BLAKE2b-256 |
b8f20fee2424cb921b05533231b3741a0a4d00299473c6ad2b013ca26a1be33f
|
Provenance
The following attestation bundles were made for aiohomematic-2025.9.8.tar.gz:
Publisher:
python-publish.yml on SukramJ/aiohomematic
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
aiohomematic-2025.9.8.tar.gz -
Subject digest:
8a6256de62b4fe86f89265ea60d95996ba6cb9b1bb366913f65eb816b98287f4 - Sigstore transparency entry: 567903743
- Sigstore integration time:
-
Permalink:
SukramJ/aiohomematic@36101e81fd22591b27401e84196f861b891cf1fa -
Branch / Tag:
refs/tags/2025.9.8 - Owner: https://github.com/SukramJ
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@36101e81fd22591b27401e84196f861b891cf1fa -
Trigger Event:
release
-
Statement type:
File details
Details for the file aiohomematic-2025.9.8-py3-none-any.whl.
File metadata
- Download URL: aiohomematic-2025.9.8-py3-none-any.whl
- Upload date:
- Size: 214.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7660f6cf4356ad85de0e5096fc0ee063b45c0dbc83febcb4ea7aaa5c9126a297
|
|
| MD5 |
7f2e9a0b26941e1b4c1504f0e04ac9b1
|
|
| BLAKE2b-256 |
06dc2570533ccc93c00ade990080bb8e3faacf1b56829e57511ba18cb8877cff
|
Provenance
The following attestation bundles were made for aiohomematic-2025.9.8-py3-none-any.whl:
Publisher:
python-publish.yml on SukramJ/aiohomematic
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
aiohomematic-2025.9.8-py3-none-any.whl -
Subject digest:
7660f6cf4356ad85de0e5096fc0ee063b45c0dbc83febcb4ea7aaa5c9126a297 - Sigstore transparency entry: 567903748
- Sigstore integration time:
-
Permalink:
SukramJ/aiohomematic@36101e81fd22591b27401e84196f861b891cf1fa -
Branch / Tag:
refs/tags/2025.9.8 - Owner: https://github.com/SukramJ
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@36101e81fd22591b27401e84196f861b891cf1fa -
Trigger Event:
release
-
Statement type:
