Diese Dokumentation erklärt den technischen Aufbau des hDP – homeESS Device Protocol und dient als Einstieg für Entwickler, technisch interessierte Anwender und Hersteller kompatibler Geräte.

hDP verbindet ein kompatibles Endgerät mit dem hDP-Adapter von homeESS. Das Protokoll regelt dabei unter anderem Geräteerkennung, Pairing, Authentifizierung, Hardwarekonfiguration, Laufzeitkommunikation und Firmwareupdates.

Die vollständigen verbindlichen Details sind in der normativen hDP-Protokollspezifikation beschrieben. Diese Dokumentationsseite erklärt dagegen die grundlegenden Konzepte und Zusammenhänge.

→ hDP-Protokollspezifikation 1.0-draft öffnen

Architektur von hDP

Ein hDP-System besteht im Wesentlichen aus drei Ebenen:

hDP-Gerät
Das physische Gerät mit ESP-Mikrocontroller, Ein- und Ausgängen, Sensoren oder anderen Hardwarefunktionen.

hDP-Adapter
Der Adapter innerhalb von homeESS stellt die Verbindung zum Gerät her, verwaltet Pairing und Konfiguration und übersetzt die Gerätefunktionen in homeESS-States.

homeESS
Das zentrale System verwendet diese States anschließend für Dashboards, Automationen, Energiemanagement und andere Funktionen.

Vereinfacht dargestellt:

hDP-Gerät ↔ hDP-Adapter ↔ homeESS

Die eigentliche anwendungsspezifische Logik liegt dabei grundsätzlich auf der Seite von homeESS beziehungsweise des Adapters.

Klare Trennung zwischen Gerät und homeESS

Ein wichtiger Bestandteil von hDP ist die klare Zuständigkeitsverteilung.

Das hDP-Gerät übernimmt vor allem hardwarebezogene Aufgaben wie:

• Pairing und Binding
• Authentifizierung
• Persistieren der Hardwarekonfiguration
• Ansteuerung der konfigurierten Ein- und Ausgänge
• Verarbeitung generischer Laufzeitbefehle
• sichere Offline- und Fehlerzustände
• Firmwareupdates

Der Adapter übernimmt dagegen die Bedeutung der Daten.

Dazu gehören beispielsweise:

• Interpretation von States
• Zuordnung von Datenquellen
• Schaltlogik
• Berechnung von Pixelwerten
• Farben und Animationen
• Schwellenwerte
• anwendungsspezifische Steuerung

Das Gerät kennt damit beispielsweise nicht die Bedeutung „Hausakku 70 %“.

Es erhält stattdessen nur die bereits vom Adapter berechneten Ausgabedaten.

Geräte automatisch im lokalen Netzwerk finden

hDP verwendet mDNS/DNS-SD, damit kompatible Geräte automatisch im lokalen Netzwerk gefunden werden können.

Ein erreichbares Gerät veröffentlicht dazu den Dienst:

_homeess-hdp._tcp.local

Darüber kann der hDP-Adapter unter anderem Informationen über:

• Geräte-ID
• Firmwareversion
• Protokollversion
• Laufzeitprofil
• Pairing-Zustand
• konfigurierte Gerätefunktion
• API-Port
• WebSocket-Port
• OTA-Port

erkennen.

Dadurch muss die IP-Adresse eines Geräts nicht dauerhaft manuell konfiguriert werden.

Eindeutige Geräte-ID

Jedes hDP-Gerät besitzt eine dauerhafte device_id.

Diese wird beim ersten Start zufällig erzeugt und bleibt normalerweise auch über:

• Neustarts
• Firmwareupdates
• Entkopplung

erhalten.

Erst bei einem vollständigen Factory Reset wird eine neue Geräte-ID erzeugt.

homeESS behandelt die Geräte-ID als eindeutige Identität des Geräts und nicht dessen aktuelle IP-Adresse.

Dadurch bleibt ein Gerät auch nach einer Änderung seiner Netzwerkadresse eindeutig erkennbar.

