FHEMWiki - Benutzerbeiträge [de]

AMAD

2016-11-21T19:40:43Z

Nesges: /* Definition */ Typos korrigiert

{{Infobox Modul
|ModPurpose=Steuern von Adroidgeräten und Anzeige von bestimmten Informationen dieser Geräte
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModTechName=74_AMAD.pm
|ModOwner=CoolTux <br />([http://forum.fhem.de/index.php?action=profile;u=13684 Forum] / [[Benutzer:CoolTux|Wiki]])
}}

==Vorwort==
===Warum AMAD2===
Bei der Entwicklung von AMAD musste ich auf Grund meines damaligen Wissenstandes ein einfaches Konzept zum erhalt von Daten wählen. Hierfür wählte ich das Prinzip des pullens. Die Daten wurden alle 3 min vom Gerät angefordert.
Mit AMAD2, also der 2. Version von AMAD werden die Daten nun vom Androidgerät selbst nach FHEM gepusht. So kommen Statusänderungen quasi in Echtzeit als Reading ins Device.

==Vorstellung==
Dieses Modul liefert, '''in Verbindung mit der Android APP Automagic''', diverse Informationen von Android Geräten.
Die AndroidAPP Automagic (welche nicht von mir stammt und 2.90 Euro kostet) funktioniert wie Tasker, ist aber bei weitem User freundlicher.

== Features / Funktionen ==
Im Auslieferiungszustand werden folgende Zustände dargestellt:
* installierte Android Version
* Zustand von Automagic auf dem Gerät
* Spracheingabe
* Bluetooth An/Aus
* Zustand einer definierten App (läuft aktiv im Vordergrund oder nicht?)
* verbundene Bluetoothgeräte, inklusive deren MAC Adresse
* aktuell abgespieltes Musikalbum des verwendeten Mediaplayers
* aktuell abgespielter Musikinterpret des verwendeten Mediaplayers
* aktuell abgespielter Musiktitel des verwendeten Mediaplayers
* Status des Androidgerätes - Online/Offline
* nächster Alarmtag
* nächste Alarmzeit
* Batteriestatus in %
* Ladestatus - Netztei angeschlossen / nicht angeschlossen
* Bildschirmstatus An/Aus
* Bildschirmhelligkeit
* Vollbildmodus An/Aus
* Bildschirmausrichtung Auto/Landscape/Portrait
* Standardlautstärke
* Media Lautstärke
* ...

Mit etwas Einarbeitung können jegliche Informationen welche Automagic bereit stellt in FHEM angezeigt werden. Hierzu bedarf es lediglich eines eigenen Flows welcher seine Daten an die AMADCommBridge sendet. Das Modul gibt auch die Möglichkeit Androidgeräte zu steuern.

Das Modul gibt Dir auch die Möglichkeit Deine Androidgeräte zu steuern. So können folgende Aktionen durchgeführt werden:
* Bluetooth Ein/Aus schalten
* zu einem bestimmten Bluetoothgerät wechseln/verbinden
* Status des Gerätes (Online,Offline)
* Mediaplayer steuern (Play, Stop, nächster Titel, vorheriger Titel)
* nächste Alarmzeit setzen
* ein Benachrichtigungston abspielen (Notificationsound)
* eine App auf dem Gerät öffnen
* eine URL im Browser öffnen
* Bildschirm An/Aus machen
* Bildschirmhelligkeit einstellen
* Vollbildmodus einschalten
* eine Nachricht senden welche am Bildschirm angezeigt wird
* Bildschirmausrichtung einstellen (Auto,Landscape,Portrait)
* neuen Statusreport des Gerätes anfordern
* Systembefehle setzen (Reboot)
* eine Nachricht senden welche angesagt wird (TTS)
* Medienlautstärke regeln
* ...

== Hinweise zum Betrieb mit Fhem ==
Für all diese Aktionen und Informationen wird auf dem Androidgerät Automagic und ein so genannter Flow benötigt.
Die App Automagic Premium könnt Ihr Euch aus dem App Store installieren, die Flows bekommt Ihr aus dem Flowset 74_AMADautomagicFlowset$VERSION.xml unter $FHEMINSTALL/FHEM/lib/

AutomagicApp Anweisung
* installiert die App
* installiert das Flowset 74_AMADautomagicFlowset$VERSION.xml aus dem Ordner $INSTALLFHEM/FHEM/lib/ auf Eurem Androidgerät. '''NOCH NICHT''' die Flows aktivieren

==Definition==
<code>define <name> AMAD <IP-ADRESSE></code>
'''!!! Wichtig - Es dürfen ausschließlich nur IP Adressen verwendet werden, keine FQDN !!!'''

'''Beispiel:'''

<code>define WandTabletWohnzimmer AMAD 192.168.0.23</code>

Diese Anweisung erstellt zwei neue AMAD-Devices im Raum AMAD. Der Parameter <IP-ADRESSE> legt die IP Adresse des Android Gerätes fest.
Das zweite Device ist die AMADCommBridge, welche als Kommunikationsbrücke vom Androidgerät zu FHEM dient. !!!Comming Soon!!! Wer den Port ändern möchte, kann dies über das Attribut "port" tun. Ihr solltet aber wissen was Ihr tut, da dieser Port im HTTP Request Trigger der beiden Flows eingestellt ist. Demzufolge muß der Port dort auch geändert werden.
Der Port für die Bridge kann ohne Probleme im Bridge Device mittels dem Attribut "port" verändert werden.

===AMAD Communication Bridge===
Beim ersten anlegen einer AMAD Deviceinstanz wird automatisch ein Gerät Namens AMADCommBridge im Raum AMAD angelegt. Dieses Gerät dient zur Kommunikation vom Androidgerät zu FHEM ohne das zuvor eine Anfrage von FHEM aus ging. Damit das Androidgerät die IP von FHEM kennt, muss diese sofort nach dem anlegen der Bridge über den set Befehl in ein entsprechendes Reading in die Bridge geschrieben werden. DAS IST SUPER WICHTIG UND FÜR DIE FUNKTION DER BRIDGE NOTWENDIG.
Bitte führt hierzu folgenden Befehl aus. set AMADCommBridge fhemServerIP <FHEM-IP>.
Als zweites Reading könnt ihr expertMode setzen. Mit diesem Reading wird eine unmittelbare Komminikation mit FHEM erreicht ohne die Einschränkung über ein Notify gehen zu müssen und nur reine set Befehle ausführen zu können.

'''JETZT bitte die Flows AKTIVIEREN!!!'''

'''Fertig! Nach anlegen der Geräteinstanz und dem Eintragen der fhemServerIP in der CommBridge sollten nach spätestens 15 Sekunden bereits die ersten Readings reinkommen. Nun wird alle 15 Sekunden probiert einen Status Request erfolgreich ab zu schließen. Wenn der Status sich über einen längeren Zeitraum nicht auf "activ" ändert, sollte man im Log nach eventuellen Fehlern suchen.'''

Es gibt die Möglichkeit einer Abfrage des Status jeglicher Geräte in FHEM über das Androidgerät und Auswertung auf dem Androidgerät.

'''Beispiel:'''
Erstelle einen Flow mit einer HTTP Request Aktion mit folgendem Inhalt:

<code>
URL
http://{global_fhemip}:8090

REQUEST METHODE
POST

CONTENT TYP
Genereller Text
text/plain

DATEN
(hier kommen die drei Werte für ein ReadingsVal Aufruf rein, getrennt durch Leerzeichen)
TempFeuchtSensorSchlafzimmer temperature 300

(haken)Setze eigenen Header
FHEMDEVICE: {global_fhemdevice}
FHEMCMD: readingsval

SPEICHERE ANTWORT ...
Variable

VARIABLE
response
</code>

Du erhälst dann den Rückgabewert in der Response-Variablen. Diesen kannst Du dann innerhalb Deines Flows weiter verarbeiten. Z.B. Ansagetext.

==Readings==
* airplanemode - Status des Flugmodus
* androidVersion - aktuell installierte Androidversion
* automagicState - Statusmeldungen von der AutomagicApp '''(Voraussetzung Android >4.3). Wer ein Android >4.3 hat und im Reading steht "wird nicht unterstützt", muß in den Androideinstellungen unter Ton und Benachrichtigungen -> Benachrichtigungszugriff ein Haken setzen für Automagic'''
* bluetooth on/off - ist auf dem Gerät Bluetooth an oder aus
* checkActiveTask - Zustand einer zuvor definierten APP. 0=nicht aktiv oder nicht aktiv im Vordergrund, 1=aktiv im Vordergrund, '''siehe Hinweis unten'''
* connectedBTdevices - eine Liste der verbundenen Gerät
* connectedBTdevicesMAC - eine Liste der MAC Adressen aller verbundender BT Geräte
* currentMusicAlbum - aktuell abgespieltes Musikalbum des verwendeten Mediaplayers
* currentMusicApp - aktuell verwendeter Mediaplayers
* currentMusicArtist - aktuell abgespielter Musikinterpret des verwendeten Mediaplayers
* currentMusicTrack - aktuell abgespielter Musiktitel des verwendeten Mediaplayers
* daydream - on/off Daydream gestartet oder nicht
* deviceState - Status des Androidgerätes / unknown, online, offline
* doNotDisturb - aktueller Status des nicht stören Modus
* dockingState - undocked/docked Status ob das Gerät in einer Dockinstation ist oder nicht.
* flow_SetCommands - active/inactive, gibt den Status des SetCommands Flow wieder
* flow_informations - active/inactive, gibt den Status des Informations Flow wieder
* flowsetVersionAtDevice - aktuell installiertes Flowset auf dem Device
* intentRadioName - zu letzt eingestellter Intent Radio Name
* intentRadioState - Status des IntentRadio Players
* keyguardSet - 0/1 Displaysperre gesetzt 0=nein 1=ja, bedeutet nicht das sie gerade aktiv ist
* lastSetCommandError - letzte Fehlermeldung vom set Befehl
* lastSetCommandState - letzter Status vom set Befehl, Befehl erfolgreich/nicht erfolgreich gesendet
* lastStatusRequestError - letzte Fehlermeldung vom statusRequest Befehl
* lastStatusRequestState - letzter Status vom statusRequest Befehl, Befehl erfolgreich/nicht erfolgreich gesendet
* nextAlarmDay - aktiver Alarmtag
* nextAlarmState - aktueller Status des Androidinternen Weckers
* nextAlarmTime - aktive Alarmzeit
* powerLevel - Status der Batterie in %
* powerPlugged - Netzteil angeschlossen? 0=NEIN, 1|2=JA
* screen - on locked/unlocked, off locked/unlocked zeigt an ob der Bildschirm an oder aus ist und gleichzeitig gesperrt oder nicht gesperrt
* screenBrightness - Bildschirmhelligkeit von 0-255
* screenFullscreen - Vollbildmodus (On,Off)
* screenOrientation - (Landscape,Portrait) Bildschirmausrichtung
* screenOrientationMode - (auto, manual) Modus für die Ausrichtung
* state - aktueller Status des Devices
* volume - Media Lautstärkewert
* volumeNotification - Benachrichtigungs Lautstärke

Beim Reading checkActivTask muß zuvor der Packagename der zu prüfenden App als Attribut checkActiveTask angegeben werden. Beispiel: attr Nexus10Wohnzimmer checkActiveTask com.android.chrome für den Chrome Browser.

==Befehle==

===Set===
* activateVoiceInput - schaltet die Spracheingabe ein
* bluetooth - Schaltet Bluetooth on/off
* clearNotificationBar - (All,Automagic) löscht alle Meldungen oder nur die Automagic Meldungen in der Statusleiste
* currentFlowsetUpdate - fürt ein Flowset Update auf dem Device aus
* deviceState - setzt den Device Status Online/Offline. Siehe Readings
* installFlowSource - installiert einen Flow auf dem Device, das XML File muss unter /tmp/ liegen und die Endung xml haben. '''Bsp:''' set TabletWohnzimmer installFlowSource WlanUebwerwachen.xml
* doNotDisturb - schaltet den nicht stören Modus, always immer Stören, never niemals stören, alarmClockOnly nur Wecker darf stören, onlyImportant nur wichtige Störungen
* mediaPlayer - steuert den Standard Mediaplayer. play, stop, Titel zürück, Titel vor.
* nextAlarmTime - setzt die Alarmzeit. Geht aber nur innerhalb der nächsten 24Std.
* notifySndFile - spielt die angegebende Mediadatei auf dem Androidgerät ab. '''Die aufzurufende Mediadatei muß sich im Ordner /storage/emulated/0/Notifications/ befinden.'''
* screenBrightness - setzt die Bildschirmhelligkeit, von 0-255.
* screenMsg - versendet eine Bildschirmnachricht
* sendintent - sendet einen Intentstring Bsp: set $AMADDEVICE sendIntent org.smblott.intentradio.PLAY url http://stream.klassikradio.de/live/mp3-192/stream.klassikradio.de/play.m3u name Klassikradio, der erste Befehl ist die Aktion un der zweite das Extra. Es können immer zwei Extras mitgegeben werden.
* statusRequest - Fordert einen neuen Statusreport beim Device an. Es können nicht von allen Readings per statusRequest die Daten geholt werden. Einige wenige geben nur bei Statusänderung ihren Status wieder.
* timer - setzt einen Timer innerhalb der als Standard definierten ClockAPP auf dem Device. Es können nur Sekunden angegeben werden.
* ttsMsg - versendet eine Nachricht welche als Sprachnachricht ausgegeben wird
* vibrate - lässt das Androidgerät vibrieren
* volume - setzt die Medialautstärke. Entweder die internen Lautsprecher oder sofern angeschlossen die Bluetoothlautsprecher und per Klinkenstecker angeschlossenen Lautsprecher, + oder - vor dem Wert reduziert die aktuelle Lautstärke um den Wert
* volumeNotification - setzt die Benachrichtigungslautstärke.

===Set abhängig von gesetzten Attributen===
* changetoBtDevice - wechselt zu einem anderen Bluetooth Gerät. '''Attribut setBluetoothDevice muß gesetzt sein. Siehe Hinweis unten!'''
* openApp - öffnet eine ausgewählte App. '''Attribut setOpenApp'''
* openURL - öffnet eine URL im Standardbrowser, sofern kein anderer Browser über das Attribut setOpenUrlBrowser ausgewählt wurde. '''Bsp:''' ''attr Tablet setOpenUrlBrowser de.ozerov.fully|de.ozerov.fully.MainActivity'', das erste ist der Package Name und das zweite der Class Name
* screen - on/off/lock/unlock schaltet den Bildschirm ein/aus oder sperrt/entsperrt ihn, in den Automagic Einstellungen muss "Admin Funktion" gesetzt werden sonst funktioniert "Screen off" nicht. '''Attribut setScreenOnForTimer''' ändert die Zeit wie lange das Display an bleiben soll!
* screenFullscreen - Schaltet den Vollbildmodus on/off. '''Attribut setFullscreen'''
* screenLock - Sperrt den Bildschirm mit Pinabfrage. '''Attribut setScreenlockPIN''' - hier die Pin dafür eingeben. Erlaubt sind nur Zahlen. Es müßen mindestens 4 bis max 16 Zeichen sein.
* screenOrientation - Schaltet die Bildschirmausrichtung Auto/Landscape/Portait. '''Attribut setScreenOrientation'''
* setAPSSID - setzt die Acces Point SSID um WLAN Sleeps zu verhindern'''
* setTtsMsgSpeed - setzt die Sprachgeschwindigkeit bei der Sprachausgabe '''(Werte zwischen 0.5 bis 4.0 in 0.5er Schritten) default ist 1.0'''
* setTtsMsgLang - setzt die Sprache der Sprachausgabe, (de-Deutsch - en Englisch) default ist de'''
* system - setzt Systembefehle ab (nur bei gerootetet Geräen). reboot,shutdown,airplanemodeON (kann nur aktiviert werden) '''Attribut root''', in den Automagic Einstellungen muss "Root Funktion" gesetzt werden
* setNotifySndFilePath - setzt den korrekten Systempfad zur Notifydatei '''(default ist /storage/emulated/0/Notifications/'''

Um openApp verwenden zu können, muss als Attribut der Package Name der App angegeben werden.

Um zwischen Bluetoothgeräten wechseln zu können, muß das Attribut setBluetoothDevice mit folgender Syntax gesetzt werden. ''attr <DEVICE> BTdeviceName1|MAC,BTDeviceName2|MAC'' Es muss zwingend darauf geachtet werden das beim BTdeviceName kein Leerzeichen vorhanden ist. Am besten zusammen oder mit Unterstrich. Achtet bei der MAC darauf das Ihr wirklich nach jeder zweiten Zahl auch einen : drin habt '''Beispiel:''' ''attr Nexus10Wohnzimmer setBluetoothDevice Logitech_BT_Adapter|AB:12:CD:34:EF:32,Anker_A3565|GH:56:IJ:78:KL:76''

==STATE==
* initialized - Ist der Status kurz nach einem define..
* active - die Geräteinstanz ist im aktiven Status.
* disabled - die Geräteinstanz wurde über das Attribut disable deaktiviert

==deviceState==
* online - Das Gerät ist online und kann set Befehle entgegennehmen.
* offline - Ein Gerät wird in den folgenden 3 Szenarien in den Status offline gesetzt:
** Das Gerät wird mittels shutdown über FHEM runtergefahren.
** Der Airplainmod (Flugmodus) wird über FHEM aktiviert.
** Es wurde mehr als 5 mal ein statusRequest erfolglos und mehr als 3 mal ein set Command erfolglos abgeschickt.
Es bleibt also dem User überlassen das Gerät nach erneuter Verfügbarkeit wieder in den Status online zu setzen. Das kann z.B. über das Presence Modul erzeugt werden (set DEVICE deviceState online)

==Anwendungsbeispiele==
=== Lademanagement ===
Ich habe die Ladegeräte für meine Androidgeräte an Funkschaltsteckdosen. ein DOIF schaltet bei unter 30% die Steckdose ein und bei über 90% wieder aus.

Hier mal ein einfaches DOIF Beispiel für ein Lademanagment

<code>
... DOIF ([Nexus5Handy:powerLevel] < 30) (set LadenetzteilNexus5Handy:FILTER=STATE=off on) DOELSEIF ([Nexus5Handy:powerLevel] > 90) (set LadenetzteilNexus5Handy:FILTER=STATE=on off) DOELSE
</code>

=== Wecker ===
Morgens lasse ich mich über mein Tablet im Schlafzimmer mit Musik wecken. Verwendet wird hierzu der wakeuptimer des RESIDENTS Modules. Das abspielen stoppe ich dann von Hand. Danach erfolgt noch eine Ansage wie das Wetter gerade ist und wird.

=== Mediacenter ===
Mein 10" Tablet im Wohnzimmer ist Mediaplayer für das Wohnzimmer mit Bluetoothlautsprechern. Die Lautstärke wird automatisch runter gesetzt wenn die Fritzbox einen Anruf auf das Wohnzimmer Handgerät signalisiert.

=== Sprachbefehl - Abfragen von Zuständen diverser Sensoren ===
Wenn ich die Spracheingabe aktiviere und nach der Temperatur im Wohnzimmer frage, bekomme ich diese angesagt.

Der Teil im Feld Daten ist ein klassisches RadingsVal, halt nur ohne Komma und ohne Anführungszeichen

WIRD GERADE ÜBERARBEITET

=== Schaltbefehle vom Androidgerät an FHEM senden ===
Hierfür richte bitte einen eigen Flow ein. Wie das genau geht, verrät Dir die Hilfe.
Um einen Schaltbefehl für FHEM zu erstellen, folgt nach dem Trigger eine Aktion als Script (Aktion Type: Script). Hier trägst Du folgendes ein

setcmd = "LichtWohnzimmerLampeRechts on"

fhemcmd = "set"

In der ersten Zeile wird also der Schaltbefehl in der Variablem setcmd eingetragen und in der zweiten Zeile der FHEM Befehl in der Variablen fhemcmd.

Danach müsst Ihr nur noch in einer weiteren Aktion den Flow "Send Data to AMADCommBridge" ausführen (Aktion Type: Flows ausführen). Die Aktion sollte bereits in Eurer Liste Vorhanden sein.

[[Datei:Screenshot_20160717-134948.png|200px]]
[[Datei:Screenshot 17.07.2016 1-50-27.png|200px]]

Nun sollte Lampe1 angeschalten werden wenn der Flow ausgeführt wird.

== Bekannte Meldungen/Hinweise/Probleme ==
<code>PERL WARNING: Use of uninitialized value in hash element at /opt/fhem/FHEM/74_AMAD.pm line 14X</code>
Ist ab Version 2.2.2 gefixt. [https://forum.fhem.de/index.php/topic,54433.0.html Dickes Danke an Andy(gandy)]

Wenn auf dem Android-Gerät die Fehlermeldung 'Accessibility service not running' von Automagic kommt, oder im FHEM das reading state 'Flow Informations mit Fehler beendet' steht, dann muss der Accessibility Service auf dem Android-Device aktiviert werden: Einstellungen --> Bedienungshilfen --> Automagic Premium. Hier muss der Schalter auf 'an' stehen. Sollte dies der Fall sein, hilft u.U. ein kurzes Aus- und wieder Einschalten.

Gerät wird oft als offline angezeigt und es können keine set Befehle abgesetzt werden.
Mit der AMAD Version 2.2 hielt eine neue Behandlung des deviceState Readings Einzug. Das Reading stellt nun den tatsächlichen Status des Gerätes gegenüber FHEM da. Bei vielen Android 6 Geräten kommt es aber auf Grund vom DeepSleep Modus zum wegfall der WLAN Verbindung. Hier hilft die neue KeepAlive Funktion in AMAD. Dafür muß lediglich unter
* Einstellungen --> Akku --> oben auf die drei Punkte - Akku Leistungsoptimierung --> alle Apps und dann Automagic auswählen und "Nicht optimieren"
ausgewählt werden. Alles andere macht das Modul selbst.

==Ich sage Danke==
''Der größte Dank geht an meinen Mentor Andre (justme1968), er hat mir mit hilfreichen Tips geholfen Perlcode zu verstehen und Spaß am programmieren zu haben.''

''Auch möchte ich mich bei Jens bedanken (jensb) welcher mir ebenfalls mit hilfreichen Tips bei meinen aller ersten Gehversuchen beim Perlcode schreiben unterstützt hat.''

''So und nun noch ein besonderer Dank an pah (Prof. Dr. Peter Henning ), ohne seine Aussage "Keine Ahnung hatten wir alle mal, das ist keine Ausrede" hätte ich bestimmt nicht angefangen Interesse an Modulentwicklung zu zeigen :-)''

''Danke an Jürgen(ujaudio) und Andreas(scooty) die sich um die Übersetzung der Commandref ins Englische gekümmert haben''

''Danke auch an Ronny(RoBra81) für seine tollte Idee und Umsetzung von eigenen AMAD Readings aus externen Flows.''

Benutzer:Nesges

2015-05-29T20:12:03Z

Nesges:

== Meine FHEM-Installation ==
[[File:Wopr home.png|400x300px|right|link=File:Wopr home.png]] [[File:Ftui-wopr-index.png|400x300px|right|link=File:Ftui-wopr-index.png]]
(Haupt-) Aktoren und Sensoren in meinem FHEM-Setup:

* [[CUL]]
** [[MAX]]
*** HeatingThermostatPlus
*** ShutterContact
** [[Intertechno Code Berechnung|IT]]
*** Mumbi Zwischenstecker
* [[JeeLink]]
** [[TFA 30.3144]]
** [[TFA 30.3147]]
* [[XBMC]]
* [[MPD]]
* [[PRESENCE]]
* [[FB_CALLMONITOR]]
* [[FRITZBOX]]
* [[MilightBridge]]
** [[MilightDevice]]

Installiert seit 2014/12 auf [[Raspberry Pi]].

== FHEM Tablet UI ==

Zum [[FHEM Tablet UI]] steuere ich ein [https://github.com/nesges/Widgets-for-fhem-tablet-ui Repository mit zusätzlichen Widgets] bei, hoste [http://fhem.nesg.es eine Live-Demo] und beteilige mich generell an der Weiterentwicklung.

Datei:Ftui-wopr-index.png

2015-05-29T20:10:29Z

Nesges:

FHEM Tablet UI

2015-05-29T12:34:50Z

Nesges: Widgets for fhem-tablet-ui: Installation per FHEM-Update; Link auf die Dokumentation

[[Datei:tablet_ui.png|200px|thumb|right|FHEM Tablet UI]]
FHEM Tablet UI ist ein leichtgewichtiges aber funktionsreiches Framework zum Steuern und Überwachen von in FHEM integrierten Geräten. Zahlreiche Widgets können sehr flexibel und leicht per HTML Code konfiguriert werden.

In dieser Anleitung wird die Installation und Konfiguration des FHEM Tablet UI beschrieben. Beitrag im FHEM-Forum: http://forum.fhem.de/index.php/topic,34233.0.html

{{Todo|alle Widgets hier übernehmen, Übersetzung, weitere Beispiele aus dem Forum einfügen (evtl. mit Link!?)}}

== Voraussetzungen ==
Dieses User Interface für Tablets benötigt <u>keine</u> zusätzliche Frameworks, wie PHP, MySQL oder SmartVisu.

Voraussetzungen ist nur ein Standard-FHEM mit HTTPSRV Modul und ein beliebiger Standard-Browser mit Javascript auf einem beliebigen Betriebssystem oder Webviewcontrol.

Alle nötigen Files sind im Zip-File inklusive, die einfach nur in einem bestimmten Unterordner der FHEM Installation kopiert werden müssen.

== Installation ==
* Dateien herunterladen: https://github.com/knowthelist/fhem-tablet-ui
* einen neuen Ordner 'tablet' im Verzeichnis /<fhem-Pfad>/www erstellen
* alle Dateien und Unterordner nach /<fhem-Pfad>/www/tablet kopieren
* in fhem.cfg folgende Zeile einfügen: <code>define tablet_ui HTTPSRV tablet/index.html ./www/tablet Tablet Frontend</code>
* index-example.html in index.html umbenennen oder eine neue index.html erzeugen

Das UI ist über "http://<fhem-url>:8083/fhem/tablet/index.html" zu erreichen.

== Update ==
Zum Update des UI in der FHEM-Befehlszeile eingeben: <code>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code>
bzw. mit <code>update check https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code> vorher schauen was sich seit dem letzten Download alles geändert hat

== Weitere Widgets ==

=== Widgets for fhem-tablet-ui ===

Installation und Update können per FHEM-Update veranlasst werden. Dazu folgenden Befehl in die FHEM-Befehlszeile eingeben: <code>update all https://raw.githubusercontent.com/nesges/Widgets-for-fhem-tablet-ui/master/controls_widgets-for-fhem-tablet-ui.txt</code>. Näheres zur Installation unter [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/Installation Wiki: Installation]. Die Dokumentation der einzelnen Widgets befindet sich ebenfalls [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki im Github-Wiki].

== Konfiguration ==
Die Konfiguration der angezeigten Widgets erfolgt in der Datei '''index.html''' im Hauptordner 'tablet'.

'''Metadaten-Konfiguration'''

Refresh sofort, alle 15 Minuten ein voller Refresh (shortpoll) statt alle 30 Sekunden ein voller Refresh
:<code><meta name="longpoll" content="1"></code>

Drag&Drop deaktivieren
:<code><meta name='gridster_disable' content='1'></code>

Toast messages deaktivieren
:<code><meta name='toast' content='1'></code>

Größe des Basis-Rasters (data-sizey=1/data-sizex=1)
:<code><meta name="widget_base_width" content="116"></code>
:<code><meta name="widget_base_height" content="131"></code>

Abstände der Gridsterelemente verkleinern:
:<code><meta name="widget_margin" content="3"></code>

Das Layout und das Aussehen des UI kann durch die Klassen-Attribute beeinflusst werden. Verfügbare Klassen sind:

container, left, right, cell, narrow, darker, big, bigger, small

== Farbe ==
Es besteht die Möglichkeit, die Farbwerte in hexadezimaler Form oder als RGB-Wert anzugeben. Zum Beispiel: Hex: #A3CFA3 RBG: rgb(163, 207, 163).

Knallige Farben wie #ff0000 für Rot oder #00ff00 für Grün sollten vermieden werden. Es ist besser unterhalb von #D0 (208) für die Grundfarben zu bleiben.

Hilfreich bei der Suche nach den Farbwerten ist der color picker: http://www.w3schools.com/tags/ref_colorpicker.asp

== CSS Class description ==

Not all widgets support all classes

* readonly : changing of state is not allowed
* wider : 25px extra space for the widget to the top
* narrow : shorter distant to the widget above
* w1x, w2x, w3x : set the widget to a fix width: 1x, 2x, 3x width
* small : font 80% size (label), small diameter for volume widget
* mini : lowest diameter for volume widget
* large : font 150% size
* big : font 200% size
* bigger : font 320% size
* thin : font thin
* darker : forecolor in gray
* hue-tick : draw ticks in color range
* hue-front : draw handle in color range
* hue-back : draw background in color range
* dim-tick : draw ticks in brightness range
* dim-front : draw handle in brightness range
* dim-back : draw background in brightness range
* red : foreground color red
* green : foreground color green
* blue : foreground color blue
* doublebox-v : container to place 2 small widgets (e.g. switch) one above the other
* doublebox-h : container to place 2 small widgets (e.g. switch) side by side
* timestamp : deliver the date time for the reading instead the value
* inline : positioning elements in a row, no line break
* top-space : 15px extra on top (top-space-2x -> 30px; top-space-3x -> 45px)
* left-space : 15px extra on left (left-space-2x -> 30px; left-space-3x -> 45px)
* right-space : 15px extra on right (right-space-2x -> 30px; right-space-3x -> 45px)
* blink : blink animatation for label or symbol widget

== Widgets -- Konfiguration ==

Zurzeit stehen 17 Widgets zur Verfügung:
* [[#circlemenu|circlemenu]]: Mehrere Widgets hinter einem Widget verborgen
* [[#dimmer|dimmer]]: toogle button with a setter for on value
* [[#homestatus|homestatus]]: selector for 4 states (1=home, 2=night, 3=away, 4=holiday)
* [[#image|image]]: insert an image, the URL is given by a reading
* [[#label|label]]: ein state als Text anzeigen (Farbe einstellbar)
* [[#level|level]]: vertical/horizontal bar to show values between min/max value
* [[#pagetab|pagetab]]: Element to smoothly exchange the whole page with another page
* [[#playstream|playstream]]: Abspielen eines Webradio-Streams per Button
* [[#push|push]]: send any command to FHEM e.g. up / down
* [[#rotor|rotor]]: Umschalten von zwei oder mehr Widgets an einer Position
* [[#select|select]]: Combobox to provide a list for selection
* [[#slider|slider]]: vertical slider to select between min/max value
* [[#switch|switch]]: Toggle any command to FHEM (e.g. on / off)
* [[#symbol|symbol]]: State als Symbol darstellen (z.B. Fenster offen)
* [[#thermostat|thermostat]]: dial for heater thermostates to set desired value and show current value
* [[#volume|volume]]: dial to set a single value (e.g. 0-60)
* [[#weather|weather]]: insert an icon or image, represending a weather literal

----------------------------------

Für alle Widgets gilt:
{| 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
|}

<div id="circlemenu">'''CIRCLEMENU'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-item-diameter
|diameter of the circle
|52
|-
!align="right" |data-circle-radius
|radius of each item, in pixel
|70
|-
!align="right" |data-direction
|position of the items in relation to the center
|'full'
|-
!align="right" |data-close-after
|closing time of the circle-menu
|(item-count + 1s) or a minimum of 4s
|-
!align="right" |class
|keepopen
|
|-
|}

Optionen für data-direction: top | right | bottom | left | top-right | top-left | bottom-right | bottom-left | top-half | right-half | bottom-half | left-half | full

[[#Beispiel_circlemenu|Link zu einem Beispiel]]

<div id="dimmer">'''DIMMER'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-get-on
|value for ON status to get
|'on'
|-
!align="right" |data-get-off
|value for OFF status to get
|'off'
|-
!align="right" |data-set
|(<command> <device> <reading> <value>)
|
|-
!align="right" |data-set-on
|value for ON status to set
|value of data-get-on
|-
!align="right" |data-set-off
|value for OFF status to set
|value of data-get-off
|-
!align="right" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-dim
|name of the reading responsible for dim (<command> <device> <reading> <value>)
|value of data-get-on
|-
!align="right" |data-icon
|name of the font-awesome icon
|fa-lightbulb-o
|-
|}

[[#Beispiel_dimmer|Link zu einem Beispiel]]

<div id="homestatus">'''HOMESTATUS'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-set
|command to send to FHEM (<code>set <device> <command> <value></code>)
|''
|-
!align="righ" |data-version
|name of the special dummy device to represent
|
|-
|}

<code>data-version=''</code> (default) 4 states are valid: 1,2,3 or 4 (1=home, 2=night, 3=away, 4=holiday) data-version='residents' or 'roomate' or 'guest' residents states are valid (absent,gone,asleep,home)

[[#Beispiel_homestatus|Link zu einem Beispiel]] (fehlt noch)

<div id="image">'''IMAGE'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get an URL from FHEM
|'STATE'
|-
!align="right" |data-size
|width of the image in px or %, the height scales proportionally
|50%
|-
!align="right" |data-url
|URL of the image to show (use data-url or data-device + data-get, not both)
|
|-
!align="right" |data-refresh
|Interval in seconds for image refresh for usage together with data-url
|900
|-
|}

[[#Beispiel_image|Link zu einem Beispiel]]

<div id="label">'''LABEL'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|
|-
!align="right" |data-fix
|keeping a specified number of decimals.
|'-1' -> non-numeric
|-
!align="right" |data-part
|split position of the space separated value to show or an RegEx
|
|-
!align="right" |data-colors
|a array of color values to affect the colour of the label according to the limit value
|
|-
!align="right" |data-limits
|a array of numeric values to affect the colour of the Label
|
|-
!align="right" |data-unit
|add a unit after a numeric value. use encoded strings e.g. "%B0C%0A"
|
|-
!align="right" |class
|small, large, big, bigger, thin, red, green, blue, darker
|
|}

[[#Beispiel_label|Link zu einem Beispiel]]

<div id="level">'''LEVEL'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-min
|minimal value to set
|'0'
|-
!align="right" |data-max
|maximal value to set
|'100'
|-
!align="right" |data-on
|value where the slider moves to max
|'on'
|-
!align="right" |data-off
|value where the slider moves to min
|'off'
|-
!align="right" |data-colors
|a array of color values to affect the colour of the label according to the limit value
|
|-
!align="right" |data-limits
|a array of numeric or RegEx values to affect the colour of the label
|
|-
!align="right" |class
|mini, horizontal
|
|-
|}

[[#Beispiel_level|Link zu einem Beispiel]] (fehlt noch)

<div id="pagetab">'''PAGETAB'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-url
|URL of the new page to show
|
|-
!align="right" |data-icon
|name of the font-awesome icon
|'fa-power-off'
|-
!align="right" |data-background-icon
|name of the font-awesome icon for background
|''
|-
!align="right" |data-on-background-color
|color of ON state
|'#aa6900'
|-
!align="right" |data-off-background-color
|color of OFF state
|'#505050'
|-
!align="right" |data-on-color
|color of ON state
|'#aa6900'
|-
!align="right" |data-off-color
|color of Off state
|'#505050'
|-
!align="right" |data-get-on
|array of status to assign a special icon-list from data-icons
|
|-
!align="right" |data-icons
|array of icons related to the a data-get-on array
|
|-
!align="right" |class
|warn, activate (as additionals for data-icons)
|
|-
|}

[[#Beispiel_pagetab|Link zu einem Beispiel]]

<div id="playstream">'''PLAYSTREAM'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-url
|URL des Radio-Streams
|-
|}

[[#Beispiel_playstream|Link zu einem Beispiel]]

<div id="push">'''PUSH'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default-Wert
|-
!align="right" |data-set
|value to send to FHEM (<command> <device> <value>)
|
|-
!align="right" |data-set-on
|value to send when the the button get pressed.
|
|-

!align="right" |data-icon
|name of the font-awesome icon
|
|-
!align="right" |data-background-icon
|name of the font-awesome icon for background
|'fa-circle'
|-
!align="right" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-doubleclick
|timeout to wait for a second click or touch. '0' disables the doubleclick feature.
|0
|-
!align="right" |data-countdown
|secondes for the countdown progress control
|autodetect from 'on-for-timer' command
|-
|}

[[#Beispiel_push|Link zu einem Beispiel]]

<div id="rotor">'''ROTOR'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" | data-delay
|time in millisecondes to wait until next list item get shown
|3500
|-
!align="right" |class
|fade, rotate
|''
|-
|}
Ohne Angabe von class erfolgt keine Animation.

[[#Beispiel_rotor|Link zu einem Beispiel]]

<div id="select">'''SELECT'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading that get the selected item of the list
|
|-
!align="right" |data-set
|name of the reading to set on FHEM (<command> <device> <reading> <value>)
|''
|-
!align="right" |data-list
|name of the reading to get a :-separated list from FHEM
|''
|-
!align="right" |data-items
|an array of fix items to show in the selection box (alternative if data-list is empty)
|
|-
!align="right" |data-alias
|an array of fix names to show only in the selection box as an alias to the real items
|
|-
!align="right" |data-cmd
|name of the command to send to FHEM (<command> <device> <reading> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-quote
|characters to enclose the send value
|
|-
!align="right" |class
|wider, w1x, w2x, w3x, large, big
|
|-
|}

[[#Beispiel_select|Link zu einem Beispiel]]

<div id="slider">'''SLIDER'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-set
|command to send to FHEM (<code>set <device> <command> <value></code>)
|''
|-
!align="right" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-min
|minimal value to set
|0
|-
!align="right" |data-max
|maximal value to set
|100
|-
!align="right" |data-on
|value where the slider moves to max
|'on'
|-
!align="right" |data-off
|value where the slider moves to min
|'off'
|-
!align="right" |data-value
|wenn true wird beim sliden der Wert angezeigt
|
|-
!align="right" |data-width
|width for horizontal sliders
|'120px', for mini '60px'
|-
!align="right" |data-height
|height for vertical sliders
|'120px', for mini '60px'
|-
!align="right" |class
|Aussehen/Ausrichtung
|
|-
|}

Für class steht mini, horizontal und negated (0 liegt oben) zur Verfügung.

[[#Beispiel_slider|Link zu einem Beispiel]]

<div id="switch">'''SWITCH'''</div>

{| class="wikitable"
!HTML-Attribut
!Beschreibung
!Default-Wert
|-
!align="right" |data-get
|Name des Reading, was gelesen werden soll
|'STATE'
|-
!align="right" |data-get-on
|Wert, bei dem zum Status ON geschaltet werden soll.
|'on'
|-
!align="right" |data-get-off
|Wert, bei dem zum Status OFF geschaltet werden soll.
|'off'
|-
!align="right" |data-set-on
|Wert, der zu FHEM gesendet werden soll, wenn das Widget auf ON geschaltet wurde
|Wert von data-get-on
|-
!align="right" |data-set-off
|Wert, der zu FHEM gesendet werden soll, wenn das Widget auf OFF geschaltet wurde
|Wert von data-get-off
|-
!align="right" |data-cmd
|Kommando Name (<command> <device> <value>) <br />(z.B setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-icon
|Name des Font-Awesome Icon.
|'fa-lightbulb-o'
|-
!align="right" |data-background-icon
|Name des Font-Awesome Hintergrund Icon.
|'fa-circle'
|-
!align="right" |data-on-color
|Widget Farbe beim Status ON
|'#aa6900'
|-
!align="right" |data-off-color
|Widget Farbe beim Status OFF
|'#505050'
|}

<code>data-get-on</code> and <code>data-get-off</code> accept also RegEx values. e.g. data-get-on="[0-9]{1,3}|on" means set switch on if STATE is a numeric value or 'on'. data-get-off="!on" means accept all but the data-get-on value (negation)

[[#Beispiel_switch|Link zu einem Beispiel]]

<div id="symbol">'''SYMBOL'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|Name des Reading, was gelesen werden soll
|'STATE'
|-
!align="right" |data-get-on
|value for ON status to get or an array of states.
|'open'
|-
!align="right" |data-get-off
|value for OFF status to get.
|'closed'
|-
!align="right" |data-icon
|Name des font-awesome-Symbols
|'ftui-window'
|-
!align="right" |data-background-icon
|Hintergrundsymbol
|''
|-
!align="right" |data-on-background-color
|Farbe für ON-Zustand.
|'#aa6900'
|-
!align="right" |data-off-background-color
|Farbe für ON-Zustand.
|'#505050'
|-
!align="right" |data-on-color
|Farbe für ON-Zustand.
|'#aa6900'
|-
!align="right" |data-off-color
|Farbe für ON-Zustand.
|'#505050'
|-
!align="right" |data-icons
|Array mit Icons zu data-get-on Array
|
|-
!align="right" |data-on-colors
|array of colors related to the data-get-on array
|''
|-
!align="right" |data-on-background-colors
|array of background-colors related to the data-get-on array
|''
|-
|}

To use multiple icons, data-get-on, data-icons and data-on-colors have to be an array with the same size. The value for one icon can also contain an additional animatation CSS name, e.g. "fa-exclamation-triangle fa-blink" for a blinking symbol. data-get-on and data-get-off accept also RegEx values. The value for one icon can also contain an additional animatation CSS name, e.g. "fa-exclamation-triangle fa-blink" for a blinking symbol

[[#Beispiel_symbol|Link zu einem Beispiel]]

<div id="thermostat">'''THERMOSTAT'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'desired-temp'
|-
!align="right" |data-temp
|reading for measured temperature of thermostates
|'measured-temp'
|-
!align="right" |data-set
|command to send to FHEM (set <device> <command> <value>)
|'desired-temp'
|-
!align="right" |data-valve
|reading for valve position of thermostates
|
|-
!align="right" |data-min
|minimal value to set
| 10
|-
!align="right" |data-max
|maximal value to set
| 30
|-
!align="right" |data-minColor
|Farbe des Keises für Min
| #4477FF
|-
!align="right" |data-maxColor
|Farbe des Kreises für Max, zwischen Min und Max wird linear interpoliert
| #FF0000
|-
!align="right" |data-step
|step size for value adjustment e.g. 0.5
|1
|-
!align="right" |data-bgColor
|Die Farbe der Kreises zwischen den ticks
|'transparent'
|-
!align="right" |data-fgColor
|Die Farbe der zahl im Kreismittelpunkt
|#bbbbbb
|-
!align="right" |data-tkColor
|Die Farbe der ticks
|#696969
|-
|-
!align="right" |data-angleOffset
|Start der ticks im Kreis (in Winkelgraden, 0 = oben)
| -120
|-
!align="right" |data-angleArc
|Bereich der ticks im Kreis (in Winkelgraden)
|240
|-
!align="right" |class
|big, readonly
|
|-
|}

[[#Beispiel_thermostat|Link zu einem Beispiel]]

<div id="volume">'''VOLUME'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-set
|command to send to FHEM (set <device> <command> <value>)
|''
|-
!align="rigth" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-min
|minimal value to set
|0
|-
!align="right" |data-max
|maximal value to set
|70
|-
!align="right" |class
|small, hue-tick, hue-front, hue-back, dim-tick ,dim-front, dim-back
|
|-
|}

[[#Beispiel_volume|Link zu einem Beispiel]] (fehlt noch)

<div id="weather">'''WEATHER'''</div>

{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get the weather literal from FHEM
|'STATE'
|-
!align="right" |data-imageset
|collection of images to display current weather situation. Possible values: 'meteocons', 'kleinklima'
|'meteocons'
|-
!align="right" |data-image-path
|path to the images of the selected imageset
|/images/weather/
|-
|}

[[#Beispiel_weather|Link zu einem Beispiel]]

== Widgets -- Beispiele ==

<div id="Beispiel_circlemenu">'''Circlemenu'''</div>

Cover a lot of other button behind one single button

<pre>
<div class="left">
<div data-type="circlemenu" class="cell circlemenu">
<ul class="menu">
<li><div data-type="push" data-icon="fa-wrench"></div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level -6"
data-icon="">-6</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level -2"
data-icon="">-2</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level 0"
data-icon="">0</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level +3"
data-icon="">2</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level +9"
data-icon="">9</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level +C"
data-icon="">12</div></li>
</ul>
</div>
<div data-type="label" class="cell">Woofer</div>
</div>
</pre>

[[Datei:circlemenu_tabletUI.png]]

<div id="Beispiel_dimmer">'''Dimmer'''</div>

Dimmer Widget Beispiel für Philips Hue

Minimalvariante
<pre>
<div data-type="dimmer" data-device="HUEDevice1"
data-get-on="!off" data-get-off="off"
data-set="pct"</div>
</pre>

Mit Anzeige der Dimstufe
<pre>
<div data-type="dimmer" data-device="HUEDevice1"
data-get="onoff"
data-get-on="1" data-get-off="0"
data-set=""
data-set-on="on" data-set-off="off"
data-dim="pct">
</div>
</pre>

Dimmer Widget für MilightDevice

<pre>
<div data-type="dimmer"
data-device="SonstWas"
data-get="brightness"
data-get-off="0"
data-get-on="[1-9][0-9]*"
data-set-on="on"
data-set-off="off"
data-dim="dim"
data-min="0"
data-max="100"
></div>
</pre>

<div id="Beispiel_image">'''Image'''</div>

Erzeugt ein Widget mit einem Bild aus dem www, das alle 5 Sekunden aktualisiert wird (hier eine Wetterkarte vom DWD).

<pre>
<div data-type="image"
data-size="80%"
data-url="http://www.dwd.de/wundk/wetter/de/Deutschland.jpg"
</div>
</pre>

[[Datei:image_tabletUI.jpg]]

Example for how to add an image to the dashboard which its URL is delivered by a FHEM module like PROPLANTA:

<pre>
<div data-type="image" data-device="Wetter1"
data-get="fc0_weatherDayIcon"
data-size="40px"
class="cell">
</div>
</pre>

<div id="Beispiel_label">'''Label'''</div>

Example for HM-WDS40-TH-I Funk-Temperatur-/Feuchtesensor innen

<pre>
STATE T: 20.0 H: 61
</pre>
<pre>
<div data-type="label" data-device="THSensorWZ"
data-part="2" data-unit="%B0C%0A" class="cell big"></div>
<div data-type="label" class="cell">Temperatur</div>
<div data-type="label" data-device="THSensorWZ" data-part="4"
data-unit="%" class="cell big"></div>
<div data-type="label" class="cell">Luftfeuchte</div>
</pre>

But the same result can reached by getting single readings:
<pre>
humidity 58
temperature 20.1
</pre>

<pre>
<div data-type="label" data-device="THSensorWZ"
data-get="temperature" data-unit="%B0C%0A" class="cell big"></div>
<div data-type="label" class="cell">Temperatur</div>
<div data-type="label" data-device="THSensorWZ"
data-get="humidity" data-unit="%" class="cell big"></div>
<div data-type="label" class="cell">Luftfeuchte</div>
</pre>

Example for how to influence the color of the label according to value limits
<pre>
<div data-type="label"
data-device="OutTemp"
data-limits='[-73,10,23]'
data-colors='["#6699FF","#AA6900","#FF0000"]'
data-unit="%B0C%0A"
class="cell big">
</div>
</pre>

Example for how to create a widget for shutter via push: show state and set up/down
<pre>
<div data-type="switch"
data-device="wzRollo"
data-get-on="up"
data-get-off="down"
data-icon="fa-bars"
class="cell" >
</div>
<div data-type="label"
class="cell">Rollo</div>
</pre>

Example for how to create a label for a time value in short format with usage of RegEx.

<pre>
<div data-type="label"
data-device="dummy1"
data-part="(\d\d\.\d\d\.).*"
class="cell">
</div>
</pre>

Example for how to show two labels in one line.

<pre>
<div class="">
<div type="label" device="OnSunrise" class="inline"></div>bis
<div type="label" device="OnSunset" class="inline"></div>
</div>
</pre>

Beispiel für die Anzeige des UV-Indexes und der Abhängigkeit der anzuzeigenden Farbe.

<pre>
<div data-type="label" class="wider cell bigger" data-device="ProVorhersage"
data-get="fc0_uv"
data-limits="[-2, 2, 5, 7, 10]"
data-colors='["#66FF33","#FFFF00","#FF6600","#FF0000","#993399"]'></div>
<div data-type="label" class="cell" data-device="ProVorhersage" data-get="fc0_date"></div>
<div data-type="label" class="wider cell bigger" data-device="ProVorhersage"
data-get="fc1_uv"
data-limits="[-2, 2, 5, 7, 10]"
data-colors='["#66FF33","#FFFF00","#FF6600","#FF0000","#993399"]'></div>
<div data-type="label" class="cell" data-device="ProVorhersage" data-get="fc1_date"></div>
</pre>

[[Datei:label_tabletUI.jpg]]

<div id="Beispiel_pagetab">'''Pagetab'''</div>

Example for a tab menu to switch smoothly between multiple pages. Multiple pagetabs in a template file: menu.html

<pre>
<html>
<body>
<header>MENU</header>
<div class="cell">
<div data-type="pagetab" data-url="index.html" data-icon="fa-home" class="cell"></div>
<div data-type="pagetab" data-url="index_2.html" data-icon="fa-sliders" class="cell"></div>
<div data-type="pagetab" data-url="index_3.html" data-icon="fa-music" class="cell"></div>
<div data-type="pagetab" data-url="index_4.html" data-icon="fa-hotel" class="cell"></div>
<div data-type="pagetab" data-url="index_5.html" data-icon="fa-music" class="cell"></div>
<div data-type="pagetab" data-url="index_6.html" data-icon="fa-database" class="cell"></div>
<div data-type="pagetab" data-url="index_7.html" data-icon="fa-fax" class="cell"></div>
</div>
</body>
</html>
</pre>

<div id="Beispiel_playstream">'''Playstream'''</div>

Erzeugt einen Knopf zum direkten Abspielen eines Webradio-Streams.

<pre>
<div data-type="playstream" data-url="http://radioeins.de/stream"></div>
<div data-type="label" class="darker">Radio eins</div>
</pre>

<div id="Beispiel_push">'''Push'''</div>

Example for how to create a push button widget to trigger all devices on:

<pre>
<div data-type="push"
data-device="LightAll"
data-cmd="trigger"
data-set="on"
class="cell">
</div>
</pre>

Beispiel für zwei horizontale Buttons:

<pre>
<div class="cell">
<div class="doublebox-h">
<div data-type="push" data-device="Rollo"
data-icon="fa-angle-up" data-background-icon="fa-square-o"
data-set="up">
</div>
<div data-type="push" data-device="Rollo"
data-icon="fa-angle-down" data-background-icon="fa-square-o"
data-set="down">
</div>
</div>
</div>
</pre>

[[Datei:push1.png]]

Beispiel für zwei quadratische vertikale Buttons:

<pre>
<div class="cell">
<div class="doublebox-v">
<div data-type="push" data-device="Rollo"
data-icon="fa-chevron-up" data-background-icon="fa-square-o"
data-set="up">
</div>
<div data-type="push" data-device="Rollo"
data-icon="fa-chevron-down" data-background-icon="fa-square-o"
data-set="down">
</div>
</div>
</div>
</pre>

[[Datei:push2.png]]

<div id="Beispiel_rotor">'''Rotor'''</div>

Example for a rotor widget, which switches between to days of weather forecast

<pre>
<div data-type="rotor" class="fade">
<ul>
<li>
<div data-type="label" class="darker">Heute</div>
<div data-type="weather" data-device="AgroWeather" data-get="fc0_weatherDay" class="big"></div>
<div data-type="label" data-device="AgroWeather" data-get="fc0_weatherDay" class=""></div>
<div data-type="label" data-device="AgroWeather" data-get="fc0_tempMax" data-unit="%B0C%0A" class="large"></div>
</li>
<li>
<div data-type="label" class="darker">Morgen</div>
<div data-type="weather" data-device="AgroWeather" data-get="fc1_weatherDay" class="big"></div>
<div data-type="label" data-device="AgroWeather" data-get="fc1_weatherDay" class=""></div>
<div data-type="label" data-device="AgroWeather" data-get="fc1_tempMax" data-unit="%B0C%0A" class="large"></div>
</li>
</ul>
</div>
</pre>

<div id="Beispiel_select">'''Select'''</div>

Erzeugt zwei Comboboxen zur Auswahl des Eingang eines 2-Zonen-AV-Receivers. Die Liste für Zone2 ist fest, die Liste für Zone1 wird von FHEM übergeben.

<pre>
<div class="cell wider">
<div data-type="label" class="inline wider">Zone2</div>
<div data-type="select" data-device="AvReceiverZ2" data-items='["Airplay","Webradio","BD/DVD","PHONO"]' data-get="input" data-set="input" class="cell w2x" ></div>
<div></div>
<div data-type="label" class="inline">Zone1</div>
<div data-type="select" data-device="AvReceiver" data-list="inputs" data-get="input" data-set="input" class="cell w2x" ></div>
</div>
</pre>

[[Datei:select_tabeltUI.png]]

<div id="Beispiel_slider">'''Slider'''</div>

Slider mit einstellbaren Werten von 10 bis 90:

<pre>
<div data-type="slider"
data-device='Dummy1'
data-min="10"
data-max="90"
class="cell" >
</div>
<div data-type="label" class="cell">Light1</div>
</pre>

[[Datei:slider_tabletUI.png]]

Horizontal angeordneter Slider:

<pre>
<div data-type="slider"
data-device='Dummy1'
data-min="0"
data-max="100"
class="horizontal"
</div>
</pre>

[[Datei:slider_tabletUI2.jpg]]

<div id="Beispiel_switch">'''Switch'''</div>

Schalter. Usage of RegEx pattern for state request:

<pre>
<div data-type="switch" class="cell"
data-device="MILIGHT_Zone1_Wohnzimmer"
data-get-on="on.*"
data-get-off="off"></div>
</pre>

[[Datei:switch.png]]

Beispiel für eine Gruppe von Schaltern, um zwischen vier verschiedenen Werten eines device umzuschalten:

<pre>
<div class="cell left">
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert1).)*"
data-get-on="Wert1" class="cell" ></div>
<div data-type="label" class="cell">Wert1</div>
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert2).)*"
data-get-on="Wert2" class="cell" ></div>
<div data-type="label" class="cell">Wert2</div>
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert3).)*"
data-get-on="Wert3" class="cell" ></div>
<div data-type="label" class="cell">Wert3</div>
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert4).)*"
data-get-on="Wert4" class="cell" ></div>
<div data-type="label" class="cell">Wert4</div>
</div>
</pre>

[[Datei:switch4.png]]

<div id="Beispiel_symbol">'''Symbol'''</div>

Example for a tristate icon

<pre>
<div data-type="symbol" data-device="dummy1"
data-get-on='["wert1","wert2","wert3"]'
data-icons='["fa-arrow-up","fa-user","fa-arrow-down"]'
data-on-colors='["SeaGreen","SlateBlue","IndianRed"]'
class="cell big">
</div>
</pre>

Example for a tristate icon with blink and spin animation

<pre>
<div data-type="symbol" data-device="dummy1"
data-icons='["fa-exclamation-triangle fa-blink","fa-exclamation-circle","fa-cog fa-spin"]'
data-on-colors='["Crimson","GoldenRod","SeaGreen"]'
data-get-on='["Wert1","Wert2","Wert3"]' >
</div>
</pre>

Example for a battery level control with RegEx

<pre>
<div data-type="symbol" data-device="BadHeizung" data-get="batteryLevel"
data-icons='["oa-measure_battery_100","oa-measure_battery_75","oa-measure_battery_50","oa-measure_battery_25","oa-measure_battery_0"]'
data-get-on='["3\\.[0-9]","2\\.[789]","2\\.[456]","2\\.[123]","((2\\.0)|([01]\\.[0-9]))"]'
data-on-colors='["#505050","#505050","#505050","#ad3333","#ad3333"]'>
</div>
</pre>

Example for a battery level control with greater-equal compare and 90° rotated symbols

<pre>
<div data-type="symbol" data-device="BadHeizung" data-get="batteryLevel"
data-icons='["oa-measure_battery_0 fa-rotate-90","oa-measure_battery_25 fa-rotate-90","oa-measure_battery_50 fa-rotate-90","oa-measure_battery_75 fa-rotate-90","oa-measure_battery_0 fa-rotate-90"]'
data-get-on='["0","2","2.4","2.7","3.0"]'
data-on-colors='["#ad3333","#ad3333","#505050","#505050","#505050"]'>
</div>
</pre>

<div id="Beispiel_thermostat">'''Thermostat'''</div>

Configure as data-device='...' that item which delivers temp and desired-temp as reading.

Default parameters are:
<pre>
data-get="desired-temp" data-temp="measured-temp" data-set="desired-temp"
</pre>

Therefor for HomaMatic HM-CC-RT-DN this is sufficient.

<pre>
<div data-type="thermostat" data-device='KH_Clima' class="cell"></div>
</pre>

The long format looks like this:

<pre>
<div data-type="thermostat"
data-device="KH_Clima"
data-get="desired-temp"
data-temp="measured-temp"
class="cell">
</div>
</pre>

Example for MAX!:
<pre>
<div data-type="thermostat" data-device="HZ_Tuer"
data-valve="valveposition"
data-get="desiredTemperature"
data-temp="temperature"
data-set="desiredTemperature"
class="cell">
</div>
</pre>

The wigets will show the valve value only in case of a valid data-valve attribute. The default for data-valve ist null. That means, a empty data-valve attribute hides the valve label for the widget.

[[Datei:thermostat.png]]

<div id="Beispiel_weather">'''Weather'''</div>

Das Widget fügt ein dem Wetter entsprechendes Bild ein. Die Daten können durch FHEM-Module wie PROLANTA, OPENWEATHER und Weather bereitgestellt werden.
Add 'big' or 'bigger' to CSS class to get a bigger weather icon.

Beispiel:
<pre>
<div data-type="weather"
data-device="Weather"
data-get="fc0_weatherDay"
class="cell big">
</div>
</pre>

[[Datei:weather.png]]

== Icon-Konfiguration ==

* Eingebaute Icons: Diese haben das ftui-Präfix. Zurzeit sind folgende verfügbar: ftui-window, ftui-door

* Mehr als 500 Icons von "http://fortawesome.github.io/Font-Awesome/icons" verfügbar. Einfach den Icon-Namen angeben (Suffix "fa-" nicht vergessen, Z.B. <code>data-icon="fa-volume-up"</code>

* Es stehen auch Openautomation Font-Files zur Verfügung. Wer sie nutzen möchte, muss folgende Stylesheets in die index.html hinzufügen.
<pre>
<link rel="stylesheet" href="/fhem/tablet/lib/openautomation.css" />
<link rel="stylesheet" href="/fhem/tablet/lib/fhemSVG.css" />
</pre>

Diese font icons haben das Präfix 'fs-' bzw. 'oa-'.

Beispiel bei einem Schalter:
<pre><div data-type="switch" data-device='dummy1' data-icon="oa-secur_locked"></div></pre>

Und so als großes Symbol:
<pre>
<div data-type="symbol" data-device='dummy1'
data-icon="oa-status_frost"
data-on-color="#bb3232"
data-get-on="on"
data-get-off="!on"
class="bigger">
</div>
</pre>

Die Icons kann man auch etwas dicker darstellen mit den Zusatz bold: <code>data-icon="oa-secur_locked bold"</code>

Die Namen der verfügbaren Icons findet man auch in den CSS Files (openautomation.css / fhemSVG.css)

== Spezial ==
Folgender Befehl setzt einen direkten Befehl an FHEM ab (<code>set dummy1 off</code>):
<pre>
<div onclick="setFhemStatus('set dummy1 off')">All off!</div>
</pre>

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

== Links ==
* [http://forum.fhem.de/index.php/topic,34233.0.html Forums-Beitrag]
* [https://github.com/knowthelist/fhem-tablet-ui Projekt auf Github]
* [http://forum.fhem.de/index.php/topic,37378.0.html User-Demos]
* [https://github.com/ovibox/fhem-ftui-user-demos Download der User-Demo-Dateien]

[[Kategorie:FHEM Frontends]]

FHEM Tablet UI

2015-05-13T13:05:40Z

Nesges: /* Installation */

[[Datei:tablet_ui.png|200px|thumb|right|FHEM Tablet UI]]
FHEM Tablet UI ist ein leichtgewichtiges aber funktionsreiches Framework zum Steuern und Überwachen von in FHEM integrierten Geräten. Zahlreiche Widgets können sehr flexibel und leicht per HTML Code konfiguriert werden.

In dieser Anleitung wird die Installation und Konfiguration des FHEM Tablet UI beschrieben. Beitrag im FHEM-Forum: http://forum.fhem.de/index.php/topic,34233.0.html

{{Todo|alle Widgets hier übernehmen, Übersetzung, weitere Beispiele aus dem Forum einfügen (evtl. mit Link!?)}}

== Voraussetzungen ==
Dieses User Interface für Tablets benötigt <u>keine</u> zusätzliche Frameworks, wie PHP, MySQL oder SmartVisu.

Voraussetzungen ist nur ein Standard-FHEM mit HTTPSRV Modul und ein beliebiger Standard-Browser mit Javascript auf einem beliebigen Betriebssystem oder Webviewcontrol.

Alle nötigen Files sind im Zip-File inklusive, die einfach nur in einem bestimmten Unterordner der FHEM Installation kopiert werden müssen.

== Installation ==
* Dateien herunterladen: https://github.com/knowthelist/fhem-tablet-ui
* einen neuen Ordner 'tablet' im Verzeichnis /<fhem-Pfad>/www erstellen
* alle Dateien und Unterordner nach /<fhem-Pfad>/www/tablet kopieren
* in fhem.cfg folgende Zeile einfügen: <code>define tablet_ui HTTPSRV tablet/index.html ./www/tablet Tablet Frontend</code>
* index-example.html in index.html umbenennen oder eine neue index.html erzeugen

Das UI ist über "http://<fhem-url>:8083/fhem/tablet/index.html" zu erreichen.

Weitere verfügbare Plugins: https://github.com/nesges/Widgets-for-fhem-tablet-ui

Alle Widgets (widget_xxx.js) in den js-Ordner kopieren.

== Update ==
Zum Update des UI in der FHEM-Befehlszeile eingeben: <code>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code>
bzw. mit <code>update check https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code> vorher schauen was sich seit dem letzten Download alles geändert hat

== Konfiguration ==
Die Konfiguration der angezeigten Widgets erfolgt in der Datei '''index.html''' im Hauptordner 'tablet'.

'''Metadaten-Konfiguration'''

Refresh sofort, alle 15 Minuten ein voller Refresh (shortpoll) statt alle 30 Sekunden ein voller Refresh
:<code><meta name="longpoll" content="1"></code>

Drag&Drop deaktivieren
:<code><meta name='gridster_disable' content='1'></code>

Toast messages deaktivieren
:<code><meta name='toast' content='1'></code>

Größe des Basis-Rasters (data-sizey=1/data-sizex=1)
:<code><meta name="widget_base_width" content="116"></code>
:<code><meta name="widget_base_height" content="131"></code>

Das Layout und das Aussehen des UI kann durch die Klassen-Attribute beeinflusst werden. Verfügbare Klassen sind:

container, left, right, cell, narrow, darker, big, bigger, small

== CSS Class description ==

Not all widgets support all classes

* readonly : changing of state is not allowed
* wider : 25px extra space for the widget to the top
* narrow : shorter distant to the widget above
* w1x, w2x, w3x : set the widget to a fix width: 1x, 2x, 3x width
* small : font 80% size (label), small diameter for volume widget
* mini : lowest diameter for volume widget
* large : font 150% size
* big : font 200% size
* bigger : font 320% size
* thin : font thin
* darker : forecolor in gray
* hue-tick : draw ticks in color range
* hue-front : draw handle in color range
* hue-back : draw background in color range
* dim-tick : draw ticks in brightness range
* dim-front : draw handle in brightness range
* dim-back : draw background in brightness range
* red : foreground color red
* green : foreground color green
* blue : foreground color blue
* doublebox-v : container to place 2 small widgets (e.g. switch) one above the other
* doublebox-h : container to place 2 small widgets (e.g. switch) side by side
* timestamp : deliver the date time for the reading instead the value
* inline : positioning elements in a row, no line break
* top-space : 15px extra on top (top-space-2x -> 30px; top-space-3x -> 45px)
* left-space : 15px extra on left (left-space-2x -> 30px; left-space-3x -> 45px)
* right-space : 15px extra on right (right-space-2x -> 30px; right-space-3x -> 45px)
* blink : blink animatation for label or symbol widget

== Widgets -- Konfiguration ==

Zurzeit stehen 17 Widgets zur Verfügung:
* circlemenu: Mehrere Widgets hinter einem Widget verborgen
* dimmer: toogle button with a setter for on value
* homestatus: selector for 4 states (1=home, 2=night, 3=away, 4=holiday)
* image: insert an image, the URL is given by a reading
* label: ein state als Text anzeigen (Farbe einstellbar)
* level: vertical/horizontal bar to show values between min/max value
* pagetab: Element to smoothly exchange the whole page with another page
* playstream: Abspielen eines Webradio-Streams per Button
* push: send any command to FHEM e.g. up / down
* rotor: Umschalten von zwei oder mehr Widgets an einer Position
* select: Combobox to provide a list for selection
* slider: vertical slider to select between min/max value
* switch: Toggle any command to FHEM (e.g. on / off)
* symbol: State als Symbol darstellen (z.B. Fenster offen)
* thermostat: dial for heater thermostates to set desired value and show current value
* volume: dial to set a single value (e.g. 0-60)
* weather: insert an icon or image, represending a weather literal

----------------------------------

Für alle Widgets gilt:
{| 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
|}

'''Icon-Konfiguration'''

Mehr als 500 Icons von "http://fortawesome.github.io/Font-Awesome/icons" verfügbar. Einfach den Icon-Namen angeben (Suffix "fa-" nicht vergessen, Z.B. <code>data-icon="fa-volume-up"</code>

Es stehen auch Openautomation Font-Files zur Verfügung. Wer sie nutzen möchte, muss folgende Stylesheets in die index.html hinzufügen.
<pre>
<link rel="stylesheet" href="/fhem/tablet/lib/openautomation.css" />
<link rel="stylesheet" href="/fhem/tablet/lib/fhemSVG.css" />
</pre>

Beispiel bei einem Schalter:
<pre><div data-type="switch" data-device='dummy1' data-icon="oa-secur_locked"></div></pre>

Und so als großes Symbol:
<pre>
<div data-type="symbol" data-device='dummy1'
data-icon="oa-status_frost"
data-on-color="#bb3232"
data-get-on="on"
data-get-off="!on"
class="bigger">
</div>
</pre>

Die Icons kann man auch etwas dicker darstellen mit den Zusatz bold: <code>data-icon="oa-secur_locked bold"</code>

Die Namen der verfügbaren Icons findet man auch in den CSS Files (openautomation.css / fhemSVG.css)

'''CIRCLEMENU'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-item-diameter
|diameter of the circle
|52
|-
!align="right" |data-circle-radius
|radius of each item, in pixel
|70
|-
!align="right" |data-direction
|position of the items in relation to the center
|'full'
|-
!align="right" |data-close-after
|closing time of the circle-menu
|(item-count + 1s) or a minimum of 4s
|-
!align="right" |class
|keepopen
|
|-
|}

Optionen für data-direction: top | right | bottom | left | top-right | top-left | bottom-right | bottom-left | top-half | right-half | bottom-half | left-half | full

'''DIMMER'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-get-on
|value for ON status to get
|'on'
|-
!align="right" |data-get-off
|value for OFF status to get
|'off'
|-
!align="right" |data-set-off
|value for OFF status to set
|value of data-get-off
|-
!align="right" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-set
|command to send to FHEM (<code>set <device> <command> <value></code>)
|''
|-
!align="right" |data-icon
|name of the font-awesome icon
|fa-lightbulb-o
|-
|}

'''HOMESTATUS'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-set
|command to send to FHEM (<code>set <device> <command> <value></code>)
|''
|-
!align="righ" |data-version
|name of the special dummy device to represent
|
|-
|}

<code>data-version=''</code> (default) 4 states are valid: 1,2,3 or 4 (1=home, 2=night, 3=away, 4=holiday) data-version='residents' or 'roomate' or 'guest' residents states are valid (absent,gone,asleep,home)

'''IMAGE'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get an URL from FHEM
|'STATE'
|-
!align="right" |data-size
|width of the image in px or %, the height scales proportionally
|50%
|-
!align="right" |data-url
|URL of the image to show (use data-url or data-device + data-get, not both)
|
|-
!align="right" |data-refresh
|Interval in seconds for image refresh for usage together with data-url
|900
|-
|}

'''LABEL'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|
|-
!align="right" |data-fix
|keeping a specified number of decimals.
|'-1' -> non-numeric
|-
!align="right" |data-part
|split position of the space separated value to show or an RegEx
|
|-
!align="right" |data-colors
|a array of color values to affect the colour of the label according to the limit value
|
|-
!align="right" |data-limits
|a array of numeric values to affect the colour of the Label
|
|-
!align="right" |data-unit
|add a unit after a numeric value. use encoded strings e.g. "%B0C%0A"
|
|-
!align="right" |class
|small, large, big, bigger, thin, red, green, blue, darker
|
|}

'''LEVEL'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-min
|minimal value to set
|'0'
|-
!align="right" |data-max
|maximal value to set
|'100'
|-
!align="right" |data-on
|value where the slider moves to max
|'on'
|-
!align="right" |data-off
|value where the slider moves to min
|'off'
|-
!align="right" |data-colors
|a array of color values to affect the colour of the label according to the limit value
|
|-
!align="right" |data-limits
|a array of numeric or RegEx values to affect the colour of the label
|
|-
!align="right" |class
|mini, horizontal
|
|-
|}

'''PAGETAB'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-url
|URL of the new page to show
|
|-
!align="right" |data-icon
|name of the font-awesome icon
|'fa-power-off'
|-
!align="right" |data-background-icon
|name of the font-awesome icon for background
|''
|-
!align="right" |data-on-background-color
|color of ON state
|'#aa6900'
|-
!align="right" |data-off-background-color
|color of OFF state
|'#505050'
|-
!align="right" |data-on-color
|color of ON state
|'#aa6900'
|-
!align="right" |data-off-color
|color of Off state
|'#505050'
|-
|}

'''PLAYSTREAM'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-url
|URL des Radio-Streams
|-
|}

'''PUSH'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default-Wert
|-
!align="right" |data-set
|value to send to FHEM (<command> <device> <value>)
|
|-
!align="right" |data-icon
|name of the font-awesome icon
|
|-
!align="right" |data-background-icon
|name of the font-awesome icon for background
|'fa-circle'
|-
!align="right" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
|}

'''ROTOR'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" | data-delay
|time in millisecondes to wait until next list item get shown
|3500
|-
!align="right" |class
|fade, rotate
|''
|-
|}
Ohne Anagbe von class erfolgt keine Animation.

'''SELECT'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading that get the selected item of the list
|
|-
!align="right" |data-set
|name of the reading to set on FHEM (<command> <device> <reading> <value>)
|''
|-
!align="right" |data-list
|name of the reading to get a :-separated list from FHEM
|''
|-
!align="right" |data-items
|a array of fix items to show in the selection box (alternative if data-list is empty)
|
|-
!align="right" |data-cmd
|name of the command to send to FHEM (<command> <device> <reading> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |class
|wider, w1x, w2x, w3x
|
|-
|}

'''SLIDER'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-set
|command to send to FHEM (<code>set <device> <command> <value></code>)
|''
|-
!align="right" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-min
|minimal value to set
|0
|-
!align="right" |data-max
|maximal value to set
|100
|-
!align="right" |data-on
|value where the slider moves to max
|'on'
|-
!align="right" |data-off
|value where the slider moves to min
|'off'
|-
!align="right" |class
|Aussehen/Ausrichtung
|
|-
|}

Für class steht mini und horizontal zur Verfügung.

'''SWITCH'''
{| class="wikitable"
!HTML-Attribut
!Beschreibung
!Default-Wert
|-
!align="right" |data-get
|Name des Reading, was gelesen werden soll
|'STATE'
|-
!align="right" |data-get-on
|Wert, bei dem zum Status ON geschaltet werden soll.
|'on'
|-
!align="right" |data-get-off
|Wert, bei dem zum Status OFF geschaltet werden soll.
|'off'
|-
!align="right" |data-set-on
|Wert, der zu FHEM gesendet werden soll, wenn das Widget auf ON geschaltet wurde
|Wert von data-get-on
|-
!align="right" |data-set-off
|Wert, der zu FHEM gesendet werden soll, wenn das Widget auf OFF geschaltet wurde
|Wert von data-get-off
|-
!align="right" |data-cmd
|Kommando Name (<command> <device> <value>) <br />(z.B setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-icon
|Name des Font-Awesome Icon.
|'fa-lightbulb-o'
|-
!align="right" |data-background-icon
|Name des Font-Awesome Hintergrund Icon.
|'fa-circle'
|-
!align="right" |data-on-color
|Widget Farbe beim Status ON
|'#aa6900'
|-
!align="right" |data-off-color
|Widget Farbe beim Status OFF
|'#505050'
|}

<code>data-get-on</code> and <code>data-get-off</code> accept also RegEx values. e.g. data-get-on="[0-9]{1,3}|on" means set switch on if STATE is a numeric value or 'on'. data-get-off="!on" means accept all but the data-get-on value (negation)

'''SYMBOL'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|Name des Reading, was gelesen werden soll
|'STATE'
|-
!align="right" |data-get-on
|value for ON status to get or an array of states.
|'open'
|-
!align="right" |data-get-off
|value for OFF status to get.
|'closed'
|-
!align="right" |icon
|Name des font-awesome-Symbols
|
|-
!align="right" |data-background-icon
|Hintergrundsymbol
|''
|-
!align="right" |data-on-color
|Farbe für ON-Zustand.
|'#aa6900'
|-
!align="right" |data-off-color
|Farbe für OFF-Zustand.
|'#505050'
|-
!align="right" |data-on-colors
|Name des Font-Awesome Hintergrund Icon.
|'fa-circle'
|-
!align="right" |data-on-color
|array of colors related to the data-get-on array
|''
|-
|}

To use multiple icons, data-get-on, data-icons and data-on-colors have to be an array with the same size. The value for one icon can also contain an additional animatation CSS name, e.g. "fa-exclamation-triangle fa-blink" for a blinking symbol.

'''THERMOSTAT'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'desired-temp'
|-
!align="right" |data-temp
|reading for measured temperature of thermostates
|'measured-temp'
|-
!align="right" |data-set
|command to send to FHEM (set <device> <command> <value>)
|'desired-temp'
|-
!align="right" |data-valve
|reading for valve position of thermostates
|
|-
!align="right" |data-min
|minimal value to set
| 10
|-
!align="right" |data-max
|maximal value to set
| 30
|-
!align="right" |data-minColor
|Farbe des Keises für Min
| #4477FF
|-
!align="right" |data-maxColor
|Farbe des Kreises für Max, zwischen Min und Max wird linear interpoliert
| #FF0000
|-
!align="right" |data-step
|step size for value adjustment e.g. 0.5
|1
|-
!align="right" |data-bgColor
|Die Farbe der Kreises zwischen den ticks
|'transparent'
|-
!align="right" |data-fgColor
|Die Farbe der zahl im Kreismittelpunkt
|#bbbbbb
|-
!align="right" |data-tkColor
|Die Farbe der ticks
|#696969
|-
|-
!align="right" |data-angleOffset
|Start der ticks im Kreis (in Winkelgraden, 0 = oben)
| -120
|-
!align="right" |data-angleArc
|Bereich der ticks im Kreis (in Winkelgraden)
|240
|-
!align="right" |class
|big, readonly
|
|-
|}

'''VOLUME'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get from FHEM
|'STATE'
|-
!align="right" |data-set
|command to send to FHEM (set <device> <command> <value>)
|''
|-
!align="rigth" |data-cmd
|name of the command (<command> <device> <value>) (e.g. setstate, set, setreading, trigger)
|'set'
|-
!align="right" |data-min
|minimal value to set
|0
|-
!align="right" |data-max
|maximal value to set
|70
|-
!align="right" |class
|small, hue-tick, hue-front, hue-back, dim-tick ,dim-front, dim-back
|
|-
|}

'''WEATHER'''
{| class="wikitable"
!HTML Attribut
!Beschreibung
!Default Wert
|-
!align="right" |data-get
|name of the reading to get the weather literal from FHEM
|'STATE'
|-
!align="right" |data-imageset
|collection of images to display current weather situation. Possible values: 'meteocons', 'kleinklima'
|'meteocons'
|-
!align="right" |data-image-path
|path to the images of the selected imageset
|/images/weather/
|-
|}

== Widgets -- Beispiele ==

'''Circlemenu'''

Cover a lot of other button behind one single button

<pre>
<div class="left">
<div data-type="circlemenu" class="cell circlemenu">
<ul class="menu">
<li><div data-type="push" data-icon="fa-wrench"></div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level -6"
data-icon="">-6</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level -2"
data-icon="">-2</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level 0"
data-icon="">0</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level +3"
data-icon="">2</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level +9"
data-icon="">9</div></li>
<li><div data-type="push" data-device="AvReceiver"
data-set="remoteControl subwoofer-temporary-level +C"
data-icon="">12</div></li>
</ul>
</div>
<div data-type="label" class="cell">Woofer</div>
</div>
</pre>

[[Datei:circlemenu_tabletUI.png]]

'''Image'''

Erzeugt ein Widget mit einem Bild aus dem www, das alle 5 Sekunden aktualisiert wird (hier eine Wetterkarte vom DWD).

<pre>
<div data-type="image"
data-size="80%"
data-url="http://www.dwd.de/wundk/wetter/de/Deutschland.jpg"
</div>
</pre>

[[Datei:image_tabletUI.jpg]]

Example for how to add an image to the dashboard which its URL is delivered by a FHEM module like PROPLANTA:

<pre>
<div data-type="image" data-device="Wetter1"
data-get="fc0_weatherDayIcon"
data-size="40px"
class="cell">
</div>
</pre>

'''Label'''

Example for HM-WDS40-TH-I Funk-Temperatur-/Feuchtesensor innen

<pre>
STATE T: 20.0 H: 61
</pre>
<pre>
<div data-type="label" data-device="THSensorWZ"
data-part="2" data-unit="%B0C%0A" class="cell big"></div>
<div data-type="label" class="cell">Temperatur</div>
<div data-type="label" data-device="THSensorWZ" data-part="4"
data-unit="%" class="cell big"></div>
<div data-type="label" class="cell">Luftfeuchte</div>
</pre>

But the same result can reached by getting single readings:
<pre>
humidity 58
temperature 20.1
</pre>

<pre>
<div data-type="label" data-device="THSensorWZ"
data-get="temperature" data-unit="%B0C%0A" class="cell big"></div>
<div data-type="label" class="cell">Temperatur</div>
<div data-type="label" data-device="THSensorWZ"
data-get="humidity" data-unit="%" class="cell big"></div>
<div data-type="label" class="cell">Luftfeuchte</div>
</pre>

Example for how to influence the color of the label according to value limits
<pre>
<div data-type="label"
data-device="OutTemp"
data-limits='[-73,10,23]'
data-colors='["#6699FF","#AA6900","#FF0000"]'
data-unit="%B0C%0A"
class="cell big">
</div>
</pre>

Example for how to create a widget for shutter via push: show state and set up/down
<pre>
<div data-type="switch"
data-device="wzRollo"
data-get-on="up"
data-get-off="down"
data-icon="fa-bars"
class="cell" >
</div>
<div data-type="label"
class="cell">Rollo</div>
</pre>

Example for how to create a label for a time value in short format with usage of RegEx.

<pre>
<div data-type="label"
data-device="dummy1"
data-part="(\d\d\.\d\d\.).*"
class="cell">
</div>
</pre>

Example for how to show two labels in one line.

<pre>
<div class="">
<div type="label" device="OnSunrise" class="inline"></div>bis
<div type="label" device="OnSunset" class="inline"></div>
</div>
</pre>

Beispiel für die Anzeige des UV-Indexes und der Abhängigkeit der anzuzeigenden Farbe.

<pre>
<div data-type="label" class="wider cell bigger" data-device="ProVorhersage"
data-get="fc0_uv"
data-limits="[-2, 2, 5, 7, 10]"
data-colors='["#66FF33","#FFFF00","#FF6600","#FF0000","#993399"]'></div>
<div data-type="label" class="cell" data-device="ProVorhersage" data-get="fc0_date"></div>
<div data-type="label" class="wider cell bigger" data-device="ProVorhersage"
data-get="fc1_uv"
data-limits="[-2, 2, 5, 7, 10]"
data-colors='["#66FF33","#FFFF00","#FF6600","#FF0000","#993399"]'></div>
<div data-type="label" class="cell" data-device="ProVorhersage" data-get="fc1_date"></div>
</pre>

[[Datei:label_tabletUI.jpg]]

'''Pagetab'''

Example for a tab menu to switch smoothly between multiple pages. Multiple pagetabs in a template file: menu.html

<pre>
<html>
<body>
<header>MENU</header>
<div class="cell">
<div data-type="pagetab" data-url="index.html" data-icon="fa-home" class="cell"></div>
<div data-type="pagetab" data-url="index_2.html" data-icon="fa-sliders" class="cell"></div>
<div data-type="pagetab" data-url="index_3.html" data-icon="fa-music" class="cell"></div>
<div data-type="pagetab" data-url="index_4.html" data-icon="fa-hotel" class="cell"></div>
<div data-type="pagetab" data-url="index_5.html" data-icon="fa-music" class="cell"></div>
<div data-type="pagetab" data-url="index_6.html" data-icon="fa-database" class="cell"></div>
<div data-type="pagetab" data-url="index_7.html" data-icon="fa-fax" class="cell"></div>
</div>
</body>
</html>
</pre>

'''Playstream'''

Erzeugt einen Knopf zum direkten Abspielen eines Webradio-Streams.

<pre>
<div data-type="playstream" data-url="http://radioeins.de/stream"></div>
<div data-type="label" class="darker">Radio eins</div>
</pre>

'''Push'''

Example for how to create a push button widget to trigger all devices on:

<pre>
<div data-type="push"
data-device="LightAll"
data-cmd="trigger"
data-set="on"
class="cell">
</div>
</pre>

Beispiel für zwei horizontale Buttons:

<pre>
<div class="cell">
<div class="doublebox-h">
<div data-type="push" data-device="Rollo"
data-icon="fa-angle-up" data-background-icon="fa-square-o"
data-set="up">
</div>
<div data-type="push" data-device="Rollo"
data-icon="fa-angle-down" data-background-icon="fa-square-o"
data-set="down">
</div>
</div>
</div>
</pre>

[[Datei:push1.png]]

Beispiel für zwei quadratische vertikale Buttons:

<pre>
<div class="cell">
<div class="doublebox-v">
<div data-type="push" data-device="Rollo"
data-icon="fa-chevron-up" data-background-icon="fa-square-o"
data-set="up">
</div>
<div data-type="push" data-device="Rollo"
data-icon="fa-chevron-down" data-background-icon="fa-square-o"
data-set="down">
</div>
</div>
</div>
</pre>

[[Datei:push2.png]]

'''Rotor'''

Example for a rotor widget, which switches between to days of weather forecast

<pre>
<div data-type="rotor" class="fade">
<ul>
<li>
<div data-type="label" class="darker">Heute</div>
<div data-type="weather" data-device="AgroWeather" data-get="fc0_weatherDay" class="big"></div>
<div data-type="label" data-device="AgroWeather" data-get="fc0_weatherDay" class=""></div>
<div data-type="label" data-device="AgroWeather" data-get="fc0_tempMax" data-unit="%B0C%0A" class="large"></div>
</li>
<li>
<div data-type="label" class="darker">Morgen</div>
<div data-type="weather" data-device="AgroWeather" data-get="fc1_weatherDay" class="big"></div>
<div data-type="label" data-device="AgroWeather" data-get="fc1_weatherDay" class=""></div>
<div data-type="label" data-device="AgroWeather" data-get="fc1_tempMax" data-unit="%B0C%0A" class="large"></div>
</li>
</ul>
</div>
</pre>

'''Select'''

Erzeugt zwei Comboboxen zur Auswahl des Eingang eines 2-Zonen-AV-Receivers. Die Liste für Zone2 ist fest, die Liste für Zone1 wird von FHEM übergeben.

<pre>
<div class="cell wider">
<div data-type="label" class="inline wider">Zone2</div>
<div data-type="select" data-device="AvReceiverZ2" data-items='["Airplay","Webradio","BD/DVD","PHONO"]' data-get="input" data-set="input" class="cell w2x" ></div>
<div></div>
<div data-type="label" class="inline">Zone1</div>
<div data-type="select" data-device="AvReceiver" data-list="inputs" data-get="input" data-set="input" class="cell w2x" ></div>
</div>
</pre>

[[Datei:select_tabeltUI.png]]

'''Slider'''

Slider mit einstellbaren Werten von 10 bis 90:

<pre>
<div data-type="slider"
data-device='Dummy1'
data-min="10"
data-max="90"
class="cell" >
</div>
<div data-type="label" class="cell">Light1</div>
</pre>

[[Datei:slider_tabletUI.png]]

Horizontal angeordneter Slider:

<pre>
<div data-type="slider"
data-device='Dummy1'
data-min="0"
data-max="100"
class="horizontal"
</div>
</pre>

[[Datei:slider_tabletUI2.jpg]]

'''Switch'''

Schalter. Usage of RegEx pattern for state request:

<pre>
<div data-type="switch" class="cell"
data-device="MILIGHT_Zone1_Wohnzimmer"
data-get-on="on.*"
data-get-off="off"></div>
</pre>

[[Datei:switch.png]]

Beispiel für eine Gruppe von Schaltern, um zwischen vier verschiedenen Werten eines device umzuschalten:

<pre>
<div class="cell left">
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert1).)*"
data-get-on="Wert1" class="cell" ></div>
<div data-type="label" class="cell">Wert1</div>
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert2).)*"
data-get-on="Wert2" class="cell" ></div>
<div data-type="label" class="cell">Wert2</div>
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert3).)*"
data-get-on="Wert3" class="cell" ></div>
<div data-type="label" class="cell">Wert3</div>
<div data-type="switch" data-device="dummy1"
data-get-off="((?!Wert4).)*"
data-get-on="Wert4" class="cell" ></div>
<div data-type="label" class="cell">Wert4</div>
</div>
</pre>

[[Datei:switch4.png]]

'''Symbol'''

Example for a tristate icon

<pre>
<div data-type="symbol" data-device="dummy1"
data-get-on='["wert1","wert2","wert3"]'
data-icons='["fa-arrow-up","fa-user","fa-arrow-down"]'
data-on-colors='["SeaGreen","SlateBlue","IndianRed"]'
class="cell big">
</div>
</pre>

Example for a tristate icon with blink and spin animation

<pre>
<div data-type="symbol" data-device="dummy1"
data-icons='["fa-exclamation-triangle fa-blink","fa-exclamation-circle","fa-cog fa-spin"]'
data-on-colors='["Crimson","GoldenRod","SeaGreen"]'
data-get-on='["Wert1","Wert2","Wert3"]' >
</div>
</pre>

Example for a battery level control with RegEx

<pre>
<div data-type="symbol" data-device="BadHeizung" data-get="batteryLevel"
data-icons='["oa-measure_battery_100","oa-measure_battery_75","oa-measure_battery_50","oa-measure_battery_25","oa-measure_battery_0"]'
data-get-on='["3\\.[0-9]","2\\.[789]","2\\.[456]","2\\.[123]","((2\\.0)|([01]\\.[0-9]))"]'
data-on-colors='["#505050","#505050","#505050","#ad3333","#ad3333"]'>
</div>
</pre>

Example for a battery level control with greater-equal compare and 90° rotated symbols

<pre>
<div data-type="symbol" data-device="BadHeizung" data-get="batteryLevel"
data-icons='["oa-measure_battery_0 fa-rotate-90","oa-measure_battery_25 fa-rotate-90","oa-measure_battery_50 fa-rotate-90","oa-measure_battery_75 fa-rotate-90","oa-measure_battery_0 fa-rotate-90"]'
data-get-on='["0","2","2.4","2.7","3.0"]'
data-on-colors='["#ad3333","#ad3333","#505050","#505050","#505050"]'>
</div>
</pre>

'''Thermostat'''

Configure as data-device='...' that item which delivers temp and desired-temp as reading.

Default parameters are:
<pre>
data-get="desired-temp" data-temp="measured-temp" data-set="desired-temp"
</pre>

Therefor for HomaMatic HM-CC-RT-DN this is sufficient.

<pre>
<div data-type="thermostat" data-device='KH_Clima' class="cell"></div>
</pre>

The long format looks like this:

<pre>
<div data-type="thermostat"
data-device="KH_Clima"
data-get="desired-temp"
data-temp="measured-temp"
class="cell">
</div>
</pre>

Example for MAX!:
<pre>
<div data-type="thermostat" data-device="HZ_Tuer"
data-valve="valveposition"
data-get="desiredTemperature"
data-temp="temperature"
data-set="desiredTemperature"
class="cell">
</div>
</pre>

The wigets will show the valve value only in case of a valid data-valve attribute. The default for data-valve ist null. That means, a empty data-valve attribute hides the valve label for the widget.

[[Datei:thermostat.png]]

'''Weather'''

Das Widget fügt ein dem Wetter entsprechendes Bild ein. Die Daten können durch FHEM-Module wie PROLANTA, OPENWEATHER und Weather bereitgestellt werden.
Add 'big' or 'bigger' to CSS class to get a bigger weather icon.

Beispiel:
<pre>
<div data-type="weather"
data-device="Weather"
data-get="fc0_weatherDay"
class="cell big">
</div>
</pre>

[[Datei:weather.png]]

== Spezial ==
Folgender Befehl setzt einen direkten Befehl an FHEM ab (<code>set dummy1 off</code>):
<pre>
<div onclick="setFhemStatus('set dummy1 off')">All off!</div>
</pre>

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

== Links ==
* [http://forum.fhem.de/index.php/topic,34233.0.html Forums-Beitrag]
* [https://github.com/knowthelist/fhem-tablet-ui Projekt auf Github]

[[Kategorie:FHEM Frontends]]

FHEM Tablet UI FAQ

2015-05-13T13:04:31Z

Nesges: /* Warum führen mich Links auf andere Seiten zurück zu FHEMWEB? */

==Das UI zeigt Statusänderungen erst nach 30s==

Sehr wahrscheinlich hast du die Aktualisierungsmethode '''longPoll''' deaktiviert. Es gibt zwei Aktualisierungsmethoden: shortPoll und longPoll.

'''shortPoll''' aktualisiert den Status aller Widgets auf einmal. Bei aktivem longPoll ist das shortPoll-Interval mit 15 Minuten festgelegt, ansonsten mit 30 Sekunden. shortPoll kann nicht deaktiviert werden.

'''longPoll''' benutzt den eventgesteuerten Benachrichtigungsdienst von fhem um Statusänderungen direkt zu aktualisieren. Das heisst, fhem sendet eine Nachricht per longPoll sobald sich ein Status ändert und das UI aktualisiert daraufhin automatisch nur die betroffenen Widgets. longPoll ist in fhem standardmäßig aktiv, kann aber deaktiviert werden. Im Zweifel bitte prüfen ob an der verwendeten [[FHEMWEB]]-Instanz das Attribut "longpoll 1" gesetzt ist (`list WEB`). Falls nicht, bitte `attr WEB longpoll 1` in fhem ausführen ("WEB" ist ggf. durch den Namen der verwendeten [[FHEMWEB]]-Instanz zu ersetzen). Im UI ist longPoll ebenfalls standardmäßig aktiv, kann aber ebenfalls deaktiviert werden. Bitte prüfen, ob der HTML-Code den Meta-Tag `<meta name="longpoll" content="1">` enthält. Falls nicht, bitte so übernehmen.

==Das UI zeigt Statusänderungen gar nicht an==

Prüfe zunächst, ob die Statusänderungen nicht vielleicht nur verspätet kommen (siehe FAQ [[#Das UI zeigt Statusänderungen erst nach 30s|Das UI zeigt Statusänderungen erst nach 30s]]). Wenn tatsächlich keine Statusänderungen im UI ankommen, sind die Werte der data-get-on/off Attribute vermutlich falsch gesetzt. Prüfe im [[Event_monitor]] welche Werte die Events, die bei Statusänderungen erzeugt werden, genau haben und passe deine Attribute entsprechend an. Manchmal weichen die erzeugten Events von den Namen der zugehörigen Readings ab. Sollten allerdings gar keine Events erzeugt werden (manche Module erzeugen nicht für jede Readingsänderung ein Event), dann kann die longPoll-Aktualisierung für diese Statusänderung nicht funktionieren.

==Wie öffne ich die Javascript-Konsole?==

"FHEM Tablet UI" benutzt Javascript und um Fehlermeldungen nachvollziehen zu können ist es oft erforderlich Informationen aus der "Javascript Konsole" des Browsers zu posten. Je nach Browser wird die Konsole mit einer anderen Tastenkombination geöffnet:

{| class="wikitable"
|-
! Browser
! Tastenkombination
|-
|Chrome:
|{{Taste|Ctrl}} + {{Taste|Shift}} + {{Taste|J}}
|-
|Firefox:
|{{Taste|Ctrl}} + {{Taste|Shift}} + {{Taste|K}}
|-
|Internet Explorer:
|{{Taste|F12}}
|-
|Opera:
|{{Taste|Ctrl}} + {{Taste|Shift}} + {{Taste|I}}
|-
|Safari:
|{{Taste|Cmd}} + {{Taste|Opt}} + {{Taste|C}}
|}

==Wie kann ich eigene Icons verwenden?==

Die Button-ähnlichen Widgets (switch, push, symbol etc.) verwenden Fonts um Icons anzuzeigen. Standardmässig wird der Font [http://fortawesome.github.io/Font-Awesome/ Font-Awesome] mitgeliefert, der mehr als [http://fortawesome.github.io/Font-Awesome/icons/ 500 Icons] mitbringt. Wenn diese Auswahl nicht ausreichend ist, kann ein eigener Iconfont eingebunden werden. Am einfachsten kann ein solcher Font mit Hilfe der [https://icomoon.io/app IcoMoon App] erstellt werden.

===IcoMoon App===

IcoMoon bietet verschiedene Icon-Libraries aus denen gewählt werden kann. Viele davon sind unter kostenlosen Lizenzen verfügbar, die App weist transparent darauf hin, wenn man eine (bzw. aus einer) nicht kostenfreien Library auswählt. Standardmässig wird die Library "IcoMoon Free" angeboten, weitere können über den Button "Add Icons From Library" ausgewählt werden. Zielführender ist das "search" Feld oben zu verwenden. Die Icons aller Libraries sind verschlagwortet und über das Suchfeld findbar. Darüber hinaus können eigene Grafiken hochgeladen werden ("Import Icons"), diese müssen im SVG-Format vorliegen.

Nach abgeschlossener Icon-Auswahl wird über den großen Button "Generate Font" (unten) ein Font erstellt. Dazu sollte zunächst oben unter "Preferences" ein Font Name (zB "Font 1") und ein eindeutiger Class-Prefix (zB "font1-") gewählt werden. Insbesondere der Class-Prefix ist wichtig und sollte nicht zu lang ausfallen. Er wird bei der Benutzung der Icons dem Icon-Namen vorangestellt. Das Class-Prefix des mitgelieferten Font-Awesome lautet "fa-". Danach kann der Font über den Button "Download" herunter geladen werden.

===Nachbearbeitung===

Im heruntergeladenen Zip-file aus der IcoMoon App muss die Zeile

line-height: 1;

auskommentiert oder gelöscht werden, da die Anzeige in den Buttons ansonsten "verschoben" wirkt.

===In FTUI einbinden===

Der gesamte Inhalt des Ziparchivs kann jetzt in ein eigenes Verzeichnis innerhalb der Fhem Tablet UI Installation kopiert werden, zB nach "customfonts/font1". Es sollte nicht in eines der Standardverzeichnisse kopiert werden, da dort die Gefahr besteht, dass die Dateien vom Updatemechanismus überschrieben werden. In der/den HTML-File(s) ist jetzt im <head>-Bereich noch der Pfad zur style.css aus dem Archiv anzugeben:

<link rel="stylesheet" href="customfonts/font1/style.css">

===Verwenden===

Jetzt können die eigenen Icons in den Widgets verwendet werden, indem sie im Attribut data-icon (bzw. data-icons, data-background-icon..) eingetragen werden; zB:

<div data-type="push" data-device="WECKER" data-icon="font1-alarmclock"></div>

Wichtig: Daran denken vor dem Namen des Icons das selbst gewählte Class-Prefix (hier "font1-") zu notieren.

==Warum führen mich Links auf andere Seiten zurück zu FHEMWEB?==

Zur Auslieferung des FTUI an den Browser wird das Modul [http://fhem.de/commandref.html#HTTPSRV HTTPSRV] verwendet. Leider zeigt es ein seltsames Verhalten, wenn man ausgehend von einer Adresse ohne abschliessenden Slash oder Dateinamen auf einen Link mit relativem URL (also zB nur ein Dateiname) klickt. Der relative Pfad wird in so einem Fall ab dem letzten Slash der Adresse der Ausgangsseite ermittelt.

Ein Beispiel: Wir starten bei ''<nowiki>http://host:8083/fhem/tablet</nowiki>'' und klicken auf einen Link zur Datei ''wohnzimmer.html''. Dieser Klick wird '''nicht''' auf ''<nowiki>http://host:8083/fhem/tablet/wohnzimmer.html</nowiki>'' geleitet, sondern zu ''<nowiki>http://host:8083/fhem/wohnzimmer.html</nowiki>''. Da es ''<nowiki>http://host:8083/fhem/wohnzimmer.html</nowiki>'' nicht gibt, wird man darauf postwendend zu ''<nowiki>http://host:8083/fhem</nowiki>'' gebracht. Startet man den gleichen Vorgang ausgehend von ''<nowiki>http://host:8083/fhem/tablet/</nowiki>'' (mit Slash am Ende), wird man wie erwartet nach ''<nowiki>http://host:8083/fhem/tablet/wohnzimmer.html</nowiki>'' gebracht.

Darüber hinaus kann die Startseite - typischerweise index.html - nicht gefunden werden, wenn ein abschliessender Slash, aber kein Dateiname notiert wird.

Es sollte also insbesondere in der Definition des Links für FHEMWEB darauf geachtet werden, den vollen Pfad zur Startseite zu notieren (<code>define tablet_ui HTTPSRV tablet/index.html ./www/tablet Tablet Frontend</code>). Das gleiche beim Anlegen von Lesezeichen.

[[Kategorie: FAQ]]

FHEM Tablet UI FAQ

2015-04-23T20:36:37Z

Nesges: Warum führen mich Links auf andere Seiten zurück zu FHEMWEB?

==Das UI zeigt Statusänderungen erst nach 30s==

Sehr wahrscheinlich hast du die Aktualisierungsmethode '''longPoll''' deaktiviert. Es gibt zwei Aktualisierungsmethoden: shortPoll und longPoll.

'''shortPoll''' aktualisiert den Status aller Widgets auf einmal. Bei aktivem longPoll ist das shortPoll-Interval mit 15 Minuten festgelegt, ansonsten mit 30 Sekunden. shortPoll kann nicht deaktiviert werden.

'''longPoll''' benutzt den eventgesteuerten Benachrichtigungsdienst von fhem um Statusänderungen direkt zu aktualisieren. Das heisst, fhem sendet eine Nachricht per longPoll sobald sich ein Status ändert und das UI aktualisiert daraufhin automatisch nur die betroffenen Widgets. longPoll ist in fhem standardmäßig aktiv, kann aber deaktiviert werden. Im Zweifel bitte prüfen ob an der verwendeten [[FHEMWEB]]-Instanz das Attribut "longpoll 1" gesetzt ist (`list WEB`). Falls nicht, bitte `attr WEB longpoll 1` in fhem ausführen ("WEB" ist ggf. durch den Namen der verwendeten [[FHEMWEB]]-Instanz zu ersetzen). Im UI ist longPoll ebenfalls standardmäßig aktiv, kann aber ebenfalls deaktiviert werden. Bitte prüfen, ob der HTML-Code den Meta-Tag `<meta name="longpoll" content="1">` enthält. Falls nicht, bitte so übernehmen.

==Das UI zeigt Statusänderungen gar nicht an==

Prüfe zunächst, ob die Statusänderungen nicht vielleicht nur verspätet kommen (siehe FAQ [[#Das UI zeigt Statusänderungen erst nach 30s|Das UI zeigt Statusänderungen erst nach 30s]]). Wenn tatsächlich keine Statusänderungen im UI ankommen, sind die Werte der data-get-on/off Attribute vermutlich falsch gesetzt. Prüfe im [[Event_monitor]] welche Werte die Events, die bei Statusänderungen erzeugt werden, genau haben und passe deine Attribute entsprechend an. Manchmal weichen die erzeugten Events von den Namen der zugehörigen Readings ab. Sollten allerdings gar keine Events erzeugt werden (manche Module erzeugen nicht für jede Readingsänderung ein Event), dann kann die longPoll-Aktualisierung für diese Statusänderung nicht funktionieren.

==Wie öffne ich die Javascript-Konsole?==

"FHEM Tablet UI" benutzt Javascript und um Fehlermeldungen nachvollziehen zu können ist es oft erforderlich Informationen aus der "Javascript Konsole" des Browsers zu posten. Je nach Browser wird die Konsole mit einer anderen Tastenkombination geöffnet:

{| class="wikitable"
|-
! Browser
! Tastenkombination
|-
|Chrome:
|{{Taste|Ctrl}} + {{Taste|Shift}} + {{Taste|J}}
|-
|Firefox:
|{{Taste|Ctrl}} + {{Taste|Shift}} + {{Taste|K}}
|-
|Internet Explorer:
|{{Taste|F12}}
|-
|Opera:
|{{Taste|Ctrl}} + {{Taste|Shift}} + {{Taste|I}}
|-
|Safari:
|{{Taste|Cmd}} + {{Taste|Opt}} + {{Taste|C}}
|}

==Wie kann ich eigene Icons verwenden?==

Die Button-ähnlichen Widgets (switch, push, symbol etc.) verwenden Fonts um Icons anzuzeigen. Standardmässig wird der Font [http://fortawesome.github.io/Font-Awesome/ Font-Awesome] mitgeliefert, der mehr als [http://fortawesome.github.io/Font-Awesome/icons/ 500 Icons] mitbringt. Wenn diese Auswahl nicht ausreichend ist, kann ein eigener Iconfont eingebunden werden. Am einfachsten kann ein solcher Font mit Hilfe der [https://icomoon.io/app IcoMoon App] erstellt werden.

===IcoMoon App===

IcoMoon bietet verschiedene Icon-Libraries aus denen gewählt werden kann. Viele davon sind unter kostenlosen Lizenzen verfügbar, die App weist transparent darauf hin, wenn man eine (bzw. aus einer) nicht kostenfreien Library auswählt. Standardmässig wird die Library "IcoMoon Free" angeboten, weitere können über den Button "Add Icons From Library" ausgewählt werden. Zielführender ist das "search" Feld oben zu verwenden. Die Icons aller Libraries sind verschlagwortet und über das Suchfeld findbar. Darüber hinaus können eigene Grafiken hochgeladen werden ("Import Icons"), diese müssen im SVG-Format vorliegen.

Nach abgeschlossener Icon-Auswahl wird über den großen Button "Generate Font" (unten) ein Font erstellt. Dazu sollte zunächst oben unter "Preferences" ein Font Name (zB "Font 1") und ein eindeutiger Class-Prefix (zB "font1-") gewählt werden. Insbesondere der Class-Prefix ist wichtig und sollte nicht zu lang ausfallen. Er wird bei der Benutzung der Icons dem Icon-Namen vorangestellt. Das Class-Prefix des mitgelieferten Font-Awesome lautet "fa-". Danach kann der Font über den Button "Download" herunter geladen werden.

===Nachbearbeitung===

Im heruntergeladenen Zip-file aus der IcoMoon App muss die Zeile

line-height: 1;

auskommentiert oder gelöscht werden, da die Anzeige in den Buttons ansonsten "verschoben" wirkt.

===In FTUI einbinden===

Der gesamte Inhalt des Ziparchivs kann jetzt in ein eigenes Verzeichnis innerhalb der Fhem Tablet UI Installation kopiert werden, zB nach "customfonts/font1". Es sollte nicht in eines der Standardverzeichnisse kopiert werden, da dort die Gefahr besteht, dass die Dateien vom Updatemechanismus überschrieben werden. In der/den HTML-File(s) ist jetzt im <head>-Bereich noch der Pfad zur style.css aus dem Archiv anzugeben:

<link rel="stylesheet" href="customfonts/font1/style.css">

===Verwenden===

Jetzt können die eigenen Icons in den Widgets verwendet werden, indem sie im Attribut data-icon (bzw. data-icons, data-background-icon..) eingetragen werden; zB:

<div data-type="push" data-device="WECKER" data-icon="font1-alarmclock"></div>

Wichtig: Daran denken vor dem Namen des Icons das selbst gewählte Class-Prefix (hier "font1-") zu notieren.

==Warum führen mich Links auf andere Seiten zurück zu FHEMWEB?==

Zur Auslieferung des FTUI an den Browser wird das Modul [http://fhem.de/commandref.html#HTTPSRV HTTPSRV] verwendet. Leider zeigt es ein seltsames Verhalten, wenn man ausgehend von einer Adresse ohne abschliessenden Slash oder Dateinamen auf einen Link mit relativem URL (also zB nur ein Dateiname) klickt. Der relative Pfad wird in so einem Fall ab dem letzten Slash der Adresse der Ausgangsseite ermittelt.

Ein Beispiel: Wir starten bei ''<nowiki>http://host:8083/fhem/tablet</nowiki>'' und klicken auf einen Link zur Datei ''wohnzimmer.html''. Dieser Klick wird '''nicht''' auf ''<nowiki>http://host:8083/fhem/tablet/wohnzimmer.html</nowiki>'' geleitet, sondern zu ''<nowiki>http://host:8083/fhem/wohnzimmer.html</nowiki>''. Da es ''<nowiki>http://host:8083/fhem/wohnzimmer.html</nowiki>'' nicht gibt, wird man darauf postwendend zu ''<nowiki>http://host:8083/fhem</nowiki>'' gebracht. Startet man den gleichen Vorgang ausgehend von ''<nowiki>http://host:8083/fhem/tablet/</nowiki>'' (mit Slash am Ende), wird man wie erwartet nach ''<nowiki>http://host:8083/fhem/tablet/wohnzimmer.html</nowiki>'' gebracht. Es sollte also insbesondere in der Definition des Links für FHEMWEB darauf geachtet werden, den abschliessenden Slash zu notieren (<code>define tablet_ui HTTPSRV tablet/ ./www/tablet Tablet Frontend</code>). Das gleiche beim Anlegen von Lesezeichen. Wenn man das UI aber von Hand ansteuert, muss man schlicht daran denken den Slash mit einzugeben.

[[Kategorie: FAQ]]

FHEM Tablet UI FAQ

2015-04-21T13:30:31Z

Nesges: Eigene Iconfonts erstellen

FHEM Tablet UI FAQ

2015-04-08T17:53:07Z

Nesges: /* Wie öffne ich die Javascript-Konsole? */

FHEM Tablet UI FAQ

2015-04-08T17:50:30Z

Nesges:

FHEM Tablet UI FAQ

2015-04-03T11:06:11Z

Nesges: Die Seite wurde neu angelegt: „=Das UI zeigt Statusänderungen erst nach 30s= Sehr wahrscheinlich hast du die Aktualisierungsmethode '''longPoll''' deaktiviert. Es gibt zwei Aktualisierungs…“

=Das UI zeigt Statusänderungen erst nach 30s=

Sehr wahrscheinlich hast du die Aktualisierungsmethode '''longPoll''' deaktiviert. Es gibt zwei Aktualisierungsmethoden: shortPoll und longPoll.

'''shortPoll''' aktualisiert den Status aller Widgets auf einmal. Bei aktivem longPoll ist das shortPoll-Interval mit 15 Minuten festgelegt, ansonsten mit 30 Sekunden. shortPoll kann nicht deaktiviert werden.

'''longPoll''' benutzt den eventgesteuerten Benachrichtigungsdienst von fhem um Statusänderungen direkt zu aktualisieren. Das heisst, fhem sendet eine Nachricht per longPoll sobald sich ein Status ändert und das UI aktualisiert daraufhin automatisch nur die betroffenen Widgets. longPoll ist in fhem standardmäßig aktiv, kann aber deaktiviert werden. Im Zweifel bitte prüfen ob an der verwendeten [[FHEMWEB]]-Instanz das Attribut "longpoll 1" gesetzt ist (`list WEB`). Falls nicht, bitte `attr WEB longpoll 1` in fhem ausführen ("WEB" ist ggf. durch den Namen der verwendeten [[FHEMWEB]]-Instanz zu ersetzen). Im UI ist longPoll ebenfalls standardmäßig aktiv, kann aber ebenfalls deaktiviert werden. Bitte prüfen, ob der HTML-Code den Meta-Tag `<meta name="longpoll" content="1">` enthält. Falls nicht, bitte so übernehmen.

=Das UI zeigt Statusänderungen gar nicht an=

Prüfe zunächst, ob die Statusänderungen nicht vielleicht nur verspätet kommen (siehe FAQ ''Das UI zeigt Statusänderungen erst nach 30s''). Wenn tatsächlich keine Statusänderungen im UI ankommen, sind die Werte der data-get-on/off Attribute vermutlich falsch gesetzt. Prüfe im [[Event_monitor]] welche Werte die Events, die bei Statusänderungen erzeugt werden, genau haben und passe deine Attribute entsprechend an. Manchmal weichen die erzeugten Events von den Namen der zugehörigen Readings ab. Sollten allerdings gar keine Events erzeugt werden (manche Module erzeugen nicht für jede Readingsänderung ein Event), dann kann die longPoll-Aktualisierung für diese Statusänderung nicht funktionieren.

DevelopmentModuleIntro

2015-02-25T12:39:15Z

Nesges: /* X_Define */ Typo korrigiert

== Einleitung ==
Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden.
Insbesondere beschreibt der Text derzeit nur einstufige Module. Die Abgrenzung zu zweistufigen Modulen und deren Eigenschaften sollte noch ergänzt werden.

Um neue Geräte in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben, das automatisch von FHEM geladen wird, wenn ein passendes Gerät in FHEM definiert wird. Das Modul definiert dann wie mit dem Gerät kommuniziert wird, stellt Werte ("Readings") innerhalb von FHEM zur Verfügung oder erlaubt es das Gerät mit "Set"-Befehlen zu beeinflussen. Dieser Text soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl "define", der typischerweise in die zentrale Konfigurationsdatei fhem.cfg eingetragen wird, werden Geräte in FHEM definiert. Der Befehl sorgt dafür dass ein neues Modul bei Bedarf geladen wird und die Initialisierungsfunktion des Moduls aufgerufen wird.

Damit das funktioniert müssen der Name des Geräts, der Name des Moduls und der Name der Initialisierungsfunktion zueinander passen. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick in einer Fritz-Box könnte beispielsweise mit dem Befehl <code>define JeeLink1 JeeLink /dev/ttyUSB0@57600</code> definiert werden.

In der fhem.pl wird der define-Befehl verarbeitet, geprüft, ob ein Modul mit Namen JeeLink schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (bei einer FritzBox z.B. /var/media/ftp/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion JeeLink_Initialize aufgerufen.
Die Moduldatei muss also nach dem Namen des Geräts benannt werden und eine Funktion mit dem Namen des Geräts und einer _initialize Funktion enthalten.
In der Initialisierungsfunktion des Moduls werden dann die Namen der aller weiteren Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird der Hash - das ist die zentrale Datenstruktur für jede Instanz eines Gerätes - mit entsprechenden Werten gefüllt.

== Der Hash einer Geräteinstanz ==
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.

Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

<code>$defs{''Devicename''}</code> in fhem.pl verweist auf den Hash der Geräteinstanz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben, das direkt von fhem.pl aufgerufen wird. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im GUI als "Internals" angezeigt werden oder die Readings des Geräts. Beispiele:
*<code>$hash{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash{TYPE}</code> enthält die Typbezeichnung des Geräts
*<code>$hash->{INTERVAL}</code> enthält ein Abfrageintervall

==Ausführung von Modulen==
FHEM führt Module normalerweise nicht parallel aus. Daher wäre es ungünstig wenn Module Werte von einem Gerät abfragen und dann auf die Antwort des Geräts warten. In dieser Zeit wäre der Rest von FHEM blockiert. Die Ein- und Ausgabe sollte ohne Blockieren erfolgen und die Verarbeitung mehrerer Ein- und Ausgabekanäle quasi parallel ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sein können. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet und entsprechend gibt es in FHEM eine selectlist, in der die Filedeskriptoren der Geräedateien (z.B. /dev/ttyUSBx etc.) gespeichert sind.

In der zentralen Schleife von fhem.pl wird mit select überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion (X_Read) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und die Schleife wird weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per select überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion (X_Ready) implementieren, die prüft ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert und Werte in Readings geschrieben.

== Readings ==
Werte, die von einem Gerät gelesen werden und in FHEM zur Verfügung stehen werden Readings genannt. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash{READINGS}{Temp}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash{READINGS}{Temp}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion ReadingsVal($$$) zur Verfügung.

Readings werden im statefile von FHEM automatisch zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen, auch bevor sie vom Modul neu gesetzt oder aktualisiert werden.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code> (mehrfach wiederholt), <code>readingsEndUpdate</code>
*bei einzelnen Updates die Funktion <code>readingsSingleUpdate</code>
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<pre>
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</pre>

== Internals ==
Werte, die das Modul intern als Teil des Hashes speichert, die aber keine Readings sind, nennt man Internals. Sie werden ebenfalls als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{INTERVAL}</code> für ein Abfrageintervall, das beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Internals werden jedoch im Gegensatz zu Readings nicht im statefile zwischengespeichert.

Falls Werte wie das gerade erwähnte Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollen, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen nach dem Define-Befehl zusätzlich den Befehl <code>attr</code> erwarten.

== Attribute ==
Parameter einer Geräteinstanz können mit dem Befehl <code>attr</code> als so genannte Attribute gesetzt und damit dem Modul zur Verfügung gestellt werden. Attribute werden zusammen mit der Definition der Geräte beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben, die auch bei jedem Neustart von FHEM wieder gelesen wird. Zur Laufzeit werden Attribute in der globalen Datenstruktur <code>$attr{$name}</code> gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert (<code>$attr{$name}->{'header'}</code> wäre eine alternative aber unübliche Schreibweise für die selbe Variable).

Zum Auslesen solcher Attribute sollte die Funktion <code>AttrVal($$$)</code> verwendet werden.

Welche Attribute ein Modul unterstützt sollte in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen der Variable <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten). Wenn beim Setzen von Attributen die Werte geprüft werden sollen oder zusätzliche Funktionalität implementiert werden muss, dann kann dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> ([[#X_Attr|siehe unten]]) implementiert werden.

== Die wichtigsten Funktionen in einem Modul ==
Eine typische Grundfunktion eines einfachen Moduls ist das Auslesen von Werten von einem physischen Gerät und Bereitstellen dieser Werte innerhalb von FHEM als Readings. Das Geräte könnte beispielsweise an einem USB-Port angeschlossen sein. Folgende Funktionen könnte man beispielsweise in einem Modul mit Namen X implementieren:
* [[#X_Initialize|X_Initialize]] (initialisiert das Modul und gibt de Namen der zusätzlichen Funktionen bekannt)
* [[#X_Define|X_Define]] (wird beim <code>define</code> aufgerufen)
* [[#X_Undef|X_Undef]] (wird beim Löschen einer Geräteinstanz aufgerufen - Gegenteil zu <code>define</code>)
* [[#X_Set|X_Set]] (wird beim Befehl <code>set</code> aufgerufen um Daten an das Gerät zu senden)
* [[#X_Get|X_Get]] (wird beim Befehl <code>get</code> aufgerufen um Daten vom Gerät abzufragen)
* [[#X_Attr|X_Attr]] (wird beim Befehl <code>attr</code> aufgerufen um beispielsweise Werte zu prüfen)
* [[#X_Read|X_Read]] (wird vom globalen select aufgerufen, falls Daten zur Verfuegung stehen)
* [[#X_Parse|X_Parse]] (wird bei zweistufigen Modulen vom Dispatch aufgerufen und muss hier noch beschrieben werden)
* [[#X_Ready|X_Ready]] (wird unter windows als ReadFn-Erstatz benoetigt bzw. um zu pruefen, ob ein Geraet wieder eingesteckt ist)
* [[#X_Notify|X_Notify]] (falls man benachrichtigt werden will)
* [[#X_Rename|X_Rename]] (falls ein Gerät umbenannt wird)

Die Funktionen werden im folgenden beschrieben (soweit diese Seite inzwischen vollständig ist):

=== X_Initialize ===

<pre>
sub X_Initialize($)
{
my ($hash) = @_;
...
</pre>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von Fhem.pl nach dem Laden des Moduls aufgerufen und bekommt einen Hash für das Modul als zentrale Datenstruktur übergeben.

Dieser Hash wird im globalen Hash %modules gespeichert. <code>$modules{$ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>$ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der je Modul Werte enthält, beispielsweise auch die Namen der Funktionen, die das Modul implementiert und die fhem.pl aufrufen soll. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls:

<pre>
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
</pre>

<code>X</code> ist wieder durch den Modulnamen ohne die vorangestellte Zahl zu ersetzen.
Entsprechend können auch die Funktionen <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> etc. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützen Attribute definiert werden:

<pre>
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</pre>

In Fhem.pl werden dann die entsprechenden Werte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die Funktion <code>X_Attr</code> implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann verfügbar werden wenn das Modul zum Setzen von Readings die Funktionen readingsBeginUpdate, readingsBulkUpdate, readingsEndUpdate oder readingsSingleUpdate verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref.

=== X_Define ===
Die Define-Funktion eines Moduls wird von Fhem aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.)
Sie beginnt typischerweise mit:

<pre>
sub HTTPMOD_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</pre>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den Rest der Parameter, die im Befehl angegeben wurden. Welche und wie viele Parameter
akzeptiert werden ist Sache dieser Funktion. Im obigen Beispiel wird alles nach dem übergebenen Hash in ein Array aufgeteilt und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<pre>
my $name = $a[0];
my $url = $a[2];
my $inter = 300;
if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5, default is 300";
}
}
</pre>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:

<pre>
$hash->{url} = $url;
$hash->{Interval} = $inter;
</pre>

Wenn eine physische Schnittstelle geöffnet werden soll und dann bei verfügbaren Eingabedaten eine Lese-Funktion von Fhem aufgerufen werden soll, dann kann man in der Define-Funktion die Funktion DevIo_OpenDev aufrufen, die sich um alles weitere kümmert. Sie öffnet die Schnittstelle und fügt den Filedeskriptor an die globale Liste offener Verbindungen (selectlist / readyfnlist) an. Damit kann Fhem in seiner Hauptschleife erkennen, von welchem Gerät Daten bereit stehen und die zuständigen Funktionen aufrufen:

<pre>
my $ret = DevIo_OpenDev( $hash, 0, "X_DevInit" );
</pre>

Die optionale Funktion <code>X_DevInit</code> wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen.

=== X_Undef ===

Die <code>Undef</code>-Funktion ist das Gegenstück zur <code>Define</code>-Funktion und wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls rereadcfg, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu abarbeitet. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern sofern diese im Modul zum Pollen verwendet wurden (siehe später).

Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.

Beispiel:
<pre>
sub WKRCD4_Undef($$)
{
my ( $hash, $arg ) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</pre>

=== X_Get ===
Die Get-Funktion wird aufgerufen wenn der Fhem-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. Einige Module verwenden für diese Funktion einen Hash im Modul, der die möglichen <code>get</code>-Optionen mit zusätzlichen Werten definiert:

<pre>
my X_gets = (
"TempSoll" => "XY",
"Steilheit" => "Z"
);
</pre>
In der Get-Funktion selbst werden dann die übergebenen Parameter gegen diesen Hash geprüft.

Beispiel:

<pre>
sub X_Get($@)
{
my ( $hash, @a ) = @_;
return "\"get X\" needs at least one argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
if(!$X_gets{$opt}) {
my @cList = keys %X_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
...
</pre>

Die Ausgabe der Meldung mit <code>unknown ... choose one of ...</code> ist dabei wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.

=== X_Set ===
Die Set-Funktion ist das Gegenteil zur Get-Funktion. Sie ist dafür gedacht, Werte zum physischen Gerät zu schicken. Falls nur interne Werte im Modul gesetzt werden sollen, so sollte statt Set die Attr-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch nach dem Namen der Option auch den zu setzenden Wert übergeben.

Beispiel:
<pre>
sub X_Set($@)
{
my ( $hash, @a ) = @_;
return "\"set X\" needs at least an argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
my $value = join("", @a);

if(!defined($X_sets{$opt})) {
my @cList = keys %X_sets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
</pre>

Das GUI FHEM-Web kann für die einzelnen Set-Optionen, die das Modul versteht auch automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht des GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknwon ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück.

Beispiel:
<pre>
if(!defined($X_sets{$opt})) {
return "Unknown argument $opt, choose one of mode:verbose,ultra,relaxed turbo:NoArg";
}
</pre>

Die möglichen Zusatzinformationen sind:

'''noArg'''

es werden keine weiteren Argumente mehr benötigt
<pre>on:noArg</pre>

'''slider'''

es wird ein Schieberegler für den Wert angezeigt. Dabei Minimum, Schrittweite und Maximum angeben
<pre>dim:slider,0,1,100</pre>

'''RGB'''

es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Bitte dazu auch den Wiki Artikel zum Colorpicker lesen, da im Modul noch weiterer Code eingefügt werden muss.
<pre>rgb:colorpicker,RGB</pre>

'''Liste'''

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

'''Leer'''

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt

'''Hinweise'''

- Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.

- bei den üblichen Kommandos wie on off sollte man auf noArg verzichten, da diese durch FHEMWeb automatisch in der Raumübersicht angezeigt werden. Wenn man hier noArg spezifiziert, so werden diese nicht neben dem Modul in der Raumübersicht angezeigt und der User muss sich diese vie webCmd dann erst selbst definieren, was natürlich unschön ist

- der User kann sich in der Raumübersicht nach wie vor via webCmd eine entsprechende Steuerung anlegen.

=== X_Attr ===
Die Attr-Funktion implementiert Prüfungen der bei einem <code>attr</code> übergebenen Werte und eventuell zusätzliche Aktionen wenn ein Attribut gesetzt wird. Die Liste der möglichen Attribute wird in der <code>[[#X_Initialize|X_Initialize]]-Funktion</code> definiert ([[#X_Initialize|siehe oben]]). Fhem ruft bei einem Attr-Befehl die zuständige <code>X-Attr-Funktion</code> auf und wenn diese keine Fehlermeldung sondern <code>undef</code> zurückgibt, dann schreibt fhem.pl die bei <code>attr</code> angegebenen Werte in die jeweilige Datenstruktur <code>$attr{$name}-> ...</code>

Beispiel:

<pre>
X_Attr(@)
{
my ($cmd,$name,$aName,$aVal) = @_;
# $cmd can be "del" or "set"
# $name is device name
# aName and aVal are Attribute name and value
if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X: Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal";
}
}
}
return undef;
}
</pre>

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie ja auch keine Werte dort speichern muss, sondern den Befehl <code>set</code> oder <code>del</code> je nachdem ob ein Attribut gesetzt oder gelöscht wird, den Namen der Geräteinstanz sowie den Namen des Attributs und seinen Wert.
Im obigen Beispiel wird für ein Attribut mit Namen Regex geprüft ob die Regex fehlerhaft ist. Falls sie ok ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs.

Falls man Attribute mit Platzhaltern definiert (Wildcard-Attribute), z.B. mit
<pre>
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</pre>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken, da Fhemweb nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muß solche Attribute über den <code>attr</code> Befehl eintippen.

Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in Fhemweb durch Klicken ausgewählt und geändert werden.
Dazu reicht ein Aufruf von

<pre>
addToDevAttrList($name, $aName);
</pre>

in der Attr-Funktion wenn ein Attribut gesetzt wird.

=== X_Read ===

Die X_Read-Funktion wird aus der Hauptschleife von FHEM aus aufgerufen wenn das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können. Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten zwischenspeichern. Es bietet sich an, dies im Hash der Geräteinstanz zu tun. Im Beispiel ist dies <code>$hash->{buffer}</code> an den die jeweils gelesenen Daten angehängt werden bis die folgende Prüfung ein für das jeweilige Protokoll passendes Frame identifiziert.

<pre>
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# read from serial device
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );

# convert to hex string to make parsing with regex easier
$hash->{buffer} .= unpack ('H*', $buf);
Log3 $name, 5, "Current buffer content: " . $hash->{buffer};

# did we already get a full frame?
if ($hash->{buffer} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)")
...
</pre>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{buffer}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und in Readings gespeichert werden (siehe unten).

=== X_Ready ===

muss noch beschrieben werden.

Beispiel:
<pre>
sub X_Ready($)
{
my ($hash) = @_;
return DevIo_OpenDev($hash, 1, undef )
if ( $hash->{STATE} eq "disconnected" );

# This is relevant for windows/USB only
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
</pre>

=== X_Notify ===

Die X_Notify-Funktion wird aus der Funktion DoTrigger in fhem.pl heraus aufgerufen wenn ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind das Filelog-Modul oder das Average-Modul. Average reagiert auf Events anderer Module und erweitert diese mit der Berechnung von Tages- und Monats-Durchschnittswerten.

Die Notify-Funktion bekommt dafür zwei Hashes übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Geräts, das die Events erzeugt hat, kann es die Events verarbeiten. Events werden je Gerät in einem Array, das über das Internal <code>CHANGED</code> referenziert wird, gespeichert.

Beispiel:
<pre>
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash
my $devName = $dev_hash->{NAME}; # Device that created the events

return "" if(AttrVal($ownName, "disable", undef)); # Abbruch wenn das Attribut disable gesetzt ist

my $max = int(@{$dev_hash->{CHANGED}}); # number of events / changes

for (my $i = 0; $i < $max; $i++) {
my $s = $dev->{CHANGED}[$i];

</pre>

Da die Notify-Funktion für jedes Gerät mit allen seinen Events aufgerufen wird, muss sie in einer Schleife alle Events prüfen und entscheiden, ob es mit dem jeweiligen Event etwas tun möchte. Ein Gerät, das die Notify-Funktion implementiert sieht dafür typischerweise einen regulären Ausdruck vor, der für die Filterung verwendet wird.
Als anschauliches Beispiel und für weitere Details eignet sich das Modul 98_Average.pm

=== X_DbLog_splitFn ===
Mit der DbLog_SplitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten.<br>
Eingangsparameter: Das generierte Event<br>
Rückgabewerte: Array: Reading/Value/Unit

Beispiel:
<pre>
sub X_DbLog_splitFn($)
{
my ($event) = @_;
my ($reading, $value, $unit);

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</pre>

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion <code>InternalTimer</code> verwenden. Man übergibt ihr den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, den zu übergebenden Parameter und ein Flag ob der erste Aufruf verzögert werden soll falls die Initialiserung des Geräts noch nicht abgeschlossen ist. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der Define-Funktion den Timer folgendermassen setzen:

<pre>
# initial request after 2 secs, there timer is set to interval for further update
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash, 0);
</pre>

in der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<pre>
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash, 1);
Log3 $name, 4, "X: GetUpdate called ...";
</pre>

Im weiteren Verlauf der Funktion könnte man dann das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene Read-Funktion zu implementieren, die beim Anstehen von Daten aufgerufen wird.

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Protokollmeldung in die Fhem-Logdatei zu schreiben, wird die Funktion Log3 aufgerufen:
<pre>
Log3 $name, 3, "X: Problem erkannt ...";
</pre>

Die Parameter der Funktion Log3 sind der Name oder der Hash der Geräteinstanz, das Verbose-Level, in dem die Meldung sichtbar sein soll und die Meldung selbst.
Den Namen der Geräteinstanz kann man in den Funktionen, die den Hash übergeben bekommen einfach aus diesem Hash nehmen:

<pre>
my $name = $hash->{NAME};
</pre>

Um für ein neues Modul das Verbose-Level zu erhöhen, ohne gleich für das Gesamte FHEM alle Meldungen zu erzeugen kann man den Befehl
<code>attr gerätename verbose</code> verwenden. Beispielsweise <code>attr PM verbose 5</code>

Damit bietet es sich an im Modul Meldungen, die im normalen Betrieb nicht benötigt werden, beim Aufruf von Log3 mit dem Level 4 oder 5 anzugeben. Wenn man dann bei der Fehlersuche mehr Meldungen sehen möchte, erhöht man mit attr X verbose das Level für das betroffene Gerät.

== Zweistufiges Modell für Module ==
siehe auch
* [http://forum.fhem.de/index.php/topic,18920.msg128100.html#msg128100|The FHEM two-level model]
* [http://forum.fhem.de/index.php/topic,13438.msg83643.html#msg83643|Zum Initialize bei physikalischen und logischen Geräten]

Das zweistufige Modell besteht aus
* physisches Modul - z.B. für CUL (00_CUL.pm), der mehrer Protokolle empfängt, u.a. FS20
* logische Modul(e) - z.B. das Protokoll FS20 (10_FS20.pm)

Das physische Modul öffnet die Datenverbindung zum Gerät.

=== Kommunikation vom Gerät zu den logischen Modulen ===
Die [[#X_Read|X_Read]]-Funktion wird aus der Hauptschleife von Fhem aufgerufen sobald das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können.

Unter Windows funktioniert "select" nur für Geräte, die via TCP verbunden sind. Für alle anderen Geräte ist eine [[#X_Ready|X_Ready]]-Funktion von Nöten, die 10x pro Sekunde das Gerät abfrägt und "true" zurück gibt, sollten Daten bereit stehen.

Die X_Read-Funktion stellt sicher, dass die Daten
* komplett und
* korrekt
sind und sie ruft die globale Funktion Dispatch() mit einer Nachricht auf.

Dispatch() sucht nach einem passenden lokalen Modul via
* $hash->{Clients} oder $hash->{MatchList} im physischen Modul
* $hash->{Match} in allen passenden logischen Modulen
und ruft X_Parse in den gefundenen Modulen auf.

X_Parse
* untersucht die übergebenen Daten (von Dispatch() übergeben)
* setzt alle [[#Readings|readings]] via readings*update Funktionen
* gibt den Namen des logischen Device zurück

Es findet kein Event-Triggering statt, wenn die readings*update Funktionen
* von X_Parse aufgerufen werden und
* X_Parse wiederum von Dispatch() aufgerufen wurde.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Dispatch() triggert das Event-Handling für das von X_Parse zurückgegebene logische Device.

=== Kommunikation von den logischen Modulen zum Gerät ===

Um von einem logischen Modul an ein physisches Gerät zu senden, wird im logischen Modul das Attribut IODev mit dem namen des physischen Devices gesetzt.
Der Befehl
<code>AssignIoPort($hash);</code>
in der X_Define-Funktion des logischen Devices erledigt das.

Als Befehl zum Schreiben vom logischen ins physische Gerät soll <code>IOWrite()</code> verwendet werden. IOWrite() ruft im physischen Gerät die X_Write-Funktion auf.

Wenn es keine direkte Kommunikation zwischen dem logischen und dem physischen Gerät gibt(keine direkten Aufrufe von Funktionen, kein direktes überprüfen von $hash Werten,...) so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie in RFR) oder mittels FHEM2FHEM:RAW zwei Fhem Installationen verbunden werden und die logischen Devices werden dennoch funktionieren.

== Ergänzende Hinweise ==
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.

Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.

== Weitere Informationen ==
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM Commandref [http://fhem.de/commandref.html] sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.

== Noch zu beschreiben ==
* Zweistufiges Modell für Module
* Funktion X_Ready ...
* Funktion X_State_Fn: {{Link2Forum|Topic=32680}}, siehe auch [[DevelopmentState]]
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* DevIO

[[Kategorie:Development]]

Benutzer:Nesges

2015-01-28T10:26:20Z

Nesges:

[[File:Wopr home.png|400x300px|right|link=File:Wopr home.png]]
(Haupt-) Aktoren und Sensoren in meinem FHEM-Setup:

* [[CUL]]
** [[MAX]]
*** HeatingThermostatPlus
*** ShutterContact
** [[Intertechno Code Berechnung|IT]]
*** Mumbi Zwischenstecker
* [[JeeLink]]
** [[TFA 30.3144]]
** [[TFA 30.3147]]
* [[XBMC]]
* [[PRESENCE]]
* [[FB_CALLMONITOR]]
* [[FRITZBOX]]
* [[MilightBridge]]
** [[MilightDevice]]

Installiert seit 2014/12 auf [[Raspberry Pi]].

Fritzbox: interne Weiterleitung für FHEM-Server einrichten

2015-01-28T08:42:22Z

Nesges: Typos korrigiert

== Fritzbox: interne Weiterleitung für FHEM-Server ==

Falls erforderlich, kann auf einer [[AVM Fritz!Box|FritzBox]] eine direkte Portfreigabe auf eine lokale FHEM-Installation erfolgen. '''ACHTUNG: Dadurch hat man direkten Zugriff via dynamischem DNS über das Internet und öffnet somit das Tor zum Router über einen bestimmten Port!'''

== Voraussetzung ==
Um den FHEM-Server auf einer Fritzbox direkt anzusprechen und diesen von unterwegs zu erreichen, braucht man einen Provider für dynamisches DNS (z.B. hier eine Liste einiger Anbieter [http://www.dmoz.org/Computers/Internet/Protocols/DNS/Service_Providers/Dynamic_DNS/]) und eine Portweiterleitung auf die FritzBox. Des Weiteren sollte der FHEM Server intern laufen und erreichbar sein ;-)

== Portweiterleitung im Web-Interface ==
* Hier kann '''keine''' direkte Portweiterleitung auf eine FritzBox eingestellt werden
* Beim Versuch eine direkte Weiterleitung auf "fritz.box" zu erstellen, egal an welchem Port, wird dieses mit einer Fehlermeldung ''FEHLER: Eintrag kollidiert mit interner Regel'' quittiert

== Portweiterleitung per Telnet ==
* Telnet-Verbindung zur Fritzbox
* Modifizierung der Datei ''ar7.cfg''
* Neustart der FritzBox

=== Modifizierung der ar7.cfg ===
* Telnetverbindung aufbauen
telnet fritz.box
* Kopieren der Datei ''ar7.cfg'' auf den internen Speicher, um den Eintrag für die gewünschte Portweiterleitung hinzuzufügen.
cat /var/flash/ar7.cfg > /var/media/ftp/ar7.cfg
* Ändern der Datei
vi /var/media/ftp/ar7.cfg
* In der 300. Zeile ist folgender Eintrag (oder ähnlich) zu finden:
internet_forwardrules = "tcp 0.0.0.0:443 0.0.0.0:443 0",
* Hinzufügen der internen Portweiterleitung als '''vorletzter Eintrag''' (der letzte Eintrag endet nämlich mit einem ";")
internet_forwardrules = "tcp 0.0.0.0:8083 0.0.0.0:8083 0",
Der Port für den FHEM Server ist in diesem Beispiel 8083, kann aber auch auf einenen anderen gestellt werden (8084 bzw. 8085)
* Per Taste ''ESC'' und einem '':wq'' speichert man die Datei
* Datei in den Flashspeicher kopieren und die alte Datei überschreiben
cat /var/media/ftp/ar7.cfg > /var/flash/ar7.cfg
* Reboot der FritzBox
reboot

== Funktionstest der Weiterleitung ==
Nach dem Neustart der Fritzbox sollte nun die Weiterleitung bei Eingabe des dynamischen DNS-Eintrags auf den FHEM Server umgeleitet werden. Die Weiterleitung ist '''nicht''' im Webinterface zu sehen.

[[Kategorie:FritzBox]]
[[Kategorie:FAQ]]
[[Kategorie:HOWTOS]]

Fritzbox: interne Weiterleitung für FHEM-Server einrichten

2015-01-28T08:33:11Z

Nesges: /* Portweiterleitung im Web-Interface */ Typo korrigiert

== Fritzbox: interne Weiterleitung für FHEM-Server ==

Falls erforderlich, kann ein auf einer [[AVM Fritz!Box|FritzBox]] eine direkte Portfreigabe erfolgen. '''ACHTUNG: Dadurch hat man direkten zugriff via dynamischer DNS über das Internet und öffnet somit das Tor zum Router über einen bestimmten Port!'''

== Voraussetzung ==
Um den FHEM-Server auf eine Fritzbox direkt anzusprechen und von Unterwegs diesen zu erreichen, braucht man eine dynamische DNS (z.B. hier eine Liste einiger Anbieter [http://www.dmoz.org/Computers/Internet/Protocols/DNS/Service_Providers/Dynamic_DNS/]) und eine Portweiterleitung auf die FritzBox. Des Weiteren sollte der FHEM Server intern laufen und erreichbar sein ;-)

== Portweiterleitung im Web-Interface ==
* Hier kann keine direkte Portweiterleitung auf eine FritzBox eingestellt werden
* Beim Versuch eine direkte Weiterleitung auf "fritz.box" zu erstellen, egal an welchem Port, wird dieses mit einer Fehlermeldung ''FEHLER: Eintrag kollidiert mit interner Regel'' quittiert

== Portweiterleitung per Telnet ==
* Telnet-Verbindung zur Fritzbox
* Modifizierung der Datei ''ar7.cfg''
* Neustart der FritzBox

=== Modifizierung der ar7.cfg ===
* Telnetverbindung aufbauen
telnet fritz.box
* Kopieren der Datei ''ar7.cfg'' auf den internen Speicher, um den Eintrag für die gewünschte Portweiterleitung hinzuzufügen.
cat /var/flash/ar7.cfg > /var/media/ftp/ar7.cfg
* Ändern der Datei
vi /var/media/ftp/ar7.cfg
* In der 300. Zeile folgender Eintrag (oder ähnlich) zu finden: internet_forwardrules = "tcp 0.0.0.0:443 0.0.0.0:443 0",
* Hinzufügen der internen Portweiterleitung als '''vorletzter Eintrag''' (der letzte Eintrag endet nämlich mit einem ";"!
internet_forwardrules = "tcp 0.0.0.0:8083 0.0.0.0:8083 0",
Der Port für den FHEM Server ist in diesem Beispiel 8083, kann aber auch auf einenen anderen gestellt werden (8084 bzw. 8085)
* Per Taste ''ESC'' und der einem '':wq'' speichert man die Datei
* Datei in den Flash speicher kopieren und die alte Datei überschreiben
cat /var/media/ftp/ar7.cfg > /var/flash/ar7.cfg
* Reboot der FritzBox
reboot

== Funktionstest der Weiterleitung ==
Nach dem Neustart der FB sollte nun die Weiterleitung bei eingabe der Dynamischer DNS eintrags auf den FHEM Server umgeleitet werden. Die Weiterleitung ist '''nicht''' im Webinterface zu sehen.

[[Kategorie:FritzBox]]
[[Kategorie:FAQ]]
[[Kategorie:HOWTOS]]

SVG-Plots von FileLog auf DbLog umstellen

2015-01-26T10:10:13Z

Nesges: /* Define */ "define DBLOG DbLog mydb.conf .*:.*" ergänzt

Grundsätzlich verhält sich [[DbLog]] bei der Verwendung in [[Creating Plots|SVG-Plots]] sehr ähnlich wie ein [[FileLog]]. So kann ein neuer Plot auf DbLog-Daten in der [[FHEMWEB|FHEM-Oberfläche]] genauso angelegt werden wie beim FileLog, indem man an der Definition des DbLog Devices auf "Create SVG plot from DbLog" klickt. Wenn man von FileLog auf DbLog umstellt, möchte man aber evtl. nur die Definitionen der SVG-Plots anpassen. Hier einige Anmerkungen dazu.

== Define ==

Eine bestehende FileLog Definition für ein Thermostat könnte zB so aussehen:

define FileLog_W_HEIZUNG FileLog ./log/W_HEIZUNG-%Y.log W_HEIZUNG
attr FileLog_W_HEIZUNG logtype text
attr FileLog_W_HEIZUNG room hidden

define SVG_FileLog_W_HEIZUNG_1 SVG FileLog_W_HEIZUNG:SVG_FileLog_W_HEIZUNG_1:CURRENT
attr SVG_FileLog_W_HEIZUNG_1 room hidden

Bei Umstellung auf DbLog kann das FileLog-Device natürlich gelöscht werden, nachdem es durch ein allgemeines DbLog-Device ersetzt worden ist (siehe [[DbLog]]). Die Definition des Plots wird danach folgendermassen geändert:

define DBLOG DbLog mydb.conf .*:.*

define SVG_W_HEIZUNG_1 SVG DBLOG:SVG_DBLOG_W_HEIZUNG_1:CURRENT
attr SVG_W_HEIZUNG_1 room hidden

Mit dieser Anweisung wird ein SVG-Plot mit Namen ''SVG_W_HEIZUNG_1'' (der Name muss natürlich nicht geändert werden, soviel Zeit sollte man sich allerdings nehmen) angelegt, der seine Daten vom DbLog-Device ''DBLOG'' bezieht und mit Hilfe der Gplot-Datei ''SVG_DBLOG_W_HEIZUNG_1.gplot'' (auch dieser Name muss nicht zwingend geändert werden) rendert.

== Gplot-Datei ==

Die bestehende Gplot-Datei ''SVG_FileLog_W_HEIZUNG_1.gplot'' (im Verzeichnis ''www/gplot'') wird zunächst nach ''SVG_DBLOG_W_HEIZUNG_1.gplot'' kopiert. Sie kann gelöscht werden, wenn die Umstellung zufrieden stellend abgeschlossen ist. Geändert werden müssen nur die Zeilen, die mit ''#FileLog'' beginnen:

#FileLog 4:W_HEIZUNG.temperature\x3a:0:
#FileLog 4:W_HEIZUNG.desiredTemperature:0:
#FileLog 4:W_HEIZUNG.valveposition\x3a:0:

Daraus wird:

#DbLog W_HEIZUNG:temperature:0:
#DbLog W_HEIZUNG:desiredTemperature:0:
#DbLog W_HEIZUNG:valveposition:0:

''#FileLog'' wird durch ''#DbLog'' ersetzt. Die Angabe der Feldnummer vor dem Device (hier: "4") fällt weg, ebenso evtl. notierte Sonderzeichen am Ende der Readings-Bezeichnung (hier "\x3a"). Ansonsten bleibt der Inhalt der Gplot-Datei gleich.

===@fld===
Ein Sonderfall in der Notation liegt in der Verwendung von Mappings mit Hilfe des @fld-Arrays (siehe auch [[Creating Plots]]). Da es dieses Array in der Form in DbLogs nicht gibt, muss auf eine Zuweisung der Variable $val umgestellt werden. Lautet die Anweisung bei Verwendung von FileLog zB:

#FileLog 3:W_FENSTER:onoff::$fld[2]=~"1"?24:-10

muss sie für DbLog folgendermassen geändert werden:

#DbLog W_FENSTER:onoff:::$val=($val=~'1'?24:-10)

Insbesondere ist auch der zusätzliche Doppelpunkt vor der Anweisung zu beachten (Grund ist mir leider nicht bekannt, bitte ergänzen!).

===logProxy===

#logProxy FileLog:FileLog_W_HEIZUNG:4:W_HEIZUNG.valveposition\x3a:0:

wird zu

#logProxy DbLog:DBLOG:W_HEIZUNG:valveposition:0:

Näheres dazu unter [[LogProxy]].

[[Kategorie:HOWTOS]]

Benutzer:Nesges

2015-01-25T19:34:06Z

Nesges:

Datei:Wopr home.png

2015-01-25T19:29:02Z

Nesges: Screenshot der Startseite meiner Tablettanwendung

Screenshot der Startseite meiner Tablettanwendung

Benutzer:Nesges

2015-01-25T19:22:39Z

Nesges: Die Seite wurde neu angelegt: „(Haupt-) Aktoren und Sensoren in meinem FHEM-Setup: * CUL ** MAX *** HeatingThermostatPlus *** ShutterContact ** IT *…“

(Haupt-) Aktoren und Sensoren in meinem FHEM-Setup:

* [[CUL]]
** [[MAX]]
*** HeatingThermostatPlus
*** ShutterContact
** [[Intertechno Code Berechnung|IT]]
*** Mumbi Zwischenstecker
* [[JeeLink]]
** [[TFA 30.3144]]
** [[TFA 30.3147]]
* [[XBMC]]
* [[PRESENCE]]
* [[FB_CALLMONITOR]]

Installiert seit 2014/12 auf [[Raspberry Pi]].

Energiesparende Schimmelbekämpfung / Luftentfeuchtung in kritischen Räumen

2015-01-25T18:09:27Z

Nesges: Die Seite wurde neu angelegt: „==Voraussetzungen / Benötigte Technik== * Einen Raum mit kalten Wandstellen * Innentemperatursensor und Luftfeuchtesensor im betroffenen Raum (z.B. Homematic…“

==Voraussetzungen / Benötigte Technik==

* Einen Raum mit kalten Wandstellen
* Innentemperatursensor und Luftfeuchtesensor im betroffenen Raum (z.B. Homematic Wandthermostat)
* Außentemperatursensor (oder notfalls die aktuellen Wetterdaten von Yahoo und Co.)
* Infrarotthermometer (ohne Anbindung an FHEM und nur leihweise für ein paar Tage, wird nur zum Einrichten benötigt)
* Luftentfeuchter, der sich z.B. per Homematic-Zwischenstecker an/ausschalten lässt (optional, man kann sich natürlich auch nur Warnungen ausgeben lassen)

==Ausgangslage==

Schimmel will trinken, um Wachsen zu können. Möchte man einschätzen, ob in einem Raum Schimmelgefahr besteht, könnte man das mit FHEM-Bordmitteln über das Taupunkt-Modul „dewpoint“ machen. Wenn der Taupunkt der Raumluft über der Oberflächentemperatur der Wand liegt, dann kondensiert das Wasser und es schimmelt. Man müsste also nur die Taupunkttemperatur Td(Raumtemperatur, rel. Raumluftfeuchte) mit der Wandtemperatur vergleichen. Hierzu muss man natürlich die Wandtemperatur (an der kältesten Stelle, hier kondensiert das Wasser aus der Luft zuerst) ersteinmal kennen. Das Problem haben wir aber immer, egal wie wir es anstellen - dazu später mehr.

Diese Variante per Taupunkt ist aber nur die halbe Miete: Laut verschiedenen Quellen wächst mancher Schimmelpilz schon viel früher - ohne kondensierten, flüssigen Wasserfilm, allein durch eine hohe relative Luftfeuchte von über 70% (manche Quellen sagen 80%). Hat eine Oberfläche genau die Taupunkttemperatur der Raumluft, ist die relative Luftfeuchte dort bei 100% - also deutlich über den gefährlichen 70-80%, so dass sich Schimmel dort schon recht wohlfühlen sollte.

Nun könnte man entweder ein paar Grad "Sicherheitsmarge" auf den Taupunkt addieren. Prima. Nur wie groß sollte unsere Sicherheitsmarge genau sein, ohne den Raum mit z.B. 200-300 Watt sehr energieintensiv zu viel zu entfeuchten? Dann vielleicht doch ganz simpel ansetzen und in FHEM definieren: Schimmelwarnung ausgeben oder Luftentfeuchter anschalten bei über 70% Raumluftfeuchte. Punkt. Dazu könnte man dann bequem z.B. einen Homematic-Raumthermostaten nehmen und dessen Sensorwert für die Luftfeuchtigkeit auf Überschreitung der 70%-Marke prüfen - so tun das sicher auch viele. Aber das kann wie in meinem Fall - die Wände sind an einigen Stellen kälter als die Raumluft - genau wie die Taupunkt-Methode jämmerlich schiefgehen.

Das Problem dabei ist nämlich, dass die Luft nicht einfach schlagartig an Flächen auskondensiert, die kälter sind als der Taupunkt. Die relative Luftfeuchte steigt mit jedem Grad weniger kontinuierlich an. Und dieser Effekt ist je nach Bausubstanz und "Wandkälte" durchaus erheblich. So ist die 70%-Marke an der Wand schon mitunter bei einer Luftfeuchtigkeit im Raum von 55% oder gar weniger überschritten. Eine „Sicherheitsmarge“ muss da dann schon ganz schön groß ausfallen - und der Raum z.B. dauerhaft auf 50% entfeuchtet werden. Oh je, die Stromrechnung, denn das ist an wärmeren Tagen, wo die Wände vielleicht nur 2 Grad kälter sind als die Luft im Raum, viel zu viel. Bei mir liegt z.B. in den Fensterzargen die (mit einem Infrarotthermometer gemessene) Oberflächentemperatur an kalten Tagen mit Temperaturen unter dem Gefrierpunkt manchmal 10 Grad unter der Raumtemperatur - man spricht bei solchen nicht immer behebbaren Baumängeln von sog. „Kältebrücken“. Das wirkt sich an solchen Tagen schon extrem auf die relative Luftfeuchte aus und ließ bei mir den Schimmel wachsen.

Nur wie stark ist diese Auswirkung denn nun genau? Das hängt wie gesagt von der Differenz zwischen Raumtemperatur und Wandtemperatur (und damit der Außentemperatur) ab - je größer die Differenz, desto stärker der Feuchteanstieg in Wandnähe. Leider ist der Zusammenhang aber nicht linear, so dass man das ausrechnen muss. Da ich das nirgends fertig gefunden habe, habe ich hier: http://www.wetterochs.de/wetter/feuchte.html die nötigen Formeln gefunden, umgestellt und in folgende Funktion für die 99_myUtils.pm gegossen:

sub shiftRelHumidity($$$)
# Uses a pair of relative humidity and temperature ($r1, $T1) to calculate the relative
# humidity on spots with same absolute humidity of the air but different temperature $T2.
#
# Useful to calculate the relative humidity near the surface of cold walls. Therefore, use the rel.
# humidity of the room ($r1 in percent), the room Temperature ($T2 in degrees of C) and the temperature
# of the surface of the wall ($T2 in degrees of C). Returns the rel. humidity on the surface in pct then.
{
my ($T1, $r1, $T2) = @_;
my $r2 = ($r1 * 10**((7.62*$T1)/(234.175+$T1))*(273.15+$T2)) / ( 10**((7.62*$T2)/(234.175+$T2))*(273.15+$T1));
return $r2;
}

Wen die Herleitung interessiert und nachrechnen möchte, ob ich mich vertan habe, der möge es mich wissen lassen. Einem Vergleich mit der Berechnung dieser Seite hier: http://wetterstationwien22.at/html/relative-luftfeuchte--erwarmung-.html hält die Formel aber einigermaßen Stand ;-)

Wir können hiermit nun also in Abhängigkeit von der Raumtemperatur, der rel. Luftfeuchte des Raumes und der Oberflächentemperatur der Wand die relative Luftfeuchte in Wandnähe ziemlich genau ausrechnen. Und dann das ganze in ein UserReading packen und unseren Luftentfeuchter danach regeln - oder unsere Schimmelwarnung versenden, mit dem Hinweis, dass vielleicht mal gelüftet oder der Raum mehr beheizt werden müsste (beides kann helfen - das ist aber ein anderes Thema und will ich hier nicht weiter behandeln). Super. Da gibt es vorher aber nach wie vor noch ein mittelprächtiges Problem: Woher nehmen wir die Wandtemperatur?

==Wandtemperatur ermitteln==

Perfekt wäre natürlich, einen Oberflächentemperatursensor an der kältesten Stelle der Wand zu platzieren und den Wert direkt zu messen. Wer es ganz genau machen will und seinen Luftentfeuchter wirklich sparsam einsetzen will, der sollte das vielleicht auch so tun - dann kann man aber dort auch gleich die Luftfeuchtigkeit oder Oberflächenfeuchtigkeit messen. Meistens ist das aber relativ umständlich, unhübsch und kostet auch noch Geld für zusätzliche Sensoren.

Was sich bei mir aber auch als ziemlich genau herausgestellt hat, ist die Wandtemperatur kontinuierlich zu schätzen - und zwar in Abhängigkeit von Innen- und Außentemperatur. Hierzu ist es nötig, eine kleine Messreihe mit einem Infrarotthermometer zu machen: Gemessen wird hiermit die Oberflächentemperatur der Wand an der kältesten Stelle, die sich im Raum finden lässt - also z.B. in der Fensterzarge. Zusätzlich benötigen wir die Innentemperatur des Raumes und die Außentemperatur, die FHEM zu dieser Zeit gemessen hat - die kann man ja nach der Messung im FileLog / DBlog nachschauen.

Aus diesen 3 Werten berechnen wir uns einen "Isolationsfaktor" K:

K = (Oberflächentemperatur - Außentemperatur) / (Innentemperatur - Außentemperatur)

Wichtig ist es, die Messung durchzuführen wenn es draußen richtig schön kalt ist (schön spät Abends / nachts bei Minusgraden) und die Raumtemperatur längere Zeit konstant war - direkt nach dem Aufheizen des Bades bei 15 Grad Außentemperatur ergibt das ganze also eher keine genauen Werte. Die Außentemperatur sollte idealerweise auch konstant sein, aber das ist sie nunmal nicht, daher kann das ganze nicht perfekt funktionieren - aber für unsere Zwecke durchaus ausreichend. Die Messung solltet ihr aber auf jeden Fall ein paar mal wiederholen (6-7 mal zu verschiedenen Zeiten, am besten an mehreren Tagen), ggf. Ausreißer wegwerfen und dann K mitteln. Sollte K bei euch nicht sonderlich konstant sein - was je nach Bausubstanz / Beheizung durchaus möglich ist - nehmt tendentiell eher einen kleineren Wert, geht also von schlechterer Dämmung aus, wenn ihr sicher sein wollt, dass es nicht schimmelt. Bei mir ergaben sich für meine Altbauwohnung Werte zwischen 0,67 und 0,70 - Mittelwert ist 0,68, den verwende ich seitdem.

Über den Wert können wir nun mit folgender Funktion für die 99_myUtils.pm künftig die Wandtemperatur jederzeit aus Innen- und Außentemperatur schätzen:

sub wallSurfaceTemp($$$)
# Estimates the temperature of the inner wall surface given the outside Temperature in degrees of C as $Tinside,
# the outdoor-temperature $Toutside in degrees of C and an insulation Factor $Kinsulation with K = 1 (theoretical perfect insulation, e.g. vacuum) and
# K = 0 (no insulation at all, means: less than a sheet of paper). You have to calculate K on your own by measuring inside-, outside-, and wall-temperature,
# preferably by averaging multiple measurements on cold days with constant heating of the room.
{
my ($Tinside, $Toutside, $Kinsulation) = @_;
my $Tsurface = ($Tinside * $Kinsulation) + ($Toutside * (1 - $Kinsulation));
return $Tsurface;
}

Wirklich genau ist die Methode wie gesagt nicht und unterliegt gewissen Schwankungen. Sie ist inspiriert durch diesen Artikel hier (und auf das für uns nötigste weiter vereinfacht): http://www.u-wert.net/u-wert-messen/ - dort sind auch die prinzipiellen Nachteile dieser Schätzung diskutiert worden. Ich habe meine Messreihe vor knapp einem Jahr durchgeführt und immer mal wieder das Ergebnis mit der realen Wandtemperatur verglichen: Die Abweichung lag maximal bei 1,5 Grad, normalerweise stimmte sie aber auf +/- 0,5 Grad genau. Damit kann ich gut leben ;-) Möglicherweise funktioniert das bei euch nicht so gut - einfach testen.

==Alles zusammenpacken==

Die zwei neuen Werte (Wandtemperatur und „Wandfeuchte“ - bessergesagt, relative Luftfeuchte in Wandnähe) können wir nun z.B. in die UserReadings unseres Wandthermostaten packen. Hier mal ein Beispiel zum Kopieren in das Feld für das UserReadings-Attribut:

wandTemp { sprintf("%.1f", wallSurfaceTemp(ReadingsVal("kuechenthermometer","temperature",15),ReadingsVal("aussenthermometer","temperature",0),0.68)) }, \
wandHumidity { sprintf("%.1f", shiftRelHumidity( ReadingsVal("kuechenthermometer","temperature",17), ReadingsVal("kuechenthermometer","humidity",90), \
wallSurfaceTemp( ReadingsVal("kuechenthermometer","temperature",15), ReadingsVal("aussenthermometer","temperature",0), 0.68) ) ) }

Nicht vergessen, die 0.68 durch euren ermittelten K-wert zu ersetzen und event-on-change-reading anzupassen falls gesetzt, so dass ihr auch Events für die Userreadings bekommt.

Nun könnt ihr beide Werte ganz normal in Plots einfügen, euch Warnungen bei wandHumidity > 70% oder 80% schicken lassen oder das ganze auch per DOIF zur Entfeuchterregelung benutzen:

define di_bad.oben.luftentfeuchter \
DOIF ([bad.oben.thermometer:wandHumidity] > 68 and [bad.oben.fenster] eq "geschlossen") (set bad.oben.luftentfeuchter_Sw on) \
DOELSEIF ([bad.oben.thermometer:wandHumidity] < 60) (set bad.oben.luftentfeuchter_Sw off) \
DOELSEIF ([bad.oben.fenster] eq "offen") (set bad.oben.luftentfeuchter_Sw off)

Hier regele ich einen Luftentfeuchter an einem Homematic Zwischenstecker mit Leistungsmessung genau so, dass die Wand immer unter 70% bleibt (mit 2% Sicherheitsmarge). Und beim Lüften geht das Ding sofort aus. Ihr müsst dann nur noch einen Luftentfeuchter finden, der diese Art des Ein-/Ausschaltens per Steckerziehen mitmacht und ein wenig mit der Hysterese (dem Abschaltpunkt - hier 60%) spielen, so dass in euren Raum passt. Ich verwende übrigens einen comfee
MDF2-16DEN3 - ein sehr preiswerter Luftentfeuchter, der nicht wie viele andere die Eigenart hat, nach Stromwiederkehr einfach auszubleiben. Er genehmigt seinem Kompressor danach zwar eine kurze Zwangspause, läuft dann aber wieder an.

([http://forum.fhem.de/index.php/topic,29773.msg224962.html Aus dem Forum übernommen])

[[Kategorie:HOWTOS]]

DbLog

2015-01-25T15:49:52Z

Nesges: /* Links */ Typo korrigiert

{{Todo|Diese Seite muss noch vervollständigt werden. Informationen sind bisher verstreut, hauptsächlich über [[PGM3 dbLog]] und [[Neues Charting Frontend]].}}

{{Infobox Modul|
ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModTechName=93_DbLog.pm
|ModOwner=Tobias
}}
[[DbLog]] protokolliert, im Unterschied zu [[FileLog]], Fhem-Ereignisse in einer Datenbank.

== Definition ==
===db.conf===
DbLog wird durch 2 verschiedene Einträge aktiviert/definiert. In einer Datei namens '''db.conf''' werden die Parameter für eine Verbindung zur Datenbank (host, username, password, etc.) hinterlegt. Diese Datei kann in einem beliebigen Verzeichnis angelegt werden. Für eine MySQL-Datenbank sieht die db.conf folgendermassen aus:

%dbconfig= (
connection => "mysql:database=fhem;host=db;port=3306",
user => "fhemuser",
password => "fhempassword",
);

Im Verzeichnis '''contrib/dblog''' der FHEM-Installation befindet sich eine Beispielkonfiguration mit der Syntax für jeden unterstützen Datenbanktypen.

===Device===
Das DbLog Device wird dann in der fhem.cfg definiert mit
:<code>define <name> DbLog <configfilename> <regexp> </code>
wobei ''<configfilename>'' dem Pfad zur zuvor angelegten db.conf entspricht.
Ein Beispiel hierfür wäre:
:<code>define logdb DbLog ./db.conf .*:.* </code>
Die Angabe von .*:.* bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit vielen teils irrelevanten Werten gefüllt wird. Man kann daher die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Die erste Wildcard, also das erste .*, entspricht dem in FHEM verwendeten Device-Namen. Die zweite Wildcard entspricht dem vom Device ausgegebenen, zu loggenden Wert. Separiert werden beiden Angaben durch einen Doppelpunkt. Ein Beispiel um zwar alle definierten Devices zu erfassen, aber nur die Werte Temperatur, Ventilposition und Luftfeuchte in die Datenbank zu schreiben wäre:
:<code>define myDbLog DbLog ./db.conf .*:(temperature|valveposition|humidity).* </code>

== Datenbank ==
Unterstützte Datenbanksysteme (Auswahl):
* Sqlite
* MySQL
* PostGreSql

=== Tabellen ===
* current
* history

=== Tabellenlayout ===
DbLog ist auf eine feste Tabellenstruktur angewiesen. Man muss daher in seiner Datenbank eine Tabelle mit folgenden Spalten anlegen:
{| class="wikitable"
|-
! Spalte
! Beschreibung (en)
! Beschreibung (de)
! Beispiel
|-
| '''TIMESTAMP'''
| timestamp of event
| Zeitstempel
| 2007-12-30 21:45:22
|-
| '''DEVICE'''
| device name
| Device-Name
| Wetterstation
|-
| '''TYPE'''
| device type
| Device-Typ
| KS300
|-
| '''EVENT'''
| event specification as full string
| Eventspezifikation als Text
| humidity: 71 (%)
|-
| '''READING'''
| name of reading extracted from event
| Bezeichnung des Readings
| humidity
|-
| '''VALUE'''
| actual reading extracted from event
| Wert des Readings
| 71
|-
| '''UNIT'''
| unit extracted from event
| Einheit des Readings
| %
|-
|}

Die Vorlagen zur Anlage von Tabellen und Indices sind für jeden unterstützten Datenbanktyp im Verzeichnis '''contrib/dblog''' der FHEM-Installation, oder hier zu finden: [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/dblog/ Link]. Das MySQL-Skript (db_create_mysql.sql) legt eine neue Datenbank, das PostGres-Skript (db_create_postgresql.sql) ein neues Schema mit Namen "fhem" an.

== Integration von DBLog in eigene Module ==
=== Bereitstellung der UNITS ===
Mit der DbLog_SplitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten.
Weitere Informationen siehe hier: [[DevelopmentModuleIntro#X_DbLog_splitFn]]

== Links ==
* [[Heizleistung_und_Gasverbrauch|Beispiel das DbLog-Daten für SVG-Plots verwendet]]
* [[SVG-Plots von FileLog auf DbLog umstellen]]

DbLog

2015-01-25T15:49:27Z

Nesges: /* Links */ SVG Plots von FileLog auf DbLog umstellen

SVG-Plots von FileLog auf DbLog umstellen

2015-01-25T15:31:48Z

Nesges: Die Seite wurde neu angelegt: „Grundsätzlich verhält sich DbLog bei der Verwendung in SVG-Plots sehr ähnlich wie ein FileLog. So kann ein neuer Plot auf DbLog-D…“

Grundsätzlich verhält sich [[DbLog]] bei der Verwendung in [[Creating Plots|SVG-Plots]] sehr ähnlich wie ein [[FileLog]]. So kann ein neuer Plot auf DbLog-Daten in der [[FHEMWEB|FHEM-Oberfläche]] genauso angelegt werden wie beim FileLog, indem man an der Definition des DbLog Devices auf "Create SVG plot from DbLog" klickt. Wenn man von FileLog auf DbLog umstellt, möchte man aber evtl. nur die Definitionen der SVG-Plots anpassen. Hier einige Anmerkungen dazu.

== Define ==

Eine bestehende FileLog Definition für ein Thermostat könnte zB so aussehen:

define FileLog_W_HEIZUNG FileLog ./log/W_HEIZUNG-%Y.log W_HEIZUNG
attr FileLog_W_HEIZUNG logtype text
attr FileLog_W_HEIZUNG room hidden

define SVG_FileLog_W_HEIZUNG_1 SVG FileLog_W_HEIZUNG:SVG_FileLog_W_HEIZUNG_1:CURRENT
attr SVG_FileLog_W_HEIZUNG_1 room hidden

Bei Umstellung auf DbLog kann das FileLog-Device natürlich gelöscht werden, nachdem es durch ein allgemeines DbLog-Device ersetzt worden ist (siehe [[DbLog]]). Die Definition des Plots wird danach folgendermassen geändert:

define SVG_W_HEIZUNG_1 SVG DBLOG:SVG_DBLOG_W_HEIZUNG_1:CURRENT
attr SVG_W_HEIZUNG_1 room hidden

Mit dieser Anweisung wird ein SVG-Plot mit Namen ''SVG_W_HEIZUNG_1'' (der Name muss natürlich nicht geändert werden, soviel Zeit sollte man sich allerdings nehmen) angelegt, der seine Daten vom DbLog-Device ''DBLOG'' bezieht und mit Hilfe der Gplot-Datei ''SVG_DBLOG_W_HEIZUNG_1.gplot'' (auch dieser Name muss nicht zwingend geändert werden) rendert.

== Gplot-Datei ==

Die bestehende Gplot-Datei ''SVG_FileLog_W_HEIZUNG_1.gplot'' (im Verzeichnis ''www/gplot'') wird zunächst nach ''SVG_DBLOG_W_HEIZUNG_1.gplot'' kopiert. Sie kann gelöscht werden, wenn die Umstellung zufrieden stellend abgeschlossen ist. Geändert werden müssen nur die Zeilen, die mit ''#FileLog'' beginnen:

#FileLog 4:W_HEIZUNG.temperature\x3a:0:
#FileLog 4:W_HEIZUNG.desiredTemperature:0:
#FileLog 4:W_HEIZUNG.valveposition\x3a:0:

Daraus wird:

#DbLog W_HEIZUNG:temperature:0:
#DbLog W_HEIZUNG:desiredTemperature:0:
#DbLog W_HEIZUNG:valveposition:0:

''#FileLog'' wird durch ''#DbLog'' ersetzt. Die Angabe der Feldnummer vor dem Device (hier: "4") fällt weg, ebenso evtl. notierte Sonderzeichen am Ende der Readings-Bezeichnung (hier "\x3a"). Ansonsten bleibt der Inhalt der Gplot-Datei gleich.

===@fld===
Ein Sonderfall in der Notation liegt in der Verwendung von Mappings mit Hilfe des @fld-Arrays (siehe auch [[Creating Plots]]). Da es dieses Array in der Form in DbLogs nicht gibt, muss auf eine Zuweisung der Variable $val umgestellt werden. Lautet die Anweisung bei Verwendung von FileLog zB:

#FileLog 3:W_FENSTER:onoff::$fld[2]=~"1"?24:-10

muss sie für DbLog folgendermassen geändert werden:

#DbLog W_FENSTER:onoff:::$val=($val=~'1'?24:-10)

Insbesondere ist auch der zusätzliche Doppelpunkt vor der Anweisung zu beachten (Grund ist mir leider nicht bekannt, bitte ergänzen!).

===logProxy===

#logProxy FileLog:FileLog_W_HEIZUNG:4:W_HEIZUNG.valveposition\x3a:0:

wird zu

#logProxy DbLog:DBLOG:W_HEIZUNG:valveposition:0:

Näheres dazu unter [[LogProxy]].

[[Kategorie:HOWTOS]]

DbLog

2015-01-25T13:59:17Z

Nesges: /* Definition */ ausführlichere Infos zur db.conf ergänzt

DbLog

2015-01-25T13:51:15Z

Nesges: /* Tabellenlayout */ Formatierung der Spaltenbeschreibung als Tabelle; Hinweis auf lokales contrib-Verzeichnis und Aktionen der SQL-Skripte ergänzt

{{Todo|Diese Seite muss noch vervollständigt werden. Informationen sind bisher verstreut, hauptsächlich über [[PGM3 dbLog]] und [[Neues Charting Frontend]].}}

{{Infobox Modul|
ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModTechName=93_DbLog.pm
|ModOwner=Tobias
}}
[[DbLog]] protokolliert, im Unterschied zu [[FileLog]], Fhem-Ereignisse in einer Datenbank.

== Definition ==
DbLog wird durch 2 verschiedene Einträge aktiviert/definiert. In einer Datei namens db.conf werden die Parameter für eine Verbindung zur Datenbank (host, username, password, etc.) hinterlegt. Diese Datei kann in einem beliebigen Verzeichnis angelegt werden.
Das DbLog Device wird dann in der fhem.cfg definiert mit
:<code>define <name> DbLog <configfilename> <regexp> </code>
wobei ''<configfilename>'' dem Pfad zur zuvor angelegten db.conf entspricht.
Ein Beispiel hierfür wäre:
:<code>define logdb DbLog ./db.conf .*:.* </code>
Die Angabe von .*:.* bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit vielen teils irrelevanten Werten gefüllt wird. Man kann daher die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Die erste Wildcard, also das erste .*, entspricht dem in FHEM verwendeten Device-Namen. Die zweite Wildcard entspricht dem vom Device ausgegebenen, zu loggenden Wert. Separiert werden beiden Angaben durch einen Doppelpunkt. Ein Beispiel um zwar alle definierten Devices zu erfassen, aber nur die Werte Temperatur, Ventilposition und Luftfeuchte in die Datenbank zu schreiben wäre:
:<code>define myDbLog DbLog ./db.conf .*:(temperature|valveposition|humidity).* </code>

== Datenbank ==
Unterstützte Datenbanksysteme (Auswahl):
* Sqlite
* MySQL
* PostGreSql

=== Tabellen ===
* current
* history

=== Tabellenlayout ===
DbLog ist auf eine feste Tabellenstruktur angewiesen. Man muss daher in seiner Datenbank eine Tabelle mit folgenden Spalten anlegen:
{| class="wikitable"
|-
! Spalte
! Beschreibung (en)
! Beschreibung (de)
! Beispiel
|-
| '''TIMESTAMP'''
| timestamp of event
| Zeitstempel
| 2007-12-30 21:45:22
|-
| '''DEVICE'''
| device name
| Device-Name
| Wetterstation
|-
| '''TYPE'''
| device type
| Device-Typ
| KS300
|-
| '''EVENT'''
| event specification as full string
| Eventspezifikation als Text
| humidity: 71 (%)
|-
| '''READING'''
| name of reading extracted from event
| Bezeichnung des Readings
| humidity
|-
| '''VALUE'''
| actual reading extracted from event
| Wert des Readings
| 71
|-
| '''UNIT'''
| unit extracted from event
| Einheit des Readings
| %
|-
|}

Die Vorlagen zur Anlage von Tabellen und Indices sind für jeden unterstützten Datenbanktyp im Verzeichnis '''contrib/dblog''' der FHEM-Installation, oder hier zu finden: [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/dblog/ Link]. Das MySQL-Skript (db_create_mysql.sql) legt eine neue Datenbank, das PostGres-Skript (db_create_postgresql.sql) ein neues Schema mit Namen "fhem" an.

== Integration von DBLog in eigene Module ==
=== Bereitstellung der UNITS ===
Mit der DbLog_SplitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten.
Weitere Informationen siehe hier: [[DevelopmentModuleIntro#X_DbLog_splitFn]]

== Links ==
* [[Heizleistung_und_Gasverbrauch|Beispiel das DbLog-Daten für SVG-Plots verwendet]]

DbLog

2015-01-25T13:34:50Z

Nesges: /* Definition */ Typos korrigiert

{{Todo|Diese Seite muss noch vervollständigt werden. Informationen sind bisher verstreut, hauptsächlich über [[PGM3 dbLog]] und [[Neues Charting Frontend]].}}

{{Infobox Modul|
ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModTechName=93_DbLog.pm
|ModOwner=Tobias
}}
[[DbLog]] protokolliert, im Unterschied zu [[FileLog]], Fhem-Ereignisse in einer Datenbank.

== Definition ==
DbLog wird durch 2 verschiedene Einträge aktiviert/definiert. In einer Datei namens db.conf werden die Parameter für eine Verbindung zur Datenbank (host, username, password, etc.) hinterlegt. Diese Datei kann in einem beliebigen Verzeichnis angelegt werden.
Das DbLog Device wird dann in der fhem.cfg definiert mit
:<code>define <name> DbLog <configfilename> <regexp> </code>
wobei ''<configfilename>'' dem Pfad zur zuvor angelegten db.conf entspricht.
Ein Beispiel hierfür wäre:
:<code>define logdb DbLog ./db.conf .*:.* </code>
Die Angabe von .*:.* bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit vielen teils irrelevanten Werten gefüllt wird. Man kann daher die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Die erste Wildcard, also das erste .*, entspricht dem in FHEM verwendeten Device-Namen. Die zweite Wildcard entspricht dem vom Device ausgegebenen, zu loggenden Wert. Separiert werden beiden Angaben durch einen Doppelpunkt. Ein Beispiel um zwar alle definierten Devices zu erfassen, aber nur die Werte Temperatur, Ventilposition und Luftfeuchte in die Datenbank zu schreiben wäre:
:<code>define myDbLog DbLog ./db.conf .*:(temperature|valveposition|humidity).* </code>

== Datenbank ==
Unterstützte Datenbanksysteme (Auswahl):
* Sqlite
* MySQL
* PostGreSql

=== Tabellen ===
* current
* history

=== Tabellenlayout ===
DbLog ist auf eine feste Tabellenstruktur angewiesen. Man muss daher in seiner Datenbank eine Tabelle mit folgenden Spalten anlegen:
* TIMESTAMP: timestamp of event, e.g. 2007-12-30 21:45:22
* DEVICE: device name, e.g. Wetterstation
* TYPE: device type, e.g. KS300
* EVENT: event specification as full string, e.g. humidity: 71 (%)
* READING: name of reading extracted from event, e.g. humidity
* VALUE: actual reading extracted from event, e.g. 71
* UNIT: unit extracted from event, e.g. %

Die Vorlagen zum Aufbau von Tabellen und Indices sind für jeden unterstützten Datenbanktyp hier zu finden: [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/dblog/ Link]

== Integration von DBLog in eigene Module ==
=== Bereitstellung der UNITS ===
Mit der DbLog_SplitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten.
Weitere Informationen siehe hier: [[DevelopmentModuleIntro#X_DbLog_splitFn]]

== Links ==
* [[Heizleistung_und_Gasverbrauch|Beispiel das DbLog-Daten für SVG-Plots verwendet]]

MAX

2015-01-15T00:42:04Z

Nesges: Typo korrigiert

'''MAX!''' ist eine Heizungssteuerung, die die Raumtemperatur durch funkvernetzte Heizkörperthermostate an den Heizkörpern regelt. MAX! stellt eine Alternative zur [[:Kategorie:FHT Components|FHT]] und [[HomeMatic]] Heizungsteuerung dar.

== Features ==
* Bidirektionale Kommuniktion (jeder Befehl wird mit ACK quittiert)
* Heizkörperthermostate übertragen auch die gemessene Temperatur

== FHEM Module ==
Die MAX Komponenten können über den MAX!Cube per Modul 00_MAXLAN oder über einen [[CUL]] oder [[CUNO]] per 14_CUL_MAX gesteuert werden. In beiden Fällen werden die einzelnen MAX! Geräte vom Modul 10_MAX
bereitgestellt.

Nachteil vom Cube ist, dass man ein Polling machen muss, um zu sehen ob sich der Status eines Gerätes geändert hat. Z.B. checkt man das alle 30 Sekunden. Dann sieht man aber auch Änderungen möglicherweise erst nach 30 Sekunden. Beim CUL sieht man die Funknachrichten direkt. Es wird aber auch ein Kombimodus unterstützt, in welchem man alles über den MAXLAN steuert, der CUL_MAX aber für zeitnahe Benachrichtigungen sorgt.

== Komponenten ==
=== Limit ===
* Auf 8 Thermostate pro Raum beschränkt
* Limit mit Cube liegt bei ca. 140 Geräten. Durch die [[1% Regel]] dürften es aber in der Praxis weniger sein

=== Heizkörperthermostate ===
Unterstützt wird das Einstellen von

* desiredTemperature = auto (Wochenprogramm), manuell (4.5 - 30.5), eco, comfort, boost, until
** (Besonderheit der Werte: 4.5 = Off und 30.5 = On)
* ecoTemperature, comfortTemperature, measurementOffset, maximumTemperature, minimumTemperature, windowOpenTemperature, windowOpenDuration

und das Auslesen

* der gemessenen Temperatur. (Hinweis: Wird bei Verwendung des MAX CUBE nicht regelmäßig aktualisiert)

=== Fensterkontakte ===
Der aktuelle Status (offen/geschlossen) wird (praktisch ohne Verzögerung) angezeigt. '''Nur bei CUL, oder?'''

Falls wir nicht mit Ack antworten, wird er mehrmals wiederholt.

Die Fensterkontakte können zusätzlich direkt an mehrere Heizkörperthermostate angelernt werden, und versetzen diese dann automatisch in windowOpenTemperature während sie geöffnet sind.

Wenn der Fensterkontakt an mindestens ein Heizkörperthermostat angelernt ist, dann sendet er zusätzlich stündlich seinen aktuellen Zustand.

'''Beispiel Autocreate'''
MAXLAN_Parse: Paired new device, type ShutterContact, addr 1a2b3c, serial JEQ0123456
autocreate: define MAX_1a2b3c MAX ShutterContact 1a2b3c
autocreate: define FileLog_MAX_1a2b3c FileLog /fhem/log/MAX_1a2b3c-%Y.log MAX_1a2b3c

'''Beispiel Definition'''
define MAX_1a2b3c MAX ShutterContact 1a2b3c

'''Beispiel Log'''
==> MAX_1a2b3c-2013.log <==
2013-10-20_18:52:08 MAX_1a2b3c battery: ok
2013-10-20_18:52:08 MAX_1a2b3c onoff: 0
2013-10-20_18:52:08 MAX_1a2b3c closed

=== Wandthermostate ===
Unterstützt wird das Einstellen von

* desiredTemperature (siehe Heizkörperthermostate), ecoTemperature, comfortTemperature

und das Auslesen

* der gemessenen Temperatur.

=== Eco-Taster ===
'''Achtung''': Zumindest über MAXLAN lässt sich der Zustand weder auslesen, noch wird man über Veränderungen informiert.

Per CUL_MAX funktioniert der Eco-Taster problemlos.

==== Beispielhafte Definition ====
:<code>define BUTTON.EG MAX PushButton 069d33</code>

==== Beispielhafte Event-Ausgabe ====

2013-07-02 21:06:14 MAX BUTTON.EG battery: ok
2013-07-02 21:06:14 MAX BUTTON.EG onoff: 0
2013-07-02 21:06:14 MAX BUTTON.EG closed

Wobei gilt
{| class="wikitable"
|-
! onoff !! Bedeutung
|-
| 0 || Eco
|-
| 1 || Auto
|}

== Anlernen per CUL ==
Das Anlernen funktioniert nur mit zurückgesetzen (Werksreset, also entweder alle 3 Tasten am Heizkörperthermostate betätigen, Batterien einlegen, Anzeige rES; oder in FHEM set factoryReset) Heizkörperthermostaten. Bereits an einen Cube angelernte Heizungsregler können '''nicht''' an ein CUL angemeldet werden, hier ist dann nur das "mitlesen" der Funkbotschaften möglich.

Info: Durch den Reset geht auch ein evtl. per Cube eingestelltes Automatikprogramm verloren.

== Konfiguration ==
Siehe [http://fhem.de/commandref.html#CUL_MAX commandref].

Die Module sind so konzipiert, dass man die offizielle Max! Software nicht benutzen muss. Man kann alles aus FHEM heraus machen. Nachdem das MAXLAN oder CUL_MAX Modul konfiguriert wurden (siehe unten), werden bereits gepairte Geräte automatisch erkannt.

=== MAXLAN ===
Minimale Konfiguration:
:<code>define ml MAXLAN 192.168.178.2</code>
wobei 192.168.178.2 die IP des MAX! Cube ist. Das MAXLAN-Modul findet selbstständig bereits gepairte Geräte und trägt diese in die Konfigurationsdatei fhem.cfg ein. Diese können dann im WEB-Interface mittels „alias“ einen eindeutigen Namen bekommen.

=== CUL_MAX ===
Minimale Konfiguration:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
attr CUL0 rfmode MAX
define cm CUL_MAX 123456</nowiki>

=== Anlernen ===
Dazu muss der "pairmode" auf MAXLAN/CUL_MAX per
:<code>set ml/cm pairmode</code>
oder über das Web-Interface aktiviert werden. Falls kein Parameter angegeben wird, ist er standardmäßig für 60 Sekunden aktiviert. In dieser Zeit können MAX! Geräte nach deren Anleitung in den Anlernmodus versetzt werden, um sie mit FHEM zu pairen.

=== Geräte untereinander anlernen ===
Es gibt einen anderen Befehl, um Devices untereinander anzulernen (in neueren Versionen des MAX Moduls enthalten, heißt "associate").

Wenn man z.B.
:<code>set MAXFensterKontakt0 associate MaxHeizkörperthermostat3</code>
ausführt, dann sendet der MAXFensterKontakt0 jede Änderung zusätzlich (direkt über Funk, ohne Cube oder FHEM) an das MaxHeizkörperthermostat3.

Damit MaxHeizkörperthermostat3 auch auf die Nachrichten vom MAXFensterKontakt0 hört, muss noch ein
set MaxHeizkörperthermostat3 associate MAXFensterKontakt0 erfolgen.

Dann wechselt MaxHeizkörperthermostat3 immer dann auf die windowOpenTemperature, wenn der AXFensterKontakt0 offen ist. Dabei muss die groupId von beiden Geräte gar nicht gleich sein! (Die Semantik der groupId erschließt sich mir deshalb noch nicht ganz. Ich glaube, man kann damit Befehle (ala set desiredTemperature) an mehrere Thermostate gleichzeitig richten. Im Moment sendet FHEM einfach an jedes Thermostat einen Befehl.)

Wahrscheinlich funktioniert associate genauso zwischen Heizkörper/Wandthermostaten. Das müsste mal jemand ausprobieren und dann hier berichten.

=== Temperatursturzerkennung ===
Die Heizkörperthermostate verfügen über eine interne "Fenster-offen Erkennung" (Temperatursturzerkennung). Wird diese ausgelöst, regeln sie für die Zeit die unter "windowOpenDuration" festgelegt wurde auf die als "windowOpenTemperature" festgelegt Temperatur herunter und danach wieder auf die zuvor eingestellte Temperatur zurück.

Nachteil: Die Erkennung benötigt etwas Zeit und reagiert nicht sofort wie es beim Fensterkontakt oben der Fall ist

Vorteil: Es ist kein Fensterkontakt erforderlich

'''Wichtig:''' Setzt man die windowOpenTemperature auf "Off" (= 4.5 Grad), dann ist die Fenster-offen-Funktion abgeschaltet. Und auch wenn die desiredTemperature gerade auf "On" (= 30.5 Grad") steht, geht der Heizkörper nicht in die Fenster-offen-Funktion.

=== Externer Sensor für Fenster-offen-Erkennung ===
Ziel dieses Abschnittes ist es, einen externen Sensor (z.B. 1-Wire o.ä.) zu benutzen, um die MAX Heizkörperthermostate in und aus dem Fenster-offen Modus zu holen. Dazu sei bereits ein CUL, ein CUL_MAX und ein MAX Heizkörper definiert:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>

Wir müssen einmalig den internen Fake-Fensterkontakt mit dem Heizkörper assozieren
:<code>set Heizung associate fakeShutterContact</code>
damit dieser die Nachrichten vom Fensterkontakt akzeptiert.

Nun können wir per
:<code>set cm fakeSC Heizung 1</code>
die Nachricht "Fenster offen" an die Heizung senden und per
:<code>set cm fakeSC Heizung 0</code>
die Nachricht "Fenster zu".

=== Externer Temperatursensor für Heizkörperregelung ===
Ziel dieses Abschnittes ist es, einen externen Sensor (z.B. 1-Wire o.ä.) zu benutzen, um die MAX Heizkörperthermostate zu regeln. Dazu sei bereits ein CUL, ein CUL_MAX und ein MAX Heizkörper definiert:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>

Wir müssen einmalig das interne Fake-Wandthermostat mit dem Heizkörper assozieren:
:<code>set Heizung associate fakeWallThermostat</code>
damit dieser die Nachrichten vom Wandthermostat akzeptiert. Achtung: Dies schaltet im
Heizkörperthermostat die Regelung mit dem internen Temperaturfühler aus. Ohne die gleich kommenden "fakeWT" Nachrichten wird das Heizkörperthermostat nicht mehr regeln.

Nun können wir per
:<code>set cm fakeWT Heizung 14.5 12.1</code>
die desiredTemperature 14.5 und gemessene Temperatur 12.1 an die Heizung senden. Diese wird dann die Ventile öffnen, bis wir ein "fakeWT" absetzten, dessen gemessene Temperatur höher als die desiredTemperature ist.

Falls man zu lange Zeit (ca. 30 Minuten) kein neues "fakeWT" sendet, wird bei der Heizung das Attribut rferror gleich 1. Es ist nicht klar, ob das neben diesem Attribut auch Auswirkung auf die Funktionalität hat. Es wurde beobachtet, dass dann der interne Temperatursensor bis zum nächsten FakeWT aktiviert wird.

Beispiel eines automatischen Sendens einer externen Temperatur, der externe Temperatursensor heißt "WS300":

<nowiki>define SendExtTemp notify WS300:temperature.* {
MaxFakeWallThermostat("Heizung", %EVTPART1);
}</nowiki>

Dazu die Funktion, bitte in 99_MyUtils.pm eintragen:

sub MaxFakeWallThermostat($$)
{
my ($heizung, $aktTemp) = @_;
my $CULMAX = $defs{$heizung}{LASTInputDev};
my $desiredTemp = ReadingsVal($heizung, "desiredTemperature", undef);
my $windowOpenTemp = ReadingsVal($heizung, "windowOpenTemperature", undef);
my $lastTemp = ReadingsVal($heizung, "LastExtTemperature", 0);
my $lastSet = ReadingsTimestamp($heizung, "LastExtTemperature", 0);
if($desiredTemp && $windowOpenTemp &&
$desiredTemp != $windowOpenTemp &&
(time()-time_str2num($lastSet) >= 600 || abs($aktTemp-$lastTemp)>=0.2 )) {
Log 3, "set $CULMAX fakeWT $heizung $desiredTemp $aktTemp";
readingsSingleUpdate($defs{$heizung}, "LastExtTemperature", $aktTemp, 0);
fhem("set $CULMAX fakeWT $heizung $desiredTemp $aktTemp");
}
}

In diesem Beispiel heißt das zu steuernde Thermostat "Heizung". Die vom externen Sensor gemessene Temperatur wird nur unter den folgenden Voraussetzungen gesendet:
* das Thermostat befindet sich nicht im "Fenster-offen" Modus, und
* das letzte Senden liegt mindestens 10min zurück
* oder die gemessene Temperatur weicht um mindestens 0.2°C von der letzten gesendeten Temperatur ab

=== Wochenheizplan für Wandthermostat/Ventilantriebe erstellen ===
Ein Heizplan, den das Wandthermostat und auch der Ventilantrieb versteht und speichern kann, sieht folgendermaßen aus:
:<code>set WZ_Wandthermostat weekProfile Mon 17,17:30,20,23:00,17 Tue 17,17:30,20,23:00,17 Wed 17,17:30,20,23:00,17 Thu 17,17:30,20,23:00,17 Fri 17,15:00,20,23:00,17 Sat 17,11:00,20,23:00,17 Sun 17,11:00,20,23:00,17</code>
Genauer erläutert wird die Funktionsweise auch in der [http://fhem.de/commandref.html#MAX commandref].

Der gesamte Block kann kopiert und als FHEM Befehl abgesetzt werden. Unter Umständen benötigt das Speichern bzw. Übertragen wegen der Größe etwas Zeit, bevor die aktuellen, neu gesetzten Werte wieder ausgelesen werden können.

'''Bitte folgendes beachten:'''

Es gibt im Zusammenhang mit dem Wochenprogramm ein Problem mit dem letzten Schaltpunkt des Tages.
Der Workaround wurde [http://forum.fhem.de/index.php/topic,17231.msg112738.html#msg112738 hier]
beschrieben.
Man muss dafür sorgen, dass man kurz vor Ende des Tages noch einen Schaltpunkt setzt! Bei mir hat sich ein Schaltpunkt (ohne Änderung der Soll-Temperatur) um 23:55 bewährt:
:<code>set WZ_Wandthermostat weekProfile Mon 17,17:30,20,22:00,17,23:55,17</code>

=== Werte Plotten ===
[[File:Plot_MAX_Beispiel.png|thumb|right|Plot eines MAX Heizkörperthermostates]]
In den Log-Dateien wird regelmäßig der Batteriestatus, die Soll-Temperatur, die Ventilstellung und die Ist-Temperatur (Vorsicht: Wird nicht zuverlässig, möglicherweise nur bei einer Änderung der Ventilstellung übertragen.)

Inhalt der LOG-Datei eines Heizkörperthermostates:

<nowiki>2012-12-30_08:55:31 MAX_018d3f battery: ok
2012-12-30_08:55:31 MAX_018d3f desiredTemperature: 19.5
2012-12-30_08:55:31 MAX_018d3f valveposition: 83
2012-12-30_08:55:31 MAX_018d3f temperature: 16.4</nowiki>

Mit folgender Plot-Datei (max_temp.gplot) kann der Verlauf der Sensordaten gut angezeigt werden.

<nowiki>set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set y2tics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur in Grad Celsius"
set ylabel "Signal in %"
#FileLog 4:desiredTemperature:0:
#FileLog 4:temperature:0:
#FileLog 4:valveposition:0:
plot \
"< egrep 'desiredTemperature' <IN>"\
using 1:4 axes x1y2 title 'Soll-Temperatur (C)' with lines lw 2 \
"< egrep 'temperature' <IN>"\
using 1:4 axes x1y2 title 'Ist-Temperatur(ungenau)(C)' with lines lw 2 \
"< egrep 'valveposition' <IN>"\
using 1:4 axes x1y1 title 'Ventil (%)' with lines lw 2</nowiki>
Einbinden eines Plots in der fhem.cgf

<nowiki>#Werte plotten
define MAX_017840_weblink weblink fileplot FileLog_MAX_017840:max_temp:CURRENT
attr MAX_017840_weblink label "Kueche Soll-Temperatur Min $data{min1}, Max $data{max1}, Last $data{currval1}"
attr MAX_017840_weblink room MAX</nowiki>

=== Nützliche kleine Erweiterungen ===
'''Einen Alias-Namen vergeben für eine bessere Lesbarkeit im Webinterface'''
:<code>attr MAX_018d3f alias Kueche</code>
'''Die Anzeigen für die einzelnen File-Logs füllen das Webinterface schnell und machen es unübersichtlich.''' Die File-Logs können einfach in einen separaten Raum verbannt werden.
:<code>attr FileLog_MAX_018d3f room LOG</code>
'''Einstellmöglichkeit für die Soll-Temperatur direkt in der „Raum-Seite“ schaffen.''' Die Temperatur wird dauerhaft auf einen bestimmten Wert gestellt. Das Wochenprogramm in dem Thermostat wird deaktiviert.
:<code>attr MAX_018d3f webCmd desiredTemperature</code>

'''Soll-Temperatur setzen, ohne das automatische Programm des Thermostates abzuschalten.'''
Es besteht die Möglichkeit eine Soll-Temperatur bis zum nächsten Schaltzeitpunkt zu setzen. Zum Beispiel kann das automatische Wochenprogramm in den Thermostaten dazu genutzt werden, nur abends die Soll-Temperatur zu senken. So läuft die Heizung nachts nicht voll durch. Wenn jedoch die Temperatur im Web-Interface von Fhem verändert wird, wird auch der Thermostat auf manuell gesetzt. So greift das Wochenprogramm nicht mehr. Abhilfe schafft der Befehl
:<code>set MAX_04711 desiredTemperature auto 20</code>
Damit die Eingabe komfortabel aus Fhem möglich ist, kann ein Dummy-Device erstellt werden:

<nowiki>#Dummy für die Schnell-Einstellung der Temperatur bis zum nächsten automatischen Schaltzeitpunkt
define HeizkoerperBad dummy
attr HeizkoerperBad room MAX,Heizungen
attr HeizkoerperBad setList state:eco,auto,14.0,16.0,17.0,18.0,19.0,20.0,21.0,22.0,23.0
attr HeizkoerperBad webCmd state
define HeizkoerperBad.ntfy notify HeizkoerperBad.* {\
my $valtemp = "%";;\
my $device = "MAX_04711";;\
my $cmd = 'set '.$device.' desiredTemperature auto '.$valtemp;;\
fhem($cmd);;\
}</nowiki>
Diese Dummy-Device kann alternativ oder ergänzend zu <code>attr MAX_018d3f webCmd desiredTemperature</code> verwendet werden.

== Internals ==
=== IST-Temperaturwerte ===
[[File:Plot_MAX_Beispiel.png|thumb|right|Plot eines MAX Heizkörperthermostates]]
Diese Abbildung zeigt, dass die IST-Temperatur nicht regelmäßig dem MAX CUBE mitgeteilt wird. Im Automatikbetrieb wird beim einer Änderung der Ventilstellung die neue Ventilstellung zusammen mit der aktuellen IST-Temperatur gesendet. Bei der Abbildung war die Therme in der Nacht ausgeschaltet. Daraufhin sank die Temperatur soweit ab, dass das Heizungsthermostat das Ventil in Maximalstellung geöffnet hat. Gegen 08:50 wurde die Therme eingeschaltet und die Soll-Temperatur an diesem Heizungsthermostat erhöht. Während dieser ganzen Zeit erfolgt keine Aktualisierung der Ist-Temperatur. So kommt es auch gegen 10:30 zu einem sprunghaften Temperaturanstieg von 13,5°C auf 19°C (siehe Markierung *A).

Die IST-Temperatur wird anscheinend aktualisiert bei einer Änderung der:

* Ventilstellung
* Soll-Temperatur
* des Betriebsmodis (Auto/Manuell)

Wer eine detaillierte Kurven wünscht, sollte sich den [[MAX! Temperatur-Scanner]] ansehen.

=== MAXLAN ===
=== CUL_MAX ===
The Max devices use a CC1100 chip. For parameters see rf_moritz.c in culfw.
The thermostats use a Wake-On-Radio, thus one has to send packets at the right time.

CC1100 initialization sequence on one of the max devices (not Cube) (format: addr value, both in hex):

<nowiki>00 08
02 46
04 C6
05 26
0B 06
10 C8 //MDMCFG4 DRATE_E=8
11 93 //MDMCFG3 DRATE_M=147, data rate = (256+DRATE_M)*2^DRATE_E/2^28*f_xosc = (9992.599) 1kbit/s (at f_xosc=26 Mhz)
12 03
15 34
17 00
18 18
19 16
1B 43
21 56
25 00
26 11
0D 21
0E 65
0F 6A
07 4C //PKTCTRL1: ADR_CHK=0 APPEND_STATUS=1 CRC_AUTOFLUSH=1 PQT=2 (preamble must have 8 toggling bits before sync word detection)
16 1C //RXTIME=4
RX_TIME_QUAL=1 (when rx timeout expires, keep receiving if either sync word is found or PQI is set (see PQT))
RX_TIME_RSSI=1 (terminate RX if there is no carrier sense within the first 8 symbol periods)
20 78 //WORCTRL, WOR_RES=00 (1.8-1.9 sec), RC_CAL=1, EVENT1=7 (48 ticks), RC_PD=0
1E 87 //WOREVT1
1F 6B //WOREVT0, i.e. EVENT0 = 34667
29 59
2C 81
2D 35
3E C3</nowiki>
<nowiki>Not set, i.e. factory defaults:
13 MDMCFG1 NUM_PREAMBLE=2 (4 preamble bytes)</nowiki>
From the configuration, we see that the

<nowiki>RC Oscillator: f_xosc/750 = 34666.66 Hz
Event1 = Event1(=48 ticks)/RC Oscillator = 1.385 ms
t_Event0 = 750/26Mhz * EVENT0 * 2^(5*WOR_RES) = 1.00 second
C(RX_TIME, WOR_RES)= 0.2254
rx timeout = EVENT0·C(RX_TIME, WOR_RES) ·26/X(=26) = 34667*0.2254 us = 7.8139 ms</nowiki>

The ShutterContact seems to always sleep. Thus it is necessary to trigger it manually (by opening/closing the window) to make it receive messages. Pushing the button may work to. It is also awake just after
pairing, so one may send messages right then. One can use the WakeUp message to keep it from sleeping for some time. (This is also the reason why in the official MAX software, one must trigger the ShutterContact
after removing it from the house. The "factoryReset" packet is sent directly after the "ShutterContactState" packet has been acked.)

== Probleme und Lösungen ==
=== Der Wandthermostat oder Heizthermostat reagieren nicht auf Änderungen über FHEM ===
Das Autocreate von FHEM erkennt, wenn aktiviert, die Geräte initial und legt auch Einträge an. Es fehlt aber noch das Pairing, da sonst keine Steuerung möglich ist!
Wenn im Log also Meldungen wie

<nowiki>2013.03.20 15:12:30 5: CUL_MAX_SendQueueHandler: 1 items in queue
2013.03.20 15:12:30 5: CUL_MAX_SendQueueHandler: 1 items in queue
2013.03.20 15:12:30 2: CUL_MAX_SendQueueHandler: Missing ack from 01c9bb for 0b05008212345601c9bb0000</nowiki>
auftauchen (im Verbose Modus 5), dann wurde vermutlich kein oder ein inkorrektes Paring durchgeführt.
Nach dem Pairing sollten diese Meldungen verschwinden und stattdessen etwas wie
:<code>2013.03.20 15:21:43 5: Got matching ack</code>
auftauchen.

[[Kategorie:Kontaktsensor (magnetisch)]]
[[Kategorie:MAX]]
[[Kategorie:Heizungsventile]]

MAX

2015-01-15T00:39:38Z

Nesges: Typo korrigiert

'''MAX!''' ist eine Heizungssteuerung, die die Raumtemperatur durch funkvernetzte Heizkörperthermostate an den Heizkörpern regelt. MAX! stellt eine Alternative zur [[:Kategorie:FHT Components|FHT]] und [[HomeMatic]] Heizungsteuerung dar.

== Features ==
* Bidirektionale Kommuniktion (jeder Befehl wird mit ACK quittiert)
* Heizkörperthermostate übertragen auch die gemessene Temperatur

== FHEM Module ==
Die MAX Komponenten können über den MAX!Cube per Modul 00_MAXLAN oder über einen [[CUL]] oder [[CUNO]] per 14_CUL_MAX gesteuert werden. In beiden Fällen werden die einzelnen MAX! Geräte vom Modul 10_MAX
bereitgestellt.

Nachteil vom Cube ist, dass man ein Polling machen muss, um zu sehen ob sich der Status eines Gerätes geändert hat. Z.B. checkt man das alle 30 Sekunden. Dann sieht man aber auch Änderungen möglicherweise erst nach 30 Sekunden. Beim CUL sieht man die Funknachrichten direkt. Es wird aber auch ein Kombimodus unterstützt, in welchem man alles über den MAXLAN steuert, der CUL_MAX aber für zeitnahe Benachrichtigungen sorgt.

== Komponenten ==
=== Limit ===
* Auf 8 Thermostate pro Raum beschränkt
* Limit mit Cube liegt bei ca. 140 Geräten. Durch die [[1% Regel]] dürften es aber in der Praxis weniger sein

=== Heizkörperthermostate ===
Unterstützt wird das Einstellen von

* desiredTemperature = auto (Wochenprogramm), manuell (4.5 - 30.5), eco, comfort, boost, until
** (Besonderheit der Werte: 4.5 = Off und 30.5 = On)
* ecoTemperature, comfortTemperature, measurementOffset, maximumTemperature, minimumTemperature, windowOpenTemperature, windowOpenDuration

und das Auslesen

* der gemessenen Temperatur. (Hinweis: Wird bei Verwendung des MAX CUBE nicht regelmäßig aktualisiert)

=== Fensterkontakte ===
Der aktuelle Status (offen/geschlossen) wird (praktisch ohne Verzögerung) angezeigt. '''Nur bei CUL, oder?'''

Falls wir nicht mit Ack antworten, wird er mehrmals wiederholt.

Die Fensterkontakte können zusätzlich direkt an mehrere Heizkörperthermostate angelernt werden, und versetzen diese dann automatisch in windowOpenTemperature während sie geöffnet sind.

Wenn der Fensterkontakt an mindestens ein Heizkörperthermostat angelernt ist, dann sendet er zusätzlich stündlich seinen aktuellen Zustand.

'''Beispiel Autocreate'''
MAXLAN_Parse: Paired new device, type ShutterContact, addr 1a2b3c, serial JEQ0123456
autocreate: define MAX_1a2b3c MAX ShutterContact 1a2b3c
autocreate: define FileLog_MAX_1a2b3c FileLog /fhem/log/MAX_1a2b3c-%Y.log MAX_1a2b3c

'''Beispiel Definition'''
define MAX_1a2b3c MAX ShutterContact 1a2b3c

'''Beispiel Log'''
==> MAX_1a2b3c-2013.log <==
2013-10-20_18:52:08 MAX_1a2b3c battery: ok
2013-10-20_18:52:08 MAX_1a2b3c onoff: 0
2013-10-20_18:52:08 MAX_1a2b3c closed

=== Wandthermostate ===
Unterstützt wird das Einstellen von

* desiredTemperature (siehe Heizkörperthermostate), ecoTemperature, comfortTemperature

und das Auslesen

* der gemessenen Temperatur.

=== Eco-Taster ===
'''Achtung''': Zumindest über MAXLAN lässt sich der Zustand weder auslesen, noch wird man über Veränderungen informiert.

Per CUL_MAX funktioniert der Eco-Taster problemlos.

==== Beispielhafte Definition ====
:<code>define BUTTON.EG MAX PushButton 069d33</code>

==== Beispielhafte Event-Ausgabe ====

2013-07-02 21:06:14 MAX BUTTON.EG battery: ok
2013-07-02 21:06:14 MAX BUTTON.EG onoff: 0
2013-07-02 21:06:14 MAX BUTTON.EG closed

Wobei gilt
{| class="wikitable"
|-
! onoff !! Bedeutung
|-
| 0 || Eco
|-
| 1 || Auto
|}

== Anlernen per CUL ==
Das Anlernen funktioniert nur mit zurückgesetzen (Werksreset, also entweder alle 3 Tasten am Heizkörperthermostate betätigen, Batterien einlegen, Anzeige rES; oder in FHEM set factoryReset) Heizkörperthermostaten. Bereits an einen Cube angelernte Heizungsregler können '''nicht''' an ein CUL angemeldet werden, hier ist dann nur das "mitlesen" der Funkbotschaften möglich.

Info: Durch den Reset geht auch ein evtl. per Cube eingestelltes Automatikprogramm verloren.

== Konfiguration ==
Siehe [http://fhem.de/commandref.html#CUL_MAX commandref].

Die Module sind so konzipiert, dass man die offizielle Max! Software nicht benutzen muss. Man kann alles aus FHEM heraus machen. Nachdem das MAXLAN oder CUL_MAX Modul konfiguriert wurden (siehe unten), werden bereits gepairte Geräte automatisch erkannt.

=== MAXLAN ===
Minimale Konfiguration:
:<code>define ml MAXLAN 192.168.178.2</code>
wobei 192.168.178.2 die IP des MAX! Cube ist. Das MAXLAN-Modul findet selbstständig bereits gepairte Geräte und trägt diese in die Konfigurationsdatei fhem.cfg ein. Diese können dann im WEB-Interface mittels „alias“ einen eindeutigen Namen bekommen.

=== CUL_MAX ===
Minimale Konfiguration:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
attr CUL0 rfmode MAX
define cm CUL_MAX 123456</nowiki>

=== Anlernen ===
Dazu muss der "pairmode" auf MAXLAN/CUL_MAX per
:<code>set ml/cm pairmode</code>
oder über das Web-Interface aktiviert werden. Falls kein Parameter angegeben wird, ist er standardmäßig für 60 Sekunden aktiviert. In dieser Zeit können MAX! Geräte nach deren Anleitung in den Anlernmodus versetzt werden, um sie mit FHEM zu pairen.

=== Geräte untereinander anlernen ===
Es gibt einen anderen Befehl, um Devices untereinander anzulernen (in neueren Versionen des MAX Moduls enthalten, heißt "associate").

Wenn man z.B.
:<code>set MAXFensterKontakt0 associate MaxHeizkörperthermostat3</code>
ausführt, dann sendet der MAXFensterKontakt0 jede Änderung zusätzlich (direkt über Funk, ohne Cube oder FHEM) an das MaxHeizkörperthermostat3.

Damit MaxHeizkörperthermostat3 auch auf die Nachrichten vom MAXFensterKontakt0 hört, muss noch ein
set MaxHeizkörperthermostat3 associate MAXFensterKontakt0 erfolgen.

Dann wechselt MaxHeizkörperthermostat3 immer dann auf die windowOpenTemperature, wenn der AXFensterKontakt0 offen ist. Dabei muss die groupId von beiden Geräte gar nicht gleich sein! (Die Semantik der groupId erschließt sich mir deshalb noch nicht ganz. Ich glaube, man kann damit Befehle (ala set desiredTemperature) an mehrere Thermostate gleichzeitig richten. Im Moment sendet FHEM einfach an jedes Thermostat einen Befehl.)

Wahrscheinlich funktioniert associate genauso zwischen Heizkörper/Wandthermostaten. Das müsste mal jemand ausprobieren und dann hier berichten.

=== Temperatursturzerkennung ===
Die Heizkörperthermostate verfügen über eine interne "Fenster-offen Erkennung" (Temperatursturzerkennung). Wird diese ausgelöst, regeln sie für die Zeit die unter "windowOpenDuration" festgelegt wurde auf die als "windowOpenTemperature" festgelegt Temperatur herunter und danach wieder auf die zuvor eingestellte Temperatur zurück.

Nachteil: Die Erkennung benötigt etwas Zeit und reagiert nicht sofort wie es beim Fensterkontakt oben der Fall ist

Vorteil: Es ist kein Fensterkontakt erforderlich

'''Wichtig:''' Setzt man die windowOpenTemperature auf "Off" (= 4.5 Grad), dann ist die Fenster-offen-Funktion abgeschaltet. Und auch wenn die desiredTemperature gerade auf "On" (= 30.5 Grad") steht, geht der Heizkörper nicht in die Fenster-offen-Funktion.

=== Externer Sensor für Fenster-offen-Erkennung ===
Ziel dieses Abschnittes ist es, einen externen Sensor (z.B. 1-Wire o.ä.) zu benutzen, um die MAX Heizkörperthermostate in und aus dem Fenster-offen Modus zu holen. Dazu sei bereits ein CUL, ein CUL_MAX und ein MAX Heizkörper definiert:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>

Wir müssen einmalig den internen Fake-Fensterkontakt mit dem Heizkörper assozieren
:<code>set Heizung associate fakeShutterContact</code>
damit dieser die Nachrichten vom Fensterkontakt akzeptiert.

Nun können wir per
:<code>set cm fakeSC Heizung 1</code>
die Nachricht "Fenster offen" an die Heizung senden und per
:<code>set cm fakeSC Heizung 0</code>
die Nachricht "Fenster zu".

=== Externer Temperatursensor für Heizkörperregelung ===
Ziel dieses Abschnittes ist es, einen externen Sensor (z.B. 1-Wire o.ä.) zu benutzen, um die MAX Heizkörperthermostate zu regeln. Dazu sei bereits ein CUL, ein CUL_MAX und ein MAX Heizkörper definiert:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>

Wir müssen einmalig das interne Fake-Wandthermostat mit dem Heizkörper assozieren:
:<code>set Heizung associate fakeWallThermostat</code>
damit dieser die Nachrichten vom Wandthermostat akzeptiert. Achtung: Dies schaltet im
Heizkörperthermostat die Regelung mit dem internen Temperaturfühler aus. Ohne die gleich kommenden "fakeWT" Nachrichten wird das Heizkörperthermostat nicht mehr regeln.

Nun können wir per
:<code>set cm fakeWT Heizung 14.5 12.1</code>
die desiredTemperature 14.5 und gemessene Temperatur 12.1 an die Heizung senden. Diese wird dann die Ventile öffnen, bis wir ein "fakeWT" absetzten, dessen gemessene Temperatur höher als die desiredTemperature ist.

Falls man zu lange Zeit (ca. 30 Minuten) kein neues "fakeWT" sendet, wird bei der Heizung das Attribut rferror gleich 1. Es ist nicht klar, ob das neben diesem Attribut auch Auswirkung auf die Funktionalität hat. Es wurde beobachtet, dass dann der interne Temperatursensor bis zum nächsten FakeWT aktiviert wird.

Beispiel eines automatischen Sendens einer externen Temperatur, der externe Temperatursensor heißt "WS300":

<nowiki>define SendExtTemp notify WS300:temperature.* {
MaxFakeWallThermostat("Heizung", %EVTPART1);
}</nowiki>

Dazu die Funktion, bitte in 99_MyUtils.pm eintragen:

sub MaxFakeWallThermostat($$)
{
my ($heizung, $aktTemp) = @_;
my $CULMAX = $defs{$heizung}{LASTInputDev};
my $desiredTemp = ReadingsVal($heizung, "desiredTemperature", undef);
my $windowOpenTemp = ReadingsVal($heizung, "windowOpenTemperature", undef);
my $lastTemp = ReadingsVal($heizung, "LastExtTemperature", 0);
my $lastSet = ReadingsTimestamp($heizung, "LastExtTemperature", 0);
if($desiredTemp && $windowOpenTemp &&
$desiredTemp != $windowOpenTemp &&
(time()-time_str2num($lastSet) >= 600 || abs($aktTemp-$lastTemp)>=0.2 )) {
Log 3, "set $CULMAX fakeWT $heizung $desiredTemp $aktTemp";
readingsSingleUpdate($defs{$heizung}, "LastExtTemperature", $aktTemp, 0);
fhem("set $CULMAX fakeWT $heizung $desiredTemp $aktTemp");
}
}

In diesem Beispiel heißt das zu steuernde Thermostat "Heizung". Die vom externen Sensor gemessene Temperatur wird nur unter den folgenden Voraussetzungen gesendet:
* das Thermostat befindet sich nicht im "Fenster-offen" Modus, und
* das letzte Senden liegt mindestens 10min zurück
* oder die gemessene Temperatur weicht um mindestens 0.2°C von der letzten gesendeten Temperatur ab

=== Wochenheizplan für Wandthermostat/Ventilantriebe erstellen ===
Ein Heizplan, den das Wandthermostat und auch der Ventilantrieb versteht und speichern kann, sieht folgendermaßen aus:
:<code>set WZ_Wandthermostat weekProfile Mon 17,17:30,20,23:00,17 Tue 17,17:30,20,23:00,17 Wed 17,17:30,20,23:00,17 Thu 17,17:30,20,23:00,17 Fri 17,15:00,20,23:00,17 Sat 17,11:00,20,23:00,17 Sun 17,11:00,20,23:00,17</code>
Genauer erläutert wird die Funktionsweise auch in der [http://fhem.de/commandref.html#MAX commandref].

Der gesamte Block kann kopiert und als FHEM Befehl abgesetzt werden. Unter Umständen benötigt das Speichern bzw. Übertragen wegen der Größe etwas Zeit, bevor die aktuellen, neu gesetzten Werte wieder ausgelesen werden können.

'''Bitte folgendes beachten:'''

Es gibt im Zusammenhang mit dem Wochenprogramm ein Problem mit dem letzten Schaltpunkt des Tages.
Der Workaround wurde [http://forum.fhem.de/index.php/topic,17231.msg112738.html#msg112738 hier]
beschrieben.
Man muss dafür sorgen, dass man kurz vor Ende des Tages noch einen Schaltpunkt setzt! Bei mir hat sich ein Schaltpunkt (ohne Änderung der Soll-Temperatur) um 23:55 bewährt:
:<code>set WZ_Wandthermostat weekProfile Mon 17,17:30,20,22:00,17,23:55,17</code>

=== Werte Plotten ===
[[File:Plot_MAX_Beispiel.png|thumb|right|Plot eines MAX Heizkörperthermostates]]
In den Log-Dateien wird regelmäßig der Batteriestatus, die Soll-Temperatur, die Ventilstellung und die Ist-Temperatur (Vorsicht: Wird nicht zuverlässig, möglicherweise nur bei einer Änderung der Ventilstellung übertragen.)

Inhalt der LOG-Datei eines Heizkörperthermostates:

<nowiki>2012-12-30_08:55:31 MAX_018d3f battery: ok
2012-12-30_08:55:31 MAX_018d3f desiredTemperature: 19.5
2012-12-30_08:55:31 MAX_018d3f valveposition: 83
2012-12-30_08:55:31 MAX_018d3f temperature: 16.4</nowiki>

Mit folgender Plot-Datei (max_temp.gplot) kann der Verlauf der Sensordaten gut angezeigt werden.

<nowiki>set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set y2tics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur in Grad Celsius"
set ylabel "Signal in %"
#FileLog 4:desiredTemperature:0:
#FileLog 4:temperature:0:
#FileLog 4:valveposition:0:
plot \
"< egrep 'desiredTemperature' <IN>"\
using 1:4 axes x1y2 title 'Soll-Temperatur (C)' with lines lw 2 \
"< egrep 'temperature' <IN>"\
using 1:4 axes x1y2 title 'Ist-Temperatur(ungenau)(C)' with lines lw 2 \
"< egrep 'valveposition' <IN>"\
using 1:4 axes x1y1 title 'Ventil (%)' with lines lw 2</nowiki>
Einbinden eines Plots in der fhem.cgf

<nowiki>#Werte plotten
define MAX_017840_weblink weblink fileplot FileLog_MAX_017840:max_temp:CURRENT
attr MAX_017840_weblink label "Kueche Soll-Temperatur Min $data{min1}, Max $data{max1}, Last $data{currval1}"
attr MAX_017840_weblink room MAX</nowiki>

=== Nützliche kleine Erweiterungen ===
'''Einen Alias-Namen vergeben für eine bessere Lesbarkeit im Webinterface'''
:<code>attr MAX_018d3f alias Kueche</code>
'''Die Anzeigen für die einzelnen File-Logs füllen das Webinterface schnell und machen es unübersichtlich.''' Die File-Logs können einfach in einen separaten Raum verbannt werden.
:<code>attr FileLog_MAX_018d3f room LOG</code>
'''Einstellmöglichkeit für die Soll-Temperatur direkt in der „Raum-Seite“ schaffen.''' Die Temperatur wird dauerhaft auf einen bestimmten Wert gestellt. Das Wochenprogramm in dem Thermostat wird deaktiviert.
:<code>attr MAX_018d3f webCmd desiredTemperature</code>

'''Soll-Temperatur setzen, ohne das automatische Programm des Thermostates abzuschalten.'''
Es besteht die Möglichkeit eine Soll-Temperatur bis zum nächsten Schaltzeitpunkt zu setzen. Zum Beispiel kann das automatische Wochenprogramm in den Thermostaten dazu genutzt werden, nur abends die Soll-Temperatur zu senken. So läuft die Heizung nachts nicht voll durch. Wenn jedoch die Temperatur im Web-Interface von Fhem verändert wird, wird auch der Thermostat auf manuell gesetzt. So greift das Wochenprogramm nicht mehr. Abhilfe schafft der Befehl
:<code>set MAX_04711 desiredTemperature auto 20</code>
Damit die Eingabe komfortabel aus Fhem möglich ist, kann ein Dummy-Device erstellt werden:

<nowiki>#Dummy für die Schnell-Einstellung der Temperatur bis zum nächsten automatischen Schaltzeitpunkt
define HeizkoerperBad dummy
attr HeizkoerperBad room MAX,Heizungen
attr HeizkoerperBad setList state:eco,auto,14.0,16.0,17.0,18.0,19.0,20.0,21.0,22.0,23.0
attr HeizkoerperBad webCmd state
define HeizkoerperBad.ntfy notify HeizkoerperBad.* {\
my $valtemp = "%";;\
my $device = "MAX_04711";;\
my $cmd = 'set '.$device.' desiredTemperature auto '.$valtemp;;\
fhem($cmd);;\
}</nowiki>
Diese Dummy-Device kann alternativ oder ergänzend zu <code>attr MAX_018d3f webCmd desiredTemperature</code> verwendet werden.

== Internals ==
=== IST-Temperaturwerte ===
[[File:Plot_MAX_Beispiel.png|thumb|right|Plot eines MAX Heizkörperthermostates]]
Diese Abbildung zeigt, dass die IST-Temperatur nicht regelmäßig dem MAX CUBE mitgeteilt wird. Im Automatikbetrieb wird beim einer Änderung der Ventilstellung die neue Ventilstellung zusammen mit der aktuellen IST-Temperatur gesendet. Bei der Abbildung war die Therme in der Nacht ausgeschaltet. Daraufhin sinkte die Temperatur soweit ab, dass das Heizungsthermostat das Ventil in Maximalstellung geöffnet hat. Gegen 08:50 wurde die Therme eingeschaltet und die Soll-Temperatur an diesem Heizungsthermostat erhöht. Während dieser ganzen Zeit erfolgt keine Aktualisierung der Ist-Temperatur. So kommt es auch gegen 10:30 zu einem sprunghaften Temperaturanstieg von 13,5°C auf 19°C (siehe Markierung *A).

Die IST-Temperatur wird anscheinend aktualisiert bei einer Änderung der:

* Ventilstellung
* Soll-Temperatur
* des Betriebsmodis (Auto/Manuell)

Wer eine detaillierte Kurven wünscht, sollte sich den [[MAX! Temperatur-Scanner]] ansehen.

=== MAXLAN ===
=== CUL_MAX ===
The Max devices use a CC1100 chip. For parameters see rf_moritz.c in culfw.
The thermostats use a Wake-On-Radio, thus one has to send packets at the right time.

CC1100 initialization sequence on one of the max devices (not Cube) (format: addr value, both in hex):

<nowiki>00 08
02 46
04 C6
05 26
0B 06
10 C8 //MDMCFG4 DRATE_E=8
11 93 //MDMCFG3 DRATE_M=147, data rate = (256+DRATE_M)*2^DRATE_E/2^28*f_xosc = (9992.599) 1kbit/s (at f_xosc=26 Mhz)
12 03
15 34
17 00
18 18
19 16
1B 43
21 56
25 00
26 11
0D 21
0E 65
0F 6A
07 4C //PKTCTRL1: ADR_CHK=0 APPEND_STATUS=1 CRC_AUTOFLUSH=1 PQT=2 (preamble must have 8 toggling bits before sync word detection)
16 1C //RXTIME=4
RX_TIME_QUAL=1 (when rx timeout expires, keep receiving if either sync word is found or PQI is set (see PQT))
RX_TIME_RSSI=1 (terminate RX if there is no carrier sense within the first 8 symbol periods)
20 78 //WORCTRL, WOR_RES=00 (1.8-1.9 sec), RC_CAL=1, EVENT1=7 (48 ticks), RC_PD=0
1E 87 //WOREVT1
1F 6B //WOREVT0, i.e. EVENT0 = 34667
29 59
2C 81
2D 35
3E C3</nowiki>
<nowiki>Not set, i.e. factory defaults:
13 MDMCFG1 NUM_PREAMBLE=2 (4 preamble bytes)</nowiki>
From the configuration, we see that the

<nowiki>RC Oscillator: f_xosc/750 = 34666.66 Hz
Event1 = Event1(=48 ticks)/RC Oscillator = 1.385 ms
t_Event0 = 750/26Mhz * EVENT0 * 2^(5*WOR_RES) = 1.00 second
C(RX_TIME, WOR_RES)= 0.2254
rx timeout = EVENT0·C(RX_TIME, WOR_RES) ·26/X(=26) = 34667*0.2254 us = 7.8139 ms</nowiki>

The ShutterContact seems to always sleep. Thus it is necessary to trigger it manually (by opening/closing the window) to make it receive messages. Pushing the button may work to. It is also awake just after
pairing, so one may send messages right then. One can use the WakeUp message to keep it from sleeping for some time. (This is also the reason why in the official MAX software, one must trigger the ShutterContact
after removing it from the house. The "factoryReset" packet is sent directly after the "ShutterContactState" packet has been acked.)

== Probleme und Lösungen ==
=== Der Wandthermostat oder Heizthermostat reagieren nicht auf Änderungen über FHEM ===
Das Autocreate von FHEM erkennt, wenn aktiviert, die Geräte initial und legt auch Einträge an. Es fehlt aber noch das Pairing, da sonst keine Steuerung möglich ist!
Wenn im Log also Meldungen wie

<nowiki>2013.03.20 15:12:30 5: CUL_MAX_SendQueueHandler: 1 items in queue
2013.03.20 15:12:30 5: CUL_MAX_SendQueueHandler: 1 items in queue
2013.03.20 15:12:30 2: CUL_MAX_SendQueueHandler: Missing ack from 01c9bb for 0b05008212345601c9bb0000</nowiki>
auftauchen (im Verbose Modus 5), dann wurde vermutlich kein oder ein inkorrektes Paring durchgeführt.
Nach dem Pairing sollten diese Meldungen verschwinden und stattdessen etwas wie
:<code>2013.03.20 15:21:43 5: Got matching ack</code>
auftauchen.

[[Kategorie:Kontaktsensor (magnetisch)]]
[[Kategorie:MAX]]
[[Kategorie:Heizungsventile]]

MAX! Thermostat für die Fussbodenheizung

2015-01-15T00:22:32Z

Nesges: Typo korrigiert

Nachfolgend wird eine Lösung beschrieben, das MAX! Thermostat für eine Fußbodenheizung einzusetzen.

== Aufgabenstellung ==
* eine zuvor ungeregelte Fußbodenheizung soll mit Hilfe eines MAX-Thermostats (HT.FUBO) geregelt werden
* es können keine bauliche Veränderungen durchgeführt werden
* das Steuerventil (an dem HT.FUBO zu montieren ist) befindet sich '''nicht''' im Raum der Fußbodenheizung (FUBO)
* im Raum der FUBO befindet sich ein weiterer kleiner Heizkörper (HT.BAD,Handtücher trocknen), der nicht den Raum selbst erwärmen kann, jedoch auch über einen MAX-Thermostat verfügt

== 1. Lösungs-Ansatz ==
* der Regler des MAX-Thermostats HT.FUBO ist zu deaktivieren
* das MAX-Thermostat arbeitet somit als reines Stellglied
* der Temperatur-Istwert wird von einem Funk-Sensor im Raum der FUBO bezogen
* als Regler wird das PID20-Modul eingesetzt
* FHEM verbindet die Komponenten Istwertgeber + Stellglied + Regler
<br />

==== Wie kann man das MAX-Thermostat als einfaches Stellglied einsetzen ? ====
* Solltemperatur auf ON stellen via : <pre> set HT.FUBO desiredTemperature on </pre>
* MAX Thermostat fährt nun auf 100%
* über maxValveSetting kann nun die Ventilstellung direkt vorgegeben werden, z.B. 50%
<pre> set HT.FUBO maxValveSetting 50</pre>

====Temperatur-Istwert====
* da sich das MAX-Thermostat nicht im Raum befindet, benötigen wir einen Temperaturgeber; dies kann jeder Temperatur-Geber sein, der sich in FHEM einbinden lässt. Im vorliegenden Fall wird ein HMS100TF verwendet.
<pre>define DG.BAD.TF HMS 4c81</pre>

====PID20====
* PID20 ist ein PID-Regler innerhalb von FHEM, der den deaktivierten Regler des MAX-Thermostats HT.FUBO ersetzen soll
* mit PID20 kann man anders als bei MAX, die Regelparameter verändern und an die Gegebenheiten anpassen
<pre> define PID.PID PID20 DG.BAD.TF:temperature HT.FUBO:maxValveSetting</pre>

====Sollwert einstellen====
* den Sollwert von PID20 kann man über FHEM einstellen

==== Variante A : Sollwert von HT.FUBO über HT.BAD vorgeben ====
* damit dient das im Raum befindliche MAX-Thermostat als Sollwert-Panel für die Fußbodenheizung
* wir spiegeln den Sollwert von HT.BAD auf den Sollwert von PID.PID via
<pre>
define HT.BAD.Event notify HT.BAD:(desiredTemperature:).* {fhem("set PID.PID desired %EVTPART1");;}
</pre>

==== Variante B : Istwert vom MAX-Thermostat statt vom HMS100TF Sensor beziehen ====
* da das MAX-Thermostat HT.BAD sich im Raum befindet, mißt es auch die Raum-Temperatur
* diese können wir als Istwert für PID.PID verwenden
* damit ändert sich die Definition:
<pre>
define PID.PID PID20 HT.BAD:temperature HT.FUBO:maxValveSetting
</pre>
* es ist hierbei jedoch dringend zu empfehlen den [[MAX!_Temperatur-Scanner]] einzusetzen, damit die Temperatur ausreichend oft erfasst wird

== Ergebnis (Variante B) ==
* die Regelung der Fußbodenheizung funktioniert bestens
[[Datei: 14 01 26.png |Regelung Fußbodenheizung mit MAX]]

[[Kategorie:MAX]]
[[Kategorie:Regelungstechnik]]

MAX

2015-01-14T15:24:44Z

Nesges: Typos korrigiert

'''MAX!''' ist eine Heizungssteuerung, die die Raumtemperatur durch funkvernetzte Heizkörperthermostate an den Heizkörpern regelt. MAX! stellt eine Alternative zur [[:Kategorie:FHT Components|FHT]] und [[HomeMatic]] Heizungsteuerung dar.

== Features ==
* Bidirektionale Kommuniktion (jeder Befehl wird mit ACK quittiert)
* Heizkörperthermostate übertragen auch die gemessene Temperatur

== FHEM Module ==
Die MAX Komponenten können über den MAX!Cube per Modul 00_MAXLAN oder über einen [[CUL]] oder [[CUNO]] per 14_CUL_MAX gesteuert werden. In beiden Fällen werden die einzelnen MAX! Geräte vom Modul 10_MAX
bereitgestellt.

Nachteil vom Cube ist, dass man ein Polling machen muss, um zu sehen ob sich der Status eines Gerätes geändert hat. Z.B. checkt man das alle 30 Sekunden. Dann sieht man aber auch Änderungen möglicherweise erst nach 30 Sekunden. Beim CUL sieht man die Funknachrichten direkt. Es wird aber auch ein Kombimodus unterstützt, in welchem man alles über den MAXLAN steuert, der CUL_MAX aber für zeitnahe Benachrichtigungen sorgt.

== Komponenten ==
=== Limit ===
* Auf 8 Thermostate pro Raum beschränkt
* Limit mit Cube liegt bei ca. 140 Geräten. Durch die [[1% Regel]] dürften es aber in der Praxis weniger sein

=== Heizkörperthermostate ===
Unterstützt wird das Einstellen von

* desiredTemperature = auto (Wochenprogramm), manuell (4.5 - 30.5), eco, comfort, boost, until
** (Besonderheit der Werte: 4.5 = Off und 30.5 = On)
* ecoTemperature, comfortTemperature, measurementOffset, maximumTemperature, minimumTemperature, windowOpenTemperature, windowOpenDuration

und das Auslesen

* der gemessenen Temperatur. (Hinweis: Wird bei Verwendung des MAX CUBE nicht regelmäßig aktualisiert)

=== Fensterkontakte ===
Der aktuelle Status (offen/geschlossen) wird (praktisch ohne Verzögerung) angezeigt. '''Nur bei CUL, oder?'''

Falls wir nicht mit Ack antworten, wird er mehrmals wiederholt.

Die Fensterkontakte können zusätzlich direkt an mehrere Heizkörperthermostate angelernt werden, und versetzen diese dann automatisch in windowOpenTemperature während sie geöffnet sind.

Wenn der Fensterkontakt an mindestens ein Heizkörperthermostat angelernt ist, dann sendet er zusätzlich stündlich seinen aktuellen Zustand.

'''Beispiel Autocreate'''
MAXLAN_Parse: Paired new device, type ShutterContact, addr 1a2b3c, serial JEQ0123456
autocreate: define MAX_1a2b3c MAX ShutterContact 1a2b3c
autocreate: define FileLog_MAX_1a2b3c FileLog /fhem/log/MAX_1a2b3c-%Y.log MAX_1a2b3c

'''Beispiel Definition'''
define MAX_1a2b3c MAX ShutterContact 1a2b3c

'''Beispiel Log'''
==> MAX_1a2b3c-2013.log <==
2013-10-20_18:52:08 MAX_1a2b3c battery: ok
2013-10-20_18:52:08 MAX_1a2b3c onoff: 0
2013-10-20_18:52:08 MAX_1a2b3c closed

=== Wandthermostate ===
Unterstützt wird das Einstellen von

* desiredTemperature (siehe Heizkörperthermostate), ecoTemperature, comfortTemperature

und das Auslesen

* der gemessenen Temperatur.

=== Eco-Taster ===
'''Achtung''': Zumindest über MAXLAN lässt sich der Zustand weder auslesen, noch wird man über Veränderungen informiert.

Per CUL_MAX funktioniert der Eco-Taster problemlos.

==== Beispielhafte Definition ====
:<code>define BUTTON.EG MAX PushButton 069d33</code>

==== Beispielhafte Event-Ausgabe ====

2013-07-02 21:06:14 MAX BUTTON.EG battery: ok
2013-07-02 21:06:14 MAX BUTTON.EG onoff: 0
2013-07-02 21:06:14 MAX BUTTON.EG closed

Wobei gilt
{| class="wikitable"
|-
! onoff !! Bedeutung
|-
| 0 || Eco
|-
| 1 || Auto
|}

== Anlernen per CUL ==
Das Anlernen funktioniert nur mit zurückgesetzen (Werksreset, also entweder alle 3 Tasten am Heizkörperthermostate betätigen, Batterien einlegen, Anzeige rES; oder in FHEM set factoryReset) Heizkörperthermostaten. Bereits an einen Cube angelernte Heizungsregler können '''nicht''' an ein CUL angemeldet werden, hier ist dann nur das "mitlesen" der Funkbotschaften möglich.

Info: Durch den Reset geht auch ein evtl. per Cube eingestelltes Automatikprogramm verloren.

== Konfiguration ==
Siehe [http://fhem.de/commandref.html#CUL_MAX commandref].

Die Module sind so konzipiert, dass man die offizielle Max! Software nicht benutzen muss. Man kann alles aus FHEM heraus machen. Nachdem das MAXLAN oder CUL_MAX Modul konfiguriert wurden (siehe unten), werden bereits gepairte Geräte automatisch erkannt.

=== MAXLAN ===
Minimale Konfiguration:
:<code>define ml MAXLAN 192.168.178.2</code>
wobei 192.168.178.2 die IP des MAX! Cube ist. Das MAXLAN-Modul findet selbstständig bereits gepairte Geräte und trägt diese in die Konfigurationsdatei fhem.cfg ein. Diese können dann im WEB-Interface mittels „alias“ einen eindeutigen Namen bekommen.

=== CUL_MAX ===
Minimale Konfiguration:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
attr CUL0 rfmode MAX
define cm CUL_MAX 123456</nowiki>

=== Anlernen ===
Dazu muss der "pairmode" auf MAXLAN/CUL_MAX per
:<code>set ml/cm pairmode</code>
oder über das Web-Interface aktiviert werden. Falls kein Parameter angegeben wird, ist er standardmäßig für 60 Sekunden aktiviert. In dieser Zeit können MAX! Geräte nach deren Anleitung in den Anlernmodus versetzt werden, um sie mit FHEM zu pairen.

=== Geräte untereinander anlernen ===
Es gibt einen anderen Befehl, um Devices untereinander anzulernen (in neueren Versionen des MAX Moduls enthalten, heißt "associate").

Wenn man z.B.
:<code>set MAXFensterKontakt0 associate MaxHeizkörperthermostat3</code>
ausführt, dann sendet der MAXFensterKontakt0 jede Änderung zusätzlich (direkt über Funk, ohne Cube oder FHEM) an das MaxHeizkörperthermostat3.

Damit MaxHeizkörperthermostat3 auch auf die Nachrichten vom MAXFensterKontakt0 hört, muss noch ein
set MaxHeizkörperthermostat3 associate MAXFensterKontakt0 erfolgen.

Dann wechselt MaxHeizkörperthermostat3 immer dann auf die windowOpenTemperature, wenn der AXFensterKontakt0 offen ist. Dabei muss die groupId von beiden Geräte gar nicht gleich sein! (Die Semantik der groupId erschließt sich mir deshalb noch nicht ganz. Ich glaube, man kann damit Befehle (ala set desiredTemperature) an mehrere Thermostate gleichzeitig richten. Im Moment sendet FHEM einfach an jedes Thermostat einen Befehl.)

Wahrscheinlich funktioniert associate genauso zwischen Heizkörper/Wandthermostaten. Das müsste mal jemand ausprobieren und dann hier berichten.

=== Temperatursturzerkennung ===
Die Heizkörperthermostate verfügen über eine interne "Fenster-offen Erkennung" (Temperatursturzerkennung). Wird diese ausgelöst, regeln sie für die Zeit die unter "windowOpenDuration" festgelegt wurde auf die als "windowOpenTemperature" festgelegt Temperatur herunter und danach wieder auf die zuvor eingestellte Temperatur zurück.

Nachteil: Die Erkennung benötigt etwas Zeit und reagiert nicht sofort wie es beim Fensterkontakt oben der Fall ist

Vorteil: Es ist kein Fensterkontakt erforderlich

'''Wichtig:''' Setzt man die windowOpenTemperature auf "Off" (= 4.5 Grad), dann ist die Fenster-offen-Funktion abgeschaltet. Und auch wenn die desiredTemperature gerade auf "On" (= 30.5 Grad") steht, geht der Heizkörper nicht in die Fenster-offen-Funktion.

=== Externer Sensor für Fenster-offen-Erkennung ===
Ziel dieses Abschnittes ist es, einen externen Sensor (z.B. 1-Wire o.ä.) zu benutzen, um die MAX Heizkörperthermostate in und aus dem Fenster-offen Modus zu holen. Dazu sei bereits ein CUL, ein CUL_MAX und ein MAX Heizkörper definiert:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>

Wir müssen einmalig den internen Fake-Fensterkontakt mit dem Heizkörper assozieren
:<code>set Heizung associate fakeShutterContact</code>
damit dieser die Nachrichten vom Fensterkontakt akzeptiert.

Nun können wir per
:<code>set cm fakeSC Heizung 1</code>
die Nachricht "Fenster offen" an die Heizung senden und per
:<code>set cm fakeSC Heizung 0</code>
die Nachricht "Fenster zu".

=== Externer Temperatursensor für Heizkörperregelung ===
Ziel dieses Abschnittes ist es, einen externen Sensor (z.B. 1-Wire o.ä.) zu benutzen, um die MAX Heizkörperthermostate zu regeln. Dazu sei bereits ein CUL, ein CUL_MAX und ein MAX Heizkörper definiert:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>

Wir müssen einmalig das interne Fake-Wandthermostat mit dem Heizkörper assozieren:
:<code>set Heizung associate fakeWallThermostat</code>
damit dieser die Nachrichten vom Wandthermostat akzeptiert. Achtung: Dies schaltet im
Heizkörperthermostat die Regelung mit dem internen Temperaturfühler aus. Ohne die gleich kommenden "fakeWT" Nachrichten wird das Heizkörperthermostat nicht mehr regeln.

Nun können wir per
:<code>set cm fakeWT Heizung 14.5 12.1</code>
die desiredTemperature 14.5 und gemessene Temperatur 12.1 an die Heizung senden. Diese wird dann die Ventile öffnen, bis wir ein "fakeWT" absetzten, dessen gemessene Temperatur höher als die desiredTemperature ist.

Falls man zu lange Zeit (ca. 30 Minuten) kein neues "fakeWT" sendet, wird bei der Heizung das Attribut rferror gleich 1. Es ist nicht klar, ob das neben diesem Attribut auch Auswirkung auf die Funktionalität hat. Es wurde beobachtet, dass dann der interne Temperatursensor bis zum nächsten FakeWT aktiviert wird.

Beispiel eines automatischen Sendens einer externen Temperatur, der externe Temperatursensor heißt "WS300":

<nowiki>define SendExtTemp notify WS300:temperature.* {
MaxFakeWallThermostat("Heizung", %EVTPART1);
}</nowiki>

Dazu die Funktion, bitte in 99_MyUtils.pm eintragen:

sub MaxFakeWallThermostat($$)
{
my ($heizung, $aktTemp) = @_;
my $CULMAX = $defs{$heizung}{LASTInputDev};
my $desiredTemp = ReadingsVal($heizung, "desiredTemperature", undef);
my $windowOpenTemp = ReadingsVal($heizung, "windowOpenTemperature", undef);
my $lastTemp = ReadingsVal($heizung, "LastExtTemperature", 0);
my $lastSet = ReadingsTimestamp($heizung, "LastExtTemperature", 0);
if($desiredTemp && $windowOpenTemp &&
$desiredTemp != $windowOpenTemp &&
(time()-time_str2num($lastSet) >= 600 || abs($aktTemp-$lastTemp)>=0.2 )) {
Log 3, "set $CULMAX fakeWT $heizung $desiredTemp $aktTemp";
readingsSingleUpdate($defs{$heizung}, "LastExtTemperature", $aktTemp, 0);
fhem("set $CULMAX fakeWT $heizung $desiredTemp $aktTemp");
}
}

In diesem Beispiel heißt das zu steuernde Thermostat "Heizung". Die vom externen Sensor gemessene Temperatur wird nur unter den folgenden Voraussetzungen gesendet:
* das Thermostat befindet sich nicht im "Fenster-offen" Modus, und
* das letzte Senden liegt mindestens 10min zurück
* oder die gemessene Temperatur weicht um mindestens 0.2°C von der letzten gesendeten Temperatur ab

=== Wochenheizplan für Wandthermostat/Ventilantriebe erstellen ===
Ein Heizplan, den das Wandthermostat und auch der Ventilantrieb versteht und speichern kann, sieht folgendermaßen aus:
:<code>set WZ_Wandthermostat weekProfile Mon 17,17:30,20,23:00,17 Tue 17,17:30,20,23:00,17 Wed 17,17:30,20,23:00,17 Thu 17,17:30,20,23:00,17 Fri 17,15:00,20,23:00,17 Sat 17,11:00,20,23:00,17 Sun 17,11:00,20,23:00,17</code>
Genauer erläutert wird die Funktionsweise auch in der [http://fhem.de/commandref.html#MAX commandref].

Der gesamte Block kann kopiert und als FHEM Befehl abgesetzt werden. Unter Umständen benötigt das Speichern bzw. Übertragen wegen der Größe etwas Zeit, bevor die aktuellen, neu gesetzten Werte wieder ausgelesen werden können.

'''Bitte folgendes beachten:'''

Es gibt im Zusammenhang mit dem Wochenprogramm ein Problem mit dem letzten Schaltpunkt des Tages.
Der Workaround wurde [http://forum.fhem.de/index.php/topic,17231.msg112738.html#msg112738 hier]
beschrieben.
Man muss dafür sorgen, dass man kurz vor Ende des Tages noch einen Schaltpunkt setzt! Bei mir hat sich ein Schaltpunkt (ohne Änderung der Soll-Temperatur) um 23:55 bewährt:
:<code>set WZ_Wandthermostat weekProfile Mon 17,17:30,20,22:00,17,23:55,17</code>

=== Werte Plotten ===
[[File:Plot_MAX_Beispiel.png|thumb|right|Plot eines MAX Heizkörperthermostates]]
In den Log-Dateien wird regelmäßig der Batteriestatus, die Soll-Temperatur, die Ventilstellung und die Ist-Temperatur (Vorsicht wird nicht zuverlässig, möglicherweise nur bei einer Änderung der Ventilstellung übertragen.)

Inhalt der LOG-Datei eines Heizkörperthermostates:

<nowiki>2012-12-30_08:55:31 MAX_018d3f battery: ok
2012-12-30_08:55:31 MAX_018d3f desiredTemperature: 19.5
2012-12-30_08:55:31 MAX_018d3f valveposition: 83
2012-12-30_08:55:31 MAX_018d3f temperature: 16.4</nowiki>

Mit folgender Plot-Datei (max_temp.gplot) kann der Verlauf der Sensordaten gut angezeigt werden.

<nowiki>set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set y2tics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur in Grad Celsius"
set ylabel "Signal in %"
#FileLog 4:desiredTemperature:0:
#FileLog 4:temperature:0:
#FileLog 4:valveposition:0:
plot \
"< egrep 'desiredTemperature' <IN>"\
using 1:4 axes x1y2 title 'Soll-Temperatur (C)' with lines lw 2 \
"< egrep 'temperature' <IN>"\
using 1:4 axes x1y2 title 'Ist-Temperatur(ungenau)(C)' with lines lw 2 \
"< egrep 'valveposition' <IN>"\
using 1:4 axes x1y1 title 'Ventil (%)' with lines lw 2</nowiki>
Einbinden eines Plots in der fhem.cgf

<nowiki>#Werte plotten
define MAX_017840_weblink weblink fileplot FileLog_MAX_017840:max_temp:CURRENT
attr MAX_017840_weblink label "Kueche Soll-Temperatur Min $data{min1}, Max $data{max1}, Last $data{currval1}"
attr MAX_017840_weblink room MAX</nowiki>
=== Nützliche kleine Erweiterungen ===
'''Einen Alias-Namen vergeben für eine bessere Lesbarkeit im Webinterface'''
:<code>attr MAX_018d3f alias Kueche</code>
'''Die Anzeigen für die einzelnen File-Logs füllen das Webinterface schnell und machen es unübersichtlich.''' Die File-Logs können einfach in einen separaten Raum verbannt werden.
:<code>attr FileLog_MAX_018d3f room LOG</code>
'''Einstellmöglichkeit für die Soll-Temperatur direkt in der „Raum-Seite“ schaffen.''' Die Temperatur wird dauerhaft auf einen bestimmten Wert gestellt. Das Wochenprogramm in dem Thermostat wird deaktiviert.
:<code>attr MAX_018d3f webCmd desiredTemperature</code>

'''Soll-Temperatur setzen, ohne das automatische Programm des Thermostates abzuschalten.'''
Es besteht die Möglichkeit eine Soll-Temperatur bis zum nächsten Schaltzeitpunkt zu setzen. Zum Beispiel kann das automatische Wochenprogramm in den Thermostaten dazu genutzt werden, nur abends die Soll-Temperatur zu senken. So läuft die Heizung nachts nicht voll durch. Wenn jedoch die Temperatur im Web-Interface von Fhem verändert wird, wird auch der Thermostat auf manuell gesetzt. So greift das Wochenprogramm nicht mehr. Abhilfe schafft der Befehl
:<code>set MAX_04711 desiredTemperature auto 20</code>
Damit die Eingabe komfortabel aus Fhem möglich ist, kann ein Dummy-Device erstellt werden:

<nowiki>#Dummy für die Schnell-Einstellung der Temperatur bis zum nächsten automatischen Schaltzeitpunkt
define HeizkoerperBad dummy
attr HeizkoerperBad room MAX,Heizungen
attr HeizkoerperBad setList state:eco,auto,14.0,16.0,17.0,18.0,19.0,20.0,21.0,22.0,23.0
attr HeizkoerperBad webCmd state
define HeizkoerperBad.ntfy notify HeizkoerperBad.* {\
my $valtemp = "%";;\
my $device = "MAX_04711";;\
my $cmd = 'set '.$device.' desiredTemperature auto '.$valtemp;;\
fhem($cmd);;\
}</nowiki>
Diese Dummy-Device kann alternativ oder ergänzend zu <code>attr MAX_018d3f webCmd desiredTemperature</code> verwendet werden.

== Internals ==
=== IST-Temperaturwerte ===
[[File:Plot_MAX_Beispiel.png|thumb|right|Plot eines MAX Heizkörperthermostates]]
Diese Abbildung zeigt, dass die IST-Temperatur nicht regelmäßig dem MAX CUBE mitgeteilt wird. Im Automatikbetrieb wird beim einer Änderung der Ventilstellung die neue Ventilstellung zusammen mit der aktuellen IST-Temperatur gesendet. Bei der Abbildung war die Therme in der Nacht ausgeschaltet. Daraufhin sinkte die Temperatur soweit ab, dass das Heizungsthermostat das Ventil in Maximalstellung geöffnet hat. Gegen 08:50 wurde die Therme eingeschaltet und die Soll-Temperatur an diesem Heizungsthermostat erhöht. Während dieser ganzen Zeit erfolgt keine Aktualisierung der Ist-Temperatur. So kommt es auch gegen 10:30 zu einem sprunghaften Temperaturanstieg von 13,5°C auf 19°C (siehe Markierung *A).

Die IST-Temperatur wird anscheinend aktualisiert bei einer Änderung der:

* Ventilstellung
* Soll-Temperatur
* des Betriebsmodis (Auto/Manuell)

Wer eine detaillierte Kurven wünscht, sollte sich den [[MAX! Temperatur-Scanner]] ansehen.

=== MAXLAN ===
=== CUL_MAX ===
The Max devices use a CC1100 chip. For parameters see rf_moritz.c in culfw.
The thermostats use a Wake-On-Radio, thus one has to send packets at the right time.

CC1100 initialization sequence on one of the max devices (not Cube) (format: addr value, both in hex):

<nowiki>00 08
02 46
04 C6
05 26
0B 06
10 C8 //MDMCFG4 DRATE_E=8
11 93 //MDMCFG3 DRATE_M=147, data rate = (256+DRATE_M)*2^DRATE_E/2^28*f_xosc = (9992.599) 1kbit/s (at f_xosc=26 Mhz)
12 03
15 34
17 00
18 18
19 16
1B 43
21 56
25 00
26 11
0D 21
0E 65
0F 6A
07 4C //PKTCTRL1: ADR_CHK=0 APPEND_STATUS=1 CRC_AUTOFLUSH=1 PQT=2 (preamble must have 8 toggling bits before sync word detection)
16 1C //RXTIME=4
RX_TIME_QUAL=1 (when rx timeout expires, keep receiving if either sync word is found or PQI is set (see PQT))
RX_TIME_RSSI=1 (terminate RX if there is no carrier sense within the first 8 symbol periods)
20 78 //WORCTRL, WOR_RES=00 (1.8-1.9 sec), RC_CAL=1, EVENT1=7 (48 ticks), RC_PD=0
1E 87 //WOREVT1
1F 6B //WOREVT0, i.e. EVENT0 = 34667
29 59
2C 81
2D 35
3E C3</nowiki>
<nowiki>Not set, i.e. factory defaults:
13 MDMCFG1 NUM_PREAMBLE=2 (4 preamble bytes)</nowiki>
From the configuration, we see that the

<nowiki>RC Oscillator: f_xosc/750 = 34666.66 Hz
Event1 = Event1(=48 ticks)/RC Oscillator = 1.385 ms
t_Event0 = 750/26Mhz * EVENT0 * 2^(5*WOR_RES) = 1.00 second
C(RX_TIME, WOR_RES)= 0.2254
rx timeout = EVENT0·C(RX_TIME, WOR_RES) ·26/X(=26) = 34667*0.2254 us = 7.8139 ms</nowiki>

The ShutterContact seems to always sleep. Thus it is necessary to trigger it manually (by opening/closing the window) to make it receive messages. Pushing the button may work to. It is also awake just after
pairing, so one may send messages right then. One can use the WakeUp message to keep it from sleeping for some time. (This is also the reason why in the official MAX software, one must trigger the ShutterContact
after removing it from the house. The "factoryReset" packet is sent directly after the "ShutterContactState" packet has been acked.)

== Probleme und Lösungen ==
=== Der Wandthermostat oder Heizthermostat reagieren nicht auf Änderungen über FHEM ===
Das Autocreate von FHEM erkennt, wenn aktiviert, die Geräte initial und legt auch Einträge an. Es fehlt aber noch das Pairing, da sonst keine Steuerung möglich ist!
Wenn im Log also Meldungen wie

<nowiki>2013.03.20 15:12:30 5: CUL_MAX_SendQueueHandler: 1 items in queue
2013.03.20 15:12:30 5: CUL_MAX_SendQueueHandler: 1 items in queue
2013.03.20 15:12:30 2: CUL_MAX_SendQueueHandler: Missing ack from 01c9bb for 0b05008212345601c9bb0000</nowiki>
auftauchen (im Verbose Modus 5), dann wurde vermutlich kein oder ein inkorrektes Paring durchgeführt.
Nach dem Pairing sollten diese Meldungen verschwinden und stattdessen etwas wie
:<code>2013.03.20 15:21:43 5: Got matching ack</code>
auftauchen.

[[Kategorie:Kontaktsensor (magnetisch)]]
[[Kategorie:MAX]]
[[Kategorie:Heizungsventile]]