aiohomematic¶

Modern async Python library for Homematic and HomematicIP devices.

aiohomematic powers the Homematic(IP) Local integration for Home Assistant, enabling local control of Homematic devices without cloud dependency.

Features¶

• Async-first: Built on asyncio for non-blocking I/O operations
• Type-safe: Fully typed with strict mypy enforcement
• Auto-discovery: Automatic entity creation from device parameters
• Extensible: Custom entity classes for device-specific features
• Fast startup: Paramset caching for quick initialization
• Multi-backend: Supports CCU3, CCU2, Homegear, and RaspberryMatic

Quick Start¶

Installation¶

pip install aiohomematic

Basic Usage¶

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

async def main():
    # Configure the central unit
    config = CentralConfig(
        name="my-ccu",
        host="192.168.1.100",
        username="Admin",
        password="your-password",
        central_id="my-central",
        interface_configs={
            InterfaceConfig(
                central_name="my-ccu",
                interface=Interface.HMIP_RF,
                port=2010,
            ),
        },
    )

    # Create and start the central
    central = config.create_central()
    await central.start()

    # Access devices
    for address, device in central.devices.items():
        print(f"Device: {device.name} ({address})")

    # Stop the central
    await central.stop()

asyncio.run(main())

Documentation Overview¶

For Users (Home Assistant)¶

• User Guide - Complete integration guide
• Features:
• Actions Reference - Available Home Assistant actions
• CCU Backup - Backup agent and manual backup
• Calculated Climate Sensors - Derived climate metrics
• Climate Schedule Card - Climate schedule UI card
• Device Configuration Panel - Device configuration in HA
• Optimistic Updates - Instant UI feedback and rollback
• Schedule Card - Schedule management UI card
• Week Profile - Weekly schedule management
• Troubleshooting - Common issues and solutions
• FAQ - Frequently asked questions
• Glossary - Terminology reference

For Developers (Library Usage)¶

• Quick Start - Get running in 5 minutes
• Getting Started - Detailed setup guide
• Consumer API - API patterns for integrations
• API Reference - Auto-generated API docs
• Architecture - System design overview
• Protocol Selection Guide - Choosing the right protocol interface

For Contributors¶

• Contributing - How to contribute
• Coding Standards - Naming and style conventions
• ADRs - Architecture Decision Records
• Changelog - Version history

Supported Devices¶

aiohomematic supports a wide range of Homematic and HomematicIP devices:

For a complete list, see the Extension Points documentation.

Two Projects, One Ecosystem¶

This documentation covers two related but separate projects:

Which documentation do I need?¶

• Home Assistant user? → Start with the User Guide
• Building a Python application? → See Quick Start and Consumer API
• Contributing code? → Check the Contributor Guide

Architecture Overview¶

Home Assistant
     │
     ▼
Homematic(IP) Local Integration    ← HA-specific: entities, services, UI
     │
     ▼
aiohomematic Library               ← Standalone: protocol, devices, events
     │
     ▼
CCU3 / OpenCCU / Homegear          ← Backend hardware/software
     │
     ▼
Homematic Devices                  ← Physical devices

See Home Assistant Lifecycle for detailed integration flow.

Links¶

• GitHub: sukramj/aiohomematic
• PyPI: aiohomematic
• Issues: Report a bug
• Discussions: Ask questions
• HA Integration: homematicip_local

License¶

MIT License - see LICENSE for details.