FHEM Tutorial-Reihe - Part 24: Amazon Echo / Alexa FHEM - Custom Skill

Der Smart-Home-Skill über Alexa läuft ja bereits einwandfrei. Allerdings gibt es jetzt die Möglichkeit, alles ein wenig weiter zu treiben, und über die 8 Standard-Skills hinweg zu gehen. Theoretisch ist damit alles möglich.

In diesem Tutorial gehe ich darauf ein, wie man sich den Custom Skill konfiguriert und wie man diesen dann entsprechend erweitert. Das Thema ist leider nicht ganz so einfach wie ersteres, aber dennoch sehr erstrebenswert, da hier die Flexibilität sehr viel höher ist.

Was wird benötigt?

• Ein komplett erledigtes Tutorial 23
• Alles muss so laufen, wie dort im Video gezeigt

Die Basis hier ist jetzt eben alles, was in Tutorial 23 gezeigt wurde. Die dort eingerichteteten Dienste werden nun erweitert und entsprechend konfiguriert. Solltet ihr das nicht umgesetzt haben, klickt bitte ein Video zurück und beginnt dort, ansonsten werdet ihr viele Schritte in diesem Tutorial nicht verstehen.

Video

Im folgenden habe ich noch einmal so gut es geht die einzelnen Dokumentationen aus dem Wiki und dem Forum zusammengetragen, um Euch einen möglichst guten Überblick über die Funktionen zu geben. Diese Dokumentation basiert ebenfalls auf dem Modul von Andre (justme1986) in Version 0.1.9. In neueren Versionen kann die einzelne Konfiguration natürlich abweichen. Ich hoffe allerdings, dass die hier beschriebene Notation gleich bleibt, da man ansonsten immer viel umkonfigurieren muss.

Letztes Update dieses Beitrags ist der 10.10.2017

Eigene Namen und Räume für Alexa

Wenn man sich ein alexa-Gerät angelegt hat, können für alle anderen eigene Namen für alexa Vergeben werden. Das spart uns den Umweg über die Gruppen in der Alexa-Oberfläche und wir können alles lokal an einem Ort verwalten.

define alexa alexa
attr <name> alexaRoom Wohnzimmer
attr <name> alexaName Wohnzimmerlampe

Hierarchie der Namen in Alexa

1. alexaName
2. alias
3. name

Als erstes greift der Name im Attribut alexaName, sollte hier kein Wert hinterlegt sein, hört das Gerät auf seinen alias. Ist hier ebenfalls nichts gepflegt, hört es auf den normalen Gerätenamen. Hat man also schon überall einen sprechenden im Attribut alias, kann man sich dier erneute Vergabe von einem Alexa-Namen sparen. Erst recht, wenn man das gleiche reinschreiben würde.

Generell sind die Geräte natürlich nur ansprechbar, wenn sie sich im entsprechenden Raum zur Filterung (Standard: alexa) befinden

Home-Automation-Skill

“Alexa, schalte <gerät/raum> ein”
“Alexa, schalte <gerät/raum> aus”
“Alexa, stelle <gerät/raum> auf <wert> Prozent”
“Alexa, stelle <gerät/raum> auf <anzahl> Grad”
“Alexa, erhöhe <gerät/raum> um <anzahl> Prozent”
“Alexa, reduziere <gerät/raum> um <anzahl> Prozent”
“Alexa, erhöhe <gerät/raum> um <anzahl> Grad”
“Alexa, reduziere <gerät/raum> um <anzahl> Grad”

Achtung

Folgendes Phänomen: Angenommen es gibt einen Dimmer “Licht” und ein Rollo “Rollo” im Wohnzimmer. Sage man dann: “Alexa, dimme das Licht im Wohnzimmer auf 50%”, geht das Licht auf 50% und das Rollo ebenfalls.

Grund: Es gibt (Stand heute) keine wirklichen Device-Typen, sondern nur Geräte die man schalten kann (bei denen man einen prozentualen Wert ändern, oder eine Temperatur einstellen kann). Die ersten beiden zählen alle als Licht, letzteres als Thermostat. Das ist eine Einschränkung an der man mit dem Home-Automation-Skill aktuell nicht vorbei kommt.

