FHEMWiki - Benutzerbeiträge [de]

FHEM Tablet UI

2018-01-17T23:35:33Z

Pula: neues widget todoist

{{Infobox Modul
|ModPurpose=Oberfläche für FHEM
|ModType=x
|ModFTopic=34233
|ModForumArea=Frontends
|ModTechName=n.a.
|ModOwner=setstate ({{Link2FU|7023|Forum}})
}}
[[FHEM Tablet UI]] (FTUI) ist ein leichtgewichtiges aber funktionsreiches Frontend-Framework zum Steuern und Überwachen von in FHEM integrierten Geräten. Es basiert auf HTML/CSS/JavaScript und stellt somit keine zusätzlichen Anforderungen an den FHEM-Server.

Mit Hilfe zahlreicher Widgets, die sehr leicht mit HTML Code konfiguriert werden können, ist es möglich, innerhalb kurzer Zeit ein den eigenen Wünschen entsprechendes User-Interface aufzubauen.

Für den Betrieb ist nur eine FHEM-Installation mit [[HTTPSRV|HTTPSRV-Modul]] sowie ein gängiger Webbrowser notwendig.

Mit wenigen Anpassungen ist es auch möglich das UI auf anderen Webservern (Apache, u.a.) zu betreiben. Somit können FHEM und FHEM Tablet UI auch auf getrennten Systemen ausgeführt werden.

[[File:tablet_ui.png|thumb|500px|center|Beispiel für ein mit [[FHEM Tablet UI]] erstelltes User-Interface]]

{{Todo|Design-Möglichkeiten erklären, Navigationsmethoden ausformulieren}}

== Installation ==
Die Installation von FHEM Tablet UI erzeugt keinen großen Aufwand und besteht im Großen und Ganzen aus drei Schritten:
*Dateien aus dem GitHub-Repository herunterladen
*FHEM konfigurieren ([[HTTPSRV]]-Device erstellen, [[FHEMWEB]]-Attribut longpoll einstellen)
*Eine Beispieldatei anlegen

{{Hinweis|Diese Anleitung geht davon aus, dass FHEM unter Debian nach der Anleitung [https://debian.fhem.de Stable build using apt] installiert wurde.
Ist dies nicht der Fall, muss der Pfad '''/opt/fhem''' dementsprechend angepasst werden.}}

'''1.''' Zuerst müssen alle Dateien von FHEM Tablet UI in das FHEM-Verzeichnis '''/opt/fhem/www''' kopiert werden. Das geht mit folgendem '''update'''-Befehl über die FHEM-Befehlszeile.
:<code>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code>

:[[Datei:FTUI_Installation_01.png|thumb|none|Schritt 1: Dateien kopieren]]

'''2.''' Anschließend ist ein neues [[HTTPSRV]]-Device in FHEM anzulegen, welches auf den Ordner mit den gerade heruntergeladenen Dateien verweist.
:<code>define TABLETUI HTTPSRV ftui/ ./www/tablet/ Tablet-UI</code>

:[[Datei:FTUI_Installation_02.png|thumb|none|Schritt 2: HTTPSRV-Device anlegen]]

'''3.''' Damit FHEM Tablet UI mit FHEM kommunizieren kann, ist noch die '''longpoll'''-Einstellung im [[FHEMWEB]] Device festzulegen.

:<code>attr WEB longpoll websocket</code>
:bzw. bei Problemen mit ''websocket''
:<code>attr WEB longpoll 1</code>

:[[Datei:FTUI_Installation_03.png|thumb|none|Schritt 3: longpoll einstellen]]

'''4.''' Weil FTUI noch nichts anzuzeigen hat, wird die Datei '''/opt/fhem/www/tablet/index-example.html''' nach '''/opt/fhem/www/tablet/index.html''' kopiert.
:<code>sudo cp -a /opt/fhem/www/tablet/index-example.html /opt/fhem/www/tablet/index.html</code>

:[[Datei:FTUI_Installation_04.png|thumb|none|Schritt 4: index.html erstellen]]

'''5.''' Abschließend muss FHEM noch '''neu gestartet''' werden (''shutdown restart'') da das Attribut '''longpoll''' geändert wurde.

Somit ist FHEM Tablet UI bereit zur Verwendung und kann durch Aufruf der URL '''<nowiki>http://<fhem-server>:8083/fhem/ftui</nowiki>''' oder den Link im FHEM-Menü geöffnet werden

== Update ==
Ein Update von FTUI kann ebenfalls über die FHEM-Kommandozeile erfolgen.

'''1.''' Prüfen der Änderungen seit dem letzten Download/Update durch Eingabe von:
:<code><nowiki>update check https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

'''2.''' Update der geänderten Dateien durch Eingabe von:
:<code><nowiki>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

Eine weitere Option ist das Hinzufügen des FTUI-Git-Repositories zum allgemeinem Update-Vorgang von FHEM. Dabei wird dann bei einem FHEM-Update auch gleich FHEM Tablet UI aktualisiert, bzw. die Änderungen angezeigt.
:<code><nowiki>update add https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

== Konfiguration ==
===DOCTYPE===
In allen HTML-Dateien, die im Browser geladen werden und das typische HTML-Gerüst besitzen (also alle Hauptseiten, jedoch keine Template-Dateien), sollte eine ''Document Type Declaration'' (DTDT) eingefügt werden. Mit ihr wird festgelegt, welche ''Document Type Definition'' hier verwendet wird (das kommt aus der Metasprache XML), konkret also, in welcher Version der nachfolgende HTML-Code vom Browser interpretiert werden soll. Lässt man die DTDT weg, oder definiert sie auf verschiedenen Seiten unterschiedlich, kann ein und der selbe HTML-Code zu unterschiedlichen Darstellungen führen. Die DTDT erfolgt immer auf der ersten Zeile, noch vor dem <code><html></code>-Tag. Nachfolgend wird HTML5 verwendet.

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head>...</head>
<body>...</body>
</html>
</syntaxhighlight>

===META-Parameter===
Das Tablet UI lässt sich über die META-Parameter konfigurieren. Diese Parameter sind in jeder '''.html''' Datei (z.B. index.html) im Abschnitt '''<head>''' einzutragen. Ausgenommen davon sind Dateien, die als Template, Pagebutton-Zielseiten oder ähnliches eingebunden werden.

Die Parameter sind immer nach diesem Schema aufgebaut:
<meta name="[Parameter-Name]" content="[Parameter-Wert]">

===Verbindung zu FHEM===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|web_device||WEB||String||FHEM-Device, welches für das Polling verwendet wird
|-
|longpoll||1||0, 1||
'''0''': Longpoll deaktiviert; alle 30s ein Shortpoll (Neuladen der gesamten Statusänderungen)

'''1''': Longpoll aktiv; geänderte Stati werden sofort aktualisiert, zusätzlich werden alle 15min die gesamten Statusänderungen geladen.
|-
|longpoll_type||websocket||websocket, ajax, 0||
'''websocket''': Für die Aktualisierung der Daten wird das Websocket-Protokoll verwendet. Werden vom Browser keine Websockets unterstützt, gibt es einen automatischen Fallback auf Ajax.

'''ajax''': Ajax wird für die Aktualisierung verwendet.

'''0''': Longpoll deaktiviert, Shortpoll wird verwendet.
|-
|longpoll_filter||.*||RegEx||Event-Filter. Kann verwendet werden, wenn z.B. Devices, die in FTUI angezeigt werden, in einem eigenen FHEM-Room sind.
|-
|longpoll_maxage||240||Integer||Kommen in diesem Zeitraum (Sekunden) keine Longpoll-Events bei FTUI an, wird die Verbindung als "disconnected" angesehen und ein neuer Verbindungsversuch wird gestartet.
|-
|shortpoll_interval||900||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet
|-
|shortpoll_only_interval||30||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet, sollte Longpoll deaktiviert sein
|-
|fhemweb_url||/fhem/||Integer||URL zu FHEM. Wird benötigt wenn FTUI auf einem anderen als dem FHEM Server läuft oder nicht im Standard-Pfad installiert ist.
Hinweis: Wenn FHEM auf einem anderem Server/Domain läuft muss man das "CORS" Attribut im FHEMWEB Modul (s.o.) auf 1 setzen, sonst bekommt man Cross Origin Fehler.
|}

===Funktionalität===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|debug||0||0 - 5||Log-Level
|-
|toast||5||Integer||Anzahl an gleichzeitig angezeigten Toast-Nachrichten. Um keine anzuzeigen, ist der Wert auf 0 zu setzen.
|-
|toast_position||bottom-left||||Position im Browserfenster, wo die Toast-Nachrichten angezeigt werden.
|-
|lang||de||de||Sprache der Oberfläche (für z.B. Datums-/Zeitfunktionen)
|-
|username||||String||Benutzername für eine Basic-Authentifierung *
|-
|password||||String||Passwort für eine Basic-Authentifizierung *
|}
'''*''' Derzeit wird die Basic-Authentifizierung in Kombination mit WebSockets nicht unterstützt. Die Verwendung von '''longpoll=1''' (ajax) ist daher notwendig.

===Toast-Nachrichten===
[[Datei:Ftui_toast.png|thumb|Toast-Nachrichten]]
Tablet-UI liefert Informationen darüber, was im Moment gerade passiert. Das geschieht über Toast-Nachrichten, die in der Standardeinstellung unten links im Browser auftauchen.

Wird beispielsweise ein Gerät eingeschaltet, so erscheint eine kleine Nachricht mit dem abgesetzten Befehl. Auch Fehlermeldungen und Statusinformationen werden angezeigt. Ob überhaupt und was konkret angezeigt wird, richtet sich nach dem eingestellten Debug-Level (siehe oben). Beim Debug-Level 5 werden alle Nachrichten angezeigt, bei 0 keine.

Die Position der Toast-Nachrichten kann über den Meta-Tag <code>meta name='toast_position'</code> festgelegt werden. Für oben-mittig müsste folgender Code eingefügt werden:
<pre><meta name='toast_position' content='top-center'></pre>

Möglich sind folgende Positionen:
* <code>top-left</code>
* <code>top-right</code>
* <code>bottom-left</code>
* <code>bottom-right</code>
* <code>top-center</code>
* <code>bottom-center</code>
* <code>mid-center</code>

Die maximale Anzahl an Nachrichten, die gleichzeitig angezeigt werden können, lässt sich mit <code>meta name='toast'</code> Sind maximal 2 Nachrichten gewünscht, muss folgender Meta-Tag gesetzt werden:
<pre><meta name='toast' content='2'></pre>

==Navigationsmethoden==
{{Todo|Dieser Abschnitt dient derzeit lediglich als Sammlung von Stichpunkten und muss vollständig überarbeitet werden.}}

