FHEMWiki - Benutzerbeiträge [de]

Arduino Firmata

2022-12-08T20:08:59Z

Slanesh:

{{Hinweis|Device::Firmata Updates: Bis Oktober 2020 wurde eine Kopie des Perl-Moduls ''Device::Firmata'' als Teil von FHEM zur Verfügung gestellt, zuletzt die Version 0.64 aus 05/2018. In neueren Installation von FHEM ist das Modul nicht mehr enthalten. Die aktuelle Version des Moduls gibt es über [[#CPAN|CPAN]]. Bei bestehenden Installationen sollte die vorhandene Kopie des Moduls gelöscht und auf die aktuelle Version umgestellt werden (siehe Punkt 1 dieses {{Link2Forum|Topic=114552|Message=1087982|Linktext=Beitrag}}s im Forum).
}}

{{Infobox Modul
|ModPurpose=Schnittstelle für Firmata-Devices (USB, LAN, WiFi)
|ModType=d
|ModCmdRef=FRM
|ModForumArea=Sonstige Systeme
|ModTechName=10_FRM.pm
|ModOwner=JensB ({{Link2FU|14024|Forum}}/[[Benutzer Diskussion:JensB|Wiki]])
}}

== Firmata-Devices ==

Für Arduinos (und diverse kompatible Boards) gibt es eine Standardimplementierung des Kommunikationsprotokolls ''Firmata'' [https://github.com/firmata/protocol]. Mit Hilfe des Perl-Moduls ''Device::Firmata'', auch bekannt als perl-firmata [https://github.com/ntruchsess/perl-firmata], kann das Firmata-Protokoll in Perl genutzt werden und mit dem Modul [[#FRM|FRM]] auch in FHEM.

Für die Kommunikation zwischen FHEM (Master) und Firmata-Device (Slave) stehen mehrere Schnittstellen zur Auswahl: RS-232, USB, Ethernet und WiFi. Insbesondere Ethernet und WiFi erlauben die Integration dezentraler IO-Periperie mit FHEM.

Firmata ermöglicht es, mit nur geringen Arduino-Kenntnissen digitale und analoge Signale aus eigenen Schaltungen in FHEM zu verarbeiten. Dabei können Signale sowohl eingelesen als auch ausgegeben werden. Ein Verständnis der Bedienung der Arduino-IDE und elektronische Kenntnisse zum Anschluss von Sensoren und Aktoren sind natürlich erforderlich.

=== Arduino IDE ===

Zur Installation von Firmware auf dem Firmata-Device wird natürlich erst mal die Arduino-IDE (Version 1.8 oder höher) benötigt [https://www.arduino.cc/en/main/software]. Die gibt es für die Betriebssysteme Windows, Mac OS X und Linux.

Über die Bibliotheksverwaltung der Arduino-IDE (Menü 'Sketch'->'Bibliothek einbinden'->'Bibliotheken verwalten...') stehen verschiedene Firmware-Versionen von Firmata zur Auswahl. Im folgenden wird auf die Version "Firmata by Firmata Developers" und "ConfigurableFirmata by Firmata Developers" eingegangen. Diese beiden Versionen unterscheiden sich in den unterstützten Hardware-Funktionen:

* Firmata: digitale und analoge I/Os, Servos, I2C
* ConfigurableFirmata: zusätzlich 1-Wire und Schrittmotoren

Bei ConfigurableFirmata ist es auch außerdem einfacher, nicht benötigte Funktionen zu deaktivieren, damit die Firmware möglichst wenig Speicher belegt. Wenn man den zusätzlichen Funktionsumfang von ConfigurableFirmata nicht benötigt, kann man mit etwas Geschick durch Auskommentieren von nicht benötigtem Code aus Firmata z.T. ein noch kompakteres Ergebnis erzielen (das ist aber nur etwas für Fortgeschrittene).

Bei Firmata ist zwischen der Firmata-Protokoll-Version (z.B. 2.6.0) und der Version der jeweiligen Firmware (Firmata: z.B. 2.5.7, ConfigurableFirmata: z.B. 2.10.0) zu unterscheiden, die insbesondere bei ConfigurableFirmata voneinander unabhängig sind.

Nach Installation der gewünschten Firmata-Firmware wählt man eines der funktionsfertigen Beispiele über das Arduino-IDE Menü 'Datei'->'Beispiele'->'Firmata' bzw. 'Datei'->'Beispiele'->'ConfigurableFirmata' aus. Je nach ausgewähltem Beispielprojekt sind noch Anpassungen direkt im Sketch oder in einer zusätzlichen Konfigurationsdatei erforderlich (z.B. um für Ethernet- und WiFi-Schnittstellen die Netzwerkparameter einzustellen).

Über das Arduino-IDE Menü 'Werkzeuge'->'Bords' wählt man das Board aus, das dem eigenen Firmata-Device entspricht. Fehlt das Board in der Auswahl, kann die erforderliche Unterstützung oft über das Menü 'Werkzeuge'->'Bords'->'Boardverwalter...' nachinstalliert werden. Ansonsten hilft ein Blick auf die Hersteller-Webseiten des Boards.

Ist das Firmata-Device korrekt angeschlossen, drückt man den 'Upload'-Knopf (der mit dem Rechspfeil oben links), um den Arduino-Sketch zu kompilieren und auf das Board hochzuladen. Die Vorgehensweise zum Hochladen ist sehr stark davon abhängig, welches Board man verwendet und mit welcher Technik es angeschlossen ist. Bitte die jeweiligen Angaben des Board-Herstellers beachten.

Wer zum ersten mal mit der Arduino-IDE arbeitet, sollte statt Firmata zunächst das Standard Arduino Beispielprojekt 'Blink' auswählen und es auf dem Firmata-Device installieren. Sobald das klappt, kann man mit Firmata weiter machen.

=== Firmata mit Ethernet oder WiFi ===

Vor dem Kompilieren muss man unbedingt die Netzwerkparameter anpassen, d.h. die IP-Adresse des FHEM-Servers und den Port des FRM-Moduls eintragen (ggf. auch eine neue eindeutige MAC-Adresse), bei WiFi auch die SSID und den PSK. In älteren Firmata-Versionen und bei ConfigurableFirmata geschieht das direkt im Sketch. Aktuelle Firmata-Versionen haben dazu eine getrennte Konfigurationsdatei (ethernetConfig.h bzw. wifiConfig.h), so dass keine Änderungen am Sketch erforderlich sind.

Falls der Speicherbedarf der kompilierten Firmware die Möglichkeiten des Boards übersteigt (insbesondere bei Verwendung eines ENC28J60-Ethernet-Shields [https://github.com/ntruchsess/arduino_uip] in Kombination mit einem "kleinen" Arduiono wie den Uno oder Nano) kann man bei Verwendung von ConfigurableFirmata nicht benötigten Features im Sketch auskommentieren. Wenn der Speicherbedarf nur "knapp" ausreicht, läuft die Firmware u.U. trotzdem nicht zuverlässig.

Als ersten Funktionstest für die Netzwerkverbindung empfiehlt sich ein Ping von FHEM zum Firmata-Device.

=== Sonderfälle ===

Je nach verwendetem Board sind u.U. individuelle Besonderheiten zu berücksichtigen. Hier ein paar Beispiele:

Ein MEGA256 z.B. benutzt einen anderen Pin als SS (Slave select) zur Kommunikation mit dem Ethernetmodul. Man muss der Firmata im Setup mitteilen, welche Pins zu ignorieren sind, damit es keine Wechselwirkungen zwischen Firmata und Ethernet Library gibt. Das ist im ConfigurableFirmata-Sketch [https://github.com/firmata/arduino/blob/configurable/examples/ConfigurableFirmata/ConfigurableFirmata.ino] vorbereitet und muss (wenn man etwas anderes als ein Standard-Ethernetshield am Uno verwendet) geeignet angepasst werden (Beim Mega muss man z.B. den Pin 10 ignorieren und Pin 53 als hardcodiert auf Output stellen). Das gleiche gilt, wenn man eine andere Hardware (z.B. mit ENC28J60 anstelle des WizNet W5100 des Ethernetshields) benutzen möchte, die einen anderen Pin als CS/SS benutzt.

== FHEM FRM-Device ==

Bei FHEM stellt ein FRM-Device (Modul 10_FRM.pm) für die FRM-Client-Devices die Schnittstelle (das IODev) zum Firmata-Device zur Verfügung. Jeder FRM-Client erlaubt die Konfiguration eines oder mehrerer Pins eines Firmata-Devices z.B. als analoger Eingang, digitaler Ausang oder I2C-Bus. Es können so viele FRM-Clients für ein FRM-Device definiert werden, bis alle Pins zugeordnet sind. Dabei muss man darauf achten, dass nicht alle Pins alle Ein-/Ausgabemöglichkeiten besitzen. Konfiguriert man einen Pin für einen nicht unterstützen Modus so gibt es bei aktuellen Firmata-Versionen eine Fehlermeldung. Ältere Versionen (vor 2.3) schlucken Fehlkonfigurationen aber der betreffende Pin funktioniert dann nicht.

Vor dem Anlegen des FRM-Devices muss das Perl-Modul ''Device::Firmata'' installiert werden. Dies kann abhänig von den vorhandenen Voraussetzung und Vorlieben auf unterschiedliche Weise erfolgen, Details zur Installation und zum Update von Perl-Modulen finden sich im [[#CPAN|Artikel über CPAN]]. Eine mögliche Installationsvariante auf einem Raspberry Pi ist:

<pre>
sudo cpan install Device::Firmata
</pre>

Beispiele für das Anlegen eines FRM-Devices:

<hr />

<nowiki># definiere FRM mit USB-Schnittstelle /dev/ttyUSB0, Baudrate 57600 ist Default für StandardFirmata
define FIRMATA FRM /dev/ttyUSB0@57600</nowiki>

<nowiki># definiere FRM mit TCP/IP-Schnittstelle auf Port 3030
define FIRMATA FRM 3030 global</nowiki>

FRM öffnet bei Netzwerkverbindungen FHEM-seitig einen Serverport (dieser wird in der define-Zeile angegeben). 'global' muss zusätzlich angegeben werden, damit der Serversocket an alle IP-Adressen gebunden wird. Ohne 'global' sind nur Verbindungen für 'localhost' möglich. Das Firmata-Device verbindet sich aktiv zu diesem Port, sonst gilt im Prinzip alles was auch für den über USB angebunden Firmata-Device gilt.

<nowiki># für alle analogen Eingangs-Pins
attr FIRMATA sampling-interval 1000 # [ms] - maximal 16384 setzbar</nowiki>

siehe auch: {{Link2CmdRef|Anker=FRM}} FRM

Hat man mehrere FRM-Devices definiert, muss man nach dem Anlegen eines FRM-Client-Devices dessen Attribut ''IODev'' überprüfen und ggf. ändern, wenn das gewünschte FRM-Device nicht automatisch erkannt wurde.

Es folgt eine Auflistung der generischen FRM-Client-Devices. Darüber hinaus gibe es noch mehrere spezialisierte FRM-Client-Devices, vor allem für I2C-Bus-Devices (siehe {{Link2CmdRef}}):

=== 20_FRM_IN.pm ===

Macht einen Pin als digitalen Eingang nutzbar.

<nowiki>define Firmata_IN FRM_IN 12 # definiert Pin 12 als digitalen Eingang</nowiki>

siehe auch: {{Link2CmdRef|Anker=FRM_IN}} FRM_IN

=== 20_FRM_OUT.pm ===

Macht einen Pin als digitalen Ausgang nutzbar.

<nowiki>define Firmata_OUT FRM_OUT 11 # definiert Pin 11 als digitalen Ausgang</nowiki>

siehe auch: {{Link2CmdRef|Anker=FRM_OUT}} FRM_OUT

=== 20_FRM_AD.pm ===

Macht einen Pin als analogen Eingang nutzbar.

<nowiki>define Firmata_ANALOG FRM_AD 17 # definiert Pin 17 als analogen Eingang</nowiki>

siehe auch: {{Link2CmdRef|Anker=FRM_AD}} FRM_AD

=== 20_FRM_PWM.pm ===

Macht einen Pin als analogen Ausgang nutzbar. Es wird ein pulsweitenmoduliertes Signal ausgegeben.

define Firmata_ANALOG FRM_PWM 10 # definiert Pin 10 als PWM-Ausgang

siehe auch: {{Link2CmdRef|Anker=FRM_PWM}} FRM_PWM

=== 20_FRM_SERVO.pm ===

Erlaubt die Ansteuerung eines analogen Modelbauservos über einen Pin per PWM.

define Firmata_ANALOG FRM_SERVO 9 # definiert Pin 9 als Servo-Ausgang

siehe auch: {{Link2CmdRef|Anker=FRM_SERVO}} FRM_SERVO

=== 20_FRM_I2C.pm ===

<p>Erlaubt das Lesen und Schreiben über den I2C-Bus am Firmata-Device.</p>
siehe auch: {{Link2CmdRef|Anker=FRM_I2C}}FRM_I2C

=== 20_FRM_RGB.pm ===

<p>Erlaubt das Ansteuern eines RGB-LED-Controller per PWM.</p>
siehe auch: {{Link2CmdRef|Anker=FRM_RGB}}FRM_RGB

=== 20_FRM_ROTENC.pm ===

<p>Erlaubt das Auswerten eines Drehgebers.</p>
siehe auch: {{Link2CmdRef|Anker=FRM_ROTENC}}FRM_ROTENC

=== 20_FRM_STEPPER.pm ===

<p>Erlaubt das Ansteuern eines Schrittmotors.</p>
siehe auch: {{Link2CmdRef|Anker=FRM_STEPPER}}FRM_STEPPER

=== OneWire-Firmata ===

<p>Der Artikel [[Arduino mit OneWireFirmata]] beschreibt, wie man am Firmata-Device angeschlossene 1-Wire Devices in FHEM einzubindet.</p>
siehe auch: {{Link2CmdRef|Anker=OWX}} OWX

[[Kategorie:Other_Components]]
[[Kategorie:Arduino]]
[[Kategorie:HOWTOS]]

FTUI Widget Chart

2022-04-25T10:35:42Z

Slanesh: /* Attribute */ data-xtext_offset ergänzt

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
Datei:FTUI Widget Chart Stacked.png
Datei:FTUI Widget Chart-fc-Proplanta.png
Datei:Wetterchart2.png
Datei:PieChart.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"<br>Beachte: Der Wert "CURRENT" ermöglicht die Navigation auch zu älterne Logfiles (Jahreswechsel)
|-
|'''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 (siehe [[#Aussehen_der_Linien|Hinweise]])||||
|-
|'''data-ptype'''||Form, wie die Graphen dargestellt werden sollen (z.B. 'lines', 'cubic' oder 'fa-cog'), oder ein Array (siehe [[#Form_der_Linien|Hinweise]])||'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_format'''||Dient zur Formatierung der Ticks der Y-Achse. Die Formatierung geschieht über Platzhalter, Trenner und einen beliebigen durch ' ' getrennten Text. Als Platzhalter dient ein oder mehrere '#', als Trenner können '.', ',' und ':' verwendet werden. Ist ein Trenner enthalten (z.B. '#.##') dann bedeutet das in dem Beispiel, dass der Ytick mit 2 Nachkommastellen versehen wird und vorne Platz für eine Stelle vor dem Komma vorgehalten wird (führende Nullen werden nicht dargestellt, aber de Platz wird reserviert so dass das ganze rechtsbündig immer passt). Ist kein Trenner vorhanden, dann wird der Ytick auf die Summe der Platzhalter mit einer festen Gesamtbreite gesetzt (#### würde also bedeuten, dass immer 4 Stellen (ohne Trenner) verwendet werden. aus 0.4 würde 0.400 aus 10.437 würde 10.44). Als Trenner kann man z.B. für Zeiten auch einen ':' verwenden und dadurch auch so etwas wie "12:00 Uhr" realisieren (in dem Beispiel wäre data-yticks_format="##:## Uhr" und kein data-yunit oder data-yticks="##:##" und data-yunit="Uhr").||||data-yticks_format="#.##"
|-
|'''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_format_sec'''||Dient zur Formatierung der Ticks der Y-Achse. Die Formatierung geschieht über Platzhalter, Trenner und einen beliebigen durch ' ' getrennten Text. Als Platzhalter dient ein oder mehrere '#', als Trenner können '.', ',' und ':' verwendet werden. Ist ein Trenner enthalten (z.B. '#.##') dann bedeutet das in dem Beispiel, dass der Ytick mit 2 Nachkommastellen versehen wird und vorne Platz für eine Stelle vor dem Komma vorgehalten wird (führende Nullen werden nicht dargestellt, aber de Platz wird reserviert so dass das ganze rechtsbündig immer passt). Ist kein Trenner vorhanden, dann wird der Ytick auf die Summe der Platzhalter mit einer festen Gesamtbreite gesetzt (#### würde also bedeuten, dass immer 4 Stellen (ohne Trenner) verwendet werden. aus 0.4 würde 0.400 aus 10.437 würde 10.44). Als Trenner kann man z.B. für Zeiten auch einen ':' verwenden und dadurch auch so etwas wie "12:00 Uhr" realisieren (in dem Beispiel wäre data-yticks_format="##:## Uhr" und kein data-yunit oder data-yticks="##:##" und data-yunit="Uhr").||||data-yticks_format_sec="#.##"
|-
|'''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-ytype'''||Legt fest, ob die primäre y Achse logarithmisch sein soll (wert "log")||||data-ytype="log"
|-
|'''data-ytype_sec'''||Legt fest, ob die sekundäre y Achse logarithmisch sein soll (wert "log")||||data-ytype_sec="log"
|-
|'''data-margin'''|||Abstand zwischen Buttons und Chart (Einheit Pixel). ||"0"|||data-margin="10"
|-
|'''data-y_margin'''|||Gibt die Möglichkeit, Abstände zwischen den Graphen und dem oberen Rand des Plots zu definieren (Einheit Pixel). Falls der Wert skalar ist, werden oben und unten die gleichen Abstände eingehalten. Falls ein 2D Array angegeben wird, können die Werte unten (erster Wert im Array) und oben (zweiter Wert im Array) getrennt festgelegt werden||"0"|||data-y_margin='["10","20"]'
|-
|'''data-y_margin_sec'''|||Gibt die Möglichkeit, Abstände zwischen den Graphen und dem oberen Rand des Plots zu definieren (Einheit Pixel). Falls der Wert skalar ist, werden oben und unten die gleichen Abstände eingehalten. Falls ein 2D Array angegeben wird, können die Werte unten (erster Wert im Array) und oben (zweiter Wert im Array) getrennt festgelegt werden||"0"|||data-y_margin='["10","20"]'
|-
|'''data-daysago_start'''||Anzahl der vergangenen Tage, wo das Diagramm beginnen soll. '0' = Beginn heute 0:00 Uhr. (siehe [[#Zeitstrahl_.2F_Start_.26_Ende_auf_der_X-Achse|Hinweise]])||'0'||
|-
|'''data-daysago_end'''||Anzahl der vergangenen Tage, wo das Diagramm enden soll. '-1' = Ende heute 24:00 Uhr. (siehe [[#Zeitstrahl_.2F_Start_.26_Ende_auf_der_X-Achse|Hinweise]])||'-1'||
|-
|'''data-xticks_round'''||Wenn vorhanden und entweder 'h', 'd', 'w', wird auf Stunde, Tag oder Woche bei den xticks gerundet (also die Tickmarks und die Gridlines bei den entsprechend gerundeten Zeiten gesetzt). Es kann auch 'auto' angegeben werden, um eine autmoatische Rundung durchzuführen||||
|-
|'''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 [[#Zeitformat_der_X-Achse|Hinweise]])||||
|-
|'''data-timeranges'''||Hierdurch können vordefinierte Zeiträume für die X-Achse festgelegt werden, die dann durch eine pulldown menu (neuer Button oben neben dem "-" Button) direkt ausgewählt werden können. Der Parameter ist ein Array aus Array Einträgen, welche jeweils [<Name>,<daysago_start>,<daysago_end>] enthalten)||
||data-timeranges='[<br>
["Actual Year","0Y","-1Y"],<br>
["Last Year","1Y","0Y"],<br>
["Actual Month","0M","-1M"],<br>
["Last Month","1M","0M"],<br>
["Actual Week","0W","-1W"],<br>
["Last Week","1W","0W"],<br>
["Today","0D","-1D"],<br>
["Yesterday","1D","0D"]<br>
]'
|-
|'''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-show_both_axes'''||Legt fest ob beide Y-Achsen Linien gezeichnet werden sollen||false||
|-
|'''data-crosshair'''||Aktiviert/deaktiviert den Fadenkreuz-Cursor. Binärwert ('true' oder 'false')||'false'||
|-
|'''data-cursorgroup'''||Zahl zur Gruppierung der Werte am Fadenkreuz-Cursor ([[#Fadenkreuz-Cursor|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 ([[#Legende|Hinweise]])||'["right","top"]'||
|-
|'''data-legend_horiz'''||legt fest, dass die Legendeneinträge horizontal angeordnet sind (anstatt vertikal wie im default Fall)||false||data-legend_horiz="true"
|-
|'''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-graphsshown='[true,false,true]'
|-
|'''data-ddd'''||Einstellung für die 3D-Drehung ([[#3-dimensionale_Drehung|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 ([[#Diagrammtitel|Hinweise]])||||
|-
|'''data-title_class'''||Klassenname für die Formatierung des Titels. Die Eigenschaften müssen dann entsprechend in einem CSS File angegeben werden (z.B. in fhem-tablet-ui-user.css)||||
|-
|'''data-prefetch'''||Legt fest, ob zusätzliche Daten rechts und links des Plots im Hintergrund vom Server geholt werden sollen||false||data-prefetch="true"
|-
|'''data-xtext_offset'''
|Verschiebt den Text auf der x-Achse um die angegebene Anzahl in Minuten.
|
|
|}
Einige Parameter (style, maxvalue, minvalue, maxvalue_sec, minvalue_sec) können auch aus Readings dynamisch gesetzt werden wenn "<device>:<reading>" als Parameter gesetzt wird. Damit kann man z.B. in FHEM über notify etc. die Linientypen dynamisch anpassen (z.B. wenn der Wert eines Devices in einem bestimmten Bereich liegt, ändert sich die Farbe des Graphen).

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

<syntaxhighlight 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>
</syntaxhighlight>

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:

<syntaxhighlight lang="html">
<div data-type="chart"
data-device="DG.wz.HZ.Heizungsventil"
data-get="measured-temp"
data-style='["ftui l0"]'
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>
</syntaxhighlight>

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.

<syntaxhighlight 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>
</syntaxhighlight>

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

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

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

'''Übergänge mit datenabhängigen Grenzen:''' Plotstile (data-style) können auch direkt als Gradienten auf Basis von Plot-Datenwerten definiert werden. Dazu muss der Plotstil als Array angegeben werden. Der erste Wert des Arrays gibt an, ob nur die Linie gezeichnet werden soll (Zahl angeben, die die Dicke der Linie definiert) oder gefüllt ("fill" eintragen). Alle danach folgenden Array Elemente sind beliebig viele Stopp Punkte für die Farbübergänge, welche wiederum aus Arrays mit 3 Parametern bestehen. Für jeden Stopp Punkt werden der Datenwert, die Farbe und die Durchsichtigkeit gesetzt. Hierdurch lassen sich z.B. Einfärbungen setzen, die für Temperaturplots immer negative Werte blau einfärben und positive Werte rot. Zwischen den Stop Punkten wird die Farbe interpoliert, also ein weicher Übergang generiert. Will man harte Übergänge muss man Zwei Stopp Punkte mit unterschiedlichen Farbwerten aber dem gleichen Datenwert erzeugen.<br>
Beispiel 1 für einen weichen Gradienten, der bei 0 von blau nach rot übergeht, bei diesem Übergang durchsichtig ist und von dort nach negativen bzw. positiven Werden immer deckender wird:<br>
<code>data-style='["fill",["-20","#0000ff","0.7"],["0","#0000ff","0"],["0","#ff0000","0"],["302","#ff0000","0.7"]]'</code><br>
Beispiel 2 mit einem harten Übergang von blau nach rot bei 0:<br>
<code>data-style='["fill",["-20","#0000ff","0.7"],["0","#0000ff","0.7"],["0","#ff0000","0.7"],["50","#ff0000","0.7"]]'</code>
Es gibt auch die Möglichkeit den Bereich zwischen zwei Graphen einzufärben. Dazu muss ein Wert in Columnspec als Array angegeben werden. Ist dies der Fall, dann wird der zweite Graph umgekehrt an den ersten angehängt.<br>
Beispiel:
<syntaxhighlight lang="html">
data-columnspec='[
"Func:logProxy_proplanta2Plot(\\x22AgroWeather\\x22,\\x22weatherIcon\\x22,$from,$to,12)",
[
"Func:logProxy_proplanta2Plot(\\x22AgroWeather\\x22,\\x22tempMax\\x22,$from,$to,12)",
"Func:logProxy_proplanta2Plot(\\x22AgroWeather\\x22,\\x22tempMin\\x22,$from,$to,12)"
],
"Func:logProxy_proplanta2Plot(\\x22AgroWeather\\x22,\\x22rain\\x22,$from,$to,0,\\x22day\\x22)"
]'
</syntaxhighlight>
[[Datei:FTUI Widget Chart DynamicStyles.png|thumb|none|500px|dynamischer Übergang]]

===Form der Linien===
Das Attribut '''data-ptype''' beeinflusst die Form der Linien. Hier sind folgende Werte möglich (in den Bildern sind zur Info zusätzlich auch immer points dargestellt):
<div><ul>
<li style="display: inline-block;"> [[File:Llines.png|thumb|none|350px|Darstellung in 2D: Stil "lines"]] </li>
<li style="display: inline-block;"> [[File:Points.png|thumb|none|350px|Darstellung in 2D: Stil "points"]] </li>
<li style="display: inline-block;"> [[File:Steps.png|thumb|none|350px|Darstellung in 2D: Stil "steps"]] </li>
<li style="display: inline-block;"> [[File:Fsteps.png|thumb|none|350px|Darstellung in 2D: Stil "fsteps"]] </li>
<li style="display: inline-block;"> [[File:Histeps.png|thumb|none|350px|Darstellung in 2D: Stil "histeps"]] </li>
<li style="display: inline-block;"> [[File:Bars.png|thumb|none|350px|Darstellung in 2D: Stil "bars"]] </li>
<li style="display: inline-block;"> [[File:Ibars.png|thumb|none|350px|Darstellung in 2D: Stil "ibars"]] </li>
<li style="display: inline-block;"> [[File:Cubic.png|thumb|none|350px|Darstellung in 2D: Stil "cubic"]] </li>
<li style="display: inline-block;"> [[File:Quadratic.png|thumb|none|350px|Darstellung in 2D: Stil "quadratic"]] </li>
<li style="display: inline-block;"> [[File:QuadraticSmooth.png|thumb|none|350px|Darstellung in 2D: Stil "quadraticSmooth"]] </li>
</div>

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.

<syntaxhighlight 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-cloud"
...>
</div>
</syntaxhighlight>
<li style="display: inline-block;"> [[File:Ssymbols.png|thumb|none|500px|Darstellung in 2D: Stil "symbol fa-cloud"]] </li>

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.

<syntaxhighlight 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; }
</syntaxhighlight>

'''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]].
<li style="display: inline-block;"> [[File:Wetterchart2.png|thumb|none|500px|Darstellung in 2D: Stil "Beispiel mit icons aus Readings"]] </li>

===Stapeln von Linien===
Über '''data-ptype''' kann zusätzlich festgelegt werden, ob Graphen übereinander gestapelt werden sollen. <code>data-ptype='lines:1'</code> bedeutet, dass der zugehörige Graph auf den Graph mit der Nummer 1 gestapelt werden soll. So etwas kann z.B. Sinn machen, wenn man den Stromverbrauch einzelner Devices darstellen und zusätzlich sehen will, wie hoch die Summe ist. Beispiel siehe unten.

[[Datei:FTUI Widget Chart Stacked.png]]

===Zeitstrahl / Start & Ende auf der X-Achse===
Die Attribute '''data-daysago_start''' und '''data-daysago_end''' dienen der Definition von Anfang und Ende der X-Achse. Im einfachsten Fall wird eine Anzahl an Tagen eingegeben, die sich auf das aktuelle Datum beziehen. Dabei gilt es zu beachten, dass es sich um ''vergangene Tage'' handelt. Das bedeutet, dass Tage in der Vergangenheit als positive Zahl angegeben werden, Tage in der Zukunft hingegen als negative Zahl. Es kann jeweils auch ein fixes Datum (z.B. '2013-10-23') angegeben werden. Uhrzeitangaben werden nur berücksichtigt, wenn '''data-nofulldays='true' ''' verwendet wird.

'''Relative Zeitangabe in Stunden/Tagen/Wochen/Monaten/Jahren'''<br />
Zur Ausgabe einer Anzahl an zurückliegenden Stunden bis zum aktuellen Zeitpunkt wird als Startzeitpunkt die Anzahl der Stunden/Tage/Wochen/Monate/Jahre angegeben, die angezeigt werden sollen, gefolgt vom Kleinbuchstaben '''h''' für Stunden, '''d''' für Tage, '''w''' für Wochen, '''m''' für Monate, '''y''' für Jahre, . Als Endzeitpunkt wird '''now''' gewählt.<br />
Das nachfolgende Beispiel zeigt die Werte der vergangenen 3 Stunden an:
<syntaxhighlight lang="html">
data-nofulldays="true"
data-daysago_start="3h"
data-daysago_end="now"
</syntaxhighlight>

'''Fester Zeitbereich des heutigen Tages (Stunden/Tage/Wochen/Monate/Jahre)'''<br />
Um ein festes Stunden/Tages/Wochen/Monats/Jahresfenster anzuzeigen, werden die absoluten Stunden/Tages/Wochen/Monats/Jahreszahlen mit negativem Vorzeichen, gefolgt vom Großbuchstaben '''H''' (entsprechend D/W/M/Y für Tage/Wochen/Monate/Jahre) angegeben. Wird '''data-daysago_start''' als positiver Wert angegeben, wird die Anzahl der Stunden/Tage/Wochen/Monate/Jahre von heute 0:00 Uhr subtrahiert (siehe Rechenweg weiter unten).<br />
Das Beispiel zeigt den Zeitbereich von heute 5:00 Uhr bis heute 22:00 Uhr:
<syntaxhighlight lang="html">
data-nofulldays="true"
data-daysago_start="-5H"
data-daysago_end="-22H"
</syntaxhighlight>

'''Fester Zeitbereich Tage-übergreifend'''<br />
Die Zeit in Tagen kann als Gleitkommazahl angegeben werden. Damit ist es möglich, Tage und Uhrzeiten zu kombinieren. Die Werte sind dann als Teil eines ganzen Tages, bezogen auf heute 0:00 Uhr zu errechnen und mit <code>.</code> als Teiler anzugeben.<br />
Das nachfolgende Beispiel zeigt einen Zeitbereich von '''gestern 15:00 Uhr''' bis '''morgen 3:00 Uhr'''.
<syntaxhighlight lang="html">
data-nofulldays="true"
data-daysago_start="0.375"
data-daysago_end="-1.125"
</syntaxhighlight>

Für die nachfolgenden Rechenwege sind die Einheiten nur zur Verdeutlichung angegeben. Die Einheiten werden im Attribut nicht angegeben.

Der Wert für '''GESTERN''' wird wie folgt ermittelt:<br />
Ausgangspunkt ist heute 0:00 Uhr, gestern 15:00 Uhr liegt also 9 Stunden davor. Diese 9 Stunden sind ein <code>9/24 Tag</code> und errechnet sich so:
<pre>
1d / 24h = 0.0416666...d/h
0.0416d/h * 9h = 0.375d
</pre>

Der Wert für '''MORGEN''' wird wie folgt ermittelt:<br />
Ausgangspunkt ist wieder heute 0:00 Uhr, morgen 3:00 Uhr liegt dann 27 Stunden dahinter. Der Einfachheit halber werden hier nur die 3 Stunden errechnet und dann ein ganzer Tag addiert:
<pre>
1d / 24h = 0.0416666...d/h
0.0416d/h * 3h = 0.125d

0.125d + 1d = 1.125d
</pre>
Da das Attribut Tage in der Vergangenheit erwartet, muss für einen Wert in der Zukunft wieder eine negative Zahl angegeben werden.

===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 der Maus. Unter iOS und Android 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>, <code>'right'</code>, <code>'before'</code>, und <code>'behind'</code>, die vertikale Positionierung <code>'top'</code>, <code>'bottom'</code>, <code>'above'</code>, <code>'below'</code> erlaubt (der Unterschied zwischen <code>'left'</code> und <code>'before'</code> liegt darin, dass im zweiten Fall die Legende nicht in den Zeichenbereich gesetzt wird sondern vor das ganze Chart (entsprechend für <code>'after'</code>, <code>'above'</code> und <code>'below'</code>). 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.
Zusätzlich ist es möglich durch "$eval(<regexp>)" regular Expressions auszuwerten (also z.B. Berechnungen durchzuführen). In <regexp> können auch "$data()" vorkommen.

Beispiel: <code>data-title="Klima Wohnzimmer Average: $eval(parseInt($data{avg1}*10)/10)°C / Max: $eval(parseInt($data{max1}*10)/10)°C"</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. Falls der 3D Modus eingeschaltet ist, gibt es Buttons zum Drehen der Darstellung um die X- und Y-Achse. Falls <code>data-timeranges</code> gesetzt ist, wird ein Pulldown Menü dargestellt, welches die Auswahl von dort definierten Zeiträumen für die X-Achse erlaubt.

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

[[File:Chart_tabletUI.png]]

<syntaxhighlight 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>
</syntaxhighlight>

===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:
<syntaxhighlight 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( (looks_like_number($prev_value) && ($prev_value < $min)) || ($prev_value lt $min) );
$max = $prev_value if( (looks_like_number($prev_value) && ($prev_value > $max)) || ($prev_value gt $max) );
$ret .= "$from $prev_value\n";
}

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

$min = $value if( (looks_like_number($value) && ($value < $min )) || ($value lt $min) );
$max = $value if( (looks_like_number($value) && ($value > $max )) || ($value gt $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);
}
</syntaxhighlight>

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

<syntaxhighlight 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>
</syntaxhighlight>

'''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).
<syntaxhighlight 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","");}
</syntaxhighlight>
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:
<syntaxhighlight lang="css">
/* icon lines */
.ftui.l99icon { stroke:#DDA400; stroke-width:48px; fill:none; }
</syntaxhighlight>
angepasst werden.

Im folgenden ein Beispiel, welches eine Linie für die Maximale Tagestemperatur zeichnet und auf dieser Linie die Wetter Icons darstellt.
<syntaxhighlight 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>
</syntaxhighlight>

===Kuchendiagramme===
In folgendem Beispiel wird gezeigt, wie man ein "Kuchendiagramm" darstellen kann.

[[File:PieChart.png]]

Ähnlich wie bei den Beispielen für die Wetter Darstellungen wird hierzu auch wieder logProxy benötigt. Zunächst muss die folgende zusätzliche Funktion in <code>99_myUtils.pm</code> einfügen.
<syntaxhighlight lang="perl">
#---------------------------------------
# Funktion zum Erzeugen der Inputs für Kuchendiagramme
#---------------------------------------
sub logProxy_values2PieChart($$$$;$$) {
my ($device, $reading, $angle_start, $angle_dif, $inner_rad, $show_text) = @_;
Log3 undef, 1, "$device, $reading, $angle_start, $angle_dif, $inner_rad, $show_text\n";

use constant PI => 4 * atan2(1,1);

my $value=ReadingsVal($device,$reading,0);

my $angle_delta = $value/100*360;
$angle_start = $angle_start/100*360;

my $rad=10;
my $irad=0;
if ($inner_rad) {
$irad = $rad*$inner_rad;
}
my $angle=$angle_start/360*2.0*PI;
my $x=$irad*sin($angle);
my $y=$irad*cos($angle);
my $ret .= ";p ".$x." ".$y."\n"; # add segment at angle $angle

for (my $i=$angle_start; $i<=$angle_start+$angle_delta; $i+=$angle_dif) {
$angle = $i/360*2.0*PI;
$x = $rad*sin($angle);
$y = $rad*cos($angle);
$ret .= ";p ".$x." ".$y."\n"; # add segment at angle $angle
}

$angle = ($angle_start+$angle_delta)/360*2.0*PI; # add last segment
$ret .= ";p ".$rad*sin($angle)." ".$rad*cos($angle)."\n";

if ($inner_rad) {
for (my $i=$angle_start; $i<$angle_start+$angle_delta; $i+=$angle_dif) {
$angle = ($angle_start+$angle_start+$angle_delta-$i)/360*2.0*PI;
$x = $irad*sin($angle);
$y = $irad*cos($angle);
$ret .= ";p ".$x." ".$y."\n"; # add segment at angle $angle
}
}

$angle = ($angle_start)/360*2.0*PI; # add last segment
$ret .= ";p ".$irad*sin($angle)." ".$irad*cos($angle)."\n";

if ($show_text) { # show text values
$x = ($rad+$irad)/2*sin((2*$angle_start+$angle_delta)/2/360*2.0*PI);
$y = ($rad+$irad)/2*cos((2*$angle_start+$angle_delta)/2/360*2.0*PI);

$ret .= ";t ".$x." ".$y." middle ".$show_text.":".$value."%\n";
}

return($ret);
}
</syntaxhighlight>
In FHEM braucht man Readings, welche eine Zahl enthalten, die als Prozentwert interpretiert wird. Für jeden Prozentwert (also für jedes Reading) generiert die o.a. Funktion nun den Chart Input für ein Kuchenstück und liefert diesen als Antwort auf das GET, welches das Chart Widget auslöst. Dazu braucht die Funktion folgende Parameter: (Name des FHEM Devices, Name des Readings, Start Winkel des Kuchenstücks (Mathematisch gegen den Uhrzeigersinn in Grad), Delta Winkel zum Zeichnen (legt fest in welchen Schritten der Teilkreis des Kuchenstücks gezeichnet wird), Skalierungsfaktor für inneren Ring wenn ein Ring gezeichtnet werden soll (0 bedeutet komplette Kuchenstücke), optionaler Text der ins Kuchenstück vor die Prozentzahl geschrieben wird).
Im Folgenden eine Beispielkonfiguration für die Darstellung als Kuchendiagramm, die Readings heißen hier dPer1 bis dPer4. Der Startwinkel wird duch Aufsummierung der jeweils vorher schon gezeichneten Kuchenstücke gebildet, dadurch entstehen aneinander hängende Stücke.
<syntaxhighlight lang="html">
[[Datei:[[Datei:Beispiel.jpg]]]]<div class="normal noaxes nobuttons"
data-type="chart"
data-logdevice='["lp"]'
data-logfile="CURRENT"
data-columnspec='[
"Func:logProxy_values2PieChart(\"dPer1\",\"state\",ReadingsVal(\"dPer4\",\"state\",0)+ReadingsVal(\"dPer3\",\"state\",0),5,0,\"first\")",
"Func:logProxy_values2PieChart(\"dPer2\",\"state\",ReadingsVal(\"dPer4\",\"state\",0)+ReadingsVal(\"dPer3\",\"state\",0)+ReadingsVal(\"dPer1\",\"state\",0),5,0,\"second\")",
"Func:logProxy_values2PieChart(\"dPer3\",\"state\",ReadingsVal(\"dPer4\",\"state\",0),5,0,\"third\")",
"Func:logProxy_values2PieChart(\"dPer4\",\"state\",0,5,0,\"fourth\")"
]'
data-style='["ftui l0fill","ftui l1fill","ftui l2fill","ftui l3fill"]'
data-ptype='["lines"]'
data-uaxis='["primary"]'
data-legend='["First","Second","Third","Fourth"]'
data-legendpos='["left","top"]'
data-yunit=""
data-height="300"
data-width="300"
data-ddd='["-40","0","0"]'
data-dddspace='["-10"]'
data-dddwidth='["10"]'
data-showlegend="true"
data-legend_horiz="true"
data-xticks="auto">
</div>
</syntaxhighlight>

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

<syntaxhighlight 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>
</syntaxhighlight>

'''Hinweis:''' Das Beispiel funktioniert nur mit DbLog. Falls Logfiles verwendet werden muss statt '$val' '$fld[''num'']' verwendet werden. Hierbei steht ''num'' für die Spalte (beginnend bei 0) in der die Daten stehen.

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

[[Kategorie:FHEM Tablet UI|Chart]]

Harmony

2020-03-16T18:37:58Z

Slanesh: Schreibfehler korrigiert

{{SEITENTITEL:harmony}}
{{Infobox Modul
|ModPurpose=Anbindung Logitech Harmony Hub basierter Fernbedienungen
|ModType=d
|ModCmdRef=harmony
|ModForumArea=Multimedia
|ModTechName=37_harmony.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])}}

Das FHEM-[[:Kategorie:Gerätemodul|Gerätemodul]] [[harmony]] bietet die Möglichkeit Logitech Harmony Hub basierte Fernbedienungen an FHEM anzubinden und so von FHEM aus Aktivitäten zu starten und zu stoppen, in FHEM auf das Starten und Stoppen von Aktivitäten über eine der mit dem Hub verbundenen Fernbedienungen zu reagieren oder auf Geräteebene jedes im Hub konfigurierte Gerät über IR, Bluetooth und/oder einen Smart Keyboard USB Dongle zu steuern.

Unterstützt werden zur Zeit die Modelle Ultimate Hub, Ultimate Smart Control, Ultimate, Smart Keyboard sowie alle darauf basierenden Kombinationen mit Smart Control und Smart Keyboard Add-On.

== Vorbereitung ==
Seit Ende 2018 hat Logitech die undokumentierte Schnittstelle die für die Anbindung der Harmony an FHEM verwendet werden geschlossen. Nach viel Protest aus der Community wurde die XMPP-Schnittstelle als "Entwickler-Option" nach akzeptieren von Haftungsausschlüssen wieder zur Verfügung gestellt. Ab Firmware 4.15.250 und Harmony-App-Version 5.6 für iOS und Android ist die Option zur Aktivierung von XMPP direkt in den Einstellungen der Harmony App zu finden. Die Einstellung versteckt sich unter Menü > Harmony-Einrichtung > Geräte und Aktionen hinzufügen und bearbeiten > Fernbedienung und Hub > XMPP aktivieren.

== Define ==
define <hub> harmony [<username> <password>] <ip>

Hier sind <code>username</code> und <code>password</code> die myharmony Zugangsdaten und <code>ip</code> ist die IP-Adresse des Hub im lokalen Netz.

Für die Firmware-Versionen 3.x ist die volle Funktionalität des Moduls auch ohne Angaben von <code>username</code> und <code>password</code> gegeben. Ab Firmware 4.x muss beides angegeben werden. Sonst ist keine Steuerung auf Geräteebene möglich.

==Allgemeines==
Aktivitäten und Geräte lassen sich an allen Stellen entweder als ID oder als Name angeben. Wenn der Name angegeben wird, müssen hierbei Leerzeichen durch einen Punkt ersetzt werden. Dies kann auch für eventuell andere im Namen vorhandene Sonderzeichen gelten.

== Aktivitäten ==
Das Reading <code>currentActivity</code> enthält die gerade laufende Aktivität. Beim Wechsel zwischen Aktivitäten erzeugt es Events, auf die in FHEM über ''notify'' reagiert werden kann. Das Reading <code>previousActivity</code> enthält die davor laufende Aktivität, sofern diese bekannt ist. Dieses Reading erzeugt keine Events.

In den Internals <code>currentActivityID</code> und <code>previousActivityID</code> stehen die dazu gehörenden IDs der Aktivitäten.

Mögliche Aktivitäten anzeigen geht über
get <hub> activities

Eine der Aktivitäten via FHEM starten über
set <hub> activity <activityname>
Wobei der Activityname zwingend so geschrieben werden muss wie FHEM ihn im Dropdown anzeigt.

Innerhalb einer laufenden Aktivität kann mit
set <hub> command <command>
ein IR-Kommando an eines der beteiligten Geräte gesendet werden.

== Geräteebene ==
Innerhalb und außerhalb einer laufenden Aktivität kann mit
set <hub> command <id|name> <command>
ein IR-Kommando an eines der im Hub bekannten Geräte gesendet werden. Hierbei ist darauf zu achten, dass innerhalb einer Aktivität keine Kommandos verwendet werden sollten, die den Smart-State betreffen.

Die möglichen Kommandos kann man sich über
get <hub> deviceCommands
anzeigen lassen.

Wichtig ist, dass wenn in der so erzeugten Liste ein Gerät mit Leerzeichen geschrieben wird, dass man im FHEM Befehl das Leerzeichen durch einen "." ersetzen muss. Hat man bspw. ein Harmony Device "Samsung TV" ist der Gerätebefehl zum anschalten:
set <hub> command Samsung.TV PowerOn

=== FHEM Devices auf Geräteebene ===
Es ist möglich, sich für einzelne oder alle im Hub konfigurierten Geräte ein zugehöriges FHEM-Device anlegen zu lassen:
set <hub> autocreate [<id|name>]

Beim Umschalten zwischen Aktivitäten wird in diesen FHEM-Devices im Reading power der in der Aktivität konfigurierten Einschaltzustand (on, off oder manual) angezeigt. Mit einem ''notify'' auf <code>power</code> Events lässt sich in FHEM auf einzelne Geräte reagieren.

'''Wichtig:''' Diese FHEM-Device spiegeln nicht den tatsächlichen Gerätezustand wieder, sondern den innerhalb einer Aktivität beabsichtigen Zustand. Der tatsächliche Zustand kann z.B. auf Grund von Empfangsproblemen abweichen.

Das get <code>commands</code> sowie die set <code>command</code>, <code>hidDevice</code>, <code>text</code>, <code>cursor</code> und <code>special</code> Kommandos auf Hub-Ebene stehen hier direkt und ohne Angabe von Device-ID oder Name zur Verfügung.

=== Kommandos an FHEM senden ===
Da es (zur Zeit) nicht möglich ist, Geräte-Kommandos oder einzelne Tasten direkt vom HUB zu empfangen, muss hierzu ein zusätzlicher Empfänger in FHEM eingebunden werden. Dies kann z.B. mit einem MCE-IR Empfänger oder per Bluetooth geschehen. Ein FHEM-Modul hierzu findet sich im in diesem {{Link2Forum|Topic=36257|LinkText=Forenthread}}.

Mit dem in diesem {{Link2Forum|Topic=51619|LinkText=Forenthread}} vorgestellten Modul ist es möglich einzeln belegte Tasten der Harmony über das Roku External Control Protocol per Netzwerk an FHEM zu senden und dort auszuwerten.

== Smart Keyboard ==
Der Harmony Hub kann über Bluetooth oder die zum Smart Keyboard gehörenden USB-Dongle mit einem Rechner, Media PC oder sonstigem Gerät, das Tastatureingabe unterstützt, verbunden werden. FHEM kann diese Verbindung nutzen, um beliebige Tastendrücke an ein solches Gerät zu senden. Das können Texte sein, Cursorbewegungen oder die Power-, Multimedia oder sonstigen Funktionstasten, die das Gerät unterstützt.

Alle gesendeten Tastendrücke beziehen sich normalerweise auf das zur gerade laufenden Aktivität gehörende Tastatureingabegerät. Mit dem <code>hidDevice</code> Kommando lässt sich die Tastatureingabe auf jedes im Hub dafür konfigurierte Gerät umschalten.

'''Wichtig:''' Dieses Umschalten kann einige Sekunden dauern, da hierbei die bestehende Bluetooth-Verbindung getrennt und eine neue aufgebaut wird.

Es stehen die Kommandos <code>text</code>, <code>cursor</code> und <code>special</code> zur Verfügung.

Beispiele:

Gehe in PLEX auf die Library Musik und spiele das erste Item in der OnDeck Liste:
set <hub> text M
set <hub> cursor right
set <hub> text p

== Beispiele ==

=== Vorgeschaltete Funksteckdose ansteuern ===

'''Vorbereitung Harmony'''

Nachdem die Geräte mit Strom versorgt werden, benötigen sie einige Sekunden, bis sie ihre Einschaltsignale verarbeiten können. Diese Verzögerung wird durch ein Dummy Gerät in jeder Aktion erzeugt.

1) In MyHarmony einen Amazon Fire TV anlegen und ihm einen passenden Namen geben (z.B. Pause)

2) Unter "Geräte" dieses markieren und per "Ändern der Betriebseinstellungen" die Einstellungen aufrufen

3) Punkt "Ich möchte dieses Gerät eingeschaltet lassen, wenn Aktionen gewechselt werden und nur durch Drücken der Off-Taste ausschalten" auswählen

4) Einen harmlosen Befehl einfügen ("Search"), danach eine Verzögerung von 5000ms einbauen und dann noch einen Befehl ("Search"). Dies bewirkt eine Verzögerung von 5 Sekunden beim Ein- und Ausschalten

5) Unter Aktionen die Aktion auswählen und per "Einstellung ändern" das neue Gerät hinzufügen

6) Per "Diese Aktion anpassen" das neue Gerät an die erste Stelle schieben

7) Schritte 5-7 für alle Aktionen wiederholen

'''Konfiguration in FHEM'''

1) Der Harmony Hub muss existieren

#Harmony Hub Wohnzimmer definieren
define wz_harmonyhub harmony 192.168.123.123

2) Ihr benötigt eine fertig konfigurierte Funksteckdose (hier "wz_Multimedia")

3) Ihr baut eine Bedingung, die auf den Ein- und Ausschaltvorgang des Harmony Hub (hier wz_harmonyhub) reagiert und die Steckdose (hier wz_Multimedia) schaltet. Es wird eine '''zusätzliche''' Pause genutzt von 0 Sekunden bei der ersten Bedingung (wäre kontraproduktiv) und 10 Sekunden bei der zweiten Bedingung (DOELSEIF). Bei der Nutzung eines Beamers lässt sich hierüber die Abkühlzeit einstellen. Im Beispiel bleiben den Geräten somit 15 Sekunden zum Ausschalten und 5 Sekunden um die Empfangsbereitschaft herzustellen. Die erste Bedingung im DOIF ist eine Regex, da "currentActivity" bei mehrfachem Abschalten hintereinander immer wieder von "PowerOff" auf "Stopping PowerOff" wechselt.

#Auf den Schaltvorgang des Hubs reagieren
define wz_Multimedia_Automatik DOIF ([wz_harmonyhub:currentActivity] !~ /PowerOff/) (set wz_Multimedia on) DOELSEIF ([wz_harmonyhub:activity] eq "PowerOff") (set wz_Multimedia off)
attr wz_Multimedia_Automatik wait 0:10

====Weitere Möglichkeiten====
Statt Fire TV kann jedes andere nicht vorhandene Gerät als Platzhalter in der Harmony verwendet werden. In diesem Gerät kann man auch direkt die Einschaltverzögerung anpassen um die nötige Wartezeit zu erhalten.
Besser als ein notify oder DOIF auf Activity-Ebene ist es über die Harmony autocreate funktion ein FHEM Device für die platzhalter Steckdose anzulegen und dort dann auf das power Event zu reagieren. Damit ist man unabhängig von allen Änderungen bei den Activities.

===Button für eine bestimmte Activity im Frontend und Homekit über readingsProxy ===
In FHEMWEB und Homebridge:
<syntaxhighlight lang="perl">
define Fernsehen readingsProxy <hub>:activity
attr Fernsehen devStateIcon on:control_on_off@green off:control_standby
attr Fernsehen event-on-change-reading .*
attr Fernsehen genericDeviceType switch
attr Fernsehen setFn { return 'activity <meine activity>' if( $CMD eq 'on' );; return 'off';; }
attr Fernsehen setList on off
attr Fernsehen valueFn { return 'on' if( $VALUE eq '<meine activity>' );; return 'off';; }
</syntaxhighlight>

Zusätzlich im TableUI:
<syntaxhighlight lang="xml">
<div class="left">
<div data-type="switch" data-device="Fernsehen" data-icon="fa-tv" class="cell" ></div>
<div data-type="label" class="narrow">FERNSEHEN</div>
</div>
</syntaxhighlight>

== Bekannte Probleme ==
Wenn FHEM den Harmony Hub nicht erreichen kann, blockiert das Modul FHEM für den Timeout von 2 Sekunden im Abstand von nur wenigen Sekunden:

<pre>[...]
2015.12.26 18:25:45 1: Perfmon: possible freeze starting at 18:25:43, delay is 2.794
2015.12.26 18:25:58 1: Perfmon: possible freeze starting at 18:25:56, delay is 2.709
2015.12.26 18:26:11 1: Perfmon: possible freeze starting at 18:26:09, delay is 2.676
2015.12.26 18:26:24 1: Perfmon: possible freeze starting at 18:26:22, delay is 2.686
2015.12.26 18:26:37 1: Perfmon: possible freeze starting at 18:26:35, delay is 2.686
[...]
</pre>

Da dieses Blockieren die Funktionalität von FHEM beeinträchtigen kann, sollte man bei geplanten Auszeiten des Hubs diesen disablen:

set <hub> disable 1

== Weblinks ==
* [http://myharmony.com myHarmony] Logitech Harmony Hersteller
* [http://www.harmony-remote-forum.de/portal.php Harmony Remote Forum] deutsches Harmony Forum
* {{Link2Forum|Topic=14163|LinkText=Thread im FHEM Forum}} Weitere Infos im FHEM Forum Thread

[[Kategorie:Unterhaltungselektronik]]
[[Kategorie:IP Components]]

Harmony

2020-03-16T13:53:33Z

Slanesh: Aktivierung der XMPP-Schnittstelle über die Harmony App beschrieben

{{SEITENTITEL:harmony}}
{{Infobox Modul
|ModPurpose=Anbindung Logitech Harmony Hub basierter Fernbedienungen
|ModType=d
|ModCmdRef=harmony
|ModForumArea=Multimedia
|ModTechName=37_harmony.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])}}

Das FHEM-[[:Kategorie:Gerätemodul|Gerätemodul]] [[harmony]] bietet die Möglichkeit Logitech Harmony Hub basierte Fernbedienungen an FHEM anzubinden und so von FHEM aus Aktivitäten zu starten und zu stoppen, in FHEM auf das Starten und Stoppen von Aktivitäten über eine der mit dem Hub verbundenen Fernbedienungen zu reagieren oder auf Geräteebene jedes im Hub konfigurierte Gerät über IR, Bluetooth und/oder einen Smart Keyboard USB Dongle zu steuern.

Unterstützt werden zur Zeit die Modelle Ultimate Hub, Ultimate Smart Control, Ultimate, Smart Keyboard sowie alle darauf basierenden Kombinationen mit Smart Control und Smart Keyboard Add-On.

== Vorbereitung ==
Seit Ende 2018 hat Logitech die undokumentierten Schnittstellen die für die Anbindung der Harmony an FHEM verwendet werden geschlossen. Nach viel Protest aus der Community wurde die XMPP-Schnittstelle als "Entwickler-Option" nach akzeptieren von Haftungsauscshlussen wieder zur Verfügung gestellt. Ab Firmware 4.15.250 und Harmony-App-Version 5.6 für iOS und Android ist die Option zur Aktivierung von XMPP direkt in den Einstellungen der Harmony App zu finden. Die Einstellung versteckt sich unter Menü > Harmony-Einrichtung > Geräte und Aktionen hinzufügen und bearbeiten > Fernbedienung und Hub > XMPP aktivieren.

== Define ==
define <hub> harmony [<username> <password>] <ip>

Hier sind <code>username</code> und <code>password</code> die myharmony Zugangsdaten und <code>ip</code> ist die IP-Adresse des Hub im lokalen Netz.

Für die Firmware-Versionen 3.x ist die volle Funktionalität des Moduls auch ohne Angaben von <code>username</code> und <code>password</code> gegeben. Ab Firmware 4.x muss beides angegeben werden. Sonst ist keine Steuerung auf Geräteebene möglich.

==Allgemeines==
Aktivitäten und Geräte lassen sich an allen Stellen entweder als ID oder als Name angeben. Wenn der Name angegeben wird, müssen hierbei Leerzeichen durch einen Punkt ersetzt werden. Dies kann auch für eventuell andere im Namen vorhandene Sonderzeichen gelten.

== Aktivitäten ==
Das Reading <code>currentActivity</code> enthält die gerade laufende Aktivität. Beim Wechsel zwischen Aktivitäten erzeugt es Events, auf die in FHEM über ''notify'' reagiert werden kann. Das Reading <code>previousActivity</code> enthält die davor laufende Aktivität, sofern diese bekannt ist. Dieses Reading erzeugt keine Events.

In den Internals <code>currentActivityID</code> und <code>previousActivityID</code> stehen die dazu gehörenden IDs der Aktivitäten.

Mögliche Aktivitäten anzeigen geht über
get <hub> activities

Eine der Aktivitäten via FHEM starten über
set <hub> activity <activityname>
Wobei der Activityname zwingend so geschrieben werden muss wie FHEM ihn im Dropdown anzeigt.

Innerhalb einer laufenden Aktivität kann mit
set <hub> command <command>
ein IR-Kommando an eines der beteiligten Geräte gesendet werden.

== Geräteebene ==
Innerhalb und außerhalb einer laufenden Aktivität kann mit
set <hub> command <id|name> <command>
ein IR-Kommando an eines der im Hub bekannten Geräte gesendet werden. Hierbei ist darauf zu achten, dass innerhalb einer Aktivität keine Kommandos verwendet werden sollten, die den Smart-State betreffen.

Die möglichen Kommandos kann man sich über
get <hub> deviceCommands
anzeigen lassen.

Wichtig ist, dass wenn in der so erzeugten Liste ein Gerät mit Leerzeichen geschrieben wird, dass man im FHEM Befehl das Leerzeichen durch einen "." ersetzen muss. Hat man bspw. ein Harmony Device "Samsung TV" ist der Gerätebefehl zum anschalten:
set <hub> command Samsung.TV PowerOn

=== FHEM Devices auf Geräteebene ===
Es ist möglich, sich für einzelne oder alle im Hub konfigurierten Geräte ein zugehöriges FHEM-Device anlegen zu lassen:
set <hub> autocreate [<id|name>]

Beim Umschalten zwischen Aktivitäten wird in diesen FHEM-Devices im Reading power der in der Aktivität konfigurierten Einschaltzustand (on, off oder manual) angezeigt. Mit einem ''notify'' auf <code>power</code> Events lässt sich in FHEM auf einzelne Geräte reagieren.

'''Wichtig:''' Diese FHEM-Device spiegeln nicht den tatsächlichen Gerätezustand wieder, sondern den innerhalb einer Aktivität beabsichtigen Zustand. Der tatsächliche Zustand kann z.B. auf Grund von Empfangsproblemen abweichen.

Das get <code>commands</code> sowie die set <code>command</code>, <code>hidDevice</code>, <code>text</code>, <code>cursor</code> und <code>special</code> Kommandos auf Hub-Ebene stehen hier direkt und ohne Angabe von Device-ID oder Name zur Verfügung.

=== Kommandos an FHEM senden ===
Da es (zur Zeit) nicht möglich ist, Geräte-Kommandos oder einzelne Tasten direkt vom HUB zu empfangen, muss hierzu ein zusätzlicher Empfänger in FHEM eingebunden werden. Dies kann z.B. mit einem MCE-IR Empfänger oder per Bluetooth geschehen. Ein FHEM-Modul hierzu findet sich im in diesem {{Link2Forum|Topic=36257|LinkText=Forenthread}}.

Mit dem in diesem {{Link2Forum|Topic=51619|LinkText=Forenthread}} vorgestellten Modul ist es möglich einzeln belegte Tasten der Harmony über das Roku External Control Protocol per Netzwerk an FHEM zu senden und dort auszuwerten.

== Smart Keyboard ==
Der Harmony Hub kann über Bluetooth oder die zum Smart Keyboard gehörenden USB-Dongle mit einem Rechner, Media PC oder sonstigem Gerät, das Tastatureingabe unterstützt, verbunden werden. FHEM kann diese Verbindung nutzen, um beliebige Tastendrücke an ein solches Gerät zu senden. Das können Texte sein, Cursorbewegungen oder die Power-, Multimedia oder sonstigen Funktionstasten, die das Gerät unterstützt.

Alle gesendeten Tastendrücke beziehen sich normalerweise auf das zur gerade laufenden Aktivität gehörende Tastatureingabegerät. Mit dem <code>hidDevice</code> Kommando lässt sich die Tastatureingabe auf jedes im Hub dafür konfigurierte Gerät umschalten.

'''Wichtig:''' Dieses Umschalten kann einige Sekunden dauern, da hierbei die bestehende Bluetooth-Verbindung getrennt und eine neue aufgebaut wird.

Es stehen die Kommandos <code>text</code>, <code>cursor</code> und <code>special</code> zur Verfügung.

Beispiele:

Gehe in PLEX auf die Library Musik und spiele das erste Item in der OnDeck Liste:
set <hub> text M
set <hub> cursor right
set <hub> text p

== Beispiele ==

=== Vorgeschaltete Funksteckdose ansteuern ===

'''Vorbereitung Harmony'''

Nachdem die Geräte mit Strom versorgt werden, benötigen sie einige Sekunden, bis sie ihre Einschaltsignale verarbeiten können. Diese Verzögerung wird durch ein Dummy Gerät in jeder Aktion erzeugt.

1) In MyHarmony einen Amazon Fire TV anlegen und ihm einen passenden Namen geben (z.B. Pause)

2) Unter "Geräte" dieses markieren und per "Ändern der Betriebseinstellungen" die Einstellungen aufrufen

3) Punkt "Ich möchte dieses Gerät eingeschaltet lassen, wenn Aktionen gewechselt werden und nur durch Drücken der Off-Taste ausschalten" auswählen

4) Einen harmlosen Befehl einfügen ("Search"), danach eine Verzögerung von 5000ms einbauen und dann noch einen Befehl ("Search"). Dies bewirkt eine Verzögerung von 5 Sekunden beim Ein- und Ausschalten

