So entwickelst du dein eigenes Plugin für die Homematic IP HCU-1 [Teil 3: Plugin testen, exportieren und installieren]
Im zweiten Teil dieser Anleitung hast du dein Plugin-Projekt eingerichtet und die Grundlagen für die Entwicklung geschaffen. Jetzt ist es Zeit für den ersten Praxistest.
In diesem Teil lernst du, wie du dein Plugin lokal startest, Fehler erkennst und anschließend ein Installationspaket erstellst, das sich direkt auf deiner Homematic IP HCU-1 installieren lässt.
Alle Programme, die du benötigst findest du in Teil 1 dieser Reihe.
Plugin lokal testen
Bevor du dein Plugin auf der HCU installierst, solltest du es lokal testen. Das spart viel Zeit, da Fehler bzw. Logs direkt im Terminal sichtbar werden und nicht erst nach einer Installation auffallen. Außerdem lassen sich so Crashes viel einfacher nachvollziehen und beheben.
So startest du mit dem lokalen Test:
Öffne dein Plugin-Projekt (Ordner) in Visual Studio Code.
Anschließend öffnest du über die Menüleiste ein neues Terminal:
Terminal > New Terminal
Das Terminal wird automatisch im Hauptverzeichnis deines Projekts geöffnet.
Abhängigkeiten installieren
Bevor du dein Plugin lokal ausführen kannst, Installiere zunächst alle benötigten Node.js-Abhängigkeiten über das Terminal in Visual Studio Code.
npm install
Der Befehl lädt alle Pakete herunter, die in der package.json definiert sind.
Diesen Schritt musst du normalerweise nur nach Änderungen an den Abhängigkeiten oder beim ersten Öffnen des Projekts durchführen. Denn die Daten werden in deinem Projektordner gespeichert.

