Experten Features

Zusätzlich zu den Standardfunktionen, die über die normale Weboberfläche (WebUI) konfiguriert werden können, stellt OpenCCU weitere „Experten-Features“ bereit. Dabei handelt es sich um zusätzliche Funktionalitäten, die in der Regel über die Kommandozeile (SSH) bzw. über Konfigurationsdateien aktiviert/deaktiviert werden und bewusst nicht als Schalter in der WebUI verfügbar sind – mitunter aus guten Gründen. Viele früher nur per Kommandozeile verfügbare Optionen lassen sich inzwischen bequem unter Einstellungen → Systemsteuerung → Erweiterte Einstellungen schalten.

Bitte diese Funktionen mit Umsicht einsetzen; je nach Umgebung können sie sich negativ auf Stabilität und Verfügbarkeit auswirken. Für den SSH-Zugriff muss SSH zuvor in der WebUI unter Einstellungen → Systemsteuerung → Sicherheit aktiviert werden.

Entgegen der Standardeinstellung, OpenCCU ausschließlich per Ethernet/LAN anzubinden, kann die Zentrale prinzipiell auch per WLAN/Wi-Fi mit dem Heimnetz verbunden werden.

Warnung: Diese Betriebsart wird nicht empfohlen, da WLAN in der Regel nicht die Stabilität einer kabelgebundenen Verbindung erreicht und es zu Zugriffsproblemen oder Ausfällen bei externen Abfragen kommen kann. WLAN sollte nur genutzt werden, wenn keine kabelgebundene Alternative möglich ist.

OpenCCU unterstützt die folgende getestete WLAN-Hardware:

• Onboard-WLAN des Raspberry Pi 5, Raspberry Pi 4/400, Raspberry Pi 3 bzw. Raspberry Pi Zero 2 W
• Edimax EW-7612UAN V2 – RTL81xx-basierter USB-WiFi-Stick
• ThePiHut – RT2xx-basierter USB-WiFi-Stick

Andere WLAN-Adapter wurden nicht getestet und können Probleme verursachen.

Hinweis: Ein paralleler Betrieb von LAN und WLAN ist nicht möglich. Das Ethernet-Kabel muss beim Hochfahren abgezogen sein, damit WLAN als präferiertes Netzwerk überhaupt initialisiert wird.

Soll OpenCCU statt über LAN ein vorhandenes WLAN/Wi-Fi nutzen, kann das verwendete Installationsmedium (z. B. die SD-Karte) an einen PC angeschlossen und auf der FAT32-Boot-Partition eine Datei SetupWIFI (Groß-/Kleinschreibung beachten, keine Dateiendung) mit genau zwei Zeilen angelegt werden:

SSID
WLAN-Passwort

Zeile 1 enthält die SSID, Zeile 2 den Pre-Shared Key (WLAN-Passwort). Beim nächsten Start (ohne Ethernet-Kabel) erkennt OpenCCU die Datei automatisch, erzeugt daraus die Datei /etc/config/wpa_supplicant.conf mit den WLAN-Zugangsdaten und versucht, eine Verbindung zum angegebenen WLAN aufzubauen. Die Datei SetupWIFI wird anschließend aus Sicherheitsgründen automatisch gelöscht.

Alternativ ist dies auch auf einem bereits laufenden System möglich: Die Datei SetupWIFI unter /etc/config anlegen und anschließend neu starten.

OpenCCU enthält den Bluetooth-Stack BlueZ, sodass z. B. die Onboard-Bluetooth-Funktion eines Raspberry Pi oder ein USB-Bluetooth-Stick genutzt werden kann (z. B. durch CCU-Add-ons). Standardmäßig ist Bluetooth deaktiviert. Zum Aktivieren per SSH folgende Datei anlegen und OpenCCU neu starten:

touch /etc/config/enableBluetooth
reboot

Beim Raspberry Pi 3/4 wird das Onboard-Bluetooth dabei über die Mini-UART angebunden, da die Haupt-UART für ein GPIO-Funkmodul (RPI-RF-MOD, HM-MOD-RPI-PCB) benötigt wird. Zum Deaktivieren die Datei wieder löschen (rm -f /etc/config/enableBluetooth) und neu starten.