5) Unter Aktionen die Aktion auswählen und per "Einstellung ändern" das neue Gerät hinzufügen

6) Per "Diese Aktion anpassen" das neue Gerät an die erste Stelle schieben

7) Schritte 5-7 für alle Aktionen wiederholen

'''Konfiguration in FHEM'''

1) Der Harmony Hub muss existieren

#Harmony Hub Wohnzimmer definieren
define wz_harmonyhub harmony 192.168.123.123

2) Ihr benötigt eine fertig konfigurierte Funksteckdose (hier "wz_Multimedia")

3) Ihr baut eine Bedingung, die auf den Ein- und Ausschaltvorgang des Harmony Hub (hier wz_harmonyhub) reagiert und die Steckdose (hier wz_Multimedia) schaltet. Es wird eine '''zusätzliche''' Pause genutzt von 0 Sekunden bei der ersten Bedingung (wäre kontraproduktiv) und 10 Sekunden bei der zweiten Bedingung (DOELSEIF). Bei der Nutzung eines Beamers lässt sich hierüber die Abkühlzeit einstellen. Im Beispiel bleiben den Geräten somit 15 Sekunden zum Ausschalten und 5 Sekunden um die Empfangsbereitschaft herzustellen. Die erste Bedingung im DOIF ist eine Regex, da "currentActivity" bei mehrfachem Abschalten hintereinander immer wieder von "PowerOff" auf "Stopping PowerOff" wechselt.

