ioBroker Adapter-Entwicklung mit KI — Minimal-Guide

Du willst einen ioBroker-Adapter mit ChatGPT, Claude, Copilot & Co. bauen? Gut — aber halt dich an die Spielregeln. KI-generierter Code ist kein Freifahrtschein, die etablierten Prozesse zu ignorieren.

---

Vor Projekt Beginn

Prüfen ob bereits ein identischer oder ähnlicher Adapter existiert der die Bedürfnisse erfüllt bzw. um die fehlende funktion erweitert werden kann. Wenn bereits ein Adapter existiert sollte immer zuerst dazu beigetragen werden, sofern möglich. Die zu prüfenden Quellen sind www.github.com, forum.iobroker.net und www.npmjs.com. Außerdem lohnt sich ein Blick in die Adapter requests unter https://github.com/ioBroker/AdapterRequests/issues

1. Projekt RICHTIG starten

NICHT: Code von einem anderen Adapter kopieren und umbauen.
NICHT: Die KI bitten, ein komplettes Adapter-Projekt von Null zu generieren.

STATTDESSEN: Immer den offiziellen Adapter Creator verwenden:

npx @iobroker/create-adapter@latest

Der Creator stellt alle nötigen Fragen (Name, Typ, Sprache, Lizenz, Testing) und erzeugt eine korrekte Projektstruktur mit:

• Aktuelle io-package.json mit allen Pflichtfeldern
• Funktionierende GitHub Actions für CI/Testing
• Admin-UI (JSONConfig)
• Korrekte package.json
• ESLint-Konfiguration

Warum? Die KI kennt oft veraltete Projektstrukturen. Der Creator liefert immer die aktuelle Version.

---

2. Was die KI NICHT wissen kann

KI-Modelle haben häufig veraltetes oder falsches Wissen über ioBroker. Prüfe IMMER:

