Installation - OpenCCU/OpenCCU GitHub Wiki

Nachdem die notwendigen Hard- und Softwarevoraussetzungen für die Installation von OpenCCU geprüft und erfüllt wurden, kann mit der eigentlichen Installation fortgefahren werden. Der Ablauf unterscheidet sich je nach eingesetzter Hardwareplattform; daher wird die Installation für jede Plattform in den folgenden Abschnitten separat als Schritt-für-Schritt-Anleitung erläutert.

Schnellstart

Für Ungeduldige bzw. fortgeschrittene CCU-/Homematic-/Linux-Nutzer erklärt die folgende Schnellstart-Anleitung die grundlegenden Schritte, die sich in jeder hardwarebasierten Anleitung in ähnlicher Form wiederfinden, um die OpenCCU-Installation vorzunehmen:

Bei Einsatz einer CCU3-Hardware:

Unter Releases die aktuellste Version als OpenCCU-X.XX.XX.YYYYMMDD-ccu3.tgz-Archiv herunterladen.
In die WebUI der laufenden CCU3 einloggen.
Unter Einstellungen -> Systemsteuerung -> Zentralen-Wartung die heruntergeladene *.tgz-Datei wie ein reguläres Firmware-Update über Datei auswählen wählen und anschließend über Hochladen starten.
Anschließend ist OpenCCU auf der CCU3-Hardware installiert und einsatzbereit.

Bei Einsatz eines eigenen Raspberry Pi / ELV-Charly oder ASUS Tinker Board:

Unter Releases die aktuellste Version als OpenCCU-X.XX.XX.YYYYMMDD-ZZZ.zip-Archiv herunterladen (ZZZ entspricht der Zielplattform – rpiX bzw. tinkerboard, für ELV-Charly rpi3).
Das Archiv mit einem geeigneten Tool entpacken.
Die im Archiv enthaltene *.img-Datei mit einem Imaging-Tool wie Etcher auf eine geeignete SD-Karte (mind. 4 GB) flashen; beim Tinker Board S kann das Image nach dem Anschließen per USB auch direkt auf die interne eMMC geschrieben werden.
Die SD-Karte in den Raspberry Pi / ELV-Charly bzw. das Tinker Board stecken.
Ein passendes Homematic / Homematic IP-Funkmodul per GPIO oder USB anschließen.
Das Gerät mit Strom versorgen – OpenCCU startet und fährt hoch.

Bei Einsatz einer Virtualisierungsumgebung (VMware ESXi, Proxmox VE, VirtualBox, etc.):

Unter Releases die aktuellste Version als OpenCCU-X.XX.XX.YYYYMMDD.ova herunterladen (nicht die *.zip-Datei!).
In der Administrationsoberfläche der Virtualisierungsumgebung die *.ova-Datei importieren und die Grundeinstellungen der virtuellen OpenCCU-VM vornehmen.
Ein passendes Homematic / Homematic IP-Funkmodul per USB an den Host anschließen und an die VM durchreichen.
Die VM starten – OpenCCU fährt hoch und ist anschließend über die WebUI erreichbar.

Detailliertere Installationsanleitungen für alle unterstützten Plattformen sind in den folgenden Abschnitten zu finden.

Grundinstallation (Hardware)

In den folgenden Abschnitten wird beschrieben, wie man OpenCCU mit dedizierter Hardware installiert und betreibt bzw. es in einer Virtualisierungsumgebung in Betrieb nimmt.

Grundinstallation (Virtuell)

Zusätzlich zur Installation auf echter Hardware kann OpenCCU in modernen Virtualisierungsumgebungen wie VMware ESXi, Proxmox VE, VirtualBox, Synology VMM usw. als virtuelle x86-Maschine betrieben und zusammen mit einem passenden USB-basierten Homematic-Funkmodul verwendet werden. OpenCCU wird hierfür als *.ova-Archiv bereitgestellt, das sich in gängigen Virtualisierungslösungen mit wenigen Klicks importieren lässt. Im Folgenden wird dies für jede unterstützte Virtualisierungsplattform separat beschrieben:

Konfigurationsübernahme

