Homematic(IP) Local for OpenCCU lädt nicht mehr

Integrationen custom_homematic
41

Also bei mir klappt es nicht.

42

Ich habe jetzt eine dauerhafte Lösung für das Problem. Aber der Reihe nach:

Was ist die Ursache des Problems?

Es gibt HA-Integrationen, die zusätzliche Python-Module brauchen, die sie nicht selber mitbringen. Fehlen diese Module, können die Integrationen nicht starten.

Bisher (vor 2026.3.0) wurden diese benötigten Modul von HA selbständig nachgeladen, wenn sie in der erforderlichen Version noch nicht vorhanden waren.

Seit HA 2026.3.0 passiert das nicht mehr. Soweit ich weiß, wird an einem Fix gearbeitet, aber Stand 10.4.2026 gibt es den noch nicht.

Wie kann man das Problem lösen?

Indem man die notwendigen Module von Hand nachinstalliert. Das geht nur über die Kommandozeile, ist aber für jedes fehlende Modul nur eine Zeile.

Woher weiß ich, welche Module ich installieren muss?

Jede Integration enthält eine Datei mit Namen “manifest.json”. Das ist eine Json-formatierte Textdatei, welche die Metadaten einer Integration enthält, also Name, Version, Autoren und eben auch Abhängigkeiten. Diese Datei liegt im Verzeichnis der jeweiligen Integration, also z.B. “/config/custom_components/homematicip_local”. Sie kann mit dem File-Editor von HA oder auch mit dem “Studio Code Server”-Addon geöffnet werden.

Die manifest.json von homematicip_local 2.5.2 sieht so aus:

{
  "domain": "homematicip_local",
  "name": "Homematic(IP) Local for OpenCCU",
  "after_dependencies": ["backup", "http", "mqtt"],
  "codeowners": ["@SukramJ"],
  "config_flow": true,
  "documentation": "https://github.com/sukramj/homematicip_local",
  "homekit": {},
  "integration_type": "hub",
  "iot_class": "local_push",
  "issue_tracker": "https://github.com/sukramj/aiohomematic/issues",
  "loggers": ["aiohomematic", "aiohomematic_config"],
  "requirements": ["aiohomematic-config==2026.3.5", "aiohomematic==2026.4.0"],
  "ssdp": [
    {
      "manufacturer": "OpenCCU",
      "manufacturerURL": "https://openccu.de"
    }
  ],
  "version": "2.5.2",
  "zeroconf": []
}

Entscheidend ist diese Zeile:
"requirements": ["aiohomematic-config==2026.3.5", "aiohomematic==2026.4.0"],

Hier stehen die Abhängigkeiten der Integration, in diesem Fall also

  • aiohomematic-config Version 2026.3.5
  • aiohomematic Version 2026.4.0

Wie installiere ich die fehlenden Module?

Dazu brauchen wir Zugriff auf die Kommandozeile. Die bekommen wir am einfachsten über die HA-App Advanced SSH & Web Terminal, die man im HA App-Store unter Home Assistant Community Apps findet.

:warning: Wichtig: Diese App bietet die Option “Gesicherter Modus”, die normalerweise eingeschaltet ist und auch eingeschaltet sein sollte. Sie stellt sicher, dass die App keinen Schreib-Zugriff auf wichtige Systemeinstellung hat, dass man also nicht versehentlich sein HA-System zerschießen kann.
Für die Installation der fehlenden Module muss dieser Schalter aber ausgeschaltet werden. Denkt daran, ihn nach erfolgter Installation wieder einzuschalten.

Der eigentliche Kommandozeilen-Befehl für aiohomematicip_local lautet:

docker exec homeassistant uv pip install \
  aiohomematic==2026.4.0 \
  aiohomematic-config==2026.3.5 \
  --system

In den Zeilen 2 und 3 stehen die beiden zu installierenden Module genau so, wie sie auch in manifest.json hinterlegt sind. Für die aktuelle Version könnt Ihr den Befehl einfach so kopieren und einfügen.

Falls in Zukunft neuere Versionen dieser Module gebraucht werden, müssen die Zeilen 2 und 3 einfach entsprechend angepasst werden. Das gleich gilt auch, wenn Module für andere Integrationen installiert werden sollen. Mehrere Zeilen können auch zusammengefasst werden. Der obige Befehl als Einzeiler lautet

docker exec homeassistant uv pip install aiohomematic==2026.4.0 aiohomematic-config==2026.3.5 --system

:warning: Neustart

Nach der Installation der Module muss HA neu gestartet werden. Dann sollte die Integration wieder geladen werden und zur Verfügung stehen.