Der Custom-Skill kann das besser!

Custom-Skill

Die Konfiguration erfolgt zweistufig

Die erste Stufe erfolgt über den genericDeviceType und das homebridgeMapping. Hier werden die Devices, Readings und Set-Kommandos einer überschaubaren Anzahl an Geräte-Typen und Kommando-Arten zugeordnet.

Diese sind dann über Siri, und wenn möglich den Alexa-Home-Automation-Skill, direkt verfügbar. Die größte Einschränkung hierbei ist, dass Alexa außer Schaltern (Lampen) und Thermostaten keine weiteren Gerätearten kennt.

Die zweite Stufe erfolgt über das Alexa-Device und ein alexaMapping. Hier werden den möglichen Kommandoarten der Wortlaut und Wertebereiche zugeordnet.

Kommandos sind grundsätzlich wie folgt aufgebaut:

<verb> [<artikel>] (<DEVICE>|<type>) [[<preposition>] <ROOM>] <prefix> <value> <suffix>

Die kleingeschriebenen Platzhalter werden konfiguriert, die großgeschriebenen Platzhalter werden aus FHEM ausgelesen.

Welche gesprochenen Kommandos möglich sein sollen, wird über das Alexa-Device konfiguriert:

attr <alexa> articles der,die,das,den
attr <alexa> prepositions in,im,in der

Die Service-Types (Gerätetypen) werden so Deutschen Worten zugeordnet:

attr <alexa> alexaTypes light:licht,lampe,lampen blind:rolladen,jalousie,rollo Outlet:steckdose TemperatureSensor:thermometer,temperatur

Generell werden im alexaMapping die gleichen Characteristics wie in der Homebridge verwendet. Welche das genau sind, steht in dieser Anleitung unter Homebridge Characteristics.

Wenn man z.B. sagen möchte “schalte die Lampe ein”, wäre schalte das Verb, die der Artikel, Lampe das Device und ein der Wert.

Das Ein- und Ausschalten über die Kommandos schalte xyz an, schalte xyz ein und schalte xyz aus würde man so als alexaMapping konfigurieren:

attr <alexa> alexaMapping On=verb=schalte,valueOn=an;ein,valueOff=aus,valueToggle=um

Hier konfiguriert man nur die Zurodnung zu Worten. Also welches Wort gesprochen werden muss, um den valueOn, valueOff oder valueToggle auszuführen. Sagt man also “schalte xyz an/aus/um”, meint man damit jetzt immer ein Gerät der Homebridge-Characteristic “On” - also einen einfachen Schalter. Hier ergibt die Kombination des gesamten Satzes allerdings erst die entsprechende Characteristic.

Die Helligkeit einer Lampe mit stelle xyz auf n Prozent zu steuern würde man so konfigurieren:

attr <alexa> alexaMapping Brightness=verb=stelle,valuePrefix=auf,values=AMAZON.NUMBER,valueSuffix=prozent

Um die Farbe einer Lampe einzustellen, könnte man folgendes konfigurieren:

attr <alexa> alexaMapping Hue=verb=stelle,valuePrefix=auf,values=rot:0;grün:128;blau:200
attr <alexa> alexaMapping Hue=verb=färbe,values=rot:0;grün:128;blau:200

Den Worten rot, grün und blau wird ein passender hue-Wert zugeordnet, der dann im Set-Kommando an FHEM verwendet wird. Damit kann man dann sagen stelle die Lampe auf rot oder färbe die Lampe blau. Wie genau die Lampe dann angesteuert wird, d.h. welches set Kommando und ob per hsv, rgb oder auf eine andere Weise, ist im homebridgeMapping für jedes device festgelegt. Man kann also mit einem färbe die Lampen im Wohnzimmer auch mehrere Lampen, die unterschiedlich angesteuert werden, auf ein mal steuern.

Um einen Rolladen mit mach den Rolladen im Schlafzimmer auf zu steuern:

attr <alexa> alexaMapping TargetPosition=verb=mach,values=auf:100;zu:0

