FHEMWiki - Benutzerbeiträge [de]

LightScene

2025-12-25T17:15:02Z

Benheim: Hinweis, dass gespeichert werden muss, auch wenn das rote Fragezeichen nicht angezeigt wird.

{{Infobox Modul
|ModPurpose=Speicherung und Wiederherstellung des Zustands von einer Gruppe von Geräten.
|ModType=h


|ModTechName=31_LightScene.pm
|ModOwner=justme1968
}}

'''LightScene''' ist ein Hilfsmodul, das es erlaubt, Zustände einer Gruppe von Geräten abzuspeichern und wiederherzustellen.

== Anwendung ==
=== Define ===
:<code>define <name> LightScene [<dev1>] [<dev2>] [<dev3>] ... </code>
:Beispiele:<syntaxhighlight>
define light_group LightScene Lampe1 Lampe2 Dimmer1
define kino_group LightScene LampeDecke LampeFernseher Fernseher Verstaerker
define Wohnzimmer LightScene Leinwand Beamer TV Leselampe Deckenlampe
</syntaxhighlight>Die Gerätedetailansicht zeigt eine HTML-Übersicht über den aktuellen Zustand aller eingebundenen Geräte und aller konfigurierten Szenen mit den jeweiligen Gerätezuständen. Die Spaltenüberschrift mit den Gerätenamen ist anklickbar, um zur Detailansicht dieses Geräts zu gelangen. Die erste Zeile, die den aktuellen Gerätezustand anzeigt, ist anklickbar und sollte wie ein Klick auf das Gerätesymbol in einer Raumübersicht reagieren. Damit kann interaktiv eine neue Szene konfiguriert und mit dem Befehlsmenü der Detailansicht gespeichert werden. Die erste Spalte der Tabelle mit den Szenennamen ist anklickbar, um die Szene zu aktivieren.
:'''Achtung''': nach einer Änderung von Szenen muss die FHEM-Konfiguration gespeichert werden, auch wenn nicht wie üblich mit einem roten Fragezeichen angezeigt wird, dass die Konfiguration geändert hat.
:Ein Weblink mit einer Szenenübersicht, der in jeden Raum oder Grundriss eingebunden werden kann, lässt sich erstellen mit:<syntaxhighlight>
define wlScene weblink htmlCode {LightScene_2html("LightSceneName")}
</syntaxhighlight>

=== Set ===

=== Get ===

=== Attributes ===

== Funktionen ==