'''Unterschied zwischen Pagetab und Pagebutton:

'''Pagetab:''' Ganze Seite austauschen -> Menü muss auf jede Seite
[[FTUI_Widget_Pagetab]]

'''Pagebutton:''' Teil der Seite austauschen -> Menü nur in erster Seite
[[FTUI_Widget_Pagebutton]]

==Gestaltung==
===Layout-Optionen===
* [[FTUI Layout Gridster|Gridster]]
* [[FTUI Layout Flex|Flex]]
* [[FTUI Layout Sheet|Tabelle]]
* [[FTUI Layout Row|Reihen]]

=== Farben ===
Es besteht die Möglichkeit, die Farbwerte in hexadezimaler Form, als RGB-Wert oder mit dem Farbnamen anzugeben. Zum Beispiel:

*HEX: #ADD8E6
*RBG: rgb(173, 216, 230)
*Namen: lightblue

Knallige Farben wie '''<span style="color: #ff0000;">#ff0000</span>''' für Rot oder '''<span style="color: #00ff00;">#00ff00</span>''' für Grün sollten vermieden werden.
Es ist besser unterhalb von #D0 (208) für die Grundfarben zu bleiben.

Empfohlene Farben sind z.B.:

*Orange: <span style="color: #aa6900;">#aa6900</span>
*Rot: <span style="color: #ad3333;">#ad3333</span>
*Grün: <span style="color: #32a054;">#32a054</span>
*Blau: <span style="color: #6699FF;">#6699FF</span>
*Grau: <span style="color: #8C8C8C;">#8C8C8C</span>

Hilfreich bei der Suche nach den Farbwerten ist zum Beispiel der Color-Picker auf dieser Seite: http://www.colorpicker.com. Für die Suche nach Farben, die einen guten Kontrast bilden, diese Webseite: http://vanisoft.pl/~lopuszanski/public/colors/

Im Ordner ''css'' der FTUI Installation finden sich einige vorbereitete Farbschemas. Diese können mit einem zusätzlichen Eintrag im <nowiki><head></nowiki>-Bereich der FTUI-Seite(n) aktiviert werden.

Hier am Beispiel eines blauen Farbschemas:
<syntaxhighlight lang="html">
<html>
<head>
[...]
<link rel="stylesheet" href="/fhem/tablet/css/fhem-blue-ui.css" />
[...]
</head>
</syntaxhighlight>

Diese Schema-Dateien ändern alle Widgets. Einzelne Widgets können durch Hinzufügen der jeweiligen [[#CSS-Klassen|CSS-Klasse]] geändert werden.

===CSS-Styles===
Das Layout und das Aussehen des UI kann durch diverse vorgegebene CSS-Klassen beeinflusst werden. Die verfügbaren Klassen sind im Abschnitt [[#CSS-Klassen|CSS-Klassen]] aufgeführt.

Soll das Aussehen des UI durch eigene CSS-Klassen oder durch Überschreiben der vorhandenen verändert werden, kann eine eigene CSS-Datei erstellt werden, die dann bei einem eventuellen Update von FTUI nicht überschrieben wird. Diese Datei muss den Dateinamen '''fhem-tablet-ui-user.css''' haben und im Ordner '''/fhem/tablet/css''' abgelegt werden. Sie wird dann beim Aufruf von FTUI automatisch mitgeladen.

=== CSS-Klassen ===
Nicht alle Widgets unterstützen alle hier angegebenen Klassen. Welche genau unterstützt werden, kann auf der jeweiligen Widget-Seite nachgelesen werden.

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|sheet/row/cell-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|sheet}}{{FTUI Klasse|row}}{{FTUI Klasse|cell}}{{FTUI Klasse|cell-1-x}}{{FTUI Klasse|cell-x}}{{FTUI Klasse|left-align}}{{FTUI Klasse|right-align}}{{FTUI Klasse|bottom-align}}{{FTUI Klasse|top-align}}{{FTUI Klasse|center-align}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|row/col-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|col}}{{FTUI Klasse|col-1-x}}{{FTUI Klasse|col-x}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|hbox/vbox-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|vbox}}{{FTUI Klasse|hbox}}{{FTUI Klasse|card}}{{FTUI Klasse|phone-width}}{{FTUI Klasse|full-height}}{{FTUI Klasse|full-width}}{{FTUI Klasse|grow-0}}{{FTUI Klasse|grow-1}}{{FTUI Klasse|grow-2}}{{FTUI Klasse|grow-x}}{{FTUI Klasse|items-top}}{{FTUI Klasse|items-center}}{{FTUI Klasse|items-bottom}}{{FTUI Klasse|items-space-between}}{{FTUI Klasse|items-space-around}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Generelle Klassen für die Positionierung
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|inline}}{{FTUI Klasse|newline}}{{FTUI Klasse|top-space}}{{FTUI Klasse|top-space-2x}}{{FTUI Klasse|top-space-3x}}{{FTUI Klasse|left-space}}{{FTUI Klasse|left-space-2x}}{{FTUI Klasse|left-space-3x}}{{FTUI Klasse|right-space}}{{FTUI Klasse|right-space-2x}}{{FTUI Klasse|right-space-3x}}{{FTUI Klasse|top-narrow}}{{FTUI Klasse|top-narrow-2x}}{{FTUI Klasse|top-narrow-10}}{{FTUI Klasse|left-narrow}}{{FTUI Klasse|left-narrow-2x}}{{FTUI Klasse|left-narrow-3x}}{{FTUI Klasse|right-narrow}}{{FTUI Klasse|right-narrow-2x}}{{FTUI Klasse|right-narrow-3x}}{{FTUI Klasse|centered}}{{FTUI Klasse|wider}}{{FTUI Klasse|narrow}}{{FTUI Klasse|fullsize}}{{FTUI Klasse|compressed}}{{FTUI Klasse|height-narrow}}{{FTUI Klasse|w1x}}{{FTUI Klasse|w2x}}{{FTUI Klasse|w3x}}{{FTUI Klasse|maxw40}}{{FTUI Klasse|doublebox-v}}{{FTUI Klasse|doublebox-h}}{{FTUI Klasse|triplebox-v}}{{FTUI Klasse|right}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Vordergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|red}}{{FTUI Klasse|green}}{{FTUI Klasse|blue}}{{FTUI Klasse|lightblue}}{{FTUI Klasse|orange}}{{FTUI Klasse|gray}}{{FTUI Klasse|lightgray}}{{FTUI Klasse|white}}{{FTUI Klasse|black}}{{FTUI Klasse|mint}}{{FTUI Klasse|yellow}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Hintergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|bg-red}}{{FTUI Klasse|bg-green}}{{FTUI Klasse|bg-blue}}{{FTUI Klasse|bg-lightblue}}{{FTUI Klasse|bg-orange}}{{FTUI Klasse|bg-gray}}{{FTUI Klasse|bg-lightgray}}{{FTUI Klasse|bg-white}}{{FTUI Klasse|bg-black}}{{FTUI Klasse|bg-mint}}{{FTUI Klasse|bg-yellow}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Rahmen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|verticalLine}}{{FTUI Klasse|border-black}}{{FTUI Klasse|border-white}}{{FTUI Klasse|border-orange}}{{FTUI Klasse|border-red}}{{FTUI Klasse|border-green}}{{FTUI Klasse|border-mint}}{{FTUI Klasse|border-lightblue}}{{FTUI Klasse|border-blue}}{{FTUI Klasse|border-gray}}{{FTUI Klasse|border-yellow}}{{FTUI Klasse|border-lightgray}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Größen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|mini}}{{FTUI Klasse|tiny}}{{FTUI Klasse|small}}{{FTUI Klasse|normal}}{{FTUI Klasse|large}}{{FTUI Klasse|big}}{{FTUI Klasse|bigger}}{{FTUI Klasse|tall}}{{FTUI Klasse|great}}{{FTUI Klasse|grande}}{{FTUI Klasse|gigantic}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Schriftstil
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|thin}}{{FTUI Klasse|bold}}{{FTUI Klasse|darker}}{{FTUI Klasse|truncate}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Sonstiges
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|blank}}{{FTUI Klasse|transparent}}{{FTUI Klasse|half-transparent}}{{FTUI Klasse|blurry}}{{FTUI Klasse|shake}}{{FTUI Klasse|fail-shake}}{{FTUI Klasse|marquee}}{{FTUI Klasse|icon round}}{{FTUI Klasse|icon square}}{{FTUI Klasse|readonly}}{{FTUI Klasse|blink}}{{FTUI Klasse|rotate-90}}{{FTUI Klasse|horizontal}}{{FTUI Klasse|circleborder}}{{FTUI Klasse|autohide}}{{FTUI Klasse|notransmit}}{{FTUI Klasse|tab}}{{FTUI Klasse|FS20}}{{FTUI Klasse|value}}{{FTUI Klasse|novalue}}{{FTUI Klasse|timestamp}}{{FTUI Klasse|percent}}{{FTUI Klasse|nocache}}{{FTUI Klasse|fade}}{{FTUI Klasse|rotate}}{{FTUI Klasse|nolabels}}{{FTUI Klasse|default}}{{FTUI Klasse|prefetch}}{{FTUI Klasse|circulate}}{{FTUI Klasse|valueonly}}{{FTUI Klasse|positiononly}}{{FTUI Klasse|lineIndicator}}{{FTUI Klasse|barIndicator}}{{FTUI Klasse|roundIndicator}}{{FTUI Klasse|dim-tick}}{{FTUI Klasse|dim-front}}{{FTUI Klasse|dim-back}}{{FTUI Klasse|hue-tick}}{{FTUI Klasse|hue-front}}{{FTUI Klasse|hue-back}}{{FTUI Klasse|warn}}{{FTUI Klasse|activate}}{{FTUI Klasse|labelright}}{{FTUI Klasse|interlock}}{{FTUI Klasse|keepopen}}{{FTUI Klasse|noshade}}
|}

=== Icons ===
FTUI bringt einige Icons-"Schriftarten" mit, die für die Darstellung genützt werden können. Diese werden automatisch beim Start des UI eingebunden, sobald ein entsprechendes Icon-Präfix im Code der Seite vorkommt.

