Node-RED als Addon für die Homematic CCU3 und OpenCCU

_{Click here for 🇬🇧🇺🇸 english readme}

🚀 Schnellstart       📚 Dokumentation       📦 Download       🚑 Support       👮 Lizenzen

---

⚠️ RedMatic 9: RedMatic wurde radikal verschlankt und modernisiert (Node.js 24, Node-RED 5). Ab Version 9 ist nur noch node-red-contrib-ccu vorinstalliert — alle weiteren Nodes (z. B. Dashboard, HomeKit, Matter) werden bei Bedarf über den Node-RED Paletten-Manager installiert. Der RedMatic-Paketmanager und die RedMatic-WebApp sind deprecated und entfallen ersatzlos. Bekannte und akzeptierte Einschränkung: npm-Pakete bzw. Nodes mit binären (nativen) Abhängigkeiten können auf der CCU nicht installiert werden — auf der CCU gibt es keine Compiler-Toolchain, und vorkompilierte Binaries werden nicht mehr mitgeliefert.

RedMatic 9 ist veröffentlicht - siehe Releases. Voraussetzung: CCU3 mit Firmware ab 3.61.5 oder aktuelles OpenCCU. Vor einem Update von RedMatic 7 unbedingt ein CCU-Backup anlegen - das Backup liegt in der Verantwortung des Anwenders, ein Weg zurück führt nur darüber. Bitte die Release-Hinweise lesen.

RedMatic verpackt Node-RED als CCU Addon, ein Softwarepaket, das auf einer Homematic CCU3 oder OpenCCU (ehemals RaspberryMatic) als Zusatzsoftware komfortabel über das WebUI installiert werden kann.

Die Grundlage bildet Node-RED mit den CCU Nodes für Node-RED. Hiermit ist es auf einfache und visuelle Weise möglich Regeln, Automationen, Scripte und Anbindungen von externen Services und Systemen für ein Homematic System zu realisieren - und das weitgehend auch ohne Programmierkenntnisse. Im Wiki gibt es weitere Informationen zu Node-RED und einige Anwendungsbeispiele (sogenannte Flows).

Die Einrichtung und der Betrieb von RedMatic ist sehr benutzerfreundlich, es bedarf keiner Linux-Kenntnisse und es müssen keine Konfigurationsdateien bearbeitet werden.

RedMatic als Brücke von der CCU zu MQTT, Home Assistant, Alexa, Apple Home, Google Home, ...

RedMatic ist ein guter Weg, eine Homematic CCU an andere Systeme anzubinden - direkt auf der CCU, ohne zusätzlichen Server:

• MQTT - der ccu-mqtt Node publiziert alle Datenpunkte mit frei konfigurierbarer Topic- und Payload-Struktur und nimmt Befehle entgegen (Beispiel-Flow).
• Home Assistant - der ccu-homeassistant Node ergänzt ccu-mqtt um MQTT Auto-Discovery: ausgewählte Geräte erscheinen automatisch als Entitäten in Home Assistant.
• Matter - RedMatic-Matter stellt Homematic-Geräte als Matter-Bridge bereit, nutzbar u.a. mit Apple Home, Amazon Alexa und Google Home.
• HomeKit - RedMatic-HomeKit stellt Homematic-Geräte als HomeKit-Zubehör bereit. (Mögliche Ergänzung zu Matter für Apple Nutzer um den fehlenden Matter-Support für bestimmte Geräte wie z.B. Garagentore oder Bewässerungssysteme zu umschiffen)

Alle Anbindungen laufen über eine einzige ccu-connection, die auf der CCU ausgewählte Geräte per Häkchen freigibt (opt-in). Matter und HomeKit werden über den Node-RED Paletten-Manager installiert, MQTT und Home Assistant sind in den vorinstallierten CCU Nodes enthalten.

