Seminar ioBroker – Adapterentwicklung mit TypeScript

Eigene Adapter werden benötigt, wenn Geräte, Fachsysteme oder Dienste nicht durch vorhandene Integrationen abgedeckt sind oder ein organisationsspezifisches Datenmodell erforderlich ist. Das Seminar führt von der fachlichen Schnittstellenanalyse bis zu einem installierbaren und getesteten Paket.

Die Entwicklung erfolgt mit TypeScript, klarer Trennung von Konfiguration, Laufzeitlogik und Datenmodell. Jeder Entwicklungsschritt wird durch Tests, Protokollierung und eine definierte Abnahme abgesichert.

Inhaltsverzeichnis

• Lernziele
• Schrittweise Seminarinhalte
• Tag 1: Architektur, Entwicklungsumgebung und Projektgerüst
• Tag 2: Objektmodell, Zustände und Ereignisse
• Tag 3: Konfiguration und externe Schnittstellen
• Tag 4: Robustheit, Sicherheit und Qualitätssicherung
• Tag 5: Paketierung, Abnahme und Wartung
• Praxisübungen und Laborszenarien
• Zielgruppe und Voraussetzungen
• Didaktik und Arbeitsweise

Lernziele

• Adapterlebenszyklus, Projektstruktur und zentrale Metadaten fachlich richtig einsetzen.
• Objekte und Zustände stabil modellieren, aktualisieren, abonnieren und bereinigen.
• Externe Geräte oder Dienste mit Zeitüberschreitungen, Wiederholungen und Fehlerklassen anbinden.
• Konfiguration, Berechtigungen, Geheimnisse und Protokollierung sicher gestalten.
• Automatisierte Tests, Paketierung, Versionsführung und Wartungsprozesse etablieren.

Schrittweise Seminarinhalte

Tag 1: Architektur, Entwicklungsumgebung und Projektgerüst

1. Schritt 1: Integrationsziel, Kommunikationsrichtung, Datenmengen, Schreibrechte und Ausfallverhalten spezifizieren.
2. Schritt 2: Entwicklungsumgebung, TypeScript-Werkzeuge und lokales Testsystem reproduzierbar vorbereiten.
3. Schritt 3: Ein Adapterprojekt mit standardisierter Struktur erzeugen und die Metadaten des Pakets prüfen.
4. Schritt 4: Start-, Bereitschafts-, Entlade- und Fehlerpfade des Adapterlebenszyklus implementieren.
5. Schritt 5: Protokollstufen, Konfigurationszugriff und erste automatisierte Startprüfung einrichten.

Tag 2: Objektmodell, Zustände und Ereignisse

1. Schritt 1: Ein konsistentes Namespace-, Kanal-, Geräte- und Datenpunktmodell entwerfen.
2. Schritt 2: Objekte idempotent anlegen, aktualisieren und bei Modelländerungen kontrolliert migrieren.
3. Schritt 3: Zustände mit Rollen, Typen, Einheiten, Schreibrechten, Bestätigung und Zeitstempeln behandeln.
4. Schritt 4: Änderungsereignisse abonnieren und Rückkopplungen zwischen Gerät und Plattform vermeiden.
5. Schritt 5: Grenzwerte, fehlende Werte und ungültige Daten mit klaren Qualitätsregeln verarbeiten.

Tag 3: Konfiguration und externe Schnittstellen

1. Schritt 1: Administrationsparameter nach Pflichtwerten, Standardwerten und Validierungsregeln strukturieren.
2. Schritt 2: Zugangsdaten und sensible Parameter so behandeln, dass sie nicht in Protokollen oder Testdaten erscheinen.
3. Schritt 3: Eine externe Schnittstelle mit Verbindungsaufbau, Authentisierung, Zeitüberschreitung und Wiederholungslogik integrieren.
4. Schritt 4: Polling und ereignisbasierte Aktualisierung hinsichtlich Last, Aktualität und Rate Limits abwägen.
5. Schritt 5: Verbindungsstatus und Diagnoseinformationen als verständliche Betriebszustände bereitstellen.

Tag 4: Robustheit, Sicherheit und Qualitätssicherung

1. Schritt 1: Fehlerklassen für Konfiguration, Netzwerk, Protokoll, Daten und Plattform definieren.
2. Schritt 2: Wiederverbindung, Backoff, kontrolliertes Beenden und Ressourcenfreigabe implementieren.
3. Schritt 3: Einheiten-, Integrations- und Lebenszyklustests für Normal-, Rand- und Fehlerfälle erstellen.
4. Schritt 4: Eingaben validieren, Abhängigkeiten prüfen und unnötige Berechtigungen vermeiden.
5. Schritt 5: Protokolle und Metriken so gestalten, dass Supportfälle ohne unnötige Datenoffenlegung analysierbar bleiben.

Tag 5: Paketierung, Abnahme und Wartung

1. Schritt 1: Versionsschema, Änderungsdokumentation und kompatible Datenmodelländerungen planen.
2. Schritt 2: Paket bauen, in einer sauberen Testinstanz installieren und die Erstinbetriebnahme prüfen.
3. Schritt 3: Upgrade, Downgrade, Konfigurationsänderung und Datenmigration mit definierten Testfällen abnehmen.
4. Schritt 4: Betriebsdokumentation, Diagnoseleitfaden und Supportinformationen vervollständigen.
5. Schritt 5: Den Adapter anhand einer Freigabecheckliste für internen oder öffentlichen Einsatz bewerten.

Praxisübungen und Laborszenarien

• Aufbau eines TypeScript-Adapters für ein simuliertes Gerät oder Fachsystem.
• Modellierung und Migration eines mehrstufigen Objekt- und Zustandsbaums.
• Implementierung von Wiederverbindung, Rate-Limit-Behandlung und Diagnosezuständen.
• Automatisierte Tests für Start, Datenübernahme, Schreibbefehl und Verbindungsabbruch.
• Installation des erzeugten Pakets in einer leeren Abnahmeumgebung.

Zielgruppe und Voraussetzungen

Zielgruppe: Softwareentwicklung, technische Integration, IoT-Engineering und Teams mit eigenen Geräten, Protokollen oder Fachsystemen.

Voraussetzungen: Sichere Kenntnisse in JavaScript oder TypeScript, asynchroner Programmierung, JSON, Netzwerkgrundlagen und grundlegender ioBroker-Administration.

Didaktik und Arbeitsweise

Kurze Fachimpulse werden unmittelbar durch Demonstrationen, geführte Konfigurationsschritte, praktische Übungen und kontrollierte Fehlerfälle vertieft. Jeder Arbeitsabschnitt verwendet definierte Ausgangswerte, Prüfpunkte und Dokumentationsanforderungen, damit die erarbeiteten Abläufe reproduzierbar und betrieblich nutzbar bleiben.