Verfügbare Icon-Schriftarten sind:
* Eingebaute Icons ''ftui-windows'' und ''ftui-door''. Präfix '''ftui-'''. Beispiel: <code>data-icon="ftui-door"</code>
* [http://fontawesome.io/icons/ Font-Awesome]: Mehr als 500 Icons zur Auswahl. Präfix '''fa-'''. Beispiel: <code>data-icon="fa-volume-up"</code>
* [https://material.io/icons/ Material Icons]: Mehr als 900 Icons zur Auswahl. Präfix '''mi-'''. Beispiel: <code>data-icon="mi-local_gas_station"</code>
* FHEM und OpenAutomation Icons: Präfix '''fs-''' und '''oa-'''. Beispiel: <code>data-icon="oa-secur_locked"</code>
* [https://erikflowers.github.io/weather-icons/ Weather-Icons]: Präfix '''wi-'''. Beispiel: <code>data-icon="wi-day-rain-mix"</code>

Alternativ können auch Bilder Icons (bspw. png) über CSS verwendet werden. Bspw:
<syntaxhighlight lang="html5">
<head>
<style type="text/css">
.logo-fhem {
background: url(https://wiki.fhem.de/fhemlogo.png) no-repeat;
width: 120px;
height: 132px;
background-size: contain;
}
</style>
</head>
<body>
<div data-type="symbol" data-icon="logo-fhem"></div>
</body>
</syntaxhighlight>

== Widgets ==
===Allgemeine Attribute===
Jedes Widget kann über verschiedene Attribute konfiguriert werden. Folgende Attribute gelten für alle Widgets:

{| class="wikitable"
|+allgemeine Attribute
|-
!align="right" |data-type
|Widget-Typ
|-
!align="right" |data-device
|FHEM-Name des Gerätes (mit dem Befehl 'list' bekommt man im FHEM die kpl. Liste)
|-
!align="right" |class
|CSS-Klassen für Aussehen und Formatierung des Widgets
|-
|}

{| class="wikitable"
|+Daten Empfangen
|-
!align="right" |data-get
|Reading Name
|-
!align="right" |data-get-on
|Wert für den Status on
|-
!align="right" |data-get-off
|Wert für den Status off
|-
|}

{| class="wikitable"
|+Daten Senden
|-
!align="right" |data-set
|Reading Name
|-
!align="right" |data-set-on
|Wert für den Status on
|-
!align="right" |data-set-off
|Wert für den Status off
|-
|}

Widget-spezifische Attribute können auf der jeweiligen Widget-Seite nachgelesen werden.

=== Integrierte Widgets ===
Folgende Widgets sind direkt in FHEM Tablet UI integriert und können "out of the box" verwendet werden.

* [[FTUI Widget Button|button]]: Variante der push und switch Widgets, die entweder einen URL ansteuern oder einen FHEM-Befehl absetzen kann
* [[FTUI Widget Checkbox|checkbox]]: Umschalter zwischen zwei definierten Zuständen
* [[FTUI Widget Circlemenu|circlemenu]]: Mehrere Widgets hinter einem Widget verborgen, trotz des 'circle' im Namen kann das Menue jetzt auch horizontal oder vertikal ausgeklappt werden
* [[FTUI Widget Clock|clock]]: Stellt eine einfach Uhr zur Verfügung
* [[FTUI Widget Colorwheel|colorwheel]]: Farbpalette zur Auswahl von Farben
* [[FTUI Widget Controlbutton|controlbutton]]: iOS-ähnlicher Button zum Schalten zwischen zwei Zuständen (z.B. on / off)
* [[FTUI Widget Controller|controller]]: iOS-ähnlicher vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Datetimepicker|datetimepicker]]: Erstellt eine Auswahl für Datum/Uhrzeit
* [[FTUI Widget Departure|departure]]: Abfahrtszeiten öffentlicher Verkehrsmittel
* [[FTUI Widget Dimmer|dimmer]]: Ein-/Aus-Button mit integriertem Schieberegler für z.B. einen Dim-Wert
* [[FTUI Widget Eventmonitor|eventmonitor]]:
* [[FTUI Widget Homestatus|homestatus]]: Auswahl für vier oder fünf definierte Stati eines Objects (z.B.: FHEM Residents)
* [[FTUI Widget Html|html]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/iframe iframe]: Widget zum Einbinden externer Inhalte in einem Iframe
* [[FTUI Widget Image|image]]: Zeigt ein Bild, dessen URL fest vorgegeben oder aus einem Device-Reading gelesen werden kann
* [[FTUI Widget Input|input]]: Erstellen eines Texteingabefeldes
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/joinedlabel joinedlabel]: verbindet mehrere Readings zu einem Feld
* [[FTUI Widget Klimatrend|klimatrend]]: wandelt Daten aus dem statistics-Modul in einen Pfeil um, der den aktuellen Trend anzeigt
* [[FTUI Widget Knob|knob]]: Erstellt einen Statusbalken auf einer Kreisbahn
* [[FTUI Widget Label|label]]: Reading als Text anzeigen
* [[FTUI Widget Level|level]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI Widget Link|link]]: Erstellt einen Link oder Button zum Aufrufen von URLs oder Senden von Befehlen an FHEM
* [[FTUI Widget Medialist|medialist]]:
* [[FTUI Widget Multistatebutton|multistatebutton]]: Variante des push-Widgets, welches den set-Befehl abhängig vom gelesenen Status ändert
* [[FTUI Widget Notify|notify]]: Blendet ein Hinweisfenster im Browser ein
* [[FTUI Widget Pagebutton|pagebutton]]: Button, mit dem auf andere Seiten gesprungen werden kann. Eignet sich gut für eine Navigation
* [[FTUI Widget Pagetab|pagetab]]: Tauscht den Inhalt einer Seite durch den einer anderen. Eignet sich gut für ein Navigationsmenü
* [[FTUI Widget Playstream|playstream]]: Abspielen eines Webradio-Streams per Button
* [[FTUI Widget Popup|popup]]: Öffnet ein Popup nach einem Klick auf ein Widget oder HTML-Element
* [[FTUI Widget Progress|progress]]: Zeigt einen Prozentwert in Form einer runden Fortschrittsleiste
* [[FTUI_Widget_Push|push]]: Button, mir dem ein Befehl an FHEM gesendet werden kann
* [[FTUI Widget Range|range]]: Erstellt vertikale Balken, die einen Wertebereich in unterschiedlichen Farben darstellen
* [[FTUI Widget Readingsgroup|readingsgroup]]: Zeigt eine Readingsgroup an, wie sie in FHEM definiert wurde
* [[FTUI Widget Rotor|rotor]]: Animiertes Umschalten von zwei oder mehr Widgets an einer Position
* [[FTUI Widget Scale|scale]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI_Widget_Select|select]]: Combobox, die eine Liste an Werten zur Auswahl anzeigt
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/settimer settimer]: Zum Anzeigen und Einstellen einer Uhrzeit
* [[FTUI Widget Simplechart|simplechart]]: Einfaches XY-Diagramm zur Anzeige eines Wertes, der direkt aus einem FHEM-Logfile gelesen wird
* [[FTUI Widget Slideout|slideout]]:
* [[FTUI Widget Slider|slider]]: Vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Spinner|spinner]]: Element um Werte durch Drücken auf Plus- und Minus- oder Höher-/Tiefer-Icons zu ändern
* [[FTUI Widget Swiper|swiper]]: Bietet die Möglichkeit, durch Wischen zwischen verschiedenen Seiten zu wechseln
* [[FTUI Widget Switch|switch]]: Button um zwischen zwei Zuständen zu schalten (z.B. on / off)
* [[FTUI Widget Symbol|symbol]]: Status eines Devices als Symbol darstellen (z.B. Fenster offen)
* [[FTUI Widget Thermostat|thermostat]]: Anzeige für Heizungsthermostate, mit der die gewünschte Temperatur eingestellt werden kann
* [[FTUI Widget Volume|volume]]: Einstellscheibe zur Änderung eines einzelnen Wertes
* [[FTUI Widget Weather|weather]]: Wettersymbol anzeigen
* [[FTUI Widget WindDirection|wind_direction]]: Anzeige der Windrichtung auf einer Windrose