Warum auf der CCU und nicht mit einem externen Bridge-Projekt? Es gibt gute Alternativen wie CCU-Jack, openccu-loom oder matterbridge-homematic. Die Schnittstellen-Prozesse der CCU (rfd, hs485d, HmIPServer) reagieren jedoch empfindlich auf viele gleichzeitige RPC-Event-Abonnenten und auf Netzwerkstörungen. RedMatic bündelt alle Anbindungen in einem einzigen Abonnenten pro Schnittstelle, spricht mit rfd und hs485d das effizientere BIN-RPC statt XML-RPC und hält den gesamten RPC-Verkehr auf der Loopback-Schnittstelle der CCU - Netzwerkaussetzer erreichen die CCU-Prozesse so gar nicht erst.

Was auf der anderen Seite der MQTT-Brücke sitzen kann - zwei Projekte des RedMatic-Autors, die die Discovery-Daten von RedMatic direkt verstehen:

• feezal - Dashboards und Apps für MQTT visuell im Browser bauen (WYSIWYG-Editor, Web Components, PWA, Export als statische Seite oder Android/iOS-App). Erkennt die von RedMatic per Auto-Discovery gemeldeten Geräte und verdrahtet sie mit einem Klick - ein moderner Ersatz für die entfallene RedMatic-WebApp.
• she - Smart Home Engine: Automationen als einfache JavaScript-Scripte mit MQTT, integriertem Matter-Controller, Scheduler und Web-IDE mit KI-Assistent. Für alle, die Logik lieber in Code als in Flows schreiben oder eine zentrale Engine abseits der üblichen Verdächtigen (z.B. Home Assistant oder ioBroker) suchen 😉

Automatisieren mit Node-RED

Eine große und aktive Community rund um Node-RED hat zudem eine Bibliothek von tausenden zusätzlichen Nodes geschaffen die auf einfache Weise installiert werden können und es ermöglichen spezielle Automatismen zu implementieren und diverse weitere Services und Systeme komfortabel anzubinden - wie z.B. KNX, Loxone, Somfy Tahoma, Velux KLF200, Home Connect Haushaltsgeräte, verschiedene Smart TVs und AV-Receiver, Sonos, Netatmo, Hue, Amazon Alexa, Google Home, diverse Datenbanken wie z.B. InfluxDB oder MySQL, Webservices zur Abfrage von beispielsweise Wetterdaten und vieles mehr.

RedMatic kann damit - insbesondere auch für diejenigen die neben der CCU keinen weiteren Server betreiben möchten - eine Alternative zu einem "ausgewachsenen" Smart Home System wie z.B. Home Assistant oder ioBroker darstellen. Auch eine Koexistenz mit vorhandener anderer Smart Home Software kann sinnvoll sein. Nicht zuletzt kann RedMatic auch als stabile und mit wesentlich mehr Möglichkeiten aufwartende Alternative oder Ergänzung zu den WebUI-Programmen und Scripten der CCU Logikschicht "Rega" dienen.

Voraussetzungen

RedMatic ist geeignet für die CCU3 (und piVCCU3) mit Firmware ab 3.61.5 sowie für aktuelles OpenCCU auf den Architekturen armv7l (z.B. Raspberry Pi 2), aarch64 (z.B. Raspberry Pi 3/4/5) und x86_64 (z.B. ova, intelnuc, Container).

Auf der CCU1, CCU2 und auf armv6l-Systemen (Raspberry Pi 1/Zero) kann RedMatic nicht verwendet werden.

Für Matter (RedMatic-Matter) muss IPv6 im LAN aktiv sein (eine Link-Local-Adresse genügt; RedMatic legt sie auf der CCU3 beim Start an, falls sie fehlt), und der Matter-Controller (Apple TV/HomePod, Echo, Nest Hub, Home Assistant) muss sich im selben Netzsegment wie die CCU befinden.

Schnellstart

Unter Releases steht die Datei redmatic-<version>.tar.gz zum Download zur Verfügung. Nach der Installation des Addons über das Homematic WebUI (Systemsteuerung -> Zusatzsoftware) und dem darauf folgenden Reboot der CCU ist Node-RED unter http://<ccu-addresse>/addons/red erreichbar. Bei der Installation ist Geduld erforderlich, es kann einige Minuten dauern.