Wenn man sein Rolläden zusätzlich noch mit stelle den Rolladen im Wohnzimmer auf 15 % steuern möchte:

attr <alexa> alexaMapping TargetPosition=verb=stelle,valuePrefix=auf,values=AMAZON.NUMBER,valeuSuffix=prozent

Hier muss man darauf achten, dass man bei Verwendung des gleichen Verbs wie zum Lampe dimmen auch den gleichen Wertebereich und Suffix verwendet.

Ein stelle die Heizung im Wohnzimmer auf 19 Grad würde so aussehen:

attr <alexa> alexaMapping TargetTemperature=verb=stelle,valuePrefix=auf,values=AMAZON.NUMBER,valueSuffix=grad

Achtung: In den alexaTypes dürfen keine Leerzeichen um die Kommas stehen.

Aus den so konfigurierten Möglichkeiten baut das Alexa-Device dann das Interaction Model für die Skill-Konfiguration inklusive der möglichen permutationen von Device-, Typ- und Raumnamen zusammen. **Diese muss dann von Hand dort eingetragen und aktiviert werden.

get <alexa> interactionModel
get <alexa> customSlotTypes

Wichtig

• keine Intelligenz, keine Semantik. Nur ein Mustervergleich -> funktioniert trozdem recht gut
• Nicht alle Kombinationen sinnvoll (vermutlich egal, so lange sie nicht verwendet werden)
• Alexa ist bei Deutschen zahlen noch nicht besonders gut
• Man kann ein Kommando jeweils auf einen bestimmten Raum einschränken
• Statt einem Gerätenamen (alexaName, alias, name) kann man auch die Geräteart (alexaType) verwenden
• Es gibt eine Reihe von voreingestellten Kommandos

Wenn Amazon-Lex in Deutschland verfügbar ist, kann man mit Hilfe dieser Konfiguration die Lex-Konfiguration erzeugen.

Einen Custom-Skill muss man über den konfigurierten Invocation-Name (z.B. FHEM) plus “sage, starte oder frage” für diesen Skill ansprechen. Also entweder Alexa, sage FHEM, schalte das Licht in der Küche an oder Alexa, starte FHEM, schalte das Licht in der Küche an.

In diesem Video haben wir den Invocation-Name auf “Wohnung” gesetzt. Das heißt, dass wir Befehle für den Custom-Skills immer mit Alexa, sage Wohnung, oder mit Alexa, starte Wohnung, beginnen müssen. Daher ist ratsam, hier einen Namen zu nehmen, der Euch nicht auf Dauer nervt und den man gut sagen kann. Wohnung ist mir auf Dauer zum Beispiel viel zu lang. Abkürzungen funktionieren dagegen nicht immer besonders gut. Hier muss man ein wenig probieren.

Über den Invocation-Name wird das, was du sagst, mit dem Skill der es bearbeiten soll verknüpft. Nur ein Home-Automation-Skill (und direkt eingebaute Funktionalität) braucht keinen Invocation-Name. Dafür kann man hier aber auch nicht konfigurieren, was Alexa verstehen soll. Es gibt dann nur die 8 fest vorgegebenen Kommandos (siehe oben unter Smart-Home-Skill).

Generelle Infos

Es gibt keinen Grund nicht den Home-Automation- und den Custom-Skill parallel zu nutzen.

Für den Home-Automation-Skill ist die oauthClientID “zuständig” und für den Custom-Skill die applicationId in der Konfiguration. Das habe ich anfangs auch falsch verstanden und ebenfalls die applicationId des Smart-Home-Skills eingetragen - das ist zwar nicht schlimm, aber total überflüssig.

Homebridge-Mapping

Entscheident dafür, was das einzelne Gerät am Ende macht ist das homebridgeMapping eines jeden Gerätes. Das kommt einem zum einem jetzt ein wenig komisch vor, da man eventuell noch gar kein HomeKit/Siri verwendet (erkläre ich in Video 16), aber macht am Ende schon Sinn. Warum sollte man das Rad neu erfinden, wenn doch schon alles vorhanden ist.

