Um Entities und Geräte optimal nach Homey zu importieren, bedarf es eines Grundverständnisses beider Systeme.
Beide Systeme bilden Geräte und deren Eigenschaften ab. Dazu kommen ausführbare Aktionen. Aus Anwendersicht sind beide System recht ähnlich. Allerdings unterscheiden sie sich im Detail teilweise deutlich, was eine passende Gestaltung der Datenübernahme erschwert.
Domains und Capabilities
HomeAssistant Domains
Eine Domain definiert einen Standard-Gerätetyp. Diese Domain ist Bestandteil der HomeAssistant Basis-Installation und kann von allen Integrationen zur Bereitstellung passender Inhalte und Funktionen verwendet werden.
Eine einfache Domain ist sensor. Eine Entity sensor.motion verwendet die Eigenschaften der sensor-Domain. Dies umfasst den Entity-Status sowie Services zum Ändern des Wertes.
Neben dem Status besitzt die Entiyt weitere (ggf. optionale) Attribute wie:
- Bezeichnung
- Einheit
- Eigenschaften wie Einheit, Min-/Max-Werte
- Möglichen Werten bei Wertelisten
Der Status besitzt immer den Typ string (Text).
Eine Entity ist damit bereits die Repräsentation eines Gerätes und dessen Status.
Im Gegensatz zu einfachen Domains wie sensor gibt es aber auch komplexe Domains wie z.B. media_player. Solche Domains enthalten mehrere Attribute, die jeweils Statuswerte für Unterattribute der Domain darstellen. Beispiele dafür wären source, sound_mode oder volume_level.
HomeAssistant-Geräte
Die Entity umfasst sowohl Status als auch Funktionen (Services) und kann eigenständig in HomeAssistant verwendet werden.
Oft liefern reale Geräte (wie Bewegungsmelder) mehrere Werte (Temperatur, Bewegungsalarm …). Diese Werte werden jeweils durch Entities abgebildet. Diese Entities werden zu einem Gerät zusammengefasst. Das Gerät ist dabei lediglich eine Gruppierung von Entities, besitzt aber selbst keine weiteren Eigenschaften.
Weiterführende Informationen:
Homey-Capabilities
Homey-Capabilities sind vordefinierte Typen, die für Geräteattribute verwendet werden können. Eine Capability kann nur innerhalb eines Gerätes verwendet werden.
Bei der Definition eines Gerätes werden dabei eine oder mehrere Capabilities hinzugefügt. Jede Capability besitzt dabei eine Definition von:
- Datentyp
- Eigenschaften wie Einheit, Min-/Max-Werte
- Möglichen Werten bei Wertelisten
- Flow-Trigger, -Bedingungen oder -Aktionen
Ein Gerät kann somit verschiedenste Daten umfassen.
Zusätzlich besitzen Geräte auch Eingenschaften , die für das Gerät selbst definiert werden, wie z.B. Energie-Parameter.
Capabilities können mit der Capability-ID eingefügt werden (z.B. measure_power). Sollen mehrere Capabilities vom gleichen Typ eingefügt werden, so müssen Sub-Capabilities verwendet werden, um die IDs eindeutig zu definieren (z.B. meter_power.imported und meter_power.exported).
Homey-Gerät mit einer Capability:
Weiterführende Informationen:
- Homey-Capabilities (SDK-Referenz)
- Geräte- und Capability-Definition (App-SDK Guidelines)
Vergleich einfacher Entities und Capabilities
Betrachte man einfache Entities (Sensorwerte), so sind diese meist 1-zu-1 in ein Homey-Gerät konvertierbar.
Dazu wird ein Gerät mit einer passenden Capability angelegt und der Entity-Status als Capability-Wert übernommen.
In diesem Beispiel wurde ein Sensor-Gerät angelegt und die Temperatur-Entity gewählt. Aufgrund der Entity-Eigenschaften (Einheit °C) wird eine Capability measure_temperature eingefügt.
Anhand dieses Beispiels könnte man denken, eine Entity entspricht einer Capability. Das ist aber nur bei einfachen Entities mit nur einem Statuswert der Fall.
Vergleich komplexer Entities und Homey-Geräte
Beim Vergleich komplexer Entities mit dem entsprechenden Homey-Gerät wird der Unterschied der Datenverwaltung beider Systeme deutlich.
Als Beispiel wird ein Mediegerät verwendet.
In HomeAssistant wird ein solches Gerät über die Domain media_player abgebildet.
Die entsprechenden Entity besitzt einen Status (wie jede Entity). Zusätzlich werden alle weiteren notwendigen Eigenschaften als Attribute gespeichert. Attribute könnem dabei einzelne Werte sein, aber auch Listen, die wiederum auch hierarchisch verschachtelt sein können.
Im Homey-Gerät werden die verschiedenen Werte dagegen als separate Capabilities abgebildet. Man benötigt damit ein Gerät und muss für die zu importierenden Entity-Attribute jeweils Capabilities anlegen.
Eine media_player Domain bietet mehrere Services an zum Steuern des Medien-Gerätes. Um die HomeAssistant-Entity von Homey aus zu steuern, muss innerhab Homey auf Capability-Änderungen (z.B. Taste gedrückt, Slider verschoben) reagiert werden. Die Homey-Werte müssen ggf. konvertiert werden (z.B. Prozentwerte von 0..1 Skala in eine 0..100 Skala) und mit Service-Aufrufen an HomeAssistant gesendet werden.
Aus diesem Grund können komplexe Entities (bzw. Domains) nur in ein entsprechendes Homey-Gerät übernommen werden. Nur so können alle Daten korrekt konvertiert und in Capabilities übernommen werden und Aktionen durch Service-Aufrufe ausgeführt werden.
Sollen nicht nur Entity-Werte in einem Gerät angezeigt werden, sondern die komplette HomeAssistant Domain mit allen Funktionen übernommen werden, so binde die Entities als Gerät ein.
Homey-Geräte um Entities erweitern
Um bei Geräten noch mehr Flexibilität zu ermöglichen, können in ein Homey-Gerät weitere Entities eingefügt werden. Die einfachste Möglichkeit ist es, die im HomeAssistant-Gerät gruppierten Entities zu übernehmen.
Beispiel: Eines Bewegungssensors wird als Sensorgerät importiert. Zusärtlich liefert der Bewegungssensor aber auch Werte zu Temperatur und Helligkeit sowie ggf. Steuerungen als Schalter zum Ein-/Ausschalten der Bewegungserkennung.
Über die Geräteeinstellung können diese zusätzlichen Entitäten des HomeAssistant-Gerätes ergänzt werden.
Weitere Informationen dazu sind als Blogbeitrag verfügbar.
Diese Variante ist bevorzugt für Entities/Geräte zu verwenden, die im HomeAssistant-Gerät neben den eigentlichen Geräteattributen noch weitere Entities verwenden.
Benutzerdefinierte Geräte anlegen
Eine noch flexiblere Möglichkeit ist die Verwendung benutzerdefinierter Geräte. Dazu wird ein „leeres“ Gerät angelegt und um Capabilities ergänzt.
In dieses Geräte werden nun nach und nach die gewünschten Entities hinzugefügt. Dabei wird die Ziel-Capability automatisch vorbelegt, kann aber auch angepasst werden. Außerdem können die Entity-Werte konvertiert werden, um HomeAssistant-Werte in für Homey-Capabilities zulässige Werte zu konvertieren.
Weitere Informationen dazu sind als Blogbeitrag verfügbar.
Diese Variante ist bevorzugt zu verwenden, um verschiedene „einfache“ Entities wie Sensoren, Buttons oder Schalter in einem Homey-Gerät zu gruppieren bzw. einem Gerät hinzuzufügen.
Dies kann auch bei komplexen Geäten wie Medianplayer oder Klimagerät verwendet werden, um weitere Entities in das Homey-Gerät einzufügen.
