aiohomematic 2026.4.18

Homematic interface for Home Assistant running on Python 3.

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 pydevccu 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

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) 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

1. Homematic(IP) Local creates a CentralUnit via aiohomematic's API
2. aiohomematic connects to the CCU/Homegear 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. Install HACS in your Home Assistant instance (see HACS documentation).
2. In HACS, add https://github.com/SukramJ/homematicip_local as a custom repository (category: Integration).
3. Install Homematic(IP) Local via HACS and restart Home Assistant.
4. 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
  • pydevccu (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
pydevccu	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.

License

MIT License - see LICENSE for details.

Support

If you find this project useful, consider sponsoring the development.