Läuft Dein Siri also schon perfekt mit allen Möglichkeiten, sparst Du Dir hier jede Menge Arbeit, die Du bereits getan hast. Es wäre nervig, jetzt noch einmal alles auf eine andere Art mappen zu müssen. Was einem anfangs eventuell komisch vorkommt, ist eigentlich aber eine enorme Ersparnis an Pflegeaufwand, wenn man beide Dienste parallel betreibt.

attr <device> homebridgeMapping [clear] <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...

• <Characteristic-n> ist hierbei ein in HomeKitTypes.js deklarierer Name einer Characteristic
• <param-n> kann entweder <command>:<device>:<reading> oder <name>=<value> oder das Schlüsselwort “clear” sein
• <value> kann entweder ein Wert oder eine mit ; (Semikolon) unterteilte Liste sein

Das optionale Schlüsselwort “clear” hat eine besondere Bedeutung: Es löscht die Standardmappings - das wird meist nicht notwendig sein, schadet aber nichts

attr <name> homebridgeMapping On:<hub>:activity,cmdOn=command.Kanal1
attr <name> homebridgeMapping On=state,cmdOn=on,cmdOff=off
attr <name> homebridgeMapping Brightness=Volume,cmd=volume

• On ist die Characteristic (Eigenschaft) die einen Schalter beschreibt der on und off versteht
• <hub>:activity gibt an, dass es um das Reading activity vom Harmony-Hub geht. Das Reading ist eigentlich wichtig um in Homekit/Alexa den aktuellen Status anzeigen zu können. Der Smart-Home-Skill kann das nicht, den Custom-Skill wird man danach fragen können. Aktuell ist hier nur <hub> relevant
• cmdOn ist das Kommando das gesendet werden soll, wenn eingeschaltet wird

Homebridge Characteristics

• On (Boolean -> valueOn, valueOff, cmdOn, cmdOff)
• ContactSensorState (Integer -> CONTACT_DETECTED = 0, CONTACT_NOT_DETECTED = 1)
• Brightness
• Hue
• Saturation
• CurrentTemperaure
• TargetTemperature
• CurrentRelativeHumidity
• CurrentAmbientLightLevel
• AirQuality
• CurrentDoorState (Integer -> OPEN = 0, CLOSED = 1, OPENING = 2, CLOSING = 3, STOPPED = 4)
• TargetDoorState (Integer -> OPEN = 0, CLOSED = 1)
• LockCurrentState (Integer -> UNSECURED = 0, SECURED = 1, JAMMED = 2, UNKNOWN = 3)
• LockTargetState (Integer -> UNSECURED = 0, SECURED = 1)
• OccupancyDetected
• StatusLowBattery
• SecuritySystemCurrentState
• SecuritySystemTargetState
• FirmwareRevision

Die folgenden Parameter-Namen sind für die Richtung von Homebridge zu FHEM möglich:

• delay: true/<number> -> der Wert wird nach <number>ms Inaktivität an FHEM gesendet. true -> 1000.
• maxValue: maximal Wert in HomeKit
• max: Maximalwert in FHEM, wenn er von maxValue abweicht
• invert: invertiert den HomeKit-Wert
• cmd: das set-Kommando das verwendet werden soll: set <device> <cmd> <value>
• cmdOn, cmdOff: die Kommandos die für on/off bzw. true/false verwendet werden sollen
• cmdLock, cmdUnlock, cmdOpen: die Kommandos zum Verschließen, Aufschließen und Öffnen einer Tür
• cmds: eine mit ; (Semikolon) unterteilte list aus <von>:<nach> Werte-Paaren die das mapping von HomeKit-Werten auf FHEM-Kommandos beschreibt:
• von> kann ein Wert oder eine in HomeKitTypes.js deklarierte Konstante der Characteristic sein
• <nach> ist das zu verwendende set Kommando

Wichtig

• Leerzeichen in Kommandos müßen durch + ersetzt werden
• Die Reihenfolge der Transformationen ist: invert, max/maxValue
• der Vorrang der Kommando-Mappings ist in aufsteigender reihenfolge: cmd, cmdOn/cmdOff, cmds