Support, Mitarbeit

Für Feedback jeglicher Art, Fragen, Vorschläge und Wünsche bitte das Diskussionsforum nutzen. Für Bug Reports bitte den Issue Tracker nutzen.

Beteiligung in jeder Form ist willkommen und gewünscht, insbesondere sind alle Nutzer aufgefordert die Liste erfolgreich getesteter Nodes zu ergänzen, Beispiel-Flows zu veröffentlichen und an der Verbesserung und Erweiterung der Dokumentation mitzuarbeiten.

Es werden keine Spenden angenommen, ich würde mich jedoch darüber freuen wenn der erfolgreiche Einsatz dieser Software mit einem Github Sternchen ⭐️ honoriert wird (Github Account ist schnell angelegt! ;-)

Dokumentation

• FAQ - Häufig gestellte Fragen

• Administration

  • Installation
  • Update
  • Migration auf RedMatic 9 - was sich gegenüber 7.x/8.x ändert
  • Backup
  • Firewall
  • Context Storage Konfigurieren
  • Passwort Schutz für Node-RED einrichten
  • Sicherheits-Hinweise
  • Zusätzliche Nodes installieren
  • Erfolgreich mit RedMatic getestete Nodes - bitte diese Liste ergänzen!
  • Log-Level erhöhen für Fehleranalyse
  • Safe Mode
  • Deinstallation

• Nutzung

  • Node-RED Grundlagen
  • CCU Nodes
  • Tipps
  • Flows exportieren
  • Flows importieren

• Spezielle Nodes und Erweiterungen

  • node-red-contrib-zigbee - ⚠️ deprecated, nicht mehr gepflegt, auf RedMatic 9 nicht installierbar (Alternative: zigbee2mqtt auf einem separaten Rechner)
  • RedMatic-HomeKit - Anbindung an Apple HomeKit (ab RedMatic 9 nicht mehr vorinstalliert, Installation über den Paletten-Manager)
  • RedMatic-WebApp - ⚠️ deprecated, ab RedMatic 9 nicht mehr enthalten
  • Node-RED Dashboard - ab RedMatic 9 nicht mehr vorinstalliert, Installation über den Paletten-Manager
  • node-red-contrib-sun-position Zeit- und Sonnenstandabhängige Funktionen, Komfortable Beschattungssteuerung
  • node-red-contrib-signal-client

• Beispiel Flows

  • Kostenlose Alexa (und Google) Anbindung
  • Sprachausgabe über Alexa/Echo
  • CCU an MQTT anbinden
  • Anzahl und Liste offener Fenster im Dashboard anzeigen
  • Hue Lampen mit langem Tastendruck dimmen
  • UNREACH Meldung unterdrücken
  • STICKY_UNREACH Meldungen bestätigen und zählen
  • Anzeigen und Setzen von Systemvariablen im Dashboard
  • DutyCycle Graph im Dashboard anzeigen
  • JSON Daten von Webservice abfragen und in Systemvariable schreiben
  • Inhalt einer Systemvariablen über einfachen Webservice bereitstellen
  • Per Pushover benachrichtigen wenn Fenster länger als 10 Minuten offen ist
  • CPU Auslastung als Graph im Dashboard anzeigen
  • Schnelles Blinken der LED im Offline-Betrieb unterbinden
  • Bidcos-Wired Dimmer mit Bidcos-RF Tasten steuern
  • Discovery von Geräten mit Echo Dot v3 und node-red-contrib-amazon-echo

