Homematic(IP) Local for OpenCCU
February 15, 2026 · View on GitHub
Homematic(IP) Local for OpenCCU is a custom integration for Home Assistant.
At a Glance
- Local Home Assistant integration for Homematic(IP) hubs (CCU2/3, OpenCCU, Debmatic, Homegear). No cloud required.
- Communication: Local XML-RPC for control and push state updates; JSON-RPC for names and rooms.
- Installation: HACS recommended; manual installation supported.
- Auto-discovery: Supported for CCU and compatible hubs.
- Minimum requirements: Home Assistant 2025.10.0+; for Homematic IP on CCU require at least CCU2 2.61.x / CCU3 3.61.x.
Quick Start
| Resource | Link |
|---|---|
| Full Documentation | User Guide |
| Installation | See Installation below |
| Alternative Setup (OpenCCU) | OpenCCU Wiki |
| Changelog | changelog.md |
| Issues | GitHub Issues |
| Discussions | GitHub Discussions |
Related Integrations
| Integration | Use Case |
|---|---|
| This integration | Local connection to CCU2/3, OpenCCU, Debmatic, Homegear |
| Homematic(IP) Cloud | Cloud connection via Homematic IP Access Point |
| Homematic IP Local (HCU) | Local connection to HmIP-HCU1 |
Installation
HACS (Recommended)
- In Home Assistant, go to HACS > Integrations > Explore & Download Repositories
- Search for "Homematic(IP) Local for OpenCCU" and install it
- Restart Home Assistant when prompted
Manual Installation
- Copy the
custom_components/homematicip_localdirectory to your Home Assistantconfig/custom_componentsdirectory - Restart Home Assistant
Note: Manual installation does not support automatic updates.
After installation, add the integration via Settings > Devices & Services > Add Integration or use this button:
Requirements
Supported Hardware
- CCU2/3
- OpenCCU
- Debmatic
- Homegear
- Home Assistant OS/Supervised with suitable add-on + communication device
Required Ports
| Interface | Purpose | Port | TLS Port |
|---|---|---|---|
| HomematicIP (HmIP-RF) | Wireless/wired HmIP devices | 2010 | 42010 |
| Homematic (BidCos-RF) | Classic wireless devices | 2001 | 42001 |
| Homematic Wired | Classic wired devices | 2000 | 42000 |
| Virtual Devices | Heating groups | 9292 | 49292 |
| JSON-RPC | Names and rooms | 80 | 443 |
Authentication
- Admin privileges required on your CCU
- Allowed password characters:
A-Z,a-z,0-9,.!$():;#- - XML-RPC authentication recommended (Settings > Control Panel > Security)
For complete requirements and configuration details, see the Full Documentation.
Documentation
The complete documentation is available at sukramj.github.io/aiohomematic:
| Topic | Link |
|---|---|
| Home Assistant Integration | User Guide |
| Actions Reference | Actions |
| Troubleshooting | Troubleshooting Guide |
| Week Profiles | Week Profiles |
| Naming Conventions | Naming |
| Glossary | Glossary |
Additional Resources
- Contributing Guide: See CONTRIBUTING.md for development setup and contribution guidelines
- Local Naming Documentation: See docs/naming.md
Device Configuration Panel
A built-in sidebar panel for editing Homematic device MASTER parameters directly from the Home Assistant UI.
Features
- Browse all configurable devices grouped by interface
- View device details including reachability, RSSI, and firmware
- Edit MASTER paramset values per channel with auto-generated forms (sliders, toggles, dropdowns)
- Validate changes before writing to the device
- Reset parameters to factory defaults
Enabling the Panel
- Go to Settings → Devices & Services → Homematic(IP) Local
- Click Configure on your integration entry
- Navigate to Advanced Options
- Enable Device configuration panel
- The panel appears in the sidebar as Homematic Config
Note: The panel requires admin access and is not visible to non-admin users.
Blueprints
Ready-to-use automation blueprints are available in the blueprints/automation directory:
- Support for 2/4/6/8-button remotes
- Persistent notifications for unavailable devices
- Device reactivation helpers
- Error event handlers
Copy the desired blueprint files to your config/blueprints/automation directory.
Community blueprints are welcome via pull request in blueprints/community.
Companion Cards
Enhance your Home Assistant dashboard with custom cards designed for this integration:
| Card | Description |
|---|---|
| Climate Schedule Card | Visual editor for Homematic thermostat week profiles. Edit heating schedules directly from your dashboard. |
Support and Contributing
| Resource | Link |
|---|---|
| Report Issues | GitHub Issues |
| Discussions | GitHub Discussions |
| Documentation | sukramj.github.io/aiohomematic |
| Contributing | CONTRIBUTING.md |
| Sponsor | GitHub Sponsors |
License
This project is licensed under the MIT License. See LICENSE for details.