Nach erfolgreicher Grundinstallation auf eigener Hardware oder in einer Virtualisierungsumgebung – und sofern bereits eine andere bzw. ältere CCU-Zentrale von eQ-3/ELV vorhanden ist – zeigen die folgenden Abschnitte, wie die bestehende Konfiguration übernommen werden kann.

Umstieg von CCU3

Aufgrund der weitreichenden Kompatibilität zwischen dem auf der CCU3 eingesetzten Betriebssystem/Firmware und OpenCCU sind beim Umstieg von einer CCU3-Firmware zu OpenCCU in der Regel nur dann manuelle Anpassungen nötig, wenn direkt auf ein virtuelles OpenCCU-System gewechselt wird. Mehr Infos zum Wechsel auf ein virtuelles OpenCCU finden sich hier.

Wenn OpenCCU gemäß der Installationsanleitung direkt auf der bestehenden CCU3-Hardware installiert wurde, sollten die Konfiguration inklusive installierter CCU-Add-ons automatisch übernommen worden sein – weitere Schritte sind nicht erforderlich. Wechselt man hingegen von der CCU3-Hardware zu einer anderen ARM-basierten Plattform (Raspberry Pi, Tinker Board), kann nach der frischen Grundinstallation das zuvor über die CCU3-WebUI exportierte System-Backup (*.sbk) über die OpenCCU-WebUI eingespielt werden. Weitere Schritte sind dann nicht mehr notwendig.

Umstieg von CCU2

Beim Umstieg von einer älteren CCU2 mit Firmware-Version 2.x auf OpenCCU sind einige Punkte zu beachten. Nach Abschluss der Grundinstallation auf der neuen Hardware bzw. der virtuellen Umgebung – und sobald die OpenCCU-WebUI erreichbar ist – erfolgt die Datenübernahme wie folgt (gilt auch für LXCCU, YAHM, piVCCU2):

Vor der Übernahme der Konfiguration (*.sbk) sicherstellen, dass auf der alten CCU2 die aktuellste CCU2-Firmware installiert ist. Ein direkter Wechsel von einer sehr alten CCU2-Version auf eine aktuelle OpenCCU kann Probleme verursachen. Empfehlenswert ist, zunächst eine OpenCCU-Version zu verwenden, die der aktuellsten CCU2-Firmware am nächsten kommt (z. B. bei CCU2-Firmware 2.59.7 zunächst 3.59.6.20211009 für den Umstieg einsetzen und anschließend – sofern alles fehlerfrei – auf die aktuellste OpenCCU-Version aktualisieren).
Auf der alten CCU2 in die WebUI einloggen und unter Einstellungen->Systemsteuerung->Sicherheit->Backup erstellen ein Backup (*.sbk) der Konfiguration erstellen und sicher aufbewahren.
Unter Einstellungen->Systemsteuerung->Zusatzsoftware alle gelisteten Zusatzpakete (CCU-Add-ons) notieren, da diese später (nach der Konfigurationsübernahme zu OpenCCU) manuell in einer OpenCCU-kompatiblen Version nachinstalliert werden müssen.
Nun unter Einstellungen->Systemsteuerung->Zusatzsoftware die Liste der Zusatzpakete/CCU-Add-ons durchgehen und alle deinstallieren. Ausnahmen (nicht deinstallieren, da sonst Konfiguration verloren geht; diese können später in Schritt 10 wieder installiert werden):
Erneut unter Einstellungen->Systemsteuerung->Sicherheit->Backup erstellen ein weiteres Backup (*.sbk) erstellen und temporär aufbewahren.
Die alte CCU2 herunterfahren und vom Strom trennen (darf nicht parallel zu OpenCCU laufen!).
Den Browser-Cache des genutzten Browsers vollständig löschen und den Browser neu starten.
In der OpenCCU-WebUI einloggen und unter Einstellungen->Systemsteuerung->Sicherheit->Backup einspielen das zuletzt erstellte Backup (ohne Add-ons) einspielen.
Nach dem durch das Backup ausgelösten Neustart wieder mit der WebUI verbinden und zuerst unter Einstellungen->Systemsteuerung->Zeit-/Positionseinstellungen->NTP-Server folgende NTP-Server-Zeichenkette eintragen:
```
0.de.pool.ntp.org 1.de.pool.ntp.org 2.de.pool.ntp.org 3.de.pool.ntp.org
```
Damit ist sichergestellt, dass beim nächsten Start ein gültiger NTP-Server für die Zeitsynchronisation eingetragen ist.
Über die WebUI die in Schritt 3 notierte Add-on-Liste durchgehen und alle Add-ons in der jeweiligen OpenCCU-kompatiblen Version installieren, um die vorherigen Funktionen wiederherzustellen.
Abschließend OpenCCU erneut neu starten. Danach sollten Anmeldung und WebUI mit den bisherigen Zugangsdaten sowie alle Homematic-Geräte, Programme usw. wieder zur Verfügung stehen. Falls dies wider Erwarten nicht klappt, kann in der alten Installation das erste Backup (vor der Add-on-Deinstallation) zurückgespielt werden. Bitte beachten: abhängig von der vorhandenen Programmierung kann nach dem Start ein erhöhter Duty Cycle (d. h. Funkauslastung) auftreten. Es kann u. U. > 1 h dauern, bis Kommunikationsstörungen zu bestimmten Homematic-Geräten verschwinden.

