Installation HomeAssistant - OpenCCU/OpenCCU GitHub Wiki

OpenCCU kann als App innerhalb von Home Assistant installiert werden. In dieser Betriebsart läuft OpenCCU als leichtgewichtige, containerbasierte virtuelle Appliance innerhalb von Home Assistant OS. Home Assistant OS selbst kann dabei auf verschiedenen Systemen laufen – vom Raspberry Pi über ein Generic-x86_64-System bis hin zu einer virtuellen Maschine unter Proxmox VE oder ähnlichen Virtualisierungsumgebungen.

Als Home Assistant App ist der volle CCU-Funktionsumfang direkt in Home Assistant eingebettet und läuft parallel zu anderen Integrationen (z. B. Philips Hue, Sonos). Zudem profitiert OpenCCU von Funktionen wie den Backups von Home Assistant.

Im Repository „OpenCCU Apps“ stehen folgende Apps zur Verfügung:

App	Zweck
OpenCCU	Die reguläre OpenCCU-Zentrale als Home Assistant App.
OpenCCU (snapshot)	Experimentelle Entwicklungsversion (Nightly-Snapshot) – nur für Testzwecke.
OpenCCU HAP/DRAP-Helper	Hilfs-App, die der OpenCCU App eine eigene IP-Adresse im lokalen Netzwerk zuweist, damit HmIP-HAP bzw. HmIPW-DRAP genutzt werden können (siehe unten).
OpenCCU (Proxy)	Stellt keine eigene Zentrale bereit, sondern bindet die WebUI einer extern laufenden OpenCCU in die Seitenleiste von Home Assistant ein (siehe unten).

---

1. Home Assistant OS ab Version 17 Die OpenCCU App setzt Home Assistant OS 17 oder neuer voraus; bei Verwendung eines HmIP-RFUSB-TK mindestens Home Assistant OS 17.1. Unterstützt werden ausschließlich aarch64- und amd64-Systeme. Downloads: https://github.com/home-assistant/operating-system/releases

2. GPIO-Unterstützung aktivieren (nur für GPIO-Funkmodule) Nur erforderlich, wenn ein RPI-RF-MOD oder HM-MOD-RPI-PCB auf der GPIO-Schnittstelle genutzt werden soll. Nicht erforderlich bei Verwendung von HB-RF-USB, HB-RF-USB-2, HB-RF-ETH, HmIP-RFUSB oder HmIP-RFUSB-TK.

   • Zugriff auf die Boot-Partition (/mnt/boot) verschaffen: SD-Karte/SSD an einem PC einbinden, per SSH auf den Host zugreifen oder Monitor und Tastatur für eine Konsolenanmeldung anschließen.
   • Raspberry Pi – in /mnt/boot/config.txt die folgenden Zeilen einkommentieren:

     # Enable GPIO support for RPI-RF-MOD/HM-MOD-RPI-PCB
     enable_uart=1
     dtparam=i2c_arm=on
     dtoverlay=miniuart-bt
     dtoverlay=rpi-rf-mod

   • Tinker Board / ODROID – in /mnt/boot/haos-config.txt einkommentieren:

     # Enable GPIO support for RPI-RF-MOD/HM-MOD-RPI-PCB
     overlays=rpi-rf-mod

   • Den Home-Assistant-OS-Host neu starten, damit die Änderungen wirksam werden.

---

