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
• Extensible via custom entity classes for complex devices (thermostats, lights, covers, locks, sirens)
• Fast startups through caching of paramsets
• Robust operation with automatic reconnection after CCU restarts
• Fully typed with strict mypy compliance
• 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 guide
Developer Guide	API reference for integrations
Architecture	System design overview
Glossary	Terminology reference

How It Works

┌─────────────────────────────────────────────────────────┐
│                    Home Assistant                       │
│                                                         │
│  ┌────────────────────────────────────────────────────┐ │
│  │           Homematic(IP) Local Integration          │ │
│  │                                                    │ │
│  │  • Home Assistant entities (climate, light, etc.)  │ │
│  │  • UI configuration flows                          │ │
│  │  • Services and automations                        │ │
│  │  • Device/entity registry integration              │ │
│  └────────────────────────┬───────────────────────────┘ │
└───────────────────────────┼─────────────────────────────┘
                            │
                            │ uses
                            ▼
┌───────────────────────────────────────────────────────────┐
│                      aiohomematic                         │
│                                                           │
│  • Protocol implementation (XML-RPC, JSON-RPC)            │
│  • Device model and data point abstraction                │
│  • Connection management and reconnection                 │
│  • Event handling and callbacks                           │
│  • Caching for fast startups                              │
└───────────────────────────────────────────────────────────┘
                            │
                            │ communicates with
                            ▼
┌───────────────────────────────────────────────────────────┐
│              CCU3 / OpenCCU / Homegear                    │
└───────────────────────────────────────────────────────────┘

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 and notifies subscribers
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. Add the custom repository: https://github.com/sukramj/homematicip_local
2. Install via HACS
3. Configure via Settings → Devices & Services → Add Integration

See the Integration Guide for detailed instructions.

For Developers

pip install aiohomematic

Quick Start

from aiohomematic.central import CentralConfig
from aiohomematic.client import InterfaceConfig
from aiohomematic.const import Interface

config = CentralConfig(
    central_id="ccu-main",
    host="ccu.local",
    username="admin",
    password="secret",
    default_callback_port=43439,
    interface_configs={
        InterfaceConfig(central_name="ccu-main", interface=Interface.HMIP_RF, port=2010)
    },
)

central = config.create_central()
await central.start()

for device in central.devices:
    print(f"{device.name}: {device.device_address}")

await central.stop()

See Getting Started for more examples.

Requirements

• Python: 3.13+
• CCU Firmware: CCU2 ≥2.61.x, CCU3 ≥3.61.x
• There is not active testing to identify the minimum required firmware versions.

Important Notes on Backend Supportf

Actively tested backends:

• OpenCCU with current firmware

Not actively tested:

• CCU2
• Homegear

Running outdated firmware versions or using 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 depends on.

Related Projects

Project	Description
Homematic(IP) Local	Home Assistant integration
aiohomematic Documentation	Full documentation

Contributing

Contributions are welcome! See the Contributing Guide for details.

License

MIT License - see LICENSE for details.

Support

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