#Auf den Schaltvorgang des Hubs reagieren
define wz_Multimedia_Automatik DOIF ([wz_harmonyhub:currentActivity] !~ /PowerOff/) (set wz_Multimedia on) DOELSEIF ([wz_harmonyhub:activity] eq "PowerOff") (set wz_Multimedia off)
attr wz_Multimedia_Automatik wait 0:10

====Weitere Möglichkeiten====
Statt Fire TV kann jedes andere nicht vorhandene Gerät als Platzhalter in der Harmony verwendet werden. In diesem Gerät kann man auch direkt die Einschaltverzögerung anpassen um die nötige Wartezeit zu erhalten.
Besser als ein notify oder DOIF auf Activity-Ebene ist es über die Harmony autocreate funktion ein FHEM Device für die platzhalter Steckdose anzulegen und dort dann auf das power Event zu reagieren. Damit ist man unabhängig von allen Änderungen bei den Activities.

===Button für eine bestimmte Activity im Frontend und Homekit über readingsProxy ===
In FHEMWEB und Homebridge:
<syntaxhighlight lang="perl">
define Fernsehen readingsProxy <hub>:activity
attr Fernsehen devStateIcon on:control_on_off@green off:control_standby
attr Fernsehen event-on-change-reading .*
attr Fernsehen genericDeviceType switch
attr Fernsehen setFn { return 'activity <meine activity>' if( $CMD eq 'on' );; return 'off';; }
attr Fernsehen setList on off
attr Fernsehen valueFn { return 'on' if( $VALUE eq '<meine activity>' );; return 'off';; }
</syntaxhighlight>