Umstieg von CCU1

Für den großen Sprung von einer CCU1 zu OpenCCU gilt im Wesentlichen der gleiche Ablauf wie beim Umstieg von CCU2. Zusätzlich ist wichtig, vor dem Wechsel auf die jeweils aktuelle 3.x.x-OpenCCU-Version das CCU1-System-Backup (*.sbk) zunächst in die letzte 2.x.x-OpenCCU-Version zu übernehmen. Konkret: zuerst die letzte 2.x.x-Version von OpenCCU installieren (2.35.16.20180826), dann das CCU1-Backup einspielen und anschließend auf die aktuelle 3.x.x-Version aktualisieren.

Da ein so großer Versionssprung (CCU1 → CCU3) erfahrungsgemäß fehleranfällig sein kann, empfiehlt sich ggf. eine komplette Neueinrichtung (alle Homematic-Geräte abmelden, Werksreset, an OpenCCU neu anlernen, neu konfigurieren). Für die Zukunft empfiehlt es sich, auf derartige große Sprünge zu verzichten und OpenCCU regelmäßig aktuell zu halten.

Umstieg zu virtuellem OpenCCU

Möchte man von einer älteren CCU2/CCU3 oder von einem hardwarebasierten OpenCCU direkt auf ein virtuelles OpenCCU wechseln, geht man wie folgt vor:

Zuerst gemäß der Grundinstallationsanleitung in der jeweiligen Virtualisierungsumgebung sicherstellen, dass das neue virtuelle OpenCCU ordnungsgemäß hochfährt und die WebUI erreichbar ist.
In der alten Installation/Zentrale unter Einstellungen->Systemsteuerung->Sicherheit->Backup ein System-Backup (*.sbk) erstellen und herunterladen.
Unter Einstellungen->Systemsteuerung->Zusatzsoftware die Liste der Zusatzpakete/CCU-Add-ons durchgehen und alle deinstallieren. Ausnahmen (nicht deinstallieren, da sonst Konfiguration verloren geht; diese können später in Schritt 8 wieder installiert werden):
Ein weiteres Backup (*.sbk) erstellen und temporär aufbewahren.
Die alte CCU-Zentrale deaktivieren bzw. vom Strom trennen – keine zwei CCU-Zentralen mit identischer Konfiguration parallel betreiben!
Falls noch kein USB-basiertes Funkmodul (HB-RF-USB, HmIP-RFUSB, HM-CFG-USB2) mit der virtuellen OpenCCU-VM verbunden ist, dies entsprechend der Installationsanleitung der Virtualisierungsumgebung nachholen.
In der WebUI des virtuellen OpenCCU einloggen und das Backup (ohne Add-ons) einspielen.
Anschließend alle zuvor manuell deinstallierten CCU-Add-ons wieder installieren. Wichtig: die Kompatibilität der Add-ons (insbesondere bzgl. x86 in virtuellen Umgebungen) vorher prüfen.
Abschließend das virtuelle OpenCCU neu starten. Hinweis: abhängig von der vorhandenen Programmierung kann nach dem Start ein erhöhter Duty Cycle (d. h. Funkauslastung) auftreten. Es kann u. U. > 1 h dauern, bis Kommunikationsstörungen zu bestimmten Homematic-Geräten verschwinden.

Migration von FHEM

