• Startseite
  • Plugins
    • Basisstationen
      • HCU-1 Plugins
      • CCU3 Plugins
    • Plugins herunterladen
      • Licht
      • Garten
      • Heizung und Kühlung
      • Verdunkelung
      • Solar und Energie
      • Luft und Umwelt
      • Zutrittssteuerung
      • Sicherheit
      • Alle Plugins
    • Hilfe für Nutzer
      • Wie installiere ich HCU-1-Plugins?
    • Für Entwickler
      • Plugins für die HCU-1 entwickeln
  • Blog
  • Anmelden
  • Menü Menü
Du bist hier: Startseite1 / Blog2 / Für Entwickler3 / So entwickelst du dein eigenes Plugin für die Homematic IP HCU-1 [Teil ...
Homematic IP HCU Plugins entwickeln - Teil 3HCU Plugins

So entwickelst du dein eigenes Plugin für die Homematic IP HCU-1 [Teil 3: Plugin testen, exportieren und installieren]

31. Juli 2026/in Für Entwickler

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.

Die HCU-Plugin-Abhaengigkeiten über Visual Studio und das Terminal installieren

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.

Screenshot der Oberfläche, um ein eigenes Plugin auf der Homematic IP HCU-1 zu installieren

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.

Blick in die Logs eines Homematic IP HCU Plugins

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 COPY in 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.

Eintrag teilen
  • Facebook Facebook Teilen auf Facebook
  • Square-x-twitter Square-x-twitter Share on X
  • Whatsapp Whatsapp Teilen auf WhatsApp
  • Pinterest Pinterest Teilen auf Pinterest
  • Linkedin Linkedin Teilen auf LinkedIn
  • Reddit Reddit Teilen auf Reddit
  • Mail Mail Per E-Mail teilen
https://hcu-plugins.de/wp-content/uploads/2026/07/Homematic-IP-HCU-Plugins-Entwickeln-Beitragsbild-Teil-3.jpg 1333 2000 kevinschipper https://hcu-plugins.de/wp-content/uploads/2026/07/HCU-Plugins-Logo-Icon-blau.svg kevinschipper2026-07-31 19:21:112026-09-05 19:32:38So entwickelst du dein eigenes Plugin für die Homematic IP HCU-1 [Teil 3: Plugin testen, exportieren und installieren]

Aus dem Inhalt

Archive

HCU Plugins - Community Store

Nützliche Links

Homematic IP
eQ-3
ELV
Homematic Forum
Homematic IP Connect API

HCU Plugins für Homematic IP

HCU Plugins ist die Community für kostenfreie Plugins der Homematic IP HCU-1 und CCU3. Entdecke neue Erweiterungen, folge Entwicklern und finde hilfreiche Informationen rund um Plugins für dein Smart Home.

Unterstützt von

Markenhinweis: HCU Plugins ist eine unabhängige Community-Plattform und steht in keiner Verbindung zur eQ-3 AG. Homematic IP, HCU-1, CCU3 sowie weitere genannte Marken sind Eigentum ihrer jeweiligen Inhaber und werden ausschließlich zur Beschreibung der Kompatibilität und des Verwendungszwecks verwendet.

© Copyright - HCU Plugins
  • Kontakt
  • Impressum
  • Nutzungsbedingungen
  • Datenschutzerklärung
Nach oben scrollen Nach oben scrollen Nach oben scrollen
Barrierefreiheitsanpassungen

Präsentiert von OneTap

Wie lange möchten Sie die Werkzeugleiste ausblenden?
Dauer des Ausblendens der Werkzeugleiste
Wählen Sie Ihr Barrierefreiheitsprofil aus
Modus für Sehbehinderte
Verbessert das Erscheinungsbild der Website
Profil für Anfallsicherheit
Entfernt Blitze und reduziert die Farbe
ADHS-freundlicher Modus
Fokussiertes Browsen, ablenkungsfrei
Blindmodus
Reduziert Ablenkungen, verbessert die Konzentration
Sicherer Modus bei Epilepsie
Dimmt die Farben und stoppt das Blinken
Inhaltsmodule
Schriftgröße

Standard

Zeilenhöhe

Standard

Farbmodule
Orientierungsmodule