Zusätzlich im TableUI:
<syntaxhighlight lang="xml">
<div class="left">
<div data-type="switch" data-device="Fernsehen" data-icon="fa-tv" class="cell" ></div>
<div data-type="label" class="narrow">FERNSEHEN</div>
</div>
</syntaxhighlight>

== Bekannte Probleme ==
Wenn FHEM den Harmony Hub nicht erreichen kann, blockiert das Modul FHEM für den Timeout von 2 Sekunden im Abstand von nur wenigen Sekunden:

<pre>[...]
2015.12.26 18:25:45 1: Perfmon: possible freeze starting at 18:25:43, delay is 2.794
2015.12.26 18:25:58 1: Perfmon: possible freeze starting at 18:25:56, delay is 2.709
2015.12.26 18:26:11 1: Perfmon: possible freeze starting at 18:26:09, delay is 2.676
2015.12.26 18:26:24 1: Perfmon: possible freeze starting at 18:26:22, delay is 2.686
2015.12.26 18:26:37 1: Perfmon: possible freeze starting at 18:26:35, delay is 2.686
[...]
</pre>

Da dieses Blockieren die Funktionalität von FHEM beeinträchtigen kann, sollte man bei geplanten Auszeiten des Hubs diesen disablen:

set <hub> disable 1