hDP Pairing und Gerätebindung

Gerät einmalig mit homeESS koppeln

Ein neues hDP-Gerät befindet sich zunächst im kopplungsbereiten Zustand.

Der hDP-Adapter kann anschließend eine Pairing-Session starten.

Bei erfolgreicher Kopplung entsteht eine eindeutige Bindung zwischen:

• dem hDP-Gerät
• und einer bestimmten homeESS-Installation.

Diese Bindung bleibt auch nach einem Neustart erhalten.

Exklusive Bindung an eine homeESS-Installation

Ein bereits gekoppeltes Gerät kann nicht automatisch von einer anderen homeESS-Installation übernommen werden.

Dadurch wird verhindert, dass ein fremdes System ein vorhandenes Gerät einfach neu konfiguriert.

Soll das Gerät mit einer anderen homeESS-Installation verwendet werden, muss die vorhandene Bindung zunächst kontrolliert aufgehoben werden.

Binding-Key zur Authentifizierung

Bei der Kopplung wird ein zufälliger Binding-Key erzeugt.

Dieser dient anschließend zur Authentifizierung geschützter Zugriffe zwischen homeESS und dem Gerät.

Der Binding-Key wird nach erfolgreicher Kopplung nicht öffentlich übertragen.

Zusätzlich verwendet hDP eine daraus abgeleitete binding_id, um eine vorhandene Bindung vergleichen zu können, ohne den eigentlichen geheimen Schlüssel offenzulegen.

HTTP-API für Konfiguration und Geräteverwaltung

Lokale REST-Schnittstelle

hDP verwendet eine HTTP-Schnittstelle für Geräteinformationen, Konfiguration, Pairing und Firmwareverwaltung.

Die API liegt unter:

/api/v1

Dort stehen unter anderem Endpunkte bereit für:

• Geräteinformationen
• Gerätefähigkeiten
• Systemstatus
• Pairing
• Hardwarekonfiguration
• Entkopplung
• Neustart
• Factory Reset
• Firmwareinformationen
• Firmwareupdate

Die Kommunikation erfolgt im lokalen Netzwerk.

Geräteinformationen abfragen

Über die Geräte-API kann homeESS unter anderem feststellen:

• welche Geräte-ID vorhanden ist
• welche Plattform verwendet wird
• welche Firmware installiert ist
• welche hDP-Version unterstützt wird
• welcher Gerätetyp konfiguriert ist
• welches Laufzeitprofil aktiv ist
• ob eine Hardwarekonfiguration vorhanden ist

Diese Informationen ermöglichen es dem Adapter, ein Gerät dynamisch zu behandeln, statt feste Annahmen über dessen Fähigkeiten zu verwenden.

Manifest und Hardwarefähigkeiten

Gerät beschreibt seine Fähigkeiten selbst

Ein hDP-Gerät stellt über sein Manifest Informationen darüber bereit, welche Funktionen es tatsächlich unterstützt.

Dazu können beispielsweise gehören:

• verfügbare Gerätetypen
• mögliche GPIOs
• unterstützte LED-Typen
• unterstützte Farbfolgen
• Binary-I/O-Funktionen
• OTA-Unterstützung
• maximale Pixelanzahl
• Speicher- und Größenlimits
• unterstützte Laufzeitprofile

Dadurch muss der Adapter keine fest eingebauten Boardtabellen für jedes unterstützte Gerät besitzen.

Die Firmware beschreibt ihre Fähigkeiten selbst.

GPIO-Eigenschaften erkennen

Das Gerät kann zusätzlich Besonderheiten einzelner GPIOs mitteilen.

Beispielsweise kann ein Pin:

• einen internen Pull-up unterstützen
• beim Booten besondere Pegel benötigen
• von der seriellen Schnittstelle verwendet werden

homeESS kann diese Informationen bei der Konfiguration anzeigen und so bei der Auswahl geeigneter Pins helfen.

Geräteprofile und Hardwarekonfiguration

Gerätetyp zentral festlegen