Thema	Häufiger KI-Fehler	Richtig
Admin-UI	Generiert admin/index_m.html (Admin2)	JSONConfig verwenden (jsonConfig.json5)
Rollen	Setzt role: "state" überall	Korrekte State Roles verwenden
Objekte	Erstellt States unter States	device → channel → state Hierarchie einhalten
Timer	Verwendet setTimeout/setInterval von Node.js	adapter.setTimeout/adapter.setInterval verwenden
Prozess-Exit	Verwendet process.exit()	adapter.terminate() verwenden
Passwörter	Speichert Passwörter im Klartext	encryptedNative + protectedNative in io-package.json
setObject	Überschreibt bestehende Objekte	setObjectNotExists oder extendObject verwenden
ack-Flag	Ignoriert ack komplett	ack=true für finale Werte, ack=false für Kommandos
Sprache	Erstellt deutsches README.md / logging	README.md muss in englisch sein, logs müssen englisch sein sofern nicht 1:1 von externer Quelle
Objekt-Ids	keine Filterung	Objekt-Ids dürfen keine Sonderzeichen, Spaces etc. enthalten. Optimal sollten diese nur A-Za-z0-9-_ enthalten
Objekte	Zischenobjekt fehlen	Es müssen alle Objecte im Baum expizit angelegt werden, also bei a.b.c sowohl a als auch b und c
Sprachen	direkte Sprachkodierung in jsonConfig	es sollte die i18n Struktur verwendet werden
Testing	kein standard testing	standard Testumgebung (test-and-release.yml workflow verwenden (zusätzliche Tests ind natürlich ok)

---

3. Pflicht-Checkliste vor dem Einreichen

Bevor du deinen Adapter ins Repository einreichst, müssen folgende Punkte erfüllt sein:

• Adapter Creator verwendet (nicht von Hand zusammenkopiert)
• Adapter Checker durchlaufen und alle Fehler behoben: https://www.iobroker.dev/adapter-check
• GitHub-Repo heißt ioBroker.<adaptername> (großes B)
• package.json Name ist lowercase (iobroker.<adaptername>)
• README.md auf Englisch vorhanden mit Beschreibung + Link zur Geräte-/Hersteller-Website
• Lizenz in io-package.json, README.md UND als LICENSE-Datei
• GitHub Actions für Adapter-Testing eingerichtet (Package + Integration Tests)
• io-package.json: type, connectionType, dataSource, authors gesetzt
• State Roles korrekt (nicht einfach "state" überall)
• npm veröffentlicht + iobroker-Organisation als Owner hinzugefügt
• Unload räumt ALLE Ressourcen auf (Timer, Connections, Ports)
• Compact Mode getestet (Start → Lauf → Stop → Neustart)
• info.connection State implementiert (wenn externe Verbindung)
• Unbenutzte Verzeichnisse (www, widgets, docs) entfernt
• Port-Attribut heißt port, IP-Attribut heißt ip (nicht bind)

---

4. KI richtig einsetzen

✅ Gute Verwendung

• Logik implementieren: Geräte-Kommunikation, Parsing, Datenverarbeitung
• Tests schreiben: Unit-Tests für deine Adapter-Logik
• README schreiben: Dokumentation formulieren lassen
• Fehler debuggen: Stacktraces und Logs analysieren

❌ Schlechte Verwendung

• Projektstruktur generieren lassen → Adapter Creator verwenden
• io-package.json generieren lassen → Enthält fast immer veraltete/falsche Felder
• Blind übernehmen → KI-Code IMMER reviewen und verstehen
• Admin-UI generieren lassen → JSONConfig-Doku lesen und selbst bauen

💡 Tipp: KI mit Kontext füttern

Wenn du die KI für Adapter-Code nutzt, gib ihr die relevante Doku als Kontext mit:

• Die offizielle Adapter-Referenz
• Die Object-Schema-Doku
• Die State Roles
• Einen gut gepflegten Referenz-Adapter (z.B. ioBroker.denon)
• ioBroker copilot template verwenden (https://github.com/DrozmotiX/ioBroker-Copilot-Instructions)

---

5. Einreichungs-Prozess

Ins Beta-Repository (Latest):

1. Adapter Checker bestanden ✅
2. über iobroker.dev → Login → Adapter → Manage → "ADD TO LATEST" Oder
3. Fork von ioBroker.repositories
4. npm run addToLatest -- --name <name> --type <type>
5. PR erstellen

Ins Stable-Repository:

1. Adapter muss bereits im Beta-Repository sein
2. Forum-Thread zum Testen erstellen: Forum Tester-Bereich
3. User-Feedback sammeln
4. Discovery-Funktion implementieren (wenn Gerät automatisch findbar)
5. PR für Stable erstellen

---

6. Häufige Fehler bei KI-generierten Adaptern

1. Veraltete Boilerplate: KI kopiert Code-Muster von vor 3+ Jahren. Adapter Creator löst das.
2. Fehlende Ressourcen-Bereinigung: unload wird vergessen oder unvollständig → bricht Compact Mode.
3. Falsche Objektstruktur: States unter States verschachtelt statt device/channel/state.
4. Generische Rollen: Alles ist role: "state" → wird beim Review abgelehnt.
5. Keine Tests: KI schreibt selten automatisch GitHub Actions ein. Der Creator macht das.
6. package.json von installiertem Adapter kopiert: Enthält installedFrom und andere Felder die nicht reingehören.
7. Scheduling-Bibliotheken für einfache Intervalle: Overkill + alle User pollen gleichzeitig → DoS auf externe APIs.
8. Kein info.connection State: Admin zeigt dann keinen Verbindungsstatus (grün/gelb/rot).

---

7. Wichtige Links

Ressource	URL
iobroker.dev	https://www.iobroker.dev/
Adapter Creator	npx @iobroker/create-adapter@latest
Adapter Checker	https://www.iobroker.dev/adapter-check
Repository Requirements	https://github.com/ioBroker/ioBroker.repositories/blob/master/README.md
Adapter-Referenz	https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/adapterref.md
Object Schema	https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/objectsschema.md
State Roles	https://github.com/ioBroker/ioBroker/blob/master/doc/STATE_ROLES.md
Übersetzer	https://translator.iobroker.in/
Forum (Tester)	https://forum.iobroker.net/category/91/tester
YouTube (deutsch)	https://www.youtube.com/watch?v=7N8fsJcAdlE

---

TL;DR: npx @iobroker/create-adapter@latest → Code schreiben → Adapter Checker → Fixen → Einreichen. Die KI hilft beim Code, aber die Projektstruktur und Prozesse kommen von den offiziellen Tools.