Homematic(IP) Local for OpenCCU

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)

1. In Home Assistant, go to HACS > Integrations > Explore & Download Repositories
2. Search for "Homematic(IP) Local for OpenCCU" and install it
3. Restart Home Assistant when prompted

Manual Installation

1. Copy the custom_components/homematicip_local directory to your Home Assistant config/custom_components directory
2. 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

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.