OpenCCU kann auch als reines BidCos-LAN-Gateway betrieben und an eine CCU oder eine andere OpenCCU angebunden werden, um die Reichweite für BidCos-RF (HomeMatic)-Geräte – analog zum HM-LGW-O-TW-W-EU – zu vergrößern. Aufgrund technischer Einschränkungen des LAN-Gateway-Protokolls ist keine Reichweitenverlängerung für Homematic IP (HmIP) möglich. Der LAN-Gateway-Betrieb funktioniert mit HM-MOD-RPI-PCB, RPI-RF-MOD und HmIP-RFUSB (die beiden letzteren seit Version 3.67.10.20230114).

Wer die Reichweite von HmIP erhöhen möchte, muss dies über dafür vorgesehene Geräte/Wege tun (z. B. „reichweitenverlängerte“ Aktoren wie HmIP-PSM oder über einen HmIP-HAP, der an OpenCCU angelernt wird).

• Der LAN-Gateway-Betrieb gilt nur für BidCos-RF (klassisches „HomeMatic“); Homematic IP wird nicht unterstützt.
• Ein LAN-Gateway sollte grundsätzlich per Kabel angebunden sein; bei WLAN-Betrieb drohen Verbindungsstörungen.
• Wie beim originalen LAN-Gateway (HM-LGW-O-TW-W-EU) wird keine WebUI gestartet, wenn OpenCCU im LAN-Gateway-Modus läuft.

1. In der WebUI die Firewall für die Homematic XML-RPC API freigeben (Einstellungen → Systemsteuerung → Firewall konfigurieren).
2. SSH-Zugang in der WebUI freischalten (Einstellungen → Systemsteuerung → Sicherheit → SSH).
3. Per SSH als Benutzer root anmelden und folgendes Kommando ausführen:

   touch /usr/local/HMLGW
   

4. OpenCCU neu starten (z. B. mit reboot).

Nach dem Neustart fährt OpenCCU normal hoch, zeigt auf dem Startbildschirm in der Versionszeile jedoch LAN-Gateway Mode (IP: <IP-Adresse>, Serial: <Seriennummer>) an. Diese IP-Adresse und Seriennummer können anschließend in der „Haupt-CCU/OpenCCU“ bei der LAN-Gateway-Konfiguration eingetragen werden.

Soll OpenCCU wieder im Normalbetrieb laufen, die Datei /usr/local/HMLGW löschen und neu starten. Alternativ lokal anmelden (z. B. Monitor+Tastatur, ALT+F2, Login root) und ausführen:

rm -f /usr/local/HMLGW && reboot

Wer eine unterbrechungsfreie Stromversorgung (USV) nutzt, kann OpenCCU entweder als NUT-Client mit einem NUT-Server verbinden oder – sofern von NUT unterstützt – eine USV direkt per USB betreiben.

Beispiel: OpenCCU als NUT-Client (z. B. USV am Synology NAS):

