Du möchtest Homematic IP in Home Assistant einrichten und deine Geräte lokal steuern? Mit HACS und der Community-Integration „Homematic(IP) Local for OpenCCU“ verbindest du eine kompatible CCU, OpenCCU, Debmatic- oder Homegear-Zentrale mit Home Assistant. Diese Anleitung erklärt die Voraussetzungen, Installation und Einrichtung Schritt für Schritt – inklusive Tipps zur Fehlersuche.
Wichtig: Diese Anleitung gilt für CCU-kompatible Zentralen. Ein Homematic-IP-Access-Point (HmIP-HAP) lässt sich mit dieser HACS-Integration nicht verbinden. Für ihn brauchst du einen anderen Weg, den wir im Abschnitt zum Access-Point erklären.
Werbung / Affiliate-Links: Mit einem Sternchen (*) gekennzeichnete Links sind Amazon-Partnerlinks. Wenn du darüber etwas kaufst, erhalte ich möglicherweise eine Provision. Für dich entstehen dadurch keine zusätzlichen Kosten.
Das Wichtigste in Kürze
- Die HACS-Integration verbindet Home Assistant lokal mit einer unterstützten CCU-kompatiblen Zentrale.
- Unterstützt werden unter anderem CCU2/CCU3, OpenCCU, Debmatic und Homegear.
- Ein Homematic-IP-Access-Point (HmIP-HAP) und die Home Control Unit (HmIP-HCU1) benötigen jeweils einen anderen Integrationsweg.
Was bedeutet „Homematic IP mit HACS“?
HACS steht für Home Assistant Community Store. Der Community Store verwaltet Erweiterungen, die nicht zum offiziellen Kern von Home Assistant gehören. Die Integration „Homematic(IP) Local for OpenCCU“ wird über HACS installiert und anschließend wie andere Integrationen in der Home-Assistant-Oberfläche eingerichtet.
Die Verbindung zu einer kompatiblen CCU läuft über das lokale Netzwerk. Für diese Einrichtung brauchst du keine Verbindung zur Homematic-IP-Cloud und normalerweise auch keine Änderungen an der Datei configuration.yaml. HACS ist dabei nur der Installationsweg – die eigentliche Verbindung stellt die Integration her.
Welche Homematic-IP-Zentrale hast du?
Prüfe vor der Installation das Modell deiner Zentrale. Die Gerätenamen ähneln sich, aber nicht jede Zentrale verwendet dieselbe Verbindungsmethode.
| Deine Zentrale | Passender Weg in Home Assistant | Passt zu dieser Anleitung? |
|---|---|---|
| CCU2, CCU3, OpenCCU, Debmatic oder Homegear | „Homematic(IP) Local for OpenCCU“ über HACS | Ja |
| Homematic-IP-Access-Point (HmIP-HAP) | „HomematicIP Cloud“, die in Home Assistant integrierte Cloud-Integration | Nein |
| Homematic IP Home Control Unit (HmIP-HCU1) | Die separate HCU-Integration; sie ist nicht dieselbe Integration wie „Homematic(IP) Local for OpenCCU“ | Nein |
Verwende die Schritte für deine Zentrale. Mit einem Access-Point allein kannst du direkt zum Abschnitt „Homematic-IP-Access-Point statt CCU“ springen.
Voraussetzungen
Für die Einrichtung mit HACS brauchst du:
- Home Assistant und eine bereits eingerichtete HACS-Integration.
- Eine unterstützte CCU-kompatible Zentrale, zum Beispiel eine CCU3 oder OpenCCU.
- Die lokale IP-Adresse oder den Hostnamen der Zentrale.
- Die Zugangsdaten für ein Konto mit Administratorrechten auf der Zentrale.
- Ein lokales Netzwerk, in dem Home Assistant und die CCU einander erreichen können.
Versionshinweis (Stand: 6. Oktober 2026): Die aktuelle Projekt-README nennt Home Assistant 2026.9.0 oder neuer als Mindestversion. Für Homematic-IP-Geräte an einer CCU werden mindestens CCU2-Firmware 2.61.x beziehungsweise CCU3-Firmware 3.61.x angegeben. Anforderungen können sich ändern; prüfe vor der Installation die aktuelle Projektseite von Homematic(IP) Local for OpenCCU.
HACS noch nicht eingerichtet? Folge zuerst der offiziellen HACS-Installationsanleitung. Die Schritte unterscheiden sich je nach Home-Assistant-Installationsart. Fahre hier erst fort, wenn HACS in Home Assistant eingerichtet ist.
Schritt 1: Integration über HACS installieren
- Öffne Home Assistant und wähle HACS in der Seitenleiste.
- Öffne den Bereich Integrationen.
- Wähle Explore & Download Repositories beziehungsweise die Schaltfläche zum Durchsuchen von Integrationen. Die genaue Bezeichnung kann je nach Sprache und HACS-Version abweichen.
- Suche nach Homematic(IP) Local for OpenCCU.
- Öffne den Eintrag des Projekts und wähle Download beziehungsweise Herunterladen.
- Starte Home Assistant neu, wenn HACS dich dazu auffordert.
Kontrolliere den vollständigen Namen: Gesucht ist die Integration für CCU-kompatible Zentralen – nicht „HomematicIP Cloud“ und nicht die separate HCU-Integration. Details und Installationshinweise findest du in der Dokumentation des Integrationsprojekts.
Schritt 2: CCU-Verbindung in Home Assistant einrichten
Nach dem Neustart kann Home Assistant eine kompatible CCU automatisch erkennen. Wird eine Entdeckung angezeigt, kannst du sie öffnen und den Einrichtungsdialog starten. Andernfalls fügst du die Integration manuell hinzu:
- Öffne Einstellungen → Geräte & Dienste.
- Klicke auf Integration hinzufügen und suche nach Homematic(IP) Local for OpenCCU.
- Gib einen eindeutigen Instanznamen ein, zum Beispiel
ccu3. Nutzt mehr als eine Home-Assistant-Instanz dieselbe CCU, braucht jede Instanz einen eigenen Namen. - Trage die lokale IP-Adresse oder den Hostnamen der CCU ein.
- Gib Benutzername und Passwort des CCU-Administratorkontos ein.
- Folge dem Einrichtungsdialog. Die Integration ermittelt die Zentrale und zeigt verfügbare Schnittstellen und TLS-Einstellungen an.
- Wähle nur die Schnittstellen aus, die du verwendest – zum Beispiel Homematic IP (HmIP-RF). Weitere Schnittstellen brauchst du nur für entsprechende Homematic-Geräte oder Funktionen.
- Schließe den Dialog ab und warte, bis Geräte und Entitäten geladen sind.
Die Integration baut nicht nur eine Verbindung von Home Assistant zur CCU auf: Für Statusmeldungen muss auch die CCU Home Assistant erreichen können. Eine erreichbare CCU-Weboberfläche allein garantiert daher noch keine funktionierende Aktualisierung der Gerätezustände.
Netzwerk und Ports: Was muss erreichbar sein?
Welche Schnittstellen und Ports gebraucht werden, hängt von deinen Geräten und davon ab, ob TLS aktiviert ist. Die Projektdokumentation nennt folgende Standardports für Verbindungen zur Zentrale:
| Schnittstelle | Zweck | Standardport | TLS-Port |
|---|---|---|---|
| Homematic IP (HmIP-RF) | Funk- und Wired-HmIP-Geräte | 2010 | 42010 |
| Homematic (BidCos-RF) | Klassische Homematic-Funkgeräte | 2001 | 42001 |
| Homematic Wired | Klassische Wired-Geräte | 2000 | 42000 |
| Virtuelle Geräte | Heizungsgruppen | 9292 | 49292 |
| JSON-RPC | Gerätenamen und Räume | 80 | 443 |
Du musst nicht automatisch jeden Port verwenden. Die Auswahl der Schnittstellen in der Integration richtet sich nach deinem System. Öffne die genannten Ports nicht pauschal im Internet-Router: Sie gehören ins lokale Netzwerk und sollten nur zwischen den beteiligten Geräten erreichbar sein.
Besonderheit bei Docker, Windows und WSL2
Bei Home Assistant in Docker oder in einer WSL2-Umgebung kann die Rückverbindung zusätzliche Netzwerkkonfiguration erfordern. Die CCU muss die Rückrufadresse von Home Assistant erreichen können. Prüfe deshalb die Callback-Adresse in den erweiterten Optionen, die Windows-Firewall und die Docker-Netzwerkeinstellungen. localhost bezeichnet innerhalb eines Containers den Container selbst – nicht automatisch den Windows-Host oder die CCU.
Die genaue Einstellung hängt davon ab, wie Home Assistant und die CCU installiert und vernetzt sind. Ermittle zuerst die Adresse, unter der die CCU Home Assistant erreichen kann, bevor du Ports oder Firewallregeln änderst.
* Homematic-IP-Geräte bei Amazon ansehen
Schritt 3: Geräte und Entitäten prüfen
Nach erfolgreicher Einrichtung findest du die Integration unter Einstellungen → Geräte & Dienste. Öffne sie, um erkannte Geräte und die dazugehörigen Entitäten zu prüfen. Entitäten sind einzelne steuer- oder auslesbare Funktionen, zum Beispiel Temperatur, Batteriestand, Schaltzustand oder Solltemperatur.
Gib den Geräten am besten schon in der CCU verständliche Namen. Die Integration kann diese Namen übernehmen. Fehlt eine erwartete Funktion, prüfe die Entitäten des Geräts und blende deaktivierte Entitäten ein. Nicht jedes Gerät stellt dieselben Funktionen bereit.
Neue Geräte lernst du zuerst an der CCU an. Falls ein Gerät anschließend nicht in Home Assistant erscheint, prüfe Einstellungen → System → Reparaturen auf eine Benachrichtigung zur Übernahme oder Benennung.
Schritt 4: Eine einfache Automation testen
Teste die Verbindung mit einer einfachen Automation. Dieses Beispiel sendet eine Benachrichtigung, sobald ein Homematic-IP-Fensterkontakt geöffnet wird:
- Öffne Einstellungen → Automationen & Szenen und erstelle eine neue Automation.
- Wähle den Fensterkontakt als Auslöser und den Wechsel zum geöffneten Zustand.
- Füge eine Benachrichtigungsaktion für dein Home-Assistant-Gerät hinzu.
- Speichere die Automation und öffne das Fenster beziehungsweise betätige den Kontakt.
Bleibt die Benachrichtigung aus, prüfe zuerst den Sensorstatus in Home Assistant. Ändert sich dieser nicht, liegt die Ursache wahrscheinlich bei der Verbindung oder der Rückmeldung von der CCU – nicht bei der Automation.
Häufige Probleme und Lösungen
Die Integration wird beim Hinzufügen nicht gefunden
Prüfe, ob die Integration in HACS wirklich heruntergeladen wurde und ob Home Assistant danach neu gestartet wurde. Suche beim Hinzufügen der Integration nach dem vollständigen Namen „Homematic(IP) Local for OpenCCU“. Vergewissere dich außerdem, dass du nicht nach der Cloud-Integration suchst.
Home Assistant kann die CCU nicht erreichen
Kontrolliere IP-Adresse oder Hostnamen und prüfe, ob Home Assistant die CCU im lokalen Netzwerk erreicht. Prüfe anschließend die Firewall und die benötigten Schnittstellen. In Docker- oder WSL2-Umgebungen kontrolliere zusätzlich die Callback-Adresse.
Geräte sind sichtbar, aber ihre Zustände aktualisieren sich nicht
Die CCU muss Home Assistant für Ereignis- und Statusmeldungen erreichen können. Prüfe die Rückrufadresse und den Rückrufport in den erweiterten Optionen, falls deine Netzwerktopologie eine manuelle Konfiguration erfordert. Sieh anschließend in den Home-Assistant-Protokollen nach Meldungen zur Integration homematicip_local.
Die Anmeldung schlägt fehl
Verwende ein Konto mit Administratorrechten und kontrolliere Groß- und Kleinschreibung. Die Integration dokumentiert Einschränkungen bei den Zeichen, die das XML-RPC-Passwort enthalten darf. Prüfe bei einem ungewöhnlichen Passwort die aktuellen Anforderungen in der Projektdokumentation. Veröffentliche niemals dein Passwort oder ungeschwärzte Zugangsdaten in Screenshots.
Ein Gerät oder eine Funktion fehlt
Prüfe zuerst, ob das Gerät an der CCU angelernt ist und dort funktioniert. Kontrolliere danach die unterstützten Versionen und ob die benötigte Schnittstelle eingerichtet wurde. Suche bei anhaltenden Problemen in den Projekt-Issues. Entferne vor dem Teilen von Protokollen oder Diagnosedaten Passwörter, Tokens und andere persönliche Informationen.
Homematic-IP-Access-Point statt CCU
Wenn du einen Homematic-IP-Access-Point (HmIP-HAP) verwendest, ist „Homematic(IP) Local for OpenCCU“ nicht die richtige Integration. Der Access-Point arbeitet nicht wie eine CCU-kompatible Zentrale mit den von dieser HACS-Integration erwarteten Schnittstellen.
Für den Access-Point verwendest du die in Home Assistant integrierte Integration HomematicIP Cloud. Füge sie über Einstellungen → Geräte & Dienste → Integration hinzufügen hinzu und folge dem Einrichtungsdialog. Anders als die HACS-Integration für eine CCU kommuniziert dieser Weg über die Homematic-IP-Cloud.
Die Home-Assistant-Dokumentation führt einen aktiven Hinweis zur Cloud-Integration: Bei häufigen Cloud-Zugriffen können öffentliche IP-Adressen blockiert werden. Informiere dich vor der Einrichtung über den aktuellen Home-Assistant-Hinweis zu HomematicIP Cloud. Für eine Homematic IP Home Control Unit (HmIP-HCU1) benötigst du wiederum eine separate HCU-Integration.
Ist Homematic IP über HACS die richtige Wahl?
Die HACS-Integration passt, wenn deine Geräte an einer CCU-kompatiblen Zentrale angelernt sind und Home Assistant sie über dein Heimnetz erreichen soll. Sie bindet die Geräte der Zentrale lokal ein und benötigt für diesen Verbindungsweg keine Homematic-IP-Cloud.
Beachte: HACS-Erweiterungen stammen aus Community-Projekten und werden unabhängig vom Home-Assistant-Kern gepflegt. Lies die aktuelle Dokumentation und prüfe die Kompatibilität vor größeren Aktualisierungen. Eine Sicherung deiner Home-Assistant-Konfiguration hilft, falls ein Update Probleme verursacht.
Fazit
Homematic IP mit HACS in Home Assistant einzurichten ist mit einer unterstützten CCU, OpenCCU, Debmatic- oder Homegear-Zentrale unkompliziert: Installiere die Integration über HACS, starte Home Assistant neu und füge die Zentrale über „Geräte & Dienste“ hinzu. Wichtig sind aktuelle, unterstützte Versionen und eine Netzwerkverbindung in beide Richtungen, damit Befehle und Statusmeldungen funktionieren.
Mit einem Homematic-IP-Access-Point nutzt du stattdessen die offizielle Cloud-Integration. Für die HmIP-HCU1 brauchst du eine separate HCU-Integration. Prüfe deshalb zuerst, welche Zentrale du besitzt – so findest du den passenden Einrichtungsweg.
Häufige Fragen zu Homematic IP und HACS
Kann ich einen Homematic-IP-Access-Point über HACS mit Home Assistant verbinden?
Nicht mit „Homematic(IP) Local for OpenCCU“. Diese Integration ist für CCU-kompatible Zentralen gedacht. Für einen üblichen Homematic-IP-Access-Point verwendest du die offizielle Integration „HomematicIP Cloud“ in Home Assistant.
Brauche ich für die HACS-Integration eine Verbindung zur Homematic-IP-Cloud?
Nein. Die hier beschriebene Integration kommuniziert lokal mit einer unterstützten CCU-kompatiblen Zentrale. Die genaue Funktion hängt von deiner Zentrale, ihrer Firmware und den aktivierten Schnittstellen ab.
Muss ich für die Einrichtung YAML bearbeiten?
Für die hier beschriebene Integration erfolgt die normale Einrichtung über die Benutzeroberfläche von Home Assistant. Die Verbindung wird nach der Installation über „Einstellungen → Geräte & Dienste → Integration hinzufügen“ konfiguriert.
Warum aktualisieren sich meine Geräte trotz erfolgreicher Einrichtung nicht?
Häufig kann Home Assistant zwar die CCU erreichen, aber die CCU keine Statusmeldungen an Home Assistant zurücksenden. Prüfe deshalb Netzwerk, Firewall und Rückrufadresse, insbesondere bei Docker oder WSL2.
Du möchtest Home Assistant zunächst grundsätzlich kennenlernen? Hier findest du unsere Einführung in Home Assistant mit Installation und Praxisbeispielen.