Alexa und Mappings: Unterschied zwischen den Versionen
Justme (Diskussion | Beiträge) |
|||
(83 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
Zeile 1: | Zeile 1: | ||
Auf dieser Seite soll das Zusammenwirken zwischen Sensoren/Aktoren in FHEM, dem Programm Alexa-Fhem und den Amazon Web Services erläutern. | Auf dieser Seite soll das Zusammenwirken zwischen Sensoren/Aktoren in FHEM, dem Programm Alexa-Fhem und den Amazon Web Services erläutern. | ||
== Glossar== | |||
* '''Aspekte''': Die Sensoren/Aktoren von FHEM haben aus der Sichweise von Alexa bestimmte Eigenschaften - diese können "read only" sein,(z.b. die aktuell gemessene Temperatur) oder durch den Benutzer veränderbar (z.b. die gewünschte Raumtemperatur). Um die Mehrdeutigkeit des Begriffs "Eigenschaften" zu vermeiden, werden sie auf dieser Wiki-Seite als ''Aspekte'' bezeichnet. | |||
* '''Characteristic''': Dieser Begriff ist der Homekit-Software entlehnt, er bezeichnet einen abfragbaren oder setzbaren ''Aspekt'' eines Sensors/Aktors - allerdings in einer abstrakten Sichtweise, die nicht mit der sehr gerätespezifischen Sichtweise von FHEM übereinstimmt. ''Characteristics'' sind typischerweise auch mit einem entsprechenden ''Service'' verbunden. | |||
* '''Service''': Eine Zusammenfassung mehrerer ''Characteristics'' zu einer logischen Gesamtheit, die z.B. mit einem bestimmten abstrakten Gerätetyp verbunden ist. Beispielsweise ist der Service "Door" eine Zusammenfassung der ''Characteristics'' "CurrentPosition","PositionState","TargetPosition" sowie optional "HoldPosition","ObstructionDetected","Name". | |||
== Attribute der Sensoren/Aktoren == | == Attribute der Sensoren/Aktoren == | ||
Über zwei Attribute wird die sehr variable Welt von FHEM in einer eher abstrakte und semantisch eindeutigere Zwischenschicht (die ''Characteristics'') überführt und dann mit der Sprachsteuerung verbunden. Dabei wird versucht, dem Benutzer so viel Arbeit wie möglich abzunehmen und die häufigsten Devices so automatisch wie möglich zu erkennen. Erst wo dies nicht ausreicht, ist eine komplett freie Konfiguration möglich. Auf Grund dieses Vorgehens ist die automatische Zuordnung von ''Characteristics'' sehr komplex, weil sie je nach Gerät auf Grund von unterschiedlichen Kriterien getroffen wird. Dabei kann es sich handeln um | |||
* das Attribut ''genericDeviceType'' | |||
* das INTERNAL ''TYPE'', z.B. | |||
** ''TYPE'' = "harmony" -> als ''genericDeviceType'' wird automatisch "switch" ausgewählt. | |||
* das Reading ''temperature'' bzw. ''measured-temp'' | |||
===genericDeviceType=== | ===genericDeviceType=== | ||
Dieses Attribut | Dieses Attribut dient dazu, ohne spezielle Angaben einen bestimmten ''Service'' (und somit auch bestimmte ''Characteristics'') auszuwählen und somit Konfigurationsaufwand zu sparen. | ||
Das Attribut kann nur wenige verschiedene Werte annehmen, die per Drop-Down-Liste ausgewählt werden können. | |||
{| class="wikitable" | |||
|- | |||
! Name !! ''Service'' !! ''Characteristics'' !! Bemerkungen | |||
|- | |||
| security | |||
|- | |||
| ignore | |||
|- | |||
| switch | |||
|- | |||
| outlet | |||
|- | |||
| light | |||
|- | |||
| blind || blind || CurrentPosition/TargetPosition || | |||
* Wenn das Device einen set-Befehl ''position'' hat, wird gemappt<br/> CurrentPosition => reading=''position'', TargetPosition => reading=''position'', cmd=''position'' | |||
** Wenn TYPE=''DUOFERN'', werden die Datenwerte für CurrentPosition und TargetPosition invertiert. | |||
** Wenn TYPE=''SOMFY'', werden die Datenwerte für CurrentPosition und TargetPosition invertiert, und das Kommando zum Setzen wird auf cmd=''pos'' geändert. | |||
* Ansonsten wird gemappt <br/> CurrentPosition => reading=''pct'', TargetPosition => reading=''pct'', cmd=''pct'' | |||
** Wenn ein Attribut levelInverse gesetzt ist, werden die Datenwerte für CurrentPosition und TargetPosition invertiert. | |||
|- | |||
| thermometer | |||
|- | |||
| thermostat | |||
|- | |||
| contact | |||
|- | |||
| garage | |||
|- | |||
| window | |||
|- | |||
| lock || lock || LockCurrentState/LockTargetState | |||
|} | |||
Andere Werte des Attributes können über das Befehlsfeld zugewiesen werden, hiervon wird aber abgeraten, weil diese ggf. in Alexa-Fhem nicht ausgewertet werden. | |||
===homebridgeMapping=== | ===homebridgeMapping=== | ||
Dieses Attribut beinhaltet eine durch Leerzeichen getrennte Liste von Datenpaaren | Das Attribut homebridgeMapping gibt an, welches konkrete FHEM-Reading und bzw. FHEM-Kommando dieses Gerätes mit welchem ''Aspekt'' (= abstrakte Eigenschaft) verknüpft ist. | ||
attr meinSensor homebridgeMapping clear <Characteristic1>=<reading1> | |||
*Das | Das Konzept des homebridgeMapping ist hier: https://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 und hier: https://github.com/justme-1968/homebridge-fhem/blob/master/README.md beschrieben. | ||
* | |||
Dieses Attribut beinhaltet eine durch Leerzeichen getrennte Liste von Datenpaaren, in der einfachsten Form | |||
attr <meinSensor> homebridgeMapping [clear] <Characteristic1>=<FHEM-reading1> <Characteristic2>=<FHEM-reading2> <Characteristic3>=<FHEM-reading3> ... | |||
*Das optionale Schlüsselwort <code>clear</code> hat eine besondere Bedeutung: Es löscht Standardmappings - das wird meist nicht notwendig sein, schadet aber nichts | |||
*Siehe hierzu die einleitende Bemerkung über ''Characteristics''. <code><Characteristic1>=<FHEM-reading1></code> verbindet diesen logischen Kanal (linke Seite) mit einem ''reading'' des Sensors/Aktors aus FHEM (rechte Seite). Die Liste der vordefinierten ''Characteristics'' findet man in Abschnitt [[#Characteristics|Characteristics]], und ein <FHEM-reading> kann die komplexere Struktur <code><command>:<device>:<reading></code> haben. | |||
*An den Wert des <FHEM-readings> kann eine Liste von Parameter-Wert-Paaren angehängt werden. Dabei sind die einzelnen Paare durch Komma getrennt, mehrere Werte eines Parameters durch ein Semikolon voneinander abgegrenzt. Beispielsweise lässt sich mit dem values-Parameter eine direkte Entsprechung zwischen Werten aus FHEM und Werten aus dem Homekit realisieren. Die Liste der vordefinierten Parameter findet man in Abschnitt [[#Parameter|Parameter]], | |||
==Attribute des Alexa-Devices== | ==Attribute des Alexa-Devices== | ||
Im Gegensatz zu Homekit, das die Daten aus den ''Characteristics'' bei der Sprachanalyse verwendet, muss dies für Alexa-Fhem im Custom Skill selbst implementiert werden. Hier kommt das Attribut alexaMapping ins Spiel, mit dem festgelegt wird, welches gesprochene Kommando Auswirkung auf welche ''Characteristic'' hat. | |||
Im Attribut alexaMapping lassen sich auch zusätzliche ''Characteristics'' unterbringen, wenn die bereits definierten nicht ausreichen. | |||
===alexaMapping=== | ===alexaMapping=== | ||
In diesem Attribut finden wir die abstrakten '' | In diesem Attribut finden wir also die abstrakten ''Characteristics'' in Verbindung mit sprachlichen Parametern wieder - und zwar in der allgemeinen Form | ||
Characteristic=<name1>=<value11>[;<value12>]*[,<name2>=<value21>[;<value22>]*]* | |||
*<code>< | *<code><namex></code> ist der Name eines Parameters, z.B. ''verb'' | ||
*Es folgt eine durch Semikolon getrennte Liste von möglichen Werten. Für ''verb'' könnte diese z.B. sein <code>verb=stelle;setze</code> | *Es folgt eine durch Semikolon getrennte Liste von möglichen Werten. Für ''verb'' könnte diese z.B. sein <code>verb=stelle;setze</code> | ||
*Weitere Parameter/Wert-Listen werden durch ein Komma getrennt angehängt. | *Weitere Parameter/Wert-Listen werden durch ein Komma getrennt angehängt, z.B. <code>verb=stelle;setze,valueOn=an;ein,valueOff=aus</code> | ||
Jede ''Characteristic'' kann mehrfach auftauchen - nämlich für jede Aussprachemöglichkeit dieser ''Characteristic''. Beispiele: | Jede ''Characteristic'' kann mehrfach auftauchen - nämlich für jede Aussprachemöglichkeit dieser ''Characteristic''. Beispiele: | ||
On=verb=schalte,valueOn=an;ein,valueOff=aus,valueToggle=um | On=verb=schalte,valueOn=an;ein,valueOff=aus,valueToggle=um | ||
Zeile 27: | Zeile 78: | ||
Hue=verb=färbe,values=rot:0;grün:120;blau:220 | Hue=verb=färbe,values=rot:0;grün:120;blau:220 | ||
== | ==Liste der unterstützten ''Characteristics'' und ihrer Parameter== | ||
Viele Namen für die ''Aspekte'' und ''Characteristics'' eines Gerätes entstammen dem Apple Homekit API. | |||
Welche Services mit welchen Characteristics es dort gibt ist hier zu finden: https://github.com/homebridge/HAP-NodeJS/blob/master/src/lib/gen/HomeKit.ts | |||
===''Characteristics''=== | |||
{| class="wikitable" | |||
|- | |||
! Name !! Typ !! Parameter und Werte !! Standardmapping | |||
|- | |||
| On || Boolean || valueOn, valueOff, cmdOn, cmdOff || | |||
* state,valueOff:/off|A0|000000/, cmdOn:on,cmdOff:off | |||
* Wenn es sich um einen Dummy handelt, bei dem das Attribut ''setList'' den Wert "<cmd0> <cmd1>" hat: <br/>state,valueOn:<cmd0>,cmdOn:<cmd0>,cmdOff:<cmd1> | |||
|- | |||
| ContactSensorState || Integer || CONTACT_DETECTED=0,CONTACT_NOT_DETECTED=1 || value,values=???:CONTACT_DETECTED,???:CONTACT_NOT_DETECTED | |||
|- | |||
| Brightness | |||
|- | |||
| Hue | |||
|- | |||
| Saturation | |||
|- | |||
| CurrentTemperature | |||
|- | |||
| TargetTemperature | |||
|- | |||
| CurrentPosition || Integer || position oder pct || | |||
* Wenn das Device einen set-Befehl position hat: CurrentPosition => reading=position | |||
** Wenn TYPE=DUOFERN, werden die Datenwerte invertiert. | |||
** Wenn TYPE=SOMFY, werden die Datenwerte invertiert. | |||
* Ansonsten wird gemappt: CurrentPosition => reading=pct | |||
** Wenn ein Attribut levelInverse gesetzt ist, werden die Datenwerte invertiert. | |||
|- | |||
| TargetPosition || Integer || position oder pct || | |||
* Wenn das Device einen set-Befehl position hat: TargetPosition => reading=position, cmd=position | |||
** Wenn TYPE=DUOFERN, werden die Datenwerte invertiert. | |||
** Wenn TYPE=SOMFY, werden die Datenwerte invertiert, und das Kommando zum Setzen wird auf cmd=pos geändert. | |||
* Ansonsten wird gemappt: TargetPosition => reading=pct, cmd=pct | |||
** Wenn ein Attribut levelInverse gesetzt ist, werden die Datenwerte invertiert. | |||
|- | |||
| CurrentRelativeHumidity | |||
|- | |||
| CurrentAmbientLightLevel | |||
|- | |||
| AirQuality | |||
|- | |||
| CurrentDoorState || Integer || OPEN=0, CLOSED=1, OPENING=2, CLOSING=3, STOPPED=4|| Mehrere Mappings möglich: | |||
* doorState,values=/^opening/:OPENING,/^closing/:CLOSING,/^open/:OPEN,/^closed/:CLOSED,/.*/:STOPPED | |||
* state,values=/^Closed/:CLOSED,/.*/:OPEN | |||
* Window,values=/^Closed/:CLOSED,/.*/:OPEN | |||
* contact,values=/^closed/:CLOSED,/.*/:OPEN | |||
|- | |||
| TargetDoorState || Integer || OPEN=0, CLOSED=1|| | |||
* state,values=???:OPEN,???:CLOSED | |||
* Wenn es sich um eine KeyMatic handelt, also das Attribut ''model'' den Wert HM-SEC-KEY hat, oder ''genericDeviceType'' den Wert "lock" hat:<br/>???,default:CLOSED,timeout:500,cmds=OPEN:open | |||
|- | |||
| LockCurrentState || Integer || UNSECURED=0, SECURED=1, JAMMED = 2, UNKNOWN = 3|| lock,values=/uncertain/:UNKNOWN,/^locked/:SECURED,/.*/:UNSECURED<br/> | |||
|- | |||
| LockTargetState || Integer || UNSECURED=0, SECURED=1|| | |||
* Wenn es sich um eine KeyMatic handelt, also das Attribut ''model'' den Wert HM-SEC-KEY hat:<br/>state,values=/^locked/:SECURED,/.*/:UNSECURED,cmds=SECURED:lock;UNSECURED:unlock | |||
* Wenn ''genericDeviceType'' den Wert "lock" hat:<br/>state,values=/^locked/:SECURED,/.*/:UNSECURED,cmds=SECURED:lock+locked,UNSECURED:lock+unlocked | |||
|- | |||
| OccupancyDetected | |||
|- | |||
| StatusLowBattery | |||
|- | |||
| SecuritySystemCurrentState | |||
|- | |||
| SecuritySystemTargetState | |||
|- | |||
| FirmwareRevision | |||
|- | |||
| alle anderen Homebridge Characteristic | |||
|} | |||
===Parameter=== | |||
{| class="wikitable" | |||
|- | |||
! Name !! Typ !! Parameter | |||
|- | |||
| values || Dieser Parameter enthält eine durch Semikolon getrennte Liste von Entsprechungen der Form <code>FHEM-Wert:Homekit-Wert</code>. Jeder FHEM-Wert kann ein Literal (String) sein, oder ein Regulärer Ausdruck der Form /regex/. Jeder Homekit-Wert kann ein Literal (String) sein, oder ein für diese ''Characteristic'' definierter Term. Wenn als Homekit-Wert ein "#" steht, wird es gleich dem aktuellen Wert gesetzt (Heißt was ???).'''Achtung''': Wegen der nicht konsistenten Vertauschung der Seitenbezüge links-rechts ist das eine sehr gewöhnungsbedürftige Notation. | |||
|- | |||
| valueOn, valueOff || Dies sind die FHEM-Werte für boolesche ''readings'', die auf die Homekit-Werte true/false bzw. on/off states gemappt werden. Abkürzung: Wenn nur einer der beiden Werte angegeben wird, werden alle anderen automatisch auf den anderen gemappt. | |||
|- | |||
| timeout || Timeout in ms, nach dem der Homekit-Wert auf den Default-Wert zurückgesetzt wird, verwendet zur Simulation von Tastenkontakten | |||
|} | |||
==Beispiele== | |||
=== Harmony Hub Fernbedienung === | |||
Im Harmony Hub System von Logitech steuert die Fernbedienung Geräte normalerweise nicht direkt per IR, sondern sendet per Funk einen Befehl an den "Harmony Hub", der dies in ein Infrarotsignal umsetzt. Via TCP/IP lässt sich der Hub auch direkt von FHEM aus steuern. Das relevante Reading des "Harmony Hub" trägt die Bezeichnung ''activity'', setzbar sind z.B. die Werte ''activity'' und ''channel''. | |||
=== Fenstersensor === | |||
Ein Fenstersensor liefert für sein ''reading'' state die Werte open oder closed. Homekit unterstützt einen Service "ContactSensor", der allerdings andere Datenwerte kennt. Das Mapping lautet in diesem Fall | |||
attr <meinSensor> homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED | |||
=== Temperatur- und Feuchtesensor === | |||
Kombinierte Temperatur-Feuchtesensoren haben in der Regel ''readings'' "humidity" und "temperature". Homekit unterstützt einen Service "HumiditySensor". Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden): | |||
<code>attr meinSensor genericDeviceType HumiditySensor</code> | |||
Im nächsten Schritt werden die Readings gemappt: | |||
attr <meinSensor> homebridgeMapping clear CurrentRelativeHumidity=humidity CurrentTemperature=temperature | |||
=== Rolladen === | |||
Ein Rolladen ist in Alexa-Fhem nicht auf oder zu, oben oder unten - sondern durch einen Positionswert 0 - 100 (Prozent) gekennzeichnet. Dabei kann je nach physikalischem Device 100% "offen" bedeuten oder "zu" (invertierte Datenwerte). Dem entsprechend muss er auch durch einen solchen Positionswert setbar sein, und zwar muss das zugeordnete Reading entweder ''position'' oder ''pct'' (Abk. für Prozent) heißen. Man kann auch einen entsprechenden Dummy verwenden, etwa | |||
define Alexa.Blind dummy | |||
attr Alexa.Blind alexaName rollladen | |||
attr Alexa.Blind alexaRoom alexaroom | |||
attr Alexa.Blind genericDeviceType blind | |||
attr Alexa.Blind readingList position | |||
attr Alexa.Blind setList position | |||
attr Alexa.Blind stateFormat position | |||
Durch die Auswahl des genericDeviceType=blind werden die beiden Characteristics CurrentPosition und TargetPosition voreingestellt. | |||
Bei den alexaMappings im Alexa-Device muss für die Characteristic TargetPosition vorhanden sein: | |||
TargetPosition=verb=mach:mache,articles=den,values=auf:100;zu:0 | |||
TargetPosition=verb=stell:stelle,valuePrefix=auf,values=AMAZON.NUMBER,valueSuffix=prozent | |||
==== SmartHome Skill ==== | |||
Dieses Mapping wird nun bereits durch den SmartHome Skill von Alexa erkannt. | |||
Konkret sind folgende Alexa-Befehle ausführbar | |||
* "Stell(e) den Rollladen auf xx Prozent" => position wird auf xx gesetzt | |||
* "Mach(e) den Rollladen hoch/runter" => position wird um 25% erhöht / erniedrigt. | |||
==== Custom Skill ==== | |||
'''Achtung: In Bearbeitung''' | |||
* stell {article} {Device} {preposition} {Room} auf {pct} prozent | |||
* mach {article} {Device} {preposition} {Room} {TargetPosition_Value} | |||
Aktuelle Version vom 16. Februar 2021, 09:09 Uhr
Auf dieser Seite soll das Zusammenwirken zwischen Sensoren/Aktoren in FHEM, dem Programm Alexa-Fhem und den Amazon Web Services erläutern.
Glossar
- Aspekte: Die Sensoren/Aktoren von FHEM haben aus der Sichweise von Alexa bestimmte Eigenschaften - diese können "read only" sein,(z.b. die aktuell gemessene Temperatur) oder durch den Benutzer veränderbar (z.b. die gewünschte Raumtemperatur). Um die Mehrdeutigkeit des Begriffs "Eigenschaften" zu vermeiden, werden sie auf dieser Wiki-Seite als Aspekte bezeichnet.
- Characteristic: Dieser Begriff ist der Homekit-Software entlehnt, er bezeichnet einen abfragbaren oder setzbaren Aspekt eines Sensors/Aktors - allerdings in einer abstrakten Sichtweise, die nicht mit der sehr gerätespezifischen Sichtweise von FHEM übereinstimmt. Characteristics sind typischerweise auch mit einem entsprechenden Service verbunden.
- Service: Eine Zusammenfassung mehrerer Characteristics zu einer logischen Gesamtheit, die z.B. mit einem bestimmten abstrakten Gerätetyp verbunden ist. Beispielsweise ist der Service "Door" eine Zusammenfassung der Characteristics "CurrentPosition","PositionState","TargetPosition" sowie optional "HoldPosition","ObstructionDetected","Name".
Attribute der Sensoren/Aktoren
Über zwei Attribute wird die sehr variable Welt von FHEM in einer eher abstrakte und semantisch eindeutigere Zwischenschicht (die Characteristics) überführt und dann mit der Sprachsteuerung verbunden. Dabei wird versucht, dem Benutzer so viel Arbeit wie möglich abzunehmen und die häufigsten Devices so automatisch wie möglich zu erkennen. Erst wo dies nicht ausreicht, ist eine komplett freie Konfiguration möglich. Auf Grund dieses Vorgehens ist die automatische Zuordnung von Characteristics sehr komplex, weil sie je nach Gerät auf Grund von unterschiedlichen Kriterien getroffen wird. Dabei kann es sich handeln um
- das Attribut genericDeviceType
- das INTERNAL TYPE, z.B.
- TYPE = "harmony" -> als genericDeviceType wird automatisch "switch" ausgewählt.
- das Reading temperature bzw. measured-temp
genericDeviceType
Dieses Attribut dient dazu, ohne spezielle Angaben einen bestimmten Service (und somit auch bestimmte Characteristics) auszuwählen und somit Konfigurationsaufwand zu sparen. Das Attribut kann nur wenige verschiedene Werte annehmen, die per Drop-Down-Liste ausgewählt werden können.
Name | Service | Characteristics | Bemerkungen |
---|---|---|---|
security | |||
ignore | |||
switch | |||
outlet | |||
light | |||
blind | blind | CurrentPosition/TargetPosition |
|
thermometer | |||
thermostat | |||
contact | |||
garage | |||
window | |||
lock | lock | LockCurrentState/LockTargetState |
Andere Werte des Attributes können über das Befehlsfeld zugewiesen werden, hiervon wird aber abgeraten, weil diese ggf. in Alexa-Fhem nicht ausgewertet werden.
homebridgeMapping
Das Attribut homebridgeMapping gibt an, welches konkrete FHEM-Reading und bzw. FHEM-Kommando dieses Gerätes mit welchem Aspekt (= abstrakte Eigenschaft) verknüpft ist.
Das Konzept des homebridgeMapping ist hier: https://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 und hier: https://github.com/justme-1968/homebridge-fhem/blob/master/README.md beschrieben.
Dieses Attribut beinhaltet eine durch Leerzeichen getrennte Liste von Datenpaaren, in der einfachsten Form
attr <meinSensor> homebridgeMapping [clear] <Characteristic1>=<FHEM-reading1> <Characteristic2>=<FHEM-reading2> <Characteristic3>=<FHEM-reading3> ...
- Das optionale Schlüsselwort
clear
hat eine besondere Bedeutung: Es löscht Standardmappings - das wird meist nicht notwendig sein, schadet aber nichts - Siehe hierzu die einleitende Bemerkung über Characteristics.
<Characteristic1>=<FHEM-reading1>
verbindet diesen logischen Kanal (linke Seite) mit einem reading des Sensors/Aktors aus FHEM (rechte Seite). Die Liste der vordefinierten Characteristics findet man in Abschnitt Characteristics, und ein <FHEM-reading> kann die komplexere Struktur<command>:<device>:<reading>
haben. - An den Wert des <FHEM-readings> kann eine Liste von Parameter-Wert-Paaren angehängt werden. Dabei sind die einzelnen Paare durch Komma getrennt, mehrere Werte eines Parameters durch ein Semikolon voneinander abgegrenzt. Beispielsweise lässt sich mit dem values-Parameter eine direkte Entsprechung zwischen Werten aus FHEM und Werten aus dem Homekit realisieren. Die Liste der vordefinierten Parameter findet man in Abschnitt Parameter,
Attribute des Alexa-Devices
Im Gegensatz zu Homekit, das die Daten aus den Characteristics bei der Sprachanalyse verwendet, muss dies für Alexa-Fhem im Custom Skill selbst implementiert werden. Hier kommt das Attribut alexaMapping ins Spiel, mit dem festgelegt wird, welches gesprochene Kommando Auswirkung auf welche Characteristic hat.
Im Attribut alexaMapping lassen sich auch zusätzliche Characteristics unterbringen, wenn die bereits definierten nicht ausreichen.
alexaMapping
In diesem Attribut finden wir also die abstrakten Characteristics in Verbindung mit sprachlichen Parametern wieder - und zwar in der allgemeinen Form
Characteristic=<name1>=<value11>[;<value12>]*[,<name2>=<value21>[;<value22>]*]*
<namex>
ist der Name eines Parameters, z.B. verb- Es folgt eine durch Semikolon getrennte Liste von möglichen Werten. Für verb könnte diese z.B. sein
verb=stelle;setze
- Weitere Parameter/Wert-Listen werden durch ein Komma getrennt angehängt, z.B.
verb=stelle;setze,valueOn=an;ein,valueOff=aus
Jede Characteristic kann mehrfach auftauchen - nämlich für jede Aussprachemöglichkeit dieser Characteristic. Beispiele:
On=verb=schalte,valueOn=an;ein,valueOff=aus,valueToggle=um Hue=verb=stelle,valuePrefix=auf,values=rot:0;grün:128;blau:200 Hue=verb=färbe,values=rot:0;grün:120;blau:220
Liste der unterstützten Characteristics und ihrer Parameter
Viele Namen für die Aspekte und Characteristics eines Gerätes entstammen dem Apple Homekit API. Welche Services mit welchen Characteristics es dort gibt ist hier zu finden: https://github.com/homebridge/HAP-NodeJS/blob/master/src/lib/gen/HomeKit.ts
Characteristics
Name | Typ | Parameter und Werte | Standardmapping |
---|---|---|---|
On | Boolean | valueOn, valueOff, cmdOn, cmdOff |
|
ContactSensorState | Integer | CONTACT_DETECTED=0,CONTACT_NOT_DETECTED=1 | value,values=???:CONTACT_DETECTED,???:CONTACT_NOT_DETECTED |
Brightness | |||
Hue | |||
Saturation | |||
CurrentTemperature | |||
TargetTemperature | |||
CurrentPosition | Integer | position oder pct |
|
TargetPosition | Integer | position oder pct |
|
CurrentRelativeHumidity | |||
CurrentAmbientLightLevel | |||
AirQuality | |||
CurrentDoorState | Integer | OPEN=0, CLOSED=1, OPENING=2, CLOSING=3, STOPPED=4 | Mehrere Mappings möglich:
|
TargetDoorState | Integer | OPEN=0, CLOSED=1 |
|
LockCurrentState | Integer | UNSECURED=0, SECURED=1, JAMMED = 2, UNKNOWN = 3 | lock,values=/uncertain/:UNKNOWN,/^locked/:SECURED,/.*/:UNSECURED |
LockTargetState | Integer | UNSECURED=0, SECURED=1 |
|
OccupancyDetected | |||
StatusLowBattery | |||
SecuritySystemCurrentState | |||
SecuritySystemTargetState | |||
FirmwareRevision | |||
alle anderen Homebridge Characteristic |
Parameter
Name | Typ | Parameter |
---|---|---|
values | Dieser Parameter enthält eine durch Semikolon getrennte Liste von Entsprechungen der Form FHEM-Wert:Homekit-Wert . Jeder FHEM-Wert kann ein Literal (String) sein, oder ein Regulärer Ausdruck der Form /regex/. Jeder Homekit-Wert kann ein Literal (String) sein, oder ein für diese Characteristic definierter Term. Wenn als Homekit-Wert ein "#" steht, wird es gleich dem aktuellen Wert gesetzt (Heißt was ???).Achtung: Wegen der nicht konsistenten Vertauschung der Seitenbezüge links-rechts ist das eine sehr gewöhnungsbedürftige Notation.
| |
valueOn, valueOff | Dies sind die FHEM-Werte für boolesche readings, die auf die Homekit-Werte true/false bzw. on/off states gemappt werden. Abkürzung: Wenn nur einer der beiden Werte angegeben wird, werden alle anderen automatisch auf den anderen gemappt. | |
timeout | Timeout in ms, nach dem der Homekit-Wert auf den Default-Wert zurückgesetzt wird, verwendet zur Simulation von Tastenkontakten |
Beispiele
Harmony Hub Fernbedienung
Im Harmony Hub System von Logitech steuert die Fernbedienung Geräte normalerweise nicht direkt per IR, sondern sendet per Funk einen Befehl an den "Harmony Hub", der dies in ein Infrarotsignal umsetzt. Via TCP/IP lässt sich der Hub auch direkt von FHEM aus steuern. Das relevante Reading des "Harmony Hub" trägt die Bezeichnung activity, setzbar sind z.B. die Werte activity und channel.
Fenstersensor
Ein Fenstersensor liefert für sein reading state die Werte open oder closed. Homekit unterstützt einen Service "ContactSensor", der allerdings andere Datenwerte kennt. Das Mapping lautet in diesem Fall
attr <meinSensor> homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED
Temperatur- und Feuchtesensor
Kombinierte Temperatur-Feuchtesensoren haben in der Regel readings "humidity" und "temperature". Homekit unterstützt einen Service "HumiditySensor". Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):
attr meinSensor genericDeviceType HumiditySensor
Im nächsten Schritt werden die Readings gemappt:
attr <meinSensor> homebridgeMapping clear CurrentRelativeHumidity=humidity CurrentTemperature=temperature
Rolladen
Ein Rolladen ist in Alexa-Fhem nicht auf oder zu, oben oder unten - sondern durch einen Positionswert 0 - 100 (Prozent) gekennzeichnet. Dabei kann je nach physikalischem Device 100% "offen" bedeuten oder "zu" (invertierte Datenwerte). Dem entsprechend muss er auch durch einen solchen Positionswert setbar sein, und zwar muss das zugeordnete Reading entweder position oder pct (Abk. für Prozent) heißen. Man kann auch einen entsprechenden Dummy verwenden, etwa
define Alexa.Blind dummy attr Alexa.Blind alexaName rollladen attr Alexa.Blind alexaRoom alexaroom attr Alexa.Blind genericDeviceType blind attr Alexa.Blind readingList position attr Alexa.Blind setList position attr Alexa.Blind stateFormat position
Durch die Auswahl des genericDeviceType=blind werden die beiden Characteristics CurrentPosition und TargetPosition voreingestellt. Bei den alexaMappings im Alexa-Device muss für die Characteristic TargetPosition vorhanden sein:
TargetPosition=verb=mach:mache,articles=den,values=auf:100;zu:0 TargetPosition=verb=stell:stelle,valuePrefix=auf,values=AMAZON.NUMBER,valueSuffix=prozent
SmartHome Skill
Dieses Mapping wird nun bereits durch den SmartHome Skill von Alexa erkannt. Konkret sind folgende Alexa-Befehle ausführbar
- "Stell(e) den Rollladen auf xx Prozent" => position wird auf xx gesetzt
- "Mach(e) den Rollladen hoch/runter" => position wird um 25% erhöht / erniedrigt.
Custom Skill
Achtung: In Bearbeitung
- stell {article} {Device} {preposition} {Room} auf {pct} prozent
- mach {article} {Device} {preposition} {Room} {TargetPosition_Value}