Die Hardwarefunktion eines hDP-Geräts wird über device_type definiert.

Beispiele sind:

• percentage_indicator
• argb_output
• binary_io

Der Gerätetyp bestimmt, welche generische Laufzeitschicht auf dem Gerät verwendet wird.

Die eigentliche Bedeutung der Ein- und Ausgänge bleibt beim Adapter.

Hardwarekonfiguration persistent speichern

homeESS kann die Hardwarekonfiguration auf dem Gerät speichern.

Dazu gehören beispielsweise:

• GPIO-Zuordnung
• Richtung eines Pins
• Anzahl adressierbarer LEDs
• LED-Treiber
• Farbreihenfolge
• maximale Helligkeit
• Strombegrenzung
• Verhalten bei Verbindungsverlust

Die Konfiguration bleibt auch nach Neustarts und Firmwareupdates erhalten.

Revisionssystem verhindert überschriebenen Konfigurationsstand

Jede Hardwarekonfiguration besitzt eine Revisionsnummer.

Will homeESS eine Konfiguration verändern, muss es die aktuell bekannte Revision mitsenden.

Hat sich die Konfiguration zwischenzeitlich verändert, wird der Schreibvorgang abgelehnt.

Dadurch wird verhindert, dass ältere Konfigurationsstände versehentlich neuere Einstellungen überschreiben.

Laufzeitprofile von hDP

Unterschied zwischen Gerätetyp und Runtime Profile

Der Gerätetyp beschreibt die konfigurierbare Geräteklasse.

Das Runtime Profile definiert dagegen die technische Kommunikation während des laufenden Betriebs.

hDP 1.0-draft definiert unter anderem:

pixel-timeline-v1

und

binary-io-v1

Mehrere Gerätetypen können dasselbe Laufzeitprofil verwenden.

Dadurch können beispielsweise zwei unterschiedliche Anwendungsfälle dieselbe technische Ausgabeschicht nutzen.

WebSocket-Verbindung für laufende Gerätedaten

Echtzeitkommunikation zwischen homeESS und hDP-Gerät

Für die laufende Kommunikation verwendet hDP eine WebSocket-Verbindung.

Diese wird nach erfolgreicher Authentifizierung zwischen Adapter und Gerät aufgebaut.

Nach dem Verbindungsaufbau tauschen beide Seiten zunächst Informationen über:

• Protokollversion
• Laufzeitprofil
• Konfigurationsrevision
• Geräteidentität

aus.

Erst wenn diese Werte übereinstimmen, wird die eigentliche Steuersitzung freigegeben.

Heartbeat überwacht die Verbindung

homeESS sendet regelmäßig Heartbeat-Nachrichten.

Antwortet der Adapter beziehungsweise das Gerät über einen längeren Zeitraum nicht mehr, wird die Verbindung als verloren behandelt.

Das Gerät kann anschließend automatisch in einen definierten Offline-Zustand wechseln.

Dadurch kann ein hDP-Gerät kontrolliert reagieren, wenn homeESS nicht mehr erreichbar ist.

Binary I/O – digitale Ein- und Ausgänge

Digitale Eingänge

Im Laufzeitprofil binary-io-v1 können GPIOs als digitale Eingänge konfiguriert werden.

Unterstützte Eingangstypen sind unter anderem:

• Schalter
• Taster

Schalter erzeugen Ereignisse bei stabilen Zustandsänderungen.

Taster melden dagegen den aktiven Tastendruck.

Die Firmware übernimmt dabei auch die Entprellung der Eingänge.

Digitale Ausgänge

Ausgänge können über WebSocket-Befehle geschaltet werden.

Nach der physischen Übernahme bestätigt das Gerät den tatsächlich gesetzten Zustand.

Bei Verlust der Steuersitzung werden Binary-Ausgänge in einen sicheren Grundzustand gesetzt.

Die eigentliche Schaltlogik bleibt dabei vollständig in homeESS.

ARGB-Ausgabe und Pixelsteuerung

Pixelwerte werden von homeESS berechnet