• Von Usern bereitgestellte Flows

  • Licht mittels Tastendruck aus und einschalten
  • Licht schalten mit einem Dashboard button
  • Textausgabe mittels Chromecast oder Google Home
  • Berechnung von Feiertagen
  • Funktion nur innerhalb einer bestimmten Uhr-Zeit ausführen
  • Fehlerüberwachung der CCU
  • Integration Weatherman (JSON, httpStatic, SteelSeries Gauges)
  • Systeminformationen der CCU Zentrale
  • Werte in InfluxDB speichern
  • Diverse Flows von @Sineos
  • Harmony Activities mit Homekit nutzen
  • Homekit: Kamera einbinden
  • Homekit: Öffnen einer Tür mit Keymatic HM-Sec-Key-(S)
  • Nachrichten an Telegram versenden
  • Dashbuttons ohne zusätzliche Nodes auswerten
  • Monitoring der Batteriespannung von Aktoren (hier: HM-CC-RT-DN)
  • Datenpunktstatus von mehreren Geraeten gleichzeitig abfragen
  • Rollladen und Jalousiesteuerung
  • Zwischen zwei Zeitpunkten jede halbe Stunde einen Inject generieren
  • Wetterdaten mittels OpenWeatherMap in ein CUxD Device übertragen
  • Schalter mit Statusanzeige
  • Pillenförmige-Schalter sychron mit globaler Variable
  • Zusätzliche Wettericons für UI-Dashboard in Redmatic verfügbar machen
  • E3DC Anbindung per Modbus-TCP
  • Steuerung von Miele Geräten
  • Subflow für Enigma2 Receiver
  • INSTAR Kameras anbinden
  • Shelly Relais zu Schalten von Leuchten
  • Waschmaschine fertig? Waschmaschine mit HmIP-PSM Messsteckdose monitoren
  • SMS mit SIM800 Modul: SMS senden & empfangen
  • BMW Connect Status in Dashboard und Apple HomeKit
  • EgiGeoZone Geofence Subflow: An/abmelden von Geozonen, in Redmatic empfangen
  • Xiaomi / Roborock S1-S6 in Dashboard
  • Anrufsperre über Fritzbox für eingehende Anrufe
  • AIO NEO Popup Subflow (öffnen von AIO-NEO Popups auf Tablet oder Smartphone)

• Verwandte Projekte

  • RedMatic-HomeKit - Homematic-Geräte in Apple HomeKit
  • RedMatic-Matter - Homematic-Geräte als Matter-Bridge
  • feezal - Dashboards und Apps für MQTT visuell bauen
  • she - Smart Home Engine: Automationen als JavaScript-Scripte mit MQTT und Matter

• Sonstiges

  • Berichterstattung, Blogbeiträge, Videos über RedMatic
  • Node-RED Link Sammlung
  • Telemetrie
  • Danksagungen
  • Change History

openccu-lite

openccu-lite ist eine Homematic-CCU-Firmware ohne ReGaHSS. RedMatic läuft dort mit demselben Paket, denselben Einstellungen und denselben Flows wie auf einer CCU3, RaspberryMatic oder OpenCCU. Um welche Art Zentrale es sich handelt, wird zur Laufzeit erkannt (GET /api/meta/v1/version); konfiguriert werden muss nichts, und ein Backup lässt sich zwischen beiden hin- und herschieben.

Was funktioniert

• Node-RED selbst mit Palette-Manager, Projekten/git, Einstellungsseite samt Session-Prüfung, Backup, Log, Log-Upload und dem Ein-Klick-Selbstupdate.
• Alles, was die node-red-contrib-ccu-Nodes über die Schnittstellenprozesse (rfd, hs485d, hmipserver) machen: Werte, Kommandos, RPC-Events. Geräte-, Kanal-, Raum- und Gewerkenamen kommen statt aus der ReGaHSS aus der Metadaten-API der Zentrale und folgen einer Umbenennung binnen einer Sekunde. msg.channelName, msg.rooms, msg.functions und die Raum-/Gewerke-Filter behalten exakt die Form, die sie auf einer CCU haben.
• Für die Namen wird ein Token gebraucht: auf der Zentrale wird der nur lesende Token aus /usr/local/etc/occulite/local-token automatisch verwendet (RedMatic läuft dort als root), es ist also nichts einzustellen. Läuft Node-RED woanders, gehört ein auf der Benutzer-Seite der Zentrale erzeugter Token in das Feld openccu-lite token des Connection-Nodes.
• Der Admin-Login des Editors: die Authentifizierungs-Einstellung Benutzer der Zentrale nutzt auf einer CCU die ReGaHSS-Benutzer und auf openccu-lite die Benutzer der Zentrale (POST /api/auth/v1/login).

