• 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 2HCU Plugins

So entwickelst du dein eigenes Plugin für die Homematic IP HCU-1 [Teil 2: Projekt vorbereiten und erstes Plugin programmieren]

24. Juli 2026/in Für Entwickler

Im ersten Teil dieser Anleitung hast du die Entwicklungsumgebung eingerichtet, den Entwicklermodus aktiviert und deinen Auth-Token erstellt. Jetzt geht es an den eigentlichen Start der Plugin-Entwicklung.

In diesem Teil richtest du dein Projekt ein, passt das Beispiel-Plugin an und erfährst, wie deine eigenen Dateien in das Plugin eingebunden werden. Anschließend kannst du mit der eigentlichen Programmierung beginnen.


Plugin-Projekt anlegen

Erstelle zunächst einen neuen Ordner für dein Plugin, beispielsweise:

mein-hcu-plugin

Öffne diesen Ordner anschließend mit Visual Studio Code. Hierfür öffnest du das Programm und klickst in der linken Spalte auf das Datei-Symbol [Explorer]. Klicke dann auf “Open Folder” und wähle den erstellten Ordner.

Auth-Token speichern

Erstelle im Hauptverzeichnis deines Plugins eine neue Datei mit dem Namen

authtoken.txt

Kopiere anschließend den im ersten Teil erzeugten Auth-Token in diese Datei und speichere sie.

Die Projektstruktur sieht zunächst beispielsweise so aus:

mein-hcu-plugin
│
└── authtoken.txt

Beispiel-Plugin herunterladen

Die Homematic IP stellt fertige Beispielprojekte für Node.js und Java bereit.

Repository:

https://github.com/homematicip/connect-api/tree/main/examples

Lade das Beispielprojekt der gewünschten Programmiersprache herunter und entpacke den Inhalt direkt in deinen Plugin-Ordner. Denk daran: Node.JS ist einfacher für Beginner, Java eher für Experten.

Danach sollte sich unter anderem eine Dockerfile im Hauptverzeichnis befinden.

Die Struktur könnte anschließend beispielsweise so aussehen:

mein-hcu-plugin
│
├── Dockerfile
├── authtoken.txt
├── package.json
├── node-example.js
└── ...

Dockerfile anpassen

Die Dockerfile beschreibt, wie später dein Plugin für die HCU-1 erstellt wird.

Damit dein Plugin korrekt erkannt wird, musst du einige Einträge anpassen.

Plugin-Metadaten ändern

Suche zunächst nach folgendem LABEL:

LABEL de.eq3.hmip.plugin.metadata='...'

Passe dort mindestens folgende Werte an:

  • pluginId: Einzigartige Plugin-ID für dein Plugin. Kann frei vergeben werden.
  • friendlyName
    • de: deutscher Plugin-Name dargestellt in der HCU Web
    • en: englischer Plugin-Name dargestellt in der HCU Web
  • version: Versionsnummer bestehend aus Zahlen und Punkten. Übrigens: Konvention ist: 1.2.3 (1 = Komplette Überarbeitung, 2 = Funktionsupdate, 3 = Patch/Fehlerbehebung)
  • description
    • de: deutsche Beschreibung deines Plugins, kann frei vergeben werden
    • en: englische Beschreibung deines Plugins, kann frei vergeben werden

Achte darauf, dass die Plugin-ID und die Friendly Names exakt den Werten entsprechen, die du beim Erzeugen des Auth-Tokens verwendet hast.

Bereits kleine Abweichungen können dazu führen, dass dein Plugin später nicht korrekt funktioniert.

Screenshot des Meta-Block des Nanoleaf-Connectors
So sieht beispielsweise der Meta-Block des Nanoleaf-Connectors aus.

ENTRYPOINT anpassen

Weiter unten findest du den ENTRYPOINT.

Im Beispielprojekt sieht dieser beispielsweise so aus:

ENTRYPOINT ["node", "node-example.js", "de.doe.jane.plugin.example.node", "host.containers.internal", "/TOKEN"]

Passe ihn nun an dein Plugin an.

Dabei solltest du insbesondere folgende Werte ändern:

  • den Dateinamen deiner Startdatei
  • die Plugin-ID
  • den Pfad zur Auth-Token-Datei: In der HCU-1 ist das /TOKEN beim Start des Plugins

Beispielsweise:

