Metadata-Version: 2.4
Name: aiohomematic
Version: 2026.4.2
Summary: Homematic interface for Home Assistant running on Python 3.
Home-page: https://github.com/sukramj/aiohomematic
Author-email: SukramJ <sukramj@icloud.com>, Daniel Perna <danielperna84@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/sukramj/aiohomematic
Project-URL: Source Code, https://github.com/sukramj/aiohomematic
Project-URL: Bug Reports, https://github.com/sukramj/aiohomematic/issues
Project-URL: Changelog, https://github.com/sukramj/aiohomematic/blob/devel/changelog.md
Project-URL: Documentation, https://sukramj.github.io/aiohomematic
Project-URL: Forum, https://github.com/sukramj/aiohomematic/discussions
Keywords: home,automation,homematic,openccu,homegear
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: German
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Framework :: AsyncIO
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.12.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-slugify>=8.0.0
Provides-Extra: fast
Requires-Dist: orjson>=3.11.0; extra == "fast"
Dynamic: license-file

[![Release][releasebadge]][release]
[![License][license-shield]](LICENSE)
[![Python][pythonbadge]][release]
[![GitHub Sponsors][sponsorsbadge]][sponsors]

# aiohomematic

A modern, async Python library for controlling and monitoring [Homematic](https://www.eq-3.com/products/homematic.html) and [HomematicIP](https://www.homematic-ip.com/en/start.html) devices. Powers the Home Assistant integration "Homematic(IP) Local".

This project is the modern successor to [pyhomematic](https://github.com/danielperna84/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](https://sukramj.github.io/aiohomematic/)

| Section                                                                              | Description                      |
| ------------------------------------------------------------------------------------ | -------------------------------- |
| [Getting Started](https://sukramj.github.io/aiohomematic/getting_started/)           | Installation and first steps     |
| [User Guide](https://sukramj.github.io/aiohomematic/user/homeassistant_integration/) | Home Assistant integration guide |
| [Developer Guide](https://sukramj.github.io/aiohomematic/developer/consumer_api/)    | API reference for integrations   |
| [Architecture](https://sukramj.github.io/aiohomematic/architecture/)                 | System design overview           |
| [Glossary](https://sukramj.github.io/aiohomematic/reference/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](https://github.com/sukramj/aiohomematic) | [homematicip_local](https://github.com/sukramj/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](https://sukramj.github.io/aiohomematic/user/homeassistant_integration/) for detailed instructions.

## For Developers

```bash
pip install aiohomematic
```

### Quick Start

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

config = CentralConfig(
    name="ccu-main",
    host="ccu.local",
    username="admin",
    password="secret",
    default_callback_port_xml_rpc=43439,
    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()
```

See [Getting Started](https://sukramj.github.io/aiohomematic/getting_started/) for more examples.

## Requirements

- **Python**: 3.14+
- **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 Support

**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](https://github.com/sukramj/homematicip_local)   | Home Assistant integration |
| [aiohomematic Documentation](https://sukramj.github.io/aiohomematic/) | Full documentation         |

## Contributing

Contributions are welcome! See the [Contributing Guide](https://sukramj.github.io/aiohomematic/contributor/contributing/) for details.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

[![GitHub Sponsors][sponsorsbadge]][sponsors]

If you find this project useful, consider [sponsoring](https://github.com/sponsors/SukramJ) the development.

[license-shield]: https://img.shields.io/github/license/SukramJ/aiohomematic.svg?style=for-the-badge
[pythonbadge]: https://img.shields.io/badge/Python-3.14+-blue?style=for-the-badge&logo=python&logoColor=white
[release]: https://github.com/SukramJ/aiohomematic/releases
[releasebadge]: https://img.shields.io/github/v/release/SukramJ/aiohomematic?style=for-the-badge
[sponsorsbadge]: https://img.shields.io/github/sponsors/SukramJ?style=for-the-badge&label=Sponsors&color=ea4aaa
[sponsors]: https://github.com/sponsors/SukramJ