Wofür es keinen Ersatz gibt (aus der Portierungsanleitung von openccu-lite):

• Systemvariablen und Programme: es gibt kein ReGa-DOM. Die Nodes ccu-sysvar, ccu-program und ccu-poll bleiben in der Palette und in den Flows — sie werden akzeptiert, sie legen die Verbindung nie lahm, und jede Nachricht wird stattdessen mit einer klaren Fehlermeldung beantwortet.
• exec() von HM-Script — dom.GetObject, system.GetSessionVarStr und alles andere, was der ccu-script-Node schickt: nicht vorhanden, gleiche Behandlung wie oben.
• ReGa-IDs (dom.GetObject(1234)): gibt es nicht. Die Metadaten-API identifiziert Objekte über <Schnittstelle>.<Adresse>; diese Nodes arbeiten seit jeher mit der Adresse, für Flows ändert sich also nichts.
• Servicemeldungen / Alarme (Systemvariablen 40 und 41): nur Zustand auf Schnittstellenebene.
• Die JSON-RPC-API der CCU-WebUI (/api/homematic.cgi, Session.login, Device.listAll): nicht vorhanden.

Auf den systemd-Produkten von openccu-lite läuft das rc.d-Skript in einer generierten Unit addon-redmatic.service (Type=oneshot, RemainAfterExit=yes, KillMode=control-group): start kehrt zurück, nachdem Node-RED in den Hintergrund gestartet wurde, stop beendet es. Ein /var/log/messages gibt es dort nicht — Node-RED und das Addon loggen ins Journal unter den Tags node-red und redmatic (journalctl -t node-red -t redmatic), das Log der Einstellungsseite liest sie von dort. RedMatic schreibt keine PID-Datei (es findet seinen Prozess über den Namen), hängt also nicht an einem beschreibbaren /var/run. Geschrieben wird: das eigene Verzeichnis /usr/local/addons/redmatic (etc, var, tmp, home, lib, www), /tmp/redmatic-update (Zustand des Selbstupdates), /usr/local/tmp (Backup-Archiv und heruntergeladene Pakete), /etc/config/rdmtc.uuid (die Telemetrie-ID, wird übersprungen wenn das Verzeichnis nicht beschreibbar ist) und bei der Installation /usr/local/etc/config/rc.d, /usr/local/etc/config/lighttpd und /usr/local/etc/config/addons/www.

Lizenzen

• RedMatic © 2018-2026 Sebastian Raff and RedMatic Contributors, licensed under Apache License 2.0
• RedMatic Documentation © 2018-2026 Sebastian Raff and RedMatic Contributors, licensed under CC BY-SA License 4.0
• Third-party components are listed in the SBOM files (CycloneDX) attached to each release; the full license texts ship inside the addon in each package's node_modules directory

DIE SOFTWARE WIRD OHNE JEDE AUSDRÜCKLICHE ODER IMPLIZIERTE GARANTIE BEREITGESTELLT, EINSCHLIEẞLICH DER GARANTIE ZUR BENUTZUNG FÜR DEN VORGESEHENEN ODER EINEM BESTIMMTEN ZWECK SOWIE JEGLICHER RECHTSVERLETZUNG, JEDOCH NICHT DARAUF BESCHRÄNKT. IN KEINEM FALL SIND DIE AUTOREN ODER COPYRIGHTINHABER FÜR JEGLICHEN SCHADEN ODER SONSTIGE ANSPRÜCHE HAFTBAR ZU MACHEN, OB INFOLGE DER ERFÜLLUNG EINES VERTRAGES, EINES DELIKTES ODER ANDERS IM ZUSAMMENHANG MIT DER SOFTWARE ODER SONSTIGER VERWENDUNG DER SOFTWARE ENTSTANDEN.