Alexa und Mappings

Aus FHEMWiki

Auf dieser Seite soll das Zusammenwirken zwischen Sensoren/Aktoren in FHEM, dem Programm Alexa-Fhem und den Amazon Web Services erläutern.

Glossar

  • Charakteristik oder Characteristic: Dieser Begriff ist der Homekit-Software entlehnt, er bezeichnet einen durch die Sprachsteuerung abfragbaren oder setzbaren Aspekt eines Sensors/Aktors.
  • 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.

Attribute der Sensoren/Aktoren

über zwei Attribute mit der Sprachsteuerung verbunden. kurz: sowohl homebridge-fhem als auch alexa-fhem gehen davon aus das geräte bestimmte eigenschaften haben. diese eigenschaften können

d.h. über die genericDeviceType und homebridgeMapping attribute wird die sehr variable FHEM welt (device abhängige readings und set kommandos mit unterschiedlichen namen) in eine eher abstrakte und semantisch eindeutigere zwischenschicht überführt (fest definierte characteristics mit festen eigenschaften).

homebridge-fhem und alexa-fhem versuchen die häufisgten devices so automatisch wie möglich zu erkennen. wo dies nicht ausrecht ist eine komplett freie konfiguration möglich. 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.

genericDeviceType

Dieses Attribut dient dazu, ohne spezielle Angaben eine bestimmte Characteristic auszuwählen. Das Attribute kennt standardmäßig nur wenige Werte, die per Drop-Down-Liste ausgewählt werden können.

Name Characteristic
security
ignore
switch
outlet
light
blind
thermometer
thermostat
contact
garage
window
lock LockCurrentState/LockTargetState

Andere Werte müssen über das Befehlsfeld zugewiesen werden: attr meinSensor genericDeviceType <meinDeviceType> TODO: Macht eher wenig Sinn, weil diese iN Alxea-Fhem nicht ausgewertet werden ???

homebridgeMapping

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

HomebridgeMapping

da die homekit anbindung zuerst da war und das konzept gut funktioniert kommen die namen für die eigenschaften (characteristics) die ein gerät hat direkt aus dem apple homekit api. ebenso ungereimtheiten wie LockTargetState vs. TargetDoorState. welche services mit welchen characteristics es dort gibt ist hier zu finden: https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

alexaMapping

In diesem Attribut finden wir die abstrakten Characteristics 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

Characteristics

Name Typ Parameter Standardmapping
On Boolean valueOn, cmdOn, cmdOff
Brightness
Hue
Saturation
CurrentTemperaure
TargetTemperature
CurrentRelativeHumidity
CurrentAmbientLightLevel
AirQuality
CurrentDoorState Aufzählungstyp 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 state,values=???:OPEN,???:CLOSED

Wenn es sich um eine KeyMatic handelt, also das Attribut model den Wert hat, oder genericDeviceType den Wert "lock" hat:
???,default:CLOSED,timeout:500,cmds=OPEN:open

LockCurrentState Aufzählungstyp lock,values=/uncertain/:UNKNOWN,/^locked/:SECURED,/.*/:UNSECURED
LockTargetState Aufzählungstyp Wenn es sich um eine KeyMatic handelt, also das Attribut model den Wert hat:

state,values=/^locked/:SECURED,/.*/:UNSECURED,cmds=SECURED:lock;UNSECURED:unlock
Wenn genericDeviceType den Wert "lock" hat:
state,values=/^locked/:SECURED,/.*/:UNSECURED,cmds=SECURED:lock+locked,UNSECURED:lock+unlocked

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

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