1. SSH in der WebUI freischalten (Einstellungen → Systemsteuerung → Sicherheit → SSH).
2. Per SSH als root anmelden und /etc/config/nut/nut.conf anpassen: MODE=netclient (Standard ist none).
3. In /etc/config/nut/upsmon.conf die MONITOR-Zeile aktivieren (Kommentarzeichen # entfernen) und korrekt setzen, z. B.:

   MONITOR ups@bigserver 1 <USERNAME> <PASSWORD> secondary
   

   Statt ups@bigserver z. B. ups@<IP-ADRESSE> verwenden. Für Synology NAS gilt: Benutzername monuser, Passwort secret (es ist kein Benutzer auf dem NAS anzulegen). In älteren Konfigurationen – und auch in der mit OpenCCU ausgelieferten Vorlage – wird statt secondary noch die gleichbedeutende, veraltete Bezeichnung slave verwendet.
4. NUT-Dienst neu starten:

   /etc/init.d/S51nut restart
   

Danach läuft der NUT-Daemon upsmon und überwacht die USV. Bei Stromausfall wird zunächst eine Alarmmeldung in der WebUI erzeugt; bei längerem Ausfall fährt OpenCCU geordnet herunter.

Hinweis: Der Betrieb als NUT-Server (direkter USB-Anschluss) ist prinzipiell über die Konfiguration unter /etc/config/nut möglich, wurde aber noch nicht umfassend getestet. Siehe die NUT-Dokumentation für die Anpassung der Konfiguration an eigene Bedürfnisse.

Mit einem Raspberry Pi 3/4/5 ist es möglich, OpenCCU vollständig von einem USB-Medium (USB-Stick bzw. USB-Festplatte/SSD) zu betreiben, beim Raspberry Pi 5 zusätzlich auch von einer NVMe-SSD (z. B. über einen M.2-HAT). Dazu die *.img-Datei statt auf eine microSD-Karte mit demselben Imaging-Tool (z. B. dem Raspberry Pi Imager) auf den USB-Datenträger bzw. die NVMe-SSD schreiben und diese am Raspberry Pi anschließen.

Bitte beachten:

• Der Raspberry Pi 3 B+ und 3 A+ können ab Werk von USB starten. Beim Raspberry Pi 3 B muss der USB-Boot zuvor einmalig aktiviert werden, indem der Pi mit dem Eintrag program_usb_boot_mode=1 in der Datei config.txt von einer microSD-Karte gestartet wird (siehe Raspberry-Pi-Dokumentation); anschließend die microSD entfernen und vom USB-Medium booten. Beim Pi 3 ist aufgrund von USB 2.0 mit geringerer I/O-Leistung als bei microSD zu rechnen.
• Beim Raspberry Pi 4/5 muss eine aktuelle Bootloader-Firmware (EEPROM) vorhanden sein, die den Start von USB bzw. NVMe unterstützt (siehe Raspberry-Pi-Dokumentation). Das OpenCCU-Image enthält dazu ein Bootloader-Update (pieeprom.upd/recovery.bin), das der Raspberry Pi beim Start selbstständig einspielt; ggf. ist dafür ein einmaliger Start von microSD nötig.
• Beim Start ohne SD-Karte kann folgender Eintrag in der Datei config.txt der Boot-Partition nötig sein, um Warnungen wie mmc0: timeout waiting for hardware interrupt zu vermeiden:

  dtparam=sd_poll_once=on
  

• Funktioniert der USB-Boot beim Raspberry Pi 4 nicht, kann dies an Adapter-Spezifika liegen (siehe Finding the VID and PID of your USB SSD im Raspberry-Pi-Forum). Die ermittelten „quirks“ können in der Datei cmdline.txt der Boot-Partition hinterlegt werden.

Weitere Hinweise zum USB-Boot:

• Beste Performance: Pi 4/5 + SSD via USB-3 → SATA-Adapter (am USB-3-Port) bzw. beim Pi 5 eine NVMe-SSD.
• ASM1053/ASM1153-Adapter sind empfehlenswert.
• JMSxxx-Adapter können problematisch sein; ggf. über cmdline.txt-„quirks“ lauffähig.
• USB-2/-3-Sticks funktionieren, bringen jedoch keinen Vorteil und sind nicht empfohlen.
• Beim Raspberry Pi 4 können USB-3-Geräte den Funkempfang eines GPIO-Funkmoduls stören (siehe Bekannte Probleme).

Einschränkungen beim USB-Boot: Grundsätzlich sollte nur das Boot-USB-Medium angeschlossen sein. Ein weiteres USB-Medium ist nicht nötig, da die Benutzerdaten auf dem Boot-Medium abgelegt werden. Soll dennoch ein zweites Medium genutzt werden, beachten:

• Pi 4/5: bootet korrekt vom vorgesehenen USB-Medium (das zweite Medium darf nicht bootfähig sein).
• Pi 3B(+): bootet nicht korrekt, wenn das zweite USB-Medium mit FAT/FAT32/NTFS formatiert ist; mit F2FS startet der Boot.

Tweaks für USB-Boot: Systembedingt zeigt die rote LED des Raspberry Pi beim USB-Boot nicht die Aktivität (Lesen/Schreiben) des Boot-Mediums an. Ein anderer LED-Trigger kann gesetzt werden:

• Nur Boot-Medium am USB:

  echo usb-host >/sys/class/leds/PWR/trigger
  

• Mehrere USB-Geräte angeschlossen (USB-Platine, USV etc.):

  echo activity >/sys/class/leds/PWR/trigger
  

Für das automatische Setzen des Triggers nach einem Neustart kann der Befehl in das rc-Skript rc.postlocal aufgenommen werden.

OpenCCU integriert den Software-Watchdog Monit, der abgestürzte oder nicht reagierende Prozesse automatisch neu startet und Systemzustände überwacht, damit alle CCU-Dienste zuverlässig laufen (siehe auch WatchDog-Meldungen).

Standardmäßig arbeitet Monit im Hintergrund. Zusätzlich zum Zugriff über die Kommandozeile (z. B. monit summary) kann eine Weboberfläche aktiviert werden:

1. Per SSH auf der OpenCCU anmelden.
2. Datei /usr/local/etc/monit.cfg erstellen (z. B. mit vi /usr/local/etc/monit.cfg).
3. Beispiel-Konfiguration mit Nutzer/Passwort:

   set httpd port 2812
       allow 192.168.x.x/24  # Eigenes Netz oder Host-IP(s)
       allow user:passwort   # Bei Sonderzeichen Passwort in "..." setzen
   

   Beispiel mit htpasswd-Datei:

   set httpd port 2812
       allow 192.168.x.x/24  # Eigenes Netz oder Host-IP(s)
       allow md5 /pfad/zur/htpasswd-datei
   

4. Monit die Konfiguration neu einlesen lassen: monit reload
5. In der Firewall (Einstellungen → Systemsteuerung → Firewall konfigurieren) den Port 2812 für den Zugriff freigeben.

Danach ist Monit über folgende URL erreichbar: http://<IP-der-CCU>:2812

OpenCCU enthält einen SNMP-Dienst (Net-SNMP), über den sich die Zentrale in Netzwerk-Monitoring-Systeme (z. B. Zabbix, PRTG, LibreNMS, Checkmk) einbinden lässt.

Aktivierung über die WebUI:

1. Unter Einstellungen → Systemsteuerung → Sicherheit im Bereich SNMP die Option „SNMP aktiv“ setzen.
2. Einen Benutzernamen sowie ein Passwort (zweimal) eingeben und speichern.

Unterstützt wird dabei ausschließlich SNMPv3 mit SHA (Authentifizierung) und AES (Verschlüsselung). Der angegebene Benutzer erhält Lesezugriff; die Firewall wird für den SNMP-Dienst (UDP-Port 161) automatisch freigegeben. Wie alle CCU-Dienste ist SNMP standardmäßig nur aus lokalen/privaten Netzen erreichbar.

Abfrage-Beispiel von einem anderen Linux-System:

snmpwalk -v3 -l authPriv -u <BENUTZER> -a SHA -A <PASSWORT> -x AES -X <PASSWORT> <IP-der-CCU> system

Eigene Erweiterungen der SNMP-Konfiguration: Zusätzliche Einstellungen für den SNMP-Dienst (z. B. sysLocation, sysContact oder weitere Zugriffsrechte) können per SSH in der Datei /etc/config/snmp/snmpd-user.conf im Format der snmpd.conf hinterlegt werden. Anschließend den Dienst neu starten:

/etc/init.d/S59snmpd restart

Der SNMP-Dienst wird nur gestartet, solange SNMP in der WebUI aktiviert ist.

Mit dem HB-RF-ETH von Alexander Reinert (siehe auch Einleitung → Voraussetzungen) ist es möglich, ein Funkmodul (RPI-RF-MOD oder HM-MOD-RPI-PCB) abgesetzt über das Netzwerk zu betreiben – z. B. für eine virtualisierte OpenCCU oder um das Funkmodul entstört (abseits des Rechners) zu platzieren.

Bitte beachten:

• HB-RF-ETH ausschließlich über verkabeltes Netzwerk betreiben. WLAN/VPN kann aufgrund höherer Latenzen unzuverlässig sein.
• Es kann nie mehr als ein über HB-RF-ETH angebundenes Funkmodul genutzt werden. Werden zwei Module (GPIO + HB-RF-ETH) angeschlossen, wird eines für HomeMatic (BidCos-RF) und das andere nur für Homematic IP genutzt – keine Reichweitenverlängerung. Für mehr Reichweite ggf. ein LAN-Gateway (BidCos-RF) bzw. einen HAP (HmIP) verwenden.
• Während Start und Betrieb muss das HB-RF-ETH stabil erreichbar sein. Bei einer Verbindungsunterbrechung wird die Alarmmeldung WatchDog: hb-rf-eth-connection erzeugt; ggf. ist ein Neustart von OpenCCU erforderlich.

1. Dem HB-RF-ETH eine feste IP-Adresse geben (Router-Reservierung oder direkt in dessen Weboberfläche).
2. Unter Einstellungen → Systemsteuerung → Erweiterte Einstellungen bei IP-Adresse (HB-RF-ETH) die IP-Adresse des HB-RF-ETH eintragen.
3. OpenCCU neu starten (reboot) – oder, falls das Funkmodul erst noch umgebaut wird, die Zentrale herunterfahren (poweroff), Funkmodul umbauen, HB-RF-ETH in Betrieb nehmen und danach OpenCCU starten.

Alternativ kann die IP-Adresse per SSH in /etc/config/hb_rf_eth eingetragen werden.

1. Unter Einstellungen → Systemsteuerung → Erweiterte Einstellungen die IP-Adresse des HB-RF-ETH entfernen.
2. OpenCCU neu starten.

Über Einstellungen → Systemsteuerung → Erweiterte Einstellungen → Alternativer Speicherpfad bzw. die Datei /etc/config/CustomStoragePath kann das Standard-Speicherverzeichnis für Diagramme und – sofern kein eigener Backup-Speicherpfad gesetzt ist – die automatischen Backups (i. d. R. ein USB-Stick bzw. /usr/local/sdcard bei USB-Boot, virtuellen Maschinen und Containern) auf ein beliebiges Nutzerverzeichnis umgestellt werden – lokal oder auf ein gemountetes Netzlaufwerk (z. B. NAS).

Inhalt von /etc/config/CustomStoragePath: absoluter Pfad, z. B.

• /mnt (z. B. für ein gemountetes Netzwerklaufwerk)

Nach dem Anlegen/Ändern ist ein Neustart erforderlich.

Hinweis: Verzeichnisse, die erst beim Hochfahren eingebunden werden (z. B. NFS, CIFS/SMB), sollten über rc.prelocal gemountet werden, damit sie anschließend als Speicherpfad verfügbar sind.

Um beim Start der Zentrale zu definierten Zeitpunkten eigene Shell-Kommandos auszuführen (z. B. Mount eines NAS), können sog. rc-Skripte angelegt werden. Existiert ein Skript nicht, wird es übersprungen.

Bitte beachten:

• Jedes rc-Skript wird nach spätestens 120 Sekunden abgebrochen, damit ein hängendes Skript den Startvorgang nicht blockiert. Länger laufende Aktionen daher im Hintergrund starten (z. B. mit &).
• Beim Booten im abgesicherten Modus (siehe Vorgehen bei fehlgeschlagenem Update) werden die rc-Skripte übersprungen, damit fehlerhafte Skripte das Hochfahren nicht verhindern.

Die Skripte müssen mit dem Shebang beginnen (#!/bin/sh) und der ash/dash-Syntax folgen (keine bash-Spezifika). Außerdem benötigen sie Ausführrechte (chmod a+rx <DATEI>). Skripte am besten zunächst interaktiv per SSH testen.

Nachfolgend kurze Beispiele für typische Anwendungsfälle:

Mounten einer CIFS-Freigabe in /usr/local/etc/rc.prelocal:

#!/bin/sh
mount -t cifs -o noserverino,vers=3.11,username=USER,password=PASS //192.168.1.1/fritz.nas/test/RM_B /mnt

Mounten einer NFS-Freigabe in /usr/local/etc/rc.prelocal:

#!/bin/sh
mount -t nfs -o nolock,hard,intr,relatime 192.168.1.1:/volume1/Backup/Freigabe /mnt

Hinweis: rc.prelocal wird vor dem Start der CCU-Add-ons und vor den zentralen Diensten mit bereits verfügbarem Netzwerk ausgeführt. Ausführrechte setzen, z. B.: chmod u+rx /usr/local/etc/rc.prelocal

Mount einer vorbereiteten lokalen Partition (z. B. /dev/sda4) in /usr/local/etc/rc.postinit:

#!/bin/sh
mount /dev/sda4 /mnt

Die Onboard-LEDs eines Einplatinencomputers lassen sich direkt über Einstellungen → Systemsteuerung → Erweiterte Einstellungen → LED-Nutzung (Onboard) deaktiviert bzw. reaktiviert werden (siehe Status-LED-Funktion).

Auch beim Herunterfahren können eigene Shell-Kommandos ausgeführt werden. Fehlt das Skript, wird es übersprungen.

Für rc.shutdown gelten dieselben Anforderungen (Shebang, ash-Syntax, Ausführrechte, Abbruch nach spätestens 120 Sekunden) wie für die rc-Skripte beim Bootvorgang. Im Gegensatz zu diesen wird rc.shutdown auch im abgesicherten Modus ausgeführt.