===3rd Party Widgets===
Für diese Widgets kann nicht sichergestellt werden, dass sie mit der jeweils aktuellen Version von FTUI funktionieren.
* [[FTUI Widget Agenda|agenda]]: Zeigt Kalendereinträge in einer Listenform an
* [[FTUI Widget Calview|calview]]: Zeigt Einträge aus einem [[CALVIEW]]-Device an
* [[FTUI Widget Chart|chart]]: Diagramm mit ähnlichen Möglichkeiten wie die FHEM-Plots
* [[FTUI Widget Classchanger|classchanger]]: Ändert seine CSS-Klassen je nach Status eines Devices
* [[FTUI Widget Clicksound|clicksound]]: Mit dem Widget "clicksound" können Sounds an Click-Events von Elementen gebunden werden.
* [[FTUI Widget Filelog|filelog]]:
* [[FTUI Widget Fullcalview|fullcalview]]:
* [[FTUI Widget Gds|gds]]:
* [https://forum.fhem.de/index.php/topic,78379.msg703359.html#msg703359 gmaps]: Kartendarstellung mit Google Maps API
* [[FTUI Widget Highchart|highchart]]:
* [[FTUI Widget Highchart3d|highchart3d]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/itunes_artwork itunes_artwork]: itunes_artwork durchsucht die iTunes-Datenbank anhand eines Arrays von beliebigen Suchworten nach einem Cover-Artwork und zeigt dieses an.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/javascript javascript]: Ermöglicht die Ausführung beliebigen Javascript-Codes aus einem Reading.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/kodinowplaying kodinowplaying]: zeigt Informationen zu grade in KODI gespielten Medien in Form eines Labels an.
* [[FTUI Widget Loading|loading]]:
* [[FTUI Widget Meteogram|meteogram]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/mpdnowplaying mpdnowplaying]: Zeigt Titelinformationen eines per MPD-Modul angebundenen Music Player Daemon an.
* [https://forum.fhem.de/index.php/topic,79283.msg712855.html#msg712855 pinpad]: Pinpad für z.B. eine Alarmanlage
* [https://forum.fhem.de/index.php/topic,76643.msg685472.html#msg685472 postme]: Liste des PostMe-Devices anzeigen
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/reload reload]: auslösen eine Pagereloads
* [[FTUI Widget Screensaver|screensaver]]:
* [https://forum.fhem.de/index.php/topic,73497.0.html scrolllabel]: Texte in Laufschrift darstellen
* [[FTUI Widget Svgplot|svgplot]]:
* [https://forum.fhem.de/index.php?topic=82883.msg750237#msg750237 todoist]: einfaches widget für todoist
* [[FTUI Widget Tts|tts]]: Sprachausgabe eines Textes aus einem Reading auf dem Endgerät.
* [[FTUI Widget UWZ|uwz]]: Anzeige der Warnungen der Unwetterzentrale
* [[FTUI Widget Wakeup|wakeup]]:
* [https://github.com/svenson08/ftui-weekdaytimer-widget wdtimer]: Visualisierung des [[WeekdayTimer]] Modul
* [[FTUI Widget Weekprofile|weekprofile]]: Visualisierung des [[weekprofile]] Moduls

==Templates==
Kommt ein bestimmtes "Code-Fragment" auf mehreren Seiten oder öfter pro Seite vor, bietet FTUI die Option, Templates zu erstellen. Diese werden einmal gebaut und können dann mit dem Attribut '''data-template''' nach Belieben in eine Seite eingefügt werden. Dabei besteht auch die Möglichkeit, Variablen zu verwenden.

Die Variablennamen sollten möglichst eindeutig und unverwechselbar gewählt werden, da bei der Verwendung von Templates im Prinzip Suchen & Ersetzen angewendet wird. Verwendet man beispielsweise die Variablen '''dev:Thermostat_Kueche''' und '''dev_temp:temperatue''', so kann es passieren, dass die Ergebnisse im erzeugten Code dann '''Thermostat_Kueche''' und '''Thermostat_Kueche_temp''' lauten, statt wie gewünscht '''Thermostat_Kueche''' und '''temperature'''. Um dies zu vermeiden, sollten die Variablen besser '''device:Thermostat_Kueche''' und '''temp:temperatue''' lauten.

Im Folgenden ein paar Beispiele, wie Templates verwendet werden können.

===Einzelnes Widget===
Soll ein Widget an mehreren Stellen in exakt der selben Ausführung eingebunden werden, kann diese Widget in einer eigenen Datei erstellt und diese dann auf den Zielseiten automatisch mitgeladen werden.

;Template-Seite
Die Template-Seite soll in diesem Beispiel ''template_symbol.html'' genannt werden. Diese wird daher zuerst im FTUI-Verzeichnis erstellt.
<syntaxhighlight lang="html">
<div data-type="symbol"
data-device="dummy1">
</syntaxhighlight>

;Haupt-Seite
Die oben erstellte Template-Seite kann nun in jeder gewünschten Seite eingebunden werden.
<syntaxhighlight lang="html" highlight="6">
[...]
<body>
<div class="gridster">
<ul>
<li data-row="1" data-col="1" data-sizey="1" data-sizex="1">
<div data-template="template_symbol.html"></div>
</li>
</ul>
</div>
</body>
[...]
</syntaxhighlight>

===Gridster-Element===
Natürlich kann auch ein ganzes Gridster-Element - in diesem Fall ein Menü - als Template eingebunden werden.
<syntaxhighlight lang="html">
<li data-row="1" data-col="1" data-sizex="1" data-sizey="4" data-template="menu.html"></li>
</syntaxhighlight>

=== Widget-Gruppen ===
Die Template-Datei des [[#Einzelnes Widget|ersten Beispiels]] kann natürlich auch mehrere Widgets auf einmal enthalten.

=== Verwendung von Variablen ===
==== Einfaches Beispiel ====
Oft wird ein und dasselbe Widget für verschiedenen Devices verwendet. Um nicht für jedes Device das Widget neu kopieren zu müssen (bzw. bei Änderungen alle Seiten ausbessern zu müssen), kann ein Template verwendet werden, dem einfach per Parameter mitgeteilt wird, von welchem Device es gerade die Daten empfangen soll.

In diesem Beispiel wird ein Template erzeugt, dass nur die Temperatur verschiedenen Thermostate mittels eines [[FTUI Widget Label|Label-Widgets]] anzeigt.

;Template-Seite
Die Template-Seite enthält nur ein einfaches Label-Widget und wird in diesem Beispiel ''template_label.html'' genannt. Um sie für mehrere Devices verwenden zu können, wird im Attribut '''data-device''' der Name des eigentlichen Devices durch den Parameter '''par01''' ersetzt.
<syntaxhighlight lang="html" highlight="2">
<div data-type="label"
data-device="par01"
data-get="measured-temp"></div>
</syntaxhighlight>

;Haupt-Seite
Auf der Haupt-Seite wird die Template-Seite mit dem Attribut '''data-template''' eingebunden und ihr via Attribut '''data-parameter''' das jeweils gewünschte Device übergeben.
<syntaxhighlight lang="html">
[...]
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat1"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat2"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat3"}'></div>
[...]
</syntaxhighlight>

==== Wetter-Slider mit Template ====
In diesem Beispiel wird ein [[FTUI Widget Slider|Slider-Widget]] erstellt, welches die verschiedenen Tage eines Wetterberichtes anzeigt. Dabei wird für den Wetterbericht des jeweiligen Tages immer dasselbe Template verwendet um nicht für jeden Tag ein eigenes Widget schreiben zu müssen.

;Template-Seite
<syntaxhighlight lang="html">
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par01" data-unit="°C"></div>
<div class="inline">
<div data-type="label" data-device="AgroWeather" data-get="par02"></div>
<div data-type="weather" data-device="AgroWeather" data-get="par02"></div>
min: <div data-type="label" data-device="AgroWeather" data-get="par03" data-unit="°C"></div>
</div>
</div>
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().eeee()+','"></div>
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().ddmm()"></div>
</div>
</syntaxhighlight>

;Haupt-Seite
In der Haupt-Seite wird das Template dann für jede Slider-Seite eingebunden und das Reading für den jeweiligen Tag via Parameter übergeben.
<syntaxhighlight lang="html">
[...]
<div data-type="swiper">
<ul>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc0_tempMax","par02":"fc0_weatherDay","par03":"fc0_tempMin","par04":"fc0_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc1_tempMax","par02":"fc1_weatherDay","par03":"fc1_tempMin","par04":"fc1_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc2_tempMax","par02":"fc2_weatherDay","par03":"fc2_tempMin","par04":"fc2_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc3_tempMax","par02":"fc3_weatherDay","par03":"fc3_tempMin","par04":"fc3_date"}'></li>
</ul>
</div>
[...]
</syntaxhighlight>

== JavaScript-Funktionen ==
Neben den Widgets können auch einige JavaScript-Funktionen verwendet werden, um Befehle an FHEM zu senden.

Folgende Zeile setzt einen direkten Befehl an FHEM ab (<code>set dummy1 off</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('set dummy1 off')">Dummy1 aus</div></syntaxhighlight>

Diese Zeile veranlasst FHEM dazu, eine Funktion aus der 99_myUtils.pm auszuführen (<code>myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('{myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")}')">+</div></syntaxhighlight>

Ein Beispiel, wie ein Kommando an FHEM gesendet wird und gleichzeitig der Wert eines bereits in FTUI angezeigten Readings verwendet werden kann:
<syntaxhighlight lang="html">
<div data-type="label" data-device="dummy1" data-get="temperature"></div>
<div onClick="ftui.setFhemStatus('set dummy2 '+ftui.getDeviceParameter('dummy1','temperature').val);">Senden</div>
</syntaxhighlight>

== Eigene Widgets erstellen ==
Wie eigenen Widgets für FTUI erstellt werden können, ist auf der Seite [[FTUI eigene Widgets]] beschrieben.

== FAQ ==
Häufig gestellte Fragen zum FHEM Tablet UI sind in der [[FHEM Tablet UI FAQ]] zusammengestellt.

== Links ==
* [https://github.com/knowthelist/fhem-tablet-ui Projekt auf Github]
* {{Link2Forum|Topic=34233|LinkText=Forums-Beitrag}}
* [[FTUI_Snippets|Snippets]]
* [http://knowthelist.github.io/fhem/tablet/demo_widgets.html Live-Demos]
* [https://waschto.eu/fhem-und-tabletui-livedemo/ FHEM und TabletUI Live-Demo]
* {{Link2Forum|Topic=37378|LinkText=User-Demos}}
* [https://github.com/ovibox/fhem-ftui-user-demos Download der User-Demo-Dateien]

[[Kategorie:FHEM Tablet UI]]

FTUI eigene Widgets

2017-12-29T21:38:08Z

Pula:

Eigene Widgets für [[FHEM Tablet UI]] zu erstellen ist relativ einfach. Dafür muss nur eine widget_mywidget.js im js-Folder neben den anderen Widgets angelegt werden.

Eine Minimalvariante einer widget_mywidget.js-Datei könnte so aussehen:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {
alert('init called');
}

function update(device, reading) {
alert('update called for' + device + ':' + reading );
}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Am Ende der Datei steht die Definition der Public-Parameter. Neben dem Namen müssen mindestens die beiden Funktionen '''init()''' und '''update()''' implementiert sein.

'''init()''' wird einmal gleich nach dem Laden des Plugins aufgerufen, '''update()''' jedesmal, wenn Änderungen von Readings passieren.

Dieses FTUI-Plugin kann man jetzt so einbinden:

<syntaxhighlight lang="html">
<div data-type="mywidget"></div>
</syntaxhighlight>

Wenn das Plugin für ein UI-Control sein soll, das mehrfach auf der Seite vorkommt, kann man im '''init()''' per '''each()''' durch alle Elemente iterieren:

<syntaxhighlight lang="javascript">
function init() {
me.elements = $('[data-type="' + me.widgetname + '"]');
me.elements.each(function (index) {
alert('init #' + index + ' called');
});
}
</syntaxhighlight>

Wenn ein Plugin Daten abrufen soll, die NICHT in einem Reading von FHEM enthalten sind, empfiehlt es sich, eine Klasse zu definieren:

<syntaxhighlight lang="html">
<div class="neueklasse" data-type="blabla" data-device='test-device' data-get='neueklasse'>}
</syntaxhighlight>

Im JS kann man dann so diese Elemente auswählen bzw ihnen etwas zuweisen:
<syntaxhighlight lang="javascript">
if (elem.is('.neueklasse')) {
elem.html(text);
}
</syntaxhighlight>

Nicht vergessen: Wenn hier Daten aus Readings abgefragt werden sollen, müssen diese Readings in init() abonniert werden:
<syntaxhighlight lang="javascript">
elem.initData('reading123', 'testreading');
me.addReading(elem, 'reading123');
</syntaxhighlight>

Und dann in der Update-Routine muss auf diese Readings geprüft werden:
<syntaxhighlight lang="javascript">
me.elements.filterDeviceReading('reading123', dev, par)
.add(me.elements.filterDeviceReading('testreading', dev, par))
</syntaxhighlight>
Nur dann werden die Elemente bei Updates aus fhem auch aktualisiert.

Ausserdem empfiehlt es sich natürlich in fhem bei den betroffenen Devices ein

<syntaxhighlight>
attr device event-on-change-reading .*
</syntaxhighlight>

zu machen!

Updates werden aber nur gerufen, wenn man die entsprechenden Readings beim '''init()''' abonniert. Das passiert mit '''addReading();''' (Funktion ist enthalten im Base-Widget: Modul_widget)

In diesem Beispiel fügen wir das Reading hinzu, das im Attribut '''data-get''' angegeben ist. Wir legen gleich noch als Default das Reading 'STATE' fest, für den Fall, dass data-get im HTML Code fehlt. Das passiert mit '''elem.initData();'''

<syntaxhighlight lang="javascript">
function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}
</syntaxhighlight>

Dann können wir unter '''update()''' auf die Notifizierungen warten. Wir filtern mit '''elements.filterDeviceReading()''' die Elemente heraus, die unter '''data-get''' das aktualisierte Reading haben und holen mit '''elem.getReading().val''' den aktuell bekannten Wert aus dem lokalen Cache.

'''elem.getReading().date''' würde den Zeitstempel des Readings liefern.

<syntaxhighlight lang="javascript">
function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});
}
</syntaxhighlight>

Zusammengefasst sieht unser FTUI Plugin jetzt so aus:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}

function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});

}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Im HTML würde man das jetzt so nutzen können.

<syntaxhighlight lang="html">
<div data-type="mywidget" data-device='AvReceiver' data-get='volume'></div>
</syntaxhighlight>

[[Kategorie:FHEM Tablet UI]]

FTUI eigene Widgets

2017-12-29T21:36:37Z

Pula:

Eigene Widgets für [[FHEM Tablet UI]] zu erstellen ist relativ einfach. Dafür muss nur eine widget_mywidget.js im js-Folder neben den anderen Widgets angelegt werden.

Eine Minimalvariante einer widget_mywidget.js-Datei könnte so aussehen:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {
alert('init called');
}

function update(device, reading) {
alert('update called for' + device + ':' + reading );
}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Am Ende der Datei steht die Definition der Public-Parameter. Neben dem Namen müssen mindestens die beiden Funktionen '''init()''' und '''update()''' implementiert sein.

'''init()''' wird einmal gleich nach dem Laden des Plugins aufgerufen, '''update()''' jedesmal, wenn Änderungen von Readings passieren.

Dieses FTUI-Plugin kann man jetzt so einbinden:

<syntaxhighlight lang="html">
<div data-type="mywidget"></div>
</syntaxhighlight>

Wenn das Plugin für ein UI-Control sein soll, das mehrfach auf der Seite vorkommt, kann man im '''init()''' per '''each()''' durch alle Elemente iterieren:

<syntaxhighlight lang="javascript">
function init() {
me.elements = $('[data-type="' + me.widgetname + '"]');
me.elements.each(function (index) {
alert('init #' + index + ' called');
});
}
</syntaxhighlight>

Wenn ein Plugin Daten abrufen soll, die NICHT in einem Reading von FHEM enthalten sind, empfiehlt es sich, eine Klasse zu definieren:

<syntaxhighlight lang="html">
<div class="neueklasse" data-type="blabla" data-device='test-device' data-get='neueklasse'>}
</syntaxhighlight>

Im JS kann man dann so diese Elemente auswählen bzw ihnen etwas zuweisen:
<syntaxhighlight lang="javascript">
if (elem.is('.neueklasse')) {
elem.html(text);
}
</syntaxhighlight>

Nicht vergessen: Wenn hier Daten aus Readings abgefragt werden sollen, müssen diese Readings in init() abonniert werden:
<syntaxhighlight lang="javascript">
elem.initData('reading123', 'testreading');
me.addReading(elem, 'reading123');
</syntaxhighlight>

Und dann in der Update-Routine muss auf diese Readings geprüft werden:
<syntaxhighlight lang="javascript">
me.elements.filterDeviceReading('reading123', dev, par)
.add(me.elements.filterDeviceReading('testreading', dev, par))
</syntaxhighlight>
Nur dann werden die Elemente bei Updates aus fhem auch aktualisiert.

Ausserdem empfiehlt es sich natürlich in fhem bei den betroffenen Devices ein

event-on-change-reading .*

zu machen ;-)

Updates werden aber nur gerufen, wenn man die entsprechenden Readings beim '''init()''' abonniert. Das passiert mit '''addReading();''' (Funktion ist enthalten im Base-Widget: Modul_widget)

In diesem Beispiel fügen wir das Reading hinzu, das im Attribut '''data-get''' angegeben ist. Wir legen gleich noch als Default das Reading 'STATE' fest, für den Fall, dass data-get im HTML Code fehlt. Das passiert mit '''elem.initData();'''

<syntaxhighlight lang="javascript">
function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}
</syntaxhighlight>