1. App Store öffnen In der Home-Assistant-Oberfläche (http://homeassistant.local:8123/) unter Einstellungen → Apps (in älteren Home-Assistant-Versionen: Add-ons) den App Store öffnen und über das ⋮-Menü (oben rechts) Repositories auswählen.

2. OpenCCU-Repository hinzufügen Folgende URL als zusätzliches Repository hinzufügen: https://github.com/OpenCCU/OpenCCU

3. OpenCCU App auswählen Den Dialog schließen, zum Abschnitt „OpenCCU Apps“ scrollen und die App „OpenCCU“ auswählen.

4. App installieren Auf Installieren klicken, um die OpenCCU App zu installieren.

5. In der Seitenleiste anzeigen & starten Nach der Installation In der Seitenleiste anzeigen aktivieren, um schnell auf die CCU-WebUI zugreifen zu können, und anschließend auf Starten klicken. Der Startvorgang lässt sich im Reiter Protokoll verfolgen (Hostname, CPU-/RAM-Auslastung).

6. Zusätzliche Ports freigeben (optional) Sollen die Programmierschnittstellen der CCU (z. B. XML-RPC, Script-API) von anderen Systemen aus erreichbar sein, im Reiter Konfiguration der App die gewünschten Ports freigeben.

7. CCU-WebUI öffnen Den neuen Eintrag OpenCCU in der Seitenleiste von Home Assistant anklicken, um die gewohnte CCU-WebUI zu öffnen.

Sobald die App läuft, kann eine bestehende Konfiguration eingespielt, können Geräte angelernt (abhängig von der Funk-/Wired-Hardware) und OpenCCU wie auf eigener Hardware genutzt werden. Anschließend helfen die ersten Schritte nach der Installation bei der weiteren Einrichtung.

Die OpenCCU App wird wie jede andere Home Assistant App über die Home-Assistant-Oberfläche aktualisiert. Ein Zurückkehren zu einer älteren Version ist nur über ein vorher erstelltes Home-Assistant-Backup der App möglich.

---

Damit die Homematic/Homematic IP-Geräte als Entitäten in Home Assistant zur Verfügung stehen, nach der Einrichtung der App die Integration hinzufügen. Die Schritt-für-Schritt-Anleitung findet sich unter Home-Assistant-Integration.

---

Aufgrund der Netzwerk-Einschränkungen von Home Assistant Apps kann die reguläre OpenCCU App nicht mit einem HmIP-HAP als Reichweitenverstärker oder einem HmIPW-DRAP als Homematic IP Wired Access Point kommunizieren. Ist die Unterstützung dieser Geräte erforderlich, steht die App OpenCCU HAP/DRAP-Helper zur Verfügung, die parallel zur regulären OpenCCU App installiert wird. Solange sie läuft, sorgt sie dafür, dass der Container der OpenCCU App eine eigene IPv4-Adresse im lokalen Netzwerk erhält und die Routing-Tabellen so eingerichtet werden, dass die Kommunikation mit HmIP-HAP bzw. HmIPW-DRAP möglich ist.

Einrichtung der App OpenCCU HAP/DRAP-Helper:

1. Die reguläre App OpenCCU installieren und starten (siehe Installation der App).
2. Zusätzlich die App OpenCCU HAP/DRAP-Helper aus demselben Repository installieren.
3. In der Konfiguration der Helper-App die Option OpenCCU IP (openccu_ip) auf eine freie, statische IPv4-Adresse des lokalen Netzwerks setzen.
4. Den Schutzmodus (Protection Mode) der Helper-App deaktivieren.
5. Beim Booten starten sowie den Watchdog der Helper-App aktivieren, damit sie automatisch gestartet bzw. neu gestartet wird.
6. Die App OpenCCU HAP/DRAP-Helper starten und dauerhaft laufen lassen.
7. Die reguläre OpenCCU App (neu) starten und im Protokoll der Helper-App prüfen, ob die IPv4-Adresse korrekt zugewiesen wurde.
8. Die WebUI der OpenCCU App über die festgelegte IPv4-Adresse aufrufen (z. B. http://<IP-ADRESSE>/) und bei Bedarf die Firewall von OpenCCU anpassen. Hinweis: Die Port-Einstellungen der OpenCCU App gelten dann nicht mehr, da die App nun direkt über die festgelegte IPv4-Adresse mit dem lokalen Netzwerk verbunden ist.

Weitere, optionale Einstellungen der Helper-App:

Option	Beschreibung
openccu_mac	Feste MAC-Adresse für die Netzwerkschnittstelle der OpenCCU App. Ohne Angabe wird eine bestehende MAC-Adresse wiederverwendet bzw. automatisch eine abgeleitet.
check_interval	Intervall in Sekunden (10–3600) für die regelmäßige Prüfung der Netzwerkeinrichtung (Standard: 15).
openccu_slug	Slug der OpenCCU App, falls abweichend vom Standard openccu (z. B. openccu-dev für die Snapshot-App).
network_name	Name des verwendeten macvlan-Netzwerks (Standard: ccu).
parent_interface	Netzwerkschnittstelle des Hosts für das macvlan-Netzwerk (z. B. enp0s18); ohne Angabe automatisch ermittelt.
subnet / gateway	Subnetz bzw. Gateway des macvlan-Netzwerks; ohne Angabe automatisch ermittelt.

Danach sollte die OpenCCU App mit den angelernten HmIP-HAP- bzw. HmIPW-DRAP-Geräten kommunizieren können.

---

Die App OpenCCU (Proxy) stellt keine eigene Zentrale bereit. Sie fügt lediglich einen OpenCCU-Eintrag in die Seitenleiste von Home Assistant ein, über den die WebUI einer extern laufenden OpenCCU (z. B. auf einem Raspberry Pi oder in einer VM) innerhalb von Home Assistant geöffnet werden kann.

1. Die App OpenCCU (Proxy) aus dem Repository „OpenCCU Apps“ installieren.
2. In der Konfiguration der App die Option webui-url auf die Adresse der externen OpenCCU-WebUI setzen (z. B. http://192.168.178.43; Standard: http://openccu).
3. Sicherstellen, dass Home Assistant direkt auf die WebUI der externen OpenCCU zugreifen kann; ggf. die IP-Adresse des Home-Assistant-Systems in der Firewall von OpenCCU freigeben.
4. Die App starten und In der Seitenleiste anzeigen aktivieren.

---

Die OpenCCU App wird über die Home-Assistant-Oberfläche (Seite der App → Deinstallieren) entfernt. Vorher sollte ein Backup der OpenCCU-Konfiguration erstellt werden (siehe Backup/Restore).

---

Weitere Hilfe zur Installation der App:

• YouTube (🇩🇪) – „RaspberryMatic AddOn auf Home Assistant installieren und einrichten 2022“ vom Kanal simon42 (noch unter dem früheren Namen RaspberryMatic)