Adapter-Entwicklung
Auf dem Weg zum eigenen/neuen Adapter gibt es viele Werkzeuge, welche das Entwickler-Leben leichter machen und sehr schnell erste Ergebnisse ermöglichen!
Eine Sammlung von Tools, Links und Informationen ist im ioBroker Dev-Portal zu finden (mit GitHub-Account einloggen!).
Um einen Überblick zu bekommen, wie die Adapter-Entwicklung ablaufen kann, habe ich folgenden Video-Leitfaden (zusätzlich zu dieser Seite) erstellt:
Voraussetzungen
Ein Linux-System, auf welchem noch kein ioBroker installiert wurde (z.B. Debian oder Ubuntu)
Grundlegende Kenntnisse in JavaScript (und optional TypeScript)
Grundwissen über git und npm
Erfahrung mit dem ioBroker und der Arbeitsweise (Objekte, Zustände, Datentypen, Rollen, …)
Neuer Adapter
Warnung
Bevor ein neuer Adapter entwickelt wird, sollte auf GitHub und im ioBroker-Forum geprüft werden, ob dieser nicht schon existiert oder bereits angefangen wurde.
Offene Anfragen für Adapter sind hier zu finden.
Wenn eine neuer Adapter entwickelt werden soll, sollte das Grundgerüst mit Hilfe des Create-Adapter-Tools durchgeführt werden. Dieses Tool erstellt auf Basis eines Templates ein komplett neues Projekt, mit welchem man direkt durchstarten kann. Das spart viel Zeit, welche dann in den Adapter fließen kann!
Um einen neuen Adapter zu erstellen, führe folgenden Befehl aus:
npx @iobroker/create-adapter
Wenn das Programm ausgeführt wird, werden einige Fragen gestellt, wie man gerne arbeiten möchte. Das Ergebnis sieht beispielsweise so aus:
Need to install the following packages:
@iobroker/create-adapter
Ok to proceed? (y) y
=====================================================
Welcome to the ioBroker adapter creator v2.1.1!
=====================================================
You can cancel at any point by pressing Ctrl+C.
Let's get started with a few questions about your project!
✔ Please enter the name of your project: · gira-iot
✔ Which title should be shown in the admin UI? · Gira IoT
✔ Please enter a short description: · Integrate your Gira X1 or HomeServer
✔ Enter some keywords (separated by commas) to describe your project: · gira,x1,homeserver,iot
✔ If you have any contributors, please enter their names (seperated by commas): ·
Nice! Let's get technical...
✔ How detailed do you want to configure your project? · yes
✔ Which features should your project contain? · adapter
✔ Which additional features should be available in the admin? · No items were selected
✔ Which category does your adapter fall into? · iot-systems
✔ When should the adapter be started? · daemon
✔ From where will the adapter get its data? · local
✔ How will the adapter receive its data? · push
✔ Do you want to indicate the connection state? · yes
Some more questions about the source code...
✔ Which language do you want to use to code the adapter? · JavaScript
✔ Use React for the Admin UI? · no
✔ Which of the following tools do you want to use? · ESLint, type checking
✔ Would you like to automate new releases with one simple command? · yes
✔ Would you like to use dev-server to develop and test your code with a simple command line tool? · yes
✔ Please choose the port number on which dev-server should present the admin web interface: · 8081
✔ Do you prefer tab or space indentation? · Space (4)
✔ Do you prefer double or single quotes? · single
✔ How should the main adapter file be structured? · yes
Almost done! Just a few administrative details...
✔ Please enter your name (or nickname): · Matthias Kleine
✔ What's your name/org on GitHub? · klein0r
✔ What's your email address? · info@haus-automatisierung.com
✔ Which protocol should be used for the repo URL? · SSH
✔ Initialize the GitHub repo automatically? · yes
✔ How should your default Git branch be called? · main
✔ Which license should be used for your project? · MIT License
✔ Do you want to receive regular dependency updates through Pull Requests? · yes
Danach werden automatisch alle nötigen Dateien erstellt und es kann direkt mit der Entwicklung gestartet werden!
Natürlich könnte man auch alle Dateien manuell anlegen - aber das ist nicht zu empfehlen und bedeutet sehr viel mehr Arbeit!
Dev-Server
Um das neue Projekt lokal auszuführen, kann der sog. Dev-Server verwendet werden. Dieser legt in einem Unterverzeichnis des aktuellen Projektes eine ioBroker-Installation an und kann diese bei bedarf starten. So hat man für jeden Adapter eine eigene Entwicklungsumgebung. Das schöne ist: JavaScript-Dateien werden automatisch überwacht und ein Neustart der Adapter-Instanz durchgeführt, sobald sich etwas ändert:
GitHub Repository
Tipp
Es ist empfehlenswert, den Quellcode für den Adapter auf GitHub zu veröffentlichen. Natürlich würden andere Plattformen wie Amazon Code Commit oder Bitbucket genauso funktionieren, allerdings arbeitet der Großteil der ioBroker-Community mit GitHub. Und darauf ist das komplett ioBroker-Universrum ausgelegt.
Wichtig ist, dass man den Namenskonventionen für ein neues Repository folgt (darum kümmert sich der Adapter-Creator ebenfalls). Das Repository heißt dann ioBroker.<deinadapter>. Auf Groß- und Kleinschreibung achten! Das B von ioBroker wird im Repository-Namen groß geschrieben! Der Rest wird klein geschrieben!
Gültige Namen für ein neues Repository wären also zum Beispiel:
ioBroker.adminioBroker.javascriptioBroker.luftdatenioBroker.octoprint
Warnung
Es ist darauf zu achten, dass der gewählte Name für einen Adapter noch nicht vergeben ist! Die oben genannten Beispiele sind alle schon vorhanden. Ansonsten kann der neue Adapter später nicht veröffentlicht werden bzw. in die Adapter-Liste mit aufgenommen werden.
Wichtige Themen / Stichworte für die Adapter-Entwicklung (Google-Suche nutzen!):
git commitgit pushgit remote/ Remote RepositoriesBranches und Tags
SSH Key Authentication / SSH Key Agent / SSH Key Forwarding
Übersetzungen
Generell ist es sinnvoll, einen neuen Adapter (direkt von Anfang an) in mehrere Sprachen zu übersetzen. Die „Basis-Sprache“ ist dabei Englisch. Von dieser wird in andere Sprachen übersetzt.
Bemerkung
Generell gab es schon viele Ansätze und Werkzeuge, welche Dir bei Übersetzungen im ioBroker helfen sollten. Angefangen von Webseiten, bis zu irgendwelchen gulp-Scripts. Vieles davon existiert heute noch in den meisten Adaptern.
Der aktuellste Weg ist das Paket - Adapter-Dev (npm i --save-dev @iobroker/adapter-dev). Anstatt also Dateien in zig unterschiedlichen Versionen hin und her zu kopieren, sollte dieses Paket verwendet werden!
Alternativ, gibt es vom ioBroker-Team ein Tool, welches einen Englischen Text in alle andere Sprachen übersetzt und im richtigen Format für den ioBroker zurückliefert (JSON).
Gibst man zum Beispiel today ein, liefert das Programm die folgenden Übersetzungen im JSON-Format:
{
"today": {
"en": "today",
"de": "heute",
"ru": "сегодня",
"pt": "hoje",
"nl": "vandaag",
"fr": "aujourd'hui",
"it": "oggi",
"es": "hoy dia",
"pl": "dzisiaj",
"uk": "сьогодні",
"zh-cn": "今天"
}
}
Diese Informationen können direkt im Adapter verwendet werden.
Es ist darauf zu achten, dass ALLE Texte übersetzt sind (inklusive Objekt-Namen).
Bemerkung
Leider ist es so, dass (wie üblich) die erstellen Übersetzungen nicht immer einwandfrei sind. Häufig ist z.B. die Deutsche Übersetzung falsch oder ergibt keinen Sinn. Eine manuelle Kontrolle ist in jedem Fall sinnvoll. Ist die Übersetzung von Englisch zu Deutsch korrekt, dann passt es höchstwahrscheinlich auch in den anderen Sprachen.
Alle Texte müssen in die folgenden Sprachen übersetzt werden:
Englisch (en)
Deutsch (de)
Alle Text sollten zusätzlich auch diese Sprachen übersetzt werden:
Russisch (ru)
Portugisisch (pt)
Niederländisch (nl)
Französisch (fr)
Italienisch (it)
Spanisch (es)
Polnisch (pl)
Ukrainisch (uk)
Chinesisch (zh-cn)
npm
Sobald es einen „Release“ des neuen Adapters gibt, wird eine Versionsnummer vergeben. Dabei ist auf semantische Versionierung zu achten!
Die erste Version des Adapters wird also höchstwahrscheinlich die 0.0.1 sein.
Generell werden nodejs-Pakete über npm veröffentlicht. Dieser Paketmanager kümmert sich um deine Abhängigkeiten im Projekt (package.json) und von dort werden auch die Pakete bei der Installation des Adapters geladen.
Tipp
Es gibt im Adapter-Creator-Tool (siehe oben) verschiedene Scripts, welche Dir automatisch beim Erstellen eines neuen Releases das Paket auf npmjs.com veröffentlichen. Dafür musst Du ein Token erstellen, welches im GitHub-Repository hinterlegt wird.
Folgende Themen sind wichtig (Schlüsselwörter für Google):
semantische Versionierung
package.jsonnpm installpublish von neuen npm Paketen
Bemerkung
Generell haben GitHub und npmjs erstmal nichts miteinadner zu tun. Das sind zwei unterschiedliche Plattformen. GitHub hilft bei der Entwicklung und Issue-Tracking, während npm das fertige Pakete vorhält und an die Nutzer ausliefert. Über diverse Integrationsmöglichen greifen diese beiden Plattformen aber ineinander und vereinfachen den Workflow!
Der Name des Paketes für npm unterscheidet sich dabei vom Namen des Repository! Hier wird das „B“ in ioBroker nicht mehr groß geschrieben! Der Paket-Name enthält also nur Kleinbuchstaben.
Gültige Namen für ein neues npm Paket wären also beispielsweise:
iobroker.adminiobroker.javascriptiobroker.luftdateniobroker.octoprint
Sollte der Adapter mit dem oben genannten Tool erstellt worden sein, wird dies bereits automatisch berücksichtigt!
Adapter prüfen
Für einen Adapter gibt es eine Liste an Regeln, welche die Qualität der Adapter erhöhen sollen. Entspricht ein Adapter nicht diesen Anforderungen, wird er eventuell nicht in die (offizielle) Liste der verfügbaren Adapter aufgenommen!
Diese Regeln einzuhalten ist relativ einfach, da der ioBroker Adapter Checker genau sagt, was noch getan werden muss bzw. falsch läuft.
Sobald also eine erste Version von einem Adapter fertig ist, alles ins GitHub-Repository gepusht wurde und ein Paket auf npmjs.com veröffentlich wurde, kann der Adapter-Checker gestartet werden:
Dort wird die URL von einem GitHub-Repository eingefügt.
Wichtig ist, dass alle Haken grün sind und möglichst keine Warnungen ausgegeben werden.
Tipp
Es ist sinnvoll, schon während der Entwicklung regelmäßig zu prüfen, ob ein Adapter den Anforderungen entspricht.
Generell gilt, dass auch hier die Entwicklung weiter geht. Es werden regelmäßig mehr Prüfungen hinzugefügt oder andere entfernt. Wenn ein Adapter also heute alle Tests besteht, muss das bei der nächsten Version nicht mehr unbedingt so sein. Der Repository-Checker wird in unregelmäßigen Abständen Issues in deinem Repository anlegen, falls etwas nicht stimmen sollte.
Das Repository vom Adapter-Checker kann mit neuen Regeln erweitert werden (siehe index.js).
Adapter veröffentlichen
Soll der neue Adapter nun auch anderen zur Verfügung gestellt werden, sollte dieser von erfahrenen Nutzerb im ioBroker Forum getestet werden. Dazu kann ein neuer Foren-Beitrag mit der Bitte um einen Test erstellt werden.
Danach kann ein Pull-Request im GitHub Repository (ioBroker.repositories) erstellt werden, mit welchem der neue Adapter dort hinzugefügt wird. Mehr Details hier: Repositories.
Bemerkung
Adapter können abgelehnt werden, wenn nicht alle Adapter-Checks (siehe oben) erfüllt sind.