Dann können wir unter '''update()''' auf die Notifizierungen warten. Wir filtern mit '''elements.filterDeviceReading()''' die Elemente heraus, die unter '''data-get''' das aktualisierte Reading haben und holen mit '''elem.getReading().val''' den aktuell bekannten Wert aus dem lokalen Cache.

'''elem.getReading().date''' würde den Zeitstempel des Readings liefern.

<syntaxhighlight lang="javascript">
function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});
}
</syntaxhighlight>

Zusammengefasst sieht unser FTUI Plugin jetzt so aus:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}

function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});

}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Im HTML würde man das jetzt so nutzen können.

<syntaxhighlight lang="html">
<div data-type="mywidget" data-device='AvReceiver' data-get='volume'></div>
</syntaxhighlight>

[[Kategorie:FHEM Tablet UI]]

FTUI eigene Widgets

2017-12-29T21:35:29Z

Pula:

Eigene Widgets für [[FHEM Tablet UI]] zu erstellen ist relativ einfach. Dafür muss nur eine widget_mywidget.js im js-Folder neben den anderen Widgets angelegt werden.

Eine Minimalvariante einer widget_mywidget.js-Datei könnte so aussehen:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {
alert('init called');
}

function update(device, reading) {
alert('update called for' + device + ':' + reading );
}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Am Ende der Datei steht die Definition der Public-Parameter. Neben dem Namen müssen mindestens die beiden Funktionen '''init()''' und '''update()''' implementiert sein.

'''init()''' wird einmal gleich nach dem Laden des Plugins aufgerufen, '''update()''' jedesmal, wenn Änderungen von Readings passieren.

Dieses FTUI-Plugin kann man jetzt so einbinden:

<syntaxhighlight lang="html">
<div data-type="mywidget"></div>
</syntaxhighlight>

Wenn das Plugin für ein UI-Control sein soll, das mehrfach auf der Seite vorkommt, kann man im '''init()''' per '''each()''' durch alle Elemente iterieren:

<syntaxhighlight lang="javascript">
function init() {
me.elements = $('[data-type="' + me.widgetname + '"]');
me.elements.each(function (index) {
alert('init #' + index + ' called');
});
}
</syntaxhighlight>

Wenn ein Plugin Daten abrufen soll, die NICHT in einem Reading von FHEM enthalten sind, empfiehlt es sich, eine Klasse zu definieren:

<syntaxhighlight lang="html">
<div class="neueklasse" data-type="blabla" data-device='wzcore' data-get='cm'>}
</syntaxhighlight>

Im JS kann man dann so diese Elemente auswählen bzw ihnen etwas zuweisen:
<syntaxhighlight lang="javascript">
if (elem.is('.neueklasse')) {
elem.html(text);
}
</syntaxhighlight>

Nicht vergessen: Wenn hier Daten aus Readings abgefragt werden sollen, müssen diese Readings in init() abonniert werden:
<syntaxhighlight lang="javascript">
elem.initData('reading123', 'testreading');
me.addReading(elem, 'reading123');
</syntaxhighlight>

Und dann in der Update-Routine muss auf diese Readings geprüft werden:
<syntaxhighlight lang="javascript">
me.elements.filterDeviceReading('reading123', dev, par)
.add(me.elements.filterDeviceReading('testreading', dev, par))
</syntaxhighlight>
Nur dann werden die Elemente bei Updates aus fhem auch aktualisiert.

Ausserdem empfiehlt es sich natürlich in fhem bei den betroffenen Devices ein

event-on-change-reading .*

zu machen ;-)

Updates werden aber nur gerufen, wenn man die entsprechenden Readings beim '''init()''' abonniert. Das passiert mit '''addReading();''' (Funktion ist enthalten im Base-Widget: Modul_widget)

In diesem Beispiel fügen wir das Reading hinzu, das im Attribut '''data-get''' angegeben ist. Wir legen gleich noch als Default das Reading 'STATE' fest, für den Fall, dass data-get im HTML Code fehlt. Das passiert mit '''elem.initData();'''

<syntaxhighlight lang="javascript">
function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}
</syntaxhighlight>

Dann können wir unter '''update()''' auf die Notifizierungen warten. Wir filtern mit '''elements.filterDeviceReading()''' die Elemente heraus, die unter '''data-get''' das aktualisierte Reading haben und holen mit '''elem.getReading().val''' den aktuell bekannten Wert aus dem lokalen Cache.

'''elem.getReading().date''' würde den Zeitstempel des Readings liefern.

<syntaxhighlight lang="javascript">
function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});
}
</syntaxhighlight>

Zusammengefasst sieht unser FTUI Plugin jetzt so aus:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}

function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});

}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Im HTML würde man das jetzt so nutzen können.

<syntaxhighlight lang="html">
<div data-type="mywidget" data-device='AvReceiver' data-get='volume'></div>
</syntaxhighlight>

[[Kategorie:FHEM Tablet UI]]

FTUI eigene Widgets

2017-12-29T21:31:15Z

Pula:

Eigene Widgets für [[FHEM Tablet UI]] zu erstellen ist relativ einfach. Dafür muss nur eine widget_mywidget.js im js-Folder neben den anderen Widgets angelegt werden.

Eine Minimalvariante einer widget_mywidget.js-Datei könnte so aussehen:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {
alert('init called');
}

function update(device, reading) {
alert('update called for' + device + ':' + reading );
}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Am Ende der Datei steht die Definition der Public-Parameter. Neben dem Namen müssen mindestens die beiden Funktionen '''init()''' und '''update()''' implementiert sein.

'''init()''' wird einmal gleich nach dem Laden des Plugins aufgerufen, '''update()''' jedesmal, wenn Änderungen von Readings passieren.

Dieses FTUI-Plugin kann man jetzt so einbinden:

<syntaxhighlight lang="html">
<div data-type="mywidget"></div>
</syntaxhighlight>

Wenn das Plugin für ein UI-Control sein soll, das mehrfach auf der Seite vorkommt, kann man im '''init()''' per '''each()''' durch alle Elemente iterieren:

<syntaxhighlight lang="javascript">
function init() {
me.elements = $('[data-type="' + me.widgetname + '"]');
me.elements.each(function (index) {
alert('init #' + index + ' called');
});
}
</syntaxhighlight>

Wenn ein Plugin Daten abrufen soll, die NICHT in einem Reading von FHEM enthalten sind, empfiehlt es sich, eine Klasse zu definieren:

<syntaxhighlight lang="html">
<div class="neueklasse" data-type="blabla" data-device='wzcore' data-get='cm'>}
</syntaxhighlight>

Im JS kann man dann so diese Elemente auswählen bzw ihnen etwas zuweisen:
<syntaxhighlight lang="javascript">
if (elem.is('.neueklasse')) {
elem.html(text);
}
</syntaxhighlight>

