So entwickelst du dein eigenes Plugin für die Homematic IP HCU-1 [Teil 2: Projekt vorbereiten und erstes Plugin programmieren]
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.

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.
HCU Plugins