{"id":34582380,"url":"https://github.com/sukramj/aiohomematic","last_synced_at":"2026-05-29T13:01:01.285Z","repository":{"id":38026635,"uuid":"354983911","full_name":"SukramJ/aiohomematic","owner":"SukramJ","description":"Python 3 Interface to interact with HomeMatic devices","archived":false,"fork":false,"pushed_at":"2026-05-29T11:46:38.000Z","size":18710,"stargazers_count":166,"open_issues_count":0,"forks_count":25,"subscribers_count":10,"default_branch":"devel","last_synced_at":"2026-05-29T12:13:20.678Z","etag":null,"topics":["ccu","eq-3","homematic","homematicip","json-rpc","openccu","xml-rpc"],"latest_commit_sha":null,"homepage":"https://sukramj.github.io/aiohomematic/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SukramJ.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"SukramJ","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"sukramj","thanks_dev":null,"custom":null}},"created_at":"2021-04-05T22:01:04.000Z","updated_at":"2026-05-29T11:16:39.000Z","dependencies_parsed_at":"2026-02-16T11:02:19.331Z","dependency_job_id":null,"html_url":"https://github.com/SukramJ/aiohomematic","commit_stats":null,"previous_names":["sukramj/hahomematic","danielperna84/hahomematic","sukramj/aiohomematic"],"tags_count":1004,"template":false,"template_full_name":null,"purl":"pkg:github/SukramJ/aiohomematic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SukramJ%2Faiohomematic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SukramJ%2Faiohomematic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SukramJ%2Faiohomematic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SukramJ%2Faiohomematic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SukramJ","download_url":"https://codeload.github.com/SukramJ/aiohomematic/tar.gz/refs/heads/devel","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SukramJ%2Faiohomematic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33652986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ccu","eq-3","homematic","homematicip","json-rpc","openccu","xml-rpc"],"created_at":"2025-12-24T10:19:01.869Z","updated_at":"2026-05-29T13:01:01.186Z","avatar_url":"https://github.com/SukramJ.png","language":"Python","funding_links":["https://github.com/sponsors/SukramJ","https://buymeacoffee.com/sukramj"],"categories":[],"sub_categories":[],"readme":"[![Release][releasebadge]][release]\n[![License][license-shield]](LICENSE)\n[![Python][pythonbadge]][release]\n[![GitHub Sponsors][sponsorsbadge]][sponsors]\n\n# aiohomematic\n\nA 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\".\n\nThis project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.\n\n## Key Features\n\n- **Automatic entity discovery** from device/channel parameters\n- **Broad backend support**: CCU3, OpenCCU, Homegear, CUxD, CCU-Jack, and [pydevccu](https://github.com/danielperna84/pydevccu) for testing\n- **Multiple transport protocols**: XML-RPC (standard interfaces) and JSON-RPC (CUxD / CCU-Jack), with MQTT event forwarding via Homematic(IP) Local\n- **Extensible** via custom entity classes for complex devices (climate, cover, light, lock, siren, valve, …)\n- **Hub entities** for CCU programs, system variables, inbox messages, install mode, and service messages\n- **Event-driven architecture** with a unified `EventBus` for lifecycle, state, and diagnostic events\n- **Fast startups** through paramset and description caching\n- **Robust operation** with circuit breaker, command retry/throttling, and automatic reconnection after CCU restarts\n- **Fully typed** (mypy strict mode) and **async/await** based on asyncio\n\n## Documentation\n\n**Full documentation:** [sukramj.github.io/aiohomematic](https://sukramj.github.io/aiohomematic/)\n\n| Section                                                                               | Description                                        |\n| ------------------------------------------------------------------------------------- | -------------------------------------------------- |\n| [Getting Started](https://sukramj.github.io/aiohomematic/getting_started/)            | Installation and first steps                       |\n| [User Guide](https://sukramj.github.io/aiohomematic/user/homeassistant_integration/)  | Home Assistant integration and device topics       |\n| [Developer Guide](https://sukramj.github.io/aiohomematic/developer/consumer_api/)     | API reference for library consumers                |\n| [Contributor Guide](https://sukramj.github.io/aiohomematic/contributor/contributing/) | Dev environment, coding standards, release process |\n| [Architecture \u0026 ADRs](https://sukramj.github.io/aiohomematic/architecture/)           | System design and decision records                 |\n\nAdditional entry points in this repository: [`CLAUDE.md`](CLAUDE.md) (AI assistant / contributor quick-reference) and [`changelog.md`](changelog.md).\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    Home Assistant                       │\n│                                                         │\n│  ┌────────────────────────────────────────────────────┐ │\n│  │           Homematic(IP) Local Integration          │ │\n│  │                                                    │ │\n│  │  • Home Assistant entities (climate, light, etc.)  │ │\n│  │  • UI configuration flows                          │ │\n│  │  • Services and automations                        │ │\n│  │  • MQTT bridge for CUxD / CCU-Jack events          │ │\n│  └────────────────────────┬───────────────────────────┘ │\n└───────────────────────────┼─────────────────────────────┘\n                            │\n                            │ uses\n                            ▼\n┌───────────────────────────────────────────────────────────┐\n│                      aiohomematic                         │\n│                                                           │\n│  • Protocol adapters (XML-RPC, JSON-RPC)                  │\n│  • Device model and data point abstraction                │\n│  • Connection management and reconnection                 │\n│  • EventBus for lifecycle / state / diagnostic events     │\n│  • Caching (paramset, device descriptions, sessions)      │\n└───────────────────────────────────────────────────────────┘\n                            │\n                            │ communicates with\n                            ▼\n┌────────────────────────────────────────────────────────────┐\n│     CCU3 / OpenCCU / Homegear / CUxD / CCU-Jack            │\n└────────────────────────────────────────────────────────────┘\n```\n\nCUxD and CCU-Jack use JSON-RPC and receive events via MQTT forwarded by the Home Assistant integration — see [CUxD and CCU-Jack](https://sukramj.github.io/aiohomematic/user/advanced/cuxd_ccu_jack/) for details.\n\n### Why Two Projects?\n\n| Aspect           | aiohomematic                                            | Homematic(IP) Local                                               |\n| ---------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| **Purpose**      | Python library for Homematic protocol                   | Home Assistant integration                                        |\n| **Scope**        | Protocol, devices, data points                          | HA entities, UI, services                                         |\n| **Dependencies** | Standalone (aiohttp, orjson)                            | Requires Home Assistant                                           |\n| **Reusability**  | Any Python project                                      | Home Assistant only                                               |\n| **Repository**   | [aiohomematic](https://github.com/SukramJ/aiohomematic) | [homematicip_local](https://github.com/SukramJ/homematicip_local) |\n\n**Benefits of this separation:**\n\n- **Reusability**: aiohomematic can be used in any Python project, not just Home Assistant\n- **Testability**: The library can be tested independently without Home Assistant\n- **Maintainability**: Protocol changes don't affect HA-specific code and vice versa\n- **Clear boundaries**: Each project has a focused responsibility\n\n### How They Work Together\n\n1. **Homematic(IP) Local** creates a `CentralUnit` via aiohomematic's API\n2. **aiohomematic** connects to the CCU/Homegear and discovers devices\n3. **aiohomematic** creates `Device`, `Channel`, and `DataPoint` objects\n4. **Homematic(IP) Local** wraps these in Home Assistant entities\n5. **aiohomematic** receives events from the CCU (XML-RPC callbacks or MQTT bridge for CUxD/CCU-Jack) and notifies subscribers via the `EventBus`\n6. **Homematic(IP) Local** translates events into Home Assistant state updates\n\n## For Home Assistant Users\n\nUse the Home Assistant custom integration **Homematic(IP) Local**:\n\n1. Install **HACS** in your Home Assistant instance (see [HACS documentation](https://hacs.xyz/)).\n2. In HACS, add `https://github.com/SukramJ/homematicip_local` as a **custom repository** (category: Integration).\n3. Install **Homematic(IP) Local** via HACS and restart Home Assistant.\n4. Configure the integration under **Settings** → **Devices \u0026 Services** → **Add Integration**.\n\nSee the [Integration Guide](https://sukramj.github.io/aiohomematic/user/homeassistant_integration/) for detailed instructions.\n\n## For Developers\n\n```bash\npip install aiohomematic\n```\n\n### Quick Start\n\n```python\nimport asyncio\n\nfrom aiohomematic.central import CentralConfig\nfrom aiohomematic.client import InterfaceConfig\nfrom aiohomematic.const import Interface\n\n\nasync def main() -\u003e None:\n    config = CentralConfig(\n        central_id=\"ccu-main\",\n        name=\"ccu-main\",\n        host=\"ccu.local\",\n        username=\"admin\",\n        password=\"secret\",\n        interface_configs={\n            InterfaceConfig(central_name=\"ccu-main\", interface=Interface.HMIP_RF, port=2010),\n        },\n    )\n\n    central = await config.create_central()\n    await central.start()\n\n    for device in central.devices:\n        print(f\"{device.name}: {device.address}\")\n\n    await central.stop()\n\n\nasyncio.run(main())\n```\n\nFor a more complete example (multiple interfaces, event subscriptions, `.env` loading) see [`example.py`](example.py). For API usage patterns see the [Consumer API guide](https://sukramj.github.io/aiohomematic/developer/consumer_api/).\n\n### Contributing\n\n- **Development environment**: [`docs/contributor/dev-environment.md`](https://sukramj.github.io/aiohomematic/contributor/dev-environment/)\n- **Contract tests** (protocol / capability invariants, incl. CUxD / CCU-Jack): [`tests/contract/`](tests/contract/)\n- **Benchmarks**: [`tests/benchmarks/`](tests/benchmarks/)\n- **AI assistant / contributor quick-reference**: [`CLAUDE.md`](CLAUDE.md)\n\n## Requirements\n\n- **Python**: 3.14+\n- **CCU firmware**: CCU3 ≥ 3.61.x recommended; CCU2 ≥ 2.61.x is best-effort (see backend support below)\n- No active testing is performed to identify the minimum required firmware versions — stay on a current release.\n\n### Backend Support\n\n- **Primary test targets** (continuously tested in CI):\n  - OpenCCU with current firmware\n  - `pydevccu` (virtual CCU used in the automated test suite)\n- **Supported, best-effort** (expected to work, not continuously tested):\n  - CCU3 with current firmware\n  - CUxD (via JSON-RPC)\n  - CCU-Jack (via JSON-RPC)\n- **Legacy / unsupported**:\n  - CCU2 — works with recent firmware but is not actively tested\n  - Homegear — not actively tested\n\nRunning outdated firmware or untested backends (CCU2, Homegear) is at your own risk.\n\n**Recommendation:** keep your CCU firmware up to date. Outdated versions may lack bug fixes, security patches, and compatibility improvements that this library relies on.\n\n## Related Projects\n\n| Project                                                             | Description                                        |\n| ------------------------------------------------------------------- | -------------------------------------------------- |\n| [Homematic(IP) Local](https://github.com/SukramJ/homematicip_local) | Home Assistant integration built on aiohomematic   |\n| [pydevccu](https://github.com/danielperna84/pydevccu)               | Virtual CCU used as a test target                  |\n| [pyhomematic](https://github.com/danielperna84/pyhomematic)         | Predecessor project (no longer actively developed) |\n\n## Contributing\n\nContributions are welcome! See the [Contributing Guide](https://sukramj.github.io/aiohomematic/contributor/contributing/) and the in-repo [`CLAUDE.md`](CLAUDE.md) for coding standards and the refactoring checklist.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Support\n\n[![GitHub Sponsors][sponsorsbadge]][sponsors]\n\nIf you find this project useful, consider [sponsoring](https://github.com/sponsors/SukramJ) the development.\n\n[license-shield]: https://img.shields.io/github/license/SukramJ/aiohomematic.svg?style=for-the-badge\n[pythonbadge]: https://img.shields.io/badge/Python-3.14+-blue?style=for-the-badge\u0026logo=python\u0026logoColor=white\n[release]: https://github.com/SukramJ/aiohomematic/releases\n[releasebadge]: https://img.shields.io/github/v/release/SukramJ/aiohomematic?style=for-the-badge\n[sponsorsbadge]: https://img.shields.io/github/sponsors/SukramJ?style=for-the-badge\u0026label=Sponsors\u0026color=ea4aaa\n[sponsors]: https://github.com/sponsors/SukramJ\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsukramj%2Faiohomematic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsukramj%2Faiohomematic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsukramj%2Faiohomematic/lists"}