Nicht vergessen: Wenn hier Daten aus Readings abgefragt werden sollen, müssen diese Readings in init() abonniert werden:
<syntaxhighlight lang="javascript">
elem.initData('reading123', 'testreading');
me.addReading(elem, 'reading123');
</syntaxhighlight>

Updates werden aber nur gerufen, wenn man die entsprechenden Readings beim '''init()''' abonniert. Das passiert mit '''addReading();''' (Funktion ist enthalten im Base-Widget: Modul_widget)

In diesem Beispiel fügen wir das Reading hinzu, das im Attribut '''data-get''' angegeben ist. Wir legen gleich noch als Default das Reading 'STATE' fest, für den Fall, dass data-get im HTML Code fehlt. Das passiert mit '''elem.initData();'''

<syntaxhighlight lang="javascript">
function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}
</syntaxhighlight>

Dann können wir unter '''update()''' auf die Notifizierungen warten. Wir filtern mit '''elements.filterDeviceReading()''' die Elemente heraus, die unter '''data-get''' das aktualisierte Reading haben und holen mit '''elem.getReading().val''' den aktuell bekannten Wert aus dem lokalen Cache.

'''elem.getReading().date''' würde den Zeitstempel des Readings liefern.

<syntaxhighlight lang="javascript">
function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});
}
</syntaxhighlight>

Zusammengefasst sieht unser FTUI Plugin jetzt so aus:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}

function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});

}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Im HTML würde man das jetzt so nutzen können.

<syntaxhighlight lang="html">
<div data-type="mywidget" data-device='AvReceiver' data-get='volume'></div>
</syntaxhighlight>

[[Kategorie:FHEM Tablet UI]]

FTUI eigene Widgets

2017-12-29T21:28:05Z

Pula:

Eigene Widgets für [[FHEM Tablet UI]] zu erstellen ist relativ einfach. Dafür muss nur eine widget_mywidget.js im js-Folder neben den anderen Widgets angelegt werden.

Eine Minimalvariante einer widget_mywidget.js-Datei könnte so aussehen:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {
alert('init called');
}

function update(device, reading) {
alert('update called for' + device + ':' + reading );
}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Am Ende der Datei steht die Definition der Public-Parameter. Neben dem Namen müssen mindestens die beiden Funktionen '''init()''' und '''update()''' implementiert sein.

'''init()''' wird einmal gleich nach dem Laden des Plugins aufgerufen, '''update()''' jedesmal, wenn Änderungen von Readings passieren.

Dieses FTUI-Plugin kann man jetzt so einbinden:

<syntaxhighlight lang="html">
<div data-type="mywidget"></div>
</syntaxhighlight>

Wenn das Plugin für ein UI-Control sein soll, das mehrfach auf der Seite vorkommt, kann man im '''init()''' per '''each()''' durch alle Elemente iterieren:

<syntaxhighlight lang="javascript">
function init() {
me.elements = $('[data-type="' + me.widgetname + '"]');
me.elements.each(function (index) {
alert('init #' + index + ' called');
});
}
</syntaxhighlight>

Wenn ein Plugin Daten abrufen soll, die NICHT in einem Reading von FHEM enthalten sind, empfiehlt es sich, eine Klasse zu definieren:

<syntaxhighlight lang="html">
<div class="neueklasse" data-type="blabla" data-device='wzcore' data-get='cm'>}
</syntaxhighlight>

Im JS kann man dann so diese Elemente auswählen bzw ihnen etwas zuweisen:
<syntaxhighlight lang="javascript">
if (elem.is('.neueklasse')) {
elem.html(text);
}
</syntaxhighlight>

Updates werden aber nur gerufen, wenn man die entsprechenden Readings beim '''init()''' abonniert. Das passiert mit '''addReading();''' (Funktion ist enthalten im Base-Widget: Modul_widget)

In diesem Beispiel fügen wir das Reading hinzu, das im Attribut '''data-get''' angegeben ist. Wir legen gleich noch als Default das Reading 'STATE' fest, für den Fall, dass data-get im HTML Code fehlt. Das passiert mit '''elem.initData();'''

<syntaxhighlight lang="javascript">
function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}
</syntaxhighlight>

Dann können wir unter '''update()''' auf die Notifizierungen warten. Wir filtern mit '''elements.filterDeviceReading()''' die Elemente heraus, die unter '''data-get''' das aktualisierte Reading haben und holen mit '''elem.getReading().val''' den aktuell bekannten Wert aus dem lokalen Cache.

'''elem.getReading().date''' würde den Zeitstempel des Readings liefern.

<syntaxhighlight lang="javascript">
function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});
}
</syntaxhighlight>

Zusammengefasst sieht unser FTUI Plugin jetzt so aus:

<syntaxhighlight lang="javascript">
var Modul_mywidget = function () {

function init() {

me.elements = $('div[data-type="' + me.widgetname + '"]', me.area);
me.elements.each(function (index) {

var elem = $(this);
elem.initData('get', 'STATE');

me.addReading(elem, 'get');
});
}

function update(device, reading) {
me.elements.filterDeviceReading('get', device, reading)
.each(function (index) {
var elem = $(this);
var value = elem.getReading('get').val;
if (value) {
elem.html(value);
}
});

}

var me = $.extend(new Modul_widget(), {
widgetname: 'mywidget',
init: init,
update: update,
});

return me;
};
</syntaxhighlight>

Im HTML würde man das jetzt so nutzen können.

<syntaxhighlight lang="html">
<div data-type="mywidget" data-device='AvReceiver' data-get='volume'></div>
</syntaxhighlight>

[[Kategorie:FHEM Tablet UI]]

CsrfToken-HowTo

2017-03-07T19:42:37Z

Pula: python-routinen eingebaut

{{SEITENTITEL:csrfToken-HowTo}}
FHEM hat mit der Version 5.8 eine Sicherheitsmaßnahme scharfgeschaltet, den csrfToken.
Dieser Token wird bei jedem Neustart von FHEM neu gebildet.

Dieses Feature erhöht die Sicherheit, führt aber dazu, dass man nicht mehr mit einem einfachen http Link auf das FHEMWEB zugreifen kann.

==Einzeiler==

Was früher so ging:

<nowiki>http://localhost:8083/fhem?cmd=set%20Office%20on</nowiki>

muss jetzt etwas ergänzt werden. Mit dem Einzeiler

<nowiki>curl -s -D - 'http://localhost:8083/fhem?XHR=1' | awk '/X-FHEM-csrfToken/{print $2}'</nowiki>

kann man den aktuellle csrfToken aus dem Header extrahieren und muss ihn nur noch an den Aufruf anhängen.
Erste Variante:

<nowiki>curl --data-raw "fwcsrf=$(curl -s -D - 'http://localhost:8083/fhem?XHR=1' | awk '/X-FHEM-csrfToken/{print $2}')" http://localhost:8083/fhem?cmd=set%20Office%20on</nowiki>

Zweite Variante, in dieser wird cr+lf am Ende des ermittelten csrfTokens abgeschnitten:

<nowiki>curl "http://fhem.example.org:8083/fhem?cmd=set%20Office%20on?XHR=1&fwcsrf="`curl -s -D - 'http://fhem.example.org:8083/fhem?XHR=1' | awk '/X-FHEM-csrfToken/{print $2}' | tr -d "\r\n"`</nowiki>

Man kann auch in Scripten den token zunächst abspeichern:

<nowiki>token=$(curl -s -D - 'http://localhost:8083/fhem?XHR=1' | awk '/X-FHEM-csrfToken/{print $2}')
curl --data-raw "fwcsrf=$token" http://localhost:8083/fhem?cmd=set%20Office%20on</nowiki>

==API Web==
Falls man ohne den Token arbeiten will, könnte man ein eigenes API Web erstellen und den Zugriff darauf beschränken. In vorhandenen Scripten / Applikationen müsste dann lediglich der Port geändert werden.

define WEBapi FHEMWEB 8088 global
attr WEBapi csrfToken none
attr WEBapi allowFrom 192.168.178.83|127.0.0.1

Im Forum ist ganz gut beschrieben wie man die Gestaltung des regEx für die IP Adresse machen kann -> Links

==csrfToken festlegen==
Dies kann man tun, falls die dynamische Abfrage zur Laufzeit des Tokens nicht möglich ist.

attr WEB.* csrfToken <beliebige Folge aus Zeichen und Zahlen>

Damit können feste URLs verwendet werden:

<nowiki>http://localhost:8083/fhem?cmd=set%20Office%20on&fwcsrf=<fester token></nowiki>

==csrfToken abschalten==
Dies sollte man als erste Hilfe tun, aber unbedingt darüber nachdenken wie man die Applikation umstellt.

attr WEB.* csrfToken none

==Featurelevel==
Eine weitere temporäre Notfallmaßnahme wäre den Featurelevel nach dem Update einfach wieder zurückzudrehen

attr global featurelevel 5.7

==Python==
Falls mal jemand aus python (hier für python 2.7) heraus fhem ansteuern möchte

<nowiki>import sys
import urllib2
import urllib
import ssl
import urlparse
BASEURL = 'https://user:password@server_ip:8083/fhem?'
url = BASEURL + 'cmd=set+licht+on'
def get_token(url):
nurl = urlparse.urlsplit(url)
username = nurl.username
password = nurl.password
url = url.replace(username + ':' + password + '@', '')
url = url.replace(" ", "%20")
ssl._create_default_https_context = ssl._create_unverified_context
p = urllib2.HTTPPasswordMgrWithDefaultRealm()
p.add_password(None, url, username, password)
handler = urllib2.HTTPBasicAuthHandler(p)
opener = urllib2.build_opener(handler)
urllib2.install_opener(opener)
try:
uu = urllib2.urlopen(
url=url,
data=None,
timeout=10
)
token = uu.read()
token = token[token.find('csrf_'):]
token = token[:token.find("\'")]
return token
except urllib2.URLError, urllib2.URLError.reason:
print('URLError: %s' % urllib2.URLError.reason)
return False

def fire_command(url):
# type: (object) -> object
if "@" in url:
token = get_token(BASEURL)
data = {'fwcsrf': token}
data = urllib.urlencode(data)
nurl = urlparse.urlsplit(url)
username = nurl.username
password = nurl.password
url = url.replace(username + ':' + password + '@', '')
url = url.replace(" ", "%20")
ssl._create_default_https_context = ssl._create_unverified_context
p = urllib2.HTTPPasswordMgrWithDefaultRealm()
p.add_password(None, url, username, password)
handler = urllib2.HTTPBasicAuthHandler(p)
opener = urllib2.build_opener(handler)
urllib2.install_opener(opener)
try:
urllib2.urlopen(
url=url,
data=data,
timeout=10
)
except urllib2.URLError, urllib2.URLError.reason:
print('URLError: %s' % urllib2.URLError.reason)
return False</nowiki>