ENTRYPOINT ["node", "main.js", "de.mein-name.plugin.mein-hcu-plugin", "host.containers.internal", "/TOKEN"]

Wenn deine Hauptdatei später anders als “main.js” heißt, musst du den Dateinamen hier ebenfalls anpassen.

Eigene Dateien kopieren

Beim Erstellen des Plugins werden nur Dateien übernommen, die in der Dockerfile ausdrücklich kopiert werden.

Dafür werden die COPY-Anweisungen verwendet.

Eine sinnvolle Projektstruktur könnte beispielsweise so aussehen:

mein-hcu-plugin
│
├── Dockerfile
├── authtoken.txt
└── src
    ├── main.js
    ├── api.js
    ├── devices.js
    └── helpers.js

Nun ergänzt du beispielsweise:

COPY src ./src

Dadurch wird der komplette Ordner src in dein Plugin übernommen.

Wichtig:
Die Datei authtoken.txt darf NICHT mit COPY eingebunden werden. Sie wird ausschließlich während der lokalen Entwicklung benötigt und gehört nicht in das fertige Plugin.

Die Hauptdatei festlegen

Lege nun deine eigentliche Startdatei an.

Empfehlenswert ist beispielsweise

src/main.js

Anschließend muss der ENTRYPOINT entsprechend angepasst werden:

ENTRYPOINT ["node", "src/main.js", "de.mein-name.plugin.mein-hcu-plugin", "host.containers.internal", "/TOKEN"]

So bleibt dein Projekt auch bei größeren Plugins übersichtlich.


Jetzt beginnt die eigentliche Entwicklung

Nun kannst du dein Plugin programmieren.

Wie du dein Projekt strukturierst, bleibt dir überlassen.

Für größere Plugins empfiehlt sich eine Aufteilung in mehrere Dateien, beispielsweise:

src
│
├── main.js
├── api.js
├── settings.js
├── devices.js
├── websocket.js
├── logger.js
└── utils.js

Dadurch bleiben einzelne Komponenten besser wartbar und wiederverwendbar. Du kannst beispielsweise auch weitere Ordner im Stammverzeichnis anlegen, um andere Dateitypen zu gruppieren (JSON, Sprachdateien, etc.). Vergiss dann aber nicht, diese auch über die Dockerfile auf die HCU-1 kopieren zu lassen.


Best Practices

Während der Entwicklung haben sich einige Vorgehensweisen bewährt.

Verwende sprechende Plugin-IDs

Nutze möglichst eine eindeutige Plugin-ID.

Ein gutes Beispiel wäre:

de.max.mustermann.plugin.mein-plugin

Dadurch sinkt die Wahrscheinlichkeit von Konflikten mit anderen Plugins erheblich.

Arbeite mit Versionsnummern

Erhöhe deine Versionsnummer bei jeder veröffentlichten Änderung.

So erkennen Nutzer und Plugin-Updater sofort, ob eine neue Version verfügbar ist.

Trenne Logik und Kommunikation

Lege API-Aufrufe, Geräteverwaltung und Einstellungen möglichst in getrennten Dateien ab.

Dadurch bleibt dein Plugin auch bei wachsendem Umfang übersichtlich und modular.

Speichere Daten dauerhaft

Eigene Konfigurationen oder erzeugte Daten solltest du im dafür vorgesehenen Datenverzeichnis speichern.

mein-hcu-plugin
│
└── data

Dadurch bleiben sie auch nach Updates oder einem Neustart des Plugins erhalten.

Nächster Schritt

Dein Plugin-Projekt ist nun vollständig eingerichtet.

Im nächsten Teil testen wir dein Plugin erstmals lokal mit Node.js, beheben typische Fehler und erstellen anschließend das fertige .tar.gz-Plugin, das du direkt auf deiner Homematic IP HCU-1 installieren kannst. Du hast den ersten Teil noch nicht gelesen? Dann kannst du hier zurückspringen.

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-2.jpg 1333 2000 kevinschipper https://hcu-plugins.de/wp-content/uploads/2026/07/HCU-Plugins-Logo-Icon-blau.svg kevinschipper2026-07-24 20:32:332026-09-05 19:32:12So entwickelst du dein eigenes Plugin für die Homematic IP HCU-1 [Teil 2: Projekt vorbereiten und erstes Plugin programmieren]

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