Homematic(IP) Local for OpenCCU is a custom integration for Home Assistant.
- Local Home Assistant integration for Homematic(IP) hubs (CCU2/3, OpenCCU, Debmatic, Homegear). No cloud required. See Supported Hardware for the complete, exhaustive list.
- 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.
| Resource | Link |
|---|---|
| Full Documentation | User Guide |
| Installation | See Installation below |
| Alternative Setup (OpenCCU) | OpenCCU Wiki |
| Changelog | changelog.md |
| Issues | GitHub Issues |
| Discussions | GitHub Discussions |
| 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 |
- 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
- 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:
- CCU2/3
- OpenCCU
- Debmatic
- Homegear
- Home Assistant OS/Supervised with suitable add-on + communication device
Note: This list is exhaustive. Third-party hubs that reimplement the CCU interfaces (XML-RPC, JSON-RPC, ReGa) are not supported, even if they appear to work. Issues reported against such a setup are closed without further assessment.
| 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 |
- 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.
The complete documentation is available at sukramj.github.io/aiohomematic:
| Topic | Link |
|---|---|
| Home Assistant Integration | User Guide |
| Actions Reference | Actions |
| Events Reference | Events |
| Troubleshooting | Troubleshooting Guide |
| Week Profiles | Week Profiles |
| Naming Conventions | Naming |
| Glossary | Glossary |
- Contributing Guide: See CONTRIBUTING.md for development setup and contribution guidelines
- Local Naming Documentation: See docs/naming.md
A built-in sidebar panel for editing Homematic device MASTER parameters directly from the Home Assistant UI.
- 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
- 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.
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.
Blueprints that react to devices are driven by the integration's events — see the
Events Reference
for which parameters trigger which event. Note that CCU service messages (CONFIG_PENDING,
UPDATE_PENDING, …) are not events; they are available through the
sensor.<instance>_hub_service_messages sensor.
Community blueprints are welcome via pull request in blueprints/community.
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. |
| Resource | Link |
|---|---|
| Report Issues | GitHub Issues |
| Discussions | GitHub Discussions |
| Documentation | sukramj.github.io/aiohomematic |
| Contributing | CONTRIBUTING.md |
| AI Contribution Policy | AI_POLICY.md |
| Sponsor | GitHub Sponsors |
Parts of Homematic(IP) Local for OpenCCU are developed with agentic AI assistance, primarily Claude Code. Submitted issues are also triaged and analysed with agentic help. Every change is still reviewed by a human maintainer and must pass the project's tests before it lands — AI accelerates the work, it does not replace the review gate. The rules for AI use in contributions are documented in AI_POLICY.md.
This project is licensed under the MIT License. See LICENSE for details.