== Weblinks ==
* [http://myharmony.com myHarmony] Logitech Harmony Hersteller
* [http://www.harmony-remote-forum.de/portal.php Harmony Remote Forum] deutsches Harmony Forum
* {{Link2Forum|Topic=14163|LinkText=Thread im FHEM Forum}} Weitere Infos im FHEM Forum Thread

[[Kategorie:Unterhaltungselektronik]]
[[Kategorie:IP Components]]

Mi vacuum

2018-08-21T20:49:42Z

Slanesh: Auslesen und Definition von Zonen ergänzt

{{Baustelle}}
=Mi Vacuum=
Wie der preiswerte Staubsaugerroboter auch auf FHEM hört...

==Für wen ist die Anleitung gedacht?==
Ich gehe davon aus, dass ihr ein funktionierendes FHEM auf einem Linux Rechner (Debian) betreibt.

Weiterhin denke ich, dass euer Hauptarbeitsrechner unter Windows läuft.

Als Smartphone OS Android (wer Apple hat, kann gerne die Token-Auslese-Geschichte hier beschreiben).

Um das Teil auch von Alexa aus ein und aus zu schalten, sollte auch die Installation von Alexa in FHEM fertig sein.

==Die Einrichtung des Moduls==
Das ist insofern spannend, als das Modul nicht offiziell in FHEM eingecheckt ist. Man muss also das Modul runterladen, auf den FHEM Rechner bringen etc...

===Vorarbeiten (Linux)===
Zunächst fangen wir mal auf unserem FHEM Rechner an. Mit Putty verbinden wir uns per SSH mit dem FHEM Computer.

Folgende Befehle können benötigt werden (Debian):
* <code>sudo apt-get install libjson-perl</code>
* <code>sudo apt-get install libdigest-md5-perl</code>
* <code>sudo apt-get install libcrypt-cbc-perl</code>
* <code>sudo cpan Crypt::Rijndael_PP</code>
* <code>sudo apt-get install libcrypt-ecb-perl</code> (nur nötig, wenn ihr einen verschlüsselten Token mit 96 Zeichen habt)
* <code>sudo cpan Crypt::Cipher::AES</code> (nur nötig, wenn Crypt::Rijndael_PP aus irgendwelchen Gründen nicht funktioniert)
Wenn bei dem ein oder anderen Modul die Meldung kommt, dass es schon installiert ist, einfach mit dem nächsten Befehl weiter machen. Das CPAN Teil würde ich am Schluss machen, das braucht ziemlich lang zum installieren.

===Vorarbeiten am Smartphone (Token)===
Das Problem ist folgendes:

Wenn der Roboter mit dem WLAN verbunden wird, generiert er einen Token. Das ist ein Schlüssel, ohne den er sich nicht steuern lässt. Damit FHEM drauf zugreifen kann, benötigt man diesen Token.

Mit den neueren Versionen der MiHome App klappt das Auslesen der Tokens leider nicht mehr.

====Auslesen bei Android Endgeräten====

Ich gehe davon aus, dass der Staubsauger mit der original MiHome App eingebunden ist und funktioniert. (Ich habe bei der Einrichtung des Servers => "other" gewählt. Offenbar wollen neuere Staubsauger sich mit "China Mainland" nicht mehr verbinden. Tut hier an dieser Stelle zwar nichts zur Sache, aber vielleicht hilft es dem ein oder anderen. Wenn man die Region gewechselt hat, muss man auch den Staubsauger neu einbinden)

* MiHome löschen
* alte MiHome suchen (APKMirror z.B., Version 5.0.19 hat bei mir funktioniert, unsichere Quellen müssen erlaubt sein)
* runtergeladene MiHome App öffnen und anmelden (sollte ganz normal den Sauger finden)
* USB-Debugging am Handy einschalten (Entwickleroptionen...)
* Handy mit USB Kabel und PC verbinden
* [https://github.com/ultrara1n/MiToolkit/releases MiToolkit] 1.6 runterladen und öffnen
* [https://github.com/ultrara1n/MiToolkit/releases MiToolkit] erzeugt nun am Handy ein Backup
* anschließend zeigt es den Token direkt am PC an

====Auslesen bei iOS Endgeräten====

Zum Auslesen des Tokens mit iOS Endgeräten kann die Anleitung unter folgendem Link befolgt werden: [https://forum.smartapfel.de/forum/thread/370-xiaomi-token-auslesen/]

===Installation des inoffiziellen Moduls===
Der folgende Teil ist für völlige Noobs. Wenn ihr einen eleganteren Weg kennt, her damit.

Zunächst bitte das Modul aus dem Forum herunterladen.
[https://forum.fhem.de/index.php/topic,73052.0.htmlm Hier] befindet sich der Thread. Markus M. hat sich die Mühe gemacht, ein Modul zu schreiben. Solange es nicht offiziell eingecheckt ist, muss man es händisch installieren. Das kann man wie folgt machen:
* das Modul zunächst auf seinem Windows PC speichern

Wie kommt das Modul nun auf den eigenen RasPi?

Ich nutze dafür einen kleinen HTTP Server auf meinem Windows Rechner: [http://miniweb.sourceforge.net/ MiniWeb]

Dieses Tool runterladen und irgendwohin entpacken. Zum starten habe ich eine kleine Batchdatei geschrieben:
<pre>D:\Software\MiniWebServer\miniweb\miniweb.exe -p 80</pre>
Die sorgt nur dafür, dass der Server auf Port 80 läuft.

Im entpackten Verzeichnis ist ein Unterverzeichnis mit dem Namen "htdocs". Dahin kopieren wir das soeben runtergeladene Modul aus dem Forum-Thread.

Langsam sollte das cpan Tool auf unserer SSH Verbindung durchgelaufen sein.

Nun wechseln wir (auf dem Linux Rechner) in das FHEM Verzeichnis (cd /opt/fhem/FHEM).

<pre>wget http://IP-Adresse_EUres_Windows_Rechners/72_XiaomiDevice.pm</pre>

bringt die Datei in euer FHEM Verzeichnis.

Jetzt noch die Rechte anpassen:

<pre>sudo chown fhem:dialout /opt/fhem/FHEM/72_XiaomiDevice.pm</pre>

Fertig.

Jetzt können wir auf die FHEM Oberfläche wechseln.

<pre>reload 72_XiaomiDevice.pm</pre>

und unser runtergeladenes Modul steht in FHEM zur Verfügung.

==Einrichten des Moduls==
<pre>
define Mi_Vacuum XiaomiDevice 192.168.222.77 55387753545937326a33396943557999

attr Mi_Vacuum subType VacuumCleaner
</pre>

Und schon (=etwa nach 10 Sekunden) sollte euer Roboter in FHEM mit ganz vielen Readings auftauchen.

==Anwendung: Sprachsteuerung mit Alexa (einfach, ein und aus)==
Wie bindet man das jetzt schnell in Alexa ein?

Wir legen uns in FHEM einen Dummy an. Dieser wird ein Switch (on off). Dazu noch ein DOIF oder ein notify, welches diesen Switch überwacht. Je nach Status des Dummys schalten wir den Roboter.

Ein List meines Dummys:
<pre>
Internals:
CFGFN
NAME Mi_Vacuum_Staubsauger
NR 719473
STATE on
TYPE dummy
Readings:
2017-09-18 21:10:12 state on
Attributes:
alexaName Mi_Vacuum_Staubsauger
genericDeviceType switch
room alexa
setList on off
</pre>

Mein DOIF:

<pre>
define di_Mi_Vacuum DOIF ([Mi_Vacuum_Staubsauger:"on"]) (set Mi_Vacuum start) DOELSE (set Mi_Vacuum charge)
</pre>

Das Attribut do always nicht vergessen!

Den Dummy setzen wir in den Raum, der unsere Alexa Geräte beinhaltet. Nun den Alexa FHEM Service neu starten. Anschließend sollte eine Suche nach neuen Geräten in Alexa unseren Dummy finden. Für diesen legen wir in Alexa einen neuen Raum an, z.B. Staubsauger.

Fertig.

Ein "Alexa schaltet den Staubsauger ein" lässt unseren Mi-Vacuum loslegen. "Alexa schalte den Staubsauger aus" schickt ihn wieder zurück zu seiner Station.

==Zonenreinigung==
Um nur Teilbereiche einer Wohnung zu reinigen, ist es möglich über das Modul Zonen zu definieren. Hierzu ist es notwendig, die Koordinaten der gewünschten Zone zu ermitteln. Hierzu eignet sich die [https://xiaomi.flole.de/ FloleVac App] die entweder auf einem Android Device oder auf einem Android Emulator (z.B. [https://www.bluestacks.com/download.html BlueStacks]) verwendet werden kann. In der App kann man in der Karte eine Zone für die Reinigung markieren und durch langes Gedrückthalten des "Reinigen-Buttons" in der FloleVac App die Koordinaten dieser Zone in die Zwischenablage kopieren.

Mit diesen Koordindaten im Format [16200,27250,31650,27650,1] kann man dann loslegen die Zonen in FHEM zu definieren:

Entweder direkt über die Werte:

<pre>
set vacuum zone 16200,27250,31650,27650,1 23700,23050,25200,24200,2
</pre>

Oder über die passenden Attribute erst ein Alias anlegen:

<pre>
attr vacuum zone_names home:[16200,27250,31650,27650,1],[23700,23050,25200,24200,2] livingroom:[16200,26250,23000,30150,1]
</pre>

Ein Alias kann dann wie folgt genutzt werden:

<pre>
set vacuum zone home
</pre>

==Quellen==
* {{Link2Forum|Topic=73052|LinkText=Forums-Thread}}
* {{Link2Forum|Topic=76940|LinkText=Diskussionsthread}}
* [http://miniweb.sourceforge.net/ MiniWeb], kleiner WebServer für Windows
* [https://xiaomi.flole.de/ Flole], alternative App für Android, die das Token nach GoogleDrive exportiert
* [http://www.roboter-forum.com/forumdisplay.php?130-Xiaomi Roboter-Forum] deutschsprachiges Forum, welches sich mit dem Mi Vacuum beschäftigt (auch vor dem Kauf des Roboters lohnt sich ein Besuch dort)
* [https://paypal.me/mm0 PayPal]-Link, um Markus M. Dankeschön zu sagen

Mi vacuum

2018-07-28T12:28:52Z

Slanesh: Link zum Token-Auslesen bei iOS Endgeräten hinzugefügt.

{{Baustelle}}
=Mi Vacuum=
Wie der preiswerte Staubsaugerroboter auch auf FHEM hört...

==Für wen ist die Anleitung gedacht?==
Ich gehe davon aus, dass ihr ein funktionierendes FHEM auf einem Linux Rechner (Debian) betreibt.

Weiterhin denke ich, dass euer Hauptarbeitsrechner unter Windows läuft.

Als Smartphone OS Android (wer Apple hat, kann gerne die Token-Auslese-Geschichte hier beschreiben).

Um das Teil auch von Alexa aus ein und aus zu schalten, sollte auch die Installation von Alexa in FHEM fertig sein.

==Die Einrichtung des Moduls==
Das ist insofern spannend, als das Modul nicht offiziell in FHEM eingecheckt ist. Man muss also das Modul runterladen, auf den FHEM Rechner bringen etc...

===Vorarbeiten (Linux)===
Zunächst fangen wir mal auf unserem FHEM Rechner an. Mit Putty verbinden wir uns per SSH mit dem FHEM Computer.

Folgende Befehle können benötigt werden (Debian):
* <code>sudo apt-get install libjson-perl</code>
* <code>sudo apt-get install libdigest-md5-perl</code>
* <code>sudo apt-get install libcrypt-cbc-perl</code>
* <code>sudo cpan Crypt::Rijndael_PP</code>
* <code>sudo apt-get install libcrypt-ecb-perl</code> (nur nötig, wenn ihr einen verschlüsselten Token mit 96 Zeichen habt)
* <code>sudo cpan Crypt::Cipher::AES</code> (nur nötig, wenn Crypt::Rijndael_PP aus irgendwelchen Gründen nicht funktioniert)
Wenn bei dem ein oder anderen Modul die Meldung kommt, dass es schon installiert ist, einfach mit dem nächsten Befehl weiter machen. Das CPAN Teil würde ich am Schluss machen, das braucht ziemlich lang zum installieren.

===Vorarbeiten am Smartphone (Token)===
Das Problem ist folgendes:

Wenn der Roboter mit dem WLAN verbunden wird, generiert er einen Token. Das ist ein Schlüssel, ohne den er sich nicht steuern lässt. Damit FHEM drauf zugreifen kann, benötigt man diesen Token.

Mit den neueren Versionen der MiHome App klappt das Auslesen der Tokens leider nicht mehr.

====Auslesen bei Android Endgeräten====

Ich gehe davon aus, dass der Staubsauger mit der original MiHome App eingebunden ist und funktioniert. (Ich habe bei der Einrichtung des Servers => "other" gewählt. Offenbar wollen neuere Staubsauger sich mit "China Mainland" nicht mehr verbinden. Tut hier an dieser Stelle zwar nichts zur Sache, aber vielleicht hilft es dem ein oder anderen. Wenn man die Region gewechselt hat, muss man auch den Staubsauger neu einbinden)

* MiHome löschen
* alte MiHome suchen (APKMirror z.B., Version 5.0.19 hat bei mir funktioniert, unsichere Quellen müssen erlaubt sein)
* runtergeladene MiHome App öffnen und anmelden (sollte ganz normal den Sauger finden)
* USB-Debugging am Handy einschalten (Entwickleroptionen...)
* Handy mit USB Kabel und PC verbinden
* [https://github.com/ultrara1n/MiToolkit/releases MiToolkit] 1.6 runterladen und öffnen
* [https://github.com/ultrara1n/MiToolkit/releases MiToolkit] erzeugt nun am Handy ein Backup
* anschließend zeigt es den Token direkt am PC an

====Auslesen bei iOS Endgeräten====

Zum Auslesen des Tokens mit iOS Endgeräten kann die Anleitung unter folgendem Link befolgt werden: [https://forum.smartapfel.de/forum/thread/370-xiaomi-token-auslesen/]

===Installation des inoffiziellen Moduls===
Der folgende Teil ist für völlige Noobs. Wenn ihr einen eleganteren Weg kennt, her damit.

Zunächst bitte das Modul aus dem Forum herunterladen.
[https://forum.fhem.de/index.php/topic,73052.0.htmlm Hier] befindet sich der Thread. Markus M. hat sich die Mühe gemacht, ein Modul zu schreiben. Solange es nicht offiziell eingecheckt ist, muss man es händisch installieren. Das kann man wie folgt machen:
* das Modul zunächst auf seinem Windows PC speichern

Wie kommt das Modul nun auf den eigenen RasPi?

Ich nutze dafür einen kleinen HTTP Server auf meinem Windows Rechner: [http://miniweb.sourceforge.net/ MiniWeb]

Dieses Tool runterladen und irgendwohin entpacken. Zum starten habe ich eine kleine Batchdatei geschrieben:
<pre>D:\Software\MiniWebServer\miniweb\miniweb.exe -p 80</pre>
Die sorgt nur dafür, dass der Server auf Port 80 läuft.

Im entpackten Verzeichnis ist ein Unterverzeichnis mit dem Namen "htdocs". Dahin kopieren wir das soeben runtergeladene Modul aus dem Forum-Thread.

Langsam sollte das cpan Tool auf unserer SSH Verbindung durchgelaufen sein.

Nun wechseln wir (auf dem Linux Rechner) in das FHEM Verzeichnis (cd /opt/fhem/FHEM).

<pre>wget http://IP-Adresse_EUres_Windows_Rechners/72_XiaomiDevice.pm</pre>

bringt die Datei in euer FHEM Verzeichnis.

Jetzt noch die Rechte anpassen:

<pre>sudo chown fhem:dialout /opt/fhem/FHEM/72_XiaomiDevice.pm</pre>

Fertig.

Jetzt können wir auf die FHEM Oberfläche wechseln.

<pre>reload 72_XiaomiDevice.pm</pre>

und unser runtergeladenes Modul steht in FHEM zur Verfügung.

==Einrichten des Moduls==
<pre>
define Mi_Vacuum XiaomiDevice 192.168.222.77 55387753545937326a33396943557999

attr Mi_Vacuum subType VacuumCleaner
</pre>

Und schon (=etwa nach 10 Sekunden) sollte euer Roboter in FHEM mit ganz vielen Readings auftauchen.

==Anwendung: Sprachsteuerung mit Alexa (einfach, ein und aus)==
Wie bindet man das jetzt schnell in Alexa ein?

Wir legen uns in FHEM einen Dummy an. Dieser wird ein Switch (on off). Dazu noch ein DOIF oder ein notify, welches diesen Switch überwacht. Je nach Status des Dummys schalten wir den Roboter.

Ein List meines Dummys:
<pre>
Internals:
CFGFN
NAME Mi_Vacuum_Staubsauger
NR 719473
STATE on
TYPE dummy
Readings:
2017-09-18 21:10:12 state on
Attributes:
alexaName Mi_Vacuum_Staubsauger
genericDeviceType switch
room alexa
setList on off
</pre>

Mein DOIF:

<pre>
define di_Mi_Vacuum DOIF ([Mi_Vacuum_Staubsauger:"on"]) (set Mi_Vacuum start) DOELSE (set Mi_Vacuum charge)
</pre>

Das Attribut do always nicht vergessen!

Den Dummy setzen wir in den Raum, der unsere Alexa Geräte beinhaltet. Nun den Alexa FHEM Service neu starten. Anschließend sollte eine Suche nach neuen Geräten in Alexa unseren Dummy finden. Für diesen legen wir in Alexa einen neuen Raum an, z.B. Staubsauger.

Fertig.

Ein "Alexa schaltet den Staubsauger ein" lässt unseren Mi-Vacuum loslegen. "Alexa schalte den Staubsauger aus" schickt ihn wieder zurück zu seiner Station.

==Quellen==
* {{Link2Forum|Topic=73052|LinkText=Forums-Thread}}
* {{Link2Forum|Topic=76940|LinkText=Diskussionsthread}}
* [http://miniweb.sourceforge.net/ MiniWeb], kleiner WebServer für Windows
* [https://xiaomi.flole.de/ Flole], alternative App für Android, die das Token nach GoogleDrive exportiert
* [http://www.roboter-forum.com/forumdisplay.php?130-Xiaomi Roboter-Forum] deutschsprachiges Forum, welches sich mit dem Mi Vacuum beschäftigt (auch vor dem Kauf des Roboters lohnt sich ein Besuch dort)
* [https://paypal.me/mm0 PayPal]-Link, um Markus M. Dankeschön zu sagen

HMCCU

2018-07-24T10:08:18Z

Slanesh: Dativ ist dem Genitiv sein Tod

{{Baustelle}}
{{Infobox Modul
|ModPurpose=Anbindung Homematic CCU2 an FHEM
|ModType=d
|ModCmdRef=HMCCU
|ModForumArea=HomeMatic
|ModTechName=88_HMCCU.pm
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])
}}

==Einführung==
===Übersicht===
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:

* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben
* Lesen und Schreiben von CCU2 Systemvariablen
* Ausführen von CCU2 Programmen
* Ausführen von Homematic Scripts auf der CCU2

Die einzelnen Module haben folgende Aufgaben:

* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)
* HMCCURPC: Alternativer auf Threads basierender RPC-Server
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen

===Geräte, Kanäle und Datenpunkte===
Geräte in der HomeMatic CCU bestehen aus einem oder mehreren Kanälen. Ein Kanal wiederum hat einen oder mehrere Datenpunkte. Über diese Datenpunkte kann ein Gerät gesteuert oder Statusinformationen ausgelesen werden. Sofern ein Datenpunkt lesbar ist, kann er als Reading in einem HMCCUCHN oder HMCCUDEV Device dargestellt werden. Ausgehend von dieser Abbildung in der CCU kann man nun entscheiden, ob man ein CCU Gerät mit HMCCUCHN oder HMCCUDEV definiert.

Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.

Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}

==Inbetriebnahme==
===Zu beachten===

* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.
* Seit der CCU2 Firmware 2.27.7 sind die Zugriffsmöglichkeiten auf die CCU durch eine Firewall abgesichert. Der Zugriff durch FHEM muss explizit freigeschaltet werden, da HMCCU sonst nicht korrekt funktioniert (s. nächster Abschnitt).

===CCU Firewall Einstellungen===
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:
* Menü "Einstellungen > Systemsteuerung" aufrufen
* Button "Firewall konfigurieren" anklicken
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.
* Man kann die Rechte auf "Eingeschränkter Zugriff" belassen, muss dann aber im Feld "IP-Adressen für eingeschränkten Zugriff" die IP des FHEM-Servers oder das komplette Subnetz in Subnet-Notation angeben.

===Installation===
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre>
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.

Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.

===Definition I/O Device===
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.
<pre>define d_ccu HMCCU 192.168.1.10</pre>
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Paramter waitforccu angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch waitfoccu wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die 180 Sekunden sind nur ein Beispiel. Je nach Installation kann auch ein höherer Wert notwendig sein:
<pre>define d_ccu HMCCU 192.168.1.10 waitforccu=180</pre>

===RPC Server konfigurieren===
Im nächsten Schritt wird der RPC-Server konfiguriert und gestartet. Zunächst werden mit dem Attribut ''rpcinterfaces'' die Schnittstellen bzw. Ports festgelegt, für die sich der RPC-Server bei der CCU2 registrieren soll. Folgende Angaben sind möglich:
* BidCos-RF
* BidCos-Wired
* HmIP-RF
* CUxD
* Homegear
* VirtualDevices
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.

Mit Version 4.2 stehen drei verschiedene RPC Server zur Verfügung. Der verwendete RPC Server wird im I/O Device mit dem Attribut ccuflags festgelegt:
* intrpc = Interner RPC Server des Moduls HMCCU. Verwendet Filequeues für die Eventverarbeitung. Relativ langsame Reaktionszeit
* extrpc = Externer RPC Server (Modul HMCCURPC). Verwendet Threads und ist teilweise inkompatibel mit Modulen, die JSON verwenden (s.u.)
* procrpc = Externer RPC Server (Modul HMCCURPCPROC). Verwendet Subprozesse, hat eine sehr kurze Reaktionszeit und keine Probleme mit JSON.

Ab Version 4.2 ist ccuflags=procrpc zu bevorzugen. Ab Version 4.3 werden die anderen beiden Varianten eingestellt.

'''Interner RPC-Server'''
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:
<pre>attr d_ccu ccuflags intrpc
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices
attr d_ccu rpcqueue /tmp/ccuqueue
attr d_ccu rpcinterval 5</pre>

'''Externer RPC-Server (HMCCURPC)'''
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden. Beispiel:
<pre>attr d_ccu ccuflags extrpc
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre>
{{Hinweis|Beim externen RPC-Server kann es zu Inkompatibilitäten mit Modulen kommen, die JSON verwenden (z.B. HUEBridge). Falls im Log von FHEM JSON Fehlermeldungen auftauchen, muss entweder der interne RPC-Server verwendet oder das Perl Modul JSON::XS deinstalliert werden. Für die Nutzung von JSON ist es nicht zwingend erforderlich. Unter Raspbian kann das Modul mit folgendem Befehl entfernt werden:
<pre>sudo dpkg --purge libjson-xs-perl</pre>
Für CPAN lautet der Befehl:
<pre>sudo cpan --uninstall JSON::XS</pre>
}}

'''Externer RPC-Server (HMCCURPCPROC)'''
Beim ersten Start dieses RPC-Servers über das I/O Device wird automatisch je Schnittstelle ein Device vom Typ HMCCURPCPROC angelegt. Die Attribute room und group werden vom I/O Device übernommen.

'''RPC-Server starten'''
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.

Der eigentliche Startbefehl sieht so aus:
<pre>set d_ccu rpcserver on</pre>
Während des Starts des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:
<pre>attr d_ccu rpcserver on</pre>

===Vorgaben für Client Devices===
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:
{| class="wikitable"
|-
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung
|-
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.
|-
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden
|-
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings
|-
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.
|}
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.

Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.

==Synchronisation mit der CCU==
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' liest alle Geräte aus der CCU. Er sollte immer ausgeführt werden, wenn sich an einer Gerätedefinition in der CCU etwas geändert hat, z.B. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.

Der Befehl '''get update''' liest die Datenpunkte aller in FHEM definierten HMCCUDEV und HMCCUCHN Devices aus der CCU und aktualisiert alle Readings aller Client Devices.

==Autocreate von Client Devices==
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre>
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.
Folgende ''Options'' sind möglich:
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.

Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre>

==Verwaltung von Default Attributen==
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.

===Anzeigen der Gerätetypen mit Default Attributen===
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.

===Default Attribute exportieren und importieren===
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:
<pre>
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt

... Datei /opt/fhem/hmccu_defattr.txt editieren ...

set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt
</pre>
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.

===Benutzerdefinierte Attribute löschen===
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.

==Weitere Funktionen des Moduls HMCCU==
===Lesen und Ändern von CCU2 Systemvariablen===
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.

Beispiel: Lesen aller Systemvariablen, die mit A beginnen:
<pre>get d_ccu vars A.*</pre>
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:
<pre>set d_ccu var Temperatur 20.5</pre>

===Ausführen von CCU2 Programmen===
Ein in der CCU2 hinterlegtes Programm kann mit dem Befehl '''set execute''' ausgeführt werden. Einziger Parameter des Befehls ist der Name des Programms. Es spielt keine Rolle, ob das Programm in der CCU2 aktiv oder inaktiv ist.

Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:
<pre>set d_ccu execute Schalter_Ein</pre>

===Aggregation von Gerätezuständen (ab 3.6)===
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?
* Wieviele und welche Fenster sind geöffnet?
Für die Beantwortung dieser Fragen stellt HMCCU einige Befehle und Attribute bereit. Die Ergebnisse werden in Form von Readings im I/O Device bereitgestellt:
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).
Aggregationen werden automatisch bei Änderung von Readings neu berechnet. Alternativ kann mit dem Befehl '''get aggregation''' eine Aggregation explizit durchgeführt werden. Als Parameter wird der Name der Aggregationsregel oder "all" für alle Aggregationen übergeben:
<pre>get <io-dev> aggregation {all|<name>}</pre>
Die Konfiguration der Aggregationen erfolgt mit Hilfe von Regeln, die über das Attribut ''ccuaggregate'' definiert werden. Dabei werden mehrere Regeln durch ein Semikolon und optional ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:
*'''name''':<Name> - Legt den Namen einer Aggregation fest.
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:
**name: FHEM Device Name
**alias: FHEM Device Alias
**group: FHEM Device ''group'' Attribut
**room: FHEM Device ''room'' Attribut
**type: Homematic Gerätetyp
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.
*'''else''':<Value>
*'''prefix''':{RULE|<Text>} - Legt das Präfix für die Readings fest, die das Ergebnis einer Aggregation beinhalten wobei "RULE" für den Namen der Aggregationsregel steht.
*'''coll''':{NAME|<Attribute>}[!<Default>] - Legt fest, welches Attribut der FHEM Devices, die in die Aggregation einbezogen werden, in das _list Reading aufgenommen werden, sofern sie die if Bedingung erfüllen. Dabei entspricht "NAME" dem FHEM-Devicename. Der optionale Parameter Default legt den Inhalt des _list Readings fest, wenn keines der FHEM Devices die if Bedingung erfüllt. Voreingestellt ist "no match".

Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):
<pre>
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias
</pre>
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):
<pre>
battery_count: 50
battery_list: Fenster Bad,Fenster Wohnzimmer
battery_match: 2
battery_state: yes
</pre>

===Ausführen von Homematic Scripts===
Mit dem Befehl '''set hmscript''' kann ein beliebiges Homematic Script an die CCU2 zur Ausführung gesendet werden. Wenn das Script zeilenweise Daten im Format "Parameter=Value" zurück gibt, werden diese als Readings mit dem Namen ''Parameter" im I/O Device gespeichert.

Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):
<pre>
object osysvar;
string ssysvarid;
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())
{
osysvar = dom.GetObject(ssysvarid);
WriteLine (osysvar.Name() # "=" # osysvar.Value());
}
</pre>

Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:

<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre>

[[Kategorie:HomeMatic Components]]

Diskussion:Alexa-Fhem

2017-01-02T12:14:43Z

Slanesh: Formatierung angepasst

== Vorschlag zur Optimierung der Anleitungs-Struktur ==

Für eine bessere Strukturierung/Nachvollziehbareit ohne zu viele Sprünge in der Anleitung, schlage ich vor die Abschnitte 2.2 bis 2.4 (Installation in FHEM) an das Ende der Anleitung zu verschieben, da dann bereits ''applicationId'' und ''oauthClientID'' bekannt sind.

Die Struktur könnte wie folgt optimiert werden:

# Einführung
## Arbeitsweise und Datenfluss
## Anmerkungen
## Abgrenzung Alexa Smart Home Skill und Alexa Custom Skill
# Vorbereitung
## Alexa Skills anlegen
### Smart Home Skill
### Custom Skill
## AWS Lambda Funktion anlegen
# Installation
## Alexa-FHEM installieren
## Alexa-Fhem aus FHEM starten
## Alexa Device anlegen
# Einrichtung
## Alexa Skills aktivieren
## Geräte suchen
# Nutzung
## Smart Home Skill
## Custom Skill
# Troubleshooting
## Allgemeiner Hinweis
## [...]

--[[Benutzer:Slanesh|Slanesh]] ([[Benutzer Diskussion:Slanesh|Diskussion]]) 13:14, 2. Jan. 2017 (CET)

Diskussion:Alexa-Fhem

2017-01-02T12:05:42Z

Slanesh: Vorschlag zur Optimierung der Seiten-Struktur

Für eine bessere Strukturierung/Nachvollziehbareit ohne zu viele Sprünge in der Anleitung, schlage ich vor die Abschnitte 2.2 bis 2.4 (Installation in FHEM) an das Ende der Anleitung zu verschieben, da dann bereits ''applicationId'' und ''oauthClientID'' bekannt sind.

Die Struktur könnte wie folgt optimiert werden:

1. Einführung
1.1 Arbeitsweise und Datenfluss
1.2 Anmerkungen
1.3 Abgrenzung Alexa Smart Home Skill und Alexa Custom Skill

2. Vorbereitung
2.1 Alexa Skills anlegen
2.2.1 Smart Home Skill
2.2.2 Custom Skill
2.2 AWS Lambda Funktion anlegen

3. Installation
3.1 Alexa-FHEM installieren
3.2 Alexa-Fhem aus FHEM starten
3.3 Alexa Device anlegen

4. Einrichtung
4.1 Alexa Skills aktivieren
4.2 Geräte suchen

5. Nutzung
5.1 Smart Home Skill
5.2 Custom Skill

6. Troubleshooting
6.1 Allgemeiner Hinweis
6.2 [...]

Alexa-Fhem

2017-01-01T19:26:50Z

Slanesh: Kleine Korrekturen/Ergänzungen (Tippfehler, Installation, Verweis, Link-Bezeichnung)

'''Alexa-Fhem''' ist eine in JavaScript 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 [https://forum.fhem.de/index.php/topic,60244.0.html 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=Sonstige Systeme
|ModOwner=justme1968
}}

==Einführung==

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

*Der Echo (oder ein anderes Alexa/AVS fähiges device) 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 Custom Skill kommen die dazu nötgen Informationen aus dem ''Interaction Model'' der Alexa Skills Konfiguration
:*Beim Home Automation Skill sind die möglichen Sätze fest vorgegeben
*Das Event wird an den unter ''Configruation'' in der Alexa Skills Konfiguration hinterlegten Endpoint geschickt
:*Beim Home Automation Skill ist das zwingend eine AWS Lambda Routine
:*Beim 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 das 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.
*Es ist ein kleines Wunder wie schnell die Reaktion auf einen gesprochenen Satz erfolgt wenn man berücksichtigt welchen Weg die Daten insgesamt gehen.

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

Grundvoraussetzung für alle folgenden Schritte ist, dass ein Amazon-Account vorhanden ist. Es wird davon ausgegangen, dass bereits für alle folgenden Amazon-Dienste vorab das Konto jeweils eingerichtet wurde, die Einrichtung dieser ist nicht Bestandteil dieser Anleitungen.

Es sei an dieser Stelle darauf hingewiesen, dass für die Nutzung der Amazon AWS-Dienste zwingend die Daten einer Kreditkarte angegeben werden müssen. 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.

{{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. Dies vermeidet Fehler, die ansonsten geschehen können. Während der Konfiguration bietet es sich an diese Schritte dann parallel in gleichzeitig geöffneten Browserfenster durchzuführen. }}

=== Voraussetzungen ===
Folgende grundlegende Voraussetzungen sollten erfüllt sein, bevor du mit der Einrichtung beginnst:
* Amazon Echo oder Amazon Dot
* node.js (vermutlich ab Version 0.12.7, getestet mit 4.2.6. Kann in Debian z.B. mit <source lang="bash" style="width:50%;">sudo apt-get install nodejs-legacy</source> installiert werden)
* Weiterleitung von Port 3000 vom Router aus auf den Rechner, auf dem Alexa-Fhem läuft
* Es empfiehlt sich ein alexa Gerät in FHEM anzulegen.

=== Alexa-Fhem installieren ===
# Die tgz-Datei unter Linux entpacken (Windows macht die Rechte kaputt!) (Quelle: https://forum.fhem.de/index.php/topic,60244.0.html) (neuere Version verügbar, bitte Hinweise unter Custom Skill beachten:https://forum.fhem.de/index.php/topic,60244.msg540117.html#msg540117) <source lang="bash" style="width:50%;">tar -xzf alexa-fhem-0.1.3.tgz</source>
# Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit (kein sudo!) <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren
# SSL Zertifikat erzeugen durch Aufruf von (kein sudo!)<source lang="bash" style="width:50%;">./createKey.sh</source>. Hierbei beachten, dass ein Kennwort vergeben werden soll, das mindestens aus 4 Zeichen besteht.
# Die Datei ''config-sample.json'' nach ''~/.alexa/config.json'' kopieren (~/.alexa gegebenenfalls vorher anlegen) und die Werte auf die eigene Umgebung hin anpassen. Der Filter funktioniert hierbei wie bei [http://www.fhemwiki.de/wiki/Homebridge_einrichten#Einstellungen_f.C3.BCr_homebridge homebridge-fhem],die folgenden Zeilen sind anzupassen oder zu löschen:<br>"nat-pmp": -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers,<br>"nat-upnp": -> wenn nat-upnp verwendet werden soll: ''true'',<br>"applicationId": -> SkillID aus "Alexa Custom Skill anlegen" Punkt 7 (s.u.),<br>"oauthClientID": -> ''Client Id'' aus Punkt 1. '''Login with Amazon'''
# Durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)

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 [https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271 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:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

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):

<source lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy</source>

<source lang="bash" style="width:75%;">define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart</source>

<source lang="bash" style="width:75%;">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 &")})</source>

=== Alexa Device mit dem Modul 39_alexa.pm 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:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

=== Alexa Skills anlegen ===

==== Smart Home ====
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]]

===== Apps & Services =====
# Klicke nach der Anmeldung auf ''APPS & SERVICES''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Klicke anschließend auf ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Wähle anschließend ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Gebe dann ein Namen und eine Beschreibung für das Profil ein und bestätige die Eingaben durch anklicken von ''Save''<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 ist}}
# Nachdem du die vorherigen Schritte befolgt hast, siehst du im Browser das Profil dass du angelegt hast. Klicke jetzt oben rechts auf ''Login with Amazon''<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite klickst du dann auf ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Wähle anschließend im Dropdown Menü das vorher angelegte Profil aus und bestätige das anschließend mit ''Confirm''<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 gibst du dann die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] ein und bestätigst die Eingabe mit ''Save''<br/>[[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Klicke dann bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad und wähle ''Web Settings'' aus<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster klickst du dann auf ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Füge zuletzt dann bei ''Allowed Return URLs'' die Adresse [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], und [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx] hinzu. xxx muss hierbei durch den Wert ersetzt werden, der bei Punkt 6 '''Skill Kit einrichten''' unter '''Redirect Urls''' am Ende der URLs angezeigt wird.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

===== Skill Kit einrichten =====
# Wähle im Menü den Punkt ''Alexa'' aus<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Klicke dann ''Get started'' beim Punkt ''Alexa Skills Kit'' an<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]
# Wähle dann auf der neu geladenen Seite oben rechts ''Add a New Skill'' aus<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# Auf der folgenden Seite wählst du ''Smart Home Skill API'' sowie ''German'' als Sprache aus und gibst ein Name für den Skill ein was du dann mit ''Next'' bestätigst.<br />[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite klickst du mit ''Next'' dann weiter<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# Auf der Seite Configuration gibst du dann unter '''Authorization URL''' die Adresse: <source lang="bash" style="width:70%;">https://www.amazon.com/ap/oa</source>an, bei '''Scope''': <source lang="bash" style="width:70%;">profile:user_id</source> und bei '''Access Token URI''': <source lang="bash" style="width:70%;">https://api.amazon.com/auth/o2/token</source>sowie bei '''Privacy Policy URL''' die Adresse: <source lang="bash" style="width:70%;">https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</source><br /><br />Folgende Felder müssen individuell ausgefüllt werden:<br />* ''Service Endpoint Type'' -> Europe auswählen und im Textfeld den Wert aus Punkt 12 '''AWS Lambda Funktion anlegen''' eintragen<br />* ''Client Id'' -> ''Client Id'' aus Punkt 1. '''Login with Amazon'''<br />* ''Client Secret'' -> ''Client Secret'' aus Punkt 1. '''Login with Amazon'''<br /><br /><br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]]
# <br />[[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Zur späteren Verwendung unter Punkt 7 '''AWS Lambda Funktion anlegen''' wird noch die Application Id benötigt. An diese kommt man wie folgt:
# Wähle im Menü den Punkt ''Alexa'' aus<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Klicke dann ''Get started'' beim Punkt ''Alexa Skills Kit'' an<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]
# Beim vorher angelegten 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 <br />[[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

==== Custom ====
'''ACHTUNG:''' die daten unter 'interaction model' unten gelten nur für skill version 0.1.3. ab version 0.1.4 werden die daten im alexa device erzeugt. wie das geht steht hier {{Link2Forum|Topic=60244|Message=540117|LinkText=im Forum}}.

Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein{{Randnotiz|RNTyp=[g|Info]|RNText=Bei Punkt 6 wird die Skill ID angezeigt (siehe Screenshot), die später als zusätzlicher Trigger für AWS Lambda verwendet wird. Bitte per Copy / Paste speichern.}}
# Anmeldung auswählen<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|200px]]
# Wähle im Menü den Punkt ''Alexa'' aus und klicke dann ''Get started'' beim Punkt ''Alexa Skills Kit''<br />[[Datei:CustomSkill_1.PNG|400px]]
# Klicke dann oben rechts auf ''Add a new skill''
# Auf der Seite '''Create a new Alexa Skill''' werden folgende Optionen gewählt / Informationen eingetragen:
#:* Skill Type = Custom Interaction Model
#:* Language = German
#:* Name: Hier dem Skill einen beliebigen Namen geben. Dieser wird in der Alexa App unter "Meine Skills" angezeigt.
#:* Invocation Name: Name des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James"<br />[[Datei:CustomSkill_2.PNG|400px]]
# Mit ''Next'' die Seite verlassen.
# Auf der Seite '''Interaction Model''' folgende Eingaben tätigen:
#* In die Box '''Intent Schema''' den Programmcode aus folgendem Post einfügen: [https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230 https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230]<br />[[Datei:CustomSkill_3.PNG|400px]]<br /><br />
#* Nun auf ''Add Slot Type'' klicken und die Custom Slot Types (siehe [https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230 https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230]) einrichten. Bitte beachten, dass das Pipeline-Zeichen einen Zeilenumbruch darstellen soll. Im Screenshot ist sichtbar, wie das aussehen muss.<br /> Für FHEM_DEVICE und FHEM_ROOM bitte die eigenen in FHEM definierten Devices und Räume benennen (siehe oben alexaName und alexaRoom).<br />[[Datei:CustomSkill_4.PNG|400px]]<br />Der Screenshot zeigt die Einrichtung für FHEM_DEVICE. Nach der Einrichtung von FHEM_DEVICE ''SAVE'' klicken und die weiteren Slot Types (FHEM_ROOM, FHEM_SWITCH_ACTION und FHEM_artikel) jeweils durch klicken auf ''Add Slot Type'' einrichten.<br /><br />
#* Unter Sample Utterances bitte den Text aus [https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230 https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230] reinkopieren<br />[[Datei:CustomSkill_5.PNG|400px]]<br /><br />
#* Eingaben mit ''Next'' abschließen.
# Auf der Folgeseite ''Configuration'' bitte folgende Angaben machen:
#* Service Endpoint Type = AWS Lambda
#* Geographical Region = Europe
#* Im Feld ''Europe'' wird die ARN eingetragen, die man erst in nachfolgenden Abschnitt erhält! Es muss hier also erst mal pausiert werden! Den Browser Tab geöffnet lassen!
#* Sobald man die ARN hat geht es hier weiter...
#* Do you allow users to create an account or link to an existing account with you? = Yes
#* Authorization URL = https://www.amazon.com/ap/oa
#* Client ID = Client ID von oben aus '''Login with Amazon'''
#* Domain List - nichts eingeben
#* Scope = profile:user_id
#* Redirect URLs - sollten vorbelegt sein
#* Authorization Grant Type - Auth Code Grant auswählen
#* Access Token URI = https://api.amazon.com/auth/o2/token
#* Client Secret = siehe oben bei '''Login with Amazon'''
#* Client Authentication Scheme = HTTP Basic
#* Privacy Policy URL = https://www.amazon.com/gp/help/customer/display.html?nodeId=468496
#* Das sollte jetzt alles wie folgt aussehen:<br />[[Datei:CustomSkill_6.PNG|400px]]<br />[[Datei:CustomSkill_7.PNG|400px]]<br />

Damit ist die Einrichtung des Custom Skill abgeschlossen. Auf der Folgeseite lässt sich der Skill dann testen. In der Alexa App sollte der Skill nun auch sichtbar sein. Er musshier noch aktiviert werden und die Kontoverknüpfung eingerichtet werden, was selbsterklärend ist.

=== AWS Lambda Funktion anlegen ===
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<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]
# Anschließend 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]]<br />''Achtung! Es ist möglich, dass ihr hier '''Alexa Smart Home''' überhaupt nicht auswählen könnt. Dann solltet ihr ganz rechts oben in der Ecke mal schauen, welche Region bzw. welches Land ausgewählt ist. Ich empfehle hier '''Ireland''' auszuwählen. Dann erscheint bei den Funktionen auch '''Alexa Smart Home'''.''
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung unter '''Skill Kit einrichten''' in der zusätzlichen Beschreibung 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 bei ''Name'' den Wert FHEM eingeben, bei ''Runtime'' Node.js 4.3. Bei ''Role'' den Wert ''Choose an existing role'' wählen (wenn es noch keine existing role gibt: zuerst Create a custom role -> in dem Popup dann lambda_basic_execution und auf Allow) und bei ''Existing role'' dann ''x'' wählen. Der Quellcode der Datei lambda.js aus dem Quellpaket wird dann an die Stelle des großen Textfeldes vollständig eingefügt. Dann noch den Hostname im Quellcode an den eigenen anpassen. 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]]
# Klicke dann auf der Übersichtsseite oben links auf ''Functions''<br />[[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Wähle dann die angelegte Funktion aus und klicke dann im Menü ''Action'' auf den Punkt ''Show ARN''<br />[[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Punkt 6 bei '''Skill Kit einrichten''' benötigt wird<br />[[Datei:Aws.amazon.com-10-2-arn.png|200px]]

== Einrichtung ==
Nachdem die Alexa Skills installiert bzw. definiert wurden, müssen diese noch in deiner Alexa eingerichtet werden.

=== Alexa Skill ===
# Auf http://alexa.amazon.de anmelden (Per Desktop-Browser, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.)
# Auf ''Skills'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine 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 Authorisierung 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.
== 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 Bezeichnungen möglichst aus einem Wort und ohne Ziffern verwendet werden. Wenn Alexa einen Namen nicht versteht sollte man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und die Benennung anpassen.

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

==== Sprachkommandos ====
Nach erfolgreicher Einrichtung des Smart Home 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 Smart Home 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: [http://www.fhemwiki.de/wiki/Homebridge_einrichten#NodeJS_installieren NodeJS installieren] sowie [http://www.fhemwiki.de/wiki/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<source lang="bash" style="width:50%;">node -v</source>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter http://www.fhemwiki.de/wiki/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 http://www.fhemwiki.de/wiki/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.

====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====
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:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

[[Kategorie:HOWTOS]]