== Anwendungsbeispiele ==
* [[XBMC#Lichtsteuerung_durch_KODI_oder_PLEX|Lichtsteuerung durch KODI oder PLEX]]
* [[Zuhause-Status|Umsetzung Zuhause-Status mit LightScene]]
* [[ReadingsGroup#LightScene_DropDown-Men.C3.BC_f.C3.BCr_smallscreen_Styles_oder_Floorplan|LightScene-DropDown-Menü für Smallscreen-Styles oder Floorplan]]

== Links ==
* weitere Dokumentation
* ...

HM-CFG-USB USB Konfigurations-Adapter

2018-04-16T12:14:34Z

Benheim: /* Einrichtung unter Linux */ git-core ist obsolet und umbenannt in git (siehe https://packages.debian.org/jessie/git-core)

{{Infobox Hardware
|Bild=HM-CFG-USB-2.jpg
|Bildbeschreibung=HomeMatic USB Konfigurationsadapter (Version 2)
|HWProtocol=HomeMatic
|HWType=Interface/Gateway
|HWCategory=HomeMatic
|HWComm=868,3 MHz
|HWChannels=
|HWVoltage=5 V
|HWPowerConsumption=
|HWPoweredBy=USB-Bus
|HWSize=V1: 40 x 90 x 25 mm<br />V2: 28 x 84 x 11,5 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]

|HWManufacturer=eQ-3
}}
Der [[HomeMatic]] '''USB Konfigurations-Adapter''' ist ein USB-Stick, der außer zur Konfiguration von HomeMatic-Komponenten auch als [[Interface]] zwischen FHEM und HomeMatic-Geräten benutzt werden kann. Er existiert in zwei Versionen: der älteren HM-CFG-USB und der neueren HM-CFG-USB2. Die folgenden Beschreibungen gelten für beide Versionen, es sei denn, es ist ausdrücklich eine spezifische Version genannt.

== Einbindung in FHEM ==
Im FHEM-Forum wird die Einbindung als Interface in diesem {{Link2Forum|Topic=13071}} beschrieben und diskutiert. Im {{Link2Forum|Topic=13071|Message=79872|LinkText=Eröffnungsbeitrag}} wird eine gut funktionierende HMLAN-Emulationssoftware [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland] von ihrem Entwickler vorgestellt, um den HM-CFG-USB in FHEM zu integrieren. Die HMLAN-Emulationssoftware muss zunächst kompiliert und installiert werden. Anschließend wird der HM-CFG-USB (üblicherweise auf localhost) genau wie [[HM-CFG-LAN LAN Konfigurations-Adapter|HMLAN]] in FHEM eingebunden.

=== Einrichtung unter Linux ===
Die Schritte zur Kompilierung und Installation hat der hmland-Entwickler sowohl auf der [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland-Internetseite] in Englisch (kurz) als auch im oben genannten {{Link2Forum|Topic=13071|Message=79872|LinkText=Eröffnungsbeitrag}} in Deutsch (ausführlich) dargestellt. Die dort gemachten Angaben werden auch bei Bedarf aktualisiert und sind deshalb der beste Anlaufpunkt für Kompilierung und Installation.

{{Randnotiz|RNTyp=Info|RNText='''Skript zur Kompletteinrichtung unter Linux'''
Dieser {{Link2Forum|Topic=13071|Message=190887|LinkText=Bericht}} im Forum stellt ein Script vor, das ''hmland'' herunterlädt, übersetzt (kompiliert), installiert sowie ein init-Script anlegt, so dass fast keine manuellen Eingriffe mehr notwendig sind.}}
Die nachfolgenden Angaben in diesem Abschnitt sind rein zu Informationszwecken (noch) enthalten:

Zunächst muss die HMLAN-Emulationssoftware kompiliert werden. Analog zu [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb dieser Beschreibung] ist die Vorgehensweise die folgende (in Debian/Ubuntu/Raspbian):
<syntaxhighlight lang="bash">
cd /opt/
apt-get install build-essential libusb-1.0-0-dev make gcc git
git clone git://git.zerfleddert.de/hmcfgusb
cd hmcfgusb
make
</syntaxhighlight>

Danach kann der Dienst (zu Testzwecken sind Debugging-Ausgaben mit <code>-D</code> aktiviert) gestartet werden:
:<code> /opt/hmcfgusb/hmland -p 1234 -D</code>

==== Start als Daemon ====
Um ''hmland'' automatisch als Daemon zu starten, kann ein init-Script genutzt werden. Die Quellen von ''hmland'' enthalten ein solches Script im <code>debian/</code> Unterverzeichnis:

<syntaxhighlight lang="bash">
cp /opt/hmcfgusb/debian/hmland.init /etc/init.d/hmland
cp /opt/hmcfgusb/debian/hmland.default /etc/default/hmland
</syntaxhighlight>

Einstellungen, beispielsweise der Port, auf dem ''hmland'' hört, können (und sollten) in der Datei <code>/etc/default/hmland</code> vorgenommen werden. Wichtig: Wenn diese Anleitung befolgt wurde, muss in der Datei die folgende Zeile wie folgt angepasst werden (<code>/hm</code> aus dem Pfad entfernen), damit der automatische Start des Daemon klappt:
<syntaxhighlight lang="bash">
DAEMON=/opt/hmcfgusb/$NAME # Introduce the server's location here
</syntaxhighlight>

Die kopierte Datei mit <code>chmod 755 /etc/init.d/hmland</code> ausführbar machen, anschließend kann ''hmland'' mit folgendem Befehl gestartet werden:
:<code>/etc/init.d/hmland start</code>

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgende Konfigurationsdatei verwendet werden:
<syntaxhighlight lang="bash">
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

chdir /opt/hmcfgusb
exec /opt/hmcfgusb/hmland -d -l 127.0.0.1 -p 1234
</syntaxhighlight>

Die Datei sollte als <code>/etc/init/hmland.conf</code> angelegt werden. Mit dem Befehl
:<code>initctl reload-configuration </code>
wird Upstart angewiesen, seine Konfiguration erneut einzulesen. Danach kann der Dienst ''hmland'' mit
:<code>service hmland start </code>
gestartet werden. <code>hmland</code> wird jetzt immer vor FHEM gestartet und nach FHEM beendet.

==== Start über FHEM Startskript ====
Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

Zunächst hmland kompilieren wie oben beschrieben, bis zum make. Das muss erfolgreich durchgelaufen sein.

Dann geht es weiter:
:<code>sudo cp hmcfgusb.rules /etc/udev/rules.d/ </code>

Jetzt das FHEM Startskript anpassen (in den Blöcken 'start' und 'stop' muss quasi nur jeweils 1 Zeile eingefügt werden:

Damit editiert man das FHEM Startskript:
:<code>sudo nano /etc/init.d/fhem </code>

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)
<syntaxhighlight lang="bash">
'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

'stop')
echo "Stopping fhem..."
perl fhem.pl $port "shutdown"
RETVAL=$?
pkill hmland
</syntaxhighlight>

So wird hmland vor FHEM gestartet und nach FHEM beendet. Letztlich erspart es Probleme mit den diversen Startskripten und ihren Rechten.

Es dauert nach dem Start von FHEM noch einige Sekunden, bis hmland fertig geladen ist. In dieser Zeit kann es zu fehlerhaften Einträgen im Logfile kommen.

=== Einrichtung auf Synology DiskStations ===
Packages für DSM5.2 finden sich hier:
https://github.com/mkunzmann/spksrc/releases/tag/0.101-3

Welches Package für welche DS kann man hier sehen:
https://github.com/SynoCommunity/spksrc/wiki/Architecture-per-Synology-model

Einfach das passende Package installieren und dann kann man den hmland über den Synology Package-Manager starten und stoppen. Während der Installation kann man den Port für hmland festlegen. Bitte einen Port > 1024 wählen, da der hmland nicht als root läuft. Außerdem kann ein Logfile angegeben werden. Hier am besten eine Datei auf einem USB Stick angeben die für jedermann schreibbar sein muss. Damit sollten die Platten nach wie vor in den Standby gehen.

=== Einrichtung unter Mac OS X ===
Wie unter Linux braucht man die HMLAN-Emulationssoftware hmland, die man aus Quelltexten erstellen muss. Dazu muss man die Bibliothek libusb installieren, entweder mit einem der Paketmanager wie Fink, MacPorts oder Homebrew oder direkt aus den Quellentexten (Beispiel: "fink install libusb1-shlibs libusb1"). Hat man wie bei Linux das Quelltextarchiv für hmland heruntergeladen und ausgepackt, müssen die Dateien Makefile und hmcfgusb.c angepasst werden.

Im Makefile muss man den Pfad zur libusb anpassen. Hat man libusb mit fink installiert, muss man, "/opt/local/" durch "/sw/" bei den CFLAGS und den LDFLAGS ersetzen und
das "-lrt" aus den LDLIBS entfernen. Die Library librt gibt es bei Mac OS X nicht und wird anscheinend auch nicht gebraucht. (Stimmt das eigentlich?)

In der Datei hmcfgusb.c muss man die Zeilen 130-134 mit dem Aufruf libusb_detach_kernel_driver auskommentieren oder löschen. Der geht nicht auf Mac OS X.

Nach den Änderungen in den zwei Dateien, kann man wie bei Linux den Dämon hmland mit dem Kommando "make" erzeugen und mit "./hmland" ausführen. Automatisches Starten beim Booten mit launchd ist noch nicht probiert.

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:
<syntaxhighlight lang="text">
Datum Zeit: Client 127.0.0.1 connected!
Can't claim interface: Access denied (insufficient permissions)
Can't find/open hmcfgusb!
Datum Zeit: Connection to 127.0.0.1 closed!
</syntaxhighlight>

Auch ein Start von hmland mit Superuser-Rechten ändert daran nichts. Damit das claim interface klappt, muss man eine codeless kext in den Ordner /Library/Extensions legen. Ich habe dieses (http://mspdebug.sourceforge.net/misc/ex430rf2500-kext.zip) herunter geladen. Damit es funktioniert, muss man aber in der Datei Info.plist des Bundle die Properties idProduct und idVendor ändern, entweder mit dem Property List Editor oder einem anderen Texteditor. Die beiden Properties sind etwas versteckt bei Information Property List → IOKitPersonalities → ComIntf. Bei DebugIntf und DeviceDriver scheint man es nicht ändern zu müssen, aber schaden kann es nicht.

<syntaxhighlight lang="text">
idProduct: 49167
idVendor: 6943
</syntaxhighlight>

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:
<syntaxhighlight lang="bash">
chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext
</syntaxhighlight>

Danach die Datei ex430rf2500.kext in den Ordner /Library/Extensions legen und hmland sollte dann funktionieren.

Es kann sein, dass ab Mac OS X 10.9 der Trick mit dem codeless kext nicht mehr funktioniert, aber noch ist das nicht getestet oder bestätigt. Langfristig kann man vielleicht auch eine kext mit einem Treiber für den HM-CFG-USB USB erstellen

=== Einrichtung unter Windows ===
Bei der Einrichtung und vermutlich auch dem Betrieb unter Windows 8.1 sind wegen der erweiterten Energieverwaltungsfunktionen die von eQ-3 [http://www.eq-3.de/Downloads/eq3/pdf_FAQ/Funk-Konfigurationsdapter-USB_Windos_8.1.pdf zusammengestellten Tipps] zu befolgen.

=== Definition(en) in der FHEM-Konfiguration ===
In der FHEM [[Konfiguration]] muss noch, sofern/sobald der ''hmland'' läuft, das Device eingerichtet werden mit den folgenden Anweisungen:
:<code>define '''hmusb''' HMLAN 127.0.0.1:1234 </code>
wobei '''hmusb''' der frei wählbare Devicename ist. Anschließend sollte bzw. muss noch mit
:<code>attr '''hmusb''' hmId <'''hmId'''> </code>
eine '''hmId''' zugeordnet werden (dabei bitte auch die Hinweise und Regeln beachten, die im Zusammenhang mit der [[Virtueller Controller VCCU|VCCU]] beschrieben sind!

== Firmware Update ==
Der Firmware Update (unter Linux) ist ebenfalls auf der [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland-Internetseite] beschrieben. Auch die letzte bekannte Firmware-Version (0.967) steht dort zur Verfügung.

== Bekannte Probleme ==
=== Verbindung zu neueren hmland-Versionen nicht stabil ===
Seit Version 0.100 meldet sich die HMLAN-Emulationssoftware als USB-Interface bei FHEM. Ältere FHEM-Versionen (vor dem 19.6.2015) brechen deshalb die Verbindung ab, da sie nur ein LAN-Interface erwarten.

Lösung: Kommandozeilenparameter <code>-I</code> dem hmland-Aufruf hinzufügen, dann meldet sich dieser wieder als LAN-Interface.

=== Stick nicht (mehr) ansprechbar ===
Zitat aus dem {{Link2Forum|Topic=32502|Message=249122|LinkText=FHEM-Forum}}:
:''... befürchte ich, dass dein Stick das Zeitliche gesegnet hat. Machen die Dinger leider sehr gerne... Ganz besonders beim Modus-Wechsel vom 10k- in den 100k-Modus, wenn man bei irgendeinem Device ein Firmwareupdate durchführt. <br />Die gute Nachricht ist, dass der Fehler bei sämtlichen Händlern bekannt ist und anstandslos getauscht wird.''

=== Raspberry Pi ===
Der USB-Stack am Raspberry Pi ist für viele Probleme verantwortlich. Daher sieht man öfter Fehlermeldungen:
:<code>usb-transfer took more than 100ms (1039ms), this may lead to timing problems!</code>

Da das Timing bei HomeMatic wichtig ist führt das zu vielen Retransmits und zu unzuverlässigen Aktoren. Als Workaround kann man den USB-Stack auf die deutlich langsamere Version 1.1 stellen. Dazu fügt man folgenden Text am Anfang der Datei /boot/cmdline.txt ein:
:<code>dwc_otg.speed=1</code>

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
{{Randnotiz|RNTyp=r|RNText=Stand März 2016 ist allem Anschein nach kein HM-CFG-USB mehr im ELV Programm enthalten!}}
* HM-CFG-USB-2: die aktuelle Version; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

== Links ==
* Bedienungsanleitung [http://www.eq-3.de/Downloads/eq3/pdf_produkte/HM-CFG-USB-2_-UM-eQ-3-150129-web.pdf HM-CFG-USB-2, PDF]
* FHEM-Forums {{Link2Forum|Topic=13071}}: HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in FHEM nutzen
* [http://www.elv.de/homematic-usb-konfigurations-adapter-1.html ELV Shopseite] zum HM-CFG-USB
* [http://www.eq-3.de/produkt-detail-zentralen-und-gateways/items/homematic-funk-konfigurationsadapter-usb.html eQ-3 Produktseite] zum "HomeMatic Funk-Konfigurationsadapter USB"; Downloads, technische Daten, etc.

[[Kategorie:HomeMatic Components]]
[[Kategorie:Interfaces]]
[[Kategorie:OSX]]

Alexa-Fhem

2017-12-04T06:59:25Z

Benheim: /* Alexa Skills */ URL zu "Login with Amazon" eingefügt

'''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 weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fähigkeit) ist die Bezeichnung für eine per Spracherkennung bediente Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, zur 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_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</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=60244|Message=540117|LinkText=hier}} zu finden.

====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!).
# 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. <br/>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.<br/> 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>.<br/>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. <br/>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,
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'',
# ''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:
{
"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"
}
]
}

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 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 ====
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>

==== 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/alexa/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<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|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''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen<br />[[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken (https://developer.amazon.com/lwa/sp/overview.html).<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen<br/>[[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|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'''<br/>[[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<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [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]
.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# Auf der folgenden Seite eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Type'' -> ''SmartHome Skill API''
#:* ''Language'' -> ''German''
#:* ''Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Payload Version'' -> ''v2 (other devices)'' <br/>[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# Auf der Seite ''Configuration'' Folgendes eingeben:
#:* ''Service Endpoint Type'' -> ''AWS Lambda'' ist vorausgewählt und kann nicht geändert werden.
#:* ''Geographical Region'' -> ''Europe'' auswählen und im Textfeld die ARN aus Abschnitt [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code><br /><br />
<br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen<br />[[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"<br />[[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:<br/><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<br />[[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.
<br />[[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<br />[[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><br />[[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<br />[[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben<br />[[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<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]

==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen<br />[[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen<br />[[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<br />[[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 <br />[[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''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.<br />[[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken<br />[[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<br />[[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<br />[[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<br />[[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<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen<br />[[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken<br />[[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken<br />[[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen<br />[[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein <br />[[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken<br />[[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.

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=im Forum}} beschrieben.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions)

== 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 <b>UnityMedia</b> 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

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

Alexa-Fhem

2017-12-03T21:48:01Z

Benheim: /* Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können? */ Hinweis auf Ausgabe von alexa-fhem in Konsole

'''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 weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fähigkeit) ist die Bezeichnung für eine per Spracherkennung bediente Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, zur 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_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</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=60244|Message=540117|LinkText=hier}} zu finden.

====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!).
# 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. <br/>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.<br/> 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>.<br/>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. <br/>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,
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'',
# ''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:
{
"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"
}
]
}

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 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 ====
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>

==== 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/alexa/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<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|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''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen<br />[[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken.<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen<br/>[[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|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'''<br/>[[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<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [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]
.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# Auf der folgenden Seite eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Type'' -> ''SmartHome Skill API''
#:* ''Language'' -> ''German''
#:* ''Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Payload Version'' -> ''v2 (other devices)'' <br/>[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# Auf der Seite ''Configuration'' Folgendes eingeben:
#:* ''Service Endpoint Type'' -> ''AWS Lambda'' ist vorausgewählt und kann nicht geändert werden.
#:* ''Geographical Region'' -> ''Europe'' auswählen und im Textfeld die ARN aus Abschnitt [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code><br /><br />
<br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen<br />[[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"<br />[[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:<br/><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<br />[[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.
<br />[[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<br />[[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><br />[[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<br />[[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben<br />[[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<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]

==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen<br />[[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen<br />[[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<br />[[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 <br />[[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''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.<br />[[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken<br />[[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<br />[[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<br />[[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<br />[[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<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen<br />[[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken<br />[[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken<br />[[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen<br />[[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein <br />[[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken<br />[[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.

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=im Forum}} beschrieben.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions)

== 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 <b>UnityMedia</b> 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

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

Alexa-Fhem

2017-12-03T21:36:31Z

Benheim: /* Einrichtung unter FHEM */ Link auf Harmony-Hub-HowTo im Forum

'''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 weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fähigkeit) ist die Bezeichnung für eine per Spracherkennung bediente Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, zur 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_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</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=60244|Message=540117|LinkText=hier}} zu finden.

====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!).
# 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. <br/>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.<br/> 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>.<br/>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. <br/>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,
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'',
# ''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:
{
"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"
}
]
}

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 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 ====
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>

==== 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/alexa/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<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|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''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen<br />[[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken.<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen<br/>[[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|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'''<br/>[[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<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [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]
.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# Auf der folgenden Seite eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Type'' -> ''SmartHome Skill API''
#:* ''Language'' -> ''German''
#:* ''Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Payload Version'' -> ''v2 (other devices)'' <br/>[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# Auf der Seite ''Configuration'' Folgendes eingeben:
#:* ''Service Endpoint Type'' -> ''AWS Lambda'' ist vorausgewählt und kann nicht geändert werden.
#:* ''Geographical Region'' -> ''Europe'' auswählen und im Textfeld die ARN aus Abschnitt [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code><br /><br />
<br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen<br />[[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"<br />[[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:<br/><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<br />[[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.
<br />[[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<br />[[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><br />[[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<br />[[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben<br />[[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<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]

==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen<br />[[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen<br />[[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<br />[[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 <br />[[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''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.<br />[[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken<br />[[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<br />[[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<br />[[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<br />[[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<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen<br />[[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken<br />[[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken<br />[[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen<br />[[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein <br />[[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken<br />[[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.

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=im Forum}} beschrieben.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions)

== 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 <b>UnityMedia</b> 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 Änderugen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt.

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

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

Alexa und Mappings

2017-11-27T20:44:19Z

Benheim: /* Characteristics */ Typo

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 Attribute kennt standardmäßig nur wenige Werte, die per Drop-Down-Liste ausgewählt werden können.
{| class="wikitable"
|-
! Name !! ''Service'' !! ''Characteristic''
|-
| security
|-
| ignore
|-
| switch
|-
| outlet
|-
| light
|-
| blind
|-
| thermometer
|-
| thermostat
|-
| contact
|-
| garage
|-
| window
|-
| lock || lock || LockCurrentState/LockTargetState
|}
Andere Werte müssen über das Befehlsfeld zugewiesen werden:
<code>attr meinSensor genericDeviceType <meinDeviceType></code> '''TODO:''' Macht eher wenig Sinn, weil diese iN Alxea-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/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

===''Characteristics''===
{| class="wikitable"
|-
! Name !! Typ !! Parameter und Werte !! Standardmapping
|-
| On || Boolean || valueOn, valueOff, cmdOn, cmdOff ||
* state,valueOff:/off|A0|000000/, cmdOn:on,cmdOff:off
* Wenn es sich um einen Dummy handelt, bei dem das Attribut ''setList'' den Wert "<cmd0> <cmd1>" hat: <br/>state,valueOn:<cmd0>,cmdOn:<cmd0>,cmdOff:<cmd1>
|-
| ContactSensorState || Integer || CONTACT_DETECTED=0,CONTACT_NOT_DETECTED=1 || value,values=???:CONTACT_DETECTED,???:CONTACT_NOT_DETECTED
|-
| Brightness
|-
| Hue
|-
| Saturation
|-
| CurrentTemperature
|-
| TargetTemperature
|-
| CurrentRelativeHumidity
|-
| CurrentAmbientLightLevel
|-
| AirQuality
|-
| CurrentDoorState || Integer || OPEN=0, CLOSED=1, OPENING=2, CLOSING=3, STOPPED=4|| Mehrere Mappings möglich:
* doorState,values=/^opening/:OPENING,/^closing/:CLOSING,/^open/:OPEN,/^closed/:CLOSED,/.*/:STOPPED
* state,values=/^Closed/:CLOSED,/.*/:OPEN
* Window,values=/^Closed/:CLOSED,/.*/:OPEN
* contact,values=/^closed/:CLOSED,/.*/:OPEN
|-
| TargetDoorState || Integer || OPEN=0, CLOSED=1||
* state,values=???:OPEN,???:CLOSED
* Wenn es sich um eine KeyMatic handelt, also das Attribut ''model'' den Wert HM-SEC-KEY hat, oder ''genericDeviceType'' den Wert "lock" hat:<br/>???,default:CLOSED,timeout:500,cmds=OPEN:open
|-
| LockCurrentState || Integer || UNSECURED=0, SECURED=1, JAMMED = 2, UNKNOWN = 3|| lock,values=/uncertain/:UNKNOWN,/^locked/:SECURED,/.*/:UNSECURED<br/>
|-
| LockTargetState || Integer || UNSECURED=0, SECURED=1||
* Wenn es sich um eine KeyMatic handelt, also das Attribut ''model'' den Wert HM-SEC-KEY hat:<br/>state,values=/^locked/:SECURED,/.*/:UNSECURED,cmds=SECURED:lock;UNSECURED:unlock
* Wenn ''genericDeviceType'' den Wert "lock" hat:<br/>state,values=/^locked/:SECURED,/.*/:UNSECURED,cmds=SECURED:lock+locked,UNSECURED:lock+unlocked
|-
| OccupancyDetected
|-
| StatusLowBattery
|-
| SecuritySystemCurrentState
|-
| SecuritySystemTargetState
|-
| FirmwareRevision
|-
| alle anderen Homebridge Characteristic
|}

===Parameter===
{| class="wikitable"
|-
! Name !! Typ !! Parameter
|-
| values || Dieser Parameter enthält eine durch Semikolon getrennte Liste von Entsprechungen der Form <code>FHEM-Wert:Homekit-Wert</code>. Jeder FHEM-Wert kann ein Literal (String) sein, oder ein Regulärer Ausdruck der Form /regex/. Jeder Homekit-Wert kann ein Literal (String) sein, oder ein für diese ''Characteristic'' definierter Term. Wenn als Homekit-Wert ein "#" steht, wird es gleich dem aktuellen Wert gesetzt (Heißt was ???).'''Achtung''': Wegen der nicht konsistenten Vertauschung der Seitenbezüge links-rechts ist das eine sehr gewöhnungsbedürftige Notation.
|-
| valueOn, valueOff || Dies sind die FHEM-Werte für boolesche ''readings'', die auf die Homekit-Werte true/false bzw. on/off states gemappt werden. Abkürzung: Wenn nur einer der beiden Werte angegeben wird, werden alle anderen automatisch auf den anderen gemappt.
|-
| timeout || Timeout in ms, nach dem der Homekit-Wert auf den Default-Wert zurückgesetzt wird, verwendet zur Simulation von Tastenkontakten
|}

==Beispiele==

=== Harmony Hub Fernbedienung ===
Im Harmony Hub System von Logitech steuert die Fernbedienung Geräte normalerweise nicht direkt per IR, sondern sendet per Funk einen Befehl an den "Harmony Hub", der dies in ein Infrarotsignal umsetzt. Via TCP/IP lässt sich der Hub auch direkt von FHEM aus steuern. Das relevante Reading des "Harmony Hub" trägt die Bezeichnung ''activity'', setzbar sind z.B. die Werte ''activity'' und ''channel''.

=== Fenstersensor ===
Ein Fenstersensor liefert für sein ''reading'' state die Werte open oder closed. Homekit unterstützt einen Service "ContactSensor", der allerdings andere Datenwerte kennt. Das Mapping lautet in diesem Fall
attr <meinSensor> homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

=== Temperatur- und Feuchtesensor ===
Kombinierte Temperatur-Feuchtesensoren haben in der Regel ''readings'' "humidity" und "temperature". Homekit unterstützt einen Service "HumiditySensor". Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):
<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:
attr <meinSensor> homebridgeMapping clear CurrentRelativeHumidity=humidity CurrentTemperature=temperature

[[Kategorie:Sprachsteuerung]]

FTUI Widget Chart

2017-03-22T11:46:49Z

Benheim: data-yticks_prio: Beispiel nutzte data-yticks ohne '_prio'

Das [[{{PAGENAME}}|Chart Widget]] ist ein Widget für [[FHEM Tablet UI]], mit dem sich verschiedenste Diagramme darstellen lassen. Die Aneinanderreihung mehrerer Werte eines Device-Readings zu einem zeitlichen Verlauf wird dabei als Graph bezeichnet.

Es können beliebige Werte dargestellt und entsprechend der Sinnhaftigkeit, oder persönlichem Geschmack, formatiert werden. Farbe und Form der Linien sind je Graph einstellbar, auch wenn mehrere gleichzeitig in einem Diagramm angezeigt werden.

Jedes Diagramm kann zwei Y-Achsen besitzen. Die primäre Y-Achse (primary) wird auf der linken Seite angezeigt, die sekundäre Y-Achse (secondary) auf der rechten Seite. Beide Achsen können unterschiedlich formatiert werden.

<gallery>
File:Chart_tabletUI.png
</gallery>

==Attribute==
{|class="wikitable"
! style="width:150px"|Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-device'''||Name des FHEM-Device, das die Aktualisierung des Charts triggert||||data-device="WohnzimmerHeizung"
|-
|'''data-get'''||Reading, das das Update des Diagramms triggert||'STATE'||
|-
|'''data-logdevice'''||Name des Log-Device, das dargestellt werden soll, oder ein Array, um mehrere Werte in einem Diagramm darzustellen||||data-logdevice="FileLog_WohnzimmerHeizung"
|-
|'''data-logfile'''|| Name des Log-Files, aus dem die Daten entnommen werden sollen (oder Array)||'-' = aktuelle Datei||data-logfile="WohnzimmerHeizung-2015.log"
|-
|'''data-columnspec'''||Ermittelt den Wert aus dem Log-File, der angezeigt werden soll (oder Array)||||data-columnspec="4:meas.*"
|-
|'''data-style'''||Stil, wie die Graph-Linien dargestellt werden sollen (z.B. 'SVGplot l0' oder 'ftui l0dash'), oder ein Array, wenn mehrere Linien unterschiedlich dargestellt werden sollen||||
|-
|'''data-ptype'''||Form, wie die Graphen dargestellt werden sollen (z.B. 'lines', 'cubic' oder 'fa-cog'), oder ein Array||'lines'||
|-
|'''data-uaxis'''||Name der Achse, die verwendet werden soll ('primary' = links, oder 'secondary' = rechts), oder ein Array||'primary'||
|-
|'''data-legend'''||Bezeichnung des Graphen (wird in Legende und am Cursor angezeigt), oder ein Array||||
|-
|'''data-minvalue'''||Minimaler Wert, der auf der linken Y-Achse ('primary') angezeigt werden soll. 'auto' = automatische Berechnung||'10'||
|-
|'''data-maxvalue'''||Maximaler Wert, der auf der linken Y-Achse ('primary') angezeigt werden soll. 'auto' = automatische Berechnung||'30'||
|-
|'''data-minvalue_sec'''||Minimaler Wert, der auf der rechten Y-Achse ('secondary') angezeigt werden soll. 'auto' = automatische Berechnung||'auto'||
|-
|'''data-maxvalue_sec'''||Maximaler Wert, der auf der rechten Y-Achse ('secondary') angezeigt werden soll. 'auto' = automatische Berechnung||'auto'||
|-
|'''data-xticks'''||Abstand zwischen den vertikalen Hilfslinien (bezogen auf die X-Achse) in Minuten. 'auto' = automatische Berechnung||'auto'||
|-
|'''data-yticks'''||Abstand zwischen den horizontalen Hilfslinien (bezogen auf die linke Y-Achse). Kann auch ein Array mit Werte-Paaren enthalten, um die Linien mit Text zu beschriften.||'auto'||data-yticks='[[0,"open"],[1,"closed"]]'
|-
|'''data-yticks_sec'''||Abstand zwischen den horizontalen Hilfslinien (bezogen auf die rechte Y-Achse). Kann auch ein Array mit Werte-Paaren enthalten, um die Linien mit Text zu beschriften.||'auto'||data-yticks='[[0,"open"],[1,"closed"]]'
|-
|'''data-yticks_prio'''||Legt fest, ob die horizontalen Hilfslinien der linken (primary) oder der rechten (secondary) Y-Achse zugeordnet werden sollen||||data-yticks_prio='secondary'
|-
|'''data-daysago_start'''||Anzahl der vergangenen Tage, wo das Diagramm beginnen soll. '0' = Beginn heute 0:00 Uhr. Es kann auch ein fixes Datum (z.B. '2013-10-23') angegeben werden. Uhrzeitangaben werden nur berücksichtigt, wenn '''data-nofulldays='true' ''' verwendet wird.||'0'||
|-
|'''data-daysago_end'''||Anzahl der vergangenen Tage, wo das Diagramm enden soll. '-1' = Ende heute 24:00 Uhr. Es kann auch ein fixes Datum (z.B. '2013-10-24') angegeben werden. Uhrzeitangaben werden nur berücksichtigt, wenn '''data-nofulldays='true' ''' verwendet wird.||'-1'||
|-
|'''data-nofulldays'''||Aktiviert/deaktiviert die Rundung der X-Achse auf ganze Tage. Binärwert ('true' oder 'false')||'false'||
|-
|'''data-timeformat'''||Zeitformat für die Anzeige an der X-Achse (siehe Hinweise)||||
|-
|'''data-ytext'''||Text, der neben der linken Y-Achse angezeigt wird||||
|-
|'''data-ytext_sec'''||Text, der neben der rechten Y-Achse angezeigt wird||||
|-
|'''data-yunit'''||Einheit, die an der linken Y-Achse angezeigt wird||||
|-
|'''data-yunit_sec'''||Einheit, die an der rechten Y-Achse angezeigt wird||||
|-
|'''data-crosshair'''||Aktiviert/deaktiviert den Fadenkreuz-Cursor. Binärwert ('true' oder 'false')||'false'||
|-
|'''data-cursorgroup'''||Zahl zur Gruppierung der Werte am Fadenkreuz-Cursor (siehe Hinweise)||||
|-
|'''data-scrollgroup'''||Zahl zur Gruppierung der Graphen beim Bewegen und Zoomen. Alle Linien mit der selben Zahl werden miteinander gekoppelt und bewegen sich gemeinsam.||||
|-
|'''data-showlegend'''||Aktiviert/deaktiviert die Anzeige der Legene. Binärwert ('true' oder 'false')||'false'||
|-
|'''data-legendpos'''||Array von zwei Werten, die die horizontale und vertikale Position der Legende festlegen (siehe Hinweise)||'["top","right"]'||
|-
|'''data-width'''||Breite des Diagramms (in % oder px)||||
|-
|'''data-height'''||Höhe des Diagramms (in % oder px)||||
|-
|'''data-graphsshown'''||Aktiviert/deaktiviert die initiale Anzeige von Graphen. Binärwert ('true' oder 'false'). Array, wenn mehrere Linien angezeigt werden sollen.||||
|-
|'''data-ddd'''||Einstellung für die 3D-Drehung (siehe Hinweise)||||data-ddd='["40","60","0"]'
|-
|'''data-dddspace'''||Abstand zwischen zwei Graphen, wenn die 3D-Anzeige aktiviert wurde (px)||'15'||
|-
|'''data-dddwidth'''||Breite, bzw. Tiefe der Graphen, wenn diese 3-dimensional angezeigt werden (px)||'10'||
|-
|'''data-title'''||Titel, der über dem Diagramm angezeigt werden soll. Der Inhalt kann auch dynamisch erzeugt werden (siehe Hinweise)||||
|}

==CSS Klassen==
{|class="wikitable"
!Klasse!!Beschreibung
{{FTUI Klasse|fullsize}}{{FTUI Klasse|noticks}}{{FTUI Klasse|nobuttons}}{{FTUI Klasse|small}}{{FTUI Klasse|normal}}{{FTUI Klasse|big}}
|}

Folgende Widget-spezifsche Klassen können zusätzlich in einer eigenen CSS-Datei definiert werden:

{|class="wikitable"
!Klasse
!Beschreibung
|-
|'''chart-background'''||Hintergrundfarbe des Diagramms
|-
|'''buttons'''||Größe und Farbe der Buttons
|-
|'''text.axes'''||Generelle Schriftart und Farbe der Achsen
|-
|'''gridlines'''||Generelle Farbe und Größe der Gitternetzlinien
|-
|'''xaxis'''||Schriftart, Größe und Farbe der X-Achse
|-
|'''yaxis'''||Schriftart, Größe und Farbe der Y-Achse
|-
|'''xticks'''||Schriftart, Größe und Farbe der X-Achse (Zwischenlinien)
|-
|'''yticks'''||Schriftart, Größe und Farbe der Y-Achse (Zwischenlinien)
|-
|'''crosshair'''||Schriftart, Größe und Vordergrund/Hintergrundfarbe der Momentanwerte am Fadenkreuzcursor
|-
|'''caption'''||Schriftart, Größe und Farbe der Text-Buttons für Legende und Cursor
|-
|'''legend'''||Schriftart, Größe und Farbe der Legende
|}

Die Standardwerte sind in der Datei <code>css/ftui_chart.css</code> zu finden.

==Datenquellen==
Beim Chart-Widget können die gleichen Datenquellen genutzt werden, die auch für SVG-Plots verwendet werden können:
# [[FileLog]]: Verlaufsdaten einer Textdatei entnehmen
# [[DbLog]]: Verlaufsdaten einer Datenbank entnehmen
# [[LogProxy]]: Daten dynamisch berechnet

===FileLog===
Um [[FileLog]] zu nutzen, wird als '''data-logdevice''' das FHEM-Device für das FileLog angegeben. In der Regel entstehen hier im Laufe der Zeit mehrere Log-Dateien. Name und Anzahl sind von der Definition abhängig - meist wird jeden Monat oder jedes Jahr eine neue Datei angelegt. Die gewünschte Datei kann mit '''data-logfile''' ausgewählt werden. Möchte man stets die aktuelle Datei verwenden (macht vor allem dann Sinn, wenn man die neusten Daten anzeigen will), kann das Attribut weggelassen, oder explizit <code>-</code> eingetragen werden. Zuletzt wird '''data-columnspec''' benötigt, um die gewünschten Daten zu in der Logdatei zu identifizieren. Hier wird die Spalte, in der die Daten stehen, gefolgt von Doppelpunkt und Readingname angegeben.

Für ein Heizungsthermostat von Homematic mit dem Namen ''DG.wz.HZ.Heizungsventil'' ergibt sich somit beispielhaft folgende Definition, um gemessene Temperatur, Sollwert und Ventilstellung im Diagramm darzustellen:

<source lang="html">
<div data-type="chart"
data-device="DG.wz.HZ.Heizungsventil"
data-logdevice="FileLog_DG.wz.HZ.Heizungsventil"
data-logfile="-"
data-columnspec='["4:measured-temp","4:desired-temp","4:actuator"]'
...>
</div>
</source>

Sollen Daten von unterschiedlichen Geräten in einem Diagramm angezeigt werden, muss '''data-logdevice''' als Array nach dem Schema <code>data-logdevice='["<Logdatei_1>","<Logdatei_2>","<Logdatei_3>"]'</code> definiert werden. Für jeden Eintrag in '''data-columnspec''' muss es auch den passenden Eintrag in '''data-logdevice''' geben (auch die Reihenfolge ist relevant).

===DbLog===
Um die Daten aus [[DbLog]] anzeigen zu können, werden die gleichen Attribute verwendet und mit für die Datenbank angepassten Werten beschrieben. Bei '''data-logdevice''' das FHEM-Device für die Datenbank angegeben. Im nachfolgenden Beispiel heißt diese <code>logdb</code> und besitzt wie üblich zwei Tabellen: <code>current</code> und <code>history</code> (der zeitliche Verlauf liegt in letzterer). Der Tabellenname wird bei '''data-logfile''' eingetragen. Da die Daten in der Datenbank etwas anders abgelegt werden, muss auch '''data-columnspec''' entsprechend angepasst werden. Statt der Spalte wird hier das FHEM-Device, gefolgt von Doppelpunkt und Readingname angegeben.

Für das oben beschriebene Homematic-Heizungsthermostat ergibt sich dann folgende Definition, um die gleichen Daten aus einer Datenbank, statt einem LogFile zu lesen:

<source lang="html">
<div data-type="chart"
data-device="DG.wz.HZ.Heizungsventil"
data-logdevice="logdb"
data-logfile="HISTORY"
data-columnspec='["DG.wz.HZ.Heizungsventil:measured-temp","DG.wz.HZ.Heizungsventil:desired-temp","DG.wz.HZ.Heizungsventil:actuator"]'
...>
</div>
</source>

Für die Anzeige von unterschiedlichen Geräten in einem Diagramm, muss nur '''data-columnspec''' entsprechend angepasst werden, solange sich alle Daten in der Datenbank befinden.

===LogProxy===
Um die Daten mittels [[LogProxy]] berechnen und anzeigen zu können, muss in FHEM ein LogProxy-Device definiert sein:

<pre>
define myLogProxy logProxy
</pre>

Weitere Einstellungen am LogProxy sind nicht nötig, die bloße Existenz reicht.

Bei '''data-logdevice''' wird das FHEM-Device für den LogProxy angegeben. Im nachfolgenden Beispiel heißt dieses <code>myLogProxy</code>. Das Attribut '''data-logfile''' wird für LogProxy nicht benötigt. Befinden sich nur LogProxy-Werte im Diagramm kann das Attribut komplett entfallen. Sollen weitere Werte angezeigt werden, bleibt die Definition im Array einfach leer.

Im Attribut '''data-columnspec''' wird eine Formel angegeben, wie die Werte berechnet werden sollen. Hier können die Formeln 1:1 von einem eventuell vorhandenen SVG-Plot übernommen werden. '''Dabei gibt es jedoch folgendes zu beachten:''' Befindet sich die Formel in einem Array, dürfen die Formeln keine Anführungszeichen (<code>"</code>) beinhalten. Stattdessen müssen sie als escapter Ascii-Code (<code>\\x22</code>) eingefügt werden.

Das nachfolgende Beispiel zeigt, wie Vorhersagewerte aus einem FHEM-Device vom Typ Proplanta (Name hier <code>AU.xx.WE.Proplanta</code>) angezeigt werden können.

<source lang="html">
<div data-type="chart"
data-device="AU.xx.WE.Proplanta"
data-logdevice='[
"myLogProxy",
"myLogProxy",
"myLogProxy",
"myLogProxy"
]'
data-columnspec='[
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22temp_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22rain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22chOfRain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22cloud_\\x22,$from,$to,12,\\x22day\\x22)"
]'
...>
</div>
</source>

'''Auch alle anderen Funktionen, die [[LogProxy]] bietet, können hier angewendet werden.'''

==Hinweise==
===Aktualisierung des Charts===
Damit der Refresh des Charts funktioniert, muss auch ein Device angegeben werden, der das Refresh triggert. Das Diagramm wird immer dann aktualisiert, wenn sich der Inhalt von '''data-get''' ändert.

<source lang="html">
<div data-type="chart"
data-device="WohnzimmerHeizung"
data-logdevice="FileLog_WohnzimmerHeizung"
...>
</div>
</source>

===Aussehen der Linien===
Mit dem Attribut '''data-style''' kann das Aussehen der Linien des jeweiligen Graphen verändert werden. Hierfür können die Standard-FHEM-Styles verwendet werden. Dazu wird das Attribut mit <code>SVGplot</code>, gefolgt von einem Leerzeichen und der gewünschten Farbe/Stil befüllt. Es existieren jedoch auch noch weitere, an FTUI angepasste Styles, zu finden in der CSS-Datei <code>css/ftui_chart.css</code>. Um diese zu verwenden, wird das Attribut mit <code>ftui</code>, gefolgt von einem Leerzeichen und der gewünschten Farbe/Stil befüllt. Eigene Styles können zum Beispiel in der Datei <code>css/fhem-table-ui-user.css</code> definiert werden.

Folgende Übersicht zeigt die im Standard verfügbaren '''Farben''', alle Abbildungen sind mit im FTUI-Style entstanden:
<div><ul>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f0.png|thumb|none|150px|Farbe "l0"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f1.png|thumb|none|150px|Farbe "l1"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f2.png|thumb|none|150px|Farbe "l2"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f3.png|thumb|none|150px|Farbe "l3"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f4.png|thumb|none|150px|Farbe "l4"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f5.png|thumb|none|150px|Farbe "l5"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f6.png|thumb|none|150px|Farbe "l6"]] </li>
</ul></div>

Die Angabe zur Farbe kann dann mit der Linienart kombiniert werden. Dazu stehen folgende '''Stile''' zur Verfügung:
<div><ul>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-normal.png|thumb|none|225px|Darstellung in 2D: Stil "normal"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-dot.png|thumb|none|225px|Darstellung in 2D: Stil "dot"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-dash.png|thumb|none|225px|Darstellung in 2D: Stil "dash"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-fill.png|thumb|none|225px|Darstellung in 2D: Stil "fill"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-sym.png|thumb|none|225px|Darstellung in 2D: Stil "sym"]] </li>
</ul></div>

<div><ul>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-normal.png|thumb|none|225px|Darstellung in 3D: Stil "normal"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-dot.png|thumb|none|225px|Darstellung in 3D: Stil "dot"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-dash.png|thumb|none|225px|Darstellung in 3D: Stil "dash"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-fill.png|thumb|none|225px|Darstellung in 3D: Stil "fill"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-sym.png|thumb|none|225px|Darstellung in 3D: Stil "sym"]] </li>
</ul></div>

Farbe und Stil werden kombiniert (zusammengeschrieben) beim Attribut '''data-style''' angegeben, sodass sich beispielsweise für eine graue Punktlinie folgendes ergibt: <code>data-style="ftui l1dot"</code>.
Um die Darstellung als normale Linie zu erhalten, darf im Gegensatz zu den anderen Linienformen der Stil <code>normal</code> nicht angegeben werden. Für eine einfache graue Linie ist also die Angabe <code>data-style="ftui l1"</code> korrekt, wohingegen <code>data-style="ftui l1normal"</code> zu einer fehlerhaften Anzeige führt.

'''Hinweis:''' Der Stil ''sym'' ist speziell dafür geeignet, Symbole statt Linien zu zeichnen. Dazu kann beim Attribut '''data-ptype''' als Linienform ein beliebiges Font-Awsome-, oder Open Automation-Icon angegeben werden. Alle in diesem Abschnitt enthaltenen Abbildungen sind mit <code>data-ptype="lines"</code> entstanden.

===Form der Linien===
Das Attribut '''data-ptype''' beeinflusst die Form der Linien. Hier sind folgende Werte möglich:

* <code>lines</code>
* <code>steps</code>
* <code>fsteps</code>
* <code>histeps</code>
* <code>bars</code>
* <code>ibars</code>
* <code>cubic</code>
* <code>quadratic</code>
* <code>quadraticSmooth</code>

Zusätzlich ist es möglich, Symbole anzeigen zu lassen. Unterstützt werden Font-Awesome ('fa-...'), Open Automation ('oa-...') und FHEM-Symbole ('fs-...')). Damit die Symbole korrekt angezeigt werden, muss im Attribut '''data-style''' der Stil <code>sym</code> gewählt werden, da sonst nur Punkte, statt der Symbole gezeichnet werden.

<source lang="html">
<div data-type="chart"
data-device="DG.wz.HZ.Heizungsventil"
data-logdevice="FileLog_DG.wz.HZ.Heizungsventil"
...
data-style="ftui l1sym"
data-ptype="fa-cog"
...>
</div>
</source>

Die Größe der Symbole ist in der Datei <code>css/ftui_chart.css</code> auf 12px festgelegt. Dieser Wert kann in einer eigenen CSS-Datei durch Anpassung von <code>stroke-width</code> überschrieben werden.

<source lang="css">
.ftui.l0sym { stroke:#DDA400; stroke-width:12px; fill:none; }
.ftui.l1sym { stroke:#BBBBBB; stroke-width:12px; fill:none; }
.ftui.l2sym { stroke:#CC0000; stroke-width:12px; fill:none; }
.ftui.l3sym { stroke:#CCCC00; stroke-width:12px; fill:none; }
.ftui.l4sym { stroke:#33CC33; stroke-width:12px; fill:none; }
.ftui.l5sym { stroke:#33CCCC; stroke-width:12px; fill:none; }
.ftui.l6sym { stroke:#3333CC; stroke-width:12px; fill:none; }
</source>

'''data-ptype''' kann auch Inhalt im Format <code>'icon:1'</code> verarbeiten. Dann muss der zugehörige Wert in '''data-columnspec''' den Pfad zu einem Icon (z.B. für Wettervorhersagen) beinhalten. Der Y-Wert wird dann vom ersten Graphen übernommen. Weitere Ausführungen hierzu im Beispiel [[#Darstellung der Wetter Icons im Diagramm]]

===Zeitformat der X-Achse===
Die Zeitanzeige auf der X-Achse kann sehr flexibel eingestellt werden. Dafür stehen verschiedene Platzhalter zur Verfügung, die durch spezielle Zeichen (<code>-</code>, <code>.</code>, <code>/</code>, <code> </code> (Leerzeichen), <code>:</code>, <code>,</code>, <code>\</code>) getrennt werden. Alle Zeichen werden trotz Escape-Zeichen (<code>\</code>) in der Ausgabe angezeigt.

Folgende Platzhalter werden unterstützt:
*<code>'mm'</code>: Minuten als zweistellige Zahl
*<code>'hh'</code>: Stunden als zweistellige Zahl
*<code>'dd'</code>: Tag als zweistellige Zahl (Kalenderdatum)
*<code>'MM'</code>: Monat als zweistellige Zahl (z.B. 02 für Februar)
*<code>'MMM'</code>: Monat als dreistellige Abkürzung (z.B. Dec für Dezember)
*<code>'MMMM'</code>: Langname des Monats (z.B. March)
*<code>'ee'</code>: Wochentag als zweistellige Zahl (z.B. 00 für Sonntag)
*<code>'eee'</code>: Wochentag als dreistellige Abkürzung (z.B. Mon für Montag)
*<code>'eeee'</code>: Langname des Wochentags (z.B. Tuesday)
*<code>'yy'</code>: Jahr als zweistellige Zahl (z.B. 16 für 2016)
*<code>'yyyy'</code>: Jahr als vierstellige Zahl (z.B. 2016)
*<code>'LF'</code>: Fügt einen Zeilenumbruch hinzu

Beispiel: Der String <code>'MMM\LF\yyyy'</code> zeigt <code>'Jan'</code> in der ersten, und <code>'2016'</code> in der zweiten Zeile. <code>'MM.dd 2016'</code> wird zu <code>'03.05 2016'</code>.

===Fadenkreuz-Cursor===
Der Fadenkreuz-Cursor zeigt die Momentanwerte, indem man ihn über die Graphen bewegt. In Desktop-Browsern reicht einfaches Bewegen des Maus. Unter iOS und Android kann der Cursor wird der Cursor durch einfaches Tippen auf die neue Position bewegt.

Mit dem Attribut '''data-cursorgroup''' können Graphen gruppiert werden. Am Cursor werden dann die Momentanwerte aller Graphen gleichzeitig angezeigt, die die selbe Zahl besitzen, sobald man die Maus über einen aus der Gruppe bewegt.

===Legende===
Mit dem Attribut '''data-legendpos''' kann die Position der Legende innerhalb des Diagramms festgelegt werden. Die Position wird mit einem Array, bestehend aus zwei Werten im Format <code>'["<horizontal>","<vertikal>"]'</code> angegeben. Für die horizontale Positionierung sind <code>'left'</code> und <code>'right'</code>, die vertikale Positionierung <code>'top'</code> und <code>'bottom'</code> erlaubt. Alternativ können auch Zahlen verwendet werden, die die Position in Prozent angeben. Durch verschieben mit der Maus oder durch verschieben mit dem Finger oder Stift auf Touch Devices kann die Legende auch an eine andere Position verschoben werden.

Wenn die Legende eingeblendet ist, kann mittels Klick auf einen Legendeneintrag der zugehörige Graph ein- und ausgeblendet werden.

===3-dimensionale Drehung===
'''data-ddd''' ermöglicht, den Graphen 3-dimensional zu drehen. Als Wert wird ein Array mit den 3 Winkeln für x, y und z erwartet, wobei z selbst bisher nicht unterstützt wird.

Beispiel: <code>data-ddd='["40","60","0"]'</code>.

Wenn der 3D Modus aktiv ist ('''data-ddd''' gesetzt) sind 2 zusätzliche Parameter verfügbar um das Aussehen der Graphen zu beeinflussen. '''data-dddspace''' gibt an, wie viele pixel der Raum zwischen den einzelnen in z-Richtung hintereinander angeordneten Graphen betragen soll.
'''data-dddwidth''' legt fest, wie viele pixel die einzelnen Graphen tief (oder dick) sein sollen.

Wenn das Array angegeben wird, erscheinen zwei zusätzliche Buttons im Diagramm, mit denen die Drehung in X- und Y-Richtung verändert werden kann.

===Diagrammtitel===
Mit dem Attribut '''data-title''' kann dem Diagramm, ähnlich wie in FHEM-SVG-Plots, ein Titel hinzugefügt werden.

Folgende Platzhalter werden unterstützt:
*<code>'min1'</code>: Minimaler Y-Wert des ersten Graphs
*<code>'max1'</code>: Maximaler Y-Wert des ersten Graphs
*<code>'avg1'</code>: Mittlerer Y-Wert des ersten Graphs
*<code>'cnt1'</code>: Anzahl der dargestellten Einzelwerte im ersten Graph
*<code>'currval1'</code>: Letzter, bzw. aktuellster Y-Wert des ersten Graphs
*<code>'mindate1'</code>: Niedrigster Wert auf der X-Achse des ersten Graphs
*<code>'maxdate1'</code>: Höchster Wert auf der X-Achse vom ersten Graphs
*<code>'currdate1'</code>: Letzter, bzw. aktuellster Wert auf der X-Achse des ersten Graphs

Durch Einsetzen einer anderen Zahl statt '1' können auch die Werte der anderen Graphen angezeigt werden. Das Weglassen der Zahl bewirkt, dass der jeweils zutreffende Wert automatisch ermittelt wird. Bedeutet: <code>max</code> führt dazu, dass der höchste Wert aller angezeigter Graphen verwendet wird.

Beispiel: <code>data-title="Min: $data{mindate4}, Max: $data{maxdate4}, Last: $data{currdate4}"</code>

===Buttons im Diagramm===
Es gibt mehrere Buttons, mit denen sich die Anzeige des Diagramms verändern lässt. <code><-</code> und <code>-></code> bewegen die Graphen nach links und rechts. <code>+</code> und <code>-</code> zoomen die Anzeige. <code>legend</code> und <code>cursor</code> schalten die zugehörigen Anzeigen ein und aus.

==Beispiele==
===Einfaches Diagramm===
Das Beispiel zeigt ein einfaches Diagramm mit 4 unterschiedlich formatierten Graphen, Legende und Momentanwerten am Fadenkreuz-Cursor.

[[File:Chart_tabletUI.png]]

<source lang="html">
<div data-type="chart"
data-logdevice='["Log.Garden","Log.Garden","Log.Garden","Log.Predicted"]'
data-columnspec='["4:Garden.T:15:","10:Garden.T:0:delta-h","10:Garden.T:0:delta-d","4:predicted.*:15:"]'
data-style='["ftui l0fill","ftui l1fill","ftui l2","ftui l3dot"]'
data-ptype='["lines","histeps","histeps","cubic"]'
data-uaxis='["primary","secondary","secondary","primary"]'
data-legend='["Temperature","Rain/hour","Rain/day","Predicted Temp."]'
data-yunit="°C"
data-ytext="Temperature"
data-minvalue="auto"
data-maxvalue="auto"
data-yunit_sec="mm"
data-ytext_sec="Rain (mm)"
data-height="250"
data-yticks="auto"
data-minvalue_sec="auto"
data-maxvalue_sec="auto"
data-nofulldays="true"
data-daysago_start="2013-08-13T00:00:00"
data-daysago_end="2013-08-14T00:00:00"
data-cursorgroup="1"
data-scrollgroup="1"
data-xticks="auto">
</div>
</source>

===7-Tage-Wettervorhersage mit Proplanta===
In diesem Beispiel wird gezeigt, wie die Vorhersagewerte von [[PROPLANTA]] in einem Diagramm dargestellt werden können. Da die Werte nicht in einer Datenbank oder einem FileLog vorliegen, müssen sie über [[LogProxy]] verarbeitet werden. Dafür sind einige Vorbereitungen in FHEM nötig.

[[File:FTUI_Widget_Chart-fc-Proplanta.png|941px]]

'''1.''' Ein LogProxy-Device muss vorhanden sein:
<pre>
define myLogProxy logProxy
</pre>

'''2.''' In der Datei <code>99_myUtils.pm</code> muss folgende Routine hinzugefügt werden, die die Daten bereitstellt:
<source lang="perl">
#---------------------------------------
# Proplanta LogProxy-Funktion
#---------------------------------------
sub logProxy_proplanta2Plot($$$$;$$) {
my ($device, $fcValue, $from, $to, $fcHour, $expMode) = @_;
my $regex;
my @rl;

return undef if(!$device);

if($fcValue =~ s/_$//) {
$regex = "^fc[\\d]+_".$fcValue."[\\d]{2}\$";
}
else {
$regex = "^fc[\\d]+_".$fcValue."\$";
}

$fcHour = 12 if(!defined $fcHour);
$expMode = "point" if(!defined $expMode);

if( defined($defs{$device}) ) {
if( $defs{$device}{TYPE} eq "PROPLANTA" ) {
@rl = sort{
my ($an) = ($a =~ m/fc(\d+)_.*/);
my ($bn) = ($b =~ m/fc(\d+)_.*/);
$an <=> $bn or $a cmp $b;
}( grep /${regex}/,keys %{$defs{$device}{READINGS}} );
return undef if( !@rl );
} else {
Log3 undef, 2, "logProxy_proplanta2Plot: $device is not a PROPLANTA device";
return undef;
}
}

my $fromsec = SVG_time_to_sec($from);
my $tosec = SVG_time_to_sec($to);
my $sec = $fromsec;
my ($h,$fcDay,$mday,$mon,$year);
my $timestamp;

my $reading;
my $value;
my $prev_value;
my $min = 999999;
my $max = -999999;
my $ret = "";

# while not end of plot range reached
while(($sec < $tosec) && @rl) {
#remember previous value for start of plot range
$prev_value = $value;

$reading = shift @rl;
($fcDay) = $reading =~ m/^fc(\d+).*/;
$h = ($reading =~ m/.*(\d\d)$/)?$1:$fcHour;
$value = ReadingsVal($device,$reading,undef);

($mday,$mon,$year) = split('\.',ReadingsVal($device,"fc".$fcDay."_date",undef));
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, $h, 0, 0);
$sec = SVG_time_to_sec($timestamp);

# skip all values before start of plot range
next if( SVG_time_to_sec($timestamp) < $fromsec );

# add first value at start of plot range
if( !$ret && $prev_value ) {
$min = $prev_value if( $prev_value < $min );
$max = $prev_value if( $prev_value > $max );
$ret .= "$from $prev_value\n";
}

# done if after end of plot range
last if($sec > $tosec);

$min = $value if( $value < $min );
$max = $value if( $value > $max );

# add actual controll point
$ret .= "$timestamp $value\n";

# Log 1, "$timestamp $value -0- $reading";
}
if(($sec < $tosec) && !@rl && ($expMode eq "day")) {
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, 23, 59, 59);
if(SVG_time_to_sec($timestamp) < $tosec) {
$ret .= "$timestamp $value\n";
}
else {
$ret .= "$to $value\n";
}
}
elsif(($sec > $tosec) && ($expMode eq "day")) {
$value = $prev_value + ($value - $prev_value)*(86400 + ($tosec - $sec))/86400;
$ret .= "$to $value\n";
}
return ($ret,$min,$max,$prev_value);
}
</source>

Anschließend können die Daten im Chart-Widget angezeigt werden. Der Device-Name von Proplanta heißt hier im Beispiel <code>AU.xx.WE.Proplanta</code>.

<source lang="html">
<div data-type="chart"
data-device="AU.xx.WE.Proplanta"
data-logdevice='[
"myLogProxy",
"myLogProxy",
"myLogProxy"
]'
data-columnspec='[
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22rain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22chOfRain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22cloud_\\x22,$from,$to,12,\\x22day\\x22)"
]'
data-style='[
"ftui l6fill",
"ftui l5fill",
"ftui l1fill"
]'
data-ptype='[
"steps",
"quadraticSmooth",
"quadraticSmooth"
]'
data-uaxis='[
"primary",
"secondary",
"secondary"
]'
data-legend='[
"Regen",
"Regenwahrscheinlichkeit",
"Wolken"
]'
data-yunit="mm"
data-ytext="Regen"
data-yunit_sec="%"
data-ytext_sec="Chance auf Regen / Wolken"
data-timeformat="eeee"
data-minvalue="auto"
data-maxvalue="auto"
data-minvalue_sec="auto"
data-maxvalue_sec="auto"
data-daysago_start = "0"
data-daysago_end = "-7"
data-xticks="1440"
data-yticks="auto"
data-title="7-Tage-Wettervorhersage"
data-showlegend="true"
class="nobuttons fullsize">
</div>
</source>

'''Hilfreiche Links und Quellen zu diesem Beispiel:'''
*[[LogProxy|LogProxy im FHEM-Wiki]]
*{{Link2Forum|Topic=22967|Message=246973|LinkText=Stundengenaue Wettervorhersage (#1) im FHEM-Forum}}
*{{Link2Forum|Topic=22967|Message=334713|LinkText=Stundengenaue Wettervorhersage (#2) im FHEM-Forum}}

===Darstellung der Wetter Icons im Diagramm===

[[File:Wetterchart2.png]]

Wie oben bereits beschrieben, gibt es beim Chart grundsätzlich die Möglichkeit, Icons, welche in Form von URLs in den Logs abgelegt sind oder welche per logProxy generiert werden, darzustellen. Die Icons werden auf genau dem gleichen Weg von FHEM gelesen, wie alle anderen Datenpunkte. Im Folgenden wird ein Beispiel gezeigt, mit dem die im Proplanta Modul als Readings abgelegten Icons per logProxy Funktion gelesen und in ein Chart eingebaut werden könnnen.
Da es beim Proplanta Modul für die ersten 7 Tage nicht das Reading <code>fc#_weatherIcon</code> gibt, sondern mehrere Readings für unterschiedliche Tageszeiten wogegen für die zweiten 7 Tage ausschließlich das Reading <code>fc#_weatherIcon</code> vorhanden ist, sollte per <code>attr device userReading</code> mit folgendem Eintrag dafür gesorgt werden, dass für alle Tage ein Reading <code>fc#_weatherIcon</code> vorhanden ist (alternativ könnten auch 2 Graphen gezeichnet werden, wobei der erste dann nur die ersten 7 Tage enthält und der zweite die letzen 7 Tage, will man nur die ersten 7 Tage darstellen braucht man das userReading nicht unbedingt).
<source lang="perl">
fc0_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc0_weatherDayIcon","");},
fc1_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc1_weatherDayIcon","");},
fc2_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc2_weatherDayIcon","");},
fc3_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc3_weatherDayIcon","");},
fc4_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc4_weatherDayIcon","");},
fc5_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc5_weatherDayIcon","");},
fc6_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc6_weatherDayIcon","");}
</source>
Um die Icons darzustellen muss ein zusätzlicher Graph definiert werden. Dieser nutzt neben der Columnspec, die die URLs abruft den Parameter <code>data-ptype="icons:#"</code> (# ist eine Zahl und steht für die Nummer, beginnend bei 0 des Graphen, welcher für die y-Position der Icons verwendet werden soll) und den Stil <code>sym</code>. Der Wert für die Symbolgröße sollte z.B. durch eine zusätzliche Definition im File fhem-tablet-ui-user.css in der Form:
<source lang="css">
/* icon lines */
.ftui.l99icon { stroke:#DDA400; stroke-width:48px; fill:none; }
</source>
angepasst werden.

Im folgenden ein Beispiel, welches eine Linie für die Maximale Tagestemperatur zeichnet und auf dieser Linie die Wetter Icons darstellt.
<source lang="html">
<div data-type="chart"
data-device="AU.xx.WE.Proplanta"
data-logdevice='[
"myLogProxy",
"myLogProxy"
]'
data-columnspec='[
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22weatherIcon\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22tempMax\\x22,$from,$to,12,\\x22day\\x22)",
]'
data-style='[
"ftui l99icon",
"ftui l1fill"
]'
data-ptype='[
"icons:1",
"quadraticSmooth"
]'
data-uaxis='[
"primary",
"primary"
]'
data-legend='[
"Wetterbedingung",
"Max. Temperature"
]'
data-yunit="°C"
data-ytext="Temperature (°C)"
data-timeformat="ee\LF\dd.MM"
data-minvalue="auto"
data-maxvalue="auto"
data-minvalue_sec="auto"
data-maxvalue_sec="auto"
data-daysago_start="-1w"
data-y_margin="20"
data-daysago_end="-3w"
data-xticks="1440"
data-yticks="auto"
data-title="14-Tage-Wettervorhersage"
data-showlegend="true"
class="nobuttons fullsize">
</div>
</source>

===Fensterstatus offen/geschlossen===
Dieses Beispiel zeigt, wie ein Fensterkontakt, dessen Reading die Werte <code>closed</code> und <code>open</code> einnimmt, als Graph gezeichnet werden kann. Technisch gesehen werden hier die Werte <code>0</code> und <code>1</code> gezeichnet, indem über das Attribut '''data-columnspec''' dem Zustand <code>open</code> der Wert <code>1</code> und allen anderen Zuständen der Wert <code>0</code> zugeordnet wird. Über das Attribut '''data-yticks''' wird die Beschriftung an der Y-Achse (<code>0</code> und <code>1</code>) gegen einen frei definierbaren Text ausgetauscht.

<source lang="html">
<div data-type="chart"
data-device="wz_fensterstatus"
data-logdevice='["myDbLog"]'
data-logfile='["HISTORY"]'
data-columnspec='["wz_fensterstatus:state:0::$val=($val=~\\x22open\\x22?1:0)"]'
data-style='["ftui l4fill"]'
data-ptype='["steps"]'
data-height="290"
data-yticks='[[0,"geschlossen"],[1,"offen"]]'
data-minvalue="0"
data-maxvalue="1.1"
data-nofulldays="true"
data-daysago_start="1"
data-daysago_end="-1"
data-cursorgroup="1"
data-scrollgroup="1">
</div>
</source>

==Links==
{{Link2Forum|Topic= 48450 |Message=401006|LinkText=Thread im FHEM-Forum}}

[[Kategorie:FHEM Tablet UI]]

FTUI Widget Chart

2017-03-22T11:06:36Z

Benheim: Tippfehler korrigiert

Das [[{{PAGENAME}}|Chart Widget]] ist ein Widget für [[FHEM Tablet UI]], mit dem sich verschiedenste Diagramme darstellen lassen. Die Aneinanderreihung mehrerer Werte eines Device-Readings zu einem zeitlichen Verlauf wird dabei als Graph bezeichnet.

Es können beliebige Werte dargestellt und entsprechend der Sinnhaftigkeit, oder persönlichem Geschmack, formatiert werden. Farbe und Form der Linien sind je Graph einstellbar, auch wenn mehrere gleichzeitig in einem Diagramm angezeigt werden.

Jedes Diagramm kann zwei Y-Achsen besitzen. Die primäre Y-Achse (primary) wird auf der linken Seite angezeigt, die sekundäre Y-Achse (secondary) auf der rechten Seite. Beide Achsen können unterschiedlich formatiert werden.

<gallery>
File:Chart_tabletUI.png
</gallery>

==Attribute==
{|class="wikitable"
! style="width:150px"|Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-device'''||Name des FHEM-Device, das die Aktualisierung des Charts triggert||||data-device="WohnzimmerHeizung"
|-
|'''data-get'''||Reading, das das Update des Diagramms triggert||'STATE'||
|-
|'''data-logdevice'''||Name des Log-Device, das dargestellt werden soll, oder ein Array, um mehrere Werte in einem Diagramm darzustellen||||data-logdevice="FileLog_WohnzimmerHeizung"
|-
|'''data-logfile'''|| Name des Log-Files, aus dem die Daten entnommen werden sollen (oder Array)||'-' = aktuelle Datei||data-logfile="WohnzimmerHeizung-2015.log"
|-
|'''data-columnspec'''||Ermittelt den Wert aus dem Log-File, der angezeigt werden soll (oder Array)||||data-columnspec="4:meas.*"
|-
|'''data-style'''||Stil, wie die Graph-Linien dargestellt werden sollen (z.B. 'SVGplot l0' oder 'ftui l0dash'), oder ein Array, wenn mehrere Linien unterschiedlich dargestellt werden sollen||||
|-
|'''data-ptype'''||Form, wie die Graphen dargestellt werden sollen (z.B. 'lines', 'cubic' oder 'fa-cog'), oder ein Array||'lines'||
|-
|'''data-uaxis'''||Name der Achse, die verwendet werden soll ('primary' = links, oder 'secondary' = rechts), oder ein Array||'primary'||
|-
|'''data-legend'''||Bezeichnung des Graphen (wird in Legende und am Cursor angezeigt), oder ein Array||||
|-
|'''data-minvalue'''||Minimaler Wert, der auf der linken Y-Achse ('primary') angezeigt werden soll. 'auto' = automatische Berechnung||'10'||
|-
|'''data-maxvalue'''||Maximaler Wert, der auf der linken Y-Achse ('primary') angezeigt werden soll. 'auto' = automatische Berechnung||'30'||
|-
|'''data-minvalue_sec'''||Minimaler Wert, der auf der rechten Y-Achse ('secondary') angezeigt werden soll. 'auto' = automatische Berechnung||'auto'||
|-
|'''data-maxvalue_sec'''||Maximaler Wert, der auf der rechten Y-Achse ('secondary') angezeigt werden soll. 'auto' = automatische Berechnung||'auto'||
|-
|'''data-xticks'''||Abstand zwischen den vertikalen Hilfslinien (bezogen auf die X-Achse) in Minuten. 'auto' = automatische Berechnung||'auto'||
|-
|'''data-yticks'''||Abstand zwischen den horizontalen Hilfslinien (bezogen auf die linke Y-Achse). Kann auch ein Array mit Werte-Paaren enthalten, um die Linien mit Text zu beschriften.||'auto'||data-yticks='[[0,"open"],[1,"closed"]]'
|-
|'''data-yticks_sec'''||Abstand zwischen den horizontalen Hilfslinien (bezogen auf die rechte Y-Achse). Kann auch ein Array mit Werte-Paaren enthalten, um die Linien mit Text zu beschriften.||'auto'||data-yticks='[[0,"open"],[1,"closed"]]'
|-
|'''data-yticks_prio'''||Legt fest, ob die horizontalen Hilfslinien der linken (primary) oder der rechten (secondary) Y-Achse zugeordnet werden sollen||||data-yticks='secondary'
|-
|'''data-daysago_start'''||Anzahl der vergangenen Tage, wo das Diagramm beginnen soll. '0' = Beginn heute 0:00 Uhr. Es kann auch ein fixes Datum (z.B. '2013-10-23') angegeben werden. Uhrzeitangaben werden nur berücksichtigt, wenn '''data-nofulldays='true' ''' verwendet wird.||'0'||
|-
|'''data-daysago_end'''||Anzahl der vergangenen Tage, wo das Diagramm enden soll. '-1' = Ende heute 24:00 Uhr. Es kann auch ein fixes Datum (z.B. '2013-10-24') angegeben werden. Uhrzeitangaben werden nur berücksichtigt, wenn '''data-nofulldays='true' ''' verwendet wird.||'-1'||
|-
|'''data-nofulldays'''||Aktiviert/deaktiviert die Rundung der X-Achse auf ganze Tage. Binärwert ('true' oder 'false')||'false'||
|-
|'''data-timeformat'''||Zeitformat für die Anzeige an der X-Achse (siehe Hinweise)||||
|-
|'''data-ytext'''||Text, der neben der linken Y-Achse angezeigt wird||||
|-
|'''data-ytext_sec'''||Text, der neben der rechten Y-Achse angezeigt wird||||
|-
|'''data-yunit'''||Einheit, die an der linken Y-Achse angezeigt wird||||
|-
|'''data-yunit_sec'''||Einheit, die an der rechten Y-Achse angezeigt wird||||
|-
|'''data-crosshair'''||Aktiviert/deaktiviert den Fadenkreuz-Cursor. Binärwert ('true' oder 'false')||'false'||
|-
|'''data-cursorgroup'''||Zahl zur Gruppierung der Werte am Fadenkreuz-Cursor (siehe Hinweise)||||
|-
|'''data-scrollgroup'''||Zahl zur Gruppierung der Graphen beim Bewegen und Zoomen. Alle Linien mit der selben Zahl werden miteinander gekoppelt und bewegen sich gemeinsam.||||
|-
|'''data-showlegend'''||Aktiviert/deaktiviert die Anzeige der Legene. Binärwert ('true' oder 'false')||'false'||
|-
|'''data-legendpos'''||Array von zwei Werten, die die horizontale und vertikale Position der Legende festlegen (siehe Hinweise)||'["top","right"]'||
|-
|'''data-width'''||Breite des Diagramms (in % oder px)||||
|-
|'''data-height'''||Höhe des Diagramms (in % oder px)||||
|-
|'''data-graphsshown'''||Aktiviert/deaktiviert die initiale Anzeige von Graphen. Binärwert ('true' oder 'false'). Array, wenn mehrere Linien angezeigt werden sollen.||||
|-
|'''data-ddd'''||Einstellung für die 3D-Drehung (siehe Hinweise)||||data-ddd='["40","60","0"]'
|-
|'''data-dddspace'''||Abstand zwischen zwei Graphen, wenn die 3D-Anzeige aktiviert wurde (px)||'15'||
|-
|'''data-dddwidth'''||Breite, bzw. Tiefe der Graphen, wenn diese 3-dimensional angezeigt werden (px)||'10'||
|-
|'''data-title'''||Titel, der über dem Diagramm angezeigt werden soll. Der Inhalt kann auch dynamisch erzeugt werden (siehe Hinweise)||||
|}

==CSS Klassen==
{|class="wikitable"
!Klasse!!Beschreibung
{{FTUI Klasse|fullsize}}{{FTUI Klasse|noticks}}{{FTUI Klasse|nobuttons}}{{FTUI Klasse|small}}{{FTUI Klasse|normal}}{{FTUI Klasse|big}}
|}

Folgende Widget-spezifsche Klassen können zusätzlich in einer eigenen CSS-Datei definiert werden:

{|class="wikitable"
!Klasse
!Beschreibung
|-
|'''chart-background'''||Hintergrundfarbe des Diagramms
|-
|'''buttons'''||Größe und Farbe der Buttons
|-
|'''text.axes'''||Generelle Schriftart und Farbe der Achsen
|-
|'''gridlines'''||Generelle Farbe und Größe der Gitternetzlinien
|-
|'''xaxis'''||Schriftart, Größe und Farbe der X-Achse
|-
|'''yaxis'''||Schriftart, Größe und Farbe der Y-Achse
|-
|'''xticks'''||Schriftart, Größe und Farbe der X-Achse (Zwischenlinien)
|-
|'''yticks'''||Schriftart, Größe und Farbe der Y-Achse (Zwischenlinien)
|-
|'''crosshair'''||Schriftart, Größe und Vordergrund/Hintergrundfarbe der Momentanwerte am Fadenkreuzcursor
|-
|'''caption'''||Schriftart, Größe und Farbe der Text-Buttons für Legende und Cursor
|-
|'''legend'''||Schriftart, Größe und Farbe der Legende
|}

Die Standardwerte sind in der Datei <code>css/ftui_chart.css</code> zu finden.

==Datenquellen==
Beim Chart-Widget können die gleichen Datenquellen genutzt werden, die auch für SVG-Plots verwendet werden können:
# [[FileLog]]: Verlaufsdaten einer Textdatei entnehmen
# [[DbLog]]: Verlaufsdaten einer Datenbank entnehmen
# [[LogProxy]]: Daten dynamisch berechnet

===FileLog===
Um [[FileLog]] zu nutzen, wird als '''data-logdevice''' das FHEM-Device für das FileLog angegeben. In der Regel entstehen hier im Laufe der Zeit mehrere Log-Dateien. Name und Anzahl sind von der Definition abhängig - meist wird jeden Monat oder jedes Jahr eine neue Datei angelegt. Die gewünschte Datei kann mit '''data-logfile''' ausgewählt werden. Möchte man stets die aktuelle Datei verwenden (macht vor allem dann Sinn, wenn man die neusten Daten anzeigen will), kann das Attribut weggelassen, oder explizit <code>-</code> eingetragen werden. Zuletzt wird '''data-columnspec''' benötigt, um die gewünschten Daten zu in der Logdatei zu identifizieren. Hier wird die Spalte, in der die Daten stehen, gefolgt von Doppelpunkt und Readingname angegeben.

Für ein Heizungsthermostat von Homematic mit dem Namen ''DG.wz.HZ.Heizungsventil'' ergibt sich somit beispielhaft folgende Definition, um gemessene Temperatur, Sollwert und Ventilstellung im Diagramm darzustellen:

<source lang="html">
<div data-type="chart"
data-device="DG.wz.HZ.Heizungsventil"
data-logdevice="FileLog_DG.wz.HZ.Heizungsventil"
data-logfile="-"
data-columnspec='["4:measured-temp","4:desired-temp","4:actuator"]'
...>
</div>
</source>

Sollen Daten von unterschiedlichen Geräten in einem Diagramm angezeigt werden, muss '''data-logdevice''' als Array nach dem Schema <code>data-logdevice='["<Logdatei_1>","<Logdatei_2>","<Logdatei_3>"]'</code> definiert werden. Für jeden Eintrag in '''data-columnspec''' muss es auch den passenden Eintrag in '''data-logdevice''' geben (auch die Reihenfolge ist relevant).

===DbLog===
Um die Daten aus [[DbLog]] anzeigen zu können, werden die gleichen Attribute verwendet und mit für die Datenbank angepassten Werten beschrieben. Bei '''data-logdevice''' das FHEM-Device für die Datenbank angegeben. Im nachfolgenden Beispiel heißt diese <code>logdb</code> und besitzt wie üblich zwei Tabellen: <code>current</code> und <code>history</code> (der zeitliche Verlauf liegt in letzterer). Der Tabellenname wird bei '''data-logfile''' eingetragen. Da die Daten in der Datenbank etwas anders abgelegt werden, muss auch '''data-columnspec''' entsprechend angepasst werden. Statt der Spalte wird hier das FHEM-Device, gefolgt von Doppelpunkt und Readingname angegeben.

Für das oben beschriebene Homematic-Heizungsthermostat ergibt sich dann folgende Definition, um die gleichen Daten aus einer Datenbank, statt einem LogFile zu lesen:

<source lang="html">
<div data-type="chart"
data-device="DG.wz.HZ.Heizungsventil"
data-logdevice="logdb"
data-logfile="HISTORY"
data-columnspec='["DG.wz.HZ.Heizungsventil:measured-temp","DG.wz.HZ.Heizungsventil:desired-temp","DG.wz.HZ.Heizungsventil:actuator"]'
...>
</div>
</source>

Für die Anzeige von unterschiedlichen Geräten in einem Diagramm, muss nur '''data-columnspec''' entsprechend angepasst werden, solange sich alle Daten in der Datenbank befinden.

===LogProxy===
Um die Daten mittels [[LogProxy]] berechnen und anzeigen zu können, muss in FHEM ein LogProxy-Device definiert sein:

<pre>
define myLogProxy logProxy
</pre>

Weitere Einstellungen am LogProxy sind nicht nötig, die bloße Existenz reicht.

Bei '''data-logdevice''' wird das FHEM-Device für den LogProxy angegeben. Im nachfolgenden Beispiel heißt dieses <code>myLogProxy</code>. Das Attribut '''data-logfile''' wird für LogProxy nicht benötigt. Befinden sich nur LogProxy-Werte im Diagramm kann das Attribut komplett entfallen. Sollen weitere Werte angezeigt werden, bleibt die Definition im Array einfach leer.

Im Attribut '''data-columnspec''' wird eine Formel angegeben, wie die Werte berechnet werden sollen. Hier können die Formeln 1:1 von einem eventuell vorhandenen SVG-Plot übernommen werden. '''Dabei gibt es jedoch folgendes zu beachten:''' Befindet sich die Formel in einem Array, dürfen die Formeln keine Anführungszeichen (<code>"</code>) beinhalten. Stattdessen müssen sie als escapter Ascii-Code (<code>\\x22</code>) eingefügt werden.

Das nachfolgende Beispiel zeigt, wie Vorhersagewerte aus einem FHEM-Device vom Typ Proplanta (Name hier <code>AU.xx.WE.Proplanta</code>) angezeigt werden können.

<source lang="html">
<div data-type="chart"
data-device="AU.xx.WE.Proplanta"
data-logdevice='[
"myLogProxy",
"myLogProxy",
"myLogProxy",
"myLogProxy"
]'
data-columnspec='[
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22temp_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22rain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22chOfRain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22cloud_\\x22,$from,$to,12,\\x22day\\x22)"
]'
...>
</div>
</source>

'''Auch alle anderen Funktionen, die [[LogProxy]] bietet, können hier angewendet werden.'''

==Hinweise==
===Aktualisierung des Charts===
Damit der Refresh des Charts funktioniert, muss auch ein Device angegeben werden, der das Refresh triggert. Das Diagramm wird immer dann aktualisiert, wenn sich der Inhalt von '''data-get''' ändert.

<source lang="html">
<div data-type="chart"
data-device="WohnzimmerHeizung"
data-logdevice="FileLog_WohnzimmerHeizung"
...>
</div>
</source>

===Aussehen der Linien===
Mit dem Attribut '''data-style''' kann das Aussehen der Linien des jeweiligen Graphen verändert werden. Hierfür können die Standard-FHEM-Styles verwendet werden. Dazu wird das Attribut mit <code>SVGplot</code>, gefolgt von einem Leerzeichen und der gewünschten Farbe/Stil befüllt. Es existieren jedoch auch noch weitere, an FTUI angepasste Styles, zu finden in der CSS-Datei <code>css/ftui_chart.css</code>. Um diese zu verwenden, wird das Attribut mit <code>ftui</code>, gefolgt von einem Leerzeichen und der gewünschten Farbe/Stil befüllt. Eigene Styles können zum Beispiel in der Datei <code>css/fhem-table-ui-user.css</code> definiert werden.

Folgende Übersicht zeigt die im Standard verfügbaren '''Farben''', alle Abbildungen sind mit im FTUI-Style entstanden:
<div><ul>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f0.png|thumb|none|150px|Farbe "l0"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f1.png|thumb|none|150px|Farbe "l1"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f2.png|thumb|none|150px|Farbe "l2"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f3.png|thumb|none|150px|Farbe "l3"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f4.png|thumb|none|150px|Farbe "l4"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f5.png|thumb|none|150px|Farbe "l5"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Farbe-f6.png|thumb|none|150px|Farbe "l6"]] </li>
</ul></div>

Die Angabe zur Farbe kann dann mit der Linienart kombiniert werden. Dazu stehen folgende '''Stile''' zur Verfügung:
<div><ul>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-normal.png|thumb|none|225px|Darstellung in 2D: Stil "normal"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-dot.png|thumb|none|225px|Darstellung in 2D: Stil "dot"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-dash.png|thumb|none|225px|Darstellung in 2D: Stil "dash"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-fill.png|thumb|none|225px|Darstellung in 2D: Stil "fill"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-2D-sym.png|thumb|none|225px|Darstellung in 2D: Stil "sym"]] </li>
</ul></div>

<div><ul>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-normal.png|thumb|none|225px|Darstellung in 3D: Stil "normal"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-dot.png|thumb|none|225px|Darstellung in 3D: Stil "dot"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-dash.png|thumb|none|225px|Darstellung in 3D: Stil "dash"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-fill.png|thumb|none|225px|Darstellung in 3D: Stil "fill"]] </li>
<li style="display: inline-block;"> [[File:FTUI_Widget_Chart_Form-3D-sym.png|thumb|none|225px|Darstellung in 3D: Stil "sym"]] </li>
</ul></div>

Farbe und Stil werden kombiniert (zusammengeschrieben) beim Attribut '''data-style''' angegeben, sodass sich beispielsweise für eine graue Punktlinie folgendes ergibt: <code>data-style="ftui l1dot"</code>.
Um die Darstellung als normale Linie zu erhalten, darf im Gegensatz zu den anderen Linienformen der Stil <code>normal</code> nicht angegeben werden. Für eine einfache graue Linie ist also die Angabe <code>data-style="ftui l1"</code> korrekt, wohingegen <code>data-style="ftui l1normal"</code> zu einer fehlerhaften Anzeige führt.

'''Hinweis:''' Der Stil ''sym'' ist speziell dafür geeignet, Symbole statt Linien zu zeichnen. Dazu kann beim Attribut '''data-ptype''' als Linienform ein beliebiges Font-Awsome-, oder Open Automation-Icon angegeben werden. Alle in diesem Abschnitt enthaltenen Abbildungen sind mit <code>data-ptype="lines"</code> entstanden.

===Form der Linien===
Das Attribut '''data-ptype''' beeinflusst die Form der Linien. Hier sind folgende Werte möglich:

* <code>lines</code>
* <code>steps</code>
* <code>fsteps</code>
* <code>histeps</code>
* <code>bars</code>
* <code>ibars</code>
* <code>cubic</code>
* <code>quadratic</code>
* <code>quadraticSmooth</code>

Zusätzlich ist es möglich, Symbole anzeigen zu lassen. Unterstützt werden Font-Awesome ('fa-...'), Open Automation ('oa-...') und FHEM-Symbole ('fs-...')). Damit die Symbole korrekt angezeigt werden, muss im Attribut '''data-style''' der Stil <code>sym</code> gewählt werden, da sonst nur Punkte, statt der Symbole gezeichnet werden.

<source lang="html">
<div data-type="chart"
data-device="DG.wz.HZ.Heizungsventil"
data-logdevice="FileLog_DG.wz.HZ.Heizungsventil"
...
data-style="ftui l1sym"
data-ptype="fa-cog"
...>
</div>
</source>

Die Größe der Symbole ist in der Datei <code>css/ftui_chart.css</code> auf 12px festgelegt. Dieser Wert kann in einer eigenen CSS-Datei durch Anpassung von <code>stroke-width</code> überschrieben werden.

<source lang="css">
.ftui.l0sym { stroke:#DDA400; stroke-width:12px; fill:none; }
.ftui.l1sym { stroke:#BBBBBB; stroke-width:12px; fill:none; }
.ftui.l2sym { stroke:#CC0000; stroke-width:12px; fill:none; }
.ftui.l3sym { stroke:#CCCC00; stroke-width:12px; fill:none; }
.ftui.l4sym { stroke:#33CC33; stroke-width:12px; fill:none; }
.ftui.l5sym { stroke:#33CCCC; stroke-width:12px; fill:none; }
.ftui.l6sym { stroke:#3333CC; stroke-width:12px; fill:none; }
</source>

'''data-ptype''' kann auch Inhalt im Format <code>'icon:1'</code> verarbeiten. Dann muss der zugehörige Wert in '''data-columnspec''' den Pfad zu einem Icon (z.B. für Wettervorhersagen) beinhalten. Der Y-Wert wird dann vom ersten Graphen übernommen. Weitere Ausführungen hierzu im Beispiel [[#Darstellung der Wetter Icons im Diagramm]]

===Zeitformat der X-Achse===
Die Zeitanzeige auf der X-Achse kann sehr flexibel eingestellt werden. Dafür stehen verschiedene Platzhalter zur Verfügung, die durch spezielle Zeichen (<code>-</code>, <code>.</code>, <code>/</code>, <code> </code> (Leerzeichen), <code>:</code>, <code>,</code>, <code>\</code>) getrennt werden. Alle Zeichen werden trotz Escape-Zeichen (<code>\</code>) in der Ausgabe angezeigt.

Folgende Platzhalter werden unterstützt:
*<code>'mm'</code>: Minuten als zweistellige Zahl
*<code>'hh'</code>: Stunden als zweistellige Zahl
*<code>'dd'</code>: Tag als zweistellige Zahl (Kalenderdatum)
*<code>'MM'</code>: Monat als zweistellige Zahl (z.B. 02 für Februar)
*<code>'MMM'</code>: Monat als dreistellige Abkürzung (z.B. Dec für Dezember)
*<code>'MMMM'</code>: Langname des Monats (z.B. March)
*<code>'ee'</code>: Wochentag als zweistellige Zahl (z.B. 00 für Sonntag)
*<code>'eee'</code>: Wochentag als dreistellige Abkürzung (z.B. Mon für Montag)
*<code>'eeee'</code>: Langname des Wochentags (z.B. Tuesday)
*<code>'yy'</code>: Jahr als zweistellige Zahl (z.B. 16 für 2016)
*<code>'yyyy'</code>: Jahr als vierstellige Zahl (z.B. 2016)
*<code>'LF'</code>: Fügt einen Zeilenumbruch hinzu

Beispiel: Der String <code>'MMM\LF\yyyy'</code> zeigt <code>'Jan'</code> in der ersten, und <code>'2016'</code> in der zweiten Zeile. <code>'MM.dd 2016'</code> wird zu <code>'03.05 2016'</code>.

===Fadenkreuz-Cursor===
Der Fadenkreuz-Cursor zeigt die Momentanwerte, indem man ihn über die Graphen bewegt. In Desktop-Browsern reicht einfaches Bewegen des Maus. Unter iOS und Android kann der Cursor wird der Cursor durch einfaches Tippen auf die neue Position bewegt.

Mit dem Attribut '''data-cursorgroup''' können Graphen gruppiert werden. Am Cursor werden dann die Momentanwerte aller Graphen gleichzeitig angezeigt, die die selbe Zahl besitzen, sobald man die Maus über einen aus der Gruppe bewegt.

===Legende===
Mit dem Attribut '''data-legendpos''' kann die Position der Legende innerhalb des Diagramms festgelegt werden. Die Position wird mit einem Array, bestehend aus zwei Werten im Format <code>'["<horizontal>","<vertikal>"]'</code> angegeben. Für die horizontale Positionierung sind <code>'left'</code> und <code>'right'</code>, die vertikale Positionierung <code>'top'</code> und <code>'bottom'</code> erlaubt. Alternativ können auch Zahlen verwendet werden, die die Position in Prozent angeben. Durch verschieben mit der Maus oder durch verschieben mit dem Finger oder Stift auf Touch Devices kann die Legende auch an eine andere Position verschoben werden.

Wenn die Legende eingeblendet ist, kann mittels Klick auf einen Legendeneintrag der zugehörige Graph ein- und ausgeblendet werden.

===3-dimensionale Drehung===
'''data-ddd''' ermöglicht, den Graphen 3-dimensional zu drehen. Als Wert wird ein Array mit den 3 Winkeln für x, y und z erwartet, wobei z selbst bisher nicht unterstützt wird.

Beispiel: <code>data-ddd='["40","60","0"]'</code>.

Wenn der 3D Modus aktiv ist ('''data-ddd''' gesetzt) sind 2 zusätzliche Parameter verfügbar um das Aussehen der Graphen zu beeinflussen. '''data-dddspace''' gibt an, wie viele pixel der Raum zwischen den einzelnen in z-Richtung hintereinander angeordneten Graphen betragen soll.
'''data-dddwidth''' legt fest, wie viele pixel die einzelnen Graphen tief (oder dick) sein sollen.

Wenn das Array angegeben wird, erscheinen zwei zusätzliche Buttons im Diagramm, mit denen die Drehung in X- und Y-Richtung verändert werden kann.

===Diagrammtitel===
Mit dem Attribut '''data-title''' kann dem Diagramm, ähnlich wie in FHEM-SVG-Plots, ein Titel hinzugefügt werden.

Folgende Platzhalter werden unterstützt:
*<code>'min1'</code>: Minimaler Y-Wert des ersten Graphs
*<code>'max1'</code>: Maximaler Y-Wert des ersten Graphs
*<code>'avg1'</code>: Mittlerer Y-Wert des ersten Graphs
*<code>'cnt1'</code>: Anzahl der dargestellten Einzelwerte im ersten Graph
*<code>'currval1'</code>: Letzter, bzw. aktuellster Y-Wert des ersten Graphs
*<code>'mindate1'</code>: Niedrigster Wert auf der X-Achse des ersten Graphs
*<code>'maxdate1'</code>: Höchster Wert auf der X-Achse vom ersten Graphs
*<code>'currdate1'</code>: Letzter, bzw. aktuellster Wert auf der X-Achse des ersten Graphs

Durch Einsetzen einer anderen Zahl statt '1' können auch die Werte der anderen Graphen angezeigt werden. Das Weglassen der Zahl bewirkt, dass der jeweils zutreffende Wert automatisch ermittelt wird. Bedeutet: <code>max</code> führt dazu, dass der höchste Wert aller angezeigter Graphen verwendet wird.

Beispiel: <code>data-title="Min: $data{mindate4}, Max: $data{maxdate4}, Last: $data{currdate4}"</code>

===Buttons im Diagramm===
Es gibt mehrere Buttons, mit denen sich die Anzeige des Diagramms verändern lässt. <code><-</code> und <code>-></code> bewegen die Graphen nach links und rechts. <code>+</code> und <code>-</code> zoomen die Anzeige. <code>legend</code> und <code>cursor</code> schalten die zugehörigen Anzeigen ein und aus.

==Beispiele==
===Einfaches Diagramm===
Das Beispiel zeigt ein einfaches Diagramm mit 4 unterschiedlich formatierten Graphen, Legende und Momentanwerten am Fadenkreuz-Cursor.

[[File:Chart_tabletUI.png]]

<source lang="html">
<div data-type="chart"
data-logdevice='["Log.Garden","Log.Garden","Log.Garden","Log.Predicted"]'
data-columnspec='["4:Garden.T:15:","10:Garden.T:0:delta-h","10:Garden.T:0:delta-d","4:predicted.*:15:"]'
data-style='["ftui l0fill","ftui l1fill","ftui l2","ftui l3dot"]'
data-ptype='["lines","histeps","histeps","cubic"]'
data-uaxis='["primary","secondary","secondary","primary"]'
data-legend='["Temperature","Rain/hour","Rain/day","Predicted Temp."]'
data-yunit="°C"
data-ytext="Temperature"
data-minvalue="auto"
data-maxvalue="auto"
data-yunit_sec="mm"
data-ytext_sec="Rain (mm)"
data-height="250"
data-yticks="auto"
data-minvalue_sec="auto"
data-maxvalue_sec="auto"
data-nofulldays="true"
data-daysago_start="2013-08-13T00:00:00"
data-daysago_end="2013-08-14T00:00:00"
data-cursorgroup="1"
data-scrollgroup="1"
data-xticks="auto">
</div>
</source>

===7-Tage-Wettervorhersage mit Proplanta===
In diesem Beispiel wird gezeigt, wie die Vorhersagewerte von [[PROPLANTA]] in einem Diagramm dargestellt werden können. Da die Werte nicht in einer Datenbank oder einem FileLog vorliegen, müssen sie über [[LogProxy]] verarbeitet werden. Dafür sind einige Vorbereitungen in FHEM nötig.

[[File:FTUI_Widget_Chart-fc-Proplanta.png|941px]]

'''1.''' Ein LogProxy-Device muss vorhanden sein:
<pre>
define myLogProxy logProxy
</pre>

'''2.''' In der Datei <code>99_myUtils.pm</code> muss folgende Routine hinzugefügt werden, die die Daten bereitstellt:
<source lang="perl">
#---------------------------------------
# Proplanta LogProxy-Funktion
#---------------------------------------
sub logProxy_proplanta2Plot($$$$;$$) {
my ($device, $fcValue, $from, $to, $fcHour, $expMode) = @_;
my $regex;
my @rl;

return undef if(!$device);

if($fcValue =~ s/_$//) {
$regex = "^fc[\\d]+_".$fcValue."[\\d]{2}\$";
}
else {
$regex = "^fc[\\d]+_".$fcValue."\$";
}

$fcHour = 12 if(!defined $fcHour);
$expMode = "point" if(!defined $expMode);

if( defined($defs{$device}) ) {
if( $defs{$device}{TYPE} eq "PROPLANTA" ) {
@rl = sort{
my ($an) = ($a =~ m/fc(\d+)_.*/);
my ($bn) = ($b =~ m/fc(\d+)_.*/);
$an <=> $bn or $a cmp $b;
}( grep /${regex}/,keys %{$defs{$device}{READINGS}} );
return undef if( !@rl );
} else {
Log3 undef, 2, "logProxy_proplanta2Plot: $device is not a PROPLANTA device";
return undef;
}
}

my $fromsec = SVG_time_to_sec($from);
my $tosec = SVG_time_to_sec($to);
my $sec = $fromsec;
my ($h,$fcDay,$mday,$mon,$year);
my $timestamp;

my $reading;
my $value;
my $prev_value;
my $min = 999999;
my $max = -999999;
my $ret = "";

# while not end of plot range reached
while(($sec < $tosec) && @rl) {
#remember previous value for start of plot range
$prev_value = $value;

$reading = shift @rl;
($fcDay) = $reading =~ m/^fc(\d+).*/;
$h = ($reading =~ m/.*(\d\d)$/)?$1:$fcHour;
$value = ReadingsVal($device,$reading,undef);

($mday,$mon,$year) = split('\.',ReadingsVal($device,"fc".$fcDay."_date",undef));
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, $h, 0, 0);
$sec = SVG_time_to_sec($timestamp);

# skip all values before start of plot range
next if( SVG_time_to_sec($timestamp) < $fromsec );

# add first value at start of plot range
if( !$ret && $prev_value ) {
$min = $prev_value if( $prev_value < $min );
$max = $prev_value if( $prev_value > $max );
$ret .= "$from $prev_value\n";
}

# done if after end of plot range
last if($sec > $tosec);

$min = $value if( $value < $min );
$max = $value if( $value > $max );

# add actual controll point
$ret .= "$timestamp $value\n";

# Log 1, "$timestamp $value -0- $reading";
}
if(($sec < $tosec) && !@rl && ($expMode eq "day")) {
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, 23, 59, 59);
if(SVG_time_to_sec($timestamp) < $tosec) {
$ret .= "$timestamp $value\n";
}
else {
$ret .= "$to $value\n";
}
}
elsif(($sec > $tosec) && ($expMode eq "day")) {
$value = $prev_value + ($value - $prev_value)*(86400 + ($tosec - $sec))/86400;
$ret .= "$to $value\n";
}
return ($ret,$min,$max,$prev_value);
}
</source>

Anschließend können die Daten im Chart-Widget angezeigt werden. Der Device-Name von Proplanta heißt hier im Beispiel <code>AU.xx.WE.Proplanta</code>.

<source lang="html">
<div data-type="chart"
data-device="AU.xx.WE.Proplanta"
data-logdevice='[
"myLogProxy",
"myLogProxy",
"myLogProxy"
]'
data-columnspec='[
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22rain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22chOfRain_\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22cloud_\\x22,$from,$to,12,\\x22day\\x22)"
]'
data-style='[
"ftui l6fill",
"ftui l5fill",
"ftui l1fill"
]'
data-ptype='[
"steps",
"quadraticSmooth",
"quadraticSmooth"
]'
data-uaxis='[
"primary",
"secondary",
"secondary"
]'
data-legend='[
"Regen",
"Regenwahrscheinlichkeit",
"Wolken"
]'
data-yunit="mm"
data-ytext="Regen"
data-yunit_sec="%"
data-ytext_sec="Chance auf Regen / Wolken"
data-timeformat="eeee"
data-minvalue="auto"
data-maxvalue="auto"
data-minvalue_sec="auto"
data-maxvalue_sec="auto"
data-daysago_start = "0"
data-daysago_end = "-7"
data-xticks="1440"
data-yticks="auto"
data-title="7-Tage-Wettervorhersage"
data-showlegend="true"
class="nobuttons fullsize">
</div>
</source>

'''Hilfreiche Links und Quellen zu diesem Beispiel:'''
*[[LogProxy|LogProxy im FHEM-Wiki]]
*{{Link2Forum|Topic=22967|Message=246973|LinkText=Stundengenaue Wettervorhersage (#1) im FHEM-Forum}}
*{{Link2Forum|Topic=22967|Message=334713|LinkText=Stundengenaue Wettervorhersage (#2) im FHEM-Forum}}

===Darstellung der Wetter Icons im Diagramm===

[[File:Wetterchart2.png]]

Wie oben bereits beschrieben, gibt es beim Chart grundsätzlich die Möglichkeit, Icons, welche in Form von URLs in den Logs abgelegt sind oder welche per logProxy generiert werden, darzustellen. Die Icons werden auf genau dem gleichen Weg von FHEM gelesen, wie alle anderen Datenpunkte. Im Folgenden wird ein Beispiel gezeigt, mit dem die im Proplanta Modul als Readings abgelegten Icons per logProxy Funktion gelesen und in ein Chart eingebaut werden könnnen.
Da es beim Proplanta Modul für die ersten 7 Tage nicht das Reading <code>fc#_weatherIcon</code> gibt, sondern mehrere Readings für unterschiedliche Tageszeiten wogegen für die zweiten 7 Tage ausschließlich das Reading <code>fc#_weatherIcon</code> vorhanden ist, sollte per <code>attr device userReading</code> mit folgendem Eintrag dafür gesorgt werden, dass für alle Tage ein Reading <code>fc#_weatherIcon</code> vorhanden ist (alternativ könnten auch 2 Graphen gezeichnet werden, wobei der erste dann nur die ersten 7 Tage enthält und der zweite die letzen 7 Tage, will man nur die ersten 7 Tage darstellen braucht man das userReading nicht unbedingt).
<source lang="perl">
fc0_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc0_weatherDayIcon","");},
fc1_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc1_weatherDayIcon","");},
fc2_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc2_weatherDayIcon","");},
fc3_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc3_weatherDayIcon","");},
fc4_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc4_weatherDayIcon","");},
fc5_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc5_weatherDayIcon","");},
fc6_weatherIcon {ReadingsVal("AU.xx.WE.Proplanta","fc6_weatherDayIcon","");}
</source>
Um die Icons darzustellen muss ein zusätzlicher Graph definiert werden. Dieser nutzt neben der Columnspec, die die URLs abruft den Parameter <code>data-ptype="icons:#"</code> (# ist eine Zahl und steht für die Nummer, beginnend bei 0 des Graphen, welcher für die y-Position der Icons verwendet werden soll) und den Stil <code>sym</code>. Der Wert für die Symbolgröße sollte z.B. durch eine zusätzliche Definition im File fhem-tablet-ui-user.css in der Form:
<source lang="css">
/* icon lines */
.ftui.l99icon { stroke:#DDA400; stroke-width:48px; fill:none; }
</source>
angepasst werden.

Im folgenden ein Beispiel, welches eine Linie für die Maximale Tagestemperatur zeichnet und auf dieser Linie die Wetter Icons darstellt.
<source lang="html">
<div data-type="chart"
data-device="AU.xx.WE.Proplanta"
data-logdevice='[
"myLogProxy",
"myLogProxy"
]'
data-columnspec='[
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22weatherIcon\\x22,$from,$to,12,\\x22day\\x22)",
"Func:logProxy_proplanta2Plot(\\x22AU.xx.WE.Proplanta\\x22,\\x22tempMax\\x22,$from,$to,12,\\x22day\\x22)",
]'
data-style='[
"ftui l99icon",
"ftui l1fill"
]'
data-ptype='[
"icons:1",
"quadraticSmooth"
]'
data-uaxis='[
"primary",
"primary"
]'
data-legend='[
"Wetterbedingung",
"Max. Temperature"
]'
data-yunit="°C"
data-ytext="Temperature (°C)"
data-timeformat="ee\LF\dd.MM"
data-minvalue="auto"
data-maxvalue="auto"
data-minvalue_sec="auto"
data-maxvalue_sec="auto"
data-daysago_start="-1w"
data-y_margin="20"
data-daysago_end="-3w"
data-xticks="1440"
data-yticks="auto"
data-title="14-Tage-Wettervorhersage"
data-showlegend="true"
class="nobuttons fullsize">
</div>
</source>

===Fensterstatus offen/geschlossen===
Dieses Beispiel zeigt, wie ein Fensterkontakt, dessen Reading die Werte <code>closed</code> und <code>open</code> einnimmt, als Graph gezeichnet werden kann. Technisch gesehen werden hier die Werte <code>0</code> und <code>1</code> gezeichnet, indem über das Attribut '''data-columnspec''' dem Zustand <code>open</code> der Wert <code>1</code> und allen anderen Zuständen der Wert <code>0</code> zugeordnet wird. Über das Attribut '''data-yticks''' wird die Beschriftung an der Y-Achse (<code>0</code> und <code>1</code>) gegen einen frei definierbaren Text ausgetauscht.

<source lang="html">
<div data-type="chart"
data-device="wz_fensterstatus"
data-logdevice='["myDbLog"]'
data-logfile='["HISTORY"]'
data-columnspec='["wz_fensterstatus:state:0::$val=($val=~\\x22open\\x22?1:0)"]'
data-style='["ftui l4fill"]'
data-ptype='["steps"]'
data-height="290"
data-yticks='[[0,"geschlossen"],[1,"offen"]]'
data-minvalue="0"
data-maxvalue="1.1"
data-nofulldays="true"
data-daysago_start="1"
data-daysago_end="-1"
data-cursorgroup="1"
data-scrollgroup="1">
</div>
</source>

==Links==
{{Link2Forum|Topic= 48450 |Message=401006|LinkText=Thread im FHEM-Forum}}

[[Kategorie:FHEM Tablet UI]]

FTUI Widget Label

2017-03-08T19:41:23Z

Benheim: Beispiel für data-hide hinzugefügt

Das [[{{PAGENAME}}|Label Widget]] ist ein Widget für [[FHEM Tablet UI]], mit dem ein Reading eines FHEM-Devices in Textform angezeigt werden kann.

<gallery>
File:FTUI_Widget_Label_01.png
File:FTUI_Widget_Label_02.png
File:FTUI_Widget_Label_03.png
File:FTUI_Widget_Label_04.png
File:FTUI_Widget_Label_05.png
</gallery>

==Attribute==
{|class="wikitable"
!Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-get'''||Name des Readings, dessen Wert angezeigt werden soll||||data-get="measured-temp"
|-
|'''data-part'''||[[Regulärer Ausdruck|RegEx]] oder Nummer des Wortes, nach welcher der angezeigte Text gefiltert werden soll||||
|-
|'''data-fix'''||Angegebene Anzahl an Dezimalstellen einhalten||(-1 -> nicht numerisch)||
|-
|'''data-color'''||Fester Wert oder Reading eines Devices für die Label-Farbe||||data-color="red"
|-
|'''data-colors'''||Ein Array von Farben. Welche Farbe für das Label verwendet wird, wird durch das ''data-limits''-Attribut bestimmt||||data-colors='["red","yellow","green"]'
|-
|'''data-classes'''||Ein Array von CSS-Klassen. Welche Klasse verwendet wird, hängt vom zutreffenden Wert im ''data-limits''-Attribut ab||||data-classes='["bg-red","bg-yellow","bg-green"]'
|-
|'''data-limits'''||Ein Array numerischer oder RegEx Werte für den Vergleich mit dem aktuellen Wert||||data-limits='[1,15,30]'
|-
|'''data-limits-get'''||Name des Readings, von dem die Werte für den Vergleich mit dem data-limits-Array geholt werden||data-get||data-limit-get="Dummy01:Limits"
|-
|'''data-limits-part'''||Filtern nach Wert, Position eines Wertes in einer Leerzeichen-getrennte Liste oder RegEx|'-1' -> alle||
|-
|'''data-unit'''||Einheit nach Zahl hinzufügen||||data-unit="%B0C%0A"
|-
|'''data-substitution'''||Verschiedene Funktionen, um den empfangenen Wert durch etwas anderes zu ersetzen||||siehe [[#Hinweise]]
|-
|'''data-pre-text'''||Text, der vor dem empfangenen Wert stehen soll||||data-pre-text="Es ist "
|-
|'''data-post-text'''||Text, der nach dem empfangenen Wert sehen soll||||data-post-text=" Grad warm"
|-
|'''data-hide'''||Name des Readings, nach dessen Wert das Widget angezeigt werden soll oder nicht||STATE||data-hide="power-on"
|-
|'''data-hide-on'''||Wert, bei dem das Widget versteckt wird||true,1,on||data-hide-on="on"
|-
|'''data-hide-off'''||Wert, bei dem das Widget angezeigt wird||!on||data-hide-off="!on"
|-
|'''data-hideparents'''||jQuery-Selector, um auch die Eltern-Elemente zu verstecken||||data-hideparents="#Name"
|-
|'''data-refresh'''||Anzahl Sekunden, nach denen das Widget aktualisiert werden soll||0 -> kein Auto-Refresh||data-refresh="10"
|}

==CSS Klassen==
{|class="wikitable"
!Klasse!!Beschreibung
{{FTUI Klasse|small}}{{FTUI Klasse|large}}{{FTUI Klasse|big}}{{FTUI Klasse|bigger}}{{FTUI Klasse|thin}}{{FTUI Klasse|red}}{{FTUI Klasse|green}}{{FTUI Klasse|blue}}{{FTUI Klasse|orange}}{{FTUI Klasse|darker}}{{FTUI Klasse|timestamp}}{{FTUI Klasse|w1x}}{{FTUI Klasse|w2x}}{{FTUI Klasse|w3x}}{{FTUI Klasse|circleborder}}{{FTUI Klasse|squareborder}}{{FTUI Klasse|bg-limit}}{{FTUI Klasse|icon square}}{{FTUI Klasse|icon round}}{{FTUI Klasse|truncate}}
|}

==Hinweise==
* Es kann nur entweder ''data-color'' verwendet werden, oder ''data-colors'' + ''data-limits'', nicht beides gleichzeitig
* Mit der Klasse ''bg-limit'' wird die Hintergrund- statt der Vordergrundfarbe abhängig von den Werten in ''data-limits'' geändert
* Die Klassen ''icon square'' und ''icon round'' formatieren das Label mit einer fixen Breite und Höhe im Icon-Stil
* Wird die Klasse ''timestamp'' zusammen mit ''data-substitution="toDate().ago()"'' verwendet, sollte eine automatische Aktualisierung (''data-refresh="xx"'') eingestellt werden für den Fall, dass die Aktualisierungsrate des Readings zu gering ist.
* Ein benutzerdefiniertes Layout kann durch Hinzufügen der folgenden Klassen in die fhem-tablet-ui-user.css erreicht werden:
** .label-precomma
** .label-comma
** .label-aftercomma
** .label-unit
** z.B.: <code>.label-aftercomma{ font-size:40%; left: 4px; top: -25px; position: relative; }</code>
* Bis zur Version 2.6.2 wurde data-unit mit 50% Schriftgröße auf der Baseline des Wertes positioniert, danach wird die Unit auf superscript angehoben. Dies kann mit einem Eintrag in fhem-tablet-ui-user.css wieder überschrieben werden.
** <Code>.label-unit{ font-size: 50%; vertical-align: baseline; }</code>

;Funktionsweise(n) von ''data-substitution'':
* Ein Array an Ersetzungen: <code>data-substitution='["on","Lampe ist an","off","Lampe ist aus"]'</code>
* [[Regulärer Ausdruck|RegEx]], die auf dem Wert angewandt werden soll. Standard RegEx-Schreibweise wird erwartet (s/regex/subst/modifier): <code>data-substitution="s/no soundplayer active//g"</code>
* <code>data-substitution="weekdayshort"</code>
* Mit JavaScript- und RegEx-Funktionen den Wert umwandeln in:
** Tag:Monat: <code>data-substitution="toDate().ddmm()"</code>
** Stunden:Minuten: <code>data-substitution="toDate().hhmm()"</code>
** Stunden:Minuten:Sekunden: <code>data-substitution="toDate().hhmmss()"</code>
** den Namen des Wochentages: <code>data-substitution="toDate().eeee()"</code>
** einen Zeitraum (langes Format): <code>data-substitution="toDate().ago()"</code>
** einen Zeitraum (kurzes Format):<code>data-substitution="toDate().ago('hh:mm:ss')"</code>
** einen Zeitraum (Minuten ohne führende Nullen):<code>data-substitution="toDate().ago('m')"</code>
** 20:15 statt 20:15:00: <code>data-substitution="s/(:00)$//g"</code>

==Beispiele==
===Einfaches Auslesen des STATE eines Devices===
Ein ganz einfaches Beispiel, welches den ''STATE'' eines FHEM-Devices (in diesem Fall ein Heizkörperthermostat) ausliest und anzeigt.
<source lang="html">
<div data-type="label" data-device="HM_367B39_Climate"></div>
</source>
[[File:FTUI_Widget_Label_01.png]]

===Anzeige bestimmter Werte eines Devices===
In diesem Beispiel werden Temperatur und Luftfeuchtigkeit eines Heizkörperthermostates ausgelesen und untereinander angezeigt.
<source lang="html">
<div>Temperatur</div>
<div data-type="label"
data-device="HM_367B21_Climate"
data-get="measured-temp"
data-unit="°C"></div>

<div>Luftfeuchte</div>
<div data-type="label"
data-device="HM_367B21_Climate"
data-get="humidity"
data-unit="%"></div>
</source>
[[File:FTUI_Widget_Label_02.png]]

===Textfarbe bei bestimmten Grenzwerten ändern===
Mit dem Label-Widget kann die Textfarbe je nach bestimmten Grenzwerten geändert werden. In diesem Beispiel ist die Farbe blau, sobald die Temperatur gleich oder kleiner 18° ist, grün ab 20° und rot ab 23°.
<source lang="html">
<div data-type="label"
data-device="dDummy"
data-limits='[18,20,23]'
data-colors='["blue","green","#FF0000"]'
data-unit="°C"></div>
</source>
[[File:FTUI_Widget_Label_03.png]]
[[Kategorie:FHEM Tablet UI]]

===Zwei Labels in einer Textzeile===
Mit der Klasse ''inline'' (kein Zeilenumbruch) können mehrere Label-Widgets in der selben Textzeile platziert werden.
<source lang="html">
<div>
<div data-type="label" data-device="dDummy" class="inline"></div> bis
<div data-type="label" data-device="dDummy2" class="inline"></div>
</div>
</source>
[[File:FTUI_Widget_Label_04.png]]

===Kombination von Label- mit anderen Widgets===
Das Label-Widget kann sehr gut verwendet werden, um einen Beschreibungstext für andere Widgets bereitzustellen.
<source lang="html">
<div data-type="switch" data-device="EnO_0193F070" data-icon="mi-power_settings_new"></div>
<div data-type="label">Nexus7</div>
(<div data-type="label" data-device="Nexus7" data-get="powerLevel"></div>%)
</source>
[[File:FTUI_Widget_Label_05.png]]

===Statisches Label mit Symbol===
Möchte man einen statischen Text darstellen, muss hierfür nicht unbedingt das Label-Widget verwendet werden. Das nachfolgende Beispiel zeigt genau dies und fügt links noch ein Symbol ein. Der Teil für das Symbol kann auch für richtige Labels verwendet werden.
<source lang="html">
<i class="fa fa-cloud fa-2x inline"></i><div class="inline big">WETTER</div>
</source>
[[File:FTUI_Widget_label_symbol.png]]

===Label- und Symbol-Widget kombiniert===
Dieses Beispiel zeigt, wie man ein Label- innerhalb eines [[FTUI Widget Symbol|Symbol]]-Widgets anzeigen kann. Dazu wird einfach das Label-Widget im <DIV>-Container des Symbols platziert.
<source lang="html">
<div>
<div data-type="symbol"
data-device="dDummy3"
data-icon="none"
data-color='none'
data-background-icon="fa-circle"
data-background-colors='["red","blue"]'
data-limits='["0","1"]'>
<div data-type="label"
data-device="dDummy3"
data-color="white"></div>
</div>
</div>
</source>
[[File:FTUI_Widget_Label_06.png]]

===Unterdrücken der Anzeige===
Die Argumente für ''data-hide-on'' und ''data-hide-off'' sind reguläre Ausdrücke. Um die Anzeige zu aktivieren, wenn eine Bedingung nicht zutrifft, ist für ''data-hide-off'' ein Schema <code>(?!.*MUSTER).*</code> zu verwenden, resp. <code>(?!.*MUSTER1|MUSTER2).*</code>, wenn mehrere Bedinungen zutreffen können; für ''data-hide-on'' entsprechend <code>MUSTER</code> resp. <code>MUSTER1|MUSTER2</code>.

Im folgenden Beispiel wird ein Eintrag eines [[CALVIEW|CALVIEW-Objekts]] ''Abfalldaten'' nur dann angezeigt, wenn er heute oder morgen aktuell ist, ausgeblendet wird die ganze Gruppe von Widgets über die ID des Elternelements:
<source lang="html">
<div id="Abfall1">
<div class="inline"
data-type="label"
data-device="Abfalldaten"
data-get="t_001_bdate"
data-hide="t_001_daysleftLong"
data-hide-on="(?!.*heute|morgen).*"
data-hide-off="heute|morgen"
data-hideparents="#Abfall1">
</div>
<div class="inline"
data-type="label"
data-device="Abfalldaten"
data-get="t_001_summary">
</div>
</div>
</source>

HM-WDS100-C6-O Funk-Kombi-Sensor OC3

2016-05-18T18:16:40Z

Benheim:

{{Infobox Hardware
|Bild=HM-WDS100-C6-O.jpg
|Bildbeschreibung=Montierter Funk-Kombi-Sensor OC3
|HWProtocol=[[HomeMatic]]
|HWType=[[HomeMatic Type THSensor|THSensor]]
|HWCategory=[[:Kategorie:Wetterstationen|Wetterstationen]] [[:Kategorie:Feuchtesensoren|Feuchtesensoren]] [[:Kategorie:Temperatursensoren|Temperatursensoren]] [[:Kategorie:Regensensor|Regensensor]] [[:Kategorie:Lichtsensoren|Lichtsensoren]]
|HWComm=868,35 MHz
|HWChannels=
|HWVoltage=4,5 V
|HWPowerConsumption=
|HWPoweredBy=3x LR6/Mignon/AA
|HWSize=700 x 400 x 150 mm
|HWDeviceFHEM=[[CUL_HM]]
|HWManufacturer=ELV / eQ-3
}}

Der '''Funk-Kombi-Sensor OC3 (HM-WDS100-C6-O)''' ist eine [[HomeMatic]] Funk-Wetterstation für den Außeneinsatz zur Messung von Temperatur, relativer Luftfeuchte, Windrichtung, Windstärke, Regenmenge und Helligkeit.

== Features ==
* Batteriebetrieb (3 x Mignon/LR6/AA)
* Funkfrequenz 868,3 MHz
* Temperaturmessbereich -29,9°C bis 79,9°C (± 0,8°C)
* Relative Luftfeuchte 1 % bis 99 % (±5 %)
* Windgeschwindigkeit 1 km/h bis 199,9 km/h
* Windrichtungsmesser 0° bis 355° (±5°)
* Schwankung der Windrichtung 0°/22,5°/45°/67,5°
* Regenmengenmesser 0 mm bis 999 mm
* Regen-Soforterkennung
* Sturm-Soforterkennung
* Helligkeit gemessen über Photodiode mit einheitenlosen Wert 1-255
* Sonnenschein-Dauer gezählt als Minuten oberhalb der Helligkeitsschwelle von 30 (Default)
* Datenübermittlung alle 120 bis 180 Sekunden
* Übermittlung des Batteriestatus

== Hinweise zum Betrieb mit Fhem ==
Das Pairing sollte wie unter [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Hierfür muss die von außen erreichbare Anlerntaste betätigt werden.

=== Konfiguration (fhem.cfg) ===
<pre>define Wetterstation CUL_HM 338893
attr Wetterstation IODev CUL_HM
attr Wetterstation autoReadReg 5_readMissing
attr Wetterstation expert 2_full
attr Wetterstation firmware 1.4
attr Wetterstation model HM-WDS100-C6-O
attr Wetterstation serialNr LEQ1442799
attr Wetterstation stateFormat Temperatur: temperature °C, Feuchtigkeit: humidity %, Helligkeit: brightness, Regen: rain mm/qm, Wind: windSpeed km/h, Richtung: windDirection
attr Wetterstation subType THSensor</pre>

=== Event-Monitor ===

Wetterstation T: 17.5 H: 82 W: 0 R: 553.715 IR: 0 WD: 10 WDR: 67.5 S: 106 B: 16
Wetterstation temperature: 17.5
Wetterstation humidity: 82
Wetterstation windSpeed: 0
Wetterstation windDirection: 10
Wetterstation windDirRange: 67.5
Wetterstation rain: 553.715
Wetterstation isRaining: 0
Wetterstation sunshine: 106

=== Parameterliste ===
'''list: register | range | peer | description'''
0: intKeyVisib | literal | | visibility of internal channel options:visib,invisib
0: pairCentral | 0 to 16777215 | | pairing to central
1: stormLowThresh | 0 to 255 | | Storm lower threshold
1: stormUpThresh | 0 to 255 | | Storm upper threshold

=== Log-Einträge ===
<pre>2015-08-13_12:47:18 Wetterstation T: 28.6 H: 57 W: 7 R: 145.14 IR: 0 WD: 80 WDR: 67.5 S: 8 B: 140
2015-08-13_12:47:18 Wetterstation brightness: 140
2015-08-13_12:47:18 Wetterstation humidity: 57
2015-08-13_12:47:18 Wetterstation isRaining: 0
2015-08-13_12:47:18 Wetterstation rain: 145.14
2015-08-13_12:47:18 Wetterstation sunshine: 8
2015-08-13_12:47:18 Wetterstation temperature: 28.6
2015-08-13_12:47:18 Wetterstation windDirRange: 67.5
2015-08-13_12:47:18 Wetterstation windDirection: 80
2015-08-13_12:47:18 Wetterstation windSpeed: 70</pre>

=== Anwendungsbeispiele ===
==== Anbindung an OpenWeathermap ====
Das hier verwendete "inoffizielle" 98_openweathermap.pm-Modul muss manuell aus dem [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/ Contrib]-Verzeichnis des Fhem-SVN heruntergeladen und in das Modulverzeichnis der eigenen Fhem-Installation kopiert werden.

Zunächst eine Funktion zur Berechnung der Differenz der gemessenen Regenmengen in 99_myUtils anlegen (abgeleitet von einer Funktion zur [[Gleitende Mittelwerte berechnen und loggen|Mittelwertberechnung]]):

<pre># myDiff
# berechnet die Differenz aus der ersten Zeile eines LogFiles und der letzten Zeile eines LogFiles über einen Zeitraum zwischen einem Zeitpunkt in der Vergangenheit und dem Zeitpunkt des Aufrufs
sub
myDiff($$$)
{
my ($offset,$logfile,$cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time-$offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr{global}{verbose};
$attr{global}{verbose} = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr{global}{verbose} = $oll;
my ($cnt, $first, $last, $diff) = (0)x4;
foreach (@logdata){
my @line = split(" ", $_);
if(defined $line[1] && "$line[1]" ne ""){
$cnt += 1;
if ($cnt == 1) {
$first = $line[1];
}
$last = $line[1];
}
}
$diff = $last - $first;
Log 4, ("myDiff: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, First: $first, Last: $last, Diff: $diff");
return $diff;
} </pre>

Danach in der fhem.cfg folgendes hinzufügen (inklusive Umrechnung der Windmesswerte von km/h in m/s):

<pre>define RegenmengeOffset dummy
define RegenmengeTag dummy
define RegenmengeLast1Hours dummy
define RegenmengeLast3Hours dummy
define RegenmengeLast24Hours dummy
define WindSpeed_mps dummy

define RegenmengeNotify notify OC3:rain.* {\
my $menge = (ReadingsVal("OC3", "rain", 0) - ReadingsVal("RegenmengeOffset", "state", 0));;\
my $last1hours = myDiff("3600", "FileLog_OC3", "10:::");;\
my $last3hours = myDiff("10800", "FileLog_OC3", "10:::");;\
my $last24hours = myDiff("86400", "FileLog_OC3", "10:::");;\
fhem("set RegenmengeTag $menge");;\
fhem("set RegenmengeLast1Hours $last1hours");;\
fhem("set RegenmengeLast3Hours $last3hours");;\
fhem("set RegenmengeLast24Hours $last24hours");;\
}

define RegenmengeOffsetReset at *00:00:00 {\
my $offset = ReadingsVal("OC3", "rain", 0);;\
fhem("set RegenmengeOffset $offset");; \
}

define WindSpeedNotify notify OC3:windSpeed.* {\
my $windspeed = (ReadingsVal("OC3", "windSpeed", 0) / 3.6);;\
$windspeed = int(100 * $windspeed + 0.5) / 100;;\
fhem("set WindSpeed_mps $windspeed") \
} </pre>

Dann können die Werte mit dem 98_openweathermap.pm - Modul aus [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/ Contrib] übertragen werden:
<pre>...
attr owo owoSrc03 rain_today:RegenmengeTag:state
attr owo owoSrc04 wind_speed:WindSpeed_mps:state
attr owo owoSrc05 rain_1h:RegenmengeLast1Hours:state
attr owo owoSrc06 rain_24h:RegenmengeLast24Hours:state
...</pre>

==== Anbindung an wetter.com ====

Die Anbindung an wetter.com benötigt zusätzlich zu den bereits vorhandenen Readings des Funk-Kombi-Sensors OC3 folgende Readings:
* RegenmengeLast1Hours
* WindSpeed_mps

Diese Readings können wie unter [[HM-WDS100-C6-O_Funk-Kombi-Sensor_OC3#Anbindung an OpenWeathermap|Anbindung an OpenWeathermap]] beschrieben erzeugt werden.

Dann können die Werte mit dem 55_weco.pm - Modul übertragen werden:
<pre>...
attr Wetter_com wecopa RegenmengeLast1Hours:state
attr Wetter_com wecows WindSpeed_mps:state
...</pre>

==== Sturmerkennung ====
Die Sensor-interne Sturmerkennung hat den Vorteil, dass bei Über-/Unterschreiten von konfigurierbaren Schwellwerten sofort ein Event generiert wird bzw. ein gepeerter Aktor sofort getriggert wird und somit eine Sturmerkennung nicht nachgelagert über das Reading "windSpeed" erfolgen muss (der Sensor sendet seine Werte sonst nur ca. alle 2-3 Minuten).

Folgende Schritte zur Nutzung und Anpassung der internen Sturmerkennung sind durchzuführen:

1. Peeren des Kanal 1 des Sensors (WGEG_SENW) mit einem Aktor (VCCU_Chan03, in diesem Beispiel also der virtuelle Kanal 3 einer VCCU):

<pre>set WGEG_SENW peerChan 1 VCCU_Chan03 single set</pre>

Damit werden neben der Peerkonfiguration auch folgende Readings im Sensor-Device erzeugt

<pre>R-VCCU_Chan03-stormLowThresh 5
R-VCCU_Chan03-stormUpThresh 25</pre>

2. Diese Schwellwerte können nun mit z.B.

<pre>set WGEG_SENW regSet stormUpThresh 15 VCCU_Chan03</pre>

angepaßt werden (s. Commandref zu [http://fhem.de/commandref.html#CUL_HMregSet regSet]).

== Bekannte Probleme ==
Der Zähler sunshine läuft nach gut 4 Stunden über, an Sonnentagen läuft dieser Zähler u.U. sogar mehr als einmal über.

Fhem hat bislang (noch) nicht die Möglichkeit implementiert, die Mengenmessung zu justieren. In Einzelfällen sind im Werksauslieferungszustand konstante Messabweichungen von 10% beobachtet worden.

== Links ==
* [http://www.eq-3.de/Downloads/eq3/pdf_produkte/HM-WDS100-C6-O-UM-eQ-3-GE-150415-web.pdf Montage- und Bedienungsanleitung]
* [http://www.eq-3.de/Downloads/eq3/pdf_produkte/Funk-Kombisensor-OC-3_83346_Produktdatenblatt.pdf Produktdatenblatt]
* {{Link2Forum|Area= |Topic=6106|Message=24524|LinkText=Thread}} im Forum
* wetter.com Anbindung: {{Link2Forum|Area= |Topic=22020|Message= |LinkText=Thread}} im Forum

[[Kategorie:HomeMatic Components]]
[[Kategorie:Feuchtesensoren]]
[[Kategorie:Temperatursensoren]]
[[Kategorie:Wetterstationen]]
[[Kategorie:Regensensor]]
[[Kategorie:Lichtsensoren]]

HM-WDS100-C6-O Funk-Kombi-Sensor OC3

2016-05-18T18:13:54Z

Benheim: Fotografie hochgeladen und eingefügt

{{Infobox Hardware
|Bild=HM-WDS100-C6-O.jpg
|Bildbeschreibung=Bild und Daten müssen noch ergänzt werden
|HWProtocol=[[HomeMatic]]
|HWType=[[HomeMatic Type THSensor|THSensor]]
|HWCategory=[[:Kategorie:Wetterstationen|Wetterstationen]] [[:Kategorie:Feuchtesensoren|Feuchtesensoren]] [[:Kategorie:Temperatursensoren|Temperatursensoren]] [[:Kategorie:Regensensor|Regensensor]] [[:Kategorie:Lichtsensoren|Lichtsensoren]]
|HWComm=868,35 MHz
|HWChannels=
|HWVoltage=4,5 V
|HWPowerConsumption=
|HWPoweredBy=3x LR6/Mignon/AA
|HWSize=700 x 400 x 150 mm
|HWDeviceFHEM=[[CUL_HM]]
|HWManufacturer=ELV / eQ-3
}}

Der '''Funk-Kombi-Sensor OC3 (HM-WDS100-C6-O)''' ist eine [[HomeMatic]] Funk-Wetterstation für den Außeneinsatz zur Messung von Temperatur, relativer Luftfeuchte, Windrichtung, Windstärke, Regenmenge und Helligkeit.

== Features ==
* Batteriebetrieb (3 x Mignon/LR6/AA)
* Funkfrequenz 868,3 MHz
* Temperaturmessbereich -29,9°C bis 79,9°C (± 0,8°C)
* Relative Luftfeuchte 1 % bis 99 % (±5 %)
* Windgeschwindigkeit 1 km/h bis 199,9 km/h
* Windrichtungsmesser 0° bis 355° (±5°)
* Schwankung der Windrichtung 0°/22,5°/45°/67,5°
* Regenmengenmesser 0 mm bis 999 mm
* Regen-Soforterkennung
* Sturm-Soforterkennung
* Helligkeit gemessen über Photodiode mit einheitenlosen Wert 1-255
* Sonnenschein-Dauer gezählt als Minuten oberhalb der Helligkeitsschwelle von 30 (Default)
* Datenübermittlung alle 120 bis 180 Sekunden
* Übermittlung des Batteriestatus

== Hinweise zum Betrieb mit Fhem ==
Das Pairing sollte wie unter [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Hierfür muss die von außen erreichbare Anlerntaste betätigt werden.

=== Konfiguration (fhem.cfg) ===
<pre>define Wetterstation CUL_HM 338893
attr Wetterstation IODev CUL_HM
attr Wetterstation autoReadReg 5_readMissing
attr Wetterstation expert 2_full
attr Wetterstation firmware 1.4
attr Wetterstation model HM-WDS100-C6-O
attr Wetterstation serialNr LEQ1442799
attr Wetterstation stateFormat Temperatur: temperature °C, Feuchtigkeit: humidity %, Helligkeit: brightness, Regen: rain mm/qm, Wind: windSpeed km/h, Richtung: windDirection
attr Wetterstation subType THSensor</pre>

=== Event-Monitor ===

Wetterstation T: 17.5 H: 82 W: 0 R: 553.715 IR: 0 WD: 10 WDR: 67.5 S: 106 B: 16
Wetterstation temperature: 17.5
Wetterstation humidity: 82
Wetterstation windSpeed: 0
Wetterstation windDirection: 10
Wetterstation windDirRange: 67.5
Wetterstation rain: 553.715
Wetterstation isRaining: 0
Wetterstation sunshine: 106

=== Parameterliste ===
'''list: register | range | peer | description'''
0: intKeyVisib | literal | | visibility of internal channel options:visib,invisib
0: pairCentral | 0 to 16777215 | | pairing to central
1: stormLowThresh | 0 to 255 | | Storm lower threshold
1: stormUpThresh | 0 to 255 | | Storm upper threshold

=== Log-Einträge ===
<pre>2015-08-13_12:47:18 Wetterstation T: 28.6 H: 57 W: 7 R: 145.14 IR: 0 WD: 80 WDR: 67.5 S: 8 B: 140
2015-08-13_12:47:18 Wetterstation brightness: 140
2015-08-13_12:47:18 Wetterstation humidity: 57
2015-08-13_12:47:18 Wetterstation isRaining: 0
2015-08-13_12:47:18 Wetterstation rain: 145.14
2015-08-13_12:47:18 Wetterstation sunshine: 8
2015-08-13_12:47:18 Wetterstation temperature: 28.6
2015-08-13_12:47:18 Wetterstation windDirRange: 67.5
2015-08-13_12:47:18 Wetterstation windDirection: 80
2015-08-13_12:47:18 Wetterstation windSpeed: 70</pre>

=== Anwendungsbeispiele ===
==== Anbindung an OpenWeathermap ====
Das hier verwendete "inoffizielle" 98_openweathermap.pm-Modul muss manuell aus dem [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/ Contrib]-Verzeichnis des Fhem-SVN heruntergeladen und in das Modulverzeichnis der eigenen Fhem-Installation kopiert werden.

Zunächst eine Funktion zur Berechnung der Differenz der gemessenen Regenmengen in 99_myUtils anlegen (abgeleitet von einer Funktion zur [[Gleitende Mittelwerte berechnen und loggen|Mittelwertberechnung]]):

<pre># myDiff
# berechnet die Differenz aus der ersten Zeile eines LogFiles und der letzten Zeile eines LogFiles über einen Zeitraum zwischen einem Zeitpunkt in der Vergangenheit und dem Zeitpunkt des Aufrufs
sub
myDiff($$$)
{
my ($offset,$logfile,$cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time-$offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr{global}{verbose};
$attr{global}{verbose} = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr{global}{verbose} = $oll;
my ($cnt, $first, $last, $diff) = (0)x4;
foreach (@logdata){
my @line = split(" ", $_);
if(defined $line[1] && "$line[1]" ne ""){
$cnt += 1;
if ($cnt == 1) {
$first = $line[1];
}
$last = $line[1];
}
}
$diff = $last - $first;
Log 4, ("myDiff: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, First: $first, Last: $last, Diff: $diff");
return $diff;
} </pre>

Danach in der fhem.cfg folgendes hinzufügen (inklusive Umrechnung der Windmesswerte von km/h in m/s):

<pre>define RegenmengeOffset dummy
define RegenmengeTag dummy
define RegenmengeLast1Hours dummy
define RegenmengeLast3Hours dummy
define RegenmengeLast24Hours dummy
define WindSpeed_mps dummy

define RegenmengeNotify notify OC3:rain.* {\
my $menge = (ReadingsVal("OC3", "rain", 0) - ReadingsVal("RegenmengeOffset", "state", 0));;\
my $last1hours = myDiff("3600", "FileLog_OC3", "10:::");;\
my $last3hours = myDiff("10800", "FileLog_OC3", "10:::");;\
my $last24hours = myDiff("86400", "FileLog_OC3", "10:::");;\
fhem("set RegenmengeTag $menge");;\
fhem("set RegenmengeLast1Hours $last1hours");;\
fhem("set RegenmengeLast3Hours $last3hours");;\
fhem("set RegenmengeLast24Hours $last24hours");;\
}

define RegenmengeOffsetReset at *00:00:00 {\
my $offset = ReadingsVal("OC3", "rain", 0);;\
fhem("set RegenmengeOffset $offset");; \
}

define WindSpeedNotify notify OC3:windSpeed.* {\
my $windspeed = (ReadingsVal("OC3", "windSpeed", 0) / 3.6);;\
$windspeed = int(100 * $windspeed + 0.5) / 100;;\
fhem("set WindSpeed_mps $windspeed") \
} </pre>

Dann können die Werte mit dem 98_openweathermap.pm - Modul aus [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/ Contrib] übertragen werden:
<pre>...
attr owo owoSrc03 rain_today:RegenmengeTag:state
attr owo owoSrc04 wind_speed:WindSpeed_mps:state
attr owo owoSrc05 rain_1h:RegenmengeLast1Hours:state
attr owo owoSrc06 rain_24h:RegenmengeLast24Hours:state
...</pre>

==== Anbindung an wetter.com ====

Die Anbindung an wetter.com benötigt zusätzlich zu den bereits vorhandenen Readings des Funk-Kombi-Sensors OC3 folgende Readings:
* RegenmengeLast1Hours
* WindSpeed_mps

Diese Readings können wie unter [[HM-WDS100-C6-O_Funk-Kombi-Sensor_OC3#Anbindung an OpenWeathermap|Anbindung an OpenWeathermap]] beschrieben erzeugt werden.

Dann können die Werte mit dem 55_weco.pm - Modul übertragen werden:
<pre>...
attr Wetter_com wecopa RegenmengeLast1Hours:state
attr Wetter_com wecows WindSpeed_mps:state
...</pre>

==== Sturmerkennung ====
Die Sensor-interne Sturmerkennung hat den Vorteil, dass bei Über-/Unterschreiten von konfigurierbaren Schwellwerten sofort ein Event generiert wird bzw. ein gepeerter Aktor sofort getriggert wird und somit eine Sturmerkennung nicht nachgelagert über das Reading "windSpeed" erfolgen muss (der Sensor sendet seine Werte sonst nur ca. alle 2-3 Minuten).

Folgende Schritte zur Nutzung und Anpassung der internen Sturmerkennung sind durchzuführen:

1. Peeren des Kanal 1 des Sensors (WGEG_SENW) mit einem Aktor (VCCU_Chan03, in diesem Beispiel also der virtuelle Kanal 3 einer VCCU):

<pre>set WGEG_SENW peerChan 1 VCCU_Chan03 single set</pre>

Damit werden neben der Peerkonfiguration auch folgende Readings im Sensor-Device erzeugt

<pre>R-VCCU_Chan03-stormLowThresh 5
R-VCCU_Chan03-stormUpThresh 25</pre>

2. Diese Schwellwerte können nun mit z.B.

<pre>set WGEG_SENW regSet stormUpThresh 15 VCCU_Chan03</pre>

angepaßt werden (s. Commandref zu [http://fhem.de/commandref.html#CUL_HMregSet regSet]).

== Bekannte Probleme ==
Der Zähler sunshine läuft nach gut 4 Stunden über, an Sonnentagen läuft dieser Zähler u.U. sogar mehr als einmal über.

Fhem hat bislang (noch) nicht die Möglichkeit implementiert, die Mengenmessung zu justieren. In Einzelfällen sind im Werksauslieferungszustand konstante Messabweichungen von 10% beobachtet worden.

== Links ==
* [http://www.eq-3.de/Downloads/eq3/pdf_produkte/HM-WDS100-C6-O-UM-eQ-3-GE-150415-web.pdf Montage- und Bedienungsanleitung]
* [http://www.eq-3.de/Downloads/eq3/pdf_produkte/Funk-Kombisensor-OC-3_83346_Produktdatenblatt.pdf Produktdatenblatt]
* {{Link2Forum|Area= |Topic=6106|Message=24524|LinkText=Thread}} im Forum
* wetter.com Anbindung: {{Link2Forum|Area= |Topic=22020|Message= |LinkText=Thread}} im Forum

[[Kategorie:HomeMatic Components]]
[[Kategorie:Feuchtesensoren]]
[[Kategorie:Temperatursensoren]]
[[Kategorie:Wetterstationen]]
[[Kategorie:Regensensor]]
[[Kategorie:Lichtsensoren]]

Datei:HM-WDS100-C6-O.jpg

2016-05-18T18:11:08Z

Benheim: Eigene Aufnahme

Eigene Aufnahme

Vorlage:EnOceanSubTypeTable

2016-05-04T11:22:14Z

Benheim: blindsCtrl.00 hinzugefügt (Omnio UPJ230/12)

{|
{{News|'''subType''' |'''Wiki-Seite'''}}
{{News|tempSensor.XX | }}
{{News|roomSensorControl.01 | }}
{{News|tempHumiSensor.02 |[[EnOcean-FBH65TFB-Funk-Bewegungs- Helligkeits- Temperatur- und Feuchte-Sensor]] }}
{{News|lightSensor.XX |[[EnOcean-FAH60-Au%C3%9Fen-Helligkeitssensor]] }}
{{News|occupSensor.XX | }}
{{News|lightTempOccupSensor.XX |[[EnOcean-FBH65S-Funk-Bewegungs- Helligkeitssensor]] }}
{{News||[[EnOcean-FBH65TFB-Funk-Bewegungs- Helligkeits- Temperatur- und Feuchte-Sensor]] }}
{{News|COSensor.01 | }}
{{News|tempHumiCO2Sensor.XX | }}
{{News|vocSensor.01 | }}
{{News|radonSensor.01 | }}
{{News|particlesSensor.01 | }}
{{News|roomSensorControl.XX | }}
{{News|tempCtrlState.01 | }}
{{News|shutterCtrlState.01 |[[EnOcean-D-452-FU-EBIM-JR-Aktor-Beschattungselemente-Rollladen]]}}
{{News|blindsCtrl.00 |[[EnOcean-UPJ230_12-Jalousieaktor]]}}
{{News|lightCtrlState.XX |[[EnOcean-D-452-FU-EBIM-Aktor-2fach]] }}
{{News|autoMeterReading.XX |[[EnOcean-FSR61VA-10A-Stromstoß-Schaltrelais mit Strommessung]] }}
{{News|environmentApp |[[EnOcean-FWS61-24V-DC-Funk-Wetterdaten-Sendemodul]] }}
{{News|multiFuncSensor | }}
{{News|hvac.XX |[[EnOcean-MD15-Kleinstellantrieb]] }}
{{News|digitalInput.XX | }}
{{News|gateway; gwCmd switching|[[EnOcean-FSR14-4x-RS485-Bus-Schaltaktor-4-Kanal-Stromstoß-Schaltrelais]] }}
{{News|gateway; gwCmd dimming|[[EnOcean-FUD12NPN-RS485-Bus-Universal-Dimmaktor]] }}
{{News||[[EnOcean-FUD14-RS485-Bus-Universal-Dimmaktor]] }}
{{News||[[EnOcean-FUD61NPN-Funk-Universal-Dimmaktor]] }}
{{News||[[EnOcean-FUD61NPN-Funk-Universal-Dimmaktor-unidirektional]] }}
{{News|gateway; gwCmd blindCmd|[[EnOcean-D-452-FU-EBIM-JR-Aktor-Beschattungselemente-Rollladen]] }}
{{News||[[EnOcean-D-452-FU-EBI-JR-Aktor-Beschattungselemente-Rollladen]] }}
{{News|manufProfile |[[EnOcean-FSB12-RS485-Bus-Schaltaktor-2-Kanal-Beschattungselemente-Rollladen]] }}
{{News||[[EnOcean-FSB14-RS485-Bus-Schaltaktor-2-Kanal-Beschattungselemente-Rollladen]]}}
{{News||[[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen]]}}
{{News|actuator.01 |[[EnOcean-D-452-FU-EBIM-Aktor-2fach]] }}
{{News||[[EnOcean-PSC234-Zwischenstecker]] }}
{{News|switch.XX |[[EnOcean-PTM-210-Taster]] }}
{{News||[[EnOcean-FBH65TFB-Funk-Bewegungs- Helligkeits- Temperatur- und Feuchte-Sensor]]}}
{{News||[[EnOcean-FSR12-4x-RS485-Bus-Schaltaktor-4-Kanal-Stromstoß-Schaltrelais]]}}
{{News||[[EnOcean-FMS61NP-2-Kanal-Multifunktions-Stromstoßschalter]]}}
{{News||[[EnOcean-FSR61VA-10A-Stromstoß-Schaltrelais mit Strommessung]]}}
{{News||[[EnOcean-SecuSignal-Fenstergriff]]}}
{{News|roomCtrlPanel.00 | }}
{{News|contact |[[EnOcean_Starter_Guide#Kontakte]] }}
{{News||[[EnOcean-STM-250-Fenster-Türkontakt]]}}
{{News|keycard.xx | }}
{{News|windowHandle.XX |[[EnOcean-SecuSignal-Fenstergriff]]}}
{{News|sensor | }}
{{News|FRW |[[EnOcean-FRW-Rauchmelder]]}}
{{News|PM101|[[EnOcean_Starter_Guide#Profilloses_4BS-Teach-In]] }}
{{News|raw | }}
|}

<code>Die Endung .XX bei einem subType bedeutet, dass es mehrere subType-Untervarianten gibt, die sich aber nur in Kleinigkeiten -zumeist Skalierung- unterscheiden.</code>

EnOcean-UPJ230 12-Jalousieaktor

2016-05-02T21:15:58Z

Benheim: readingsProxy nach Test ersetzt durch widgetOverride

{{Infobox Hardware
|Bild=Omnio_UPJ230.jpg
|Bildbeschreibung=UPJ230/12 UP Multifunktions-Jalousieaktor 1-Kanal
|HWProtocol=EnOcean
|HWType=Aktor, Empfänger, Sensor, Repeater
|HWCategory=EnOcean
|HWComm=EnOcean Funk, 868Mhz
|HWChannels=1 (bidirektional)
|HWVoltage=230V~
|HWPowerConsumption=Eigenverbrauch 0,4W
|HWPoweredBy=230V
|HWSize=45x50x25mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#EnOcean EnOcean]
|HWManufacturer=[http://www.awag.ch/ AWAG Elektrotechnik AG]
}}

'''EnOcean-UPJ230/12-Jalousieaktor''' ist ein Aktor
* für
** Unterputzmontage
* für
** Steuerung von Rollladen, Beschattungselementen und elektrisch betriebenen Fenstern

== Features ==
Aktor für Beschattungselemente, Rolladen und elektrisch betriebene Fenster, mit Repeater-Funktion.

=== Definition/Anlernvorgang ===
Der Aktor kann, wenn der [[EnOcean Starter Guide|EnOcean]]-Empfänger in den Anlernmodus geschaltet wurde, automatisch per [[autocreate]] in Fhem angelegt werden. Für die Auswertung und Einstellung der Lamellenposition muss danach manuell ein <code>readingsProxy</code> definiert werden.

Folgende Schritte sind vorzunehmen:
* Fhem Eingabefeld: <code>set TCM_ESP3_0 teach 300</code> (Lernmodus für 5 Minuten)
* Drehschalter am Aktor auf Stellung 13
* Taste LRN am Aktor für 2 Sekunden drücken
* Drehschalter am Aktor auf Stellung 11
* Taste LRN am Aktor drücken

Die Definition des Aktors wird nun erstellt.

Um Zwischenpositionen und Lamellenstellungen anfahren zu können, muss direkt am Aktor die Laufzeit gemäss beiliegender Anleitung erfasst werden (siehe Anleitung S. 4).

=== Fhem Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration|fhem.cfg]]:

define Jal_01 EnOcean 0185D7E8
attr Jal_01 IODev TCM_ESP3_0
attr Jal_01 comMode biDir
attr Jal_01 devChannel 0
attr Jal_01 eep D2-05-00
attr Jal_01 manufID 005
attr Jal_01 subDef FFEFF301
attr Jal_01 subType blindsCtrl.00
attr Jal_01 teachMethod UTE
attr Jal_01 webCmd opens:stop:closes:position
attr Jal_01 widgetOverride angle:slider,1,1,100

Der <code>widgetOverride</code> dient der Lamellensteuerung. Diese Definition sollte auch für die Steuerung von Fenstern vorgenommen werden. Andernfalls übernimmt der Aktor diese Steuerung, dabei stellt er die Lamellen nach dem Schliessen standardmässig auf "Auf". Dadurch öffnet sich ein Fenster nach dem Schliessen wieder ein wenig. Ist die Winkelstellung in FHEM eingerichtet, wird das Verhalten des Aktors übersteuert und dauernd auf "Zu" gehalten, das Fenster bleibt nach dem Schliessen geschlossen.

== Einsatzbeispiel ==
Siehe Beispiele hier: [[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen]].

== Links ==
* Anleitung: [http://www.awag.ch/ekat/page_de/upload_insta/UPJ230_12_Bd.pdf PDF]

[[Kategorie:EnOcean Components]]
[[Kategorie:Rollladensteuerung]]

Diskussion:EnOcean-UPJ230 12-Jalousieaktor

2016-04-28T20:18:16Z

Benheim:

== Alternative zur readingProxy-Definition ==
Hallo!

Hat es einen bestimmten Grund, warum der Weg über ein separates readingsProxy-Device für die Slider-Darstellung gewählt wurde, statt das einfach über "widgetOverride angle:slider,1,1,100" beim EnO-Device zu lösen?

Danke und Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 10:56, 26. Apr. 2016 (CEST)

<hr>
Hallo Christian

ich habe die Angaben vom zuständigen Abteilungsleiter beim Hersteller AWAG erhalten, der mir die Konfiguration so beschrieben hat. Mir fehlen aber (noch) die Skills, zu beurteilen ob es eine bessere Lösung gibt. Ich kann das aber gerne versuchen, nächste Woche sollte ich genug Zeit haben.

Gruss, --[[Benutzer:Benheim|Bengt]] ([[Benutzer Diskussion:Benheim|Diskussion]]) 22:05, 28. Apr. 2016 (CEST)

Benutzer:Benheim/Startscript systemd

2016-04-28T20:07:57Z

Benheim: Die Seite wurde neu angelegt: „== Startscript für FHEM == Für Linux-Versionen, die als Startsystem <code>systemd</code> einsetzen, kann folgende Unit (systemd-Bezeichnung für Startscript…“

== Startscript für FHEM ==

Für Linux-Versionen, die als Startsystem <code>systemd</code> einsetzen, kann folgende Unit (systemd-Bezeichnung für Startscripts) verwendet werden:

<pre>
[Unit]
Description=FHEM service
After=network.target
Wants=hmland.service

[Service]
Type=forking
User=fhem
Group=dialout
WorkingDirectory=/opt/fhem
ExecStart=/usr/bin/perl fhem.pl fhem.cfg

[Install]
WantedBy=multi-user.target
</pre>

Da der FHEM-Prozess sich nach dem Starten vom Eingabe-Terminal löst und im Hintergrund läuft, muss der Typ mit <code>Type=forking</code> angegeben werden werden.

== Startscript für einen unterstützenden Dienst ==

Für das Starten des HomeMatic-Daemons <code>hmland</code> ist ein ähnliches Unit verantwortlich:

<pre>
[Unit]
Description=Homematic LAN Adapter service
After=network.target

[Service]
ExecStart=/usr/local/bin/hmland -p 1234

[Install]
WantedBy=multi-user.target
</pre>

<code>hmland</code> gibt den Prompt nach dem Starten nicht wieder frei, wenn die Option -d nicht gesetzt ist. In diesem Fall kann eine Angabe von <code>Type=</code> entfallen.

== Installation und Aktivierung ==

Die Dateien kommen ins Verzeichnis <code>/etc/systemd/system</code>. Sie sollten nicht ausführbar gemacht werden. Der Start klappt auch mit ausführbaren Dateien, aber im Log (<code>journalctl</code>) lösen ausführbare Dateien eine Warnung aus.

Nun muss einmalig der Befehl

<code>systemctl daemon-reload</code>

eingegeben werden, damit die neuen Dateien eingelesen werden. Mit dem Befehl

<code>systemctl enable fhem.service</code>

wird dafür gesorgt, dass bei einem Systemstart FHEM automatisch gestartet wird (ein symbolischer Link im mit <code>WantedBy=</code> wird erstellt). Der automatische Start lässt sich mit

<code>systemctl disable fhem.service</code>

wieder deaktivieren.

== Starten, Stoppen und Statusabfrage ==

Erfolgt ähnlich wie beim klassischen SysV-Init:

* <code>systemctl start fhem</code>
* <code>systemctl stop fhem</code>
* <code>systemctl status fhem</code>

== Abhängigkeiten ==

Durch den Eintrag in der Unit für FHEM <code>Wants=hmland.service</code> wird dafür gesorgt, dass ''vor'' dem Start von FHEM der Daemon für den HomeMatic-Stick gestartet wird. Es können mehrere Dienste aufgelistet werden, die vorher gestartet werden müssen:

<code>Wants=hmland.service knxd.service</code>

Diese Units müssen darum nicht für den automatischen Start "enabled" werden. Sollte einer dieser Dienste nicht gestartet werden können, wird FHEM trotzdem gestartet.

== Links ==
Systemd-Dokumentation:

* [https://www.freedesktop.org/software/systemd/man/systemd.unit.html|Optionen für Units allgemein]
* [https://www.freedesktop.org/software/systemd/man/systemd.exec.html|Optionen für den Start von Prozessen]
* [https://www.freedesktop.org/software/systemd/man/systemd.service.html|Optionen für Units vom Typ service]

Diskussion:EnOcean-UPJ230 12-Jalousieaktor

2016-04-28T20:05:47Z

Benheim:

== Alternative zur readingProxy-Definition ==
Hallo!

Hat es einen bestimmten Grund, warum der Weg über ein separates readingsProxy-Device für die Slider-Darstellung gewählt wurde, statt das einfach über "widgetOverride angle:slider,1,1,100" beim EnO-Device zu lösen?

Danke und Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 10:56, 26. Apr. 2016 (CEST)

<hr>
Hallo Christian

ich habe die Angaben vom zuständigen Abteilungsleiter beim Hersteller AWAG erhalten, der mir die Konfiguration so beschrieben hat. Mir fehlen aber (noch) die Skills, zu beurteilen ob es eine bessere Lösung gibt. Ich kann das aber gerne versuchen, nächste Woche sollte ich genug Zeit haben.

Gruss, --[[Benutzer:Benheim|Benheim]] ([[Benutzer Diskussion:Benheim|Diskussion]]) 22:05, 28. Apr. 2016 (CEST)

Benutzer:Benheim

2016-04-28T18:03:36Z

Benheim:

In Bearbeitung [[/Startscript systemd|Startscript für systemd]]

EnOcean Starter Guide

2016-04-27T18:54:02Z

Benheim: /* Teach-In als Tasteremulation */

{{Todo|Noch einzuarbeitetende Moduländerungen :: http://forum.fhem.de/index.php/topic,36237.msg285274.html#msg285274: Vereinfachte Anlage von FHEM-EnOcean-Devices gemäß 18 und 19 einarbeiten, Anlage Liste von nicht offiziellen EEPs und Zuordnung zu Geräten, bessere Einbindung von getNextId ++++ http://forum.fhem.de/index.php/topic,42354.0.html: Plot-Anlage einbinden ++++ http://forum.fhem.de/index.php/topic,45810.0.html: RLT}}

<div style="float:right">
{{Infobox Modul
|Name=TCM
|ModPurpose=Einbindung EnOcean-Gateway
|ModType=d
|ModCmdRef=TCM
|ModForumArea=EnOcean
|ModTechName=00_TCM.pm
|ModOwner=klaus.schauer ([http://forum.fhem.de/index.php?action=profile;u=293 Forum] / [[Benutzer Diskussion:Klaus.schauer|Wiki]])
}}
{{Infobox Modul
|Name=EnOcean
|ModPurpose=Ansteuerung EnOcean-Geräte über TCM
|ModType=d
|ModCmdRef=EnOcean
|ModForumArea=EnOcean
|ModTechName=10_EnOcean.pm
|ModOwner=klaus.schauer ([http://forum.fhem.de/index.php?action=profile;u=293 Forum] / [[Benutzer Diskussion:Klaus.schauer|Wiki]])
}}
</div>

== EnOcean ==
[http://www.enocean.com/de/ EnOcean] ist
* ein [http://www.enocean.com/de/enocean-wireless-standard/ ISO ratifizierter Funkstandard], ausgelegt für Funksensoren und Funksensornetze mit besonders niedrigem Energieverbrauch
* ein Anbieter batterieloser Funksensoren
EnOcean-Endgeräte mit dem von der EnOcean Alliance zur Verfügung gestellten EnOcean-Funkprotokoll werden von [http://www.enocean-alliance.org/de/hiererhaeltlich/ zahlreichen Hardware-Herstellern] angeboten.

=== EnOcean Equipment Profile ===
Abhängig von den Funktionen des EnOcean-Endgerätes werden bestimmte veröffentlichte Anwendungs-Profile/Funk-Telegramme, die sogenannten EnOcean Equipment Profiles (EEPs), zur Funkkommunikation genutzt. Technische Details zum EnOcean-Funkprotokoll und insbesondere zu den [http://www.enocean-alliance.org/eep/ EnOcean Equipment Profiles (EEPs)] sind auf der Internetseite der [http://www.enocean-alliance.org EnOcean Alliance] zu finden.

==== Manufacturer Specific Communication ====
EnOcean bietet - neben den veröffentlichten Standard-Enocean-Profilen - die Möglichkeit für die Nutzung von herstellerspezifischen Anwendungs-Profilen/Funk-Telegrammen (MSC = Manufacturer Specific Communication). Falls die Herstellerfirmen den Inhalt dieser MSC-Telegramme nicht veröffentlichen, ist eine Unterstützung durch FHEM grundsätzlich nicht möglich. Teilweise werden die Produkte sowohl mit MSC- als auch mit Standard-Enocean-Profilen vertrieben [http://forum.fhem.de/index.php/topic,19544.msg132240.html#msg132240]. Angaben zu den verwendeten Profilen/Telegrammen sind den Bedienungsanleitungen der Produkte zu entnehmen.

=== uni- versus bidirektional ===
EnOcean-Endgeräte gibt es sowohl in uni- als auch in bidirektionalen Ausführungen. Bei '''unidirektionalen Endgeräten''' erfolgt die Funk-Kommunikation nur in eine Richtung. Einem Aktor, der Licht schaltet, kann zwar der Befehl zum An- bzw. Ausschalten gegeben werden, er liefert aber keine Rückinformation über die erfolgreiche Ausführung des Befehls. Bei '''bidirektionalen Endgeräten''' erfolgt die Funk-Kommunikation hingegen in zwei Richtungen: sie bieten
# Sende- und
# Empfangsmöglichkeiten.
Der bidirektionale Aktor kann somit unter anderem die erfolgreiche Ausführung eines empfangenen Befehls zurückmelden.

=== SenderID ===
Damit EnOcean Funk-Aktoren (z.B. Relais, Dimmer, Heizungsventil) auf EnOcean Sensoren (z.B. Taster, Temperatursensor, Fensterkontakt, Energieverbrauchsmesser) reagieren können, werden die Sensoren bei den Aktoren eingelernt (Teach-in). So wird festgelegt, dass z.B. "Funktaster 1" den "Dimmer 1" steuert.
Alle EnOcean Geräte mit Sendefunktion haben mindestens eine eindeutige, unabänderliche 8-stellige Hex-SenderID (z.B. ffc54500; teilweise auch dargestellt mit Punkten oder Doppelpunkten dazwischen). Die SenderID ist meist auf den EnOcean Geräten aufgedruckt oder liegt der Verpackung des Endgerätes bei. Beim Anlernvorgang wird die eindeutige SenderID des Sensors in der Empfängertabelle des Aktors gespeichert.

== EnOcean in FHEM ==
=== Allgemein ===
FHEM wird fortwährend weiterentwickelt und verbessert. Daher ist es zwingend notwendig, dass FHEM auf dem aktuellsten Stand ist. Dazu nach der FHEM-Installation den Befehl <code>update</code> ausführen und anschließend <code>shutdown restart</code> durchführen. Genauso auch vor [[#Welche_Infos_sollten_Anfragen_im_EnOcean-Forum_enthalten.3F|Anfragen im Forum]] die Aktualität von FHEM überprüfen.

Die Nutzung von EnOcean in FHEM ist für den Anfänger nur mit der standardmäßig eingeschalteten [http://fhem.de/commandref.html#autocreate autocreate-Funktion] einfach umsetzbar. Die Kenntnis der FHEM-Grundlagen und Durcharbeitung der Anfänger-Lektüren wird im Folgenden vorausgesetzt. Insbesondere sind [[Erste_Schritte_in_fhem|Erste Schritte in FHEM]] und [http://fhem.de/Heimautomatisierung-mit-fhem.pdf Heimautomatisierung mit FHEM] Pflicht, auch wenn sie nicht EnOcean behandeln, so werden doch wesentliche Punkte für ein Verständnis von FHEM vermittelt.

Im Folgenden und auf den [[:Kategorie:EnOcean Components|Wiki-Seiten der Einzelgeräte]] werden immer wieder Auszüge aus der [[Konfiguration]] dargestellt. Diese dienen zur Erläuterung und Veranschaulichung. Die Bearbeitung der [[Konfiguration]] sollte - zur Verhinderung von Fehlern - nach Möglichkeit immer über das "[[Konfiguration#Befehl-Eingabefeld|Befehl-Eingabefeld]]" und die "[[Konfiguration#Objektdetails|Objektdetails]]" erfolgen.

=== Vorbereitung ===
Die SenderIDs der EnOcean-Geräte haben eine zentrale Bedeutung in FHEM. Sie sind eindeutiges Unterscheidungsmerkmal, werden von FHEM im Rahmen der Funkkommunikation genutzt und in der Definition der Geräte bzw. den Attributen des Geräte hinterlegt. Auch wenn FHEM die SenderIDs des Gateways regelmäßig automatisch vergeben kann, ist für einen Überblick über die SenderIDs hilfreich eine Tabelle mit folgender oder ähnlicher Struktur aufzubauen:

<table class="wikitable" border="1">
<tr>
<th> A
</th>
<th> B
</th>
<th> C
</th>
<th> D
</th>
<th> E
</th></tr>
<tr>
<th> Nr.
</th>
<th> Name EnOcean
</th>
<th> Name in FHEM
</th>
<th> HEX (Sender-ID)
</th>
<th> Zimmer
</th></tr>
<tr>
<td>
</td>
<td> <Name Hardwareschalter>
</td>
<td> <Name in FHEM>
</td>
<td> <HEX Code>
</td>
<td> <Raumname>
</td></tr>
<tr>
<td>
</td>
<td> TCM_ESP3_0
</td>
<td> TCM_ESP3_0
</td>
<td> AABBCC00
</td>
<td>
</td></tr>
<tr>
<td> 1
</td>
<td> EnO_switch_123456
</td>
<td> eg_fl_Licht
</td>
<td> AABBCC01
</td>
<td> EG_Flur
</td></tr>
<tr>
<td> ...
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td></tr>
<tr>
<td> 128
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td></tr></table>

== Definition von TCM / Gateway ==
FHEM kann mit einem Funkgateway, das auf einem TCM-Modul basiert, EnOcean-Funk empfangen und senden.
Bisher gibt es zwei Transceiver Chips von EnOcean:
* TCM120 (ausgelaufen)
** für den USB-Port: [https://embedded-intelligence.de/de/products/hardware/bsc-bor.html BSC BOR]
* TCM310
** als USB-Stick: [http://www.enocean.com/de/enocean_module/usb-300-oem/ USB 300] und [http://busware.de/tiki-index.php?page=EUL Busware EUL (End-Of-Life)]
** als Aufsteckmodul für Raspberry Pi: [http://www.enocean.com/de/enocean-pi/ EnOceanPi]<BR>
::* Beim Raspberry Pi 3 muss der GPIO-Port auf den Hardware-UART0 umgestellt werden: [[Raspberry Pi 3: GPIO-Port Module und Bluetooth]]
::* Die seriellen Schnittstelle /dev/ttyAMA0 muss am Raspberry Pi freigeschaltet werden, damit das EnOceanPi-Modul funktionsfähig ist. Zur Vorgehensweise siehe: {{Link2Forum|Topic=14814|Message=95265}}

Zudem existiert eine [http://forum.fhem.de/index.php/topic,22635.msg160582.html#msg160582 Lösung zur kabelgebundenen Anbindung] des FHEM-Rechners mittels Eltako FGW14 an den [[EnOcean-Eltako-RS485-Bus|Eltako RS485-Bus]], über die sowohl Busaktoren als auch EnOcean-Funkaktoren gesteuert werden können und auch EnOcean-Funktelegramme über das [[EnOcean-Eltako-RS485-Bus|FAM14 Funkantennenmodul]] am RS485-Bus empfangen werden können.

Das TCM-basierte Gateway wird unter Linux nach Anschluss an den FHEM-Rechner beim FHEM-Start oder ohne FHEM-Neustart durch Aufruf des Befehls <code>usb scan</code> zumeist automatisch erkannt und grundlegend durch entsprechende Einträge in der Konfiguration definiert. Ein manuelles Anlegen des TCM-Moduls oder Eingriffe in die Konfiguration sind normalerweise nicht notwendig und auch nicht ratsam. Unter Windows ist ein manuelles Anlegen der Definition des TCM-Gateways wegen fehlender Unterstützung des Befehls <code>usb scan</code> notwendig.

Bei RS485-basierte Gateways (bspw. FGW14) muss in der [[Konfiguration]] zusätzlich manuell das Attribut <code>comType</code> auf <code>RS485</code> gesetzt werden.

Beispiele der automatisch erzeugten define-Zeile in der Konfiguration:

EnOceanPi an Raspberry Pi:
define TCM_ESP3_0 TCM ESP3 /dev/ttyAMA0@57600

TCM310/USB300 an Fritzbox oder Raspberry Pi:
define TCM_ESP3_0 TCM ESP3 /dev/ttyUSB0@57600

Hier folgt ein Beispiel der define-Zeile in der Konfiguration für kabelgebundene Anbindung mit FGW14 über serielle Schnittstelle
define TCM_ESP2_0 TCM ESP2 /dev/ttyS3@57600
attr TCM_ESP2_0 comType RS485 <---- Manuell zu setzen

Nach erfolgreicher Definition ist das Gateway im Raum "Everything" in der Gruppe "TCM" zu finden. Wenn neben dem Gatewaynamen "initialized" oder "opened" angezeigt wird, ist FHEM in der Lage mit den EnOcean-Geräten zu kommunizieren.

Wie im [[#SenderID|Einführungsabschnitt]] bereits erläutert hat jedes sendende EnOcean-Endgerät mindestens eine eindeutige SenderID. Diese SenderID kann aus Sicherheitsgründen nicht vom EnOcean-Gateway simuliert werden. Vielmehr hat das Gateway eigene SenderIDs, die separat in die Endgeräte/Aktoren angelernt werden müssen. Das Gateway stellt 128 verschiedene SenderIDs zur Verfügung. Ausgehend von der baseID, die bei jedem Gateway grundsätzlich anders ist, werden die SenderIDs fortlaufend hexadezimal hochgezählt:
* FHEM stehen 127 fortlaufende eigene SenderID zur Verfügung
* beginnend mit der baseID des TCM + 1

Die baseID des TCM erhält man durch Eingabe von
get TCM_ESP3_0 baseID
in das Befehl-Eingabefeld (TCM_ESP3_0 gegebenenfalls durch den eigenen Gatewaynamen ersetzen) oder duch Auswahl dieses Befehls in den Objektdetails des FHEM-Gateway-Device.

Das Webfrontend zeigt dann beispielsweise:
BaseID=AABBCC00,RemainingWriteCycles=0A
Die niedrigste SenderID in diesem Beispiel ist AABBCC0'''1''' (BaseID=AABBCC00 +1 HEX!!!), die nächste AABBCC0'''2''' usw.

Nach der Definition des Gateways und Ermittlung der baseID des Gateways kann nun der nächste Schritt, die Definition der EnOcean-Geräte in FHEM, erfolgen.

== Definition von Geräten ==
=== Definition / Anlernvorgang (Teach-In) ===
Damit FHEM und EnOcean-Geräte miteinander kommunizieren können, müssen sie miteinander bekannt gemacht werden. Dies geschieht durch Definition des Gerätes in FHEM und den Anlernvorgang. Dazu muss sich FHEM im [http://fhem.de/commandref.html#TCM_learningMode learningMode] befinden. Viele Geräte werden von FHEM während des Anlernvorgangs automatisch erkannt und definiert. Dennoch ist ein grundlegendes Verständnis der Anlernvorgänge und Unterscheidungsprinzipen in FHEM und EnOcean notwendig. Sofern das Gerät Bestätigungstelegramme verschicken kann, sind diese zwingend '''vorher''' am Gerät einzuschalten (u.a. Eltako).

FHEM entnimmt die Angaben, wie ein Funk-Telegramm für ein bestimmtes Gerät aufgebaut ist, im Wesentlichen den folgenden Attributen der Definition des Gerätes:
*<code>subtype</code>: FHEM-Profilname, der als Klartextname das genutzte EEP des Gerätes (EEP steht meist in der Bedienungsanleitung des Gerätes) repräsentiert . Einige FHEM-Profile z. B. "roomSensorControl.01" bedienen mehrere ähnliche EEP gleichzeitig.
*<code>manufID</code>: Code für den Hersteller des Gerätes (Übersetzungstabelle Code zu Name ist in der [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/FHEM/10_EnOcean.pm 10_EnOcean.pm] unter %EnO_manuf)
*<code>model</code>: Modell des Gerätes
*<code>eep</code>: EEP des Gerätes. Unter anderem werden die Informationen zur automatischen Anlage von [[FileLog]], [[SVG]] und des Attributs <code>webCmd</code> anhand des EEPs ermittelt.
Während des Anlernvorgangs werden diese Angaben von FHEM soweit wie möglich automatisch in der Definition vorbelegt. Hinweise zu den Besonderheiten von bestimmten Geräten und EEP finden sich oft in der [http://fhem.de/commandref.html#EnOcean commandref] zu EnOcean. Darum bitte immer in der commandref zunächst nach dem speziellen Gerät (Modellbezeichnung) suchen, wenn dies keinen Treffer liefert nach dem verwendeten EEP suchen. Die gegebenen Hinweise und Erläuterungen dort beachten.

Die Definition und der Anlernvorgang unterscheiden sich je nach Gerätetyp:
* Sensoren:
** [[#Schalter/Switch|Schalter (EEP RPS)]]: werden automatisch beim ersten empfangenen Funktelegramm in FHEM mit den notwendigen Attributen angelegt.
** [[#Kontakte|Kontakte (EEP 1BS)]]: werden automatisch beim ersten empfangenen Funktelegramm in FHEM mit den notwendigen Attributen angelegt.
** [[#Sonstige_Sensoren|Sonstige Sensoren (EEP 4BS)]]: Durch Versand eines speziellen Anlern-Funktelegramms können sie in FHEM automatisch mit den notwendigen Attributen angelegt werden. Im Anlerntelegramm übermittelt der Sensor FHEM die EEP-Profilangabe und die Hersteller-ID. Aufgrund dieser Angaben kann FHEM das Gerät eindeutig erkennen und die richtigen Attribute in FHEM setzen. Einige wenige Sensoren verschicken leider ein Anlerntelegramm ohne EEP-Profilangabe und/oder Herstellerangabe (Bsp: Omnio Ratio eagle-PM101). Bei diesen Sensoren müssen die Attribute subType, manufID und/oder model manuell in FHEM gesetzt werden, damit eine richtige Auswertung der Funktelegramme erfolgt.
* Aktoren (4BS, VLD, UTE, MSC): Bei den Aktoren gibt es je nach Gerätetyp verschiedene Anlernvorgänge, die unterschiedlich in FHEM ausgeführt werden. Einige Aktoren unterstützen auch mehrere Anlernvorgänge. Grundsätzlich muss wegen abweichender Vorgehensweise in FHEM unterschieden werden zwischen
** [[#uni- versus bidirektional|unidirektionalen]] Aktoren und
*** [[#Teach-In_als_Tasteremulation|Teach-In als Tasteremulation]]
*** [[#Teach-In_als_Gateway.2FPC-Steuerung|Teach-In als Gateway/PC-Steuerung]]
** [[#uni- versus bidirektional|bidirektionalen]] Aktoren
*** [[#Teach-In_als_Tasteremulation_2|Teach-In als Tasteremulation]]
*** [[#Unidirektionales_4BS-Teach-In|Unidirektionales 4BS-Teach-In]]
*** [[#Bidirektionales_4BS-Teach-In|Bidirektionales 4BS-Teach-In]]
*** [[#UTE-Teach-In|UTE-Teach-In]]

In den nachfolgenden Gliederungspunkten wird beispielhaft für je ein Gerät aus den obigen Gerätetypen die Einbindung in FHEM erläutert.

Grundlegend gilt immer:
FHEM legt sendende, noch nicht definierte EnOcean Geräte selbst an, wenn
* in Konfiguration autocreate aktiviert ist:
** <code>[http://fhem.de/commandref_DE.html#autocreate define autocreate autocreate]</code>
* FHEM/das TCM-Modul sich im <code>learningMode</code> befindet und
* FHEM eine Nachricht vom noch nicht definierten EnOcean Gerät empfängt
Im Webfrontend werden automatisch angelegte neue Geräte im Raum "EnOcean" angezeigt.

=== Sensoren ===
'''Sensoren Beispiele:'''

==== Schalter/Switch ====
[[EnOcean-PTM-210-Taster|PTM 210 - Schaltermodul]] ([http://www.enocean.com/de/enocean_module/ptm-210-data-sheet-pdf/ Datenblatt])

EEP: F6-02-xx

FHEM in den learningMode (<code>set <nowiki><IODev> teach <time/s></nowiki></code>) versetzen, dazu im Befehl-Eingabefeld eingeben:
set TCM_ESP3_0 teach 600

Dann einen beliebigen Taster des Moduls drücken (und loslassen). Beim Drücken des Tasters wird vom Taster eine Nachricht ausgesendet, die von FHEM empfangen wird. Daraufhin definiert FHEM automatisch den Taster und der Taster ist in FHEM angelernt. FHEM fügt dazu folgenden Code zur Konfiguration hinzu:
* exemplarischer Auszug aus Konfiguration
define EnO_switch_FFC54500 EnOcean FFC54500 <-- "FFC54500" ist die 8-stellige Hex-SenderID des Tasters
attr EnO_switch_FFC54500 IODev TCM_ESP3_0
attr EnO_switch_FFC54500 room EnOcean
attr EnO_switch_FFC54500 subType switch <-- handelt sich um einen Schalter
# attr EnO_switch_FFC54500 eventMap AI:off A0:on BI:an B0:aus <-- bei Bedarf ... die gemapten Werte (hier: off, on, an, aus) sollen eindeutig sein
define FileLog_EnO_switch_FFC54500 FileLog ./log/EnO_switch_FFC54500-%Y.log EnO_switch_FFC54500
attr FileLog_EnO_switch_FFC54500 logtype text

Ein Schalter (hier: FT55) hat vier Taster:
{|
| '''Taster''' || '''in FHEM'''
|-
| links oben || A0
|-
| links unten || AI (nicht "eins" sondern "i"!)
|-
| rechts oben || B0
|-
| rechts unten || BI
|}

Das Log FileLog_EnO_switch_FFC54500 zeichnet beim einmaligen Drücken des linken unteren Tasters ("AI") folgendes auf:
2014-01-01_07:00:01 EnO_switch_FFC54500 buttons: pressed
2014-01-01_07:00:01 EnO_switch_FFC54500 channelA: AI
2014-01-01_07:00:01 EnO_switch_FFC54500 AI
2014-01-01_07:00:02 EnO_switch_FFC54500 buttons: released

Der angelegte Sensor repräsentiert im Webfrontend den physischen Schalter (bspw. an der Wand). Ein Druck auf den physischen Taster ändert den Zustand im Webfrontend. Jedoch führt ein Schalten des Repräsentanten im Webfrontend nicht zu einer Schaltung des Aktors.

FHEM kann sich '''nicht''' als einer der vorhandenen (automatisch angelegten) physischen Sensoren ausgeben (um z.B. das Licht zu schalten), sondern verwendet eigene SenderIDs. Diese FHEM-eigenen SenderIDs können in EnOcean-Aktoren eingelernt werden, damit die Aktoren auf FHEM reagieren [[#Aktoren|siehe unten]].

==== Kontakte ====
[[EnOcean-STM-250-Fenster-T%C3%BCrkontakt|STM 320 Batterieloses Magnetkontakt-Funkmodul]] ([http://www.enocean.com/de/enocean_module/stm-320-data-sheet-pdf/ Datenblatt])

EEP: D5-00-01

FHEM in den learningMode versetzen, dazu im Befehl-Eingabefeld eingeben:
set TCM_ESP3_0 teach 600

Anlerntelegramm laut Anleitung verschicken oder Magnetkontakt öffnen und schließen.

Der Kontakt wird automatisch in FHEM definiert und ist angelernt.

* exemplarischer Auszug aus Konfiguration
define EnO_contact_0000FF53 EnOcean 0000FF53
attr EnO_contact_0000FF53 IODev TCM_ESP3_0
attr EnO_contact_0000FF53 room EnOcean
attr EnO_contact_0000FF53 subType contact
define FileLog_EnO_contact_0000FF53 FileLog ./log/EnO_contact_0000FF53-%Y.log EnO_contact_0000FF53
attr FileLog_EnO_contact_0000FF53 logtype text
attr FileLog_EnO_contact_0000FF53 room EnOcean

==== Sonstige Sensoren ====
===== 4BS-Teach-In =====
FHEM in den learningMode versetzen, dazu im Befehl-Eingabefeld eingeben:
set TCM_ESP3_0 teach 600
Dann das Anlerntelegramm laut Bedienungsanleitung am Sensor auslösen. Der Sensor wird dann automatisch in FHEM definiert und ist angelernt.

===== Profilloses 4BS-Teach-In =====
Omnio Ratio eagle-PM101 Licht- und Anwesenheitssensor ([http://www.omnio.ch/content-en/downloads/Betriebsanleitungen/2902000_Betriebsanleitung_ea.pdf Betriebsanleitung])

FHEM in den learningMode versetzen, dazu im Befehl-Eingabefeld eingeben:
set TCM_ESP3_0 teach 600

Das Anlerntelegramm vom Omnio Ratio eagle-PM101 verschicken (MÖGLICH??)

Im angelegten FHEM-Device manuell das Attribut <code>subType</code> auf <code>PM101</code> setzen.

=== Aktoren ===
Die Bedienungsanleitungen und die commandref liefern Informationen, welche Anlernvorgänge der Aktor unterstützt. Finden sich keine Hinweise auf besondere PC- oder Gateway-Anlernvorgänge, so kann FHEM als "Notlösung" immer als virtueller FHEM-Schalter (Tasteremulation) angelernt werden. Einige Aktoren unterstützen mehrere Arten von Anlernvorgängen. Hier ist der mit den meisten/besten Steuerungsmöglichkeiten zu bevorzugen.

'''Aktoren Beispiele:'''

==== unidirektionale Aktoren ====
Bei unidirektionalen Aktoren steht eine SenderID des TCM-Gateways immer im <code>define</code> des FHEM-Devices. Mit dieser SenderID steuert FHEM den Aktor. Diese SenderID muss dazu im Aktor eingelernt werden.
{{Hinweis|'''MERKE:''' Eine SenderID des TCM-Gateways muss bei unidirektionalen Aktoren immer im <code>define</code> des Devices stehen.<br/>
'''MERKE:''' Bei unidirektionalen Aktoren stimmt der Status des FHEM-Devices im Webfrontend nur mit dem realen Aktorzustand überein, wenn ausschließlich über FHEM gesteuert wird ([[#Physischer_EnOcean-_und_virtueller_Fhem-Schalter_zu_einem_Device_zusammenfassen|Abhilfe]])}}
===== Teach-In als Tasteremulation =====
PEHA 451 FU-EP o.T. (Schaltaktor unidirektional)

Eine [[#Wie ermittelt man freie Sender-IDs des TCM-basierten Funkgateways?|freie SenderID des TCM-basierten Gateways heraussuchen]] und diese als EnOcean-Gerät in FHEM definieren, dazu im Befehl-Eingabefeld eingeben:
define eg_fl_Licht EnOcean AABBCC01

Alternativ kann man FHEM auch anweisen, für das EnOcean-Gerät selbst die nächste freie SenderID zu ermitteln. Die Definition ist dann folgendermaßen vorzunehmen:
define eg_fl_Licht EnOcean getNextID

Anschließend das Attribut <code>subType</code> beim erzeugten Device auf <code>switch</code> setzen. Durch diese Definition wird ein 8-fach EnOcean-Taster erzeugt. Der Taster hat 4 Kanäle (A,B,C,D) zu je 2 Tasten (0,I). Alle diese 8 Taster senden mit der gleichen SenderID des TCM. Das entspricht einem Gerät mit 4 Schaltwippen die jeweils "oben" '''oder''' "unten" gedrückt sein können. FHEM emuliert mit diesem EnOcean-Gerät einen EnOcean-Schalter (darum auch "virtueller FHEM-Schalter"). Der Taster 0 des Kanal A wird "gedrückt" mit <code>set eg_fl_Licht A0</code>.

Dieser virtuelle FHEM-Schalter wird in den Aktor wie ein physischer Schalter eingelernt. Den Aktor in den Anlernmodus bringen (Taste LRN/SET drücken) und den virtuellen FHEM-Schalter betätigen, indem im Befehl-Eingabefeld eingeben wird:
set eg_fl_Licht B0
Wenn der Aktor den erfolgreichen Anlernvorgang signalisiert, den Anlernmodus am Aktor ausschalten.

* exemplarischer Auszug aus Konfiguration
define eg_fl_Licht EnOcean AABBCC01 <--- AABBCC01 ist eine der 127 SenderID's des TCM, mit der FHEM sendet
attr eg_fl_Licht room EG_Flur
attr eg_fl_Licht eventMap BI:off B0:on
attr eg_fl_Licht subType switch
define FileLog_eg_fl_Licht FileLog ./log/ eg_fl_Licht-%Y.log eg_fl_Licht
attr FileLog_eg_fl_Licht logtype text

Der Status des Devices im Webfrontend stimmt bei unidirektionalen Aktoren nur, wenn die Steuerung des Aktors ausschließlich über FHEM erfolgt. Wird der Aktor sowohl über einen physischen Schalter als auch über FHEM gesteuert, so müssen die Stati der beiden Devices für physischen und virtuellen Schalter im Webfrontend verknüpft werden, damit der richtige Status des Aktors angezeigt wird ([[#Physischer EnOcean- und virtueller FHEM-Schalter zu einem Device zusammenfassen |siehe unten]]).

===== Teach-In als Gateway/PC-Steuerung =====
"ältere" Eltako FSB61 (Produktionszeitraum KW 43/10 - KW 40/11 [http://www.eltako.com/fileadmin/downloads/de/_bedienung/FSB61NP_30200420-3_dtsch.pdf Bedienungsanleitung])

EEP: A5-3F-7F

Eine [[#Wie ermittelt man freie Sender-IDs des TCM-basierten Funkgateways?|freie SenderID des TCM-basierten Gateways heraussuchen]] und diese als EnOcean-Gerät in FHEM definieren, dazu im Befehl-Eingabefeld eingeben:
define eg_fl_Rollo EnOcean AABBCC02

Alternativ kann man FHEM auch anweisen, für das EnOcean-Gerät selbst die nächste freie SenderID zu ermitteln. Die Definiton ist dann folgendermaßen vorzunehmen:
define eg_fl_Rollo EnOcean getNextID

Beim erzeugten FHEM-Device muss das Attribut <code>subType</code> auf <code>manufProfile</code> gesetzt werden. Die Attribute <code>manufID</code> und <code>model</code> sind auf die unten in der Konfiguration gezeigten Werte zu setzen.

Dieser virtuelle FHEM-Schalter wird in den Aktor als PC/Szenentaster angelernt indem im Befehl-Eingabefeld eingeben wird:
set eg_fl_Rollo teach
Wenn der Aktor den erfolgreichen Anlernvorgang signalisiert, den Anlernmodus am Aktor ausschalten.

* exemplarischer Auszug aus Konfiguration
define eg_fl_Rollo EnOcean AABBCC02 <--- AABBCC02 ist eine der 127 SenderID's des TCM, mit der FHEM sendet
attr eg_fl_Rollo room EG_Flur
attr eg_fl_Rollo subType manufProfile
attr eg_fl_Rollo manufID 00D
attr eg_fl_Rollo model FSB61

Der Status des Devices im Webfrontend stimmt bei unidirektionalen Aktoren nur, wenn die Steuerung des Aktors ausschließlich über FHEM erfolgt. Wird der Aktor sowohl über einen physischen Schalter als auch über FHEM gesteuert, so müssen die Stati der beiden Devices für physischen und virtuellen Schalter im Webfrontend verknüpft werden, damit der richtige Status des Aktors angezeigt wird ([[#Physischer EnOcean- und virtueller FHEM-Schalter zu einem Device zusammenfassen |siehe unten]]).

==== bidirektionale Aktoren ====
Bei bidirektionalen Aktoren steht die SenderID des Aktors im <code>define</code> des FHEM-Devices. FHEM ordnet empfangene Bestätigungstelegramme anhand der Aktor-SenderID dem passenden FHEM-Device zu. Eine SenderID des TCM-Gateways mit der FHEM den Aktor steuert steht bei bidirektionalen Aktoren immer im Attribut <code>subDef</code>. Diese SenderID muss dazu im Aktor eingelernt werden.
{{Hinweis|'''MERKE:''' Eine SenderID des TCM-Gateways muss bei bidirektionalen Aktoren immer im Attribut <code>subDef</code> des Devices stehen.<br/>
'''MERKE:''' Bei bidirektionalen Aktoren stimmt nach korrekter Einbindung in FHEM der Status des FHEM-Devices im Webfrontend immer mit dem realen Aktorzustand überein.}}
===== Teach-In als Tasteremulation =====
[[EnOcean-FSR61VA-10A-Stromsto%C3%9F-Schaltrelais_mit_Strommessung|10A-Stromstoß-Schaltrelais mit Strommessung FSR61VA]]<br/>
Schaltrelais (bidirektional)

FHEM in den learningMode versetzen, dazu im Befehl-Eingabefeld eingeben:
set TCM_ESP3_0 teach 600

Die [[#SenderID|SenderID]] des Aktors heraussuchen und diese als EnOcean-Gerät in FHEM definieren, dazu im Befehl-Eingabefeld eingeben:
define EnO_switch_FSR61VA EnOcean FFAABBC0

Eine freie SenderID des TCM-basierten Gateways heraussuchen und diese im Attribut <code>subDef</code> des angelegten Devices hinterlegen.

Anschließend die Attribute <code>subType</code> und <code>switchMode</code> wie im unten wiedergegebenen exemplarischen Auszug aus der Konfiguration anlegen.

Damit der FSR61VA auf FHEM reagieren kann (Ein/Ausschalten), wird das FHEM-Device EnO_switch_FSR61VA in den FSR61VA als Richtungstaster (bzw. Taster ein/aus) eingelernt:
# Unterer Drehschalter je nach Produktionswoche des FSR61VA (aufgedruckt):
## bis KW 2/13: "ca. Mitte" (Taster Ein/Aus einlernen)
## ab KW 3/13 bis KW 10/14: "60" (Taster Ein/Aus einlernen)
## ab KW 11/14: "40" (Richtungstaster einlernen)
# Oberer Funktions-Drehschalter: "LRN" (LED blinkt)
# FHEM Eingabefeld: „set EnO_switch_FSR61VA B0“, <Enter> (LED erlischt)
# Oberer Funktions-Drehschalter: Eine der ESV-Einstellungen
# Unterer Funktions-Drehschalter: auf "oo" einstellen (unendlich)

* exemplarischer Auszug aus der Konfiguration
define EnO_switch_FSR61VA EnOcean FFAABBC0 --> EnO_switch_FSR61VA ist ein frei gewählter eindeutiger Name
für das FHEM-Device.
FFAABBC0 ist die erste am Boden des FSR61VA aufgedruckte SenderID.
Damit sendet das FSR61VA den Schaltzustand (B0/BI --> ein/aus)
attr EnO_switch_FSR61VA IODev TCM_ESP3_0 --> TCM_ESP3_0 ist der Name des Devices, mit dem FHEM EnOcean-Funk
sendet und empfängt.
attr EnO_switch_FSR61VA subDef FF998877 --> FF998877 ist eine der 127 SendeIDs des TCM_ESP3_0, damit sendet FHEM an den FSR61VA
attr EnO_switch_FSR61VA subType switch --> es handelt sich um einen EnOcean Schalter (der kann A0, AI, B0, BI,...)
attr EnO_switch_FSR61VA switchMode pushbutton --> als "pushbutton" sendet FHEM bei einem
"set EnO_switch_FSR61VA B0" nach dem Kommando (B0) noch ein "release".
Das brauchts, wenn der FSR61VA als ES oder ESV betrieben wird.
Sonst wird jedes "set"-Kommando vom FSR61VA als
"länger als eine Sekunde gedrückt" interpretiert -> "Tasterdauerlicht".

===== Unidirektionales 4BS-Teach-In =====
[[EnOcean-FSR14-4x-RS485-Bus-Schaltaktor-4-Kanal-Stromsto%C3%9F-Schaltrelais|RS485-Bus-Aktor 4-Kanal-Stromstoß-Schaltrelais FSR14]]<br/>
Schaltrelais (bidirektional)

FHEM in den learningMode versetzen, dazu im Befehl-Eingabefeld eingeben:
set TCM_ESP3_0 teach 600

Die [[#SenderID|SenderID]] des Aktors heraussuchen und diese als EnOcean-Gerät in FHEM definieren, dazu im Befehl-Eingabefeld eingeben:
define EnOcean_switch_FEFF4AF8 EnOcean FEFF4AF8

{{Randnotiz|RNText=Ab {{Link2Forum|Topic=31450|Message=239937|LinkText=Updatestand 04.01.2015}} ist eine manuelle Vergabe einer freien SenderID per <code>subDef</code> nicht mehr notwendig. Beim ersten Senden des "teach"-Befehls an den Aktor wird eine freie SenderID vergeben, sofern keine gültige SenderID eingetragen war.}}
Eine freie SenderID des TCM-basierten Gateways heraussuchen und diese im Attribut <code>subDef</code> des angelegten Devices hinterlegen.

Anschließend die Attribute <code>subType</code> und <code>gwCmd</code> wie im unten wiedergegebenen exemplarischen Auszug aus der Konfiguration anlegen.

Jetzt den Aktor in den Lernmodus versetzen und dann von FHEM das Lerntelegramm verschicken:
set EnOcean_switch_FEFF4AF8 teach
Lernmodus am Aktor ausschalten

* exemplarischer Auszug aus Konfiguration
define EnOcean_switch_FEFF4AF8 EnOcean FEFF4AF8 <--- FEFF4AF8 ist hier die SenderID eines FSR14-Kanals (Aktor)
attr EnOcean_switch_FEFF4AF8 subDef AABBCC03 <--- AABBCC03 ist eine der 127 SenderID's des TCM, mit der FHEM sendet [[#Taster - physisch und in FHEM|(siehe unten)]]
attr EnOcean_switch_FEFF4AF8 room EnOcean # Der Raum kann angepasst werden
attr EnOcean_switch_FEFF4AF8 gwCmd switching # Wichtig für FSR14
attr EnOcean_switch_FEFF4AF8 subType gateway # Wichtig für FSR14
define FileLog_EnOcean_switch_FEFF4AF8 FileLog ./log/EnOcean_switch_FEFF4AF8-%Y.log EnOcean_switch_FEFF4AF8
attr FileLog_EnOcean_switch_FEFF4AF8 logtype text

===== Bidirektionales 4BS-Teach-In =====
[[EnOcean-MD15-Kleinstellantrieb|Kleinstellantrieb MD15-FTL-xx]]<br/>
Funkgesteuerter, batteriegespeister Kleinstellantrieb für Raumtemperaturregelung (bidirektional)

EEP: A5-20-01

4BS-Bidirektionales-Teach-In:

#Aktor möglichst komplett zurücksetzen, sofern nicht mehr im Original-Auslieferzustand
#Falls vorhanden, alle bisherigen FHEM-Devices des Aktors löschen und nach Speichern der geänderten Konfiguration FHEM neu starten
#FHEM in Lernmodus schalten: <code>set <nowiki><IODev> teach <time/s></nowiki></code>
#Taster am MD15-FTL-xx so lange drücken, bis ein Signalton ertönt. MD15 bestätigt erfolgreichen Anlernvorgang durch das Aufleuchten der Status-LED und 2 Signaltöne
#Aktor wird in FHEM automatisch mit allen notwendigen Parametern angelegt.

* exemplarischer Auszug aus Konfiguration
define EnO_sensor_01000EFA EnOcean 01000EFA
attr EnO_sensor_01000EFA IODev TCM_ESP3_0
attr EnO_sensor_01000EFA comMode biDir
attr EnO_sensor_01000EFA destinationID unicast
attr EnO_sensor_01000EFA manufID 00A
attr EnO_sensor_01000EFA room EnOcean
attr EnO_sensor_01000EFA subDef AABBCC04
attr EnO_sensor_01000EFA subType hvac.01
define FileLog_EnO_sensor_01000EFA FileLog ./log/EnO_sensor_01000EFA-%Y.log EnO_sensor_01000EFA
attr FileLog_EnO_sensor_01000EFA logtype text
attr FileLog_EnO_sensor_01000EFA room EnOcean

===== UTE-Teach-In =====
[[EnOcean-D-452-FU-EBIM-Aktor-2fach|Einbau-Aktor 452 FU-EBIM o.T.]]<br/>
2-Kanal-Multifunktionsaktor (bidirektional) mit Energiemessfunktion

EEP: D2-01-08

UTE-Teach-In:

#Aktor möglichst komplett zurücksetzen, sofern nicht mehr im Original-Auslieferzustand
#Falls vorhanden, alle bisherigen FHEM Devices des Aktors löschen und nach Speichern der geänderten Konfiguration FHEM neu starten
#FHEM in Lernmodus schalten: <code>set <nowiki><IODev> teach <time/s></nowiki></code>
#Aktor-Kanal 0 oder 1 in Lernmodus versetzen (immer nur einen Kanal)
#Aktor-Kanal 0 oder 1 wird in FHEM automatisch mit allen notwendigen Parametern angelegt.
#Das Anlernen für den zweiten Kanal wie nach 3. bis 5. beschrieben wiederholen

Die Kanäle können jetzt geschaltet werden mit:

*FHEM Device für Kanal 0: set <Name_0> on|off 0
*FHEM Device für Kanal 1: set <Name_1> on|off 1

Falls gewünscht, kann der Kanal mit dem Attribut attr <Name_0|1> defaultChannel 0|1 voreingestellt werden. Dann entfällt die Angabe des Kanals im set-Befehl.

Die Statusrückmeldungen mit den aktuellen Werten des Energieverbrauches und der Leistung werden vom Aktor automatisch gesendet. Sie werden sowohl als Telegramme nach EEP D2-01-08 als auch nach EEP A5-11-04 mit unterschiedlichen SenderIDs (vgl. Etikett in Original-Verpackung) gesendet.
Die Rückmeldungen nach EEP D2-01-08 werden von FHEM im Aktor-Device subType actuator.01 berücksichtigt. Die Rückmeldungen nach EEP A5-11-04 werden von FHEM in einem senor-device subType lightCtrlState.02 berücksichtigt.

== Besonderheiten für die Anzeige im WebFrontend ==

=== Aufteilung der Kanäle in unabhängige Devices ===
===== Mehrkanalige bidirektionale Aktoren =====
Mehrkanalige bidirektionale Aktoren (bspw. Eltako FMS61NP) haben teilweise nur eine SenderID und werden daher in FHEM über ein FHEM-Device im Webfrontend abgebildet und gesteuert. Um im WebFrontend für jeden Kanal ein separates FHEM-Device zur Anzeige und Steuerung zu erhalten, kann [[ReadingsProxy|readingsProxy]] genutzt werden.

Zunächst wird der Aktor standardmäßig in FHEM definiert/angelernt und die Funktion geprüft (hier am Beispiel eines Aktor mit dem Namen "Aktor"). Anschließend wird pro Kanal ein readingProxy-Device mit Bezug auf das Reading channelA, channelB, ... angelegt:

#Kanal A zur Steuerung mit on und off
define AktorKanalA readingsProxy Aktor:channelA
attr AktorKanalA setFn {($CMD eq "on")?"A0":"AI";;}
attr AktorKanalA setList off on
attr AktorKanalA valueFn {($VALUE eq "A0")?"on":"off"}
attr AktorKanalA webCmd off:on

#Kanal B zur Steuerung mit on und off
define AktorKanalB readingsProxy Aktor:channelB
attr AktorKanalB setFn {($CMD eq "on")?"B0":"BI";;}
attr AktorKanalB setList off on
attr AktorKanalB valueFn {($VALUE eq "B0")?"on":"off"}
attr AktorKanalB webCmd off:on

Jeder Kanal wird jetzt separat im WebFrontend durch das readingsProxy-Device abgebildet (Statusanzeige) und kann mit diesem gesteuert werden.

===== Virtuelle Schalter für unidirektionale Aktoren =====
Um die 4 Kanäle jeweils einzeln als Schalter (einzelne Schaltwippe) im WebFrontend abzubilden kann [[ReadingsProxy|readingsProxy]] genutzt werden. So werden vier Schalter (im unten gezeigten Beispiel: fhemSchalterKanal[A-D]) mit nur einer der 127 eigenen SenderIDs zur Verfügung gestellt.

Anders als bei den bekannten bidirektionalen Aktoren und den FHEM-Devices der physischen Schalter, existiert bei den virtuellen Schaltern das Reading channelA, channelB, ... nicht. Daher muss das readingsProxy für den virtuellen Schalter vom Reading state abgeleitet werden:

#Kanal A zur Steuerung mit on und off
define fhemSchalterKanalA readingsProxy fhemSchalter:state
attr fhemSchalterKanalA setFn {($CMD eq "on")?"A0":"AI";;}
attr fhemSchalterKanalA setList on off
attr fhemSchalterKanalA valueFn {$LASTCMD}
attr fhemSchalterKanalA webCmd on:off

#Kanal B zur Steuerung mit on und off
define fhemSchalterKanalB readingsProxy fhemSchalter:state
attr fhemSchalterKanalB setFn {($CMD eq "on")?"B0":"BI";;}
attr fhemSchalterKanalB setList on off
attr fhemSchalterKanalB valueFn {$LASTCMD}
attr fhemSchalterKanalB webCmd on:off

#Kanal C zur Steuerung mit on und off
define fhemSchalterKanalC readingsProxy fhemSchalter:state
attr fhemSchalterKanalC setFn {($CMD eq "on")?"C0":"CI";;}
attr fhemSchalterKanalC setList on off
attr fhemSchalterKanalC valueFn {$LASTCMD}
attr fhemSchalterKanalC webCmd on:off

#Kanal D zur Steuerung mit on und off
define fhemSchalterKanalD readingsProxy fhemSchalter:state
attr fhemSchalteKanalD setFn {($CMD eq "on")?"D0":"DI";;}
attr fhemSchalterKanalD setList on off
attr fhemSchalterKanalD valueFn {$LASTCMD}
attr fhemSchalterKanalD webCmd on:off

Werden diese FHEM-Taster (und etwaige physische Taster) in EnOcean-Aktoren eingelernt (siehe Anleitung des Aktors), so können nun die EnOcean-Aktoren mit physischen Tastern (sendet mit der 8-stelligen SenderID des Tasters) und mit virtuellen FHEM-Readingsproxy-Schaltern (senden mit einer der 127 eigenen SenderIDs) bedient werden.

=== Physischer EnOcean- und virtueller Fhem-Schalter zu einem Device zusammenfassen ===
Um im Webfrontend die Aktionen beider Schalter in einem Element zusammengefasst und damit den realen Zustand bei '''unidirektionalen''' Aktoren zu sehen, kann man eine <code>structure</code> nutzen:
<br />
(Bei bidirektionalen Aktoren ist dies aufgrund der Statusrückmeldungen nicht notwendig. Achtung: Teilweise müssen Statusrückmeldungen/Bestätigungstelegramme erst am Aktor eingeschaltet werden)

#Definition des virtuellen FHEM-Schalters
define fhemSchalter EnOcean AABBCC01 <--- AABBCC01 ist eine der 127 SenderID's des TCM, mit der FHEM sendet
attr fhemSchalter eventMap BI:off B0:on
attr fhemSchalter icon icoBELEUCHTUNG.png
attr fhemSchalter subType switch

#Definition des physischen Tasters (z.B. durch autocreate erzeugt)
define EnO_switch_0021E4BB EnOcean 0021E4BB <--- 0021E4BB ist die (aufgedruckte) 8-stellige SenderID des physischen Tasters
attr EnO_switch_0021E4BB eventMap BI:off B0:on
attr EnO_switch_0021E4BB room EnOcean
attr EnO_switch_0021E4BB subType switch
attr EnO_switch_0021E4BB dummy

#fhemSchalter ist der Name des virtuellen FHEM-Schalters
#EnO_switch_0021E4BB ist der (z.B. per autocreate erstellte) FHEM-Taster
define Gruppe_test_notify structure room fhemSchalter EnO_switch_0021E4BB
attr Gruppe_test_notify eventMap BI:off B0:on
attr Gruppe_test_notify room Gaestezimmer
attr Gruppe_test_notify clientstate_behavior last

Alternativ kann man für diesen Zweck auch ein <code>notify</code> in Verbindung mit <code> setreading <device> state <state></code> nutzen:

define nAbgleich notify EnO_switch_0021E4BB:(on|off) setreading fhemSchalter state $EVENT

== FAQ ==
=== Warum schaltet mein Aktor nicht, wenn ich im WebFrontend auf das Icon für den physischen Taster/Schalter klicke bzw. mit <code>set <device> <command></code> ansteuere? ===
:Aus Sicherheitsgründen können bei EnOcean keine physischen Geräte(-adressen) durch FHEM bzw. das TCM-Gateway emuliert werden. FHEM muss zur Steuerung separat an den Aktor angelernt werden. Dazu eine der TCM-Adressen an den Aktor anlernen.

=== Welche Infos sollten Anfragen im EnOcean-Forum enthalten? ===
* Anfragen bitte nur zur aktuellsten FHEM-Version: Befehl <code>update</code> ergibt Ausgabe "nothing to do..."
* detaillierte Beschreibung des Problems
* beteiligte Komponenten (genaue Bezeichnung und evtl. Link auf Hersteller-Dokumentation)
* list des jeweiligen devices (<code>list <device></code>) oder zumindest Config-Auszug
* passender Ausschnitt aus Logfile (siehe Link im FHEM-Menülinks) mit verbose 5 (<code>attr <device> verbose 5</code>)

=== Wie kann ich zur Fortentwicklung der EnOcean-Module beitragen? ===
* Erfolgreichen Einsatz von neuen/bisher nicht gemeldeten EnOcean-Geräten im Forum mitteilen
* In der Commandref als [untested] markierte EEPs bei erfolgreichen Tests im Forum als getestet melden
* Codeschnipsel und Ideen im Forum posten
* Fehler und Probleme im Forum melden
* Wiki: Neue Geräte ins Wiki aufnehmen; Codeschnipsel und Beispiele einpflegen

=== Wie findet man die Sender-ID eines bidirektionalen Aktors? ===
* Aufkleber auf dem Aktor oder beigelegte Information in der Aktorverpackung
* Ermittlung mit FHEM:
# Bestätigungstelegramme am Aktor aktivieren
# Funktaster am Aktor anlernen oder alternativ Taster am örtlichen Steuereingang anschließen
# FHEM in den learningMode versetzen: <code>set <nowiki><IODev> teach <time/s></nowiki></code>
# [[Event monitor|Event Monitor]] aufrufen
# Aktor mit Taster schalten
# Im Event Monitor wird nun die Sender-ID des Aktors durch das Bestätigungstelegramm angezeigt. Sofern ein Funktaster zur Ansteuerung genutzt wird, zeigt der Event Monitor auch dessen Sender-ID.
# FHEM hat mittels autocreate für das Bestätigungstelegramm ein Device angelegt, sofern das vorher noch nicht existierte. Dieses Device kann man nach eventueller Änderung des subType und dem Setzen anderer gegebenenfalls notwendiger Attribute an den Aktor anlernen.

=== Wie ermittelt man freie Sender-IDs des TCM-basierten Funkgateways? ===
FHEM ermittelt eine freie SenderID automatisch, wenn die Definition folgermaßen erfolgt:
* unidirektionaler Aktor:
: <code><nowiki>define <name> EnOcean getNextID <EEP></nowiki></code>
: Im definierten Device ist "getNextID" durch eine freie SenderID des TCMs ersetzt.
* bidirektionaler Aktor:
: <code><nowiki>define <name> EnOcean <SenderId des Aktors> <EEP></nowiki></code>
: Dem definierten Device wird das Attribut <code>subDef</code> mit dem Wert <code>getNextId</code> zugewiesen: <code><nowiki>attr <name> subDef getNextID</nowiki></code>. "getNextID" ersetzt FHEM automatisch durch eine freie SenderID des TCMs

Manuelle Ermittlung der freien SenderIDs, wenn die obige automatische mit FHEM fehlschlägt oder eine manuelle Vergabe gewünscht wird:
* Aus der oben [[EnOcean_Starter_Guide#Vorbereitung|gezeigten Tabelle]]
* Anzeige der nächsten freien Sender-ID: <pre>{EnOcean_CheckSenderID("getNextID", "<IODev>", "0000000")} </pre>
* Auflistung der bereits vergebenen Sender-IDs: <pre>{EnOcean_CheckSenderID("getUsedID", "<IODev>", "0000000")} </pre>
* Auflistung der noch nicht vergebenen Sender-IDs: <pre>{EnOcean_CheckSenderID("getFreeID", "<IODev>", "0000000")} </pre>
Den jeweiligen Befehl in das "[[Konfiguration#Befehl-Eingabefeld|Befehl-Eingabefeld]]" kopieren, <IODev> durch den Namen des TCM-Devices ersetzen und dann Auslösen.

=== Schaltet immer AI ein und A0 aus, BI ein und B0 aus usw. ? ===
Nein. <br>
Das Verhalten der Aktoren ist abhängig vom Hersteller und/oder vom Anlernvorgang. Laut EEP schaltet xI ein und x0 aus. Dies wird von den meisten Herstellern entsprechend umgesetzt. Eltako definiert dies genau andersherum: xI schaltet aus und x0 ein. Analog sind auch die jeweiligen Bestätigungstelegramme der Aktoren herstellerspezifisch festgelegt. Zudem kann bei einigen Aktoren auch je nach Anlernvorgang ein anderes Verhalten erreicht werden; Details enthalten die Bedienungsanleitungen.

=== Wie kann man einen Plot für ein EnOcean-Device anlegen? ===
Bei der manuellen Anlage von Devices über das EEP und bei der automatischen Anlage durch die autocreate-Funktion beim teach-in werden neben dem Device selbst auch das FileLog-Device und -soweit als Vorlage von FHEM mitgeliefert- die SVG-Devices mit .gplot-Datei für die Plots automatisch erzeugt. Manuell sollten die Devices deshalb möglichst über die Vorgabe des EEP erzeugt werden:
* <code><nowiki>define <name> EnOcean <ID> <EEP></nowiki></code> oder
* <code><nowiki>define <name> EnOcean <EEP></nowiki></code>

Beispiel:
<code><nowiki>define test EnOcean A5-04-02</nowiki></code>

Bei bestehenden Devices können die FileLog- und SVG-Devices nachträglich erzeugt werden. Hierzu wird im DEF das entsprechende EEP statt der ID eingetragen und {{Taste|modify <name>}} bestätigt. Nach dem automatischen Anlegen der zugehörigen Devices erscheint dort wieder die ID.

Sollte für das EEP keine .gplot-Vorlage für einen Plot bzw. das SVG-Device existieren, kann ein Plot mit dem [[Plots erzeugen|.gplot-Editor]] erstellt werden.

=== Was muss man beim Einsatz der "set extensions" (on-for-timer, on-till, ...) beachten? ===
Die [http://fhem.de/commandref#setExtensions set extensions] werden von EnOcean grundsätzlich unterstützt, wenn das Device als
# set-Befehle "on" und "off" automatisch anbietet '''oder'''
# dies manuell durch das Mapping (bspw. <code>eventMap BI:on B0:off</code>) erreicht wird.

Im 1. Fall sind alle "set extensions"-Befehle automatisch funktionsfähig.

Im 2. Fall ist die eventMap jedoch zusätzlich - je nach gewünschten "set extensions"-Befehl - zwingend weiter zu ergänzen:
* on-tor-timer: <code>attr <device> eventMap on-for-timer:on-for-timer BI:on B0:off</code> ({{Link2Forum|Topic=28855|Message=214960}})
* off-tor-timer: <code>attr <device> eventMap off-for-timer:off-for-timer BI:on B0:off</code>
* on-till: <code>attr <device> eventMap on-till:on-till BI:on B0:off</code> ({{Link2Forum|Topic=29993|Message=226886}})
* off-till: <code>attr <device> eventMap off-till:off-till BI:on B0:off</code>
* blink: <code>attr <device> eventMap on-for-timer:on-for-timer BI:on B0:off</code> ({{Link2Forum|Topic=31358|Message=239151}})
* intervals: <code>attr <device> eventMap on-till:on-till BI:on B0:off</code>
Sollen mehrere "set extensions"-Befehle verwendet werden, so sind die obigen Codes entsprechend zu kombinieren.

=== Für mein EnOcean-Gerät gibt es keine spezielle Wiki-Seite; wo finde ich dann Informationen? ===
* In der commandref nach dem Gerät suchen
* In der commandref nach dem verwendeten EEP suchen
* Im Wiki nach einem Gerät mit einer ähnlichen EEP/subType suchen
* Im EnOcean-Forum nach Threads zum Gerät/EEP suchen

=== Warum funktioniert mein Eltako-Gerät nicht wie in commandref/Wiki beschrieben? ===
* Eltako-Geräte haben bei gleicher Produktbezeichnung teilweise je nach Produktionswoche unterschiedliche Funktionen/Eigenschaften
* die Produktionswoche ist auf dem Gerät angegeben (z.B. 11/14 -> Elfte Woche im Jahr 2014)
* in den nach Produktionswoche untergliederten [http://www.eltako.com/de/bedienungsanleitungen/der-gebaeudefunk.html Bedienungsanleitungen] stehen genauere Angaben
* Angaben in commandref/Wiki analog für die Angaben laut Bedienungsanleitung für den speziellen Produktionszeitraum umsetzen
* bei gravierenden Abweichungen und Neuerungen Info im Forum/Wiki

=== Wie kann ich Eltako-Aktoren anhand Ihrer Modellbezeichnung grob unterscheiden? ===
* 12er Baureihe (ausgelaufen) = unidirektionale RS485-Bus-Aktoren für Hutschiene
* 14er Baureihe = bidirektionale RS485-Bus-Aktoren für Hutschiene
* 61er Baureihe = uni- und bidirektionale Aktoren je nach Produktionszeitraum für Einbaumontage (Hohlwanddose)
* 70/71er Baureihe = uni- und bidirektionale Aktoren je nach Produktionszeitraum für Einbaumontage (Zwischendecke)
* zwischen den Modellreihen gibt es bei uni- und bidirektonalen Aktoren bei der Ansteuerung Übereinstimmungen; Angaben können dementsprechend analog zwischen den Geräten übertragen werden

=== Wie kann ich PEHA-Aktoren anhand Ihrer Modellbezeichnung grob unterscheiden? ===
* Easyclick-Unterputzempfänger: unidirektionale Aktoren für Einbaumontage; Modellbezeichnung enthält typischerweise die Buchstaben EP
* Easyclickpro-Unterputzempfänger: bidirektionale Aktoren für Einbaumontage; Modellbezeichnung enthält die Buchstaben EBI oder EBIM (mit zusätzlicher Energiemessung)

=== Wo finde ich Angaben zu Jäger Direkt - OPUS GreenNet EnOcean-Geräten? ===
* Es handelt sich im Wesentlichen um umgelabelte Produkte anderer Hersteller (Peha, Eltako usw.). Anhand der Gehäuseform lassen sich Rückschlüsse ziehen
* Angaben zu den "Original"-Produkten können grundsätzlich -soweit bekannt- auf OPUS GreenNet Geräte übertragen werden

[[Kategorie:HOWTOS]]
[[Kategorie:EnOcean Components]]

EnOcean-UPJ230 12-Jalousieaktor

2016-04-25T20:37:37Z

Benheim: "Baustelle" entfernt

{{Infobox Hardware
|Bild=Omnio_UPJ230.jpg
|Bildbeschreibung=UPJ230/12 UP Multifunktions-Jalousieaktor 1-Kanal
|HWProtocol=EnOcean
|HWType=Aktor, Empfänger, Sensor, Repeater
|HWCategory=EnOcean
|HWComm=EnOcean Funk, 868Mhz
|HWChannels=1 (bidirektional)
|HWVoltage=230V~
|HWPowerConsumption=Eigenverbrauch 0,4W
|HWPoweredBy=230V
|HWSize=45x50x25mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#EnOcean EnOcean]
|HWManufacturer=[http://www.awag.ch/ AWAG Elektrotechnik AG]
}}

'''EnOcean-UPJ230/12-Jalousieaktor''' ist ein Aktor
* für
** Unterputzmontage
* für
** Steuerung von Rollladen, Beschattungselementen und elektrisch betriebenen Fenstern
== Features ==
Aktor für Beschattungselemente, Rolladen und elektrisch betriebenen Fenster, mit Repeater-Funktion

=== Definition/Anlernvorgang ===
Der Aktor kann, wenn der EnOcean-Empfänger in den Anlernmodus geschaltet wurde, automatisch per autocreate in Fhem angelegt werden. Für die Auswertung und Einstellung der Lamellenposition ist danach manuell ein <code>readingsProxy</code> definiert werden.

Folgende Schritte sind vorzunehmen:

* Fhem Eingabefeld: <code>set TCM_ESP3_0 teach 300</code> (Lernmodus für 5 Minuten)
* Drehschalter am Aktor auf Stellung 13
* Taste LRN am Aktor für 2 Sekunden drücken
* Drehschalter am Aktor auf Stellung 11
* Taste LRN am Aktor drücken

Die Definition des Aktors wird nun erstellt.

Um Zwischenpositionen und Lamellenstellungen anfahren zu können, muss direkt am Aktor die Laufzeit gemäss beiliegender Anleitung erfasst werden (siehe Anleitung S. 4).

=== Fhem Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration|fhem.cfg]]:

define Jal_01 EnOcean 0185D7E8
attr Jal_01 IODev TCM_ESP3_0
attr Jal_01 comMode biDir
attr Jal_01 devChannel 0
attr Jal_01 eep D2-05-00
attr Jal_01 manufID 005
attr Jal_01 subDef FFEFF301
attr Jal_01 subType blindsCtrl.00
attr Jal_01 teachMethod UTE
attr Jal_01 webCmd opens:stop:closes:position

Um die Lamellenstellung zu steuern:

define Jal_01_Lamellen readingsProxy Jal_01:anglePos
attr Jal_01_Lamellen setList angle:slider,1,1,100
attr Jal_01_Lamellen webCmd angle

Diese Definition sollte auch für die Steuerung von Fenstern vorgenommen werden. Andernfalls übernimmt der Aktor diese Steuerung, dabei stellt er die Lamellen nach dem Schliessen standardmässig auf "Auf". Dadurch öffnet sich ein Fenster nach dem Schliessen wieder ein wenig. Ist die Winkelstellung in FHEM eingerichtet, wird das Verhalten des Aktors übersteuert und dauernd auf "Zu" gehalten, das Fenster bleibt nach dem Schliessen geschlossen.

== Einsatzbeispiel ==
Siehe Beispiele hier: [[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen]]

== Links ==
* Anleitung: [http://www.awag.ch/ekat/page_de/upload_insta/UPJ230_12_Bd.pdf PDF]

[[Kategorie:EnOcean Components]]
[[Kategorie:Rollladensteuerung]]

Benutzer:Benheim

2016-04-25T20:37:12Z

Benheim:

Keine Seite aktuell in Bearbeitung

EnOcean-UPJ230 12-Jalousieaktor

2016-04-25T20:35:10Z

Benheim: Benheim verschob die Seite FHEMWiki:EnOcean-UPJ230 12-Jalousieaktor nach EnOcean-UPJ230 12-Jalousieaktor

{{Baustelle}}

{{Infobox Hardware
|Bild=Omnio_UPJ230.jpg
|Bildbeschreibung=UPJ230/12 UP Multifunktions-Jalousieaktor 1-Kanal
|HWProtocol=EnOcean
|HWType=Aktor, Empfänger, Sensor, Repeater
|HWCategory=EnOcean
|HWComm=EnOcean Funk, 868Mhz
|HWChannels=1 (bidirektional)
|HWVoltage=230V~
|HWPowerConsumption=Eigenverbrauch 0,4W
|HWPoweredBy=230V
|HWSize=45x50x25mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#EnOcean EnOcean]
|HWManufacturer=[http://www.awag.ch/ AWAG Elektrotechnik AG]
}}

'''EnOcean-UPJ230/12-Jalousieaktor''' ist ein Aktor
* für
** Unterputzmontage
* für
** Steuerung von Rollladen, Beschattungselementen und elektrisch betriebenen Fenstern
== Features ==
Aktor für Beschattungselemente, Rolladen und elektrisch betriebenen Fenster, mit Repeater-Funktion

=== Definition/Anlernvorgang ===
Der Aktor kann, wenn der EnOcean-Empfänger in den Anlernmodus geschaltet wurde, automatisch per autocreate in Fhem angelegt werden. Für die Auswertung und Einstellung der Lamellenposition ist danach manuell ein <code>readingsProxy</code> definiert werden.

Folgende Schritte sind vorzunehmen:

* Fhem Eingabefeld: <code>set TCM_ESP3_0 teach 300</code> (Lernmodus für 5 Minuten)
* Drehschalter am Aktor auf Stellung 13
* Taste LRN am Aktor für 2 Sekunden drücken
* Drehschalter am Aktor auf Stellung 11
* Taste LRN am Aktor drücken

Die Definition des Aktors wird nun erstellt.

Um Zwischenpositionen und Lamellenstellungen anfahren zu können, muss direkt am Aktor die Laufzeit gemäss beiliegender Anleitung erfasst werden (siehe Anleitung S. 4).

=== Fhem Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration|fhem.cfg]]:

define Jal_01 EnOcean 0185D7E8
attr Jal_01 IODev TCM_ESP3_0
attr Jal_01 comMode biDir
attr Jal_01 devChannel 0
attr Jal_01 eep D2-05-00
attr Jal_01 manufID 005
attr Jal_01 subDef FFEFF301
attr Jal_01 subType blindsCtrl.00
attr Jal_01 teachMethod UTE
attr Jal_01 webCmd opens:stop:closes:position

Um die Lamellenstellung zu steuern:

define Jal_01_Lamellen readingsProxy Jal_01:anglePos
attr Jal_01_Lamellen setList angle:slider,1,1,100
attr Jal_01_Lamellen webCmd angle

Diese Definition sollte auch für die Steuerung von Fenstern vorgenommen werden. Andernfalls übernimmt der Aktor diese Steuerung, dabei stellt er die Lamellen nach dem Schliessen standardmässig auf "Auf". Dadurch öffnet sich ein Fenster nach dem Schliessen wieder ein wenig. Ist die Winkelstellung in FHEM eingerichtet, wird das Verhalten des Aktors übersteuert und dauernd auf "Zu" gehalten, das Fenster bleibt nach dem Schliessen geschlossen.

== Einsatzbeispiel ==
Siehe Beispiele hier: [[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen]]

== Links ==
* Anleitung: [http://www.awag.ch/ekat/page_de/upload_insta/UPJ230_12_Bd.pdf PDF]

[[Kategorie:EnOcean Components]]
[[Kategorie:Rollladensteuerung]]

EnOcean-UPJ230 12-Jalousieaktor

2016-04-25T20:33:35Z

Benheim: Benheim verschob die Seite Benutzer:Benheim/EnOcean-UPJ230 12-Jalousieaktor nach FHEMWiki:EnOcean-UPJ230 12-Jalousieaktor

EnOcean-UPJ230 12-Jalousieaktor

2016-04-25T20:32:10Z

Benheim:

EnOcean-UPJ230 12-Jalousieaktor

2016-04-25T14:20:05Z

Benheim:

{{Baustelle}}

{{Infobox Hardware
|Bild=Omnio_UPJ230.jpg
|Bildbeschreibung=UPJ230/12 UP Multifunktions-Jalousieaktor 1-Kanal
|HWProtocol=EnOcean
|HWType=Aktor, Empfänger, Sensor, Repeater
|HWCategory=EnOcean
|HWComm=EnOcean Funk, 868Mhz
|HWChannels=1 (bidirektional)
|HWVoltage=230V~
|HWPowerConsumption=Eigenverbrauch 0,4W
|HWPoweredBy=230V
|HWSize=45x50x25mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#EnOcean EnOcean]
|HWManufacturer=[http://www.awag.ch/ AWAG Elektrotechnik AG]
}}

'''EnOcean-UPJ230/12-Jalousieaktor''' ist ein Aktor
* für
** Unterputzmontage
* für
** Steuerung von Rollladen, Beschattungselementen und elektrisch betriebenen Fenstern
== Features ==
Aktor für Beschattungselemente, Rolladen und elektrisch betriebenen Fenster, mit Repeater-Funktion

=== Definition/Anlernvorgang ===
Der Aktor kann, wenn der EnOcean-Empfänger in den Anlernmodus geschaltet wurde, automatisch per autocreate in Fhem angelegt werden. Für die Auswertung und Einstellung der Lamellenposition ist danach manuell ein <code>readingsProxy</code> definiert werden.

Folgende Schritte sind vorzunehmen:

* Fhem Eingabefeld: <code>set TCM_ESP3_0 teach 300</code> (Lernmodus für 5 Minuten)
* Drehschalter am Aktor auf Stellung 13
* Taste LRN am Aktor für 2 Sekunden drücken
* Drehschalter am Aktor auf Stellung 11
* Taste LRN am Aktor drücken

Die Definition des Aktors wird nun erstellt.

Um Zwischenpositionen und Lamellenstellungen anfahren zu können, muss direkt am Aktor die Laufzeit gemäss beiliegender Anleitung erfasst werden (siehe Anleitung S. 4).

=== Fhem Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration|fhem.cfg]]:

define Jal_01 EnOcean 0185D7E8
attr Jal_01 IODev TCM_ESP3_0
attr Jal_01 comMode biDir
attr Jal_01 devChannel 0
attr Jal_01 eep D2-05-00
attr Jal_01 manufID 005
attr Jal_01 subDef FFEFF301
attr Jal_01 subType blindsCtrl.00
attr Jal_01 teachMethod UTE
attr Jal_01 webCmd opens:stop:closes:position

Um die Lamellenstellung zu steuern:

define Jal_01_Lamellen readingsProxy Jal_01:anglePos
attr Jal_01_Lamellen setList angle:slider,1,1,100
attr Jal_01_Lamellen webCmd angle

Diese Definition sollte auch für die Steuerung von Fenstern vorgenommen werden. Andernfalls übernimmt der Aktor diese Steuerung, dabei stellt er die Lamellen nach dem Schliessen standardmässig auf "Auf". Dadurch öffnet sich ein Fenster nach dem Schliessen wieder ein wenig. Ist die Winkelstellung in FHEM eingerichtet, wird das Verhalten des Aktors übersteuert und dauernd auf "Zu" gehalten, das Fenster bleibt nach dem Schliessen geschlossen.

== Einsatzbeispiel ==
Siehe Beispiele hier: [[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen]]

== Links ==
* Anleitung: [http://www.awag.ch/ekat/page_de/upload_insta/UPJ230_12_Bd.pdf PDF]

-[-[-Kategorie:EnOcean Components]]
-[-[-Kategorie:Rollladensteuerung]]

EnOcean-UPJ230 12-Jalousieaktor

2016-04-25T14:19:00Z

Benheim:

{{Baustelle}}

{{Infobox Hardware
|Bild=Omnio_UPJ230.jpg
|Bildbeschreibung=UPJ230/12 UP Multifunktions-Jalousieaktor 1-Kanal
|HWProtocol=EnOcean
|HWType=Aktor, Empfänger, Sensor, Repeater
|HWCategory=EnOcean
|HWComm=EnOcean Funk, 868Mhz
|HWChannels=1 (bidirektional)
|HWVoltage=230V~
|HWPowerConsumption=Eigenverbrauch 0,4W
|HWPoweredBy=230V
|HWSize=45x50x25mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#EnOcean EnOcean]
|HWManufacturer=[http://www.awag.ch/#AWAG Elektrotechnik AG]
}}

'''EnOcean-UPJ230/12-Jalousieaktor''' ist ein Aktor
* für
** Unterputzmontage
* für
** Steuerung von Rollladen, Beschattungselementen und elektrisch betriebenen Fenstern
== Features ==
Aktor für Beschattungselemente, Rolladen und elektrisch betriebenen Fenster, mit Repeater-Funktion

=== Definition/Anlernvorgang ===
Der Aktor kann, wenn der EnOcean-Empfänger in den Anlernmodus geschaltet wurde, automatisch per autocreate in Fhem angelegt werden. Für die Auswertung und Einstellung der Lamellenposition ist danach manuell ein <code>readingsProxy</code> definiert werden.

Folgende Schritte sind vorzunehmen:

* Fhem Eingabefeld: <code>set TCM_ESP3_0 teach 300</code> (Lernmodus für 5 Minuten)
* Drehschalter am Aktor auf Stellung 13
* Taste LRN am Aktor für 2 Sekunden drücken
* Drehschalter am Aktor auf Stellung 11
* Taste LRN am Aktor drücken

Die Definition des Aktors wird nun erstellt.

Um Zwischenpositionen und Lamellenstellungen anfahren zu können, muss direkt am Aktor die Laufzeit gemäss beiliegender Anleitung erfasst werden (siehe Anleitung S. 4).

=== Fhem Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration|fhem.cfg]]:

define Jal_01 EnOcean 0185D7E8
attr Jal_01 IODev TCM_ESP3_0
attr Jal_01 comMode biDir
attr Jal_01 devChannel 0
attr Jal_01 eep D2-05-00
attr Jal_01 manufID 005
attr Jal_01 subDef FFEFF301
attr Jal_01 subType blindsCtrl.00
attr Jal_01 teachMethod UTE
attr Jal_01 webCmd opens:stop:closes:position

Um die Lamellenstellung zu steuern:

define Jal_01_Lamellen readingsProxy Jal_01:anglePos
attr Jal_01_Lamellen setList angle:slider,1,1,100
attr Jal_01_Lamellen webCmd angle

Diese Definition sollte auch für die Steuerung von Fenstern vorgenommen werden. Andernfalls übernimmt der Aktor diese Steuerung, dabei stellt er die Lamellen nach dem Schliessen standardmässig auf "Auf". Dadurch öffnet sich ein Fenster nach dem Schliessen wieder ein wenig. Ist die Winkelstellung in FHEM eingerichtet, wird das Verhalten des Aktors übersteuert und dauernd auf "Zu" gehalten, das Fenster bleibt nach dem Schliessen geschlossen.

== Einsatzbeispiel ==
Siehe Beispiele hier: [[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen]]

== Links ==
* Anleitung: [http://www.awag.ch/ekat/page_de/upload_insta/UPJ230_12_Bd.pdf PDF]

-[-[-Kategorie:EnOcean Components]]
-[-[-Kategorie:Rollladensteuerung]]

Datei:Omnio UPJ230.jpg

2016-04-25T14:17:50Z

Benheim: Mit freundlicher Genehmigung der AWAG AG.

Mit freundlicher Genehmigung der AWAG AG.

Hue

2016-04-24T09:37:44Z

Benheim: /* HUE-Device */ Link unter kompatible Modelle auf Wiki-Eintrag zu HUE Dimmer eingefügt

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

|ModCmdRef=HUEBridge
|ModForumArea=Beleuchtung
|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 Phillips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Beleuchtung
|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 ein mal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss bei nächsten Fhem-Neustart das Paring erneut durchgefürt werden.

Eine ausführliche Anleitung mit Bildern zudem unter: http://www.meintechblog.de/2014/11/philips-hue-so-klappt-die-integration-in-fhem/

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man

<pre>attr <HUEBridge_Name> httpUtils 1</pre>

setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden. Dies sind zur Zeit (Anfang 2014):
*HueBulbs (alle drei Modelle)
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom und Iris
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*[[HUE_Dimmer_Switch|HUE Dimmer]]
Diese sind jeweils über eine Bridge (HueDevice) aus steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.
=== 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 .<br>
Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

=== 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.

== RaspBee ==
Das HUEBridge Modul unterstützt in einer beta version auch das RaspBee ZigBee Modul über die zugehörige deCONZ Software und die Wireless Light Control WebApp mit dem REST plugin. Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet sollten aber auch funktionieren.

== 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 <b>lib-Verzeichnis</b> 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=hier}}

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

Benutzer:Benheim

2016-04-23T15:25:34Z

Benheim:

In Bearbeitung: [[/EnOcean-UPJ230_12-Jalousieaktor]]

EnOcean-PTM-210-Taster

2016-04-23T15:25:07Z

Benheim: Omnio Wandsender als Beispiel hinzugefügt (IMHO einziges Modell nach CH-Norm)

{{Infobox Hardware
|Bild=PTM215_F1FT65_FT55.jpg
|Bildbeschreibung=EnOcean Funktaster: Eltako FT55 (schwarz), in seine Einzelteile zerlegter Eltako F1FT65, links unten das PTM215
|HWProtocol=EnOcean
|HWType=Sender, Sensor
|HWCategory=EnOcean
|HWComm=EnOcean Funk, 868Mhz
|HWChannels=2
|HWVoltage=
|HWPowerConsumption=
|HWPoweredBy=Tastendruck
|HWSize=
|HWDeviceFHEM=[http://fhem.de/commandref.html#EnOcean EnOcean]
|HWManufacturer=EnOcean, diverse
}}

'''EnOcean-PTM-210-Taster''' ist "das" batterielose Funkschaltmodul
* für
** Schalter/Taster und Fernbedienungen ohne Verschlüsselungsfunktion

== Features ==
=== EnOcean-PTM-210-Taster ===
"Das" batterielose Funkschaltmodul, das in den Schaltern/Tastern oder Fernbedienungen ohne Verschlüsselungsfunktion von diversen Hersteller genutzt wird (z.b. Eltako FT4, FT55, Peha Easyclick-2-Kanal-Wandsender, AWAG Omnio Wandsender WS-CH-102...). Die Energie für das Funktelegramm wird durch den Tastendruck erzeugt. Das Funkmodul hat 2 Kanäle. Bei den Wandtastern wird durch Aufklicken von einer Einzelwippe daraus ein 1-kanaliger Einfach-Wandtaster bzw. durch Aufklicken von 2 Wippen ein 2-kanaliger Doppeltaster
=== EnOcean-PTM-215-Taster ===
wie PTM-210, jedoch zusätzlich mit zuschaltbarer verschlüsselter Datenübertragung, verbaut z.B. in Eltako 1FT65, FT55
== Hinweise zum Betrieb mit Fhem ==
=== Definition/Anlernvorgang ===
Der Sensor wird bei Versand eines Telegramms vollständig von Fhem im <code>learningMode</code> erkannt. Definition in der Konfiguration erfolgt dann automatisch durch autocreate.

Anlernvorgang:
# Fhem in Lernmodus schalten: <code><nowiki>set <IODev> teach <time/s></nowiki></code>
# Funktelegramm durch Druck auf eine Taste auslösen. Das Anlegen in der Konfiguration erfolgt dann automatisch per autocreate.

=== Besonderheiten bei verschlüsseltem PTM-215 über Eltako FAM14/FGW14 ===
Ist FHEM über ein FGW14 an ein FAM14 angeschlossen und erhält darüber EnOcean-Funktelegramme, so ist eine ggf. aktivierte Verschlüsselung eines PTM-215 für FHEM grundsätzlich transparent (der Taster muss nach Anleitung im FAM14 eingelernt werden und funktioniert anschließend so, als wäre er nicht verschlüsselt). Damit die korrekten channelA- und B-Events erzeugt werden, sind aber nach dem automatischen Anlegen des Tasters durch FHEM noch folgende Schritte durchzuführen (PTM_215 ist im folgenden der Devicename des Tasters):
<pre>
attr PTM_215 subType switch.7F
attr PTM_215 manufID 00D
</pre>

=== Fhem Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration]]:
<pre>
define EnO_switch_FFC54500 EnOcean FFC54500 <-- "FFC54500" ist die 8-stellige Hex-SenderID des Tasters
attr EnO_switch_FFC54500 IODev TCM310_0
attr EnO_switch_FFC54500 room EnOcean
attr EnO_switch_FFC54500 subType switch
</pre>

=== Logbeispiel ===
<pre>
2014-01-01_07:00:01 EnO_switch_FFC54500 buttons: pressed
2014-01-01_07:00:01 EnO_switch_FFC54500 channelA: AI
2014-01-01_07:00:01 EnO_switch_FFC54500 AI
2014-01-01_07:00:02 EnO_switch_FFC54500 buttons: released
2014-01-01_07:00:03 EnO_switch_FFC54500 buttons: pressed
2014-01-01_07:00:03 EnO_switch_FFC54500 channelB: BI
2014-01-01_07:00:03 EnO_switch_FFC54500 BI
2014-01-01_07:00:03 EnO_switch_FFC54500 buttons: released
</pre>

== Einsatzbeispiel ==
Wie zu Anfang beschrieben, kann ein PTM-210/215 bis zu vier verschiedene Events erzeugen. Diese werden in FHEM als A0/AI (für die linke Tasterseite oben bzw. unten) und B0/BI (für die rechte Tasterseite oben bzw. unten) abgebildet. Um eine Lampe beim Betätigen des linken oberen Tasters einzuschalten, wäre also folgende Definition möglich:
<pre>
define nLampeAn notify PTM_215:A0 set Lampe on
</pre>

=== "Mehrfachklick"-Erkennung ===
Am 07.09.2014 wurde für das Kommando <code>sequence</code> das Attribut <code>triggerPartial</code> eingeführt. Damit kann ein Mehrfachklick erkannt und entsprechend der Klickanzahl eine unterschiedliches Szenario ausgeführt werden ({{Link2Forum|Topic=26772|Message=198050}}).

Bei einem Update-Stand von Fhem vor dem 08.09.2014 kann mit folgendem Code für eine Tasterseite (B0) ein Doppelklick erkannt werden:

define sDoppelklickB0 sequence Taster2:channelB:.B0 1 Taster2:channelB:.B0
define nDoppelklickB0 notify DoppelklickB0:trigger set Lampe off
define wEinfachklickB0 watchdog Taster2:channelB:.B0 00:00:01 SAME set Lampe on;; trigger wEinfachklickB0 .
attr wEinfachklickB0 regexp1WontReactivate 1

aus {{Link2Forum|Topic=22289|Message=186698}}
=== "Taste lange gedrückt" und "Taste kurz gedrückt" unterscheiden ===

Beide Tasterseiten (B0/BI) unterscheiden hiermit die Tastdauer (bei einem Einfachtaster):

define nklickdauer notify Taster:buttons:.released {\
my $start=time_str2num(ReadingsTimestamp("$NAME", "channelB", 0));;\
my $stop=time_str2num(ReadingsTimestamp("$NAME", "buttons", 0));;\
if (ReadingsVal("$NAME","channelB",0) eq "B0"){\
if ($stop-$start<=1) {fhem "set Raffstore 50"} else {fhem "set Raffstore 100"}}\
else {if ($stop-$start<=1) {fhem "set Raffstore 20"} else {fhem "set Raffstore 80"}}\
}

Gleichen Zweck erfüllt auch der Code für eine Tasterseite (BI)

define Schalter1BIlongclick notify Schalter1:BI define Test at +00:00:01 set Alles off
define sSchalter1BIlongclick sequence Schalter1:BI 1 Schalter1:buttons:.*released
define nSchalter1BIlongclick notify sSchalter1BIlongclick:trigger delete Test

oder alternativ diese Variante mit Nutzung von <code>sequence</code> und dem Attribut <code>triggerPartial</code>

define sKurzerLangerDruck sequence Taster:BI 0.5 Taster:buttons:.released
attr sKurzerLangerDruck triggerPartial 1
define nKurzerDruck notify sKurzerLangerDruck:trigger set Raffstore 100
define nLangerDruck notify sKurzerLangerDruck:partial_1 set Raffstore 50

aus {{Link2Forum|Topic=22289|Message=186698}}, der auch eine Variante für einen Doppeltaster enthält.

Ein weitergehendes Anwendungsbeispiel für eine indirekte Dimmersteuerung: [[Enocean_Dimmer_mit_kurzem_und_langem_Tastendruck_ansteuern|Enocean Dimmer mit kurzem und langem Tastendruck ansteuern]]

== Links ==
* Datenblatt: [http://www.enocean.com/de/enocean_module/ptm-210-data-sheet-pdf/ PDF]

[[Kategorie:EnOcean Components]]
[[Kategorie:Schalter (Sender)]]

Benutzer:Benheim

2016-04-23T15:15:20Z

Benheim:

In Bearbeitung: [[/EnOcean-UPJ230_12-Jalousieaktor]] [[/EnOcean-WS-CH-Wandsender-4-Kanal]]

EnOcean-UPJ230 12-Jalousieaktor

2016-04-23T12:58:16Z

Benheim: Die Seite wurde neu angelegt: „{{Baustelle}} {{Infobox Hardware |Bild=nopicrightnow.jpg |Bildbeschreibung=UPJ230/12 UP Multifunktions-Jalousieaktor 1-Kanal |HWProtocol=EnOcean |HWType=Aktor…“

{{Baustelle}}

{{Infobox Hardware
|Bild=nopicrightnow.jpg
|Bildbeschreibung=UPJ230/12 UP Multifunktions-Jalousieaktor 1-Kanal
|HWProtocol=EnOcean
|HWType=Aktor, Empfänger, Sensor, Repeater
|HWCategory=EnOcean
|HWComm=EnOcean Funk, 868Mhz
|HWChannels=1 (bidirektional)
|HWVoltage=230V~
|HWPowerConsumption=Eigenverbrauch 0,4W
|HWPoweredBy=230V
|HWSize=45x50x25mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#EnOcean EnOcean]
|HWManufacturer=[http://www.awag.ch/#AWAG Elektrotechnik AG]
}}

'''EnOcean-UPJ230/12-Jalousieaktor''' ist ein Aktor
* für
** Unterputzmontage
* für
** Steuerung von Rollladen, Beschattungselementen und elektrisch betriebenen Fenstern
== Features ==
Aktor für Beschattungselemente, Rolladen und elektrisch betriebenen Fenster, mit Repeater-Funktion

=== Definition/Anlernvorgang ===
Der Aktor kann, wenn der EnOcean-Empfänger in den Anlernmodus geschaltet wurde, automatisch per autocreate in Fhem angelegt werden. Für die Auswertung und Einstellung der Lamellenposition ist danach manuell ein <code>readingsProxy</code> definiert werden.

Folgende Schritte sind vorzunehmen:

* Fhem Eingabefeld: <code>set TCM_ESP3_0 teach 300</code> (Lernmodus für 5 Minuten)
* Drehschalter am Aktor auf Stellung 13
* Taste LRN am Aktor für 2 Sekunden drücken
* Drehschalter am Aktor auf Stellung 11
* Taste LRN am Aktor drücken

Die Definition des Aktors wird nun erstellt.

Um Zwischenpositionen und Lamellenstellungen anfahren zu können, muss direkt am Aktor die Laufzeit gemäss beiliegender Anleitung erfasst werden (siehe Anleitung S. 4).

=== Fhem Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration|fhem.cfg]]:

define Jal_01 EnOcean 0185D7E8
attr Jal_01 IODev TCM_ESP3_0
attr Jal_01 comMode biDir
attr Jal_01 devChannel 0
attr Jal_01 eep D2-05-00
attr Jal_01 manufID 005
attr Jal_01 subDef FFEFF301
attr Jal_01 subType blindsCtrl.00
attr Jal_01 teachMethod UTE
attr Jal_01 webCmd opens:stop:closes:position

Um die Lamellenstellung zu steuern:

define Jal_01_Lamellen readingsProxy Jal_01:anglePos
attr Jal_01_Lamellen setList angle:slider,1,1,100
attr Jal_01_Lamellen webCmd angle

Diese Definition sollte auch für die Steuerung von Fenstern vorgenommen werden. Andernfalls übernimmt der Aktor diese Steuerung, dabei stellt er die Lamellen nach dem Schliessen standardmässig auf "Auf". Dadurch öffnet sich ein Fenster nach dem Schliessen wieder ein wenig. Ist die Winkelstellung in FHEM eingerichtet, wird das Verhalten des Aktors übersteuert und dauernd auf "Zu" gehalten, das Fenster bleibt nach dem Schliessen geschlossen.

== Einsatzbeispiel ==
Siehe Beispiele hier: [[EnOcean-FSB61-Aktor-Beschattungselemente-Rollladen]]

== Links ==
* Anleitung: [http://www.awag.ch/ekat/page_de/upload_insta/UPJ230_12_Bd.pdf PDF]

-[-[-Kategorie:EnOcean Components]]
-[-[-Kategorie:Rollladensteuerung]]

Benutzer:Benheim

2016-04-23T11:49:12Z

Benheim: Die Seite wurde neu angelegt: „In Bearbeitung: /EnOcean-UPJ230_12-Jalousieaktor“

In Bearbeitung: [[/EnOcean-UPJ230_12-Jalousieaktor]]