aiohomematic
A modern, async Python library for controlling and monitoring Homematic and HomematicIP devices. Powers the Home Assistant integration "Homematic(IP) Local".
This project is the modern successor to pyhomematic, focusing on automatic entity creation, fewer manual device definitions, and faster startups.
Key Features
- Automatic entity discovery from device/channel parameters
- Broad backend support: CCU3, OpenCCU, Homegear, CUxD, CCU-Jack, and godevccu for testing
- Multiple transport protocols: XML-RPC (standard interfaces) and JSON-RPC (CUxD / CCU-Jack), with MQTT event forwarding via Homematic(IP) Local
- Extensible via custom entity classes for complex devices (climate, cover, light, lock, siren, valve, …)
- Hub entities for CCU programs, system variables, inbox messages, install mode, and service messages
- Event-driven architecture with a unified
EventBusfor lifecycle, state, and diagnostic events - Fast startups through paramset and description caching
- Robust operation with circuit breaker, command retry/throttling, and automatic reconnection after CCU restarts
- Fully typed (mypy strict mode) and async/await based on asyncio
Documentation
Full documentation: sukramj.github.io/aiohomematic
| Section | Description |
|---|---|
| Getting Started | Installation and first steps |
| User Guide | Home Assistant integration and device topics |
| Developer Guide | API reference for library consumers |
| Contributor Guide | Dev environment, coding standards, release process |
| Architecture & ADRs | System design and decision records |
Additional entry points in this repository: CLAUDE.md (AI assistant / contributor quick-reference), AI_POLICY.md (rules for AI-assisted contributions) and changelog.md.
How It Works
┌─────────────────────────────────────────────────────────┐
│ Home Assistant │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Homematic(IP) Local Integration │ │
│ │ │ │
│ │ • Home Assistant entities (climate, light, etc.) │ │
│ │ • UI configuration flows │ │
│ │ • Services and automations │ │
│ │ • MQTT bridge for CUxD / CCU-Jack events │ │
│ └────────────────────────┬───────────────────────────┘ │
└───────────────────────────┼─────────────────────────────┘
│
│ uses
▼
┌───────────────────────────────────────────────────────────┐
│ aiohomematic │
│ │
│ • Protocol adapters (XML-RPC, JSON-RPC) │
│ • Device model and data point abstraction │
│ • Connection management and reconnection │
│ • EventBus for lifecycle / state / diagnostic events │
│ • Caching (paramset, device descriptions, sessions) │
└───────────────────────────────────────────────────────────┘
│
│ communicates with
▼
┌────────────────────────────────────────────────────────────┐
│ CCU3 / OpenCCU / Homegear / CUxD / CCU-Jack │
└────────────────────────────────────────────────────────────┘
CUxD and CCU-Jack use JSON-RPC and receive events via MQTT forwarded by the Home Assistant integration — see CUxD and CCU-Jack for details.
Why Two Projects?
| Aspect | aiohomematic | Homematic(IP) Local |
|---|---|---|
| Purpose | Python library for Homematic protocol | Home Assistant integration |
| Scope | Protocol, devices, data points | HA entities, UI, services |
| Dependencies | Standalone (aiohttp, orjson) | Requires Home Assistant |
| Reusability | Any Python project | Home Assistant only |
| Repository | aiohomematic | homematicip_local |
Benefits of this separation:
- Reusability: aiohomematic can be used in any Python project, not just Home Assistant
- Testability: The library can be tested independently without Home Assistant
- Maintainability: Protocol changes don't affect HA-specific code and vice versa
- Clear boundaries: Each project has a focused responsibility
How They Work Together
- Homematic(IP) Local creates a
CentralUnitvia aiohomematic's API - aiohomematic connects to the CCU/Homegear and discovers devices
- aiohomematic creates
Device,Channel, andDataPointobjects - Homematic(IP) Local wraps these in Home Assistant entities
- aiohomematic receives events from the CCU (XML-RPC callbacks or MQTT bridge for CUxD/CCU-Jack) and notifies subscribers via the
EventBus - Homematic(IP) Local translates events into Home Assistant state updates
For Home Assistant Users
Use the Home Assistant custom integration Homematic(IP) Local:
- Install HACS in your Home Assistant instance (see HACS documentation).
- In HACS, add
https://github.com/SukramJ/homematicip_localas a custom repository (category: Integration). - Install Homematic(IP) Local via HACS and restart Home Assistant.
- Configure the integration under Settings → Devices & Services → Add Integration.
See the Integration Guide for detailed instructions.
For Developers
pip install aiohomematic
Quick Start
import asyncio
from aiohomematic.central import CentralConfig
from aiohomematic.client import InterfaceConfig
from aiohomematic.const import Interface
async def main() -> None:
config = CentralConfig(
central_id="ccu-main",
name="ccu-main",
host="ccu.local",
username="admin",
password="secret",
interface_configs={
InterfaceConfig(central_name="ccu-main", interface=Interface.HMIP_RF, port=2010),
},
)
central = await config.create_central()
await central.start()
for device in central.devices:
print(f"{device.name}: {device.address}")
await central.stop()
asyncio.run(main())
For a more complete example (multiple interfaces, event subscriptions, .env loading) see example.py. For API usage patterns see the Consumer API guide.
Contributing
- Development environment:
docs/contributor/dev-environment.md - Contract tests (protocol / capability invariants, incl. CUxD / CCU-Jack):
tests/contract/ - Benchmarks:
tests/benchmarks/ - AI assistant / contributor quick-reference:
CLAUDE.md
Requirements
- Python: 3.14+
- CCU firmware: CCU3 ≥ 3.61.x recommended; CCU2 ≥ 2.61.x is best-effort (see backend support below)
- No active testing is performed to identify the minimum required firmware versions — stay on a current release.
Backend Support
- Primary test targets (continuously tested in CI):
- OpenCCU with current firmware
godevccu(virtual CCU used in the automated test suite)
- Supported, best-effort (expected to work, not continuously tested):
- CCU3 with current firmware
- CUxD (via JSON-RPC)
- CCU-Jack (via JSON-RPC)
- Legacy / unsupported:
- CCU2 — works with recent firmware but is not actively tested
- Homegear — not actively tested
Running outdated firmware or untested backends (CCU2, Homegear) is at your own risk.
Recommendation: keep your CCU firmware up to date. Outdated versions may lack bug fixes, security patches, and compatibility improvements that this library relies on.
Related Projects
| Project | Description |
|---|---|
| Homematic(IP) Local | Home Assistant integration built on aiohomematic |
| godevccu | Virtual CCU used as a test target |
| pyhomematic | Predecessor project (no longer actively developed) |
Contributing
Contributions are welcome! See the Contributing Guide and the in-repo CLAUDE.md for coding standards and the refactoring checklist.
Development
Parts of aiohomematic are developed with agentic AI assistance, primarily Claude Code. Submitted issues are also triaged and analyzed with agentic help. Every change is still reviewed by a human maintainer and must pass the project's test suite before it lands — AI accelerates the work, it does not replace the review gate.
License
MIT License - see LICENSE for details.
Support
If you find this project useful, consider sponsoring the development.
1 maintainer
Metadata
1 maintainer
Release files for aiohomematic 2026.10.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aiohomematic-2026.10.3.tar.gz | 597.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aiohomematic-2026.10.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.3 MB
Release files / aiohomematic-2026.10.3.tar.gz
| Download URL | aiohomematic-2026.10.3.tar.gz |
|---|---|
| Size | 597.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ddc35e78fa2caa46dbd117f922119e7cd104ab01361d7d51f1b19eaa09ebe20
|
|
BLAKE2b-256 checksum How to use checksums |
8660267a97953003225a1aef0ac96191fc9f6e519279d90846747bdaf3a09711
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / aiohomematic-2026.10.3-py3-none-any.whl
| Download URL | aiohomematic-2026.10.3-py3-none-any.whl |
|---|---|
| Size | 717.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
434f8863f268aaf80ba9f7b85cc18f36989a3fce802c207388aa168ca934b02c
|
|
BLAKE2b-256 checksum How to use checksums |
011d70ef6ac27aa2cf0693bfd3a55a7bfbc97ffa08592b072152795b2b14a7ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency log