Bei ARGB-Geräten berechnet ausschließlich der hDP-Adapter die logischen RGB-Werte.

Das Gerät selbst kennt keine Bedeutung wie:

• Prozentanzeige
• Batteriestand
• Warnfarbe
• Animation
• Energiefluss

Es erhält lediglich fertige Pixelwerte und gibt diese physisch aus.

Dadurch bleibt die Firmware generisch.

Vollständige Frames und einzelne Pixeländerungen

hDP kann komplette Pixelbilder übertragen.

Zusätzlich können einzelne Pixel verändert werden, wenn nicht das gesamte Bild neu übertragen werden muss.

Vor der Ausgabe prüft die Firmware unter anderem:

• Ausgang
• Konfigurationsrevision
• Pixelanzahl
• Wertebereiche
• zulässige Ausgabefrequenz

Erst nach erfolgreicher Validierung wird der physische Ausgang verändert.

Timeline-Programme für Animationen

Animationen lokal auf dem Gerät wiedergeben

Animationen werden nicht als ständig neue Netzwerkframes übertragen.

Stattdessen kann homeESS eine Timeline vollständig vorberechnen und an das Gerät übertragen.

Diese Timeline enthält ausschließlich:

• Zeitabstände
• Pixeloperationen
• RGB-Werte

Das Gerät speichert das Programm temporär und spielt es anschließend zeitgesteuert ab.

Damit können Animationen auch bei kleinen Netzwerkschwankungen gleichmäßig dargestellt werden.

Keine anwendungsspezifische Animation in der Firmware

Die Timeline enthält keine Bedeutung.

Die Firmware weiß beispielsweise nicht, dass eine Animation einen Ladezustand oder einen Warnhinweis darstellen soll.

Alle Farben, Übergänge und Pixeländerungen werden vorher vom Adapter berechnet.

Das hDP-Gerät übernimmt lediglich die zeitlich korrekte Wiedergabe.

Helligkeits- und Strombegrenzung

Schutzgrenzen direkt auf dem Gerät

Bei adressierbaren LEDs kann die Hardwarekonfiguration eine maximale Helligkeit und einen maximal zulässigen Strom definieren.

Diese Werte werden direkt vom Gerät berücksichtigt.

Überschreitet ein berechnetes Pixelbild die zulässige Stromaufnahme, reduziert die Firmware alle Farben proportional.

Dadurch bleibt das Farbverhältnis erhalten.

Die Schutzbegrenzung verändert dabei nicht den logischen Pixelpuffer, sondern ausschließlich die tatsächliche physische Ausgabe.

Sicheres Verhalten bei Verbindungsverlust

Offline-Modi für Ausgänge

Für ARGB-Ausgänge kann festgelegt werden, wie sich das Gerät bei Verlust der homeESS-Verbindung verhält.

Mögliche Verhaltensweisen sind beispielsweise:

• letzten Frame beibehalten
• LEDs ausschalten
• eine bereits laufende lokale Timeline weiterlaufen lassen

Binary-Ausgänge wechseln dagegen bei Verlust der aktiven Steuersitzung in den sicheren ausgeschalteten Zustand.

Damit ist das Verhalten bei Ausfall des Controllers eindeutig definiert.

Firmwareupdates über OTA

Firmware direkt über das Netzwerk aktualisieren

Ein gekoppeltes hDP-Gerät kann seine Firmware über das Netzwerk erhalten.

homeESS überträgt dabei:

• Firmwareimage
• Versionsinformationen
• Plattforminformationen
• Prüfsumme
• weitere Metadaten

direkt an das Gerät.

Firmware vor dem Update prüfen

Vor und während eines OTA-Updates prüft das Gerät unter anderem:

• Gerätebindung
• Firmwarefamilie
• Plattform
• Board
• Firmwarevariante
• Protokollversion
• Config-Schema
• Imagegröße
• SHA-256-Prüfsumme

Unterstützt das Gerät signierte Firmwareimages, kann zusätzlich eine kryptografische Signatur geprüft werden.