Möchte man für die Steuerung seiner Homematic / Homematic IP Geräte von der inzwischen stark veralteten FHEM Hausautomationsplatform direkt auf OpenCCU wechseln, so kann man hierfür die separate Migration von FHEM Kurzanleitung in diesem Dokumentationswiki nutzen.

Migration von RaspberryMatic

Durch die im Oktober 2025 erfolgte Umbenennung von „RaspberryMatic“ zu „OpenCCU“ – einschließlich interner Umstellungen in der Firmware – ist der Wechsel nicht per automatischem Update möglich. D. h.: Wer eine bestehende RaspberryMatic-Installation auf OpenCCU „updaten“ möchte, muss dies einmalig manuell durchführen.

Gehe dazu wie folgt vor:

Lade unter Releases das passende Installationsarchiv (*.zip) für deine aktuell genutzte Plattform (z. B. rpi3, ova usw.) herunter.
Öffne in der RaspberryMatic-WebUI: Einstellungen → Systemsteuerung → Zentralen-Wartung → Datei auswählen …, lade das *.zip hoch und starte das Firmware-Update.
Nach dem erfolgreichen Update ist OpenCCU installiert. Künftige Updates lassen sich wieder wie gewohnt über die automatische Updatefunktion einspielen.

Migration des RaspberryMatic HA-Add-ons

Auch beim Home-Assistant-Add-on ist kein automatischer Wechsel von „RaspberryMatic“ zu „OpenCCU“ möglich. Daher muss man einmalig die Umstellung wie folgt manuell vornehmen:

[!WARNING] Bitte beachten, dass Home Assistant aufgrund der Umbenennung des Add-ons von "RaspberryMatic" zu "OpenCCU" unter Umständen warnen kann, dass das "RaspberryMatic HA-Add-on" aus dem Repository entfernt wurde. Solange die Migration zu OpenCCU noch nicht abgeschlossen ist, den "Repair Issue"-Dialog nicht mit "Submit" oder "OK" bestätigen, sondern über das "X" oben links schließen.

Die Umstellung erfolgt einmalig manuell wie folgt:

Im laufenden RaspberryMatic-Add-on ein manuelles Backup in der CCU WebUI unter Einstellungen → Systemsteuerung → Sicherheit → Backup-Verwaltung erstellen und als *.sbk herunterladen.

HINWEIS
Falls das RaspberryMatic-Addon-on bereits vor Inbetriebnahme des neuen OpenCCU HA-Addons deinstalliert oder gelöscht wurde, kann man versuchen das letzte automatisch Konfigurations/sbk-Backup unter /backup/raspberrymatic via der Anleitung zum Download von Konfigurationsbackups aus Home Assistant heraus herunterzuladen.
Das RaspberryMatic-Add-on stoppen, Autostart deaktivieren und ggf. die im Add-on freigegebenen Port-Einstellungen notieren.
Das OpenCCU-Add-on zusätzlich in Home Assistant installieren.
Für das OpenCCU-Add-on Autostart und Seitenleistenanzeige aktivieren sowie die zuvor notierten Freigabe-Ports dort wieder einrichten.
OpenCCU-Add-on starten und in der WebUI anmelden (Die zu setzenden Einstellungen werden im nächsten Schritt durch das Backup überschrieben).
Unter Einstellungen → Systemsteuerung → Sicherheit → Backup-Verwaltung das zuvor erstellte SBK-Backup einspielen.
In Home Assistant unter den OpenCCU Add-on-Einstellungen den Hostnamen notieren (z. B. xxxxxx-openccu).
In Home Assistant unter Einstellungen → Geräte & Dienste → Homematic(IP) Local auswählen und das Zahnrad zum Konfigurieren anklicken. Dort den Hostnamen von xxxxxx-raspberrymatic auf xxxxxx-openccu ändern. Der Name des Hubs ändert sich danach automatisch in RaspberryMatic.
Home Assistant neu starten. Wenn alles funktioniert, das alte RaspberryMatic-Add-on entfernen (inkl. „Daten löschen“).
Falls danach nicht alle Geräte mit Namen gefunden werden in Home Assistant unter Entwicklerwerkzeuge → Aktionen die Aktion homematicip_local.clear_cache ausführen und die Erweiterung neu laden.