==Links==
* https://forum.fhem.de/index.php?topic=23994.0
* [https://de.wikipedia.org/wiki/Cross-Site-Request-Forgery Wikipedia - Cross Site Request Forgery (csrf)]

WifiLight

2015-11-06T20:47:18Z

Pula: /* HSV */

{{Infobox Modul
|ModPurpose=Steuern von LEDs / Stripes mit Hilfe eines WLAN LED Moduls
|ModType=x


|ModForumArea=Sonstige Systeme
|ModTechName=32_WifiLight.pm
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}



FHEM Modul zum steuern diverser LED Leuchtmittel über WLAN wie Mi-Light, Limitless, IVY, sengled, LW12, LED Streifen, 2,4GHz E27 RGB Lampen ...

=== Basic Syntax ===
==== Definition ====
:<code>define <name> WifiLight <Leuchtmitteltyp> <bridgetyp>:<IP|FQDN></code>
''Für die Milight Typen die Gruppen unterstützen werden die Gruppen in der Reihenfolge der Definition automatisch erstellt.''

==== on / off ====
:<code>set <name> on|off</code>
''"on" schaltet weißes Licht mit 100% ein. (Ausnahme Milight/RGB(old) da dort kein weiß unterstützt wird: 100% rot)''

Erweiterte Parameter:
* ramp

==== dim ====
:<code>set <name> dim level</code>
''"dim" behält die aktuell gesetzte Farbe bei und so kann "dim 100" anstelle von "on" verwendet werden wenn die aktuelle Lichtfarbe beibehalten werden soll.''

erweiterte Parameter:
* ramp
* queue

==== HSV ====
:<code>set <name> HSV H,S,V</code>
''Farbangaben im Farbraum "HSV" sind vollständig und in der Regel intuitiver als RGB. H (HUE: 0..360) gibt die Grundfarbe in einem Farbkreis (Regenbogen) an. Rot liegt bei 0°, Grün bei 120° und blau bei 240°. S (Saturation/Sättigung: 0..100) steht für die Sättigung der Farbe. Eine Sättigung von 100 bedeutet die Farbe ist "rein" oder komplett gesättigt. Blau zum Beispiel mit 100% Sättigung entspricht RGB #0000FF. V (Value: 0..100) gibt die Helligkeit an. Ein V von 50 heist: "halbe Helligkeit"''

erweiterte Parameter:
* ramp
* queue
* direction
* event

<code>ramp</code>
Dieser Parameter steuert einen weichen Übergang zwischen zwei Zuständen und wird in Sekunden angegeben.

Beispiel:

<code>set <name> on</code> : schaltet die LED sofort an.

<code>set <name> on 20</code> : Die LED wird über einen Zeitraum von 20 Sekunden weich hoch-gedimmt.

<code>queue</code>
Angenommen das Modul arbeitet gerade intern eine Transition, also dem weichen Übergang zu einem anderen Zustand (siehe ramp), ab. Der user setzt während der Transition einen weiteren Befehl für die LED ab.

Ohne den Parameter "q" wird die laufende Transition sofort unterbrochen und der neue Befehl wird ausgeführt.
Mit dem Parameter "q" wird der neue Befehl in eine interne Queue geschrieben und erst bearbeitet nachdem die laufende Transition, und alle vorher in die Queue geschriebenen Befehle, abgearbeitet wurden.

Dadurch wird es möglich das mit einem Befehl mehrere ganz unterschiedliche Farb- oder Helligkeitswechsel an das modul übergibt die dann nacheinander abgearbeitet werden.

<code>direction</code>
Im HSV Farbraum entsprechen die Farben einem Winkel (0° Rot, 120° Grün, 240° Blau). Der weiche Übergang von einer Farbe zu einer anderen wird Standardmäßig auf dem "kürzesten Weg" durchlaufen. Der Wechsel von Grün auf Rot sieht also so aus: 120°, 119°, 118°, ... 2°, 1°, 0°. Das entspricht der default direction "s" für "short" - dem kürzesten Weg.

Mit dem Flag "l" für "long" (langer Weg) wird die gleiche Transition jetzt mit dem "Umweg" über Blau ausgeführt, also so: 120°, 121°, 122°, ... 358°, 359°, 360° ( = 0°).

==== RGB ====
:<code>set <name> RGB RRGGBB</code>
''RGB Angaben werden im 6 stelligen Hexadezimalen Format erwartet.''

erweiterte Parameter:
* ramp
* queue
* direction
* event

===== Unterschiede von Farbangaben HSV zu RGB =====
Angenommen das Ziel ist ein Farbverlauf Rot (ganz dunkel, Helligkeit 0) auf Blau sowie ein Farbverlauf von Grün (ebenfalls 0) auf Blau. Im RGB Farbraum starten beide Farbverläufe bei #000000 auf gehen dann auf #0000FF. Damit lassen sie sich nicht unterscheiden und anders als erwartet beginnt der Farbverlauf in beiden Fällen mit einem neutralen "Grau" (RGB #010101). Die entsprechende Beschreibung im HSV Farbraumraum ist hingegen eindeutig (120,100,0 -> 240,100,100 für GRÜN 0% auf BLAU 100%) und funktioniert wie erwartet.

==== Erweiterte Funktionen / Transitions ====
Das Modul unterstützt komplexe programmierbare Farbverläufe. Da diese im Modul berechnet werden hängt die flüssige Wiedergabe von einer ganzen Reihe von Faktoren ab:
* FHEM Host Hardware
* FHEM Auslastung und "Kooperation" von anderen Modulen
* verwendete Leuchtmittel
* Auslastung der ''Bridge''
Das Modul ist stark optimiert um die Farbverläufe flüssig wiedergeben zu können. Auf der anderen Seite reagiert das menschliche Auge sehr empfindlich. Deshalb sind gelegentliche "Sprünge" bei Farbverläufen unvermeidlich und sehr von der konkreten Umgebung abhängig.

== Unterstützte Wifi-Leuchtmittel ==

=== RGB LED (Streifen) am LW12 Wifi LED Controller ===

{{Randnotiz|RNTyp=Info|RNText=Achtung: Vom LW12 existieren mindestens zwei Ausführungen. Unterscheidbar am "eigenen" WLAN. LW12 spannt ein Netz mit der Bezeichnung "LEDNET..." auf. LW12 - HX001 spannt ein Netz mit der Bezeichnung "HX..." auf. Beide Typen werden unterstützt, müssen jedoch mit anderer Signatur definiert werden}}
[[Datei:LW12.JPG|mini|LW12 LED stripe WiFi Controller]]

Der LW12 vereint die LED Steuereinheit und den Wifi Empfänger. Zum Betrieb ist noch der LED Streifen mit gemeinsamer Anode sowie ein in Spannung und Leistung zum LED Streifen passendes Netzteil erforderlich. Alle Anschlüsse am Controller sind als Schraubklemmen ausgeführt.

==== Alternative Bezeichnungen ====
* WF200 Controller

Der Controller erstellt im Werkszustand ein WLAN mit eigener SSID und wird über die vom Hersteller gelieferte Smartphone App in das eigene Netzwerk eingebunden.
* Android Version im Google PlayStore [https://play.google.com/store/apps/details?id=com.Zengge.LEDWifiMagicColor&hl=de LED Magic Color Controller v2]
* Apple Version im Apple App-Store [https://itunes.apple.com/de/app/led-magic-color/id595148649?mt=8 LED Magic Color]

Die Definition erfolgt im Modul so:

LW12 (eigene SSID "LEDNET..."):
:<code>define <name> WifiLight RGB LW12:<IP|FQDN></code>
LW12 (eigene SSID "HX..."):
:<code>define <name> WifiLight RGB LW12HX:<IP|FQDN></code>

Es können eine beliebige Anzahl LW12 definiert werden. Ein LW12 steuert jeweils nur einen LED RGB Streifen.

Der LW12 erzeugt weißes Licht durch RGB Farbmischung und unterstützt beliebige Sättigungen sowie Helligkeiten. <strike>Deshalb und wegen seiner hohen Aktualisierungsrate, ist er für reine RGB Streifen die erste Wahl.</strike> Mittlerweile ist der (bessere) LD382 vom gleichen Hersteller verfügbar.

Zum Betrieb sind der LW12, ein RGB LED Streifen sowie passendes Netzteil (Klemmschrauben) erforderlich.

==== Bezug ====

* Zum Zeitpunkt der Erstellung dieses Artikels ist der LW12 bei eBay von diversen Händlern ab ca 30,- Euro erhältlich.
* [http://www.amazon.de/NEUER-STRIPS-CONTROLLER-iPhone-Android/dp/B00G55329A/ref=sr_1_1?ie=UTF8&qid=1390006342&sr=8-1&keywords=lw12+led LW12 RGB LED Stripecontroller Amazon]

=== RGB und RGBW LED (Streifen) am LD382 Wifi LED Controller ===

Der LD382 vereint die LED Steuereinheit und den Wifi Empfänger. Am LD382 können reine RGB Streifen, RGBW Streifen oder eine Kombination beider angeschlossen werden. Zum Betrieb ist noch der LED Streifen mit gemeinsamer Anode sowie ein in Spannung und Leistung zum LED Streifen passendes Netzteil erforderlich. Alle Anschlüsse am Controller sind als Schraubklemmen ausgeführt, das Netzteil verfügt zusätzlich über einen Steckeranschluss.

Der LD382 verfügt über einen WPS Button, kann also per "one-click" ins Netzwerk genommen werden.

==== Alternative Bezeichnungen ====
* LED Magic UFO (XCSOURCE)

Die Definition erfolgt im Modul so:

LD382 mit RGB Streifen (Weiß wird gemischt)
:<code>define <name> WifiLight RGB LD382:<IP|FQDN></code>
LD382 mit RGBW Streifen (oder Kombination aus RGB und separatem Weiß)
:<code>define <name> WifiLight RGBW LD382:<IP|FQDN></code>

=== RGBW LD316 LED-Lampe Wifi ===

Der LD316 vereint LED-Lampe (Fassung E27), Steuereinheit und Wifi Empfänger. Eine externe Steuereinheit ist nicht notwendig. Einfach gegen vorhandene Glühbirne auswechseln. Mittels App (sh. LW12) kann LD316 gesteuert und eingestellt werden. Betrieb im eigenen WLAN ist möglich. Weiterhin sind Einstellungen über den in LD316 vorhandenen Webserver möglich (Benutzer: admin, Kennwort: nimda).

Die Definition erfolgt im Modul so:
:<code>define <name> WifiLight RGBW LD316:<IP|FQDN></code>

==== Alternative Bezeichnungen ====
* WIFI WLAN LED Lampe IWY MASTER Color (RGB)
* diverse wechselnde Bezeichnungen bei AliExpress

==== Bezug ====
* Amazon, ab und an vorhanden, Preis schwankt zwischen 40 und 55 €
* ebay, ab und an vorhanden, Preis meist um 45 €
* AliExpress, fast immer was zu finden, Preis zwischen 22 $ und 34 $, Coupon beim Angebot beachten, [http://de.aliexpress.com/item/Free-shipping-smartphone-controlled-lights-bulb-7w-e27-rgbw-colors/32437430102.html?adminSeq=223453226&shopNumber=1763377 Beispiel 1], [http://de.aliexpress.com/item/LED-Smart-bulb-7-5w-E27-RGB-LED-WIFI-Bulb-Light-Color-Temperature-Brightness-Adjustable-Light/32254107494.html?adminSeq=201473654&shopNumber=811614 Beispiel 2]

=== sengled Boost LED-Lampe Wifi ===
<gallery>
Sengled Boost.JPG|sengled Boost
</gallery>
Die sengled Boost vereint eine Weiß-LED-Lampe (Fassung E27), Wifi Empfänger und Steuereinheit und bietet eine Wifi Repeater Funktion. Eine externe Steuereinheit ist nicht notwendig. Einfach gegen vorhandene Glühbirne auswechseln. Mittels App ("sengled Boost" unter [http://forum.fhem.de/index.php/topic,36811.0.html Android] oder [https://itunes.apple.com/de/app/sengled-boost/id848792893?mt=8 iOS]) kann die sengled Boost gesteuert und eingestellt werden. Betrieb im eigenen WLAN ist möglich. Weiterhin sind Einstellungen (besonders zur Wifi Repeater Funktion) über den in der sengled Boost vorhandenen Webserver möglich (Benutzer: admin, Kennwort: admin).

Die Definition erfolgt im Modul so:
:<code>define <name> WifiLight White SENGLED:<IP|FQDN></code>

Weitere Informationen können im entsprechenden {{Link2Forum|Topic=36811|LinkText=Forumsthema}} nachgelesen werden.

=== Milight Systeme für LED Streifen und E27 Leuchtmittel ===

Milight Leuchtmittel sind von diversen Herstellern unter diversen Handelsnamen erhältlich. Verfügbar sind preiswerte Ansteuerungen (RGB, RGB oder Weiß, RGB und Weiß, Warm- und Kaltweiß) für LED Streifen, Downlights sowie E27 Leuchtmittel. Die E27 Leuchtmittel haben den Empfänger integriert und können direkt in vorhandenen Fassungen eingesetzt werden.

Die Lampen / Controller sprechen ein proprietäres 2,4GHz Protokoll. Zur Ansteuerung mit fhem wird eine zusätzliche bridge benötigt.

==== Alternative Bezeichnungen ====
* Rocket LED
* Limitless LED
* Easybulb
* s`luce iLight
* iBulb
* Kreuzer
* ...

==== Milight WiFi bridge ====
aktuell sind vier bridge Versionen erschienen (v1 .. v4) wobei die v1 praktisch nicht mehr erhältlich ist und nicht unterstützt wird. Der bridge erstellen im Werkszustand ein WLAN mit eigener SSID und werden über eine Smartphone App in das eigene Netzwerk eingebunden. Zum Betrieb ist ein 5V USB Netzteil erforderlich. Ein Betrieb an den USB Ports des Host ist möglich, wegen eventueller Energiemanagement Funktionen des Host jedoch nicht empfohlen.
<gallery>
BridgeV2.JPG|Milight v2 bridge
BridgeV3.JPG|Milight v3 bridge mit Limitless Aufkleber
BridgeV4.JPG|Milight v4 bridge
</gallery>

===== Milight bridge v2 =====

Die v2 bridge hört auf UDP Port 50000 und ist typischerweise am blauen Etikett erkennbar. Eine v2 bridge kann ansteuern:
* ein RGB Leuchtmittel
ODER
* ein RGBW1 Leuchtmittel
UND
* vier Gruppen Warmwhite/Coldwhite (White)

===== Milight bridge v3 =====

Die v3 bridge hört auf UDP Port 8899 und hat typischerweise ein dunkles Etikett. Eine v3 bridge kann ansteuern:
* ein RGB Leuchtmittel
ODER
* ein RGBW1 Leuchtmittel

UND

* vier Gruppen Warmwhite/Coldwhite (White)
UND
* vier Gruppen RGB + White (RGBW2)

===== Milight bridge v4 =====

Die Funktionen der v4 entsprechen im wesentlichen der v3, allerdings ist das WLAN Modul ein anderes (Draft-N) und das Web Interface wurde entfernt.

==== Leuchtmittel ====

===== Milight Leuchtmitteltyp RGB =====

E27, LED Streifen Controller oder Downlight.

Dieser Typ RGB Leuchtmittel ist veraltet und von Neuanschaffungen wird abgeraten. Die Ansteuerung ist nur im Farbkreis möglich (keine volle RGB Mischung, keine Sättigung, kein Weiß). Das Protokoll zur Ansteuerung dieses Typ ist fehleranfällig und sehr langsam. Eine parallele Benutzung der FB oder der App verursacht ebenfalls Fehler.

Benötigt eine bridge ab v2.
<gallery>
Milight-RGB-Stripe.jpg|Milight RGB LED stripe Controller mit FB
Milight-RGB-e27.JPG|Milight RGB e27 mit FB
Milight-RGB-downlight.JPG|s'luce RGB Downlight
</gallery>

===== Milight Leuchtmitteltyp RGBW1 =====

LED Streifen Controller. (RGB mit separatem Weiß Kanal)

Dieser Typ RGB Leuchtmittel ist veraltet.

FHEM kann mit diesem Controller Farbe, Helligkeit und Sättigung komplett steuern. Durch den extra Weißkanal sind sehr angenehme Farbmischungen möglich allerdings ist das verwendete Protokoll wie beim RGB langsam und fehleranfällig. Daher eignet sich der Controller nicht für häufige dynamische Farbwechsel und nur bedingt für unbeaufsichtigten / automatischen Betrieb.

Die Sättigung wird durch die Balance des Weiß- und des Farbkanals erreicht. Bei einer Sättigung von 50% werden Weiß und Farbe jeweils voll angesteuert.

Benötigt eine bridge ab v2.
<gallery>
Milight-RGBW1.JPG|Milight RGBW LED stripe Controller mit FB
</gallery>

===== Milight Leuchtmitteltyp White =====

E27, LED Streifen Controller oder Downlight.

Pur weiße LED Leuchtmittel mit Unterstützung der Farbtemperatur (Kaltweiß/Warmweiß).

FHEM steuert die Helligkeit der Leuchtmittel. Ein Unterstützung der Farbtemperatur (Weiß Kelvin) ist noch nicht implementiert. Die Farbtemperatur sollte initial über die app eingestellt werden und wird von den Leuchtmitteln beibehalten. Die e27 Lampen sind zum Zeitpunkt der Erstellung dieses Artikels (04/14) ab etwa 11,- Euro bei eBay verfügbar. Erhältlich in 9Watt (Alukühlkörper) und in 6Watt (OEM, Kunststoffsockel). Die Lichtausbeute ist sehr gut.

Benötigt eine bridge ab v2. Eine bridge kann vier getrennte Gruppen White ansteuern. Wenn mehr als vier Gruppen eingesetzt werden sollen können weitere bridge eingebunden werden.
<gallery>
Milight-WWCW-FB.JPG|Milght Warmweiß/kaltweiß LED Streifen controller mit FB
Milight-E27-WWCW-OEM.JPG|Milight Warmweiß/kaltweiß 6 Watt E27 OEM
Milight-E27-WWCW-9W.JPG|Milight Warmweiß/kaltweiß 9 Watt E27
Milight-Downlight-WWCW.JPG|Milight Warmweiß/kaltweiß Downlight (IWY STAR 6 Watt)
</gallery>

===== Milight Leuchtmitteltyp RGBW2 =====

E27, LED Streifen Controller oder Downlight.

Aktuelle Typen mit neuem und robusterem Protokoll.

Dieser Typ Leuchtmittel gibt farbiges oder weißes Licht. Die Sättigung ist nicht stufenlos sondern 0% oder 100%. Die E27 Typen sind dabei wahlweise mit Warm- oder Kaltweiß bestellbar.

Erhältlich in 9Watt (Alukühlkörper) und in 6Watt (OEM, Kunststoffsockel).

Benötigt eine bridge ab v3. Eine bridge kann vier getrennte Gruppen RGBW2 ansteuern. Mehr als vier Gruppen können mit zusätzlichen bridge verwendet werden.

Die Sättigung wird wie folgt umgesetzt: S: 0..20 => 0% / S: 21..100 => 100%.

''Bei Farbverläufen (Sonnenaufgang) die bei einer Farbe beginnen und bei Weiß enden kann es sinnvoll sein in zwei Schritten zuerst auf 100% Gelb zu faden, dort auf 20%..40% Weiß (typenabhängig) umzuschalten und dann Weiß weiter auf 100% zu dimmen.''
<gallery>
Milight-rgbw2-LED.jpg|Milight RGB/Weiß LED Streifen Controller 4 Zonen
Milight-E27-RGBW2-OEM.JPG|Milight RGB/Weiß 6 Watt E27 OEM
Milight-E27-RGBW2-9Watt.JPG|Milight RGB/Weiß 9 Watt E27 mit FB
</gallery>

== Installation ==
{{Randnotiz|RNTyp=r|RNText=Achtung: Das modul ist nicht Bestandteil der fhem Standardinstallation weil der dev lieber die Unterstützung neuer Controller einbaut anstelle die Doku zu schreiben :)}}
Das Modul wird bequem so installiert:
<code>update force https://raw.githubusercontent.com/herrmannj/wifilight/master/controls_wifilight.txt</code>

== Color-Picker aktivieren ==
Um den sog. "Color-Picker" zu aktivieren müssen die beiden folgenden Attribute gesetzt werden:
<pre>
attr <name> webCmd RGB
attr <name> widgetOverride RGB:colorpicker,RGB
</pre>
<gallery>
Wifiled_colorpicker.png|Colorpicker Beispiel
</gallery>

Weitere Informationen unter [http://www.fhemwiki.de/wiki/Color Color Wiki Artikel]

== Farbiges Icon ==
Weiterhin kann das Lampen-Icon auch farbig dargestellt werden. Dazu ist es erforderlich, das folgende Attribut zu setzen:
<pre>
attr <name> devStateIcon {Color_devStateIcon(ReadingsVal($name,"RGB","000000"))}
</pre>

== Links ==
* Thread über das Modul im [http://forum.fhem.de/index.php/topic,18958.0.html Fhem Forum]
* [http://www.ledsee.com/datasheet_ledsee/LED%20WiFi%20controller%20for%20home%20use_Hontech-wins__-EN.pdf LW12 Datasheet]

[[Kategorie:Unterhaltungselektronik]]
[[Kategorie:Code Snippets]]