Erst nach erfolgreicher Validierung wird das neue Image für den Neustart freigegeben.

Hardwarekonfiguration bleibt bei Firmwareupdates erhalten

Firmwareupdates verändern nicht automatisch:

• Geräte-ID
• WLAN-Konfiguration
• Binding
• Hardwarekonfiguration

Dadurch bleibt ein konfiguriertes hDP-Gerät nach einem normalen Firmwareupdate weiterhin Bestandteil derselben homeESS-Installation.

Neustart, Entkopplung und Factory Reset

Gerät neu starten

homeESS kann ein gekoppeltes Gerät kontrolliert neu starten.

Die bestehende Geräteidentität und Konfiguration bleiben erhalten.

Gerät von homeESS entkoppeln

Beim Entkoppeln wird die bestehende Gerätebindung gelöscht.

Die Hardwarekonfiguration bleibt erhalten.

Dadurch kann das Gerät anschließend erneut gekoppelt werden, ohne seine vollständige physische Konfiguration neu aufbauen zu müssen.

Vollständiger Factory Reset

Ein Factory Reset löscht dagegen die persistenten Gerätedaten vollständig.

Dazu gehören unter anderem:

• Geräte-ID
• WLAN-Konfiguration
• Binding
• Hardwarekonfiguration

Dieser Vorgang ist ausschließlich über einen gesonderten Recovery-Zustand möglich.

Fehlerbehandlung und Wiederverbindung

hDP definiert feste Fehlercodes für typische Situationen.

Dazu gehören beispielsweise:

• ungültige Requests
• inkompatible Protokollversion
• fehlgeschlagene Authentifizierung
• Pairing-Konflikte
• ungültige Konfiguration
• falsche Konfigurationsrevision
• unbekannte GPIOs
• Timelinefehler
• Verbindungsfehler
• OTA-Probleme

Damit müssen Adapter Fehler nicht anhand von Textmeldungen interpretieren.

Automatische Wiederverbindung

Nach einem unerwarteten Verlust der WebSocket-Verbindung versucht der Adapter die Verbindung mit steigenden Wartezeiten erneut aufzubauen.

Die aktuelle IP-Adresse wird dabei wieder über die Geräteerkennung bestimmt.

Dadurch funktionieren Geräte auch dann weiter, wenn sich ihre Adresse im lokalen Netzwerk geändert hat.

Protokollversion und Kompatibilität

Die aktuelle Spezifikation verwendet den Protokollbezeichner:

1.0-draft

Solange es sich um einen Draft handelt, kann das Protokoll noch präzisiert werden.

Inkompatible Änderungen an einer Laufzeitschicht erhalten mindestens ein neues Runtime Profile.

Nach Veröffentlichung einer stabilen Version 1.0 erfordern inkompatible Protokolländerungen eine neue Protokollversion.

Dadurch können Adapter und Firmware eindeutig feststellen, ob sie technisch miteinander kompatibel sind.

Normative hDP-Protokollspezifikation

Diese Dokumentation beschreibt die Architektur und grundlegende Funktionsweise von hDP.

Für die Entwicklung eigener Firmware, Adapter oder vollständig hDP-kompatibler Geräte ist ausschließlich die normative Protokollspezifikation maßgeblich.

Sie enthält unter anderem:

• sämtliche HTTP-Endpunkte
• vollständige JSON-Strukturen
• mDNS-TXT-Records
• Pairing-Ablauf
• Authentifizierung
• Binding-Regeln
• Hardwarekonfiguration
• WebSocket-Nachrichten
• Binary-I/O-Protokoll
• Pixel- und Timelineformate
• OTA-Protokoll
• Fehlerregister
• Timeouts
• Retryregeln
• Konformitätsanforderungen

→ hDP-Protokollspezifikation 1.0-draft öffnen

Weitere hDP-Dokumentation

→ Was ist hDP?
→ hDP-Funktionen und Gerätetypen
→ Eigene hDP-Geräte bauen
→ hDP-Firmware installieren