Plugin starten
Nun kannst du dein Plugin direkt starten.
node <auszuführende-datei.js> de.dein-name.plugin.plugin-name <hcu1-XXXX.local> authtoken.txt
Ersetze anschließend die Platzhalter durch deine Werte.
Ein Beispiel könnte so aussehen:
node src/main.js de.mein-name.plugin.mein-hcu-plugin hcu1-ABCD.local authtoken.txt
Dabei bedeuten die einzelnen Parameter:
- Startdatei deines Plugins
- Plugin-ID
- Hostname deiner HCU-1, beginnt immer mit hcu1- gefolgt von den letzten vier Stellen der SGTIN deiner HCU
- Pfad zur Auth-Token-Datei, die in diesem Fall im Stammverzeichnis des Plugins liegt
Was passiert beim Start?
Beim Start verbindet sich dein Plugin mit der lokalen Homematic IP Connect API auf deiner HCU-1. Hierbei ist wichtig, dass du diese nur erreichen kannst, wenn sich dein Computer und deine HCU-1 im selben Netzwerk befinden.
Verläuft alles erfolgreich, erscheint dein Plugin innerhalb weniger Sekunden in der HCU-Weboberfläche unter
Plugins
als sogenanntes Remote-Plugin.
Das Plugin läuft dabei weiterhin auf deinem Rechner und kommuniziert lediglich mit deiner HCU-1.
Diese Vorgehensweise eignet sich hervorragend zum Entwickeln und Debuggen.
Wenn du das Plugin beenden möchtest, um beispielsweise eine veränderte Version zu starten, drücke einfach im Terminal Strg + C. Das beendet den Prozess sofort und du kannst den node-Befehl wieder ausführen.
Wusstest du, dass du im Terminal mit den Pfeiltasten hoch und runter durch die Historie der eingegebenen Befehle wechseln kannst? Das kann sehr hilfreich sein.
Typische Fehler
Falls dein Plugin nicht erscheint, lohnt sich zunächst ein Blick auf die Konsolenausgabe.
Häufige Ursachen sind:
- falscher Auth-Token
- Tippfehler in der Plugin-ID
- HCU nicht erreichbar
- Entwicklermodus deaktiviert
- WebSocket nicht aktiviert
- falscher Hostname
- Programmier-Fehler im Plugin
In den meisten Fällen liefert die Konsolenausgabe bereits einen eindeutigen Hinweis auf die Ursache.Wenn du einmal mit dem Fehler nichts anfangen kannst, hilft dir Professor Google :-)
Plugin exportieren
Sobald dein Plugin wie gewünscht funktioniert, kannst du daraus ein Installationspaket erstellen.
Wichtig! Bevor du mit diesem Schritt fortfährst, solltest du die authtoken.txt aus dem Verzeichnis verschieben oder mit einer .dockerignore-Datei ausschließen, um diese nicht ins Image zu brennen.
Hierfür wird Docker verwendet, genauer in unserem Fall Docker Desktop. Als erstes musst du das Programm starten, um die folgenden Befehle zum Export des Plugins ausführen zu können.
Öffne erneut ein Terminal im Hauptverzeichnis deines Projekts.
Führe anschließend folgenden Befehl aus:
docker buildx build --platform linux/arm64 -t <plugin-name>:<version> .
Zum Beispiel:
docker buildx build --platform linux/arm64 -t mein-hcu-plugin:1.0.0 .
Bitte achte darauf, dass die Versionsnummer mit jener in der Dockerfile und package.json übereinstimmt.
Docker erstellt nun das eigentliche Plugin-Image für die Homematic IP HCU-1.
Je nach Projektgröße kann dieser Vorgang ein paar Sekunden bis Minuten dauern.
Plugin als Installationsdatei exportieren
Nachdem das Docker-Image erstellt wurde, muss daraus ein Archiv erzeugt werden.
Windows
Unter Windows verwendest du:
docker save <plugin-name>:<version> -o <dateiname>.tar
Beispiel:
docker save mein-hcu-plugin:1.0.0 -o mein-hcu-plugin-1-0-0.tar
Anschließend öffnest du die erzeugte TAR-Datei mit 7-Zip und erstellst daraus ein .tar.gz-Archiv.
Nur dieses Format kann auf der Homematic IP HCU-1 installiert werden.
Linux und macOS
Unter Linux oder macOS genügt ein einzelner Befehl.
docker save <plugin-name>:<version> | gzip > <dateiname>.tar.gz
Zum Beispiel:
docker save mein-hcu-plugin:1.0.0 | gzip > mein-hcu-plugin-1-0-0.tar.gz
Falls gzip noch nicht installiert ist, musst du dieses gegebenenfalls zunächst nachinstallieren. Da der Weg dorthin unterschiedlich ist, empfehlen wir dir eine kurze Google Suche zu dem Thema.
Plugin auf der HCU installieren
Melde dich nun in der Weboberfläche deiner Homematic IP HCU-1 an.
Wechsle zu
Plugins
und klicke anschließend auf
Eigenes Plugin installieren.
Wähle dein zuvor erzeugtes .tar.gz-Archiv aus.
Nun beginnt die Installation. Auch hier kann der Vorgang wieder ein paar Sekunden bis Minuten in Anspruch nehmen.
Falls die Installation nicht abgeschlossen werden kann – das kann gerade beim Testen vorkommen – solltest du die HCU rebooten. Nach dem Neustart ist das Plugin wieder verschwunden. Meist deutet das dann darauf hin, dass es Probleme beim Installieren der Abhängigkeiten gibt oder dein Plugin-Skript versucht zu starten, bevor diese fertig installiert sind.
Nach wenigen Augenblicken erscheint dein Plugin dann in der Plugin-Übersicht.
Ein grüner Balken unter der Plugin-Kachel zeigt an, dass das Plugin erfolgreich gestartet wurde.
Erscheint stattdessen ein roter Balken, konnte das Plugin nicht korrekt gestartet werden.
Ist kein Balken zu sehen, ist dein Plugin zwar installiert, aber inaktiv.

Plugin-Logs prüfen
Sollte sich dein Plugin nicht soverhalten, wie du es erwartest hast, prüfe die Logs.
Hierzu öffnest du zunächst die Plugin-Kachel. Klicke anschließend unten rechts auf
Logs anzeigen
Hier findest du sämtliche Ausgaben deines Plugins.
Gerade während der Entwicklung solltest du diese Logs regelmäßig kontrollieren.
Sie liefern häufig wesentlich detailliertere Informationen als die HCU-Installationsmeldung selbst, die leider aktuell noch sehr wenig aussagekraft hat.

Typische Fehler nach der Installation
Sollte dein Plugin nach der Installation nicht starten, liegen die Ursachen häufig an einer der folgenden Stellen:
- falsche Plugin-ID in der Dockerfile
- falscher ENTRYPOINT
- Startdatei oder andere essentielle Dateien wurden nicht per
COPYin das Image übernommen - Syntaxfehler im Programmcode (daher solltest du immer erst lokal testen)
- Dateien befinden sich an einem anderen Pfad als im ENTRYPOINT angegeben
Kontrolliere diese Punkte zuerst, bevor du umfangreiche Änderungen am Code vornimmst.
Herzlichen Glückwunsch!
Du hast dein erstes Homematic IP Plugin erfolgreich entwickelt, getestet und als Installationspaket erstellt.
Im nächsten und letzten Teil beschäftigen wir uns mit bewährten Vorgehensweisen bei der Plugin-Entwicklung, häufigen Fehlerquellen sowie der Veröffentlichung deines Plugins im HCU Plugins Community Store, damit auch andere Nutzer deine Entwicklung entdecken und verwenden können.
HCU Plugins