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, 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 EventBus for 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

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 / 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?

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

1. Homematic(IP) Local creates a CentralUnit via aiohomematic's API
2. aiohomematic connects to the CCU and discovers devices
3. aiohomematic creates Device, Channel, and DataPoint objects
4. Homematic(IP) Local wraps these in Home Assistant entities
5. aiohomematic receives events from the CCU (XML-RPC callbacks or MQTT bridge for CUxD/CCU-Jack) and notifies subscribers via the EventBus
6. Homematic(IP) Local translates events into Home Assistant state updates

For Home Assistant Users

Use the Home Assistant custom integration Homematic(IP) Local:

1. From Home Assistant 2026.11 on, open the Home Assistant Marketplace, search for Homematic(IP) Local for OpenCCU and install it. On earlier versions, install HACS and add https://github.com/SukramJ/homematicip_local as a custom repository (category: Integration).
2. Restart Home Assistant.
3. 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

Running outdated firmware or untested backends (CCU2) is at your own risk.

OpenCCU Lite: OpenCCU Lite (a CCU platform without ReGaHSS) is not supported by aiohomematic. Use it with the OpenCCU Loom backend and openccu-loom-client in Homematic(IP) Local instead.

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

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.