FHEMWiki - Benutzerbeiträge [de]

Hue

2022-12-11T18:00:51Z

Justme: /* Spezielle Konfigurationsmöglichkeiten */

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge 192.168.0.123</code>
wird die Bridge eingebunden. (Die IP-Adresse gegen die der HUE Bridge ersetzen oder den DNS Namen.) Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

Das HUEBridge Modul erkennt, wenn ein Leuchtmittel zwischen einer Hue und einer deCONZ Bridge (oder umgekehrt) wechselt und verschiebt das zugehörige HUEDevice in FHEM jeweils zum richtigen Bridge-Device. D.h. wenn z.B. zum Firmwareupdate die Bridge gewechselt wird, ist auf FHEM Seite nichts weiter zu tun.

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

=== Spezielle Konfigurationsmöglichkeiten ===
Zur Syntax der nachfolgenden Attribute (für widgets) siehe {{Link2Forum|Topic=119298|LinkText=
Patchvorschlag im Forum}}
==== setList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''setsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=118788|LinkText=
Eurotonics Spirit bzw. MOES Thermostat}}
* [https://forum.fhem.de/index.php/topic,11020.msg1192888.html#msg1192888 HueLabs Scene aus FHEM über die HUEBridge ein- und ausschalten]

==== configList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''configsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=115102|Message=1093876|LinkText=Aqara motion sensor - duration}}
* {{Link2Forum|Topic=111887|Message=1064164|LinkText=Aqara vibration sensor - sensitivity}}
* [https://forum.fhem.de/index.php/topic,130869.msg1250786.html#msg1250786 Hue Bewegungsmelder - aktivieren, empfindlichkeit und mehr]

==== weiter Konfigurationsmöglichkeiten ====
Device spezifische Kommandos hinzufügen - [https://forum.fhem.de/index.php/topic,11020.msg1193583.html#msg1193583 effect] , [https://forum.fhem.de/index.php/topic,125676.msg1208041.html#msg1208041 startup]

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ in einer Proxmox-VM ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</syntaxhighlight>
:oder
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</syntaxhighlight>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<syntaxhighlight lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</syntaxhighlight>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<syntaxhighlight lang="bash">
qm set 804 -usb0 host=0403:6015
</syntaxhighlight>

* Installation von deCONZ:
:<syntaxhighlight lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</syntaxhighlight>

=== Installation von deCONZ in einem Proxmox LXC-Container ===

[[Conbee/deCONZ im Proxmox LXC-Container (Tutorial)]]

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

=== Installation von deCONZ auf einem RaspberryPI ===
Für den ConBee2 [https://phoscon.de/en/conbee2/install#raspbian kann der guten Installation von Phoscon gefolgt werden]. Entweder ihr installiert deCONZ direkt (wie hier beschrieben) oder über einen Docker Container. Der Docker Container hat ein paar Einschränkungen bzgl. Firmware Updates.

Der ausführende Benutzer muss dialout Rechte haben um auf /dev/tty* zugreifen zu dürfen:
:<syntaxhighlight lang="bash">
sudo gpasswd -a pi dialout
</syntaxhighlight>
Im Standard wird deCONZ mit dem pi-Benutzer (user id 1000) ausgeführt.

Das deCONZ Repository bei APT hinzufügen (Vorteil davon ist dass später ganz normal mit sudo apt update/upgrade deCONZ aktualisieren könnt):
:<syntaxhighlight lang="bash">
wget -O - http://phoscon.de/apt/deconz.pub.key | \
sudo apt-key add -;
sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
$(lsb_release -cs) main' > \
/etc/apt/sources.list.d/deconz.list";
sudo apt update
</syntaxhighlight>

Mit der Einführung des Raspberry Pi 3 sind noch weitere Einstellungen notwendig. Diese sind hier: [[Raspberry Pi 3: GPIO-Port Module und Bluetooth|Raspberry Pi 3: GPIO-Port Module und Bluetooth – FHEMWiki]] ausführlich beschrieben.

deCONZ installieren:
:<syntaxhighlight lang="bash">
sudo apt install deconz
</syntaxhighlight>
Wenn ihr euren RaspberryPI mit UI betreibt, kann deCONZ über ''Menu > Programming > deCONZ'' aufgerufen werden. Es gibt aber auch den Service-Modus, der ohne X11 funktionert. Hierfür die Datei ''/lib/systemd/system/deconz.service'' anpassen (ich habe z.B. den Port des Webservers geändert) und den Service wie folgt aktivieren:
:<syntaxhighlight lang="bash">
systemctl enable deconz.service
</syntaxhighlight>

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom lib-Verzeichnis nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

Hue

2022-12-11T17:47:34Z

Justme: /* configList */

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge 192.168.0.123</code>
wird die Bridge eingebunden. (Die IP-Adresse gegen die der HUE Bridge ersetzen oder den DNS Namen.) Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

Das HUEBridge Modul erkennt, wenn ein Leuchtmittel zwischen einer Hue und einer deCONZ Bridge (oder umgekehrt) wechselt und verschiebt das zugehörige HUEDevice in FHEM jeweils zum richtigen Bridge-Device. D.h. wenn z.B. zum Firmwareupdate die Bridge gewechselt wird, ist auf FHEM Seite nichts weiter zu tun.

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

=== Spezielle Konfigurationsmöglichkeiten ===
Zur Syntax der nachfolgenden Attribute (für widgets) siehe {{Link2Forum|Topic=119298|LinkText=
Patchvorschlag im Forum}}
==== setList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''setsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=118788|LinkText=
Eurotonics Spirit bzw. MOES Thermostat}}
* [https://forum.fhem.de/index.php/topic,11020.msg1192888.html#msg1192888 HueLabs Scene aus FHEM über die HUEBridge ein- und ausschalten]

==== configList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''configsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=115102|Message=1093876|LinkText=Aqara motion sensor - duration}}
* {{Link2Forum|Topic=111887|Message=1064164|LinkText=Aqara vibration sensor - sensitivity}}
* [https://forum.fhem.de/index.php/topic,130869.msg1250786.html#msg1250786 Hue Bewegungsmelder - aktivieren, empfindlichkeit und mehr]

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ in einer Proxmox-VM ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</syntaxhighlight>
:oder
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</syntaxhighlight>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<syntaxhighlight lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</syntaxhighlight>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<syntaxhighlight lang="bash">
qm set 804 -usb0 host=0403:6015
</syntaxhighlight>

* Installation von deCONZ:
:<syntaxhighlight lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</syntaxhighlight>

=== Installation von deCONZ in einem Proxmox LXC-Container ===

[[Conbee/deCONZ im Proxmox LXC-Container (Tutorial)]]

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

=== Installation von deCONZ auf einem RaspberryPI ===
Für den ConBee2 [https://phoscon.de/en/conbee2/install#raspbian kann der guten Installation von Phoscon gefolgt werden]. Entweder ihr installiert deCONZ direkt (wie hier beschrieben) oder über einen Docker Container. Der Docker Container hat ein paar Einschränkungen bzgl. Firmware Updates.

Der ausführende Benutzer muss dialout Rechte haben um auf /dev/tty* zugreifen zu dürfen:
:<syntaxhighlight lang="bash">
sudo gpasswd -a pi dialout
</syntaxhighlight>
Im Standard wird deCONZ mit dem pi-Benutzer (user id 1000) ausgeführt.

Das deCONZ Repository bei APT hinzufügen (Vorteil davon ist dass später ganz normal mit sudo apt update/upgrade deCONZ aktualisieren könnt):
:<syntaxhighlight lang="bash">
wget -O - http://phoscon.de/apt/deconz.pub.key | \
sudo apt-key add -;
sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
$(lsb_release -cs) main' > \
/etc/apt/sources.list.d/deconz.list";
sudo apt update
</syntaxhighlight>

Mit der Einführung des Raspberry Pi 3 sind noch weitere Einstellungen notwendig. Diese sind hier: [[Raspberry Pi 3: GPIO-Port Module und Bluetooth|Raspberry Pi 3: GPIO-Port Module und Bluetooth – FHEMWiki]] ausführlich beschrieben.

deCONZ installieren:
:<syntaxhighlight lang="bash">
sudo apt install deconz
</syntaxhighlight>
Wenn ihr euren RaspberryPI mit UI betreibt, kann deCONZ über ''Menu > Programming > deCONZ'' aufgerufen werden. Es gibt aber auch den Service-Modus, der ohne X11 funktionert. Hierfür die Datei ''/lib/systemd/system/deconz.service'' anpassen (ich habe z.B. den Port des Webservers geändert) und den Service wie folgt aktivieren:
:<syntaxhighlight lang="bash">
systemctl enable deconz.service
</syntaxhighlight>

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom lib-Verzeichnis nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

FHEM Connector für Amazon Alexa

2022-06-23T17:22:12Z

Justme: /* Was geht alles ? */

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf einem Zufallsport auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" oder höher vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

'''Anmerkung:''' diese Aussage bzgl. node-Version (und Jessie/Stretch) stimmt wohl für alexa-fhem Stand heute (12.06.2020) nicht mehr, siehe https://forum.fhem.de/index.php/topic,112025.msg1063218.html#msg1063218

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.

===== 401: Authorization Required =====

Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

===== Permission denied =====

Wenn du folgende Fehlermeldungen im Alexa Logfile siehst, wurde das Verzeichnis "/opt/fhem/.ssh/" von dir bei der Arbeit mit "root" oder "sudo" mit den falschen Berechtigungen versehen:

<syntaxhighlight lang="bash" style="width:90%;">
[2019-7-25 11:59:12] sshautoconf: aborted with ssh-keygen returned error - key_save_private: Permission denied
[2019-7-25 11:59:12] *** SSH: proxy configuration failed: ssh-keygen returned error - key_save_private: Permission denied
</syntaxhighlight>

Prüfen kannst du die Berechtigungen mit folgendem Befehl auf der Shell-Konsole:

<syntaxhighlight lang="bash" style="width:90%;">
ls -l /opt/fhem/.ssh
</syntaxhighlight>

Du solltest dann folgende Ausgabe erhalten:

<syntaxhighlight lang="bash" style="width:90%;">
insgesamt 12
-rw------- 1 fhem dialout 1675 Jul 12 13:10 id_rsa
-rw-r--r-- 1 fhem dialout 391 Jul 12 13:10 id_rsa.pub
-rw-r--r-- 1 fhem dialout 884 Jul 12 13:10 known_hosts
</syntaxhighlight>

Steht in der Ausgabe nicht "fhem dialout" (dein fhem User), sondern bspw. "root root", dann bspw. mit folgendem Befehl an deinen fhem User anpassen:

<syntaxhighlight lang="bash" style="width:90%;">
chown fhem:dialout /opt/fhem/.ssh
</syntaxhighlight>

Mit dem ersten Befehl "ls -l ..." kannst du dann nochmal prüfen, ob die Berechtigungen korrekt übernommen wurden.

===== weitere Prüfungen =====

Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</code>, oder über den Namen bei ''currentlogfile'' in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Mehrere Namen für dasselbe Gerät/Device in fhem werden unterstützt. Mehrere Namen werden durch Strichpunkt getrennt<ref>Feature nicht dokumentiert {{Link2Forum|Topic=74041|LinkText=Forumsthread}}</ref>.
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!
[[Datei:HowToSet alexaName.png|alternativtext=How to set alexaName|ohne|mini|Wie setzt man das Attribut alexaName]]

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

 '''Mehrere Namen für dasselbe Gerät/Device in fhem sind möglich.''' 
Die Namen werden durch <s>Strichpunkt</s> Komma getrennt. 
Beispiel: 
<code>attr dmLampe alexaName Lichtkuppel,Lichtkugel</code>

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: homebridgeMapping On:cmdOn=<ein>,cmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus
* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading <code>temperature</code> geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: homebridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus: homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>
** Kommandos:
*** Alexa, mache <name> heller/dunkler
*** Alexa, Licht heller/dunkler
* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** homebridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** homebridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** homebridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** homebridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** homebridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** homebridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** homebridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** homebridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

* Alarmmelder (noch nicht in Deutschland):
** genericDeviceType Security
** homebridgeMapping Alarm=<reading>[,type=[fireAlarm|waterAlarm|burglaryAlarm|carbonMonoxideAlarm]]
** wenn der type nicht angegeben wird ist fireAlarm der default
** automatisch werden 0, ok und alles was mit no anfängt als OK erkannt. alles andere gilt als ALARM.
*Geräte mit mehrstufigen Modi:
**siehe den zugehörigen Thread im Forum: {{Link2Forum|Topic= 125604}}

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.

==== Dummygeräte: ====
Ein Dummydevice sollte einen Kontaktschalter oder Bewegungssensor simulieren, um dann in FHEM eine beliebige Bedingung als Trigger zu definieren, und eine freie Ansage in Alexa als Routine zu definieren. Hier ein Beispiel:

<syntaxhighlight lang="bash" style="width:90%;">
define voicetrigger1 dummy
attr voicetrigger1 alexaName alle Fenster
attr voicetrigger1 alexaProactiveEvents 1
attr voicetrigger1 genericDeviceType contact
attr voicetrigger1 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED
attr voicetrigger1 setList open closed

set alexa add voicetrigger1
set alexa restart
</syntaxhighlight>

'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

== Bug- und Wunschliste ==
* Ist beim Start keine Internetverbindung vorhanden, erfolgt kein Retry -- alexa-fhem muss restartet werden (ssh_autoconfig wertet keine temporären Fehler aus)

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

==Hinweise==
<references />

Color

2022-03-10T12:37:51Z

Justme: /* Farbton */

{{Infobox Modul
|ModPurpose=Hilfsfunktionen zur modulübergreifenden Benutzung von Farben.
|ModType=h
|ModCmdRef=intro 
|ModForumArea=Sonstiges
|ModTechName=Color.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])}}

[[Color]] soll modulübergreifend Funktionen bereitstellen, die die Interaktion mit farbigen Lampen erleichtern. Es wird zur Zeit von [[Hue|HUEDevice]] und dem [[panStamp#Section SWAP_0000002200000003|SWAP RGB Driver]] Modul sowie von FRM_RGB und PHTV und verwendet.

== Benutzung ==
Um die im Folgenden beschriebenen Funktionen zu nutzen, muss die Datei Color.pm eingebunden werden. Ein Modulautor kann das durch eine
:<code>use Color;</code>
Anweisung in seinem Modul tun. Ein Endanwender mit einem notify:
:<code><nowiki>define colorInit notify global:INITIALIZED {use Color}</nowiki></code>

== Colorpicker ==
[[Datei:SWAP_0000002200000003.png|thumb|Colorpicker und Presets]]
Der colorpicker stellt ein FHEM-Web Widget bereit, das es ermöglicht, in der webCmd Liste interaktiv eine Farbe einzustellen oder fest definierte presets zur Auswahl zu stellen. Hierzu sind je nach reading folgende Schritte nötig:

=== RGB Farbe ===
* Ein entsprechendes Kommando, das den colorpicker verwendet, in der 'set ?' liste des Moduls vorsehen (oder eines mit widgetOverride überschreiben):
:<code>... <rgb>:colorpicker,RGB ...</code>

Nun lässt sich das Kommando ''rgb'' auf zwei Arten in der webCmd Liste verwenden:
* ohne Parameter: um ein interaktives Eingabefeld für einen RGB-Farbwert einzublenden
* mit einem RGB-Wert als Parameter, um einen festen Preset einzublenden
:<code>attr <device> webCmd rgb:rgb ff0000:rgb 00ff00:rgb 0000ff:toggle:on:off</code>

Bei jedem Seitenaufbau wird der Wert zum Initialisieren des colorpicker aus dem Reading mit dem gleichen Namen wie das set-kommando geholt.

=== RGB als HSV ===
[[Datei:Colorpicker_HSV.png|mini|rechts|350px|Colorpicker im HSV Modus]]
Eine RGB Farbe lässt sich alternativ auch über den HSV Mode einstellen. Hierbei werden untereinander jeweils ein Schieberegler für Farbton, Sättigung und Helligkeit dargestellt.
... rgb:colorpicker,HSV ...
attr <device> webCmd rgb

Alternativ lässt sich als Mode statt <code>HSV</code> auch <code>HSVp</code> verwenden. Dann werden die Schieberegler bei einem Klick auf das Widget in einem Popup-Fenster eingeblendet.

=== echtes HSV ===
Wenn das Device kein RGB Reading und Kommando hat aber ein HSV Reading und drei Kommandos um Farbton, Sättigung und Helligkeit einzustellen lässt sich die folgende Variante verwenden:
... hsv:colorpicker,HSV,hue,0,1,360,sat,0,1,100,bri,0,1,100 ...
d.h. es wird nach dem <code>HSV</code> oder <code>HSVp</code> Schlüsselwort für jedes der drei Kommandos der Name und der wertebereich mit Komma getrennt angegeben. Falls es im Device das nötige Reading mit den aktuellen Werten nicht gibt lässt sich dieses mit einem user reading z.B. wie folgt erzeugen:
attr <device> userReadings hsv {ReadingsVal($name,'hue','0').','.ReadingsVal($name,'sat','100').','.ReadingsVal($name,'bri','100')}

=== Farbtemperatur ===
Der colorpicker lässt sich auch für die Farbtemperatur (ct, in Kelvin oder Mired) verwenden. Hier ein Beispiel für die Set-Liste eines ct Kommandos mit erlaubten Werten von 2000 bis 6500 Kelvin und eine webCmd Definition mit ct slider und 4 ct Presets.
... ct:colorpicker,CT,2000,10,6500 ...
attr <device> webCmd ct:ct 2040:ct 2630:ct 3703:ct 6250:on:off

=== Farbton ===
[[Datei:Colorpicker_webCmd.png|mini|rechts|400px|Colorpicker im CT, HUE und RGB-Preset Modus]]

In der aktuellen Version lässt sich der colorpicker auch für den Farbton (hue) verwenden (ab 11.03.2022 auch mit presets):

... hue:colorpicker,HUE,0,1,359 ...
attr <device> webCmd hue:rgb:rgb ff0000:rgb 00ff00:rgb 0000ff:rgb ffffff:on:off

=== Helligkeit ===
[[Datei:Colorpicker_bri.png|mini|rechts|400px|Colorpicker im BRI Modus]]

In der aktuellen Version lässt sich der colorpicker auch als Slider der mit einem Graukeil hinterlegt ist verwenden um z.b. die Helligkeit (bri,pct,...) einzustellen:
... pct:colorpicker,BRI,0,1,100 ...
attr <device> webCmd pct:toggle:on:off

Die Slider für Farbtemperatur, Farbton und Helligkeit sind jeweils mit einem passenden Hintergrund hinterlegt.

== Farbige Lampen Icons ==
Die Funktion Color_devStateIcon($) erzeugt aus einem übergebenen RGB Wert in der Form "RRGGBB" einen devStateIcon String für farbige SVG Icons (die bunten Blobs werden noch nicht unterstützt). Der Aufruf kann z.B. so zum Setzen des devStateIcons verwendet werden:
:<code>attr <device> devStateIcon {Color_devStateIcon(ReadingsVal($name,"rgb","000000"))}</code>
oder
:<code>attr <device> devStateIcon {Color_devStateIcon(CommandGet(undef,"$name rgb"))}</code>

'''NEU:'''
Im Namespace Color gibt es eine zweite, experimentelle Version einer devStateIcon Funktion. Diese unterstützt neben farbigen Lampen auch Dimmer und Schalter. Hier muss der Name (oder hash) des FHEM-Device, ein String der den Typ der Lampe festlegt und bis zu drei Namen von Readings, die den RGB-Wert, die aktuelle Helligkeit im Bereich 0-100 und den Ein/Aus Status enthalten. Also:
:<code><nowiki>Color::devStateIcon( <name|hash>, <type>, <rgb reading>, <percent reading>, <on/off reading> );</nowiki></code>

In <code>type</code> kann zur Zeit <code>rgb</code>, <code>dimmer</code> oder <code>switch</code> übergeben werden. Im Reading für die Helligkeit wird neben den Werten 0-100 auch <code>on</code> und <code>off</code> verstanden.

Ein Beispiel für eine Lampe, die im Reading <code>rgb</code> die aktuell eingestellte Farbe und im Reading <code>state</code> on oder off enthalten kann:
:<code><nowiki>attr meineLampe devStateIcon {Color::devStateIcon($name,"rgb","rgb","state")}</nowiki></code>

Um z.B. einen WeekdayTimer, der eine Lampe steuert, mit einem passenden Icon zu versehen, könnte man folgendes verwenden:
:<code><nowiki>attr FlurTimer devStateIcon {Color::devStateIcon($name,"dimmer",undef,"state")}</nowiki></code>
[[Datei:Colorpicker_devStateIcons.png|mini|rechts|400px|Beispiel mit Nutzung der unterschiedlichen Möglichkeiten]]
Das Icon des WeekdayTimer stellt dann den Zustand dar, mit dem die Lampe aktuell über den Timer gesteuert wird. Nicht den aktuellen Zustand der Lampe, die ja auch anderweitig gesteuert werden kann.

'''ToDo''': Bestimmen der Helligkeit über den RGB-Wert, wenn kein Reading dafür angeben ist.

'''Fragen''':
* Ist es für das Interface besser, jeweils direkt die Werte zu übergeben oder die Namen der Readings in denen die Werte zu finden sind?
* Sollte angegeben werden können, welchen Wertebereich die Helligkeit haben kann?

Zwei Beispiele für die Verwendung und Kombination der oben beschriebenen Routinen gibt es in der fhem.cfg.demo im Simulator für farbige Lanpen.

== Routinen um zwischen Farbräumen und Darstellungen zu konvertieren ==
Color::rgb2hsv
Color::hsv2rgb
Color::hsb2rgb
Color::rgb2hsb
Color::hex2hsv
Color::hsv2hex
Color::hex2hsb
Color::hsb2hex
Color::hex2rgb
Color::rgb2hex
Color::ct2rgb
Color::xyY2rgb
Color::xyY2hex

== Farbskala mit Color::pahColor ==
Das auf der Seite [[Temperaturfarbe]] beschriebene Verfahren ist über die Routine <code>Color::pahColor</code> verfügbar, siehe auch {{Link2Forum|Topic=30128|LinkText=diesem Beitrag im FHEM Forum}}.

:<code><nowiki>Color::pahColor($starttemp,$midtemp,$endtemp,$temp,$colors,$opacity)</nowiki></code>

<code>$colors</code>: Mit [[Temperaturfarbe#Skala_0 | 0]], [[Temperaturfarbe#Skala_1 | 1]] oder [[Temperaturfarbe#Skala_2 | 2]] wird das verwendete [[Temperaturfarbe | Farbmodell]] ausgewählt. Ein selbst definiertes Farbmodell kann als array-ref übergeben werden.

=== Beispiele ===
Steuern einer Lampe in Abhängigkeit von einer Temperatur:
define <n> notify mytemp:temperature.* {fhem("set lampe rgb ".substr(Color::pahColor(0,15,30,$EVTPART1,0,0),0,6))}

Einfärben eines Temperaturwertes in einer [[readingsGroup]]:
attr <rg> valueStyle { temperature => '{"style=\"color:\x23".substr(Color::pahColor(0,15,30,$VALUE,0),0,6)."\""}'}

Einfärben eines Feuchte-Readings in einer readingsGroup:
:<code><nowiki>attr <rg> valueStyle { humidity => '{style=\"color:\x23".substr(Color::pahColor(0,50,100,$VALUE,[255,255,0, 127,255,0, 0,255,0, 0,255,255, 0,127,255]),0,6)."\"}'}</nowiki></code>
Hier wird die folgende Farbzuordnung verwendet:[[Datei:color-humidity.png]]

Anmerkung: {{Taste|\x23}} ist die hexadezimale Escapesequenz für das {{Taste|#}} Zeichen, das beim Einlesen der [[Konfiguration]] sonst als Kommentar interpretiert werden würde. Ist mit aktuellen FHEM Versionen nicht mehr nötig. Das {{Taste|#}} Zeichen kann direkt verwendet werden.

Mit pahColor erzeugte Farbtabellen können mit [[DOIFtools#Farbtabellen_erzeugen|DOIFtools]] angezeigt werden.

[[Kategorie:Development]]

Homebridge einrichten

2022-01-26T07:59:46Z

Justme: /* Unterstützte Geräte */

Dieses HOWTO zeigt die Installation und Erstinbetriebnahme von Homebridge.

Damit kann Siri benutzt werden, um FHEM-Devices zu steuern. So können Devices angesprochen werden, die offiziell HomeKit nicht unterstützen (die Vorgehensweise wurde auf einem Intel NUC mit Ubuntu Server 14.04 LTS und auf einem Raspberry Pi mit Raspbian getestet). Der Wiki-Eintrag bezieht sich hauptsächlich auf eine {{Link2Forum|Topic=32652|LinkText=Diskussion im FHEM-Forum}}. Ein Riesendank gilt vor allem {{Link2FU|430|Andre (justme1968)}}.

Die Konfiguration der inzwischen aktuellen zweiten Version des Homekit-Plugins ist in einem neuen {{Link2Forum|Topic= 48558 |LinkText=Thread im FHEM-Forum}} beschrieben. Hinzugekommen ist vor allem die freie Konfigurierbarkeit der Zuordnung zwischen FHEM Device und Homekit Accessory/Service, zwischen FHEM Reading und Homekit Characteristic, das mapping vom FHEM Readingwerten zu Homekit Werten sowie das Mapping von Homekit Werten zu FHEM Set-Kommandos und Werten.

Eine Sammlung funktionsfähiger Homebridge FHEM Konfigurationen kann hier gefunden werden: [[Homebridge User Configs]]. Die Sammlung befindet sich noch im Aufbau.

= Vorbereitung der Umgebung =

== NodeJS installieren ==
''Die nachfolgenden Befehle sind alle mit "sudo" prefixed. Wenn du unter "root" arbeitest oder deine Distribution einen anderen Mechanismus verwendet, so kannst du dies natürlich weglassen.''

Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:

'''NodeJS V4'''
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

{{Randnotiz|RNTyp=y|RNText=Bei Installation von NodeJS auf einem "alten" RasPi (B) bitte die besonderen Hinweise in {{Link2Forum|Topic=32652|Message=419325|LinkText=diesem Forenbeitrag}} beachten.}}
'''NodeJS V5'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V6'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V11'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

Bei Ubunutu ist es noch nötig apt-get wie folgt auszuführen.
<syntaxhighlight lang="bash" style="width:50%">
sudo apt-get install -y nodejs
</syntaxhighlight>

Damit ist NodeJS installiert.

== Python, g++, MDNS installieren ==
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install python g++ libavahi-compat-libdnssd-dev
</syntaxhighlight>

Nun sind alle Voraussetzungen geschaffen.

= Installation von Homebridge & notwendiger Shims =
Im nachfolgenden Absatz wird die Installation von Homebridge sowie des notwendigen Plugins (Shim) für FHEM erläutert.
Eventuell muss vor die Befehle ein
<syntaxhighlight lang="bash" style="width:50%;">
sudo
</syntaxhighlight>
vorangestellt werden.
== Homebridge installieren ==
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm install -g --unsafe-perm homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm install -g homebridge-fhem
</syntaxhighlight>
installiert.

=== Fehler während der Installation ===
Bei folgendem Fehler ist das Abrufen von Github nicht möglich.
<pre>npm ERR! git clone --template=/home/hs-server-admin/.npm/_git-remotes/_templates --mirror
git://github.com/KhaosT/ed25519.git /home/hs-server-admin/.npm/_git-remotes/git-github-com-KhaosT-ed25519-git-d8bdee1d:
github.com[0: 192.30.252.128]: errno=Die Wartezeit für die Verbindung ist abgelaufen</pre>
Fehler könnte hier durch eine aktive Firewall verursacht werden.

Kommt eine DNS Fehlermeldung fehlt meistens der AVAHI-DAEMON, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install avahi-daemon
</syntaxhighlight>

Wenn npm beim Kompilieren von mdns mit der Meldung abbricht, dass "dns_sd.h" nicht gefunden wird, fehlt das Paket libavahi-compat-libdnssd-dev, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install libavahi-compat-libdnssd-dev
</syntaxhighlight>

== Homebridge aktualisieren ==
Prüfen, ob es Updates gibt:
<syntaxhighlight lang="bash" style="width:50%;">
npm -g outdated
</syntaxhighlight>
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm -g update homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm -g update homebridge-fhem
</syntaxhighlight>
installiert.

Sollte dies nicht funktionieren, kann mit
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge
</syntaxhighlight>
bzw.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem
</syntaxhighlight>
das Update installiert werden.

Um eine spezielle Version zu installieren, können die Installationsbefehle, von oben, wie folgt angepasst werden.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem@0.4.5
</syntaxhighlight>

= Homebridge konfigurieren =
''Wichtig: Für die weiteren Schritte sollte man nicht root verwenden, sondern beispielsweise einen dedizierten Nutzer für homebridge oder der Einfachheit halber den Nutzer, unter dem auch FHEM läuft (meist "fhem").''

== Einstellungen für homebridge ==
Zunächst wird das Verzeichnis für die Konfigurationsdatei erstellt und in dieses gewechselt:
<syntaxhighlight lang="bash" style="width:50%;">
mkdir -p ~/.homebridge
cd ~/.homebridge/
</syntaxhighlight>

Nun muss darin noch die config.json erstellt bzw. angepasst werden:
<syntaxhighlight lang="bash" style="width:50%;">
nano ~/.homebridge/config.json
</syntaxhighlight>

Hinweise zur Konfiguration:
* "''bridge''":
** "''username''": Sollte so belassen werden. Sollte später auf dem iOS Device keine Homebridge gefunden werden, so kann man hier beispielsweise den String auf 31 statt 30 enden lassen um so eine neue Homebridge vorzutäuschen.
** "''port''": Sollte so belassen werden
** "''pin''": Der PIN kann beliebig in dem Format xxx-xx-xxx angepasst werden. Dieser muss nur einmal bei der Einrichtung in iOS eingegeben werden.
* "''platforms''":
** "''platform''": Hier muss "FHEM" beibehalten werden.
** "''server''": Hier muss die IP des FHEM-Servers eingetragen werden. Dabei muss Homebridge nicht auf dem selben Server laufen wie FHEM, kann aber. Wenn es auf dem gleichen Rechner läuft, dann bietet es sich an, die IP 127.0.0.1 zu verwenden.
** "''port''": Hier muss der Port des gewählten FHEMWEBs eingetragen werden (muss nicht das "normale" sein, kann eine extra Instanz sein)
** "''auth''": Ist FHEM nicht mit Nutzername/Password abgesichert, so kann man diese Zeile einfach entfernen.
** "''filter''": Damit nicht alle Devices von Homebridge berücksichtigt werden, bietet es sich an, die Devices zu filtern. In diesem Beispiel wurden alle Devices, die über Siri steuerbar sein sollen, zusätzlich in den Raum Homekit konfiguriert.
<syntaxhighlight lang="json" style="width:50%;">
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "031-45-154"
},

"platforms": [
{
"platform": "FHEM",
"name": "FHEM",
"server": "127.0.0.1",
"port": "8083",
"auth": {"user": "FhemUser", "pass": "XXX"},
"filter": "room=Homekit"
}
],

"accessories": []
}
</syntaxhighlight>

Wenn für FHEMWEB kein user/password vergeben ist muss die "auth" Zeile weggelassen werden.
Wird FHEM mit SSL abgesichert, so muss zusätzlich in der Sektion "platforms" noch diese Zeile (nach "port") eingefügt werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"ssl": true,
</syntaxhighlight>
Wenn man SSL ohne user/password benutzt, muss man "auth" Zeile einfugen, wobei die Werte weggelassen werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"auth": {"user": "", "pass": ""},
</syntaxhighlight>

Natürlich kann man auch nach beliebigen anderen Kriterien filtern. z.b. nach Device TYPE, nach subtype Attribut, ... Es können mehrere FHEM platforms Abschnitte mit eigenem Filter im config file stehen (dabei das Komma zwischen den einzelnen Abschnitten nicht vergessen!) . Auch Geräte auf die mehr als ein Filterausdruck matched werden dabei nur einmal hinzugefügt.

= FHEM konfigurieren =
Es empfiehlt sich ein siri Gerät in FHEM anzulegen.
define siri siri

Die benötigten Attribute werden inzwischen beim ersten Start von homebridge-fhem automatisch auf FHEM Seite eingetragen.

Mehr zu den inzwischen verfügbaren Konfigurationsmöglichkeiten findet sich auf den github und npmjs Seiten des Plugins und im ersten Beitrag des zugehörigen Thread im {{Link2Forum|Topic= 48558 |LinkText=Diskussion im FHEM-Forum}}

= Start von Homebridge =

== Hinweis ==
Nach allen Änderungen die in FHEM gemacht werden, welche Homebridge betreffen, muss Homebridge neu gestartet werden. Wie der Neustart erfolgen muss, ist abhängig davon, wie man Homebridge gestartet hat. Bitte den entsprechenden Methoden entnehmen.

== Einmaliger Manueller Start ==
<syntaxhighlight lang="bash" style="width:50%;">
homebridge
</syntaxhighlight>

Homebridge sollte nun laufen. Hier kann man die Kommunikation nachverfolgen. Abbrechen kann das ganze mit CTRL+c (es sind dann auch keine Befehle mehr mit Siri möglich). Damit Siri auch Befehle ohne ständig offenes Terminal bearbeiten kann, bitte nächsten Punkt beachten.

=== Fehler während des Manuellen Starts ===
Kommt ein Fehler der ähnlich aussieht wie folgender, sollte zuerst die Nodesversion geprüft werden.
Die Nodes version kann durch ein System Update auf eine niedrigere Version wie benötigt gedowngraded werden
<syntaxhighlight lang="bash" style="width=50%">
Error: Module version mismatch. Expected 47, got 46.
at Error (native)
at Object.Module._extensions..node (module.js:450:18)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:313:12)
at Module.require (module.js:366:17)
at require (module.js:385:17)
at Object.<anonymous> (/usr/lib/node_modules/homebridge/node_modules/mdns/lib/dns_sd.js:24:20)
at Module._compile (module.js:425:26)
at Object.Module._extensions..js (module.js:432:10)
at Module.load (module.js:356:32)
</syntaxhighlight>
Geprüft werden kann die Nodes Version mit:
<syntaxhighlight lang="bash" style="width=50%">node -v zeigt mir: v0.10.28, nodejs -v: v5.11.1</syntaxhighlight>
Hier ist die Version v0.10.28 wobei v0.12 Mindestvorraussetzung ist.
Die Installation der richtigen Nodes Version kann oben am Anhang des Wiki Artikels entnommen werden.

== Homebridge automatisch starten ==
Es gibt verschiedene Methoden, Homebridge automatisch zu starten.

=== Steuerung via FHEM ===
Auf Basis der unten stehenden ''Alternativen Methode'' wurde eine Version entwickelt, mit der man auch den Status einsehen und den Restart des Dienstes aus FHEM heraus erledigen kann. Diese Version ist auf der Seite [[Homebridge Start und Status in FHEM]] im Detail beschrieben.

=== Alternative Methode: Init-Skript ===
Dies startet homebridge als einen Service.

==== Service anlegen ====
<code>
sudo nano /etc/init.d/homebridge
</code>

Code einfügen (startet den Homebridge Server als Benutzer "pi" und nimmt an, dass sich .homebridge/config.json in seinem Homeverzeichnis unter /home/pi/ befindet):

<syntaxhighlight lang=bash>
#!/bin/sh
### BEGIN INIT INFO
# Provides: homebridge
# Required-Start: $network $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start daemon at boot time for homebridge
# Description: Enable service provided by daemon.
### END INIT INFO
export PATH=$PATH:/usr/local/bin
export NODE_PATH=$NODE_PATH:/usr/local/lib/node_modules
PID=`pidof homebridge`
case "$1" in
start)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is already running"
else
su - pi -c "homebridge > /dev/null 2>&1 &"
echo "Homebridge starting"
$0 status
fi
;;
stop)
if ! ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is not running"
else
kill $PID
echo "Homebridge closed"
fi
;;
restart)
if ! ps -p $PID > /dev/null 2>&1; then
$0 start
else
$0 stop
$0 start
fi
;;
status)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is running PID $PID"
else
echo "Homebridge is not running"
fi
;;
*)
echo "Usage: $0 {start|stop|status|restart}"
exit 1
;;
esac
exit 0
</syntaxhighlight>

==== Autostart aktivieren ====

<code>
sudo chmod 755 /etc/init.d/homebridge

sudo update-rc.d homebridge defaults
</code>

Nun kann man mit

<code>
sudo service homebridge start
</code>

bzw.

<code>
sudo /etc/init.d/homebridge start
</code>

den Dienst starten

=== Alternative Methode: systemd ===

Während das Init-Skript grundsätzlich auch mit systemd funktioniert, kann man natürlich für Homebridge auch ein systemd-Skript anlegen. Wie das geht, ist im [https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi#running-homebridge-on-bootup-systemd Wiki zu Homebridge] beschrieben.

== FHEM Device Einstellungen ==
Damit die zu schaltenden Geräte überhaupt in der Homebridge aufgenommen werden, muss man sie im Raum Homekit hinzufügen.

Um HM-CC-RT-DN Thermostate steuern zu können, muss wie oben beschrieben folgendes attribute gesetzt werden (hier als Beispiel das Device "Heizung"):
# attr Heizung subtype thermostat
Für einen Dummy muss man den genericDeviceType setzen, also beispielsweise:
# attr Dummy genericDeviceType switch
# attr Dummy setList on off

Wie bereits vorher angemerkt: fügt man ein Device hinzu oder führt eine Änderung an einem Device durch, so sollte homebridge neu gestartet werden.

= HomeKit in iOS =

== Einrichtung ==
Um FHEM über Homebridge in iOS nutzen zu können, muss HomeKit eingerichtet werden.

Es gibt verschiedene Apps. Im Folgenden wird die App EVE von Elgato empfohlen, die aus dem App-Store geladen werden muss.
In der App auf:
<pre style="width:50%;">
Gerät hinzufügen
</pre>
Es sollte ein Gerät mit der Bezeichnung "Homebridge" zur Auswahl erscheinen. Zur Ersteinrichtung auf PIN manuell eingeben gehen und (falls in der config.json nicht geändert):
<pre style="width:50%;">
031-45-154
</pre>
eingeben.

Im Anschluss können die Devices nach Belieben verschiedenen Räumen zugeteilt werden, sowie Szenen und Bereiche erstellt werden.

== Schalten mit Siri ==
'''HolyMoly''' aus dem FHEM-Forum hat ein paar Beispiele gegeben, wie man Siri dazu bringt Devices zu schalten:
<pre style="width:50%;">
"Schalte alle Lampen im Obergeschoss ein."
"Schalte Chloes Licht aus."
"Dimme das Licht in der Küche."
"Dimme das Licht im Esszimmer auf 50 %."
"Stelle das Licht in der Küche am hellsten ein."
"Stelle die Temperatur im Tahoe-Haus auf 22 °C ein."
"Stelle das Thermostat im Erdgeschoss auf 21 °C ein.
"Schalte den Drucker im Büro ein."
"Siri, bereite alles für eine Party vor."
"Bereite das Ambiente fürs Abendessen vor."
"Aktiviere den Nachtruhemodus."
</pre>

Mittlerweile kann Siri auch noch die Lichtfarbe von LEDs ändern.

= Hinweise =

== Unterstützte Geräte ==
Das FHEM Plugin von {{Link2FU|430|Andre (justme1968)}} unterstützt automatisch mindestens die folgenden Geräte:

switches (devices with set on and set off commands)
lights (devices with set on and set off commands)
HomeMatic, FS20 and ZWave dimmers (devices with set on, set off and set dim or set pct commands)
HUE, WifiLight, MilightDevice, SWAP_0000002200000003 (hue, sat, bri, rgb)
homematic, max and pid20 thermostats
homematic, DUOFERN and FS20/IT(?) blinds
homematic, MAX and FHTTK contact sensors (door, window)
HM-SEC-WIN, HM-SEC-KEY
presence, ROOMMATE
SONOS (power, volume)
harmony scenes
temperaturecw and humidity sensors
CO20 air quality sensor
probably some more ...

Über eine entsprechende Konfiguration lässt sich darüber hinaus jedes mit FHEM steuerbare Gerät auf die unterstützten Homekit-Typen abbilden.

Die aktuelle Liste und eine Beschreibung der Konfigurationsmöglichkeiten findet sich [https://www.npmjs.com/package/homebridge-fhem auf den npmjs seiten] bzw. [https://github.com/justme-1968/homebridge-fhem auf github].

Mehr zum homebridgeMapping findet sich hier: [[Alexa_und_Mappings#homebridgeMapping]]

Mehr zu den unterstützen Services und Characteristics findet sich hier: [https://github.com/homebridge/HAP-NodeJS/blob/master/src/lib/gen/HomeKit.ts]

Über eine '''history''' Characteristic lässt sich für bestimmte Service-Typen eine Eve-Kompatible history aktivieren:
... history:size=1024 ...

=== Beispiele ===

Gesammelte Beispiele funktionierender HomebridgeMappings sind hier zu finden: [[Homebridge_User_Configs]]

== Zusätzliche Plugins ==
Für manche der über FHEM steuerbaren Geräte wie z.b. MiLight, Harmony Hub, Philips Hue, Sonos,... gibt es eigene homekit plugins. Wenn immer möglich, empfiehlt es sich aber diese '''nicht''' zu verwenden, sondern die Steuerung über die FHEM-Integration zu realisieren, da
* diese in der Regel sehr viel mächtiger und frei konfigurierbar ist
* es FHEM erlaubt, als zentrale Instanz den Überblick über den aktuellen Gesamtzustand zu haben (wichtig bei Geräten, die gepollt werden)
* die Ressourcen auf den angesteuerten Geräten schont, da Werte optimal gecached werden und nur eine einzige Verbindung aufgebaut wird

== Hinweis für alte homebridge Versionen ==
UPDATE: Homebridge funktioniert mit einer kleinen Einschränkung nun auch mit node 4.0.0. Laut
[https://github.com/cflurin/homebridge-shims/wiki/Minimalist-Homebridge-on-a-Raspberry-Pi Homebridge on a Raspberry Pi] müssen die folgenden Abhängigkeiten (Dependencies) aus der '''package.json''' entfernt werden:
<pre>
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git"
</pre>

== Hinweis zur Geschwindigkeitsoptimierung auf einem Raspberry PI ==
Damit es auf einem Raspberry schneller läuft, wird darüber hinaus empfohlen, auch diverse Abhängigkeiten aus der '''package.json''' zu entfernen:
<pre>
"ad2usb": "git+https://github.com/alistairg/node-ad2usb.git#local",
"carwingsjs": "0.0.x",
"chokidar": "^1.0.5",
"eibd": "^0.3.1",
"elkington": "kevinohara80/elkington",
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git",
"lifx-api": "^1.0.1",
"lifx": "git+https://github.com/magicmonkey/lifxjs.git",
"node-hue-api": "^1.0.5",
"node-icontrol": "^0.1.4",
"node-milight-promise": "0.0.x",
"tough-cookie": "^2.0.0",
"sonos": "0.8.x",
"telldus-live": "0.2.x",
"teslams": "1.0.1",
"unofficial-nest-api": "git+https://github.com/hachidorii/unofficial_nodejs_nest.git#d8d48edc952b049ff6320ef99afa7b2f04cdee98",
"wemo": "0.2.x",
"wink-js": "0.0.5",
"komponist" : "0.1.0",
"yamaha-nodejs": "0.4.x",
</pre>

Daher zunächst ein Backup der Datei anlegen
<pre>sudo cp package.json package.json.bkp </pre>
Am einfachsten geht das Entfernen der Zeilen mit einem Editor, beispielsweise nano oder vi.
<pre>sudo nano package.json</pre>

Das config file sollte dann wie folgt aussehen: Achtung vor den letzten zwei "}" am Ende darf kein Komma sein.
<syntaxhighlight lang="json">
{
"name": "homebridge",
"description": "HomeKit support for the impatient",
"version": "0.1.1",
"scripts": {
"start": "DEBUG=* node app.js || true"
},
"repository": {
"type": "git",
"url": "git://github.com/nfarina/homebridge.git"
},
"license": "ISC",
"dependencies": {
"async": "^1.4.2",
"color": "0.10.x",
"debug": "^2.2.0",
"hap-nodejs": "^0.0.2",
"isy-js": "",
"mdns": "^2.2.4",
"netatmo": "1.3.0",
"node-cache": "3.0.0",
"node-persist": "0.0.x",
"node-xmpp-client": "1.0.0-alpha23",
"q": "1.4.x",
"queue": "^3.1.0",
"request": "2.49.x",
"xml2js": "0.4.x",
"xmldoc": "0.1.x"
}
}
</syntaxhighlight>

== Links ==
* [https://github.com/nfarina/homebridge Github homebridge]
* [https://github.com/justme-1968/homebridge-fhem Github homebridge-fhem]
* [https://www.npmjs.com/package/homebridge NPM homebridge]
* [https://www.npmjs.com/package/homebridge-fhem NPM homebridge-fhem]

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Alexa und Mappings

2021-02-16T08:09:46Z

Justme: /* Liste der unterstützten Characteristics und ihrer Parameter */

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.
{| 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 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 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===
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 <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==
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>]*]*
*<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>
*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:
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''===
{| 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: 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: ???,default:CLOSED,timeout:500,cmds=OPEN:open
|-
| LockCurrentState || Integer || UNSECURED=0, SECURED=1, JAMMED = 2, UNKNOWN = 3|| lock,values=/uncertain/:UNKNOWN,/^locked/:SECURED,/.*/:UNSECURED 
|-
| LockTargetState || Integer || UNSECURED=0, SECURED=1||
* Wenn es sich um eine KeyMatic handelt, also das Attribut ''model'' den Wert HM-SEC-KEY 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===
{| 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}

[[Kategorie:Sprachsteuerung]]

Speedtest

2020-10-08T08:49:03Z

Justme:

{{Todo|Fehlerkontrolle, Formatierung, Ergänzung, ggf. Detaillieren des Troubleshooting}}

[[Speedtest]] ist ein Modul, mit dem in regelmäßigen Abständen die Internet-Geschwindigket (Download, Upload, Ping) gemessen werden kann. Dabei wird auf das externe Python-Script [https://github.com/sivel/speedtest-cli speedtest-cli] zurück gegriffen.

Mit dem stand vom 05.10.2020 kann alternativ auch das offizielle CLI Binary von ookla verwendet werden. Dies liefert in der Regel genauere Werte. Vor allem bei höheren Bandbreiten.

{{Infobox Modul
|ModPurpose=Testet die Internetgeschwindigkeit
|ModType=d
|ModCmdRef=speedtest
|ModForumArea=Sonstiges
|ModTechName=32_speedtest.pm
|ModOwner=Andre / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer_Diskussion:Justme|Wiki]])}}

== Voraussetzungen ==

Für diese Anleitung ist notwendig
* Debian-Derivat (Debian, Ubuntu, Raspbian, ...)
* Linux-Grundkenntnisse
* Paket- und Quellenverwaltung apt-get
* Python 2.4 - 3.4
* wget

Alle in diesen Kapitel genannten Befehle müssen auf der Kommandozeile abgesetzt werden.

{{Hinweis|Sollte [https://www.python.org/ Python] und/oder [https://www.gnu.org/software/wget/ wget] nicht installiert sein, kann das mit folgenden zwei Befehlen erledigt werden:
sudo apt-get update
sudo apt-get install python wget
}}

=== Installation von speedtest-cli ===

Zuerst muss das speedtest-cli - Script heruntergeladen werden. Der folgende Befehl erledigt das mit Hilfe von wget und speichert die Datei im Verzeichnis ''/usr/local/bin'':
sudo wget -O /usr/local/bin/speedtest-cli https://raw.githubusercontent.com/sivel/speedtest-cli/master/speedtest.py

Anschließend muss die Datei noch als "ausführbar" markiert werden:
sudo chmod +x /usr/local/bin/speedtest-cli

Ob alles funktioniert hat, kann man dann mit einem einfachen Aufruf überprüfen:
speedtest-cli --help

Weitere Installationsanleitungen sind auf der [https://github.com/sivel/speedtest-cli speedtest-cli - Webseite] zu finden.

Alternativ CLI Binary von ookla: https://www.speedtest.net/apps/cli und setzen des ookla Attributs.

Falls damit der folgende Fehler im FHEM-Log angezeigt wird:<syntaxhighlight>
2020.10.07 11:52:14.721 5: speedtest done
what(): basic_string::_M_construct null not valid
terminate called after throwing an instance of 'std::logic_error'

</syntaxhighlight>muss das FHEM-Start -Script angepasst werden. Beispiel hier: https://forum.fhem.de/index.php/topic,114118.msg1090706.html#msg1090706

== Definition ==
Das Modul wird folgendermaßen definiert:
define <name> speedtest [interval] [server]

=== Optionen ===

*<code><interval></code>: Optional. Der Wert bestimmt, in welchen Zeitabständen ein Geschwindigkeitstest durchgeführt wird. Wird kein Intervall angegeben, wird der Standard-Wert (3600s) verwendet. Minimum sind 1800 Sekunden.
*<code><server></code>: Optional. Hier kann die ID eines Speedtest-Servers eingetragen werden, gegen den die Geschwindigkeits-Tests gefahren werden. Ist kein Wert angegeben, wird der "nächstgelegene" Server verwendet.

{{Hinweis|Eine Liste aller verfügbaren Speedtest-Server kann mittels <code>speedtest-cli --list</code> bzw. <code>speedtest-cli --list {{!}} grep Germany</code> angezeigt werden}}

=== Readings ===
* <code>ping</code> (ms)
* <code>download</code> (MBit/s)
* <code>upload</code> (MBit/s)

=== Set ===
* <code>statusRequest</code>: Startet einen manuellen Durchlauf des definierten Tests

=== Attribute ===
Bei der Definition des Moduls können folgende Attribute gesetzt werden

* <code>path</code>: Hier kann das Verzeichnis des speedtest-cli-Scripts angegeben werden (z.B.: /usr/local/bin).
* <code>checks-till-disable</code>: Über dieses Attribut lässt sich festlegen, wie häufig speedtest-cli ausgeführt werden soll, bevor der automatische Aufruf deaktiviert wird. Nach Ablauf des Zählers wird das Modul automatisch auf disable gesetzt. Bei jedem Durchlauf wird der Zähler um 1 reduziert.
* <code>disable</code>: Ist dieses Attribut auf 1 gesetzt, ist die automatische Ausführung deaktiviert. Das manuelle Ausführen über <code>set</code> ist trotzdem möglich.

== Beispiel ==
[[File:speedtest01.png|mini|right|200px|Ein speedtest-Device nach dem Geschwindigkeits-Test]]
=== Definition des Moduls ===
<syntaxhighlight lang="perl">
define MySpeedtest speedtest 1800 5255
attr MySpeedtest path /usr/local/bin
</syntaxhighlight>

=== Logging in eine Datei ===

Das Speichern der Ergebnisse in ein Logfile erreicht man z.B. so:
<syntaxhighlight lang="perl">
define FileLog_MySpeedtest FileLog ./log/MySpeedtest-%Y%m.log MySpeedtest:.*
attr FileLog_MySpeedtest logtype text
</syntaxhighlight>

==== Plot (FileLog)====

Ein zugehörige SVG-Plot könnte wie folgt aussehen:
<syntaxhighlight lang="perl">
############################
# Display speedtest results

set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'

set yrange [0:1]
set y2range [0:12]
set y3range [0:120]

set ylabel "Mbit/s"
set y2label "Mbit/s"
set y3label "ms"

#FileLog 4:speedtest.download\x3a::
#FileLog 4:speedtest.upload\x3a::
#FileLog 4:speedtest.ping\x3a::

plot
using 1:2 ls l0 axes x1y2 title 'download (Mbit/s)' with lines,
using 1:2 ls l1 axes x1y1 title 'upload (Mbit/s)' with lines,
using 1:2 ls l2 axes x1y3 title 'ping (ms)' with lines
</syntaxhighlight>

Der Weblink dazu wird wie folgt definiert:
<syntaxhighlight lang="perl">
define wl_speedtest SVG FileLog_speedtest:speedtest3:CURRENT
</syntaxhighlight>

=== Logging mit Hilfe von [[DbLog]] ===

Das Loggen in eine Datenbank erfolgt, wenn ein Reading explizit oder generell alle Readings bei der Definition von [[DbLog]] angegeben worden sind und bei der Definition des Moduls [[Speedtest]] die Readings nicht über ''DbLogExclude'' ausgeschlossen wurden.

==== Plot (DbLog) ====
Definition des Plots bei Verwendung von DbLog:
<syntaxhighlight lang="perl">
define wl_speedtest SVG myDbLog:speedtest:HISTORY
attr wl_speedtest label "DL $data{currval1} / UL $data{currval2} / ping $data{currval3}"
attr wl_speedtest plotfunction speedtest
</syntaxhighlight>

Definition der Datei speedtest.gplots:
<syntaxhighlight lang="perl">
############################
# Display speedtest results

set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'

set yrange [0:1]
set y2range [0:12]
set y3range [0:120]

set ylabel "Mbit/s"
set y2label "Mbit/s"
set y3label "ms"

#myDbLog <SPEC1>:download:::$val=~s/([\d.]*).*/$1/eg
#myDbLog <SPEC1>:upload:::$val=~s/([\d.]*).*/$1/eg
#myDbLog <SPEC1>:ping:::$val=~s/([\d.]*).*/$1/eg

plot
using 1:2 ls l0 axes x1y2 title 'download (Mbit/s)' with lines,
using 1:2 ls l1 axes x1y1 title 'upload (Mbit/s)' with lines,
using 1:2 ls l2 axes x1y3 title 'ping (ms)' with lines
</syntaxhighlight>

== Bekannte Probleme ==
* Für den Betrieb ist Python notwendig. Daher läuft das Script nicht ohne Weiteres auf einer FritzBox.
* Zwischenzeitlich wurde das Script umbenannt. Das Modul erwartet nach wie vor den ursprünglichen Namen. Daher ist wie oben beschrieben darauf zu achten, dass das abgelegte Script <code>speedtest-cli</code> heißt und notfalls dementsprechend umbenannt wird.
* Das Modul bricht ggf. mit einer Perl-Fehlermeldung im FHEM-Log ab, obwohl das Script von der Konsole aus einwandfrei läuft. Dies tritt z.B. bei Verwendung von Rasbian mit installierten Python 2.7 und Python 3 auf. Zur Behebung muss im Script <code>speedtest-cli</code> die erste Zeile auf <code>#!/usr/bin/env python'''3'''</code> geändert werden.
* Auf manchen Systemen muss in aktuellen speedtest-cli Versionen die Zeile <code>'(%s; U; %s; en-us)' % (platform.system(), platform.architecture()[0]),</code> auskommentiert werden.

== Troubleshooting ==
Im Folgenden sind ein paar Ansatzpunkte genannt, um beim Troubleshooting zu unterstützen.

* Das Script läuft auf der Kommandzeile problemlos, das Modul bringt aber Fehler:
** Script ist nicht ausführbar (<code>chmod +x speedtest-cli</code>)
** Der FHEM-User (''fhem'') hat keine Berechtigung das Script auszuführen

* SVG-Plot zeigt nichts an:
** Verweis auf Filelog oder DbLog falsch
** Falsches gplot-File angegeben
** Übergabe der Plotfunktion (bei DbLog) nicht korrekt
** Falsche Groß-/Kleinschreibung verwendet (case sensitive)

* Fehlermeldung ''isn't numeric in sprintf at ./FHEM/98_SVG.pm''
** Dieses kommt grundsätzlich immer dann vor, wenn SVG versucht einen Wert einzulesen, der neben der Zahl auch die Einheit enthält. Dieses kann bei der Verwendung von DbLog vorkommen, weil DbLog nicht weiß, wie es Wert und Einheit trennen soll. Abhilfe schafft eine entsprechende Regular Expression, die nur den Zahlenwert liefert.

== Weblinks ==
* Beschreibung des Scripts [http://binarynature.blogspot.de/2013/03/measure-internet-connection-speed-from-linux-command-line.html binarynature.blogspot.de]
* [https://pypi.python.org/pypi/speedtest-cli speedtest-cli auf pypi.python.org]
* [https://github.com/sivel/speedtest-cli speedtest-cli auf github.com]
* Forumseintrag über die Entwicklung des Moduls {{Link2Forum|Topic=13419|Message=83189|LinkText=Thema: Internetgeschwindigkeit überwachen}}
* Forumseintrag darüber, dass das Binary nicht auf der Fritzbox läuft {{Link2Forum|Topic=27242|Message=201516|LinkText=Thema: Internetgeschwindigkeit - speedtest}}
* Forumseintrag über aus der Idee wird ein Modul {{Link2Forum|Topic=13483|Message=83538|LinkText=Thema: Internetgeschwindigkeit überwachen}}
* Forumsbeitrag zum Einsatz unter Windows {{Link2Forum|Topic= 111602|LinkText=Thema: Speedtest für windows}}

== Sonstiges ==
Besten Dank an wkarl, Puschel74, justme1968 für Idee, Modulerstellung/Pflege und Installationsanleitung.

Speedtest

2020-10-05T17:59:57Z

Justme: ookla version hinzugefügt

{{Todo|Fehlerkontrolle, Formatierung, Ergänzung, ggf. Detaillieren des Troubleshooting}}

[[Speedtest]] ist ein Modul, mit dem in regelmäßigen Abständen die Internet-Geschwindigket (Download, Upload, Ping) gemessen werden kann. Dabei wird auf das externe Python-Script [https://github.com/sivel/speedtest-cli speedtest-cli] zurück gegriffen.

Mit dem stand vom 05.10.2020 kann alternativ auch das offizielle CLI Binary von ookla verwendet werden. Dies liefert in der Regel genauere Werte. vor allem bei höheren Bandbreiten.

{{Infobox Modul
|ModPurpose=Testet die Internetgeschwindigkeit
|ModType=d
|ModCmdRef=speedtest
|ModForumArea=Sonstiges
|ModTechName=32_speedtest.pm
|ModOwner=Andre / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer_Diskussion:Justme|Wiki]])}}

== Voraussetzungen ==

Für diese Anleitung ist notwendig
* Debian-Derivat (Debian, Ubuntu, Raspbian, ...)
* Linux-Grundkenntnisse
* Paket- und Quellenverwaltung apt-get
* Python 2.4 - 3.4
* wget

Alle in diesen Kapitel genannten Befehle müssen auf der Kommandozeile abgesetzt werden.

Alternativ CLI Binary von ookla: https://www.speedtest.net/apps/cli

{{Hinweis|Sollte [https://www.python.org/ Python] und/oder [https://www.gnu.org/software/wget/ wget] nicht installiert sein, kann das mit folgenden zwei Befehlen erledigt werden:
sudo apt-get update
sudo apt-get install python wget
}}

=== Installation von speedtest-cli ===

Zuerst muss das speedtest-cli - Script heruntergeladen werden. Der folgende Befehl erledigt das mit Hilfe von wget und speichert die Datei im Verzeichnis ''/usr/local/bin'':
sudo wget -O /usr/local/bin/speedtest-cli https://raw.githubusercontent.com/sivel/speedtest-cli/master/speedtest.py

Anschließend muss die Datei noch als "ausführbar" markiert werden:
sudo chmod +x /usr/local/bin/speedtest-cli

Ob alles funktioniert hat, kann man dann mit einem einfachen Aufruf überprüfen:
speedtest-cli --help

Weitere Installationsanleitungen sind auf der [https://github.com/sivel/speedtest-cli speedtest-cli - Webseite] zu finden.

== Definition ==
Das Modul wird folgendermaßen definiert:
define <name> speedtest [interval] [server]

=== Optionen ===

*<code><interval></code>: Optional. Der Wert bestimmt, in welchen Zeitabständen ein Geschwindigkeitstest durchgeführt wird. Wird kein Intervall angegeben, wird der Standard-Wert (3600s) verwendet. Minimum sind 1800 Sekunden.
*<code><server></code>: Optional. Hier kann die ID eines Speedtest-Servers eingetragen werden, gegen den die Geschwindigkeits-Tests gefahren werden. Ist kein Wert angegeben, wird der "nächstgelegene" Server verwendet.

{{Hinweis|Eine Liste aller verfügbaren Speedtest-Server kann mittels <code>speedtest-cli --list</code> bzw. <code>speedtest-cli --list {{!}} grep Germany</code> angezeigt werden}}

=== Readings ===
* <code>ping</code> (ms)
* <code>download</code> (MBit/s)
* <code>upload</code> (MBit/s)

=== Set ===
* <code>statusRequest</code>: Startet einen manuellen Durchlauf des definierten Tests

=== Attribute ===
Bei der Definition des Moduls können folgende Attribute gesetzt werden

* <code>path</code>: Hier kann das Verzeichnis des speedtest-cli-Scripts angegeben werden (z.B.: /usr/local/bin).
* <code>checks-till-disable</code>: Über dieses Attribut lässt sich festlegen, wie häufig speedtest-cli ausgeführt werden soll, bevor der automatische Aufruf deaktiviert wird. Nach Ablauf des Zählers wird das Modul automatisch auf disable gesetzt. Bei jedem Durchlauf wird der Zähler um 1 reduziert.
* <code>disable</code>: Ist dieses Attribut auf 1 gesetzt, ist die automatische Ausführung deaktiviert. Das manuelle Ausführen über <code>set</code> ist trotzdem möglich.

== Beispiel ==
[[File:speedtest01.png|mini|right|200px|Ein speedtest-Device nach dem Geschwindigkeits-Test]]
=== Definition des Moduls ===
<syntaxhighlight lang="perl">
define MySpeedtest speedtest 1800 5255
attr MySpeedtest path /usr/local/bin
</syntaxhighlight>

=== Logging in eine Datei ===

Das Speichern der Ergebnisse in ein Logfile erreicht man z.B. so:
<syntaxhighlight lang="perl">
define FileLog_MySpeedtest FileLog ./log/MySpeedtest-%Y%m.log MySpeedtest:.*
attr FileLog_MySpeedtest logtype text
</syntaxhighlight>

==== Plot (FileLog)====

Ein zugehörige SVG-Plot könnte wie folgt aussehen:
<syntaxhighlight lang="perl">
############################
# Display speedtest results

set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'

set yrange [0:1]
set y2range [0:12]
set y3range [0:120]

set ylabel "Mbit/s"
set y2label "Mbit/s"
set y3label "ms"

#FileLog 4:speedtest.download\x3a::
#FileLog 4:speedtest.upload\x3a::
#FileLog 4:speedtest.ping\x3a::

plot
using 1:2 ls l0 axes x1y2 title 'download (Mbit/s)' with lines,
using 1:2 ls l1 axes x1y1 title 'upload (Mbit/s)' with lines,
using 1:2 ls l2 axes x1y3 title 'ping (ms)' with lines
</syntaxhighlight>

Der Weblink dazu wird wie folgt definiert:
<syntaxhighlight lang="perl">
define wl_speedtest SVG FileLog_speedtest:speedtest3:CURRENT
</syntaxhighlight>

=== Logging mit Hilfe von [[DbLog]] ===

Das Loggen in eine Datenbank erfolgt, wenn ein Reading explizit oder generell alle Readings bei der Definition von [[DbLog]] angegeben worden sind und bei der Definition des Moduls [[Speedtest]] die Readings nicht über ''DbLogExclude'' ausgeschlossen wurden.

==== Plot (DbLog) ====
Definition des Plots bei Verwendung von DbLog:
<syntaxhighlight lang="perl">
define wl_speedtest SVG myDbLog:speedtest:HISTORY
attr wl_speedtest label "DL $data{currval1} / UL $data{currval2} / ping $data{currval3}"
attr wl_speedtest plotfunction speedtest
</syntaxhighlight>

Definition der Datei speedtest.gplots:
<syntaxhighlight lang="perl">
############################
# Display speedtest results

set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'

set yrange [0:1]
set y2range [0:12]
set y3range [0:120]

set ylabel "Mbit/s"
set y2label "Mbit/s"
set y3label "ms"

#myDbLog <SPEC1>:download:::$val=~s/([\d.]*).*/$1/eg
#myDbLog <SPEC1>:upload:::$val=~s/([\d.]*).*/$1/eg
#myDbLog <SPEC1>:ping:::$val=~s/([\d.]*).*/$1/eg

plot
using 1:2 ls l0 axes x1y2 title 'download (Mbit/s)' with lines,
using 1:2 ls l1 axes x1y1 title 'upload (Mbit/s)' with lines,
using 1:2 ls l2 axes x1y3 title 'ping (ms)' with lines
</syntaxhighlight>

== Bekannte Probleme ==
* Für den Betrieb ist Python notwendig. Daher läuft das Script nicht ohne Weiteres auf einer FritzBox.
* Zwischenzeitlich wurde das Script umbenannt. Das Modul erwartet nach wie vor den ursprünglichen Namen. Daher ist wie oben beschrieben darauf zu achten, dass das abgelegte Script <code>speedtest-cli</code> heißt und notfalls dementsprechend umbenannt wird.
* Das Modul bricht ggf. mit einer Perl-Fehlermeldung im FHEM-Log ab, obwohl das Script von der Konsole aus einwandfrei läuft. Dies tritt z.B. bei Verwendung von Rasbian mit installierten Python 2.7 und Python 3 auf. Zur Behebung muss im Script <code>speedtest-cli</code> die erste Zeile auf <code>#!/usr/bin/env python'''3'''</code> geändert werden.
* Auf manchen Systemen muss in aktuellen speedtest-cli Versionen die Zeile <code>'(%s; U; %s; en-us)' % (platform.system(), platform.architecture()[0]),</code> auskommentiert werden.

== Troubleshooting ==
Im Folgenden sind ein paar Ansatzpunkte genannt, um beim Troubleshooting zu unterstützen.

* Das Script läuft auf der Kommandzeile problemlos, das Modul bringt aber Fehler:
** Script ist nicht ausführbar (<code>chmod +x speedtest-cli</code>)
** Der FHEM-User (''fhem'') hat keine Berechtigung das Script auszuführen

* SVG-Plot zeigt nichts an:
** Verweis auf Filelog oder DbLog falsch
** Falsches gplot-File angegeben
** Übergabe der Plotfunktion (bei DbLog) nicht korrekt
** Falsche Groß-/Kleinschreibung verwendet (case sensitive)

* Fehlermeldung ''isn't numeric in sprintf at ./FHEM/98_SVG.pm''
** Dieses kommt grundsätzlich immer dann vor, wenn SVG versucht einen Wert einzulesen, der neben der Zahl auch die Einheit enthält. Dieses kann bei der Verwendung von DbLog vorkommen, weil DbLog nicht weiß, wie es Wert und Einheit trennen soll. Abhilfe schafft eine entsprechende Regular Expression, die nur den Zahlenwert liefert.

== Weblinks ==
* Beschreibung des Scripts [http://binarynature.blogspot.de/2013/03/measure-internet-connection-speed-from-linux-command-line.html binarynature.blogspot.de]
* [https://pypi.python.org/pypi/speedtest-cli speedtest-cli auf pypi.python.org]
* [https://github.com/sivel/speedtest-cli speedtest-cli auf github.com]
* Forumseintrag über die Entwicklung des Moduls {{Link2Forum|Topic=13419|Message=83189|LinkText=Thema: Internetgeschwindigkeit überwachen}}
* Forumseintrag darüber, dass das Binary nicht auf der Fritzbox läuft {{Link2Forum|Topic=27242|Message=201516|LinkText=Thema: Internetgeschwindigkeit - speedtest}}
* Forumseintrag über aus der Idee wird ein Modul {{Link2Forum|Topic=13483|Message=83538|LinkText=Thema: Internetgeschwindigkeit überwachen}}
* Forumsbeitrag zum Einsatz unter Windows {{Link2Forum|Topic= 111602|LinkText=Thema: Speedtest für windows}}

== Sonstiges ==
Besten Dank an wkarl, Puschel74, justme1968 für Idee, Modulerstellung/Pflege und Installationsanleitung.

Speedtest

2020-05-28T15:47:33Z

Justme: Hinweis zu Verwendung unter Windows

{{Todo|Fehlerkontrolle, Formatierung, Ergänzung, ggf. Detaillieren des Troubleshooting}}

[[Speedtest]] ist ein Modul, mit dem in regelmäßigen Abständen die Internet-Geschwindigket (Download, Upload, Ping) gemessen werden kann. Dabei wird auf das externe Python-Script [https://github.com/sivel/speedtest-cli speedtest-cli] zurück gegriffen.

{{Infobox Modul
|ModPurpose=Testet die Internetgeschwindigkeit
|ModType=d
|ModCmdRef=speedtest
|ModForumArea=Sonstiges
|ModTechName=32_speedtest.pm
|ModOwner=Andre / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer_Diskussion:Justme|Wiki]])}}

== Voraussetzungen ==

Für diese Anleitung ist notwendig
* Debian-Derivat (Debian, Ubuntu, Raspbian, ...)
* Linux-Grundkenntnisse
* Paket- und Quellenverwaltung apt-get
* Python 2.4 - 3.4
* wget

Alle in diesen Kapitel genannten Befehle müssen auf der Kommandozeile abgesetzt werden.

{{Hinweis|Sollte [https://www.python.org/ Python] und/oder [https://www.gnu.org/software/wget/ wget] nicht installiert sein, kann das mit folgenden zwei Befehlen erledigt werden:
sudo apt-get update
sudo apt-get install python wget
}}

=== Installation von speedtest-cli ===

Zuerst muss das speedtest-cli - Script heruntergeladen werden. Der folgende Befehl erledigt das mit Hilfe von wget und speichert die Datei im Verzeichnis ''/usr/local/bin'':
sudo wget -O /usr/local/bin/speedtest-cli https://raw.githubusercontent.com/sivel/speedtest-cli/master/speedtest.py

Anschließend muss die Datei noch als "ausführbar" markiert werden:
sudo chmod +x /usr/local/bin/speedtest-cli

Ob alles funktioniert hat, kann man dann mit einem einfachen Aufruf überprüfen:
speedtest-cli --help

Weitere Installationsanleitungen sind auf der [https://github.com/sivel/speedtest-cli speedtest-cli - Webseite] zu finden.

== Definition ==
Das Modul wird folgendermaßen definiert:
define <name> speedtest [interval] [server]

=== Optionen ===

*<code><interval></code>: Optional. Der Wert bestimmt, in welchen Zeitabständen ein Geschwindigkeitstest durchgeführt wird. Wird kein Intervall angegeben, wird der Standard-Wert (3600s) verwendet. Minimum sind 1800 Sekunden.
*<code><server></code>: Optional. Hier kann die ID eines Speedtest-Servers eingetragen werden, gegen den die Geschwindigkeits-Tests gefahren werden. Ist kein Wert angegeben, wird der "nächstgelegene" Server verwendet.

{{Hinweis|Eine Liste aller verfügbaren Speedtest-Server kann mittels <code>speedtest-cli --list</code> bzw. <code>speedtest-cli --list {{!}} grep Germany</code> angezeigt werden}}

=== Readings ===
* <code>ping</code> (ms)
* <code>download</code> (MBit/s)
* <code>upload</code> (MBit/s)

=== Set ===
* <code>statusRequest</code>: Startet einen manuellen Durchlauf des definierten Tests

=== Attribute ===
Bei der Definition des Moduls können folgende Attribute gesetzt werden

* <code>path</code>: Hier kann das Verzeichnis des speedtest-cli-Scripts angegeben werden (z.B.: /usr/local/bin).
* <code>checks-till-disable</code>: Über dieses Attribut lässt sich festlegen, wie häufig speedtest-cli ausgeführt werden soll, bevor der automatische Aufruf deaktiviert wird. Nach Ablauf des Zählers wird das Modul automatisch auf disable gesetzt. Bei jedem Durchlauf wird der Zähler um 1 reduziert.
* <code>disable</code>: Ist dieses Attribut auf 1 gesetzt, ist die automatische Ausführung deaktiviert. Das manuelle Ausführen über <code>set</code> ist trotzdem möglich.

== Beispiel ==
[[File:speedtest01.png|mini|right|200px|Ein speedtest-Device nach dem Geschwindigkeits-Test]]
=== Definition des Moduls ===
<syntaxhighlight lang="perl">
define MySpeedtest speedtest 1800 5255
attr MySpeedtest path /usr/local/bin
</syntaxhighlight>

=== Logging in eine Datei ===

Das Speichern der Ergebnisse in ein Logfile erreicht man z.B. so:
<syntaxhighlight lang="perl">
define FileLog_MySpeedtest FileLog ./log/MySpeedtest-%Y%m.log MySpeedtest:.*
attr FileLog_MySpeedtest logtype text
</syntaxhighlight>

==== Plot (FileLog)====

Ein zugehörige SVG-Plot könnte wie folgt aussehen:
<syntaxhighlight lang="perl">
############################
# Display speedtest results

set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'

set yrange [0:1]
set y2range [0:12]
set y3range [0:120]

set ylabel "Mbit/s"
set y2label "Mbit/s"
set y3label "ms"

#FileLog 4:speedtest.download\x3a::
#FileLog 4:speedtest.upload\x3a::
#FileLog 4:speedtest.ping\x3a::

plot
using 1:2 ls l0 axes x1y2 title 'download (Mbit/s)' with lines,
using 1:2 ls l1 axes x1y1 title 'upload (Mbit/s)' with lines,
using 1:2 ls l2 axes x1y3 title 'ping (ms)' with lines
</syntaxhighlight>

Der Weblink dazu wird wie folgt definiert:
<syntaxhighlight lang="perl">
define wl_speedtest SVG FileLog_speedtest:speedtest3:CURRENT
</syntaxhighlight>

=== Logging mit Hilfe von [[DbLog]] ===

Das Loggen in eine Datenbank erfolgt, wenn ein Reading explizit oder generell alle Readings bei der Definition von [[DbLog]] angegeben worden sind und bei der Definition des Moduls [[Speedtest]] die Readings nicht über ''DbLogExclude'' ausgeschlossen wurden.

==== Plot (DbLog) ====
Definition des Plots bei Verwendung von DbLog:
<syntaxhighlight lang="perl">
define wl_speedtest SVG myDbLog:speedtest:HISTORY
attr wl_speedtest label "DL $data{currval1} / UL $data{currval2} / ping $data{currval3}"
attr wl_speedtest plotfunction speedtest
</syntaxhighlight>

Definition der Datei speedtest.gplots:
<syntaxhighlight lang="perl">
############################
# Display speedtest results

set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'

set yrange [0:1]
set y2range [0:12]
set y3range [0:120]

set ylabel "Mbit/s"
set y2label "Mbit/s"
set y3label "ms"

#myDbLog <SPEC1>:download:::$val=~s/([\d.]*).*/$1/eg
#myDbLog <SPEC1>:upload:::$val=~s/([\d.]*).*/$1/eg
#myDbLog <SPEC1>:ping:::$val=~s/([\d.]*).*/$1/eg

plot
using 1:2 ls l0 axes x1y2 title 'download (Mbit/s)' with lines,
using 1:2 ls l1 axes x1y1 title 'upload (Mbit/s)' with lines,
using 1:2 ls l2 axes x1y3 title 'ping (ms)' with lines
</syntaxhighlight>

== Bekannte Probleme ==
* Für den Betrieb ist Python notwendig. Daher läuft das Script nicht ohne Weiteres auf einer FritzBox.
* Zwischenzeitlich wurde das Script umbenannt. Das Modul erwartet nach wie vor den ursprünglichen Namen. Daher ist wie oben beschrieben darauf zu achten, dass das abgelegte Script <code>speedtest-cli</code> heißt und notfalls dementsprechend umbenannt wird.
* Das Modul bricht ggf. mit einer Perl-Fehlermeldung im FHEM-Log ab, obwohl das Script von der Konsole aus einwandfrei läuft. Dies tritt z.B. bei Verwendung von Rasbian mit installierten Python 2.7 und Python 3 auf. Zur Behebung muss im Script <code>speedtest-cli</code> die erste Zeile auf <code>#!/usr/bin/env python'''3'''</code> geändert werden.
* Auf manchen Systemen muss in aktuellen speedtest-cli Versionen die Zeile <code>'(%s; U; %s; en-us)' % (platform.system(), platform.architecture()[0]),</code> auskommentiert werden.

== Troubleshooting ==
Im Folgenden sind ein paar Ansatzpunkte genannt, um beim Troubleshooting zu unterstützen.

* Das Script läuft auf der Kommandzeile problemlos, das Modul bringt aber Fehler:
** Script ist nicht ausführbar (<code>chmod +x speedtest-cli</code>)
** Der FHEM-User (''fhem'') hat keine Berechtigung das Script auszuführen

* SVG-Plot zeigt nichts an:
** Verweis auf Filelog oder DbLog falsch
** Falsches gplot-File angegeben
** Übergabe der Plotfunktion (bei DbLog) nicht korrekt
** Falsche Groß-/Kleinschreibung verwendet (case sensitive)

* Fehlermeldung ''isn't numeric in sprintf at ./FHEM/98_SVG.pm''
** Dieses kommt grundsätzlich immer dann vor, wenn SVG versucht einen Wert einzulesen, der neben der Zahl auch die Einheit enthält. Dieses kann bei der Verwendung von DbLog vorkommen, weil DbLog nicht weiß, wie es Wert und Einheit trennen soll. Abhilfe schafft eine entsprechende Regular Expression, die nur den Zahlenwert liefert.

== Weblinks ==
* Beschreibung des Scripts [http://binarynature.blogspot.de/2013/03/measure-internet-connection-speed-from-linux-command-line.html binarynature.blogspot.de]
* [https://pypi.python.org/pypi/speedtest-cli speedtest-cli auf pypi.python.org]
* [https://github.com/sivel/speedtest-cli speedtest-cli auf github.com]
* Forumseintrag über die Entwicklung des Moduls {{Link2Forum|Topic=13419|Message=83189|LinkText=Thema: Internetgeschwindigkeit überwachen}}
* Forumseintrag darüber, dass das Binary nicht auf der Fritzbox läuft {{Link2Forum|Topic=27242|Message=201516|LinkText=Thema: Internetgeschwindigkeit - speedtest}}
* Forumseintrag über aus der Idee wird ein Modul {{Link2Forum|Topic=13483|Message=83538|LinkText=Thema: Internetgeschwindigkeit überwachen}}
* Forumsbeitrag zum Einsatz unter Windows {{Link2Forum|Topic= 111602|LinkText=Thema: Speedtest für windows}}

== Sonstiges ==
Besten Dank an wkarl, Puschel74, justme1968 für Idee, Modulerstellung/Pflege und Installationsanleitung.

FHEM Connector for Amazon Alexa

2020-05-19T13:08:29Z

Justme:

{{Baustelle_en}}

Currently the main documentation for this Skill is available only in German. see: [[FHEM_Connector_für_Amazon_Alexa|FHEM Connector für Amazon Alexa]]

==Supported Devices==
This skill supports switches (on and off), lights (on, off, brightness, color temperatuire, color), blinds, thermometers, thermostats, contact sensors, motion detectors, Doorlocks, Alarms und Scenes as well as Speakers, Channel-, Playback- und InputControllers.

See a more complete list in German: [[FHEM_Connector_für_Amazon_Alexa#Was_geht_alles_.3F|Was geht alles?]]

FHEM Connector für Amazon Alexa

2020-05-18T14:24:31Z

Justme: /* Was geht alles ? */

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf einem Zufallsport auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" oder höher vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.

===== 401: Authorization Required =====

Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

===== Permission denied =====

Wenn du folgende Fehlermeldungen im Alexa Logfile siehst, wurde das Verzeichnis "/opt/fhem/.ssh/" von dir bei der Arbeit mit "root" oder "sudo" mit den falschen Berechtigungen versehen:

<syntaxhighlight lang="bash" style="width:90%;">
[2019-7-25 11:59:12] sshautoconf: aborted with ssh-keygen returned error - key_save_private: Permission denied
[2019-7-25 11:59:12] *** SSH: proxy configuration failed: ssh-keygen returned error - key_save_private: Permission denied
</syntaxhighlight>

Prüfen kannst du die Berechtigungen mit folgendem Befehl auf der Shell-Konsole:

<syntaxhighlight lang="bash" style="width:90%;">
ls -l /opt/fhem/.ssh
</syntaxhighlight>

Du solltest dann folgende Ausgabe erhalten:

<syntaxhighlight lang="bash" style="width:90%;">
insgesamt 12
-rw------- 1 fhem dialout 1675 Jul 12 13:10 id_rsa
-rw-r--r-- 1 fhem dialout 391 Jul 12 13:10 id_rsa.pub
-rw-r--r-- 1 fhem dialout 884 Jul 12 13:10 known_hosts
</syntaxhighlight>

Steht in der Ausgabe nicht "fhem dialout" (dein fhem User), sondern bspw. "root root", dann bspw. mit folgendem Befehl an deinen fhem User anpassen:

<syntaxhighlight lang="bash" style="width:90%;">
chown fhem:dialout /opt/fhem/.ssh
</syntaxhighlight>

Mit dem ersten Befehl "ls -l ..." kannst du dann nochmal prüfen, ob die Berechtigungen korrekt übernommen wurden.

===== weitere Prüfungen =====

Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</code>, oder über den Namen bei ''currentlogfile'' in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!
[[Datei:HowToSet alexaName.png|alternativtext=How to set alexaName|ohne|mini|Wie setzt man das Attribut alexaName]]

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: homebridgeMapping On:cmdOn=<ein>,cmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus
* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading <code>temperature</code> geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: homebridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus: homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>
** Kommandos:
*** Alexa, mache <name> heller/dunkler
*** Alexa, Licht heller/dunkler
* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** homebridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** homebridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** homebridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** homebridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** homebridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** homebridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** homebridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** homebridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

* Alarmmelder (noch nicht in Deutschland):
** genericDeviceType Security
** homebridgeMapping Alarm=<reading>[,type=[fireAlarm|waterAlarm|burglaryAlarm|carbonMonoxideAlarm]]
** wenn der type nicht angegeben wird ist fireAlarm der default
** automatisch werden 0, ok und alles was mit no anfängt als OK erkannt. alles andere gilt als ALARM.

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.

==== Dummygeräte: ====
Ein Dummydevice sollte einen Kontaktschalter oder Bewegungssensor simulieren, um dann in FHEM eine beliebige Bedingung als Trigger zu definieren, und eine freie Ansage in Alexa als Routine zu definieren. Hier ein Beispiel:

<syntaxhighlight lang="bash" style="width:90%;">
define voicetrigger1 dummy
attr voicetrigger1 alexaName Trigger 1
attr voicetrigger1 alexaProactiveEvents 1
attr voicetrigger1 genericDeviceType contact
attr voicetrigger1 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;;open:CONTACT_NOT_DETECTED
attr voicetrigger1 readingList 0:closed 1:open
attr voicetrigger1 setList closed open

set alexa add voicetrigger1
set alexa restart
</syntaxhighlight>

'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

== Bug- und Wunschliste ==
* Ist beim Start keine Internetverbindung vorhanden, erfolgt kein Retry -- alexa-fhem muss restartet werden (ssh_autoconfig wertet keine temporären Fehler aus)

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Alexa-Fhem

2020-03-03T14:38:57Z

Justme:

{{Randnotiz|RNTyp=r|RNText='''ACHTUNG''': Diese Seite beschreibt nicht mehr exakt die jeweils nötigen Amazon Seiten. Es ist etwas Interpretation und Verständnis nötig.

Für alle, die neu einsteigen und sich mit dem FHEM Vereinsserver als Proxy anfreunden können, empfiehlt es sich hier: [[FHEM Connector für Amazon Alexa]] einzusteigen.}}

'''alexa-fhem''' ist eine in JavaScript geschriebene und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==Einführung==
===Glossar===
*Echo bzw. Echo Dot (im Folgenden maskulin bezeichnet) sind die derzeit verfügbaren Geräte des Alexa-Systems '''BILDER EINSTELLEN - Achtung Urheberrecht'''
*AVS ist der Amazon Voice Service, d.h. die Spracherkennungskomponente des Systems.
{{Randnotiz|RNTyp=r|RNText=Für die Nutzung der Amazon AWS-Dienste müssen zwingend die Daten einer Kreditkarte angegeben werden. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen. Die Autoren dieser Anleitung und der darin beschriebenen Module übernehmen keine Haftung für eventuelle Kosten, die aus der Nutzung der AWS entstehen. }}
*AWS sind die Amazon Web Services, also per URL erreichbare Dienste zur Ausführung von Berechnungen etc. Im Rahmen von Alexa-Fhem wird bei AWS eine eigene JavaScript-Funktion hinterlegt, die zur Kommunikation mit dem FHEM-Server dient. Im Jargon von Amazon ist dies eine so genannte Lambda-Funktion '''WARUM ? Nachlesen bei Amazon'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht, sowie weitergehende Informationen über die Reaktion von Alexa enthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fertigkeit, Können) ist die Bezeichnung für eine per Spracherkennung zu bedienende Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, Wettervorhersage oder zur Steuerung von FHEM

===Arbeitsweise und Datenfluss===
[[Datei:2gpXyLN.jpg|200px|thumb|right|Grafische Darstellung der beteiligten Komponenten]]
Echo → AVS → AWS Lambda → alexa-fhem → AWS Lambda → AVS → Echo

*Der Echo (oder ein anderes Alexa/AVS fähiges Gerät) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung
*AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den erkannten Daten
:*Beim Alexa SmartHome Skill sind die möglichen Sätze für die Spracherkennung relativ fest vorgegeben
:*Beim Alexa Custom Skill kommen die dazu nötigen Informationen aus dem ''Interaction Model'' der Alexa Skills Configuration
*Das Event wird an den unter ''Configuration'' in der Alexa Skills Configuration hinterlegten Endpoint geschickt
:*Beim Alexa SmartHome Skill ist das zwingend eine AWS Lambda Routine
:*Beim Alexa Custom Skill kann das im Prinzip auch ein eigener Web Service sein
*Das Event wird vom <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> nimmt diese Antwort entgegen und gibt sie an AVS zurück
*AVS sogt dafür das der Echo 'antwortet' und dass die Card in der Alexa App erscheint

===Anmerkungen===
*Ein Skill hat keinen Zugriff auf die Audiodaten
*Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.
*Wenn man berücksichtigt welchen Weg die Daten insgesamt gehen, ist es erstaunlich, wie schnell die Reaktion auf einen gesprochenen Satz erfolgt.

=== Abgrenzung des '''Alexa Smart Home Skills''' und des '''Alexa Custom Skills''' ===

Der [[Alexa-Fhem#Smart_Home|Alexa Smart Home Skill]] ist ein Amazon-Alexa-Standard-Skill, der nur Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.

Der [[Alexa-Fhem#Custom|Alexa Custom Skill]] ist ein individuell entwickelter Skill, so wie die meisten anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch können anspruchsvollere Steuerungsmöglichkeiten auf diese Weise verwirklicht werden.

==Installation==
{{Randnotiz|RNTyp=[g|Info]|RNText=Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Während der Konfiguration sollten alle nachfolgenden Abschnitte parallel in gleichzeitig geöffneten Browserfenstern durchgeführt werden, die jeweils bis zum Abschluss geöffnet bleiben müssen. }}
Grundvoraussetzung für alle folgenden Schritte ist das Vorhandensein eines Amazon-Accounts. Es wird davon ausgegangen, dass die Konten für alle im Folgenden genutzten Amazon-Dienste eingerichtet wurden.

===node.js installieren===
Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss Node.js installiert werden. Versuchen Sie dies erst mit
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs
</syntaxhighlight>
Überprüfen Sie dann die Version mit
<syntaxhighlight lang="bash" style="width:50%;">
dpkg-query -W nodejs
</syntaxhighlight>
Sollte die Versionsnummer kleiner als 8.10 sein, müssen Sie einen Umweg gehen, dazu wird mit den folgenden Befehlen das Node Repository hinzugefügt und node.js (in der LTS Version) entsprechend installiert:
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

===node.js updaten===
Um node.js aus einer vorherige Installation zu updaten (Version 4 ist deprecated und in AWS Amazon nicht mehr unterstützt):
<syntaxhighlight lang="bash" style="width:50%;">
# Zuerst alexa-fhem stoppen, dann
sudo apt-get remove nodejs
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install npm@latest -g

#--> in Amazon Konsole NodeJs auf 8.1 umstellen (Funktion in AWS Konsole editieren, im Pulldown-Menü "Runtime" eine neuere Version auswählen, und speichern)
#--> Raspi Reboot (vielleicht nicht nötig)
</syntaxhighlight>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen!

Die aktuelle Version ist jeweils {{Link2Forum|Topic=81324|Message=733986|LinkText=hier}} zu finden.
Wer bisher noch keinen Alexa-FHEM Skill angelegt hat, bitte {{Link2Forum|Topic=81324|Message=733986|LinkText=diesen Forumsbeitrag}} beachten!

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).<syntaxhighlight lang="bash" style="width:50%;">tar -xvzf dateiname.tgz</syntaxhighlight>
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <syntaxhighlight lang="bash" style="width:50%;">mv package alexa-fhem</syntaxhighlight>
# Durch <syntaxhighlight lang="bash" style="width:50%;">cd alexa-fhem</syntaxhighlight> in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
{{Randnotiz|RNTyp=[g|Info]|RNText=createKey.sh erzeugt ein Zertifikat, das 365 Tage gültig ist. Dies muss deswegen jedes Jahr erneuert werden }}
# SSL Zertifikat erzeugen durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./createKey.sh</syntaxhighlight> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei wird ggf. bei einem manuellen Start von Alexa-Fhem nicht gefunden.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis kopiert werden.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren. Bei der Fehlermeldung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<syntaxhighlight lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">move /y newkey.pem key.pem</syntaxhighlight> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<syntaxhighlight lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">
mkdir ".alexa"</syntaxhighlight>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>\.alexa\config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
===== Linux =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.
===== Windows =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version im Hauptverzeichnis von FHEM entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren.
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.

==== Alexa-Fhem konfigurieren ====
Der Inhalt der Datei ''~/.alexa/config.json'' muss an die eigene Umgebung angepasst werden.
# ''nat-pmp'' -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers, sonst die Zeile löschen!
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'', sonst die Zeile löschen!
# ''applicationId''
#:* Wenn man nur den SmartHome-Skill verwenden möchte, kann dieser Eintrag leer bleiben.
#:* Ansonsten ist er mit der SkillID des Alexa Custom Skills zu belegen, siehe Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
# ''server'' -> IP-Adresse des eigenen FHEM-Servers
# ''port'' -> Portnummer des eigenen FHEM-Servers

Beispiel a) Offenes fhem - System ohne Absicherung:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Beispiel b) Abgesichertes fhem - System mit TLS/SSL und HTTP Basic-Authentication:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"auth": {"user": "fhemuser", "pass": "fhempassword"},
"ssl": true,
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./bin/alexa</syntaxhighlight> den Dienst starten (kein sudo!)

Unter Windows startet man den Alexa-Dienst durch <syntaxhighlight lang="bash" style="width:50%;">node alexa</syntaxhighlight> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.

==== Alexa-Fhem aus FHEM heraus starten ====
Hierbei muss man zunächst herausfinden, welche der folgenden Startvarianten sein LINUX - OS zum Einsatz kommen:
initd.d oder systemd.

Auf keinen Fall darf man "sicherheitshalber" beide Varianten installieren, dies zu Fehler(-meldungen) führt.

===== Vorgehen bei init.d =====
Diese Variante kommt unter anderem auf dem Raspberry Pi mit dem OS-Varianten "Wheezy" zum Einsatz

Zunächst das Start-up-Skript aus diesem Post herunterladen {{Link2Forum|Topic=60244|Message=517271|LinkText=https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271}} und unter /etc/init.d/alexa speichern.

Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.

Nun folgende Kommandos ausführen:
<syntaxhighlight lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</syntaxhighlight>

In der Datei <code>/etc/sudoers</code> den User fhem für die Nutzung von sudo zulassen (<code>sudo nano /etc/sudoers</code>), z.B. durch Anfügen der nachfolgenden Zeile:
<code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<syntaxhighlight lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy

define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart

define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "stop")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "restart")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "status")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})</syntaxhighlight>

===== Vorgehen bei systemd =====
Diese Variante kommt unter anderem auf dem Raspberry Pi ab/seit der OS-Variante "Jessie" zum Einsatz

Bei systemd Systemen funktioniert das obengenannte vorgehen leider nicht, man kann das gleiche aber mit dem Modul
[https://forum.fhem.de/index.php/topic,79952.0.html 98_serviced.pm - systemd und initd Dienste steuern] umsetzen.
Wichtig ist das der User unter dem alexa ausgeführt wird ohne Passwort abfrage sudo ausführen darf, dazu muss er in der <code>/etc/sudoers</code> eingetragen werden, z.b. so <code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Sollte es dann nicht funktionieren kann das an einem Gruppen eintrag unterhalb der User definition in der <code>/etc/sudoers</code>, in diesem Fall den user am ende der <code>/etc/sudoers</code> eintragen, dann sollte es funktionieren

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code style="width:75%;" lang="bash">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa
WorkingDirectory=/opt/fhem/alexa-fhem
ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Den Pfad <code>/home/alexa/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo.

Im WorkingDirectory wird der alexa Dienst die Zertifikate suchen.

Achtung: Natürlich muss der Benutzer auch Zugriff sowohl auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis und das WorkingDirectory haben.

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Sollte sich der Service nicht starten lassen und endet die Ausgabe ähnlich wie hier:
<code>Feb 02 09:47:25 inet alexa[2738]: STDIN EOF</code>
kann eine Anpassung der ExecStart Zeile aus der alexa.service Datei helfen:
ExecStart=/opt/fhem/alexa-fhem/bin/alexa --dockerDetached -U /home/alexa/.alexa
Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== Alexa-Fhem testen ====
Node.Js stellt einen Web-Server am Port 3000 bereit, das oben erzeugte Zertifikat sichert diesen Zugang per SSL ab. Durch Aufruf der Adresse
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== Alexa Device anlegen ===
Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.

Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:
<syntaxhighlight lang="bash" style="width:70%;">define MyAlexa alexa</syntaxhighlight>

<hr />

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Amazon Developer.jpg||200px]]
# Anmeldedaten eingeben [[Datei:LogIn.jpg||200px]]

==== Security Profile anlegen ====
Die Erzeugung eines Sicherheitsprofils muss nur einmal erfolgen, es wird dann für alle weiteren Skills verwendet.
# Nach der Anmeldung Auswahl von ''APPS & SERVICES'' [[Datei:Apps1.jpg|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Security.jpg|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Newsecurity.jpg|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:SecurityName.jpg|200px]]
# Anschließend den die Daten unter ''Gneral'' merken oder Kopieren [[Datei:SecurityGenerl.jpg|200px]]
# Im Anschluß daran auf ''Web Settings'' klicken und dort auf ''Edit'' [[Datei:WebSettings.jpg|200px]]
# Und nun die im Bild gezeigten Daten eintragen [[Datei:WebSettingsDaten.jpg|200px]]
## https://layla.amazon.co.uk/api/skill/link/xxx
## https://pitangui.amazon.com/api/skill/link/xxx
## https://layla.amazon.com/api/skill/link/xxx
# Das xxx muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten SmartHome Skill anlegen bzw. Custom Skill anlegen jeweils unter Punkt 4 (Seite Configuration) bei Redirect Urls am Ende der URLs angezeigt wird
# Im anschluß daran oben auf ''Login with Amazon'' [[Datei:LoginwithAlexa.jpg|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# In der neu geladenen Seite im Dropdown Menü das vorher angelegte Profil unter ''Select a Security Profil'' auswählen und mit ''Confirm'' bestätigen [[Datei:LoginwithAlexaSelect.jpg|200px]]
# Im folgenden Fenster die Adresse https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]

==== Skills bearbeiten (Gilt für den SmartHome wie auch den Customer Skill)====
# Im Menü den Punkt ''ALEXA'' auswählen und anschließend im Dropdown Menü ''Alexa Skills Kit'' auswählen [[Datei:AlexaSkill.jpg|200px]]

===== SmartHome Skill anlegen =====
# Rechts ''Create Skill'' auswählen [[Datei:AlexaSkillCreate.jpg|200px]]
# Auf der folgenden Seite die folgenden Daten eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Default Language'' -> ''German''
#:* ''Choose a model to add to your skill'' -> ''SmartHome '' anklicken
#:* ''Anschließend rechts oben auf ''Create Skill'' [[Datei:AlexaSkillCreateSmart.jpg|200px]]''
# Nun auf die Seite https://signin.aws.amazon.com/ wechseln und dort einloggen [[Datei:AWSAnmelden.jpg|200px]]
# Nach dem Login links oben auf ''Services'' klicken und anschließend auf ''Lambda'' [[Datei:AWSLambda.jpg|200px]]
# Auf der ''Lambda'' Seite "Funktion' auswählen links im Menü und dann rechts auf ''Funktion erstellen'' klicken [[Datei:LamdbaFunktion.jpg|200px]]
# Auf der Seite ''Funktion erstellen'' dann auf ''Ohne Vorgabe erstellen' klicken''
#:* Unter ''Name'' einen Beliebigen Namen eingeben
#:* Bei ''Laufzeit'' ''Nodejs 8.10'' auswählen
#:* Unter ''Rolle'' ''Erstellen einer benutzerdefinierten Rolle'' auswählen, im anschluß daran sollte sich automatisch ein neues Fenster öffnen, in diesem alles unverändert lassen und auf ''Allow'' klicken wodurch sich das Fenster wieder schließen sollte [[Datei:IAM.jpg|200px]]
#:*Jetzt noch rechts unten auf ''Funktion erstellen klicken'' [[Datei:OhneVorgabe.jpg|200px]]

# Auf der jetzt geöffneten Seite rechts oben die ''arn'' Nummer aufschreiben/kopieren und links aus dem Menü ''Alexa Smart Home'' hinzufügen [[Datei:Arn.jpg|200px]]
# Unten auf der Seite unter ''Auslöser konfigurieren'' muss die Skill ID eingetragen werden, diese findet man im developer account unter dem Skill. [[Datei:Auslöser.jpg|200px]]
# Anschließend noch rechts unten auf ''Hinzufügen'' klicken und danach rechts oben auf ''Speichern''

# Nun auf ''Test'' (Bezeichnung im Screenshot) klicken und unten auf der Seite unter ''Funktionscode'' den vorhanden Code löschen und den Code aus der ''Lambda.js'' welche sich in dem ''alexa-fhem-0.4.4'' Paket befindet einfügen [[Datei:Arn2.jpg|200px]]
 [[Datei:Code.jpg|200px]]
# Im Code müsst ihr den ''Hostname'' anpassen, also eure DynDns z.b. einfügen, anschließen rechts oben wieder auf ''Speichern''

# Nun wieder zurück in den Alexa developer Account und hier folgende Daten eintragen
{{Randnotiz|RNTyp=r|RNText=Es funktioniert nur noch die v3 api (v2 ist deprecated). Die Version hierfür gibt es im {{Link2Forum|Topic=81324|LinkText=Forum}}. bitte die hinweise dort lesen und beachten.}}
#:* ''Payload Version'' -> ''v3(preferred)'' auswählen 
#:* ''Default endpoint'' -> Hier die ''arn'' Nummer von oben eintragen/einfügen
#:* Dann den Haken setzen bei ''Europe, India'' und nochmals die ''arn'' eintragen und anschließend rechts oben auf ''Save''
# Links im Menü ''Account Linking'' auswählen und dort folgende Daten eintragen
#:* ''Authorization URI'' -> ''https://www.amazon.com/ap/oa''
#:* ''Access Token URI'' -> ''https://api.amazon.com/auth/o2/token''
#:* ''Client ID'' -> ''Eure Client ID, fängt mit amzn......an'', zu finden unter ''https://developer.amazon.com'' -> '' Apps & Services'' -> ''Security Profiles'' -> Profil auswählen -> ''Web Settings''
#.* ''Client Secret'' -> ''Euer Client Secret'', siehe ''Client ID''
#:* ''Scope'' -> ''Add Scope'' auswählen und ''profile:user_id'' (wörtlich 1:1 eintragen) eintragen
#:* ''Redirect URLs'' -> Diese 3 Adressen merken/kopieren
# Alles andere auf dieser seite kann gleich bleiben, jetzt noch rechts oben wieder auf ''Save'' klicken [[Datei:Account.jpg|200px]]

# Anschließend wieder zurück zum ''Amazon developer Account'' https://developer.amazon.com , dort wieder das ''Security Profile'' aufrufen und die drei Links unter ''Allowed Return URLs'' (wo eingangs am Schluss 3 XXX gesetzt wurden) mit den Links von Oben ''Redirect URLs'' ersetzen
# Nun geht es weiter in der ''Amazon Alexa developer Konsole'' https://developer.amazon.com/alexa/console/ask wo oben auf ''Distribution'' geklickt werden muss.
# Hier sind alle angaben Freiwillig bzw. können Frei gewählt werden bis auf die ''Privacy Policy URL'' , diese muss eingetragen werden, anschließend links unten auf ''Save and continue'' [[Datei:German.jpg|200px]]

# Auf der kommenden Seite ''Privacy & Compliance'' entsprechend anklicken und wieder unter auf ''Save and continue''
# Unter ''Availability'' alles so lassen und wieder auf ''Save and continue''
# Nun den Alexa Service auf dem Fhem Rechner neustarten, den Skill in der Alexa App aktivieren und nach geräten suchen lassen

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) in das Feld ''TYPE'' eingetragen werden, das nach dem Anklicken von ''Add Slot Type'' erscheint. In das darunter liegende größere Textfeld kommen die möglichen Werte für diesen Slot, so wie sie aus der FHEM-Ausgabe abzulesen sind. Dann mit ''Save'' sichern. Als Custom Slot Type erscheint dann für diesen Beispiel-Slot
FHEM_article der | die | das | den
d.h., die Zeilenumbrüche bei den möglichen Werten werden als "|" dargestellt.</li>
<li>Hier muss nun ein Bruch im Arbeitsfluss durchgeführt werden, denn bei der Erstellung des Custom Skills kommt es auf die Reihenfolge der Einträge an. Deshalb zunächst diese FHEM-Ausgabe schließen, und für dasselbe FHEM-Device <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> '''<code>profile:user_id</code>''' (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
Beim Sichern dieser Seite mit ''Next'' kann es zu einer Fehlermeldung kommen, wenn man seine Skill-Definitionen mit dem einfachen SmartHome-Skill begonnen hat. Deshalb muss noch der entsprechende Trigger für die [[#AWS_Lambda-Funktion | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== Testen ====
Hat man den Custom Skill angelegt, bietet dieser auch eine komfortable Testmöglichkeit. Dazu wählt man in der Übersichtsseite ''All Skills'' den Button ''Edit'' des Alexa Custom Skill aus. Auf der nachfolgenden Seite dann links ''Test''.
Die Testseite enthält
* ein Feld ''Voice Simulator'', mit dem man die Sprachsausgabe testen kann,
* ein Feld ''Service Simulator'', mit dem die Verarbeitung von Alexa-Kommandois getestet werden kann. Hier kann man z.B. eintragen
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Siebenundzwanzig Uhr"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"

Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr />

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]

==== AWS Lambda Funktion anlegen ===={{Randnotiz|RNTyp=r|RNText=Die AWS Seiten sehen inzwischen etwas anders aus. Eine angepasste Beschreibung findet sich im {{Link2Forum|Topic=81790|Message=739211|LinkText=Forum}}. Bitte auch die Hinweise dort lesen.}}
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## Achtung, es ist möglich, dass dabei ''Alexa Smart Home'' überhaupt nicht angeboten wird. Dann bitte ganz rechts oben in der Ecke nachsehen, welche Region bzw. welches Land ausgewählt ist. Empfohlen wird, ''Ireland'' auszuwählen. Dann erscheint bei den Funktionen auch ''Alexa Smart Home''.
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung im Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 6.10 (oder 8.10).
## ''Role'' -> ''Choose an existing role''
### Achtung: wenn es noch keine existing role gibt, zuerst ''Create a custom role'' -> in dem Popup dann ''lambda_basic_execution'' auswählen und auf ''Allow'' klicken sowie bei ''Existing role'' dann ''x'' wählen.
# Auf der Code-Seite ist im großen Textfeld dann der Code aus der Datei ''lambda.js'' im Paket [[#Alexa-Fhem_installieren | Alexa-Fhem]] vollständig einzufügen. Dabei muss der vorhandene Code im Texteil komplett gelöscht, der Teil aus der ''lamda.js'' eingefügt und noch der Hostname im Quellcode an den eigenen Hostnamen angepasst werden.
# Anschließend alles mit ''Next'' bestätigen. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== Trigger für Custom Skill hinzufügen ====
Editiert man eine Lambda-Funktion, werden auf der Seite ''Triggers'' diejenigen Dienste angezeigt, die diese Funktion aufrufen.
* Hier taucht der Trigger ''Alexa Smart Home'' zusammen mit der ''Application Id'' auf, der bei der Einrichtung des SmartHome-Skills eingetragen wurde.
* Zur Verbindung mit dem Custom Skill ist es nötig, einen zweiten Trigger hinzuzufügen. Durch Anklicken von ''Add Trigger'' wird eine Auswahlseite eingeblendet. Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Skills Kit' auswählen und mit ''Next'' bestätigen''

==== ARN der AWS Lambda Funktion bestimmen ====
# Auf der Übersichtsseite oben links den Menüpunkt ''Functions'' aúswählen [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm

htpasswd <passwdfile> <username>

ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>

Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern

'''const PORT=443;'''

const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)

Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== Einrichtung in der Alexa App==
Nachdem die Alexa Skills angelegt wurden, müssen diese noch in der Alexa App eingerichtet werden.
Dafür jeweils per Desktop-Browser auf [http://alexa.amazon.de alexa.amazon.de] anmelden, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.

=== Alexa Skill ===
# Auf ''Skills'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.

Tip: Es macht Sinn, unter ''Meine Gruppen'' Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.

== Einrichtung unter FHEM ==
Im Folgenden werden exemplarisch ein paar Geräte beschrieben, die man nutzbringend mit FHEM einsetzen kann.

Bei Verwendung des Custom Skills übersetzt die Kombination der Attribute ''alexaMapping'' und ''homebridgeMapping'' Sprachbefehle ("Intents") in gerätespezifische Kommandos.
* Das Attribut alexaMapping wird am Alexa-Device gesetzt und dient dazu, erkannte Sprachkommandos in abstrakte Characteristiken zu überführen. Für den einfacheren SmartHome Skill hat darum das Attribut ''alexaMapping'' keine Bedeutung, sondern nur der ''genericDeviceType'' des zu steuernden Gerätes.
* Das Attribut homebridgeMapping wird für beide Skills am zu steuernden Gerät gesetzt und übersetzt diese Charakteristiken in die konkreten Befehle, die das Gerät versteht. Der inhalt des Attributs wird von links nach rechts ausgewertet und ist wie folgt aufgebaut:
** Das Attribut enthält eine durch Leerzeichen getrennte Liste aus Konfigurationen für jeweils eine Characteristik
** Jede einzelne der Characteristik-Konfigurationen besteht aus dem Namen der Characteristik, gefolgt von "=" und einer kommaseparierten Liste von Parametern.
attr <device> homebridgeMapping <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...
** Jeder Parameter besteht entweder aus
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> kann auch an Stelle einer ganzen Characteristik-Konfiguration stehen
Weiter führende Dokumentation zum homebridgeMapping findet sich unter https://forum.fhem.de/index.php/topic,48558.0.html

=== Einfacher Schalter ===
* Ein einfacher Schalter, der die set-Kommandos ''on'' und ''off'' kennt, kann direkt mit Alexa-Fhem gekoppelt werden
* Für kompliziertere Aktionen, etwa das Übermitteln eines spezifischen Schaltbefehls an FHEM, ist die Einrichtung eines Dummies zu empfehlen.
Ob Dummy oder nicht, wichtig sind die drei fett gedruckten Zeilen

define Alexa.Party dummy

'''attr Alexa.Party alexaName party'''
'''attr Alexa.Party alexaRoom alexaroom'''
'''attr Alexa.Party genericDeviceType switch'''
attr Alexa.Party group AlexaGeräte
attr Alexa.Party room AlexaRoom
attr Alexa.Party setList on off

Selbstverständlich kann man diesen Dummy mit einem notify oder DOIF abfangen, um die gewünschte Schaltaktion auszuführen.

Ein Alternative zum Dummy ist das Anlegen eines readingsProxy, dem die entsprechenden Attribute gegeben werden.

Weil es sich hierbei um eines der einfachen Geräte handelt, die Alexa selbst im SmartHome Skill bearbeiten kann, ist auch der zweite Schritt bei der Einrichtung in der Alexa App sinnvoll: Der Schalter wird dann im Bereich Smart Home der Alexa App erkannt. Wer ihn auch mit dem Custon Skill bedienen möchte, muss natürlich Sorge tragen, dass der Alexa-Name ''party'' bei den FHEM_Devices auftaucht und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sind (siehe Abschnitt [[##Custom_Skill_anlegen | Custom Skill Anlegen]]).

=== Wecker ===
Dieses Gerät kann man nur mit dem Custom Skill bedienen, es wird also '''nicht''' im Bereich Smart Home der Alexa App auftauchen. Wir richten einen Dummy ein, wichtig sind wieder die fett gedruckten Zeilen:

define Alexa.Weckzeit dummy

'''attr Alexa.Weckzeit alexaName weckzeit'''
'''attr Alexa.Weckzeit alexaRoom alexaroom'''
attr Alexa.Weckzeit genericDeviceType clock
attr Alexa.Weckzeit group AlexaGeräte
'''attr Alexa.Weckzeit homebridgeMapping Weckzeit=state,cmd=+'''
attr Alexa.Weckzeit room AlexaRoom
'''attr Alexa.Weckzeit setList Weckzeit:time'''

Das Attribut ''genericDeviceTye'' ist nicht wichtig, weil es ein generisches Device dieser Art gar nicht gibt. Wichtig hingegen ist das Attribut ''homebridgeMapping''

Für das Gerät ''MyAlexa'', das in Abschnitt definiert wurde, muss im Attribut ''alexaMapping'' auftauchen

Weckzeit=verb=stelle,valuePrefix=für;auf,values=AMAZON.TIME,valueSuffix=uhr

Darüber hinaus muss der Alexa-Name ''weckzeit'' bei den FHEM_Devices auftauchen und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sein (siehe Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

Zur weiteren Bearbeitung kann man jetzt mit einem DOIF Statusänderungen des Dummies abfangen und durch eine kleine Helperfunktion ins "echte" FHEM weiterleiten.

define Alexa.Weckzeit.N DOIF (["Alexa.Weckzeit:.*"])({AlexaHelper("Alexa.Weckzeit","$EVENT")})

Die Helperfunktion (z.B. in 99_myUtils.pm) stellt aus der übergebenen Zeit (immer im Format dd:mm) eine sprachkompatible Nachricht $nc und einen mit den FHEM-Zeitangaben kompatiblen String $nt zusammen und reicht beide an eine Routine ''changeWakeTime'' weiter (dokumentiert in den [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks]).
sub AlexaHelper($$){
my ($name,$event)=@_;
if( $name eq "Alexa.Weckzeit" ){
my ($nc,$nt);
#-- volle Stunde----------------------------------------
if( $event =~ /(\d+):00/ ){
$nc=sprintf("%d Uhr",$1);
$nt=sprintf("%02d:00:00",$1);
#-- nicht volle Stunde---------------------------------
}elsif( $event =~ /(\d+):(\d+)/ ){
$nc=sprintf("%d Uhr %d",$1,$2);
$nt=sprintf("%02d:%02d:00",$1,$2);
}
changeWakeTime(\'GalaxyTab.EG\',\'$nc\',\'$nt\');
}
}

<hr />

=== Lichtszene ===
Eine Lichtszene wird mit dem Modul LightScene angelegt. Wir gehen davon aus, dass in der Lichtszene die beiden Szenen Alle_An und Alle_Aus, sowie mindestens eine weitere Szene (hier: Sitzgruppe) definiert wurde.
* Nachfolgend wird ein Beispiel beschrieben, wie man eine Lichtszene mit dem einfachen SmartHome Skill steuern kann. Die verwendeten Kommandos sind dann
<pre>
"Alexa, schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
"Alexa, schalte (die) Beleuchtungsitzgruppe an" -> LightScene Sitzgruppe wird ausgewählt
...
"Alexa, schalte (die) Beleuchtung aus" -> LightScene Alle_Aus wird ausgewählt
</pre>
* Künftig wird man LightScene mit dem Custom Skill eventuell direkt steuern können - allerdings hat das einen geringeren WAF, als die Steuerung über den SmartHome Skill: Der Einschaltsatz muss dann mindestens lauten
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

Im ersten Schritt wird ein Dummy für die Gesamtbeleuchtung eingerichtet:

define Alexa.Beleuchtung dummy

attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung alexaName beleuchtung'''
'''attr Alexa.Beleuchtung alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung genericDeviceType switch'''

Anschließend wird für jede vorhandene Lichtszene (außer Alle_An und Alle_Aus) ein weiterer Dummy angelegt:

define Alexa.Beleuchtung.Sitzgruppe dummy

attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung.Sitzgruppe alexaName beleuchtungsitzgruppe'''
'''attr Alexa.Beleuchtung.Sitzgruppe alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung.Sitzgruppe genericDeviceType switch'''

Die eigentliche Steuerung übernimmt dann ein DOIF

define Alexa.Beleuchtung.N DOIF

(["Alexa.Beleuchtung.Sitzgruppe:on"])
(set <devicename der Lichtszene> scene Sitzgruppe,
set Alexa.Beleuchtung off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSIF
... <weitere on-Events der anderen Szenen werden abgefangen>
DOELSEIF
(["Alexa.Beleuchtung:on"])
(set <devicename der Lichtszene> scene Alle_An,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSEIF
(["Alexa.Beleuchtung:off"])
(set <devicename der Lichtszene> scene Alle_Aus,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)

Mit diesem DOIF wird ein Radiobutton simuliert, d.h. wie bei den Stationstasten vor Uralt-Radios sorgt die Auswahl einer Szene immer dafür, dass alle anderen Dummies ausgeschaltet werden.
Natürlich kann man das auch mit einem kleinen Perl-Programm erreichen.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

=== Harmony Hub ===
Ein [https://forum.fhem.de/index.php/topic,60244.msg550298.html#msg550298 HowTo-Beitrag im Forum] beschreibt die Ansteuerung von Harmony-Aktionen über den Custom Skill, beispielsweise für eine Aktion ''ARD'': „Alexa, sage FHEM stelle Anlage auf ARD“.

== Nutzung ==
Um den Namen zu bestimmen, unter dem ein Gerät mit Alexa angesprochen wird, verwendet Alexa-Fhem mit absteigender Priorität:
* das alexaName Attribut
* das alias Attribut
* das NAME Internal
Damit Alexa ein Gerät eindeutig identifizieren kann, sollten eindeutige Gerätenamen verwendet werden, bestehed möglichst aus einem Wort und ohne Ziffern. Wenn Alexa einen Namen nicht versteht, kann man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und den Gerätenamen ggf. anpassen.

=== SmartHome Skill ===
Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.

Nach erfolgreicher Einrichtung des SmartHome Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:
<pre style="width:50%;">
“alexa, schalte <gerät/gruppe> ein”
“alexa, schalte <gerät/gruppe> aus”
“alexa, stelle <gerät/gruppe> auf <wert> prozent”
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”
</pre>

=== Custom Skill ===
Der Custom Skill erlaubt im Gegensatz zum SmartHome Skill eine weitreichende Konfiguration der möglichen Kommandos. Die Dokumentation ist aktuell noch über diverse Artikel im Wiki verstreut:

*Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=hier}} beschrieben.
*Die erste Umsetzung ist {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} beschrieben.
*Mehr zu FHEM-Intents und deren Möglichkeiten gibt es {{Link2Forum|Topic=67490|Message=589378|LinkText=hier}}.
*Wie man die Alexa TTS-Engine bei den Antworten auf FHEM-Intents beeinflussen kann {{Link2Forum|Topic=77421|Message=693631|LinkText=hier}}.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions), alles hier sammeln.

== Troubleshooting ==

====Allgemeiner Hinweis====
Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein ''http://'' davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von UnityMedia z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276}}

Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können.
Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.

Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde.

Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter ''Internet -> Freigaben -> Portfreigaben'' statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.

Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: ''https://mein.hostname:3000''. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.

Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.

====Probleme mit node.js - npm install====

Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|Python, g++, MDNS installieren]], siehe auch folgenden Abschnitt.

====Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich====
Wenn man auf der Konsole angemeldet ist, den Befehl<syntaxhighlight lang="bash" style="width:50%;">node -v</syntaxhighlight>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter [[Homebridge_einrichten#NodeJS_installieren]] nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter [[Alexa-Fhem#Voraussetzungen]] erfüllt sind! Keine Experimente mit Versionen die darunter liegen.

====Fehlermeldung ''NAT-PMP failed: Error: timeout'' Fehler angezeigt beim Start von alexa-fhem====
Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: ''NAT-PMP failed: Error: timeout'', lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.

====Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder====
Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder.

Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.

====Was ist zu tun, wenn alexa-fhem keine Geräte findet?====
Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut ''genericDeviceType switch'' hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut ''alias'' eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann.
Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.

====Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?====
Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:
* wenn nichts bei alexa-fhem ankommt: port forwarding prüfen
* wenn lambda.js nichts los wird: im cloudwatch log nachsehen
* wenn bei lambda.js nichts ankommt: den trigger prüfen

Zunächst sollte man sich unter ''http://aws.amazon.com'' das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger.
Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf ''Triggers'' klicken und mit ''Add trigger'' erneut einen anlegen. Hier muss, wie in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 7, die ''Application Id'' stehen und der Haken bei ''Enable trigger'' gesetzt sein. Dann alexa-fhem neu starten.
Wenn ihr Änderungen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt. Fürs Debugging empfiehlt es sich, alexa-fhem in einer Konsole laufen zu lassen, um eingehende Anfragen mitverfolgen zu können.

Es kann sein, dass immer noch keine Log im Cloudwatch ([http://docs.aws.amazon.com/de_de/lambda/latest/dg/monitoring-functions-logs.html]) zu sehen ist. In dem Fall hilft es, eine neue Role Policy anzulegen.
* in der AWS Console [https://console.aws.amazon.com] oben links auf Services klicken, und in der Gruppe "Security, Identity & Compliance" auf IAM klicken
* links auf Roles klicken
* Auf dem Knopf "Create Role" klicken
* AWS Services > Lambda auswählen, unten auf Next:Permissions klicken
* im Filter / Policy Type, "log" eintragen (ohne quotes)
* CloudWatchLogsFullAccess hacken, auf Next:Review unten klicken
* Name vergeben und mit "Create role" bestätigen
* Oben links auf Services klicken, und in der Gruppe "Compute", auf Lambda klicken
* auf den Name der Funktion klicken
* Reiter Configuration auswählen
* in Existing Role, den neukreierten Role auswählen
* oben auf Save (und Testen wenn gewünscht) klicken.
Schon sollte eine neue Gruppe im Cloudwatch sichtbar sein. Die Suche von den Devices in Alexa wiederholen, und die Logs analysieren

====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====
{{Randnotiz|RNTyp=[g|Info]|RNText=Der User in der User= Directive von alexa.service muss Ausführungsrecht auf dem alexa binary haben (x), so wie auch mind. Lesezugriff auf dem Verzeichnis nach -U Option in der ExecStart= Directive und auch auf dem WorkingDirectory }}
Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei ''alexa'' muss ausführbar sein. Also z.B. so:
<syntaxhighlight lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</syntaxhighlight>
Sollte dies nicht der Fall sein bitte mit:
<syntaxhighlight lang="bash" style="width:70%;">chmod +x alexa</syntaxhighlight>
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

Eine lauffähige Konfiguration ist {{Link2Forum|Topic=71612|Message=668383|LinkText=hier}} zu sehen.

Ein Fehler in der Rechtekonfiguration führt in der Regel zu folgendem Ergebnis nach <code>sudo systemctl status alexa</code>:

<syntaxhighlight lang="bash"> Loaded: loaded (/etc/systemd/system/alexa.service; enabled)
Active: activating (auto-restart) (Result: exit-code) since mer. 2017-09-06 02:33:23 CEST; 3s ago
Process: 18332 ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa (code=exited, status=217/USER)
Main PID: 18332 (code=exited, status=217/USER)</syntaxhighlight>

====Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?====

Hierzu muss die Datei <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FHEM Connector for Amazon Alexa

2020-02-26T10:43:57Z

Justme:

{{Baustelle_en}}

Currently the main documentation for this Skill is available only in German. see: [[FHEM_Connector_für_Amazon_Alexa|FHEM Connector für Amazon Alexa]]

FHEM Connector for Amazon Alexa

2020-02-26T10:35:07Z

Justme: englische version angefangen

{{Baustelle_en}}

Currently the main documentation for this Skill is available only in German. see: [[FHEM_Connector_für_Amazon_Alexa]]

Vorlage:Baustelle en

2020-02-26T10:32:02Z

Justme: englische version hinzugefügt

{| class="wikitable centered" cellpadding="10" style="margin: 1em auto;"
| align="center" | [[Image:Clock - Under Construction.svg|40px]]
| align="center" | '''This Page is Work in progress.'''
|}

<includeonly>
[[Kategorie:Baustelle]]
</includeonly>
<noinclude>
<templatedata>
{
"params": {},
"description": {
"en": "Work in progress indicator"
}
}
</templatedata>

Die Vorlage ''Baustelle_en'' wird derzeit verwendet auf den [[Special:Linkliste/Vorlage:Baustelle_en|hier]] gelisteten Seiten.

[[Kategorie:Vorlage]]
</noinclude>

FHEM Connector für Amazon Alexa

2020-02-20T17:14:56Z

Justme: bewegungsmelder hinzugefügt

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf einem Zufallsport auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" oder höher vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.

===== 401: Authorization Required =====

Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

===== Permission denied =====

Wenn du folgende Fehlermeldungen im Alexa Logfile siehst, wurde das Verzeichnis "/opt/fhem/.ssh/" von dir bei der Arbeit mit "root" oder "sudo" mit den falschen Berechtigungen versehen:

<syntaxhighlight lang="bash" style="width:90%;">
[2019-7-25 11:59:12] sshautoconf: aborted with ssh-keygen returned error - key_save_private: Permission denied
[2019-7-25 11:59:12] *** SSH: proxy configuration failed: ssh-keygen returned error - key_save_private: Permission denied
</syntaxhighlight>

Prüfen kannst du die Berechtigungen mit folgendem Befehl auf der Shell-Konsole:

<syntaxhighlight lang="bash" style="width:90%;">
ls -l /opt/fhem/.ssh
</syntaxhighlight>

Du solltest dann folgende Ausgabe erhalten:

<syntaxhighlight lang="bash" style="width:90%;">
insgesamt 12
-rw------- 1 fhem dialout 1675 Jul 12 13:10 id_rsa
-rw-r--r-- 1 fhem dialout 391 Jul 12 13:10 id_rsa.pub
-rw-r--r-- 1 fhem dialout 884 Jul 12 13:10 known_hosts
</syntaxhighlight>

Steht in der Ausgabe nicht "fhem dialout" (dein fhem User), sondern bspw. "root root", dann bspw. mit folgendem Befehl an deinen fhem User anpassen:

<syntaxhighlight lang="bash" style="width:90%;">
chown fhem:dialout /opt/fhem/.ssh
</syntaxhighlight>

Mit dem ersten Befehl "ls -l ..." kannst du dann nochmal prüfen, ob die Berechtigungen korrekt übernommen wurden.

===== weitere Prüfungen =====

Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</code>, oder über den Namen bei ''currentlogfile'' in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst! 
 

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: hombridgeMapping On:cmdOn=<ein>,cmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus
* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading <code>temperature</code> geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: hombridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus: homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>
** Kommandos:
*** Alexa, mache <name> heller/dunkler
*** Alexa, Licht heller/dunkler
* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** hombridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** hombridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** hombridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** hombridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** hombridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.
'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

== Bug- und Wunschliste ==
* Ist beim Start keine Internetverbindung vorhanden, erfolgt kein Retry -- alexa-fhem muss restartet werden (ssh_autoconfig wertet keine temporären Fehler aus)

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FHEM Connector für Amazon Alexa

2020-02-20T07:31:24Z

Justme:

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf einem Zufallsport auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" oder höher vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.

===== 401: Authorization Required =====

Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

===== Permission denied =====

Wenn du folgende Fehlermeldungen im Alexa Logfile siehst, wurde das Verzeichnis "/opt/fhem/.ssh/" von dir bei der Arbeit mit "root" oder "sudo" mit den falschen Berechtigungen versehen:

<syntaxhighlight lang="bash" style="width:90%;">
[2019-7-25 11:59:12] sshautoconf: aborted with ssh-keygen returned error - key_save_private: Permission denied
[2019-7-25 11:59:12] *** SSH: proxy configuration failed: ssh-keygen returned error - key_save_private: Permission denied
</syntaxhighlight>

Prüfen kannst du die Berechtigungen mit folgendem Befehl auf der Shell-Konsole:

<syntaxhighlight lang="bash" style="width:90%;">
ls -l /opt/fhem/.ssh
</syntaxhighlight>

Du solltest dann folgende Ausgabe erhalten:

<syntaxhighlight lang="bash" style="width:90%;">
insgesamt 12
-rw------- 1 fhem dialout 1675 Jul 12 13:10 id_rsa
-rw-r--r-- 1 fhem dialout 391 Jul 12 13:10 id_rsa.pub
-rw-r--r-- 1 fhem dialout 884 Jul 12 13:10 known_hosts
</syntaxhighlight>

Steht in der Ausgabe nicht "fhem dialout" (dein fhem User), sondern bspw. "root root", dann bspw. mit folgendem Befehl an deinen fhem User anpassen:

<syntaxhighlight lang="bash" style="width:90%;">
chown fhem:dialout /opt/fhem/.ssh
</syntaxhighlight>

Mit dem ersten Befehl "ls -l ..." kannst du dann nochmal prüfen, ob die Berechtigungen korrekt übernommen wurden.

===== weitere Prüfungen =====

Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</code>, oder über den Namen bei ''currentlogfile'' in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst! 
 

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: hombridgeMapping On:cmdOn=<ein>,cmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus

* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading temperature geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: hombridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus:
*** homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>

**Kommandos:
***Alexa, mache <name> heller/dunkler
***Alexa, Licht heller/dunkler

* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** hombridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** hombridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** hombridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** hombridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.
'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

== Bug- und Wunschliste ==
* Ist beim Start keine Internetverbindung vorhanden, erfolgt kein Retry -- alexa-fhem muss restartet werden (ssh_autoconfig wertet keine temporären Fehler aus)

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Hue

2020-01-17T11:59:25Z

Justme: /* Mögliche andere Gateways */

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge eu.re.ip.1</code>
wird die Bridge eingebunden. Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

Das HUEBridge Modul erkennt, wenn ein Leuchtmittel zwischen einer Hue und einer deCONZ Bridge (oder umgekehrt) wechselt und verschiebt das zugehörige HUEDevice in FHEM jeweils zum richtigen Bridge-Device. D.h. wenn z.B. zum Firmwareupdate die Bridge gewechselt wird, ist auf FHEM Seite nichts weiter zu tun.

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ unter Proxmox auf einem Intel Nuc ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</source>
:oder
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</source>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<source lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</source>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<source lang="bash">
qm set 804 -usb0 host=0403:6015
</source>

* Installation von deCONZ:
:<source lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</source>

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

=== Installation von deCONZ auf einem RaspberryPI ===
Für den ConBee2 [https://phoscon.de/en/conbee2/install#raspbian kann der guten Installation von Phoscon gefolgt werden]. Entweder ihr installiert deCONZ direkt (wie hier beschrieben) oder über einen Docker Container. Der Docker Container hat ein paar Einschränkungen bzgl. Firmware Updates.

Der ausführende Benutzer muss dialout Rechte haben um auf /dev/tty* zugreifen zu dürfen:
:<source lang="bash">
sudo gpasswd -a pi dialout
</source>
Im Standard wird deCONZ mit dem pi-Benutzer (user id 1000) ausgeführt.

Das deCONZ Repository bei APT hinzufügen (Vorteil davon ist dass später ganz normal mit sudo apt update/upgrade deCONZ aktualisieren könnt):
:<source lang="bash">
wget -O - http://phoscon.de/apt/deconz.pub.key | \
sudo apt-key add -;
sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
$(lsb_release -cs) main' > \
/etc/apt/sources.list.d/deconz.list";
sudo apt update
</source>

deCONZ installieren:
:<source lang="bash">
sudo apt install deconz
</source>

Wenn ihr euren RaspberryPI mit UI betreibt, kann deCONZ über ''Menu > Programming > deCONZ'' aufgerufen werden. Es gibt aber auch den Service-Modus, der ohne X11 funktionert. Hierfür die Datei ''/lib/systemd/system/deconz.service'' anpassen (ich habe z.B. den Port des Webservers geändert) und den Service wie folgt aktivieren:
:<source lang="bash">
systemctl enable deconz.service
</source>

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom lib-Verzeichnis nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

ZigBee

2020-01-17T11:58:11Z

Justme: /* Firmware updates */

== Allgemeines ==
[[ZigBee]] ist eine Spezifikation für drahtlose Netzwerke mit geringem Datenaufkommen, wie beispielsweise Hausautomation, Sensornetzwerke oder Lichttechnik. Der Schwerpunkt von ZigBee liegt in kurzreichweitigen Netzwerken (bis 100 Meter). Es sind via vermaschtem Netz (auch Meshnetzwerk) aber auch Reichweiten von mehreren Kilometern möglich.

Die Spezifikation ist eine Entwicklung der ZigBee-Allianz, die Ende 2002 gegründet wurde. Die Allianz ist ein Zusammenschluss von derzeit mehr als 230 Unternehmen, welche die weltweite Entwicklung dieser Technologie vorantreiben.

== Gerätetypen ==
=== Endgerät (ZigBee End Device, ZED) ===
Geräte, wie zum Beispiel Steuerungs- oder Sensormodule, werden meist mit Batterien betrieben. Diese können als ZigBee-Endgeräte implementiert werden und benötigen nur einen Teil der Funktionen der ZigBee-Spezifikation. Sie nehmen nicht am Routing im Netzwerk teil und können in einen Schlafmodus gehen. Sie melden sich an einem Router ihrer Wahl an und treten so dem ZigBee-Netzwerk bei. Sie können ausschließlich mit dem Router kommunizieren, über den sie dem Netzwerk beigetreten sind. Werden Daten an ein solches Endgerät geschickt, welches sich im Schlafmodus befindet, speichert der Router diese Pakete, bis das Endgerät sie abruft.

=== Router (ZigBee-Router, ZR) ===
ZigBee-Router nehmen am Routing der Pakete durch das Netzwerk teil. Sie benötigen einen größeren Funktionsumfang und damit auch etwas mehr Hardwareressourcen. ZigBee-Router treten einem Netzwerk bei, indem sie sich an einem im Netzwerk befindlichen Router anmelden. Das Routing im Netzwerk erfolgt entweder entlang eines sich so bildenden Baumes (Stackprofil ZigBee) oder durch dynamisches Routing als Meshnetzwerk.

'''Ein ZigBee Router hat so ungefähr die Funktion wie ein WLAN Repeater...'''

=== Koordinator (ZigBee coordinator, ZC) ===
Ein ZigBee-Koordinator startet das Netzwerk mit festgelegten Parametern. Nach dem Start übernimmt er dieselben Aufgaben wie ein ZigBee-Router.
Es kann nur einen Koordinator in einem ZigBee Netz geben.
'''In FHEM wird ein solches Gerät Gateway genannt.'''

== Mischen von Komponenten unterschiedlicher Hersteller ==
Prinzipiell ist es möglich, die Komponenten unterschiedlicher Hersteller zu mischen. Dies kann interessant sein, da jeder Hersteller andere Schwerpunkte in der Modellpalette hat, nicht jeder Hersteller alle Leuchtmittel-Typen vertreibt und sich auch die Eigenschaften und Preise für vergleichbare Leuchtmittel unterscheiden. Auch der in FHEM verfügbare Funktionsumfang unterscheidet sich je nach Bridge.

Leuchtmittel sind in der Regel am unproblematischsten. Taster auch wenn sie direkt die Leuchtmittel steuern. Über die Bridge sind in der Regel aber oft nur die Taster des jeweiligen Herstellers direkt abfragbar bzw. in FHEM einzubinden. Dies gilt auch für Bewegungsmelder und sonstige Sensoren.

Im einzelnen sollte man sich also vor dem Kauf informieren, welche Komponenten tatsächlich problemlos zusammen arbeiten.

Beim Vergleich der Kosten muss aber die jeweilige Bridge des Herstellers zusätzlich mit berücksichtigt werden (siehe [[#Firmware updates]]).

=== Firmware updates ===
Es ist sinnvoll oder sogar zwingend nötig, neue Leuchtmittel zumindest einmal bei der Inbetriebnahme auf den aktuellen Firmwarestand zu bringen. Gerade wenn Komponenten herstellerübergreifend verwendet werden sollen, ist sonst oft mit Einschränkungen oder sogar Problemen zu rechnen.

Hierzu ist aktuell in der Regel<ref>Der Diskussionsstand 11/2018 hierzu ist diesem {{Link2Forum|Topic=93836|LinkText=Forenthread}} zu entnehmen.</ref> die zugehörige original Bridge (und oft auch die App) des jeweiligen Herstellers nötig, d.h., auch wenn man z.B. Osram LIGHTIFY oder IKEA Trådfri Leuchtmittel an einer Hue Bridge betreiben möchte, braucht man zumindest am Anfang einmal auch noch die Osram und IKEA Bridge und muss das Leuchtmittel jeweils an- und ab- und wieder anlernen.

Aktualisierungen der Hue Bridge und Hue Leuchtmittel lassen sich direkt aus FHEM heraus anstoßen.

Das HUEBridge Modul erkennt, wenn ein Leuchtmittel zwischen einer Hue und einer deCONZ Bridge (oder umgekehrt) wechselt und verschiebt das zugehörige HUEDevice in FHEM jeweils zum richtigen Bridge-Device. D.h. wenn z.B. zum Firmwareupdate die Bridge gewechselt wird, ist auf FHEM Seite nichts weiter zu tun.

== Einbindung in FHEM ==
Prinzipiell lässt sich hier vorwegschicken, dass die FHEM Hue-Module (ob mit einer Philips Hue Bridge oder mit der Dresden Elektronik Software) den größten Funktionsumfang ermöglichen.

=== Hersteller-Bridges ===
Wir benötigen also zur Einbindung ein Gateway. Manche Nutzer haben sich gleich ein Starterkit wie Philips Hue oder IKEA Trådfri gekauft.
Diese Lösungen haben den Vorteil, dass Alexa-Integration etc. sowie die Smartphone-App gleich mitkommen, und das Einbinden der Endgeräte, aber vor allem aber Softwareupdates i.d.R. herstellerproprietär gelöst wurden.

Der Nachteil ist, dass die Lösungen bis hin zum gut dokumentierten Hue-System mit API in anderer Hinsicht geschlossene Systeme sind. So ist z.B. über die Hue-Bridge die Abfrage von Hue-Bewegungssensoren oder -Tastern nur per Polling durch FHEM möglich - es gibt keinen Event-Mechanismus, der FHEM notifizieren könnte (siehe [[#Freie Lösungen]]). Alle 5 Minuten die Bridge fragen (= Pollen), ob der Bewegungsmelder jemanden gesehen hat und ggf. das Licht ausschalten, ist also per Polling machbar, auf einen ZigBee-Tasterdruck oder Bewegung hin via FHEM die WiFi-Steckdose schalten hingegen eher zu verzögert.

Außerdem ist unser Ziel ja, die Steckerleiste der Steuergeräte kurz zu halten.

Auch die native HomeKit- (Siri) oder Alexa-Integration ist mit kleinen oder größeren Problemen und Einschränkungen behaftet, diese sind unter anderem:
* nur Steuerung der herstellereigenen Leuchtmittel
* Verzögerung der Statusaktualisierung in FHEM, wenn an FHEM vorbei geschaltet wird
* Eventuell 'Cloud-Zwang' des jeweiligen Herstellers
* Eventuell erhöhter Ressourcenverbrauch auf der jeweiligen Bridge durch zusätzliche Verbindungen
Diese Nachteile gibt es bei einer Integration über FHEM nicht.

==== Hue Bridge von Philips ====
Siehe [[Hue]]. Eine gute Dokumentation kompatibler Geräte findet sich [https://iconnecthue.com/supported-devices/ hier]. Hue ist wohl die meist verbreitete Bridge und hat auch ein dokumentiertes REST-API. Jedoch ist die Anzahl der Endgeräte (offiziell: 50) und Regeln (ca. 200) stärker als bei anderen Lösungen begrenzt und Events können nicht zu FHEM weitergeleitet werden.

==== Trådfri von IKEA ====
Siehe {{Link2Forum|Topic=70653}} und [[TRÅDFRI]].

==== Lightify von Osram ====
Siehe {{Link2Forum|Topic=28339}}. Auch hier geht nur Polling von Events, ebenfalls max. 50 Geräte, und der Nutzerkreis ist kleiner.

=== Andere Lösungen ===
Die Alternative sind Lösungen, die spezielle Hardware erfordern, wie den RaspBee (Aufsteckmodul für Raspberry) oder Conbee (USB-Gateway) von Dresden Elektronik oder manche Module mit Chips des Herstellers [https://github.com/Koenkk/zigbee2mqtt/wiki/Supported-sniffer-devices Texas Instruments], und die zusätzlich nötige Software auf dem Raspberry etc. mitlaufen lassen. Eine reine Hardware-Lösung ohne Zusatzsoftware, in der FHEM die Software-Funktionen des Gateway vollständig abbildet, gibt es nicht - FHEM kommuniziert lediglich mit einer Software, die ebenfalls auf dem - ggf. gleichen - Computer mitläuft.

==== Dresden Elektronik ====
Das Dresden Elektronik System ermöglicht aktuell als einziges der 'fertigen' Systeme auch das aktive Senden von Events und somit eine 'fast Echtzeit' Reaktion auf Taster, Bewegungsmelder oder Ähnliches. Realisiert ist das über eine Push Erweiterung im ansonsten weitgehend Hue kompatiblen API. Auch die Integration von Tastern und anderen Sensoren unterschiedlichster Hersteller ist mit der DE Software gut möglich. Die Anbindung an FHEM (inklusive Push) erfolgt über die HUE-Module.

==== Direkt per MQTT ====
Siehe [[MQTT2-Module - Praxisbeispiele#zigbee2mqtt]]

==== Das Modul von Neumann ====
Siehe diesen Forenbeitrag: {{Link2Forum|Topic=84790}}

== Funkübertragung ==

=== Reichweite erhöhen ===
* Eine brauchbare WLAN Antenne (2,4GHz) an einen CC2531 "Stick" oder ein anderes Gateway anbauen (eher für Experten)
* ein CC2530 als Gateway oder in der Mitte als Repeater (Achtung verschiedene Firmwares erforderlich. Gute Antenne muss meist gesondert gekauft werden, anstatt der beigelegten)
* ZigBee ist ein Mesh-Netz, daher irgendwo auf dem Weg ein ZigBee-Gerät verbauen, welches immer eingeschaltet ist (z.B. ZigBee Funksteckdose)
{{Hinweis|Da derselbe Frequenzbereich wie WLAN genutzt wird, kann es auch zu Interferenzen mit diesem kommen. In diesen Fall kann es sinnvoll sein, für eine der beiden Techniken einen anderen Kanal zu wählen.}}

== Sicherheit ==
=== Sicherheitsrelevante Geräte ===
Welche Geräte sicherheitsrelevant sind, ist eine sehr schwierige Frage. Beim Türschloss ist das klar. Wenn ein Temperatursensor dafür sorgt, dass ein Raum nicht mehr beheizt und daraufhin wegen geplatztem Heizkörper die Wohnung geflutet wird, so ist dies schon etwas schwerer zu erkennen...

=== Bekannte Sicherheitslücken ===
==== Insecure Rejoin ====
Insecure Rejoin ist eine der Schwachstellen im Protokoll. ZigBee 3.0 wurde 2015 freigegeben und soll das Problem lösen. Allerdings ist ZigBee 3.0 (Stand Ende 2018) noch immer recht wenig verbreitet.

Ablauf des Insecure Rejoin aus Angreifersicht:
* einen Node aus dem Netz werfen, um nicht auf die Aktivierung neuer Geräte warten zu müssen
* der Node versucht erneut Mitglied im Netz zu werden. Schlüsselaustausch erfolgt mittels dem Key "ZigBeeAlliance09"
* Mitsniffen des neuen Schlüssels

Quelle: Link zu Golem.de über die Forschung von Tobias Zillner

==== DDOS ====
* manipulierte Counter (können sogar manche HW zerstören)
* Jamming (einfach die Frequenz belegen mit beliebigem Signal)
* Flutung mit ZigBee Messages

Quelle: https://research.kudelskisecurity.com/2017/11/21/zigbee-security-basics-part-3/

== Links ==
* https://www.golem.de/news/smart-home-sicherheitsluecken-im-zigbee-protokoll-demonstriert-1511-117657-2.html

[[Kategorie:ZigBee|!]]

ZigBee

2020-01-17T11:57:49Z

Justme: /* Mischen von Komponenten unterschiedlicher Hersteller */

== Allgemeines ==
[[ZigBee]] ist eine Spezifikation für drahtlose Netzwerke mit geringem Datenaufkommen, wie beispielsweise Hausautomation, Sensornetzwerke oder Lichttechnik. Der Schwerpunkt von ZigBee liegt in kurzreichweitigen Netzwerken (bis 100 Meter). Es sind via vermaschtem Netz (auch Meshnetzwerk) aber auch Reichweiten von mehreren Kilometern möglich.

Die Spezifikation ist eine Entwicklung der ZigBee-Allianz, die Ende 2002 gegründet wurde. Die Allianz ist ein Zusammenschluss von derzeit mehr als 230 Unternehmen, welche die weltweite Entwicklung dieser Technologie vorantreiben.

== Gerätetypen ==
=== Endgerät (ZigBee End Device, ZED) ===
Geräte, wie zum Beispiel Steuerungs- oder Sensormodule, werden meist mit Batterien betrieben. Diese können als ZigBee-Endgeräte implementiert werden und benötigen nur einen Teil der Funktionen der ZigBee-Spezifikation. Sie nehmen nicht am Routing im Netzwerk teil und können in einen Schlafmodus gehen. Sie melden sich an einem Router ihrer Wahl an und treten so dem ZigBee-Netzwerk bei. Sie können ausschließlich mit dem Router kommunizieren, über den sie dem Netzwerk beigetreten sind. Werden Daten an ein solches Endgerät geschickt, welches sich im Schlafmodus befindet, speichert der Router diese Pakete, bis das Endgerät sie abruft.

=== Router (ZigBee-Router, ZR) ===
ZigBee-Router nehmen am Routing der Pakete durch das Netzwerk teil. Sie benötigen einen größeren Funktionsumfang und damit auch etwas mehr Hardwareressourcen. ZigBee-Router treten einem Netzwerk bei, indem sie sich an einem im Netzwerk befindlichen Router anmelden. Das Routing im Netzwerk erfolgt entweder entlang eines sich so bildenden Baumes (Stackprofil ZigBee) oder durch dynamisches Routing als Meshnetzwerk.

'''Ein ZigBee Router hat so ungefähr die Funktion wie ein WLAN Repeater...'''

=== Koordinator (ZigBee coordinator, ZC) ===
Ein ZigBee-Koordinator startet das Netzwerk mit festgelegten Parametern. Nach dem Start übernimmt er dieselben Aufgaben wie ein ZigBee-Router.
Es kann nur einen Koordinator in einem ZigBee Netz geben.
'''In FHEM wird ein solches Gerät Gateway genannt.'''

== Mischen von Komponenten unterschiedlicher Hersteller ==
Prinzipiell ist es möglich, die Komponenten unterschiedlicher Hersteller zu mischen. Dies kann interessant sein, da jeder Hersteller andere Schwerpunkte in der Modellpalette hat, nicht jeder Hersteller alle Leuchtmittel-Typen vertreibt und sich auch die Eigenschaften und Preise für vergleichbare Leuchtmittel unterscheiden. Auch der in FHEM verfügbare Funktionsumfang unterscheidet sich je nach Bridge.

Leuchtmittel sind in der Regel am unproblematischsten. Taster auch wenn sie direkt die Leuchtmittel steuern. Über die Bridge sind in der Regel aber oft nur die Taster des jeweiligen Herstellers direkt abfragbar bzw. in FHEM einzubinden. Dies gilt auch für Bewegungsmelder und sonstige Sensoren.

Im einzelnen sollte man sich also vor dem Kauf informieren, welche Komponenten tatsächlich problemlos zusammen arbeiten.

Beim Vergleich der Kosten muss aber die jeweilige Bridge des Herstellers zusätzlich mit berücksichtigt werden (siehe [[#Firmware updates]]).

=== Firmware updates ===
Es ist sinnvoll oder sogar zwingend nötig, neue Leuchtmittel zumindest einmal bei der Inbetriebnahme auf den aktuellen Firmwarestand zu bringen. Gerade wenn Komponenten herstellerübergreifend verwendet werden sollen, ist sonst oft mit Einschränkungen oder sogar Problemen zu rechnen.

Hierzu ist aktuell in der Regel<ref>Der Diskussionsstand 11/2018 hierzu ist diesem {{Link2Forum|Topic=93836|LinkText=Forenthread}} zu entnehmen.</ref> die zugehörige original Bridge (und oft auch die App) des jeweiligen Herstellers nötig, d.h., auch wenn man z.B. Osram LIGHTIFY oder IKEA Trådfri Leuchtmittel an einer Hue Bridge betreiben möchte, braucht man zumindest am Anfang einmal auch noch die Osram und IKEA Bridge und muss das Leuchtmittel jeweils an- und ab- und wieder anlernen.

Aktualisierungen der Hue Bridge und Hue Leuchtmittel lassen sich direkt aus FHEM heraus anstoßen.

Das HUEBridge Modul erkennt, wenn ein Leuchtmittel zwischen einer Hue und einer deCONZ Bridge (oder umgekehrt) wechselt und verschiebt das zugehörige HUEDevice in FHEM jeweils zum richtigen Bridge-Device. D.h. wenn z.b. zum Firmwareupdate die Bridge gewechselt wird, ist auf FHEM Seite nichts weiter zu tun.

== Einbindung in FHEM ==
Prinzipiell lässt sich hier vorwegschicken, dass die FHEM Hue-Module (ob mit einer Philips Hue Bridge oder mit der Dresden Elektronik Software) den größten Funktionsumfang ermöglichen.

=== Hersteller-Bridges ===
Wir benötigen also zur Einbindung ein Gateway. Manche Nutzer haben sich gleich ein Starterkit wie Philips Hue oder IKEA Trådfri gekauft.
Diese Lösungen haben den Vorteil, dass Alexa-Integration etc. sowie die Smartphone-App gleich mitkommen, und das Einbinden der Endgeräte, aber vor allem aber Softwareupdates i.d.R. herstellerproprietär gelöst wurden.

Der Nachteil ist, dass die Lösungen bis hin zum gut dokumentierten Hue-System mit API in anderer Hinsicht geschlossene Systeme sind. So ist z.B. über die Hue-Bridge die Abfrage von Hue-Bewegungssensoren oder -Tastern nur per Polling durch FHEM möglich - es gibt keinen Event-Mechanismus, der FHEM notifizieren könnte (siehe [[#Freie Lösungen]]). Alle 5 Minuten die Bridge fragen (= Pollen), ob der Bewegungsmelder jemanden gesehen hat und ggf. das Licht ausschalten, ist also per Polling machbar, auf einen ZigBee-Tasterdruck oder Bewegung hin via FHEM die WiFi-Steckdose schalten hingegen eher zu verzögert.

Außerdem ist unser Ziel ja, die Steckerleiste der Steuergeräte kurz zu halten.

Auch die native HomeKit- (Siri) oder Alexa-Integration ist mit kleinen oder größeren Problemen und Einschränkungen behaftet, diese sind unter anderem:
* nur Steuerung der herstellereigenen Leuchtmittel
* Verzögerung der Statusaktualisierung in FHEM, wenn an FHEM vorbei geschaltet wird
* Eventuell 'Cloud-Zwang' des jeweiligen Herstellers
* Eventuell erhöhter Ressourcenverbrauch auf der jeweiligen Bridge durch zusätzliche Verbindungen
Diese Nachteile gibt es bei einer Integration über FHEM nicht.

==== Hue Bridge von Philips ====
Siehe [[Hue]]. Eine gute Dokumentation kompatibler Geräte findet sich [https://iconnecthue.com/supported-devices/ hier]. Hue ist wohl die meist verbreitete Bridge und hat auch ein dokumentiertes REST-API. Jedoch ist die Anzahl der Endgeräte (offiziell: 50) und Regeln (ca. 200) stärker als bei anderen Lösungen begrenzt und Events können nicht zu FHEM weitergeleitet werden.

==== Trådfri von IKEA ====
Siehe {{Link2Forum|Topic=70653}} und [[TRÅDFRI]].

==== Lightify von Osram ====
Siehe {{Link2Forum|Topic=28339}}. Auch hier geht nur Polling von Events, ebenfalls max. 50 Geräte, und der Nutzerkreis ist kleiner.

=== Andere Lösungen ===
Die Alternative sind Lösungen, die spezielle Hardware erfordern, wie den RaspBee (Aufsteckmodul für Raspberry) oder Conbee (USB-Gateway) von Dresden Elektronik oder manche Module mit Chips des Herstellers [https://github.com/Koenkk/zigbee2mqtt/wiki/Supported-sniffer-devices Texas Instruments], und die zusätzlich nötige Software auf dem Raspberry etc. mitlaufen lassen. Eine reine Hardware-Lösung ohne Zusatzsoftware, in der FHEM die Software-Funktionen des Gateway vollständig abbildet, gibt es nicht - FHEM kommuniziert lediglich mit einer Software, die ebenfalls auf dem - ggf. gleichen - Computer mitläuft.

==== Dresden Elektronik ====
Das Dresden Elektronik System ermöglicht aktuell als einziges der 'fertigen' Systeme auch das aktive Senden von Events und somit eine 'fast Echtzeit' Reaktion auf Taster, Bewegungsmelder oder Ähnliches. Realisiert ist das über eine Push Erweiterung im ansonsten weitgehend Hue kompatiblen API. Auch die Integration von Tastern und anderen Sensoren unterschiedlichster Hersteller ist mit der DE Software gut möglich. Die Anbindung an FHEM (inklusive Push) erfolgt über die HUE-Module.

==== Direkt per MQTT ====
Siehe [[MQTT2-Module - Praxisbeispiele#zigbee2mqtt]]

==== Das Modul von Neumann ====
Siehe diesen Forenbeitrag: {{Link2Forum|Topic=84790}}

== Funkübertragung ==

=== Reichweite erhöhen ===
* Eine brauchbare WLAN Antenne (2,4GHz) an einen CC2531 "Stick" oder ein anderes Gateway anbauen (eher für Experten)
* ein CC2530 als Gateway oder in der Mitte als Repeater (Achtung verschiedene Firmwares erforderlich. Gute Antenne muss meist gesondert gekauft werden, anstatt der beigelegten)
* ZigBee ist ein Mesh-Netz, daher irgendwo auf dem Weg ein ZigBee-Gerät verbauen, welches immer eingeschaltet ist (z.B. ZigBee Funksteckdose)
{{Hinweis|Da derselbe Frequenzbereich wie WLAN genutzt wird, kann es auch zu Interferenzen mit diesem kommen. In diesen Fall kann es sinnvoll sein, für eine der beiden Techniken einen anderen Kanal zu wählen.}}

== Sicherheit ==
=== Sicherheitsrelevante Geräte ===
Welche Geräte sicherheitsrelevant sind, ist eine sehr schwierige Frage. Beim Türschloss ist das klar. Wenn ein Temperatursensor dafür sorgt, dass ein Raum nicht mehr beheizt und daraufhin wegen geplatztem Heizkörper die Wohnung geflutet wird, so ist dies schon etwas schwerer zu erkennen...

=== Bekannte Sicherheitslücken ===
==== Insecure Rejoin ====
Insecure Rejoin ist eine der Schwachstellen im Protokoll. ZigBee 3.0 wurde 2015 freigegeben und soll das Problem lösen. Allerdings ist ZigBee 3.0 (Stand Ende 2018) noch immer recht wenig verbreitet.

Ablauf des Insecure Rejoin aus Angreifersicht:
* einen Node aus dem Netz werfen, um nicht auf die Aktivierung neuer Geräte warten zu müssen
* der Node versucht erneut Mitglied im Netz zu werden. Schlüsselaustausch erfolgt mittels dem Key "ZigBeeAlliance09"
* Mitsniffen des neuen Schlüssels

Quelle: Link zu Golem.de über die Forschung von Tobias Zillner

==== DDOS ====
* manipulierte Counter (können sogar manche HW zerstören)
* Jamming (einfach die Frequenz belegen mit beliebigem Signal)
* Flutung mit ZigBee Messages

Quelle: https://research.kudelskisecurity.com/2017/11/21/zigbee-security-basics-part-3/

== Links ==
* https://www.golem.de/news/smart-home-sicherheitsluecken-im-zigbee-protokoll-demonstriert-1511-117657-2.html

[[Kategorie:ZigBee|!]]

HUE Dimmer Switch

2019-12-22T19:05:49Z

Justme:

'''Philips HUE DimmerSwitch in FHEM einbinden'''

Die HUE Dimmer Switches sind relativ günstig (ca. 24.-€). Sie haben 4 Tasten, welche sich mit [http://iconnecthue.com/ iConnectHUE] völlig frei und teilweise auch mehrfach belegen lassen. Der eigentliche Schalter ist via Magnet perfekt auf einer Schalter-/Montageplatte eingepasst und lässt sich abnehmen und so als Fernbedienung nutzen.

Offiziell lassen sich diese Schalter (eigentlich sind es Taster) nur mit der HUE-Bridge betreiben und tauchen in FHEM etc. auch gar nicht auf. Hier nun ein Weg, um dieses Problem zu umgehen und die Schalter auch in FHEM nutzen zu können.

Als Grundvoraussetzung wird eine fertig eingerichtete [[Hue|Philips HUE-Bridge]] vorausgesetzt.

Mit
:<code>get huebridge1 sensors</code>
in FHEM auf der HUE-Bridge ausgeführt bekommt man eine Liste aller bisher an der Bridge angelernten Schalter. Wobei ''huebridge1'' der Name der HUE-Bridge ist, dieser Wert muss an die Gegebenheiten der eigenen Konfiguration angepasst werden.

Die Ausgabe sieht dann z.B. so aus:

1: Daylight Daylight
2: Flurschalter 1 ZLLSwitch
3: Flurschalter 2 ZLLSwitch
4: Badezimmerschalter 1 ZLLSwitch
5: Spiegelschalter ZLLSwitch
6: Badezimmerschalter 2 ZLLSwitch

Merken muss man sich nun nur noch die ID des Schalters, welchen man in FHEM verwenden möchte. Im Beispiel z.B. für den Flurschalter 1 die 2.

Nun legt man mit der Anweisung
:<code>define Flurschalter_1 HUEDevice sensor 2 1 </code>
das [http://fhem.de/commandref.html#HUEDevice HUEDevice] an.

Danach taucht der Schalter in FHEM auf und kann beliebig verwendet werden.

'''Eines gibt es aber zu beachten:'''

Im Beispiel ist der Wert für <Interval> auf 1 gesetzt.

Die Schalter haben dann State Readings in dieser Form:

''
On-Taste entspricht 100x

Dimmer up Taste entspricht 200x

Dimmer down Taste entspricht 300x

Off-Taste entspricht 400x''

Wobei das x den Tastenzustand wiederspiegelt.

0 entspricht INITIAL_PRESSED - dem initalen Tastendruck (von FHEM nicht nutzbar/empfangbar)

1 entspricht HOLD - dem Event während die Taste gehalten wird (für FHEM wenig sinnvoll)

2 entspricht SHORT RELEASED - dem von FHEM abfragbaren Event nachdem ein kurzer Tastendruck beendet ist

3 entspricht LONG RELEASED - dem von FHEM abfragbaren Event nachdem ein langer Tastendruck beendet ist

Die ON Taste lang zu drücken erzeugt auf der Bridge nacheinander beispielsweise folgende Events: 1000 - 1001 - (1001) - 1003

iConnectHue kann das sauber auswerten und erzeugt damit die Mehrfachbelegungen der Tasten. In FHEM ist das so leider nicht einfach zu reproduzieren.
Das Notify muss dann entsprechend aussehen, damit die letzte Ziffer des Readings des Schalters nicht beachtet wird:

''define <Name des Notify> notify <Name des HUESwitch auf den reagiert werden soll>:100.* set <Schaltaktor> on''

Äquivalent sieht das natürlich für die anderen 3 Tasten des Schalters aus. Dort muss dann eben nur die 100.* gegen die 200.*,300.* oder 400.* getauscht werden.

Wer also eine HUE-Bridge hat, kann damit recht günstige Schalter in seinem FHEM Universum nutzen. Für das HUE Universum lassen sich die Schalter weiterhin ohne weiteres gleichzeitig nutzen.

[[Kategorie:ZigBee]]
[[Kategorie:Schalter (Sender)]]

Hue

2019-12-09T20:21:13Z

Justme: /* HUE-Device */

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge eu.re.ip.1</code>
wird die Bridge eingebunden. Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ unter Proxmox auf einem Intel Nuc ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</source>
:oder
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</source>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<source lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</source>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<source lang="bash">
qm set 804 -usb0 host=0403:6015
</source>

* Installation von deCONZ:
:<source lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</source>

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom lib-Verzeichnis nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

DevelopmentModuleIntro

2019-11-15T18:32:21Z

Justme:

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}

== Einleitung ==

Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.

In fhem.pl wird der <code>define</code>-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist. Falls nicht, wird ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und, falls vorhanden, anschließend geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt und durch welche Perl-Funktionen im Modul selbst diese ausimplementiert werden.

In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''_''['''Modulname''']''.pm</code>

* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<syntaxhighlight lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Hilfsmodule
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deutsche Commandref in HTML
=end html

# Ende der Commandref
=cut
</syntaxhighlight>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].

== Der Hash einer Geräteinstanz ==
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.

Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind.

In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per <code>select()</code> überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion ([[#X_Ready|X_Ready]]) implementieren, welche prüft, ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt, beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert um die Daten zu interpretieren und Werte in Readings geschrieben.

Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.

Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant. Durch eine Prüfung auf <code>$init_done</code> kann man erkennen, ob eine Definition von Hand (<code>$init_done</code> = 1) oder im Rahmen der Initialisierung (FHEM Start / Rereadcfg => <code>$init_done</code> = 0) erfolgte. Während der Initialisierung stehen bspw. die gesetzten Attribute der Definition noch nicht zur Verfügung und können daher nicht ausgewertet werden (siehe .
|-
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.
|-
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.
|-
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.
|-
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert.
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.
|-
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.

Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.
|-
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.
|}

Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.

== Internals ==
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.

Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.

Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:

* <code>$hash->{helper}{URL}</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.
* <code>$hash->{'''.'''ELEMENT}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].
|-
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.
|-
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".
|-
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".
|-
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten.
|-
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten.
|-
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via [[DevIo]]), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.
|-
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.

Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code>
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code>
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen, je nach Hardwareperformance, spürbare Last auf dem System (siehe [[DevelopmentModuleIntro#X_Notify|NotifyFn]]), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</syntaxhighlight>

Um Readings zu löschen, wird die <code>readingsDelete</code> Routine empfohlen. Beispiel:

<syntaxhighlight lang="perl">
readingsDelete($hash, $readingsname)
</syntaxhighlight>

Hintergrundinfo dazu aus dem Forum: https://forum.fhem.de/index.php/topic,83069.msg753066.html#msg753066

:<code>CommandDeleteReading</code> bzw. <code>deletereading</code> ist eher fuer den Endbenutzer und seine userReadings gedacht, und macht bei den Modulen die unnoetige Schleife ueber devspec2array. Wenn der Modulautor beim Aufruf auch $cl weitergibt, und der Anwender meint, dieses Geraet auf blacklist setzen zu muessen, dann kann das Modul sein eigenes Reading nicht entfernen, und das ist kontraproduktiv.

== Events ==

FHEM verfügt über einen Event-Mechanismus um Änderungen verschiedenster Art an einzelne oder alle Definitionen mitzuteilen. Jedes Modul (und damit alle Definitionen dieses Moduls) können auf Events von FHEM selber (Definition <code>global</code>) oder von anderen Definitionen reagieren und dadurch selber aktiv werden. Ein Event wird innerhalb von FHEM als Zeichenkette behandelt.

Events sind grundsätzlich immer definitionsbezogen. Das bedeutet, dass ein Event immer in Verbindung mit einem Definitionsnamen erzeugt wird. Jede Definition, welche ein Event verarbeitet, erhält den Definitions-Hash (<code>$hash</code>) der auslösenden Definition.

Events werden typischerweise bei der Erstellung von Readings implizit für jedes einzelne Reading erzeugt. Es gibt jedoch auch Events die nichts mit Readings zu tun haben um anderweitige Änderungen bekannt zu geben.

Eigene Events können in FHEM mit der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] erzeugt werden. Um auf Events in einem Modul reagieren zu können, muss eine [[#X_Notify|Notify]]-Funktion implementiert sein. Sobald ein oder mehrere Events für eine Definition getriggert werden, prüft FHEM, welche Definitionen über Events der auslösenden Definition informiert werden möchten. Diese werden dann nacheinander in einer bestimmten Reihenfolge durch Aufruf der [[#X_Notify|Notify]]-Funktion über anstehende Events in Kenntnis gesetzt. Es obliegt dann dem jeweiligen Modul, wie es auf die Events reagiert.

=== globale Events ===

Als "globale Events" werden alle Events bezeichnet, die durch die Definition <code>global</code> erzeugt werden. Es handelt sich hierbei um Events die Strukturänderungen in der Konfiguration, als auch systemweite Ereignisse zu FHEM selbst signalisieren.

Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:

Allgemeine Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>INITIALIZED</code>''' || Der Start von FHEM ist abgeschlossen. Sämtliche Definitionen und Attribute wurden aus der Konfiguration (fhem.cfg oder configDB) eingelesen, sowie sämtliche Readings sind aus dem State-File eingelesen und stehen nun voll umfänglich zur Verfügung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>REREADCFG</code>''' || Die Konfiguration wurde erneut eingelesen. Dies bedeutet, es wurden alle Definitionen/Attribute/Readings aus FHEM entfernt und durch Einlesen der Konfiguration neu angelegt. (FHEM-Befehl: "rereadcfg")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SAVE</code>''' || Die laufende Konfiguration soll gespeichert werden (in fhem.cfg oder configDB). Dieses Event wird '''VOR''' dem Speichern der Konfiguration getriggert. Sobald der Trigger verarbeitet wurde, beginnt das Speichern der Konfiguration. (FHEM-Befehl: "save")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code> DELAYEDSHUTDOWN </code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")
|}

Definitionsbezogene Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DEFINED ''<Name>''</code>''' || Es wurde eine neue Definition mit Namen <code>''<Name>''</code> angelegt. (FHEM-Befehl: "define")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DELETED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde gelöscht. (FHEM-Befehl: "delete")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>RENAMED ''<Alt>'' ''<Neu>''</code>''' || Die Definition mit dem Namen <code>''<Alt>''</code> wurde in den Namen <code>''<Neu>''</code> umbenannt. (FHEM-Befehl: "rename")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UNDEFINED ''<Name> <Modul> <Define-Parameter>''</code>''' || Es wurde eine Nachricht von einem physikalischen Modul (siehe [[#Zweistufiges Modell für Module|zweistufiges Modulkonzept]]) erhalten, für die keine passende logische Definition in FHEM existiert. Details dazu, siehe dazu Abschnitt [[#Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)|Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)]].
|}

=== Begrenzung von Events ===

Ein Modul, welches Events verarbeitet, kann die Eventverarbeitung auf bestimmte Definitionen begrenzen. Dadurch werden nur Events an das Modul gemeldet (via [[#X_Notify|X_Notify()]]), welche von einer oder mehreren bestimmten Definitionen getriggert wurden. Dadurch werden unnötige Events nicht an das Modul gemeldet und schont somit Ressourcen.

Standardmäßig werden sämtliche Events ohne Begrenzung an ein Modul gemeldet, welches eine [[#X_Notify|Notify]]-Funktion implementiert hat und somit Events verarbeiten kann. Details zur Begrenzung von Events findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

=== Reihenfolge der Eventverarbeitung ===

Ein getriggertes Event wird nacheinander gegen jede Definition geprüft, deren Modul eine [[#X_Notify|Notify]]-Funktion implementiert hat. Dies bedeutet, jede Definition wird nacheinander durch Aufruf der [[#X_Notify|Notify]]-Funktion mit dem Definitionshash der auslösenden Definition aufgerufen.

Unter bestimmten Umständen kann es erforderlich sein, in diese Reihenfolge einzugreifen. Beispielsweise wenn das eigene Modul und deren Definitionen das Event als letztes oder erstes verarbeiten müssen. Ein Beispiel bietet hierbei das Modul [[dewpoint]], welches Events vor allen anderen Modulen verarbeiten muss.

Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

== Attribute ==
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).

Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.

== Modulfunktionen ==

Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.
|}

Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable"| Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.
|-
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.
|-
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|-
| [[#X_DelayedShutdown | X_DelayedShutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</syntaxhighlight>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von fhem.pl nach dem Laden des Moduls aufgerufen und bekommt eine leere Hashreferenz für den Initialisierungsvorgang übergeben.

Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:

<syntaxhighlight lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
$hash->{DelayedShutdownFn} = "X_ DelayedShutdown";
</syntaxhighlight>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:

<syntaxhighlight lang="perl">
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</syntaxhighlight>

Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu {{Link2CmdRef|Anker=readingFnAttributes|Label=readingFnAttributes}}.

Nutzung von parseParams()

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modul-Autoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.

Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight>
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Define-Funktion eines Moduls wird von FHEM aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.) oder einen [[#Pollen_von_Geräten|Status-Timer]] zu starten.
Sie beginnt typischerweise mit:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</syntaxhighlight>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<syntaxhighlight lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</syntaxhighlight>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:

<syntaxhighlight lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</syntaxhighlight>

Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.

Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.

Verfügbarkeit von Attributen

Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</syntaxhighlight>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

Nutzung von parseParams()

Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams()]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams() automatisch aufgerufen und X_Define() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Undef ====
<syntaxhighlight lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>
Die Undef-Funktion wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls <code>rereadcfg</code>, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu einliest. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern, sofern diese im Modul zum Pollen verwendet wurden (siehe Abschnitt [[#Pollen_von_Geräten|Pollen von Geräten]]).

Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.

==== X_Delete ====
<syntaxhighlight lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird.

Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<syntaxhighlight lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)

return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.

==== X_Get ====
<syntaxhighlight lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</syntaxhighlight>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des get-Befehls übergeben. Als Rückgabewert wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt));

if($opt eq "status")
{
...
}
elsif($opt eq "power")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax einhalten um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' status</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert direkt abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Get() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<syntaxhighlight lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
return ($error, $skip_trigger);
}
</syntaxhighlight>

Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des set-Befehls übergeben. Als Rückgabewert kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert.

Standardmäßig wird jeder Set-Befehl, welcher erfolgreich ausgeführt wurde (<code>$error</code> ist <code>undef</code>), als Event getriggert um dies bspw. in einem FileLog festzuhalten. Dieses Verhalten kann optional unterbunden werden indem der zweite Rückgabewert <code>$skip_trigger</code> auf <code>1</code> gesetzt wird. Damit wird das Generieren eines Events für das erfolgreich ausgeführte Set-Kommando unterbunden. Falls nicht gesetzt, wird ein Event erzeugt (<code>$cmd</code> mit sämtlichen <code>@args</code>).

Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen eines ausgeführten [[Notify]] auftreten werden im FHEM Logfile festgehalten.

Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zur Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter übergeben um Zustände zu setzen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>power</code>

Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:

* <code>set ''<NAME>'' status</code>
* <code>set ''<NAME>'' power</code>
</ul>

Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im Modul [[FHEMWEB]] verwendet wird um die möglichen <code>set</code>-Optionen zu ermitteln und als Auswahl anzubieten.

Nutzung von SetExtensions.pm

Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.

Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.
|-
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<syntaxhighlight lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</syntaxhighlight>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Set() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

Nutzung von FHEMWEB-Widgets

Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:
set ''<NAME>'' ?

Beispiel:
<syntaxhighlight lang="perl">
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";
</syntaxhighlight>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

Man kann jedoch die Eingabe-/Auswahlmöglichkeiten durch Widgets vereinfachen. Dazu gibt man hinter dem Doppelpunkt einen Widgetnamen und widgetspezifische Parameter an. Es existieren mehrere solcher Widgets in FHEMWEB. Die gebräuchlichsten sind:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''noArg''' || <code>reset:noArg</code>|| Es werden keine weiteren Argumente mehr benötigt. In so einem Fall wird bei der Auswahl keine Textbox oder ähnliches angezeigt, da keine weiteren Argumente für diesen Befehl notwendig sind.
|-
| '''slider''',<min>,<step>,<max> || <code>dim:slider,0,1,100</code>|| Es wird ein Schieberegler angezeigt um den Parameter auszuwählen. Dabei werden als Zusatzparameter Minimum, Schrittweite und Maximum angegeben.
|-
| '''colorpicker''' || <code>rgb:colorpicker,RGB</code>|| Es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Die genaue Parametersyntax kann man dem Artikel zum [[Color#Colorpicker|Colorpicker]] entnehmen.
|-
| '''multiple''' || <code>group:multiple,Telefon,Multimedia,Licht,Heizung</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte durch klicken auswählen kann. Optional kann man in einem Freitext eigene Werte ergänzen. dieser Dialog wird bspw. bei der Raum-Auswahl (Attribut "room") oder der Gruppen-Auswahl (Attribut "group") in FHEMWEB genutzt.
|-
| '''sortable''' || <code>command:sortable,monday,tuesday,...</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte auswählen und sortieren kann. Man kann dabei Werte durch Klicken auswählen und durch Drag'n'Drop sortieren.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.

'''Hinweise'''

* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</syntaxhighlight>

Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.

Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.

Attributnamen mit Platzhaltern

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<syntaxhighlight lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</syntaxhighlight>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.

Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in FHEMWEB durch Klicken ausgewählt und geändert werden.
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]:

<syntaxhighlight lang="perl">
addToDevAttrList($name, $aName);
</syntaxhighlight>

==== X_Read ====
<syntaxhighlight lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.

Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Serial-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion [[DevIo#DevIo_SimpleRead()|DevIo_SimpleRead()]] gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern (siehe auch [[DevIo#Hinweis bei der Datenverarbeitung (Buffering)|DevIo]]). Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.

<syntaxhighlight lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</syntaxhighlight>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<syntaxhighlight lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</syntaxhighlight>

Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat, je nachdem auf welchem OS FHEM ausgeführt wird, unterschiedliche Aufgaben:

* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

Bei der Nutzung des Moduls [[DevIo]] wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

# This is relevant for Windows/USB only
if(defined($hash->{USBDev})) {
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
}
</syntaxhighlight>

==== X_Notify ====

Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das {{Link2CmdRef|Anker=addStateEvent|Lang=de|Label=addStateEvent-Attribut}} vorzusehen.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</syntaxhighlight>

Begrenzung der Aufrufe auf bestimmte Geräte

Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, das die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer {{Link2CmdRef|Lang=de|Anker=devspec|Label=devspec}} in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<syntaxhighlight lang="perl">
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_.*";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";
</syntaxhighlight>

Dies schont insbesondere bei grossen Installationen Ressourcen, da die Notify-Funktion nicht sämtliche Events, sondern nur noch Events der gewünschten Definitionen erhält. Dadurch erfolgen deutlich weniger Aufrufe der Notify-Funktion, was Systemressourcen schont.

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.

Reihenfolge für den Aufruf der Notify-Funktion beeinflussen

Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.

Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</syntaxhighlight>

Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.

==== X_Rename ====
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name) = @_;

...
}
</syntaxhighlight>

Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $data) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $data);
setKeyValue($old_index, undef);
}
</syntaxhighlight>

==== X_DelayedShutdown ====
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ( $hash ) = @_;

...

return $delay_needed;
}
</syntaxhighlight>
Mit der X_DelayedShutdown Funktion kann eine Definition das Stoppen von FHEM verzögern um asynchron hinter sich aufzuräumen. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.), welcher mehrfache Requests/Responses benötigt. Als Übergabeparameter wird der Geräte-Hash <code>$hash</code> bereitgestellt. Je nach Rückgabewert <code>$delay_needed</code> wird der Stopp von FHEM verzögert. Ist ein verzögerter Stopp von FHEM notwendig, darf der Rückgabewert in diesem Fall nicht <code>0</code> oder <code>undef</code> sein.

Im Unterschied zur [[#X_Shutdown|Shutdown]]-Funktion steht vor einem bevorstehenden Stopp von FHEM für einen User-konfigurierbaren Zeitraum (global-Attribut: <code>maxShutdownDelay</code> / Standard: 10 Sekunden) weiterhin die asynchrone FHEM Infrastruktur ([[DevIo]]/[[#X_Read|Read]]-Funktion und [[DevelopmentModuleAPI#InternalTimer|InternalTimer]]) zur Verfügung.

Sobald alle nötigen Maßnahmen erledigt sind, muss der Abschluss mit [[DevelopmentModuleAPI#CancelDelayedShutdown|CancelDelayedShutdown(<code>$name</code>)]] an FHEM zurückgemeldet werden.

Beispiel:
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ($hash) = @_;

# Aufräumen starten

return 1;
}
</syntaxhighlight>

==== X_Shutdown ====
<syntaxhighlight lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Nach der Ausführung der Shutdown-Fuktion wird FHEM sofort beendet. Falls vor dem Herunterfahren von FHEM asynchrone Kommunikation (via [[DevIo]]/[[#X_Read|X_Read]]) notwendig ist um eine vorhandene Verbindung sauber zu beenden, sollte man [[#X_DelayedShutdownFn|X_DelayedShutdownFn]] verwenden.

Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</syntaxhighlight>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.
|}

Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion registriert sein. Diese dienen dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}
<syntaxhighlight lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</syntaxhighlight>

Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.

Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Bereich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<syntaxhighlight lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</syntaxhighlight>

Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).

Beispiel:

<syntaxhighlight lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</syntaxhighlight>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}
<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</syntaxhighlight>

Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischem Modul abzustimmen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</syntaxhighlight>

==== X_Fingerprint ====
<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</syntaxhighlight>

Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein - je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann.

Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</syntaxhighlight>

Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modul-Autoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.
|-
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.
|-
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.
|-
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.
|-
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.
|-
| [[#X_ActivateInform|X_ActivateInform]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das Aktivieren des inform-Mechanismus zum Senden von Events für einen einzelnen verbundenen Client.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<syntaxhighlight lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

return ( $reading, $value, $unit );
}
</syntaxhighlight>

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modul-Autor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<syntaxhighlight lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</syntaxhighlight>

==== X_Except ====
<syntaxhighlight lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>

Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">
use IO::File;

...

sub X_Except ($)
{
my ( $hash ) = @_;

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</syntaxhighlight>

==== X_Copy ====
<syntaxhighlight lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</syntaxhighlight>

Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</syntaxhighlight>

==== X_AsyncOutput ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_AsyncOutput ($)
{
my ( $client_hash, $text ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Funktion X_AsyncOutput wird durch [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] von anderen Modulen aufgerufen. Es erlaubt diesen anderen Modulen die Ausgabe von asynchronen Befehlsergebnissen <code>$text</code> zuvor ausgeführter set-/get-Befehle an den entsprechenden Client (identifiziert durch den Client-Hash <code>$client_hash</code> der temporären Definition) zurückzugeben.

Wenn ein Client einen set-/get-Befehl ausführt, wird der Client-Hash bei der Ausführung dieser Befehle an die jeweiligen Module übermittelt. Sobald ein Befehl ausgeführt wird, der seine Ausgabe asynchron ausführen möchte und die Client-Verbindung des Server-Moduls dies unterstützt (<code>$client_hash->{canAsyncOutput}</code> ist gesetzt), merkt sich das befehlsausführende Modul den Client-Hash und gibt das Ergebnis des Befehls zu späterer Zeit via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an den ursprünglichen Client zurück. Die Funktion X_AsyncOutput des Server-Moduls kümmert sich darum das Ergebnis dem entsprechenden Client in der notwendigen Form zuzustellen.

Der Rückgabewert von X_AsyncOutput() wird als Rückgabewert für asyncOutput() verwendet. Man kann hier im Fehlerfall eine Fehlermeldung angeben und im Erfolgsfall <code>undef</code>. Der Rückgabewert wird aber aktuell nicht ausgewertet.

==== X_ActivateInform====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_ActivateInform($$)
{
my ( $client_hash, $arg ) = @_;

...
}
</syntaxhighlight>

Die Funktion X_ActivateInform wird aktuell nur durch den [[update]]-Befehl aufgerufen, sofern ein Client eines Frontend-Moduls diesen Befehl aufgerufen hat um den Inform-Mechanismus (Senden von Events) zu aktivieren. Dadurch wird im Falle von [[update]] die umgehende Anzeige der Logmeldungen für den ausführenden Client aktiviert. In [[FHEMWEB]] geschieht das über den Event-Monitor, bei telnet mit der direkten Ausgabe.

Da diese Funktion aktuell nur speziell für den update-Befehl implementiert ist, kann man aktuell keine genaue Angaben zu den möglichen Werten von <code>$arg</code> geben. Dieser Parameter dient dazu genauer zu spezifizieren was exakt an Events an den entsprechenden Client <code>$client_hash</code> zu senden ist. Aktuell wird dazu die Parametersyntax des inform-Befehls verwendet (on|off|log|raw|timer|status).

==== X_State ====
<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</syntaxhighlight>

Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan=2 align=center | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen Zeitpunkt.
|-
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).
|-
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.

Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben, der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.

Beispiel:

<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</syntaxhighlight>

==== X_Authorize ====
<syntaxhighlight lang="perl">
sub X_Authorize($$$$)
{
my ( $hash, $client_hash, $type, $arg ) = @_;

...

return $authorized;
}
</syntaxhighlight>

Die Authorize-Funktion wird von fhem.pl aufgerufen um zu erfragen, ob ein bestimmter Client <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf. Auf diese Weise können Module Einfluss nehmen, welcher User welche Funktionen in FHEM nutzen darf. Wenn ein Client eine Aktion ausführen möchte, werden alle Module, die eine Authorize-Funktion implementiert haben, gefragt, ob diese Aktion ausgeführt werden darf. Als Rückgabewert wird das Ergebnis der Überprüfung zurückgegeben, wobei <code>0</code> (unbekannt / nicht zuständig), <code>1</code> (erlaubt) oder <code>2</code> (verboten) zurückgegeben werden können.

Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:

{| class="wikitable"
|-
! $type !! $arg !! Überschrift
|-
|rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code>

''Befehlsausführung''
| style="white-space: nowrap;" | <code>'''$arg''' = "set Lampe on"</code> || Jeglicher FHEM-Befehl, der ausgeführt werden soll, wird in <code>$arg</code> hinterlegt, sodass innerhalb einer Authorize-Funktion der Befehl genauer geparst werden kann um zu entscheiden, ob dieser Befehl erlaubt ist, oder nicht.
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "perl"</code> || Ausführen von Perl-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code>
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "shell"</code> || Ausführen von Shell-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>"/opt/fhem/myScript.sh"</code>
|-
|style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code>

''Sichtbarkeit von Geräten/Definitionen''
|style="white-space: nowrap;" | <code>'''$arg''' = "Licht_Wohnzimmer"</code> || Sichtbarkeit des jeweiligen Gerät/Definition in FHEM. Dies bedeutet konkret die Auffindbarkeit im <code>list</code>-Befehl, sowie der Suche via [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wird eine solche Anfrage durch die Authorize-Funktion abgelehnt, ist das entsprechende Gerät bzw. Definition für den jeweiligen Client nicht sichtbar.
|}

==== X_Authenticate ====
{{Link2Forum|Topic=72757|Message=644098}}

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.

Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:

<syntaxhighlight lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optionaler Filter für Clientmodule als regulärer Ausdruck
ClientFilter => "FHEMWEB"
};
}
</syntaxhighlight>

Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> (regulärer Ausdruck für Modulnamen) die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<syntaxhighlight lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</syntaxhighlight>

Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<syntaxhighlight lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</syntaxhighlight>

Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.

In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<syntaxhighlight lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</syntaxhighlight>

Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<syntaxhighlight lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</syntaxhighlight>
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.

Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:

<syntaxhighlight lang="perl">
my $name = $hash->{NAME};
</syntaxhighlight>

Um für eine einzelne Geräteinstanz das Verbose-Level zu erhöhen, ohne gleich für das gesamte FHEM den globalen Verbose-Level zu erhöhen und damit alle Meldungen zu erzeugen, kann man den Befehl
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code>

Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der {{Link2CmdRef|Lang=de|Anker=verbose}} beschrieben.

Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

physisches Modul

Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).

Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. Die Match-Liste enthält eine Liste von regulären Ausdrücken und ordnet diese einem Modul zu. Wenn eine Nachricht auf einen solchen regulären Ausdruck passt und das Modul noch nicht geladen ist, lädt FHEM dieses automatisch nach, zwecks Verarbeitung der Nachricht.

Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] (Auflistung von logischen Modulen) kann FHEM feststellen, welche logischen Module mit dem physischen Modul kommunizieren können. Nur die hier aufgelisteten, logischen Module werden beim Aufruf von [[DevelopmentModuleAPI#Dispatch|Dispatch()]] angesprochen.

Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten in beliebiger Form an die Hardware übertragen können.

logisches Modul

Das logische Modul interpretiert die via Dispatch() übergebene Nachricht (Zeichenkette) durch eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.

Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] (regulärer Ausdruck) zur Verfügung anhand [[DevelopmentModuleAPI#Dispatch|Dispatch()]] ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann. Nur Nachrichten, welche auf diesen Ausdruck passen, werden an das logische Modul weitergegeben (Aufruf [[#X_Parse|Parse]]-Funktion).

=== Die Client-Liste ===

Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welchen logischen Modulen das physikalische Modul kommunizieren kann.

Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen (z.B. <code>CUL_.*</code> um die logischen Module CUL_HM, CUL_MAX, etc. zu verwenden).

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:

FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT

Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können (Prüfung via [[#Der Match-Ausdruck|Match-Ausdruck]])
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</syntaxhighlight>

Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";
}
</syntaxhighlight>

In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>''':'''<Modulname>''':'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<syntaxhighlight lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</syntaxhighlight>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann ([[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur alle bisher geladenen Module aus der [[#Die Client-Liste|Client-Liste]]), so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses direkt durch Aufruf der [[#X_Parse|Parse]]-Funktion verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<syntaxhighlight lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</syntaxhighlight>

Das Sortierpräfix (<code>1:FS20</code>) dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird die Match-Liste mittels sort() nach dem Schlüssel (Sortierpräfix + Modulname) sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern zeichenbasierend.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</syntaxhighlight>

Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</syntaxhighlight>

=== Der Match-Ausdruck ===

Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion des eigenen Moduls aufgerufen um die Nachricht zu verarbeiten.

Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</syntaxhighlight>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.
* [[#X_DelayedShutdown | DelayedShutdown]]-Funktion - Verzögertes beenden zum Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

Die Gerätedefinition des physischen Moduls öffnet eine Verbindung zur Hardware (z.B. via [[DevIo]]). Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

Die Funktion Dispatch() prüft alle geladenen Module aus der [[#Die_Client-Liste|Client-Liste]] des physikalischen Moduls nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem logischen Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.

Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig nach Abschluss der Parse-Funktion.

Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt. Sollte der Fingerprint einer Nachricht innerhalb einer bestimmten Zeit (globales Attribut <code>dupTimeout</code>, standardmäßig 500ms) bereits empfangen worden sein, so wird die Nachricht verworfen. Dies ist insbesondere bei funkbasierter Hardware notwendig, wenn mehrere Empfänger die selbe Nachricht empfangen.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.

Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware.

Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter...>''

Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.

Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.

Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</syntaxhighlight>

Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| style="vertical-align:top; white-space: nowrap;" | <code>ATTR</code>|| style="vertical-align:top; white-space: nowrap;" | <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| style="vertical-align:top; white-space: nowrap;" | <code>FILTER</code> || style="vertical-align:top; white-space: nowrap;" | <code>"%NAME"</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| style="vertical-align:top; white-space: nowrap;" | <code>GPLOT</code> || style="vertical-align:top; white-space: nowrap;" | <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.

Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.

Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden.

|-
| style="vertical-align:top; white-space: nowrap;" | <code>autocreateThreshold</code> || style="vertical-align:top; white-space: nowrap;"| <code>"2:10"</code> || Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.

Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.
|-
| style="vertical-align:top; white-space: nowrap;" | <code>noAutocreatedFilelog</code>|| style="vertical-align:top; white-space: nowrap;" | <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.
|}

== Ergänzende Hinweise ==
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.

Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.

== Weitere Informationen ==
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM {{Link2CmdRef}} sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.

== "Hello World" Beispiel ==

98_Hello.pm

<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize($) {
my ($hash) = @_;

$hash->{DefFn} = 'Hello_Define';
$hash->{UndefFn} = 'Hello_Undef';
$hash->{SetFn} = 'Hello_Set';
$hash->{GetFn} = 'Hello_Get';
$hash->{AttrFn} = 'Hello_Attr';
$hash->{ReadFn} = 'Hello_Read';

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a name="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a name="Hellodefine"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a name="Helloset"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a name="Helloget"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a name="Helloattr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</syntaxhighlight>

Der HTML-Code zwischen den Tags <code>=pod</code> und <code>=cut</code> dient zur Generierung der commandref.html. Der HTML-Inhalt wird automatisch beim Verteilen des Moduls im Rahmen des Update-Mechanismus aus jedem Modul extrahiert und daraus die Commandref in verschiedenen Sprachen erstellt. Eine detaillierte Beschreibung wie ein Commandref-Abschnitt in einem Modul definiert wird, siehe: [[Guidelines zur Dokumentation]]

[[Kategorie:Development]]

DevStateIcon

2019-10-18T18:49:57Z

Justme: /* Einschränkungen */ klammern sind nicht verboten. sie haben nur eine besondere bedeutung.

{{SEITENTITEL:devStateIcon}} 


Das Attribut [[devStateIcon]] dient dazu, das anzuzeigende Icon eines Devices in Abhängigkeit vom Device-Status (STATE) in der Raumübersicht (room) festzulegen. Zudem kann man einstellen, was bei einem Klick auf das Icon geschieht.

== Syntax ==
Das ''devStateIcon'' Attribut kann in 2 verschiedenen Formen spezifiziert werden, die in der {{Link2CmdRef|Anker=devStateIcon}} sowie in [[DeviceOverview anpassen#devStateIcon|deviceOverview]] detaillierter beschrieben werden.

Seit FHEM Version 2019-02-20 gibt es die Möglichkeit mehr als ein Icon pro Device darzustellen: Sobald STATE mehrzeilig ist wird für jede Zeile ein Icon erzeugt und alle Icons nebeneinander
dargestellt. Mehrere Zeilen für STATE lassen sich über ein entsprechend gesetztes stateFormat Attribut erreichen. Ein Zeilenumbruch zwischen diesen Icons lässt sich mit erzeugen.

Ein Beispiel findet sich in {{Link2Forum|Topic=97586|LinkText=diesem Forenthread}} zur Entstehung des Features.

[[Datei:stateFormat-1.png|600px]]

== Einschränkungen ==
In ''devStateIcon'' dürfen keine Leerzeichen vorkommen (ausser zur Trennung der unterschiedlichen Zustände).

Da in der ersten Form der erste Teil jedes Tripels eine Regex ist, sind hier die für eine Regex geltenden Regeln zu beachten. Unter anderem sind das:
* Leerzeichen durch . oder \s ersetzen
* alle Zeichen die in einer Regex eine besondere Bedeutung haben (klammern, punkte, backslash, ...) maskieren

So müsste z.B. (siehe auch {{Link2Forum|Topic=42351|LinkText=dieses Forenthema}}
:<code>devStateIcon on-old-for-timer 60:weather_rain_heavy@red:off off:weather_sun@yellow:on-old-for-timer 60</code>
geändert werden auf
:<code>devStateIcon on-old-for-timer.60:weather_rain_heavy@red:off off:weather_sun@yellow:on-old-60</code>
wobei in diesem Beispiel zusätzlich der Befehlsteil des '''off''' mit der Attributdefinition
:<code>[[eventMap]] /on-old-for-timer 60:on-old-60/</code>
auf eine "leerzeichenlose" Version umdefiniert werden muss.

== Beispiele ==
* [[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen#Anzeige Rollladenstand im WebFrontend|Anzeige Rollladenstand im WebFrontend]]
* [[EnOcean-STM-250-Fenster-T%C3%BCrkontakt#Anzeige Türstatus im WebFrontend|Anzeige Türstatus im WebFrontend]]
* [[Color#Farbige_Lampen_Icons|Farbige Lampen Icons]]
* [[Icons]]

== Links ==
* Ausführliche Beschreibung (mit Beispielen) zu [[eventMap]], devStateIcon, [[setList]] und [[webCmd]] in {{Link2Forum|Topic=12080|LinkText=diesem Forenthread}} oder in [[DeviceOverview anpassen]]
* Beispiel für FS20 {{Link2Forum|Topic=26521|Message=197326}}

[[Kategorie:Attribut (allgemeingültig)]]

TRÅDFRI

2019-10-16T07:10:27Z

Justme:

<div style="float:right">{{Infobox Modul
|Name=tradfri
|ModPurpose=Anbindung IKEA TRÅDFRI Gateway
|ModType=d

|ModCmdRef=tradfri
|ModForumArea=Zigbee
|ModTechName=30_tradfri.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

'''TRÅDFRI''' bzw. '''IKEA Home smart''' ist die Serie smarter Beleuchtungslösungen von IKEA auf ZigBee-Basis , ähnlich Phillips Hue.

== tradfri ==

TRÅDFRI (nach Umbenneng jetzt '''IKEA Home smart''') ist die Serie smarter Beleuchtungslösungen von IKEA. Ähnlich von Phillips [[Hue]] gibt es diverse LEDs in Glühbirnenform, LED-Streifen-Treiber, Flächenleuchten, Wandtaster, Bewegungsmelder, Fernbedienung, Dimmer, etc. und alles via Funk gekoppelt. Außerdem ein Gateway, das sich via Ethernetstecker ins heimische LAN einbinden lässt und die Bedienung via IKEA-App auf dem Handy ermöglicht. Daneben ist auch eine Anbindung in FHEM möglich, dazu funktionieren zwei alternative Lösungen:

=== alt: IKEA Trådfri Modul ===
IKEA Trådfri Modul (TYPE ''TradfriDevice'' und ''TradfriGateway'', mehr Infos: https://forum.fhem.de/index.php/topic,70653.0.html seit April 2017)
* Erkennt Lampen
* Fernbedienung erscheint zwar in der Geräteliste, lässt sich aber nicht als Gerät anlegen oder Status lesen

Die Weiterentwicklung des Moduls durch den ursprünglichen Entwickler scheint Stand 07.19 eingestellt. Inwieweit andere am Modul weiter arbeiten ist unklar.

=== neu: tradfri-fhem Modul ===
tradfri-fhem Modul (TYPE ''HUEDevice'' und ''tradfri'' Gateway, mehr Infos: https://forum.fhem.de/index.php/topic,96125.0.html seit Januar 2019, Beschreibung folgt auf dieser Seite)
* Unterstützt Lampen (als [[Hue#HUE-Device|HUE-Device]])
* Unterstützt Rollos (Fyrtur und Kadrilj)
* Erkennt Fernbedienung, jedoch zur Zeit Batteriestatus als einziges Reading
* Erstellt (wenn gewünscht) automatisch Gruppen
* Erkennt Bewegungsmelder, jedoch zur Zeit Batteriestatus als einziges Reading
* Erkennt Repeater, nur Erreichbarkeit (reachable) als Reading

====Einrichtung in FHEM====

# node installieren (mindestens version 8)
# sudo npm install -g tradfri-fhem
# <code>define <tradfri> tradfri</code>
# <code>attr <tradfri> tradfriFHEM-securityCode <security code></code>

wenn das gateway nicht automatisch erkannt wird:
<code>attr <tradfri> tradfriFHEM-params --ip <ip></code>

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

==== HUE-Device ====
Alle auf dem Gateway bekannten Geräte automatisch als [[Hue#HUE-Device|HUEDevice]] in FHEM angelegt:
* Lampen, Stecker, Trafos, ...
: Hiermit werden die einzelnen Leuchten gesteuert
* Gruppen
: Hiermit lassen sich ganze Gruppen und Räume steuern
* Fernbedienungen
: aktuell gibt es nur ein Battery-Reading

==== Darstellung im Webfrontend ====
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

== Links ==

Githubeintrag über Einstellung der Feature-Entwicklung des IKEA Trådfri Moduls[https://github.com/peterkappelt/Tradfri-FHEM/issues/16#issuecomment-445461242 GITHUB].
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

TRÅDFRI

2019-10-16T07:07:00Z

Justme: /* tradfri-fhem Modul */

<div style="float:right">{{Infobox Modul
|Name=tradfri
|ModPurpose=Anbindung IKEA TRÅDFRI Gateway
|ModType=d

|ModCmdRef=tradfri
|ModForumArea=Zigbee
|ModTechName=30_tradfri.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

'''TRÅDFRI''' bzw. '''IKEA Home smart''' ist die Serie smarter Beleuchtungslösungen von IKEA auf ZigBee-Basis , ähnlich Phillips Hue.

== tradfri ==

TRÅDFRI (nach Umbenneng jetzt '''IKEA Home smart''') ist die Serie smarter Beleuchtungslösungen von IKEA. Ähnlich von Phillips [[Hue]] gibt es diverse LEDs in Glühbirnenform, LED-Streifen-Treiber, Flächenleuchten, Wandtaster, Bewegungsmelder, Fernbedienung, Dimmer, etc. und alles via Funk gekoppelt. Außerdem ein Gateway, das sich via Ethernetstecker ins heimische LAN einbinden lässt und die Bedienung via IKEA-App auf dem Handy ermöglicht. Daneben ist auch eine Anbindung in FHEM möglich, dazu funktionieren zwei alternative Lösungen:

=== IKEA Trådfri Modul ===
IKEA Trådfri Modul (TYPE ''TradfriDevice'' und ''TradfriGateway'', mehr Infos: https://forum.fhem.de/index.php/topic,70653.0.html seit April 2017)
* Erkennt Lampen
* Fernbedienung erscheint zwar in der Geräteliste, lässt sich aber nicht als Gerät anlegen oder Status lesen

Die Weiterentwicklung des Moduls durch den ursprünglichen Entwickler scheint Stand 07.19 eingestellt. Inwieweit andere am Modul weiter arbeiten ist unklar.

=== tradfri-fhem Modul ===
tradfri-fhem Modul (TYPE ''HUEDevice'' und ''tradfri'' Gateway, mehr Infos: https://forum.fhem.de/index.php/topic,96125.0.html seit Januar 2019, Beschreibung folgt auf dieser Seite)
* Unterstützt Lampen (als [[Hue#HUE-Device|HUE-Device]])
* Unterstützt Rollos (Fyrtur und Kadrilj)
* Erkennt Fernbedienung, jedoch zur Zeit Batteriestatus als einziges Reading
* Erstellt (wenn gewünscht) automatisch Gruppen
* Erkennt Bewegungsmelder, jedoch zur Zeit Batteriestatus als einziges Reading
* Erkennt Repeater, nur Erreichbarkeit (reachable) als Reading

====Einrichtung in FHEM====

# node installieren (mindestens version 8)
# sudo npm install -g tradfri-fhem
# <code>define <tradfri> tradfri</code>
# <code>attr <tradfri> tradfriFHEM-securityCode <security code></code>

wenn das gateway nicht automatisch erkannt wird:
<code>attr <tradfri> tradfriFHEM-params --ip <ip></code>

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

==== HUE-Device ====
Alle auf dem Gateway bekannten Geräte automatisch als [[Hue#HUE-Device|HUEDevice]] in FHEM angelegt:
* Lampen, Stecker, Trafos, ...
: Hiermit werden die einzelnen Leuchten gesteuert
* Gruppen
: Hiermit lassen sich ganze Gruppen und Räume steuern
* Fernbedienungen
: aktuell gibt es nur ein Battery-Reading

==== Darstellung im Webfrontend ====
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

== Links ==

Githubeintrag über Einstellung der Feature-Entwicklung des IKEA Trådfri Moduls[https://github.com/peterkappelt/Tradfri-FHEM/issues/16#issuecomment-445461242 GITHUB].
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

TRÅDFRI

2019-10-16T07:03:16Z

Justme: unterstützt rollos

<div style="float:right">{{Infobox Modul
|Name=tradfri
|ModPurpose=Anbindung IKEA TRÅDFRI Gateway
|ModType=d

|ModCmdRef=tradfri
|ModForumArea=Zigbee
|ModTechName=30_tradfri.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

'''TRÅDFRI''' bzw. '''IKEA Home smart''' ist die Serie smarter Beleuchtungslösungen von IKEA auf ZigBee-Basis , ähnlich Phillips Hue.

== tradfri ==

TRÅDFRI (nach Umbenneng jetzt '''IKEA Home smart''') ist die Serie smarter Beleuchtungslösungen von IKEA. Ähnlich von Phillips [[Hue]] gibt es diverse LEDs in Glühbirnenform, LED-Streifen-Treiber, Flächenleuchten, Wandtaster, Bewegungsmelder, Fernbedienung, Dimmer, etc. und alles via Funk gekoppelt. Außerdem ein Gateway, das sich via Ethernetstecker ins heimische LAN einbinden lässt und die Bedienung via IKEA-App auf dem Handy ermöglicht. Daneben ist auch eine Anbindung in FHEM möglich, dazu funktionieren zwei alternative Lösungen:

=== IKEA Trådfri Modul ===
IKEA Trådfri Modul (TYPE ''TradfriDevice'' und ''TradfriGateway'', mehr Infos: https://forum.fhem.de/index.php/topic,70653.0.html seit April 2017)
* Erkennt Lampen
* Fernbedienung erscheint zwar in der Geräteliste, lässt sich aber nicht als Gerät anlegen oder Status lesen

Die Weiterentwicklung des Moduls durch den ursprünglichen Entwickler scheint Stand 07.19 eingestellt. Inwieweit andere am Modul weiter arbeiten ist unklar.

=== tradfri-fhem Modul ===
tradfri-fhem Modul (TYPE ''HUEDevice'' und ''tradfri'' Gateway, mehr Infos: https://forum.fhem.de/index.php/topic,96125.0.html seit Januar 2019, Beschreibung folgt auf dieser Seite)
* Erkennt Lampen (als [[Hue#HUE-Device|HUE-Device]])
* unterstützt Rollos (Fyrtur und Kadrilj)
* Erkennt Fernbedienung, jedoch zur Zeit Batteriestatus als einziges Reading
* Erstellt (wenn gewünscht) automatisch Gruppen
* Erkennt Bewegungsmelder, jedoch zur Zeit Batteriestatus als einziges Reading

====Einrichtung in FHEM====

# node installieren (mindestens version 8)
# sudo npm install -g tradfri-fhem
# <code>define <tradfri> tradfri</code>
# <code>attr <tradfri> tradfriFHEM-securityCode <security code></code>

wenn das gateway nicht automatisch erkannt wird:
<code>attr <tradfri> tradfriFHEM-params --ip <ip></code>

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

==== HUE-Device ====
Alle auf dem Gateway bekannten Geräte automatisch als [[Hue#HUE-Device|HUEDevice]] in FHEM angelegt:
* Lampen, Stecker, Trafos, ...
: Hiermit werden die einzelnen Leuchten gesteuert
* Gruppen
: Hiermit lassen sich ganze Gruppen und Räume steuern
* Fernbedienungen
: aktuell gibt es nur ein Battery-Reading

==== Darstellung im Webfrontend ====
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

== Links ==

Githubeintrag über Einstellung der Feature-Entwicklung des IKEA Trådfri Moduls[https://github.com/peterkappelt/Tradfri-FHEM/issues/16#issuecomment-445461242 GITHUB].
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

ReadingsGroup

2019-10-03T21:32:18Z

Justme: Änderung 31300 von FExplorer (Diskussion) rückgängig gemacht. ° ist korrekt wenn man nicht mit utf-8 arbeitet.

{{SEITENTITEL:readingsGroup}}
{{Infobox Modul
|ModPurpose=Einfache zusammenfassende Darstellung von Informationen über mehrere Geräte und deren Steuerung
|ModType=h
|ModCmdRef=readingsGroup
|ModForumArea=Frontends
|ModTechName=33_readingsGroup.pm
|ModOwner=Andre ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])}}

Das FHEM-[[:Kategorie:Hilfsmodul|Hilfsmodul]] [[readingsGroup]] bietet eine einfache Möglichkeit, <code>Readings</code> (kein Präfix vor dem Reading-Namen), <code>Internals</code> (Präfix "+" vor dem Namen des internen Wertes) und <code>Attributes</code> (Präfix "?" vor dem Namen des Attributs) von einem oder mehreren <code>Devices</code> darzustellen und flexibel zu formatieren.

Die Aktualisierung im Browserfenster geschieht per <code>longpoll</code> und überträgt nur die jeweils geänderten Zellen. Wenn eine <code>readingsGroup</code> in keinem Browserfenster angezeigt wird, findet keine <code>longpoll</code> Aktualisierung statt.

== Definition ==
Siehe {{Link2CmdRef|Anker=readingsGroup}}.

== Attribute ==
{{Randnotiz|RNText=In allen Mappings die einen Hash verwenden muss der Key (das was jeweils links von => Operator steht) in Anführungszeichen stehen. Die einzige Ausnahme hiervon sind Keys die aus einem String bestehen der mit einem Buchstaben beginnt und nur Buchstaben und Zahlen enthält.}}
Weitergehende Erläuterungen zu einzelnen Attributen.

Die komplette Liste der Attribute ist der {{Link2CmdRef}} zu entnehmen.

=== noheading ===
[[Datei:ReadingsGroup_noheading.png|mini|rechts|400px|ReadingsGroup: rechts mit "noheading" Attribut, links der anklickbare Titel]]
Das Attribut <code>noheading</code> führt dazu, dass der Alias der ReadingsGroup nicht mehr als Titel angezeigt wird. Das kann wünschenswert sein, wenn die ReadingsGroup auf einer [[Dashboard]]-Seite angezeigt werden soll, hat allerdings den Nachteil, dass die Detail-Ansicht der ReadingsGroup nicht mehr über einen Klick auf den Titel aufgerufen werden kann. Der Einstellungsdialog der ReadingsGroup ist dann nur noch (z. B.) über
* <code>list TYPE=readingsGroup</code>
* einen "Probably associated with"-Link eines anderen Objekts oder über
* manuelle Modifikation der URL eines anderen Objekts (<code>http:.../fhem?detail=<objektname></code>)
erreichbar.

=== nolinks ===
Devicenamen und Titel der readingsGroup verlinken nicht mehr zur zugehörigen Detailansicht und sind nicht mehr anklickbar.

=== nostate ===
Das state-Reading wird bei regex match nicht berücksichtigt und nicht angezeigt.

=== notime ===
Es werden keine Timestamps für die Readings angezeigt. Nur für einspaltige readingsGroups sinnvoll.

=== mapping ===
mapping wird verwendet um Elemente einer Zeile auszutauschen, bspw. um
* den Zeilentitel gegen den Raumnamen auszutauschen (z.B. [[ReadingsGroup#Einfache Auswahl über Reading-Namen|einfach]], [[ReadingsGroup#Schriftgrößen, Farben, Icons|doppelt]], [[ReadingsGroup#Reading-Werte zuordnen (Icon / Text)|erweitert]], [[ReadingsGroup#Heizungsteuerung für HM Wand- und Heizkörperthermostate|noch mehr]], [[ReadingsGroup#Enigma Receiver|leer]])
Weitere Anwendungsbeispiele finden sich in den div. Beispielen unten und in der {{Link2CmdRef}}.

=== valueFormat ===
valueFormat wird klassischerweise dazu genutzt um die dargestellten Werte zu formatieren - bspw. um einem Wert ein Einheitensymbol zu verpassen (z.B. [[ReadingsGroup#Ausgabestil (hier rechtsbündig)]]). Man kann valueFormat aber auch für dynamische Darstellungen oder gar kleine Programmierungen "missbrauchen", bspw. um
* einen Wert dynamisch durch ein Symbol zu ersetzen ohne exzessiv [[ReadingsGroup#mapping|mappen]] (s.o.) zu müssen (z.B. [[ReadingsGroup#Reading-Werte zuordnen (Icon / Text)|Reading-Werte zuordnen]])
* unerwünschte Werte auszufiltern (z.B. [[ReadingsGroup#Inhalte filtern|Inhalte filtern]])
* kleine Berechnungen durchzuführen, ohne diese in [[99_myUtils_anlegen|99_myUtils.pm]] zu erstellen (z.B. [[ReadingsGroup#Inhalte berechnen|Inhalte berechnen]])
* größere Berechnungen in [[99_myUtils_anlegen|99_myUtils.pm]] aufzurufen (z.B. [[ReadingsGroup#Enigma Receiver|Enigma Receiver]]).

Weitere Anwendungsbeispiele finden sich in den div. Beispielen unten und in der {{Link2CmdRef}}.

=== valueIcon ===
valueIcon wird verwendet um einer Zeile zusätzlich ein Symbol hinzuzufügen (z.B. [[ReadingsGroup#Auswahl über Reading-Namen, Status als Symbol dargestellt|einfach]], [[ReadingsGroup#Heizungswerte, Status und Regelmöglichkeit|etwas mehr]]).

Weitere Anwendungsbeispiele finden sich in den div. Beispielen unten und in der {{Link2CmdRef}}.

=== valueStyle ===
valueStyle wird verwendet um die dargestellten Werte optisch anzupassen (z.B. [[ReadingsGroup#Ausgabestil (hier rechtsbündig)|einfach]], [[ReadingsGroup#Internal Values ausgeben|erweitert]], [[ReadingsGroup#Wertabhängige Farbgebung|komplex]]).

Weitere Anwendungsbeispiele finden sich in den div. Beispielen unten und in der {{Link2CmdRef}}.

== Beispiele ==
Bitte beachten: die folgenden Beispiele enthalten keine Maskierungen oder Verdoppelungen für ; und Zeilenende, sondern sind so angegeben, wie sie im [[PGM2|Web Interface]] im Befehls-Eingabefeld, nach Klick auf DEF und im Attribut-Eingabefeld eingegeben werden. Beim manuellen Einfügen in eine [[Konfiguration|Konfigurationsdatei]] sind diese Maskierungen oder Verdoppelungen natürlich vorzunehmen.

=== Einfache Auswahl über Reading-Namen ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define battStatus readingsGroup .*:[Bb]attery</code>
| Alle readings mit Namen '''Battery''' oder '''battery''' von allen Devices.
| rowspan=3 | [[Datei:rgBattery.png|thumb]]
|-
| <code>attr battStatus alias FHT Batteriestatus </code>
| Der Alias wird als Zeilentitel verwendet
|-
| <code>attr battStatus mapping %ROOM </code>
| ''Mapping %ROOM'' führt dazu, dass der Raumname als Zeilentitel angezeigt wird.
|}

=== Übersicht HomeMatic Geräte ===

<nowiki>define HM_Components readingsGroup <Gerät>,<Name>,<Model>,<S/N> TYPE=CUL_HM:+NAME,?model,D-serialNr</nowiki>

=== Auswahl über Reading-Namen, Status als Symbol dargestellt ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg_battery readingsGroup .*:battery</code>
| Alle readings mit Namen '''battery''' von allen Devices.
| rowspan=4 | [[Datei:rgBattery2.png|thumb]]
|-
| <code>attr rg_battery alias Batteriestatus </code>
| Der Alias wird als Überschrift verwendet
|-
| <code>attr rg_battery valueIcon {'battery.ok' => 'batterie', 'battery.low' => 'batterie@red'}</code>
| Statt der reading Werte "ok" und "low" soll ein Icon angezeigt werden.
|-
|<code>attr rg_battery commands { "battery.low" => "set %DEVICE replaceBatteryForSec 60" }</code>
| Für LaCrosse devices kann man beim Klick auf ein rotes "battery low icon" direkt replaceBatteryForSec setzen.
|}

=== Reading-Werte zuordnen (Icon / Text) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg readingsGroup Contact.Dachboden_gross:sensed.*</code>
| Alle sensedreadings des Contact.Dachboden_gross device.
| rowspan=4 | [[Datei:rgFenster.png|thumb]]
|-
| <code>attr rg mapping { 'sensed.A' => 'links', 'sensed.B' => 'rechts' }</code>
| Die Zuordnung rechts/links
|-
| <code>attr rg valueFormat {($VALUE eq '1')?"fts_window_roof":"fts_window_roof_open_2"}</code>
| Die Zuordnung von reading Wert zu Icon Namen.
|-
| <code>attr rg_battery valueIcon %VALUE </code>
| Statt des reading Werts soll ein Icon angezeigt werden.
|}

=== Formatvorgabe für Ausgabewerte ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define TempHygro readingsGroup TYPE=CUL_WS:temperature,humidity,dewpoint</code>
| Alle readings mit Namen '''temperature''', '''humidity''', '''dewpoint''' von allen Devices des Typs '''CUL_WS'''
| rowspan=4 | [[Datei:rgTemperatur.png|thumb|[[S300TH]]-Werte in einer readingsGroup]]
|-
| <code>attr TempHygro alias Temperatur / rel. Feuchte / Taupunkt</code>
| Der Alias der readingsGroup wird als Überschrift verwendet
|-
| <code>attr TempHygro mapping %ALIAS</code>
| ''Mapping %ALIAS'' führt dazu, dass der Alias des Geräts als Zeilentitel angezeigt wird.
|-
| <code>attr TempHygro valueFormat { temperature => "%.1f&deg;C", humidity => "%.1f %%", dewpoint => "%.1f&deg;C"}</code>
| Formatierung der Ausgabewerte. '''Achtung:''' "%" die in der Ausgabe erscheinen sollen, müssen verdoppelt werden!
|}

=== Ausgabestil (hier rechtsbündig) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Wetter readingsGroup WetterXXX:<%temp_temperature>,<Temperatur>,temperature WetterXXX:<%weather_humidity>,<Luftfeuchte>,humidity WetterXXX:<%weather_barometric_pressure>,<Luftdruck>,pressure
</code>
| Die readings mit Namen '''temperature''', '''humidity''' und '''pressure''' vom Device WetterXXX jeweils mit einem Icon und einem Label davor.
| rowspan=3 | [[Datei:rgWetter.png|thumb]]
|-
| <code>attr Wetter valueFormat { temperature => '%1.f &deg;C', humidity => '%1.f %%', pressure => '%i mbar' }</code>
| Die Formatierung der Readingswerte
|-
| <code>attr Wetter valueStyle style="text-align:right"</code>
| Die Readings sollen rechtsbündig dargestellt werden.
|}

=== Internal Value ausgeben ===
Dieses Beispiel könnte entfallen (nächstes Beispiel ist sehr ähnlich; es wird lediglich ein weiterer Wert ausgegeben).
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI</code>
| Den RSSI Wert aller Devices (am IODev ''cul'') die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau.
| rowspan=1 | [[Datei:rgculRSSI.png|thumb]]
|}

=== Internal Values ausgeben ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI,+cul_TIME</code>
| Den RSSI Wert mit der zugehörigen Zeit aller Devices (am IODev ''cul'') die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau. "Internal Values" werden durch das vorangestellte '''+''' (Pluszeichen) identifiziert.
| rowspan=2 | [[Datei:rgculRSSI2.png|thumb]]
|-
|attr culRSSI valueStyle {return undef if($READING =~ m/TIME/); ($VALUE <= -85)?'style="color:red"':($VALUE <= -80)?'style="color:yellow"':undef}
|Schlechte RSSI Werte sollen abhängig von zwei Schwellwerten gelb oder rot eingefärbt werden (auf dem Screenshot nicht zu sehen).
|}

=== Alle Readings eines Gerätes, mit Ausnahme von... ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Systemstatus readingsGroup sysstat</code>
| Alle readings des sysstat Device
| rowspan=4 | [[Datei:rgSysstat.png|thumb]]
|-
| <code>attr Systemstatus nostate 1</code>
| Ohne state
|-
| <code>attr Systemstatus notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Systemstatus mapping {'load' => 'Systemauslastung', 'temperature' => 'Systemtemperatur in &deg;C'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|}

=== Anzeige auf einem Floorplan ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Heizung readingsGroup t(1|2|3):temperature</code>
| Die Temperatur readings der Devices t1, t2 und t3
| rowspan=6 | [[Datei:rgHeizung.png|thumb|220px]]
|-
| <code>attr Heizung mapping {'t1.temperature' => 'Vorlauf', 't2.temperature' => 'R&ücklauf', 't3.temperature' => 'Zirkulation'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|-
| <code>attr Heizung nameStyle style="text-align:left"</code>
| Zeilentitel linksbündig wegen floorplan
|-
| <code>attr Heizung style style="font-size:20px;color:lightgray"</code>
| Großer Font und Farbe passend für den floorplan
|-
| <code>attr Heizung notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Heizung valueFormat : %.1f &deg;C</code>
| Doppelpunkt zwischen Zeilentitel und Wert, eine Nachkommastelle plus Einheit
|}

=== LightScene DropDown-Menü für smallscreen Styles oder Floorplan ===

{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define lcDropDown readingsGroup meineLightScene:!state</code>
| Für die LightScene ''meineLightScene'' soll ein DropDown-Menü zur Auswahl der Szene erstellt werden.
| rowspan=6 |
|-
| <code>attr lcDropDown commands { state => 'scene:' }</code>
| Die Anzeige des state Readings wird auf das DropDown-Menü für das scene Kommando gemapped.
|-
| <code>attr lcDropDown nonames 1</code>
| Keine Readingnamen
|-
| <code>attr lcDropDown notime 1</code>
| Kein Timestamp
|}

=== Schriftgrößen, Farben, Icons ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgVerbrauchPCA301.png|links|mini|400px|Schriftgröße, Farbe, Icons...]]
|-
| style="width:40%" |<code>define Verbrauch readingsGroup TYPE=PCA301:state,power,consumption</code>
| Die readings state, power und consumption aller [[PCA301 Funkschaltsteckdose mit Energieverbrauchsmessung|PCA301]] Devices mit einer Zeile pro Device.
|-
| <code>attr Verbrauch mapping %ROOM %ALIAS</code>
| Der Raumname und der Alias werden als Zeilentitel verwendet
|-
| <code>attr Verbrauch nameStyle style="font-weight:bold"</code>
| Der Zeilentitel soll fett sein
|-
| <code>attr Verbrauch style style="font-size:20px"</code>
| Alles in einem größeren Font
|-
| <code>attr Verbrauch valueFormat {power => "%.1f W", consumption => "%.2f kWh"}</code>
| Die Formatierung für die power und consumption readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr Verbrauch valueIcon { state => '%devStateIcon' }</code>
| Für die Dosen, die schaltbar sind, soll das anklickbare device icon gezeigt werden.
|-
|<code>attr Verbrauch valueStyle {($READING eq "power" && $VALUE > 40)?'style="color:red"':'style="color:green"'}</code>
|Wenn das power reading >40 ist, soll es in rot angezeigt werden, alle anderen Werte und readings in grün
|}

=== Wertabhängige Farbgebung ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:TemperaturenRG.png|600px|mini|links|Wertabhängige Farben]]
[[Datei:TemperaturenRG2.png|600px|mini|links|Andere Werte - andere Farben]]
|-
| style="width:40%" |<code>define wzTemperaturenRG readingsGroup Aussen:,<Temperatur>,temperature,<Luftfeuchte>,humidity Wohnzimmer:,<Temperatur>,temperature,<Luftfeuchte>,humidity Kasten_E_Geraete:,<Temperatur>,temperature,<Luftfeuchte>,humidity</code>
| Die readings temperatur und humidity der Devices Aussen, Wohnzimmer und Kasten_E_Geraete in einer Zeile pro Device.
|-
| <code>attr wzTemperaturenRG group 3. Temperaturen</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzTemperaturenRG noheading 1</code>
| noheading
|-
| <code>attr wzTemperaturenRG nostate 1</code>
| nostate
|-
| <code>attr wzTemperaturenRG notime 1</code>
| notime
|-
| <code>attr wzTemperaturenRG valueFormat {temperature => "%.1f °C", humidity =>"%.1f %%" }</code>
| Die Formatierung für die temperatur und humidity readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr wzTemperaturenRG valueStyle { if($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 20) { 'style="color:orange"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE < 5) { 'style="color:blue"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 23) { 'style="color:red"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 21) { 'style="color:orange"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE < 20) { 'style="color:blue"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 28) { 'style="color:orange"'}elsif($READING eq "humidity" && $VALUE > 65) { 'style="color:red"'}elsif($READING eq "humidity" && $VALUE > 60) { 'style="color:orange"'}else{'style="color:green"'} }</code>
| Diverse Farbkombinationen sind möglich
|}

=== Enigma Receiver ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:ReceiverRG.jpg|600px|mini|links|Wertabhängige Farben]]
[[Datei:ReceiverRGmute.jpg|600px|mini|links|Wertabhängige Farben]]
|-
| style="width:40%" |<code>define wzReceiverRG readingsGroup wzReceiver:,<Aktuell>,eventtitle,<Rest>,eventremaining_hr,<Dauer>,eventduration_hr wzReceiver:<Beschreibung>,eventdescription wzReceiver:,<Nächste>,eventtitle_next,<Start>,eventstart_next_hr,<Dauer>,eventduration_next_hr wzReceiver:,<HDD Kapazität>,hdd1_capacity,<Frei>,wzReceiver:hdd1_free wzReceiver:,<Lautstärke>,volume,<HDD>,hdd1_capacity,<Frei>,hdd1_free</code>
| Mehrere readings des Device wzReceiver in mehreren Zeilen. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke, mute angezeigt. Farbige Anzeige des freien Speicherplatzes
'''Benötigt:''' ENIGMA2 Receiver, 70_ENIGMA2.pm - Siehe: [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern]]
|-
| <code>attr wzReceiverRG group Fernseher Receiver</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzReceiverRG mapping &nbsp;</code>
| mapping wird auf &nbsp; (Leerzeichen) gesetzt, damit der Device Name nicht angezeigt wird
|-
| <code>attr wzReceiverRG noheading 1</code>
| noheading
|-
| <code>attr wzReceiverRG nostate 1</code>
| nostate
|-
| <code>attr wzReceiverRG notime 1</code>
| notime
|-
|-
| <code>attr wzReceiverRG valueColumns { eventdescription => 'colspan="4"' }</code>
| Die Beschreibung soll über 4 Spalten gehen
|-
| <code>attr wzReceiverRG valueFormat { wzReceiverRGvalueFormat($DEVICE,$READING,$VALUE);; }</code>
| Die Formatierung wird in die 99_myUtils.pm ausgelagert. Siehe: [[99 myUtils anlegen]]
|-
|<code>attr wzReceiverRG valueStyle { if($READING eq "hdd1_free" && $VALUE < 200){ 'style="color:red"' }elsif( $READING eq "hdd1_free" && $VALUE < 500 ){ 'style="color:orange"' }elsif( $READING eq "volume" && ReadingsVal($DEVICE, "mute", "") eq "on" ){ 'style="color:red"' }else{ 'style="color:green"' } }</code>
| Diverse Farbkombinationen sind möglich. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke mute angezeigt.
|-
|<syntaxhighlight lang="perl">
sub
wzReceiverRGvalueFormat($$$)
{
my ($DEVICE,$READING,$VALUE) = @_;

if($READING eq 'hdd1_capacity') {
return "%.2f MB";
} elsif( $READING eq 'hdd1_free') {
return "%.2f MB";
} elsif( $READING eq 'volume' ) {
if( ReadingsVal($DEVICE, "mute", "") eq "on") {
return "mute";
} else {
return "%i %%";
}
}
}</syntaxhighlight>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]
|}

=== Heizungswerte inklusive Batterie- und Fensterstatus ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung3.png|thumb|links|500px|Heizungswerte inklusive Batterie- und Fensterstatus]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<%18>,<%20>,<%22>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte commands { 'Heizungswerte.18' => 'set $DEVICE desired-temp 18', 'Heizungswerte.20' => 'set $DEVICE desired-temp 20', 'Heizungswerte.22' => 'set $DEVICE desired-temp 22' }</code>
| Die Links/Kommandos die hinter den 18, 20 und 22 liegen sollen.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte inklusive Ventilposition ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:Rg_Heizung_Valveposition.png|thumb|links|500px|Heizungswerte inklusive Statusinformationen (MAX!)]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,<Ventil>,<Soll>,<Ist>,<MaxV>,<GID>,<Mode>,<Batterie> TYPE=CUL_HM:ValvePosition,desired-temp,measured-temp,R-valveMaxPos,groupid,mode,battery</code>
| Diverse readings aller Devices des Typs MAX.
|-
| <code>attr Heizungswerte mapping %ROOM</code>
| Die Raumnamen werden angezeigt.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb (fett) sein.
|-
| <code>attr Heizungswerte room Heizung</code>
| Die "readingsgroup" wird dem Raum "Heizung" zugeordnet.
|-
| <code>attr Heizungswerte valueFormat {'temperature' => "%.0f °C", 'desiredTemperature' => "%.0f °C", 'valveposition' =>"%.0f %%", 'maxValveSetting' =>"%.0f %%" }</code>
| Es wird noch die Einheit °C hinter den Temperaturwerten angezeigt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batteriezustand werden Icons anstatt Klartextwerte genommen!
|-
| <code>attr Heizungswerte valueStyle { if($READING eq "temperature" && $VALUE > 20){ 'style="color:green;;font-weight:bold"' }elsif( $READING eq "temperature" && $VALUE <= 20 ){ 'style="color:blue"' }elsif( $READING eq "temperature" && $VALUE > 23 ){ 'style="color:red"' }else{ 'style="color:gray"' } }</code>
| Die Temperaturwerte werden abhängig vom Wert farbig dargestellt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte, Status und Regelmöglichkeit ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung2.png|thumb|500px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define Heizungswerte2 readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<{myUtils_HeizungUpDown($DEVICE,"up")}@desired-temp>,desired-new,<{myUtils_HeizungUpDown($DEVICE,"down")}@desired-temp>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte2 nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte2 valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|-
| <code>attr Heizungswerte2 valueStyle {($VALUE eq "00")?'style="visibility:hidden"':''}</code>
| Nach dem Einstellen den Wert wieder ausblenden.
|-
| <syntaxhighlight lang="perl">
#Heizung regeln in readingsGroup
sub
myUtils_HeizungUpDown($$)
{
my($DEVICE,$CMD) = @_;

my $icon = $CMD;
my $VALUE = ReadingsVal($DEVICE,"desired-new","20" );
$VALUE = ReadingsVal($DEVICE,"desired-temp","20" )
if( !$VALUE || $VALUE == 0 );
my $link;

if( $CMD eq "up" ) {
$icon = "control_arrow_upward";
$VALUE += 1;

if( $VALUE <= 24 ) {
$icon .= "\@red";
$link = "setreading $DEVICE desired-new $VALUE";
}
} elsif( $CMD eq "down" ) {
$icon = "control_arrow_downward";
$VALUE -= 1;

if( $VALUE >= 18 ) {
$icon .= "\@blue";
$link = "setreading $DEVICE desired-new $VALUE";
}
}

my $notify = "notifyHeizungUpDown";
if( !defined($defs{$notify}) ) {
CommandDefine(undef,
"$notify notify .*:desired-new.* "
."{ myUtils_HeizungUpDownNotify(\$NAME,\$EVTPART1); }" );
}

my $ret = "%$icon";
$ret .= "%$link" if( $link );

return $ret;
}

sub
myUtils_HeizungUpDownNotify($$)
{
my($DEVICE,$VALUE) = @_;

return if( $VALUE == 0 );

my $at = "triggerHeizungUpDown_$DEVICE";
CommandDelete(undef, $at) if( defined($defs{$at}) );
CommandDefine(undef,
"$at at +00:00:03 "
."{my \$v = ReadingsVal(\"$DEVICE\",\"desired-new\",undef);"
."fhem(\"set $DEVICE desired-temp \$v\") if( \$v );"
."fhem(\"setreading $DEVICE desired-new 00\");}" );

return undef;
}</syntaxhighlight>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit werden die Icons zum Ändern der gewünschten Temperatur dargestellt und im Bereich >=18 und <= 24 Grad anklickbar gemacht. Zwischen den Pfeilen wird der gerade eingestellte Wert angezeigt. Wenn dieser drei Sekunden nicht mehr geändert wurde wird die desired-temp auf diesen Wert gesetzt und die Anzeige zwischen den Pfeilen ausgeblendet.
|}

=== Heizungswerte, Status, Steuerung und Wochenprofil ===
Dieses Beispiel funktioniert nur mit HomeMatic HM-CC-RT-DN, für andere Thermostate müssen an diversen Stellen Änderungen vorgenommen werden.
{{Todo|Überarbeiten: umstellen auf readingList oder setreading, label als readings in die readingsGroup selber stecken statt in einen extra dummy. oder !<reading> und mapping verwenden.}}
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:RgThermostate.png|thumb|750px|links|Status, Steuerung und Wochenprofil]]
|-
| style="width:40%" |<pre>
define d_label dummy
setreading d_label Heizung Heizung
setreading d_label Temperatur Temperatur
setreading d_label Status Status
setreading d_label Wochenplan Wochenplan
setreading d_label Werktag Werktag
setreading d_label Samstag Samstag
setreading d_label Sonntag Sonntag
setreading d_label Zeitraum1 Zeitraum 1
setreading d_label Zeitraum2 Zeitraum 2 </pre>
|Erzeugen der Readings im Device [[dummy#d_label|d_label]]. (Zeilenweise in die Befehlszeile eintragen.)
|-
| <code>
define rg_thermostate readingsGroup <>,Heizung@d_label,<|>,Temperatur@d_label,<|>,Status@d_label,<|>,Wochenplan@d_label,<|>,Werktag@d_label,<|>,Samstag@d_label,<|>,Sonntag@d_label,<|>,<> CUL_HM_HM_CC_RT_DN_......_Clima:<>,?alias,<|>,<Soll>,desired-temp,<Tag>,dayTemp@{rg($DEVICE."§clima")},impossible@{$DEVICE},<|>,controlMode,R-globalBtnLock@{rg($DEVICE."§device")},<|>,Zeitraum1@d_label,<|>,workday_period_1_start@{rg($DEVICE."§clima")},workday_period_1_stop@{rg($DEVICE."§clima")},<|>,saturday_period_1_start@{rg($DEVICE."§clima")},saturday_period_1_stop@{rg($DEVICE."§clima")},<|>,sunday_period_1_start@{rg($DEVICE."§clima")},sunday_period_1_stop@{rg($DEVICE."§clima")},<|>,impossible@{$DEVICE},<%system_fhem_update>,<nowiki> </nowiki>,state@{rg($DEVICE."§device")},<%getConfig>,<|>,<Ist>,measured-temp,<Nacht>,nightTemp@{rg($DEVICE."§clima")},<|>,<Ventil>,ValvePosition,<|>,Zeitraum2@d_label,<|>,workday_period_2_start@{rg($DEVICE."§clima")},workday_period_2_stop@{rg($DEVICE."§clima")},<|>,saturday_period_2_start@{rg($DEVICE."§clima")},saturday_period_2_stop@{rg($DEVICE."§clima")},<|>,sunday_period_2_start@{rg($DEVICE."§clima")},sunday_period_2_stop@{rg($DEVICE."§clima")},<|>,impossible@{$DEVICE},impossible@{rg($DEVICE."§device")},<%burstXmit> </code>
| Diverse readings aller Devices CUL_HM_HM_CC_RT_DN_......_Clima, entsprechender [[Makefine#d_climaControl|d_climaControl]] (müssen vorher angelegt werden) und [[dummy#d_label|d_label]].
|-
| <code>attr rg_thermostate commands { 'desired-temp' => 'desired-temp:', 'dayTemp' => 'dayTemp:', 'controlMode' => 'trigger ntfy_rg $DEVICE controlMode', 'R-globalBtnLock' => 'trigger ntfy_rg $DEVICE globalBtnLock', 'workday_period_1_start' => 'workday_period_1_start:', 'workday_period_1_stop' => 'workday_period_1_stop:', 'saturday_period_1_start' => 'saturday_period_1_start:', 'saturday_period_1_stop' => 'saturday_period_1_stop:', 'sunday_period_1_start' => 'sunday_period_1_start:', 'sunday_period_1_stop' => 'sunday_period_1_stop:', 'rg_thermostate.system_fhem_update' => 'trigger ntfy_rg $DEVICE setTimeTable', 'rg_thermostate.getConfig' => 'set $DEVICE getConfig', 'nightTemp' => 'nightTemp:', 'workday_period_2_start' => 'workday_period_2_start:', 'workday_period_2_stop' => 'workday_period_2_stop:', 'saturday_period_2_start' => 'saturday_period_2_start:', 'saturday_period_2_stop' => 'saturday_period_2_stop:', 'sunday_period_2_start' => 'sunday_period_2_start:', 'sunday_period_2_stop' => 'sunday_period_2_stop:', 'rg_thermostate.burstXmit' => 'set $DEVICE burstXmit'}</code>
| Temperaturen werden als DropDown Auswahl dargestellt, Icons triggern [[readingsGroup#sub_rg|ntfy_rg]]
|-
| <code>attr rg_thermostate mapping { 'desired-temp' => '', 'dayTemp' => '', 'workday_period_1_start' => '', 'workday_period_1_stop' => '', 'saturday_period_1_start' => '', 'saturday_period_1_stop' => '', 'sunday_period_1_start' => '', 'sunday_period_1_stop' => '', 'nightTemp' => '', 'workday_period_2_start' => '', 'workday_period_2_stop' => '', 'saturday_period_2_start' => '', 'saturday_period_2_stop' => '', 'sunday_period_2_start' => '', 'sunday_period_2_stop' => ''}</code>
| Ausblenden der Texte vor den DropDowns.
|-
| <code>
attr rg_thermostate nameStyle{($READING eq "Soll" ||$READING eq "Tag" ||$READING eq "%getConfig" ||$READING eq "Ist" ||$READING eq "Nacht" ||$READING eq "Ventil" )?'style="text-align:right"' :($READING eq "%burstXmit" )?'style="text-align:center"' :'style=""'}
</code>
| Ausrichten der Überschriften die keine readings sind.
|-
| <code>attr rg_thermostate nonames 1</code>
| Ausblenden der Device Namen.
|-
| <code>attr rg_thermostate valueColumns { 'Heizung' => 'colspan="2"', 'Temperatur' => 'colspan="4"', 'Status' => 'colspan="2"', 'Werktag' => 'colspan="2"', 'Samstag' => 'colspan="2"', 'Sonntag' => 'colspan="2"', 'alias' => 'colspan="2"'}</code>
| Diverse Readings sollen über mehrere Spalten dargestellt werden.
|-
| <code>attr rg_thermostate valueFormat { 'measured-temp' => "%0.1f °C", 'ValvePosition' => "%0.1f %%"}</code>
| Formatierung für measured-temp und ValvePosition.
|-
| <code>attr rg_thermostate valueIcon { 'controlMode.auto' => 'sani_heating_automatic@green', 'controlMode.set_auto' => 'sani_heating_automatic@orange', 'controlMode.manual' => 'sani_heating_manual@red', 'controlMode.set_manual' => 'sani_heating_manual@orange', 'R-globalBtnLock.on' => 'secur_locked@green', 'R-globalBtnLock.on ' => 'secur_locked@green', 'R-globalBtnLock.set_on ' => 'secur_locked@orange', 'R-globalBtnLock.off' => 'secur_open@red', 'R-globalBtnLock.off ' => 'secur_open@red', 'R-globalBtnLock.set_off ' => 'secur_open@orange'}</code>
| Zuweisung der Icons.
|-
| <code>
attr rg_thermostate valueStyle{($READING eq "Heizung" ||$READING eq "Temperatur" ||$READING eq "Status" ||$READING eq "Wochenplan" ||$READING eq "Werktag" ||$READING eq "Samstag" ||$READING eq "Sonntag" )?'style="font-size:20px;;color:RoyalBlue;;text-align:center"' :($READING eq "alias" )?'style="font-size:11px;;font-weight:bold;;text-align:left"' :($READING eq "ValvePosition" &&$VALUE > 40 )?'style="font-weight:bold;;color:Orange;;text-align:left"' :($READING eq "desired-temp" ||$READING eq "measured-temp" )?'style="text-align:center"' :($READING eq "state" ||$READING eq "ValvePosition" )?'style="text-align:left"' :'style="text-align:right"'}
</code>
| Ausrichten und Einfärben der Readings.
|}

=== Heizungsteuerung für HM Wand- und Heizkörperthermostate ===

Dieses Beispiel wurde für HM-TC-IT-WM-W-EU / HM-CC-RT-DN Geräte erstellt. Verwendung anderer Thermostate wird ggf. Anpassungen erforderlich machen. Die Geräte werden nicht automatisch ermittelt, sondern sind einzeln angegeben.
Es werden Soll- und Ist-Temperaturen angezeigt, Luftfeuchte und Ventilpositionen, Modus, Batterie und Global-Tastenlock.
Steuerungsmöglichkeiten: Solltemperatur, Modus (Manual/Automatik), (globale) Tastenlock.
Die Abweichung der Isttemperatur, die Ventilpositionen, Batteriestand etc. werden farblich hervorgehoben.

Die Gerätenamen (EG_WZ_WT01_Climate / EG_WZ_WT01, EG_WZ_TT01_Clima / EG_WZ_TT01 / EG_WZ_TT02, OG_BZ_WT01_Climate / OG_BZ_WT01, OG_BZ_TT01_Clima / OG_BZ_TT01, OG_SZ_WT01_Climate / OG_SZ_WT01, OG_SZ_TT01_Clima / OG_SZ_TT01, OG_DZ_WT01_Climate / OG_DZ_WT01, OG_DZ_TT01_Clima / OG_DZ_TT01) müssen natürlich entsprechend angepasst werden.

Hinweis: Bei den Geräten muss das Attribut „expert“ auf "1_on" gesetzt werden, andernfalls fehlt das Reading „R-globalBtnLock“. Dies hätte zur Folge, dass in der Spalte Lock der batteryLevel dargestellt wird.

{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:RgHMTh.jpg|thumb|500px|links|Status, Steuerung und Wochenprofil]]
|-
| <code>define heatingInfo readingsGroup <%sani_heating>,<Soll>,<Soll neu>,<Ist>,<Ventil / RH>,<Modus>,<Lock>,<Bat> 
EG_WZ_WT01_Climate:desired-temp,<sollsetz>,measured-temp,humidity,controlMode,R-globalBtnLock@EG_WZ_WT01,batteryLevel@EG_WZ_WT01 \ 
EG_WZ_TT01_Clima:desired-temp,<>,measured-temp,ValvePosition,controlMode,R-globalBtnLock@EG_WZ_TT01,batteryLevel@EG_WZ_TT01 \ 
EG_WZ_TT02_Clima:desired-temp,<>,measured-temp,ValvePosition,controlMode,R-globalBtnLock@EG_WZ_TT02,batteryLevel@EG_WZ_TT02 \ 
<>,<>,<>,<>,<>,<>,<>,<> \ 
OG_BZ_WT01_Climate:desired-temp,<sollsetz>,measured-temp,humidity,controlMode,R-globalBtnLock@OG_BZ_WT01,batteryLevel@OG_BZ_WT01 \ 
OG_BZ_TT01_Clima:desired-temp,<>,measured-temp,ValvePosition,controlMode,R-globalBtnLock@OG_BZ_TT01,batteryLevel@OG_BZ_TT01 \ 
<>,<>,<>,<>,<>,<>,<>,<> \ 
OG_SZ_WT01_Climate:desired-temp,<sollsetz>,measured-temp,humidity,controlMode,R-globalBtnLock@OG_SZ_WT01,batteryLevel@OG_SZ_WT01 \ 
OG_SZ_TT01_Clima:desired-temp,<>,measured-temp,ValvePosition,controlMode,R-globalBtnLock@OG_SZ_TT01,batteryLevel@OG_SZ_TT01 \ 
<>,<>,<>,<>,<>,<>,<>,<> \ 
OG_DZ_WT01_Climate:desired-temp,<sollsetz>,measured-temp,humidity,controlMode,R-globalBtnLock@OG_DZ_WT01,batteryLevel@OG_DZ_WT01 \ 
OG_DZ_TT01_Clima:desired-temp,<>,measured-temp,ValvePosition,controlMode,R-globalBtnLock@OG_DZ_TT01,batteryLevel@OG_DZ_TT01</code>
| ReadingsGoup anlegen.
|-
| <code>attr heatingInfo cellStyle { "r:1"=>'style="font-weight:bold;;font-size:16px"', 
"r:2,c:0"=>'style="font-weight:bold"',"r:6,c:0" =>'style="font-weight:bold"', 
"r:9,c:0"=>'style="font-weight:bold"',"r:12,c:0"=>'style="font-weight:bold"'}</code>
| Schrift fett setzen etc.
|-
| <code>attr heatingInfo commands { 
'heatingInfo.sollsetz'=>'desired-temp:5.0,12.0,18.0,19.0,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0', 
"controlMode.manual"=>"set %DEVICE controlMode auto","controlMode.auto"=>"set %DEVICE controlMode manual", 
"R-globalBtnLock.on"=>"set %DEVICE regSet globalBtnLock off", 
"R-globalBtnLock.off"=>"set %DEVICE regSet globalBtnLock on"}</code>
| Heizungssteuerung ermöglichen
|-
| <code>
attr heatingInfo mapping {OG_BZ_WT01_Climate=>"Bad", 
OG_BZ_TT01_Clima=>"&nbsp;;&nbsp;;&nbsp;;Regler",OG_SZ_WT01_Climate=>"Schlafzimmer", 
OG_SZ_TT01_Clima=>"&nbsp;;&nbsp;;&nbsp;;Regler",OG_DZ_WT01_Climate=>"Duschbad", 
OG_DZ_TT01_Clima=>"&nbsp;;&nbsp;;&nbsp;;Regler",EG_WZ_WT01_Climate=>"Wohnzimmer", 
EG_WZ_TT01_Clima=>"&nbsp;;&nbsp;;&nbsp;;Regler1",EG_WZ_TT02_Clima=>"&nbsp;;&nbsp;;&nbsp;;Regler2",'desired-temp' => ''} 
</code>
| Gewünschte Namen definieren.
|-
| <code>
attr heatingInfo valueFormat {if($READING eq "ValvePosition" && $VALUE ne "0"){$VALUE = int($VALUE/10)*10} 
elsif($READING eq "batteryLevel"){if($VALUE>=3){$VALUE=100} 
elsif($VALUE>=2.7){$VALUE=75}elsif($VALUE>=2.5){$VALUE=50}elsif($VALUE>=2.2){$VALUE=25} 
else{$VALUE=0}}}
</code>
| Werte vorformatieren (für die Icon-Zuordnung).
|-
| <code>
attr heatingInfo valueIcon {'controlMode.manual' => 'sani_heating_manual@795CFF', 
'controlMode.auto' => 'sani_heating_automatic@FFC13A', 'controlMode.boost' => 'sani_heating_boost@FB0C02', 
'humidity'=>'humidity@6FD9FB', 'R-globalBtnLock.on'=>'secur_locked@F7301D', 
'R-globalBtnLock.off'=>'secur_open@0CFB0C','ValvePosition.0' => 'sani_heating_level_0@002AE0', 
'ValvePosition.10' => 'sani_heating_level_10@F8D53D','ValvePosition.20' => 'sani_heating_level_20@FF9341', 
'ValvePosition.30' => 'sani_heating_level_30@F17F3F','ValvePosition.40' => 'sani_heating_level_40@E46C3C', 
'ValvePosition.50' => 'sani_heating_level_50@DE3B3A','ValvePosition.60' => 'sani_heating_level_60@A30D2D', 
'ValvePosition.70' => 'sani_heating_level_70@B40A23','ValvePosition.80' => 'sani_heating_level_80@C40619', 
'ValvePosition.90' => 'sani_heating_level_90@D4030F','ValvePosition.100' => 'sani_heating_level_100@E50005', 
'batteryLevel.100'=>'measure_battery_100@0CFB0C','batteryLevel.75'=>'measure_battery_75@42BC0A', 
'batteryLevel.50'=>'measure_battery_50@F5FF10','batteryLevel.25'=>'measure_battery_25@FB5909', 
'batteryLevel.0'=>'measure_battery_0@E50005','controlMode.set_boost' => 'hourglass', 
'controlMode.set_auto' => 'hourglass','controlMode.set_manual' => 'hourglass', 
'R-globalBtnLock.set_on' => 'hourglass','R-globalBtnLock.set_off' => 'hourglass'}
</code>
| Icons zuordnen.
|-
| <code>
attr heatingInfo valueStyle {if($READING eq "measured-temp") 
{my $t=$VALUE;;my $d=ReadingsVal($DEVICE,'desired-temp',0);; 
if($t-$d>=1){'style="color:rgb(251,63,11);;"'}elsif($t-$d<=-1){'style="color:rgb(79,58,251);;"'} 
else{'style="color:rgb(12,251,12);;"'}}}
</code>
| Farben (zu kalt: blau, zu warm: rot, ok: grün).
|-
| <code>
attr heatingInfo valueSuffix {"desired-temp"=>" °C", "measured-temp"=>" °C", 
"ValvePosition"=>" (".ReadingsVal($DEVICE,$READING,0)." %)", 
"humidity"=>" ".ReadingsVal($DEVICE,$READING,0)." % RH", 
"batteryLevel"=>" (".ReadingsVal($DEVICE,$READING,0)." V)"}
</code>
| Messeinheiten und Zahlenwerte.
|}

=== Readings aus zusätzlichen Devices ===
Im folgenden Beispiel wird gezeigt wie sich Readings zusätzlicher Devices zu einer Zeile mit mehreren Readings hinzufügen lassen. Diese zusätzlichen Devices können z.b. die unterschiedlichen Channel eines HomeMatic Gerätes sein. Im folgenden Beispiel wird der Name des zugehörigen Geräts dynamisch bestimmt.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung4.png|thumb|750px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define myTemp readingsGroup <Raum>,<Tist>,<Tsoll>,<Mode>,<Tnight>,<Tday>,<Hum>,<BatTC>,<Vist>,<Vsoll>,<Verr>,<BatVD> Thermostat.(WZ|OZ|AZ|Bad|Kueche|SZ|GZ|Bad.OG):measured-temp,desired-temp,controlMode,night-temp,day-temp,humidity,battery,ValvePosition@{valveOfDevice($DEVICE)},ValveDesired@{valveOfDevice($DEVICE)},R-valveErrorPos@{valveOfDevice($DEVICE)},battery@{valveOfDevice($DEVICE)} Broetje:ToutIst </code>
| Diverse Readings aller Thermostat Devices und des jeweils zugehörigen Ventilantriebs.
|-
| <code>attr myTemp mapping { 'Broetje' => 'Garten','Thermostat.AZ' => 'EG Arbeitszimmer','Thermostat.SZ' => 'OG Schlafzimmer','Thermostat.WZ'=>'EG Wohnzimmer','Thermostat.Kueche' => 'EG Küche','Thermostat.GZ' => 'OG Gästezimmer','Thermostat.Bad' => 'EG Bad','Thermostat.Bad.OG' => 'OG Bad','Thermostat.OZ' => 'EG Kaminzimmer','desired-temp' => <nowiki>''</nowiki> }</code>
| Die Benennung der Zeilentitel (Das ist je nach Konfiguration auch über $ALIAS und/oder $ROOM lösbar).
|-
| <code>attr myTemp commands { 'desired-temp' => 'desired-temp:' }</code>
| desired-temp soll per dropDown einstellbar sein.
|-
| <code>attr myTemp nameStyle style="color:yellow"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr myTemp valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batteriestand sollen jeweils Icons angezeigt werden.
|-
| <code>attr myTemp valueFormat { 'measured-temp' => "%0.1f &deg;C",'ToutIst' => "%.1f &deg;C",'night-temp' => "%.1f &deg;C",'day-temp' => "%.1f &deg;C",'humidity' => "%.0f
%%",'ValvePosition' => "%.0f %%",'ValveDesired' => "%.0f %%",'R-valveErrorPos' => "%.0f %%" }</code>
| Die Formatierung der Werte.
|-
|<syntaxhighlight lang="perl">
#namen des ventil device aus thermostat device ableiten
sub valveOfDevice ($) {
my ($DEVICE) = @_;

if ($DEVICE =~ m/AZ/) {
return "Ventil.".substr($DEVICE,11).".Nord";
} else {
return "Ventil.".substr($DEVICE,11);
}
}</syntaxhighlight>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hier wird aus dem Namen des Thermostaten der Name des zugehörigen Ventilantriebs abgeleitet.
|}
Da im {...} Teil des <reading>@<device> Arguments keine Leerzeichen oder Kommas vorkommen dürfen ist es in der Regel das Einfachste die Funktionalität wie in diesem Beispiel in eine eigene Routine auszulagern. Mit ein paar 'Tricks' lässt es sich aber manchmal auch ohne Leerzeichen oder Kommas lösen und dann direkt in die Definition schreiben:<code>...,ValvePosition@{$DEVICE=~s/Thermostat/Ventil/;$DEVICE;},...</code>

=== Inhalte filtern ===
Wenn man gewisse Zeilen einer Readingsgroup nicht dargestellt haben möchte, so kann man diese mit Hilfe von <code>valueFormat</code> ausfiltern, bspw.:

<code>attr rg valueFormat { return $VALUE if ( $VALUE > 0 );; return undef;; }</code>

In diesem Bsp. werden alle Zeilen/Devices, deren Value > 0 sind, angezeigt. Alle anderen werden als <code>undef</code> formatiert und erscheinen damit nicht im Listing.

Dies kann man noch weiter ausbauen und dynamische Auswahllisten erstellen (s. [[ReadingsGroup#Dynamische Inhalte]]).

=== Inhalte berechnen ===
Will man nur kleine Berechnungen machen und möchte diese aus irgendeinem Grund nicht in die [[99_myUtils_anlegen|99_myUtils.pm]] auslagern (z.B. der Übersicht halber), so kann man die Berechnung auch direkt in <code>valueFormat</code> einbauen. Ein ganz einfaches Bsp. dazu ist das Filtern von Inhalten ([[ReadingsGroup#Inhalte filtern|s.o.]]).

Im konkreten Beispiel ist via CalDAV ein Abfallkalender eingebunden, der die folgenden Einträge erzeugt:

<syntaxhighlight lang="text">
t_001_bdate 06.02.2017 2017-02-04 14:40:49
t_001_btime 00:00:00 2017-02-04 14:40:49
...
t_001_summary Gelber Sack 2017-02-04 14:40:49
</syntaxhighlight>

Daraus lässt sich mit <code>readingsGroup</code> so direkt keine ordentliche Darstellung erzeugen. Gewünscht ist aber das folgende Format eines Zeileneintrags:

<code>06.02.2017 Gelber Sack</code>

Dies lässt sich durch eine noch einigermaßen kurze Berechnung erzeugen - längere Berechnungen sollte man definitiv in myUtils auslagern (vgl. [[ReadingsGroup#Enigma Receiver|hier]]). Der folgende Code filtert zusätzlich weitere nicht erwünschte Einträge aus und macht noch eine Wortanpassung:

<syntaxhighlight lang="perl">
# die readingsGroup reagiert nur auf summary-Einträge ( .* steht für eine beliebige Anzahl beliebiger Zeichen)

define Abfallkalender readingsGroup calvAbfallKalender:t_.*summary

attr Abfallkalender valueFormat {
use Time::Local;;
# alle Einträge Bio... und 4-wöchige Rest... ignorieren
if (not $VALUE =~ /Bio/ and
not $VALUE =~ /Restmülltonne..4/) {
# readingname für bdate zum summary erzeugen
my $rBdate = $READING =~ s/summary/bdate/r;;
# readingvalue für bdate auslesen
my $vDate = ReadingsVal($DEVICE,$rBdate,"");;
# wenn value 'tonne' enthält dieses entfernen
if ($VALUE =~ /tonne/) {
$vDate . " " . substr($VALUE,0,index($VALUE,'tonne'));;
} else {
"$vDate %VALUE";;
}
} else {
undef;;
}
}
</syntaxhighlight>
Der Code in der cfg-Datei würde bei valueFormat zwischen den Hauptklammern immer ;;;; statt ;; und an jedem Zeilenende ein \ haben.

=== Dynamische Inhalte ===
[[Datei:rgDynamic-1.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 1]]
[[Datei:rgDynamic-2.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 2]]
Es ist möglich, den in einer readingsGroup dargestellten Inhalt dynamisch von zusätzlichen Bedingungen abhängig zu machen. Im folgenden Beispiel lässt sich
einstellen, dass nur die Devices angezeigt werden, die einen bestimmten Zustand (hier: on/off, open/tilted/closed) haben. Hier wird zum Umschalten ein dummy, der direkt über der readingsGroup dargestellt wird, verwendet. Über das links und/oder commands lässt sich auch eine Darstellung erzeugen, bei der das Umschalten direkt innerhalb der readingsGroup möglich ist.

<pre>
define LXrg dummy
attr LXrg group -
attr LXrg setList mode1:on,off mode2:open,closed,tilted
attr LXrg stateFormat 1=mode1 2=mode2
attr LXrg webCmd mode1:mode2

define rg readingsGroup Window.*:state Light.*:state
attr rg group -
attr rg valueFormat { return $VALUE if ( $VALUE eq ReadingsVal("LXrg","mode1","") || $VALUE eq ReadingsVal("LXrg","mode2","") );; return undef;;}

define Watch_LX notify LX.*:.* {my $value = ReadingsVal($NAME,'state','');;;;fhem("setreading $NAME $value")}
</pre>

=== Enable/Disable Button am Beispiel eines WeekdayTimer ===
Dieses Beispiel zeigt die Anwendung einer readingsGroup, um im Frontend einen Enable/Disable Button für ein Objekt darzustellen. Für den [[WeekdayTimer]] gibt es hier spezielle Erweiterungen (set Routinen, um das Attribut ''disable'' zu setzen). Es gibt aber auch eine allgemeinere Variante (siehe {{Link2Forum|Topic=23655|Message=169141|LinkText=diesen Forumsbeitrag}}) für alle Objekte, die das FHEM Attribut ''disable'' unterstützen.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rg_scheduling.png|thumb|500px|links|Enable/Disable Button]]
|-
| style="width:40%" |<code>define rg_Timer_Wasser readingsGroup timer_Wasser_..:disabled,+DEF,<{rg_timer_Wasser_show_conditional($DEVICE,"nextUpdate")}@disabled>,<{rg_timer_Wasser_show_conditional($DEVICE,"nextValue")}@disabled></code>
| Definition der angezeigten Readings. Das Attribut ''disabled'' wird mit weiteren Einstellungen (''commands'') zum Button, +DEF zeigt die Definition, d.h. die Schaltzeiten, des Timers an. Die Readings nextUpdate und nextValue sollen nur angezeigt werden, falls der Timer aktiv ist. Hierfür sorgt eine Routine <code>rg_timer_Wasser_show_conditional</code>, die in der 99_myUtils.pm definiert wird. Das abschließende @disabled sorgt dafür, dass der LongPoll Mechanismus die Anzeige sofort ändert, wenn der Button betätigt wird.
|-
| <code>attr rg_Timer_Wasser valueFormat { if ( $READING =~ m/.*DEF/ ) { my @text = split(" ", $VALUE); shift @text; return join(" ", @text) }}</code>
| Der Name des Timers wird aus dem Internal "+DEF" vorne abgeschnitten. Damit werden nur die definierten Schaltpunkte angezeigt.
|-
| <code>attr rg_Timer_Wasser valueIcon { 'disabled.0' => 'Restart', 'disabled.1' => 'Shutdown' }</code>
| Die beiden Zustände für den Button werden durch zwei Standard-Icons angezeigt.
|-
| <code>attr rg_Timer_Wasser commands { 'disabled.0' => 'set $DEVICE disable', 'disabled.1' => 'set $DEVICE enable' }</code>
| Toggle-Funktion für den Button. Wenn der Timer aktiv ("disabled.0") ist, sorgt ein Klick auf den Button dafür, dass der Timer deaktiviert wird ("set $DEVICE disable").
|-
|<syntaxhighlight lang="perl">
sub rg_timer_Wasser_show_conditional($$)
{
my ($DEVICE,$READING) = @_;
return ( ReadingsVal($DEVICE, "disabled", "1") eq "0" )?
ReadingsVal($DEVICE, $READING, "reading_undef") : "disabled";
}</syntaxhighlight>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit wird das übergebene Reading des Timers nur angezeigt, wenn der Timer aktiv ist. Andernfalls wird der String "disabled" angezeigt.
|}

=== Ändern von Attributen: Noch ein WeekdayTimer Beispiel ===
{{Randnotiz|RNTyp=y|RNText=Dieses Beispiel benutzt Funktionen, die erst ab [[version|Modulversion]] 8761/16.6.2015 verfügbar sind.}}
Inzwischen ist es auch möglich das commands Mapping auf Attribute anzuwenden. Die Syntax ist die gleiche wie für die set Kommandos. Um das Beispiel übersichtlich zu halten werden hier die Werte und Icons auch für deaktivierte WeekdayTimer angezeigt.

{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rg_timer.png|thumb|500px|links|FHEMWidget für das 'disable' Attribut]]
|-
| style="width:40%" |<code>define rgTimer readingsGroup <>,<Current>,<Update-Time>,<New>,<disable> TYPE=WeekdayTimer:state,nextUpdate,nextValue,?!disable</code>
| Definition der angezeigten Readings. Das Attribut ''disable'' wird mit weiteren Einstellungen (''commands'') zum Button. Durch das ! wird das Attribut auch dann angezeigt wenn es noch nicht gesetzt ist.
|-
| <code>attr rgTimer valueIcon { state => '%devStateIcon', nextValue => '{(split(":",Color::devStateIcon($DEVICE,"dimmer",undef,"nextValue")))[1]}' }</code>
| Für den aktuellen Zustand wird das devStateIcon angezeigt und für den nächsten Zustand das passende Lampen-Icon.
|-
| <code>attr rgTimer valueFormat '{(split(" ", $VALUE))[1]}'</code>
| Vom nächsten Schaltpunkt wird nur die Zeit angezeigt.
|-
| <code>attr rgTimer commands { disable => 'disable:' }</code>
| Für das disable attribut wird das normale dropDown mit 0 und 1 angezeigt das auch in der Device Detail Ansicht verwendet wird.
|}

=== Readings löschen ===
Es kann vorkommen, dass Readings angezeigt werden, die gar nicht existieren sollten - bspw. wenn man in einer HTTPMOD ein Reading umbenannt hat, kann auch der alte Readingsname immer noch angezeigt werden. Solche Readings können mit der globalen Funktion {{Link2CmdRef|Anker=deletereading|Label=deletereading}} gelöscht werden.

'''Achtung:''' Auf jeden Fall die {{Link2CmdRef|Anker=deletereading}} dazu lesen!

Beispiel:
Im HTTPMOD des [[Pollenflug]] war zuerst das <code>reading04Name Graeser</code> definiert und wurde später in <code>reading04Name Gräser</code> umbenannt. In der zugehörigen ReadingGroup wurden dann konsequent beide Varianten dargestellt - auch nachdem alle Alt-Einträge aus den Logs entfernt wurden. Erst ein <code>deletereading Pollenflug Graeser</code> in der FHEM-Befehlszeile hat das veraltete Reading entfernt.

=== Ausrichtung der Tabelle drehen (horizontal/vertikal) ===
Eine Readingsgroup wird standardmäßig immer zeilenweise aufgebaut, z.B. jedes Gerät in eine neue Zeile. Die Werte der Geräte werden dann in den Spalten dargestellt.
Wenn man eine Readingsgroup für nur ein Gerät mit vielen Readings hat (z.B. [[Allergy]]), so kann man die Darstellung horizontal oder vertikal ausrichten, indem man die Readingsgroup detailliert definiert. Ein Bsp. dazu liefert der Foreneintrag {{Link2Forum|Topic=37194|Message=440446}} :

<pre>
define Pollenflugvorhersage allergy <PLZ>
attr Pollenflugvorhersage levelsFormat rc_dot@white,rc_dot@yellow,rc_dot@orange,rc_dot@red
attr Pollenflugvorhersage stateFormat fc1_maximum
attr Pollenflugvorhersage updateEmpty 1
attr Pollenflugvorhersage updateIgnored 1

# Pollen in Spalten, Tage in Zeilen
define PollenAlarmHorizontal readingsGroup <>,<Ampfer>,<Ambrosia>,<Beifuß>,<Birke>,<Buche>,<Eiche>,<Erle>,<Gräser>,<Hasel>,<Pappel>,<Roggen>,<Ulme>,<Wegerich>,<Weide> \
Pollenflugvorhersage:fc1_day_of_week,fc1_Ampfer,fc1_Ambrosia,fc1_Beifuß,fc1_Birke,fc1_Buche,fc1_Eiche,fc1_Erle,fc1_Gräser,fc1_Hasel,fc1_Pappel,fc1_Roggen,fc1_Ulme,fc1_Wegerich,fc1_Weide \
Pollenflugvorhersage:fc2_day_of_week,fc2_Ampfer,fc2_Ambrosia,fc2_Beifuß,fc2_Birke,fc2_Buche,fc2_Eiche,fc2_Erle,fc2_Gräser,fc2_Hasel,fc2_Pappel,fc2_Roggen,fc2_Ulme,fc2_Wegerich,fc2_Weide \
Pollenflugvorhersage:fc3_day_of_week,fc3_Ampfer,fc3_Ambrosia,fc3_Beifuß,fc3_Birke,fc3_Buche,fc3_Eiche,fc3_Erle,fc3_Gräser,fc3_Hasel,fc3_Pappel,fc3_Roggen,fc3_Ulme,fc3_Wegerich,fc3_Weide \
Pollenflugvorhersage:fc4_day_of_week,fc4_Ampfer,fc4_Ambrosia,fc4_Beifuß,fc4_Birke,fc4_Buche,fc4_Eiche,fc4_Erle,fc4_Gräser,fc4_Hasel,fc4_Pappel,fc4_Roggen,fc4_Ulme,fc4_Wegerich,fc4_Weide \
Pollenflugvorhersage:fc5_day_of_week,fc5_Ampfer,fc5_Ambrosia,fc5_Beifuß,fc5_Birke,fc5_Buche,fc5_Eiche,fc5_Erle,fc5_Gräser,fc5_Hasel,fc5_Pappel,fc5_Roggen,fc5_Ulme,fc5_Wegerich,fc5_Weide \
Pollenflugvorhersage:fc6_day_of_week,fc6_Ampfer,fc6_Ambrosia,fc6_Beifuß,fc6_Birke,fc6_Buche,fc6_Eiche,fc6_Erle,fc6_Gräser,fc6_Hasel,fc6_Pappel,fc6_Roggen,fc6_Ulme,fc6_Wegerich,fc6_Weide \
Pollenflugvorhersage:fc7_day_of_week,fc7_Ampfer,fc7_Ambrosia,fc7_Beifuß,fc7_Birke,fc7_Buche,fc7_Eiche,fc7_Erle,fc7_Gräser,fc7_Hasel,fc7_Pappel,fc7_Roggen,fc7_Ulme,fc7_Wegerich,fc7_Weide
attr PollenAlarm nonames 1
attr PollenAlarm valueFormat %VALUE
attr PollenAlarm valueIcon %VALUE

# Tage in Spalten, Pollen in Zeilen
define PollenAlarmVertikal readingsGroup Pollenflugvorhersage:<Pollen>,fc0_day_of_week,fc1_day_of_week,fc2_day_of_week,fc3_day_of_week,fc4_day_of_week,fc5_day_of_week,fc6_day_of_week,fc7_day_of_week \
Pollenflugvorhersage:<Ambrosia>,fc0_Ambrosia,fc1_Ambrosia,fc2_Ambrosia,fc3_Ambrosia,fc4_Ambrosia,fc5_Ambrosia,fc6_Ambrosia,fc7_Ambrosia\
Pollenflugvorhersage:<Ampfer>,fc0_Ampfer,fc1_Ampfer,fc2_Ampfer,fc3_Ampfer,fc4_Ampfer,fc5_Ampfer,fc6_Ampfer,fc7_Ampfer\
Pollenflugvorhersage:<Beifuß>,fc0_Beifuss,fc1_Beifuss,fc2_Beifuss,fc3_Beifuss,fc4_Beifuss,fc5_Beifuss,fc6_Beifuss,fc7_Beifuss\
Pollenflugvorhersage:<Birke<Birke>,fc0_Birke,fc1_Birke,fc2_Birke,fc3_Birke,fc4_Birke,fc5_Birke,fc6_Birke,fc7_Birke\
Pollenflugvorhersage:<Buche>,fc0_Buche,fc1_Buche,fc2_Buche,fc3_Buche,fc4_Buche,fc5_Buche,fc6_Buche,fc7_Buche\
Pollenflugvorhersage:<Eiche>,fc0_Eiche,fc1_Eiche,fc2_Eiche,fc3_Eiche,fc4_Eiche,fc5_Eiche,fc6_Eiche,fc7_Eiche\
Pollenflugvorhersage:<Erle<Erle>,fc0_Erle,fc1_Erle,fc2_Erle,fc3_Erle,fc4_Erle,fc5_Erle,fc6_Erle,fc7_Erle\
Pollenflugvorhersage:<Gräser>,fc0_Graeser,fc1_Graeser,fc2_Graeser,fc3_Graeser,fc4_Graeser,fc5_Graeser,fc6_Graeser,fc7_Graeser\
Pollenflugvorhersage:<Hasel<Hasel>,fc0_Hasel,fc1_Hasel,fc2_Hasel,fc3_Hasel,fc4_Hasel,fc5_Hasel,fc6_Hasel,fc7_Hasel\
Pollenflugvorhersage:<Pappel>,fc0_Pappel,fc1_Pappel,fc2_Pappel,fc3_Pappel,fc4_Pappel,fc5_Pappel,fc6_Pappel,fc7_Pappel\
Pollenflugvorhersage:<Roggen>,fc0_Roggen,fc1_Roggen,fc2_Roggen,fc3_Roggen,fc4_Roggen,fc5_Roggen,fc6_Roggen,fc7_Roggen\
Pollenflugvorhersage:<Ulme>,fc0_Ulme,fc1_Ulme,fc2_Ulme,fc3_Ulme,fc4_Ulme,fc5_Ulme,fc6_Ulme,fc7_Ulme\
Pollenflugvorhersage:<Wegerich>,fc0_Wegerich,fc1_Wegerich,fc2_Ulme,fc3_Wegerich,fc4_Wegerich,fc5_Wegerich,fc6_Wegerich,fc7_Wegerich\
Pollenflugvorhersage:<Weide>,fc0_Weide,fc1_Weide,fc2_Weide,fc3_Weide,fc4_Weide,fc5_Weide,fc6_Weide,fc7_Weide
</pre>

== Berechnungen ==
{{Randnotiz|RNTyp=y|RNText=Dieses Beispiel benutzt Funktionen, die erst ab [[version|Modulversion]] 8761/16.6.2015 verfügbar sind.}}
Das Rechnen funktioniert über das Flag "$", mit dem eine Funktion angegeben werden kann, die auf beliebige Kombinationen von Zeilen, Spalten und einzelnen Zellen angewendet wird. Ähnlich wie in einer Tabellenkalkulation.

Ein Beispiel:
:<code>define rg readingsGroup .*:temperature rg:$avg</code>
Damit wird eine readingsGroup über alle ''temperature'' Readings definiert. In einer zusätzlichen Zeile am Ende wird mit ''$avg'' der Durchschnittswert aller darüber liegenden Temperaturen angezeigt.

Das genaue Format: <code>$<operator>[(<zellen>)]</code> mit
*<code><operator></code>: sum, avg, min, max, scalar, count oder der Name einer beliebigen anderen Funktion, die ein Array mit allen Werten übergeben bekommt und ein Ergebnis zurückliefert.
*<code><zellen></code> ist eine durch Semikolon getrennte Liste aus <code><zeilen>:<spalten></code> Paaren.
*<code><zeilen></code> und <code><spalten></code> sind jeweils eine Perl Liste, d.h. hier können
** einzelne Werte,
** durch Komma getrennte Aufzählungen,
** mit .. angegebene Wertebereiche
** sowie <code>$ROW</code> und <code>$COLUMN</code> als Bezeichner für die aktuelle Zelle
:verwendet werden.

Alle Möglichkeiten sind kombinierbar. Die Zählung der Zeilen und Spalten beginnt bei 1. Eine nicht vorhandene Zeilenangabe wird durch den Bereich von Zeile 1 bis zur aktuellen Zeile ersetzt, eine nicht vorhandene Spalte durch die aktuelle Spalte.

Es ergeben sich somit unter anderem folgende Möglichkeiten:
*<code>$sum</code> equivalent zu <code>$sum(1..$ROW), $sum(:$COLUMN)</code> und <code>$sum(1..$ROW:$COLUMN)</code> die Summe der Werte in der Spalte über der aktuellen Zelle.
*<code>$max($ROW:1..$COLUMN-1)</code> Maximum aller Werte links von der aktuellen Zelle (in der aktuellen Zeile)
*<code>$avg(1..$ROW:1)</code> Durchschnitt aller Werte in Spalte 1 bis zur aktuellen Zeile
*<code>$scalar(:1)</code> Anzahl der Werte in Spalte 1
*<code>$min(1..5:1,2,4)</code> Minimum der Werte aus den Zeilen 1-5 in den Spalten 1, 2 und 4

Eigene Funktionen lassen sich über 99_myUtils anlegen und z.B. verwenden um Häufigkeiten zu zählen oder mit nichtnumerischen Readings umzugehen.

Die Ergebnisse werden im Weiteren wie normale Readings behandelt. Sie lassen sich von links oben nach rechts unten kaskadieren und lassen sich über valuePrefix, valueSuffix, valueFormat und valueStyle in der Darstellung beeinflussen. Also z.B. einfärben, als Balkendiagramm darstellen, ...

Mit Hilfe der Funktionalität zum auf- und zu-klappen von Teilen einer readingsGroup lassen sich z.B. im zusammengeklappten Zustand Summen, Extremwerte oder andere Ausreißer anzeigen und die Details nur beim Aufklappen zeigen.

Weitere Möglichkeiten:
* Attribut <code>firstCalcRow</code>: Hiermit kann der Default für die Nummer der ersten Zeile vorgegeben werden (sofern im Ausdruck nichts genaueres angegeben ist). firstCalcRow sollte z.B. auf 2 gesetzt werden, wenn in der readingsGroup Spaltenüberschriften verwendet werden.
* special <code><nowiki><hr></nowiki></code> um eine horizontale Linie über die volle Breite einzufügen
* Über ein angehängtes <code>@<alias></code> kann einem Rechenergebnis ein Alias-Name gegeben werden. Über diesen kann der Wert dann zur Formatierung mit den value-Attributen angesprochen werden.
* das <code>alwaysTrigger</code> Attribut kann jetzt auch den Wert 2 bekommen. Damit werden in der readingsGroup Readings für alle durch die Aggregation gebildeten Werte und entsprechende Events auch dann erzeugt wenn die readingsGroup nicht angezeigt wird. Wenn ein Alias-Name vergeben ist, wird dieser auch für den Reading-Namen verwendet.
* Über den operator <code>$count(<wert>)(<zellen>)</code> um das Vorkommen von <code><wert></code> in den angegebenen Zellen zu zählen. <code><wert></code> kann enweder direkt der zu zählende Wert sein (ohne Anführungzeichen) oder eine in / eingeschlossene regex. Mit <code>!<wert></code> kann das Nicht-Vorkommen von <code><wert></code> gezählt werden.

=== Ein interaktives Beispiel ===
[[Datei:rgCalc.png|mini|right|400px|Beispiel-readingsGroup mit Berechnungen]]
In drei [[dummy]] Objekten lässt sich jeweils ein Reading über einen Slider einstellen. In der darunter liegenden readingsGroup werden diese Readings und diverse daraus abgeleitete Werte dargestellt. Alle Readings und die daraus abgeleiteten Werte werden live per longpoll aktualisiert, wenn die slider bewegt werden.
 
<pre>
define t1 dummy
attr t1 room rg
attr t1 setList state:slider,-10,1,30
attr t1 webCmd state
define t2 dummy
attr t2 room rg
attr t2 setList state:slider,-10,1,30
attr t2 webCmd state
define t3 dummy
attr t3 room rg
attr t3 setList state:slider,-10,1,30
attr t3 webCmd state

define rg readingsGroup <>,<value>,<sum>,<min>,<max>,<avg>\
t\d:+NAME,state,$sum(1..$ROW:2),$min(1..$ROW:2),$max(1..$ROW:2),$avg(1..$ROW:2)\
<hr>\
rg:<>,$scalar,$sum(:2)@SUM,$min(:2)@MIN,$max(:2)@MAX,$avg(:2)@AVG\
<hr>\
t1:<t1,t2,t3>,state,state@t2,state@t3,$sum($ROW:2..4)@SUM,$count(/\d/)(2..$ROW-4:2)\

attr rg nonames 1
attr rg room rg
attr rg style style='text-align:center'
attr rg valueFormat { 'avg' => '%.2f', 'AVG' => '%.2f' }
attr rg valuePrefix { 'rg.scalar' => '#', 'rg.SUM' =>'Σ; ', 'rg.MIN' =>'Min: ', 'rg.MAX' =>'Max: ', 'rg.AVG' =>'∅; ', 'rg.count' => '#(X): ' }
attr rg valueSuffix { state => '°;C' }
</pre>

== Links und Trigger ==
=== readingsGroup mit Link ===
[[Datei:rgPCA-detail.png|mini|400px|readingsGroup mit Link]]
Das PCA301 Beispiel oben lässt sich mit einem ans Ende des define angehängten
:<code><{appendTrigger($DEVICE,"clear","Alle löschen")}></code>
und der folgenden appendTrigger Definition in 99_myUtils.pm um einen Link erweitern, der ein Event auslöst, an das z.B. ein notify gehängt werden kann, um die Verbrauchszähler der PCA301 Dosen zurückzusetzen.
:<code>define clearVerbrauch notify Verbrauch:clear set TYPE=PCA301 clear</code>

<syntaxhighlight lang="perl">
use vars qw($FW_ME);
use vars qw($FW_subdir);
sub
appendTrigger($$$)
{
my ($name,$trigger,$label) = @_;

my $ret .= "</table></td></tr>";

my $link = "cmd=trigger $name $trigger";
my $txt = "<a onClick=\"FW_cmd('$FW_ME$FW_subdir?XHR=1&$link')\">$label</a>";
$ret .= "<td colspan=\"99\"><div style=\"cursor:pointer;color:#888888;text-align:right\">$txt</div></td>";

return ($ret,0);
}</syntaxhighlight>

Wenn hierdurch Änderungen an einer readingsGroup erfolgen, die ein Neuladen der Seite erforderlich machen, kann dies so erfolgen:
:<code>{myUtils_refresh("WEB")}</code>
mit folgendem code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
sub
myUtils_refresh($)
{
my ($name) = @_;

FW_directNotify("#FHEMWEB:$name", "location.reload(true);","" );
}</syntaxhighlight>

Ein weiteres Beispiel für 'custom links und trigger' findet sich in {{Link2Forum|Topic=14425|Message=109383|LinkText=diesem Forenbeitrag}}: dort wird damit eine readingsGroup dynamisch umgeschaltet, um nur die eingeschalteten, nur die ausgeschalteten oder alle Lampen anzuzeigen.

=== sub rg ===
Damit beim Klicken auf ein Icon oder einen Text in einer readingsGroup etwas passiert ist es möglich dies über das commands Attribut auf ein <code>'trigger ntfy_rg $DEVICE $READING'</code> oder Ähnliches zu mappen.
Anlegen des ntfy_rg notify
<pre>
define ntfy_rg notify ntfy_rg {rg($EVENT)}
</pre>
Folgender Code muss noch in de [[99_myUtils_anlegen|99_myUtils.pm]]
<syntaxhighlight lang="perl">
sub rg($){
my @input = split(/[§\s]+/,shift);
my $device = $input[0];
my $function = $input[1];

if($function eq "clima"){
my $room = AttrVal($device, 'room', 'undef');
$room =~ s/\D//g;

return(("d_climaControl_".$room));
}
elsif($function eq "device"){
return InternalVal($device,"device","device error");
}
elsif($function eq "controlMode"){
my $controlMode = ReadingsVal($device,"controlMode","controlMode error");

if($controlMode ~~ /manual/)
{fhem("set $device controlMode auto")}
elsif($controlMode ~~ /auto/)
{fhem("set $device controlMode manual")};
}
elsif($function eq "globalBtnLock"){
my $globalBtnLock = ReadingsVal($device,"R-globalBtnLock","globalBtnLock error");

if($globalBtnLock ~~ /off/){
{fhem("set $device regSet globalBtnLock on")}
{fhem ("set $device getConfig")}
}
elsif($globalBtnLock ~~ /on/){
{fhem("set $device regSet globalBtnLock off")}
{fhem ("set $device getConfig")}
};
}
elsif($function eq "state"){
my $state = Value($device);

if($state ~~ /off/){
{fhem("set $device on")}
}
elsif($state ~~ /on/){
{fhem("set $device off")}
};
}
elsif($function eq "setTimeTable"){
my $room = AttrVal($device, 'room', 'undef');
$room =~ s/\D//g;
my $climaControl = ("d_climaControl_".$room);
my $dayTemp = ReadingsVal( $climaControl, "dayTemp" , 21.0 );
my $nightTemp = ReadingsVal( $climaControl, "nightTemp" , 17.0 );
my $workday_period_1_start = ReadingsVal( $climaControl, "workday_period_1_start" , "06:30" );
my $workday_period_1_stop = ReadingsVal( $climaControl, "workday_period_1_stop" , "18:00" );
my $workday_period_2_start = ReadingsVal( $climaControl, "workday_period_2_start" , "24:00" );
my $workday_period_2_stop = ReadingsVal( $climaControl, "workday_period_2_stop" , "24:00" );
my $saturday_period_1_start = ReadingsVal( $climaControl, "saturday_period_1_start" , "06:30" );
my $saturday_period_1_stop = ReadingsVal( $climaControl, "saturday_period_1_stop" , "12:00" );
my $saturday_period_2_start = ReadingsVal( $climaControl, "saturday_period_2_start" , "24:00" );
my $saturday_period_2_stop = ReadingsVal( $climaControl, "saturday_period_2_stop" , "24:00" );
my $sunday_period_1_start = ReadingsVal( $climaControl, "sunday_period_1_start" , "24:00" );
my $sunday_period_1_stop = ReadingsVal( $climaControl, "sunday_period_1_stop" , "24:00" );
my $sunday_period_2_start = ReadingsVal( $climaControl, "sunday_period_2_start" , "24:00" );
my $sunday_period_2_stop = ReadingsVal( $climaControl, "sunday_period_2_stop" , "24:00" );

{fhem("set $device tempListMon prep $workday_period_1_start $nightTemp $workday_period_1_stop $dayTemp $workday_period_2_start $nightTemp $workday_period_2_stop $dayTemp 24:00 $nightTemp")};
{fhem("set $device tempListTue prep $workday_period_1_start $nightTemp $workday_period_1_stop $dayTemp $workday_period_2_start $nightTemp $workday_period_2_stop $dayTemp 24:00 $nightTemp")};
{fhem("set $device tempListWed prep $workday_period_1_start $nightTemp $workday_period_1_stop $dayTemp $workday_period_2_start $nightTemp $workday_period_2_stop $dayTemp 24:00 $nightTemp")};
{fhem("set $device tempListThu prep $workday_period_1_start $nightTemp $workday_period_1_stop $dayTemp $workday_period_2_start $nightTemp $workday_period_2_stop $dayTemp 24:00 $nightTemp")};
{fhem("set $device tempListFri prep $workday_period_1_start $nightTemp $workday_period_1_stop $dayTemp $workday_period_2_start $nightTemp $workday_period_2_stop $dayTemp 24:00 $nightTemp")};
{fhem("set $device tempListSat prep $saturday_period_1_start $nightTemp $saturday_period_1_stop $dayTemp $saturday_period_2_start $nightTemp $saturday_period_2_stop $dayTemp 24:00 $nightTemp")};
{fhem("set $device tempListSun exec $sunday_period_1_start $nightTemp $sunday_period_1_stop $dayTemp $sunday_period_2_start $nightTemp $sunday_period_2_stop $dayTemp 24:00 $nightTemp")};
}
}
</syntaxhighlight>
Hier sind die benötigten CodeBlöcke für [[ReadingsGroup#Heizungswerte.2C_Status.2C_Steuerung_und_Wochenprofil|Heizungswerte, Status, Steuerung und Wochenprofil]] enthalten, aber auch um state zu triggern.

== Sonstiges ==
In der Regel werden die Parameter zu einem reading in den mappings unter <$DEVICE> und dann <$DEVICE>.<$READING> und dann unter <$READING>.<$VALUE> gesucht.

=== Lesbar machen ===
Für die meisten Attribute gilt:

* Wenn es komplexer wird ist es einfacher, den Code in eine eigene Routine in (beispielsweise) [[99 myUtils anlegen|99_myUtils]] auszulagern und diese aufzurufen:
:<code> attr <name> valueStyle {myValueToFormat($READING,$VALUE)}</code>
* code für unterschiedliche readings kann auch im mapping schon aufgeteilt werden:
:<code>attr <name> valueStyle { SuperE5 => '{perl code}', Diesel => '{perl code}' }</code>
* Ifs lassen sich verschachteln und sortieren. So kann die Anzahl der Klammern und Else-Zweige reduziert werden:
if( $READING eq ... ) {
return xxx if( $VALUE < 1 );
return yyy if( $VALUE < 1.5 );
return zzz;
} elsif( $READING eq ... ) {
...
}

Da alles lässt sich natürlich auch kombinieren und so viel lesbarer machen als ein einziger langer Bandwurm.

=== readingsGroup in einer Gruppe ===
Wenn der doppelte Rahmen um eine readingsGroup bei Darstellung in einer Gruppe stört, lässt er sich mit dem passenden style entfernen:
:<code>attr <rgName> style style="border:0px;background:none;box-shadow:none"</code>
Für die readingsGroup ''rgName'' wird der Darstellungsstil verändert.

Anwendungs-Bsp: [[Pollenflug]]

=== Einfache Balkendiagramme ===
[[Datei:rgBars.png|mini|400px|readingsGroup mit Balken]]
Readings lassen sich mit einem valueStyle der folgenden Art mit einem "Füllstandsbalken" hinterlegen:
:<code>attr <rgName> valueStyle style="width:200px; text-align:center; border: 1px solid #ccc; background:-webkit-linear-gradient(left, red $VALUE%, rgba(0,0,0,0) $VALUE%)"</code>

Die Balken werden bei Änderungen der Readings automatisch per longpoll aktualisiert.

Diese direkte Definition des <code>valueStyle</code> ist allerdings sehr unflexibel - bspw. müsste der <code>$VALUE</code> zufällig max 100 erreichen und es darf nur ein Browsertyp eingesetzt werden, damit alles sauber funktioniert.

Deutlich flexibler ist eine Auslagerung als eigenständige Funktion in die [[99_myUtils_anlegen|99_myUtils.pm]], die den valueStyle dynamisch generiert, bspw.:

<syntaxhighlight lang="perl">
sub Balkenanzeige($)
{
# Zuweisung der übergebenen Variablen
my ($val) = @_;

# Konfiguration des maximal übergebenen Werts (hier wäre der höchste zu erwartende Wert = 3)
my $maxValue = 3;

# Normalisierung auf 100%-Wert
my $percent = $val / $maxValue * 100;

# Definition des valueStyles
my $stylestring = 'style="'.
'width: 200px; '.
'text-align:center; '.
'border: 1px solid #ccc ;'.
'background-image: -webkit-linear-gradient(left,red '.$percent.'%, rgba(0,0,0,0) '.$percent.'%); '.
'background-image: -moz-linear-gradient(left,red '.$percent.'%, rgba(0,0,0,0) '.$percent.'%); '.
'background-image: -ms-linear-gradient(left,red '.$percent.'%, rgba(0,0,0,0) '.$percent.'%); '.
'background-image: -o-linear-gradient(left,red '.$percent.'%, rgba(0,0,0,0) '.$percent.'%); '.
'background-image: linear-gradient(left,red '.$percent.'%, rgba(0,0,0,0) '.$percent.'%);"';

# Rückgabe des definierten Strings
return $stylestring;
}
</syntaxhighlight>

Der Aufruf sähe dann wie folgt aus:

<code> attr <rgName> valueStyle { Balkenanzeige($VALUE) } </code>

Die einzelnen Werte des <code>$stylestring</code> haben folgende Bedeutungen:
* width - Breite des Balkenrahmens
* text-align - Ausrichtung des Texts
* border - Format des Balkenrahmens
* background-image - Format des Hintergrunds des Balkenrahmens, also des Balkens selbst
** linear-gradient - css-Funktion zur Erstellung von Farbverläufen ''(*)''
*** left - linksbündiger Balken
*** red x% - roter Balken x% breit
*** rgba(0,0,0,0) x% - farbloser Teil startet bei x%

''(*) linear-gradient wird in verschiedenen Browsern unterschiedlich umgesetzt. Deshalb sollten immer alle Varianten zusammen angegeben werden, damit die Darstellung auf allen Browsern funktioniert. (vgl. Link unten)''

Weitere Infos zu:
* linear-gradient - [https://developer.mozilla.org/de/docs/Web/CSS/linear-gradient]
* Farbanpassungen, z.B. auch unter Verwendung der [[Color#Skalenfarbe_mit_Color::pahColor|Color::pahColor]] Routine.
* Anpassung von Werten s.o. [[ReadingsGroup#Lesbar_machen]]
* weiteren Möglichkeiten zur Erzeugung von Balkendiagrammen in Forenbeiträgen {{Link2Forum|Topic=25313|LinkText=hier}} und {{Link2Forum|Topic=28318|LinkText=hier}}
* [[99_myUtils_anlegen|99_myUtils.pm]]

Anwendungs-Bsp: [[Pollenflug]]

=== readingsGroup Styling mit CSS ===
Jede readingsGroup lässt sich durch CSS individuell stylen.

==== Allgemeines ====
Damit der eigene CSS Code nach einem [[Update]] der FHEM-Style Dateien vorhanden bleibt, ist es notwendig eine eigene .css Datei (z.B. ios7ReadingsGroups.css) zu erstellen und ins Verzeichnis ''fhem/www/pgm2/'' zu kopieren. Anschließend muss in der [[FHEMWEB]] Instanz das Attribut ''CssFiles'' auf z.B. ''pgm2/ios7ReadingsGroups.css'' gesetzt werden.

==== Erweiterte Device Übersicht ====
Diese ReadingsGroup ist an der [[FHEMWEB]] Device-Übersicht angelehnt. Zusätzlich werden weitere Readings, hier Leistung, Betriebszeit Heute und Jahr, ein Link zur Detail-Seite der ReadingsGroup und Links zu der jeweiligen Device-Detail-Seite, dargestellt.

{| class="wikitable"
| [[Datei:RgStylingOhneCss.png|600px|mini|left|Device ReadingsGroup ohne CSS]] [[Datei:RgStylingMitCss.png|600px|mini|left|Device ReadingsGroup mit CSS]]
|}

===== Definition =====
<pre>
define rg_devices readingsGroup <{rgLink($DEVICE,"konfigurieren","Details")}>,<Device>,<Status>,<Leistung>,<Heute>,<Jahr>\
wzDeckenfluter:<%light_floor_lamp>,<{rgLink("wzDeckenfluter","detail","Deckenfluter")}>,state,<>,dauerHeute,dauerJahr\
wzMacMini:<%it_nas>,<{rgLink("wzMacMini","detail","MacMini")}>,state,power,consumption,consumptionYear\
attr rg_devices noheading 1
attr rg_devices nonames 1
attr rg_devices notime 1
attr rg_devices room ReadingsGroup Styling
attr rg_devices style class="block wide rgDevices"
attr rg_devices valueFormat { 'power' => "%.1f W ", consumption => "%.2f kWh", 'consumptionYear' => "%.2f kWh" }
attr rg_devices valueIcon { state => '%devStateIcon' }
</pre>

Damit sich der CSS auf die richtige readingsGroup bezieht, ist es nötig
das Attribut ''style'' anzupassen.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| style="width:40%" |<code>attr <rgName> style class="block wide rgDevices"</code>
| Die Klassen ''block'' und ''wide'' müssen eingetragen werden. Der Name der nachfolgenden Klasse, hier ''rgDevices'', ist frei wählbar.
|}
===== Funktion rgLink() =====
Die Funktion rgLink($name,$action,$label) liefert einen Link mit dem Namen $label zurück. Der Code gehört in die [[99 myUtils anlegen|99_myUtils.pm]].
* $name - Name des Device das aufgerufen werden soll
* $action - Aktion die Ausgeführt werden soll.
**''konfigurieren'' erzeugt den kleinen ''Details'' Button links oben der einen zur Detail Seite der ReadingsGroup führt - nützlich wenn das ReadingsGroup-Attribut ''noheading'' gesetzt ist
** ''detail'' erzeugt einen Link zu Device-Detail Seite
* $label - Link-Name
<syntaxhighlight lang="perl">
sub rgLink($$$){
my ($name,$action,$label) = @_;
my $link = "";
my $fhemLink = "";
my $txt = "";
my $ret = "";
my $divStyle = "";
my $aStyle = "";

# FHEM Variablen einbinden
use vars qw($FW_ME);
use vars qw($FW_subdir);
use vars qw($FW_ss);
use vars qw($FW_tp);

if( $action eq "konfigurieren" ){
$fhemLink = "detail=$name";
$divStyle = "cursor:pointer;font-size:11px;padding-bottom:2px;padding-left:3px;";
}
elsif( $action eq "detail" ){
$fhemLink = "detail=$name";
$divStyle = "cursor:pointer;display:inline;";
}

$link = '<a onclick="location.href=\'' . $FW_ME . $FW_subdir . '?' . $fhemLink . '\'" style="' . $aStyle . '">' . $label . '</a>';
$txt = '<div style="' . $divStyle . '">' . $link . '</div>';
$ret = "$txt";

return $ret;
}
</syntaxhighlight>

{{Randnotiz|RNText=Tipp
Verwende zum Bearbeiten der eigenen .css Dateien entweder den [[Konfiguration#Syntaxhervorhebung|Codemirror Editor]] oder einen eigenen Editor mit [http://de.wikipedia.org/wiki/Syntaxhervorhebung Syntax Highlighting] . Das hilft bei der Fehlersuche enorm. }}

===== Styling =====
Die eigene .css Datei erscheint in FHEM unter Edit-Files --> styles und kann direkt im FHEM-Editor oder mit eigenem Editor bearbeitet werden.

ios7ReadingsGroups.css:
<pre>
/* Readings Groups Devices */
table.rgDevices tr td{ text-align: center; }
table.rgDevices tr:first-child td:nth-child(2){ /* 1. Zeile 2. Spalte */ text-align: center; }
table.rgDevices tr td:first-child{ /* 1. Spalte */ width: 45px; text-align: center; }
table.rgDevices tr td:nth-child(2){ /* 2. Spalte */ width: 33%; text-align: left; }
table.rgDevices tr td:nth-child(3){ /* 3. Spalte */ width: 15%; }
table.rgDevices tr td:nth-child(4){ /* 4. Spalte */ width: 15%; }
table.rgDevices tr td:nth-child(5){ /* 5. Spalte */ width: 15%; }
</pre>

==== Auf Portrait / Landscape Modus des Smartphone unterscheiden ====
Dieses Beispiel ist an das obige Beispiel [[#Erweiterte_Device_.C3.9Cbersicht|Erweiterte Device Übersicht]] angelehnt.

{| class="wikitable"
| style="width:40%" |[[Datei:RgStylingSmallscreenPortrait.png|300px|mini|center|Device ReadingsGroup im Portrait Modus]]
|[[Datei:RgStylingSmallscreenLandscape.png|550px|mini|center|Device ReadingsGroup im Landscape Modus]]
|}

===== Allgemeines =====
Mit CSS ist man in der Lage auf die aktuelle Bildschirmlage zu reagieren. Alle Anweisungen die in diesen beiden Funktionen zwischen den beiden { } stehen, werden je nach Bildschirmlage aufgerufen
<pre>
/* Portrait Modus */
@media all and (orientation:portrait) { }

/* Landscape Modus */
@media all and (orientation:landscape) { }
</pre>

===== Styling =====
{{Randnotiz|RNText=Info
* ''width: xx%'' ändert die Breite der Spalte
* ''display: none'' blendet die Spalte aus}}
In der FHEMWEB_phone Instanz muss wie [[#Allgemeines|hier]] beschrieben eine neue eigene .css Datei eingetragen werden. In diesem Beispiel ios7smallscreenReadingsGroups.css

ios7smallscreenReadingsGroups.css
<pre>
/* landscape und portrait modus */
table.rgDevices tr td { /* Zuerst alles centern */ text-align: center; }
table.rgDevices tr:first-child td:nth-child(1){ /* 1. Zeile 1. Spalte */ text-align: center; }
table.rgDevices tr td:first-child { /* 1. Spalte */ width: 5%; }
table.rgDevices tr:first-child td:nth-child(2) { /* 1. Zeile 2. Spalte */ text-align: center; }
table.block table tr td table.rgDevices tr td { border-bottom: 1px solid #cbcbcb; }

/* Portrait Modus */
@media all and (orientation:portrait) {
table.rgDevices tr td:nth-child(2){ /* 2. Spalte */ width: 50%; text-align: left; }
table.rgDevices tr td:nth-child(3){ /* 3. Spalte */ width: auto; text-align: right; display: table-cell; }
table.rgDevices tr td:nth-child(4){ /* 4. Spalte */ width: 0; display: none; }
table.rgDevices tr td:nth-child(5){ /* 5. Spalte */ width: 0; display: none; }
table.rgDevices tr td:nth-child(6){ width: 0; display: none; }
table.rgDevices tr td div a svg{ margin-left: 90px; }
}

/* Landscape Modus */
@media all and (orientation:landscape) {
table.rgDevices tr td:nth-child(2){ /* 2. Spalte */ width: 35%; text-align: left; }
table.rgDevices tr td:nth-child(3){ /* 3. Spalte */ width: 15%; }
table.rgDevices tr td:nth-child(4){ /* 4. Spalte */ width: 15%; }
table.rgDevices tr td:nth-child(5){ /* 5. Spalte */ width: 15%; }
table.rgDevices tr td:nth-child(5){ /* 5. Spalte */ width: 15%; }
}
</pre>

==== Plots im Portrait Modus des Smartphones ausblenden ====
{| class="wikitable"
| style="width:40%" |[[Datei:RgStylingSmallscreenPortraitPlot.png|350px|mini|center|Device ReadingsGroup im Portrait Modus]]
|[[Datei:RgStylingSmallscreenLandscapePlot.PNG|550px|mini|center|Plot nur im Landscape]]
|}

Um den Plot und alle Steuerelemente im Portrait Modus auszublenden fügt man in seine eigene smallscreen.css wie [[#Allgemeines|hier beschrieben]] folgendes ein:
<pre>
@media all and (orientation:portrait) {
.SVGplot, .SVGlabel, .Zoom-in, .Zoom-out, .Prev { width: 0; display: none; }
}
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Homebridge User Configs

2019-09-09T10:59:36Z

Justme:

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/tree/master/src/lib/gen insbesondere in HomeKit.ts.

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Erstellung eines HomebridgeMappings am Beispiel "Feuchtesensor" ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. 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:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== BRAVIA Fernseher ==
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== Homematic Luftfeuchtigkeits- und Tmeperatursensoren ==

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- HM-WDS10-TH-O
- HM-WDS40-TH-I
- HM-WDS40-TH-I-2

Achtung: Hier wird genericDeviceType "TemperatureSensor" verwendet, um eine history in EVE zu erhalten. Mit einem "HumiditySensor" funktionierte dies bei den Tests (Februar 2019) nicht.

attr <THSensor> genericDeviceType TemperatureSensor

attr <THSensor> CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
history:size=1024

== Homematic SmokeDetector HM-SEC-SD und HM-SEC-SD2 ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Homematic Wetterstation OC3 HM-WDS100-C6-O-2 ==
[[Datei: homebridge-wetter.jpg|mini|Wetterstation in EVE]]
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]
[[Kategorie:Code Snippets]]

Homebridge User Configs

2019-09-09T10:58:55Z

Justme:

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/tree/master/src/lib/gen

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Erstellung eines HomebridgeMappings am Beispiel "Feuchtesensor" ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. 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:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== BRAVIA Fernseher ==
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== Homematic Luftfeuchtigkeits- und Tmeperatursensoren ==

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- HM-WDS10-TH-O
- HM-WDS40-TH-I
- HM-WDS40-TH-I-2

Achtung: Hier wird genericDeviceType "TemperatureSensor" verwendet, um eine history in EVE zu erhalten. Mit einem "HumiditySensor" funktionierte dies bei den Tests (Februar 2019) nicht.

attr <THSensor> genericDeviceType TemperatureSensor

attr <THSensor> CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
history:size=1024

== Homematic SmokeDetector HM-SEC-SD und HM-SEC-SD2 ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Homematic Wetterstation OC3 HM-WDS100-C6-O-2 ==
[[Datei: homebridge-wetter.jpg|mini|Wetterstation in EVE]]
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]
[[Kategorie:Code Snippets]]

FHEM Connector für Amazon Alexa

2019-08-09T19:29:00Z

Justme: /* Was geht alles ? */

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf Port 3000 auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Bei Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor. Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab 14. Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.

===== 401: Authorization Required =====

Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

===== Permission denied =====

Wenn du folgende Fehlermeldungen im Alexa Logfile siehst, wurde das Verzeichnis "/opt/fhem/.ssh/" von dir bei der Arbeit mit "root" oder "sudo" mit den falschen Berechtigungen versehen:

<syntaxhighlight lang="bash" style="width:90%;">
[2019-7-25 11:59:12] sshautoconf: aborted with ssh-keygen returned error - key_save_private: Permission denied
[2019-7-25 11:59:12] *** SSH: proxy configuration failed: ssh-keygen returned error - key_save_private: Permission denied
</syntaxhighlight>

Prüfen kannst du die Berechtigungen mit folgendem Befehl auf der Shell-Konsole:

<syntaxhighlight lang="bash" style="width:90%;">
ls -l /opt/fhem/.ssh
</syntaxhighlight>

Du solltest dann folgende Ausgabe erhalten:

<syntaxhighlight lang="bash" style="width:90%;">
insgesamt 12
-rw------- 1 fhem dialout 1675 Jul 12 13:10 id_rsa
-rw-r--r-- 1 fhem dialout 391 Jul 12 13:10 id_rsa.pub
-rw-r--r-- 1 fhem dialout 884 Jul 12 13:10 known_hosts
</syntaxhighlight>

Steht in der Ausgabe nicht "fhem dialout" (dein fhem User), sondern bspw. "root root", dann bspw. mit folgendem Befehl an deinen fhem User anpassen:

<syntaxhighlight lang="bash" style="width:90%;">
chown fhem:dialout /opt/fhem/.ssh
</syntaxhighlight>

Mit dem ersten Befehl "ls -l ..." kannst du dann nochmal prüfen, ob die Berechtigungen korrekt übernommen wurden.

===== weitere Prüfungen =====

Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</Code>, oder über den Namen bei <it>currentlogfile</it> in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: hombridgeMapping On:cmdOn=<ein>,cmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus

* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading temperature geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: hombridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus:
*** homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>

**Kommandos:
***Alexa, mache <name> heller/dunkler
***Alexa, Licht heller/dunkler

* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** hombridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** hombridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** hombridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** hombridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten ==
* alexa-fhem über FHEM anhalten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

== Bug- und Wunschliste ==
* Ist beim Start keine Internetverbindung vorhanden, erfolgt kein Retry -- alexa-fhem muss restartet werden (ssh_autoconfig wertet keine temporären Fehler aus)

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Homebridge User Configs

2019-08-09T19:28:13Z

Justme:

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Erstellung eines HomebridgeMappings am Beispiel "Feuchtesensor" ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. 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:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== BRAVIA Fernseher ==
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== Homematic Luftfeuchtigkeits- und Tmeperatursensoren ==

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- HM-WDS10-TH-O
- HM-WDS40-TH-I
- HM-WDS40-TH-I-2

Achtung: Hier wird genericDeviceType "TemperatureSensor" verwendet, um eine history in EVE zu erhalten. Mit einem "HumiditySensor" funktionierte dies bei den Tests (Februar 2019) nicht.

attr <THSensor> genericDeviceType TemperatureSensor

attr <THSensor> CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
history:size=1024

== Homematic SmokeDetector HM-SEC-SD und HM-SEC-SD2 ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Homematic Wetterstation OC3 HM-WDS100-C6-O-2 ==
[[Datei: homebridge-wetter.jpg|mini|Wetterstation in EVE]]
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]
[[Kategorie:Code Snippets]]

FHEM Connector für Amazon Alexa

2019-05-05T08:43:17Z

Justme: /* Was geht alles ? */

Set magic

2019-05-03T16:18:52Z

Justme: /* Verwendungsbereich */

== Begriff ==
Der Begriff [[set magic]]<ref>{{Link2Forum|Topic=38276|LinkText=Einfache Angabe von Reading-Values in notify Commands}}</ref> steht für die besondere Schreibweise einer Funktion zum Auslesen von [[Gerätevariable|Gerätevariablen]] im Argument einiger FHEM-Befehle. Er ist im Zusammenhang mit der Entstehung dieser Schreibweise geprägt worden.

== Verwendungsbereich ==
Die Schreibweise steht seit Featurelevel 5.7 zur Verfügung.
[[set magic]] kann verwendet werden für die Befehle
* [[set]]<ref>{{Link2CmdRef|Anker=set|Lang=de}}</ref>
* [[setreading]]<ref>{{Link2CmdRef|Anker=setreading|Lang=de}}</ref>
und als Sonderfälle für
* [[attr]]<ref>{{Link2CmdRef|Anker=attr|Lang=de}}</ref> [[stateFormat]]<ref>{{Link2CmdRef|Anker=stateFormat|Lang=de}}</ref>
* [[attr]] wu_dataValues im [[Modul]] [[HP1000]]<ref>{{Link2CmdRef|Anker=HP1000|Lang=de}}</ref>
dazu zählen auch [[Modul|Module]], die Teile der Syntax verwenden
* [[readingsGroup]]<ref>{{Link2CmdRef|Anker=readingsGroup|Lang=de}}</ref> verwendet Präfix und Suffix
oder [[Modul|Module]] mit einer erweiterten Anwendung
* [[DOIF]]<ref>{{Link2CmdRef|Anker=DOIF|Lang=de}}</ref> inhaltliche und funktionale Erweiterungen, wie [[DOIF/Einsteigerleitfaden,_Grundfunktionen_und_Erl%C3%A4uterungen#Ausl.C3.B6ser|Auslöser]]
[[set magic]] vereinfacht Schreibweisen wie
{fhem("setreading <Gerätename> <Readingname> ".ReadingsNum("<Gerätename>","<Readingname>","<Defaultwert>"))}
zu
setreading <Gerätename> <Readingname> [<Gerätename>:<Readingname>:d]

== Syntax 1 ==
[<Präfix>:<Gerätename>:<Name des [[Gerätevariable]]>:<Suffix>]

Der optionale Präfix schränkt die Suche auf bestimmte [[Gerätevariable|Gerätevariablen]] ein.
* '''a''' beschränkt die Suche auf [[Attribute]]
* '''i''' beschränkt die Suche auf [[Internals]]
* '''r''' beschränkt die Suche auf [[Readings]]

Es muss ein gültiger [[Gerätename]] für ein existierendes Gerät angegeben werden.

Es muss eine existierende, nicht leere [[Gerätevariable]] angegeben werden.

Der optionale Suffix extrahiert bestimmte Werte der [[Gerätevariable|Gerätevariablen]].
* '''d''' extrahiert die erste Zahl.
* '''i''' extrahiert die erste Zahl als Ganzzahl.
* '''r'''<'''n'''> extrahiert die erste Zahl, und rundet sie auf '''n''' Dezimalstellen, ohne '''n''' auf eine Stelle.
* '''sec''' liefert die Zeit in Sekunden seit Änderung des Readings.
* '''t''' liefert den Zeitstempel des Readings

== Syntax 2 ==
{(<Perlausdruck>)}
Der [[Gerätename]] kann im Perlausdruck mit $DEV angegeben werden.

== Verwendung ==
Mit [[set magic#Syntax 1|Syntax 1]] im Gegensatz zu [[set magic#Syntax 2|Syntax 2]], ist es möglich ohne Perlkenntnis variable Inhalte zu setzen.

=== Beispiel Syntax 1: Formatieren eines Readingwertes zu einer Ganzzahl ===
In einem [[Gerät]] ''sensor'' wird der Wert des [[Readings|Reading]] ''brightness'' zu einer Ganzzahl umgewandelt und in das [[Readings|Reading]] ''brightness'' des Gerätes ''Anzeige'' geschrieben.

<code>setreading Anzeige brightness [sensor:brightness:i]</code>

=== Beispiel Syntax 2: Inkrementieren eines Readingwertes ===
In einem [[Gerät]] ''PIR'' wird das [[Readings|Reading]] ''Count'' um den Wert 1 erhöht.

<code>setreading PIR Count {(ReadingsVal("PIR","Count",0) + 1)}</code>

== Verweise ==

<references />

[[Kategorie:Glossary]]

Alexa-Fhem

2019-04-20T07:04:02Z

Justme:

{{Randnotiz|RNTyp=r|RNText='''ACHTUNG''': Diese Seite beschreibt nicht mehr exakt die jeweils nötigen Amazon Seiten. Es ist etwas Interpretation und Verständnis nötig.

Für alle, die neu einsteigen und sich mit dem FHEM Vereinsserver als Proxy anfreunden können, empfiehlt es sich hier: [[FHEM Connector für Amazon Alexa]] einzusteigen.}}

'''alexa-fhem''' ist eine in JavaScript geschriebene und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==Einführung==
===Glossar===
*Echo bzw. Echo Dot (im Folgenden maskulin bezeichnet) sind die derzeit verfügbaren Geräte des Alexa-Systems '''BILDER EINSTELLEN - Achtung Urheberrecht'''
*AVS ist der Amazon Voice Service, d.h. die Spracherkennungskomponente des Systems.{{Randnotiz|RNTyp=r|RNText=Für die Nutzung der Amazon AWS-Dienste müssen zwingend die Daten einer Kreditkarte angegeben werden. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen. Die Autoren dieser Anleitung und der darin beschriebenen Module übernehmen keine Haftung für eventuelle Kosten, die aus der Nutzung der AWS entstehen. }}
*AWS sind die Amazon Web Services, also per URL erreichbare Dienste zur Ausführung von Berechnungen etc. Im Rahmen von Alexa-Fhem wird bei AWS eine eigene JavaScript-Funktion hinterlegt, die zur Kommunikation mit dem FHEM-Server dient. Im Jargon von Amazon ist dies eine so genannte Lambda-Funktion '''WARUM ? Nachlesen bei Amazon'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht, sowie weitergehende Informationen über die Reaktion von Alexa enthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fertigkeit, Können) ist die Bezeichnung für eine per Spracherkennung zu bedienende Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, Wettervorhersage oder zur Steuerung von FHEM

===Arbeitsweise und Datenfluss===
[[Datei:2gpXyLN.jpg|200px|thumb|right|Grafische Darstellung der beteiligten Komponenten]]
Echo → AVS → AWS Lambda → alexa-fhem → AWS Lambda → AVS → Echo

*Der Echo (oder ein anderes Alexa/AVS fähiges Gerät) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung
*AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den erkannten Daten
:*Beim Alexa SmartHome Skill sind die möglichen Sätze für die Spracherkennung relativ fest vorgegeben
:*Beim Alexa Custom Skill kommen die dazu nötigen Informationen aus dem ''Interaction Model'' der Alexa Skills Configuration
*Das Event wird an den unter ''Configuration'' in der Alexa Skills Configuration hinterlegten Endpoint geschickt
:*Beim Alexa SmartHome Skill ist das zwingend eine AWS Lambda Routine
:*Beim Alexa Custom Skill kann das im Prinzip auch ein eigener Web Service sein
*Das Event wird vom <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> nimmt diese Antwort entgegen und gibt sie an AVS zurück
*AVS sogt dafür das der Echo 'antwortet' und dass die Card in der Alexa App erscheint

===Anmerkungen===
*Ein Skill hat keinen Zugriff auf die Audiodaten
*Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.
*Wenn man berücksichtigt welchen Weg die Daten insgesamt gehen, ist es erstaunlich, wie schnell die Reaktion auf einen gesprochenen Satz erfolgt.

=== Abgrenzung des '''Alexa Smart Home Skills''' und des '''Alexa Custom Skills''' ===

Der [[Alexa-Fhem#Smart_Home|Alexa Smart Home Skill]] ist ein Amazon-Alexa-Standard-Skill, der wesentliche Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.

Der [[Alexa-Fhem#Custom|Alexa Custom Skill]] ist kein Standard-Smart-Home-Skill, sondern ein individuell entwickelter Skill, so wie alle anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch werden anspruchsvollere Steuerungsmöglichkeiten nur mit diesem realisiert werden können.

==Installation==
{{Randnotiz|RNTyp=[g|Info]|RNText=Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Während der Konfiguration sollten alle nachfolgenden Abschnitte parallel in gleichzeitig geöffneten Browserfenstern durchgeführt werden, die jeweils bis zum Abschluss geöffnet bleiben müssen. }}
Grundvoraussetzung für alle folgenden Schritte ist das Vorhandensein eines Amazon-Accounts. Es wird davon ausgegangen, dass die Konten für alle im Folgenden genutzten Amazon-Dienste eingerichtet wurden.

===node.js installieren===
Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

===node.js updaten===
Um node.js aus einer vorherige Installation zu updaten (Version 4 ist deprecated und in AWS Amazon nicht mehr unterstützt):
<syntaxhighlight lang="bash" style="width:50%;">
# Zuerst alexa-fhem stoppen, dann
sudo apt-get remove nodejs
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install npm@latest -g

#--> in Amazon Konsole NodeJs auf 8.1 umstellen (Funktion in AWS Konsole editieren, im Pulldown-Menü "Runtime" eine neuere Version auswählen, und speichern)
#--> Raspi Reboot (vielleicht nicht nötig)
</syntaxhighlight>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen!

Die aktuelle Version ist jeweils {{Link2Forum|Topic=81324|Message=733986|LinkText=hier}} zu finden.
Wer bisher noch keinen Alexa-FHEM Skill angelegt hat, bitte {{Link2Forum|Topic=81324|Message=733986|LinkText=diesen Forumsbeitrag}} beachten!

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).<syntaxhighlight lang="bash" style="width:50%;">tar -xvzf dateiname.tgz</syntaxhighlight>
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <syntaxhighlight lang="bash" style="width:50%;">mv package alexa-fhem</syntaxhighlight>
# Durch <syntaxhighlight lang="bash" style="width:50%;">cd alexa-fhem</syntaxhighlight> in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
{{Randnotiz|RNTyp=[g|Info]|RNText=createKey.sh erzeugt ein Zertifikat, das 365 Tage gültig ist. Dies muss deswegen jedes Jahr erneuert werden }}
# SSL Zertifikat erzeugen durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./createKey.sh</syntaxhighlight> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei wird ggf. bei einem manuellen Start von Alexa-Fhem nicht gefunden.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis kopiert werden.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren. Bei der Fehlermeldung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<syntaxhighlight lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">move /y newkey.pem key.pem</syntaxhighlight> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<syntaxhighlight lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">
mkdir ".alexa"</syntaxhighlight>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>\.alexa\config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
===== Linux =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.
===== Windows =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version im Hauptverzeichnis von FHEM entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren.
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.

==== Alexa-Fhem konfigurieren ====
Der Inhalt der Datei ''~/.alexa/config.json'' muss an die eigene Umgebung angepasst werden.
# ''nat-pmp'' -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers, sonst die Zeile löschen!
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'', sonst die Zeile löschen!
# ''applicationId''
#:* Wenn man nur den SmartHome-Skill verwenden möchte, kann dieser Eintrag leer bleiben.
#:* Ansonsten ist er mit der SkillID des Alexa Custom Skills zu belegen, siehe Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
# ''server'' -> IP-Adresse des eigenen FHEM-Servers
# ''port'' -> Portnummer des eigenen FHEM-Servers

Beispiel a) Offenes fhem - System ohne Absicherung:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Beispiel b) Abgesichertes fhem - System mit TLS/SSL und HTTP Basic-Authentication:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"auth": {"user": "fhemuser", "pass": "fhempassword"},
"ssl": true,
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./bin/alexa</syntaxhighlight> den Dienst starten (kein sudo!)

Unter Windows startet man den Alexa-Dienst durch <syntaxhighlight lang="bash" style="width:50%;">node alexa</syntaxhighlight> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.

==== Alexa-Fhem aus FHEM heraus starten ====
Hierbei muss man zunächst herausfinden, welche der folgenden Startvarianten sein LINUX - OS zum Einsatz kommen:
initd.d oder systemd.

Auf keinen Fall darf man "sicherheitshalber" beide Varianten installieren, dies zu Fehler(-meldungen) führt.

===== Vorgehen bei init.d =====
Diese Variante kommt unter anderem auf dem Raspberry Pi mit dem OS-Varianten "Wheezy" zum Einsatz

Zunächst das Start-up-Skript aus diesem Post herunterladen {{Link2Forum|Topic=60244|Message=517271|LinkText=https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271}} und unter /etc/init.d/alexa speichern.

Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.

Nun folgende Kommandos ausführen:
<syntaxhighlight lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</syntaxhighlight>

In der Datei <code>/etc/sudoers</code> den User fhem für die Nutzung von sudo zulassen (<code>sudo nano /etc/sudoers</code>), z.B. durch Anfügen der nachfolgenden Zeile:
<code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<syntaxhighlight lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy

define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart

define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "stop")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "restart")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "status")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})</syntaxhighlight>

===== Vorgehen bei systemd =====
Diese Variante kommt unter anderem auf dem Raspberry Pi ab/seit der OS-Variante "Jessie" zum Einsatz

Bei systemd Systemen funktioniert das obengenannte vorgehen leider nicht, man kann das gleiche aber mit dem Modul
[https://forum.fhem.de/index.php/topic,79952.0.html 98_serviced.pm - systemd und initd Dienste steuern] umsetzen.
Wichtig ist das der User unter dem alexa ausgeführt wird ohne Passwort abfrage sudo ausführen darf, dazu muss er in der <code>/etc/sudoers</code> eingetragen werden, z.b. so <code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Sollte es dann nicht funktionieren kann das an einem Gruppen eintrag unterhalb der User definition in der <code>/etc/sudoers</code>, in diesem Fall den user am ende der <code>/etc/sudoers</code> eintragen, dann sollte es funktionieren

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa
WorkingDirectory=/opt/fhem/alexa-fhem
ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Den Pfad <code>/home/alexa/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo.

Im WorkingDirectory wird der alexa Dienst die Zertifikate suchen.

Achtung: Natürlich muss der Benutzer auch Zugriff sowohl auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis und das WorkingDirectory haben.

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== Alexa-Fhem testen ====
Node.Js stellt einen Web-Server am Port 3000 bereit, das oben erzeugte Zertifikat sichert diesen Zugang per SSL ab. Durch Aufruf der Adresse
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== Alexa Device anlegen ===
Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.

Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:
<syntaxhighlight lang="bash" style="width:70%;">define MyAlexa alexa</syntaxhighlight>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Amazon Developer.jpg||200px]]
# Anmeldedaten eingeben [[Datei:LogIn.jpg||200px]]

==== Security Profile anlegen ====
Die Erzeugung eines Sicherheitsprofils muss nur einmal erfolgen, es wird dann für alle weiteren Skills verwendet.
# Nach der Anmeldung Auswahl von ''APPS & SERVICES'' [[Datei:Apps1.jpg|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Security.jpg|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Newsecurity.jpg|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:SecurityName.jpg|200px]]
# Anschließend den die Daten unter ''Gneral'' merken oder Kopieren [[Datei:SecurityGenerl.jpg|200px]]
# Im Anschluß daran auf ''Web Settings'' klicken und dort auf ''Edit'' [[Datei:WebSettings.jpg|200px]]
# Und nun die im Bild gezeigten Daten eintragen [[Datei:WebSettingsDaten.jpg|200px]]
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
# Das xxx muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten SmartHome Skill anlegen bzw. Custom Skill anlegen jeweils unter Punkt 4 (Seite Configuration) bei Redirect Urls am Ende der URLs angezeigt wird
# Im anschluß daran oben auf ''Login with Amazon'' [[Datei:LoginwithAlexa.jpg|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# In der neu geladenen Seite im Dropdown Menü das vorher angelegte Profil unter ''Select a Security Profil'' auswählen und mit ''Confirm'' bestätigen [[Datei:LoginwithAlexaSelect.jpg|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]

==== Skills bearbeiten (Gilt für den SmartHome wie auch den Customer Skill)====
# Im Menü den Punkt ''ALEXA'' auswählen und anschließend im Dropdown Menü ''Alexa Skills Kit'' auswählen [[Datei:AlexaSkill.jpg|200px]]

===== SmartHome Skill anlegen =====
# Rechts ''Create Skill'' auswählen [[Datei:AlexaSkillCreate.jpg|200px]]
# Auf der folgenden Seite die folgenden Daten eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Default Language'' -> ''German''
#:* ''Choose a model to add to your skill'' -> ''SmartHome '' anklicken
#:* ''Anschließend rechts oben auf ''Create Skill'' [[Datei:AlexaSkillCreateSmart.jpg|200px]]
# Nun auf die Seite https://signin.aws.amazon.com/ wechseln und dort einloggen [[Datei:AWSAnmelden.jpg|200px]]
# Nach dem Login links oben auf ''Services'' klicken und anschließend auf ''Lambda'' [[Datei:AWSLambda.jpg|200px]]
# Auf der ''Lambda'' Seite "Funktion' auswählen links im Menü und dann rechts auf ''Funktion erstellen'' klicken [[Datei:LamdbaFunktion.jpg|200px]]
# Auf der Seite ''Funktion erstellen'' dann auf ''Ohne Vorgabe erstellen' klicken
#:* Unter ''Name'' einen Beliebigen Namen eingeben
#:* Bei ''Laufzeit'' ''Nodejs 8.10'' auswählen
#:* Unter ''Rolle'' ''Erstellen einer benutzerdefinierten Rolle'' auswählen, im anschluß daran sollte sich automatisch ein neues Fenster öffnen, in diesem alles unverändert lassen und auf ''Allow'' klicken wodurch sich das Fenster wieder schließen sollte [[Datei:IAM.jpg|200px]]
#:*Jetzt noch rechts unten auf ''Funktion erstellen klicken'' [[Datei:OhneVorgabe.jpg|200px]]

# Auf der jetzt geöffneten Seite rechts oben die ''arn'' Nummer aufschreiben/kopieren und links aus dem Menü ''Alexa Smart Home'' hinzufügen [[Datei:Arn.jpg|200px]]
# Unten auf der Seite unter ''Auslöser konfigurieren'' muss die Skill ID eingetragen werden, diese findet man im developer account unter dem Skill. [[Datei:Auslöser.jpg|200px]]
# Anschließend noch rechts unten auf ''Hinzufügen'' klicken und danach rechts oben auf ''Speichern''

# Nun auf ''Test'' (Bezeichnung im Screenshot) klicken und unten auf der Seite unter ''Funktionscode'' den vorhanden Code löschen und den Code aus der ''Lambda.js'' welche sich in dem ''alexa-fhem-0.4.4'' Paket befindet einfügen [[Datei:Arn2.jpg|200px]]
 [[Datei:Code.jpg|200px]]
# Im Code müsst ihr den ''Hostname'' anpassen, also eure DynDns z.b. einfügen, anschließen rechts oben wieder auf ''Speichern''

# Nun wieder zurück in den Alexa developer Account und hier folgende Daten eintragen
{{Randnotiz|RNTyp=r|RNText=Es funktioniert nur noch die v3 api (v2 ist deprecated). Die Version hierfür gibt es im {{Link2Forum|Topic=81324|LinkText=Forum}}. bitte die hinweise dort lesen und beachten.}}
#:* ''Payload Version'' -> ''v3(preferred)'' auswählen 
#:* ''Default endpoint'' -> Hier die ''arn'' Nummer von oben eintragen/einfügen
#:* Dann den Haken setzen bei ''Europe, India'' und nochmals die ''arn'' eintragen und anschließend rechts oben auf ''Save''
# Links im Menü ''Account Linking'' auswählen und dort folgende Daten eintragen
#:* ''Authorization URI'' -> ''https://www.amazon.com/ap/oa''
#:* ''Access Token URI'' -> ''https://api.amazon.com/auth/o2/token''
#:* ''Client ID'' -> ''Eure Client ID, fängt mit amzn......an'', zu finden unter ''https://developer.amazon.com'' -> '' Apps & Services'' -> ''Security Profiles'' -> Profil auswählen -> ''Web Settings''
#.* ''Client Secret'' -> ''Euer Client Secret'', siehe ''Client ID''
#:* ''Scope'' -> ''Add Scope'' auswählen und ''profile:user_id'' (wörtlich 1:1 eintragen) eintragen
#:* ''Redirect URLs'' -> Diese 3 Adressen merken/kopieren
# Alles andere auf dieser seite kann gleich bleiben, jetzt noch rechts oben wieder auf ''Save'' klicken [[Datei:Account.jpg|200px]]

# Anschließend wieder zurück zum ''Amazon developer Account'' https://developer.amazon.com , dort wieder das ''Security Profile'' aufrufen und die drei Links unter ''Allowed Return URLs'' (wo eingangs am Schluss 3 XXX gesetzt wurden) mit den Links von Oben ''Redirect URLs'' ersetzen
# Nun geht es weiter in der ''Amazon Alexa developer Konsole'' https://developer.amazon.com/alexa/console/ask wo oben auf ''Distribution'' geklickt werden muss.
# Hier sind alle angaben Freiwillig bzw. können Frei gewählt werden bis auf die ''Privacy Policy URL'' , diese muss eingetragen werden, anschließend links unten auf ''Save and continue'' [[Datei:German.jpg|200px]]

# Auf der kommenden Seite ''Privacy & Compliance'' entsprechend anklicken und wieder unter auf ''Save and continue''
# Unter ''Availability'' alles so lassen und wieder auf ''Save and continue''
# Nun den Alexa Service auf dem Fhem Rechner neustarten, den Skill in der Alexa App aktivieren und nach geräten suchen lassen

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) in das Feld ''TYPE'' eingetragen werden, das nach dem Anklicken von ''Add Slot Type'' erscheint. In das darunter liegende größere Textfeld kommen die möglichen Werte für diesen Slot, so wie sie aus der FHEM-Ausgabe abzulesen sind. Dann mit ''Save'' sichern. Als Custom Slot Type erscheint dann für diesen Beispiel-Slot
FHEM_article der | die | das | den
d.h., die Zeilenumbrüche bei den möglichen Werten werden als "|" dargestellt.</li>
<li>Hier muss nun ein Bruch im Arbeitsfluss durchgeführt werden, denn bei der Erstellung des Custom Skills kommt es auf die Reihenfolge der Einträge an. Deshalb zunächst diese FHEM-Ausgabe schließen, und für dasselbe FHEM-Device <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> '''<code>profile:user_id</code>''' (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
Beim Sichern dieser Seite mit ''Next'' kann es zu einer Fehlermeldung kommen, wenn man seine Skill-Definitionen mit dem einfachen SmartHome-Skill begonnen hat. Deshalb muss noch der entsprechende Trigger für die [[#AWS_Lambda-Funktion | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== Testen ====
Hat man den Custom Skill angelegt, bietet dieser auch eine komfortable Testmöglichkeit. Dazu wählt man in der Übersichtsseite ''All Skills'' den Button ''Edit'' des Alexa Custom Skill aus. Auf der nachfolgenden Seite dann links ''Test''.
Die Testseite enthält
* ein Feld ''Voice Simulator'', mit dem man die Sprachsausgabe testen kann,
* ein Feld ''Service Simulator'', mit dem die Verarbeitung von Alexa-Kommandois getestet werden kann. Hier kann man z.B. eintragen
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Siebenundzwanzig Uhr"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]

==== AWS Lambda Funktion anlegen ===={{Randnotiz|RNTyp=r|RNText=Die AWS Seiten sehen inzwischen etwas anders aus. Eine angepasste Beschreibung findet sich im {{Link2Forum|Topic=81790|Message=739211|LinkText=Forum}}. Bitte auch die Hinweise dort lesen.}}
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## Achtung, es ist möglich, dass dabei ''Alexa Smart Home'' überhaupt nicht angeboten wird. Dann bitte ganz rechts oben in der Ecke nachsehen, welche Region bzw. welches Land ausgewählt ist. Empfohlen wird, ''Ireland'' auszuwählen. Dann erscheint bei den Funktionen auch ''Alexa Smart Home''.
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung im Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 6.10 (oder 8.10).
## ''Role'' -> ''Choose an existing role''
### Achtung: wenn es noch keine existing role gibt, zuerst ''Create a custom role'' -> in dem Popup dann ''lambda_basic_execution'' auswählen und auf ''Allow'' klicken sowie bei ''Existing role'' dann ''x'' wählen.
# Auf der Code-Seite ist im großen Textfeld dann der Code aus der Datei ''lambda.js'' im Paket [[#Alexa-Fhem_installieren | Alexa-Fhem]] vollständig einzufügen. Dabei muss der vorhandene Code im Texteil komplett gelöscht, der Teil aus der ''lamda.js'' eingefügt und noch der Hostname im Quellcode an den eigenen Hostnamen angepasst werden.
# Anschließend alles mit ''Next'' bestätigen. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== Trigger für Custom Skill hinzufügen ====
Editiert man eine Lambda-Funktion, werden auf der Seite ''Triggers'' diejenigen Dienste angezeigt, die diese Funktion aufrufen.
* Hier taucht der Trigger ''Alexa Smart Home'' zusammen mit der ''Application Id'' auf, der bei der Einrichtung des SmartHome-Skills eingetragen wurde.
* Zur Verbindung mit dem Custom Skill ist es nötig, einen zweiten Trigger hinzuzufügen. Durch Anklicken von ''Add Trigger'' wird eine Auswahlseite eingeblendet. Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Skills Kit' auswählen und mit ''Next'' bestätigen

==== ARN der AWS Lambda Funktion bestimmen ====
# Auf der Übersichtsseite oben links den Menüpunkt ''Functions'' aúswählen [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== Einrichtung in der Alexa App==
Nachdem die Alexa Skills angelegt wurden, müssen diese noch in der Alexa App eingerichtet werden.
Dafür jeweils per Desktop-Browser auf [http://alexa.amazon.de alexa.amazon.de] anmelden, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.

=== Alexa Skill ===
# Auf ''Skills'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.

Tip: Es macht Sinn, unter ''Meine Gruppen'' Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.

== Einrichtung unter FHEM ==
Im Folgenden werden exemplarisch ein paar Geräte beschrieben, die man nutzbringend mit FHEM einsetzen kann.

Bei Verwendung des Custom Skills übersetzt die Kombination der Attribute ''alexaMapping'' und ''homebridgeMapping'' Sprachbefehle ("Intents") in gerätespezifische Kommandos.
* Das Attribut alexaMapping wird am Alexa-Device gesetzt und dient dazu, erkannte Sprachkommandos in abstrakte Characteristiken zu überführen. Für den einfacheren SmartHome Skill hat darum das Attribut ''alexaMapping'' keine Bedeutung, sondern nur der ''genericDeviceType'' des zu steuernden Gerätes.
* Das Attribut homebridgeMapping wird für beide Skills am zu steuernden Gerät gesetzt und übersetzt diese Charakteristiken in die konkreten Befehle, die das Gerät versteht. Der inhalt des Attributs wird von links nach rechts ausgewertet und ist wie folgt aufgebaut:
** Das Attribut enthält eine durch Leerzeichen getrennte Liste aus Konfigurationen für jeweils eine Characteristik
** Jede einzelne der Characteristik-Konfigurationen besteht aus dem Namen der Characteristik, gefolgt von "=" und einer kommaseparierten Liste von Parametern.
attr <device> homebridgeMapping <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...
** Jeder Parameter besteht entweder aus
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> kann auch an Stelle einer ganzen Characteristik-Konfiguration stehen
Weiter führende Dokumentation zum homebridgeMapping findet sich unter https://forum.fhem.de/index.php/topic,48558.0.html

=== Einfacher Schalter ===
* Ein einfacher Schalter, der die set-Kommandos ''on'' und ''off'' kennt, kann direkt mit Alexa-Fhem gekoppelt werden
* Für kompliziertere Aktionen, etwa das Übermitteln eines spezifischen Schaltbefehls an FHEM, ist die Einrichtung eines Dummies zu empfehlen.
Ob Dummy oder nicht, wichtig sind die drei fett gedruckten Zeilen
define Alexa.Party dummy
'''attr Alexa.Party alexaName party'''
'''attr Alexa.Party alexaRoom alexaroom'''
'''attr Alexa.Party genericDeviceType switch'''
attr Alexa.Party group AlexaGeräte
attr Alexa.Party room AlexaRoom
attr Alexa.Party setList on off
Selbstverständlich kann man diesen Dummy mit einem notify oder DOIF abfangen, um die gewünschte Schaltaktion auszuführen.

Ein Alternative zum Dummy ist das Anlegen eines readingsProxy, dem die entsprechenden Attribute gegeben werden.

Weil es sich hierbei um eines der einfachen Geräte handelt, die Alexa selbst im SmartHome Skill bearbeiten kann, ist auch der zweite Schritt bei der Einrichtung in der Alexa App sinnvoll: Der Schalter wird dann im Bereich Smart Home der Alexa App erkannt. Wer ihn auch mit dem Custon Skill bedienen möchte, muss natürlich Sorge tragen, dass der Alexa-Name ''party'' bei den FHEM_Devices auftaucht und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sind (siehe Abschnitt [[##Custom_Skill_anlegen | Custom Skill Anlegen]]).

=== Wecker ===
Dieses Gerät kann man nur mit dem Custom Skill bedienen, es wird also '''nicht''' im Bereich Smart Home der Alexa App auftauchen. Wir richten einen Dummy ein, wichtig sind wieder die fett gedruckten Zeilen:
define Alexa.Weckzeit dummy
'''attr Alexa.Weckzeit alexaName weckzeit'''
'''attr Alexa.Weckzeit alexaRoom alexaroom'''
attr Alexa.Weckzeit genericDeviceType clock
attr Alexa.Weckzeit group AlexaGeräte
'''attr Alexa.Weckzeit homebridgeMapping Weckzeit=state,cmd=+'''
attr Alexa.Weckzeit room AlexaRoom
'''attr Alexa.Weckzeit setList Weckzeit:time'''
Das Attribut ''genericDeviceTye'' ist nicht wichtig, weil es ein generisches Device dieser Art gar nicht gibt. Wichtig hingegen ist das Attribut ''homebridgeMapping''

Für das Gerät ''MyAlexa'', das in Abschnitt definiert wurde, muss im Attribut ''alexaMapping'' auftauchen
Weckzeit=verb=stelle,valuePrefix=für;auf,values=AMAZON.TIME,valueSuffix=uhr
Darüber hinaus muss der Alexa-Name ''weckzeit'' bei den FHEM_Devices auftauchen und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sein (siehe Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

Zur weiteren Bearbeitung kann man jetzt mit einem DOIF Statusänderungen des Dummies abfangen und durch eine kleine Helperfunktion ins "echte" FHEM weiterleiten.
define Alexa.Weckzeit.N DOIF (["Alexa.Weckzeit:.*"])({AlexaHelper("Alexa.Weckzeit","$EVENT")})
Die Helperfunktion (z.B. in 99_myUtils.pm) stellt aus der übergebenen Zeit (immer im Format dd:mm) eine sprachkompatible Nachricht $nc und einen mit den FHEM-Zeitangaben kompatiblen String $nt zusammen und reicht beide an eine Routine ''changeWakeTime'' weiter (dokumentiert in den [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks]).
sub AlexaHelper($$){
my ($name,$event)=@_;
if( $name eq "Alexa.Weckzeit" ){
my ($nc,$nt);
#-- volle Stunde----------------------------------------
if( $event =~ /(\d+):00/ ){
$nc=sprintf("%d Uhr",$1);
$nt=sprintf("%02d:00:00",$1);
#-- nicht volle Stunde---------------------------------
}elsif( $event =~ /(\d+):(\d+)/ ){
$nc=sprintf("%d Uhr %d",$1,$2);
$nt=sprintf("%02d:%02d:00",$1,$2);
}
changeWakeTime(\'GalaxyTab.EG\',\'$nc\',\'$nt\');
}
}

<hr>

=== Lichtszene ===
Eine Lichtszene wird mit dem Modul LightScene angelegt. Wir gehen davon aus, dass in der Lichtszene die beiden Szenen Alle_An und Alle_Aus, sowie mindestens eine weitere Szene (hier: Sitzgruppe) definiert wurde.
* Nachfolgend wird ein Beispiel beschrieben, wie man eine Lichtszene mit dem einfachen SmartHome Skill steuern kann. Die verwendeten Kommandos sind dann
<pre>
"Alexa, schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
"Alexa, schalte (die) Beleuchtungsitzgruppe an" -> LightScene Sitzgruppe wird ausgewählt
...
"Alexa, schalte (die) Beleuchtung aus" -> LightScene Alle_Aus wird ausgewählt
</pre>
* Künftig wird man LightScene mit dem Custom Skill eventuell direkt steuern können - allerdings hat das einen geringeren WAF, als die Steuerung über den SmartHome Skill: Der Einschaltsatz muss dann mindestens lauten
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

Im ersten Schritt wird ein Dummy für die Gesamtbeleuchtung eingerichtet:
define Alexa.Beleuchtung dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung alexaName beleuchtung'''
'''attr Alexa.Beleuchtung alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung genericDeviceType switch'''
Anschließend wird für jede vorhandene Lichtszene (außer Alle_An und Alle_Aus) ein weiterer Dummy angelegt:
define Alexa.Beleuchtung.Sitzgruppe dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung.Sitzgruppe alexaName beleuchtungsitzgruppe'''
'''attr Alexa.Beleuchtung.Sitzgruppe alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung.Sitzgruppe genericDeviceType switch'''
Die eigentliche Steuerung übernimmt dann ein DOIF
define Alexa.Beleuchtung.N DOIF
(["Alexa.Beleuchtung.Sitzgruppe:on"])
(set <devicename der Lichtszene> scene Sitzgruppe,
set Alexa.Beleuchtung off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSIF
... <weitere on-Events der anderen Szenen werden abgefangen>
DOELSEIF
(["Alexa.Beleuchtung:on"])
(set <devicename der Lichtszene> scene Alle_An,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSEIF
(["Alexa.Beleuchtung:off"])
(set <devicename der Lichtszene> scene Alle_Aus,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
Mit diesem DOIF wird ein Radiobutton simuliert, d.h. wie bei den Stationstasten vor Uralt-Radios sorgt die Auswahl einer Szene immer dafür, dass alle anderen Dummies ausgeschaltet werden.
Natürlich kann man das auch mit einem kleinen Perl-Programm erreichen.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

=== Harmony Hub ===
Ein [https://forum.fhem.de/index.php/topic,60244.msg550298.html#msg550298 HowTo-Beitrag im Forum] beschreibt die Ansteuerung von Harmony-Aktionen über den Custom Skill, beispielsweise für eine Aktion ''ARD'': „Alexa, sage FHEM stelle Anlage auf ARD“.

== Nutzung ==
Um den Namen zu bestimmen, unter dem ein Gerät mit Alexa angesprochen wird, verwendet Alexa-Fhem mit absteigender Priorität:
* das alexaName Attribut
* das alias Attribut
* das NAME Internal
Damit Alexa ein Gerät eindeutig identifizieren kann, sollten eindeutige Gerätenamen verwendet werden, bestehed möglichst aus einem Wort und ohne Ziffern. Wenn Alexa einen Namen nicht versteht, kann man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und den Gerätenamen ggf. anpassen.

=== SmartHome Skill ===
Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.

Nach erfolgreicher Einrichtung des SmartHome Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:
<pre style="width:50%;">
“alexa, schalte <gerät/gruppe> ein”
“alexa, schalte <gerät/gruppe> aus”
“alexa, stelle <gerät/gruppe> auf <wert> prozent”
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”
</pre>

=== Custom Skill ===
Der Custom Skill erlaubt im Gegensatz zum SmartHome Skill eine weitreichende Konfiguration der möglichen Kommandos. Die Dokumentation ist aktuell noch über diverse Artikel im Wiki verstreut:

*Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=hier}} beschrieben.
*Die erste Umsetzung ist {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} beschrieben.
*Mehr zu FHEM-Intents und deren Möglichkeiten gibt es {{Link2Forum|Topic=67490|Message=589378|LinkText=hier}}.
*Wie man die Alexa TTS-Engine bei den Antworten auf FHEM-Intents beeinflussen kann {{Link2Forum|Topic=77421|Message=693631|LinkText=hier}}.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions), alles hier sammeln.

== Troubleshooting ==

====Allgemeiner Hinweis====
Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein ''http://'' davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von UnityMedia z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276}}

Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können.
Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.

Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde.

Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter ''Internet -> Freigaben -> Portfreigaben'' statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.

Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: ''https://mein.hostname:3000''. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.

Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.

====Probleme mit node.js - npm install====

Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|Python, g++, MDNS installieren]], siehe auch folgenden Abschnitt.

====Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich====
Wenn man auf der Konsole angemeldet ist, den Befehl<syntaxhighlight lang="bash" style="width:50%;">node -v</syntaxhighlight>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter [[Homebridge_einrichten#NodeJS_installieren]] nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter [[Alexa-Fhem#Voraussetzungen]] erfüllt sind! Keine Experimente mit Versionen die darunter liegen.

====Fehlermeldung ''NAT-PMP failed: Error: timeout'' Fehler angezeigt beim Start von alexa-fhem====
Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: ''NAT-PMP failed: Error: timeout'', lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.

====Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder====
Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder.

Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.

====Was ist zu tun, wenn alexa-fhem keine Geräte findet?====
Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut ''genericDeviceType switch'' hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut ''alias'' eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann.
Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.

====Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?====
Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:
* wenn nichts bei alexa-fhem ankommt: port forwarding prüfen
* wenn lambda.js nichts los wird: im cloudwatch log nachsehen
* wenn bei lambda.js nichts ankommt: den trigger prüfen

Zunächst sollte man sich unter ''http://aws.amazon.com'' das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger.
Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf ''Triggers'' klicken und mit ''Add trigger'' erneut einen anlegen. Hier muss, wie in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 7, die ''Application Id'' stehen und der Haken bei ''Enable trigger'' gesetzt sein. Dann alexa-fhem neu starten.
Wenn ihr Änderungen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt. Fürs Debugging empfiehlt es sich, alexa-fhem in einer Konsole laufen zu lassen, um eingehende Anfragen mitverfolgen zu können.

Es kann sein, dass immer noch keine Log im Cloudwatch ([http://docs.aws.amazon.com/de_de/lambda/latest/dg/monitoring-functions-logs.html]) zu sehen ist. In dem Fall hilft es, eine neue Role Policy anzulegen.
* in der AWS Console [https://console.aws.amazon.com] oben links auf Services klicken, und in der Gruppe "Security, Identity & Compliance" auf IAM klicken
* links auf Roles klicken
* Auf dem Knopf "Create Role" klicken
* AWS Services > Lambda auswählen, unten auf Next:Permissions klicken
* im Filter / Policy Type, "log" eintragen (ohne quotes)
* CloudWatchLogsFullAccess hacken, auf Next:Review unten klicken
* Name vergeben und mit "Create role" bestätigen
* Oben links auf Services klicken, und in der Gruppe "Compute", auf Lambda klicken
* auf den Name der Funktion klicken
* Reiter Configuration auswählen
* in Existing Role, den neukreierten Role auswählen
* oben auf Save (und Testen wenn gewünscht) klicken.
Schon sollte eine neue Gruppe im Cloudwatch sichtbar sein. Die Suche von den Devices in Alexa wiederholen, und die Logs analysieren

====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====
{{Randnotiz|RNTyp=[g|Info]|RNText=Der User in der User= Directive von alexa.service muss Ausführungsrecht auf dem alexa binary haben (x), so wie auch mind. Lesezugriff auf dem Verzeichnis nach -U Option in der ExecStart= Directive und auch auf dem WorkingDirectory }}
Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei ''alexa'' muss ausführbar sein. Also z.B. so:
<syntaxhighlight lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</syntaxhighlight>
Sollte dies nicht der Fall sein bitte mit:
<syntaxhighlight lang="bash" style="width:70%;">chmod +x alexa</syntaxhighlight>
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

Eine lauffähige Konfiguration ist {{Link2Forum|Topic=71612|Message=668383|LinkText=hier}} zu sehen.

Ein Fehler in der Rechtekonfiguration führt in der Regel zu folgendem Ergebnis nach <code>sudo systemctl status alexa</code>:

<syntaxhighlight lang="bash"> Loaded: loaded (/etc/systemd/system/alexa.service; enabled)
Active: activating (auto-restart) (Result: exit-code) since mer. 2017-09-06 02:33:23 CEST; 3s ago
Process: 18332 ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa (code=exited, status=217/USER)
Main PID: 18332 (code=exited, status=217/USER)</syntaxhighlight>

====Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?====

Hierzu muss die Datei <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Alexa-Fhem

2019-04-20T07:02:50Z

Justme: hinweis auf fhem connector

'''ACHTUNG''': Diese Seite beschreibt nicht mehr exakt die jeweils nötigen Amazon Seiten. Es ist etwas Interpretation und Verständnis nötig.

Für alle, die neu einsteigen und sich mit dem FHEM Vereinsserver als Proxy anfreunden können, empfiehlt es sich hier: [[FHEM Connector für Amazon Alexa]] einzusteigen.

'''alexa-fhem''' ist eine in JavaScript geschriebene und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==Einführung==
===Glossar===
*Echo bzw. Echo Dot (im Folgenden maskulin bezeichnet) sind die derzeit verfügbaren Geräte des Alexa-Systems '''BILDER EINSTELLEN - Achtung Urheberrecht'''
*AVS ist der Amazon Voice Service, d.h. die Spracherkennungskomponente des Systems.{{Randnotiz|RNTyp=r|RNText=Für die Nutzung der Amazon AWS-Dienste müssen zwingend die Daten einer Kreditkarte angegeben werden. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen. Die Autoren dieser Anleitung und der darin beschriebenen Module übernehmen keine Haftung für eventuelle Kosten, die aus der Nutzung der AWS entstehen. }}
*AWS sind die Amazon Web Services, also per URL erreichbare Dienste zur Ausführung von Berechnungen etc. Im Rahmen von Alexa-Fhem wird bei AWS eine eigene JavaScript-Funktion hinterlegt, die zur Kommunikation mit dem FHEM-Server dient. Im Jargon von Amazon ist dies eine so genannte Lambda-Funktion '''WARUM ? Nachlesen bei Amazon'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht, sowie weitergehende Informationen über die Reaktion von Alexa enthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fertigkeit, Können) ist die Bezeichnung für eine per Spracherkennung zu bedienende Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, Wettervorhersage oder zur Steuerung von FHEM

===Arbeitsweise und Datenfluss===
[[Datei:2gpXyLN.jpg|200px|thumb|right|Grafische Darstellung der beteiligten Komponenten]]
Echo → AVS → AWS Lambda → alexa-fhem → AWS Lambda → AVS → Echo

*Der Echo (oder ein anderes Alexa/AVS fähiges Gerät) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung
*AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den erkannten Daten
:*Beim Alexa SmartHome Skill sind die möglichen Sätze für die Spracherkennung relativ fest vorgegeben
:*Beim Alexa Custom Skill kommen die dazu nötigen Informationen aus dem ''Interaction Model'' der Alexa Skills Configuration
*Das Event wird an den unter ''Configuration'' in der Alexa Skills Configuration hinterlegten Endpoint geschickt
:*Beim Alexa SmartHome Skill ist das zwingend eine AWS Lambda Routine
:*Beim Alexa Custom Skill kann das im Prinzip auch ein eigener Web Service sein
*Das Event wird vom <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> nimmt diese Antwort entgegen und gibt sie an AVS zurück
*AVS sogt dafür das der Echo 'antwortet' und dass die Card in der Alexa App erscheint

===Anmerkungen===
*Ein Skill hat keinen Zugriff auf die Audiodaten
*Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.
*Wenn man berücksichtigt welchen Weg die Daten insgesamt gehen, ist es erstaunlich, wie schnell die Reaktion auf einen gesprochenen Satz erfolgt.

=== Abgrenzung des '''Alexa Smart Home Skills''' und des '''Alexa Custom Skills''' ===

Der [[Alexa-Fhem#Smart_Home|Alexa Smart Home Skill]] ist ein Amazon-Alexa-Standard-Skill, der wesentliche Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.

Der [[Alexa-Fhem#Custom|Alexa Custom Skill]] ist kein Standard-Smart-Home-Skill, sondern ein individuell entwickelter Skill, so wie alle anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch werden anspruchsvollere Steuerungsmöglichkeiten nur mit diesem realisiert werden können.

==Installation==
{{Randnotiz|RNTyp=[g|Info]|RNText=Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Während der Konfiguration sollten alle nachfolgenden Abschnitte parallel in gleichzeitig geöffneten Browserfenstern durchgeführt werden, die jeweils bis zum Abschluss geöffnet bleiben müssen. }}
Grundvoraussetzung für alle folgenden Schritte ist das Vorhandensein eines Amazon-Accounts. Es wird davon ausgegangen, dass die Konten für alle im Folgenden genutzten Amazon-Dienste eingerichtet wurden.

===node.js installieren===
Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

===node.js updaten===
Um node.js aus einer vorherige Installation zu updaten (Version 4 ist deprecated und in AWS Amazon nicht mehr unterstützt):
<syntaxhighlight lang="bash" style="width:50%;">
# Zuerst alexa-fhem stoppen, dann
sudo apt-get remove nodejs
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install npm@latest -g

#--> in Amazon Konsole NodeJs auf 8.1 umstellen (Funktion in AWS Konsole editieren, im Pulldown-Menü "Runtime" eine neuere Version auswählen, und speichern)
#--> Raspi Reboot (vielleicht nicht nötig)
</syntaxhighlight>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen!

Die aktuelle Version ist jeweils {{Link2Forum|Topic=81324|Message=733986|LinkText=hier}} zu finden.
Wer bisher noch keinen Alexa-FHEM Skill angelegt hat, bitte {{Link2Forum|Topic=81324|Message=733986|LinkText=diesen Forumsbeitrag}} beachten!

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).<syntaxhighlight lang="bash" style="width:50%;">tar -xvzf dateiname.tgz</syntaxhighlight>
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <syntaxhighlight lang="bash" style="width:50%;">mv package alexa-fhem</syntaxhighlight>
# Durch <syntaxhighlight lang="bash" style="width:50%;">cd alexa-fhem</syntaxhighlight> in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
{{Randnotiz|RNTyp=[g|Info]|RNText=createKey.sh erzeugt ein Zertifikat, das 365 Tage gültig ist. Dies muss deswegen jedes Jahr erneuert werden }}
# SSL Zertifikat erzeugen durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./createKey.sh</syntaxhighlight> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei wird ggf. bei einem manuellen Start von Alexa-Fhem nicht gefunden.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis kopiert werden.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren. Bei der Fehlermeldung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<syntaxhighlight lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">move /y newkey.pem key.pem</syntaxhighlight> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<syntaxhighlight lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">
mkdir ".alexa"</syntaxhighlight>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>\.alexa\config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
===== Linux =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.
===== Windows =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version im Hauptverzeichnis von FHEM entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren.
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.

==== Alexa-Fhem konfigurieren ====
Der Inhalt der Datei ''~/.alexa/config.json'' muss an die eigene Umgebung angepasst werden.
# ''nat-pmp'' -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers, sonst die Zeile löschen!
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'', sonst die Zeile löschen!
# ''applicationId''
#:* Wenn man nur den SmartHome-Skill verwenden möchte, kann dieser Eintrag leer bleiben.
#:* Ansonsten ist er mit der SkillID des Alexa Custom Skills zu belegen, siehe Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
# ''server'' -> IP-Adresse des eigenen FHEM-Servers
# ''port'' -> Portnummer des eigenen FHEM-Servers

Beispiel a) Offenes fhem - System ohne Absicherung:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Beispiel b) Abgesichertes fhem - System mit TLS/SSL und HTTP Basic-Authentication:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"auth": {"user": "fhemuser", "pass": "fhempassword"},
"ssl": true,
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./bin/alexa</syntaxhighlight> den Dienst starten (kein sudo!)

Unter Windows startet man den Alexa-Dienst durch <syntaxhighlight lang="bash" style="width:50%;">node alexa</syntaxhighlight> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.

==== Alexa-Fhem aus FHEM heraus starten ====
Hierbei muss man zunächst herausfinden, welche der folgenden Startvarianten sein LINUX - OS zum Einsatz kommen:
initd.d oder systemd.

Auf keinen Fall darf man "sicherheitshalber" beide Varianten installieren, dies zu Fehler(-meldungen) führt.

===== Vorgehen bei init.d =====
Diese Variante kommt unter anderem auf dem Raspberry Pi mit dem OS-Varianten "Wheezy" zum Einsatz

Zunächst das Start-up-Skript aus diesem Post herunterladen {{Link2Forum|Topic=60244|Message=517271|LinkText=https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271}} und unter /etc/init.d/alexa speichern.

Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.

Nun folgende Kommandos ausführen:
<syntaxhighlight lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</syntaxhighlight>

In der Datei <code>/etc/sudoers</code> den User fhem für die Nutzung von sudo zulassen (<code>sudo nano /etc/sudoers</code>), z.B. durch Anfügen der nachfolgenden Zeile:
<code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<syntaxhighlight lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy

define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart

define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "stop")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "restart")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "status")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})</syntaxhighlight>

===== Vorgehen bei systemd =====
Diese Variante kommt unter anderem auf dem Raspberry Pi ab/seit der OS-Variante "Jessie" zum Einsatz

Bei systemd Systemen funktioniert das obengenannte vorgehen leider nicht, man kann das gleiche aber mit dem Modul
[https://forum.fhem.de/index.php/topic,79952.0.html 98_serviced.pm - systemd und initd Dienste steuern] umsetzen.
Wichtig ist das der User unter dem alexa ausgeführt wird ohne Passwort abfrage sudo ausführen darf, dazu muss er in der <code>/etc/sudoers</code> eingetragen werden, z.b. so <code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Sollte es dann nicht funktionieren kann das an einem Gruppen eintrag unterhalb der User definition in der <code>/etc/sudoers</code>, in diesem Fall den user am ende der <code>/etc/sudoers</code> eintragen, dann sollte es funktionieren

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa
WorkingDirectory=/opt/fhem/alexa-fhem
ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Den Pfad <code>/home/alexa/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo.

Im WorkingDirectory wird der alexa Dienst die Zertifikate suchen.

Achtung: Natürlich muss der Benutzer auch Zugriff sowohl auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis und das WorkingDirectory haben.

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== Alexa-Fhem testen ====
Node.Js stellt einen Web-Server am Port 3000 bereit, das oben erzeugte Zertifikat sichert diesen Zugang per SSL ab. Durch Aufruf der Adresse
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== Alexa Device anlegen ===
Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.

Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:
<syntaxhighlight lang="bash" style="width:70%;">define MyAlexa alexa</syntaxhighlight>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Amazon Developer.jpg||200px]]
# Anmeldedaten eingeben [[Datei:LogIn.jpg||200px]]

==== Security Profile anlegen ====
Die Erzeugung eines Sicherheitsprofils muss nur einmal erfolgen, es wird dann für alle weiteren Skills verwendet.
# Nach der Anmeldung Auswahl von ''APPS & SERVICES'' [[Datei:Apps1.jpg|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Security.jpg|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Newsecurity.jpg|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:SecurityName.jpg|200px]]
# Anschließend den die Daten unter ''Gneral'' merken oder Kopieren [[Datei:SecurityGenerl.jpg|200px]]
# Im Anschluß daran auf ''Web Settings'' klicken und dort auf ''Edit'' [[Datei:WebSettings.jpg|200px]]
# Und nun die im Bild gezeigten Daten eintragen [[Datei:WebSettingsDaten.jpg|200px]]
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
# Das xxx muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten SmartHome Skill anlegen bzw. Custom Skill anlegen jeweils unter Punkt 4 (Seite Configuration) bei Redirect Urls am Ende der URLs angezeigt wird
# Im anschluß daran oben auf ''Login with Amazon'' [[Datei:LoginwithAlexa.jpg|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# In der neu geladenen Seite im Dropdown Menü das vorher angelegte Profil unter ''Select a Security Profil'' auswählen und mit ''Confirm'' bestätigen [[Datei:LoginwithAlexaSelect.jpg|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]

==== Skills bearbeiten (Gilt für den SmartHome wie auch den Customer Skill)====
# Im Menü den Punkt ''ALEXA'' auswählen und anschließend im Dropdown Menü ''Alexa Skills Kit'' auswählen [[Datei:AlexaSkill.jpg|200px]]

===== SmartHome Skill anlegen =====
# Rechts ''Create Skill'' auswählen [[Datei:AlexaSkillCreate.jpg|200px]]
# Auf der folgenden Seite die folgenden Daten eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Default Language'' -> ''German''
#:* ''Choose a model to add to your skill'' -> ''SmartHome '' anklicken
#:* ''Anschließend rechts oben auf ''Create Skill'' [[Datei:AlexaSkillCreateSmart.jpg|200px]]
# Nun auf die Seite https://signin.aws.amazon.com/ wechseln und dort einloggen [[Datei:AWSAnmelden.jpg|200px]]
# Nach dem Login links oben auf ''Services'' klicken und anschließend auf ''Lambda'' [[Datei:AWSLambda.jpg|200px]]
# Auf der ''Lambda'' Seite "Funktion' auswählen links im Menü und dann rechts auf ''Funktion erstellen'' klicken [[Datei:LamdbaFunktion.jpg|200px]]
# Auf der Seite ''Funktion erstellen'' dann auf ''Ohne Vorgabe erstellen' klicken
#:* Unter ''Name'' einen Beliebigen Namen eingeben
#:* Bei ''Laufzeit'' ''Nodejs 8.10'' auswählen
#:* Unter ''Rolle'' ''Erstellen einer benutzerdefinierten Rolle'' auswählen, im anschluß daran sollte sich automatisch ein neues Fenster öffnen, in diesem alles unverändert lassen und auf ''Allow'' klicken wodurch sich das Fenster wieder schließen sollte [[Datei:IAM.jpg|200px]]
#:*Jetzt noch rechts unten auf ''Funktion erstellen klicken'' [[Datei:OhneVorgabe.jpg|200px]]

# Auf der jetzt geöffneten Seite rechts oben die ''arn'' Nummer aufschreiben/kopieren und links aus dem Menü ''Alexa Smart Home'' hinzufügen [[Datei:Arn.jpg|200px]]
# Unten auf der Seite unter ''Auslöser konfigurieren'' muss die Skill ID eingetragen werden, diese findet man im developer account unter dem Skill. [[Datei:Auslöser.jpg|200px]]
# Anschließend noch rechts unten auf ''Hinzufügen'' klicken und danach rechts oben auf ''Speichern''

# Nun auf ''Test'' (Bezeichnung im Screenshot) klicken und unten auf der Seite unter ''Funktionscode'' den vorhanden Code löschen und den Code aus der ''Lambda.js'' welche sich in dem ''alexa-fhem-0.4.4'' Paket befindet einfügen [[Datei:Arn2.jpg|200px]]
 [[Datei:Code.jpg|200px]]
# Im Code müsst ihr den ''Hostname'' anpassen, also eure DynDns z.b. einfügen, anschließen rechts oben wieder auf ''Speichern''

# Nun wieder zurück in den Alexa developer Account und hier folgende Daten eintragen
{{Randnotiz|RNTyp=r|RNText=Es funktioniert nur noch die v3 api (v2 ist deprecated). Die Version hierfür gibt es im {{Link2Forum|Topic=81324|LinkText=Forum}}. bitte die hinweise dort lesen und beachten.}}
#:* ''Payload Version'' -> ''v3(preferred)'' auswählen 
#:* ''Default endpoint'' -> Hier die ''arn'' Nummer von oben eintragen/einfügen
#:* Dann den Haken setzen bei ''Europe, India'' und nochmals die ''arn'' eintragen und anschließend rechts oben auf ''Save''
# Links im Menü ''Account Linking'' auswählen und dort folgende Daten eintragen
#:* ''Authorization URI'' -> ''https://www.amazon.com/ap/oa''
#:* ''Access Token URI'' -> ''https://api.amazon.com/auth/o2/token''
#:* ''Client ID'' -> ''Eure Client ID, fängt mit amzn......an'', zu finden unter ''https://developer.amazon.com'' -> '' Apps & Services'' -> ''Security Profiles'' -> Profil auswählen -> ''Web Settings''
#.* ''Client Secret'' -> ''Euer Client Secret'', siehe ''Client ID''
#:* ''Scope'' -> ''Add Scope'' auswählen und ''profile:user_id'' (wörtlich 1:1 eintragen) eintragen
#:* ''Redirect URLs'' -> Diese 3 Adressen merken/kopieren
# Alles andere auf dieser seite kann gleich bleiben, jetzt noch rechts oben wieder auf ''Save'' klicken [[Datei:Account.jpg|200px]]

# Anschließend wieder zurück zum ''Amazon developer Account'' https://developer.amazon.com , dort wieder das ''Security Profile'' aufrufen und die drei Links unter ''Allowed Return URLs'' (wo eingangs am Schluss 3 XXX gesetzt wurden) mit den Links von Oben ''Redirect URLs'' ersetzen
# Nun geht es weiter in der ''Amazon Alexa developer Konsole'' https://developer.amazon.com/alexa/console/ask wo oben auf ''Distribution'' geklickt werden muss.
# Hier sind alle angaben Freiwillig bzw. können Frei gewählt werden bis auf die ''Privacy Policy URL'' , diese muss eingetragen werden, anschließend links unten auf ''Save and continue'' [[Datei:German.jpg|200px]]

# Auf der kommenden Seite ''Privacy & Compliance'' entsprechend anklicken und wieder unter auf ''Save and continue''
# Unter ''Availability'' alles so lassen und wieder auf ''Save and continue''
# Nun den Alexa Service auf dem Fhem Rechner neustarten, den Skill in der Alexa App aktivieren und nach geräten suchen lassen

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) in das Feld ''TYPE'' eingetragen werden, das nach dem Anklicken von ''Add Slot Type'' erscheint. In das darunter liegende größere Textfeld kommen die möglichen Werte für diesen Slot, so wie sie aus der FHEM-Ausgabe abzulesen sind. Dann mit ''Save'' sichern. Als Custom Slot Type erscheint dann für diesen Beispiel-Slot
FHEM_article der | die | das | den
d.h., die Zeilenumbrüche bei den möglichen Werten werden als "|" dargestellt.</li>
<li>Hier muss nun ein Bruch im Arbeitsfluss durchgeführt werden, denn bei der Erstellung des Custom Skills kommt es auf die Reihenfolge der Einträge an. Deshalb zunächst diese FHEM-Ausgabe schließen, und für dasselbe FHEM-Device <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> '''<code>profile:user_id</code>''' (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
Beim Sichern dieser Seite mit ''Next'' kann es zu einer Fehlermeldung kommen, wenn man seine Skill-Definitionen mit dem einfachen SmartHome-Skill begonnen hat. Deshalb muss noch der entsprechende Trigger für die [[#AWS_Lambda-Funktion | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== Testen ====
Hat man den Custom Skill angelegt, bietet dieser auch eine komfortable Testmöglichkeit. Dazu wählt man in der Übersichtsseite ''All Skills'' den Button ''Edit'' des Alexa Custom Skill aus. Auf der nachfolgenden Seite dann links ''Test''.
Die Testseite enthält
* ein Feld ''Voice Simulator'', mit dem man die Sprachsausgabe testen kann,
* ein Feld ''Service Simulator'', mit dem die Verarbeitung von Alexa-Kommandois getestet werden kann. Hier kann man z.B. eintragen
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Siebenundzwanzig Uhr"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]

==== AWS Lambda Funktion anlegen ===={{Randnotiz|RNTyp=r|RNText=Die AWS Seiten sehen inzwischen etwas anders aus. Eine angepasste Beschreibung findet sich im {{Link2Forum|Topic=81790|Message=739211|LinkText=Forum}}. Bitte auch die Hinweise dort lesen.}}
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## Achtung, es ist möglich, dass dabei ''Alexa Smart Home'' überhaupt nicht angeboten wird. Dann bitte ganz rechts oben in der Ecke nachsehen, welche Region bzw. welches Land ausgewählt ist. Empfohlen wird, ''Ireland'' auszuwählen. Dann erscheint bei den Funktionen auch ''Alexa Smart Home''.
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung im Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 6.10 (oder 8.10).
## ''Role'' -> ''Choose an existing role''
### Achtung: wenn es noch keine existing role gibt, zuerst ''Create a custom role'' -> in dem Popup dann ''lambda_basic_execution'' auswählen und auf ''Allow'' klicken sowie bei ''Existing role'' dann ''x'' wählen.
# Auf der Code-Seite ist im großen Textfeld dann der Code aus der Datei ''lambda.js'' im Paket [[#Alexa-Fhem_installieren | Alexa-Fhem]] vollständig einzufügen. Dabei muss der vorhandene Code im Texteil komplett gelöscht, der Teil aus der ''lamda.js'' eingefügt und noch der Hostname im Quellcode an den eigenen Hostnamen angepasst werden.
# Anschließend alles mit ''Next'' bestätigen. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== Trigger für Custom Skill hinzufügen ====
Editiert man eine Lambda-Funktion, werden auf der Seite ''Triggers'' diejenigen Dienste angezeigt, die diese Funktion aufrufen.
* Hier taucht der Trigger ''Alexa Smart Home'' zusammen mit der ''Application Id'' auf, der bei der Einrichtung des SmartHome-Skills eingetragen wurde.
* Zur Verbindung mit dem Custom Skill ist es nötig, einen zweiten Trigger hinzuzufügen. Durch Anklicken von ''Add Trigger'' wird eine Auswahlseite eingeblendet. Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Skills Kit' auswählen und mit ''Next'' bestätigen

==== ARN der AWS Lambda Funktion bestimmen ====
# Auf der Übersichtsseite oben links den Menüpunkt ''Functions'' aúswählen [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== Einrichtung in der Alexa App==
Nachdem die Alexa Skills angelegt wurden, müssen diese noch in der Alexa App eingerichtet werden.
Dafür jeweils per Desktop-Browser auf [http://alexa.amazon.de alexa.amazon.de] anmelden, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.

=== Alexa Skill ===
# Auf ''Skills'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.

Tip: Es macht Sinn, unter ''Meine Gruppen'' Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.

== Einrichtung unter FHEM ==
Im Folgenden werden exemplarisch ein paar Geräte beschrieben, die man nutzbringend mit FHEM einsetzen kann.

Bei Verwendung des Custom Skills übersetzt die Kombination der Attribute ''alexaMapping'' und ''homebridgeMapping'' Sprachbefehle ("Intents") in gerätespezifische Kommandos.
* Das Attribut alexaMapping wird am Alexa-Device gesetzt und dient dazu, erkannte Sprachkommandos in abstrakte Characteristiken zu überführen. Für den einfacheren SmartHome Skill hat darum das Attribut ''alexaMapping'' keine Bedeutung, sondern nur der ''genericDeviceType'' des zu steuernden Gerätes.
* Das Attribut homebridgeMapping wird für beide Skills am zu steuernden Gerät gesetzt und übersetzt diese Charakteristiken in die konkreten Befehle, die das Gerät versteht. Der inhalt des Attributs wird von links nach rechts ausgewertet und ist wie folgt aufgebaut:
** Das Attribut enthält eine durch Leerzeichen getrennte Liste aus Konfigurationen für jeweils eine Characteristik
** Jede einzelne der Characteristik-Konfigurationen besteht aus dem Namen der Characteristik, gefolgt von "=" und einer kommaseparierten Liste von Parametern.
attr <device> homebridgeMapping <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...
** Jeder Parameter besteht entweder aus
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> kann auch an Stelle einer ganzen Characteristik-Konfiguration stehen
Weiter führende Dokumentation zum homebridgeMapping findet sich unter https://forum.fhem.de/index.php/topic,48558.0.html

=== Einfacher Schalter ===
* Ein einfacher Schalter, der die set-Kommandos ''on'' und ''off'' kennt, kann direkt mit Alexa-Fhem gekoppelt werden
* Für kompliziertere Aktionen, etwa das Übermitteln eines spezifischen Schaltbefehls an FHEM, ist die Einrichtung eines Dummies zu empfehlen.
Ob Dummy oder nicht, wichtig sind die drei fett gedruckten Zeilen
define Alexa.Party dummy
'''attr Alexa.Party alexaName party'''
'''attr Alexa.Party alexaRoom alexaroom'''
'''attr Alexa.Party genericDeviceType switch'''
attr Alexa.Party group AlexaGeräte
attr Alexa.Party room AlexaRoom
attr Alexa.Party setList on off
Selbstverständlich kann man diesen Dummy mit einem notify oder DOIF abfangen, um die gewünschte Schaltaktion auszuführen.

Ein Alternative zum Dummy ist das Anlegen eines readingsProxy, dem die entsprechenden Attribute gegeben werden.

Weil es sich hierbei um eines der einfachen Geräte handelt, die Alexa selbst im SmartHome Skill bearbeiten kann, ist auch der zweite Schritt bei der Einrichtung in der Alexa App sinnvoll: Der Schalter wird dann im Bereich Smart Home der Alexa App erkannt. Wer ihn auch mit dem Custon Skill bedienen möchte, muss natürlich Sorge tragen, dass der Alexa-Name ''party'' bei den FHEM_Devices auftaucht und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sind (siehe Abschnitt [[##Custom_Skill_anlegen | Custom Skill Anlegen]]).

=== Wecker ===
Dieses Gerät kann man nur mit dem Custom Skill bedienen, es wird also '''nicht''' im Bereich Smart Home der Alexa App auftauchen. Wir richten einen Dummy ein, wichtig sind wieder die fett gedruckten Zeilen:
define Alexa.Weckzeit dummy
'''attr Alexa.Weckzeit alexaName weckzeit'''
'''attr Alexa.Weckzeit alexaRoom alexaroom'''
attr Alexa.Weckzeit genericDeviceType clock
attr Alexa.Weckzeit group AlexaGeräte
'''attr Alexa.Weckzeit homebridgeMapping Weckzeit=state,cmd=+'''
attr Alexa.Weckzeit room AlexaRoom
'''attr Alexa.Weckzeit setList Weckzeit:time'''
Das Attribut ''genericDeviceTye'' ist nicht wichtig, weil es ein generisches Device dieser Art gar nicht gibt. Wichtig hingegen ist das Attribut ''homebridgeMapping''

Für das Gerät ''MyAlexa'', das in Abschnitt definiert wurde, muss im Attribut ''alexaMapping'' auftauchen
Weckzeit=verb=stelle,valuePrefix=für;auf,values=AMAZON.TIME,valueSuffix=uhr
Darüber hinaus muss der Alexa-Name ''weckzeit'' bei den FHEM_Devices auftauchen und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sein (siehe Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

Zur weiteren Bearbeitung kann man jetzt mit einem DOIF Statusänderungen des Dummies abfangen und durch eine kleine Helperfunktion ins "echte" FHEM weiterleiten.
define Alexa.Weckzeit.N DOIF (["Alexa.Weckzeit:.*"])({AlexaHelper("Alexa.Weckzeit","$EVENT")})
Die Helperfunktion (z.B. in 99_myUtils.pm) stellt aus der übergebenen Zeit (immer im Format dd:mm) eine sprachkompatible Nachricht $nc und einen mit den FHEM-Zeitangaben kompatiblen String $nt zusammen und reicht beide an eine Routine ''changeWakeTime'' weiter (dokumentiert in den [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks]).
sub AlexaHelper($$){
my ($name,$event)=@_;
if( $name eq "Alexa.Weckzeit" ){
my ($nc,$nt);
#-- volle Stunde----------------------------------------
if( $event =~ /(\d+):00/ ){
$nc=sprintf("%d Uhr",$1);
$nt=sprintf("%02d:00:00",$1);
#-- nicht volle Stunde---------------------------------
}elsif( $event =~ /(\d+):(\d+)/ ){
$nc=sprintf("%d Uhr %d",$1,$2);
$nt=sprintf("%02d:%02d:00",$1,$2);
}
changeWakeTime(\'GalaxyTab.EG\',\'$nc\',\'$nt\');
}
}

<hr>

=== Lichtszene ===
Eine Lichtszene wird mit dem Modul LightScene angelegt. Wir gehen davon aus, dass in der Lichtszene die beiden Szenen Alle_An und Alle_Aus, sowie mindestens eine weitere Szene (hier: Sitzgruppe) definiert wurde.
* Nachfolgend wird ein Beispiel beschrieben, wie man eine Lichtszene mit dem einfachen SmartHome Skill steuern kann. Die verwendeten Kommandos sind dann
<pre>
"Alexa, schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
"Alexa, schalte (die) Beleuchtungsitzgruppe an" -> LightScene Sitzgruppe wird ausgewählt
...
"Alexa, schalte (die) Beleuchtung aus" -> LightScene Alle_Aus wird ausgewählt
</pre>
* Künftig wird man LightScene mit dem Custom Skill eventuell direkt steuern können - allerdings hat das einen geringeren WAF, als die Steuerung über den SmartHome Skill: Der Einschaltsatz muss dann mindestens lauten
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

Im ersten Schritt wird ein Dummy für die Gesamtbeleuchtung eingerichtet:
define Alexa.Beleuchtung dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung alexaName beleuchtung'''
'''attr Alexa.Beleuchtung alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung genericDeviceType switch'''
Anschließend wird für jede vorhandene Lichtszene (außer Alle_An und Alle_Aus) ein weiterer Dummy angelegt:
define Alexa.Beleuchtung.Sitzgruppe dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung.Sitzgruppe alexaName beleuchtungsitzgruppe'''
'''attr Alexa.Beleuchtung.Sitzgruppe alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung.Sitzgruppe genericDeviceType switch'''
Die eigentliche Steuerung übernimmt dann ein DOIF
define Alexa.Beleuchtung.N DOIF
(["Alexa.Beleuchtung.Sitzgruppe:on"])
(set <devicename der Lichtszene> scene Sitzgruppe,
set Alexa.Beleuchtung off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSIF
... <weitere on-Events der anderen Szenen werden abgefangen>
DOELSEIF
(["Alexa.Beleuchtung:on"])
(set <devicename der Lichtszene> scene Alle_An,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSEIF
(["Alexa.Beleuchtung:off"])
(set <devicename der Lichtszene> scene Alle_Aus,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
Mit diesem DOIF wird ein Radiobutton simuliert, d.h. wie bei den Stationstasten vor Uralt-Radios sorgt die Auswahl einer Szene immer dafür, dass alle anderen Dummies ausgeschaltet werden.
Natürlich kann man das auch mit einem kleinen Perl-Programm erreichen.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

=== Harmony Hub ===
Ein [https://forum.fhem.de/index.php/topic,60244.msg550298.html#msg550298 HowTo-Beitrag im Forum] beschreibt die Ansteuerung von Harmony-Aktionen über den Custom Skill, beispielsweise für eine Aktion ''ARD'': „Alexa, sage FHEM stelle Anlage auf ARD“.

== Nutzung ==
Um den Namen zu bestimmen, unter dem ein Gerät mit Alexa angesprochen wird, verwendet Alexa-Fhem mit absteigender Priorität:
* das alexaName Attribut
* das alias Attribut
* das NAME Internal
Damit Alexa ein Gerät eindeutig identifizieren kann, sollten eindeutige Gerätenamen verwendet werden, bestehed möglichst aus einem Wort und ohne Ziffern. Wenn Alexa einen Namen nicht versteht, kann man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und den Gerätenamen ggf. anpassen.

=== SmartHome Skill ===
Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.

Nach erfolgreicher Einrichtung des SmartHome Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:
<pre style="width:50%;">
“alexa, schalte <gerät/gruppe> ein”
“alexa, schalte <gerät/gruppe> aus”
“alexa, stelle <gerät/gruppe> auf <wert> prozent”
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”
</pre>

=== Custom Skill ===
Der Custom Skill erlaubt im Gegensatz zum SmartHome Skill eine weitreichende Konfiguration der möglichen Kommandos. Die Dokumentation ist aktuell noch über diverse Artikel im Wiki verstreut:

*Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=hier}} beschrieben.
*Die erste Umsetzung ist {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} beschrieben.
*Mehr zu FHEM-Intents und deren Möglichkeiten gibt es {{Link2Forum|Topic=67490|Message=589378|LinkText=hier}}.
*Wie man die Alexa TTS-Engine bei den Antworten auf FHEM-Intents beeinflussen kann {{Link2Forum|Topic=77421|Message=693631|LinkText=hier}}.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions), alles hier sammeln.

== Troubleshooting ==

====Allgemeiner Hinweis====
Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein ''http://'' davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von UnityMedia z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276}}

Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können.
Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.

Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde.

Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter ''Internet -> Freigaben -> Portfreigaben'' statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.

Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: ''https://mein.hostname:3000''. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.

Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.

====Probleme mit node.js - npm install====

Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|Python, g++, MDNS installieren]], siehe auch folgenden Abschnitt.

====Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich====
Wenn man auf der Konsole angemeldet ist, den Befehl<syntaxhighlight lang="bash" style="width:50%;">node -v</syntaxhighlight>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter [[Homebridge_einrichten#NodeJS_installieren]] nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter [[Alexa-Fhem#Voraussetzungen]] erfüllt sind! Keine Experimente mit Versionen die darunter liegen.

====Fehlermeldung ''NAT-PMP failed: Error: timeout'' Fehler angezeigt beim Start von alexa-fhem====
Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: ''NAT-PMP failed: Error: timeout'', lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.

====Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder====
Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder.

Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.

====Was ist zu tun, wenn alexa-fhem keine Geräte findet?====
Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut ''genericDeviceType switch'' hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut ''alias'' eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann.
Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.

====Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?====
Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:
* wenn nichts bei alexa-fhem ankommt: port forwarding prüfen
* wenn lambda.js nichts los wird: im cloudwatch log nachsehen
* wenn bei lambda.js nichts ankommt: den trigger prüfen

Zunächst sollte man sich unter ''http://aws.amazon.com'' das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger.
Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf ''Triggers'' klicken und mit ''Add trigger'' erneut einen anlegen. Hier muss, wie in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 7, die ''Application Id'' stehen und der Haken bei ''Enable trigger'' gesetzt sein. Dann alexa-fhem neu starten.
Wenn ihr Änderungen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt. Fürs Debugging empfiehlt es sich, alexa-fhem in einer Konsole laufen zu lassen, um eingehende Anfragen mitverfolgen zu können.

Es kann sein, dass immer noch keine Log im Cloudwatch ([http://docs.aws.amazon.com/de_de/lambda/latest/dg/monitoring-functions-logs.html]) zu sehen ist. In dem Fall hilft es, eine neue Role Policy anzulegen.
* in der AWS Console [https://console.aws.amazon.com] oben links auf Services klicken, und in der Gruppe "Security, Identity & Compliance" auf IAM klicken
* links auf Roles klicken
* Auf dem Knopf "Create Role" klicken
* AWS Services > Lambda auswählen, unten auf Next:Permissions klicken
* im Filter / Policy Type, "log" eintragen (ohne quotes)
* CloudWatchLogsFullAccess hacken, auf Next:Review unten klicken
* Name vergeben und mit "Create role" bestätigen
* Oben links auf Services klicken, und in der Gruppe "Compute", auf Lambda klicken
* auf den Name der Funktion klicken
* Reiter Configuration auswählen
* in Existing Role, den neukreierten Role auswählen
* oben auf Save (und Testen wenn gewünscht) klicken.
Schon sollte eine neue Gruppe im Cloudwatch sichtbar sein. Die Suche von den Devices in Alexa wiederholen, und die Logs analysieren

====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====
{{Randnotiz|RNTyp=[g|Info]|RNText=Der User in der User= Directive von alexa.service muss Ausführungsrecht auf dem alexa binary haben (x), so wie auch mind. Lesezugriff auf dem Verzeichnis nach -U Option in der ExecStart= Directive und auch auf dem WorkingDirectory }}
Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei ''alexa'' muss ausführbar sein. Also z.B. so:
<syntaxhighlight lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</syntaxhighlight>
Sollte dies nicht der Fall sein bitte mit:
<syntaxhighlight lang="bash" style="width:70%;">chmod +x alexa</syntaxhighlight>
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

Eine lauffähige Konfiguration ist {{Link2Forum|Topic=71612|Message=668383|LinkText=hier}} zu sehen.

Ein Fehler in der Rechtekonfiguration führt in der Regel zu folgendem Ergebnis nach <code>sudo systemctl status alexa</code>:

<syntaxhighlight lang="bash"> Loaded: loaded (/etc/systemd/system/alexa.service; enabled)
Active: activating (auto-restart) (Result: exit-code) since mer. 2017-09-06 02:33:23 CEST; 3s ago
Process: 18332 ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa (code=exited, status=217/USER)
Main PID: 18332 (code=exited, status=217/USER)</syntaxhighlight>

====Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?====

Hierzu muss die Datei <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FHEM Connector für Amazon Alexa

2019-03-26T19:14:03Z

Justme: /* Was geht alles ? */

FHEM Connector für Amazon Alexa

2019-03-18T16:44:44Z

Justme: /* Was geht alles ? */

Homebridge einrichten

2019-03-15T13:28:01Z

Justme: /* BRAVIA Fernseher */

Dieses HOWTO zeigt die Installation und Erstinbetriebnahme von Homebridge.

Damit kann Siri benutzt werden, um FHEM-Devices zu steuern. So können Devices angesprochen werden, die offiziell HomeKit nicht unterstützen (die Vorgehensweise wurde auf einem Intel NUC mit Ubuntu Server 14.04 LTS und auf einem Raspberry Pi mit Raspbian getestet). Der Wiki-Eintrag bezieht sich hauptsächlich auf eine {{Link2Forum|Topic=32652|LinkText=Diskussion im FHEM-Forum}}. Ein Riesendank gilt vor allem {{Link2FU|430|Andre (justme1968)}}.

Die Konfiguration der inzwischen aktuellen zweiten Version des Homekit-Plugins ist in einem neuen {{Link2Forum|Topic= 48558 |LinkText=Thread im FHEM-Forum}} beschrieben. Hinzugekommen ist vor allem die freie Konfigurierbarkeit der Zuordnung zwischen FHEM Device und Homekit Accessory/Service, zwischen FHEM Reading und Homekit Characteristic, das mapping vom FHEM Readingwerten zu Homekit Werten sowie das Mapping von Homekit Werten zu FHEM Set-Kommandos und Werten.

Eine Sammlung funktionsfähiger Homebridge FHEM Konfigurationen kann hier gefunden werden: [[Homebridge User Configs]]. Die Sammlung befindet sich noch im Aufbau.

= Vorbereitung der Umgebung =

== NodeJS installieren ==
''Die nachfolgenden Befehle sind alle mit "sudo" prefixed. Wenn du unter "root" arbeitest oder deine Distribution einen anderen Mechanismus verwendet, so kannst du dies natürlich weglassen.''

Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:

'''NodeJS V4'''
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

{{Randnotiz|RNTyp=y|RNText=Bei Installation von NodeJS auf einem "alten" RasPi (B) bitte die besonderen Hinweise in {{Link2Forum|Topic=32652|Message=419325|LinkText=diesem Forenbeitrag}} beachten.}}
'''NodeJS V5'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V6'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V11'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

Bei Ubunutu ist es noch nötig apt-get wie folgt auszuführen.
<syntaxhighlight lang="bash" style="width:50%">
sudo apt-get install -y nodejs
</syntaxhighlight>

Damit ist NodeJS installiert.

== Python, g++, MDNS installieren ==
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install python g++ libavahi-compat-libdnssd-dev
</syntaxhighlight>

Nun sind alle Voraussetzungen geschaffen.

= Installation von Homebridge & notwendiger Shims =
Im nachfolgenden Absatz wird die Installation von Homebridge sowie des notwendigen Plugins (Shim) für FHEM erläutert.
Eventuell muss vor die Befehle ein
<syntaxhighlight lang="bash" style="width:50%;">
sudo
</syntaxhighlight>
vorangestellt werden.
== Homebridge installieren ==
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm install -g --unsafe-perm homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm install -g homebridge-fhem
</syntaxhighlight>
installiert.

=== Fehler während der Installation ===
Bei folgendem Fehler ist das Abrufen von Github nicht möglich.
<pre>npm ERR! git clone --template=/home/hs-server-admin/.npm/_git-remotes/_templates --mirror
git://github.com/KhaosT/ed25519.git /home/hs-server-admin/.npm/_git-remotes/git-github-com-KhaosT-ed25519-git-d8bdee1d:
github.com[0: 192.30.252.128]: errno=Die Wartezeit für die Verbindung ist abgelaufen</pre>
Fehler könnte hier durch eine aktive Firewall verursacht werden.

Kommt eine DNS Fehlermeldung fehlt meistens der AVAHI-DAEMON, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install avahi-daemon
</syntaxhighlight>

Wenn npm beim Kompilieren von mdns mit der Meldung abbricht, dass "dns_sd.h" nicht gefunden wird, fehlt das Paket libavahi-compat-libdnssd-dev, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install libavahi-compat-libdnssd-dev
</syntaxhighlight>

== Homebridge aktualisieren ==
Prüfen, ob es Updates gibt:
<syntaxhighlight lang="bash" style="width:50%;">
npm -g outdated
</syntaxhighlight>
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm -g update homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm -g update homebridge-fhem
</syntaxhighlight>
installiert.

Sollte dies nicht funktionieren, kann mit
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge
</syntaxhighlight>
bzw.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem
</syntaxhighlight>
das Update installiert werden.

Um eine spezielle Version zu installieren, können die Installationsbefehle, von oben, wie folgt angepasst werden.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem@0.4.5
</syntaxhighlight>

= Homebridge konfigurieren =
''Wichtig: Für die weiteren Schritte sollte man nicht root verwenden, sondern beispielsweise einen dedizierten Nutzer für homebridge oder der Einfachheit halber den Nutzer, unter dem auch FHEM läuft (meist "fhem").''

== Einstellungen für homebridge ==
Zunächst wird das Verzeichnis für die Konfigurationsdatei erstellt und in dieses gewechselt:
<syntaxhighlight lang="bash" style="width:50%;">
mkdir -p ~/.homebridge
cd ~/.homebridge/
</syntaxhighlight>

Nun muss darin noch die config.json erstellt bzw. angepasst werden:
<syntaxhighlight lang="bash" style="width:50%;">
nano ~/.homebridge/config.json
</syntaxhighlight>

Hinweise zur Konfiguration:
* "''bridge''":
** "''username''": Sollte so belassen werden. Sollte später auf dem iOS Device keine Homebridge gefunden werden, so kann man hier beispielsweise den String auf 31 statt 30 enden lassen um so eine neue Homebridge vorzutäuschen.
** "''port''": Sollte so belassen werden
** "''pin''": Der PIN kann beliebig in dem Format xxx-xx-xxx angepasst werden. Dieser muss nur einmal bei der Einrichtung in iOS eingegeben werden.
* "''platforms''":
** "''platform''": Hier muss "FHEM" beibehalten werden.
** "''server''": Hier muss die IP des FHEM-Servers eingetragen werden. Dabei muss Homebridge nicht auf dem selben Server laufen wie FHEM, kann aber. Wenn es auf dem gleichen Rechner läuft, dann bietet es sich an, die IP 127.0.0.1 zu verwenden.
** "''port''": Hier muss der Port des gewählten FHEMWEBs eingetragen werden (muss nicht das "normale" sein, kann eine extra Instanz sein)
** "''auth''": Ist FHEM nicht mit Nutzername/Password abgesichert, so kann man diese Zeile einfach entfernen.
** "''filter''": Damit nicht alle Devices von Homebridge berücksichtigt werden, bietet es sich an, die Devices zu filtern. In diesem Beispiel wurden alle Devices, die über Siri steuerbar sein sollen, zusätzlich in den Raum Homekit konfiguriert.
<syntaxhighlight lang="json" style="width:50%;">
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "031-45-154"
},

"platforms": [
{
"platform": "FHEM",
"name": "FHEM",
"server": "127.0.0.1",
"port": "8083",
"auth": {"user": "FhemUser", "pass": "XXX"},
"filter": "room=Homekit"
}
],

"accessories": []
}
</syntaxhighlight>

Wenn für FHEMWEB kein user/password vergeben ist muss die "auth" Zeile weggelassen werden.
Wird FHEM mit SSL abgesichert, so muss zusätzlich in der Sektion "platforms" noch diese Zeile (nach "port") eingefügt werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"ssl": true,
</syntaxhighlight>
Wenn man SSL ohne user/password benutzt, muss man "auth" Zeile einfugen, wobei die Werte weggelassen werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"auth": {"user": "", "pass": ""},
</syntaxhighlight>

Natürlich kann man auch nach beliebigen anderen Kriterien filtern. z.b. nach Device TYPE, nach subtype Attribut, ... Es können mehrere FHEM platforms Abschnitte mit eigenem Filter im config file stehen (dabei das Komma zwischen den einzelnen Abschnitten nicht vergessen!) . Auch Geräte auf die mehr als ein Filterausdruck matched werden dabei nur einmal hinzugefügt.

= FHEM konfigurieren =
Es empfiehlt sich ein siri Gerät in FHEM anzulegen.
define siri siri

Die benötigten Attribute werden inzwischen beim ersten Start von homebridge-fhem automatisch auf FHEM Seite eingetragen.

Mehr zu den inzwischen verfügbaren Konfigurationsmöglichkeiten findet sich auf den github und npmjs Seiten des Plugins und im ersten Beitrag des zugehörigen Thread im {{Link2Forum|Topic= 48558 |LinkText=Diskussion im FHEM-Forum}}

= Start von Homebridge =

== Hinweis ==
Nach allen Änderungen die in FHEM gemacht werden, welche Homebridge betreffen, muss Homebridge neu gestartet werden. Wie der Neustart erfolgen muss, ist abhängig davon, wie man Homebridge gestartet hat. Bitte den entsprechenden Methoden entnehmen.

== Einmaliger Manueller Start ==
<syntaxhighlight lang="bash" style="width:50%;">
homebridge
</syntaxhighlight>

Homebridge sollte nun laufen. Hier kann man die Kommunikation nachverfolgen. Abbrechen kann das ganze mit CTRL+c (es sind dann auch keine Befehle mehr mit Siri möglich). Damit Siri auch Befehle ohne ständig offenes Terminal bearbeiten kann, bitte nächsten Punkt beachten.

=== Fehler während des Manuellen Starts ===
Kommt ein Fehler der ähnlich aussieht wie folgender, sollte zuerst die Nodesversion geprüft werden.
Die Nodes version kann durch ein System Update auf eine niedrigere Version wie benötigt gedowngraded werden
<syntaxhighlight lang="bash" style="width=50%">
Error: Module version mismatch. Expected 47, got 46.
at Error (native)
at Object.Module._extensions..node (module.js:450:18)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:313:12)
at Module.require (module.js:366:17)
at require (module.js:385:17)
at Object.<anonymous> (/usr/lib/node_modules/homebridge/node_modules/mdns/lib/dns_sd.js:24:20)
at Module._compile (module.js:425:26)
at Object.Module._extensions..js (module.js:432:10)
at Module.load (module.js:356:32)
</syntaxhighlight>
Geprüft werden kann die Nodes Version mit:
<syntaxhighlight lang="bash" style="width=50%">node -v zeigt mir: v0.10.28, nodejs -v: v5.11.1</syntaxhighlight>
Hier ist die Version v0.10.28 wobei v0.12 Mindestvorraussetzung ist.
Die Installation der richtigen Nodes Version kann oben am Anhang des Wiki Artikels entnommen werden.

== Homebridge automatisch starten ==
Es gibt verschiedene Methoden, Homebridge automatisch zu starten.

=== Steuerung via FHEM ===
Auf Basis der unten stehenden ''Alternativen Methode'' wurde eine Version entwickelt, mit der man auch den Status einsehen und den Restart des Dienstes aus FHEM heraus erledigen kann. Diese Version ist auf der Seite [[Homebridge Start und Status in FHEM]] im Detail beschrieben.

=== Alternative Methode: Init-Skript ===
Dies startet homebridge als einen Service.

==== Service anlegen ====
<code>
sudo nano /etc/init.d/homebridge
</code>

Code einfügen (startet den Homebridge Server als Benutzer "pi" und nimmt an, dass sich .homebridge/config.json in seinem Homeverzeichnis unter /home/pi/ befindet):

<syntaxhighlight lang=bash>
#!/bin/sh
### BEGIN INIT INFO
# Provides: homebridge
# Required-Start: $network $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start daemon at boot time for homebridge
# Description: Enable service provided by daemon.
### END INIT INFO
export PATH=$PATH:/usr/local/bin
export NODE_PATH=$NODE_PATH:/usr/local/lib/node_modules
PID=`pidof homebridge`
case "$1" in
start)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is already running"
else
su - pi -c "homebridge > /dev/null 2>&1 &"
echo "Homebridge starting"
$0 status
fi
;;
stop)
if ! ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is not running"
else
kill $PID
echo "Homebridge closed"
fi
;;
restart)
if ! ps -p $PID > /dev/null 2>&1; then
$0 start
else
$0 stop
$0 start
fi
;;
status)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is running PID $PID"
else
echo "Homebridge is not running"
fi
;;
*)
echo "Usage: $0 {start|stop|status|restart}"
exit 1
;;
esac
exit 0
</syntaxhighlight>

==== Autostart aktivieren ====

<code>
sudo chmod 755 /etc/init.d/homebridge

sudo update-rc.d homebridge defaults
</code>

Nun kann man mit

<code>
sudo service homebridge start
</code>

bzw.

<code>
sudo /etc/init.d/homebridge start
</code>

den Dienst starten

=== Alternative Methode: systemd ===

Während das Init-Skript grundsätzlich auch mit systemd funktioniert, kann man natürlich für Homebridge auch ein systemd-Skript anlegen. Wie das geht, ist im [https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi#running-homebridge-on-bootup-systemd Wiki zu Homebridge] beschrieben.

== FHEM Device Einstellungen ==
Damit die zu schaltenden Geräte überhaupt in der Homebridge aufgenommen werden, muss man sie im Raum Homekit hinzufügen.

Um HM-CC-RT-DN Thermostate steuern zu können, muss wie oben beschrieben folgendes attribute gesetzt werden (hier als Beispiel das Device "Heizung"):
# attr Heizung subtype thermostat
Für einen Dummy muss man den genericDeviceType setzen, also beispielsweise:
# attr Dummy genericDeviceType switch
# attr Dummy setList on off

Wie bereits vorher angemerkt: fügt man ein Device hinzu oder führt eine Änderung an einem Device durch, so sollte homebridge neu gestartet werden.

= HomeKit in iOS =

== Einrichtung ==
Um FHEM über Homebridge in iOS nutzen zu können, muss HomeKit eingerichtet werden.

Es gibt verschiedene Apps. Im Folgenden wird die App EVE von Elgato empfohlen, die aus dem App-Store geladen werden muss.
In der App auf:
<pre style="width:50%;">
Gerät hinzufügen
</pre>
Es sollte ein Gerät mit der Bezeichnung "Homebridge" zur Auswahl erscheinen. Zur Ersteinrichtung auf PIN manuell eingeben gehen und (falls in der config.json nicht geändert):
<pre style="width:50%;">
031-45-154
</pre>
eingeben.

Im Anschluss können die Devices nach Belieben verschiedenen Räumen zugeteilt werden, sowie Szenen und Bereiche erstellt werden.

== Schalten mit Siri ==
'''HolyMoly''' aus dem FHEM-Forum hat ein paar Beispiele gegeben, wie man Siri dazu bringt Devices zu schalten:
<pre style="width:50%;">
"Schalte alle Lampen im Obergeschoss ein."
"Schalte Chloes Licht aus."
"Dimme das Licht in der Küche."
"Dimme das Licht im Esszimmer auf 50 %."
"Stelle das Licht in der Küche am hellsten ein."
"Stelle die Temperatur im Tahoe-Haus auf 22 °C ein."
"Stelle das Thermostat im Erdgeschoss auf 21 °C ein.
"Schalte den Drucker im Büro ein."
"Siri, bereite alles für eine Party vor."
"Bereite das Ambiente fürs Abendessen vor."
"Aktiviere den Nachtruhemodus."
</pre>

Mittlerweile kann Siri auch noch die Lichtfarbe von LEDs ändern.

= Hinweise =

== Unterstützte Geräte ==
Das FHEM Plugin von {{Link2FU|430|Andre (justme1968)}} unterstützt automatisch mindestens die folgenden Geräte:

switches (devices with set on and set off commands)
lights (devices with set on and set off commands)
HomeMatic, FS20 and ZWave dimmers (devices with set on, set off and set dim or set pct commands)
HUE, WifiLight, MilightDevice, SWAP_0000002200000003 (hue, sat, bri, rgb)
homematic, max and pid20 thermostats
homematic, DUOFERN and FS20/IT(?) blinds
homematic, MAX and FHTTK contact sensors (door, window)
HM-SEC-WIN, HM-SEC-KEY
presence, ROOMMATE
SONOS (power, volume)
harmony scenes
temperaturecw and humidity sensors
CO20 air quality sensor
probably some more ...

Über eine entsprechende Konfiguration lässt sich darüber hinaus jedes mit FHEM steuerbare Gerät auf die unterstützten Homekit-Typen abbilden.

Die aktuelle Liste und eine Beschreibung der Konfigurationsmöglichkeiten findet sich [https://www.npmjs.com/package/homebridge-fhem auf den npmjs seiten] bzw. [https://github.com/justme-1968/homebridge-fhem auf github].

Mehr zum homebridgeMapping findet sich hier: [[Alexa_und_Mappings#homebridgeMapping]]

Mehr zu den unterstützen Services und Characteristics findet sich hier: [https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js]

Über eine '''history''' Characteristic lässt sich für bestimmte Service-Typen eine Eve-Kompatible history aktivieren:
... history:size=1024 ...

=== Beispiele ===
===== BRAVIA Fernseher =====
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

===== Wetterstation =====
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>
[[Datei: homebridge-wetter.jpg|200px|Wetterstation in EVE]]

== Zusätzliche Plugins ==
Für manche der über FHEM steuerbaren Geräte wie z.b. MiLight, Harmony Hub, Philips Hue, Sonos,... gibt es eigene homekit plugins. Wenn immer möglich, empfiehlt es sich aber diese '''nicht''' zu verwenden, sondern die Steuerung über die FHEM-Integration zu realisieren, da
* diese in der Regel sehr viel mächtiger und frei konfigurierbar ist
* es FHEM erlaubt, als zentrale Instanz den Überblick über den aktuellen Gesamtzustand zu haben (wichtig bei Geräten, die gepollt werden)
* die Ressourcen auf den angesteuerten Geräten schont, da Werte optimal gecached werden und nur eine einzige Verbindung aufgebaut wird

== Hinweis für alte homebridge Versionen ==
UPDATE: Homebridge funktioniert mit einer kleinen Einschränkung nun auch mit node 4.0.0. Laut
[https://github.com/cflurin/homebridge-shims/wiki/Minimalist-Homebridge-on-a-Raspberry-Pi Homebridge on a Raspberry Pi] müssen die folgenden Abhängigkeiten (Dependencies) aus der '''package.json''' entfernt werden:
<pre>
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git"
</pre>

== Hinweis zur Geschwindigkeitsoptimierung auf einem Raspberry PI ==
Damit es auf einem Raspberry schneller läuft, wird darüber hinaus empfohlen, auch diverse Abhängigkeiten aus der '''package.json''' zu entfernen:
<pre>
"ad2usb": "git+https://github.com/alistairg/node-ad2usb.git#local",
"carwingsjs": "0.0.x",
"chokidar": "^1.0.5",
"eibd": "^0.3.1",
"elkington": "kevinohara80/elkington",
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git",
"lifx-api": "^1.0.1",
"lifx": "git+https://github.com/magicmonkey/lifxjs.git",
"node-hue-api": "^1.0.5",
"node-icontrol": "^0.1.4",
"node-milight-promise": "0.0.x",
"tough-cookie": "^2.0.0",
"sonos": "0.8.x",
"telldus-live": "0.2.x",
"teslams": "1.0.1",
"unofficial-nest-api": "git+https://github.com/hachidorii/unofficial_nodejs_nest.git#d8d48edc952b049ff6320ef99afa7b2f04cdee98",
"wemo": "0.2.x",
"wink-js": "0.0.5",
"komponist" : "0.1.0",
"yamaha-nodejs": "0.4.x",
</pre>

Daher zunächst ein Backup der Datei anlegen
<pre>sudo cp package.json package.json.bkp </pre>
Am einfachsten geht das Entfernen der Zeilen mit einem Editor, beispielsweise nano oder vi.
<pre>sudo nano package.json</pre>

Das config file sollte dann wie folgt aussehen: Achtung vor den letzten zwei "}" am Ende darf kein Komma sein.
<syntaxhighlight lang="json">
{
"name": "homebridge",
"description": "HomeKit support for the impatient",
"version": "0.1.1",
"scripts": {
"start": "DEBUG=* node app.js || true"
},
"repository": {
"type": "git",
"url": "git://github.com/nfarina/homebridge.git"
},
"license": "ISC",
"dependencies": {
"async": "^1.4.2",
"color": "0.10.x",
"debug": "^2.2.0",
"hap-nodejs": "^0.0.2",
"isy-js": "",
"mdns": "^2.2.4",
"netatmo": "1.3.0",
"node-cache": "3.0.0",
"node-persist": "0.0.x",
"node-xmpp-client": "1.0.0-alpha23",
"q": "1.4.x",
"queue": "^3.1.0",
"request": "2.49.x",
"xml2js": "0.4.x",
"xmldoc": "0.1.x"
}
}
</syntaxhighlight>

== Links ==
* [https://github.com/nfarina/homebridge Github homebridge]
* [https://github.com/justme-1968/homebridge-fhem Github homebridge-fhem]
* [https://www.npmjs.com/package/homebridge NPM homebridge]
* [https://www.npmjs.com/package/homebridge-fhem NPM homebridge-fhem]

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Homebridge einrichten

2019-03-15T13:26:34Z

Justme: /* BRAVIA Fernseher */

Dieses HOWTO zeigt die Installation und Erstinbetriebnahme von Homebridge.

Damit kann Siri benutzt werden, um FHEM-Devices zu steuern. So können Devices angesprochen werden, die offiziell HomeKit nicht unterstützen (die Vorgehensweise wurde auf einem Intel NUC mit Ubuntu Server 14.04 LTS und auf einem Raspberry Pi mit Raspbian getestet). Der Wiki-Eintrag bezieht sich hauptsächlich auf eine {{Link2Forum|Topic=32652|LinkText=Diskussion im FHEM-Forum}}. Ein Riesendank gilt vor allem {{Link2FU|430|Andre (justme1968)}}.

Die Konfiguration der inzwischen aktuellen zweiten Version des Homekit-Plugins ist in einem neuen {{Link2Forum|Topic= 48558 |LinkText=Thread im FHEM-Forum}} beschrieben. Hinzugekommen ist vor allem die freie Konfigurierbarkeit der Zuordnung zwischen FHEM Device und Homekit Accessory/Service, zwischen FHEM Reading und Homekit Characteristic, das mapping vom FHEM Readingwerten zu Homekit Werten sowie das Mapping von Homekit Werten zu FHEM Set-Kommandos und Werten.

Eine Sammlung funktionsfähiger Homebridge FHEM Konfigurationen kann hier gefunden werden: [[Homebridge User Configs]]. Die Sammlung befindet sich noch im Aufbau.

= Vorbereitung der Umgebung =

== NodeJS installieren ==
''Die nachfolgenden Befehle sind alle mit "sudo" prefixed. Wenn du unter "root" arbeitest oder deine Distribution einen anderen Mechanismus verwendet, so kannst du dies natürlich weglassen.''

Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:

'''NodeJS V4'''
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

{{Randnotiz|RNTyp=y|RNText=Bei Installation von NodeJS auf einem "alten" RasPi (B) bitte die besonderen Hinweise in {{Link2Forum|Topic=32652|Message=419325|LinkText=diesem Forenbeitrag}} beachten.}}
'''NodeJS V5'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V6'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V11'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

Bei Ubunutu ist es noch nötig apt-get wie folgt auszuführen.
<syntaxhighlight lang="bash" style="width:50%">
sudo apt-get install -y nodejs
</syntaxhighlight>

Damit ist NodeJS installiert.

== Python, g++, MDNS installieren ==
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install python g++ libavahi-compat-libdnssd-dev
</syntaxhighlight>

Nun sind alle Voraussetzungen geschaffen.

= Installation von Homebridge & notwendiger Shims =
Im nachfolgenden Absatz wird die Installation von Homebridge sowie des notwendigen Plugins (Shim) für FHEM erläutert.
Eventuell muss vor die Befehle ein
<syntaxhighlight lang="bash" style="width:50%;">
sudo
</syntaxhighlight>
vorangestellt werden.
== Homebridge installieren ==
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm install -g --unsafe-perm homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm install -g homebridge-fhem
</syntaxhighlight>
installiert.

=== Fehler während der Installation ===
Bei folgendem Fehler ist das Abrufen von Github nicht möglich.
<pre>npm ERR! git clone --template=/home/hs-server-admin/.npm/_git-remotes/_templates --mirror
git://github.com/KhaosT/ed25519.git /home/hs-server-admin/.npm/_git-remotes/git-github-com-KhaosT-ed25519-git-d8bdee1d:
github.com[0: 192.30.252.128]: errno=Die Wartezeit für die Verbindung ist abgelaufen</pre>
Fehler könnte hier durch eine aktive Firewall verursacht werden.

Kommt eine DNS Fehlermeldung fehlt meistens der AVAHI-DAEMON, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install avahi-daemon
</syntaxhighlight>

Wenn npm beim Kompilieren von mdns mit der Meldung abbricht, dass "dns_sd.h" nicht gefunden wird, fehlt das Paket libavahi-compat-libdnssd-dev, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install libavahi-compat-libdnssd-dev
</syntaxhighlight>

== Homebridge aktualisieren ==
Prüfen, ob es Updates gibt:
<syntaxhighlight lang="bash" style="width:50%;">
npm -g outdated
</syntaxhighlight>
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm -g update homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm -g update homebridge-fhem
</syntaxhighlight>
installiert.

Sollte dies nicht funktionieren, kann mit
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge
</syntaxhighlight>
bzw.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem
</syntaxhighlight>
das Update installiert werden.

Um eine spezielle Version zu installieren, können die Installationsbefehle, von oben, wie folgt angepasst werden.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem@0.4.5
</syntaxhighlight>

= Homebridge konfigurieren =
''Wichtig: Für die weiteren Schritte sollte man nicht root verwenden, sondern beispielsweise einen dedizierten Nutzer für homebridge oder der Einfachheit halber den Nutzer, unter dem auch FHEM läuft (meist "fhem").''

== Einstellungen für homebridge ==
Zunächst wird das Verzeichnis für die Konfigurationsdatei erstellt und in dieses gewechselt:
<syntaxhighlight lang="bash" style="width:50%;">
mkdir -p ~/.homebridge
cd ~/.homebridge/
</syntaxhighlight>

Nun muss darin noch die config.json erstellt bzw. angepasst werden:
<syntaxhighlight lang="bash" style="width:50%;">
nano ~/.homebridge/config.json
</syntaxhighlight>

Hinweise zur Konfiguration:
* "''bridge''":
** "''username''": Sollte so belassen werden. Sollte später auf dem iOS Device keine Homebridge gefunden werden, so kann man hier beispielsweise den String auf 31 statt 30 enden lassen um so eine neue Homebridge vorzutäuschen.
** "''port''": Sollte so belassen werden
** "''pin''": Der PIN kann beliebig in dem Format xxx-xx-xxx angepasst werden. Dieser muss nur einmal bei der Einrichtung in iOS eingegeben werden.
* "''platforms''":
** "''platform''": Hier muss "FHEM" beibehalten werden.
** "''server''": Hier muss die IP des FHEM-Servers eingetragen werden. Dabei muss Homebridge nicht auf dem selben Server laufen wie FHEM, kann aber. Wenn es auf dem gleichen Rechner läuft, dann bietet es sich an, die IP 127.0.0.1 zu verwenden.
** "''port''": Hier muss der Port des gewählten FHEMWEBs eingetragen werden (muss nicht das "normale" sein, kann eine extra Instanz sein)
** "''auth''": Ist FHEM nicht mit Nutzername/Password abgesichert, so kann man diese Zeile einfach entfernen.
** "''filter''": Damit nicht alle Devices von Homebridge berücksichtigt werden, bietet es sich an, die Devices zu filtern. In diesem Beispiel wurden alle Devices, die über Siri steuerbar sein sollen, zusätzlich in den Raum Homekit konfiguriert.
<syntaxhighlight lang="json" style="width:50%;">
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "031-45-154"
},

"platforms": [
{
"platform": "FHEM",
"name": "FHEM",
"server": "127.0.0.1",
"port": "8083",
"auth": {"user": "FhemUser", "pass": "XXX"},
"filter": "room=Homekit"
}
],

"accessories": []
}
</syntaxhighlight>

Wenn für FHEMWEB kein user/password vergeben ist muss die "auth" Zeile weggelassen werden.
Wird FHEM mit SSL abgesichert, so muss zusätzlich in der Sektion "platforms" noch diese Zeile (nach "port") eingefügt werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"ssl": true,
</syntaxhighlight>
Wenn man SSL ohne user/password benutzt, muss man "auth" Zeile einfugen, wobei die Werte weggelassen werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"auth": {"user": "", "pass": ""},
</syntaxhighlight>

Natürlich kann man auch nach beliebigen anderen Kriterien filtern. z.b. nach Device TYPE, nach subtype Attribut, ... Es können mehrere FHEM platforms Abschnitte mit eigenem Filter im config file stehen (dabei das Komma zwischen den einzelnen Abschnitten nicht vergessen!) . Auch Geräte auf die mehr als ein Filterausdruck matched werden dabei nur einmal hinzugefügt.

= FHEM konfigurieren =
Es empfiehlt sich ein siri Gerät in FHEM anzulegen.
define siri siri

Die benötigten Attribute werden inzwischen beim ersten Start von homebridge-fhem automatisch auf FHEM Seite eingetragen.

Mehr zu den inzwischen verfügbaren Konfigurationsmöglichkeiten findet sich auf den github und npmjs Seiten des Plugins und im ersten Beitrag des zugehörigen Thread im {{Link2Forum|Topic= 48558 |LinkText=Diskussion im FHEM-Forum}}

= Start von Homebridge =

== Hinweis ==
Nach allen Änderungen die in FHEM gemacht werden, welche Homebridge betreffen, muss Homebridge neu gestartet werden. Wie der Neustart erfolgen muss, ist abhängig davon, wie man Homebridge gestartet hat. Bitte den entsprechenden Methoden entnehmen.

== Einmaliger Manueller Start ==
<syntaxhighlight lang="bash" style="width:50%;">
homebridge
</syntaxhighlight>

Homebridge sollte nun laufen. Hier kann man die Kommunikation nachverfolgen. Abbrechen kann das ganze mit CTRL+c (es sind dann auch keine Befehle mehr mit Siri möglich). Damit Siri auch Befehle ohne ständig offenes Terminal bearbeiten kann, bitte nächsten Punkt beachten.

=== Fehler während des Manuellen Starts ===
Kommt ein Fehler der ähnlich aussieht wie folgender, sollte zuerst die Nodesversion geprüft werden.
Die Nodes version kann durch ein System Update auf eine niedrigere Version wie benötigt gedowngraded werden
<syntaxhighlight lang="bash" style="width=50%">
Error: Module version mismatch. Expected 47, got 46.
at Error (native)
at Object.Module._extensions..node (module.js:450:18)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:313:12)
at Module.require (module.js:366:17)
at require (module.js:385:17)
at Object.<anonymous> (/usr/lib/node_modules/homebridge/node_modules/mdns/lib/dns_sd.js:24:20)
at Module._compile (module.js:425:26)
at Object.Module._extensions..js (module.js:432:10)
at Module.load (module.js:356:32)
</syntaxhighlight>
Geprüft werden kann die Nodes Version mit:
<syntaxhighlight lang="bash" style="width=50%">node -v zeigt mir: v0.10.28, nodejs -v: v5.11.1</syntaxhighlight>
Hier ist die Version v0.10.28 wobei v0.12 Mindestvorraussetzung ist.
Die Installation der richtigen Nodes Version kann oben am Anhang des Wiki Artikels entnommen werden.

== Homebridge automatisch starten ==
Es gibt verschiedene Methoden, Homebridge automatisch zu starten.

=== Steuerung via FHEM ===
Auf Basis der unten stehenden ''Alternativen Methode'' wurde eine Version entwickelt, mit der man auch den Status einsehen und den Restart des Dienstes aus FHEM heraus erledigen kann. Diese Version ist auf der Seite [[Homebridge Start und Status in FHEM]] im Detail beschrieben.

=== Alternative Methode: Init-Skript ===
Dies startet homebridge als einen Service.

==== Service anlegen ====
<code>
sudo nano /etc/init.d/homebridge
</code>

Code einfügen (startet den Homebridge Server als Benutzer "pi" und nimmt an, dass sich .homebridge/config.json in seinem Homeverzeichnis unter /home/pi/ befindet):

<syntaxhighlight lang=bash>
#!/bin/sh
### BEGIN INIT INFO
# Provides: homebridge
# Required-Start: $network $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start daemon at boot time for homebridge
# Description: Enable service provided by daemon.
### END INIT INFO
export PATH=$PATH:/usr/local/bin
export NODE_PATH=$NODE_PATH:/usr/local/lib/node_modules
PID=`pidof homebridge`
case "$1" in
start)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is already running"
else
su - pi -c "homebridge > /dev/null 2>&1 &"
echo "Homebridge starting"
$0 status
fi
;;
stop)
if ! ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is not running"
else
kill $PID
echo "Homebridge closed"
fi
;;
restart)
if ! ps -p $PID > /dev/null 2>&1; then
$0 start
else
$0 stop
$0 start
fi
;;
status)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is running PID $PID"
else
echo "Homebridge is not running"
fi
;;
*)
echo "Usage: $0 {start|stop|status|restart}"
exit 1
;;
esac
exit 0
</syntaxhighlight>

==== Autostart aktivieren ====

<code>
sudo chmod 755 /etc/init.d/homebridge

sudo update-rc.d homebridge defaults
</code>

Nun kann man mit

<code>
sudo service homebridge start
</code>

bzw.

<code>
sudo /etc/init.d/homebridge start
</code>

den Dienst starten

=== Alternative Methode: systemd ===

Während das Init-Skript grundsätzlich auch mit systemd funktioniert, kann man natürlich für Homebridge auch ein systemd-Skript anlegen. Wie das geht, ist im [https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi#running-homebridge-on-bootup-systemd Wiki zu Homebridge] beschrieben.

== FHEM Device Einstellungen ==
Damit die zu schaltenden Geräte überhaupt in der Homebridge aufgenommen werden, muss man sie im Raum Homekit hinzufügen.

Um HM-CC-RT-DN Thermostate steuern zu können, muss wie oben beschrieben folgendes attribute gesetzt werden (hier als Beispiel das Device "Heizung"):
# attr Heizung subtype thermostat
Für einen Dummy muss man den genericDeviceType setzen, also beispielsweise:
# attr Dummy genericDeviceType switch
# attr Dummy setList on off

Wie bereits vorher angemerkt: fügt man ein Device hinzu oder führt eine Änderung an einem Device durch, so sollte homebridge neu gestartet werden.

= HomeKit in iOS =

== Einrichtung ==
Um FHEM über Homebridge in iOS nutzen zu können, muss HomeKit eingerichtet werden.

Es gibt verschiedene Apps. Im Folgenden wird die App EVE von Elgato empfohlen, die aus dem App-Store geladen werden muss.
In der App auf:
<pre style="width:50%;">
Gerät hinzufügen
</pre>
Es sollte ein Gerät mit der Bezeichnung "Homebridge" zur Auswahl erscheinen. Zur Ersteinrichtung auf PIN manuell eingeben gehen und (falls in der config.json nicht geändert):
<pre style="width:50%;">
031-45-154
</pre>
eingeben.

Im Anschluss können die Devices nach Belieben verschiedenen Räumen zugeteilt werden, sowie Szenen und Bereiche erstellt werden.

== Schalten mit Siri ==
'''HolyMoly''' aus dem FHEM-Forum hat ein paar Beispiele gegeben, wie man Siri dazu bringt Devices zu schalten:
<pre style="width:50%;">
"Schalte alle Lampen im Obergeschoss ein."
"Schalte Chloes Licht aus."
"Dimme das Licht in der Küche."
"Dimme das Licht im Esszimmer auf 50 %."
"Stelle das Licht in der Küche am hellsten ein."
"Stelle die Temperatur im Tahoe-Haus auf 22 °C ein."
"Stelle das Thermostat im Erdgeschoss auf 21 °C ein.
"Schalte den Drucker im Büro ein."
"Siri, bereite alles für eine Party vor."
"Bereite das Ambiente fürs Abendessen vor."
"Aktiviere den Nachtruhemodus."
</pre>

Mittlerweile kann Siri auch noch die Lichtfarbe von LEDs ändern.

= Hinweise =

== Unterstützte Geräte ==
Das FHEM Plugin von {{Link2FU|430|Andre (justme1968)}} unterstützt automatisch mindestens die folgenden Geräte:

switches (devices with set on and set off commands)
lights (devices with set on and set off commands)
HomeMatic, FS20 and ZWave dimmers (devices with set on, set off and set dim or set pct commands)
HUE, WifiLight, MilightDevice, SWAP_0000002200000003 (hue, sat, bri, rgb)
homematic, max and pid20 thermostats
homematic, DUOFERN and FS20/IT(?) blinds
homematic, MAX and FHTTK contact sensors (door, window)
HM-SEC-WIN, HM-SEC-KEY
presence, ROOMMATE
SONOS (power, volume)
harmony scenes
temperaturecw and humidity sensors
CO20 air quality sensor
probably some more ...

Über eine entsprechende Konfiguration lässt sich darüber hinaus jedes mit FHEM steuerbare Gerät auf die unterstützten Homekit-Typen abbilden.

Die aktuelle Liste und eine Beschreibung der Konfigurationsmöglichkeiten findet sich [https://www.npmjs.com/package/homebridge-fhem auf den npmjs seiten] bzw. [https://github.com/justme-1968/homebridge-fhem auf github].

Mehr zum homebridgeMapping findet sich hier: [[Alexa_und_Mappings#homebridgeMapping]]

Mehr zu den unterstützen Services und Characteristics findet sich hier: [https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js]

Über eine '''history''' Characteristic lässt sich für bestimmte Service-Typen eine Eve-Kompatible history aktivieren:
... history:size=1024 ...

=== Beispiele ===
===== BRAVIA Fernseher =====
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=0:remoteControl+play;1:remoteControl+pause;2:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

===== Wetterstation =====
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>
[[Datei: homebridge-wetter.jpg|200px|Wetterstation in EVE]]

== Zusätzliche Plugins ==
Für manche der über FHEM steuerbaren Geräte wie z.b. MiLight, Harmony Hub, Philips Hue, Sonos,... gibt es eigene homekit plugins. Wenn immer möglich, empfiehlt es sich aber diese '''nicht''' zu verwenden, sondern die Steuerung über die FHEM-Integration zu realisieren, da
* diese in der Regel sehr viel mächtiger und frei konfigurierbar ist
* es FHEM erlaubt, als zentrale Instanz den Überblick über den aktuellen Gesamtzustand zu haben (wichtig bei Geräten, die gepollt werden)
* die Ressourcen auf den angesteuerten Geräten schont, da Werte optimal gecached werden und nur eine einzige Verbindung aufgebaut wird

== Hinweis für alte homebridge Versionen ==
UPDATE: Homebridge funktioniert mit einer kleinen Einschränkung nun auch mit node 4.0.0. Laut
[https://github.com/cflurin/homebridge-shims/wiki/Minimalist-Homebridge-on-a-Raspberry-Pi Homebridge on a Raspberry Pi] müssen die folgenden Abhängigkeiten (Dependencies) aus der '''package.json''' entfernt werden:
<pre>
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git"
</pre>

== Hinweis zur Geschwindigkeitsoptimierung auf einem Raspberry PI ==
Damit es auf einem Raspberry schneller läuft, wird darüber hinaus empfohlen, auch diverse Abhängigkeiten aus der '''package.json''' zu entfernen:
<pre>
"ad2usb": "git+https://github.com/alistairg/node-ad2usb.git#local",
"carwingsjs": "0.0.x",
"chokidar": "^1.0.5",
"eibd": "^0.3.1",
"elkington": "kevinohara80/elkington",
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git",
"lifx-api": "^1.0.1",
"lifx": "git+https://github.com/magicmonkey/lifxjs.git",
"node-hue-api": "^1.0.5",
"node-icontrol": "^0.1.4",
"node-milight-promise": "0.0.x",
"tough-cookie": "^2.0.0",
"sonos": "0.8.x",
"telldus-live": "0.2.x",
"teslams": "1.0.1",
"unofficial-nest-api": "git+https://github.com/hachidorii/unofficial_nodejs_nest.git#d8d48edc952b049ff6320ef99afa7b2f04cdee98",
"wemo": "0.2.x",
"wink-js": "0.0.5",
"komponist" : "0.1.0",
"yamaha-nodejs": "0.4.x",
</pre>

Daher zunächst ein Backup der Datei anlegen
<pre>sudo cp package.json package.json.bkp </pre>
Am einfachsten geht das Entfernen der Zeilen mit einem Editor, beispielsweise nano oder vi.
<pre>sudo nano package.json</pre>

Das config file sollte dann wie folgt aussehen: Achtung vor den letzten zwei "}" am Ende darf kein Komma sein.
<syntaxhighlight lang="json">
{
"name": "homebridge",
"description": "HomeKit support for the impatient",
"version": "0.1.1",
"scripts": {
"start": "DEBUG=* node app.js || true"
},
"repository": {
"type": "git",
"url": "git://github.com/nfarina/homebridge.git"
},
"license": "ISC",
"dependencies": {
"async": "^1.4.2",
"color": "0.10.x",
"debug": "^2.2.0",
"hap-nodejs": "^0.0.2",
"isy-js": "",
"mdns": "^2.2.4",
"netatmo": "1.3.0",
"node-cache": "3.0.0",
"node-persist": "0.0.x",
"node-xmpp-client": "1.0.0-alpha23",
"q": "1.4.x",
"queue": "^3.1.0",
"request": "2.49.x",
"xml2js": "0.4.x",
"xmldoc": "0.1.x"
}
}
</syntaxhighlight>

== Links ==
* [https://github.com/nfarina/homebridge Github homebridge]
* [https://github.com/justme-1968/homebridge-fhem Github homebridge-fhem]
* [https://www.npmjs.com/package/homebridge NPM homebridge]
* [https://www.npmjs.com/package/homebridge-fhem NPM homebridge-fhem]

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FHEM Connector für Amazon Alexa

2019-03-14T12:18:24Z

Justme: /* Was geht alles ? */

FHEM Connector

2019-03-13T08:20:49Z

Justme: Weiterleitungsziel von Alexa FHEM Connector nach FHEM Connector für Amazon Alexa geändert

#WEITERLEITUNG [[FHEM Connector für Amazon Alexa]]

Alexa

2019-03-13T08:19:43Z

Justme:

Es gibt zwei Betriebsmodi für das alexa Modul, die separat beschrieben sind:

# Public FHEM Connector Skill: [[FHEM Connector für Amazon Alexa]]
# Private Skills: [[Alexa-Fhem|alexa-fhem]]

Alexa

2019-03-13T08:19:09Z

Justme:

Es gibt zwei Betriebsmodi für das alexa Modul, die separat beschrieben sind:

# Public FHEM Connector Skill: [[FHEM Connector]]
# Private Skills: [[Alexa-Fhem|alexa-fhem]]

Vorlage:FHEMWiki News

2019-03-12T16:04:29Z

Justme:

{|
{{News|26.01.2019|Das [[TRÅDFRI|tradfri]] Modul erweitert die Palette der [[ZigBee]] Module.}}
{{News|14.01.2019|Der [[FHEM Connector für Amazon Alexa|FHEM Connector]] Skill für Amazon Alexa ist verfügbar.}}
{{News|02.11.2018|Das Modul [[TA_CMI_UVR16x2_UVR1611|TA_CMI_JSON]] kann Werte des C.M.I. der Firma Technische Alternative auslesen und eignet sich so optimal zum Loggen von Daten zB der UVR16x2 oder UVR1611.}}
{{News|11.09.2018|Mit dem Modul [[AutoShuttersControl|AutoShuttersControl]] oder kurz ASC können typische Aufgabenstellungen im Zusammenhang mit Rollläden u.ä. automatisiert werden, wie zum Beispiel das Öffnen bei Sonnenaufgang, Schließen bei Sonnenuntergang oder das Anfahren von Lüftungspositionen beim Öffnen des zugehörigen Fensters. }}
{{News|12.02.2018|Die Module [[Modul Babble|Babble]] und [[Modul Talk2Fhem|Talk2Fhem]] erweitern die Sprachsteuerungsmöglichkeiten von FHEM}}
{{News|02.10.2017|[[FTUI eigene Widgets|Eigene Widgets für FHEM Tablet UI erstellen]]}}
{{News|30.08.2017|[[WINCONNECT]] - Windows PC steuern und Informationen abfragen/anzeigen. }}
{{News|24.08.2017|[[FHEMWEB/Widgets]] - Widgets (Frontendelemente) von FHEMWEB }}
{{News|24.08.2017|Neues Modul [[Modul_YAAHM|YAAHM]] wird per update verteilt. Es stellt eine Oberfläche bereit, um per Webinterface die zyklische Ausführung von Kommandos - mit Tages- und Wochenprofil - zu konfigurieren}}
{{News|24.07.2017|[[Telnet|Verbindung mit dem FHEM-Server per Telnet]]}}
{{News|20.07.2017|[[FHEM startet nicht - Tipps zur Fehlersuche]]}}
{{News|06.06.2017|[[‎Relaisplatine-Homebrew-MySensors|MySensors-Relaisplatine im Selbstbau]]}}
{{News|31.05.2017|[[Datenbankgestützte_Erstellung_der_Energiebilanz_einer_SMA_PV-Anlage_mit_Überschußeinspeisung|Datenbankgestützte Erstellung der Energiebilanz einer PV-Anlage mit Überschußeinspeisung]]}}
{{News|30.04.2017|[[DoorPiBoard]]: Eine Platine zur Umsetzung des [[DoorPi_und FHEM|DoorPi-Projektes]]}}
{{News|21.03.2017|Artikel zum alternativen Frontend [[:Kategorie:FHEM_Tablet_UI|Tablet UI]] aktualisiert und deutlich erweitert}}
{{News|02.03.2017|Neues Modul zur Ansteuerung von [[LGTV_WebOS|LG-TVs mit dem Betriebssystem WebOS]] wird per update verteilt}}
{{News|20.02.2017|Neues Modul [[SIP-Client|SIP]], ein SIP-Client für FHEM, wird per update verteilt}}
{{News|19.02.2017|FHEM Version 5.8 wurde freigegeben. Updatehinweise beachten: {{Link2Forum|Topic=67419}}}}
{{News|18.01.2017|Neues Modul [[DOIFtools]] mit Funktionen zur Unterstützung des Benutzers im Umgang mit [[DOIF]] wird per update verteilt}}
{{News|12.01.2017|Neues Modul zur Ansteuerung des Bluetooth 4.1 BLE Pflanzensensors [[XiaomiFlowerSens|Xiaomi Flower Care Smart Monitor]] wird per update ausgeliefert}}
{{News|01.01.2017|Diverse neue Wiki-Artikel mit Informationen und Hilfen zu [[DOIF#Links|DOIF]] }}
{{News|10.12.2016|FHEM Wiki ist auf einen neuen Server umgezogen und hat eine neue Standard-Internetadresse: https://wiki.fhem.de}}
{{News|21.11.2016|Neues Modul [[Modul_PostMe|PostMe]] stellt eine komfortable Oberfläche zur Listenverwaltung bereit}}
{{News|11.10.2016|Neue Module [[NUKI|NUKIbridge und NUKIDevice]] zur Ansteuerung des Nuki Smartlock werden per update verteilt}}
{{News|07.10.2016|Neues Modul [[TRAFFIC]] zur Erfassung der Fahrzeiten bei aktueller Verkehrslage mittels Google Maps Directions API wird per update verteilt}}
{{News|19.07.2016|Neues Modul zur Unterstützung der HomeMatic-Interfaces [[HM-MOD-RPI-PCB_HomeMatic_Funkmodul_für_Raspberry_Pi|Funkmodul für Raspberry Pi]] und [[HM-LGW-O-TW-W-EU_Funk-LAN_Gateway|Funk-LAN Gateway]] wird per update verteilt }}
{{News|12.07.2016|Neues Modul [[DbRep - Reporting und Management von DbLog-Datenbankinhalten]] wird per update verteilt }}
{{News|08.02.2016|Neues Modul [[Mediaportal|MEDIAPORTAL]] (Steuerung einer Mediaportal-Installation über Wifiremote) wird per update verteilt}}
{{News|16.11.2015|Neues Modul [[HP1000]] (Einbindung einer HP1000 Wetterstation) wird per update verteilt}}
{{News|16.11.2015|Neuer FHEM Befehl [[msg]] (Intelligentes Versenden/Routing von Nachrichten der Typen Audio,Text,Mail,Push,Light,Screen) wird per update verteilt}}
{{News|15.11.2015|FHEM Version 5.7 wurde veröffentlicht. Unbedingt Updatehinweise beachten: {{Link2Forum|Topic=44094}}}}
{{News|30.10.2015|FHEM Wiki unterstützt nun [[Syntax Highlighting]]}}
{{News|18.10.2015|Neues Modul [[TechemHKV]] (Empfang von Daten eines Techem Heizkostenverteilers) wird per update verteilt}}
{{News|02.10.2015|Kleiner FHEM-Einsteiger-Kurs als Wiki Artikel unter [[Erste_Schritte_in_fhem|Erste Schritte in FHEM]]}}
{{News|24.09.2015|Umfangreiche Überarbeitung der Wiki Artikel über [[:Kategorie:panStamp|panStamp Hardware und Software]]}}
{{News|11.09.2015|Neues Modul [[AMAD]] (Steuern und Informationsanzeige von Android-Geräten) wird per update verteilt}}
{{News|15.06.2015|Neues Modul [[yowsup]] (WhatsApp Unterstützung) wird per update verteilt}}
{{News|03.04.2015|Neues Geräte-Modul [[JawboneUp]] wird per update verteilt}}
{{News|23.03.2015|Neue Geräte-Module [[Modbus]], [[ModbusAttr]] und [[Modbus#Writing_modules_for_devices_using_this_module_as_a_library|ModbusSET]] werden per update verteilt}}
{{News|10.02.2015|FHEM Wiki ist auf einen neuen Server umgezogen und [[FHEMWiki:Interna#Offene_Probleme|Aktualisierung der MediaWiki-Software]]}}
{{News|31.01.2015|Neues Geräte-Modul [[Pushbullet]] wird per update verteilt}}
{{News|14.01.2015|Neues Hilfs-Modul [[CALVIEW]] wird per update verteilt}}
{{News|08.01.2015|Neues Geräte-Modul [[Buderus_Web_Gateway|km200]] zur Anbindung eines Buderus Web-Gateways wird per update verteilt}}
{{News|18.12.2014|Neues Geräte-Modul [[SONOS]] wird per update verteilt}}
{{News|15.12.2014|Überarbeitetes und erweitertes Geräte-Modul [[HTTPMOD]] wird per update verteilt}}
{{News|10.12.2014|Neues Geräte-Modul [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]] zur Anbindung einer Viessmann Heizung wird per update verteilt}}
{{News|17.11.2014|Neues Hilfs-Modul [[logProxy]] wird per update verteilt}}
{{News|09.11.2014|FHEM Version 5.6 wurde veröffentlicht}}
{{News|27.10.2014|Neues Geräte-Modul [[harmony]] zur FHEM-Anbindung Logitech Harmony Hub basierter Fernbedienungen wird per update verteilt}}
{{News|25.10.2014|Neues Geräte-Modul [[KostalPiko|KOSTALPIKO]] wird per update verteilt}}
{{News|24.10.2014|Neues Hilfs-Modul [[HourCounter]] wird per update verteilt}}
{{News|06.09.2014|Neues Hilfs-Modul [[CustomReadings]] per update verteilt}}
{{News|19.08.2014|Neues Hilfs-Modul [[DOIF]] wird per update verteilt}}
{{News|19.08.2014|Der Befehl [[update]] wurde überarbeitet: {{Link2Forum|Topic=26311}} }}
{{News|13.08.2014|Zusätzliche Domäne fhem.org aktiviert: {{Link2Forum|Topic=26113}} }}
{{News|29.09.2013|FHEM Version 5.5 wurde veröffentlicht}}
{{News|11.05.2013|Die meisten Daten aus dem FhemWiki sind wieder hergestellt.}}
{{News|04.05.2013|FHEM Wiki wird neu aufgebaut.}}
{{News|04.05.2013|FHEM Wiki Update zu [[Special:Version|MediaWiki 1.20.5]].}}
|}

Alexa-FHEM-lazy

2019-03-12T16:03:22Z

Justme: Weiterleitungsziel von Alexa FHEM Connector nach FHEM Connector für Amazon Alexa geändert

#WEITERLEITUNG [[FHEM Connector für Amazon Alexa]]

FHEM Connector für Amazon Alexa

2019-03-12T16:01:58Z

Justme:

Alexa FHEM Connector

2019-03-12T16:01:44Z

Justme: Justme verschob die Seite Alexa FHEM Connector nach FHEM Connector für Amazon Alexa: Der Name des Skills ist '''FHEM Connector'''. Nicht Alexa FHEM Connector. Das ist auch nach den Amazon Regeln wichtig.

#WEITERLEITUNG [[FHEM Connector für Amazon Alexa]]

FHEM Connector für Amazon Alexa

2019-03-12T16:01:44Z

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

'''TODO: Seite verschieben nach Alexa FHEM Connector. Der bisherige Titel ist missverständlich'''

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo-Gerät.

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf Port 3000 auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Bei Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor. Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab 14. Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.

* Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, musst Du i.d.R. diese Angaben noch einmal explizit setzen: Im attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

Hast Du noch die Shell-Konsole offen?

Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:
<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</Code>, oder über den Namen bei <it>currentlogfile</it> in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: hombridgeMapping On:cmdOn=<ein>,CmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus

* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading temperature geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: hombridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** ...
**Kommandos:
***Alexa, mache <name> heller/dunkler
***Alexa, Licht heller/dunkler

* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** werden mit <code>genericDeviceType</code> scene als Szene eingebunden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
*** Ist der Typ "scene" nicht vorhanden, muss er manuell zum ''Global''-Device hinzugefügt werden: <code>attr global userattr genericDeviceType:switch,outlet,light,blind,scene,speaker,thermostat, ...</code>

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** werden mit <code>genericDeviceType</code> scene als Szenen eingebunden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
*** Ist der Typ "scene" nicht vorhanden, siehe ''structure''

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** hombridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert schon, die Abfrage per Sprache noch nicht.

* Geräte, deren Lautstärke sich schalten lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** hombridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten ==
* alexa-fhem über FHEM anhalten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FHEM Connector für Amazon Alexa

2019-02-25T20:20:28Z

Justme: /* Was geht alles ? */