aiohomematic

What it is and what it does

aiohomematic is a modern async Python library that abstracts the Homematic protocol stack, allowing you to discover, control, and monitor Homematic and HomematicIP devices connected to a CCU hub or compatible backend. It replaces the older pyhomematic project with automatic entity discovery, fewer manual device definitions, and faster startup times. The library handles connection management, event routing through a unified EventBus, protocol translation (XML-RPC for standard interfaces, JSON-RPC for CUxD/CCU-Jack), and caching of device descriptions and paramsets.

The library is built on asyncio and fully typed (mypy strict mode), making it suitable for integration into larger async applications—most notably as the backend for the Home Assistant "Homematic(IP) Local" integration. It supports extensible entity classes for complex device types (climate, cover, light, lock, siren, valve), hub entities for CCU programs and system variables, and robust operation through circuit breaker patterns, command retry/throttling, and automatic reconnection after CCU restarts.

Use it for:

• Build a Home Assistant integration or custom automation platform that controls Homematic devices without polling.
• Monitor Homematic device state and respond to events in real-time via the EventBus in a standalone Python application.
• Integrate Homematic climate, lighting, or lock devices into a broader home automation system using async/await patterns.
• Manage CCU programs, system variables, and inbox messages programmatically alongside device control.
• Test Homematic protocol implementations using pydevccu without requiring physical hardware.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An async Python library for controlling and monitoring Homematic and HomematicIP devices through multiple backend systems (CCU3, OpenCCU, Homegear, CUxD, CCU-Jack) using XML-RPC and JSON-RPC protocols.

Yes. The library is actively maintained (release 4 days old), has no known vulnerabilities, uses a permissive MIT license, and requires only four lightweight runtime dependencies. It is marked Production/Stable and powers a real Home Assistant integration. Install it if you need to control Homematic devices from Python; the only constraint is a requirement for Python 3.14 or later and network access to a compatible Homematic backend.

Install

aiohomematic on PyPI

pip install aiohomematic

uv add aiohomematic

poetry add aiohomematic

Installing aiohomematic

Before you install

Low friction install with four runtime dependencies (aiohttp, openccu-data, pydantic, python-slugify). Active maintenance with a release 4 days old and recent commits; marked Production/Stable with 167 repository stars.

License in practice

MIT License permits free use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart

pip install aiohomematic

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

async def main():
    config = CentralConfig(
        central_id="ccu-main",
        name="ccu-main",
        host="ccu.local",
        interface_configs={
            InterfaceConfig(central_name="ccu-main", interface=Interface.HMIP_RF, port=2010),
        },
    )
    central = await config.create_central()
    await central.start()

Requires Python 3.14 or later; requires network access to a Homematic CCU, OpenCCU, Homegear, CUxD, or CCU-Jack device.

Verify before relying

• Whether the library's circuit breaker and reconnection logic handles all failure modes in production environments.
• Performance characteristics when managing large numbers of devices or frequent state changes.
• Compatibility with specific Homematic device models and firmware versions beyond those listed.

Package facts

Evidence: aiohomematic-2026.8.2-py3-none-any.whl

Keywords: home, automation, homematic, openccu, homegear

Tags

More Python Modules packages