FHEMWiki - Benutzerbeiträge [de]

Diskussion:FHEM on OS X Lion with CUL v1

2015-03-06T08:11:17Z

Kamischi: Installation nach /usr/sbin?

Ist es nicht besser, statt nach /usr/sbin zu kopieren, /usr/local/sbin zu nehmen oder gibt das Probleme.

HM-CFG-USB USB Konfigurations-Adapter

2015-03-06T08:09:52Z

Kamischi: /* Einrichtung unter Mac OS X */

{{Infobox Hardware
|Bild=platzHalter.png
|Bildbeschreibung=todo
|HWProtocol=HomeMatic
|HWType=Interface/Gateway
|HWCategory=HomeMatic
|HWComm=868,3MHz
|HWChannels=
|HWVoltage=
|HWPowerConsumption=
|HWPoweredBy=USB-Bus
|HWSize=
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]

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

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

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

Die nachfolgenden Angaben in diesem Abschnitt sind rein zu Informationszwecken (noch) enthalten:

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

(Unter Debian ist "build-essentials" nicht als Paket vorhanden, dieser Schritt kann entfallen.)

Danach kann der Dienst zu Testzwecken gestartet werden (in /opt/hmcfgusb):
:<code>./hmland -p 1234 -D</code>

==== Start als Daemon ====
Um den hmland als Daemon mit dem Betriebsystem automatisiert zu starten, kann ein init-script genutzt werden. In diesem {{Link2Forum|Topic=13071|Message=190887}} ist ein Skript zur automatischen Einrichtung von hmland als Daemon über init mit Installationsanweisung enthalten. Dieses Skript enthält zudem auch die Befehle zum Download, Kompilierung und Installation von hmland, so dass fast keine manuellen Eingriffe notwendig sind.

Alternativ ist auch der (umständlichere) manuelle Weg möglich:
<pre>
#!/bin/sh
### BEGIN INIT INFO
# Provides: hmland
# Required-Start: $localfs $syslog $remote_fs
# Required-Stop:
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: hmland daemon
# Description: hmland daemon, Homematic USB Adapter on port 1234
### END INIT INFO

# simple init for hmland

pidfile=/var/run/hmland.pid
port=1234

case "$1" in
start|"")
chrt 50 /opt/hmcfgusb/hmland -d -P -l 127.0.0.1 -p $port 2>&1 | perl -ne '$|=1; print localtime . ": [hmland] $_"' >> /var/log/hmland.log &
;;
restart|reload|force-reload)
echo "Error: argument '$1' not supported" >&2
exit 3
;;
stop)
killall hmland
;;
status)
if [ ! -e $pidfile ]; then
echo "No pid"
exit 1
fi
pid=`cat $pidfile`
if kill -0 $pid &>1 > /dev/null; then
echo "Running"
exit 0
else
rm $pidfile
echo "Not running"
exit 1
fi

;;
*)
echo "Usage: hmland [start|stop|status]" >&2
exit 3
;;
esac
</pre>

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgendes Konfigurationsfile verwendet werden:
<pre>
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

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

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

==== Start über Fhem Startskript ====

Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

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

Dann geht es weiter:

sudo cp hmcfgusb.rules /etc/udev/rules.d/

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

Damit editiert man das Fhem Startskript:
sudo nano /etc/init.d/fhem

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)

'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

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

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

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

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

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

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

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

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:

Datum Zeit: Client 127.0.0.1 connected! 
Can't claim interface: Access denied (insufficient permissions) 
Can't find/open hmcfgusb! 
Datum Zeit: Connection to 127.0.0.1 closed! 

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

idProduct: 49167 
idVendor: 6943

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:

chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext

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

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

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

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

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

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

=== Windows ===
Die erweiterte Energieverwaltung unter Windows 8.1 kann dazu führen, dass der Adapter unerwünschterweise in den Stand-by Modus versetzt wird (siehe [[HM-CFG-USB USB Konfigurations-Adapter#Einrichtung unter Windows|Einrichtung unter Windows]]).

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
* HM-CFG-USB-2: die aktuelle Version; Dokumentation derzeit (12/2013) nicht über die ELV-Artikelseite verfügbar, alternativ jedoch bei [http://files.voelkner.de/625000-649999/640558-an-01-ml-USB_FUNK_KONFIGURATIONSADAPTER_de_en.pdf Völkner]; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

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

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

Benutzer:Kamischi

2015-03-06T08:07:06Z

Kamischi: Die Seite wurde neu angelegt: „Ich interessiere mich für FHEM auf dem Mac.“

Ich interessiere mich für FHEM auf dem Mac.

LinuxDeviceNaming

2014-08-14T13:59:14Z

Kamischi:

USB-Geräte erhalten unter Linux standardmäßig generische Namen. CUL erscheint beispielsweise unter

<nowiki>/dev/ttyACM0</nowiki>
beim ersten Anstecken. Bei mehrmaligen Anstecken wird die Gerätenummer hochgezählt. Damit Geräte immer denselben Namen erhalten, kann man dem udev-Dateisystem dafür Regeln mitgeben.

Unter openSUSE 11.x kann man dazu unter

<nowiki>/etc/udev/rules.d</nowiki>
eine Datei

<nowiki>69-my.rules</nowiki>
anlegen mit folgendem Inhalt:

<nowiki>KERNEL=="ttyUSB*", ATTRS{product}=="ELV EM 1010 PC", SYMLINK+="elv_em1010pc"
KERNEL=="ttyUSB*", ATTRS{product}=="ELV FHZ 1300 PC", SYMLINK+="elv_fhz1300pc"
KERNEL=="tty*", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="204b", MODE="0666", BUS=="usb", SYMLINK+="CUL"</nowiki>
Dadurch werden symbolische Links

<nowiki>/dev/elv_em1010pc
/dev/elv_fhz1300pc
/dev/CUL</nowiki>
angelegt und die Berechtigungen angemessen gesetzt.

[[Kategorie:HOWTOS]]

Kommunikationsprobleme mit FHT

2014-08-13T12:03:14Z

Kamischi: /* Problemquellen */

Während FHEM mit reinen Schaltaktoren in der Regel problemarm funktioniert, sind Probleme mit [[FHT80b]] Heizungsteuerungen recht häufig. Dies liegt in der deutlich anspruchsvolleren bidirektionalen Kommunikation, die zur Übermittlung der ggf. durchaus umfangreichen Daten notwendig ist.

== Symptome ==
Im Einsatz von FHTs kann es zu folgenden Symptomen kommen:

* FHT funktioniert zunächst einwandfrei, dann plötzlich sind keine Temperaturänderungen o.ä. mehr möglich
* FHTs funktionieren einwandfrei, jedoch seitdem ein weiteres dazu gekommen ist, wird die Datenübertragung langsam oder fällt ganz aus, auch zu FHTs, die vorher ohne Probleme liefen.
* FHT funktioniert manchmal für Stunden gut, übermittelt aktuelle Werte und lässt sich ansprechen, dann für mehrere Stunden wieder nicht, schliesslich "erholt" sich das FHT wieder (oft über Nacht)
* Temperaturänderungen werden von FHT mit hoher Verzögerung (bis hin zu Stunden) ausgeführt
* FHTs laufen ca. eine Woche problemfrei, dann kommen keinen Daten mehr. Nach einem neuen Pairing ist alles wieder in Ordnung, bis nach ca. einer Woche wieder keine Daten kommen.

== Problemquellen ==
Die FHT-Kommunikation ist recht fragil. Für eine erfolgreiche Kommunikation müssen eine Menge Funktelegramme in einem bestimmten Timing ausgetauscht werden. Selbst wenn keine Kommandos an das [[FHT80b]] übergeben werden, finden alle 15 Minuten Datenübermittlungen statt, da das FHT Temperatur und andere Daten meldet.

Bereits ein fehlendes Datenpaket kann dazu führen, dass die Kommunikation erfolglos war und insgesamt alles wiederholt werden muss.

Störungen des Kanals (z.B. der berühmte Funkkopfhörer aus China) führen daher so gut wie immer zu Problemen in der FHT-Kommunikation. Es reicht, wenn von den 5+n Kommandos (n=Anzahl der übermittelten Werteänderungen) die mindestens hin und her gehen müssen, eines nicht korrekt ankommt und schon muss alles wiederholt werden.

Diese Wiederholung kann aber nur ca. alle 2 Minuten erfolgen. Kommandos, die noch nicht erfolgreich abgearbeitet wurden, verbleiben im FHT Befehlsbuffer des CUL/CUNO (oder sonstiger Funkschnittstellen), obwohl sie seitens FHEM als "abgesetzt" geloggt werden. Dieser FHT Buffer kann mitunter sehr viele Kommandos aufnehmen, die der Reihe nach abgearbeitet werden. Kann z.B. eine Temperaturänderung aufgrund von Funkproblemen erst nach ca. 3 Versuchen erfolgreich zugestellt werden, so dauert es in der Regel etwa 3 x 2 = 6 Minuten, bis die Änderung im FHT sichtbar ankommt. Wird z.B. aus Ungeduld eine erneute Temperaturänderung ausgelöst, so wird diese im FHT Buffer gespeichert und dann nach erfolgter Übertragung des ersten Kommandos übermittelt. Die Abarbeitungszeit der Warteschlange für dieses FHT steigt dann bereits auf ca. 12 Minuten. Es ist leicht möglich, durch Abfrage der Wochenprogramme, Änderung der Day- oder Nighttemperatur, oder Änderung von Wochenschaltpunkten Warteschlangen aufzubauen, die buchstäblich Stunden oder gar Tage zum Abarbeiten benötigen. Temperaturänderungen könnten also mitunter erst Stunden später tatsächlich ausgeführt werden. Jeder Aussendungsversuch führt außerdem zur Belastung des Sendekontos. Ist die [[1% Regel]] überschritten, wird die Warteschlange nicht mehr weiter abgearbeitet.

Solche Störungen des Funkkanals sind nicht selten und können auch ohne äußere Einflüsse stattfinden.
Die FHTs sind mit relativ ungenauen Sendern ausgestattet und können in Sendefrequenz und Flankensteilheit mitunter deutlich von den Sollwerten abweichen, was insbesondere beim Einsatz von CUL / CUNO (weniger beim Einsatz einer FHZ1x00PC) ein Problem sein kann, weil die CUL / CUNO eher trennscharf sind. Dies kann dazu führen, dass die Funkkommunikation oft fehlerhaft ist oder sogar ganz abbricht.

Zusätzlich stellen einige FHTs das Aussenden von Temperatur und weiteren Daten nach 5-10 Tagen ein, wenn nicht zwischendurch von der Zentrale Änderungen übermittelt wurden.

Alle vorstehenden Gründe kombinieren sich für gewöhnlich zu einem komplexen Versagensszenario, das sich gegenseitig selbst verstärkt:

* Schlechte Funklage eines FHT80b erzeugt häufige Retrys.
* Inzwischen stauen sich weitere Kommandos an das FHT auf, z.B. wegen erneuter Temperaturänderungen, automatisiert oder aus Ungeduld, sowie andere Meldungen, etwa Abfrage oder Ändern des Wochenprogramms.
* Die Kommandos sammeln sich im FHT Buffer des Funkadapters an und sorgen dafür, dass die Sendezeit hoch belastet wird.
* Fast Glück hat man noch, wenn der Buffer voll läuft und [[EOB]] Meldungen im Log darauf hinweisen. Es kann aber auch passieren, dass über grössere Zeiträume der Buffer gerade eben nicht voll wird, insbesondere bei CUL / CUN, die im Vergleich zur FHZ1x00PC große Buffer haben, die 30 und mehr Kommandos halten können. Ist zusätzlich das Feature "Softbuffer" eingeschaltet, verschlimmert sich die Situation weiter, da die Warteschlange noch länger werden kann.
* Ist die 1% Marke erreicht, das Funkkontingent also aufgebraucht, verschlimmert sich die Situation dramatisch: Nun bricht auch die Kommunikation mit anderen FHTs zusammen. Da außerdem immer Kommandos im FHT Buffer sind, wird jede freie Sendezeit durch Versuche, die Warteschlange abzuarbeiten, sofort wieder aufgebraucht. Das Timing des Gesamtsystems ist hier leider so, dass sich innerhalb des Retryintervals von ca. 2 Minuten oft gerade zu wenig freie Sendezeiteinheiten aufbauen, um den nächsten Retry komplett abwickeln zu können. D.h. jedes Retry braucht die gerade aufgebauten freien Sendeeinheiten auf, ist aber in sich erfolglos.
* Spätestens ab hier ist vollständiger Stillstand erreicht. Im Log häufen sich die [[LOVF]]- Meldungen, jede Kommunikation mit allen FHTs ist zusammengebrochen. Es kommt eventuell sogar zu Beeinträchtigungen beim Schalten von FS20 Aktoren.

Mit der Anzahl FHTs steigt die Wahrscheinlichkeit für das Auftreten dieser Probleme.

Viele FHEM Nutzer verwenden die Kombination von FHEM und FHT so, dass die FHTs über Manipulation der im FHT gespeicherten Wochenprogramme, Schaltpunkte und Day/Nighttemp gesteuert werden. Dies erhöht die Datenmenge im Vergleich zu einer direkten Temperatursteuerung ("set desired-temp 22") und wird in kritischen Situationen die Fehlerhäufigkeit deutlich anheben. Sehr viel Datenverkehr erzeugt auch die komplette Abfrage des Wochenprogramms mittels Report1=255.

== Diagnose und Lösungsansätze ==
Im Folgenden einige Hinweise wie man das Auftreten von Problemen verringern bzw. diagnostizieren kann.

=== Sparsam mit Funkzeit umgehen ===
Da die Ausnutzung der freien Funkzeit jede Situation schnell deutlich verschlimmert, sollte man immer bemüht sein, seine Ziele mit wenig Datenverkehr zu erreichen. Dies gilt insbesondere, wenn man sich der Anzahl [[Maximal nutzbare Geräte]] nähert.

* [http://www.fhemwiki.de/wiki/Heizung_mit_Bewegungsmelder_steuern#FHT80b FHT Lazy Mode] nutzen (Temperaturänderungen werden nur übertragen, wenn sie von der momentan eingestellten Temperatur abweichen.) Dies ist besonders hilfreich, wenn die Temperatursteuerung automatisiert durch Bewegungsmelder oder "Zuhausestatus"-Automatismen gesteuert wird, da hier in relativ kurzer Folge die selbe Temperatureinstellung übermittelt wird. Lazy Mode schützt aber nicht immer davor, dass die Warteschlange schnell anschwillt. Steht ein FHT80b z.b. auf 18 Grad, und soll auf 20 Grad angehoben werden, so wird das Kommando trotz Lazy Mode immer wieder in die Warteschlange eingetragen, solange das erste Kommando nicht erfolgreich abgesetzt und die neue Temperatur vom FHT rückgemeldet wurde. Das kann dazu führen, dass die FHT-Warteschlange dutzende Male das selbe "desired-temp" Kommando enthält.
* Temperatursteuerung der FHTs nicht auf täglicher Basis durch Setzen der Wochenprograme im FHT durchführen. Obwohl diese Methode den Vorteil hat, dass sie eine höhere Ausfallsicherheit bietet (weil die FHTs auch ohne FHEM ihr zuletzt eingegebenes Wochenprogamm weiter verwenden können), so steigt der auszutauschende Datenverkehr stark an.

:Mitunter verwendete Implementationen, die Anhand von Tabellen, Kalendern oder der Auswertung von Excelsheets mehrere FHTs regelmässig mit geänderten Wochenprogrammen und/oder Änderungen der Day/Night Temperaturen steuern, sind in schwierigen Funksituation deutlich anfälliger.

* Keine regelmässigen Reports abfragen, insbesondere NICHT report1=255 (also komplettes Wochenprogramm abfragen)
:Da einige FHTs nach einiger Zeit keine Temperaturdaten mehr senden, fragen viele Nutzer diese über tägliches Absetzen von report2=255 ab. Besser ist es jedoch, das FHT mit einem Wachdog zu überwachen und nur bei Bedarf zu "wecken", z.B. so:

<nowiki>define wd_FHT_Wohnzimmer watchdog hzg_wohnzimmer:measured-temp.* 01:00 SAME set hzg_wohnzimmer time</nowiki>
:Alternativ report2=255 1-2x pro Woche nachts absetzen, bei mehreren FHTs eventuell tageweise versetzt:

<nowiki>define fht_reportZimmer1 at *04:00:00 {if ($wday == 1) { fhem("set hzg_Zimmer1 report2 255")</nowiki>

=== Funklage beobachten ===
* RSSI mitloggen:
<nowiki>attr CUL addvaltrigger 1</nowiki>
* RSSI der FHTs beobachten. Unter -85 (also z.b. -89) ist ungünstig. Unbedingt versuchen, ein besseres RSSI als -85 hinzubekommen, zu ALLEN FHTs.
* Antennnenlage des CUL/CUN korrigieren (z.b. Antenne um 45 Grad kippen), eventuell Lage des FHTs ändern, ein halber Meter kann schon viel bringen. Dabei kommt es nicht zwingend nur auf die absolute Entfernung zum Funkadapter an, auch die Lage im Gebäude kann viel ausmachen.
* Wenn CUL / CUN eingesetzt werden, gegebenenfalls die Parameter freq, bandwidth und sens ändern. Als Startpunkt z.B. bandwidth auf 464 khz und sens auf 8 db anstelle 4db ändern. Kombinationen ausprobieren, aber nicht mehrere Parameter gleichzeitig ändern. RSSI-Auswirkung jeder Änderung beobachten.

Wenn das keinen Erfolg bringt, zweiten CUL / CUNO einsetzen, z.b. auch als RFR CUL. Dabei [[RFR CUL und FHT80]] Besonderheiten berücksichtigen: Nicht zu viele FHTs ans RFR CUL anbinden, nur so viele wie gerade nötig. FS20 Repeater helfen nicht.

=== Einstellungen prüfen ===

* Attribut fhtsoftbuffer ausschalten. Beim Einsatz von CUL/CUNO ist die Verwendung von fhtsoftbuffer sowieso überflüssig, da die eigenen FHT Buffer dieser Adapter hinreichend groß sind. Gedacht ist dieses Attribut vor allem für den Einsatz von FHEM mit FHZ1x00PC Zentralen, deren FHT Buffer klein ist und zum Teil nur 8 Befehle halten kann. Das CUL V3 kann demgegenüber 40 FHT Befehle im Buffer halten. D.h. bei einer FHZ1x00PC kann es vorkommen, dass bei 10 zu steuernden FHTs schon ein Kommando der Art "Alle FHTs auf 20 Grad" *nicht* bei allen FHTs ankommt, da nicht alle Befehle zugleich in den Buffer passen. In solchen Fällen ist der Einsatz des Softbuffers hilfreich. (in neueren FHEM Versionen hat das Attribut fhtsoftbuffer daher auf CUL und CUNOs keine Wirkung mehr)

<ul>Das Attribut fhtsoftbuffer erzeugt einen "unendlich" grossen Buffer, was sehr lange Warteschlangen zur Folge haben kann. Das macht die Diagnose sehr schwer und erzeugt seltsamste Effekte, wenn die Kommunikation mit den FHTs nicht einwandfrei ist. In jedem Fall aber "glaubt" FHEM sehr viel länger, dass alles in Ordnung sei, obwohl die Kommunikation gestört ist.

Ganz generell: Wenn eine Installation ohne fhtsoftbuffer nicht zuverlässig läuft, sollte man der Versuchung widerstehen, das Problem durch einen grösseren Buffer lösen zu wollen. Fhtsoftbuffer sollte nur eingesetzt werden, wenn eine FHZ1x00 verwendet wird, die Installation an sich gut läuft und nur gelegentlich EOB Meldungen kommen.
</ul>

* Retrycount auf 1. Wenn fhtsoftbuffer aktiv ist, wird versucht, das Kommando Retrycount-Mal zu wiederholen, wenn es nicht innerhalb von 240 Sekunden abgesetzt werden kann. Das kann die Abarbeitungsgeschwindigkeit der Warteschlange zusätzlich senken, gleichzeitig den Funkzeitverbrauch erhöhen und dadurch Probleme eher noch verschärfen. Sinnvoll ist ein höherer Retrycount womöglich nur, wenn in kleineren Installationen ein FHT gerade am Rande des Funkbereiches liegt, ansonsten aber alles problemfrei abläuft. Ohne fhtsoftbuffer hat retrycount keine Wirkung, wenn retrycount nicht definiert wird, ist der Defaultwert 1.

* Bei mehreren CUxx in der Installation (auch 1 x CUL und 1x RFR CUL) das Attribut IODev kontrollieren. Ist ein FHT mit einem CUxx gepairt, aber das IODev zeigt auf das andere, ist eine Kommunikation nicht möglich. Da aber Temperatur (und weitere Werte) trotzdem empfangen werden, fällt dies zunächst eventuell nicht sofort auf. Der FHTbuffer des "falschen" CUxx wird dann mit Befehlen an das FHT zugemüllt, die nie erfolgreich abgesetzt werden können. Ist der Buffer schliesslich voll, können auch keine Kommandos an andere mit diesem CUxx gepairte FHTs mehr übermittelt werden, obwohl diese eigentlich nicht betroffen sind.
* Bei mehreren CUxx UNBEDINGT sicherstellen, dass die FHT-ID unterschiedlich ist. Bei gleicher FHT-ID fühlen sich zwei "Zentralen" für die FHT Kommunikation verantwortlich, was immer im Chaos endet: beide Funkadapter antworten bei FHT Kommunikationen und stören sich so gegenseitig. Siehe auch [[Was ist der Hauscode?]].
* Bei mehreren CUxx bitte auch die Erläuterungen zum [[Sendpool]] Attribut berücksichtigen, die Funktion von Sendpool wird oft missverstanden.

=== Diagnosemöglichkeiten im Fehlerfall ===
Eine Möglichkeit, sich dem Problem zu nähern ist, das Logfile mit verbose5 anzeigen zu lassen. Die Meldungen sind dann recht detailliert und lassen einige Rückschlüsse zu. Erfahrungsgemäß ist es jedoch besser, sich die Kommunikation mit einer Telnetsitzung anzusehen. Ein Nachteil des Logfiles liegt z.B. darin, dass eine Temperaturänderung als "ausgeführt" angezeigt wird, wenn sie erfolgreich an z.b. das CUL übermittelt wurde, auch wenn sie dort nur in einen schon übervollen Buffer geschrieben wird. In einer Telnetsitzung kann man hingegen den Zustand des Buffers prüfen und die Kommunikation mit dem FHT beobachten.

Dazu:

* Terminalprogramm starten
* Dann mittels <code>telnet (IP des FHEM Servers) 7072 <entertaste></code> eine Telnetverbindung zu FHEM starten (7072 ist FHEMs Telnetport)
* erneut <entertaste> drücken, nun muss als Prompt "fhem>" erscheinen.

Jetzt können zahlreiche Kommandos zur Diagnose abgegeben werden.

* info timer <entertaste> zeigt einem alle Events, die FHEM empfängt und sendet. Hier kann man die Kommunikation live verfolgen und so z.B. sehen, ob noch Kommunikation mit dem FHT versucht wird. Einfach eine Weile mitlaufen lassen und sich ansehen, was alles passiert.
* Wenn man einen CUxx im Einsatz hat, dann kann man sich mittels "set CUL raw X61" ("CUL" durch Namen der eigenen Schnittstelle wie in fhemconfig definiert ersetzen) auch Details der Kommunikation anzeigen lassen. So kann man vergleichen, ob die Kommunikation mit dem Beispiel [[FHT80b#Log-Auszug]] übereinstimmt, also planmäßig abläuft. "set CUL raw X21" setzt das CUL wieder auf den Standard-Loglevel zurück. Achtung, Groß- und Kleinschreibung beachten: Das X61/X21 hat ein großes X.
* Auch sollte man prüfen, ob der der CUxx so konfiguriert ist, wie man glaubt. Mit "get CUL ccconf" kann man die wichtigsten Werte ansehen.
* Ist der FHT Buffer leer oder was hat sich da ggf. aufgestaut? "'''get CUL raw T02'''" ergibt den Inhalt des Buffers. Da sollte möglichst nichts drin stehen ("CUL raw => N/A") oder nicht viel. Mit der Zeit erkennt man die Codes gleich, daraus ergibt sich, welches FHT Probleme macht (Adresse) und welche Kommandos noch auf Aussendung warten. Folgender Beispieloutput: "CUL raw => 060D:4118 060D:65FF 060D:66FF 060D:4120" ist bereits verdächtig. FHT 060D hat noch 4 Kommandos in der Warteschlange, die Abarbeitung hier dauert schon im besten Fall mindesten noch 8 Minuten. Sieht bereits nach "Rückstau" aus. (4118 = desired temp auf Wert 18, 65ff= report1=255 66ff= report2=255).
* Mehrfaches Eingeben von "get CUL raw T02" im Abstand von ca 2 Minuten (dem Intervall, in dem Kommunikation mit dem FHTs stattfinden kann) zeigt einem, ob die Schlange sich abarbeitet oder welche Kommandos klemmen.
* Wenn man CUxx im Einsatz hat kann man auch die freie Sendezeit prüfen: "get CUL raw X" Der zweite Zahlenwert ist die Sendezeit in 10ms Slots. Während ein FS20 Schalter im Idealfall mit 21 Einheiten (=210 ms) erledigt werden kann, braucht schon die simpelste Übertragung nur eines Wertes an ein FHT ca. 3x mehr Zeiteinheiten. Wenn also nicht mindestens 65 Zeiteinheiten frei sind, kann keine FHT Übertragung erfolgreich sein.
* CUxx Funkadapter können auch resettet werden: "set CUL raw B00" resettet das CUL, und löscht dabei alle Buffer und setzt die freie Funkzeit auf Maximum. Die Wirkung ist die selbe wie den Adapter kurz stromlos zu machen. Will man hingegen nur den FHT Buffer leeren, kann man auch "'''set CUL raw T01xxxx'''" eingeben, wobei xxxx = FHT-ID istdie aus fhem.cfg aus der CUL-Definition gelesen werden kann. Diese muss natürlich mit der vorherigen übereinstimmen, da sonst alle FHT-Pairings ungültig sind. Nach dem Löschen des Buffers noch kurz mit "get CUL raw T02" überprüfen, dass der buffer auch wirklich leer ist. Anschliessend irgendeinen Befehl an den FHT senden, z.B. Ändern der desired-temp um 1 Grad. Danach fängt der FHT meist wieder an zu senden. Manchmal muss man ihm auch einfach ein bischen Zeit geben, bis er sich wieder fängt.

=== Repairen ===
Lassen sich durch die obigen Massnahmen keine nahliegenden Problem entdecken, hilft gelegentlich auch ein
simples neu Pairen eines nicht komunizierenden FHTs.

Wiederkehrende Actuator-Meldung "'''unknown_69'''" lassen sich z.b. meist mit einem neuen Pairing lösen.

====Neues Pairen ohne Autocreate====
*fhem.cfg unbearbeitet lassen
*FHT80b in Sonderfunktionen "cENT" auf "n/a" stellen, danach sofort in FHEM einen Befehl (egal welchen) an die FHT80b senden.
*Wenn ca. zwei Minuten später Sonderfunktion cENT auf "ON" steht, war das Pairing erfolgreich.

====Neues Pairing mit Autocreate====
Alternativ hat auch dieser Weg zum Erfolg geführt:
*In der fhem.cfg den define-Eintrag für diesen FHT auskommentieren, autocreate ggf. einschalten, sichern.
*Am FHT80b in Sonderfunktionen "cENT" auf "n/a" stellen, sodass eine neue Paarung eingeleitet wird
*Warten bis FHEM nach Empfang eines Datenpaktes vom FHT80 das Geräte anlegt. In der nach dem erfolgten autocreate entstehenden Log-Datei nachsehen, warten, bis der angeblich neu entdeckte FHT das erste Mal seinen Status sendet.
*Wieder die fhem.cfg editieren, darin den "neu entdeckten" FHT löschen und die oben erfolgte Auskommentierung wieder rückgängig machen, autocrate ggf wieder auschalten, sichern.

== Hardware defekt? ==
Es gibt auch defekte FHT80b, aber oft hilft eine geringe Aufweitung der Bandbreite (siehe oben) oder schlicht eine neuer Satz Batterien. Manchmal führt auch ein "matchen" der FHTs mit der Funklage zum Ziel: Rausfinden, welche FHTs am problemlosesten arbeiten und diese an den Stellen unterbringen, die funktechnisch die ungünstigsten sind, während weniger zuverlässige FHTs näher an der Zentrale eingesetzt werden. Aufgrund der recht primitiven Sender/Empfänger (Pendelempfänger) der FHTs sind hier durchaus deutliche Streuungen möglich.

== Weiterführende Artikel ==
* [[Was ist der Hauscode?]]
* [[1% Regel]]
* [[Maximal nutzbare Geräte]]

[[Kategorie:FHT Components]]

Kommunikationsprobleme mit FHT

2014-08-13T11:57:58Z

Kamischi: /* Symptome */

Während FHEM mit reinen Schaltaktoren in der Regel problemarm funktioniert, sind Probleme mit [[FHT80b]] Heizungsteuerungen recht häufig. Dies liegt in der deutlich anspruchsvolleren bidirektionalen Kommunikation, die zur Übermittlung der ggf. durchaus umfangreichen Daten notwendig ist.

== Symptome ==
Im Einsatz von FHTs kann es zu folgenden Symptomen kommen:

* FHT funktioniert zunächst einwandfrei, dann plötzlich sind keine Temperaturänderungen o.ä. mehr möglich
* FHTs funktionieren einwandfrei, jedoch seitdem ein weiteres dazu gekommen ist, wird die Datenübertragung langsam oder fällt ganz aus, auch zu FHTs, die vorher ohne Probleme liefen.
* FHT funktioniert manchmal für Stunden gut, übermittelt aktuelle Werte und lässt sich ansprechen, dann für mehrere Stunden wieder nicht, schliesslich "erholt" sich das FHT wieder (oft über Nacht)
* Temperaturänderungen werden von FHT mit hoher Verzögerung (bis hin zu Stunden) ausgeführt
* FHTs laufen ca. eine Woche problemfrei, dann kommen keinen Daten mehr. Nach einem neuen Pairing ist alles wieder in Ordnung, bis nach ca. einer Woche wieder keine Daten kommen.

== Problemquellen ==
Die FHT-Kommunikation ist recht fragil. Es müssen eine Menge Funktelegramme in einem bestimmten Timing ausgetauscht werden, damit Erfolg eintritt. Selbst wenn keine Kommandos an das [[FHT80b]] übergeben werden, findet alle 15 Minuten Datenübermittlungen statt, da das FHT Temperatur und andere Daten meldet.

Bereits ein fehlendes Datenpaket kann dazu führen, dass die Kommunikation erfolglos war und insgesamt wiederholt werden muss.

Störungen des Kanals (z.B. der berühmte Funkkopfhörer aus China) führen daher so gut wie immer zu Problemen in der FHT Kommunikation. Es reicht, wenn von den 5+n Kommandos (n=Anzahl der übermittelten Werteänderungen) die mindestens hin und her gehen müssen, eines nicht korrekt ankommt und schon muss alles wiederholt werden.

Diese Wiederholung kann nur ca. alle 2 Minuten erfolgen. Kommandos, die noch nicht erfolgreich abgearbeitet wurden, verbleiben im FHT Befehlsbuffer des CUL/CUNO (oder sonstiger Funkschnittstellen), obwohl sie seitens FHEM als "abgesetzt" geloggt werden. Dieser FHT Buffer kann mitunter sehr viele Kommandos aufnehmen, die der Reihe nach abgearbeitet werden. Kann z.B. eine Temperaturänderung aufgrund von Funkproblemen erst nach ca. 3 Versuchen erfolgreich zugestellt werden, so dauert es in der Regel etwa 3 x 2 = 6 Minuten, bis die Änderung im FHT sichtbar ankommt. Wird z.B. aus Ungeduld eine erneute Temperaturänderung ausgelöst, so wird diese im FHT Buffer gespeichert und dann nach erfolgter Übertragung des ersten Kommandos übermittelt. Die Abarbeitungszeit der Warteschlange für dieses FHT steigt dann bereits auf ca. 12 Minuten. Es ist leicht möglich, durch Abfrage der Wochenprogramme, Änderung der Day- oder Nighttemperatur, oder Änderung von Wochenschaltpunkten Warteschlangen aufzubauen, die buchstäblich Stunden oder gar Tage zum Abarbeiten benötigen. Temperaturänderungen könnten also mitunter erst Stunden später tatsächlich ausgeführt werden. Jeder Aussendungsversuch führt außerdem zur Belastung des Sendekontos. Ist die [[1% Regel]] überschritten, wird die Warteschlange nicht mehr weiter abgearbeitet.

Solche Störungen des Funkkanals sind nicht selten und können auch ohne äußere Einflüsse stattfinden.
Die FHTs sind mit relativ ungenauen Sendern ausgestattet und können in Sendefrequenz und Flankensteilheit mitunter deutlich von den Sollwerten abweichen, was insbesondere beim Einsatz von CUL / CUNO (weniger beim Einsatz einer FHZ1x00PC) ein Problem sein kann, weil die CUL / CUNO eher trennscharf sind. Dies kann dazu führen, dass die Funkkommunikation oft fehlerhaft ist oder sogar ganz abbricht.

Zusätzlich stellen einige FHTs das Aussenden von Temperatur und weiteren Daten nach 5-10 Tagen ein, wenn nicht zwischendurch von der Zentrale Änderungen übermittelt wurden.

Alle vorstehenden Gründe kombinieren sich für gewöhnlich zu einem komplexen Versagensszenario, das sich gegenseitig selbst verstärkt:

* Schlechte Funklage eines FHT80b erzeugt häufige Retrys.
* Inzwischen stauen sich weitere Kommandos an das FHT auf, z.B. wegen erneuter Temperaturänderungen, automatisiert oder aus Ungeduld, sowie andere Meldungen, etwa Abfrage oder Ändern des Wochenprogramms.
* Die Kommandos sammeln sich im FHT Buffer des Funkadapters an und sorgen dafür, dass die Sendezeit hoch belastet wird.
* Fast Glück hat man noch, wenn der Buffer voll läuft und [[EOB]] Meldungen im Log darauf hinweisen. Es kann aber auch passieren, dass über grössere Zeiträume der Buffer gerade eben nicht voll wird, insbesondere bei CUL / CUN, die im Vergleich zur FHZ1x00PC große Buffer haben, die 30 und mehr Kommandos halten können. Ist zusätzlich das Feature "Softbuffer" eingeschaltet, verschlimmert sich die Situation weiter, da die Warteschlange noch länger werden kann.
* Ist die 1% Marke erreicht, das Funkkontingent also aufgebraucht, verschlimmert sich die Situation dramatisch: Nun bricht auch die Kommunikation mit anderen FHTs zusammen. Da außerdem immer Kommandos im FHT Buffer sind, wird jede freie Sendezeit durch Versuche die Warteschlange abzuarbeiten sofort wieder aufgebraucht. Das Timing des Gesamtsystems ist hier leider so, dass sich innerhalb des Retryintervals von ca. 2 Minuten oft gerade zu wenig freie Sendezeiteinheiten aufbauen, um den nächsten Retry komplett abwickeln zu können. D.h. jedes Retry braucht die gerade aufgebauten freien Sendeeinheiten auf, ist aber in sich erfolglos.
* Spätestens ab hier ist vollständiger Stillstand erreicht. Im Log häufen sich die [[LOVF]]- Meldungen, jede Kommunikation mit allen FHTs ist zusammengebrochen. Es kommt eventuell sogar zu Beeinträchtigungen beim Schalten von FS20 Aktoren.

Mit der Anzahl FHTs steigt die Wahrscheinlichkeit für das Auftreten dieser Probleme.

Viele FHEM Nutzer verwenden die Kombination von FHEM und FHT so, dass die FHTs über Manipulation der im FHT gespeicherten Wochenprogramme, Schaltpunkte und Day/Nighttemp gesteuert werden. Dies erhöht die Datenmenge im Vergleich zu einer direkten Temperatursteuerung ("set desired-temp 22") und wird in kritischen Situationen die Fehlerhäufigkeit deutlich anheben. Sehr viel Datenverkehr erzeugt auch die komplette Abfrage des Wochenprogramms mittels Report1=255.

== Diagnose und Lösungsansätze ==
Im Folgenden einige Hinweise wie man das Auftreten von Problemen verringern bzw. diagnostizieren kann.

=== Sparsam mit Funkzeit umgehen ===
Da die Ausnutzung der freien Funkzeit jede Situation schnell deutlich verschlimmert, sollte man immer bemüht sein, seine Ziele mit wenig Datenverkehr zu erreichen. Dies gilt insbesondere, wenn man sich der Anzahl [[Maximal nutzbare Geräte]] nähert.

* [http://www.fhemwiki.de/wiki/Heizung_mit_Bewegungsmelder_steuern#FHT80b FHT Lazy Mode] nutzen (Temperaturänderungen werden nur übertragen, wenn sie von der momentan eingestellten Temperatur abweichen.) Dies ist besonders hilfreich, wenn die Temperatursteuerung automatisiert durch Bewegungsmelder oder "Zuhausestatus"-Automatismen gesteuert wird, da hier in relativ kurzer Folge die selbe Temperatureinstellung übermittelt wird. Lazy Mode schützt aber nicht immer davor, dass die Warteschlange schnell anschwillt. Steht ein FHT80b z.b. auf 18 Grad, und soll auf 20 Grad angehoben werden, so wird das Kommando trotz Lazy Mode immer wieder in die Warteschlange eingetragen, solange das erste Kommando nicht erfolgreich abgesetzt und die neue Temperatur vom FHT rückgemeldet wurde. Das kann dazu führen, dass die FHT-Warteschlange dutzende Male das selbe "desired-temp" Kommando enthält.
* Temperatursteuerung der FHTs nicht auf täglicher Basis durch Setzen der Wochenprograme im FHT durchführen. Obwohl diese Methode den Vorteil hat, dass sie eine höhere Ausfallsicherheit bietet (weil die FHTs auch ohne FHEM ihr zuletzt eingegebenes Wochenprogamm weiter verwenden können), so steigt der auszutauschende Datenverkehr stark an.

:Mitunter verwendete Implementationen, die Anhand von Tabellen, Kalendern oder der Auswertung von Excelsheets mehrere FHTs regelmässig mit geänderten Wochenprogrammen und/oder Änderungen der Day/Night Temperaturen steuern, sind in schwierigen Funksituation deutlich anfälliger.

* Keine regelmässigen Reports abfragen, insbesondere NICHT report1=255 (also komplettes Wochenprogramm abfragen)
:Da einige FHTs nach einiger Zeit keine Temperaturdaten mehr senden, fragen viele Nutzer diese über tägliches Absetzen von report2=255 ab. Besser ist es jedoch, das FHT mit einem Wachdog zu überwachen und nur bei Bedarf zu "wecken", z.B. so:

<nowiki>define wd_FHT_Wohnzimmer watchdog hzg_wohnzimmer:measured-temp.* 01:00 SAME set hzg_wohnzimmer time</nowiki>
:Alternativ report2=255 1-2x pro Woche nachts absetzen, bei mehreren FHTs eventuell tageweise versetzt:

<nowiki>define fht_reportZimmer1 at *04:00:00 {if ($wday == 1) { fhem("set hzg_Zimmer1 report2 255")</nowiki>

=== Funklage beobachten ===
* RSSI mitloggen:
<nowiki>attr CUL addvaltrigger 1</nowiki>
* RSSI der FHTs beobachten. Unter -85 (also z.b. -89) ist ungünstig. Unbedingt versuchen, ein besseres RSSI als -85 hinzubekommen, zu ALLEN FHTs.
* Antennnenlage des CUL/CUN korrigieren (z.b. Antenne um 45 Grad kippen), eventuell Lage des FHTs ändern, ein halber Meter kann schon viel bringen. Dabei kommt es nicht zwingend nur auf die absolute Entfernung zum Funkadapter an, auch die Lage im Gebäude kann viel ausmachen.
* Wenn CUL / CUN eingesetzt werden, gegebenenfalls die Parameter freq, bandwidth und sens ändern. Als Startpunkt z.B. bandwidth auf 464 khz und sens auf 8 db anstelle 4db ändern. Kombinationen ausprobieren, aber nicht mehrere Parameter gleichzeitig ändern. RSSI-Auswirkung jeder Änderung beobachten.

Wenn das keinen Erfolg bringt, zweiten CUL / CUNO einsetzen, z.b. auch als RFR CUL. Dabei [[RFR CUL und FHT80]] Besonderheiten berücksichtigen: Nicht zu viele FHTs ans RFR CUL anbinden, nur so viele wie gerade nötig. FS20 Repeater helfen nicht.

=== Einstellungen prüfen ===

* Attribut fhtsoftbuffer ausschalten. Beim Einsatz von CUL/CUNO ist die Verwendung von fhtsoftbuffer sowieso überflüssig, da die eigenen FHT Buffer dieser Adapter hinreichend groß sind. Gedacht ist dieses Attribut vor allem für den Einsatz von FHEM mit FHZ1x00PC Zentralen, deren FHT Buffer klein ist und zum Teil nur 8 Befehle halten kann. Das CUL V3 kann demgegenüber 40 FHT Befehle im Buffer halten. D.h. bei einer FHZ1x00PC kann es vorkommen, dass bei 10 zu steuernden FHTs schon ein Kommando der Art "Alle FHTs auf 20 Grad" *nicht* bei allen FHTs ankommt, da nicht alle Befehle zugleich in den Buffer passen. In solchen Fällen ist der Einsatz des Softbuffers hilfreich. (in neueren FHEM Versionen hat das Attribut fhtsoftbuffer daher auf CUL und CUNOs keine Wirkung mehr)

<ul>Das Attribut fhtsoftbuffer erzeugt einen "unendlich" grossen Buffer, was sehr lange Warteschlangen zur Folge haben kann. Das macht die Diagnose sehr schwer und erzeugt seltsamste Effekte, wenn die Kommunikation mit den FHTs nicht einwandfrei ist. In jedem Fall aber "glaubt" FHEM sehr viel länger, dass alles in Ordnung sei, obwohl die Kommunikation gestört ist.

Ganz generell: Wenn eine Installation ohne fhtsoftbuffer nicht zuverlässig läuft, sollte man der Versuchung widerstehen, das Problem durch einen grösseren Buffer lösen zu wollen. Fhtsoftbuffer sollte nur eingesetzt werden, wenn eine FHZ1x00 verwendet wird, die Installation an sich gut läuft und nur gelegentlich EOB Meldungen kommen.
</ul>

* Retrycount auf 1. Wenn fhtsoftbuffer aktiv ist, wird versucht, das Kommando Retrycount-Mal zu wiederholen, wenn es nicht innerhalb von 240 Sekunden abgesetzt werden kann. Das kann die Abarbeitungsgeschwindigkeit der Warteschlange zusätzlich senken, gleichzeitig den Funkzeitverbrauch erhöhen und dadurch Probleme eher noch verschärfen. Sinnvoll ist ein höherer Retrycount womöglich nur, wenn in kleineren Installationen ein FHT gerade am Rande des Funkbereiches liegt, ansonsten aber alles problemfrei abläuft. Ohne fhtsoftbuffer hat retrycount keine Wirkung, wenn retrycount nicht definiert wird, ist der Defaultwert 1.

* Bei mehreren CUxx in der Installation (auch 1 x CUL und 1x RFR CUL) das Attribut IODev kontrollieren. Ist ein FHT mit einem CUxx gepairt, aber das IODev zeigt auf das andere, ist eine Kommunikation nicht möglich. Da aber Temperatur (und weitere Werte) trotzdem empfangen werden, fällt dies zunächst eventuell nicht sofort auf. Der FHTbuffer des "falschen" CUxx wird dann mit Befehlen an das FHT zugemüllt, die nie erfolgreich abgesetzt werden können. Ist der Buffer schliesslich voll, können auch keine Kommandos an andere mit diesem CUxx gepairte FHTs mehr übermittelt werden, obwohl diese eigentlich nicht betroffen sind.
* Bei mehreren CUxx UNBEDINGT sicherstellen, dass die FHT-ID unterschiedlich ist. Bei gleicher FHT-ID fühlen sich zwei "Zentralen" für die FHT Kommunikation verantwortlich, was immer im Chaos endet: beide Funkadapter antworten bei FHT Kommunikationen und stören sich so gegenseitig. Siehe auch [[Was ist der Hauscode?]].
* Bei mehreren CUxx bitte auch die Erläuterungen zum [[Sendpool]] Attribut berücksichtigen, die Funktion von Sendpool wird oft missverstanden.

=== Diagnosemöglichkeiten im Fehlerfall ===
Eine Möglichkeit, sich dem Problem zu nähern ist, das Logfile mit verbose5 anzeigen zu lassen. Die Meldungen sind dann recht detailliert und lassen einige Rückschlüsse zu. Erfahrungsgemäß ist es jedoch besser, sich die Kommunikation mit einer Telnetsitzung anzusehen. Ein Nachteil des Logfiles liegt z.B. darin, dass eine Temperaturänderung als "ausgeführt" angezeigt wird, wenn sie erfolgreich an z.b. das CUL übermittelt wurde, auch wenn sie dort nur in einen schon übervollen Buffer geschrieben wird. In einer Telnetsitzung kann man hingegen den Zustand des Buffers prüfen und die Kommunikation mit dem FHT beobachten.

Dazu:

* Terminalprogramm starten
* Dann mittels <code>telnet (IP des FHEM Servers) 7072 <entertaste></code> eine Telnetverbindung zu FHEM starten (7072 ist FHEMs Telnetport)
* erneut <entertaste> drücken, nun muss als Prompt "fhem>" erscheinen.

Jetzt können zahlreiche Kommandos zur Diagnose abgegeben werden.

* info timer <entertaste> zeigt einem alle Events, die FHEM empfängt und sendet. Hier kann man die Kommunikation live verfolgen und so z.B. sehen, ob noch Kommunikation mit dem FHT versucht wird. Einfach eine Weile mitlaufen lassen und sich ansehen, was alles passiert.
* Wenn man einen CUxx im Einsatz hat, dann kann man sich mittels "set CUL raw X61" ("CUL" durch Namen der eigenen Schnittstelle wie in fhemconfig definiert ersetzen) auch Details der Kommunikation anzeigen lassen. So kann man vergleichen, ob die Kommunikation mit dem Beispiel [[FHT80b#Log-Auszug]] übereinstimmt, also planmäßig abläuft. "set CUL raw X21" setzt das CUL wieder auf den Standard-Loglevel zurück. Achtung, Groß- und Kleinschreibung beachten: Das X61/X21 hat ein großes X.
* Auch sollte man prüfen, ob der der CUxx so konfiguriert ist, wie man glaubt. Mit "get CUL ccconf" kann man die wichtigsten Werte ansehen.
* Ist der FHT Buffer leer oder was hat sich da ggf. aufgestaut? "'''get CUL raw T02'''" ergibt den Inhalt des Buffers. Da sollte möglichst nichts drin stehen ("CUL raw => N/A") oder nicht viel. Mit der Zeit erkennt man die Codes gleich, daraus ergibt sich, welches FHT Probleme macht (Adresse) und welche Kommandos noch auf Aussendung warten. Folgender Beispieloutput: "CUL raw => 060D:4118 060D:65FF 060D:66FF 060D:4120" ist bereits verdächtig. FHT 060D hat noch 4 Kommandos in der Warteschlange, die Abarbeitung hier dauert schon im besten Fall mindesten noch 8 Minuten. Sieht bereits nach "Rückstau" aus. (4118 = desired temp auf Wert 18, 65ff= report1=255 66ff= report2=255).
* Mehrfaches Eingeben von "get CUL raw T02" im Abstand von ca 2 Minuten (dem Intervall, in dem Kommunikation mit dem FHTs stattfinden kann) zeigt einem, ob die Schlange sich abarbeitet oder welche Kommandos klemmen.
* Wenn man CUxx im Einsatz hat kann man auch die freie Sendezeit prüfen: "get CUL raw X" Der zweite Zahlenwert ist die Sendezeit in 10ms Slots. Während ein FS20 Schalter im Idealfall mit 21 Einheiten (=210 ms) erledigt werden kann, braucht schon die simpelste Übertragung nur eines Wertes an ein FHT ca. 3x mehr Zeiteinheiten. Wenn also nicht mindestens 65 Zeiteinheiten frei sind, kann keine FHT Übertragung erfolgreich sein.
* CUxx Funkadapter können auch resettet werden: "set CUL raw B00" resettet das CUL, und löscht dabei alle Buffer und setzt die freie Funkzeit auf Maximum. Die Wirkung ist die selbe wie den Adapter kurz stromlos zu machen. Will man hingegen nur den FHT Buffer leeren, kann man auch "'''set CUL raw T01xxxx'''" eingeben, wobei xxxx = FHT-ID istdie aus fhem.cfg aus der CUL-Definition gelesen werden kann. Diese muss natürlich mit der vorherigen übereinstimmen, da sonst alle FHT-Pairings ungültig sind. Nach dem Löschen des Buffers noch kurz mit "get CUL raw T02" überprüfen, dass der buffer auch wirklich leer ist. Anschliessend irgendeinen Befehl an den FHT senden, z.B. Ändern der desired-temp um 1 Grad. Danach fängt der FHT meist wieder an zu senden. Manchmal muss man ihm auch einfach ein bischen Zeit geben, bis er sich wieder fängt.

=== Repairen ===
Lassen sich durch die obigen Massnahmen keine nahliegenden Problem entdecken, hilft gelegentlich auch ein
simples neu Pairen eines nicht komunizierenden FHTs.

Wiederkehrende Actuator-Meldung "'''unknown_69'''" lassen sich z.b. meist mit einem neuen Pairing lösen.

====Neues Pairen ohne Autocreate====
*fhem.cfg unbearbeitet lassen
*FHT80b in Sonderfunktionen "cENT" auf "n/a" stellen, danach sofort in FHEM einen Befehl (egal welchen) an die FHT80b senden.
*Wenn ca. zwei Minuten später Sonderfunktion cENT auf "ON" steht, war das Pairing erfolgreich.

====Neues Pairing mit Autocreate====
Alternativ hat auch dieser Weg zum Erfolg geführt:
*In der fhem.cfg den define-Eintrag für diesen FHT auskommentieren, autocreate ggf. einschalten, sichern.
*Am FHT80b in Sonderfunktionen "cENT" auf "n/a" stellen, sodass eine neue Paarung eingeleitet wird
*Warten bis FHEM nach Empfang eines Datenpaktes vom FHT80 das Geräte anlegt. In der nach dem erfolgten autocreate entstehenden Log-Datei nachsehen, warten, bis der angeblich neu entdeckte FHT das erste Mal seinen Status sendet.
*Wieder die fhem.cfg editieren, darin den "neu entdeckten" FHT löschen und die oben erfolgte Auskommentierung wieder rückgängig machen, autocrate ggf wieder auschalten, sichern.

== Hardware defekt? ==
Es gibt auch defekte FHT80b, aber oft hilft eine geringe Aufweitung der Bandbreite (siehe oben) oder schlicht eine neuer Satz Batterien. Manchmal führt auch ein "matchen" der FHTs mit der Funklage zum Ziel: Rausfinden, welche FHTs am problemlosesten arbeiten und diese an den Stellen unterbringen, die funktechnisch die ungünstigsten sind, während weniger zuverlässige FHTs näher an der Zentrale eingesetzt werden. Aufgrund der recht primitiven Sender/Empfänger (Pendelempfänger) der FHTs sind hier durchaus deutliche Streuungen möglich.

== Weiterführende Artikel ==
* [[Was ist der Hauscode?]]
* [[1% Regel]]
* [[Maximal nutzbare Geräte]]

[[Kategorie:FHT Components]]

HM-CFG-USB USB Konfigurations-Adapter

2014-08-12T23:51:36Z

Kamischi: /* Einrichtung unter Mac OS X */

Der [[HomeMatic]] '''USB Konfigurations-Adapter''' ist ein USB-Stick, der außer zur Konfiguration von HomeMatic Komponenten auch als [[Interface]] zwischen Fhem und HomeMatic Geräten benutzt werden kann.

== Einbindung in FHEM ==
Im FHEM-Forum wird das Thema diskutiert unter dem Titel [http://forum.fhem.de/index.php/topic,13071.msg86075.html#msg86075 HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in Fhem nutzen]. Teile der Informationen sind hier zusammengefasst.

=== Einrichtung unter Linux ===
Es gibt einen gut funktionierenden Dämon, um den USB Stick mit FHEM zum Laufen zu bekommen. Dabei wird zuerst der Dämon [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland] installiert und danach das Gerät (üblicherweise auf localhost) genau wie [[HM-CFG-LAN LAN Konfigurations-Adapter|HMLAN]] in FHEM eingebunden.

Zunächst muss der Dämon compiliert werden. Analog zu [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb dieser Beschreibung] ist die Vorgehensweise die folgende (in Debian/Ubuntu/Raspbian):
cd /opt/
apt-get install build-essential libusb-1.0-0-dev make gcc git-core
git clone git://git.zerfleddert.de/hmcfgusb
cd hmcfgusb
make

(Unter Debian ist "build-essentials" nicht als Paket vorhanden, dieser Schritt kann entfallen.)

Danach kann der Dienst zu Testzwecken gestartet werden (in /opt/hmcfgusb):
:<code>./hmland -p 1234 -D</code>

Um den Dämon nach einem Neustart automatisiert zu starten, kann ein init-script wie das Folgende verwendet werden:
<pre>
# simple init for hmland

pidfile=/var/run/hmland.pid
port=1234

case "$1" in
start|"")
chrt 50 /opt/hmcfgusb/hmland -r 03:30 -d -P -l 127.0.0.1 -p $port 2>&1 | perl -ne '$|=1; print localtime . ": [hmland] $_"' >> /var/log/hmland.log &
;;
restart|reload|force-reload)
echo "Error: argument '$1' not supported" >&2
exit 3
;;
stop)
killall hmland
;;
status)
if [ ! -e $pidfile ]; then
echo "No pid"
exit 1
fi
pid=`cat $pidfile`
if kill -0 $pid &>1 > /dev/null; then
echo "Running"
exit 0
else
rm $pidfile
echo "Not running"
exit 1
fi

;;
*)
echo "Usage: hmland [start|stop|status]" >&2
exit 3
;;
esac
</pre>

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgendes Konfigurationsfile verwendet werden:
<pre>
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

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

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

=== Alternative Einrichtung, Start über fhem Startskript ===

Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

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

Dann geht es weiter:

sudo cp hmcfgusb.rules /etc/udev/rules.d/

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

Damit editiert man das fhem Startskript:
sudo nano /etc/init.d/fhem

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)

'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

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

So wird hmland vor fhem gestartet und nach fhem beendet. Letztlich erspart es das Hantieren mit den diversen Startskripten und ihren Rechten.

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

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

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

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

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

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:

Datum Zeit: Client 127.0.0.1 connected! 
Can't claim interface: Access denied (insufficient permissions) 
Can't find/open hmcfgusb! 
Datum Zeit: Connection to 127.0.0.1 closed! 

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

idProduct: 49167 
idVendor: 6943

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:

chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext

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

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

=== Einrichtung unter Windows ===
< Todo >

== Bekannte Probleme ==

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

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

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
* HM-CFG-USB-2: die aktuelle Version; Dokumentation derzeit (12/2013) nicht über die ELV-Artikelseite verfügbar, alternativ jedoch bei [http://files.voelkner.de/625000-649999/640558-an-01-ml-USB_FUNK_KONFIGURATIONSADAPTER_de_en.pdf Völkner]; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

== Links ==
* [http://forum.fhem.de/index.php/topic,13071.msg86075.html#msg86075 FHEM Forum: HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in Fhem nutzen]
* [http://www.elv.de/homematic-usb-konfigurations-adapter-1.html ELV- / Herstellerinformationen] zum HM-CFG-USB

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

HM-CFG-USB USB Konfigurations-Adapter

2014-08-12T23:50:47Z

Kamischi: /* Einrichtung unter Mac OS X */

Der [[HomeMatic]] '''USB Konfigurations-Adapter''' ist ein USB-Stick, der außer zur Konfiguration von HomeMatic Komponenten auch als [[Interface]] zwischen Fhem und HomeMatic Geräten benutzt werden kann.

== Einbindung in FHEM ==
Im FHEM-Forum wird das Thema diskutiert unter dem Titel [http://forum.fhem.de/index.php/topic,13071.msg86075.html#msg86075 HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in Fhem nutzen]. Teile der Informationen sind hier zusammengefasst.

=== Einrichtung unter Linux ===
Es gibt einen gut funktionierenden Dämon, um den USB Stick mit FHEM zum Laufen zu bekommen. Dabei wird zuerst der Dämon [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland] installiert und danach das Gerät (üblicherweise auf localhost) genau wie [[HM-CFG-LAN LAN Konfigurations-Adapter|HMLAN]] in FHEM eingebunden.

Zunächst muss der Dämon compiliert werden. Analog zu [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb dieser Beschreibung] ist die Vorgehensweise die folgende (in Debian/Ubuntu/Raspbian):
cd /opt/
apt-get install build-essential libusb-1.0-0-dev make gcc git-core
git clone git://git.zerfleddert.de/hmcfgusb
cd hmcfgusb
make

(Unter Debian ist "build-essentials" nicht als Paket vorhanden, dieser Schritt kann entfallen.)

Danach kann der Dienst zu Testzwecken gestartet werden (in /opt/hmcfgusb):
:<code>./hmland -p 1234 -D</code>

Um den Dämon nach einem Neustart automatisiert zu starten, kann ein init-script wie das Folgende verwendet werden:
<pre>
# simple init for hmland

pidfile=/var/run/hmland.pid
port=1234

case "$1" in
start|"")
chrt 50 /opt/hmcfgusb/hmland -r 03:30 -d -P -l 127.0.0.1 -p $port 2>&1 | perl -ne '$|=1; print localtime . ": [hmland] $_"' >> /var/log/hmland.log &
;;
restart|reload|force-reload)
echo "Error: argument '$1' not supported" >&2
exit 3
;;
stop)
killall hmland
;;
status)
if [ ! -e $pidfile ]; then
echo "No pid"
exit 1
fi
pid=`cat $pidfile`
if kill -0 $pid &>1 > /dev/null; then
echo "Running"
exit 0
else
rm $pidfile
echo "Not running"
exit 1
fi

;;
*)
echo "Usage: hmland [start|stop|status]" >&2
exit 3
;;
esac
</pre>

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgendes Konfigurationsfile verwendet werden:
<pre>
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

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

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

=== Alternative Einrichtung, Start über fhem Startskript ===

Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

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

Dann geht es weiter:

sudo cp hmcfgusb.rules /etc/udev/rules.d/

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

Damit editiert man das fhem Startskript:
sudo nano /etc/init.d/fhem

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)

'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

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

So wird hmland vor fhem gestartet und nach fhem beendet. Letztlich erspart es das Hantieren mit den diversen Startskripten und ihren Rechten.

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

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

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

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

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

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:

Datum Zeit: Client 127.0.0.1 connected! 
Can't claim interface: Access denied (insufficient permissions) 
Can't find/open hmcfgusb! 
Datum Zeit: Connection to 127.0.0.1 closed! 

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

idProduct: 49167 
idVendor: 6943

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:

chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext

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

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

=== Einrichtung unter Windows ===
< Todo >

== Bekannte Probleme ==

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

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

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
* HM-CFG-USB-2: die aktuelle Version; Dokumentation derzeit (12/2013) nicht über die ELV-Artikelseite verfügbar, alternativ jedoch bei [http://files.voelkner.de/625000-649999/640558-an-01-ml-USB_FUNK_KONFIGURATIONSADAPTER_de_en.pdf Völkner]; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

== Links ==
* [http://forum.fhem.de/index.php/topic,13071.msg86075.html#msg86075 FHEM Forum: HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in Fhem nutzen]
* [http://www.elv.de/homematic-usb-konfigurations-adapter-1.html ELV- / Herstellerinformationen] zum HM-CFG-USB

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

HM-CFG-USB USB Konfigurations-Adapter

2014-08-12T23:45:30Z

Kamischi: /* Einrichtung unter Mac OS X */

Der [[HomeMatic]] '''USB Konfigurations-Adapter''' ist ein USB-Stick, der außer zur Konfiguration von HomeMatic Komponenten auch als [[Interface]] zwischen Fhem und HomeMatic Geräten benutzt werden kann.

== Einbindung in FHEM ==
Im FHEM-Forum wird das Thema diskutiert unter dem Titel [http://forum.fhem.de/index.php/topic,13071.msg86075.html#msg86075 HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in Fhem nutzen]. Teile der Informationen sind hier zusammengefasst.

=== Einrichtung unter Linux ===
Es gibt einen gut funktionierenden Dämon, um den USB Stick mit FHEM zum Laufen zu bekommen. Dabei wird zuerst der Dämon [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland] installiert und danach das Gerät (üblicherweise auf localhost) genau wie [[HM-CFG-LAN LAN Konfigurations-Adapter|HMLAN]] in FHEM eingebunden.

Zunächst muss der Dämon compiliert werden. Analog zu [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb dieser Beschreibung] ist die Vorgehensweise die folgende (in Debian/Ubuntu/Raspbian):
cd /opt/
apt-get install build-essential libusb-1.0-0-dev make gcc git-core
git clone git://git.zerfleddert.de/hmcfgusb
cd hmcfgusb
make

(Unter Debian ist "build-essentials" nicht als Paket vorhanden, dieser Schritt kann entfallen.)

Danach kann der Dienst zu Testzwecken gestartet werden (in /opt/hmcfgusb):
:<code>./hmland -p 1234 -D</code>

Um den Dämon nach einem Neustart automatisiert zu starten, kann ein init-script wie das Folgende verwendet werden:
<pre>
# simple init for hmland

pidfile=/var/run/hmland.pid
port=1234

case "$1" in
start|"")
chrt 50 /opt/hmcfgusb/hmland -r 03:30 -d -P -l 127.0.0.1 -p $port 2>&1 | perl -ne '$|=1; print localtime . ": [hmland] $_"' >> /var/log/hmland.log &
;;
restart|reload|force-reload)
echo "Error: argument '$1' not supported" >&2
exit 3
;;
stop)
killall hmland
;;
status)
if [ ! -e $pidfile ]; then
echo "No pid"
exit 1
fi
pid=`cat $pidfile`
if kill -0 $pid &>1 > /dev/null; then
echo "Running"
exit 0
else
rm $pidfile
echo "Not running"
exit 1
fi

;;
*)
echo "Usage: hmland [start|stop|status]" >&2
exit 3
;;
esac
</pre>

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgendes Konfigurationsfile verwendet werden:
<pre>
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

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

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

=== Alternative Einrichtung, Start über fhem Startskript ===

Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

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

Dann geht es weiter:

sudo cp hmcfgusb.rules /etc/udev/rules.d/

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

Damit editiert man das fhem Startskript:
sudo nano /etc/init.d/fhem

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)

'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

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

So wird hmland vor fhem gestartet und nach fhem beendet. Letztlich erspart es das Hantieren mit den diversen Startskripten und ihren Rechten.

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

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

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

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

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

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:

Datum Zeit: Client 127.0.0.1 connected! 
Can't claim interface: Access denied (insufficient permissions) 
Can't find/open hmcfgusb! 
Datum Zeit: Connection to 127.0.0.1 closed! 

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

idProduct: 49167 
idVendor: 6943

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:

chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext

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

=== Einrichtung unter Windows ===
< Todo >

== Bekannte Probleme ==

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

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

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
* HM-CFG-USB-2: die aktuelle Version; Dokumentation derzeit (12/2013) nicht über die ELV-Artikelseite verfügbar, alternativ jedoch bei [http://files.voelkner.de/625000-649999/640558-an-01-ml-USB_FUNK_KONFIGURATIONSADAPTER_de_en.pdf Völkner]; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

== Links ==
* [http://forum.fhem.de/index.php/topic,13071.msg86075.html#msg86075 FHEM Forum: HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in Fhem nutzen]
* [http://www.elv.de/homematic-usb-konfigurations-adapter-1.html ELV- / Herstellerinformationen] zum HM-CFG-USB

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

Squeezebox

2014-08-12T21:38:23Z

Kamischi:

Um eine Logitech Squeezebox (ein Netzwerk-Musikplayer) fernzusteuern, muss diese mit einem Logitech Media Server verbunden sein. (Weitere Informationen, wie man die Squeezebox mit einem Server verbindet, findet man auf [http://www.mysqueezebox.com/download MySqueezeBox.de].)
 '''Hinweis:''' Seit 12/2013 gibt es ein Modul zur Steuerung von Squeezeboxes (98_SB_PLAYER). Bitte im [http://forum.fhem.de/index.php/topic,17667 Forum] den aktuellen Stand prüfen. 

Getestet wurde das folgende auf einer FB7390 mit FHEM [[AVM Fritz!Box]].

Einfach in ein Utils Skript ([[99 myUtils anlegen]]) folgende Funktion einfügen:

<nowiki>sub squeezebox($) {
my ($state) = @_;
if ($state eq "on")
{
system("wget -O /dev/null -q http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html?p0=play");
}
else
{
system("wget -O /dev/null -q http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html?p0=power&p1=0");
}
}</nowiki>
Ein Aufruf erfolgt mit <code>{ squeezebox("on") }</code> oder <code>{ squeezebox("off") }</code>

= Hinweise =
* In dem Skript muss die IP sowie der Port ersetzt werden. Der Standardport ist 9000.
* Es gibt noch weitere Befehle, um die Squeezebox zu steuern (Lautstärke erhöhen, Pause, Stop, ...)
** Lautstärke setzen: <code>http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html?p0=mixer&p1=volume&p2=YY</code>, wobei YY die Lautstärke auf einer Skala von 0-100 ist.
* Falls mehrere Squeezeboxen mit dem Server verbunden sind, kann mittels Parameter <code>&player=XX%3AXX%3AXX%3AXX%3AXX%3AXX</code> eine spezielle verwendet werden. XX: MAC-Adresse der Squeezebox.
* Mehr Befehle können aus den Links der Statusseite ausgelesen werden: <code>http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html</code>

= Quelle =
Grundlagen in folgendem Beitrag entdeckt: [http://www.squeezebox-forum.de/viewtopic.php?f=13&t=1521#p12286 [1]]

[[Kategorie:Code Snippets]]

SYSMON

2014-08-12T21:35:25Z

Kamischi:

{{Infobox Modul
|ModPurpose=Anzeige von Informationen und Statistiken zu dem System, auf dem Fhem ausgeführt wird.
|ModType=d

|ModForumArea=[http://forum.fhem.de/index.php/board,44.0.html Unterstützende Dienste]
|ModTechName=42_SYSMON.pm
|ModOwner=hexenmeister ([http://forum.fhem.de/index.php?action=profile;u=4065 Forum] / [[Benutzer:Hexenmeister|Wiki]])
}}

Das [[SYSMON]] Modul liefert diverse Informationen und Statistiken zu dem System, auf dem FHEM-Server ausgeführt wird.
Es werden nur Linux-basierte Systeme unterstützt. Manche Informationen sind hardwarespezifisch und sind daher nicht auf jeder Plattform verfügbar.
Bis jetzt wurde dieses Modul auf folgenden Systemen getestet: Raspberry Pi (Debian Wheezy), BeagleBone Black, FritzBox 7390, WR703N unter OpenWrt.

==Definition==
:<code>define <name> SYSMON [<M1>[ <M2>[ <M3>[ <M4>]]]]</code>

Diese Anweisung erstellt eine neue SYSMON-Instanz. Die Parameter M1 bis M4 legen die Aktualisierungsintervalle für verschiedenen Readings (Statistiken) fest. Die Parameter sind als Multiplikatoren für die Zeit, die durch INTERVAL_BASE definiert ist, zu verstehen. Da diese Zeit fest auf 60 Sekunden gesetzt ist, können die Mx-Parameters als Zeitintervalle in Minuten angesehen werden.
Wird einer (oder mehrere) Multiplikatoren auf Null gesetzt werden, wird das entsprechende Readings deaktiviert.

===Parameter===
Die Parameter sind für die Aktualisierung der Readings nach folgender Schema zuständig:

* '''M1''': (Default-Wert: 1)
:CPU-Daten: ''cpu_freq'', ''cpu_temp'', ''cpu_temp_avg'', ''loadavg'', ''stat_cpu'', ''stat_cpu_diff'', ''stat_cpu_percent'', ''stat_cpu_text'', power readings

* '''M2''': (Default-Wert: M1)
:Speicher: ''ram'', ''swap'' etc.

* '''M3''': (Default-Wert: M1)
:Netztwerkinformationen: ''eth0'', ''eth0_diff'', ''wlan0'', ''wlan0_diff'' etc.

* '''M4''': (Default-Wert: 10*M1)
:Filesystem-Informationen

folgende Readings werden immer anhand des Basisintervalls (unabhängig von den Mx-Parameters) aktualisiert:
''fhemuptime'', ''fhemuptime_text'', ''idletime'', ''idletime_text'', ''uptime'', ''uptime_text''

==readings==

* '''cpu_bogomips'''
:CPU Speed: BogoMIPS

* '''cpu_freq'''
:CPU-Frequenz

* '''cpu_temp'''
:CPU-Temperatur

* '''cpu_temp_avg'''
:Durchschnitt der CPU-Temperatur, gebildet über die letzten 4 Werte.

* '''fhemuptime'''
:Zeit (in Sekunden) seit dem Start des FHEM-Servers.

* '''fhemuptime_text'''
:Zeit seit dem Start des FHEM-Servers: Menschenlesbare Ausgabe (textuelle Darstellung).

* '''idletime'''
:Zeit (in Sekunden und in Prozent), die das System (nicht der FHEM-Server!) seit dem Start in dem Idle-Modus verbracht hat. Also die Zeit der Inaktivität.

* '''idletime_text'''
:Zeit der Inaktivität des Systems seit dem Systemstart in menschenlesbarer Form.

* '''loadavg'''
:Ausgabe der Werte für die Systemauslastung (load average): 1 Minute-, 5 Minuten- und 15 Minuten-Werte.

* '''ram'''
:Ausgabe der Speicherauslastung.

* '''swap'''
:Benutzung und Auslastung der SWAP-Datei (bzw. Partition).

* '''uptime'''
:Zeit (in Sekunden) seit dem Systemstart.

* '''uptime_text'''
:Zeit seit dem Systemstart in menschenlesbarer Form.

* '''Netzwerkinformationen'''
:Informationen zu den über die angegebene Netzwerkschnittstellen übertragene Datenmengen und der Differenz zu der vorherigen Messung.
:Beispiele:
::Menge der übertragenen Daten über die Schnittstelle eth0.
::eth0: RX: 940.58 MB, TX: 736.19 MB, Total: 1676.77 MB
::Änderung der übertragenen Datenmenge in Bezug auf den vorherigen Aufruf (für eth0).
::eth0_diff: RX: 0.66 MB, TX: 0.06 MB, Total: 0.72 MB

* '''Dateisysteminformationen'''
:Informationen zu der Größe und der Belegung der gewünschten Dateisystemen.
:Seit Version 1.1.0 können Dateisysteme auch benannt werden (s.u.).
:In diesem Fall werden für die diese Readings die angegebenen Namen verwendet.
:Dies soll die Übersicht verbessern und die Erstellung von Plots erleichtern.
:Beispiel:
::fs_root: Total: 7340 MB, Used: 3573 MB, 52 %, Available: 3425 MB at /

* '''CPU Auslastung'''
:Informationen zu der Auslastung der CPU(s).
:Beispiel:
::stat_cpu: 10145283 0 2187286 90586051 542691 69393 400342
::stat_cpu_diff: 2151 0 1239 2522 10 3 761
::stat_cpu_percent: 4.82 0.00 1.81 93.11 0.05 0.00 0.20
::stat_cpu_text: user: 32.17 %, nice: 0.00 %, sys: 18.53 %, idle: 37.72 %, io: 0.15 %, irq: 0.04 %, sirq: 11.38 %

* '''Benutzerdefinierte Einträge'''
::Diese Readings sind Ausgaben der Kommandos, die an das Betriebssystem übergeben werden. Die entsprechende Angaben werden im Attribut user-defined vorgenommen.

'''FritzBox-spezifische Readings'''
* '''wlan_state'''
:WLAN-Status: on/off

* '''wlan_guest_state'''
:Gast-WLAN-Status: on/off

* '''internet_ip'''
:aktuelle IP-Adresse

* '''internet_state'''
:Status der Internetverbindung: connected/disconnected

* '''night_time_ctrl'''
:Status der Klingelsperre on/off

* '''num_new_messages'''
:Anzahl der neuen Anrufbeantworter-Meldungen

* '''fw_version_info'''
:Angaben zu der installierten Firmware-Version:

 
'''Readings zur Stromversorgung'''
* '''power_ac_stat'''
:Statusinformation für die AC-Buchse: present (0|1), online (0|1), voltage, current
:Beispiel:
::power_ac_stat: 1 1 4.807 264

* '''power_ac_text'''
:Statusinformation für die AC-Buchse in menschenlesbarer Form
:Beispiel:
::power_ac_text ac: present / online, Voltage: 4.807 V, Current: 264 mA

* '''power_usb_stat'''
:Statusinformation für die USB-Buchse

* '''power_usb_text'''
Statusinformation für die USB-Buchse in menschenlesbarer Form

* '''power_battery_stat'''
:Statusinformation für die Batterie (wenn vorhanden): present (0|1), online (0|1), voltage, current, actual capacity
:Beispiel:
::power_battery_stat: 1 1 4.807 264 100

* '''power_battery_text'''
:Statusinformation für die Batterie (wenn vorhanden) in menschenlesbarer Form

* '''power_battery_info'''
:Menschenlesbare Zusatzinformationen für die Batterie (wenn vorhanden): Technologie, Kapazität, Status, Zustand, Gesamtkapazität
:Beispiel:
::power_battery_info: battery info: Li-Ion , capacity: 100 %, status: Full , health: Good , total capacity: 2100 mAh

===Ausgabe-Beispiel===

{| class="wikitable"
|-
|cpu_freq
|900
|2013-11-27 00:05:36
|-
|cpu_temp
|49.77
|2013-11-27 00:05:36
|-
|cpu_temp_avg
|49.7
|2013-11-27 00:05:36
|-
|eth0
|RX: 2954.22 MB, TX: 3469.21 MB, Total: 6423.43 MB
|2013-11-27 00:05:36
|-
|eth0_diff
|RX: 6.50 MB, TX: 0.23 MB, Total: 6.73 MB
|2013-11-27 00:05:36
|-
|fhemuptime
|11231
|2013-11-27 00:05:36
|-
|fhemuptime_text
|0 days, 03 hours, 07 minutes
|2013-11-27 00:05:36
|-
|idletime
|931024 88.35 %
|2013-11-27 00:05:36
|-
|idletime_text
|10 days, 18 hours, 37 minutes (88.35 %)
|2013-11-27 00:05:36
|-
|loadavg
|0.14 0.18 0.22
|2013-11-27 00:05:36
|-
|ram
|Total: 485 MB, Used: 140 MB, 28.87 %, Free: 345 MB
|2013-11-27 00:05:36
|-
|swap
|n/a
|2013-11-27 00:05:36
|-
|uptime
|1053739
|2013-11-27 00:05:36
|-
|uptime_text
|12 days, 04 hours, 42 minutes
|2013-11-27 00:05:36
|-
|wlan0
|RX: 0.00 MB, TX: 0.00 MB, Total: 0 MB
|2013-11-27 00:05:36
|-
|wlan0_diff
|RX: 0.00 MB, TX: 0.00 MB, Total: 0.00 MB
|2013-11-27 00:05:36
|-
|fs_root
|Total: 7404 MB, Used: 3533 MB, 50 %, Available: 3545 MB at /
|2013-11-27 00:05:36
|-
|fs_boot
|Total: 56 MB, Used: 19 MB, 33 %, Available: 38 MB at /boot
|2013-11-27 00:05:36
|-
|fs_usb1
|Total: 30942 MB, Used: 6191 MB, 21 %, Available: 24752 MB at /media/usb1
|2013-11-27 00:05:36
|-
|stat_cpu
|10145283 0 2187286 90586051 542691 69393 400342
|2013-11-27 00:05:36
|-
|stat_cpu_diff
|2151 0 1239 2522 10 3 761
|2013-11-27 00:05:36
|-
|stat_cpu_percent
|4.82 0.00 1.81 93.11 0.05 0.00 0.20
|2013-11-27 00:05:36
|-
|stat_cpu_text
|user: 32.17 %, nice: 0.00 %, sys: 18.53 %, idle: 37.72 %, io: 0.15 %, irq: 0.04 %, sirq: 11.38 %
|2013-11-27 00:05:36
|}

==Befehle==

===get===

*interval
:Listet die bei der Definition angegebene Polling-Intervalle auf.

*list
:Gibt alle Readings aus.

*update
:Aktualisiert alle Readings. Alle Werte werden neu abgefragt.

*version
:Zeigt die Version des SYSMON-Moduls.

===set===

*interval_multipliers
:Definiert Multipliers (wie bei der Definition des Gerätes).

*clean
:Löscht benutzerdefinierbare Readings. Nach einem Update (oder nach der automatischen Aktualisierung) werden neue Readings generiert.

*clear <reading name>
:Löscht den Reading-Eintrag mit dem gegebenen Namen. Nach einem Update (oder nach der automatischen Aktualisierung) wird dieser Eintrag ggf. neu erstellt (falls noch definiert). Dieses Mechanismus erlaubt das gezielte Löschen nicht mehr benötigter benutzerdefinierten Einträge.

==Attribute==

*filesystems <reading name>[:<mountpoint>[:<comment>]],...
:Gibt die zu überwachende Dateisysteme an. Es wird eine kommaseparierte Liste erwartet.
:Reading-Name wird bei der Anzeige und Logging verwendet, Mount-Point ist die Grundlage der Auswertung, Kommentar ist relevant für die HTML-Anzeige (s. SYSMON_ShowValuesHTML)
:Beispiel: /boot,/,/media/usb1
:oder: fs_boot:/boot,fs_root:/:Root,fs_usb1:/media/usb1:USB-Stick
:Im Sinne der besseren Übersicht sollten zumindest Name und MountPoint angegeben werden.

*network-interfaces <name>[:<interface>[:<comment>]],...
:Kommaseparierte Liste der Netzwerk-Interfaces, die überwacht werden sollen. Jeder Eintrag besteht aus dem Reading-Namen, dem Namen des Netzwerk-Adapters und einem Kommentar für die HTML-Anzeige (s. SYSMON_ShowValuesHTML). Wird kein Doppelpunkt verwendet, wird der Wert gleichzeitig als Reading-Name und Interface-Name verwendet.
:Beispiel ethernet:eth0:Ethernet,wlan:wlan0:WiFi

*user-defined <readingsName>:<Interval_Minutes>:<Comment>:<Cmd>,...
:Diese kommaseparierte Liste definiert Einträge mit jeweils folgenden Daten: Reading-Name, Aktualisierungsintervall in Minuten, Kommentar und Betriebssystem-Kommando.
:Die BS-Befehle werden entsprechend des angegebenen Intervalls ausgeführt und als Readings mit den angegebenen Namen vermerkt. Kommentare werden für die HTML-Ausgaben (s. SYSMON_ShowValuesHTML) benötigt.
:Alle Parameter sind nicht optional!
:Es ist wichtig, dass die angegebenen Befehle schnell ausgeführt werden, denn in dieser Zeit wird der gesamte FHEM-Server blockiert!
:Werden Ergebnisse der lang laufenden Operationen benötigt, sollten diese z.B als CRON-Job eingerichtet werden und in FHEM nur die davor gespeicherten Ausgaben visualisiert.

:Beispiel: Anzeige der vorliegenden Paket-Aktualisierungen für das Betriebssystem:
:In einem cron-Job wird folgendes täglich ausgeführt:
:apt-get upgrade --dry-run| perl -ne '/(\d*)\s[upgraded|aktualisiert]\D*(\d*)\D*install|^ \S+.*/ and print "$1 aktualisierte, $2 neue Pakete"' 2>/dev/null > /opt/fhem/data/updatestatus.txt
:Das Attribute uder-defined wird auf
:sys_updates:1440:System Aktualisierungen:cat /opt/fhem/data/updatestatus.txt
:gesetzt. Danach wird die Anzahl der verfügbaren Aktualisierungen täglich als Reading 'sys_updates' protokolliert.

*disable
:Mögliche Werte: 0,1. Bei 1 wird die Aktualisierung gestoppt.

==Plots==

Für dieses Modul sind bereits einige gplot-Dateien vordefiniert:

:FileLog-Versionen:
::SM_RAM.gplot
::SM_CPUTemp.gplot
::SM_FS_root.gplot
::SM_FS_usb1.gplot
::SM_Load.gplot
::SM_Network_eth0.gplot
::SM_Network_eth0t.gplot
::SM_Network_wlan0.gplot
::SM_CPUStat.gplot
::SM_CPUStatSum.gplot
::SM_CPUStatTotal.gplot
::SM_power_ac.gplot
::SM_power_usb.gplot
::SM_power_battery.gplot
:DbLog-Versionen:
::SM_DB_all.gplot
::SM_DB_CPUFreq.gplot
::SM_DB_CPUTemp.gplot
::SM_DB_Load.gplot
::SM_DB_Network_eth0.gplot
::SM_DB_RAM.gplot

==Methoden==

===HTML-Ausgabe===
HTML-Ausgabe-Methode (für ein Weblink): SYSMON_ShowValuesHTML(<SYSMON-Instanz>[,<Liste>])

Das Modul definiert eine Funktion, die ausgewählte Readings in HTML-Format ausgibt.
Als Parameter wird der Name des definierten SYSMON-Geräts erwartet.
Der zweite Parameter ist optional und gibt eine Liste der anzuzeigenden Readings im Format <ReadingName>[:<Comment>[:<Postfix>]] an.
Dabei gibt ReadingName den anzuzeigenden Reading an, der Wert aus Comment wird als der Anzeigename verwendet und Postfix wird nach dem einheitlichen Wert angezeigt (so können z.B. Einheiten wie MHz angezeigt werden).
Falls kein Comment angegeben ist, wird eine intern vordefinierte Beschreibung angegeben. Bei benutzerdefinierbaren Readings wird ggf. Comment aus der Definition verwendet.
Wird keine Liste angegeben, wird eine vordefinierte Auswahl verwendet (alle Werte).

<pre>define sysv1 weblink htmlCode {SYSMON_ShowValuesHTML('sysmon')}
define sysv2 weblink htmlCode {SYSMON_ShowValuesHTML('sysmon', ('date:Datum', 'cpu_temp:CPU Temperatur: °C', 'cpu_freq:CPU Frequenz: MHz'))}
</pre>

===Text-Ausgabe===

Text-Ausgabe-Methode: SYSMON_ShowValuesText(<SYSMON-Instance>[,<Liste>])

Analog SYSMON_ShowValuesHTML, jedoch formatiert als reines Text.

===Readings-Werte mit Perl lesen===
SYSMON_getValues([<Liste der gewünschten Schlüssel>])

Liefert ein Hash-Ref mit den gewünschten Werten. Wenn keine Liste (array) übergeben wird, werden alle Werte geliefert.

==Beispielkonfiguration==

# Modul-Definition
define sysmon SYSMON 1 1 1 10
#attr sysmon event-on-update-reading cpu_temp,cpu_temp_avg,cpu_freq,eth0_diff,loadavg,ram,^~ /.*usb.*,~ /$
attr sysmon event-on-update-reading cpu_temp,cpu_temp_avg,cpu_freq,eth0_diff,loadavg,ram,fs_.*,stat_cpu_percent
attr sysmon filesystems fs_boot:/boot,fs_root:/:Root,fs_usb1:/media/usb1:USB-Stick
attr sysmon network-interfaces eth0:eth0:Ethernet,wlan0:wlan0:WiFi
attr sysmon group RPi
attr sysmon room 9.03_Tech

# Log
define FileLog_sysmon FileLog ./log/sysmon-%Y-%m.log sysmon
attr FileLog_sysmon group RPi
attr FileLog_sysmon logtype SM_CPUTemp:Plot,text
attr FileLog_sysmon room 9.03_Tech

# Visualisierung: CPU-Temperatur
define wl_sysmon_temp SVG FileLog_sysmon:SM_CPUTemp:CURRENT
attr wl_sysmon_temp group RPi
attr wl_sysmon_temp label "CPU Temperatur: Min $data{min2}, Max $data{max2}, Last $data{currval2}"
attr wl_sysmon_temp room 9.03_Tech

# Visualisierung: Netzwerk-Datenübertragung für eth0
define wl_sysmon_eth0 SVG FileLog_sysmon:SM_Network_eth0:CURRENT
attr wl_sysmon_eth0 group RPi
attr wl_sysmon_eth0 label "Netzwerk-Traffic eth0: $data{min1}, Max: $data{max1}, Aktuell: $data{currval1}"
attr wl_sysmon_eth0 room 9.03_Tech

# Visualisierung: Netzwerk-Datenübertragung für wlan0
define wl_sysmon_wlan0 SVG FileLog_sysmon:SM_Network_wlan0:CURRENT
attr wl_sysmon_wlan0 group RPi
attr wl_sysmon_wlan0 label "Netzwerk-Traffic wlan0: $data{min1}, Max: $data{max1}, Aktuell: $data{currval1}"
attr wl_sysmon_wlan0 room 9.03_Tech

# Visualisierung: CPU-Auslastung (load average)
define wl_sysmon_load SVG FileLog_sysmon:SM_Load:CURRENT
attr wl_sysmon_load group RPi
attr wl_sysmon_load label "Load Min: $data{min1}, Max: $data{max1}, Aktuell: $data{currval1}"
attr wl_sysmon_load room 9.03_Tech

# Visualisierung: RAM-Nutzung
define wl_sysmon_ram SVG FileLog_sysmon:SM_RAM:CURRENT
attr wl_sysmon_ram group RPi
attr wl_sysmon_ram label "RAM-Nutzung Total: $data{max1}, Min: $data{min2}, Max: $data{max2}, Aktuell: $data{currval2}"
attr wl_sysmon_ram room 9.03_Tech

# Visualisierung: Dateisystem: Root-Partition
define wl_sysmon_fs_root SVG FileLog_sysmon:SM_FS_root:CURRENT
attr wl_sysmon_fs_root group RPi
attr wl_sysmon_fs_root label "Root Partition Total: $data{max1}, Min: $data{min2}, Max: $data{max2}, Aktuell: $data{currval2}"
attr wl_sysmon_fs_root room 9.03_Tech

# Visualisierung: Dateisystem: USB-Stick
define wl_sysmon_fs_usb1 SVG FileLog_sysmon:SM_FS_usb1:CURRENT
attr wl_sysmon_fs_usb1 group RPi
attr wl_sysmon_fs_usb1 label "USB1 Total: $data{max1}, Min: $data{min2}, Max: $data{max2}, Aktuell: $data{currval2}"
attr wl_sysmon_fs_usb1 room 9.03_Tech

# Anzeige der Readings zum Einbinden in ein 'Raum'.
define SysValues weblink htmlCode {SYSMON_ShowValuesHTML('sysmon')}
attr SysValues group RPi
attr SysValues room 9.03_Tech

# Anzeige CPU Auslasung
define wl_sysmon_cpustat SVG FileLog_sysmon:SM_CPUStat:CURRENT
attr wl_sysmon_cpustat label "CPU(min/max): user:$data{min1}/$data{max1} nice:$data{min2}/$data{max2} sys:$data{min3}/$data{max3} idle:$data{min4}/$data{max4} io:$data{min5}/$data{max5} irq:$data{min6}/$data{max6} sirq:$data{min7}/$data{max7}"
attr wl_sysmon_cpustat group RPi
attr wl_sysmon_cpustat room 9.99_Test
attr wl_sysmon_cpustat plotsize 840,420
define wl_sysmon_cpustat_s SVG FileLog_sysmon:SM_CPUStatSum:CURRENT
attr wl_sysmon_cpustat_s label "CPU(min/max): user:$data{min1}/$data{max1} nice:$data{min2}/$data{max2} sys:$data{min3}/$data{max3} idle:$data{min4}/$data{max4} io:$data{min5}/$data{max5} irq:$data{min6}/$data{max6} sirq:$data{min7}/$data{max7}"
attr wl_sysmon_cpustat_s group RPi
attr wl_sysmon_cpustat_s room 9.99_Test
attr wl_sysmon_cpustat_s plotsize 840,420
define wl_sysmon_cpustatT SVG FileLog_sysmon:SM_CPUStatTotal:CURRENT
attr wl_sysmon_cpustatT label "CPU-Auslastung"
attr wl_sysmon_cpustatT group RPi
attr wl_sysmon_cpustatT plotsize 840,420

# Anzeige Stromversorgung AC
define wl_sysmon_power_ac SVG FileLog_sysmon:SM_power_ac:CURRENT
attr wl_sysmon_power_ac label "Stromversorgung (ac) Spannung: $data{min1} - $data{max1} V, Strom: $data{min2} - $data{max2} mA"
attr wl_sysmon_power_ac room Technik
attr wl_sysmon_power_ac group system

# Anzeige Stromversorgung Battery
define wl_sysmon_power_bat SVG FileLog_sysmon:SM_power_battery:CURRENT
attr wl_sysmon_power_bat label "Stromversorgung (bat) Spannung: $data{min1} - $data{max1} V, Strom: $data{min2} - $data{max2} mA"
attr wl_sysmon_power_bat room Technik
attr wl_sysmon_power_bat group system

DevelopmentGuidelines

2014-08-12T21:21:35Z

Kamischi:

''Wichtiger Hinweis'': Diese Seite enthält die Ideen der fhem-Entwickler, wie fhem in einer künftigen Version funktionieren soll. Es beschreibt nicht den Zustand der aktuellen Umsetzung in den Release- oder den SVN-Versionen.

==Definitionen==
TODO: Rudis kanonische Begriffe verwenden!

===Allgemeines===
Die Version von fhem, in der diese Guidelines umgesetzt werden sollen, wird mit fhem-NEU bezeichnet. Mit fhem 4.x wird die aktuelle Architektur bezeichnet, die auch für fhem 5.x zutrifft.

===Readings===
Ein Reading (Ablesewert) ist jeglicher Wert, Zustand, etc., der von einem Gerät ausgelesen werden kann. Beispiele dafür sind Messtemperatur, Luftfeuchtigkeit, Schaltzustand (an/aus), Firmwareversion, Empfangsstärke.

=== I/O-Devices und Clients===
Um Readings durch fhem verarbeiten zu können, müssen die Daten erst über ein I/O-Device in den Rechner kommen. Beispiele: FHZ1300, CUL, CM11, M232.

Ein I/O-Device ist über einen Port (Beispiel für Unix: /dev/ttyS0) oder einen Socket ansprechbar.

Ein I/O-Device kann selbst ein Gerät sein, das Readings liefert (Beispiel: SCIVT, sowie die meisten anderen Schnittstellengeräte, wenn man die Geräteversion oder die Uptime mit zu den Readings zählt), oder die Readings von anderen Geräten (Clients) weiterleiten (Beispiel: FHZ1300).

==Requests for Proposal==
===Aktualisierung der Readings===
====Aktive und passive Readings====

Es sind zwei Arten von Readings zu unterscheiden:
# Readings, die vom Gerät aktiv mitgeteilt werden, entweder ad-hoc oder in regelmäßigen Zeitabständen (aktive Readings). Beispiele: measuredTemp bei FHT80B, wind bei KS300
# Readings, nach denen fhem die Geräte fragen muss (passive Readings). Beispiele: energyDay bei EM1010PC, counter bei M232, temperature bei OWTEMP

Dasselbe Gerät kann sowohl aktive als auch passive Readings beinhalten. Bei Geräten mit aktiven Readings sind passive Readings meist Informationen wie Versionsnummer oder Uptime (CUL, CM11).

Geräte, die mehrere verschiedene Readings haben, senden diese häufig im Batch an fhem (Beispiel: FHT80b, KS300).

====Mechanismus für aktive Readings====
''TODO: Mechanismus mit ParseFn, GetFn, Match usw. beschreiben (wie in fhem 4.x)!''

====Mechanismus für passive Readings====
Für passive Geräte gibt es eine Polling-Infrastruktur.

'''Status Quo in fhem 4.x:'''

In der Routine DEVICE_Define wird ein interner Timer gestartet, der die Updatefunktion aufruft. INTERVAL ist die Periode in Sekunden.

sub
DEVICE_Define($$) {
...
InternalTimer(gettimeofday()+$hash->{INTERVAL}, "DEVICE_GetUpdate", $hash, 0);
...
}

In der Routine DEVICE_GetUpdate werden dann die Readings vom Gerät geholt und der Timer wird mit dem gleichen Befehl erneut gestartet.

sub
DEVICE_GetUpdate($$) {
...
# start internal timer; do it at the beginning to achieve equal intervals no matter how long it takes to gather data
InternalTimer(gettimeofday()+$hash->{INTERVAL}, "DEVICE_GetUpdate", $hash, 1);
# gather data
...
}

Der letzte Paramater 0 oder 1 ist waitIfInitNotDone.

Fragen:
* Kann/soll dieses Verfahren in einem Modul gekapselt werden? Geräte melden sich dann an der Polling-Infrastruktur an. Wenn ja, wie?
* Wie wird waitIfInitNotDone korrekt eingesetzt?

====Mechanismus für langsame Readings====
'''Problemstellung:''' Längere Verarbeitungsprozesse in einzelnen Modulen (z.B. aufgrund von Netzwerklatenzen oder toten Geräten) halten fhem komplett an und verhindern die Verarbeitung von Events.

'''Lösung:''' Multiprocessing

Beim Multiprocessing wird der fhem-Prozess geforkt, wenn ein Reading vom Gerät eingelesen werden soll. Der Vaterprozess wird sofort fortgesetzt und erledigt weitere Aufgaben. Der Kindprozess holt die Readings vom Gerät, liefert sie an den Vaterprozess und verendet.

Die Lieferung des Resultats an den Vaterprozess erfolgt durch eine Loopback Verbindung zu fhem via localhost.

Dieser Mechanismus wurde durch Rudolf König in ein entsprechendes Modul verpackt, so dass jedes andere FHEM-Modul diese Möglichkeiten direkt nutzen kann. Eine nähere Erklärung sowie eine Anleitung dazu findet man in dem Artikel → [[Blocking Call]]

'''Fragen''':
* Soll es diesen Mechanismus nur passive Readings geben oder gibt es Anwendungsfälle für aktive Readings?

'''Verworfene Alternative''': Multithreading

Argumente gegen Multithreading:
* Wird praktisch auf keiner kleinen Plattform unterstützt.
* Negative Erfahrungen (z.B. Probleme bei vielen 3rd-party-Komponenten)
* Kaum Programmiererfahrung mit Multithreading in Perl.

==Verabschiedete Richtlinien==
===Zeichensatz===
Alle nach aussen sichtbaren Werte sind in der Zeichenkodierung ASCII (Codes 32..127). Dies vermeidet Konvertierungsprobleme bei der Bearbeitung des Quellcodes, bei der Ausgabe durch Perl, beim Transport in Internet-Protokollen und bei der Darstellung im Frontend/GUI.

===Klassifizierung der Attribute===
Die Attribute eines Moduls werden in logische Klassen (Rubriken) eingeteilt.

====Sinn und Zweck====
Die Rubriken helfen...
* zu sortieren, welche Attribute bei (xml)list gezeigt werden und welche nicht,
* zu definieren, welche Werte per save in die Sicherung kommen und welche nicht,
* zu vereinbaren, welche Änderungen ein notify auslösen und welche nicht,
* zu definieren, wie ein Attribut im $hash->{} abgelegt wird (in $hash->{}, $hash->{READINGS}, $hash->{INTERNALS}, ...),
* zu gliedern, welche Namenskonventionen jeweils für Attribute verwendet werden (Kleinbuchstaben, Großbuchstaben, CamelCaps, ...),
* abzugrenzen, wo der Entwickler sich an Vorgaben halten muss (z.B. bei System Internals) und wo er frei ist, Attribute zu erfinden oder wegzulassen, und
* festzulegen, wo bzgl. der Inhalte Standards notwendig sind und wo nicht (z.B. bei "Logical Readings", wenn diese im GUI angezeigt werden sollten).

====Logische Rubriken====
Die folgenden Rubriken stellen eine sehr feine Einteilung dar:
* System Internals: werden vom Framework (fhem.pl) benötigt/verwendet/erkannt, z.B. NAME, NR, CHANGED
* Device Readings: Rohdaten, die vom physischen Gerät ausgelesen werden (nicht interpretiert), z.B. rain_raw (Wippenschläge des Regensensors) in KS300
* Hilfsvariablen: z.B. rain_raw_adj (rain_raw, jedoch bereinigt um die bei einigen KS300 auftretenden erratischen Sprünge) in KS300, Zwischenergebnisse von Daten/Werten, die zur Mittelwertberechnung benötigt werden
* Logical Readings: ausgewertete Messdaten und Zustände, z.B. Temperatur, Niederschlag (nicht als Wippenschläge sondern in l/qm)
* Derived Readings: aus den Messdaten abgeleitete Werte, z.B. durchschnittliche Temperatur der laufenden Woche, Niederschlagsmenge des Tages
* Physical Device Parameter: z.B. Modell oder Housecode und Unitcode bei X10 oder die Sensornummer beim BS (brightness sensor)
* Logical Device Parameter: statische Werte, die als Grundlage für Berechnungen genutzt werden, z.B. Korrekturfaktoren bei den Energiemessgeräten, die Tankgeometrie beim USF1000
* Messages: alle Nachrichten, die das Gerät betreffen, z.B. "AVG_Month erfolgreich berechnet", "Script XYZ am xx.xx.xx gestartet", LastIODEV, LastRAWMSG
* Trigger: wenn Trigger direkt am Gerät hinterlegt werden, müssen nicht mehr alle Notifies durchsucht werden, sondern es kann das Modul direkt ermitteln, ob ein Notify ausgelöst wird.

====Ablage im Programm====
Programmtechnisch werden die Attribute eines Moduls so in Behältern abgelegt, dass folgende Kriterien erfüllt sind:
* Die Aufteilung ist möglichst einfach/minimalistisch.
* Anhand des Behälters lässt sich entscheiden,
** ob die Werte der darin enthaltenen Attribute über das Programmende hinaus gespeichert oder nicht gespeichert werden,
** welchen Anzeigestandards oder Programmierstandards die darin enthaltenen Attribute entsprechen, und
** ob es sich um fhem-interne Attribute, Readings oder Hilfsvariablen handelt.

Es gibt folgende Behälter:

readings
* Logische Rubrik: Device Reading, Logical Reading, Derived Reading
* Wird gespeichert
* Alle vom Gerät gelieferten bzw. berechneten Werte, die den Endanwender interessieren. Keine Rohdaten vom Gerät, die erst interpretiert werden müssen (Wippenschläge beim Regensensor).
* Alle Daten haben einen Wert und ein Zeitstempel
* Beispiele:
$defs{Lampe}{readings}{switchedTo}{value} = "on"; $defs{Lampe}{readings}{switchedTo}{time} = "2010-03-29 23:32:26"
$defs{FHToben}{readings}{measuredTemp}{value} = "23"; $defs{FHToben}{readings}{switchedTo}{time} = "2010-03-29 21:58:36"

helper
* Logische Rubrik: Hilfsvariable, Device Reading
* Wird nicht gespeichert
* Alle Werte, die für den Endanwender nicht direkt sinnvoll sind aber vom Modul für unterschiedliche Zwecke benötigt werden. Kann auch rohe Readings enthalten.
* Beispiele:

$defs{ks300}{helper}{cumMonth} = "23 T: 131.4 H: 816 W: 775.1 R: -651.1"
$defs{emwz}{helper}{basis} = "4776493"

fhem
* Logische Rubrik: System Internals, Physical Device Parameter, Logical Device Parameter
* Wird nicht gespeichert
* Alle Geräte-Werte, die nicht gespeichert werden müssen, weil entweder berechnet, oder aus der Definition hervorgehen.
* Beispiele

$defs{emwz}{fhem}{def} = "1 75 900"
$defs{emwz}{fhem}{lastIODev} = "CUL"

Verworfener Behälter STATE
* Logische Rubrik: Device Reading, Logical Reading, Derived Reading
* Wird gespeichert
* Kurze(!) Zusammenfassung der wichtigsten Information des Geräts. Was man in einer Übersicht über die Geräte sehen möchte, z.B. eine Warnung oder die aktuelle Temperatur beim FHT80 oder der Zeitpunkt der letzten Aktivierung beim PIRI. Falls es das nicht gibt, dann einheitlich "defined". GGf. über Attribute am Modul steuerbar. Eigentlich ist es kein Behälter im üblichen Sinne, da es keine Untereinheiten hat.

Der Behälter wurde verworfen, weil er redundant ist, an sich gar kein Behälter, und einfacher und flexibler über einen Verweis auf das Reading realisiert werden kann, der per Default angezeigt werden soll.

====Status====
Kurze Zusammenfassung der wichtigsten Information des Geräts. Was man in einer Übersicht über die Geräte sehen möchte, z.B. eine Warnung oder die aktuelle Temperatur beim FHT80 oder der Zeitpunkt der letzten Aktivierung beim PIRI. Falls es sowas nicht gibt, dann einheitlich "defined". Modulseitig gibt es einen Default, der auf das relevante Reading verweist. Dieser ist über das Attribut defaultReading am individuellen Gerät steuerbar.

Beispiel: Definition in der Konfigurationsdatei: attr myDevice defaultReading measuredTemp Verwendung im Code:

$defs{myDevice}{readings}{$attr{defaultReading}}

Die logischen Rubriken Messages und Trigger wurden noch nicht diskutiert.

===Bezeichnungen===
Verwendung von lowerCamelCaps für alle vom Modul nach aussen sichtbaren Bezeichner: a) die Bezeichnungen der Behälter für Readings, Fhem und Helper und der Untereinträge, b) die Bezeichnungen der Readings, c) die Bezeichnungen der Attribute.

Beispiel:

$defs{myFHT}{readings}{measuredTemp}{time}

===Readings===
====Standardisierung der Readings====
Die Readings werden standardisiert, indem Geräteklassen gebildet werden wie in DevelopmentInterfaces beschrieben. Die Definition der Interfaces ist explizit nicht Gegenstand dieser Entscheidungsvorlage und wird weiterentwickelt und angepasst, wie es sich bei der Entwicklung von fhem-NEU ergibt.
Struktur im Code

Zu jedem Reading gibt es die folgenden Unterbehälter:
* value: Wert der Messgröße
* time: Zeitpunkt, zu dem der Wert ermittelt wurde

Beispiel:

$defs{myFHT}{readings}{measuredTemp}{time}= timestamp;
$defs{myFHT}{readings}{measuredTemp}{value}= 23.5;

Readings enthalten grundsätzlich genau einen Wert und diesen ohne Einheit.

====Einheitendarstellung====
Die verwendete Einheit für ein Reading ergibt sich aus der Interfacespezifikation.

Beispiel: Gerät ist ein Thermometer => es gibt ein Reading "temperature" und dessen Einheit ist immer °C oder Celsius

Verworfene Alternative:
* Einheit ergibt sich aus der Dokumentation
* Einheit ergibt sich aus einem expliziten Untereintrag $defs{deviceName}{readings}{theReading}{unit}="°C"
* Einheit ergibt sich aus Festlegung gemäß "FHEM-Standard", z.B. immer SI-Einheiten, Temperaturen in Celsius, etc.

===Zeitdarstellung in fhem===
Zeiten werden im Programm grundsätzlich immer maschinenlesbar abgelegt, also sowohl in $defs{deviceName}{readings}{time} als auch z.B. bei der Speicherung des Zeitpunkts der Ausführung des nächsten at-Kommandos.

Es gibt übergreifende Hilfsfunktionen, die die maschinenlesbare in eine menschenlesbare Darstellung umwandeln.

Argumente für maschinenlesbar:
* vereinfacht Datumsarithmetik, z.B. die Berechnung der Zeitdauer zwischen zwei Ereignissen
* kann vom Frontend in die regionale Darstellung des Anwenders übersetzt werden
* hat keine Probleme mit doppelt auftretenden Zeitpunkten bei der Umstellung von Sommer- auf Winterzeit

Folgende Zeitdarstellungen werden ausschliesslich verwendet:

A. Zahl der Sekunden seit der Unix-Epoche (was time liefert); auch wenn time eine Ganzzahl liefert, muss der Verwender damit rechnen, eine Gleitkommazahl vorzufinden. Das ist z.B. dann der Fall, wenn für die Zeitbestimmung höher auflösende Funktionen (z.B. Time::HiRes) zum Einsatz kamen und Sekundenbruchteile mitgespeichert wurden.

Hinweis zu potentiellen Problemen:
* Ab perl 5.12 ist das Jahr-2038-Problem in Perl beseitigt.
* Ab Mac OS X liefert time auch auf Macs die Zahl der Sekunden seit der Unix-Epoche (statt seit Anfang 1904)

B. ISO8601 mit optionaler Zeitzonenangabe, wobei bei fehlender Zeitzone die lokale Zeitzone des fhem-Servers gilt

Die Zeitdarstellungen werden wie folgt verwendet:
* Zur Programmlaufzeit in Variablen immer A
* In Konfigurationsdateien (fhem.conf, fhem.save) immer B
* In Logs, die für den Menschen bestimmt sind, B
* In Logs, die für die Maschine bestimmt sind, also z.B. bei Weiterverarbeitung in einem GUI, A
* In Listen (list, xmllist friendly), die für den Menschen bestimmt sind, B
* In Listen (xmllist), die für die Maschine bestimmt sind, also z.B. bei Weiterverarbeitung in einem GUI, A

Die Unterscheidung bei den Logs ist noch zu diskutieren.

Hinweise zu gnuplot:

<nowiki>set timefmt '%Y-%m-%dT%H:%M:%S' </nowiki>

(ISO8601) funktioniert, und zwar unabhängig davon, ob die optionale Zeitzonenangabe anhängt oder nicht (getestet mit Gnuplot v4.2 pl3). Für die Sekunden seit der Unix-Epoche:

<nowiki>set timefmt '%s' </nowiki>

(nicht getestet).

==Allgemeine Dokumentation==
===Events, Filter, Notify===
====Event====
Ein Event tritt ein, wenn ein oder mehrere Readings eines Geräts aktualisiert werden, weil z.B. ein Datagramm empfangen oder zeitgesteuert Werte eingelesen wurden. Es wird durch drei Angaben

<nowiki>(device, timestamp, { reading1, ..., readingN } )</nowiki>

beschrieben:
* das Gerät device
* der Zeitpunkt der Aktualisierung timestamp
* die Menge der N>= 1 geaenderten Readings reading1, .. readingN

Wenn N> 1, dann handelt es sich um ein Sammelevent, wie es z.B. von KS300 generiert wird.

====Filter====
Ein Filter filtert Events. Er hat die Form

deviceNamePattern

bzw.

deviceNamePattern:readingNamePattern

Ein Filter passt auf ein Event, wenn deviceNamePattern den Namen des device matcht und, sofern vorhanden, readingNamePattern mindestens irgendeinen Namen von reading1 bis readingN matcht.

====Mechanismus====
0. Für das Gerät device namens deviceName wird ein Datagramm empfangen oder es werden zeitgesteuert Werte eingelesen.

1. Die Readings werden aktualisiert. Für X= 1..N:

$defs{deviceName}{readings}{readingX}{value}= valueX;
$defs{deviceName}{readings}{readingX}{time}= timestamp;

2. Das Event wird erstellt und an DoTrigger übergeben.

3. DoTrigger informiert zunächst alle Clients mit inform-Wunsch.

4. Das Event wird sodann von DoTrigger nacheinander an alle NotifyFn in der alphabetischen Reihenfolge der Gerätenamen gereicht. Darunter auch jene von Logs.

5. Wenn der Filter des Logs auf das Event passt, wird ein Log-Eintrag der Form

timestamp deviceName reading1: value1 reading2: value2 ... readingN: valueN

erzeugt.

==Zurückgestellte Entscheidungen==
===Attribute vs. Internals===
Die Unterscheidung zwischen Attributen und Internals ist nicht eindeutig. Manche define-Parameter sind optional, und man kann define-Parameter mit "modify" ändern. Insofern könnte man theoretisch einen der beiden Verfahren (modify vs. attribute) ablösen.

1. Idee: define-Parameter dürfen nachträglich nicht geändert werden, auch wenn es sich um optionale Parameter handelt => nicht-modifizierbare Internals

Pros:
* define-Parameter sind elementar für den Betrieb des Geräts und können nicht sinnvoll zur Programmlaufzeit geändert werden (z.B. Hauskode bei X10, FHTId bei FHT80b)
* Aus den define-Parametern werden bei der Initialisierung des Geräts weitere Helper und Internals abgeleitet und gespeichert. Eine nachträgliche Änderung zieht Änderungen der Helper und Internals nach sich mit ggf. schwer durchschaubaren Nebeneffekten (z.B. corr1..corr4 bei EM, rainadjustment bei KS300). Auch die Logs ändern sich nicht nachträglich.

Contras:
* Man will nicht ein Gerät löschen und neu anlegen, wenn es ausgetauscht wird.
* modify sollte bleiben, weil es nützlich ist.

2. Idee: Attribute enthalten Werte, die ohne Nebeneffekte zur Laufzeit geändert werden können, weil sie z.B. ad-hoc ausgewertet werden.
* follow-on-for-timer
* retrycount
* lazy

3. Idee: Attribute beinhalten geräteunabhängige Meta-Informationen:
* room
* defaultReading

Contras:
* Nach 2. und 3. müsste

attr my_at disabled

doch zu Definition gehoeren. Und "skip_next" auch.

Spezialitäten
* beim FS20 bleibt alles, wie es ist, also model als Attribut, was Auswirkung auf die möglichen set Befehle hat.
* 1wire setzt nach define das model Attribut, lässt aber eine Änderung nicht zu, oder wenn doch, dann muss sich dementsprechend verhalten, es macht ja evtl. Sinn es zu ändern. Was machbar ist, entscheidet der Modul-Author.

Damit ist "model" immer ein Attribut.

Fazit

Da es keine überzeugende Alternative zum Ist-Zustand in fhem 4.x gibt, wird b.a.w. nicht hierüber entschieden.

===notify===
Die Frage, ob der notify-Mechanismus, der weiter oben dokumentiert ist, aus Performancegründen optimiert werden sollte, ist offen.

In fhem 4.x bekommt jedes Gerät mit NotifyFn jedes Event mit. Alternativ könnte sich ein Gerät als EventListener mit einem Filter bei fhem anmelden. Dann könnten die Events nur an die NotifyFn verteilt werden, für die es ein Match auf den Filter gaebe.

Der Punkt wurde zurückgestellt, bis nachgewiesen ist, dass sich aus dieser Vorgehensweise relevante Auswirkungen auf die Systemlast ergeben.

==Entscheidungen==
;E1
:Es werden die Container fhem, readings und helper verwendet.
;E2
:Es wird ein Attribut defaultReading verwendet.
;E3
:Verwendung von lowerCamelCaps für a) die Bezeichnungen der Behälter für Readings, Fhem und Helper und der Untereintraege, b) die Bezeichnungen der Readings, c) die Bezeichnungen der Attribute.
;E4
:Verwendung von value und time.
;E5
:Zeitdarstellung im Programm grundsätzlich maschinenlesbar
;E6
:Zulässige Zeitdarstellungen
* Sekunden seit der Unix-Epoche
* ISO8601 mit optionaler Zeitzonenangabe
ISO8601 mit _ statt T war nicht mehrheitsfähig.
;E7
:Verwendung der Zeitdarstellungen
;E8
:Readings enthalten grundsätzlich genau einen Wert und diesen ohne Einheit.
;E9
:Einheiten ergeben sich aus der Interfacespezifikation.
;E10
:Entscheidung für ASCII
;E11
:Die Readings werden standardisiert, indem Geräteklassen gebildet werden wie in DevelopmentInterfaces beschrieben. Die Definition der Interfaces ist explizit nicht Gegenstand dieser Entscheidungsvorlage und wird weiterentwickelt und angepasst, wie es sich bei der Entwicklung von fhem-NEU ergibt.

[[Kategorie:Development]]

DevelopmentOpenIssues

2014-08-12T21:16:06Z

Kamischi:

= Open Issues =
== Vor Entwicklungsbeginn von fhem 5.x zu klären ==
<dl><dt>Informationsumfang von xmllist
</dt></dl>
xmllist muss alle Werte mitnehmen, da sonst diese nie angezeigt werden.

xmllist hat auch weitere Daten:

* die Liste aller möglichen set Werte
* die Liste aller möglichen Attribute

Variante: Optionales Argument bei xmllist, das die Detailstufe oder der Informationsumfang eingrenzt.

<dl><dt>Aufbau einer Polling-Infrastruktur für Geräte, die nicht aktiv den Zustand melden
</dt></dl>
Beispiele: EMEM, M232.
Denkbar auch zur Identifikation von toten Geräten (USF1000 muss alle 30 Minuten einen Wert liefern; bleibt der n mal aus, wird eine Warnung erzeugt).

<dl><dt>Multithreading/Parallelisierung
</dt></dl>
Nähe zur Polling-Infrastruktur

<dl><dt>Dokumentation
</dt></dl>
Standardfunktionen:
AttrFn
AttrList
Clients
DefFn
GetFn
ListFn
Match
MatchList
NotifyFn
ParseFn
ReadFn
ReadyFn
SetFn
ShutdownFn
StateFn
UndefFn
WriteFn

<dl><dt>Erstellung eines Template-Moduls
</dt></dl>
Kommentierte Vorlage nn_Modul.pm fuer fhem 5.x.

== Erweiterungen/Verbesserungen ==
<dl><dt> Auslagerung der Funktionen für die Bildung von Mittelwerten über Zeitintervalle in ein eigenes Modul
</dt></dl>
z.B. Niederschlag pro Tag, Woche, Monat
Module: CUL_WS,KS300,CUL_EM

<dl><dt> contrib/dblog/93_DBLog ins FHEM-Verzeichnis aufrücken lassen
</dt></dl>
Kann benutzt werden, um Events in Datenbanken zu loggen.

Todos:

* FileLog-artigen Getter implementieren
* Komplettdump
* Auflistung der gespeicherten Daten
<dl><dt>Logs und Zeitreihen
</dt></dl>
Derzeit erfüllen Logs u.a. zwei grundverschiedene Aufgaben:

* der Benutzer kann sehen, was zu einem bestimmten Zeitpunkt passiert ist
* ein Frontend kann daraus eine Zeitreihe ableiten für eine Grafik

Es sollte geklärt werden, wie mit den daraus entstehenden Anforderungen an die Logs (möglichst gut menschenlesbar vs. möglichst gut maschinenverarbeitbar) optimal erfüllt werden können.

= Martins Liste der Readings, Internals, etc. =
Beispiele:
local, LOCAL
po, PortObj
socket, SOCKET
Type, TYPE

weitere teils unklare Bezeichnungen, die evtl. harmonisiert werden könnten:
DELTAUNIT, NUMUNITS, RAINUNIT, UNIT, UNITS, WINDUNIT
CODE, FamilyCode, HOUSE
INTERVAL, Timer, TRIGGERTIME
NAME, DeviceName
NR, DEVNR

dann sind da die Standardfunktionen bei Initialize, die einfach mal
dokumentiert werden müssten:
AttrFn
AttrList
Clients
DefFn
GetFn
ListFn
Match
MatchList
NotifyFn
ParseFn
ReadFn
ReadyFn
SetFn
ShutdownFn
StateFn
UndefFn
WriteFn

einer weiteren Betrachtung bedarf der Trigger für notify's:
CHANGED
sowie der eigentlichen
READINGS
die aber in einem anderen Kontext behandelt werden sollten.

einige feste Parameter können vorab schonmal gefiltert werden:
DEF
IODev
NAME
NR
STATE
TYPE

je nach IODev können weitere dazu kommen:
CUN868_MSGCNT
CUN868_RAWMSG
CUN868_RSSI
CUN868_TIME
LASTIODev
MSGCNT
RAWMSG
RSSI

bei X10 fiel auf, das in den Internals
MODEL
gesetzt wird, aber explizit noch einmal
model
in den Attributes vorkommen.

bei CUL_WS fiel auf, das die STATE summary sowohl in den Internals als auch in
den Readings auftaucht, obwohl in den Readings einzelne Werte vorhanden sind:
Internals:
STATE T: 16.7 H: 66.7
Readings:
humidity 66.7
state T: 16.7 H: 66.7
temperature 16.7

verbleibende Internals:

ALARM
ATTR
BasicFeePerMonth
BTN
CHANGETIME
Cmd
CONTENT
corr1
corr2
corr3
corr4
CostPerUnit
currentlogfile
DELTAFACTOR
DELTAUNIT
DeviceName
DEVNR
DIAMETER
FACTOR
FamilyCode
FD
FH
FHTID
FIXNEW
FIXRENUMBER
GEOMETRY
HEIGHT
Host
HOUSE
ID
IDX
INATTR
INPUT
INSET
INTERVAL
INTV_ALARM
INTV_CHECK
LENGTH
LINK
LircObj
local
LOCAL
LOCATION
logfile
MAX
MOBILE
MODEL
NEXT_OPEN
NR_CMD_LAST_H
NR_EMSG
NR_FMSG
NR_KMSG
NR_RMSG
NR_TMSG
NTM
NUMUNITS
OFFSET
OLDDEF
OW_FAMILY
OWFS_ID
OW_ID
OW_PATH
OW_SCALE
PARTIAL
pipeopentime
po
PortObj
pos
PRESENT
PREV
QUEUE
RAINUNIT
RA_Timeout
RE
REGEXP
REP
RExt
ROUTERID
SelectObj
SENSOR
SERIAL
SERIALS
socket
SOCKET
STEP
TCPDev
Timer
TRIGGERTIME
ttytype
Type
UNIT
UNITS
USBDev
VERSION
VOLATILE
WIDTH
WINDUNIT
XMIT
XMIT_TIME

==  ;; und %% ==
Das Problem ist, dass sowohl

<nowiki>define lampoff at 07:00 set Lamp1 off;; set Lamp2 off</nowiki>
als auch später (um 07:00)

<nowiki>set Lamp1 off; set Lamp2 off</nowiki>
vom gleichen AnalyzeCommandChain verarbeitet werden.

Diese erkennt an dem ;;, dass die erste Zeile nicht zu trennen ist, die zweite
aber schon. In der ersten Zeile wird dann auch ;; nach ; gewandelt, und intern
speichert das "at" nur noch "set Lamp1 off; set Lamp2 off". Bevor
AnalyzeCommand den Befehl ausführt, müssen perl- und shellskripte wieder ein

<dl><dt><dl><dt> bekommen, um nicht von AnalyzeCommand an falscher Stelle zersägt zu werden.
</dt></dl>
</dd></dl>
Die "richtige" Lösung wäre so etwas wie

<nowiki>define lampoff at 07:00 [ set Lamp1 off; set Lamp2 off ]</nowiki>
erfordert aber einen Parser, der den passenden Klammer-zu findet, und das ist
aufwendig.

Uns gefällt @, %, %EVTPART1, usw. immer weniger, wir
finden "magische" Variablen wie $DEVICE, $EVENT, $EVTPART1, usw.
logischer - sie würden keinen Stress mit @@/%% verursachen. Wir wissen nicht, wie man einen schmerzlosen
Übergang durchführt, insb. mit den vielen fhemwiki-Beispielen.

[[Kategorie:Development]]

Callmonitor mit Anruferliste und Zusatzfunktionen

2014-08-12T21:11:01Z

Kamischi:

Die Beschreibung [[Callmonitor mit Anruferliste und Zusatzfunktionen]] basiert hauptsächlich auf dem Beitrag [http://forum.fhem.de/index.php/topic,19238.0.html Callmonitor für Anfänger] im Fhem Forum.
{{Randnotiz|RNTyp=y|RNText=Größtes Problem bei der Implementierung scheint zu sein, dass die Bezeichnung des Callmonitors (im Forenthread) nicht einheitlich durchgehalten wird. Im hier vorgestellten Code heißt er ''my_callmonitor''. Das muss sowohl in der Konfiguration als auch in der 99_myUtilsTelefon.pm konsistent durchgehalten werden}}
Der hier gezeigte Beispielcode ist einem [http://forum.fhem.de/index.php/topic,19238.msg163260.html#msg163260 Beitrag] in oben genannter Diskussion entnommen. Er umfasst alle Bestandteile zum Anzeigen einer rollierenden Anruferliste.

Die Zusatzfunktionen (z.B. Floorplan- Seitenwechsel mit Anzeige des Anrufers und dessen gleichzeitiger Ansage über TTS) sind auskommentiert. Sie können als Anregung verstanden werden.

== Aufgabenstellung ==
Wie die Anruferliste erstellt wird und wie die Voraussetzungen für auszulösende Aktionen eingebunden werden, wird im Abschnitt [[Callmonitor mit Anruferliste und Zusatzfunktionen#Lösung|Lösung]] schrittweise erklärt. Die Anforderungen an die Anruferliste und auszulösende Aktionen werden folgend kurz dargestellt.

=== Anforderungen an die Anruferliste ===
* Liste mit der Möglichkeit die letzten fünf über die Fritz!Box angenommenen und getätigten Anrufe darzustellen
* die Liste soll den letzen Anruf in der ersten Zeile anzeigen
* der Status des Anrufes ist über ein Symbol ersichtlich
* Name und Nummer des Angerufenen / Anrufenden sind ersichtlich

=== Anforderungen an die Möglichkeit Aktionen auszulösen ===
* Aktionen können in Abhängigkeit von Status des Anrufes ausgeführt werden
* Aktionen können auch gekapselt werden

=== Durchzuführende Schritte ===
Die Reihenfolge ist hier unerheblich. Die Liste soll lediglich einen groben Überblick über die einzelnen erforderlichen Schritte geben
* 99_myUtilsTelefon.pm erstellen (bitte zuerst durchführen)
* UserReadings im Callmonitor in FHEM einrichten
* [[ReadingsGroup]] erstellen, die die UserReadings anzeigt
* Notify erstellen, das die Telefonaktionen aufruft
* in Abhängigkeit vom Anrufstatus auszulösende Aktionen einbinden

== Voraussetzungen ==
=== Aktivierter Callmonitor in der Fritz!Box ===
Damit das Modul Callmonitor in FHEM überhaupt arbeitet, muss zuerst in der Fritz!Box der Callmonitor eingeschaltet werden. Das geht am einfachsten, indem man von einem direkt an die Fritz!Box angeschlossenen Telefon die Nummer #96*5* wählt.

=== Modul FB_CALLMONITOR in FHEM ===
Fhem-seitig sind die erforderlichen Funktionen im Modul [[FB_CALLMONITOR]] implementiert.

=== Anlegen einer Datei 99_myUtilsTelefon.pm ===
Die Datei 99_myUtilsTelefon.pm wird den Perlcode aufnehmen, der die Anruferliste sowie die damit verknüpften Aktionen ausführt. Das Prinzip, um die 99_myUtilsTelefon.pm zu erstellen, ist exakt das Gleiche wie für "[[99 myUtils anlegen]]" beschrieben. In unserem konkreten Fall soll die Datei allerdings den Namen 99_myUtilsTelefon.pm erhalten.

Bitte diesen Schritt nun ausführen, damit später das Script nur noch in die 99_myUtilsTelefon.pm kopiert werden muss.

Natürlich muss auch die 99_myUtilsTelefon.pm nach jeder Anpassung an eigene Bedürfnisse neu geladen werden.

== Lösung ==
In die [[Konfiguration]] (fhem.cfg) ist einzutragen:
<nowiki>
# Logfile der Anrufe (Fritzbox)
define FileLog_my_callmonitor FileLog /opt/fhem/log/my_callmonitor-%Y.log my_callmonitor
attr FileLog_my_callmonitor logtype text
attr FileLog_my_callmonitor room 4_Logdaten

# Callmonitor mit rollierender Anruferliste:
define my_callmonitor FB_CALLMONITOR 192.168.1.1:1012
attr my_callmonitor group Connections
attr my_callmonitor icon phone_call
attr my_callmonitor local-area-code 030
attr my_callmonitor reverse-search all
attr my_callmonitor reverse-search-cache-file /opt/fhem/callmoncache.txt
attr my_callmonitor reverse-search-phonebook-file /opt/fhem/fb_phonebook.xml
attr my_callmonitor room 5_System
attr my_callmonitor userReadings eing0 eing1 eing2 eing3 eing4 A0 A1 A2 A3 A4 B0 B1 B2 B3 B4 C0 C1 C2 C3 C4 D0 D1 D2 D3 D4 E0 E1 E2 E3 E4
attr my_callmonitor verbose 0
#attr my_callmonitor reverse-search-cache 1
#attr my_callmonitor reverse-search internal|klicktel.de|dasoertliche.de

# Anrufer Anzeigen:
#########################

# Dummy zur Anzeige des Namen:
define Dum_TelMon_ShowNa_D dummy
#attr Dum_TelMon_ShowNa_D fp_9_Telefon 23,209,0,Eingehender Anruf von:
attr Dum_TelMon_ShowNa_D group Programm
attr Dum_TelMon_ShowNa_D room 5_System

# Dummy zur Anzeige der Nummer:
define Dum_TelMon_ShowNu_D dummy
#attr Dum_TelMon_ShowNu_D fp_9_Telefon 165,278,0,Telefonnummer:
attr Dum_TelMon_ShowNu_D group Programm
attr Dum_TelMon_ShowNu_D room 5_System

# Wenn Telefon klingelt, wechsle zum FP "Telefon",zeige und sage Anrufer an:
#define Func_TelMon_Show_N notify my_callmonitor:event:.ring { \
#my $intum = ReadingsVal("my_callmonitor", "internal_number", undef);;\
#my $extnum = ReadingsVal("my_callmonitor", "external_number", undef);;\
#my $extname = ReadingsVal("my_callmonitor", "external_name", undef);;\
#\
#fhem "set Dum_TelMon_ShowNa_D $extname";;\
#fhem "set Dum_TelMon_ShowNu_D $extnum";;\
#fhem("set Dum_pageswap_D /fhem/floorplan/9_Telefon");;\
#\
# if ($extname eq "unknown"){\
# fhem("define Melde_Anrufer_A at +00:00:01 set TTS tts Rufnummer unterdrückt");;\
# }\
# else {\
# fhem("define Melde_Anrufer_A at +00:00:01 set TTS tts $extname.");;\
# }\
#}
#attr Func_TelMon_Show_N group Programm
#attr Func_TelMon_Show_N room 5_System

# Wenn Telefon aufgelegt, wechsle zum Haupt-FP:
#define Func_TelMon_Back_N notify my_callmonitor:event:.disconnect { \
#fhem("set Dum_pageswap_D /fhem/floorplan/0_Hauptbildschirm");;\
#}
#attr Func_TelMon_Back_N group Programm
#attr Func_TelMon_Back_N room 5_System

# Anrufliste generieren:
#########################

# Telefonevents für Anrufliste abfangen:
define Func_TelMon_N notify my_callmonitor:.* { \
TelefonMonitor ($EVENT);; \
}
attr Func_TelMon_N group Programm
attr Func_TelMon_N room 5_System

# Anzeige der Anrufliste generieren:
define Anrufliste readingsGroup my_callmonitor:A0,B0,C0,D0,E0 my_callmonitor:A1,B1,C1,D1,E1 my_callmonitor:A2,B2,C2,D2,E2 my_callmonitor:A3,B3,C3,D3,E3 my_callmonitor:A4,B4,C4,D4,E4
#attr Anrufliste fp_9_Telefon 370,206,0,Anrufliste
attr Anrufliste mapping &nbsp
attr Anrufliste nameStyle style="font-weight:bold"
attr Anrufliste noheading 0
attr Anrufliste nolinks 1
attr Anrufliste nostate 1
attr Anrufliste notime 1
attr Anrufliste room 0_Überblick
attr Anrufliste style style="font-size:20px"
attr Anrufliste valueIcon {'A0.out_connected' => 'phone_call_out@lightgreen', 'A0.out_notconnected' => 'phone_call_out@red','A0.in_connected' => 'phone_call_in@lightgreen','A0.in_notconnected' => 'phone_call_in@red', 'A0.AB' => 'audio_volume_mid@lightgreen', 'A1.out_connected' => 'phone_call_out@lightgreen', 'A1.out_notconnected' => 'phone_call_out@red','A1.in_connected' => 'phone_call_in@lightgreen','A1.in_notconnected' => 'phone_call_in@red', 'A1.AB' => 'audio_volume_mid@lightgreen','A2.out_connected' => 'phone_call_out@lightgreen', 'A2.out_notconnected' => 'phone_call_out@red','A2.in_connected' => 'phone_call_in@lightgreen','A2.in_notconnected' => 'phone_call_in@red', 'A2.AB' => 'audio_volume_mid@lightgreen','A3.out_connected' => 'phone_call_out@lightgreen', 'A3.out_notconnected' => 'phone_call_out@red','A3.in_connected' => 'phone_call_in@lightgreen','A3.in_notconnected' => 'phone_call_in@red', 'A3.AB' => 'audio_volume_mid@lightgreen','A4.out_connected' => 'phone_call_out@lightgreen', 'A4.out_notconnected' => 'phone_call_out@red','A4.in_connected' => 'phone_call_in@lightgreen','A4.in_notconnected' => 'phone_call_in@red', 'A4.AB' => 'audio_volume_mid@lightgreen'}

</nowiki>

In die 99_myUtilsTelefon.pm :
<nowiki>
#################################################
# $Id: 99_myUtilsTelefon.pm 1932 2012-10-06 20:15:33Z ulimaass $
package main;

use strict;
use warnings;
use POSIX;
use FritzBoxUtils;

# fuer Telefonanrufe
our @A;
our @B;
our @C;
our @D;
our @E;
our %TelefonAktionsListe;

sub myUtilsTelefon_Initialize($$) {
my ($hash) = @_;

#...

}
################################################################

sub SendSMS ($$) {
my $adress = $_[0] . '@sms.kundenserver.de';
my $body = $_[1];
Log( 3, "SendSMS: $adress - $body" );
FB_mail( $adress, "", $body );

# end sub SendSMS
}
#####################################
# Anruffunktionen ueber Fritzbox

sub FBCall ($$) {

my $callnr = $_[0];
my $duration = $_[1];

Log( 3, "FBCall: $callnr mit Dauer $duration" );

$callnr = "ATDT" . $callnr . "#";
my $ret = "ATD: " . `echo $callnr | nc 127.0.0.1 1011`;
InternalTimer( gettimeofday() + $duration, "FBHangOn", "", 0 );
return;
}

sub FBHangOn () {
Log( 3, "FBHangOn aufgerufen" );

my $ret = " ATH: " . `echo "ATH" | nc 127.0.0.1 1011`;
$ret =~ s,[\r\n]*,,g;
return;
}

######################################

sub TelefonAktion($$) {

# es wird der Name und die interne angerufene Nummer uebergeben

my ($caller) = split( '\(', $_[0] );
$caller = ltrim( rtrim($caller) );

my $intern = $_[1];

# Log(3,"TelefonAktion: $caller $intern");
# Sound ausgeben

my $com = $main::TelefonAktionsListe{$caller};

if ($com) {
Log( 3, "TelefonAktion: commando: $com" );
sig2_repeat( $com, 5, 4 );
} # falls commando vorhanden

} # end sub TelefonAktion

######################################

sub TelefonMonitor($) {
our $extnum;
our $intnum;
our $extname;
our $callID;
our $callDuration;
# Anrufdauer als Integervariable speichern
our $intCallDuration;
our $stat;
our @lastPhoneEvent;
my $i;
my $j;
our $ab;
my $my_callmonitor = $defs{"my_callmonitor"};

my ( $event, $arg ) = split( ':', $_[0] );
$arg = ltrim($arg);

# Log(3,"TM: event: $event arg: $arg");
if ( $event eq "event" ) {
$stat = $arg;
return;
} # end if event

if ( $stat eq "ring" ) {
if ( $event eq "external_number" ) {
$extnum = $arg;
return;
} # if external number

if ( $event eq "external_name" ) {
$extname = $arg;
return;
}
if ( $event eq "internal_number" ) {
$intnum = $arg;
return;
} # end if intnum

if ( $event eq "call_id" ) {
$callID = $arg;

$lastPhoneEvent[$callID] = $stat;

# hier koennen wir eine anrufgesteuerte Aktion starten
TelefonAktion( $extname, $intnum );

$B[$callID] = EventZeit();
$C[$callID] = $extname;
$D[$callID] = $extnum;
return;
} # end if callid
return;
} # end if ring loop

if ( $stat eq "connect" ) {
if ( ( $event eq "internal_connection" ) && ( $arg =~ m/Answering_Machine_.*/ ) )
{
$ab = "AB";
} # end if internal_connection
} # end if connect

if ( $stat eq "call" ) {
if ( $event eq "external_number" ) {
$extnum = $arg;
return;
} # if external number

if ( $event eq "external_name" ) {
$extname = $arg;
return;
}
if ( $event eq "call_id" ) {
$callID = $arg;

$B[$callID] = EventZeit();
$C[$callID] = $extname;
$D[$callID] = $extnum;

$lastPhoneEvent[$callID] = $stat;
return;
} # end if callid
return;
} # end if callloop

if ( $stat eq "disconnect" ) {

if ( $event eq "call_duration" ) {
$intCallDuration = $arg;
$callDuration = sprintf( "%2d:%02d", ( $arg / 60 ), $arg % 60 );
return;
} # if call_duration

if ( $lastPhoneEvent[$callID] eq "call" ) {
if ( $intCallDuration eq 0 ) {
$A[$callID] = "out_notconnected";
# hier notieren was passieren soll, wenn es ein eingehender Anruf war,
# der nicht angenommen wurde
} elsif ( $intCallDuration gt 0 ) {
$A[$callID] = "out_connected";
# hier notieren was passieren soll, wenn es ein eingehender Anruf war,
# der angenommen wurde
}
} elsif ( $lastPhoneEvent[$callID] eq "ring") {
if ( $intCallDuration eq 0 ) {
$A[$callID] = "in_notconnected";
# hier notieren was passieren soll, wenn es ein ausgehender Anruf war,
# der nicht angenommen wurde

$intCallDuration = undef;
} elsif ( $ab eq "AB" ) {
$A[$callID] = "AB";
$ab = undef;
# hier notieren was passieren soll, wenn der AB dranging

$intCallDuration = undef;
} elsif ($intCallDuration gt 0 ){
$A[$callID] = "in_connected";
# hier notieren was passieren soll, wenn es ein ausgehender Anruf war,
# der angenommen wurde

$intCallDuration = undef;
}
}

# hier notieren was generell passieren soll, sobald ein Anruf beendet wurde
# (egal ob angenommen, nicht angenommen, aus- oder eingehend oder der AB dranging)

if ( $event eq "call_id" ) {
$callID = $arg;

# shiften der alten Inhalte
my $tt;
readingsBeginUpdate($my_callmonitor);

for ( $i = 4 ; $i > 0 ; $i-- ) {
foreach $j ( 'A' .. 'E' ) {

# $defs{"my_callmonitor"}{READINGS}{$j.($i-1)}{VAL};

$tt = ReadingsVal( "my_callmonitor", $j . ( $i - 1 ), "-" );
readingsBulkUpdate( $my_callmonitor, $j . $i, $tt );
} # end j
} # end i
$E[$callID] = $callDuration;
readingsBulkUpdate( $my_callmonitor, "A0", $A[$callID] );
readingsBulkUpdate( $my_callmonitor, "B0", $B[$callID] );
readingsBulkUpdate( $my_callmonitor, "C0", $C[$callID] );
readingsBulkUpdate( $my_callmonitor, "D0", $D[$callID] );
readingsBulkUpdate( $my_callmonitor, "E0", $E[$callID] );

readingsEndUpdate( $my_callmonitor, 1 );
$stat = "";

return;
} # end if callid

} # end if disconnect

##############################
} #end sub TelefonMonitor

sub EventZeit() {
my ( $sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst ) =
localtime( time() );
return sprintf(
"%2d:%02d:%02d %2d.%02d.%4d",
$hour, $min, $sec, $mday,
( $mon + 1 ),
( $year + 1900 )
);
} # end sub EventZeit
###################

1;
</nowiki>

== Verwendung ==
...

== Beschreibung der Funktion ==
...

[[Kategorie:HOWTOS]]

Tecalor THZ Wärmepumpe

2014-08-12T21:08:57Z

Kamischi:

Englisch version [[Tecalor THZ Heatpump]]

Hier wird beschrieben wie man mit FHEM eine Tecalor THZ / Stieben Eltron LWZ 303/403/404
/SOL Wärmepumpe auslesen steuern kann.

Zum besseren Verständnis: Tecalor ist die Privatkundenmarke von Stieben Eltron. Die Geräte sind absolut baugleich.

Nachfolgend wird von der "THZ" gesprochen.

Getestet sind die Versionen 4.09, 4.19, 4.39 und 5.39.
Ältere Versionen können funktionieren, das ist jedoch nicht garantiert.
HINWEIS: Diese Anleitung ist für Personen gedacht, die sich mit Elektronik auskennen.
Der Autor und der Entwickler haften nicht für Schäden und geben keine Funktionsgarantie.

'''ACHTUNG! Seit Version 0.087 wurden die Parameternamen geändert!''' 
Dies dient der Vereinheitlichung der Parameternamen. Werte mit "s" sind Statuswerte, solche mit "p" sind Parameter die in der Heizung eingestellt sind.
Weitere Infos bei den ausgelesenen Parametern. Nach einem Updaten müssen ggf. Sachen wie readingsGroups, Dashboards, etc. angepasst werden.

=Verbindungsmöglichkeiten=
==Lokal per RS232 oder USB==
Die THZ hat zwei Anschlüsse die zur Verbindung genutzt werden können.
* Einen Seriellen Anschluss der mit einem MNL-SG3 Stecker genutzt werden kann.
* Einen USB Anschluss der auf der Platine zu finden ist un mit einem TYP-B Kabel funktioniert.
'''ACHTUNG! Der USB Anschluss befindet sich rückseitig auf der Platine die sich hinter der Abdeckung hinter der rechten Türe. Darf nur stromlos verbunden werden. Dazu die Wärmepumpe komplett vom Strom trennen!!!'''

Die Baudraten variieren je nach Hardware- und Softwareversion zwischen 9600 und 115200 bei Seriell. Bei USB liegt diese bei 115200 oder 57600.
Eine Verbindungsanleitung zum Seriellen Port findet sich hier: [http://robert.penz.name/heat-pump-lwz/ Robert Penz Homepage]

==Entfernte Verbindung mit Ser2Net==
Wenn die FHEM Zentrale nicht direkt in der Nähe der Heizung steht kann mir Ser2Net gearbeitet werden. Dieses stellt auf einem TCP-Port einen virtuellen seriellen Anschluss zur Verfügung.

===Installation Ser2Net auf Linux===
Um den Serial-Port-Server Ser2Net zu installieren ist auf Linux folgendes zu tun:
:<code>sudo apt-get install ser2net</code>
in der /etc/ser2net.conf (/dev/ttyXXX)
:<code>2003:raw:500:/dev/ttyUSB0:115200 NONE 1STOPBIT 8DATABITS </code>
Der Port kann frei gewählt werden, solange er nicht bereits genutzt wird.

==Getestete Host-Systeme==
Getestet ist dieses Modul auf FritzBox, nas-qnap, Raspberry Pi und MacOS.

=Definition in FHEM=
==Mit direkter serieller oder USB Verbindung==
:<code>define Mythz THZ /dev/ttyUSB0@115200 # oder (/dev/ttyXXX)</code>
:<code>attr Mythz interval_sGlobal 300 # Internes Polling Intervall 5min</code>
:<code>attr Mythz interval_sHistory 28800 # Internes Polling Intervall 8h</code>
:<code>attr Mythz interval_sLast10errors 120 # Internes Polling Fehlerspeicher</code>
:<code>define FileLog_Mythz FileLog ./log/Mythz-%Y.log Mythz</code>

Wenn die Attribute interval_sGlobal und interval_sHistory nicht definiert sind (oder 0), ist das interne Polling deaktiviert. Natürlich kann das Polling auch mit dem "at" Befehl ausserhalb des Moduls definiert werden.

:<code>define Mythz THZ /dev/ttyUSB0@115200 # oder (/dev/ttyXXX)</code>
:<code>define atMythzGlobal at +*00:05:00 {fhem "get Mythz sGlobal","1";;return()}</code>
:<code>define atMythzHistory at +*08:00:00 {fhem "get Mythz sHistory","1";;return()}</code>
:<code>define FileLog_Mythz FileLog ./log/Mythz-%Y.log Mythz </code>

==Via Netzwerk mit Ser2Net==
:<code>define Mythz THZ 192.168.0.244:2003</code>
:<code>attr Mythz interval_sGlobal 300 # Internes Polling Intervall 5min</code>
:<code>attr Mythz interval_sHistory 28800 # Internes Polling Intervall 8h</code>
:<code>attr Mythz interval_sLast10errors 120 # Internes Polling Fehlerspeicher</code>
:<code>define FileLog_Mythz FileLog ./log/Mythz-%Y.log Mythz</code>

=Ausgelesene Werte=
Wenn die Verbindung und das Auslesen erfolgreich waren, sollten Werte wie sGlobal, sFirmware, sHistory und diverse Einstellungen wie die Urlaubszeiten sowie einige PXX Werte angezeigt werden.

'''sGlobal (vormals allFB)'''

Beinhaltet alle aktuellen Werte wie Temperaturen von Wasser und Gas, Lüfterstatus, Drücke, usw.

'''sFirmware'''

Zeigt die Firmware Version der Wärmepumpe.

'''sHistory'''

Enthält Angaben zur Betriebsdauer. Beispielsweise die Anzahl der Betriebsstunden der Kompressoren.

'''pHoliday-Werte'''

Hier werden die aktuellen Einstellungen der Urlaubsfunktion der THZ angezeigt. Diese bewirken, dass keine Tagabsenkung (sofern programmiert) gemacht wird.
Die holiday-Werte können mittels <code>set</code> auch angepasst werden.

'''sLast10errors'''

Liest die letzten 10 Fehlercodes aus und stellt diese dar.

'''pXX-Werte & program-Werte'''

Die pXX-Werte und program-Werte stellen Einstellungen wie Heizkreistemperaturen und Lüfterstufen sowie Heizungs- und Warmwasserprogramme der THZ dar. Alle pXX-Werte und program-Werte können mittels <code>set</code> auch angepasst werden.
Es sind auch Lüfterdurchsatzmengen und Passivkühlung konfigurierbar. 
pOpMode zeigt den Betriebszustand. Automatik, Handbetrieb, etc...

'''party-time'''

Hier wird die Uhrzeit der Party programmiert.
Party-Time regelt die Lüfterstufe (p99FanStageParty) im Party-Modus. Diese kann auch angepasst werden.

'''sDHW (ex Status_DHW_F3)'''

Informationen zur Warmwasserbereitung

'''sHC1 (ex Status_HC1_F4)'''

Enthält Informationen zum Heizkreis 1

'''sHC2 (ex Status_HC2_F5)'''

Heizkreis 2 Informationen

'''sSol (ex Status_Sol_16)'''

Informationen zur Solaranlage

'''pOpMode (ex OperatingMode)'''

Betriebsart: Bereitschaft, Automatik, Tagbetrieb, Absenkbetrieb, WW-Betrieb, Manueller Betrieb, Notbetrieb

Wenn die Betriebsart via FHEM geändert werden soll dann muss als set-Wert die entsprechende englische Bezeichnung gesendet werden (Standby, Automatic, DAYmode, SetBack, DHWmode, Manual, Emergency)

'''sXXX'''

Es gibt noch einige weitere "s"tatus Werte die unter anderen die Wärmerückgewinnungswerte beinhalten.

= Plots - Grafische Darstellung =
Nachfolgend wird gezeigt wie man aus den Readings wie sGlobal grafische Plots erstellen kann.

'''Beispiel'''

Angenommen wir wollen aus sGlobal die outside_temp und die dhw_temp (dhw=domestic hot water = Warmwasser) grafisch darstellen:

In der fhem.cfg legen wir das Plot an:
:<code>define Plot_Temp SVG FileLog_Mythz:thz:CURRENT</code>
:<code>attr Plot_Temp room Heizung</code>

Daraufhin wird das Plot erzeugt, noch ohne Daten und evtl. mit einer Fehlermeldung.
Hier klicken wir dann auf den Plot-Namen um in das Plot-Konfigurationsfenster zu kommen.
Hier tragen wir die entsprechenden Daten ein.

'''Wichtig sind nun die Input-Felder'''

Unterhalb der Eingabemaske befinden sich die zu Mythz gehörenden Readings die verwendet werden können. Darunter auch sGlobal.

Das sGlobal wird in etwa so aussehen:
:<code>2014-03-02_13:07:49 Mythz sGlobal: outside_temp: 3.8 flow_temp: 26.5 return_temp: 27.2 hot_gas_temp: 32.1 dhw_temp: 43.4 flow_temp_HC2: -60 evaporator_temp: 5.3 condenser_temp: 27.4 Mixer_open: 0 Mixer_closed: 0 HeatPipeValve: 0 DiverterValve: 0 DHW_Pump: 0</code>

[[File:Thzplot.jpg|thumb]]

Um den richtigen Input zu finden, zählen wir die durch Leerzeichen getrennten Daten ab. Somit ist der Wert der outside_temp an Stelle 5, die dhw_temp an Stelle 13.
Diese Zahl tragen wir dann im Input-Feld ein und schon haben wir einen Plot der Daten erzeugt.

Weitere Infos zu [http://www.fhemwiki.de/wiki/Plots_erzeugen Plots]

= einzelne Werte aus den Readings=
Um einzelne Werte aus den großen Readings wie sGlobal oder history zu bekommen, kann man ein

userReading verwenden.
Beispiel:

:<code>attr Mythz userReadings AussenTemp {(split ' ',ReadingsVal("Mythz","sGlobal",0))[1]},

VorlaufTemp {(split ' ',ReadingsVal("Mythz","sGlobal",0))[3]}</code>

Weitere Infos zu userReadings in der [http://fhem.de/commandref_DE.html CommandRef]

= Hinweise =
* Ein kompletter Refresh aller Werte wird nur beim Systemstart von FHEM gemacht. Dies geschieht sehr langsam um die Performance nicht zu beeinträchtigen. Erst nachdem dieser Refresh (dauert ca. 3-4 Minuten) gelaufen ist, wird das interne Polling gestartet.
*Wenn das Refresh Intervall kürzer oder gleich ist wie der initiale Refresh kann es zu einer Überschneidung kommen was allerdings kein Problem sein sollte.
*Im Wintermodus kommt roomSetTemp (sHC1) von p01RoomTempDayHC1 und p02RoomTempNightHC1
*Im Sommermodus kommt roomSetTemp (sHC1) von p01RoomTempDayHC1SummerMode und p02RoomTempNightHC1SummerMode

= Bekannte Probleme =
Im FHEM Log tauchen bei Ser2Net Verbindung häufig folgende Meldungen auf:
:<code>2014.03.02 09:41:09 1: 192.168.178.50:2003 disconnected, waiting to reappear
2014.03.02 09:41:09 1: 192.168.178.50:2003 reappeared (Mythz)</code>
Dieses Problem ist aktuell nicht gelöst.

= Release History =
'''v0.067'''

Erstmalige Implementierung in FHEM

'''v0.068'''

neuer Befehl f. Party implementiert

'''v0.069'''

Deutsche CommandRef hinzugefügt

'''v0.070'''

BugFix in Status Bits

'''v0.071'''

Bugfix, undefFn verbessert

'''v0.072'''

* Alle programHC1*, programHC2*, programFan* und programDHW* sind nun mit "get" und "set" implementiert
* inside_temp wurde am Ende von allFB hinzugefügt
* der Ser2Net connect/disconnet Bug wurde eingedämmt auf max 1 Logeintrag pro Sekunde

'''v0.074'''

Jetzt sind auch die Lüfterdurchsatzmengen und die Passivkühlung ausgelesen und änderbar.

'''v0.075'''

interval_last10errors implementiert. Intervall, in dem der Fehlerspeicher ausgelesen werden soll

'''v0.076'''

Bugfixes und neuer Parameter Status_HC1_F4

'''v0.078'''

neue Parameter Status_Sol_16 und Status_DHW_F3

'''v0.080'''

* neue Parameter p49SummerModeTemp und p50SummerModeHysteresis
* Status_HC1_F4 und Status_HC2_F5 zeigen nun "mode: Summer" (oder Winter)
Die Berechnung des Modus ist wie folgt:
:<code> if outsidetemp > p49SummerModeTemp + p50SummerModeHysteresis ---> Summermode</code>
:<code> if outsidetemp < p49SummerModeTemp - p50SummerModeHysteresis ---> Wintermode</code>

'''v0.081'''

BugFix für Sommer/Wintermodus-Anzeige

'''v0.084'''

* OperatingMode wird nun ausgelesen (read-only)
* p33BoosterTimeoutDHW (read/write)
* p79BoosterTimeoutHC (read/write)

'''v0.085'''

OperatingMode kann jetzt auch geaendert werden.

'''v0.087'''

* Neue Readings
* Angepasste Readingnamen

'''v0.089'''

* Kommunikation wurde stabilisiert
* Bugfixes
* Neue Readings

'''v0.091'''

Neue Readings: sHeatRecoveredDay & sHeatRecoveredTotal

'''v0.094'''

Bugfixes

'''v0.095'''

Neue Readings: sHeatDHWDay & sHeatDHWTotal

'''v0.096'''

Weitere neue Readings: sEletrx... & sHeat...

'''v0.097'''

Bugfixes

'''v0.099'''

Raumeinfluss wurde in die Heizkurvengrafik eingebaut

'''v0.100'''

Neue Parameter: p54MinPumpCycles, p55MaxPumpCycles, p56OutTempMaxPumpCycles, p57OutTempMinPumpCycles

'''v0.101'''

* keine neuen Features
* Code clean up
* Logs in verbose 5 implementiert
* buffer overflow (Verursacht von sGlobal bei LWZ 303 Firmware 3.19) gefixt

'''v0.103'''

* Änderung der Kommunikation. Jetzt 10x schneller
* Versionsinformation hinzugefügt

'''v0.104'''

Delay in der Kommunikation hinzugefügt (aber immer noch 5x schneller)

'''v0.105'''

* Schnelleres set und get Verhalten
* Dauer des Update beim Start halbiert
* THZ Attribute können ohne Neustart geändert werden
* BugFix
* P83 hinzugefügt (DHWSetSolarTemp)
* Suffix bei den Temp-Werten hinzugefügt. z.B. p04DHWsetDay jetzt p04DHWsetDayTemp

'''v0.107'''

* p56 and p57 getauscht und repariert

'''v0.108'''

* Party-Time wurde entfernt da nicht funktionsfähig
* Grouping bei "set programFan_Mo-Fr_0 to 08:00--20:00" --> Einzelne Tage werden automatisch gesetzt

'''v0.109'''

* Fehlerbehebung bei langen Nachrichten via Seriellem Kabel

= Beispielkonfiguration =

'''Start Definition mit Ser2Net'''

<code>
define Mythz THZ 192.168.111.5:2003 
attr Mythz room Sysintern
</code>

'''userReadings'''

[[File:dash.jpg|thumb]]

<code>
attr Mythz userReadings AussenTemp:sGlobal {(split ' ',ReadingsVal("Mythz","sGlobal",0))[1]}, VorlaufTemp:sGlobal {(split ' ',ReadingsVal("Mythz","sGlobal",0))[3]}, RuecklaufTemp:sGlobal {(split ' ',ReadingsVal("Mythz","sGlobal",0))[5]}, WWTemp:sGlobal {(split ' ',ReadingsVal("Mythz","sGlobal",0))[9]}, KollektorTemp:sGlobal {(split ' ',ReadingsVal("Mythz","sGlobal",0))[79]}
</code>

'''interval Definitionen'''

<code>
attr Mythz interval_sGlobal 300 
attr Mythz interval_sHistory 28800 
attr Mythz interval_sLast10errors 120 
</code>

'''Definition von file-log und den SVG-Plots einiger Daten'''

<code>
define FileLog_Mythz FileLog ./log/Mythz-%Y-%m.log Mythz 
define wal_0 SVG FileLog_Mythz:thz:CURRENT 
attr wal_0 room Heizung 
define wal_1 SVG FileLog_Mythz:thz1:CURRENT 
attr wal_1 room Heizung 
define wal_2 SVG FileLog_Mythz:thz2:CURRENT 
attr wal_2 room Heizung 
define wal_3 SVG FileLog_Mythz:thz3:CURRENT 
attr wal_3 room Heizung 
define wal_4 SVG FileLog_Mythz:thz4:CURRENT 
attr wal_4 room Heizung 
</code>

'''readingsGroup'''

<code>
define rg_thz readingsGroup Mythz:<%temp_outside>,<Aussen>,AussenTemp Mythz:<%sani_supply_temp@red>,<Vorlauf>,VorlaufTemp Mythz:<%sani_return_temp@blue>,<Rücklauf>,RuecklaufTemp Mythz:<%sani_boiler_temp@BD7800>,<Wasser>,WWTemp Mythz:<%sani_solar_temp>,<Kollektor>,KollektorTemp
 
attr rg_thz alias Heizung Temperaturen 
attr rg_thz group THZ 
attr rg_thz room Sysintern 
attr rg_thz valueFormat { AussenTemp => '%1.f °C', VorlaufTemp => '%1.f °C', AussenTemp=> '%1.f °C', RuecklaufTemp=> '%1.f °C', WWTemp=> '%1.f °C', KollektorTemp=> '%1.f °C' }
</code>

'''Dashboard'''

<code>
define MyDashboard Dashboard 
attr MyDashboard dashboard_lockstate unlock 
attr MyDashboard dashboard_row top-center 
attr MyDashboard dashboard_showhelper 0 
attr MyDashboard dashboard_showtooglebuttons 0 
attr MyDashboard dashboard_tab1groups THZ 
attr MyDashboard dashboard_tab1name micofhem 
attr MyDashboard dashboard_tab1sorting t0c100,THZ,true,170,253 
attr MyDashboard dashboard_tabcount 1 
attr MyDashboard dashboard_webfrontendfilter WEB 
define MyDashboard_weblink weblink htmlCode {DashboardAsHtml("MyDashboard")} 
attr MyDashboard_weblink room DashboardRoom
</code>

'''FanSelector für die Lüftungssteuerung'''

<code>
define FanSelectorDay dummy 
attr FanSelectorDay group THZ 
attr FanSelectorDay setList 0 1 2 3 offFor60min 
attr FanSelectorDay webCmd 0:1:2:3:offFor60min 
attr FanSelectorDay devStateIcon 0:vent_ventilation_level_0 1:vent_ventilation_level_1 2:vent_ventilation_level_2 3:vent_ventilation_level_3 
define Notify_p07FanStageDay notify FanSelectorDay IF ([FanSelectorDay] eq "offFor60min") (define at_D_offFor60min at +00:59:00 set Mythz p07FanStageDay [Mythz:p07FanStageDay],set Mythz p07FanStageDay 0, setstate FanSelectorDay offFor60min) ELSE (set Mythz p07FanStageDay $EVENT) 
define Notify_FanselectorDay notify (Mythz.p07FanStageDay.*) setstate FanSelectorDay $EVTPART1 
attr FanSelectorDay room heatpump 
[[File:fanselectorv2.png|thumb]]
define FanSelectorNight dummy 
attr FanSelectorNight group THZ 
attr FanSelectorNight setList 0 1 2 3 offFor60min 
attr FanSelectorNight webCmd 0:1:2:3:offFor60min 
attr FanSelectorNight devStateIcon 0:vent_ventilation_level_0 1:vent_ventilation_level_1 2:vent_ventilation_level_2 3:vent_ventilation_level_3 
define Notify_p08FanStageNight notify FanSelectorNight IF ([FanSelectorNight] eq "offFor60min") (define at_N_offFor60min at +00:59:00 set Mythz p08FanStageNight [Mythz:p08FanStageNight],set Mythz p08FanStageNight 0, setstate FanSelectorNight offFor60min) ELSE (set Mythz p08FanStageNight $EVENT) 
define Notify_FanselectorNight notify (Mythz.p08FanStageNight.*) setstate FanSelectorNight $EVTPART1 
attr FanSelectorNight room heatpump</code>

= Links =
[https://launchpad.net/heatpumpmonitor Launchpad Heatpumpmonitor]

[http://forum.fhem.de/index.php/topic,13132.0.html Forenthread im FHEM-Forum]

[[Kategorie:Other Components]]
[[Kategorie:Heizungssteuerung]]

ReadingsGroup

2014-08-12T21:02:01Z

Kamischi:

{{SEITENTITEL:readingsGroup}}
{{Infobox Modul
|ModPurpose=Einfache zusammenfassende Darstellung von Informationen über mehrere Geräte
|ModType=h

|ModCmdRef=readingsGroup
|ModTechName=33_readingsGroup.pm
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=430 Andre / justme1968]}}
Das Fhem-[[:Kategorie:Hilfsmodul|Hilfsmodul]] [[readingsGroup]] bietet eine einfache Möglichkeit, ''readings'' und ''internal values'' von einem oder mehreren ''Devices'' darzustellen und flexibel zu formatieren.

Hier soll eine Sammlung von Beispielen zur Verwendung der ''readingsGroup'' mitsamt der zugehörigen Screenshots entstehen.

== Definition ==
Siehe commandref.

== Attribute ==
Weitergehende Erläuterungen zu einzelnen Attributen:

=== noheading ===
[[Datei:ReadingsGroup_noheading.png|mini|rechts|400px|ReadingsGroup: rechts mit "noheading" Attribut, links der anklickbare Titel]]
Das Attribut <code>noheading</code> führt dazu, dass der Alias der ReadingsGroup nicht mehr als Titel angezeigt wird. Das kann wünschenswert sein, wenn die ReadingsGroup auf einer [[Dashboard]]-Seite angezeigt werden soll, hat allerdings den Nachteil, dass die Detail-Ansicht der ReadingsGroup nicht mehr über einen Klick auf den Titel aufgerufen werden kann. Der Einstellungsdialog der ReadingsGroup ist dann nur noch (z. B.) über
* einen "Probably associated with"-Link eines anderen Objekts oder über
* manuelle Modifikation der URL eines anderen Objekts (<code>http:.../fhem?detail=<objektname></code>)
erreichbar.

== Beispiele ==
Achtung: Die Beispiele enthalten keine Maskierungen oder Verdoppelungen für ; und Zeilenende, sondern sind so angegeben, wie sie in Fhemweb, in der command box oder nach Klick auf DEF eingegeben werden. Beim manuellen Einfügen in eine [[Konfiguration|Konfigurationsdatei]] sind diese Maskierungen oder Verdoppelungen natürlich vorzunehmen.

=== Einfache Auswahl über Reading-Namen ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define battStatus readingsGroup .*:[Bb]attery</code>
| Alle readings mit Namen '''Battery''' oder '''battery''' von allen Devices.
| rowspan=3 | [[Datei:rgBattery.png|thumb]]
|-
| <code>attr battStatus alias FHT Batteriestatus </code>
| Der Alias wird als Zeilentitel verwendet
|-
| <code>attr battStatus mapping %ROOM </code>
| ''Mapping %ROOM'' führt dazu, dass der Raumname als Zeilentitel angezeigt wird.
|}

=== Auswahl über Reading-Namen, Status als Symbol dargestellt ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg_battery readingsGroup .*:battery</code>
| Alle readings mit Namen '''battery''' von allen Devices.
| rowspan=4 | [[Datei:rgBattery2.png|thumb]]
|-
| <code>attr rg_battery alias Batteriestatus </code>
| Der Alias wird als Überschrift verwendet
|-
| <code>attr rg_battery valueIcon {'battery.ok' => 'batterie', 'battery.low' => 'batterie@red'}</code>
| Statt der reading Werte "ok" und "low" soll ein Icon angezeigt werden.
|-
|<code>attr rg_battery commands { "battery.low" => "set %DEVICE replaceBatteryForSec 60" }</code>
| Für LaCrosse devices kann man beim Klick auf ein rotes "battery low icon" direkt replaceBatteryForSec setzen.
|}

=== Reading-Werte zuordnen (Icon / Text) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg readingsGroup Contact.Dachboden_gross:sensed.*</code>
| Alle sensedreadings des Contact.Dachboden_gross device.
| rowspan=4 | [[Datei:rgFenster.png|thumb]]
|-
| <code>attr rg mapping { 'sensed.A' => 'links', 'sensed.B' => 'rechts' }</code>
| Die Zuordnung rechts/links
|-
| <code>attr rg valueFormat {($VALUE eq '1')?"fts_window_roof":"fts_window_roof_open_2"}</code>
| Die Zuordnung von reading Wert zu Icon Namen.
|-
| <code>attr rg_battery valueIcon %VALUE </code>
| Statt des reading Werts soll ein Icon angezeigt werden.
|}

=== Formatvorgabe für Ausgabewerte ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define TempHygro readingsGroup TYPE=CUL_WS:temperature,humidity,dewpoint</code>
| Alle readings mit Namen '''temperature''', '''humidity''', '''dewpoint''' von allen Devices des Typs '''CUL_WS'''
| rowspan=4 | [[Datei:rgTemperatur.png|thumb|[[S300TH]]-Werte in einer readingsGroup]]
|-
| <code>attr TempHygro alias Temperatur / rel. Feuchte / Taupunkt</code>
| Der Alias der readingsGroup wird als Überschrift verwendet
|-
| <code>attr TempHygro mapping %ALIAS</code>
| ''Mapping %ALIAS'' führt dazu, dass der Alias des Geräts als Zeilentitel angezeigt wird.
|-
| <code>attr TempHygro valueFormat { temperature => "%.1f&deg;C", humidity => "%.1f %%", dewpoint => "%.1f&deg;C"}</code>
| Formatierung der Ausgabewerte. '''Achtung:''' "%" die in der Ausgabe erscheinen sollen, müssen verdoppelt werden!
|}

=== Ausgabestil (hier rechtsbündig) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Wetter readingsGroup WetterXXX:<%temp_temperature>,<Temperatur>,temperature WetterXXX:<%weather_humidity>,<Luftfeuchte>,humidity WetterXXX:<%weather_baraometric_pressure>,<Luftdruck>,pressure
</code>
| Die readings mit Namen '''temperature''', '''humidity''' und '''pressure''' vom Device WetterXXX jeweils mit einem Icon und einem Label davor.
| rowspan=3 | [[Datei:rgWetter.png|thumb]]
|-
| <code>attr Wetter valueFormat { temperature => '%1.f &deg;C', humidity => '%1.f %%', pressure => '%i mbar' }</code>
| Die Formatierung der Readingswerte
|-
| <code>attr Wetter valueStyle style="text-align:right"</code>
| Die Readings sollen rechtsbündig dargestellt werden.
|}

=== Internal Value ausgeben ===
Diese Beispiel könnte entfallen (nächstes Beispiel ist sehr ähnlich; es wird lediglich ein weiterer Wert ausgegeben).
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI</code>
| Den cul_RSSI Wert aller Devices die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau.
| rowspan=1 | [[Datei:rgculRSSI.png|thumb]]
|}

=== Internal Values ausgeben ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI,+cul_TIME</code>
| Den cul_RSSI Wert mit der zugehörigen Zeit aller Devices die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau. "Internal Values" werden durch das vorangestellte '''+''' (Pluszeichen) identifiziert.
| rowspan=1 | [[Datei:rgculRSSI2.png|thumb]]
|}

=== Alle Readings eines Gerätes, mit Ausnahme von... ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Systemstatus readingsGroup sysstat</code>
| Alle readings des sysstat Device
| rowspan=4 | [[Datei:rgSysstat.png|thumb]]
|-
| <code>attr Systemstatus nostate 1</code>
| Ohne state
|-
| <code>attr Systemstatus notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Systemstatus mapping {'load' => 'Systemauslastung', 'temperature' => 'Systemtemperatur in &deg;C'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|}

=== Anzeige auf einem Floorplan ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Heizung readingsGroup t(1|2|3):temperature</code>
| Die Temperatur readings der Devices t1, t2 und t3
| rowspan=6 | [[Datei:rgHeizung.png|thumb]]
|-
| <code>attr Heizung mapping {'t1.temperature' => 'Vorlauf', 't2.temperature' => 'R&ücklauf', 't3.temperature' => 'Zirkulation'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|-
| <code>attr Heizung nameStyle style="text-align:left"</code>
| Zeilentitel linksbündig wegen floorplan
|-
| <code>attr Heizung style style="font-size:20px;color:lightgray"</code>
| Großer Font und Farbe passend für den floorplan
|-
| <code>attr Heizung notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Heizung valueFormat : %.1f &deg;C</code>
| Doppelpunkt zwischen Zeilentitel und Wert, eine Nachkommastelle plus Einheit
|}

=== Schriftgrößen, Farben, Icons ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgVerbrauchPCA301.png|links|mini|400px|Schriftgröße, Farbe, Icons...]]
|-
| style="width:40%" |<code>define Verbrauch readingsGroup TYPE=PCA301:state,power,consumption</code>
| Die readings state, power und consumption aller [[PCA301 Funkschaltsteckdose mit Energieverbrauchsmessung|PCA301]] Devices mit einer Zeile pro Device.
|-
| <code>attr Verbrauch mapping %ROOM %ALIAS</code>
| Der Raumname und der Alias werden als Zeilentitel verwendet
|-
| <code>attr Verbrauch nameStyle style="font-weight:bold"</code>
| Der Zeilentitel soll fett sein
|-
| <code>attr Verbrauch style style="font-size:20px"</code>
| Alles in einem größeren Font
|-
| <code>attr Verbrauch valueFormat {power => "%.1f W", consumption => "%.2f kWh"}</code>
| Die Formatierung für die power und consumption readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr Verbrauch valueIcon { state => '%devStateIcon' }</code>
| Für die Dosen, die schaltbar sind, soll das anklickbare device icon gezeigt werden.
|-
|<code>attr Verbrauch valueStyle {($READING eq "power" && $VALUE > 40)?'style="color:red"':'style="color:green"'}</code>
|Wenn das power reading >40 ist, soll es in rot angezeigt werden, alle anderen Werte und readings in grün
|}

=== Wertabhängige Farbgebung ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:TemperaturenRG.png|600px|mini|links|Wertabhängige Farben]]
[[Datei:TemperaturenRG2.png|600px|mini|links|Andere Werte - andere Farben]]
|-
| style="width:40%" |<code>define wzTemperaturenRG readingsGroup Aussen:,<Temperatur>,temperature,<Luftfeuchte>,humidity Wohnzimmer:,<Temperatur>,temperature,<Luftfeuchte>,humidity Kasten_E_Geraete:,<Temperatur>,temperature,<Luftfeuchte>,humidity</code>
| Die readings temperatur und humidity der Devices Aussen, Wohnzimmer und Kasten_E_Geraete in einer Zeile pro Device.
|-
| <code>attr wzTemperaturenRG group 3. Temperaturen</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzTemperaturenRG noheading 1</code>
| noheading
|-
| <code>attr wzTemperaturenRG nostate 1</code>
| nostate
|-
| <code>attr wzTemperaturenRG notime 1</code>
| notime
|-
| <code>attr wzTemperaturenRG valueFormat {temperature => "%.1f °C", humidity =>"%.1f %%" }</code>
| Die Formatierung für die temperatur und humidity readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr wzTemperaturenRG valueStyle { if($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 20) { 'style="color:orange"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE < 5) { 'style="color:blue"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 23) { 'style="color:red"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 21) { 'style="color:orange"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE < 20) { 'style="color:blue"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 28) { 'style="color:orange"'}elsif($READING eq "humidity" && $VALUE > 65) { 'style="color:red"'}elsif($READING eq "humidity" && $VALUE > 60) { 'style="color:orange"'}else{'style="color:green"'} }</code>
| Diverse Farbkombinationen sind möglich
|}

=== Enigma Receiver ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:ReceiverRG.jpg|600px|mini|links|Wertabhängige Farben]]
[[Datei:ReceiverRGmute.jpg|600px|mini|links|Wertabhängige Farben]]
|-
| style="width:40%" |<code>define wzReceiverRG readingsGroup wzReceiver:,<Aktuell>,eventtitle,<Rest>,eventremaining_hr,<Dauer>,eventduration_hr wzReceiver:<Beschreibung>,eventdescription wzReceiver:,<Nächste>,eventtitle_next,<Start>,eventstart_next_hr,<Dauer>,eventduration_next_hr wzReceiver:,<HDD Kapazität>,hdd1_capacity,<Frei>,wzReceiver:hdd1_free wzReceiver:,<Lautstärke>,volume,<HDD>,hdd1_capacity,<Frei>,hdd1_free</code>
| Mehrere readings des Device wzReceiver in mehreren Zeilen. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke, mute angezeigt. Farbige Anzeige des freien Speicherplatzes
'''Benötigt:''' ENIGMA2 Receiver, 70_ENIGMA2.pm - Siehe: [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern]]
|-
| <code>attr wzReceiverRG group Fernseher Receiver</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzReceiverRG mapping &nbsp;</code>
| mapping wird auf &nbsp; (Leerzeichen) gesetzt, damit der Device Name nicht angezeigt wird
|-
| <code>attr wzReceiverRG noheading 1</code>
| noheading
|-
| <code>attr wzReceiverRG nostate 1</code>
| nostate
|-
| <code>attr wzReceiverRG notime 1</code>
| notime
|-
|-
| <code>attr wzReceiverRG valueColumns { eventdescription => 'colspan="4"' }</code>
| Die Beschreibung soll über 4 Spalten gehen
|-
| <code>attr wzReceiverRG valueFormat { wzReceiverRGvalueFormat($DEVICE,$READING,$VALUE);; }</code>
| Die Formatierung wird in die 99_myUtils.pm ausgelagert. Siehe: [[99 myUtils anlegen]]
|-
|<code>attr wzReceiverRG valueStyle { if($READING eq "hdd1_free" && $VALUE < 200){ 'style="color:red"' }elsif( $READING eq "hdd1_free" && $VALUE < 500 ){ 'style="color:orange"' }elsif( $READING eq "volume" && ReadingsVal($DEVICE, "mute", "") eq "on" ){ 'style="color:red"' }else{ 'style="color:green"' } }</code>
| Diverse Farbkombinationen sind möglich. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke mute angezeigt.
|-
| <code>
sub wzReceiverRGvalueFormat($$$)
{
my ($DEVICE,$READING,$VALUE) = @_;

if($READING eq 'hdd1_capacity') {
return "%.2f MB";
} elsif( $READING eq 'hdd1_free') {
return "%.2f MB";
} elsif( $READING eq 'volume' ) {
if( ReadingsVal($DEVICE, "mute", "") eq "on") {
return "mute";
} else {
return "%i %%";
}
}
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]
|}

=== Heizungswerte inklusive Batterie- und Fensterstatus ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung3.png|thumb|links|500px|Heizungswerte inklusive Batterie- und Fensterstatus]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<%18>,<%20>,<%22>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte commands { 'Heizungswerte.18' => 'set $DEVICE desired-temp 18', 'Heizungswerte.20' => 'set $DEVICE desired-temp 20', 'Heizungswerte.22' => 'set $DEVICE desired-temp 22' }</code>
| Die Links/Kommandos die hinter den 18, 20 und 22 liegen sollen.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte inklusive Ventilposition ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:Rg_Heizung_Valveposition.png|thumb|links|500px|Heizungswerte inklusive Statusinformationen (MAX!)]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,<Ventil>,<Soll>,<Ist>,<MaxV>,<GID>,<Mode>,<Batterie> type=CUL_HM:ValvePosition,desired-tempe,measured-temp,R-valveMaxPos,groupid,mode,battery</code>
| Diverse readings aller Devices des Typs MAX.
|-
| <code>attr Heizungswerte mapping %ROOM</code>
| Die Raumnamen werden angezeigt.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb (fett) sein.
|-
| <code>attr Heizungswerte room Heizung</code>
| Die "readingsgroup" wird dem Raum "Heizung" zugeordnet.
|-
| <code>attr Heizungswerte valueFormat {temperature => "%.0f °C", desiredTemperature => "%.0f °C", valveposition =>"%.0f %%",maxValveSetting =>"%.0f %%" }</code>
| Es wird noch die Einheit °C hinter den Temperaturwerten angezeigt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batteriezustand werden Icons anstatt Klartextwerte genommen!
|-
| <code>attr Heizungswerte valueStyle { if($READING eq "temperature" && $VALUE > 20){ 'style="color:green;;font-weight:bold"' }elsif( $READING eq "temperature" && $VALUE <= 20 ){ 'style="color:blue"' }elsif( $READING eq "temperature" && $VALUE > 23 ){ 'style="color:red"' }else{ 'style="color:gray"' } }</code>
| Die Temperaturwerte werden abhängig vom Wert farbig dargestellt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte, Status und Regelmöglichkeit ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung2.png|thumb|500px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define Heizungswerte2 readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<{myUtils_HeizungUpDown($DEVICE,"up")}@desired-temp>,desired-new,<{myUtils_HeizungUpDown($DEVICE,"down")}@desired-temp>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte2 nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte2 valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|-
| <code>attr Heizungswerte2 valueStyle {($VALUE eq "00")?'style="visibility:hidden"':''}</code>
| Nach dem Einstellen den Wert wieder ausblenden.
|-
| <code>
#Heizung regeln in readingsGroup
sub
myUtils_HeizungUpDown($$)
{
my($DEVICE,$CMD) = @_;

my $icon = $CMD;
my $VALUE = ReadingsVal($DEVICE,"desired-new","20" );
$VALUE = ReadingsVal($DEVICE,"desired-temp","20" )
if( !$VALUE || $VALUE == 0 );
my $link;

if( $CMD eq "up" ) {
$icon = "control_arrow_upward";
$VALUE += 1;

if( $VALUE <= 24 ) {
$icon .= "\@red";
$link = "setreading $DEVICE desired-new $VALUE";
}
} elsif( $CMD eq "down" ) {
$icon = "control_arrow_downward";
$VALUE -= 1;

if( $VALUE >= 18 ) {
$icon .= "\@blue";
$link = "setreading $DEVICE desired-new $VALUE";
}
}

my $notify = "notifyHeizungUpDown";
if( !defined($defs{$notify}) ) {
CommandDefine(undef,
"$notify notify .*:desired-new.* "
."{ myUtils_HeizungUpDownNotify(\$NAME,\$EVTPART1); }" );
}

my $ret = "%$icon";
$ret .= "%$link" if( $link );

return $ret;
}
sub
myUtils_HeizungUpDownNotify($$)
{
my($DEVICE,$VALUE) = @_;

return if( $VALUE == 0 );

my $at = "triggerHeizungUpDown_$DEVICE";
CommandDelete(undef, $at) if( defined($defs{$at}) );
CommandDefine(undef,
"$at at +00:00:03 "
."{my \$v = ReadingsVal(\"$DEVICE\",\"desired-new\",undef);"
."fhem(\"set $DEVICE desired-temp \$v\") if( \$v );"
."fhem(\"setreading $DEVICE desired-new 00\");}" );

return undef;
}
</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit werden die Icons zum Ändern der gewünschten Temperatur dargestellt und im Bereich >=18 und <= 24 Grad anklickbar gemacht. Zwischen den Pfeilen wird der gerade eingestellte Wert angezeigt. Wenn dieser drei Sekunden nicht mehr geändert wurde wird die desired-temp auf diesen Wert gesetzt und die Anzeige zwischen den Pfeilen ausgeblendet.
|}

=== Readings aus zusätzlichen Devices ===
Im folgenden Beispiel wird gezeigt wie sich Readings zusätzlicher Devices zu einer Zeile mit mehreren Readings hinzufügen lassen. Diese zusätzlichen Devices können z.b. die unterschiedlichen Channel eines HomeMatic Gerätes sein. Im folgenden Beispiel wird der Name des zugehörigen Geräts dynamisch bestimmt.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung4.png|thumb|500px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define myTemp readingsGroup <Raum>,<Tist>,<Tsoll>,<Mode>,<Tnight>,<Tday>,<Hum>,<BatTC>,<Vist>,<Vsoll>,<Verr>,<BatVD> Thermostat.(WZ|OZ|AZ|Bad|Kueche|SZ|GZ|Bad.OG):measured-temp,desired-temp,controlMode,night-temp,day-temp,humidity,battery,ValvePosition@{valveOfDevice($DEVICE)},ValveDesired@{valveOfDevice($DEVICE)},R-valveErrorPos@{valveOfDevice($DEVICE)},battery@{valveOfDevice($DEVICE)} Broetje:ToutIst </code>
| Diverse Readings aller Thermostat Devices und des jeweils zugehörigen Ventilantriebs.
|-
| <code>attr myTemp mapping { 'Broetje' => 'Garten','Thermostat.AZ' => 'EG Arbeitszimmer','Thermostat.SZ' => 'OG Schlafzimmer','Thermostat.WZ'=>'EG Wohnzimmer','Thermostat.Kueche' => 'EG Küche','Thermostat.GZ' => 'OG Gästezimmer','Thermostat.Bad' => 'EG Bad','Thermostat.Bad.OG' => 'OG Bad','Thermostat.OZ' => 'EG Kaminzimmer','desired-temp' => <nowiki>''</nowiki> }</code>
| Die Benennung der Zeilentitel (Das ist je nach Konfiguration auch über $ALIAS und/oder $ROOM lösbar).
|-
| <code>attr myTemp commands { 'desired-temp' => 'desired-temp:' }</code>
| desired-temp soll per dropDown einstellbar sein.
|-
| <code>attr myTemp nameStyle style="color:yellow"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr myTemp valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batteriestand sollen jeweils Icons angezeigt werden.
|-
| <code>attr myTemp valueFormat { 'measured-temp' => "%0.1f &deg;C",'ToutIst' => "%.1f &deg;C",'night-temp' => "%.1f &deg;C",'day-temp' => "%.1f &deg;C",'humidity' => "%.0f
%%",'ValvePosition' => "%.0f %%",'ValveDesired' => "%.0f %%",'R-valveErrorPos' => "%.0f %%" }</code>
| Die Formatierung der Werte.
|-
| <code>
#namen des ventil device aus thermostat device ableiten
sub valveOfDevice ($) {
my ($DEVICE) = @_;

if ($DEVICE =~ m/AZ/) {
return "Ventil.".substr($DEVICE,11).".Nord";
} else {
return "Ventil.".substr($DEVICE,11);
}
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hier wird aus dem Namen des Thermostaten der Name des zugehörigen Ventilantriebs abgeleitet.
|}
Da im {...} Teil des <reading>@<device> Arguments keine Leerzeichen oder Kommas vorkommen dürfen ist er in der Regel das Einfachste die Funktionalität wie in diesem Beispiel in eine eigene Routine auszulagern. Mit ein paar 'Tricks' lässt es sich aber manchmal auch ohne Leerzeichen oder Kommas lösen und dann direkt in die Definition schreiben:<code>...,ValvePosition@{$DEVICE=~s/Thermostat/Ventil/;$DEVICE;},...</code>

=== Dynamische Inhalte ===
[[Datei:rgDynamic-1.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 1]]
[[Datei:rgDynamic-2.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 2]]
Es ist möglich, den in einer readingsGroup dargestellten Inhalt dynamisch von zusätzlichen Bedingungen abhängig zu machen. Im folgenden Beispiel lässt sich
einstellen, dass nur die Devices angezeigt werden, die einen bestimmten Zustand (hier: on/off, open/tilted/closed) haben. Hier wird zum Umschalten ein dummy, der direkt über der readingsGroup dargestellt wird, verwendet. Über das links und/oder commands lässt sich auch eine Darstellung erzeugen, bei der das Umschalten direkt innerhalb der readingsGroup möglich ist.

<pre>
define LXrg dummy
attr LXrg group -
attr LXrg setList mode1:on,off mode2:open,closed,tilted
attr LXrg stateFormat 1=mode1 2=mode2
attr LXrg webCmd mode1:mode2

define rg readingsGroup Window.*:state Light.*:state
attr rg group -
attr rg valueFormat { return $VALUE if ( $VALUE eq ReadingsVal("LXrg","mode1","") || $VALUE eq ReadingsVal("LXrg","mode2","") );; return undef;;}

define Watch_LX notify LX.*:.* {my $value = ReadingsVal($NAME,'state','');;;;fhem("setreading $NAME $value")}
</pre>

=== Enable/Disable Button am Beispiel eines WeekdayTimer ===
Dieses Beispiel zeigt die Anwendung einer readingsGroup, um im Frontend einen Enable/Disable Button für ein Objekt darzustellen. Für den WeekdayTimer gibt es hier spezielle Erweiterungen (set Routinen, um das disable Attribut zu setzen, Reading "disabled"). Es gibt aber auch eine allgemeinere Variante (siehe [http://forum.fhem.de/index.php/topic,23655.msg169141.html#msg169141 diesen Forumsbeitrag]) für alle Objekte, die das FHEM Attribut "disable" unterstützen.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rg_scheduling.png|thumb|500px|links|Enable/Disable Button]]
|-
| style="width:40%" |<code>define rg_Timer_Wasser readingsGroup timer_Wasser_..:disabled,+DEF,<{rg_timer_Wasser_show_conditional($DEVICE,"nextUpdate")}@disabled>,<{rg_timer_Wasser_show_conditional($DEVICE,"nextValue")}@disabled></code>
| Definition der angezeigten Readings. Das Reading disabled wird mit den u.a. Attributen zum Button, +DEF zeigt die Definition, d.h. die Schaltzeiten, des Timers an. Die Readings nextUpdate und nextValue sollen nur angezeigt werden, falls der Timer aktiv ist. Hierfür sorgt eine Routine <code>rg_timer_Wasser_show_conditional</code>, die in der 99_myUtils.pm definiert wird. Das abschließende @disabled sorgt dafür, dass der LongPoll Mechanismus die Anzeige sofort ändert, wenn der Button betätigt wird.
|-
| <code>attr rg_Timer_Wasser valueFormat { if ( $READING =~ m/.*DEF/ ) { my @text = split(" ", $VALUE); shift @text; return join(" ", @text) }}</code>
| Der Name des Timers wird aus dem interal Reading "+DEF" vorne abgeschnitten. Damit werden nur die definierten Schaltpunkte angezeigt.
|-
| <code>attr rg_Timer_Wasser valueIcon { 'disabled.0' => 'Restart', 'disabled.1' => 'Shutdown' }</code>
| Die beiden Zustände für den Button werden durch zwei Standard-Icons angezeigt.
|-
| <code>attr rg_Timer_Wasser commands { 'disabled.0' => 'set $DEVICE disable', 'disabled.1' => 'set $DEVICE enable' }</code>
| Toggle-Funktion für den Button. Wenn der Timer aktiv ("disabled.0") sorgt ein Klick auf den Button, dass der Timer deaktiviert wird ("set $DEVICE disable").
|-
|<code>
sub rg_timer_Wasser_show_conditional($$)
{
my ($DEVICE,$READING) = @_;
return ( ReadingsVal($DEVICE, "disabled", "1") eq "0" )?
ReadingsVal($DEVICE, $READING, "reading_undef") : "disabled";
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit wird das übergebene Reading des Timers nur angezeigt, wenn der Timer aktiv ist. Andernfalls wird der String "disabled" stattdessen angezeigt.
|}

== Links und Trigger ==
[[Datei:rgPCA-detail.png|mini|400px|readingsGroup mit Link]]
Das PCA301 Beispiel oben lässt sich mit einem ans Ende des define angehängten
:<code><{appendTrigger($DEVICE,"clear","Alle löschen")}></code>
und der folgenden appendTrigger Definition in 99_myUtils.pm um einen Link erweitern, der ein Event auslöst, an das z.B. ein notify gehängt werden kann, um die Verbrauchszähler der PCA301 Dosen zurückzusetzen.
:<code>define clearVerbrauch notify Verbrauch:clear set TYPE=PCA301 clear</code>

<pre>use vars qw($FW_ME);
use vars qw($FW_subdir);
sub
appendTrigger($$$)
{
my ($name,$trigger,$label) = @_;

my $ret .= "</table></td></tr>";

my $link = "cmd=trigger $name $trigger";
my $txt = "<a onClick=\"FW_cmd('$FW_ME$FW_subdir?XHR=1&$link')\">$label</a>";
$ret .= "<td colspan=\"99\"><div style=\"cursor:pointer;color:#888888;text-align:right\">$txt</div></td>";

return ($ret,0);
}</pre>

Ein weiteres Beispiel für 'custom links und trigger' findet sich im [http://forum.fhem.de/index.php/topic,14425.msg109383.html#msg109383 Forum]: dort wird damit eine readingsGroup dynamisch umgeschaltet, um nur die eingeschalteten, nur die ausgeschalteten oder alle Lampen anzuzeigen.

== Sonstiges ==
In der Regel werden die Parameter zu einem reading in den mappings unter <$DEVICE> und dann <$DEVICE>.<$READING> und dann unter <$READING>.<$VALUE> gesucht.

===Lesbar machen===
Für die meisten Attribute gilt:

*Wenn es komplexer wird ist es einfacher den Code in eine sub in 99_myUtils auszulagern und diese aufzurufen:
<code> attr <name> valueStyle {myValueToFormat($READING,$VALUE)}</code>

*code für unterschiedliche readings kann man auch im mapping schon aufteilen:
<code>attr <name> valueStyle { SuperE5 => '{perl code}', Diesel => '{perl code}' }</code>

*Ifs lassen sich verschachteln und sortieren. So kann die Anzahl der Klammern und Else-Zweige reduziert werden:
<code>if( $READING eq ... ) {
return xxx if( $VALUE < 1 );
return yyy if( $VALUE < 1.5 );
return zzz;
} elsif( $READING eq ... ) {
...
}</code>

Da alles lässt sich natürlich auch kombinieren und so viel lesbarer machen als ein einziger langer Bandwurm.

===group===
Wenn der doppelte Rahmen um eine readingsGroup in eine group stört, lässt er sich mit dem passenden style entfernen:
<code>attr <device> style style="border:0px;background:none;box-shadow:none"</code>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

ZHK

2014-08-12T21:01:35Z

Kamischi:

{{Infobox Modul
|ModPurpose=Dieses Modul ist noch Entwicklung
|ModType=h

|ModCmdRef= ---- noch nicht Teil von FHEM ----
|ModTechName=98_ZHK.pm
|ModOwner=epsrw1}}

Das Fhem-Modul [[ZHK|ZentralHeizKessel (ZHK)]] bietet die Möglichkeit, einen Zentralheizkessel mit Vorlauf, Vorlaufmischer/Rücklaufanhebung, Warmwasserspeicher+Ladepumpe zu steuern.

== Features ==
{{Baustelle}}

----

''' umfassende Parametereinstellung '''
* alle Modulteile können einzeln eingestellt oder deaktiviert werden

''' derzeit enthaltene interne Module '''
* VorlaufRegler: Heizkurvenberechnung und/oder Zusatzmodule berücksichtigen
* VorlaufZeitschaltplan: Wochenplaner für VL-Absenkung nach Zeiten
* AussentempRegler: zuschaltbare Aussentemp.Option
* HolzofenRegler: Temperatursprung-Erkennung für Kaminofen um VL frühzeitig anzupassen
* automatische Vorlauf-Totalabschaltung
* WarmWasserRegler: Temperatursturzerkennung (sofortiges Nachheizen bei großer Entnahme)
* WwZeitschaltplan: Wochenplaner für die Temp.-Voreinstellung nach Zeiten
* Warmwasser: manuelle Einstellung Eco/Confort/Gradzahl
* WarmWasser Kochprogramm über Wochenplaner
* KesselRegler: Einstellen der optimalen Kesseltemp. nach WarmWasser, Vorlauf, Brennertakt, VL/RL-Differenztemperatur

== Funktionsweise ==

:Global
* jedes Untermodul kann mit attr abgeschaltet bzw. deaktiviert bzw. auf null gesetzte werden
* Timer-Einstellung für Zeitspanne bis zur nächsten periodischen Neuberechnung der Werte

:Vorlauf
* Vorlauf(allgemein) führt Vorlauf-Untermodule zusammen
* komplett frei konfigurierbare Parameter für lineare Heizkurve (über attr)
* Vorlauf: Heizkurve nach Außentemperatur
* Vorlauf: Nachjustierung nach Mischerposition
* Vorlauf: Nachjustierung nach VL/RL-Differenz
* Vorlauf: Nachregulierung über valvePosition falls Thermostat-Daten vorhanden
* Vorlauf: Abschaltung nach Außentemperatur-Limit
* Vorlauf: Abschaltung wenn Temperatursprung durch Holzofen erkannt
* integrierter Wochenzeitplan für timergesteuerte Erhöhung/Absenkung

:Kessel
* Grundeinstellung mit klassischer Heizkurve nach aktueller Außentemperatur (kann abgeschaltet werden)
* Totalabschaltung nach aktueller Außentemperatur
* Mindest-Temp nach Diff zu aktueller Warmwasser-Temperatur
* Mindest-Temp nach Diff zu aktueller Vorlauf-Temperatur
* Anpassung mit Rechenfaktor zu aktueller Vorlauf-Rücklauf Differenztemperatur
* Anpassung mit Rechenfaktor zu aktueller Mischer-Position
* Schlußkontrolle Sicherheitseinstellungen (attr) absoluteMax und absoluteMin

:Warmwasser
* vordefinierte Temperaturen für Eco und Confort Modus
* manuelle Temp.Einstellung über fhem jederzeit möglich
* manuelle Temp.Einstellung wird beim nächsten Zeitschaltplan automatisch auf Auto zurückgesetzt
* integrierter Wochenzeitplan für timergesteuerte Temperatureinstellung

:Valvepositions
* Nachregulierung Vorlauf über valvePositions

:TaktOpt
* Auswertung Brennertakt, häufige Starts vermeiden durch dynamische Nachregelung des Kesseltemp-Thresholds
* zhkBrennerAlwasTriggerWw: attr um automatisch bei Brennerstart die Ww-Ladepumpe zu starten

== Zeitpläne ==

Zeitplan-Syntax
<einzelner Wochentag oder * für alle> <Zeitplan in text kodiert>

Beispiele
* für den Warmwasser-Timer werden feste Temperatureinstellungen angegeben:
:<code>Fr 00:00=30|05:00=35|08:00=30|17:00=35|22:00=30|23:00=20</code>
* zur programmierten Uhrzeit wird die Ww-Temp- automatisch eingestellt.

* für den Vorlauf-Timer werden Diff.Temperaturen angegeben:
:<code>* 01:00=-3|04:00=2|07:00=-1|17:00=1|22:00=-1|23:00=-2</code>

== Elektrische Anschlüsse ==

die von FHEM mit dem modul ZHK gesteuerten Lastrelais werden in Reihe mit den sicherheitsrelevanten Teilen der Heizung geschaltet (zB. Sicherheitsabschaltung Überhitzung). Dabei sind die Anschlüsse so vorgesehen, dass die Relais im Ruhezustand durchleiten. Falls FHEM einmal nicht laufen sollte, läuft der Heizkessel mit Maximaltemperatur weiter bis die Steuerung neugestartet wurde.
Im aktuellen Modulumfang sind folgende Elektrischen Anschlussmöglichkeiten an der Heizung enthalten:

* BrennerStop
* Warmwasser-Ladepumpe
* Warmwasser-Boost (übergehen der Max.Temp.)
* VorlaufPumpe Aus/An
* Mischermotor zB.: [http://www.fhemwiki.de/wiki/Mischersteuerung]
* Thermometer Kessel
* Thermometer Kessel(2nd backup)
* Thermometer Warmwasser
* Thermometer Vorlauf
* Thermometer Rücklauf
* Thermometer Referenzraum Holzofen
* Thermometer Außentemperatur

Elektrische Anschlüsse am Kessel dürfen nur von Fachleuten durchgeführt werden. Lebensgefahr durch Stromschlag!

== Define ==
:<code>define <name> ZHK <startverzögerung></code>
der wert <startverzögerung> gibt an, wie viele Sekunden ZHK wartet bevor die Berechnung startet. Empfohlen sind ca.120 Sekunden; damit auch langsame devices wie zb. OW thermometer über Ethernet genug Zeit haben, werte zu liefern.

Um die Wirkung und Funktionsweise des Moduls auszuprobieren, bietet sich an, mehrere '''Dummys''' zu verwenden:

<code>
define zhkBrennerFhemDev dummy

define zhkWwPumpFhemDev dummy

define zhkWwBoostFhemDev dummy

define zhkVorlaufPumpOffFhemDev dummy

define zhkVorlaufMischerFhemDev dummy

define zhkVorlaufTempTriggerFhemDev dummy
</code>

* zhkVorlaufTempTriggerFhemDev ist bewusst ausgelagert als FhemDev, hier kann entweder ein notify oder eigenes dev oder zB PID20 oder eine bereits bestehende Hardware-Temperaturregelung eingebunden werden

* Um alle Einstellmöglichkeiten auf Standardwerte Grundeinzustellen kann das Kommando SetAttribs verwendet werden. Bereits bestehende Einstellungen werden dabei nicht überschrieben.

:<code>set <name> SetAttribs</code>

* Der Wochenplan für die Vorlaufabsenkung kann mit dem befehl vltimer eingestellt werden. Die Syntax ist:
:<code>set <name> vltimer <Mo|Di|Mi|Do|Fr|Sa|So|*> <04:00=0|08:30=-3|17:00=0|22:00=-3></code>
Achtung: bei set "*" werden alle Tage auf einmal überschrieben!

* Der Wochenplan für die Warmwassertemperatur kann mit dem befehl wwtimer eingestellt werden. Die Syntax ist:
:<code>set <name> wwtimer <Mo|Di|Mi|Do|Fr|Sa|So|*> <04:00=45|08:30=30|17:00=45|22:00=30></code>
Achtung: bei set "*" werden alle Tage auf einmal überschrieben!

* Die Warmwassertemperatur kann jederzeit mit FHEM manuell eingestellt werden. Beim nächsten Zeitplan-Punkt geht die Temperatur automatisch wieder auf den vorprogrammierten Wert.
:<code>set <name> zhkWwSollTemp <Eco|Confort| gradzahl ></code>
Eco und Confort sind Standardtemperaturen die über Attr voreingestellt werden können.

== Set ==
:<code>set <name> <command> <option></code>

* zhkWwSollTemp: 30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,Eco,Confort
* SetAttribs
* vorlauf: 20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,auto
* vltimer +string
* wwtimer +string

== Get ==
:<code>get <name> <command> <option></code>

extracted usage of get command:

* zhkHolzofenTempSensorTimestamp
* zhkWwPriorityOn
* zhkBrennerActualState
* autocontrol
* zhkAussenTempYesterday
* state
* zhkKesselActualMischerAnhebung
* zhkWwBetriebsmodus
* zhkAussenTempAlarmThreshold
* zhkAussenTempAlarmTempLimit
* zhkWwBoostStatus
* zhkWwIstTempVal
* zhkAussenTempIsWarmState
* zhkWwSollTemp
* zhkHolzofenState
* zhkKesselActualVLRLAnhebung
* zhkAussenTempYesterdayMax
* zhkVorlaufTotalOnOffState
* zhkAussenTempDelayCache
* zhkWwAlphaActualVal
* zhkVorlaufActualTempVL
* looptime
* zhkWwPumpStopStatus
* zhkKesselDesiredTemp
* zhkKesselState
* zhkBrennerLogLastStateChange
* zhkWwIstLastReading
* zhkBrennerLaststart
* zhkVorlaufState
* zhkKesselActualVLRLdiff
* zhkWwIstTempTimestamp
* zhkAussenTempYesterdayMin
* zhkHolzofenTempHistoryCache
* zhkWwTimerLastSetValue
* zhkWwPumpLaststart
* zhkVorlaufDesiredTemp
* zhkVorlaufMischerPosActualPosition
* zhkKesselActualTemp
* zhkHolzofenAlphaActualVal
* zhkBrennerLogLastStopDauer
* zhkHolzofenTempSensorActValue
* zhkAussenTempActualVal
* zhkHolzofenResetLowTemp
* zhkVorlaufTimerTempAdjust
* zhkAussenTempTodayMax
* zhkVorlaufActualTempRL
* attrHelp: zhkBrennerTaktMinOnSec,zhkAussenTempMaxAge,zhkVorlaufTempTriggerFhemDevReading,zhkVorlaufHkurveAussenMax_TH,zhkWwTaktMinOnSec,zhkGlobalIncludeWwZeischaltplan,autocontrol,zhkBrennerTaktMinOffSec,zhkGlobalIncludeVorlauf,zhkGlobalPollInterval,zhkGlobalIncludeAussentemp,zhkKesselAbsoluteMaxTemp,zhkKesselTempMaxReadingAge,zhkAussenTempFhemDevReadingFallback,zhkWwTimerScheduleSo,zhkVorlaufPumpOffFhemDev,zhkHolzofenAlphaUpAlarmDiffDeg,zhkAussenTempFhemDevFallback,zhkAussenTempIgnoreIfFhemDev,zhkWwAlphaThreshold,zhkHolzofenIgnoreTempIfFhemDev,zhkVorlaufTimerScheduleSo,zhkKesselTempSecondFhemDevReading,zhkAussenTempAlarmThreshold,zhkHolzofenTempSensorMinAge,zhkVorlaufTimerScheduleDo,zhkAussenTempAlarmTempLimit,zhkWwTimerScheduleMi,zhkVorlaufMischerPosFhemDevReading,zhkWwTimerScheduleMo,zhkVorlaufMischerPosFhemDev,zhkVorlaufHkurveVorlaufMin_TL,zhkGlobalIncludeKessel,zhkWwTempSensorMaxAge,zhkVorlaufHkurveAussenMin_TL,zhkWwTempSensorFhemDev,zhkHolzofenResetLowFhemDev,zhkWwBoostStartTemp,zhkHolzofenTempSensorFhemDev,zhkAussenTempFhemDevReading,zhkGlobalIncludeVorlaufZeischaltplan,zhkKesselTempFhemDev,zhkHolzofenTempSensorReading,zhkWwTimerScheduleDi,zhkWwTempSensorDefaultOnFailure,zhkWwAlphaUpAlarmDiffDeg,zhkGlobalIncludeValvePositions,zhkWwTimerScheduleFr,zhkVorlaufTimerScheduleMo,zhkHolzofenTempSensorDefaultOnFailure,zhkHolzofenResetLowFhemDevreading,zhkKesselVLRLdiffErhFaktor,zhkAussenTempAlarmDelay,zhkWwBoostFhemDev,zhkKesselTempSecondFhemDev,zhkKesselMinDiffVorlauf,zhkHolzofenAlphaThreshold,zhkGlobalIncludeHolzofen,zhkVorlaufTimerScheduleSa,zhkVorlaufTimerScheduleFr,zhkKesselThreshold,zhkVorlaufTotalOnOffMischerDelay,zhkAussenTempIsWarmState,zhkVorlaufRLTempFhemDevReading,zhkKesselTempFhemDevReading,zhkWwTimerScheduleDo,zhkVorlaufTimerScheduleDi,zhkVorlaufVLTempFhemDevReading,zhkVorlaufRLTempFhemDev,zhkKesselMinDiffWw,zhkVorlaufTempTriggerFhemDevSetting,zhkWwAlphaDownAlarmDiffDeg,zhkBrennerFhemDev,zhkVorlaufTimerScheduleMi,zhkKesselAbsoluteMinTemp,zhkWwTempSensorReading,zhkWwEcoTemp,zhkKesselMischerErhFaktor,zhkGlobalIncludeWarmwasser,zhkVorlaufMischerFhemDev,zhkVorlaufTempTriggerFhemDev,zhkAussenTempFhemDev,zhkWwPumpFhemDev,zhkVorlaufVLTempFhemDev,zhkVorlaufHkurveVorlaufMax_TH,zhkWwTimerScheduleSa,zhkVorlaufIgnoreIfFhemDev,zhkHolzofenResetLowTemp,zhkWwConfortTemp,autocontrol
* readingsHelp: zhkHolzofenTempSensorTimestamp,zhkWwPriorityOn,zhkBrennerActualState,autocontrol,zhkAussenTempYesterday,zhkVorlaufHkurveCalcFaktor,zhkKesselActualMischerAnhebung,zhkWwBetriebsmodus,zhkBrennerLogLastStartDauer,zhkWwBoostStatus,zhkWwIstTempVal,zhkAussenTempTodayMin,zhkWwSollTemp,zhkHolzofenState,zhkKesselActualVLRLAnhebung,zhkAussenTempYesterdayMax,zhkVorlaufTotalOnOffState,zhkAussenTempDelayCache,zhkWwAlphaActualVal,zhkVorlaufActualTempVL,zhkWwPumpStopStatus,zhkKesselDesiredTemp,zhkKesselState,zhkVorlaufTotalOnOffReqTimeOff,zhkWwIstLastReading,zhkBrennerLogLastStateChange,zhkVorlaufState,zhkBrennerLaststart,zhkGlobalAutoGeneratedReadings,zhkWwIstTempTimestamp,zhkKesselActualVLRLdiff,zhkAussenTempYesterdayMin,zhkHolzofenTempHistoryCache,zhkWwTimerLastSetValue,zhkVorlaufManual,zhkWwPumpLaststart,zhkVorlaufDesiredTemp,zhkVorlaufMischerPosActualPosition,zhkKesselActualTemp,zhkAussenTempActualTimestamp,zhkHolzofenAlphaActualVal,zhkBrennerLogLastStopDauer,zhkHolzofenTempSensorActValue,zhkVorlaufTimerTempAdjust,zhkAussenTempActualVal,zhkAussenTempTodayMax,zhkVorlaufActualTempRL,
* all: ,Aussen,Brenner,Global,Holzofen,Kessel,Vorlauf,VorlaufTimer,Ww,WwTimer
* zhkWwiki: get,set,readings,attr

== Readings ==
Alle Readings sind auch in fhem durch das Kommando get readingsHelp <varname> erklärt, für das "schnelle nachschauen zwischendurch".

{| class="wikitable sortable"
|-
! Reading !! (Typ) Default !! Beschreibung
|-
| zhkHolzofenTempSensorTimestamp|| (string) 0 || timestamp last OW update
|-
| zhkWwPriorityOn|| (int) 0 || wenn 1, dann brenner sofort starten
|-
| zhkBrennerActualState|| (int) 0 || burner state 0=off 1=on
|-
| autocontrol|| (int) 30 || initial delay after fhem start before ZHK starts running, needed to wait for temp sensors or other slow devices
|-
| zhkAussenTempYesterday|| (float) 0 || cache of yesterday's date
|-
| zhkVorlaufHkurveCalcFaktor|| (float) 1.16 || erhöhungsfaktor heizkurve
|-
| zhkKesselActualMischerAnhebung|| (float) 0 || cached actual kessel temp
|-
| zhkWwBetriebsmodus|| (string) Unbekannt || wird über SET eingestellt: Eco | Confort (zb. mit at plan)
|-
| zhkBrennerLogLastStartDauer|| (int) 0 || cache zeitstempel für log betriebsstunden
|-
| zhkWwBoostStatus|| (string) off || zeigt aktuellen status 1=warmwasser temperaturbegrenzer überbrückt
|-
| zhkWwIstTempVal|| (float) 0 || OW lesen, wenn fehler dann default MAX
|-
| zhkAussenTempTodayMin|| (float) 0 || aussentemp today's minimum temp
|-
| zhkWwSollTemp|| (int) 30 || einstellung User (zeitplan mit at möglich)
|-
| zhkHolzofenState|| (int) 0 || actual calc result 0|1
|-
| zhkKesselActualVLRLAnhebung|| (float) 0 || cached actual kessel temp
|-
| zhkAussenTempYesterdayMax|| (float) 0 || aussentemp yesterday's maximum temp
|-
| zhkVorlaufTotalOnOffState|| (int) 1 || status VL totalabschaltung 1=pump on 0=all off
|-
| zhkAussenTempDelayCache|| (string) 0=22334455 || cache für trägheit aussentemp last-temp=timestamp
|-
| zhkWwAlphaActualVal|| (float) 0 || zuletzt berechneter wert für alpha
|-
| zhkVorlaufActualTempVL|| (float) 0 | VL readErr || cached actual vorlauf temperature
|-
| zhkWwPumpStopStatus|| (string) off || zeigt aktuellen status 1=warmwasser ladepumpe gestoppt 0=aufheizen
|-
| zhkKesselDesiredTemp|| (int) 35 || aktuelle soll-temp kessel
|-
| zhkKesselState|| (string) 0 || actual kessel State (BURN=brenner an, hot=max.temp erreicht idle=innerh.threshold) xx °C)
|-
| zhkVorlaufTotalOnOffReqTimeOff|| (float) 0 || internal cache for zhkVorlaufTotalOnOffMischerDelay
|-
| zhkWwIstLastReading|| (string) 0 || cached last OW temp for alpha-calc
|-
| zhkBrennerLogLastStateChange|| (int) 0 || cache zeitstempel für log betriebsstunden
|-
| zhkVorlaufState|| (int) 0 || actual vorlauf state (auto manual disabled off °C)
|-
| zhkBrennerLaststart|| (int) 0 || brenner cached last start timestamp
|-
| zhkGlobalAutoGeneratedReadings|| (string) 0 || alert if readings were not present in statefile at start
|-
| zhkWwIstTempTimestamp|| (string) 0 || timestamp last OW update
|-
| zhkKesselActualVLRLdiff|| (float) 0 || cached actual kessel temp
|-
| zhkAussenTempYesterdayMin|| (float) 0 || aussentemp yesterday's minimum temp
|-
| zhkHolzofenTempHistoryCache|| (string) 20=11223344 20=11225566 || cached last 2 temp readings
|-
| zhkWwTimerLastSetValue|| (int) 0 || last Ww desired temp set by timer function
|-
| zhkVorlaufManual|| (int) 0 || cached manual setting fixed temp if >0
|-
| zhkWwPumpLaststart|| (int) 0 || zeitstempel lester start warmwasser ladepumpe
|-
| zhkVorlaufDesiredTemp|| (float) 20 || calculated desired vorlauf temp
|-
| zhkVorlaufMischerPosActualPosition|| (int) 0 || heizkreis-mischer actual position
|-
| zhkKesselActualTemp|| (float) 0 || cached actual kessel temp
|-
| zhkAussenTempActualTimestamp|| (float) 0 || timestamp of last aussentemp value
|-
| zhkHolzofenAlphaActualVal|| (float) 0 || zuletzt berechneter wert für alpha (./zhkHolzofenTempSensorMinAge
|-
| zhkBrennerLogLastStopDauer|| (int) 0 || cache zeitstempel für log betriebsstunden
|-
| zhkHolzofenTempSensorActValue|| (float) 0 || actual temp of sensor in holzofen room
|-
| zhkVorlaufTimerTempAdjust|| (int) 0 || wird in VL zu desired-t addiert
|-
| zhkAussenTempActualVal|| (float) 0 || actual aussentemp sensor temperature value
|-
| zhkAussenTempTodayMax|| (float) 0 || aussentemp today's maximum temp
|-
| zhkVorlaufActualTempRL|| (float) 0 | RL readErr || cached actual rücklauf temperature
|-

|}

== Attributes ==
Alle Attributes sind auch in fhem durch das Kommando get attrHelp <varname> erklärt, für's "schnelle nachschauen zwischendurch".

{| class="wikitable sortable"
|-
! Attribute !! (Typ) Default !! Beschreibung
|-
| zhkBrennerTaktMinOnSec|| (int) 300 || brenner delay before set off after on-command
|-
| zhkBrennerAlwasTriggerWw|| (int) 1 || 1= always trigger Ww pump when burn starts
|-
| zhkAussenTempMaxAge|| (int) 1200 || max age of out-temp reading timestamp before ignore
|-
| zhkVorlaufTempTriggerFhemDevReading|| (string) desired || evtl.PID20 oder Notify-FhemDev für Mischeransteuerung
|-
| zhkVorlaufHkurveAussenMax_TH|| (int) 15 || max.wert für heizkurvenberechnung
|-
| zhkWwTaktMinOnSec|| (int) 60 || delay before off when WwPump started
|-
| zhkGlobalIncludeWwZeischaltplan|| (int) 1 || enable warmwasser timer module
|-
| autocontrol|| (int) 30 || initial delay after fhem start before ZHK starts running, needed to wait for temp sensors or other slow devices
|-
| zhkBrennerTaktMinOffSec|| (int) 30 || delay before set on
|-
| zhkGlobalIncludeVorlauf|| (int) 1 || enable vorlauf (general) module
|-
| zhkGlobalPollInterval|| (int) 10 || internal loop interval for recalc, increase if cpu load is too high
|-
| zhkGlobalIncludeAussentemp|| (int) 1 || enable aussentemp module
|-
| zhkKesselAbsoluteMaxTemp|| (int) 70 || sicherheit falls rechenprobleme
|-
| zhkKesselTempMaxReadingAge|| (int) 600 || max age of kessel temp reading, if too old device is not present or has error ->log alert
|-
| zhkAussenTempFhemDevReadingFallback|| (string) state || fhem dev reading aussentemp second (fallback or dummy)
|-
| zhkWwTimerScheduleSo|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufPumpOffFhemDev|| (string) P6_PumpOff || FhemDev das Vorlauf stromzufuhr pumpe kappt
|-
| zhkHolzofenAlphaUpAlarmDiffDeg|| (float) 3 || min.diff für abschaltung hot
|-
| zhkAussenTempFhemDevFallback|| (string) dummyOnlineWeatherTemp || fhem device aussentemp second (fallback or dummy)
|-
| zhkAussenTempIgnoreIfFhemDev|| (string) dummyDisableAussentemp || while state if this fhem device is true, disable aussentemp-calc temporarily
|-
| zhkWwAlphaThreshold|| (float) 0.42 || Meßtoleranz ww-temp °C
|-
| zhkHolzofenIgnoreTempIfFhemDev|| (string) dummyDisableHolzofen || zb. Window shutter, do not trigger if FhemDev state is true
|-
| zhkVorlaufTimerScheduleSo|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkKesselTempSecondFhemDevReading|| (string) temperature || device reading kesseltemperatur backup-device
|-
| zhkAussenTempAlarmThreshold|| (float) 1 || Mindestabweichung vom schaltpunkt für umschaltung
|-
| zhkHolzofenTempSensorMinAge|| (int) 300 || recalc alpha after seconds
|-
| zhkVorlaufTimerScheduleDo|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkAussenTempAlarmTempLimit|| (float) 16 || grundeinstellung AT schaltpunkt °C
|-
| zhkWwTimerScheduleMi|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufMischerPosFhemDevReading|| (string) position || heizkreis-mischer device reading für position
|-
| zhkWwTimerScheduleMo|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufMischerPosFhemDev|| (string) MischerPosition || heizkreis-mischer fhem device
|-
| zhkVorlaufHkurveVorlaufMin_TL|| (int) 20 || min.wert für heizkurvenberechnung
|-
| zhkGlobalIncludeKessel|| (int) 1 || enable kessel regler module
|-
| zhkWwTempSensorMaxAge|| (int) 300 || sensor ignorieren wenn state-age > x seconds
|-
| zhkVorlaufHkurveAussenMin_TL|| (int) -20 || min.wert für heizkurvenberechnung
|-
| zhkWwTempSensorFhemDev|| (string) 5_15_WarmWasser_EB6F98050000 || fhem device to read the temperature from
|-
| zhkHolzofenResetLowFhemDev|| (string) Heizg_Wohnzimmer1 || fhem device to read reset-low temp from
|-
| zhkWwBoostStartTemp|| (int) 45 || temp. ab der die umgehung notwendig ist
|-
| zhkHolzofenTempSensorFhemDev|| (string) 83_WohnZi_9554CD040000 || fhem device to read the temperature from
|-
| zhkAussenTempFhemDevReading|| (string) temperature || fhem dev reading aussentemp
|-
| zhkGlobalIncludeVorlaufZeischaltplan|| (int) 1 || enable vorlauf timer module
|-
| zhkKesselTempFhemDev|| (string) 4_14_Kessel_E3CD97050000 || fhem device kesseltemperatur
|-
| zhkHolzofenTempSensorReading|| (string) temperature || name of reading with float temp value
|-
| zhkWwTimerScheduleDi|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkWwTempSensorDefaultOnFailure|| (int) 70 || default temp to assume if temp-sensor fails
|-
| zhkWwAlphaUpAlarmDiffDeg|| (float) 5 || min.diff zu abschaltung hot für AlphaUp
|-
| zhkGlobalIncludeValvePositions|| (int) 1 || enable valve position correction module
|-
| zhkWwTimerScheduleFr|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufTimerScheduleMo|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkHolzofenTempSensorDefaultOnFailure|| (int) 20 || temp.default if sensor fail
|-
| zhkHolzofenResetLowFhemDevreading|| (string) desiredTemperature || fhem device reading to read reset-low temp from
|-
| zhkKesselVLRLdiffErhFaktor|| (float) 0 || erhöhungsfaktor: gewichtung VL-RL-diff für kesseltemp.einstellung
|-
| zhkAussenTempAlarmDelay|| (int) 600 || Trägheit AT schaltung seconds
|-
| zhkWwBoostFhemDev|| (string) P2_WwBoost || relais um analoge temperaturbegrenzug zu übergehen
|-
| zhkKesselTempSecondFhemDev|| (string) 0 || fhem device kesseltemperatur backup-device
|-
| zhkKesselMinDiffVorlauf|| (int) 10 || min.diff Vorlauf-Soll/Kessel-Min-Soll
|-
| zhkHolzofenAlphaThreshold|| (float) 0.07 || Meßtoleranz temp °C
|-
| zhkGlobalIncludeHolzofen|| (int) 1 || enable holzofen detection module
|-
| zhkVorlaufTimerScheduleSa|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufTimerScheduleFr|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkKesselThreshold|| (int) 5 || zulässige temp.schwankung kessel
|-
| zhkVorlaufTotalOnOffMischerDelay|| (string) 150 || delay to wait for mischer calibrate before VL off
|-
| zhkAussenTempIsWarmState|| (int) 0 || actual state, 1=warm 0=cold
|-
| zhkVorlaufRLTempFhemDevReading|| (string) temperature || fhem device reading, rücklauf temp
|-
| zhkKesselTempFhemDevReading|| (string) temperature || device reading kesseltemperatur
|-
| zhkWwTimerScheduleDo|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufTimerScheduleDi|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufVLTempFhemDevReading|| (string) temperature || fhem device reading, vorlauf temp
|-
| zhkVorlaufRLTempFhemDev|| (string) 2_12_Ruecklauf_56B897050000 || fhem device name, rücklauf temp
|-
| zhkKesselMinDiffWw|| (int) 8 || min.diff Ww-Soll/Kessel-Min-Soll
|-
| zhkVorlaufTempTriggerFhemDevSetting|| (string) desired || evtl.PID20 oder Notify-FhemDev für Mischeransteuerung
|-
| zhkWwAlphaDownAlarmDiffDeg|| (float) 0.8 || mindest-temp-diff für sofort-aufheizung
|-
| zhkBrennerFhemDev|| (string) P3_BrennerStop || brennerschalter, 0=burn 1=off
|-
| zhkVorlaufTimerScheduleMi|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkKesselAbsoluteMinTemp|| (int) 30 || sicherheit falls rechenprobleme
|-
| zhkWwTempSensorReading|| (string) temperature || name of reading with float temp value
|-
| zhkWwEcoTemp|| (float) 37 || tempvoreinstellung Eco-Modus
|-
| zhkKesselMischerErhFaktor|| (float) 0 || erhöhungsfaktor: gewichtung mischerposition für kesseltemp.einstellung
|-
| zhkGlobalIncludeWarmwasser|| (int) 1 || enable warmwasser module
|-
| zhkVorlaufMischerFhemDev|| (string) VorlaufMischer || zb STELLMOTOR FhemDev oder anderes Ventil
|-
| zhkVorlaufTempTriggerFhemDev|| (string) VorlaufRegler || evtl.PID20 oder Notify-FhemDev für Mischeransteuerung
|-
| zhkAussenTempFhemDev|| (string) 81_Aussen_D745CE040000 || fhem device aussentemp
|-
| zhkWwPumpFhemDev|| (string) P7_WwStop || WW pumpe, 0=on / 1=off
|-
| zhkVorlaufVLTempFhemDev|| (string) 1_17_Vorlauf_D1F798050000 || fhem device name, vorlauf temp
|-
| zhkVorlaufHkurveVorlaufMax_TH|| (int) 50 || max.wert für heizkurvenberechnung
|-
| zhkWwTimerScheduleSa|| (string) 0 || schaltpunkte für wochentagsplanung
|-
| zhkVorlaufIgnoreIfFhemDev|| (string) dummyDisableVorlauf || while state if this fhem device is true, disable vorlauf(general)-calc temporarily
|-
| zhkHolzofenResetLowTemp|| (float) 18 || temp für reset des state auf 0 (if no FhemDev)
|-
| zhkWwConfortTemp|| (int) 31 || tempvoreinstellung Confort-Modus
|-

|}

== Links ==
* [http://forum.fhem.de/index.php/topic,24021.0.html Thread im Forum], in dem dieses Modul vorgestellt wurde

[[Kategorie:Heizungssteuerung]]
== Request for Help ==
Jegliche zusätzliche Erklärung die über die - zugegeben etwas technisch orientierte- Grundfassung dieses Artikels hinausgeht, ist herzlich willkommen.
Bitte einfach den "Bearbeiten" Link oben anklicken und eigene Texte ungefragt einfügen. Dankeschön!

FHEM und FritzBox 7490

2014-08-12T20:57:07Z

Kamischi:

FHEM auf der Fritz!Box 7490 wird von AVM mit Firmware-Version 113.06.05 unterstützt. Es werden damit die Treiber (Kernelmodule) für USB Geräte wie CUL und EUL sowie verschiedene Dienste bereitgestellt, die FHEM benötigt.

== AVM Firmware mit FHEM ==
FHEM selbst ist als so genannte Labor-Firmware von AVM ''zusätzlich''zur Basis-Firmware zu installieren und verändert die Versionsnummer nicht. Die AVM Variante kann über updatefhem auf den aktuellen Stand nachgerüstet werden. Sie hat allerdings den Nachteil, dass FHEM in einer chroot Umgebung läuft, damit sind die Funktionen der Fritz!Box nicht direkt zugreifbar.

Die aktuellen Labor-Images können [http://www.avm.de/de/Service/Service-Portale/Labor/index.php hier] bezogen werden.

== Community Firmware mit FHEM ==
Eine etwas schlankere Variante von FHEM mit der Möglichkeit des direkten Zugriffs auf die Fritz!Box Funktionen steht unter [http://fhem.de/fhem-5.5-fb7390.image] zur Verfügung. Das IMAGE ist zwar für die FB 7390 gedacht, kann aber auch für die aktuellste FritzBox genutzt werden. (Alternative Images unter www.fhem.de/Download)

Auch diese Firmware-Image lässt sich über die Funktion "Firmware-Update" der Fritz!Box installieren:

* Menüpunkt System/Firmware-Update, dort den Reiter Firmware-Datei auswählen.
* Die passende Datei auswählen und mit "Update starten" bestätigen.
* Nach kurzer Zeit meldet sich die Fritz!Box mit der Warnung: "Die angegebene Datei enthält keine von AVM für dieses Gerät freigegebene Firmware."
* Hier mit "Update fortsetzen" bestätigen. Die Firmware wird installiert, der Vorgang schließt mit dem Neustart der Fritz!Box ab.
* Anschließend steht FHEM im Webbrowser unter "fritz.box:8083/fhem", und im Telnet Fenster unter "telnet fritz.box 7072" (Vorausgesetzt ist das Telenet zuvor aktiviert wurde) zur Verfügung.

== Externe Links ==
* [http://service.avm.de/support/de/SKB/FRITZ-Box-7490 AVM Support FAQ]
* [ftp://ftp.avm.de/fritz.box/fritzbox.7490/ AVM Firmware Repository]

== FB7490 einrichten - detaillierte Schritte ==
Sollten die o.g. Beschreibungen nicht ausreichen, hier eine detaillierte Beschreibung von Dirk070 aus dem Forum für die FB 7290 (siehe
[http://forum.fhem.de/index.php/topic,13337.msg82461.html#msg82461 hier])

== FB7390 fhem als root ==
Im fhem Verzeichnis startfhem in startfhem_orig oder ähnlich umbenennen. Dann die Datei startfhemAsRoot in startfhem umbenennen, Fritzbox neu starten und schon startet fhem als Root. 
Sollten diese Schritte nicht reichen, dann nach [[FritzBox Parameter in fhem anzeigen#Wichtig|dieser Anleitung]] vorgehen.

[[Kategorie:FritzBox]]

PID20 - Der PID-Regler

2014-08-12T20:56:01Z

Kamischi:

'''PID20''' ist ein Modul, das nach dem P-I-D Algorithmus einen Regler realisiert.

== Projekt-Status ==

Das Modul ist seit dem 26.03.2014 Bestandteil von FHEM.

== Features ==
* einstellbarer Bewertungs-/Berechnungszyklus
* Überwachung des Istwert-Gebers über dessen Zeitstempel (Sensorausfall)
* Skalierbarkeit der Ausgabehäufigkeit an das Stellglied über Zeit und Mindeständerung
* Zwangsausgabe an das Stellglied nach Ablauf eines einstellbaren Zeitintervalls
* Notstellung des Stellgliedes, falls Istwert-Geber ausgefallen ist
* Begrenzung des Stellbereichs nach oben und unten
* Festlegung der Nachkommastellen (0..5) des Ausgabewertes zum Stellglied
* Festlegen einer minimalen Regelabweichung, ab der der Regler aktiv wird
* Festlegen des Reading-Namens für den Sollwert
* Festlegen des Reading-Namens für den Istwert
* Invertierung des Reglerwirksinns
* Festlegen der minimalen Aktualisierungsrate der Readings
* Festlegen der Proportionalitätskonstanten P,I,D
== Thread im Forum ==
[http://forum.fhem.de/index.php/topic,17067.msg111615.html#msg111615 Diskussion zu PID20 im Forum]

=== Define ===
<code>
define <name> PID20 sensor[:reading[:regexp]] actor:cmd
</code>

=== Attribute ===
{| class="wikitable sortable"
|-
! Parameter !! Wertebereich !! Default !! Beschreibung
|-
|pidActorValueDecPlaces||[0..5]||0||Anzahl der Nachkommastellen für Ausgabewert zu Aktor
|-
|pidActorInterval||uint||180||minimale Wartezeit in Sekunden, bis eine neue Ausgabe an das Stellglied erfolgen kann
|-
|pidActorThreshold||uint||1||Notwendige minimale Änderung zum Altwert der Stellgliedausgabe, damit diese erneut erfolgt
|-
|pidActorErrorAction||[freeze, errorPos]||freeze||legt das Verhalten der Ausgabe zum Stellglied fest, wenn der Istwert nicht innerhalb von <pidSensorTimeout> aktualisiert wurde (Sensor-Ausfall) 
freeze: Position des Stellgliedes beibehalten 
ErrorPos: Position anfahren, die unter Attribut <pidActorErrorPos> angegeben ist."
|-
|pidActorErrorPos||int||0||Diese Position ist einzunehmen, wenn pidActorErrorAction auf errorPos steht und der Istwert-Geber ausgefallen ist.
|-
|pidActorKeepAlive||uint||1800||Spätestens nach dieser Zeit erfolgt eine Zwangsausgabe an das Stellglied
(wenn PID nicht disabled und nicht stopped)
|-
|pidActorLimitLower||float||0||untere Begrenzung für das Stellglied
|-
|pidActorLimitUpper||float||100||obere Begrenzung für das Stellglied
|-
|pidCalcInterval||uint||60||Berechnungszyklus in Sekunden, nach dem die PID-Berechnung durchgeführt wird.
|-
|pidDeltaTreshold||pos. float||0||wenn die Regeldifferenz(delta) kleiner als pidDeltaThreshold, dann wird der Regler eingefroren (state=idle)
|-
|pidDesiredName||string||desired||Name für das Reading, das den Sollwert für den Regler aufnehmen soll
|-
|pidMeasuredName||string||measured||Name für das Reading, das den Istwert für den Regler aufnehmen soll
|-
|pidSensorTimeout||uint||3600||Zeitlimit in Sekunden, nach dessen Überschreitung der Ausfall des Istwert-Gebers anzunehmen ist
|-
|pidReverseAction||[0,1]||0||Umgekehrter Wirksinn des Reglers
|-
|pidUpdateInterval||uint||300||Zeitlimit in Sekunden, nach der ein Zwangsupdate der Readings erfolgen muss (Kurvendarstellung).
|-
|pidFactor_P||pos. float||25||Proportionalitätskonstante für P-Anteil

|-
|pidFactor_I||pos. float||0.25||Proportionalitätskonstante für I-Anteil

|-
|pidFactor_D||pos. float||0||Proportionalitätskonstante für D-Anteil
|-
|disable||[0,1]||0||Freigabe/Sperren des Reglers
|}

=== Setter ===
'''desired'''
* Funktion: Sollwert einstellen
* Name des Setters kann vom Anwender über das Attribute "pidDesiredName" definiert werden

'''start'''
* PID nimmt den Betrieb wieder auf, es werden P-, I- und D-Anteil vor dem Stop übernommen

'''stop'''
* PID geht in den Zustand stopped; alles wird praktisch eingefroren

'''restart'''
* arbeitet zunächst wie Start, jedoch gibt man an, mit welchen Prozentwert der Stellausgang anfangs stehen soll

=== Readings ===
[[Datei:13 10 20 Pid readings.png]]
* actuation liefert den tatsächlichen Ausgabewert an das Stellglied
* actuationCalc liefert den internen Rechenwert des Ausgabewertes für das Stellglied(ohne Begrenzung)
* delta, die aktuelle Regeldifferenz
* desired (Name ist variabel), der Sollwert
* measured (Name ist variabel), der aktuelle Wert vom Istwert-geber
* p_p, der P-Anteil des Ausgabewertes für das Stellglied
* p_i, der I-Anteil des Ausgabewertes für das Stellglied
* p_d, der D-Anteil des Ausgabewertes für das Stellglied
* state, der Betriebszustand des Reglers

'''delta'''
<code>
delta = desired - measured (also Sollwert-Istwert)
</code>

'''actuation'''
<code>
actuation = actuationCalc
</code>
jedoch begrenzt durch pidActorLimitLower und pidActorLimitUpper
und formatiert via pidActorValueDecPlaces

'''actuationCalc'''

Der Ausgabewert für das Stellglied wird wie folgt berechnet

<code>
actuationCalc = p_p + p_i + p_d
</code>

'''state'''

{| class="wikitable"
|-
! state !! Erläuterung
|-
| disabled || PID-Instanz ist inaktiv
|-
| initializing || Modul wurde initialisiert
|-
| idle || Berechnung ist inaktiv
|-
| processing || Berechnung ist aktiv, Normalbetrieb
|-
| alarm || Ausnahmezustand, z.B. Timout des Istwert-Gebers
|}

== Inbetriebnahme ==
* PID20 definieren, hier mit HMS100TF als Istwert-Geber für die Temperatur und ein MAX-Thermostat als Stellglied; Auslegung für eine Fußbodenheizung (sehr träge)
<pre>define PID.FUBO PID20 DG.BAD.TF:temperature HT.FUBO:maxValveSetting</pre>
:* <sensor> = "DG.BAD.TF": Name des Istwert-Geber s (HMS100TF)
:* <reading> = "temperature": das Reading vom HMS100TF, das die Temperatur liefert
:* <regexp> = nicht definiert, wir können also direkt den Wert des Readings verwenden
:* <actor> = "HT.FUBO" : Name des MAX-Thermostats, das als Stellglied verwendet wird
:* <cmd> = "maxValveSetting" : Das Kommando mit dem PID20 die Stellausgabe realisieren soll
 
Letztlich wird mit <actor> und <cmd> Folgendes ausgeführt
<pre>set <actor> <cmd> <setting-value> </pre>

'''zusätzlich noch einige Attribute anpassen'''
* die Ausgabehäufigkeit an das Stellglied auf 15 Minuten begrenzen
<pre>attr PID.FUBO pidActorInterval 900</pre>
* nur dann einen Wert an das Stellglied ausgeben, wenn die Differenz zum Altwert >= 5%
<pre>attr PID.FUBO pidActorTreshold 5</pre>
* Nachommastellen für das Stellglied festlegen; MAX-Thermostate erlauben nur Werte ohne Nachkommastellen
<pre>attr PID.FUBO pidActorValueDecPlaces 0</pre>
* I-Faktor festlegen; Überlegung: bei einer Regelabweichung von 1 Grad, soll der I-Anteil um 0.2% pro Minute inkrementieren/dekrementieren
<pre>attr PID.FUBO pidFactor_I 0.2</pre>
* P-Faktor festlegen; Überlegung:Bei einer Regel-Abweichung von 1 Grad, soll der P-Anteil +/-50% betragen
<pre>attr PID.FUBO pidFactor_P 50</pre>

'''Chart einrichten''' 
Es ist für das Einstellen der Regel-Faktoren (P,I,D) überaus hilfreich, das Verhalten über die Zeit aufzuzeichnen, um das Verhalten objektiv beurteilen zu können. 

;Zunächst ein Filelog einrichten 
:define PID.PID.File FileLog ./log/PID.PID-%Y.log PID\.PID
:attr PID.PID.File logtype text

Danach ein Chart definieren, angelehnt an folgendem Beispiel:

[[Datei:13_12_03_PID_ChartDef.png]]

Anbei ein Vorschlag für au

== Hintergrund-Informationen ==
=== list <pid-name> ===
<code>
Internals:
DEF DG.BAD.TF PID.Actor:state
NAME PID.PID
NR 616
NTFY_ORDER 50-PID.PID
STATE processing
TYPE PID
Readings:
2013-10-20 17:13:41 actuation 97
2013-10-20 17:21:42 actuationCalc 97.2079999999999
2013-10-20 17:21:42 delta 0.199999999999999
2013-10-20 17:13:41 desired 22
2013-10-20 17:13:41 measured 21.8
2013-10-20 17:21:42 p_d 0
2013-10-20 17:21:42 p_i 92.2079999999999
2013-10-20 17:21:42 p_p 4.99999999999998
2013-10-20 17:21:42 state processing
Helper:
actor PID.Actor
actorCommand state
actorErrorAction freeze
actorErrorPos 0
actorInterval 300
actorKeepAlive 1800
actorLimitLower 0
actorLimitUpper 100
actorThreshold 4
actorTimestamp 2013-10-20 17:13:41
actorValueDecPlaces 0
calcInterval 60
deltaGradient 0
deltaOld 0.199999999999999
deltaOldTS 2013-10-20 17:18:07
deltaTreshold 0
desiredName desired
disable 0
factor_D 0
factor_I 0.25
factor_P 25
isWindUP 0
measuredName measured
reading temperature
regexp ([\d\.]*)
reverseAction 0
sensor DG.BAD.TF
sensorTimeout 3600
updateInterval 600
Attributes:
pidActorInterval 300
pidActorTreshold 4
pidActorValueDecPlaces 0
room PID
verbose 4

</code>

=== Anti-WindUp-Strategie ===
Der integrale Anteil des PID-Reglers wird ohne Gegenmassnahmen auch dann weiter integriert,
wenn das Stellglied bereits an seine Grenzen gestossen ist.
Dies hat den Nachteil, dass nach einer Reduzierung der Regeldifferenz lange Wartezeiten entstehen können, bis das
Stellglied reagiert.
Dies nennt man den WindUP-Effekt.
Hierzu wurde die folgende Strategie entwickelt:

[[Datei:13 10 20 PID Windup.png|WindUP]]

Sobald das rechnerische Stellsignal (Ventilstellung Calc=actuationCalc) die obere Grenze des Stellgliedes überschreitet (pidActorLimitUpper) oder die untere Grenze unterschreitet (pidActorLimitLower), wird die Integration des I-Anteils eingefroren.

'''Am Beispiel:'''
An Position L1 überschreitet der rechnerische Ausgabewert des Stellgliedes die obere Grenze (100%).
Der I-Anteil verändert sich nicht mehr bis zur Position L2. Hier unterschreitet der Ausgabewert die
obere Grenze, der I-Anteil kann wieder verändert werden.

== Fragen und Antworten ==
=== Temperatur im Raum steigt nicht oder stark verzögert, was kann ich tun ? ===

==== 1.Fehlerquelle : Heizsystem ist nicht ausreichend entlüftet ====
In diesem Fall behindern die Luftblasen im System den Durchfluss des Heizmediums. 
Der Heizkörper erwärmt sich nur teilweise oder "gluckert".
Hier ist das Entlüften der Heizkörper angesagt. 
Natürlich können sich die Gasblasen an anderer Stelle befinden.
Normalerweise sorgen automatische Entlüfter, dass das Gas entweichen kann. 
Aber auch diese "verkalken" im Lauf der Zeit.

==== 2.Fehlerquelle : Totzone beim Stellglied ====
Der Temperaturanstieg erfolgt erst ab einer bestimmten Ventilöffnung von xy%. 
Der PID-Regler geht davon aus, dass jede Änderung des Stellausgangs auf die Regelgröße wirkt 
(also bei Ventil weiter öffnen, wird mehr Wärme abgegeben) 
Ist dies nicht der Fall, wird der PID über die Zeit (I-Anteil) das Ventil weiter öffnen. 
Allerdings vergeht hierbei Zeit und damit leidet die Regelgüte. 

Es ist also wichtig die Totzone zu ermitteln und im Attribut pidActorLimitLower zu hinterlegen.

==== 3.Fehlerquelle : Hydraulische Fehlanpassung ====
Wenn einzelnen Heizkreise einen sehr kleinen hydraulischen Widerstand aufweisen, kann es passieren
das Heizkreise mit höherem Widerstand zeitweise unterversorgt sind. 
Erst wenn die gut versorgten Heizkreise die Ventile schließen (Soll-Temperatur ist erreicht),
werden die Heizkreise mit hohem Widerstand ausreichend versorgt. 
Dies kann man dank FHEM sehr gut über die Charts nachvollziehen. 
Es ist regelungstechnisch, ökologisch und energetisch absolut sinnvoll geregelte Hocheffizienz-Pumpen
im Heizkreis einzusetzen. Diese sorgen für konstanten Druck im Hauptstrang bei sehr geringen Energiebedarf. 

Man kann gezielt den hydraulischen Widerstand einzelner Thermostate erhöhen, indem man deren maximale Ventilöffnung begrenzt. 

Dies erreicht man durch Reduzieren des Wertes pidActorLimitUpper. 
Dies ist gleichbedeutend mit der Erhöhung der hydraulischen Widerstandes durch voreinstellbare Heizungsventile beim hydraulischen Abgleich.

== Weblinks ==

* [http://forum.fhem.de/index.php/topic,15060.0.html Initialer Forumseintrag zur Überarbeitung des PID-Moduls]
* [http://de.wikipedia.org/wiki/Regler Wikipedia Regler]

[[Kategorie:Glossary]]
[[Kategorie:Regelungstechnik]]

ReadingsGroup

2014-08-12T20:49:53Z

Kamischi:

{{SEITENTITEL:readingsGroup}}
{{Infobox Modul
|ModPurpose=Einfache zusammenfassende Darstellung von Informationen über mehrere Geräte
|ModType=h

|ModCmdRef=readingsGroup
|ModTechName=33_readingsGroup.pm
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=430 Andre / justme1968]}}
Das Fhem-[[:Kategorie:Hilfsmodul|Hilfsmodul]] [[readingsGroup]] bietet eine einfache Möglichkeit, ''readings'' und ''internal values'' von einem oder mehreren ''Devices'' darzustellen und flexibel zu formatieren.

Hier soll eine Sammlung von Beispielen zur Verwendung der ''readingsGroup'' mitsamt der zugehörigen Screenshots entstehen.

== Definition ==
Siehe commandref.

== Attribute ==
Weitergehende Erläuterungen zu einzelnen Attributen:

=== noheading ===
[[Datei:ReadingsGroup_noheading.png|mini|rechts|400px|ReadingsGroup: rechts mit "noheading" Attribut, links der anklickbare Titel]]
Das Attribut <code>noheading</code> führt dazu, dass der Alias der ReadingsGroup nicht mehr als Titel angezeigt wird. Das kann wünschenswert sein, wenn die ReadingsGroup auf einer [[Dashboard]]-Seite angezeigt werden soll, hat allerdings den Nachteil, dass die Detail-Ansicht der ReadingsGroup nicht mehr über einen Klick auf den Titel aufgerufen werden kann. Der Einstellungsdialog der ReadingsGroup ist dann nur noch (z. B.) über
* einen "Probably associated with"-Link eines anderen Objekts oder über
* manuelle Modifikation der URL eines anderen Objekts (<code>http:.../fhem?detail=<objektname></code>)
erreichbar.

== Beispiele ==
Achtung: Die Beispiele enthalten keine Maskierungen oder Verdoppelungen für ; und Zeilenende, sondern sind so angegeben, wie sie in Fhemweb, in der command box oder nach Klick auf DEF eingegeben werden. Beim manuellen Einfügen in eine [[Konfiguration|Konfigurationsdatei]] sind diese Maskierungen oder Verdoppelungen natürlich vorzunehmen.

=== Einfache Auswahl über Reading-Namen ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define battStatus readingsGroup .*:[Bb]attery</code>
| Alle readings mit Namen '''Battery''' oder '''battery''' von allen Devices.
| rowspan=3 | [[Datei:rgBattery.png|thumb]]
|-
| <code>attr battStatus alias FHT Batteriestatus </code>
| Der Alias wird als Zeilentitel verwendet
|-
| <code>attr battStatus mapping %ROOM </code>
| ''Mapping %ROOM'' führt dazu, dass der Raumname als Zeilentitel angezeigt wird.
|}

=== Auswahl über Reading-Namen, Status als Symbol dargestellt ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg_battery readingsGroup .*:battery</code>
| Alle readings mit Namen '''battery''' von allen Devices.
| rowspan=4 | [[Datei:rgBattery2.png|thumb]]
|-
| <code>attr rg_battery alias Batteriestatus </code>
| Der Alias wird als Überschrift verwendet
|-
| <code>attr rg_battery valueIcon {'battery.ok' => 'batterie', 'battery.low' => 'batterie@red'}</code>
| Statt der reading Werte "ok" und "low" soll ein Icon angezeigt werden.
|-
|<code>attr rg_battery commands { "battery.low" => "set %DEVICE replaceBatteryForSec 60" }</code>
| Für LaCrosse devices kann man beim Klick auf ein rotes "battery low icon" direkt replaceBatteryForSec setzen.
|}

=== Reading-Werte zuordnen (Icon / Text) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg readingsGroup Contact.Dachboden_gross:sensed.*</code>
| Alle sensedreadings des Contact.Dachboden_gross device.
| rowspan=4 | [[Datei:rgFenster.png|thumb]]
|-
| <code>attr rg mapping { 'sensed.A' => 'links', 'sensed.B' => 'rechts' }</code>
| Die Zuordnung rechts/links
|-
| <code>attr rg valueFormat {($VALUE eq '1')?"fts_window_roof":"fts_window_roof_open_2"}</code>
| Die Zuordnung von reading Wert zu Icon Namen.
|-
| <code>attr rg_battery valueIcon %VALUE </code>
| Statt des reading Werts soll ein Icon angezeigt werden.
|}

=== Formatvorgabe für Ausgabewerte ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define TempHygro readingsGroup TYPE=CUL_WS:temperature,humidity,dewpoint</code>
| Alle readings mit Namen '''temperature''', '''humidity''', '''dewpoint''' von allen Devices des Typs '''CUL_WS'''
| rowspan=4 | [[Datei:rgTemperatur.png|thumb|[[S300TH]]-Werte in einer readingsGroup]]
|-
| <code>attr TempHygro alias Temperatur / rel. Feuchte / Taupunkt</code>
| Der Alias der readingsGroup wird als Überschrift verwendet
|-
| <code>attr TempHygro mapping %ALIAS</code>
| ''Mapping %ALIAS'' führt dazu, dass der Alias des Geräts als Zeilentitel angezeigt wird.
|-
| <code>attr TempHygro valueFormat { temperature => "%.1f&deg;C", humidity => "%.1f %%", dewpoint => "%.1f&deg;C"}</code>
| Formatierung der Ausgabewerte. '''Achtung:''' "%" die in der Ausgabe erscheinen sollen, müssen verdoppelt werden!
|}

=== Ausgabestil (hier rechtsbündig) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Wetter readingsGroup WetterXXX:<%temp_temperature>,<Temperatur>,temperature WetterXXX:<%weather_humidity>,<Luftfeuchte>,humidity WetterXXX:<%weather_baraometric_pressure>,<Luftdruck>,pressure
</code>
| Die readings mit Namen '''temperature''', '''humidity''' und '''pressure''' vom Device WetterXXX jeweils mit einem Icon und einem Label davor.
| rowspan=3 | [[Datei:rgWetter.png|thumb]]
|-
| <code>attr Wetter valueFormat { temperature => '%1.f &deg;C', humidity => '%1.f %%', pressure => '%i mbar' }</code>
| Die Formatierung der Readingswerte
|-
| <code>attr Wetter valueStyle style="text-align:right"</code>
| Die Readings sollen rechtsbündig dargestellt werden.
|}

=== Internal Value ausgeben ===
Diese Beispiel könnte entfallen (nächstes Beispiel ist sehr ähnlich; es wird lediglich ein weiterer Wert ausgegeben).
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI</code>
| Den cul_RSSI Wert aller Devices die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau.
| rowspan=1 | [[Datei:rgculRSSI.png|thumb]]
|}

=== Internal Values ausgeben ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI,+cul_TIME</code>
| Den cul_RSSI Wert mit der zugehörigen Zeit aller Devices die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau. "Internal Values" werden durch das vorangestellte '''+''' (Pluszeichen) identifiziert.
| rowspan=1 | [[Datei:rgculRSSI2.png|thumb]]
|}

=== Alle Readings eines Gerätes, mit Ausnahme von... ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Systemstatus readingsGroup sysstat</code>
| Alle readings des sysstat Device
| rowspan=4 | [[Datei:rgSysstat.png|thumb]]
|-
| <code>attr Systemstatus nostate 1</code>
| Ohne state
|-
| <code>attr Systemstatus notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Systemstatus mapping {'load' => 'Systemauslastung', 'temperature' => 'Systemtemperatur in &deg;C'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|}

=== Anzeige auf einem Floorplan ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Heizung readingsGroup t(1|2|3):temperature</code>
| Die Temperatur readings der Devices t1, t2 und t3
| rowspan=6 | [[Datei:rgHeizung.png|thumb]]
|-
| <code>attr Heizung mapping {'t1.temperature' => 'Vorlauf', 't2.temperature' => 'R&ücklauf', 't3.temperature' => 'Zirkulation'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|-
| <code>attr Heizung nameStyle style="text-align:left"</code>
| Zeilentitel linksbündig wegen floorplan
|-
| <code>attr Heizung style style="font-size:20px;color:lightgray"</code>
| Großer Font und Farbe passend für den floorplan
|-
| <code>attr Heizung notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Heizung valueFormat : %.1f &deg;C</code>
| Doppelpunkt zwischen Zeilentitel und Wert, eine Nachkommastelle plus Einheit
|}

=== Schriftgrößen, Farben, Icons ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgVerbrauchPCA301.png|links|mini|400px|Schriftgröße, Farbe, Icons...]]
|-
| style="width:40%" |<code>define Verbrauch readingsGroup TYPE=PCA301:state,power,consumption</code>
| Die readings state, power und consumption aller [[PCA301 Funkschaltsteckdose mit Energieverbrauchsmessung|PCA301]] Devices mit einer Zeile pro Device.
|-
| <code>attr Verbrauch mapping %ROOM %ALIAS</code>
| Der Raumname und der Alias werden als Zeilentitel verwendet
|-
| <code>attr Verbrauch nameStyle style="font-weight:bold"</code>
| Der Zeilentitel soll fett sein
|-
| <code>attr Verbrauch style style="font-size:20px"</code>
| Alles in einem größeren Font
|-
| <code>attr Verbrauch valueFormat {power => "%.1f W", consumption => "%.2f kWh"}</code>
| Die Formatierung für die power und consumption readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr Verbrauch valueIcon { state => '%devStateIcon' }</code>
| Für die Dosen, die schaltbar sind, soll das anklickbare device icon gezeigt werden.
|-
|<code>attr Verbrauch valueStyle {($READING eq "power" && $VALUE > 40)?'style="color:red"':'style="color:green"'}</code>
|Wenn das power reading >40 ist, soll es in rot angezeigt werden, alle anderen Werte und readings in grün
|}

=== Wertabhängige Farbgebung ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:TemperaturenRG.png|600px|mini|links|Wertabhängige Farben]]
[[Datei:TemperaturenRG2.png|600px|mini|links|Andere Werte - andere Farben]]
|-
| style="width:40%" |<code>define wzTemperaturenRG readingsGroup Aussen:,<Temperatur>,temperature,<Luftfeuchte>,humidity Wohnzimmer:,<Temperatur>,temperature,<Luftfeuchte>,humidity Kasten_E_Geraete:,<Temperatur>,temperature,<Luftfeuchte>,humidity</code>
| Die readings temperatur und humidity der Devices Aussen, Wohnzimmer und Kasten_E_Geraete in einer Zeile pro Device.
|-
| <code>attr wzTemperaturenRG group 3. Temperaturen</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzTemperaturenRG noheading 1</code>
| noheading
|-
| <code>attr wzTemperaturenRG nostate 1</code>
| nostate
|-
| <code>attr wzTemperaturenRG notime 1</code>
| notime
|-
| <code>attr wzTemperaturenRG valueFormat {temperature => "%.1f °C", humidity =>"%.1f %%" }</code>
| Die Formatierung für die temperatur und humidity readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr wzTemperaturenRG valueStyle { if($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 20) { 'style="color:orange"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE < 5) { 'style="color:blue"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 23) { 'style="color:red"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 21) { 'style="color:orange"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE < 20) { 'style="color:blue"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 28) { 'style="color:orange"'}elsif($READING eq "humidity" && $VALUE > 65) { 'style="color:red"'}elsif($READING eq "humidity" && $VALUE > 60) { 'style="color:orange"'}else{'style="color:green"'} }</code>
| Diverse Farbkombinationen sind möglich
|}

=== Enigma Receiver ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:ReceiverRG.jpg|600px|mini|links|Wertabhängige Farben]]
[[Datei:ReceiverRGmute.jpg|600px|mini|links|Wertabhängige Farben]]
|-
| style="width:40%" |<code>define wzReceiverRG readingsGroup wzReceiver:,<Aktuell>,eventtitle,<Rest>,eventremaining_hr,<Dauer>,eventduration_hr wzReceiver:<Beschreibung>,eventdescription wzReceiver:,<Nächste>,eventtitle_next,<Start>,eventstart_next_hr,<Dauer>,eventduration_next_hr wzReceiver:,<HDD Kapazität>,hdd1_capacity,<Frei>,wzReceiver:hdd1_free wzReceiver:,<Lautstärke>,volume,<HDD>,hdd1_capacity,<Frei>,hdd1_free</code>
| Mehrere readings des Device wzReceiver in mehreren Zeilen. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke, mute angezeigt. Farbige Anzeige des freien Speicherplatzes
'''Benötigt:''' ENIGMA2 Receiver, 70_ENIGMA2.pm - Siehe: [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern]]
|-
| <code>attr wzReceiverRG group Fernseher Receiver</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzReceiverRG mapping &nbsp;</code>
| mapping wird auf &nbsp; (Leerzeichen) gesetzt, damit der Device Name nicht angezeigt wird
|-
| <code>attr wzReceiverRG noheading 1</code>
| noheading
|-
| <code>attr wzReceiverRG nostate 1</code>
| nostate
|-
| <code>attr wzReceiverRG notime 1</code>
| notime
|-
|-
| <code>attr wzReceiverRG valueColumns { eventdescription => 'colspan="4"' }</code>
| Die Beschreibung soll über 4 Spalten gehen
|-
| <code>attr wzReceiverRG valueFormat { wzReceiverRGvalueFormat($DEVICE,$READING,$VALUE);; }</code>
| Die Formatierung wird in die 99_myUtils.pm ausgelagert. Siehe: [[99 myUtils anlegen]]
|-
|<code>attr wzReceiverRG valueStyle { if($READING eq "hdd1_free" && $VALUE < 200){ 'style="color:red"' }elsif( $READING eq "hdd1_free" && $VALUE < 500 ){ 'style="color:orange"' }elsif( $READING eq "volume" && ReadingsVal($DEVICE, "mute", "") eq "on" ){ 'style="color:red"' }else{ 'style="color:green"' } }</code>
| Diverse Farbkombinationen sind möglich. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke mute angezeigt.
|-
| <code>
sub wzReceiverRGvalueFormat($$$)
{
my ($DEVICE,$READING,$VALUE) = @_;

if($READING eq 'hdd1_capacity') {
return "%.2f MB";
} elsif( $READING eq 'hdd1_free') {
return "%.2f MB";
} elsif( $READING eq 'volume' ) {
if( ReadingsVal($DEVICE, "mute", "") eq "on") {
return "mute";
} else {
return "%i %%";
}
}
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]
|}

=== Heizungswerte inklusive Batterie- und Fensterstatus ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung3.png|thumb|links|500px|Heizungswerte inklusive Batterie- und Fensterstatus]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<%18>,<%20>,<%22>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte commands { 'Heizungswerte.18' => 'set $DEVICE desired-temp 18', 'Heizungswerte.20' => 'set $DEVICE desired-temp 20', 'Heizungswerte.22' => 'set $DEVICE desired-temp 22' }</code>
| Die Links/Kommandos die hinter den 18, 20 und 22 liegen sollen.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte inklusive Ventilposition ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:Rg_Heizung_Valveposition.png|thumb|links|500px|Heizungswerte inklusive Statusinformationen (MAX!)]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,<Ventil>,<Soll>,<Ist>,<MaxV>,<GID>,<Mode>,<Batterie> type=CUL_HM:ValvePosition,desired-tempe,measured-temp,R-valveMaxPos,groupid,mode,battery</code>
| Diverse readings aller Devices des Typs MAX.
|-
| <code>attr Heizungswerte mapping %ROOM</code>
| Die Raumnamen werden angezeigt.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb (fett) sein.
|-
| <code>attr Heizungswerte room Heizung</code>
| Die "readingsgroup" wird dem Raum "Heizung" zugeordnet.
|-
| <code>attr Heizungswerte valueFormat {temperature => "%.0f °C", desiredTemperature => "%.0f °C", valveposition =>"%.0f %%",maxValveSetting =>"%.0f %%" }</code>
| Es wird noch die Einheit °C hinter den Temperaturwerten angezeigt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batteriezustand werden Icons anstatt Klartextwerte genommen!
|-
| <code>attr Heizungswerte valueStyle { if($READING eq "temperature" && $VALUE > 20){ 'style="color:green;;font-weight:bold"' }elsif( $READING eq "temperature" && $VALUE <= 20 ){ 'style="color:blue"' }elsif( $READING eq "temperature" && $VALUE > 23 ){ 'style="color:red"' }else{ 'style="color:gray"' } }</code>
| Die Temperaturwerte werden abhängig vom Wert farbig dargestellt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte, Status und Regelmöglichkeit ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung2.png|thumb|500px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define Heizungswerte2 readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<{myUtils_HeizungUpDown($DEVICE,"up")}@desired-temp>,desired-new,<{myUtils_HeizungUpDown($DEVICE,"down")}@desired-temp>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte2 nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte2 valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|-
| <code>attr Heizungswerte2 valueStyle {($VALUE eq "00")?'style="visibility:hidden"':''}</code>
| Nach dem Einstellen den Wert wieder ausblenden.
|-
| <code>
#Heizung regeln in readingsGroup
sub
myUtils_HeizungUpDown($$)
{
my($DEVICE,$CMD) = @_;

my $icon = $CMD;
my $VALUE = ReadingsVal($DEVICE,"desired-new","20" );
$VALUE = ReadingsVal($DEVICE,"desired-temp","20" )
if( !$VALUE || $VALUE == 0 );
my $link;

if( $CMD eq "up" ) {
$icon = "control_arrow_upward";
$VALUE += 1;

if( $VALUE <= 24 ) {
$icon .= "\@red";
$link = "setreading $DEVICE desired-new $VALUE";
}
} elsif( $CMD eq "down" ) {
$icon = "control_arrow_downward";
$VALUE -= 1;

if( $VALUE >= 18 ) {
$icon .= "\@blue";
$link = "setreading $DEVICE desired-new $VALUE";
}
}

my $notify = "notifyHeizungUpDown";
if( !defined($defs{$notify}) ) {
CommandDefine(undef,
"$notify notify .*:desired-new.* "
."{ myUtils_HeizungUpDownNotify(\$NAME,\$EVTPART1); }" );
}

my $ret = "%$icon";
$ret .= "%$link" if( $link );

return $ret;
}
sub
myUtils_HeizungUpDownNotify($$)
{
my($DEVICE,$VALUE) = @_;

return if( $VALUE == 0 );

my $at = "triggerHeizungUpDown_$DEVICE";
CommandDelete(undef, $at) if( defined($defs{$at}) );
CommandDefine(undef,
"$at at +00:00:03 "
."{my \$v = ReadingsVal(\"$DEVICE\",\"desired-new\",undef);"
."fhem(\"set $DEVICE desired-temp \$v\") if( \$v );"
."fhem(\"setreading $DEVICE desired-new 00\");}" );

return undef;
}
</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit werden die Icons zum Ändern der gewünschten Temperatur dargestellt und im Bereich >=18 und <= 24 Grad anklickbar gemacht. Zwischen den Pfeilen wird der gerade eingestellte Wert angezeigt. Wenn dieser drei Sekunden nicht mehr geändert wurde wird die desired-temp auf diesen Wert gesetzt und die Anzeige zwischen den Pfeilen ausgeblendet.
|}

=== Readings aus zusätzlichen Devices ===
Im folgenden Beispiel wird gezeigt wie sich Readings zusätzlicher Devices zu einer Zeile mit mehreren Readings hinzufügen lassen. Diese zusätzlichen Devices können z.b. die unterschiedlichen Channel eines HomeMatic Gerätes sein. Im folgenden Beispiel wird der Name des zugehörigen Geräts dynamisch bestimmt.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung4.png|thumb|500px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define myTemp readingsGroup <Raum>,<Tist>,<Tsoll>,<Mode>,<Tnight>,<Tday>,<Hum>,<BatTC>,<Vist>,<Vsoll>,<Verr>,<BatVD> Thermostat.(WZ|OZ|AZ|Bad|Kueche|SZ|GZ|Bad.OG):measured-temp,desired-temp,controlMode,night-temp,day-temp,humidity,battery,ValvePosition@{valveOfDevice($DEVICE)},ValveDesired@{valveOfDevice($DEVICE)},R-valveErrorPos@{valveOfDevice($DEVICE)},battery@{valveOfDevice($DEVICE)} Broetje:ToutIst </code>
| Diverse Readings aller Thermostat Devices und des jeweils zugehörigen Ventilantriebs.
|-
| <code>attr myTemp mapping { 'Broetje' => 'Garten','Thermostat.AZ' => 'EG Arbeitszimmer','Thermostat.SZ' => 'OG Schlafzimmer','Thermostat.WZ'=>'EG Wohnzimmer','Thermostat.Kueche' => 'EG Küche','Thermostat.GZ' => 'OG Gästezimmer','Thermostat.Bad' => 'EG Bad','Thermostat.Bad.OG' => 'OG Bad','Thermostat.OZ' => 'EG Kaminzimmer','desired-temp' => <nowiki>''</nowiki> }</code>
| Die Benennung der Zeilentitel (Das ist je nach Konfiguration auch über $ALIAS und/oder $ROOM lösbar).
|-
| <code>attr myTemp commands { 'desired-temp' => 'desired-temp:' }</code>
| desired-temp soll per dropDown einstellbar sein.
|-
| <code>attr myTemp nameStyle style="color:yellow"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr myTemp valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batteriestand sollen jeweils Icons angezeigt werden.
|-
| <code>attr myTemp valueFormat { 'measured-temp' => "%0.1f &deg;C",'ToutIst' => "%.1f &deg;C",'night-temp' => "%.1f &deg;C",'day-temp' => "%.1f &deg;C",'humidity' => "%.0f
%%",'ValvePosition' => "%.0f %%",'ValveDesired' => "%.0f %%",'R-valveErrorPos' => "%.0f %%" }</code>
| Die Formatierung der Werte.
|-
| <code>
#namen des ventil device aus thermostat device ableiten
sub valveOfDevice ($) {
my ($DEVICE) = @_;

if ($DEVICE =~ m/AZ/) {
return "Ventil.".substr($DEVICE,11).".Nord";
} else {
return "Ventil.".substr($DEVICE,11);
}
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hier wird aus dem Namen des Thermostaten der Name des zugehörigen Ventilantriebs abgeleitet.
|}
Da im {...} Teil des <reading>@<device> Arguments keine Leerzeichen oder Kommas vorkommen dürfen ist er in der Regel das Einfachste die Funktionalität wie in diesem Beispiel in eine eigene Routine auszulagern. Mit ein paar 'Tricks' lässt es sich aber manchmal auch ohne Leerzeichen oder Kommas lösen und dann direkt in die Definition schreiben:<code>...,ValvePosition@{$DEVICE=~s/Thermostat/Ventil/;$DEVICE;},...</code>

=== Dynamische Inhalte ===
[[Datei:rgDynamic-1.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 1]]
[[Datei:rgDynamic-2.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 2]]
Es ist möglich, den in einer readingsGroup dargestellten Inhalt dynamisch von zusätzlichen Bedingungen abhängig zu machen. Im folgenden Beispiel lässt sich
einstellen, dass nur die Devices angezeigt werden, die einen bestimmten Zustand (hier: on/off, open/tilted/closed) haben. Hier wird zum Umschalten ein dummy, der direkt über der readingsGroup dargestellt wird, verwendet. Über das links und/oder commands lässt sich auch eine Darstellung erzeugen, bei der das Umschalten direkt innerhalb der readingsGroup möglich ist.

<pre>
define LXrg dummy
attr LXrg group -
attr LXrg setList mode1:on,off mode2:open,closed,tilted
attr LXrg stateFormat 1=mode1 2=mode2
attr LXrg webCmd mode1:mode2

define rg readingsGroup Window.*:state Light.*:state
attr rg group -
attr rg valueFormat { return $VALUE if ( $VALUE eq ReadingsVal("LXrg","mode1","") || $VALUE eq ReadingsVal("LXrg","mode2","") );; return undef;;}

define Watch_LX notify LX.*:.* {my $value = ReadingsVal($NAME,'state','');;;;fhem("setreading $NAME $value")}
</pre>

=== Enable/Disable Button am Beispiel eines WeekdayTimer ===
Dieses Beispiel zeigt die Anwendung einer readingsGroup, um im Frontend einen Enable/Disable Button für ein Objekt darzustellen. Für den WeekdayTimer gibt es hier spezielle Erweiterungen (set Routinen, um das disable Attribut zu setzen, Reading "disabled"). Es gibt aber auch eine allgemeinere Variante (siehe [http://forum.fhem.de/index.php/topic,23655.msg169141.html#msg169141 diesen Forumsbeitrag]) für alle Objekte, die das FHEM Attribut "disable" unterstützen.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rg_scheduling.png|thumb|500px|links|Enable/Disable Button]]
|-
| style="width:40%" |<code>define rg_Timer_Wasser readingsGroup timer_Wasser_..:disabled,+DEF,<{rg_timer_Wasser_show_conditional($DEVICE,"nextUpdate")}@disabled>,<{rg_timer_Wasser_show_conditional($DEVICE,"nextValue")}@disabled></code>
| Definition der angezeigten Readings. Das Reading disabled wird mit den u.a. Attributen zum Button, +DEF zeigt die Definition, d.h. die Schaltzeiten, des Timers an. Die Readings nextUpdate und nextValue sollen nur angezeigt werden, falls der Timer aktiv ist. Hierfür sorgt eine Routine <code>rg_timer_Wasser_show_conditional</code>, die in der 99_myUtils.pm definiert wird. Das abschließende @disabled sorgt dafür, daß der LongPoll Mechanismus die Anzeige sofort ändert, wenn der Button betätigt wird.
|-
| <code>attr rg_Timer_Wasser valueFormat { if ( $READING =~ m/.*DEF/ ) { my @text = split(" ", $VALUE); shift @text; return join(" ", @text) }}</code>
| Der Name des Timers wird aus dem interal Reading "+DEF" vorne abgeschnitten. Damit werden nur die definierten Schaltpunkte angezeigt.
|-
| <code>attr rg_Timer_Wasser valueIcon { 'disabled.0' => 'Restart', 'disabled.1' => 'Shutdown' }</code>
| Die beiden Zustände für den Button werden durch zwei Standard-Icons angezeigt.
|-
| <code>attr rg_Timer_Wasser commands { 'disabled.0' => 'set $DEVICE disable', 'disabled.1' => 'set $DEVICE enable' }</code>
| Toggle-Funktion für den Button. Wenn der Timer aktiv ("disabled.0") sorgt ein Klick auf den Button, dass der Timer deaktiviert wird ("set $DEVICE disable").
|-
|<code>
sub rg_timer_Wasser_show_conditional($$)
{
my ($DEVICE,$READING) = @_;
return ( ReadingsVal($DEVICE, "disabled", "1") eq "0" )?
ReadingsVal($DEVICE, $READING, "reading_undef") : "disabled";
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit wird das übergebene Reading des Timers nur angezeigt, wenn der Timer aktiv ist. Andernfalls wird der String "disabled" stattdessen angezeigt.
|}

== Links und Trigger ==
[[Datei:rgPCA-detail.png|mini|400px|readingsGroup mit Link]]
Das PCA301 Beispiel oben lässt sich mit einem ans Ende des define angehängten
:<code><{appendTrigger($DEVICE,"clear","Alle löschen")}></code>
und der folgenden appendTrigger Definition in 99_myUtils.pm um einen Link erweitern, der ein Event auslöst, an das z.B. ein notify gehängt werden kann, um die Verbrauchszähler der PCA301 Dosen zurückzusetzen.
:<code>define clearVerbrauch notify Verbrauch:clear set TYPE=PCA301 clear</code>

<pre>use vars qw($FW_ME);
use vars qw($FW_subdir);
sub
appendTrigger($$$)
{
my ($name,$trigger,$label) = @_;

my $ret .= "</table></td></tr>";

my $link = "cmd=trigger $name $trigger";
my $txt = "<a onClick=\"FW_cmd('$FW_ME$FW_subdir?XHR=1&$link')\">$label</a>";
$ret .= "<td colspan=\"99\"><div style=\"cursor:pointer;color:#888888;text-align:right\">$txt</div></td>";

return ($ret,0);
}</pre>

Ein weiteres Beispiel für 'custom links und trigger' findet sich im [http://forum.fhem.de/index.php/topic,14425.msg109383.html#msg109383 Forum]: dort wird damit eine readingsGroup dynamisch umgeschaltet, um nur die eingeschalteten, nur die ausgeschalteten oder alle Lampen anzuzeigen.

== Sonstiges ==
In der Regel werden die Parameter zu einem reading in den mappings unter <$DEVICE> und dann <$DEVICE>.<$READING> und dann unter <$READING>.<$VALUE> gesucht.

===Lesbar machen===
Für die meisten Attribute gilt:

*Wenn es komplexer wird ist es einfacher den Code in eine sub in 99_myUtils auszulagern und diese aufzurufen:
<code> attr <name> valueStyle {myValueToFormat($READING,$VALUE)}</code>

*code für unterschiedliche readings kann man auch im mapping schon aufteilen:
<code>attr <name> valueStyle { SuperE5 => '{perl code}', Diesel => '{perl code}' }</code>

*Ifs lassen sich verschachteln und sortieren. So kann die Anzahl der Klammern und Else-Zweige reduziert werden:
<code>if( $READING eq ... ) {
return xxx if( $VALUE < 1 );
return yyy if( $VALUE < 1.5 );
return zzz;
} elsif( $READING eq ... ) {
...
}</code>

Da alles lässt sich natürlich auch kombinieren und so viel lesbarer machen als ein einziger langer Bandwurm.

===group===
Wenn der doppelte Rahmen um eine readingsGroup in eine group stört, lässt er sich mit dem passenden style entfernen:
<code>attr <device> style style="border:0px;background:none;box-shadow:none"</code>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

CUL ueber Netz

2014-08-12T20:39:06Z

Kamischi:

Da bei mir [[RFR CUL]] sehr instabil lief, WLAN aber zufriedenstellend, habe ich einen Buffalo WZR-HP-G300NH mit OpenWRT Backfire (10.03.1-rc4) ausgestattet, als WLAN-Client konfiguriert und den CUL am USB-Port betrieben.

Um den CUL als Quasi-CUN über FHEM anzusprechen, läuft folgendes Script auf dem Router:
#!/bin/sh

DEV=/dev/ttyACM0

while (true)
do
/usr/bin/socat -ly -lh GOPEN:$DEV,raw,echo=0 TCP-LISTEN:2323
sleep 2
done

Zu beachten ist, dass socat in der mitgelieferten Version (1.6.0.1-2) für o.g. Zweck nicht funktioniert. Man kann aber eine neuere Version (1.7.1.3-2) von http://downloads.openwrt.org/snapshots/trunk/ar71xx/packages/ herunterladen und installieren.

Die Konfiguration in fhem ist einfach:

define cul868 CUL <name-des-geräts>:2323 <fhtid>
attr cul868 model CUL

Anstelle von socat kann man im Notfall auch netcat benutzen. Dazu im Script die Zeile mit socat durch

netcat -l -p 2323 < $DEV >$DEV

ersetzen. Allerdings gab es dann häufig Probleme mit der Echo-Einstellung, so dass mehrere Anläufe erforderlich waren, bis es nach einen Reboot stabil läuft.

[[Kategorie:Other Components]]
[[Kategorie:CUL]]
[[Kategorie:Glossary]]

Licht dimmen mit Bewegungsmelder und Taster

2014-08-12T20:37:56Z

Kamischi:

== Aufgabe: ==
Ein Flurlicht soll gedimmt werden per Bewegungsmelder (FS20 PIRI) mit 50% Lichtstärke.

Zum Schuheanziehen im Flur soll das Licht aber per Taster auf 100% geschaltet werden können. Der Bewegungsmelder springt aber nur an zwischen 7 und 20 Uhr.

Die Schwierigkeit besteht darin, dass die z. B. minütlich kommende Meldung vom Bewegungsmelder nicht wieder auf 50% runterdimmt.

== Script ==
<nowiki>define flur_licht FS20 a875 10
attr flur_licht model fs20di
attr flur_licht follow-on-for-timer 1
#Flurlicht auf hell schalten Taster
define flur_s4_hell FS20 a875 62
define n_flur_s4_hell notify flur_s4_hell:.* { \
{fhem("set flur_licht dim100%%")};;\
{fhem("set flur_licht on-old-for-timer 120")};;\
}
####Bewegungsmelder#######
define flur_bewegung FS20 a875 00
attr flur_bewegung model fs20piri
define n_flur_bewegung2 notify flur_bewegung:.* { \
Log 3, "@: flur_licht ".Value("flur_licht");;\
my $mzstate=Value("flur_licht");;\
if ($hour >= 7 && $hour <= 20) {\
if ($mzstate eq "off"){\
{fhem("set flur_licht dim50%%")}\
}\
{fhem("set flur_licht on-old-for-timer 120")}\
}\
}</nowiki>

==== Erläuterungen: ====
Taster und Bewegungsmelder schalten das Licht ein mit on-old-for-timer 120 - also für 2 Minuten auf der vorher eingestellten Helligkeit und danach schaltet der Dimmer automatisch ab.

Um Abfragen zu können, ob die Lampe aus ist, ist der Parameter follow-on-for-timer beim Dimmer wichtig, damit der Status wie der Dimmer verhält und nach dem 2 Minuten auf off geht.

Der Bewegungsmelder darf als nur auf die 50% schalten, wenn das licht schon aus war - ansonsten darf er nur die Einschaltzeit verlängern, damit das Licht auf 100% bleibt, solange noch jemand im Flur ist.

Der Taster hingegen darf IMMER sofort das licht auf 100% setzen ohne Abfrage.

Beim Bewegungsmelder kann und sollte man übrigens die Zeit bis zur nächsten Meldung sinnvoll einstellen - diese zeit muss kürzer sein als die Dauer mit der das Licht auf "ein" steht, damit das
[[Kategorie:Code Snippets]]

FHT-ID der FHZ1300 herausfinden

2014-08-12T20:35:58Z

Kamischi:

Wenn man seine FHZ1300PC (oder andere FHZ1X00 Zentralen) durch [[CUL]] ersetzen möchte und keine Lust hat, alle FHT80b-Geräte neu an die Zentrale anzulernen, kann man dem CUL die selbe FHT-ID geben, die bisher die FHZ1300 hatte.

Wie kann man diese herausfinden?

Man schließt den CUL an, stellt ihn mit

<nowiki>set myCUL raw X61</nowiki>
so ein, dass er die Protokollnachrichten weiterleitet, definiert möglichst alle seine FHT80b-Geräte und sucht im Log nach Nachrichten der Form

<nowiki>2008-09-28 13:22:47 FHT wz FHZ:can-xmit: 97</nowiki>
Statt can-xmit kann man auch nach start-xmit oder can-rcv sehen.

Die beiden angezeigten Ziffern werden nach Hex umgerechnet (61) und als die ersten beiden Stellen der FHT-ID verwendet. Die letzten beiden Stellen sind beliebig. Im Beispiel müsste der Eintrag dann lauten:

<nowiki>define myCUL CUL 6101</nowiki>
Auf einem Testsystem kann man bspw. folgende Konfigurationsdatei discover-hc.conf verwenden

<nowiki>attr global logfile -
attr global verbose 5
attr global port 7072 global
attr global modpath /path/to/fhem
define myCUL CUL /dev/ttyACM0 0000
set myCUL raw X61
# alle FHT80b-Geräte hier aufführen
define myFHT1 FHT abcd
define myFHT2 FHT 1234
...</nowiki>
und mit

<nowiki>fhem discover-hc.conf</nowiki>
starten.

Wichtig: Anschliessend keinesfalls CUL/CUN und FHZ1X00 parallel betreiben, da die FHT Kommunikation sonst gestört ist.

=== siehe auch ===
[[Was ist der Hauscode?]]

[[Kategorie:HOWTOS]]

FHEM und FritzBox 7390

2014-08-12T20:35:02Z

Kamischi:

FHEM auf der Fritz!Box 7390 wird von AVM ab Firmware-Version 84.05.05 unterstützt. Es werden damit die Treiber (Kernelmodule) für USB Geräte wie CUL und EUL sowie verschiedene Dienste bereitgestellt, die FHEM benötigt.

== AVM Firmware mit FHEM ==
FHEM selbst ist als so genannte Labor-Firmware von AVM ''zusätzlich''zur Basis-Firmware zu installieren und verändert die Versionsnummer nicht. Die AVM Variante kann über updatefhem auf den aktuellen Stand nachgerüstet werden. Sie hat allerdings den Nachteil, dass FHEM in einer chroot Umgebung läuft, damit sind die Funktionen der Fritz!Box nicht direkt zugreifbar.

Die aktuellen Labor-Images können [http://www.avm.de/de/Service/Service-Portale/Labor/index.php hier] bezogen werden.

== Community Firmware mit FHEM ==
Eine etwas schlankere Variante von FHEM mit der Möglichkeit des direkten Zugriffs auf die Fritz!Box Funktionen steht unter [http://fhem.de/fhem-5.5-fb7390.image] zur Verfügung. (Alternative Images unter www.fhem.de/Download)

Auch diese Firmware-Image lässt sich über die Funktion "Firmware-Update" der Fritz!Box installieren:

* Menüpunkt System/Firmware-Update, dort den Reiter Firmware-Datei auswählen.
* Die passende Datei auswählen und mit "Update starten" bestätigen.
* Nach kurzer Zeit meldet sich die Fritz!Box mit der Warnung: "Die angegebene Datei enthält keine von AVM für dieses Gerät freigegebene Firmware."
* Hier mit "Update fortsetzen" bestätigen. Die Firmware wird installiert, der Vorgang schließt mit dem Neustart der Fritz!Box ab.
* Anschließend steht FHEM im Webbrowser unter "fritz.box:8083/fhem", und im Telnet Fenster unter "telnet fritz.box 7072" zur Verfügung.

== Externe Links ==
* [http://service.avm.de/support/de/SKB/FRITZ-Box-7390 AVM Support FAQ]
* [ftp://ftp.avm.de/fritz.box/fritzbox.fon_wlan_7390/ AVM Firmware Repository]

== FB7390 einrichten - detaillierte Schritte ==
Sollten die o.g. Beschreibungen nicht ausreichen, hier eine detaillierte Beschreibung von Dirk070 aus dem Forum (siehe
[http://forum.fhem.de/index.php/topic,13337.msg82461.html#msg82461 hier])

== FB7390 fhem als root ==
Im fhem Verzeichnis startfhem in startfhem_orig oder ähnlich umbenennen. Dann die Datei startfhemAsRoot in startfhem umbenennen, Fritzbox neu starten und schon startet fhem als Root. 
Sollten diese Schritte nicht reichen, dann nach [[FritzBox Parameter in fhem anzeigen#Wichtig|dieser Anleitung]] vorgehen.

[[Kategorie:FritzBox]]

SONOS

2014-08-12T20:33:08Z

Kamischi:

Dieses Anwendungsbeispiel soll den Einstieg in die Steuerung der heimischen Zoneplayer der Firma [http://www.sonos.com Sonos] erleichtern. Es werden die Verwendung und Einrichtung der dazugehörenden Module '''SONOS''' und '''SONOSPLAYER''' beschrieben, und einige Beispiele für eine mehr oder weniger sinnvolle Nutzung von Events und Steuerungsmöglichkeiten gegeben.
Sollte etwas fehlen oder unklar sein, dann einfach eine kurze Nachricht an den Autor.

<div style="margin: 0; margin-top:10px; border: 1px solid #dfdfdf; padding: 0 1em 1em 1em; background-color:#fff0e0;">
<center>'''! Achtung !'''</center>
Diese Module sind '''nicht''' im offiziellen Release von FHEM enthalten. Sie müssen mittels des Thirdparty-Updatemechanismus nachinstalliert werden.
Dabei sind trotzdem die Vorbedingungen bzgl. der Perl-Installation einzuhalten, da diese Update-Installation nur im Rahmen von FHEM erfolgt.
</div>

== Kurzüberblick ==
Hier soll nur ein kurzer Überblick über die mittlerweile doch recht umfangreichen Möglichkeiten geboten werden:
*Automatisches Erkennen aller ZonePlayer im lokalen Netzwerk. Dabei werden alle Player einer Paarung zusammengehörig benannt und gruppiert
*Automatische Aktualisierung aller aktuellen (und wenn verfügbar: der nächsten) Titelinformationen innerhalb von FHEM
**Dabei wird für jede veränderte Information ein Event erzeugt, man kann also dediziert darauf reagieren
**Bei normalen Abspiellisten werden auch die Informationen zum nächsten Titel ermittelt und angezeigt
**Es können auch verschiedene Zusammenfassungen der bestehenden Informationen zusammengestellt werden
*Anzeige des aktuellen (oder auch nächsten) Covers als Weblink
*Steuern der ZonePlayer: Play, Pause, Nächster Titel, Vorheriger Titel, Lautstärke Lauter/Leiser (auch als Rampe), Stummschalten
*Alle Player auf einen Befehl hin stoppen oder pausieren lassen
*Einstellen und Abfragen der Abspielparameter Repeat, Shuffle, CrossfadeMode, Loudness, Bass und Treble
*Festlegen einer minimalen und maximalen Lautstärke für jeden ZonePlayer (getrennt zwischen Normalbetrieb und Kopfhörernutzung)
*Laden und Speichern von Playlisten (auch M3U-Dateien aus dem Filesystem)
*Abspielen eines Sonos-Favoriten (z.B. Playlist, Spotify-Playlist, Titel, Radiosender, usw.)
*Abspielen beliebiger Titel (auch von Freigaben, die nicht von Sonos indiziert wurden)
*Abspielen beliebiger Radiostationen über deren HTTP-Link
*Hinzufügen beliebiger Titel und Radiostationen zur aktuellen Abspielliste
*Temporäres Abspielen von Dateien, mit nachfolgender Wiederherstellung des vorherigen Titels inkl. genauer Position im vorherigen Titel und der Lautstärke
*Erzeugen und temporäres Abspielen von Sprachdurchsagen auf Basis von eingegebenen Texten
**Wird standardmäßig über die Google-Übersetzungsmaschine realisiert
**Kann auch über eine eigenständige, lokale Installation realisiert werden
*Auslesen der verfügbaren gespeicherten Playlisten und Radiofavoriten
*Erzeugung und Bearbeitung von Alarmen, sowie Event bei Veränderung der Alarme duch andere Controller
*Setzen des Sleeptimer inkl. Fhem-Event bei Veränderung durch andere Controller und Ablauf des Timers
*Setzen und Auslesen der Gruppierungskonfiguration, sowie einzelnes Hinzufügen und Entfernen von Gruppenmitgliedern
*Erzeugen von Events nach festgelegten Tastensequenzen (am Player)
*Umbenennen der Zonen und festlegen der Zonenicons

=== Kurze Anmerkungen zur Sonos-Landschaftsgestaltung ===
Es ist im allgemeinen besser, die Sonos-Landschaft mit allen Paarungen vor dem Einrichten des Moduls zu erzeugen.
Dieses Modul benennt die Player nach den Zonennamen und der jeweiligen Funktion des Players innerhalb der Paarungs-Zone.

Das bedeutet aber auch, dass in diesem Augenblick möglichst keine Player gruppiert sein sollten (mehrere Zonen spielen dasselbe ab), da diese sonst komische Namen erhalten könnten (es geht hier ausschliesslich um die Fhem-interne Device-Benennung, natürlich bleiben die Zoneplayer selbst wie sie sind).

Damit man nun eine einigermaßen passende Bezeichnung in Fhem erhält, sollte also die Gestaltung der Sonos-Player abgeschlossen sein. Natürlich funktioniert das System nach einer Fhem-Einrichtung und anschließender Sonos-Umbenennung immer noch, da intern alles mittels der eindeutigen Bezeichner gehandhabt wird, allerdings wird es u.U. etwas unübersichtlich bzgl. der Fhem-Device-Namen. Diese passen dann nicht mehr zu den Zonennamen (die entsprechenden Readings werden aber natürlich korrekt besetzt), was man aber natürlich auch nachträglich wieder anpassen kann.

== Einbindung von Sonos in FHEM ==
Die Einbindung erfolgt über die beiden Module '''SONOS''' und '''SONOSPLAYER'''. Dabei ist Hauptsächlich das Modul '''SONOS''' einzurichten. Alle Zoneplayer werden automatisch erkannt, und dann entsprechend angelegt:

<pre>define Sonos SONOS localhost:4711 30</pre>

Der Name dieses Devices ist automatisch das Namensprefix beim Anlegen der SonosPlayer. In diesem Fall werden alle erkannten Zoneplayer mit dem Prefix "<code>Sonos_</code>" anfangen.
Natürlich kann man das nach dem Anlegen einfach umbenennen.

Erkannte Zoneplayer werden als '''SONOSPLAYER'''-Device angelegt:

<pre>define Sonos_Wohnzimmer SONOSPLAYER RINCON_000E5828D0F401400_MR</pre>

Der Name des Device wird aus dem Namen des SONOS-Device und dem Namen der Zone gebildet. Dabei werden Leer- und Sonderzeichen in "<code>_</code>" umgewandelt.

Beim Anlegen werden automatisch einige Attribute mit angelegt:
<pre>
attr Sonos_Wohnzimmer generateInfoSummarize1 <NormalAudio><Artist prefix="(" suffix=")"/>
<Title prefix=" '" suffix="'" ifempty="[Keine Musikdatei]"/>
<Album prefix=" vom Album '" suffix="'"/></NormalAudio>
<StreamAudio><Sender suffix=":"/><SenderCurrent prefix=" '" suffix="' -"/>
<SenderInfo prefix=" "/></StreamAudio>
attr Sonos_Wohnzimmer generateInfoSummarize2 <TransportState/><InfoSummarize1 prefix=" => "/>
attr Sonos_Wohnzimmer generateInfoSummarize3 <Volume prefix="Lautstärke: "/>
<Mute instead=" ~ Kein Ton" ifempty=" ~ Ton An" emptyval="0"/>
~ Balance: <Balance ifempty="Mitte" emptyval="0"/>
<HeadphoneConnected instead=" ~ Kopfhörer aktiv"
ifempty=" ~ Kein Kopfhörer" emptyval="0"/>
attr Sonos_Wohnzimmer icon icoSONOSPLAYER_icon-ZP90.png
attr Sonos_Wohnzimmer room Sonos
attr Sonos_Wohnzimmer stateVariable InfoSummarize2
attr Sonos_Wohnzimmer webCmd Play:Pause:Previous:Next:VolumeD:VolumeU:MuteT
attr Sonos_Wohnzimmer group Wohnzimmer
</pre>

Dadurch ist dieses Device direkt in der FHEM-Oberfläche steuerbar. Auch hier gilt, dass man das natürlich anpassen kann. Das sollen nur vereinfachende Vorgaben sein.
Das Attribut "<code>room</code>" wird wieder aus dem Namen des SONOS-Device gebildet.
Das Attribut "<code>group</code>" wird aus dem Namen der Zone gebildet

Des Weiteren wird automatisch ein Weblink mit angelegt:
<pre>
define AlbumArt_Wohnzimmer weblink image fhem/icons/SONOSPLAYER/Sonos_Wohnzimmer_AlbumArt
attr AlbumArt_Wohnzimmer room Sonos
attr AlbumArt_Wohnzimmer htmlattr width="200"
attr AlbumArt_Wohnzimmer group Wohnzimmer
</pre>

Damit wird in der Raumansicht direkt über dem SonosPlayer-Device das Cover des aktuellen Titels angezeigt.

== Namensvergabe der automatischen Erkennung ==
Der automatische Erkennungsmechanismus vergibt Devicenamen auf Basis der Zonennamen und der Funktion eines Players innerhalb eines Stereopaares oder einer Surroundkonstellation.
Dabei wird immer ein Player (der Master dieser Konstellationen) nur den Namen der Zone erhalten (ohne Anhängekürzel) und die anderen werden mit Kürzel versehen. Dadurch ist der Master der Zone automatisch dasjenige Playerdevice, welches gesteuert werden muss. Alle anderen Player leiten Steueranfragen automatisch an den Master weiter.
Besteht eine Zone nur aus einem Player, so gibt es natürlich auch nur diesen einen als Master.

Als Anhängekürzel wird immer der Inhalt des Readings '''fieldType''' verwendet.

Bei der Funktion gibt es später dann zwei Fälle zu unterscheiden:
*Stereopaare werden von Sonos intern als Gruppe behandelt. Das bedeutet, dass der zweite Player (der nicht-Master) immer ''PLAYING'' als Status anzeigt, und nur der Master den korrekten Wert. Stereopaare haben, wie normale Gruppen oder Einzelplayer auch, eine Verzögerung von 70ms zu einem Eingangssignal.
*Surroundsysteme werden als Satelliten angebunden, und werden vom Modul nur mit ''intialized'' angegeben, da Sonos für diese nie eine Statusmeldung sendet. Diese Playersysteme haben eine verkürzte Verzögerung von 30ms zu einem Eingangssignal.

Dabei ist ein Eingangsignal so etwas wie ein Line-In- oder SPDIF-Eingang.

=== Beispiel für eine Zonenlandschaft ===
Folgende Landschaft mit Status könnte es geben:
<pre>
Sonos_Schlafzimmer (STOPPED => [Keine Musikdatei])
Sonos_Schlafzimmer_RF (PLAYING => 'Keine Titelinformation bei Gruppenwiedergabe')
Sonos_Kinderzimmer (PAUSED_PLAYBACK => 'Titelinformation')
Sonos_Gaestezimmer (STOPPED => [Keine Musikdatei])
Sonos_Wohnzimmer (STOPPED => [Keine Musikdatei])
Sonos_Wohnzimmer_LR (initialized)
Sonos_Wohnzimmer_RR (initialized)
Sonos_Wohnzimmer_SW (initialized)
</pre>
Dabei wäre Schlafzimmer ein Stereopaar, Kinder- und Gästezimmer jeweils ein einzelner Player und Wohnzimmer z.B. eine Playbar mit zwei Rear-Lautsprechern und Subwoofer. In keiner Zone läuft eine aktive Wiedergabe.
Hier kann man schön die einzelnen Zustände und die erzeugten Namen erkennen.

== Hardwarevoraussetzungen ==
Diese Liste sollte im Laufe der Zeit fortgeführt werden. Es soll die Hardware-/Softwarevoraussetzungen festhalten, um Probleme im Vorfeld erkennen zu können.

Funktionierende Kombinationen:
*Windows, ActivePerl
*Raspberry Pi, Default-Perl

Problematische Kombinationen:
*FritzBox: Anscheinend ist Perl dort ohne Thread-Möglichkeit kompiliert. Diese sind aber essentiell notwendig für dieses Modul.

== Softwarevoraussetzungen ==
Für die Verwendung sind Perlmodule notwendig, die unter Umständen noch nachinstalliert werden müssen:
*'''LWP::Simple'''
*'''LWP::UserAgent'''
*'''SOAP::Lite'''
*'''HTTP::Request'''

Die Installation dieser Module geht in der Regel per CPAN. Das bedeutet das zum Beispiel mit
<pre>
sudo cpan LWP::Simple
</pre>
das Modul "<code>LWP::Simple</code>" installiert wird. Wenn man bereits als Benutzer '''root''' arbeitet, dann ist das <code>sudo</code> natürlich nicht nötig.

Sollte es bei der Installation mittels CPAN zu Problemen kommen, dann folgt hier eine Beschreibung der manuellen Installation.

=== Hinweis für Debian-Systeme ===
Bei Debian-basierten Systemen (also auch Raspbian für den Raspberry Pi usw.) kann auch mittels
<pre>
sudo apt-get install <paketname>
</pre>
installiert werden. Manchmal ist es etwas schwieriger, die Paketnamen zu ermitteln, aber Google ist da sehr hilfreich.

Hier mal die Liste für die oben genannten Pakete:
*'''LWP::Simple'''-Paketname (inkl. '''LWP::UserAgent''' und '''HTTP::Request'''): <code>libwww-perl</code>
*'''SOAP::Lite'''-Paketname: <code>libsoap-lite-perl</code>
*'''XML::Parser::Lite'''-Paketname: <code>libxml-parser-lite-perl</code>

=== Manuelle Installation LWP::Simple ===
Wenn sich dieses Paket nicht einfach per CPAN-Anweisung installieren läßt, dann hilft folgende Anleitung weiter.
Beim Abbruch der Installation mittels CPAN erscheint mittendrin ein Fehler, das die Datei nicht entpackt werden könne (couldn't untar). Da scheint es einen Fehler im Installationsskript zu geben.

Man kann das aber auch Manuell installieren:
*Am Einfachsten ist ein Wechsel in den Kontext des Benutzers '''root''': "<code>sudo su -</code>"
*Erstellen eines Ordners, z.B. "<code>mkdir lwpsimple</code>"
*Wechsel in diesen Ordner "<code>cd lwpsimple</code>"
*Herunterladen der Datei von [http://search.cpan.org/~gaas/libwww-perl-6.04/ libwww-perl-6.04] oder direkter Link: [http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/libwww-perl-6.04.tar.gz libwww-perl-6.04.tar.gz]: z.B. "<code>wget http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/libwww-perl-6.04.tar.gz</code>"
*Entpacken der Datei: "<code>tar -xzvf libwww-perl-6.04.tar.gz</code>"
*Wechsel in das neu entstandene Verzeichnis: "<code>cd libwww-perl-6.04</code>"
*Nun kann es nach dem Standardvorgehen weitergehen:
**"<code>perl Makefile.PL</code>"
**"<code>make</code>"
**"<code>make install</code>"

=== Manuelle Installation SOAP::Lite ===
Wenn sich dieses Paket nicht einfach per CPAN-Anweisung installieren läßt, dann hilft folgende Anleitung weiter.
Beim Abbruch der Installation mittels CPAN erscheint mittendrin ein Fehler, das die Datei nicht entpackt werden könne (couldn't untar). Da scheint es einen Fehler im Installationsskript zu geben.

Man kann das aber auch Manuell installieren:
*Am Einfachsten ist ein Wechsel in den Kontext des Benutzers '''root''': "<code>sudo su -</code>"
*Erstellen eines Ordners, z.B. "<code>mkdir soaplite</code>"
*Wechsel in diesen Ordner "<code>cd soaplite</code>"
*Herunterladen der Datei von [http://search.cpan.org/~mkutter/SOAP-Lite-0.715/ CPAN-SOAP-Lite-0.715] oder direkter Link: [http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/authors/id/M/MK/MKUTTER/SOAP-Lite-0.715.tar.gz SOAP-Lite-0.715.tar.gz]: z.B. "<code>wget http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/authors/id/M/MK/MKUTTER/SOAP-Lite-0.715.tar.gz</code>"
*Entpacken der Datei: "<code>tar -xzvf SOAP-Lite-0.715.tar.gz</code>"
*Wechsel in das neu entstandene Verzeichnis: "<code>cd SOAP-Lite-0.715</code>"
*Nun kann es nach der [http://www.soaplite.com/2003/06/installation_in.html Anleitung] weitergehen:
**"<code>perl Makefile.PL</code>"
**Dann kommt eine Nachfrage, was zusammengebaut werden soll. An dieser Stelle ist es jetzt wie eine normale CPAN Installation. Einfach mit <Enter> weitermachen lassen.
**"<code>make</code>"
**"<code>make install</code>"

=== Einrichtung von Samba für Sprachausgabemöglichkeit ===
Wenn die Sprachausgabe verwendet werden soll, muss ein lokaler Samba-Daemon (Server für Windowsfreigaben) laufen oder eine für FHEM beschreibbare (Windows-)Freigabe woanders existieren, da Sonos nur auf eine solche lesend zugreifen kann.

Diese Beschreibung soll anhand des Raspberry-Pi (und anderer Debian-Systeme) zeigen, wie man einen solchen lokalen Samba-Server schnell für diesen Zweck einrichten kann:
*Lokales Verzeichnis für die Ablage der Tondateien erzeugen. z.B.: <pre>sudo mkdir /mnt/SonosSpeak</pre>
*Installation der notwendigen Pakete für Samba: <pre>sudo apt-get install samba samba-common-bin</pre>
*Starten des Editors zum Anpassen der Konfigurationsdatei: <pre>sudo nano /etc/samba/smb.conf</pre>
*Folgende Zeilen hinzufügen (Pfade müssen natürlich u.U. angepasst werden):
<pre>
[SonosSpeak]
comment = Audio-Files for SonosPlayer to Speak
read only = false
path = /mnt/SonosSpeak
guest ok = yes
</pre>
*Falls der Zugriff nicht funktioniert, kann vielleicht folgendes helfen:
**Sicherstellen, dass in der ''Global''-Sektion der Parameter ''Security'' auf ''Share'' steht (oder gar nicht erst definiert wurde):
<pre>
[global]
security = share
</pre>
*Samba-Server neustarten: <pre>sudo /etc/init.d/samba restart</pre>

Damit wird eine Freigabe mit dem Namen '''SonosSpeak''' erzeugt, die von allen ohne Anmeldung gelesen und beschrieben werden kann.

== Interner Aufbau ==
Um die Kommunikation mit dem UPnP-Netzwerk parallel zum normalen Betrieb von FHEM zu ermöglichen, werden [http://perldoc.perl.org/threads.html Threads] eingesetzt. Dadurch sind manche Hardwareplattformen leider überfordert und können u.U. nicht mit diesem Modul verwendet werden. Das läßt sich aus technologischen Gründen auch nicht umgehen.

Dabei wird der SubThread verwendet um die Callback-Aufrufe, die erfolgen, wenn z.B. eine Statusänderung eines Players erfolgt, zu verarbeiten. Die Aktualisierung der Daten selbst wird dann über eine interne [http://perldoc.perl.org/Thread/Queue.html Queue] "nach oben" zum Hauptthread übertragen, und dann mittels einer bestehenden TCP-Verbindung zur Verarbeitung in FHEM übertragen. Dadurch wird gewährleistet, dass die Daten immer im Hauptthread (also dem "eigentlichen" FHEM-Thread) verfügbar sind.

Da dieser SubThread auch die Kommandoübergabe an den Player übernimmt, gibt es auch eine Kommando-Queue in die andere Richtung, die dann mittels eines Thread-Signals im SubThread-Kontext ausgeführt wird.

Dieser Aufbau sorgt natürlich dafür, dass man auf die üblichen Nebenläufigskeitsprobleme achten muss (in der Hauptsache sind das Dead-Locks, da man oftmals über drei Ecken aufeinander wartet, ohne das direkt zu sehen). Deswegen wird in allen Log-Ausgaben des Moduls ein Kürzel vorangestellt: "<code>SONOS_</code>", wobei der Unterstrich durch die Nummer des aktiven, loggenden, Threads ersetzt wird. Damit kann man sehr leicht feststellen, auf welcher "Ebene" diese Ausgabe erfolgt ist, und ob das alles so seine Richtigkeit hat.

Der Rest sind nur viele Zeilen, die XML-Strukturen (mittels regulärer Ausdrücke) parsen oder erzeugen, und die entsprechenden Informationen setzen oder abfragen.

== Installation des Moduls selbst ==
Hier wird die Installation des eigentlichen Moduls beschrieben, sowie ein Changelog ausgegeben, damit man nachvollziehen kann, was am Modul so passiert ist. Dieser Changelog steht auch in der Datei 00_SONOS.pm.

=== Installation mittels FHEM-Updatemechanismus ===
Um dieses Modul über den Update-Mechanismus von FHEM zu installieren, muss folgender Befehl im Eingabefeld (oder auf der Telnet-Konsole) eingegeben werden:
<pre>update thirdparty http://fhem.lmsoft.de/sonos sonos</pre>

Für einen Vorabcheck, was installiert werden würde, kann man folgendes eingeben:
<pre>update thirdparty http://fhem.lmsoft.de/sonos sonos check</pre>

Wenn die Perl-Installation korrekt erweitert wurde, bzw. bereits erweitert war, sollte das Modul nach einem Neustart zur Verfügung stehen.

==== Living on the bleeding edge ====
Da ich vor einem Releasetermin natürlich einiges entwickelt habe, und dies natürlich auch selber teste, habe ich dafür einen Development-Server eingerichtet.
Dieser kann u.U. sinnvollerweise auch von anderen als Installationsquelle verwendet werden, da er aktuelle Fehlerbereinigungen oder neue Features und Konzepte enthält, die man gerne vorab sehen möchte.

'''Achtung''':
Diese Version muss nicht immer und zwangsläufig besser sein! ich gebe mir Mühe, bin aber auch nur ein Mensch :-)

Folgendes muss für die Installation eingegeben werden:
<pre>update thirdparty http://fhem.lmsoft.de/sonos_dev sonos</pre>

=== Manuelle Installation ===
Dieser Part ist nur solange interessant, wie das Modul (noch) nicht offiziell ist.

Für den Betrieb ist das Modul [http://perlupnp.sourceforge.net/ PerlUPnP] notwendig.

Folgende Dateien sind nötig:
*00_SONOS.pm
*21_SONOSPLAYER.pm
*2 Dateien der PerlUPnP-Library
*Dateien für MP3-Tags bei der Sprachausgabe (Wenn nicht vorhanden, fehlt nur die Funktionalität, das Modul sollte aber dennoch lauffähig sein)
*Die unter ''Softwarevoraussetzungen'' genannten Perlmodule

Die beiden SONOS-Perlmodule müssen einfach in das Verzeichnis <code>FHEM</code> kopiert werden (wie alle anderen FHEM-Module auch).

Die PerlUPnP-Library muss komplett in das Verzeichnis <code>FHEM/lib/</code> abgelegt werden. Dabei muss das Verzeichnis <code>UPnP</code> genannt werden.
Es werden für den Betrieb nicht alle Dateien des Standard-Pakets benötigt, sondern nur zwei .pm Dateien. 
Die resultierende Ordnerstruktur (inkl. Dateien von PerlUPnP) lautet dann wie folgt:
*FHEM/lib
*FHEM/lib/UPnP
*FHEM/lib/UPnP/Common.pm
*FHEM/lib/UPnP/ControlPoint.pm

Die Dateien für die MP3-Tags müssen ebenfalls in das Verzeichnis <code>lib</code> kopiert werden. Diese wird nur bei manchen Dateien für die Zwischendurchsage benötigt, da Sonos nicht immer eine Laufzeit mitliefert, bzw. für die generierten Sprachdurchsagen, da dort die Informationen für die Anzeige im ZonePlayer gesetzt werden. Die Laufzeit z.B. wird für die Pausenberechnung aber gebraucht, und muss dementsprechend auf anderem Wege ermittelt werden. 
Die resultierende Ordnerstruktur lautet dann wie folgt:
*FHEM/lib/
*FHEM/lib/MP3
*FHEM/lib/MP3/Tag.pm
*FHEM/lib/MP3/Info.pm
*FHEM/lib/MP3/Tag
*FHEM/lib/MP3/Tag/File.pm
*FHEM/lib/MP3/Tag/LastResort.pm
*FHEM/lib/MP3/Tag/ImageExifTool.pm
*FHEM/lib/MP3/Tag/CDDB_File.pm
*FHEM/lib/MP3/Tag/ID3v2_Data.pod
*FHEM/lib/MP3/Tag/ImageSize.pm
*FHEM/lib/MP3/Tag/ID3v1.pm
*FHEM/lib/MP3/Tag/ParseData.pm
*FHEM/lib/MP3/Tag/Cue.pm
*FHEM/lib/MP3/Tag/ID3v2.pm
*FHEM/lib/MP3/Tag/Inf.pm
*FHEM/lib/Normalize
*FHEM/lib/Normalize/Text
*FHEM/lib/Normalize/Text/Music_Fields.pm
*FHEM/lib/Normalize/Text/Music_Fields
*FHEM/lib/Normalize/Text/Music_Fields/Music_Fields-rus.lst
*FHEM/lib/Normalize/Text/Music_Fields/G_Gershwin.comp
*FHEM/lib/Normalize/Text/Music_Fields/A_Dvor_k.comp
*FHEM/lib/Normalize/Text/Music_Fields/J_Brahms.comp
*FHEM/lib/Normalize/Text/Music_Fields/L_van_Beethoven.comp
*FHEM/lib/Normalize/Text/Music_Fields/A_Schnittke.comp
*FHEM/lib/Normalize/Text/Music_Fields/D_Shostakovich.comp
*FHEM/lib/Encode
*FHEM/lib/Encode/transliterate_win1251.pm

Nach einem Neustart von FHEM kann das Modul wie beschrieben verwendet werden.

=== Fehlersuche ===
Da das Modul noch in der Entwicklung steht, und natürlich sowieso immer wieder Probleme auftauchen können, hier ein paar Hinweise zur Fehlersuche:
Das Modul besteht zunächst aus zwei Ebenen:
*Eine Ebene, die innerhalb von Fhem selbst läuft
*Eine Ebene, die als eigenständiger Prozess läuft (entweder durch Fhem selbst oder manuell angestartet)

Die Logausgaben der ersten Ebene landen direkt im Fhem-Log, die der zweiten Ebene können dort nicht reingeschrieben werden, und landen dementsprechend auf der Konsole (genauer: auf STDOUT).
Wenn man also die Log-Ausgaben dieses Sub-Prozesses sehen möchte, muss man im Startskript den STDOUT entsprechend umlenken, oder einen manuellen Start ausführen:
<code>sudo perl fhem.pl fhem.cfg</code>
Dazu muss man natürlich vorher in das entsprechende Verzeichnis wechseln.

Die Menge der Logausgaben werden, wie in Fhem üblich, über das Attribut Verbose am Sonos-Device gesteuert (Bis auf wenige Zeilen beim Start des Sub-Prozesses, die nur mit dem globalen Verbose-Attribut gesteuert werden können, da noch keine Verbindung besteht).

Im Normalfall sollte Anhand der Ausgabe erkennbar sein, was das jeweilige Problem ist. Bei Unklarheiten am Besten im Forum suchen/posten.

==== Hinweise / Häufige Fehler / FAQ ====
Hier soll mal eine Liste mit häufigen Fehlern, Problemen und Hinweisen entstehen.

*Allgemein läuft das Modul besser, wenn es im Benutzerkontext ''root'' läuft. Für diverse Funktionalitäten ist das sogar notwendig (z.B. Pingtype auf ''icmp'' konfiguriert).
*Wenn man das Problem hat, dass Befehle an den falschen Player gesendet werden, sollte man das Reading '''ZoneGroupID''' prüfen. Bei ungruppierten Playern sollte es die eigene UDN enthalten, bei gruppierten Playern die UDN des Gruppenmaster. Sollte das mal nicht der Fall sein, so kann es sein, dass im Sonos-System eine Falschinformation vorliegt. Da es jetzt nicht so einfach ist, die bei Sonos dazu zu bewegen, diesen Fehler zu beseitigen, gibt es u.U. eine Workaround-Möglichkeit mit dem Modul. Wenn wir z.B. zwei Player haben: ''Sonos_Bad'' und ''Sonos_Kueche'', und dort die Steuerung nicht korrekt funktioniert, dann einmal die folgenden Schritte versuchen (bei mehr oder anderen Playern natürlich analog dazu). Dadurch werden die Gruppen gebildet, und nochmal explizit aufgelöst.
**<code>set Sonos Groups [Sonos_Bad, Sonos_Kueche]</code>
**<code>set Sonos Groups [Sonos_Kueche, Sonos_Bad]</code>
**<code>set Sonos Groups [Sonos_Bad], [Sonos_Kueche]</code>
*Es ist empfehlenswert, dass erst das '''Sonos'''-Device definiert wird, und dann erst die entsprechenden '''Sonosplayer'''-Devices dazu. Sonst kann es u.U. zu einer Verdoppelung des SubProzesses kommen.
*Manchmal bleiben 'Reste' beim Beenden von Fhem. Dann kann es sinnvoll sein, erst alle Perl-Prozesse zu beenden. Diese kann man mit <pre>sudo ps -aux | grep perl</pre> finden, und dann einzeln mittels <pre>sudo kill ID</pre> beenden (die ID steht in der ersten Spalte des Ergebnisses des vorherigen Befehls).

=== Changelog ===
*2.5 (07.03.2014):
**Verwendung und Speicherung der Benutzer-IDs für Spotify und Napster wurden stabiler gegenüber Sonderzeichen gemacht
**Spotify-URLs werden im Reading 'currentTrackURI' und 'nextTrackURI' lesbarer abgelegt
**Ein Fehler beim Öffnen von M3U-Playlistdateien wurde behoben (dafür Danke an John)
**Überholt: Für die Informationsanfragen an Fhem durch den SubProzess wird nun standardmäßig der Telnet-Port von Fhem verwendet. Wenn das fehlschlägt, wird auf den alten Mechanismus zurückgeschaltet
**Neu: Es werden keine Informationsanfragen mehr zwischen Fhem und dem SubProzess ausgetauscht. Notwendige Informationen müssen vorher übertragen werden. Das bedeutet, dass bei einer Attributänderung ein Neustart von Fhem erfolgen muss.
**Es wurde ein Standard-Layout für das RemoteControl-Hilfsmodul angelegt
**Der Verbose-Level des Sonos-Devices wird nun auch an den SubProzess weitergereicht (auch zur Laufzeit), und beim initialen Start des SubProzess-Threads mitgegeben.
**AlbumArt von Napster erhält nun den den festen Mimetype 'jpg', da dieser nicht übertragen wird
**Es werden nun die durch Fhem definierten Standard-Attribute mit angeboten
**Es gab ein Problem mit der Befehlsverarbeitung, wenn das Verbose-Attribut an einem Sonos-Device gesetzt war.
**Es wird nun auf Änderungsevents für den Zonennamen und das Zonenicon reagiert, und die entsprechenden Readings aktualisiert
**Es gibt jetzt zwei neue Setter: 'Name' und 'Icon', mit dem der Name und das Icon der Zone eingestellt werden kann
**Es gibt jetzt einen Getter 'PossibleRoomIcons', welcher die möglichen Angaben für den neuen Setter 'Icon' liefert
**Das Reading 'ZoneGroupID' wird nun auf eine andere Weise ermittelt und gesetzt
**Es gib jetzt ein neues Reading 'AlarmRunning', welches auf '1' steht, wenn gerade eine Alarmabspielung aktiv ist
**Die Namens- und Aufgabenerkennung beim Ermitteln der Player wurde angepasst
**Der Aufruf von AddMember und RemoveMember wurde bzgl. des SonosDevice-Namen abgesichert, sodass hier kein Absturz mehr bei einer falschen Deviceangabe erfolgt
**Es gibt jetzt ein neues Reading 'AlarmRunningID', welches bei einer Alarmausführung die ID des aktiven Alarms enthält
**Das Senden von Aktualisierungen an Fhem wurde etwas sicherer gemacht, wenn Fhem auf der anderen Seite gerade nicht zuhören kann
**Die Readings 'AlarmList', 'AlarmListIDs' und 'AlarmListVersion' werden nicht mehr aus dem Statefile geladen, da dort Sonderzeichen wie '#' zum Abschneiden der restlichen Zeile führen
**Anpassung der UPnP-Klasse, damit das Device-Beschreibungsdokument nur noch einmal geladen wird (anstatt wie bisher zweimal)
**Anpassung im Bereich der Cover Aktualisierung über FhemWeb. Das geht jetzt mit viel weniger Aufwand durch.
**Es gibt jetzt einen Setter 'SnapshotGroupVolume', der das aktuelle Lautstärkenverhältnis der einzelnen Player einer Gruppe für die folgenden Aufrufe des Setter 'GroupVolume' festhält. Die Anweisungen 'PlayURI' und 'PlayURITemp' (sowie darauf aufbauende Aufrufe wie 'Speak') führen diese Anweisung selbsttätig beim Starten durch.
**Wenn beim Auffrischen der Subscriptions ein Fehler auftritt, der darauf schließen läßt, dass der Player weg ist, dann wird die entsprechende Referenz aufgeräumt
**Man kann als relative Angabe bei setVolume nun einen Prozentwert angeben, z.B. '+20%'. Damit wird die Lautstärke um den jeweiligen prozentualen Anteil erhöht oder abgesenkt.
**Es gibt jetzt ein Reading 'LineInConnected', welches eine '1' enthält, wenn der Line-In-Eingang angeschlossen wurde, sonst '0'.
*2.4 (31.12.2013):
**Initiale Lautstärkenermittlung wurde nun abgesichert, falls die Anfrage beim Player fehlschlägt
**Verbesserte Gruppenerkennung für die Anzeige der Informationen wie Titel usw.
**Fallback (Log) für den Aufruf von Log3 geschaffen, damit auch alte FHEM-Versionen funktionieren
**Es wurde eine Korrektur im verwendetetn UPnP-Modul gemacht, die eine bessere Verarbeitung der eingehenden Datagramme gewährleistet (dafür Danke an Sacha)
**Es werden nun zusätzliche Readings (beginnend mit 'next') mit den Informationen über den nächsten Titel befüllt. Diese können natürlich auch für InfoSummarize verwendet werden
**Es kann nun ein Eintrag aus der Sonos-Favoritenliste gestartet werden (Playlist oder Direkteintrag)
**Das Benennen der Sonos-Fhem-Devices wird nun auf Namensdoppelungen hin überprüft, und der Name eindeutig gemacht. Dabei wird im Normalfall das neue Reading 'fieldType' an den Namen angehangen. Nur der Master einer solchen Paarung bekommt dann den Original-Raumnamen als Fhem-Devicenamen
**Es gibt ein neues Reading 'fieldType', mit dem man erkennen kann, an welcher Position in einer Paarung dieser Zoneplayer steht
**Diverse Probleme mit Gruppen und Paarungen beim neu Erkennen der Sonos-Landschaft wurden beseitigt
**Es gibt jetzt einen Getter 'EthernetPortStatus', der den Status des gewünschten Ethernet-Ports liefert
**Es gibt jetzt einen Setter 'Reboot', der einen Neustart des Zoneplayers durchführt
**Es gibt jetzt einen Setter 'Wifi', mit dem der Zustand des Wifi-Ports eines Zoneplayers gesetzt werden kann
**Wenn ein Player als "Disappeared" erkannt wird, wird dem Sonos-System dies mitgeteilt, sodass er aus allen Listen und Controllern verschwindet
**Kleinere Korrektur, die eine bessere Verarbeitung der Kommunikation zwischen Fhem und dem Subprozess bewirkt
*2.3 (2.12.2013):
**Die Antwort von 'SetCurrentPlaylist' wurde korrigiert. Dort kam vorher 'SetToCurrentPlaylist' zurück.
**VolumeStep kann nun auch als Attribut definiert werden. Das fehlte in der zulässigen Liste noch.
**Speak kann nun auch für lokale Binary-Aufrufe konfiguriert werden.
**Speak kann nun einen Hash-Wert auf Basis des gegebenen Textes in den Dateinamen einarbeiten, und diese dann bei Gleichheit wiederverwenden (Caching)
**Sonos kann nun ein "set StopAll" oder "set PauseAll" ausführen, um alle Player/Gruppen auf einen Schlag zu stoppen/pausieren
**Beim Discover-Event wird nun genauer geprüft, ob sich überhaupt ein ZonePlayer gemeldet hat
**Die UserIDs für Napster und Spotify werden wieder korrekt ermittelt. Damit kann auch wieder ein Playlistenimport erfolgen.
**Loudness Einstell- und Abfragbar
**Bass Einstell- und Abfragbar
**Treble Einstell- und Abfragbar
**Volume kann nun auch als RampToVolume ausgeführt werden
*2.2 (12.10.2013):
**Befehlswarteschlange wieder ausgebaut. Dadurch gibt es nur noch das Reading LastActionResult, und alles wird viel zügiger ausgeführt, da Fhem nicht auf die Ausführung warten muss.
**TempPlaying berücksichtigt nun auch die Wiedergabe von Line-In-Eingängen (also auch Speak)
**Veraltete, mittlerweile unbenutzte, Readings werden nun gelöscht
**SetLEDState wurde hinzugefügt
**Die IsAlive-Überprüfung kann mit 'none' abgeschaltet werden
**CurrentTempPlaying wird nicht mehr benötigt
*2.1:
**Neuen Befehl 'CurrentPlaylist' eingeführt
*2.0:
**Neue Konzeptbasis eingebaut
**Man kann Gruppen auf- und wieder abbauen
**Es gibt neue Lautstärke- und Mute-Einstellungen für Gruppen ingesamt
**Man kann Button-Events definieren
*1.13:
**Neuer Abspielzustand 'TRANSITIONING' wird berücksichtigt
**Der Aufruf von 'GetDeviceDefHash' wird nun mit dem Parameter 'undef' anstatt ohne einen Parameter durchgeführt
*1.12:
**TrackURI hinzugefügt
**LoadPlayList und SavePlayList können nun auch Dateinamen annehmen, um eine M3U-Datei zu erzeugen/als Abspielliste zu laden
**Alarme können ausgelesen, gesetzt und gelöscht werden
**SleepTimer kann gesetzt und ausgelesen werden
**Reading DailyIndexRefreshTime hinzugefügt
**Bei AddURIToQueue und PlayURI können jetzt auch (wie bei LoadPlayList) Spotify und Napster-Ressourcen angegeben werden
**Beim Erzeugen des Cover-Weblinks wird nun nur noch die Breite festgelegt, damit Nicht-Quadratische Cover auch korrekt dargestellt werden
**SONOS_Stringify gibt Strings nun in einfachen Anführungszeichen aus (und maskiert etwaig enthaltene im String selbst)
*1.11:
**Ein Transport-Event-Subscribing wird nur dann gemacht, wenn es auch einen Transport-Service gibt. Die Bridge z.B. hat sowas nicht.
**Bei PlayURITemp wird nun der Mute-Zustand auf UnMute gesetzt, und anschließend wiederhergestellt
**Shuffle, Repeat und CrossfadeMode können nun gesetzt und abgefragt werden. Desweiteren wird der Status beim Transport-Event aktualisiert.
**Umlaute bei "generateInfoSmmarize3" durch "sichere" Schreibweise ersetzt (Lautstärke -> Lautstaerke)
*1.10:
**IsAlive beendet nicht mehr den Thread, wenn der Player nicht mehr erreichbar ist, sondern löscht nur noch die Proxy-Referenzen
**FHEMWEB-Icons werden nur noch im Hauptthread aktualisiert
**Getter 'getBalance' und Setter 'setBalance' eingeführt.
**HeadphoneConnected inkl. minVolumeHeadphone und maxVolumeHeadphone eingeführt
**InfoSummarize um die Möglichkeit der Volume/Balance/HeadphoneConnected-Felder erweitert. Außerdem werden diese Info-Felder nun auch bei einem Volume-Event neu berechnet (und triggern bei Bedarf auch!)
**InfoSummarize-Features erweitert: 'instead' und 'emptyval' hinzugefügt
**IsAlive prüft nicht mehr bei jedem Durchgang bis zum Thread runter, ob die Subscriptions erneuert werden müssen
*1.9:
**RTL.it Informationen werden nun schöner dargestellt (Da steht eine XML-Struktur im Titel)
**Wenn kein Cover vom Sonos geliefert werden kann, wird das FHEM-Logo als Standard verwendet (da dieses sowieso auf dem Rechner vorliegt)
**UPnP-Fehlermeldungen eingebaut, um bei einer Nichtausführung nähere Informationen erhalten zu können
*1.8:
**Device-Removed wird nun sicher ausgeführt. Manchmal bekommt man wohl deviceRemoved-Events ohne ein vorheriges deviceAdded-Event. Dann gibt es die gesuchte Referenz nicht.
**Renew-Subscriptions wurden zu spät ausgeführt. Da war alles schon abgelaufen, und konnte nicht mehr verlängert werden.
**ZonePlayer-Icon wird nun immer beim Discover-Event heruntergeladen. Damit wird es auch wieder aktualisiert, wenn FHEM das Icon beim Update verwirft.
**MinVolume und MaxVolume eingeführt. Damit kann nun der Lautstärkeregelbereich der ZonePlayer festgelegt werden
**Umlaute beim Übertragen in das Reading State werden wieder korrekt übertragen. Das Problem waren die etwaigen doppelten Anführungsstriche. Diese werden nun maskiert.
**Sonos Docks werden nun auch erkannt. Dieses hat eine andere Device-Struktur, weswegen der Erkennungsprozess angepasst werden musste.
*1.7:
**Umlaute werden bei Playernamen beim Anlegen des Devices korrekt umgewandelt, und nicht in Unterstriche
**Renew-Subscription eingebaut, damit ein Player nicht die Verbindung zum Modul verliert
**CurrentTempPlaying wird nun auch sauber beim Abbrechen des Restore-Vorgangs zurückgesetzt
**Die Discovermechanik umgebaut, damit dieser Thread nach einem Discover nicht neu erzeugt werden muss.
*1.6:
**Speak hinzugefügt (siehe Doku im Wiki)
**Korrektur von PlayURITemp für Dateien, für die Sonos keine Abspiellänge zur Verfügung stellt
**Korrektur des Thread-Problems welches unter *Nix-Varianten auftrat (Windows war nicht betroffen)
*1.5:
**PlayURI, PlayURITemp und AddURIToQueue hinzugefügt (siehe Doku im Wiki)
*1.4:
**Exception-Handling bei der Befehlsausführung soll FHEM besser vor verschwundenen Playern schützen
**Variable $SONOS_ThisThreadEnded sichert die korrekte Beendigung des vorhandenen Threads, trotz Discover-Events in der Pipeline
**Einrückungen im Code korrigiert
*1.3:
**StopHandling prüft nun auch, ob die Referenz noch existiert
*1.2:
**Proxy-Objekte werden beim Disappearen des Player entfernt, und sorgen bei einem nachfolgenden Aufruf für eine saubere Fehlermeldung
**Probleme mit Anführungszeichen " in Liedtiteln und Artist-Angaben. Diese Zeichen werden nun ersetzt
**Weblink wurde mit fehlendem "/" am Anfang angelegt. Dadurch hat dieser nicht im Floorplan funktionert
**pingType wird nun auf Korrektheit geprüft.
**Play:3 haben keinen Audio-Eingang, deshalb funktioniert das Holen eines Proxy dafür auch nicht. Jetzt ist das Holen abgesichert.
*1.1:
**Ping-Methode einstellbar über Attribut 'pingType'
*1.0:
**Initial Release

== Modul '''SONOS''' ==
Dieses Modul erledigt die eigentliche Kommunikationsarbeit zu den ZonePlayern mittles UPnP.
Es startet (und läßt ihn dauerhaft laufen) einen Discovery Prozess, der alle ZonePlayer auffordert, sich zu melden, und reagiert auf entsprechende Signalisierungen.
Es instantiiert einen Listener und meldet diesen bei allen ZonePlayern für Abspielaktualisierungen an.

Wenn ein Aufruf des Discovery-Prozesses erfolgt, wird geprüft, ob der Player bereits definiert wurde. Wenn nicht, wird eine Definition erzeugt, wenn ja, dann wird die Komponente mit den neu erhaltenen Informationen aktualisiert.

Wenn ein Aufruf der Abspielaktualisierung erfolgt, so wird die entsprechene Zoneplayer-Komponente in FHEM mit den neu erhaltenen Informationen aktualisiert, und entsprechende FHEM-Events generiert.

Wenn das Feature mit <code>minVolume</code> oder <code>maxVolume</code> verwendet wird, wird ein weiterer Listener beim entsprechenden Zoneplayer angemeldet. Mittels diesem werden Lautstärkenänderungen am Zoneplayer gemeldet umd können entsprechend umgehend korrigiert werden. Als Nebeneffekt wird für jede Lautstärkenänderung auch ein Event in FHEM erzeugt (als Folge einer Aktualisierung des Readings <code>Volume</code>).

=== Readings von SONOS ===
*<code>ZoneGroupState</code>: Die Konfigurationsinformationen zu der aktuellen Gruppenlandschaft der Zoneplayer. Der Befehl <code>get SONOS Groups</code> vereinfacht den Zugriff hierauf, indem es eine einfach les- und verarbeitbare Liste erzeugt.
*<code>UserId_Spotify</code>: Speichert die UserId für den Spotify-Zugriff. Diese Information ist notwendig, wenn eine M3U-Datei mit Spotify-Titeln importiert werden soll, und wird automatisch ermittelt, sobald man mit dem Original-Controller einen einzelnen Titel aus Spotify in die aktuelle Abspielliste überträgt.
*<code>UserId_Napster</code>: Speichert die UserId für den Napster-Zugriff. Diese Information ist notwendig, wenn eine M3U-Datei mit Napster-Titeln importiert werden soll, und wird automatisch ermittelt, sobald man mit dem Original-Controller einen einzelnen Titel aus Napster in die aktuelle Abspielliste überträgt.

=== Attribute von SONOS ===
*<code>pingType(none,tcp,udp,icmp,syn)</code>: Definiert die Art, wie der Alive-Check eines Zoneplayers erfolgen soll. Die Verfahren funktionieren unterschiedlich gut. Am Ressourcensparsamsten ist ''icmp'', benötigt aber "<code>root</code>"-Rechte. An zweiter Stelle ist ''syn'' zu empfehlen. Die anderen Verfahren melden manchmal fehlerhafte not alives. Einfach probieren. Mittels ''none'' kann dieser Mechanismus auch deaktiviert werden.
*<code>targetSpeakDir</code>: Das Verzeichnis, in dem dieses Modul die Sprachdateien von <code>Speak</code> (siehe [http://www.fhemwiki.de/wiki/Sonos_Anwendungsbeispiel#Set-Befehle_an_den_SONOSPLAYER Set-Befehle an den SONOSPLAYER]) ablegen soll (also die Adresse für den '''Schreib'''zugriff). Es wird empfohlen, dass dieses Verzeichnis '''nicht''' von Sonos indiziert ist. z.B. Pfade unter *Nix: <code>/home/www/Sonos</code> oder unter Windows: <code>C:\InetPub\Sonos</code>
*<code>targetSpeakURL</code>: Die URL, unter der ''von außen'' (also aus Sicht des Zoneplayers) auf die abgelegte Sprachdatei zugegriffen werden kann (also die Adresse für den '''Lese'''zugriff). z.B. <code>\\192.168.178.45\Sonos</code>
*<code>targetSpeakFileTimestamp(0,1)</code>: Definiert, ob in dem Namen der Sprachausgabedatei ein Zeitstempel enthalten sein soll. Das sorgt dafür, dass alle Dateien beibehalten werden (da nicht mit demselben Namen überschrieben wird). Manchmal kann das auch Caching-Probleme beseitigen. In meinen Tests hat die Anzeige der in der Sprachdatei enthaltenen MP3-Tags nur mit dieser aktivierten Option sauber funktioniert, da der ZonePlayer bei mir die Tags gecached hält. Anderseits muss man sich dabei Gedanken über eine Aufräumstrategie machen, da die alten Dateien immer vorhanden bleiben.
*<code>targetSpeakFileHashCache(0,1)</code>: Definiert, ob in dem Namen der Sprachausgabedatei ein Hash-Wert enthalten sein soll. Das sorgt dafür, dass die Dateien bei gleichem Text wiederverwendet werden und nicht neu generiert werden.
**Für diese Funktionalität wird das Perl-Modul '''Digest::SHA1''' für die Berechnung des Hash-Werts benötigt. Am einfachsten kann es bei Bedarf per CPAN installiert werden: <code>sudo cpan install Digest::SHA1</code>.
*<code>Speak1</code>: Hiermit kann ein Systemaufruf definiert werden, der zu Erzeugung einer Sprachausgabe verwendet werden kann. Sobald dieses Attribut definiert wurde, ist ein entsprechender Setter am Sonosplayer verfügbar. Das Format ist: <Ausgabedateiendung>:<Befehlszeile>
**Es dürfen folgende Platzhalter verwendet werden: '''%language%''': Wird durch die eingegebene Sprache ersetzt '''%filename%''': Wird durch den kompletten Dateinamen (inkl. Dateiendung) ersetzt. '''%text%''': Wird durch den zu übersetzenden Text ersetzt.
*<code>Speak2</code>: Siehe Speak1
*<code>Speak3</code>: Siehe Speak1
*<code>Speak4</code>: Siehe Speak1

=== Get-Befehle an SONOS ===
*<code>Groups</code>: Liefert die aktuelle Gruppierungskonfiguration der Sonos-Systemlandschaft zurück. Das Format ist eine Komma-getrennte Liste von Listen mit Devicenamen, also z.B. <code>[Sonos_Kueche], [Sonos_Wohnzimmer, Sonos_Schlafzimmer]</code>. In diesem Beispiel sind also zwei Gruppen definiert, von denen die erste aus einem Player und die zweite aus Zwei Playern besteht. Dabei ist die Reihenfolge innerhalb der Unterlisten wichtig, da der erste Eintrag der sogenannte Gruppenkoordinator ist (in diesem Fall also <code>Sonos_Wohnzimmer</code>), von dem die aktuelle Abspielliste und der aktuelle Titel auf die anderen Gruppenmitglieder übernommen wird.

=== Set-Befehle an SONOS ===
*<code>Groups <Gruppendefinition></code>: Setzt die aktuelle Gruppierungskonfiguration der Sonos-Systemlandschaft. Das Format ist jenes, welches auch von dem Get-Befehl ''Groups'' geliefert wird.
*<code>StopAll</code>: Stoppt die Wiedergabe in allen Zonen.
*<code>PauseAll</code>: Pausiert die Wiedergabe in allen Zonen.

== Modul '''SONOSPLAYER''' ==
Dieses Modul dient im großen und ganzen als Platzhalter für FHEM, damit der Anwender FHEM-Konform informiert werden, bzw. steuern kann.

Hier werden die Informationen, die vom '''SONOS'''-Modul erkannt werden, abgelegt, und die Aktualisierungs-Events erzeugt.

=== Readings von SONOSPLAYER ===
Folgende Informationen werden im SONOSPLAYER als Reading abgelegt:
*Grundlegendes
**<code>presence</code>: Erreichbarkeit des Players. Kann "appeared" oder "disappeared" sein
**<code>roomName</code>: Originalname des ZonePlayers. Kann Leer- oder Sonderzeichen enthalten
**<code>saveRoomName</code>: Sicherer Name des Zoneplayer. Sonderzeichen wurden in Unterstriche umgewandelt. Das Device wird beim Anlegen mit diesem Namen angelegt
**<code>playerType</code>: Typbezeichnung des ZonePlayer. z.B. "ZP90"
**<code>fieldType</code>: In einer Paarung wird jedem Player vom Sonos-System ein eindeutiger FieldType zugewiesen. Dieser wird von diesem Modul für die Eindeutigkeit des Device-Namen verwendet. Bei einer Stereopaarung z.B. hat ein Player den Type 'LF' (für Left-Front), 'RF' (für Right-Front) oder SW (für Subwoofer); bei Surround-Komfigurationen aber auch RR (für Right-Rear) oder LR (für Left-Rear).
**<code>location</code>: URL zum Informationsdokument des ZonePlayers
**<code>softwareRevision</code>: Version der installierten Software. z.B. "3.8.4"
**<code>serialNum</code>: Seriennummer des ZonePlayers. Entspricht weitestgehend der MAC-Adresse. z.B. "00-0E-58-28-D0-F4:2"
**<code>LastActionResult</code>: Enthält den Namen und das Ergebnis der letzten Aktion auf dem Player. Da die Aktionen asyncron übertragen werden, kann nur hier kontrolliert werden, ob das gewünschte Ergebnis erreicht wurde.
**<code>Volume</code>: Enthält im Normalfall die am Player eingestellte Laustärke zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird diese Lautstärke bei jeder Änderung am Player mit aktualisiert. Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung der Lautstärke auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Mute</code>: Enthält, wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, den aktuellen Zustand des Mute. Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Mute-Zustands auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Shuffle</code>: Enthält den aktuellen Zustand von Shuffle. Wird durch Event des Players aktualisiert (zusammen mit der Titelinformation).
**<code>Repeat</code>: Enthält den aktuellen Zustand von Repeat. Wird durch Event des Players aktualisiert (zusammen mit der Titelinformation).
**<code>CrossfadeMode</code>: Enthält den aktuellen Zustand von CrossfadeMode. Wird durch Event des Players aktualisiert (zusammen mit der Titelinformation).
**<code>Bass</code>: Enthält im Normalfall den am Player eingestellten Basslevel zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird dieser Basslevel bei jeder Änderung am Player mit aktualisiert. Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Basslevels auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Treble</code>: Enthält im Normalfall den am Player eingestellten Treblelevel zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird dieser Treblelevel bei jeder Änderung am Player mit aktualisiert. Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Treblelevels auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Balance</code>: Enthält im Normalfall die am Player eingestellte Balance zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird diese Balance bei jeder Änderung am Player mit aktualisiert. Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung der Balance auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Loudness</code>: Enthält, wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, den aktuellen Zustand des Loudness. Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Loudness-Zustands auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>HeadphoneConnected</code>: Enthält, wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> (oder auch <code>minVolumeHeadphone</code> und <code>maxVolumeHeadphone</code>) gesetzt wurde, den Zustand, ob ein Kopfhörer verwendet wird, oder nicht. Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung dieses Zustands auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>SleepTimer</code>: Enthält die Restzeit des Sleeptimers. Diese Information wird vom Player beim Setzen und Ablaufen gemeldet, und erzeugt somit ein Event zu Beginn und Ende des Timers. Während der Timer läuft, wird hier nichts aktualisiert. Man muss also, falls benötigt, selber die verbleibende Restzeit mittels des Readings-Timestamps und diesem Wert ermitteln. Diese Information wird automatisch aktualisiert, wenn sie bei einem Player verändert wird. Beim Ablaufen des Timers wird vom Player eine Aktualisierung auf den Wert '''off''' gesendet. Darauf kann in einem Notify-Event geprüft werden.
**<code>SleepTimerVersion</code>: Dieses Reading enthält die Information über die aktuelle Version der gespeicherten ''SleepTimer''-Informationen. Diese Information wird Hauptsächlich intern benötigt, um beurteilen zu können, ob das Reading ''SleepTimer'' neu geladen werden muss.
**<code>AlarmRunning</code>: Dieses Reading enthält ''1'', wenn gerade ein Alarm abgespielt wird, sonst ''0''
**<code>AlarmRunningID</code>: Dieses Reading enthält die ID des verursachenden Alarms, wenn gerade ein Alarm abgespielt wird, sonst ist es leer.
**<code>DailyIndexRefreshTime</code>: Enthält die aktuell gültige ''DailyIndexRefreshTime'', zu der der Medienindex neu aufgebaut werden soll. Diese Information wird automatisch aktualisiert, wenn sie bei einem Player verändert wird, wenn das Attribut '''getAlarms''' des Player auf ''1'' gesetzt wurde.
**<code>AlarmList</code>: Enthält die textuelle Repräsentation des Hashs mit den aktuell für diesen Player gültigen Alarminformationen. Diese Information wird automatisch aktualisiert, wenn das Attribut '''getAlarms''' auf ''1'' gesetzt wurde, ansonsten steht sie nicht zur Verfügung (und es kann kein Alarm angelegt, verändert und gelöscht werden). Das Format des Hashs entspricht dem, das zum Setzen oder Anpassen eines Alarms notwendig ist. Folgene Schlüssel sind dort zulässig/notwendig:
***'''Enabled(0,1)''': Gibt an, ob der Alarm aktiviert ist.
***'''Volume(0..100)''': Die Lautstärke, mit der der Alarm wiedergegeben werden soll.
***'''StartTime(Timstamp)''': Die Uhrzeit, zu der der Alarm starten soll.
***'''Duration(Timstamp)''': Die Dauer, die der Alarm laufen soll.
***'''Repeat(0,1)''': Gibt an, ob die Wiedergabe wiederholt werden soll.
***'''Shuffle(0,1)''': Gibt an, ob die Wiedergabe zufällig erfolgen soll.
***'''RoomUUID''': Die ID der Zone, in der der Alarm wiedergegeben werden soll. Dieser Wert muss nie mit angegeben werden, da er automatisch befüllt wird (Diese Information ist durch das verwendete Fhem-Zoneplayer-Device klar).
***'''ProgramURI''': Die abzuspielende URI.
***'''ProgramMetaData''': Die Metadaten zu der abzuspielenden URI.
***'''Recurrence_Once(0,1)''': Gibt an, dass der Alarm nur einmal laufen soll. Wenn hier eine ''1'' angegeben wurde, dann werden die anderen ''Recurrence''-Angaben ignoriert.
***'''Recurrence_Monday(0,1)''': Gibt an, dass der Alarm jeden Montag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Tuesday(0,1)''': Gibt an, dass der Alarm jeden Dienstag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Wednesday(0,1)''': Gibt an, dass der Alarm jeden Mittwoch laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Thursday(0,1)''': Gibt an, dass der Alarm jeden Donnerstag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Friday(0,1)''': Gibt an, dass der Alarm jeden Freitag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Saturday(0,1)''': Gibt an, dass der Alarm jeden Samstag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Sunday(0,1)''': Gibt an, dass der Alarm jeden Sonntag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''IncludeLinkedZones(0,1)''': Gibt an, ob die aktuell verlinkten Zonen diesen Alarm ebenfall abspielen sollen.
***'''Beispiel-Hash''': { Enabled => 1, Volume => 12, StartTime => '16:00:00', Duration => '00:15:00', Repeat => 0, Shuffle => 0, ProgramURI => 'x-rincon-buzzer:0', ProgramMetaData => ' ', Recurrence_Once => 0, Recurrence_Monday => 1, Recurrence_Tuesday => 1, Recurrence_Wednesday => 1, Recurrence_Thursday => 1, Recurrence_Friday => 1, Recurrence_Saturday => 0, Recurrence_Sunday => 0, IncludeLinkedZones => 0 }
**<code>AlarmListIDs</code>: Enthält die Hash-Schlüssel der Alarme als kommaseparierte Liste. Dieses Reading gibt es Hauptsächlich zur Vereinfachung des Zugriffs auf das Reading '''AlarmList'''. Damit hat man direkt die Anzahl und Primärschlüssel im Zugriff.
**<code>AlarmListVersion</code>: Dieses Reading enthält die Information über die aktuelle Version der gespeicherten Alarm-Informationen. Diese Information wird Hauptsächlich intern benötigt, um beurteilen zu können, ob die Alarminformationen neu geladen werden müssen.
**<code>ZoneGroupID</code>: Die ID des Gruppenkoordinators plus eine laufende Nummer. Sollte die Gruppe nur aus einem Mitglied bestehen, so ist es die eigene ID (=UDN).
**<code>ZoneGroupName</code>: Der Name der aktuellen Gruppe
**<code>ZonePlayerUUIDsInGroup</code>: Eine Liste der in der aktuellen Gruppe befindlichen Zoneplayer.
**<code>LineInConnected</code>: Gibt an, ob der Line-In-Eingang angeschlossen ist, oder nicht. Wird bei Änderung am Player automatisch aktualisiert, und erzeugt damit auch ein Event.
*Infos zum aktuellen Titel
**<code>currentTitle</code>: Titelbezeichnung des aktuellen Titels
**<code>currentArtist</code>: Interpret des aktuellen Titels
**<code>currentAlbum</code>: Albumname des aktuellen Titel
**<code>currentAlbumArtist</code>: Interpret des Albums. Kann z.B. auch "(compilations)" sein.
**<code>currentOriginalTrackNumber</code>: Nummer des aktuellen Titels bezogen auf das Album
**<code>currentTrack</code>: Nummer des aktuellen Titels in der Abspielliste
**<code>currentTrackURI</code>: Dateipfad des aktuellen Titels in der Abspielliste. Gültige Formate siehe PlayURI.
**<code>currentTrackDuration</code>: Länge des aktuellen Titels im Format H:MM:SS
**<code>currentSender</code>: Senderbezeichnung, wenn es ein Radiostream ist
**<code>currentSenderCurrent</code>: Zusatzinformationen zur Radiosendung, meist der Programmtitel wie 'Pop&Weck'
**<code>currentSenderInfo</code>: Zusatzinforationen zur Radiosendung, meist der Titel des aktuellen Liedes
**<code>currentAlbumArtURI</code>: Relativer Verzeichnis-Pfad im lokalen FHEM (physisch). Beginnt momentan mit "www"
*Infos zum nächsten Titel
**<code>nextTitle</code>: Titelbezeichnung des nächsten Titels
**<code>nextArtist</code>: Interpret des nächsten Titels
**<code>nextAlbum</code>: Albumname des nächsten Titel
**<code>nextAlbumArtist</code>: Interpret des Albums des nächsten Titels. Kann z.B. auch "(compilations)" sein.
**<code>nextOriginalTrackNumber</code>: Nummer des nächsten Titels bezogen auf das Album
**<code>nextAlbumArtURI</code>: Relativer Verzeichnis-Pfad im lokalen FHEM (physisch). Beginnt momentan mit "www"
**<code>nextTrackURI</code>: Dateipfad des nächsten Titels in der Abspielliste. Gültige Formate siehe PlayURI.
**<code>nextTrackDuration</code>: Länge des nächsten Titels im Format H:MM:SS
*Generierte Informationen
**<code>infoSummarize1</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>infoSummarize2</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>infoSummarize3</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>infoSummarize4</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>currentStreamAudio</code>: Boolean. 1 wenn gerade ein Radiostream läuft, sonst 0. Momentan faktisch Negation zu <currentNormalAudio>
**<code>currentNormalAudio</code>: Boolean. 1 wenn gerade ein normaler Titel läuft, sonst 0. Momentan faktisch Negation zu <currentStreamAudio>
*Infos zum Gesamtstatus
**<code>transportState</code>: Aktueller Abspielstatus. Kann "ERROR", "STOPPED", "PLAYING" oder "PAUSED_PLAYBACK" sein. Wobei ERROR heißt, dass es keine Verbindung zum Player gibt
**<code>numberOfTracks</code>: Anzahl der momentan in der Abspielliste befindlichen Titel

=== Attribute von SONOSPLAYER ===
*<code>disable(0,1)</code>: Deaktiviert die Verarbeitung von Events dieses Devices
*<code>VolumeStep</code>: Definiert die Schrittweite für den Aufruf von <code>VolumeU</code> und <code>VolumeD</code>.
*<code>generateVolumeSlider(0,1)</code>: Aktiviert einen Slider für die Lautstärkeneinstellung auf der Detailansicht. Standardmäßig ist dieser aktiviert (=1).
*<code>generateVolumeEvent(0,1)</code>: Aktiviert die Generierung eines Events bei Lautstärkeänderungen, wenn mindestens eines der Attribute <code>minVolume</code>, <code>maxVolume</code>, <code>minVolumeHeadphone</code> oder <code>maxVolumeHeadphone</code> definiert ist. Standardmäßig ist dies deaktiviert (=0), um die Zeitverzögerung so gering wie möglich zu halten.
*<code>generateSomethingChangedEvent(0,1)</code>: Bestimmt, ob ein Event mit dem Namen 'SomethingChanged' generiert werden soll, wenn überhaupt ein Event generiert wurde. Das ist nützlich, wenn man auf eine beliebige Änderung des Player reagieren möchte.
*<code>generateInfoSummarize1</code>: Generiert das Reading 'InfoSummarize1' mit dem angegebenen Format.
*<code>generateInfoSummarize2</code>: Generiert das Reading 'InfoSummarize2' mit dem angegebenen Format.
*<code>generateInfoSummarize3</code>: Generiert das Reading 'InfoSummarize3' mit dem angegebenen Format.
*<code>generateInfoSummarize4</code>: Generiert das Reading 'InfoSummarize4' mit dem angegebenen Format.
*<code>stateVariable(TransportState,NumberOfTracks,Track,TrackDuration,Title,Artist,Album, 
OriginalTrackNumber,AlbumArtist,Sender,SenderCurrent,SenderInfo,StreamAudio,NormalAudio, 
AlbumArtURI,nextTrackDuration,nextTrackURI,nextAlbumArtURI,nextTitle,nextArtist, 
nextAlbum,nextAlbumArtist,nextOriginalTrackNumber,Volume,Mute,Shuffle,Repeat,CrossfadeMode, 
Balance,HeadphoneConnected,SleepTimer,Presence,RoomName,SaveRoomName,PlayerType,Location, 
SoftwareRevision,SerialNum,InfoSummarize1,InfoSummarize2,InfoSummarize3,InfoSummarize4)</code>: Legt fest, welcher Variablenwert in den State geschrieben werden soll.
*<code>minVolume(0..100)</code>: Legt die untere Grenze für die einstellbare Lautstärke dieses ZonePlayers fest. Diese kann auch mit keinem Controller unterschritten werden, da diese überwacht wird.
**Wenn eine untere oder obere Grenze festgelegt wurde, so wird das Reading '''Volume''' am entsprechenden SonosPlayer bei jeder Änderung am Player aktualisiert. Möchte man also immer die aktuelle Lautstärke kennen, aber keine Enschränkung machen, dann sollte der Wert von <code>minVolume</code> auf <code>0</code> oder <code>maxVolume</code> auf <code>100</code> gesetzt werden. Desweiteren werden gleichzeitig auch Änderungen an der Balance aktualisiert, da diese mit übertragen werden.
**'''Achtung!''': Wenn eine untere oder obere Grenze festgelegt wird, werden für Lautstärkenänderungen auch Events erzeugt. Es ist unbedingt darauf zu achten, dass etwaige Notify-Definitionen zügig bearbeitet werden, da sonst das Sonos-System träge werden könnte.
*<code>maxVolume(0..100)</code>: Legt die obere Grenze für die einstellbare Lautstärke dieses ZonePlayers fest. Diese kann auch mit keinem Controller überschritten werden, da diese überwacht wird.
**Wenn eine untere oder obere Grenze festgelegt wurde, so wird das Reading '''Volume''' am entsprechenden SonosPlayer bei jeder Änderung am Player aktualisiert. Möchte man also immer die aktuelle Lautstärke kennen, aber keine Enschränkung machen, dann sollte der Wert von <code>minVolume</code> auf <code>0</code> oder <code>maxVolume</code> auf <code>100</code> gesetzt werden. Desweiteren werden gleichzeitig auch Änderungen an der Balance aktualisiert, da diese mit übertragen werden.
**'''Achtung!''': Wenn eine untere oder obere Grenze festgelegt wird, werden für Lautstärkenänderungen auch Events erzeugt. Es ist unbedingt darauf zu achten, dass etwaige Notify-Definitionen zügig bearbeitet werden, da sonst das Sonos-System träge werden könnte.
*<code>minVolumeHeadphone(0..100)</code>: Legt die untere Grenze für die einstellbare Lautstärke dieses ZonePlayers im Kopfhörerbetrieb fest.
**'''Hinweis!''': Es gelten die gleichen Bedingungen und Hinweise wie bei <code>minVolume</code>.
*<code>maxVolumeHeadphone(0..100)</code>: Legt die obere Grenze für die einstellbare Lautstärke dieses ZonePlayers im Kopfhörerbetrieb fest.
**'''Hinweis!''': Es gelten die gleichen Bedingungen und Hinweise wie bei <code>maxVolume</code>.
*<code>getAlarms(0,1)</code>: Meldet sich bei Playern für die Aktualisierung von Alarm-Informationen an. Diese werden bei Änderung direkt aktualisiert, und erzeugen dementsprechend ein Fhem-Event. Gleichzeitig wird hiermit die '''DailyIndexRefreshTime''' mit aktualisiert.
*<code>buttonEvents <Time:Pattern>[ <Time:Pattern> ...]</code>: Definiert, dass bei einer bestimten Tastenfolge am Player ein Event erzeugt werden soll. Die Definition der Events erfolgt als Tupel: Der erste Teil vor dem Doppelpunkt ist die Zeit in Sekunden, die berücksichtigt werden soll, der zweite Teil hinter dem Doppelpunkt definiert die Abfolge der Buttons, die für dieses Event notwendig sind.
**Folgende Button-Kürzel sind zulässig:
***'''M''': Der Mute-Button ('''Achtung''': Der Mute-Button am SonosPlayer ist seit Firmware 4.2 ein Play/Pause/Next-Button, der kein Mute-Event mehr erzeugt, meine Beschwerde an Sonos, dass es nicht benutzerfreundlich ist, einen Mute-Symbolisierten Button mit Play/Pause zu belegen, wurde im großen und ganzen ignoriert)
***'''H''': Die Headphone-Buchse
***'''U''': Up-Button (Lautstärke Hoch)
***'''D''': Down-Button (Lautstärke Runter)
**Das Event, das geworfen wird, heißt <code>ButtonEvent</code>, der Wert ist die definierte Tastenfolge Z.B.: <code>2:MM</code> Hier wird definiert, dass ein Event erzeugt werden soll, wenn innerhalb von 2 Sekunden zweimal die Mute-Taste gedrückt wurde. Das damit erzeugte Event hat dann den Namen <code>ButtonEvent</code>, und den Wert <code>MM</code>.

=== Get-Befehle an den SONOSPLAYER ===
'''Hinweis!''': Es wurden ein paar Get-Möglichkeiten entfernt. Diese Befehle (wie z.B. ''Volume'') können mittlerweile direkt geliefert werden, und müssen nicht angefordert werden. Übrig geblieben sind nur noch solche Anweisungen, die Informationen beschaffen, die nicht automatisch geliefert werden (können).
*<code>CurrentTrackPosition</code>: Liefert die aktuelle Zeitposition im Lied
*<code>Favourites</code>: Liefert eine Liste mit den Namen aller gespeicherten Sonos-Favoriten. Das Format der Liste ist eine Komma-Separierte Liste, bei der die Namen in doppelten Anführungsstrichen stehen. z.B. "Liste 1","Eintrag 2","Test"
*<code>Playlists</code>: Liefert eine Liste aller gespeicherten Playlists. Diese Anfrage liefert bei allen Zoneplayern die gleiche Liste zurück. Das Format ist eine Komma-Separierte Liste, bei der die Einträge in doppelten Anführungszeichen stehen z.B. "Liste 1","Liste 2","Test"
*<code>Radios</code>: Liefert eine Liste aller gespeicherten Radiosender (Favoriten). Diese Anfrage liefert bei allen Zoneplayern die gleiche Liste zurück. Das Format ist eine Komma-Separierte Liste, bei der die Einträge in doppelten Anführungszeichen stehen z.B. "Sender 1","Sender 2","Test"
*<code>Alarm <ID></code>: Ausnahmefall. Diese Get-Anweisung liefert direkt ein Hash zurück, in welchem die Informationen des Alarms mit der gegebenen ID enthalten sind. Es ist die Kurzform für <code>eval(ReadingsVal(<Devicename>, 'Alarmlist', ()))->{<ID>};</code>, damit sich nicht jeder ausdenken muss, wie er jetzt am einfachsten an die Alarm-Informationen rankommen kann.
*<code>EthernetPortStatus <PortNumber></code>: Liefert den Ethernet-Portstatus des gegebenen Ports ('0' oder '1'). Kann 'Active' oder 'Inactive' liefern.

=== Set-Befehle an den SONOSPLAYER ===
'''Hinweis!''': Alle Set-Befehle liefern kein direktes Ergebnis zurück. Sollte ein Ergebnis generiert werden (meistens eine Statusmeldung, bzw. was genau getan wurde), so landet dies nach der Ausführung in dem Reading <code>LastActionResult</code>.
*<code>Play</code>: Startet die Wiedergabe
*<code>Pause</code>: Pausiert die Wiedergabe
*<code>Stop</code>: Stoppt die Wiedergabe
*<code>Next</code>: Springt zum Anfang des nächsten Liedes
*<code>Previous</code>: Springt zum Anfang des vorhergehenden Liedes. Das ist ein anderes Verhalten als mit einem Controller. Der Controller springt zunächst an den Anfang des aktuellen Liedes, und erst beim erneuten Drücken an den Anfang des vorhergehenden Liedes.
*<code>LoadPlaylist <Playlistname> [ListeVorherLeeren]</code>: Lädt die benannte Playliste in die aktuelle Abspielliste. Der Parameter kann/muss URL-Encoded sein, um auch Leer- und Sonderzeichen angeben zu können. Wenn der Parameter ''ListeVorherLeeren'' mit ''1'' angegeben wurde, wird die aktuelle Abspielliste vor dem Import geleert. Standardmäßig wird hier eine ''1'' angenommen.
**'''Hinweis''': Es kann auch ein Dateiname angegeben werden, um eine übliche M3U-Datei aus dem Filesystem zu laden. Dieser muss mit "'''file:'''" eingeleitet werden. Beispiel: "'''file:c:/Test.m3u'''". Innerhalb der Datei selbst werden bislang folgende Sonderformate unterstützt:
***'''Spotify:''' Titel aus Spotify werden mit dem Kürzel ''x-sonos-spotify:'' begonnen.
***'''Napster/Rhapsody:''' Titel aus Napster/Rhapsody werden mit dem Kürzel ''npsdy:'' begonnen.
***''Hinweise'': Die Benutzernamen für diese Importe, die zum Zeitpunkt des Import bekannt sein müssen, müssen zuvor dem System bekannt gemacht werden. Ansonsten erscheint eine entsprechende Fehlermeldung. So kann der Benutzername für eines der Systeme bekannt gemacht werden:
****Aktuelle Abspielliste eines Players leeren
****Einen beliebigen Titel aus dem gewünschten Anbieter in die aktuelle Abspielliste einfügen. Dabei ist zu beachten, dass man das direkt aus der Auswahl des Anbietes heraus macht (also nicht über eine Playliste, Favoriten o.ä. Direktzugriffe)
****Nun gibt es ein neues Reading am zentralen Sonos-Device, welches den Benutzernamen enthält. Um diesen Dauerhaft bereitzustellen, muss der Zustand mittels ''save'' gespeichert werden.
*<code>SavePlaylist <Playlistname></code>: Speichert die aktuelle Abspielliste unter dem angegebenen Namen als Playliste ab. Dabei wird eine etwaig bestehende Liste gleichen Namens überschrieben. Der Parameter kann/muss URL-Encoded sein, um auch Leer- und Sonderzeichen angeben zu können.
**'''Hinweis''': Es kann auch ein Dateiname angegeben werden, um eine übliche M3U-Datei im Filesystem zu erzeugen. Dieser muss mit "'''file:'''" eingeleitet werden. Beispiel: "'''file:c:/Test.m3u'''". ''Nähere Informationen zum möglichen Inhalt der Datei siehe unter '''LoadPlayList'''.''
*<code>EmptyPlaylist</code>: Löscht die aktuelle Abspielliste
*<code>CurrentPlaylist</code>: Setzt den Abspielmodus auf die aktuelle Abspielliste, startet aber keine Wiedergabe (z.B. nach dem Hören eines Radiostreams, wo die aktuelle Abspielliste zwar noch existiert, aber gerade "nicht verwendet" wird)
*<code>StartFavourite <FavouriteName> [NoStart]</code>: Startet den angegebenen Favoriten. Der Name bezeichnet einen Eintrag in der Sonos-Favoritenliste. Der Parameter sollte/kann URL-Encoded werden um auch Spezialzeichen zu ermöglichen.
**Wenn das Wort 'NoStart' als zweiter Parameter angegeben wurde, dann wird der Favorit geladen und fertig vorbereitet, aber nicht explizit gestartet.
**Folgende Unterscheidungen werden auf Basis des Typs des Sonos-Favoriten gemacht:
***Bei einem Playlist-Typ (z.B. Sonos-Playlist, Spotify-Playlist, usw.) wird die aktuelle Abspielliste geleert, mit dem neuen Inhalt befüllt und die Wiedergabe gestartet
***Bei einem Einzel-Eintrag (Direkter Titel, Radiosender, Spotify-Titel, usw) wird die aktuelle Abspielliste nicht angetastet, sondern der aktuelle Abspieleintrag entsprechend angepasst und gestartet
*<code>LoadRadio <Radiostationname></code>: Lädt den benannten Radiosender, genauer gesagt, den benannten Radiofavoriten. Dabei wird die bestehende Abspielliste beibehalten, aber deaktiviert. Der Parameter kann/muss URL-Encoded sein, um auch Leer- und Sonderzeichen angeben zu können.
*<code>Mute <State></code>: Setzt den Mute-Zustand auf den angegebenen Wert. Der Wert kann on oder off sein. Liefert als Ergebnis den neuen Zustand.
*<code>MuteT</code>: Schaltet den Mute-Zustand um. Liefert als Ergebnis den neuen Zustand.
*<code>Shuffle</code>: Legt den Zustand des Shuffle-Zustands fest. Liefert den aktuell gültigen Shuffle-Zustand.
*<code>Repeat</code>: Legt den Zustand des Repeat-Zustands fest. Liefert den aktuell gültigen Repeat-Zustand.
*<code>CrossfadeMode</code>: Legt den Zustand des Crossfade-Mode fest. Liefert den aktuell gültigen Crossfade-Mode.
*<code>LEDState</code>: Legt den Zustand der LED fest. Liefert den aktuell gültigen Zustand zurück.
*<code>SleepTimer</code>: Legt den aktuellen SleepTimer fest. Der Wert muss ein kompletter Zeitstempel sein (HH:MM:SS). Zum Deaktivieren darf der Zeitstempel nur Nullen enthalten oder das Wort 'off'.
*<code>DailyIndexRefreshTime</code>: Legt die aktuell gültige ''DailyIndexRefreshTime'' fest, zu der der Medienindex neu aufgebaut werden soll. Der Wert muss ein kompletter Zeitstempel sein (HH:MM:SS).
*<code>VolumeD</code>: Verringert die Lautstärke um 10 Einheiten.
*<code>VolumeU</code>: Erhöht die Lautstärke um 10 Einheiten.
*<code>Volume <VolumeLevel> [RampType]</code>: Setzt die Lautstärke auf den angegebenen Wert. Der kann eine relative Angabe mittels + oder - sein. Dann wird um die entsprechende Höhe erhöht oder verringert. Wird eine relative Lautstärke angegeben, so kann diese mit einem folgenden Prozentzeichen als anteilige Änderung ausgeführt werden (z.B. +20%). Liefert als Ergebnis die neue Lautstärke. Als optionaler Parameter ist ein Ramptype zulässig. Mögliche Werte sind 1 (SLEEP_TIMER_RAMP_TYPE), 2 (AUTOPLAY_RAMP_TYPE) und 3 (ALARM_RAMP_TYPE). Die Werte entsprechen verschiedenen Mustern bei der Geschwindigkeit nach oben oder unten.
*<code>Balance</code>: Setzt die Balance auf den angegebenen Wert. Der Wert kann zwischen -100 (voll links) und 100 (voll rechts) liegen. Gibt die wirklich eingestellte Balance als Ergebnis zurück.
*<code>VolumeSave <VolumeLevel></code>: Setzt die Lautstärke auf den angegebenen Wert. Der kann eine relative Angabe mittels + oder - sein. Dann wird um die entsprechende Höhe erhöht oder verringert. Liefert als Ergebnis die neue Lautstärke. Zusätzlich wird die alte Lautstärke in einem Reading abgelegt, um sie wiederherstellen zu können.
*<code>VolumeRestore</code>: Stellt die mittels VolumeSave gespeicherte Lautstärke wieder her.
*<code>CurrentTrackPosition <TimePosition></code>: Setzt die aktuelle Zeitposition im Lied
*<code>Track <TrackNumber></code>: Stellt das Lied an der Position TrackNumber in der Abspielliste als aktuelles Lied ein. Dabei kann als Tracknummer der Wert <code>Random</code> angegeben werden. Dann wird eine zufällige Tracknummer ausgewählt (diese Ermittlung erfolgt nach Setzen der aktuellen Abspielliste, und erfolgt somit korrekt auf die gesamte zur Verfügung stehende Liste).
*<code>PlayURI <SongURI> [Volume]</code>: Spielt die angegebene MP3-Datei mit der optional verwendbaren Lautstärke ab. Die Datei muss vom SonosPlayer aus direkt erreichbar (und natürlich auch lesbar) sein, braucht aber nicht indiziert worden zu sein. Folgende Formate werden momentan akzeptiert:
**'''Sonos-Devicenamen''': z.B. <code>Sonos_Wohnzimmer</code>. Der Devicename muss natürlich bereits definiert worden sein. Es wird der AV-Eingang des gewählten Zoneplayer-Device als Wiedergabestrom gewählt.
**'''UNC-Pfade''': z.B. <code>\\Server\Freigabe\Dateiname.mp3</code>. Erkennungsmerkmal ist der Doppelte Backslash am Anfang. Darstellung aller üblichen Informationen inkl. Cover u.ä.
**'''Web-Streams''': z.B. <code>http://www.energyradio.de/hot</code>. Erkennungsmerkmal ist die Angabe von <code>http://</code> am Anfang. Es werden keine Cover aber Streaminformationen dargestellt.
**'''Sonstige URI-Typen''': z.B. <code>x-sonos-spotify:spotify:track:0jkLC0noG4A4i9lob2gSc3?sid=9&flags=0</code>. Darstellung aller üblichen Informationen. Die verfügbaren Formate können durch Sonos erweitert/verändert werden. '''Hinweis''': Das Format der URI, das hier angegeben werden kann, ist stets identisch zum Reading '''currentTrackURI''', das bedeutet, dass die URI, die man dort sieht, hier direkt wieder angegeben werden kann. Es gibt lediglich die oben benannte Vereinfachung für MP3-Dateien und Radio-URLs (aber auch dafür könnte man das offizielle Format angeben).
*<code>PlayURITemp <SongURI> [Volume]</code>: Spielt die angegebene MP3-Datei mit der optional verwendbaren Lautstärke als temporäre Datei ab. Nachdem die Datei abgespielt wurde, werden die vorhergehenden Abspielparameter (Lautstärke, Titel, Position usw.) wiederhergestellt. Im Normalfall geht es also direkt dort weiter, wo die Unterbrechung stattgefunden hat. Die Datei muss vom SonosPlayer aus direkt erreichbar (und natürlich auch lesbar) sein, braucht aber nicht indiziert worden zu sein. Für eine ordnungsgemäße Wiederherstellung ist es notwendig, dass dies eine Datei und kein Stream ist, da die Abspiellänge vorher bekannt sein muss.
**Für Streams (genauer: Für Dateien, deren Abspiellänge nicht ermittelt werden kann) ist dieser Aufruf identisch zu <code>PlayURI</code>, es wird im Anschluß nichts wiederhergestellt.
**Zulässige Formate stehen unter <code>PlayURI</code>.
**'''Achtung!''': Zum Ermitteln der Liedlänge wird u.U. eine zusätzliche Library verwendet (Wenn die Info nicht vom SonosPlayer bereitgestellt wird): <code>MP3::Info</code>. Diese Library muss zusätzlich in das FHEM-Lib-Verzeichnis kopiert werden.
**'''Achtung!''': Wenn bereits eine temporäre Ausgabe erfolgt, so wird die Aufforderung mit einer entsprechenden Meldung verworfen. Es kann nur eine geben :-)
*<code>AddURIToQueue <SongURI></code>: Fügt die angegebene Datei in die aktuelle Abspielliste an die Stelle hinter dem aktuellen Titel hinzu. Ändert nichts am aktuell abgespielten Titel. Zulässige Formate stehen unter <code>PlayURI</code>.
**'''Achtung!''': Es kann auch ein Radio-Stream hinzugefügt werden. Dieser wird auch normal abgespielt, wenn er dran ist. Dabei ist zu beachten, dass dieser Titel nie enden wird, und die Titel- und Interpretinformationen nicht dargestellt werden. Auch nicht die sonst üblichen Streaminformationen. Diese werden nur angezeigt, wenn der Stream mittels <code>PlayURI</code> direkt (ohne Verwendung der Queue) abgespielt wird.
*<code>Speak <Volume> <Language> <Text></code>: Wandelt den angegebenen Text mittels Google in gesprochenen Text um und spielt diesen mittels <code>PlayURITemp</code> ab. An dieser Stelle ist zu berücksichtigen, dass der Text-Parameter auch Leerzeichen enthalten darf (und damit nach FHEM-Regeln eigentlich mehrere Parameter sind). Deswegen steht die Lautstärke vorne als nicht optionaler Parameter.
**'''Hinweis''': In dem generierten MP3 wird ein ID3-Tag eingetragen, in dem die Umlaute wohl leider nicht sauber ankommen. Deswegen ist im Sonos-Controller die Anzeige dieser Umlaute bei den Sprachdurchsagen auch nicht korrekt.
**'''Achtung!''': Für die korrekte Funktionsweise müssen die Attribute <code>targetSpeakDir</code> und <code>targetSpeakURL</code> am Sonos-Device konfiguriert sein (siehe [http://www.fhemwiki.de/wiki/Sonos_Anwendungsbeispiel#Attribute_von_SONOS Attribute von SONOS]).
**Mögliche Sprachparameter können bei Google herausgefunden werden. Diese sind z.B. '''de''', '''en''', '''es''', '''fr''', '''it'''...
**'''Achtung!''': Die Textlänge ist durch Google begrenzt. Wenn die Größe überschritten wird, erhält man eine Fehlermeldung im Log: "''404 Not found''". Leider erhielt ich in meinen Tests unterschiedliche Ergebnisse bzgl. der verwendbaren Länge (ca. 100 Zeichen). Einfach probieren.
**'''Achtung!''': Wenn bereits eine temporäre Ausgabe erfolgt, so wird die Aufforderung mit einer entsprechenden Meldung verworfen. Es kann nur eine geben :-)
*<code>Alarm <Create|Update|Delete> <ID> <Datenhash></code>: Diese Anweisung wird für die Bearbeitung der Alarme verwendet:
**'''Create''': Erzeugt einen neuen Alarm-Eintrag mit den übergebenen Hash-Daten. Der Rückgabewert ist die ID des neuen Alarms.
**'''Update''': Aktualisiert den Alarm mit der übergebenen ID und den angegebenen Hash-Daten.
**'''Delete''': Löscht den Alarm-Eintrag mit der übergebenen ID.
**'''Datenhash''': Das Format ist ein Perl-Hash und wird mittels der eval-Funktion interpretiert. Eine Beschreibung befindet sich bei der Dokumentation des Readings '''AlarmList''' oder den folgenden Beispielen.
**'''Beispiele''':
***<code>set Sonos_Wohnzimmer Alarm Create 0 { Enabled => 1, Volume => 35, StartTime => '00:00:00', Duration => '00:15:00', Repeat => 0, Shuffle => 0, ProgramURI => 'x-rincon-buzzer:0', ProgramMetaData => ' ', Recurrence_Once => 0, Recurrence_Monday => 1, Recurrence_Tuesday => 1, Recurrence_Wednesday => 1, Recurrence_Thursday => 1, Recurrence_Friday => 1, Recurrence_Saturday => 0, Recurrence_Sunday => 0, IncludeLinkedZones => 0 }</code>: Erzeugt einen neuen Alarm mit den angegebenen Informationen. Die neue ID wird als Ergebnis zurückgegeben.
***<code>set Sonos_Wohnzimmer Alarm Update 17 { Shuffle => 1 }</code>: Aktualisiert den Alarm mit der ID ''17'', und passt dort Shuffle auf ''Aktiv'' an.
***<code>set Sonos_Wohnzimmer Alarm Delete 17</code>: Löscht den Alarm mit der ID ''17''.
*<code>AddMember <Devicename></code>: Fügt dem Device das übergebene Device als Gruppenmitglied hinzu. Die Wiedergabe des aktuellen Devices bleibt erhalten, und wird auf das angegebene Device mit übertragen.
*<code>RemoveMember <Devicename></code>: Entfernt dem Device das übergebene Device, sodass die beiden keine Gruppe mehr bilden. Die Wiedergabe des aktuellen Devices läuft normal weiter. Das abgetrennte Device stoppt seine Wiedergabe, und hat keine aktuelle Abspielliste mehr (seit Sonos Version 4.2 hat der Player wieder die Playliste von vorher aktiv).
*<code>GroupVolume <VolumeLevel></code>: Setzt die Gruppenlautstärke. Das dafür verwendete Lautstärkenverhältnis muss zuvor einmal mittels def Anweisung '''SnapshotGroupVolume''' festgelegt worden sein.
**''Hinweis'': Wenn man '''GroupVolume''' aufruft, ohne vorher '''SnapshotGroupVolume''' aufgerufen zu haben, wird nur die Lautstärke des Players verändert, für den man den Aufruf durchführt.
*<code>SnapshotGroupVolume</code>: Legt das Lautstärkeverhältnis der aktuellen Player der Gruppe für folgende '''GroupVolume'''-Aufrufe fest. Dieses festgelegte Verhältnis wird bis zum nächsten Aufruf von '''SnapshotGroupVolume''' beibehalten.
**''Hinweis'': Das einzelne Verstellen von Zoneplayer-Laustärken mittels '''Volume''' wird nicht im bereits gespeicherten Lautstärkenverhältnis aktualisiert/widergespiegelt. Hat man also nachträglich die Lautstärke eines einzelnen Players geändert (auch über den Controller), so muss '''SnapshotGroupVolume''' erneut aufgerufen werden, damit das Verhältnis bei einer weiteren Gruppenlautstärkenänderung wieder erhalten bleibt (ansonsten wird das alte Verhältnis vor der Lautstärkeänderung wiederhergestellt).
**''Hinweis'': Dieser Aufruf muss vor einem eventuellen Aufruf von '''GroupVolume''' erfolgen, da sonst nur die Lautstärke des Players verändert, für den man den Aufruf durchführt.
**''Beispiel'' für eine Gruppe mit stark verschiedenen Lautstärken:
***Aufruf von '''SnapshotGroupVolume''' => Aktuelles Lautstärkeverhältnis wird gespeichert
***Aufruf von '''GroupVolume 2''' => Gruppe wird sehr leise gestellt, dabei sieht das relative Lautstärkeverhältnis fast gleich aus, da sich die Abstände immer weiter annähern
***Aufruf von '''GroupVolume 35''' => Gruppe wird laut gestellt, dabei kommt wieder das vorhergehende Lautstärkeverhältnis zum tragen
*<code>GroupMute <State></code>: Setzt den Mute-Zustand für die komplette Gruppe in einem Schritt. Der Wert kann on oder off sein.
*<code>Reboot</code>: Führt für den Zoneplayer einen Neustart durch.
*<code>Wifi <State></code>: Setzt den WiFi-Zustand des Players. Kann 'off', 'persist-off' oder 'on' sein.

== Definition der InfoSummarize ==
<pre>
infoSummarizeX := <NormalAudio>:sumElem:</NormalAudio> <StreamAudio>:sumElem:</StreamAudio>|
:sumElem:
sumElem := <:variable:[ prefix=":text:"][ suffix=":text:"][ instead=":text:"]
[ ifempty=":text:"][ emptyval=":text:"]/>
variable := TransportState|NumberOfTracks|Track|TrackDuration|Title|Artist|Album|
OriginalTrackNumber|AlbumArtist|Sender|SenderCurrent|SenderInfo|StreamAudio|NormalAudio|
AlbumArtURI|nextTrackDuration|nextTrackURI|nextAlbumArtURI|nextTitle|nextArtist|
nextAlbum|nextAlbumArtist|nextOriginalTrackNumber|Volume|Mute|Shuffle|Repeat|
CrossfadeMode|Balance|HeadphoneConnected|SleepTimer|Presence|RoomName|SaveRoomName|
PlayerType|Location|SoftwareRevision|SerialNum|InfoSummarize1|InfoSummarize2|
InfoSummarize3|InfoSummarize4
text := [Beliebiger Text ohne doppelte Anführungszeichen]
</pre>
Die Unterscheidung zwischen <code><NormalAudio></code> und <code><StreamAudio></code> liegt bei der anliegenden Musikquelle. Gestreamte Audioquellen habe nur einen kleineren Set an Informationen vorliegen, während bei einer "normalen" Musikquelle z.B. eine Unterscheidung zwischen Artist und Title gemacht wird, und im Gegenzug z.B. kein Sendername existiert. 
Man kann diese Unterscheidung auch weglassen, und direkt die Variablenausgaben hinschreiben. Dann gilt der Code für beide Musikquellenarten gleichermaßen (u.U. sind dann einige Felder nicht sinnvoll bzw. gar nicht gefüllt).

Die Tag-Erweiterungen <code>prefix</code> und <code>suffix</code> werden jeweils vor bzw. hinter den Feldwert in die Ausgabe gesetzt, wenn es einen Feldwert zum Ausgeben gibt. 
Die Erweiterung <code>instead</code> wird anstatt des Feldwerts ausgegeben, wenn normalerweise der Feldwert ausgegeben werden würde (abhängig davon, ob der Feldwert als ''empty'' angesehen wird, oder nicht). 
Die Erweiterung <code>ifempty</code> wird eingesetzt, wenn es gerade ''keinen'' Feldinhalt gibt. In diesem Fall werden natürlich auch keine Pre- und Suffixe sowie Instead-Angaben ausgegeben. 
Die Erweiterung <code>emptyval</code> legt fest, was neben einem undefinierten Feldwert noch als ''leer'' gelten soll. Dies ist interessant, wenn man z.B. den Zahlwert ''0'' als ''leer'' festlegen möchte. 
Beim Definieren dieser Erweiterungen ist zu beachten, dass keine doppelten Anführungszeichen angegeben werden. Diese zerstören die weitere, interne Verarbeitung durch FHEM (Irgendwas ist immer :-)
Desweiteren können Verweise auf andere <code>InfoSummarize</code>-Felder nur in aufsteigender Reihenfolge erfolgen. Es sind also keine Vorwärtsreferenzen oder Rekursionen möglich.

== Fehlende Kommandos ==
Sollte eine Steuerungsmöglichkeit oder Information fehlen, oder anderes gewünscht sein, dann einfach eine Nachricht ins Forum. Meistens läßt sich da was machen :-)

=== Ideenpipeline ===
Folgende Ideen sind bereits in der gedanklichen Pipeline. Aber alles Schritt für Schritt und der Reihe nach:
*'''Momentan Leer'''

Erledigte Ideen:
*'''Zwischendurchsage''': Eine Datei abspielen, und danach wieder an der alten Stelle mit der alten Lautstärke weiterspielen (In Version 1.5 hinzugekommen)
*'''Beliebige MP3s in die Queue legen oder abspielen''': Entgegen dem Controllergefühl kann man sehr wohl völlig frei abspielbare Dateien in der Queue haben. Es kann nur sein, das man kein Cover oder ähnliches angezeigt bekommt (noch zu testen). (In Version 1.5 hinzugekommen, Cover funktionieren wie immer)
*'''Beliebige Radiostationen abspielen''': Hier gilt das gleich wie für die MP3s. (In Version 1.5 hinzugekommen, Cover und Streaminformationen funktionieren beim Direktabspielen, aus der Queue heraus wird nur der Stream abgespielt)
*'''Lautstärkegrenzen festlegen''': Damit soll festgelegt werden können, in welchen Grenzen die Lautstärke überhaupt verändert werden kann. Das soll in der entsprechenden Zone natürlich auch für die normalen Sonos-Controller gelten. Dabei werden explizit ''keine'' Readings im FHEM aktualisiert, da eine Lautstärkeänderung sonst von der Verarbeitungsgeschwindigkeit von FHEM (inkl. seiner Notifies) abhängig wäre. (In Version 1.8 hinzugekommen)
*'''Zonentopologie verwenden/anpassen''': Es soll eine Speichermöglichkeit für die aktuelle Topologie geschaffen werden, und auch eine neue Topologie gesetzt werden können. Ich stelle mir da eine Art von "Szenen" vor die man nach Bedarf setzen und dann natürlich auch steuern kann. Diese Szenen sollen den Gruppierungszustand aller verfügbaren ZonePlayer repräsentieren (können), also wer mit wem in einer Gruppe ist, und wer der jeweilige Koordinator ist (nur dieser kann die Steuerung entgegennehmen, und für die gesamte Gruppe ausführen). (In Version 2.0 hinzugekommen)
*'''Button-Events''': Es soll eine Möglichkeit zum direkten Reagieren auf Tastenevents am Player existieren. Man soll verschiedene Tastensequenzen festlegen können, die dann Fhem-Events erzeugen, auf die man reagieren kann. (In Version 2.0 hinzugekommen)

== Beispiele ==
Hier können mit der Zeit ein paar Beispiele eingestellt werden, um die Möglichkeiten zu verdeutlichen.

=== Beispiel zum Loggen aller Aktionen auf allen Playern ===
<pre>define FileLog_Sonos_Actions FileLog /path/to/log/Sonos_Actions-%Y-%m.log \
Sonos_.*:.*LastActionResult.*</pre>
Hiermit wird jede Aktion, die, durch Fhem verursacht, an die Player gesendet wurde, mitgeschrieben. Sehr praktisch für Fehlersuche, bzw. die Kontrolle darüber, was eigentlich von Fhem aus so auf den Playern gesteuert wird.

=== Beispiel zum automatischen Abspielen einer Liste nach dem Einschalten eines Players ===
<pre>define Sonos_Wohnzimmer_Appeared_Notify notify Sonos_Wohnzimmer:presence:.appeared { \
fhem "set Sonos_Wohnzimmer LoadPlaylist R.%%20Spielliste" ;; \
fhem "set Sonos_Wohnzimmer Volume 15" ;; \
fhem "set Sonos_Wohnzimmer Track random" ;; \
fhem "set Sonos_Wohnzimmer Play" \
}</pre>

Hier wird auf das Event '''presence: appeared''' reagiert und eine Playlist geladen (hier mit Leerzeichen im Namen, darum mittels "<code>%20</code>" HTML-kodiert, was wiederum wegen FHEM-Notify auf "<code>%%20</code>" kodiert werden muss). Anschließend wird die Lautstärke gesetzt, ein Titel ausgewählt (zufällig) und das Abspielen gestartet.

=== Beispiel für eine Verstärkerschaltung auf Basis des Player-Zustands ===
<pre>define Sonos_Wohnzimmer_GoPlaying_Notify notify Sonos_Wohnzimmer:transportState.*PLAYING { \
fhem "delete wohnzimmer_Sonos_Ton_Off_Timer" ;; \
if (Value('wohnzimmer_Sonos_Ton') ne 'on') { \
fhem "set wohnzimmer_Sonos_Ton on" \
} \
}
define Sonos_Wohnzimmer_GoNotPlaying_Notify notify \
Sonos_Wohnzimmer:transportState.*(STOPPED|PAUSED_PLAYBACK) { \
fhem "delete wohnzimmer_Sonos_Ton_Off_Timer";; \
fhem "define wohnzimmer_Sonos_Ton_Off_Timer at +00:05:00 \
set wohnzimmer_Sonos_Ton off" \
}</pre>

Hier wird beim Wechsel des <code>transportState</code> auf "<code>PLAYING</code>" der Verstärker angeschaltet, und beim Wechsel auf "<code>STOPPED</code>" oder "<code>PAUSED_PLAYBACK</code>" ein Timer zum Ausschalten des Verstärkers in 5 Minuten definiert. Der Timer ist notwendig, da beim Wechsel zwischen einem "normalen" Titel und einem Radiostream ein kurzer Zwischenwechsel auf "<code>STOPPED</code>" erfolgt, und ich nicht den Verstärker innerhalb von ein paar Sekunden aus- und wieder einschalten will.

=== Beispiel für das Loggen des gerade abgespielten Titels ===
<pre>define FileLog_Sonos_Wohnzimmer FileLog /etc/fhem/log/Sonos_Wohnzimmer-%Y-%m.log \
Sonos_Wohnzimmer:infoSummarize2:.{2,}
attr FileLog_Sonos_Wohnzimmer room Sonos</pre>

Hier wird bei jedem Wechsel des Titels oder des Abspielzustands ein Eintrag ins Log geschrieben. Damit kann man, auch bei einem Radiosender, verfolgen, welche Titel zu welcher Zeit so über den Player gelaufen sind :-)

=== Beispiel für eine Stummschaltung bei einem Anruf ===
<pre>
define fritzBox_anrufstartring_notify notify fritzBox:.*ring set Sonos_Wohnzimmer VolumeSave 15
define fritzBox_anrufstartcall_notify notify fritzBox:.*call set Sonos_Wohnzimmer VolumeSave +0
define fritzBox_anrufende_notify notify fritzBox:.*disconnect set Sonos_Wohnzimmer VolumeRestore
</pre>

Der Trigger auf 'call' existiert nur, damit ausgehende Telefonate beim Beenden nicht die Lautstärke verändern. Das passiert, weil das Disconnected-Event auch nach ausgehenden Anrufen kommt. Das Beispiel kann man natürlich noch beliebig erweitern, vielleicht etwas mit Anrufererkennung usw.

=== Beispiel für eine Anrufsignalisierung per MP3 bei einem Anruf ===
<pre>
define fritzBox_anrufstartringsong_notify notify fritzBox:.*ring set Sonos_Wohnzimmer \
PlayURITemp \\Server\Audio\RingRingRing.mp3 30
</pre>

Hier wird bei Anruf die angegebene MP3-Datei temporär mit der Lautstärke 30 eingeblendet. Wenn die Datei abgespielt wurde, wird der vorherige Zustand im Player wiederhergestellt, und es geht weiter, wo unterbrochen wurde.

=== Beispiel für beide Varianten beim Telefonanruf gleichzeitig ===
<pre>
define fritzBox_anrufstartring_notify notify fritzBox:.*ring set Sonos_Wohnzimmer VolumeSave 15 \
;; set Sonos_Wohnzimmer PlayURITemp \\Server\Audio\RingRingRing.mp3 30
define fritzBox_anrufstartcall_notify notify fritzBox:.*call set Sonos_Wohnzimmer VolumeSave +0
define fritzBox_anrufende_notify notify fritzBox:.*disconnect set Sonos_Wohnzimmer VolumeRestore
</pre>

Dieses Beispiel soll nur die Kombinationsmöglichkeiten verdeutlichen, und hat mehr spielerischen Character.

=== Beispiel für eine Sprachdurchsage auf Basis eines Notify ===
<pre>
define wohnzimmer_Tastenfeld_1_Notify notify wohnzimmer_Tastenfeld_1 set Sonos_Wohnzimmer Speak \
45 de Hier dann die Textnachricht, wie sie auf dem Player ausgegeben werden soll.
define wohnzimmer_Tastenfeld_2_Notify notify wohnzimmer_Tastenfeld_2 set Sonos_Wohnzimmer Speak \
+10 de Hier dann die Textnachricht, wie sie auf dem Player ausgegeben werden soll.
define wohnzimmer_Tastenfeld_3_Notify notify wohnzimmer_Tastenfeld_3 set Sonos_Wohnzimmer Speak \
+0 en Hello, this is a short message.
</pre>

1: Hier wird auf Basis eines Notify (hier ein FS20-Taster) eine Textnachricht auf Deutsch mit der Lautstärke 45 auf dem SonosPlayer ausgegeben. 
2: Hier wird eine deutsche Textnachricht mit 10 Einheiten lauter als aktuell eingestellt ausgegeben. 
3: Hier wird eine englische Textnachricht mit der gleichen Lautstärke wie aktuell eingestellt ausgegeben.

=== Beispiel für das Reagieren auf Tastenevents ===
Hier ein Beispiel, wie man die Tasten an einem Play5 (und natürlich auch an jedem anderen Player) zu einer einfachen, autarken Steuerung programmieren kann.

Grundlagen, die ich zur allgemeinen Vereinfachung in meiner <code>99_myUtils.pm</code> habe:
<pre>
# Wird benötigt, da ein reDefine nur einen Befehl aufrufen kann
sub pauseMuteOff($) {
my ($devName) = @_;

if (defined($main::defs{$devName})) {
fhem("set $devName Pause");
fhem("set $devName Mute Off");
}
}

# Löscht ein Define, wenn es existiert. Damit kann man dynamische AT-Defines löschen,
# ohne zu wissen, ob sie überhaupt existieren
sub deleteDefineIfExists($) {
my ($devName) = @_;

if (defined($main::defs{$devName})) {
fhem("delete $devName");
}
}

# Definiert ein define neu; Heisst, es wird, wenn es bereits existiert, gelöscht und neu angelegt
sub reDefine($$) {
my ($devName, $define) = @_;

deleteDefineIfExists($devName);
fhem('define '.$devName.' '.$define);
}
</pre>

Attribut am Sonosplayer-Device:
<pre>
attr Sonos_Schlafzimmer buttonEvents 1:MM
</pre>

Notify-Defines, die die Steuerung übernehmen:
<pre>
define Sonos_Schlafzimmer_WantPlaying_Notify notify Sonos_Schlafzimmer:ButtonEvent:.MM \
set Sonos_Schlafzimmer Play
define Sonos_Schlafzimmer_WantStopPlaying notify Sonos_Schlafzimmer:Mute.*1 \
{ reDefine('Schlafzimmer_Sonos_Stop_Timer', 'at +00:00:30 \
{ pauseMuteOff("Sonos_Schlafzimmer") }') }
define Sonos_Schlafzimmer_WantStopPlayingOff notify Sonos_Schlafzimmer:Mute.*0 \
{ deleteDefineIfExists('Schlafzimmer_Sonos_Stop_Timer') }
</pre>

Hier wird mittels des Attributs <code>buttonEvents</code> ein Event bei zweimaligen Drücken von <code>M</code>ute innerhalb von 1 Sekunde definiert.
Anschließend wird auf dieses Event reagiert, indem der Player mit der Wiedergabe beginnen soll.
Desweiteren wird auf das Ändern von Mute reagiert, indem beim Aktivieren von Mute (also einmal drücken) ein Timer gestartet wird, der nach 30 Sekunden die Wiedergabe anhält, und den Mute-Zustand wieder zurücksetzt. Das letzte notify existiert nur, damit man das Beenden der Wiedergabe innerhalb der 30 Sekunden noch verhindern kann.

Hier ist zu beachten, dass diese Events natürlich nicht unterscheiden können, ob das ganze am Player selbst oder über einen Controller geschaltet wurde. Von beiden Stellen aus kann diese Funktionalität verursacht werden.

=== Beispiel für einen Offline-Sprachsynthetisierer ===
Man kann mit den Attributen ''Speak1'', ''Speak2'', ''Speak3'' und ''Speak4'' am zentralen Sonos-Device Kommandozeilen definieren, die einen Text in eine Sounddatei umwandeln.
Hier soll dies am Beispiel von ''espeak'' verdeutlicht werden.
<pre>
wav:/usr/bin/espeak -v %language% -w %filename% "%text%"
</pre>
Zuerst muss das Ausgabedateiformat definiert werden, damit die internen Funktionen entsprechend reagieren können. Anschließend wird die Befehlszeile mit den entsprechenden Platzhaltern angegeben.
Hier muss beachtet werden, dass der Platzhalter ''%language%'' mit dem zweiten Parameter der Fhem-Befehlseingabe gefüllt wird. In diesem Beispiel muss man dort also ''german'' angeben (anstatt ''de'' bei Google), um eine deutsche Ausgabe zu erhalten.

Dieses Beispiel hat den kleinen Nachteil, dass die Ausgabe in einer WAV-Datei erfolgt, die keinerlei Tag-Informationen tragen kann. Um das zu ändern, kann man einen Konverter nachschalten:
<pre>
mp3:/usr/bin/espeak -v %language% --stdout "%text%" | /usr/bin/avconv -i - %filename%
</pre>
Damit wird die Ausgabe von ''espeak'' direkt in das MP3-Format umgewandelt, und intern mit den entsprechenden Tags versehen. Hier ist allerdings der Nachteil, dass es etwas länger dauert (bei mir ca. 1-3 Sekunden).

Die in diesem Beispiel verwendeten Pakete können unter Debian mittels der Anweisungen
<pre>
sudo apt-get install espeak
sudo apt-get install ffmpeg
</pre>
installiert werden.

=== Beispiel zu InfoSummarize ===
Standard, wie er angelegt wird:
<pre>
InfoSummarize1 = <NormalAudio><Artist prefix="(" suffix=")"/>\
<Title prefix=" '" suffix="'" ifempty="[Keine Musikdatei]"/>\
<Album prefix=" vom Album '" suffix="'"/></NormalAudio> \
<StreamAudio><Sender suffix=":"/>\
<SenderCurrent prefix=" '" suffix="' -"/>\
<SenderInfo prefix=" "/></StreamAudio>
InfoSummarize2 = <TransportState/><InfoSummarize1 prefix=" => "/>
InfoSummarize3 = <Volume prefix="Lautstärke: "/>\
<Mute instead=" ~ Kein Ton" ifempty=" ~ Ton An" emptyval="0"/>\
~ Balance: <Balance ifempty="Mitte" emptyval="0"/>\
<HeadphoneConnected instead=" ~ Kopfhörer aktiv" ifempty=" ~ Kein Kopfhörer" \
emptyval="0"/>
</pre>

Dabei ist zu beachten, dass man auf andere InfoSummarize-Felder verweisen darf, solange man diese nur in aufsteigender Reihenfolge verwendet. Rekursionen oder Vorwärtrsreferenzen werden nicht unterstützt.

Hier noch ein Beispiel, um die Informationen des nächsten Titels zusammenzufassen:
<pre>
InfoSummarize4 = <NormalAudio>Nächster Titel: <nextArtist prefix="(" suffix=")"/>\
<nextTitle prefix=" '" suffix="'" ifempty="[Keine Musikdatei]"/>\
<nextAlbum prefix=" vom Album '" suffix="'"/></NormalAudio>\
<StreamAudio>Kein nächster Titel ermittelbar</StreamAudio>
</pre>

=== Beispiel für eine Cover-Anzeige des nächsten Titels ===
Mit diesem Beispiel wird gezeigt, wie man sich einen Weblink für die Anzeige des Covers des nächsten Titels erzeugen kann:
<pre>
define NextAlbumArt_Wohnzimmer weblink image fhem/icons/SONOSPLAYER/Sonos_Wohnzimmer_NextAlbumArt
attr NextAlbumArt_Wohnzimmer group Wohnzimmer
attr NextAlbumArt_Wohnzimmer htmlattr width="200"
attr NextAlbumArt_Wohnzimmer room Sonos
</pre>

=== Beispiel für das Übertragen eines Titels an einen anderen Player ===
Mein Sohn hat öfter den Wunsch, einen gerade im Wohnzimmer laufenden Titel auch in seine eigene Abspielliste zu bekommen. Der Weg am Sonos-Controller über eine gespeicherte Playliste ist dabei sehr umständlich.
Ich habe ein 8-fach Sensorfeld an der Wohnzimmerwand, wo ich ein Feld dafür programmiert habe, das Reading ''currentTrackURI'' mittels der Set-Anweisung ''AddURIToQueue'' in die aktuelle Abspielliste meines Sohnes zu packen.
Das ist natürlich nichts besonderes, aber vielleicht für den einen oder anderen auch eine nette Idee:
<pre>
define wohnzimmer_Sensorfeld_Notify notify wohnzimmer_Sensorfeld { \
fhem "set Sonos_Sohnemann AddURIToQueue ".\
ReadingsVal("Sonos_Wohnzimmer", "currentTrackURI", "") \
}
</pre>

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Code Snippets]]
[[Category:Unterhaltungselektronik]]

DLCD

2014-08-12T20:32:02Z

Kamischi:

{{Infobox Modul
|ModPurpose=Daten sammeln und formatiert auf LCD ausgeben

|ModType=x
|ModCmdRef= ---- noch nicht Teil von FHEM ----
|ModForumArea=[http://forum.fhem.de/index.php/board,8.0.html Codeschnipsel] / [http://forum.fhem.de/index.php/topic,24519.0.html DLCD]
|ModTechName=39_DLCD.pm
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=6340 epsrw1]}}

Das [[DLCD]]-Modul bietet eine einfache Möglichkeit, Daten zu sammeln und für die Anzeige auf einem seriellen LCD aufzubereiten.

== Features ==
Diese Wiki-Seite beschreibt den Versionsstand 1.1 des DLCD-Moduls.

Thread im Forum:[http://forum.fhem.de/index.php/topic,24519.0.html]

== Beschreibung ==
[[Datei:dok39_DLCD.jpg|mini|Funktionsweise]]

DLCD bietet als kleines Helferlein die Möglichkeit, Textzeilen eines LCD Displays als Readings vorzubereiten und mit Daten frei konfigurierbarer Readings zu befüllen.

Jede Zeile wird als Attr vordefiniert, und mit Platzhaltern (zB.: %1%) für die einzutragenden Werte versehen.

Die Liste aller einzulesenden Devices:Readings wird in einem attr eingestellt. Das Modul prüft dann regelmäßig (attr: poll interval) die Daten der Fhem-Devices
und aktualisiert dann die Anzeige sobald sich einer der Werte geändert hat.

Zusätzlich können Zahlen einfach über attr formatiert werden (Kommastellen, Rundung, Anzeige von + und - Zeichen).

Die eigentliche Ausgabe auf das LCD erfolgt jeweils immer dann wenn eine Änderung der Daten festgestellt wird, auf beliebiges konfigurierbares Device. Zum beispiel I2C LCD über FHEM, oder auch über shell-command für nicht von FHEM unterstützte displays.

== Define ==

<code>
define <name> DLCD
</code>

''In der Basisversion wurde Number::Format von cpan benötigt. Dies ist ab v. 1.1. nicht mehr der Fall.''

== Attribute ==
Alle Attributes sind auch in fhem durch das Kommando get attrHelp <varname> erklärt, für's "schnelle Nachschauen zwischendurch".

* dlcdRows -> Anzahl Zeilen des LCD Displays

* dlcdCols -> Anzahl Spalten des LCD Displays

* dlcdPollInterval -> Zeitintervall nach dem FHEM die Daten versucht zu aktualisieren

* dlcdLine1 -> Formatvorlage für LCD-zeile zB: text: %1% text: %2%

* dlcdLine2 -> Formatvorlage für LCD-zeile zB: text: %3% text: %4%

* dlcdLine3 -> Formatvorlage für LCD-zeile zB: text: %5% text: %6%

* dlcdLine4 -> Formatvorlage für LCD-zeile text: %7% text: %8%

* dlcdLine5 -> Formatvorlage für LCD-zeile text: %11% text: %12%

* dlcdVal1 -> Quelle für den Wert %1% im Format: FhemDev:reading

* dlcdVal2 -> Quelle für den Wert %2% im Format: FhemDev:reading

* dlcdVal3 -> Quelle für den Wert %3% im Format: FhemDev:reading

* ...

* dlcdVal12 -> Quelle für den Wert %12% im Format: FhemDev:reading

* dlcdTriggerCmd -> Fhem-Command zum Schreiben einer LCD-Zeile. zB.: set lcd_wand writeXY 0,%L%,20,1 %T%

* dlcdVal1formatnum -> Zahlenformatierung für Wert %1%, muss none sein bei Nicht-Zahl

* dlcdVal2formatnum -> Zahlenformatierung für Wert %1%, muss none sein bei Nicht-Zahl

* dlcdVal3formatnum -> Zahlenformatierung für Wert %1%, muss none sein bei Nicht-Zahl

* ...

* dlcdVal12formatnum -> Zahlenformatierung für Wert %1%, muss none sein bei Nicht-Zahl

-----

dlcdVal .. formatnum funktioniert wie folgt:

optionen: 0 / 0+- / 1 / 1+- / 2 / 2+- / 3 / 3+-

setzen die Anzahl Dezimalstellen fest, sowie ob ein + bzw. - Zeichen vorangestellt wird.

-----

* dlcdBlankspaceReplace -> Leerzeichen wird im dlcdTriggerCmd durch diesen attr-Wert ersetzt. zB: \x20

== Settings ==
reset ->alle Readings zurücksetzen

== Readings ==
Line1 -> Aktuelle Anzeige der Zeile 1

Line2 -> Aktuelle Anzeige der Zeile 2

Line3 -> Aktuelle Anzeige der Zeile 3

Line4 -> Aktuelle Anzeige der Zeile 4

Line5 -> Aktuelle Anzeige der Zeile 5

== Spezielle Anzeigefunktionen ==

Datum und Uhrzeit basieren aktuell auf der Systemzeit des FHEM-servers. Eine Möglichkeit als Zeitbasis den Timestamp eines FHEM-Readings zu verwenden ist denkbar; wer das nutzen möchte, bitte im Forum melden.

=== Datum ===

* %date_Y% --> Jaheszahl 4-stellig
* %date_y% --> Jahreszahl 2-stellig
* %date_M% --> Monat als Zahl, 2-stellig
* %date_M_eng% --> Monat, Abkürzung englisch
* %date_M_ger% --> Monat, Abkürzung deutsch
* %date_D% --> Tag des Monats 2-stellig
* %date_WD% --> Wochentag 1-stellig im Format 0(So) ... 6(Sa)
* %date_WD_eng% --> Wochentag, Abkürzung englisch
* %date_WD_ger% --> Wochentag, Abkürzung deutsch

=== Zeit ===

* %time_hms% --> HH:MM:SS Uhrzeit
* %time_h% --> Stunde
* %time_m% --> Minute
* %time_s% --> Sekunde

=== Mathematische Werteberechnung ===

* Noch in Arbeit - Ideen sind willkommen ;) --> Forum
* To be continued

== Weblinks ==
* [http://forum.fhem.de/index.php/topic,24519.0.html] Thread im Forum, in dem dieses Modul vorgestellt wurde
* ...

[[Kategorie:Other Components]]

STELLMOTOR

2014-08-12T20:26:31Z

Kamischi:

{{SEITENTITEL:STELLMOTOR}}
{{Infobox Modul
|ModPurpose=Stellmotor-Steuerung mit Zeitabweichungskorrektur
|ModType=x


|ModForumArea=[http://forum.fhem.de/index.php/board,8.0.html Codeschnipsel] / [http://forum.fhem.de/index.php/topic,23933.msg176432.html#msg176432 STELLMOTOR]
|ModTechName=39_STELLMOTOR.pm
|ModOwner=epsrw1,cwagner}}
Das Modul [[STELLMOTOR]] bietet eine einfache Möglichkeit, mit zwei Relais den Rechts-/Linkslauf eines Motors zu steuern und punktgenau anzuhalten.

== Features ==

Diese Wiki-Seite beschreibt die Version 2.0 des STELLMOTOR Moduls.

----

* Wiedereintrittsfähig nach einem Neustart
* Wiederholungsgenauigkeit durch Ausgleich von Rundungs- und Laufzeitabweichungen
* Vermeiden von Blockade des FHEM während der Laufzeit des Motors

Thread im Forum:[http://forum.fhem.de/index.php/topic,23933.0.html]

----

== Beschreibung ==

[[Datei:dok39_STELLMOTOR.jpg|mini|Funktionsweise]]

Vorrangig ist dieses Modul für zwei Relais an GPIO- oder an PIFace-Pins eines Rasberrys gedacht. Andere Einplatinencomputer werden
mit dem Device-Typ SysCmd unterstützt. Es bietet zusätzlich auch die Option, zwei Schaltaktoren per Funk (aus Timinggründen nicht
empfohlen) oder 1-Wire anzusteuern.

Aus den Werten MaxTics (Default=100, für Prozentanzeige) und MaxDriveSeconds (Laufzeit des Motors von 0 bis 100%) wird die Zeit
berechnet, die der Motor nach rechts oder links laufen muss, um die mit set gewünschte Motorstellung zu erreichen.

FHEM läuft dann weiter ohne einzufrieren, und prüft im Loop nur noch ob, die Stoppzeit im Cache erreicht ist. Da der Stopp nie
exakt zur geplanten Zeit ausgeführt wird, liegt im Cache ein weiterer Wert, der die Differenz zwischen geplanter und tatsächlicher
Stoppzeit dem nächsten Kommando hinzurechnet. So werden sich addierende kleine Zeitdifferenzen vermieden.

Zum Kalibrieren (set calibrate) fährt der Motor einfach volle Zeit nach links/null. Hier wird der in Getriebemotoren meist eingebaute
Endschalter genutzt, um den "Null-Punkt" sicher zu finden. Falls ein angeschlossener Motor solche Endschalter nicht hat, müssen diese
für diese Schaltungsweise unbedingt vorgesehen werden.
Übliche Montagepunkte sind ein Wellrad an der Ansgangswelle, an Endpunkten des zu bewegenden Objektes oder direkt am Motor gegen
eine drehend gefedert gelagerte Motoraufhängung.

Anwendungsszenarien für das Modul sind unter Anderem:
* [[Mischersteuerung|3- oder 4-Wege Heizkreis-Mischer]]
* [[Solarspeicher|Warmwasser-Mischventil für Solarspeicher]]
* [[Eigenbau-Heizungsthermostate]]
* [[Eigenbau-Rolladensteuerung]]
* [[(Dach-)Fensteröffner]]
* [[Beamer-Leinwand]]
* [[Heliostaten]]
* ....

----

== Define ==
<code>
define <name> STELLMOTOR <PiFace|Gpio|FhemDev|SysCmd>
</code>
Je nach Device Typ sind verschiedene Attribute zur erforderlich, damit STELLMOTOR weiß, wie die beiden Relais angeschlossen sind.
* '''PiFace''' und '''Gpio''' benötigen STMgpioPortRL und STMgpioPortSTART
* '''FhemDev''' benötigt STMfhemDevRL und STMfhemDevSTART
* '''SysCmd''' benötigt STMsysCmdRL und STMsysCmdSTART

Für den Schaltvorgang "baut" STELLMOTOR einen set-Befehl zusammen. Beispielsweise bei FhemDev
<code>
set <**..PortRL> 0 sowie set <**..PortSTART> 1 zum Einschalten links
set <**..PortRL> 1 sowie set <**..PortSTART> 0 zum Einschalten rechts (bei Type "einzel", sonst 1,1)
set <**..PortRL> 0 sowie set <**..PortSTART> 0 zum Ausschalten
</code>

* Die Schaltbefehle 0 und 1 können mit Attributen invertiert und/oder gemapped werden (zB.: On/Off)

Um die Wirkung auszuprobieren, ohne jedes Mal zum Mischer rennen zu müssen, bietet sich an, zwei '''Dummys''' zu verwenden:

<code>
define Stellmotor2rl dummy

define Stellmotor2start dummy
</code>

<code>
set <name> 45
</code>

stellt den Motor nun auf 45%. Angenommen, stand er bei 10%, wird er nun (45-10)*MaxDriveSeconds/MaxTics Sekunden lang nach rechts laufen und dann von STELLMOTOR gestoppt.

Diese beiden Bilder zeigen die elektrische Verdrahtung von zwei Relais, die von je einem Aktor gesteuert werden:
[[Datei:Relais-Schaltung FBH-Mischer attr einzel.jpg|mini|Schaltplan einzel]] [[Datei:Relais-Schaltung FBH-Mischer attribut Wechsel.jpg|mini|Schaltplan wechsel]]

Typische Getriebemotoren haben eingebaute Endschalter, die beim Erreichen der 0%- oder 100%-Position die Stromversorgung unterbrechen. Das Modul Stellmotor nutzt dies
aus, um eine Kalibrierung zwischen rechnerischem und tatsächlichen Stand herzustellen.

----

== Attribute ==

Alle Attributes sind auch in fhem durch das Kommando get attrHelp <varname> erklärt, für's "schnelle Nachschauen zwischendurch".

=== Global gültige Attribute ===

{| class="wikitable sortable"
|-
! Parameter !! Wertebereich !! Default !! Beschreibung
|-
| STMrlType|| String || einzel || je nach Schaltplan, Wechsel=start+RL-relais, einzel=R-Relais+L-Relais werden geschaltet
'''ACHTUNG:''' falsche Einstellung kann zu Kurzschluss am Motor führen, bitte Einstellung genau überdenken oder mit dummy testen

bei einzel:
Rechtslauf: start=0 rl=1
Linkslauf: start=1 rl=0 Ruhe:
start=0 rl=0

bei wechsel:
Rechtslauf start=0 rl=1
Linkslauf: L start=1 rl=0
Ruhe: start=0 rl=0

|-
|STMmaxDriveSeconds ||[0...n]||muss angepasst werden||gestoppte Zeit in Sekunden, die der Motor für die Fahrt von 0 bis 100 Prozent braucht
|-
|STMmaxTics ||[0...100]||100||Motorstellung - bei Prozentangaben 100, bei Winkelangaben anzupassen
|-
|STMpollInterval || Float ||0.1||Zeitintervall nach dem FHEM prüft, ob die interne Stoppzeit erreicht wurde. Hier sollte mit einem möglichst
kleinen Wert gestartet werden, der vorsichtig erhöht werden kann, falls FHEM zu langsam läuft wegen des Stellmotors. Darf nicht größer
STMlastDiffMax sein, sonst beginnt der Motor zu schwingen.
|-

| STMresetOtherDeviceAtCalibrate|| String || 0 || Fhem Device das am Ende des Kalibriervorganges zusätzlich resettet wird. (command:
set <STMresetOtherDeviceAtCalibrate> reset" wird abgesetzt), zB für eigenes Logging oder Rotary Encoder
|-
| STMinvertOut|| Zahl || 0 || setzen für Devices die 0 für Start und 1 für Stop erwarten
|-
| STMmapOffCmd|| String || 0 || string der im device-command anstelle '0' verwendet wird für stop
|-
| STMmapOnCmd|| String || 0 || string der im device-command anstelle '1' verwendet wird für start
|-
| STMcalibrateDirection|| String || L || auf R wird die Ralibrierung nach rechts gefahren, default= L (links)
|-

| STMlastDiffMax|| Zahl || 1|| ist die Stoppzeit weiter als dieser wert vom Soll entfernt, wird sofort ein neuer drive
gestartet. Wert muss immer größer als STMpollInterval sein, sonst beginnt der Motor zu schwingen
|-
| STMtimeTolerance|| Float || 0.001 || Stop-Time Differenzen kleiner als dieser Wert werden bei der Berechnung vollständig
ignoriert (Parameter wird voraussichtlich in der nächsten Modulversion entfallen)
|-

| STMdebugToLog3|| Zahl || 0/1 || Debug Informationen ins Log schreiben. Achtung, kann eine Menge Daten verursachen, falls
man vergisst, es wieder abzuschalten!
|-

|-
|readingFnAttributes||||||readingFnAttributes
|}

=== Device Type abhängige Attribute ===

Je nach Device Type sind verschiedene Attribute vorgesehen, um STELLMOTOR mitzuteilen, wie die beiden Relais angesprochen
werden. Man kann so z. B. während der Aufbauphase der Installation neben den Gpio devices noch 2 dummy devices im Attr
vorhalten um zwischendurch zu testen. Hierzu muss dann nur noch die DEF des STELLMOTOR Devices vorübergehend auf FhemDev
geändert werden.

Alle Attributes sind auch in fhem durch das kommando get attrHelp <varname> erklärt, für das "schnelle Nachschauen zwischendurch".

{| class="wikitable sortable"
|-
! Device Type !! Parameter !! Typ !! Default !! Beschreibung
|-
| PiFace / Gpio || STMgpioPortRL || Zahl || 5 || PiFace Digital port oder Gpio-Port für RL oder R Relais
|-
| PiFace / Gpio || STMgpioPortSTART || Zahl || 4 || PiFace Digital Port oder Gpio-Port für START (oder L Relais bei 'einzel')
|-
| FhemDev || STMfhemDevRL|| String || RelaisRL || Fhem-Device name für RL (oder R) Aktor (zB.: 'keller portB' oder 'dummyRLrelais')
|-
| FhemDev || STMfhemDevSTART|| String || RelaisSTART || Fhem-Device name für START (oder L) Aktor (zB.: 'keller portC' oder 'dummySTARTrelais')
|-
| SysCmd || STMsysCmdRL|| String || 0 || freies Command, das für RL an die Shell übergeben wird (zB: '/Usr/local/bin/gpio write 4', STELLMOTOR fügt 0 oder 1 arg. dazu)
|-
| SysCmd || STMsysCmdSTART|| String || 0 || freies Command, das für START an die Shell übergeben wird (zB: '/Usr/local/bin/gpio write 5', STELLMOTOR fügt 0 oder 1 arg. am Ende dazu)
|-
|}

----

== Settings ==

{| class="wikitable sortable"
|-
! SET !! Wertebereich !! Beschreibung
|-
|set <name> N||[1...100]||stellt den Mischer auf N % Öffnung
|-
|set <name> calibrate|| - ||stellt den Mischer auf Min. oder Max. (in Fhem 1% oder 100%); default: maximaler Linkslauf bis zur Endschalterpostion. Kann über Attr in Rechtslauf geändert werden.
|-
|set <name> reset|| - ||Setzt die Position und die Werte im Cache auf Null. Verwendung ist intern (am Ende von calibrate) oder nach mechanischem Neueinbau des Motors (da reicht aber auch ein Calibrate)
|}

----

== Readings ==

Alle Readings sind auch in fhem durch das Kommando get readingsHelp <varname> erklärt, für das "schnelle nachschauen zwischendurch".

{| class="wikitable sortable"
|-
! readings !! Wertebereich !! Beschreibung
|-
|position||[1..100%]||der Wert wird gesetzt am Beginn einer Mischerbewegung (anderer Wertebereich, wenn MaxTics nicht 100)
|-
|state||active,error,position||Position wird beim Stopp der Motorbewegung gesetzt
|-
|lastStart|| Float ||Zeitstempel der letzten Motorbewegung
|-
|locked||[0 1]||Steht auf 1 während der Motor gerade läuft (Calibrate oder gewünsche Position per set).

Neue Kommandos werden während lock nur in eine Warteschleife (reading: command_queue) genommen.

Zeigt im im Frontend, dass der Motor gerade läuft.
|-
|queue_lastdiff||||Letzte Zeitdifferenz beim Stopp: abhängig von der Systemlast oder anderen blockierenden Kommandos wird das Stopp-Kommando nur nahe an der kalkulierten Stoppzeit ausgeführt, potentiell niemals exakt zum berechneten Zeitpunkt. STELLMOTOR merkt sich die Zeitdifferenz zwischen geplantem und tatsächlichem Stopp und addiert bei der nächsten Bewegung des Motors die Differenz, um möglichst präzise die gewünschte Motorstellung zu erreichen.
|-
|stopTime||||Null oder die errechnete Zeit zum Stopp der Motorbewegung
|-
|command_queue||||Position einer anstehenden neuen Motorposition, die angefordert wurde als die letzte Motorbewegung noch ausgeführt oder das Modul disabled war
|-
|OutType||||Bei der Defintion gewählte Arbeitsart: PiFace,Gpio,FhemDev,SysCmd
|-
|DoResetAtStop||||Zeitstempel des Ende der letzten Kalibrierfahrt
|}

----

== Weblinks ==
* [http://forum.fhem.de/index.php/topic,23933.msg174400.html#new Thread im Forum], in dem dieses Modul vorgestellt wurde
* to be continued

[[Kategorie:Other Components]]
[[Kategorie:Heizungssteuerung]]
[[Kategorie:Raspberry Pi]]

DevelopmentModuleIntro

2014-08-12T20:21:06Z

Kamischi:

== 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_DevIni</code>t 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>loglevel:1,2,3,4,5
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.

=== 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. 
Eingangsparameter: Das generierte Event 
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]

besteht aus
* physisches Modul
* logische Modul(e)

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 ...
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* DevIO

[[Kategorie:Development]]

Anwesenheitserkennung - Remote Fritzbox

2014-08-12T20:20:04Z

Kamischi:

In Erweiterung des Beitrages [[Anwesenheitserkennung|Anwesenheitserkennung]] wird eine Beispiel-Lösung für folgendes Szenario vorgestellt:

* Eine (nicht modifizierte) Fritzbox wird als WLAN Access Point und Router genutzt, jedoch läuft auf dieser Box kein FHEM oder Perl.
* Ein Linux Rechner (in diesem Beispiel ein RPI) wird als FHEM host verwendet.
* Device Erkennung mittels PRESENCE - ident mit PRESENCE fritzbox

Die Lösung basiert auf dem PRESENCE Modul und nutzt die Funktion '''PRESENCE function { }'''.

Auch bei einem Repeater-Einsatz im WLan (zweite Fritzbox) kann diese Lösung eingesetzt werden - es ist nur eine Installation auf der Haupt-Fritzbox notwendig, nicht auf dem Repeater.

== Background / Motivation ==
Ich hatte während der letzten 12 Monate ein modifiziertes PRESENCE Modul im Einsatz, das jedoch immer wieder ein Hängen oder Reboots der Fritzbox verursacht hatte (speziell bei 7270), daher hatte ich es nicht veröffentlicht. Die Vermutung liegt nahe, dass das ständige Telnet ein/aus-loggen die Hänger/Reboots verursacht hat.

== Konzept ==
=== Variante 1 ===
* Diese Lösung basiert (wie auch die '''PRESENCE fritzbox''' Funktion) auf dem Fritzbox Befehl ''ctlmgr_ctl'', der jedoch von der "Ferne" ausgelöst werden muss, da FHEM ja nicht auf der Fritzbox läuft. Weiters wurden Ideen/Konzepte des presenced/collectord verwendet.
* Die Lösung läuft bei mir seit Anfang Dez. 2013 stabil mit 12 abgefragten Devices / 120 Sekunden Intervall. (Env: FHEM auf RPI, Fritzbox 7390)
* Auf der Fritzbox wird ein '''shellscript''' installiert, dass von remote gestartet wird, Kommandos lokal ausführt und das Ergebniss zurückschickt.
* Am FHEM host läuft ein '''perl basierender daemon''' der Kommandos von FHEM empfängt, aufbereitet und das shellscript auf der Fritzbox (mit parameter) startet. Dieser Daemon hält auch die Telnet Verbindung zur Fritzbox permanent aufrecht. Gestartet wird dieser Daemon automatisch beim ersten Aufruf durch FHEM.
* ein Modul '''99_RFritzBox.pm''' ist die Schnittstelle zwischen FHEM und dem daemon.

=== Variante 2 ===
* Die WEB Oberfläche der Fritzbox wird über http abgefragt.
* Es ist kein code und kein Telnet auf der Fritzbox selbst notwendig, ein Nachteil könnte jedoch die Performance der Abfrage sein.
* Diese Variante ist vor allem für jene FB-Benutzer interessant, die kein Telnet auf der FB aktivieren können (oder wollen).

== Code (beide Varianten)==
Der code ist als zip-file im thread [http://forum.fhem.de/index.php/topic,17957.0.html PRESENCE-RemoteFritzbox] abgelegt. Bitte in diesem thread auch Fragen/Feedback/Wünsche posten.

== Installation & Debug Variante 1 ==
=== Voraussetzungen ===
* Telnet auf der Fritzbox aktiviert
* perl NET::Telnet Modul auf dem Host wo FHEM läuft installiert. Beim Raspberry-PI geht das so:
<pre>sudo apt-get install libnet-telnet-perl</pre>
Folgende Reihenfolge ist empfehlenswert:

=== Kopieren von Rpresence.sh in die Fritzbox ===
z.B. mittels FTP in folgendes Verzeichnis:
<pre>
/var/media/ftp/FRITZ/bin # Der Verzeichnispfad muss angepasst werden! In diesem Beispiel ist das eine FB7390 im Internen Speicher.
chmod +x Rpresence.sh # shell script ausführbar machen.</pre>
Ein erster Test von der Telnet Konsole der Fritzbox:
<pre>./Rpresence.sh <FBdevicename></pre> sollte folgendes Ergebnis liefern: <pre>RFritzBox: <FBdevicename> y z</pre> wobei für <FBdevicename> der Name eines Gerätes, so wie in der Fritzbox Weboberfläche definert einzusetzen ist. y ist die Fritzbox interne Devicenummer dieses Gerätes (es sollte jedenfalls nicht 999 hier stehen, in diesem Fall hat die FB den Namen nicht gefunden. z ist der Status (0==abwesend/1==anwesend).
Falls bis hierher alles geklappt hat, ist die Einrichtung auf der Fritzbox fertig.

=== Installation & konfig & test Daemon am FHEM host ===
kopieren von RFritzBoxScan.pl ins FHEM Verzeichnis (dort wo alle Module 00_xxx.pm - 99_yyy.pm sind)
<pre>sudo chmod +x RFritzBoxScan.pl # ausführbar machen
sudo chown fhem:root RFritzBoxScan.pl #for user fhem </pre>
Erstellen eines config- files für den daemon:
im root FHEM-Verzeichnis ( dort wo üblicherweise auch die fhem.pl zu finden ist )
ein file: '''credentials.cfg''' mit folgendem Inhalt erstellen (Adressen/User/Passwort/pfad anpassen):
<pre>
# PRESENCE credentials (only required for function RemoteFritzBox)
$credentials{RemoteFritzBox}{ipadress} = '192.168.1.254'; # FB LAN Adress
$credentials{RemoteFritzBox}{username} = 'FritzBoxusername';
$credentials{RemoteFritzBox}{password} = 'FritzboxPasswort';
$credentials{RemoteFritzBox}{shellcmd} = '/var/media/ftp/FRITZ/bin/Rpresence.sh'; # pfad anpassen!
$credentials{RemoteFritzBox}{serverhost} = 'localhost'; # RFritzBoxScan.pl provides this service
$credentials{RemoteFritzBox}{serverport} = 7777;
$credentials{RemoteFritzBox}{serverbin} = 'RFritzBoxScan.pl'; # Fritzbox daemon
$credentials{RemoteFritzBox}{speedmatching} = "active"; # optional valid: <active|speed>
</pre>
Das Format dieser cfg-file entspricht dem im Modul Webcam.
Ein erster Test:
<pre>./RFritzBoxScan.pl <fullpath and name> # of credentials.cfg eg: /opt/fhem/credentials.cfg</pre>
Damit wir der Daemon von Hand gestartet und alle debug-Meldungen kommen auf diese Konsole.
Beim Start sollte der Output so aussehen:
<pre>
RFritzBoxScan: server waiting for client connection on port 7777
RFritzBoxScan: Fritzbox login ok
### die folgenden Zeilen kommen erst ab dem nächsten Schritt !
### und zwar jedesmal wenn ein request von FHEM an den daemon kommt...
RFritzBoxScan: connection from 127.0.0.1:57595
RFritzBoxScan: ..from FHEM received data: Nokia-N810
RFritzBoxScan: ..sending to Fritzbox: Nokia-N810 17
RFritzBoxScan: ..cmdresult: RFritzBox: Nokia-N810 17 1
RFritzBoxScan: ..result to fhem: 1
</pre>

=== Installation und Konfiguration FHEM-Module ===
kopieren von 99_RFritzBox.pm ins FHEM Verzeichnis
<pre>sudo chown fhem:root 99_RFritzBox.pm # for user fhem</pre>
Im FHEM command-feld: <pre>reload 99_RFritzBox.pm</pre> eintippen (oder FHEM neu starten)
Die FHEM-PRESENCE Definition:
<pre>define <myName> PRESENCE function {RemoteFritzBox("<FBdevicename>")} 120 120</pre>
damit wird in 120 sec Abständen der Status abgefragt.
im Telnet Fenster sollten jetzt die requests / response - Meldungen kommen.

Zum Abschluß:
<pre><Strg-C></pre> im telnet Fenster eingeben, der Daemon wird dadurch gestoppt. Auf den nächsten Aufruf durch FHEM warten, der Daemon wird automatisch (im Hintergrund) gestartet. Überprüfen durch Eingabe von <pre>ps -e | grep RFritzBoxScan</pre>

== Installation & Debug Variante 2 ==
=== Voraussetzungen ===
* fhem auf raspberry o.ä.

=== installation & konfig & test am FHEM host ===
Erstellen eines config- files im root FHEM-Verzeichnis ( dort wo üblicherweise auch die fhem.pl zu finden ist )
ein file: '''credentials.cfg''' mit folgendem Inhalt erstellen (Adressen/User/Passwort/pfad anpassen):
<pre>
# PRESENCE credentials (only required for function RemoteFritzBox)
$credentials{RemoteFritzBox}{ipadress} = '192.168.1.254'; # FB LAN Adress
$credentials{RemoteFritzBox}{username} = 'FritzBoxusername';
$credentials{RemoteFritzBox}{password} = 'FritzboxPasswort';
</pre>
Das Format dieser cfg-file entspricht dem im Modul Webcam.

=== Installation und Konfiguration FHEM-Module ===
kopieren von 99_RFritzBox.pm ins FHEM Verzeichnis
<pre>sudo chown fhem:root 99_RFritzBox.pm # for user fhem</pre>
Im FHEM command-feld: <pre>reload 99_RFritzBox.pm</pre> eintippen (oder FHEM neu starten)

Die FHEM-PRESENCE Definition:
<pre>define <myName> PRESENCE function {RemoteFritzBoxWeb("<FBdevicename>")} 120 120</pre>
damit wird in 120 sec Abständen der Status abgefragt.

== Debug Tip (beide Varianten)==
Log Meldungen vom Daemon bekommt man im FHEM Log durch Anlegen eines dummy devices mit dem Namen '''RemoteFritzBox''' :
<pre>
define RemoteFritzBox dummy
attr RemoteFritzBox verbose 5
</pre>
Den Daemon beenden, falls er im Hintergrund läuft (nur Variante 1):
<pre>sudo killall RFritzBoxScan.pl</pre>

have fun

[[Kategorie:Code Snippets]]
[[Kategorie:Glossary]]

DevelopmentGuidelines

2014-08-12T20:16:27Z

Kamischi:

''Wichtiger Hinweis'': Diese Seite enthält die Ideen der fhem-Entwickler, wie fhem in einer künftigen Version funktionieren soll. Es beschreibt nicht den Zustand der aktuellen Umsetzung in den Release- oder den SVN-Versionen.

==Definitionen==
TODO: Rudis kanonische Begriffe verwenden!

===Allgemeines===
Die Version von fhem, in der diese Guidelines umgesetzt werden sollen, wird mit fhem-NEU bezeichnet. Mit fhem 4.x wird die aktuelle Architektur bezeichnet, die auch für fhem 5.x zutrifft.

===Readings===
Ein Reading (Ablesewert) ist jeglicher Wert, Zustand, etc., der von einem Gerät ausgelesen werden kann. Beispiele dafür sind Messtemperatur, Luftfeuchtigkeit, Schaltzustand (an/aus), Firmwareversion, Empfangsstärke.

=== I/O-Devices und Clients===
Um Readings durch fhem verarbeiten zu können, müssen die Daten erst über ein I/O-Device in den Rechner kommen. Beispiele: FHZ1300, CUL, CM11, M232.

Ein I/O-Device ist über einen Port (Beispiel für Unix: /dev/ttyS0) oder einen Socket ansprechbar.

Ein I/O-Device kann selbst ein Gerät sein, das Readings liefert (Beispiel: SCIVT, sowie die meisten anderen Schnittstellengeräte, wenn man die Geräteversion oder die Uptime mit zu den Readings zählt), oder die Readings von anderen Geräten (Clients) weiterleiten (Beispiel: FHZ1300).

==Requests for Proposal==
===Aktualisierung der Readings===
====Aktive und passive Readings====

Es sind zwei Arten von Readings zu unterscheiden:
# Readings, die vom Gerät aktiv mitgeteilt werden, entweder ad-hoc oder in regelmäßigen Zeitabständen (aktive Readings). Beispiele: measuredTemp bei FHT80B, wind bei KS300
# Readings, nach denen fhem die Geräte fragen muss (passive Readings). Beispiele: energyDay bei EM1010PC, counter bei M232, temperature bei OWTEMP

Dasselbe Gerät kann sowohl aktive als auch passive Readings beinhalten. Bei Geräten mit aktiven Readings sind passive Readings meist Informationen wie Versionsnummer oder Uptime (CUL, CM11).

Geräte, die mehrere verschiedene Readings haben, senden diese häufig im Batch an fhem (Beispiel: FHT80b, KS300).

====Mechanismus für aktive Readings====
''TODO: Mechanismus mit ParseFn, GetFn, Match usw. beschreiben (wie in fhem 4.x)!''

====Mechanismus für passive Readings====
Für passive Geräte gibt es eine Polling-Infrastruktur.

'''Status Quo in fhem 4.x:'''

In der Routine DEVICE_Define wird ein interner Timer gestartet, der die Updatefunktion aufruft. INTERVAL ist die Periode in Sekunden.

sub
DEVICE_Define($$) {
...
InternalTimer(gettimeofday()+$hash->{INTERVAL}, "DEVICE_GetUpdate", $hash, 0);
...
}

In der Routine DEVICE_GetUpdate werden dann die Readings vom Gerät geholt und der Timer wird mit dem gleichen Befehl erneut gestartet.

sub
DEVICE_GetUpdate($$) {
...
# start internal timer; do it at the beginning to achieve equal intervals no matter how long it takes to gather data
InternalTimer(gettimeofday()+$hash->{INTERVAL}, "DEVICE_GetUpdate", $hash, 1);
# gather data
...
}

Der letzte Paramater 0 oder 1 ist waitIfInitNotDone.

Fragen:
* Kann/soll dieses Verfahren in einem Modul gekapselt werden? Geräte melden sich dann an der Polling-Infrastruktur an. Wenn ja, wie?
* Wie wird waitIfInitNotDone korrekt eingesetzt?

====Mechanismus für langsame Readings====
'''Problemstellung:''' Längere Verarbeitungsprozesse in einzelnen Modulen (z.B. aufgrund von Netzwerklatenzen oder toten Geräten) halten fhem komplett an und verhindern die Verarbeitung von Events.

'''Lösung:''' Multiprocessing

Beim Multiprocessing wird der fhem-Prozess geforkt, wenn ein Reading vom Gerät eingelesen werden soll. Der Vaterprozess wird sofort fortgesetzt und erledigt weitere Aufgaben. Der Kindprozess holt die Readings vom Gerät, liefert sie an den Vaterprozess und verendet.

Die Lieferung des Resultats an den Vaterprozess erfolgt durch eine Loopback Verbindung zu fhem via localhost.

Dieser Mechanismus wurde durch Rudolf König in ein entsprechendes Modul verpackt, so dass jedes andere FHEM-Modul diese Möglichkeiten direkt nutzen kann. Eine nähere Erklärung sowie eine Anleitung dazu findet man in dem Artikel → [[Blocking Call]]

'''Fragen''':
* Soll es diesen Mechanismus nur passive Readings geben oder gibt es Anwendungsfälle für aktive Readings?

'''Verworfene Alternative''': Multithreading

Argumente gegen Multithreading:
* Wird praktisch auf keiner kleinen Plattform unterstützt.
* Negative Erfahrungen (z.B. Probleme bei vielen 3rd-party-Komponenten)
* Kaum Programmiererfahrung mit Multithreading in Perl.

==Verabschiedene Richtlinien==
===Zeichensatz===
Alle nach aussen sichtbaren Werte sind in der Zeichenkodierung ASCII (Codes 32..127). Dies vermeidet Konvertierungsprobleme bei der Bearbeitung des Quellcodes, bei der Ausgabe durch Perl, beim Transport in Internet-Protokollen und bei der Darstellung im Frontend/GUI.

===Klassifizierung der Attribute===
Die Attribute eines Moduls werden in logische Klassen (Rubriken) eingeteilt.

====Sinn und Zweck====
Die Rubriken helfen...
* zu sortieren, welche Attribute bei (xml)list gezeigt werden und welche nicht,
* zu definieren, welche Werte per save in die Sicherung kommen und welche nicht,
* zu vereinbaren, welche Änderungen ein notify auslösen und welche nicht,
* zu definieren, wie ein Attribut im $hash->{} abgelegt wird (in $hash->{}, $hash->{READINGS}, $hash->{INTERNALS}, ...),
* zu gliedern, welche Namenskonventionen jeweils für Attribute verwendet werden (Kleinbuchstaben, Großbuchstaben, CamelCaps, ...),
* abzugrenzen, wo der Entwickler sich an Vorgaben halten muss (z.B. bei System Internals) und wo er frei ist, Attribute zu erfinden oder wegzulassen, und
* festzulegen, wo bzgl. der Inhalte Standards notwendig sind und wo nicht (z.B. bei "Logical Readings", wenn diese im GUI angezeigt werden sollten).

====Logische Rubriken====
Die folgenden Rubriken stellen eine sehr feine Einteilung dar:
* System Internals: werden vom Framework (fhem.pl) benötigt/verwendet/erkannt, z.B. NAME, NR, CHANGED
* Device Readings: Rohdaten, die vom physischen Gerät ausgelesen werden (nicht interpretiert), z.B. rain_raw (Wippenschläge des Regensensors) in KS300
* Hilfsvariablen: z.B. rain_raw_adj (rain_raw, jedoch bereinigt um die bei einigen KS300 auftretenden erratischen Sprünge) in KS300, Zwischenergebnisse von Daten/Werten, die zur Mittelwertberechnung benötigt werden
* Logical Readings: ausgewertete Messdaten und Zustände, z.B. Temperatur, Niederschlag (nicht als Wippenschläge sondern in l/qm)
* Derived Readings: aus den Messdaten abgeleitete Werte, z.B. durchschnittliche Temperatur der laufenden Woche, Niederschlagsmenge des Tages
* Physical Device Parameter: z.B. Modell oder Housecode und Unitcode bei X10 oder die Sensornummer beim BS (brightness sensor)
* Logical Device Parameter: statische Werte, die als Grundlage für Berechnungen genutzt werden, z.B. Korrekturfaktoren bei den Energiemessgeräten, die Tankgeometrie beim USF1000
* Messages: alle Nachrichten, die das Gerät betreffen, z.B. "AVG_Month erfolgreich berechnet", "Script XYZ am xx.xx.xx gestartet", LastIODEV, LastRAWMSG
* Trigger: wenn Trigger direkt am Gerät hinterlegt werden, müssen nicht mehr alle Notifies durchsucht werden, sondern es kann das Modul direkt ermitteln, ob ein Notify ausgelöst wird.

====Ablage im Programm====
Programmtechnisch werden die Attribute eines Moduls so in Behältern abgelegt, dass folgende Kriterien erfüllt sind:
* Die Aufteilung ist möglichst einfach/minimalistisch.
* Anhand des Behälters lässt sich entscheiden,
** ob die Werte der darin enthaltenen Attribute über das Programmende hinaus gespeichert oder nicht gespeichert werden,
** welchen Anzeigestandards oder Programmierstandards die darin enthaltenen Attribute entsprechen, und
** ob es sich um fhem-interne Attribute, Readings oder Hilfsvariablen handelt.

Es gibt folgende Behälter:

readings
* Logische Rubrik: Device Reading, Logical Reading, Derived Reading
* Wird gespeichert
* Alle vom Gerät gelieferten bzw. berechneten Werte, die den Endanwender interessieren. Keine Rohdaten vom Gerät, die erst interpretiert werden muessen (Wippenschläge beim Regensensor).
* Alle Daten haben einen Wert und ein Zeitstempel
* Beispiele:
$defs{Lampe}{readings}{switchedTo}{value} = "on"; $defs{Lampe}{readings}{switchedTo}{time} = "2010-03-29 23:32:26"
$defs{FHToben}{readings}{measuredTemp}{value} = "23"; $defs{FHToben}{readings}{switchedTo}{time} = "2010-03-29 21:58:36"

helper
* Logische Rubrik: Hilfsvariable, Device Reading
* Wird nicht gespeichert
* Alle Werte, die für den Endanwender nicht direkt sinnvoll sind aber vom Modul für unterschiedliche Zwecke benötigt werden. Kann auch rohe Readings enthalten.
* Beispiele:

$defs{ks300}{helper}{cumMonth} = "23 T: 131.4 H: 816 W: 775.1 R: -651.1"
$defs{emwz}{helper}{basis} = "4776493"

fhem
* Logische Rubrik: System Internals, Physical Device Parameter, Logical Device Parameter
* Wird nicht gespeichert
* Alle Geräte-Werte, die nicht gespeichert werden müssen, weil entweder berechnet, oder aus der Definition hervorgehen.
* Beispiele

$defs{emwz}{fhem}{def} = "1 75 900"
$defs{emwz}{fhem}{lastIODev} = "CUL"

Verworfener Behälter STATE
* Logische Rubrik: Device Reading, Logical Reading, Derived Reading
* Wird gespeichert
* Kurze(!) Zusammenfassung der wichtigsten Information des Geräts. Was man in einer Übersicht über die Geräte sehen möchte, z.B. eine Warnung oder die aktuelle Temperatur beim FHT80 oder der Zeitpunkt der letzten Aktivierung beim PIRI. Falls es das nicht gibt, dann einheitlich "defined". GGf. über Attribute am Modul steuerbar. Eigentlich ist es kein Behälter im üblichen Sinne, da es keine Untereinheiten hat.

Der Behälter wurde verworfen, weil er redundant ist, an sich gar kein Behälter, und einfacher und flexibler über einen Verweis auf das Reading realisiert werden kann, der per Default angezeigt werden soll.

====Status====
Kurze Zusammenfassung der wichtigsten Information des Geräts. Was man in einer Übersicht über die Geräte sehen möchte, z.B. eine Warnung oder die aktuelle Temperatur beim FHT80 oder der Zeitpunkt der letzten Aktivierung beim PIRI. Falls es sowas nicht gibt, dann einheitlich "defined". Modulseitig gibt es einen Default, der auf das relevante Reading verweist. Dieser ist über das Attribut defaultReading am individuellen Gerät steuerbar.

Beispiel: Definition in der Konfigurationsdatei: attr myDevice defaultReading measuredTemp Verwendung im Code:

$defs{myDevice}{readings}{$attr{defaultReading}}

Die logischen Rubriken Messages und Trigger wurden noch nicht diskutiert.

===Bezeichnungen===
Verwendung von lowerCamelCaps für alle vom Modul nach aussen sichtbaren Bezeichner: a) die Bezeichnungen der Behälter für Readings, Fhem und Helper und der Untereintraege, b) die Bezeichnungen der Readings, c) die Bezeichnungen der Attribute.

Beispiel:

$defs{myFHT}{readings}{measuredTemp}{time}

===Readings===
====Standardisierung der Readings====
Die Readings werden standardisiert, indem Geräteklassen gebildet werden wie in DevelopmentInterfaces beschrieben. Die Definition der Interfaces ist explizit nicht Gegenstand dieser Entscheidungsvorlage und wird weiterentwickelt und angepasst, wie es sich bei der Entwicklung von fhem-NEU ergibt.
Struktur im Code

Zu jedem Reading gibt es die folgenden Unterbehaelter:
* value: Wert der Messgroesse
* time: Zeitpunkt, zu dem der Wert ermittelt wurde

Beispiel:

$defs{myFHT}{readings}{measuredTemp}{time}= timestamp;
$defs{myFHT}{readings}{measuredTemp}{value}= 23.5;

Readings enthalten grundsätzlich genau einen Wert und diesen ohne Einheit.

====Einheitendarstellung====
Die verwendete Einheit für ein Reading ergibt sich aus der Interfacespezifikation.

Beispiel: Gerät ist ein Thermometer => es gibt ein Reading "temperature" und dessen Einheit ist immer °C oder Celsius

Verworfene Alternative:
* Einheit ergibt sich aus der Dokumentation
* Einheit ergibt sich aus einem expliziten Untereintrag $defs{deviceName}{readings}{theReading}{unit}="°C"
* Einheit ergibt sich aus Festlegung gemaess "FHEM-Standard", z.B. immer SI-Einheiten, Temperaturen in Celsius, etc.

===Zeitdarstellung in fhem===
Zeiten werden im Programm grundsätzlich immer maschinenlesbar abgelegt, also sowohl in $defs{deviceName}{readings}{time} als auch z.B. bei der Speicherung des Zeitpunkts der Ausfuehrung des nächsten at-Kommandos.

Es gibt übergreifende Hilfsfunktionen, die die maschinenlesbare in eine menschenlesbare Darstellung umwandeln.

Argumente für maschinenlesbar:
* vereinfacht Datumsarithmetik, z.B. die Berechnung der Zeitdauer zwischen zwei Ereignissen
* kann vom Frontend in die regionale Darstellung des Anwenders übersetzt werden
* hat keine Probleme mit doppelt auftretenden Zeitpunkten bei der Umstellung von Sommer- auf Winterzeit

Folgende Zeitdarstellungen werden ausschliesslich verwendet:

A. Zahl der Sekunden seit der Unix-Epoche (was time liefert); auch wenn time eine Ganzzahl liefert, muss der Verwender damit rechnen, eine Gleitkommazahl vorzufinden. Das ist z.B. dann der Fall, wenn für die Zeibestimmung höheraufloesende Funktionen (z.B. Time::HiRes) zum Einsatz kamen und Sekundenbruchteile mitgespeichert wurden.

Hinweis zu potentiellen Problemen:
* Ab perl 5.12 ist das Jahr-2038-Problem in Perl beseitigt.
* Ab Mac OS X liefert time auch auf Macs die Zahl der Sekunden seit der Unix-Epoche (statt seit Anfang 1904)

B. ISO8601 mit optionaler Zeitzonenangabe, wobei bei fehlender Zeitzone die lokale Zeitzone des fhem-Servers gilt

Die Zeitdarstellungen werden wie folgt verwendet:
* Zur Programmlaufzeit in Variablen immer A
* In Konfigurationsdateien (fhem.conf, fhem.save) immer B
* In Logs, die für den Menschen bestimmt sind, B
* In Logs, die für die Maschine bestimmt sind, also z.B. bei Weiterverarbeitung in einem GUI, A
* In Listen (list, xmllist friendly), die für den Menschen bestimmt sind, B
* In Listen (xmllist), die für die Maschine bestimmt sind, also z.B. bei Weiterverarbeitung in einem GUI, A

Die Unterscheidung bei den Logs ist noch zu diskutieren.

Hinweise zu gnuplot:

<nowiki>set timefmt '%Y-%m-%dT%H:%M:%S' </nowiki>

(ISO8601) funktioniert, und zwar unabhängig davon, ob die optionale Zeitzonenangabe anhängt oder nicht (getestet mit Gnuplot v4.2 pl3). Für die Sekunden seit der Unix-Epoche:

<nowiki>set timefmt '%s' </nowiki>

(nicht getestet).

==Allgemeine Dokumentation==
===Events, Filter, Notify===
====Event====
Ein Event tritt ein, wenn ein oder mehrere Readings eines Geräts aktualisiert werden, weil z.B. ein Datagramm empfangen oder zeitgesteuert Werte eingelesen wurden. Es wird durch drei Angaben

<nowiki>(device, timestamp, { reading1, ..., readingN } )</nowiki>

beschrieben:
* das Gerät device
* der Zeitpunkt der Aktualisierung timestamp
* die Menge der N>= 1 geaenderten Readings reading1, .. readingN

Wenn N> 1, dann handelt es sich um ein Sammelevent, wie es z.B. von KS300 generiert wird.

====Filter====
Ein Filter filtert Events. Er hat die Form

deviceNamePattern

bzw.

deviceNamePattern:readingNamePattern

Ein Filter passt auf ein Event, wenn deviceNamePattern den Namen des device matcht und, sofern vorhanden, readingNamePattern mindestens irgendeinen Namen von reading1 bis readingN matcht.

====Mechanismus====
0. Für das Gerät device namens deviceName wird ein Datagramm empfangen oder es werden zeitgesteuert Werte eingelesen.

1. Die Readings werden aktualisiert. Für X= 1..N:

$defs{deviceName}{readings}{readingX}{value}= valueX;
$defs{deviceName}{readings}{readingX}{time}= timestamp;

2. Das Event wird erstellt und an DoTrigger übergeben.

3. DoTrigger informiert zunaechst alle Clients mit inform-Wunsch.

4. Das Event wird sodann von DoTrigger nacheinander an alle NotifyFn in der alphabetischen Reihenfolge der Gerätenamen gereicht. Darunter auch jene von Logs.

5. Wenn der Filter des Logs auf das Event passt, wird ein Log-Eintrag der Form

timestamp deviceName reading1: value1 reading2: value2 ... readingN: valueN

erzeugt.

==Zurückgestellte Entscheidungen==
===Attribute vs. Internals===
Die Unterscheidung zwischen Attributen und Internals ist nicht eindeutig. Manche define-Parameter sind optional, und man kann define-Parameter mit "modify" ändern. Insofern könnte man theoretisch einen der beiden Verfahren (modify vs. attribute) ablösen.

1. Idee: define-Parameter dürfen nachträglich nicht geändert werden, auch wenn es sich um optionale Parameter handelt => nicht-modifizierbare Internals

Pros:
* define-Parameter sind elementar für den Betrieb des Geräts und können nicht sinnvoll zur Programmlaufzeit geaendert werden (z.B. Hauskode bei X10, FHTId bei FHT80b)
* Aus den define-Parametern werden bei der Initialisierung des Geräts weitere Helper und Internals abgeleitet und gespeichert. Eine nachträgliche Änderung zieht Änderungen der Helper und Internals nach sich mit ggf. schwer durchschaubaren Nebeneffekten (z.B. corr1..corr4 bei EM, rainadjustment bei KS300). Auch die Logs ändern sich nicht nachträglich.

Contras:
* Man will nicht ein Gerät loeschen und neu anlegen, wenn es ausgetauscht wird.
* modify sollte bleiben, weil es nützlich ist.

2. Idee: Attribute enthalten Werte, die ohne Nebeneffekte zur Laufzeit geändert werden können, weil sie z.B. ad-hoc ausgewertet werden.
* follow-on-for-timer
* retrycount
* lazy

3. Idee: Attribute beinhalten geräteunabhängige Meta-Informationen:
* room
* defaultReading

Contras:
* Nach 2. und 3. muesste

attr my_at disabled

doch zu Definition gehoeren. Und "skip_next" auch.

Spezialitäten
* beim FS20 bleibt alles, wie es ist, also model als Attribut, was Auswirkung auf die möglichen set Befehle hat.
* 1wire setzt nach define das model Attribut, lässt aber eine Änderung nicht zu, oder wenn doch, dann muss sich dementsprechend verhalten, es macht ja evtl. Sinn es zu ändern. Was machbar ist, entscheidet der Modul-Author.

Damit ist "model" immer ein Attribut.

Fazit

Da es keine überzeugende Alternative zum Ist-Zustand in fhem 4.x gibt, wird b.a.w. nicht hierüber entschieden.

===notify===
Die Frage, ob der notify-Mechanismus, der weiter oben dokumentiert ist, aus Performancegruenden optimiert werden sollte, ist offen.

In fhem 4.x bekommt jedes Gerät mit NotifyFn jedes Event mit. Alternativ könnte sich ein Gerät als EventListener mit einem Filter bei fhem anmelden. Dann könnten die Events nur an die NotifyFn verteilt werden, für die es ein Match auf den Filter gaebe.

Der Punkt wurde zurückgestellt, bis nachgewiesen ist, dass sich aus dieser Vorgehensweise relevante Auswirkungen auf die Systemlast ergeben.

==Entscheidungen==
;E1
:Es werden die Container fhem, readings und helper verwendet.
;E2
:Es wird ein Attribut defaultReading verwendet.
;E3
:Verwendung von lowerCamelCaps für a) die Bezeichnungen der Behälter für Readings, Fhem und Helper und der Untereintraege, b) die Bezeichnungen der Readings, c) die Bezeichnungen der Attribute.
;E4
:Verwendung von value und time.
;E5
:Zeitdarstellung im Programm grundsätzlich maschinenlesbar
;E6
:Zulässige Zeitdarstellungen
* Sekunden seit der Unix-Epoche
* ISO8601 mit optionaler Zeitzonenangabe
ISO8601 mit _ statt T war nicht mehrheitsfähig.
;E7
:Verwendung der Zeitdarstellungen
;E8
:Readings enthalten grundsaetzlich genau einen Wert und diesen ohne Einheit.
;E9
:Einheiten ergeben sich aus der Interfacespezifikation.
;E10
:Entscheidung für ASCII
;E11
:Die Readings werden standardisiert, indem Geräteklassen gebildet werden wie in DevelopmentInterfaces beschrieben. Die Definition der Interfaces ist explizit nicht Gegenstand dieser Entscheidungsvorlage und wird weiterentwickelt und angepasst, wie es sich bei der Entwicklung von fhem-NEU ergibt.

[[Kategorie:Development]]

TuxRadio

2014-08-12T19:53:05Z

Kamischi:

{{Todo|Der Artikel sollte in die Beschreibung des Nachfolgers [[Tuxradio 2]] eingearbeitet oder auf die Erwähnung der Unterschiede zu diesem reduziert werden.}}

Das TuxRadio der Firma busware.de[http://busware.de/] kommt mit einem minimalen Debian-Betriebssystem daher und wird über eine Konsole bedient. Die Verbindung zum Router wird über einen USB/Lan Adapter oder einen USB/WLan Adapter hergestellt. Für den USB/Lan Adapter sind keine weiteren Einstellungen erforderlich, für den USB/WLan Adapter müssen die WLan Zugangsdaten in der Datei /etc/Wireless/RT2870STA/RT2870STA.dat editiert werden.

== TuxRadio Startup ==
Um auf TuxRadio zugreifen zu können benötigt man auf seinem Computer einen SSH-Clienten. Unter Windows gibt es z.b. das Program [http://www.putty.org/ Putty], bei Ubuntu-Linux gibt es z.B. [http://wiki.ubuntuusers.de/Vinagre Vinagre] (muss über den Terminal mit root-Rechten geöffnet werden: sudo vinagre). Im Clienten Vinagre wählt man "verbinden", in dem geöffneten Fenster SSH, als Rechner gibt man die vom Router zugewiesene IP-Adresse von TuxRadio ein, Benutzername ist der von busware.de mitgeteilte. In der sich öffnenden Konsole wird noch das von busware.de mitgeteilte Passwort eingegeben.

Als Erstes sollte eine Aktualisierung des Systems mit folgenden Befehlen durchgeführt werden.

<pre>
apt-get update
apt-get upgrade
</pre>

Aktualisierungen sollten regelmäßig durchgeführt werden, um immer auf dem aktuellen Stand zu sein.

Um die aktuelle Zeit aus dem Internet beziehen zu können, muss noch ein Zeitprotokoll installiert werden. Debian bietet das Network Time Protocol (NTP)[http://packages.debian.org/de/source/squeeze/ntp] zum installiert an.

<pre>
aptitude install ntp
</pre>

== Fhem installieren ==
Das aktuelle fhem Paket wird von [http://fhem.de/fhem.html fhem.de] heruntergeladen. Für Debian benötigen wir das .dep Paket. Nun wird das Paket über ein Dateiverwaltungsprogramm zum TuxRadio in den Ordner "home" kopiert. Dazu geht man z.B. im Programm Nautilus (Ubuntu) auf "Datei" und dann auf "mit Server verbinden" (SSH wählen) Zum Installieren wird in der Konsole folgender Befehl (mit der richtigen Versions-Nr) eingegeben:

<pre>
apt-get install /home/fhem-5.''x''.dep
</pre>

== CUL flashen ==

Zum Abschluß muss die CUL (das Radiomodul) geflasht (neue firmware aufgespielt) werden. Dazu wird von der Seite [http://culfw.de/culfw.html culfw.de] die aktuelle Version heruntergeladen und entpackt.

Bei Verwendung von HomeMatic muss culfw noch bearbeitet werden. Dazu geht man in den Ordner CULFW_VER_xxx/culfw/Devices/Tuxradio und dann auf board.h. Hier müssen ganz unten in der Liste bei den Einträgen

<pre>
//#define HAS_ASKSIN

//#define HAS_ESA
</pre>
die beiden // entfernt werden. Dann speichern. Jetzt wird CULFW_VER_xxx in den Ordner "dev" auf dem TuxRadio kopiert. Um flashen zu können müssen, noch mehrere Programme in der Konsole installiert werden.

<pre>
apt-get install make avrdude avr-libc binutils-avr gcc-avr dfu-programmer
</pre>

Dann folgendes eingeben

<pre>
cd /dev/CUL_VER_''xxx''/culfw/Devices/TuxRadio

make clean

make

make program
</pre>

Zum Schluß noch TuxRadio herunterfahren und neustarten mit dem Befehl

<pre>
shutdown -r now
</pre>

Über den Browser kann jetzt unter der Adresse <nowiki>http://<IP-Adresse von TuxRadio>:8083/fhem</nowiki> auf die Bedienoberfläche von fhem zugegriffen werden.

[[Kategorie:TuxRadio]]

SML

2014-08-12T19:52:22Z

Kamischi:

{{Infobox Modul
|ModPurpose=Auswertung von SML Zählern (SmartMeter)
|ModType=h


|ModForumArea=[http://forum.fhem.de/index.php/board,46.0.html Sonstiges]
|ModTechName=70_SML.pm
|ModOwner=[[SML#Kontakt|bentele]]
}}

Das Smart Metering Language ([[SML]], auf XML basierende Syntax) Modul ist ein Modul zur Auswertung von über LAN (TCP/IP) abfragbaren Stromzählern.

== Voraussetzung ==
Der Stromzähler muss von FHEM aus über das Netzwerk erreichbar sein, üblich ist der Port 80, es ist aber auch jeder andere Port denkbar.

Zur Zeit bekannte Stromzähler, die abgefragt werden können:

* "Intelligenter Strom Zähler" (ENBW)
* "Sparzähler" (Yellow Strom)

== Benutzung ==
Die Definition eines SML Devices erfolgt mit dem Befehl:

<nowiki>define <name> SML <host> <port> [<interval> [<timeout>]]</nowiki>
Wobei <host> der Hostname und <port> der angegebene TCP Port des Zählers sind.

Das <interval> ist per default 300 sec. Das bedeutet, es wird der Durchschnitt aus den letzten 300 sec (5 Minuten) ausgegeben.

Der <timeout> gibt an, wie lange ein Verbindungsaufbau versucht wird, Default ist hier 4 Sekunden.

Zählerstand einzutragen:

<nowiki>set <name> TOTALPOWER <wert></nowiki>

== Loggen ==
<nowiki>define SML_log FileLog /var/log/fhem/enbw-%Y.log sml:.*</nowiki>
So sieht dann eine Log Zeile aus, die pro Intervall erzeugt wird:

<nowiki>2012-08-08_19:03:08 enbw min: 441 max: 1935 last: 672 avg: 771.35 day: 5.124356 month: 66.241639 year: 11834.708207 total: 11834.708207</nowiki>
Day: das ist die Tagessumme, und wird um 24 Uhr wieder auf 0 KW gesetzt.
Month: das ist die Monatssumme und wird jeden Monat wieder auf 0 KW gesetzt.
Year: das ist die Jahressumme und wird jedes Jahr auf 0 KW gesetzt.
Total: das ist der Zählerstand und wird nicht verändert.

== Plotten ==
<nowiki>define wl_ENBW weblink fileplot SML_log:smartmeter:CURRENT</nowiki>
[[File:SML2.png|808px|Beispiel eines SML-Plots]]

smartmeter.gplot:

<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 title '<TL>'
set y2label "currentPower (W)"
set ylabel "totalEnergyDay (kWh)"
#FileLog 12:enbw:0:
#FileLog 10:enbw:0:
#FileLog 8:enbw:0:
#FileLog 6:enbw:0:
#FileLog 4:enbw:0:
plot \
"< awk '/enbw:/ {print $1, $12}' <IN>"\
using 1:2 ls l9 axes x1y1 title 'day' with filledcurve,\
"< awk '/totalEnergyDay:/ {print $1, $10}' <IN>",\
using 1:2 ls l2 axes x1y2 title 'averange' with histeps,\
"< awk '/totalEnergyDay:/ {print $1, $8}' <IN>",\
using 1:2 ls l3 axes x1y2 title 'last' with histeps,\
"< awk '/totalEnergyDay:/ {print $1, $6}' <IN>",\
using 1:2 ls l1 axes x1y2 title 'max' with histeps,\
"< awk '/totalEnergyDay:/ {print $1, $4}' <IN>",\
using 1:2 ls l0fill axes x1y2 title 'min' with histeps</nowiki>

== Kontakt ==
Bei Problemen/Fragen bitte per Mail an: gabriel AT bentele DOT de, wenden.
[[Kategorie:HOWTOS]]
[[Kategorie:Glossary]]

EM-1000 EM Wirkleistungsmessgerät

2014-08-12T19:51:46Z

Kamischi:

Der '''EM-1000 EM Wirkleistungsmessgerät''' ist ein als Zwischensteckdose ausgeführter Sensor. Er misst und sendet die effektive Leistungsaufnahme des angeschlossenen Verbrauchers.

== Lieferumfang ==
* EM1000-EM
* Bedienungsanleitung

== Funktionen ==
* Der Sender kann über [[CUL]] empfangen werden.
* Siehe [[FHEM Command Reference]] unter CUL_EM

== Technische Daten ==
* Sendefrequenz: 868,35 MHz

== Hinweise zum Betrieb mit FHEM ==
Zum Empfang der Daten muss ein CUL im [[SlowRF]]-Modus verwendet werden.

Definition in fhem.cfg:
:<code>define <name> CUL_EM <code> [corr1 corr2 CostPerUnit BasicFeePerMonth]</code>

* '''<code>''' ist die Einstellung, die innerhalb des Sensors gewählt werden muss. Das EM1000-System sieht insgesamt 12 Adressen vor, von denen die Adressen 5..8 für EM1000EM vorgesehen sind. Aus diesem Bereich muss die zu verwendende Adresse per Tastendruck am Gerät ausgewählt werden (siehe Handbuch)
* '''[corr1,corr2]''' corr1 ist der Kalibrierfaktor für den Momentanverbrauch, corr2 für den Gesamtverbrauch, bitte die [http://fhem.de/commandref.html#CUL_EM Hinweise in der commandref] beachten

'''EMWZ Geräte'''
* corr1 = die Umdrehungsgeschwindigkeit (U/kW) des verwendeten Stromzählers (z.B. 150)
* corr2 = 12 mal des corr1 Wert (z.B. corr1=150 dann corr2=1800)

=== Log-Auszüge ===
Erkennung des EM-1000-Sensors durch FHEM
<nowiki>2012.11.24 14:13:29 1: CUL_EM detected, Code 7 CNT: 222 CUM: 38721 5MIN: 0 TOP: 0
2012.11.24 14:13:29 2: autocreate: define CUL_EM_7 CUL_EM 7
2012.11.24 14:13:29 2: autocreate: define FileLog_CUL_EM_7 FileLog ./log/CUL_EM_7-%Y-%m.log CUL_EM_7:CNT.*
2012.11.24 14:13:29 2: autocreate: define weblink_CUL_EM_7 weblink fileplot FileLog_CUL_EM_7:power8:CURRENT</nowiki>

Empfangene Daten des EM-1000-Sensors
<nowiki>2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank CNT: 151 CUM: 41.394 5MIN: 0.050 TOP: 0.130
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank tsecs: 1354046303
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank seqno: 151
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank peak: 0.13
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank total: 41.394
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank current_cnt: 5
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank current: 0.05
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank total_cnt: 41394
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank peak_cnt: 13
2012-11-27 20:58:23 CUL_EM UG.EM7.Gefrierschrank RAW: CNT: 151 CUM: 41394 5MIN: 5 TOP: 13</nowiki>

=== Basiswert zurücksetzen ===
Um den kumulierten Zählerstand einmalig auf den abgelesenen Zählerstand zu bringen, sind folgende Schritte erforderlich:

* fhem stoppen (shutdown)
* folgende Zeile in fhem.save erzeugen: <code>setstate EMEZ_NAME 2012-mm-dd hh:MM:SS basis basisWert</code> mit <basisWert> = <abgelesenerMeterWert> / <corr2> - <total_cnt_Reading> (01.06.2013/Anmerkung PeMue: ist vermutlich nicht ganz korrekt, da im fhem Forum folgendes diskutiert wird: <code><basisWert> = <zaehlerwert> * <corr1> - <total_cnt></code>
* dann fhem starten.

Alternativ im Fhem-Befehlsfeld mit dem Befehl:
:<code>{ setReadingsVal($defs{EMEZ_NAME},"basis",basisWert,TimeNow()) }</code>

== Bekannte Probleme ==
Das Senden der Verbrauchsdaten findet alle fünf Minuten mit einer Auflösung von 1Wh statt, somit erhält Fhem nur dann einen neuen Energieverbrauchswert, wenn insgesamt 1Wh verbraucht wurde. Bei geringer Leistungsaufnahme des Verbrauchers kann dies recht lange dauern.

== Links ==
* Bedienungsanleitung bei ELV [http://www.elv-downloads.de/service/manuals/EM1000EM/62117_um.pdf PDF]

[[Kategorie:EMS Components]]
[[Kategorie:Energieverbrauchsmessung]]

Creating Plots - caching SVG's

2014-08-12T19:51:16Z

Kamischi:

== Das Problem: ==
Die Anzeige von Grafiken in FHEM benötigt relativ lange Zeit. Speziell, wenn es um längere Zeiträume (Monat/Jahr) geht, und viele Werte gespeichert sind, kann das mehrere Sekunden dauern.

Diese Anleitung geht davon aus, dass grundsätzliche Kenntnisse über Fhem sowie über die Vorgehensweise, wie Grafiken erstellt werden, besteht. Grundlegende Infos sind im Artikel [[Creating Plots]] zu finden.

== Der Lösungsansatz ==
Alle Grafiken, die sich auf Werte in der Vergangenheit beziehen, ändern sich nicht mehr, werden aber dennoch jedesmal neu abgefragt und neu berechnet. Für diese Art von Grafiken wird eine caching Lösung aufgezeigt.

== Voraussetzungen ==
Dieses Beispiel geht von folgendener Situation aus:

* es gibt ein DbLog (in diesem Beispiel myDbLog), das alle readings speichert.
* es gibt einen Sensor (in diesem Beispiel '''AussenTempHum'''), der die readings '''temperature''' und '''humidity''' liefert.
* Das Beispiel geht davon aus, dass Fhem unter dem User fhem läuft.

== Definitionen ==
=== Definition eines weblinks ===
define AussenTempHum_current_day weblink dbplot myDbLog:TempHum_MH
attr AussenTempHum_current_day label "Temp- min: $data{min1}, max: $data{max1}, last: $data{currval1}, Feuchte- min: $data{min2}, max: $data{max2}, last: $data{currval2}"
attr AussenTempHum_current_day plotfunction AussenTempHum
attr AussenTempHum_current_day title "Aussen"

Das Attribut '''plotfunction''' bestimmt, welches device in der Datenbank selektiert wird (in diesem Beispiel AussenTempHum).

Die Attribute '''title''' und '''label''' bestimmen, was in der Überschriftszeile des Plots steht.

=== Definition des gplotfile (TempHum_MH.gplot) ===

# TempHum_MH.gplot
# MH 12/2012 support both dblog and filelog
# Attribute 'small' is useful for gnuplot/-scroll only,
# if plotsize is less than 800,400
#set terminal png transparent small size <SIZE> crop
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 ytics nomirror
set y2tics
#set ytics
set title '<TL> <L1>'
set grid xtics y2tics
set y2label "Temperature (°C)"
set ylabel "Humidity (%RF)"
set yrange [0:99]
#FileLog 4:temperature:10:
#FileLog 4:humidity:50:
#DbLog <SPEC1>:temperature:10:
#DbLog <SPEC1>:humidity:50:
plot \
ls l0 axes x1y2 title 'Measured temperature' with lines
ls l1fill axes x1y1 title 'Humidity' with lines

Nachdem diese beiden Definitionen aktiviert worden sind, sollte es in Fehm eine Grafik geben, die in etwa so aussieht:

[[File:Cachesvg.png|800px]]

Bis hierher war alles standard Fhem, das sollte also funktionieren bevor es zum schwierigen Teil kommt.

Es wird ein Verzeichnis benötigt, um die Grafiken zu speichern, wo Fhem sie nachher auch wieder finden kann und darf, in diesem Beispiel (telnet/SSH auf Raspberry PI):

sudo mkdir /opt/fhem/svgcache/
sudo chown -R fhem:root /opt/fhem/svgcache/

== Erster Test ==
Ein erster Test (von der telnet/SSH commandline) wird mit den folgenden Kommandos durchgeführt:

:<code>cd /opt/fhem/svgcache/</code>
:<code>sudo -u fhem wget -O testx.svg <nowiki>'http://localhost:8083/fhem?cmd=showlog</nowiki> AussenTempHum_current_day myDbLog TempHum_MH -&pos=zoom=month;off=0'</code>

Die wesentlichen Parameter sind:
;sudo -u fhem :damit läuft das wget unter dem user 'fhem', damit es keine Probleme mit Dateiberechtigungen gibt.
;-O testx.svg :das ist der Dateiname, unter dem die erstellte svg gespeichert wird.
;<nowiki>http://localhost:8083</nowiki> : muss jeweils angepasst werden....
;&pos=zoom=xxx;off=yyy : xxx: year, month, week, day - die Zeitspanne yyy: 0, -1, -2, ... - wieviele Zeitspannen zurück, 0==aktuell Beipiel: &pos=zoom=month;off=-1 - ergibt die Grafik des vorherigen Monats.

Und das Ergebnis bewundern (im Browser):
<nowiki>http://localhost:8083/fhem/svgcache/testx.svg</nowiki>
Es sollte jetzt die gewünschte Grafik aufgebaut werden.

=== Todo ===
Automatisieren der Grafikerstellung mittels fhem at.

== Die gespeicherten SVGs von Fhem anzeigen lassen ==
=== Definitionen ===
Die folgende Definition ist als eine Zeile (ohne Zeilenumbrüche) einzutragen.

:<code>define AussenTempHum_lastmonth weblink htmlCode <object data="/fhem/svgcache/AussenTempHum_month-last.svg" type="image/svg+xml" width="800" height="160" name="weblink_test"></object> <a href="/fhem?detail=AussenTempHum_lastmonth">AussenTempHum last month</a> </code>

Damit wird Fhem mitgeteilt, wo die Grafik zu finden ist (object data="'''/fhem/svgcache/Au...''').
Der Dateiname muss natürlich mit dem aus dem vorherigen wget übereinstimmen!

== Fazit ==
Damit können beliebige plots definiert, gepeichert und von Fhem relativ schnell abgerufen werden. Grundsätzlich wäre diese Lösung auch ohne DbLog möglich, allerdings müssten dazu die Beispiele überarbeitet werden.



[[Kategorie:HOWTOS]]

Intertechno Code Berechnung

2014-08-12T19:50:39Z

Kamischi:

'''Intertechno''' Systemkomponenten sind kostengünstige und weit verbreitete Funkschalter/-dimmer im 433 MHz Bereich, die man in fast jedem Baumarkt unter den Markennamen Intertechno, düwi, KlikAanKlikUit usw. erhalten kann.

Es gibt eine Anzahl weiterer Hersteller/Handelsmarken mit ähnlicher Kodierung oder Einstellmöglichkeiten mit DIP Schaltern, die ebenfalls mit dem Intertechno Code geschaltet werden können. Dazu zählen von Usern bereits erfolgreich getestete Geräte von Elro AB440, FLS-100/m-e, Wetekom/Westfalia und weitere, theoretisch mögliche aber ungetestete Systeme wie Unitec oder Arctech Steckdosen (siehe [http://avr.börke.de/E-Funk.htm Börkes-HP])

== Voraussetzungen in Fhem ==
Schalten kann man die Intertechno Funkkomponenten in Fhem über verschiedene Wege. So z.B. über CUL/CUNO, Tellstick, [[AVR-NET-IO]].

Hier beschrieben ist die Ansteuerung über CUL/CUNO, dessen Firmware für Intertechno erweitert wurde (Danke an Olaf Droegehorn). Momentan ist in CUL/CUNO das SENDEN von Intertechno Funk implementiert. Die Firmware muss mindestens den Stand 1.44 haben (Kontrolle der Version in den Fhem Detaildaten zum [[CUL]]/[[CUNO]]). Die CUL433/CUNO433 haben dabei volle Reichweite, die Versionen CUL868/CUNO868 funktionieren ebenfalls, haben aufgrund der nicht optimalen Antennenlänge für den Frequenzbereich aber nur eine eingeschränke Reichweite.

=== Definition ===
Die Definiton des IT Gerätes in FHEM sieht so aus:

<nowiki>define myITSwitch IT <housecode><group_switch> <on-code> <off-code> [<dimup-code> <dimdown-code>]
attr myITSwitch IODev CUL_x (CUNO_x)
attr myITSwitch model itswitch</nowiki>
Die weitere Anleitung soll die Bildung der Bitfolge für die Zusammensetzung des Schaltcodes erklären.
Wichtig zu wissen ist auch, dass es sich um einen 3state code handelt, d.h. jedes Bit kann '''0,1 oder F''' sein!

== Original Intertechno System ==
=== Hauscode (die ersten vier Stellen (0-3) ===
Der Hauscode wird auf dem Drehschalter auf der Rückseite eingestellt und hat die Bezeichnung '''A-P'''

[[File:Img_3324_small.png|thumb|Intertechno Schalter]]
{| class="wikitable"
! Drehschalter !! Stelle 0-3
|-
| A || 0000
|-
| B || F000
|-
| C || 0F00
|-
| D || FF00
|-
| E || 00F0
|-
| F || F0F0
|-
| G || 0FF0
|-
| H || FFF0
|-
| I || 000F
|-
| J || F00F
|-
| K || 0F0F
|-
| L || FF0F
|-
| M || 00FF
|-
| N || F0FF
|-
| O || 0FFF
|-
| P || FFFF
|}

=== Gruppen-/Gerätecode (Stelle 4-7) ===
Der zweite Drehschalter ist mit den Zahlen von 1-16 beschriftet. Das ist eine Zusammensetzung von Gruppe und Gerätecode und ergibt die nächsten 4 Stellen. Die dritte Spalte in der Tabelle zeigt die Zuordnung einer Intertechno YCT-100 / ITS-150 Fernbedienung. Diese ist mit Drehschalter auf der Rückseite (A-P), einem Gruppenschalter (1-4) , und je vier ein-/aus-Tasten belegt.

[[File:Img_3325_small.png|right|thumb|Intertechno Fernbedienung]]

{| class="wikitable"
! Drehschalter !! Stelle 4-7 !! Fernbedienung Gruppe/Taste
|-
| 01 || 0000 || 1 - 1
|-
| 02 || F000 || 1 - 2
|-
| 03 || 0F00 || 1 - 3
|-
| 04 || FF00 || 1 - 4
|-
| 05 || 00F0 || 2 - 1
|-
| 06 || F0F0 || 2 - 2
|-
| 07 || 0FF0 || 2 - 3
|-
| 08 || FFF0 || 2 - 4
|-
| 09 || 000F || 3 - 1
|-
| 10 || F00F || 3 - 2
|-
| 11 || 0F0F || 3 - 3
|-
| 12 || FF0F || 3 - 4
|-
| 13 || 00FF || 4 - 1
|-
| 14 || F0FF || 4 - 2
|-
| 15 || 0FFF || 4 - 3
|-
| 16 || FFFF || 4 - 4
|}

=== Stellen 8-9 (Festwert 0F) ===
<nowiki>Die Positionen 8-9 sind immer fest auf '''0F'''zu stellen</nowiki>

=== Stellen 10-11 (Ein/Aus) ===
Bei den beiden letzten Stellen steht als Codierung für ON = FF und OFF = F0.

=== Beispiele ===
Drehschalter/Hauscode auf '''A'''
<nowiki> Schalter 1 -> 000000000F FF F0 (entspricht Fernbedienung Gruppe I und Schalter 1)
Schalter 2 -> 0000F0000F FF F0 (entspricht Fernbedienung Gruppe I und Schalter 2)
Schalter 3 -> 00000F000F FF F0 (entspricht Fernbedienung Gruppe I und Schalter 3)
Schalter 4 -> 0000FF000F FF F0 (entspricht Fernbedienung Gruppe I und Schalter 4)</nowiki>

Drehschalter/Hauscode auf '''L'''
<nowiki> Schalter 11 -> FF0F0F0F0F FF F0 (entspricht Fernbedienung Gruppe III und Schalter 3)
Schalter 16 -> FF0FFFFF0F FF F0 (entspricht Fernbedienung Gruppe IV und Schalter 4)</nowiki>
komplett für die fhem cfg also z.B. Hauscode A und Gruppe 1 Gerät/Schalter 1 und CUL Bezeichnung CUL1:

<nowiki> define schalter1 IT 000000000F FF F0
attr schalter1 IODev CUL1
attr schalter1 model itswitch</nowiki>

=== Selbstlernende Intertechno Funksteckdosen (z.B. ITR-1500) ===
Zum Anlernen der selbst lernenden Funksteckdosen muss ein gültiger(!) ON-Befehl in den ersten fünf Sekunden nach dem Einstecken der Funksteckdose in eine normalen Steckdose gesendet werden. Die Funksteckdosen haben drei Speicherplätze, so dass man beispielsweise ein ITR-1500 Set zuerst mit der Fernbedienung anlernen und anschließend eigene Codes von Fhem senden lassen kann. Damit man einen gültigen Code sendet, sucht man sich einfach eine beliebige Kombination aus der obigen Tabelle aus (z.B. C-1, C-2 und C-3) und ergänzt entsprechend um die immer identischen Stellen 8 und 9 (0F) und den ON- und OFF-Code (FF/F0).
Das Senden der Codes von Fhem erfolgt am einfachsten, indem man sich die Steckdosen vorher in der Konfiguration so anlegt, wie man sie haben möchte und anschließend über die Weboberfläche den ON-Befehl gibt.

Mitunter funktioniert das reine Senden des ON Befehls aber nicht, da einige dieser Steckdosen einen längeren ON Befehl benötigen und die Sendedauer bei Fhem/CUL/CUNO nicht beeinflusst werden kann. In diesem Fall nimmt man eine YCT-100 Fernbedienung, an der die gewünschte Adresse eingestellt werden kann. Zum Anlernen drückt man nun etwas länger auf den passenden Einschaltknopf, danach kann die Dose von Fhem normal geschaltet werden.

== FLS 100 ==
[[File:FLS100.jpg|right|thumb|FLS100 - konfiguriert auf IV/3]]

Beim FLS 100 von m-e.de gibt es nur 4 mögliche Einstellungen: '''I, II, III und IV'''. Dies entspricht der Gruppe auf der Fernbedienung.

{| class="wikitable"
! Drehschalter !! Stelle 0-3
|-
| I || 0FFF
|-
| II || F0FF
|-
| III || FF0F
|-
| IV || FFF0
|}

Die nächsten vier Stellen geben die Geräte ID an; diese ist identisch mit der Taste an der Fernbedienung.
{| class="wikitable"
! Drehschalter !! Stelle 4-7 !! Fernbedienung Taste
|-
| 1 || 0FFF || 1
|-
| 2 || F0FF || 2
|-
| 3 || FF0F || 3
|-
| 4 || FFF0 || 4
|}

Beim FLS 100 ist nur die letzte Stelle relevant, mit ON: F oder OFF: 0

== REV Telecontrol ==
[[File:Rev-funksteckdose-telecontrol-3500-w-008345.png|right|thumb|REV Telecontrol]]

Die REV Telecontrol haben einen Dreh-Wahlschalter auf der Rückseite, mit dem sich der Hauscode (A - D) und der Gerätecode (1 - 3) bestimmen lässt.

Die Codierung ist dabei:
{| class="wikitable"
! Hauscode !! Stelle 1-4
|-
| A || 1FFF
|-
| B || F1FF
|-
| C || FF1F
|-
| D || FFF1
|}

{| class="wikitable"
! Gerätecode !! Stelle 5-7
|-
| 1 || 1FF
|-
| 2 || F1F
|-
| 3 || FF1
|}

Dazu (Stelle 8+9+10) noch drei statische Werte: 0FF.

Der Code für '''An''' ist FF, für '''Aus''' 00.

Beispiel:
:<code>define My_Switch IT 1FFF1FF0FF FF 00 für A1</code>
Erfolgreich getestet mit CULfw V 1.49 CUL868.

== Elro AB440 ==
=== Möglichkeit 1: zu Intertechno-Codes umdippen ===
[[File:ELRO-AB440_Funkschalter.jpg|right|thumb|Élro AB440 Funkschalter]]

Günstige ELRO Funkschalter/Dimmer der Serie 440 lassen sich auch problemlos auf Intertechno Codierung "umdippen" und damit voll kompatibel mit allen möglichen A-P / 1-16 Intertechno Schaltcodes von Fhem aus nutzen. Dazu müssen die Dipschalter-Stellungen entsprechend Intertechno umgerechnet und gesetzt werden (1=ON, 0=OFF).

Beispiele:
{| class="wikitable"
! Intertechno !! Elro Hauscode 1234 !! Elro Gerätecode 5ABCDE
|-
| A1 || 1111 || 111110
|-
| A2 || 1111 || 011110
|-
| A3 || 1111 || 101110
|-
| A4 || 1111 || 001110
|-
| A5 || 1111 || 110110
|-
| A6 || 1111 || 010110
|-
| A7 || 1111 || 100110
|-
| A8 || 1111 || 000110
|-
| A9 || 1111 || 111010
|-
| A10 || 1111 || 011010
|-
| A16 || 1111 || 000010
|-
| C1 || 1011 || 111110
|-
| C2 || 1011 || 011110
|}

Weitere Erklärungen sind z.B. im [http://isn-systems.com/tools/it2elro Tool] der Fa. ISN-systems online berechnen lassen.

Einziger Nachteil: Die originale Elro Fernbedienung funktioniert dann nicht mehr uneingeschränkt mit den Funkschaltern (eine Intertechno Fernbedienung funktioniert uneingeschränkt). Wenn man den Hauscode an der Fernbedienung einstellt, kann man durch drücken von z.T. mehreren Tasten gleichzeitig auch Intertechno schalten. Das ist aber nur was für den Notfall oder für Handakrobaten.

<nowiki>15/16 -> D
13/14 -> A+D
11/12 -> B+D
09/10 -> A+B+D
07/08 -> C+D
05/06 -> A+C+D
03/04 -> B+C+D
01/02 -> A+B+C+D</nowiki>

=== Möglichkeit 2: aus der vorhanden DIP-Schalterstellung den entsprechenden 10-digit InterTechno Code bestimmen ===
Das ist prinzipiell ganz einfach. Hat man folgende DIP-Schalter-Stellung so muss man von links nach rechts einfach für jeden DIP gleich "ON" eine "0" und für "OFF" ein "F" definieren. Für die dargestellte DIP-Einstellung ergibt sich der damit der darunterstehende InterTechno Code:

[[File:ELRO_0100101111.png]]

<code>0F00F0FFFF</code>

Analog dazu ergeben sich für den gleichen Hauscode (Schalter 1-5) folgende Codes für die Funksteckdosen B bis E, wobei die Dose E mit der Originalfernbedienung nicht adressierbar ist, sich mit FHEM aber wunderbar schalten lässt.

[[File:ELRO_0100110111.png]]

<code>0F00FF0FFF</code>

[[File:ELRO_0100111011.png]]

<code>0F00FFF0FF</code>

[[File:ELRO_0100111101.png]]

<code>0F00FFFF0F</code>

[[File:ELRO_0100111110.png]]

<code>0F00FFFFF0</code>

Dazu noch die Codes für AN = FF und AUS = F0 schaut eine vollständige Definition eines ELRO440 Funkschalters dann bsw. so aus:

<nowiki> define ELRO_10110_A IT 0F00F0FFFF FF F0
attr ELRO_10110_A IODev CUL_0
attr ELRO_10110_A alias Stehlampe
attr ELRO_10110_A fp_Grundriss 340,50,1,Stehlampe
attr ELRO_10110_A group Schalter
attr ELRO_10110_A model itswitch
attr ELRO_10110_A room Wohnzimmer</nowiki>

== Wetekom/Westfalia ==
[[File:Westfalia-Funksteckdose.jpg|right|thumb|Westfalia Funksteckdose ZTC-S316A.]]
Der eingestellte Hauscode ist F00F0FFF0F.

In den Westfalia-Baumärkten gibt es Funksteckdosen mit Westfalia-Branding. Auf der Bedienungsanleitung steht aber Wetekom.

Die Funksteckdosen selbst haben zehn DIP-Switches: 1234FEDCBA, während die Fernbedienung nur sechs hat: ABCDEF. Damit die Fernbedienung mit den Funksteckdosen funktioniert, darf man nur einen der DIP-Switches 1234 pro Funksteckdose auf ON schalten.

Die Schaltung der DIP-Switches ABCDEF4321 entspricht direkt und in dieser Reihenfolge (also andersrum als direkt an der Funksteckdose) dem Hauscode und zwar entspricht ein Switch auf OFF einem F im Hauscode und ein Switch auf ON einer 0 im Hauscode.

Die Steckdosen werden dann mit 01 ein- und mit 10 ausgeschaltet.

Beispiel:
define wf_steckdose IT F00F0FFF0F 01 10

== Pollin Funksteckdosen ==

Vom Aussehen sind die Steckdosen von Pollin (z.B. 3fach Set 550666) mit den Westfalia ZTC identisch, aber:

* die DIP Schalter sind beschriftet von 0 bis 10;
* der Adresscode entspricht dem invertierten ELRO 440 Code ->also (0=ON, 1=OFF)
* der Code für "An" ist 0F, für "Aus" F0

Beispiel für Adresse C2:

define IT_C2 IT 0F00F0000F 0F F0

== me micro-electric AS 73 ==

[[Datei:Me_AS_73.JPG|right|thumb|micro-electric Funksteckdose AS 73]]

Die micro-electric Funksteckdosen haben 10 DIP-Schalter: 123456ABCD.

Der Hauscode wird an Sender und Steckdose mit 1-6 eingestellt, der Empfängercode A-D entspricht den Kanälen auf dem Handsender.

DIP-Schalterstellung OFF entspricht F und ON entspricht 0.

Die Steckdosen werden mit F0 ein- und mit 0F ausgeschaltet.

Empfängercodes:
{| class="wikitable"
! Kanal !! Position 7-10
|-
| A || 0FFF
|-
| B || F0FF
|-
| C || FFF0 (Achtung: bei C und D sind die Codes vertauscht)
|-
| D || FF0F
|}

Beispiel:
:<code>define Schalter_ME_A IT 0F0F000FFF F0 0F</code>
:<code>attr Schalter_ME_A IODev CUL1</code>
:<code>attr Schalter_ME_A model itswitch</code>

== Conrad / McPower Funkschaltset 3+1 ==
Dieses Funkschaltset wird unter mehreren Namen in verschiedenen Bau- und Heimwerkermärkten sowie bei Conrad (Best Nr. 640475 - 62) vertrieben. Teilweise auch mit unterschiedlichen Schaltleistungen.
Die Konfiguration funktioniert genauso wie beim [http://www.fhemwiki.de/wiki/Intertechno_Code_Berechnung#FLS_100 FLS100]

== Noch nicht aufgeführte Geräte ==
Wer ein Intertechno-ähnliches Gerät besitzt, das in dieser Liste noch nicht aufgeführt ist, muss die Kodierung selbst bestimmen. Dazu gibt es verschiedene Möglichkeiten, die in diesem Abschnitt aufgeführt werden. Die Ergebnisse bitte hier eintragen, um Nachfolgern die Arbeit zu ersparen!

=== Audio-Eingang zur Messung ===
Hier wird die Fernbedienung oder der Empfänger mit einer entsprechenden Schaltung an den Mikrofon-Eingang eines Rechners angeschlossen und mit einem Audio-Programm werden die Signalverläufe aufgenommen. Diese Methode wird [http://avr.börke.de/E-Funk.htm hier] näher erläutert.

=== Platine analysieren ===
Platine der Fernbedienung oder des Empfängers betrachten und so die Beschaltung des Decoder/Encoder Chips ermitteln. Bei der Wetekom-Fernbedienung wird beispielsweise der Chip LP801b verwendet, der funktional identisch zum PT2262 ist. Im [http://www.escol.com.my/Datasheets_specs/pt2262_1.pdf Datenblatt des PT2262] kann man dann die Beschaltung nachsehen. Nun betrachtet man den Verlauf der Leiterbahnen auf der Platine, um die Beschaltung des Chips zu ermitteln. So kann man beispielsweise bei der Wetekom-Fernbedienung sehen, dass die DIP-Switches A bis F auf die Eingänge A0 bis A5 geschaltet sind. Außerdem sieht man, mit welchen Eingängen die einzelnen Taster verbunden sind.

[[File:Westfalia-Funkfernbedienung-hinten.jpg|right|thumb|Platine der Westfalia Funkfernbedienung ZTC-TC von hinten.]]
[[File:Westfalia-Funkfernbedienung-vorne.jpg|right|thumb|Platine der Westfalia Funkfernbedienung ZTC-TC von vorne.]]

Nun kann man messen, zwischen welchen Chip-Eingängen und Batteriepolen eine Spannung anliegt, bzw. (ohne Batterie) zwischen welchen Chip-Eingängen und Batteriepolen es einen Durchgang gibt, um zu ermitteln, wie die DIP-Switches schalten. Im Fall der Wetekom-Fernbedienung liegt keine Spannung zwischen den Eingängen und den beiden Batteriepolen an, wenn die DIP-Switches auf OFF stehen: Der Eingang liegt also auf F (Float). Wenn die DIP-Switches auf ON stehen, liegt nur eine Spannung zwischen dem Pluspol der Batterie und dem Eingang an, es gibt also einen Durchgang zwischen dem Minuspol und dem Eingang, so dass der Eingang auf V_SS liegt und damit 0 eingestellt ist.

Bei den Eingängen D0 und D1 sieht man, dass der Batterie-Pluspol immer über einen Widerstand mit dem Dateneingang verbunden ist, also normalerweise 1 anliegt. Ist aber ein Ein-Taster gedrückt, wird der Eingang D1 direkt mit dem Minuspol der Batterie verbunden, bei den Aus-Tastern der Eingang D0 (die Verbindung der Aus-Taster ist auf den Bildern nicht besonders gut zu erkennen). Durch diese Verbindung wird der Eingang auf V_SS heruntergezogen und damit ist 0 eingestellt.

=== Mit CUL im Debug-Modus Rohsignale empfangen und analysieren ===
Das hat wohl noch keiner versucht, wurde aber [http://forum.fhem.de/index.php/topic,5599.0.html in der FHEM Users-Mailingliste diskutiert].

[[Kategorie:HOWTOS]]

Mischersteuerung

2014-08-12T19:49:11Z

Kamischi:

{{SEITENTITEL:Mischerregelung }}
{{Infobox Modul
|ModPurpose=Stellmotor Zeitsteuerung mit Zeitabweichungskorrektur.

|ModCmdRef= ---- noch nicht Teil von FHEM ----
|ModTechName=39_STELLMOTOR.pm
|ModOwner=epsrw1,cwagner}}
Das Fhem-[[:Kategorie:Hilfsmodul|Hilfsmodul]] [[STELLMOTOR]] bietet eine einfache Möglichkeit, mit zwei Relais den Rechts-/Linkslauf eines (Mischer)motors zu steuern.

== Features ==

Diese Wiki-Seite beschreibt die Version 2.0 des STELLMOTOR Moduls.

----

* Wiedereintrittsfähig nach einem Neustart
* Wiederholungsgenauigkeit durch Ausgleich von Rundungs- und Laufzeitabweichungen
* Vermeiden von Blockade des FHEM während der Laufzeit des Motors

Thread im Forum:[http://forum.fhem.de/index.php/topic,23933.0.html]

== Beschreibung ==

[[Datei:dok39_STELLMOTOR.jpg|mini|Funktionsweise]]
Typischerweise werden im Heizkreislauf Mischer eingesetzt, um einen Heizkreis mit unabhängig vom Kesselbrenner geregelten Vorlauf zu erreichen. Auch kann man so in einer Heizanlage, die mit für Fußbodenheizung zu hohen Vorläufen arbeiten muss, einen Kreis mit begrenztem Vorlauf abzuzweigen.

Mit Hilfe des hier beschriebenen Moduls VALVES [http://www.fhemwiki.de/wiki/Raumbedarfsabh%C3%A4ngige_Heizungssteuerung] kann ein geschlossener Regelkreislauf hergestellt werden, der sich am Bedarf der Wohnräume orientiert.

Vorrangig ist dieses Modul für zwei Relais an GPIO- oder an PIFace-Pins eines Rasberrys gedacht; es bietet aber auch die Option, zwei Schaltaktoren per Funk (aus Timinggründen nicht empfohlen) oder 1-Wire anzusteuern.

Die Set-Befehle für die Mischerstellung kommen idealerweise aus der Bewertung der Vorlauftemperatur durch ein Modul wie PID20 [http://www.fhemwiki.de/wiki/PID20_-_Der_PID-Regler]. Dieser berücksichtigt auch den zeitlichen Verlauf der Temperaturänderungen im Vorlauf und ist vielfältig anpassbar.

Aus den Werten MaxTics (Default=100, für Prozentanzeige) und MaxDriveSeconds (Laufzeit des Motors von 0 bis 100%) wird die Zeit berechnet, die der Motor nach rechts oder links laufen muss, um die mit set gewünschte Ventilstellung zu erreichen.

FHEM läuft dann weiter ohne einzufrieren, und prüft im Loop nur noch ob, die Stoppzeit im Cache erreicht ist. Da der Stopp nie exakt zur geplanten Zeit ausgeführt wird, liegt im Cache ein weiterer Wert der die Differenz zwischen geplanter und tatsächlicher Stoppzeit dem nächsten Kommando hinzurechnet. So werden sich addierende kleine Zeitdifferenzen vermieden.

Zum Kalibrieren (set calibrate) fährt der Motor einfach volle Zeit nach links/null. Hier wird der in Mischermotoren wie dem Honeywell Centra VMK eingebauten Entschaltetr genutzt, um den "Null-Punkt" sicher zu finden. Falls ein angeschlossener Motor solche Endschalter nicht hat, müssen die für diese Schaltungsweise unbedingt vorgesehen werden.

== Define ==
<code>
define <name> STELLMOTOR <PiFace|Gpio|FhemDev|SysCmd>
</code>
Je nach Device Typ sind verschiedene Attribute zur erforderlich, damit STELLMOTOR weiß wie die beiden Relais angeschlossen sind.
* '''PiFace''' und '''Gpio''' benötigen STMgpioPortRL und STMgpioPortSTART
* '''FhemDev''' benötigt STMfhemDevRL und STMfhemDevSTART
* '''SysCmd''' benötigt STMsysCmdRL und STMsysCmdSTART

Für den Schaltvorgang "baut" STELLMOTOR einen set-Befehl zusammen. Beispielsweise bei FhemDev
<code>
set <**..PortRL> 0 sowie set <**..PortSTART> 1 zum Einschalten links
set <**..PortRL> 1 sowie set <**..PortSTART> 0 zum Einschalten rechts (bei Type "einzel", sonst 1,1)
set <**..PortRL> 0 sowie set <**..PortSTART> 0 zum Ausschalten
</code>

* Die Schaltbefehle 0 und 1 können mit Attributen invertiert und/oder gemapped werden (zB.: On/Off)

Um die Wirkung auszuprobieren, ohne jedes Mal zum Mischer rennen zu müssen, bietet sich an zwei '''Dummys''' zu verwenden:

<code>
define Stellmotor2rl dummy

define Stellmotor2start dummy
</code>

<code>
set <name> 45
</code>

stellt den Mischer nun auf 45%. Angenommen, stand er bei 10%, wird er nun (45-10)*MaxDriveSeconds/MaxTics Sekunden lang nach rechts laufen und dann von STELLMOTOR gestoppt.

Diese beiden Bilder zeigen die elektrische Verdrahtung von zwei Relais, die von je einem Aktor gesteuert werden:
[[Datei:Relais-Schaltung FBH-Mischer attr einzel.jpg|mini|Schaltplan einzel]] [[Datei:Relais-Schaltung FBH-Mischer attribut Wechsel.jpg|mini|Schaltplan wechsel]]

Typische Mischermotoren wie der Honeywell VMK haben eingebaute Endschalter, die beim Erreichen der 0%- oder 100%-Position die Stromversorgung unterbrechen. Das Modul Stellmotor nutzt dies aus, um eine Kalibrierung zwischen rechnerischem und tatsächlichen Mischerstand herzustellen.

----

== Attribute ==

Alle Attributes sind auch in fhem durch das kommando get attrHelp <varname> erklärt, für's "schnelle Nachschauen zwischendurch".

=== Global gültige Attribute ===

{| class="wikitable sortable"
|-
! Parameter !! Wertebereich !! Default !! Beschreibung
|-
| STMrlType|| String || einzel || je nach Schaltplan, Wechsel=start+RL-relais, einzel=R-Relais+L-Relais werden geschaltet
'''ACHTUNG:''' falsche Einstellung kann zu Kurzschluß am Motor führen, bitte Einstellung genau überdenken oder mit dummy testen

bei einzel:
Rechtslauf: start=0 rl=1
Linkslauf: start=1 rl=0 Ruhe:
start=0 rl=0

bei wechsel:
Rechtslauf start=0 rl=1
Linkslauf: L start=1 rl=0
Ruhe: start=0 rl=0

|-
|STMmaxDriveSeconds ||[0...n]||muss angepasst werden||gestoppte Zeit in Sekunden, die der Motor für die Fahrt von 0 bis 100 Prozent braucht
|-
|STMmaxTics ||[0...100]||100||Mischerstellung - bei Prozentangaben (PID20) 100, bei Winkelangaben anzupassen
|-
|STMpollInterval || Float ||0.1||Zeitintervall nach dem FHEM prüft, ob die interne Stoppzeit erreicht wurde. Hier sollte mit einem möglichst kleinen Wert gestartet werden, der vorsichtig erhöht werden kann, falls FHEM zu langsam läuft wegen des Mischermotors. Darf nicht größer STMlastDiffMax sein, sonst beginnt der Motor zu Schwingen.
|-

| STMresetOtherDeviceAtCalibrate|| String || 0 || Fhem Device das am Ende des Kalibriervorganges zusätzlich resettet wird. (command: set <STMresetOtherDeviceAtCalibrate> reset" wird abgesetzt), zB für eigenes Logging oder Rotary Encoder
|-
| STMinvertOut|| Zahl || 0 || setzen für Devices die 0 für Start und 1 für Stop erwarten
|-
| STMmapOffCmd|| String || 0 || string der im device-command anstelle '0' verwendet wird für stop
|-
| STMmapOnCmd|| String || 0 || string der im device-command anstelle '1' verwendet wird für start
|-
| STMcalibrateDirection|| String || L || auf R wird die Ralibrierung nach rechts gefahren, default= L (links)
|-

| STMlastDiffMax|| Zahl || 1|| ist die Stoppzeit weiter als dieser wert vom Soll entfernt, wird sofort ein neuer drive gestartet. Wert muss immer größer als STMpollInterval sein, sonst beginnt der Motor zu Schwingen
|-
| STMtimeTolerance|| Float || 0.001 || Stop-Time Differenzen kleiner als dieser Wert werden bei der Berechnung vollständig ignoriert (wird eventuell in Zukunft entfallen)
|-

|-
|readingFnAttributes||||||readingFnAttributes
|}

=== Device Type abhängige Attribute ===

Je nach Device Type sind verschiedene Attribute vorgesehen, um STELLMOTOR mitzuteilen, wie die beiden Relais angesprochen werden. Man kann so zB während der Aufbauphase der Installation neben den Gpio devices noch 2 dummy devices im Attr vorhalten um zwischendurch zu testen. Hierzu muss dann nur noch die DEF des STELLMOTOR Devices vorübergehend auf FhemDev geändert werden.

Alle Attributes sind auch in fhem durch das kommando get attrHelp <varname> erklärt, für's "schnelle Nachschauen zwischendurch".

{| class="wikitable sortable"
|-
! Device Type !! Parameter !! Typ !! Default !! Beschreibung
|-
| PiFace / Gpio || STMgpioPortRL || Zahl || 5 || PiFace Digital port oder Gpio-Port für RL oder R Relais
|-
| PiFace / Gpio || STMgpioPortSTART || Zahl || 4 || PiFace Digital Port oder Gpio-Port für START (oder L Relais bei 'einzel')
|-
| FhemDev || STMfhemDevRL|| String || RelaisRL || Fhem-Device name für RL (oder R) Aktor (zB.: 'keller portB' oder 'dummyRLrelais')
|-
| FhemDev || STMfhemDevSTART|| String || RelaisSTART || Fhem-Device name für START (oder L) Aktor (zB.: 'keller portC' oder 'dummySTARTrelais')
|-
| SysCmd || STMsysCmdRL|| String || 0 || freies Command das für RL an die Shell übergeben wird (zB: '/Usr/local/bin/gpio write 4', STELLMOTOR fügt 0 oder 1 arg. dazu)
|-
| SysCmd || STMsysCmdSTART|| String || 0 || freies Command das für START an die Shell übergeben wird (zB: '/Usr/local/bin/gpio write 5', STELLMOTOR fügt 0 oder 1 arg. am Ende dazu)
|-
|}

== Settings ==

{| class="wikitable sortable"
|-
! SET !! Wertebereich !! Beschreibung
|-
|set <name> N||[1...100]||stellt den Mischer auf N % Öffnung
|-
|set <name> calibrate|| - ||stellt den Mischer auf Min. oder Max (in Fhem 1% oder 100%); default: maximaler Linkslauf bis zur Endschalterpostion, kann über Attr in Rechtslauf geändert werden.
|-
|set <name> reset|| - ||Setzt die Position und die Werte im Cache auf Null. Verwendung ist intern (am Ende von calibrate) oder nach mechanischem Neueinbau des Motors (da reicht aber auch ein Calibrate)
|}

== Readings ==

Alle Readings sind auch in fhem durch das kommando get readingsHelp <varname> erklärt, für's "schnelle nachschauen zwischendurch".

{| class="wikitable sortable"
|-
! readings !! Wertebereich !! Beschreibung
|-
|position||[1..100%]||der Wert wird gesetzt am Beginn einer Mischerbewegung (anderer Wertebereich, wenn MaxTics nicht 100)
|-
|state||active,error,position||Position wird beim Stopp der Motorbewegung gesetzt
|-
|lastStart|| Float ||Zeitstempel der letzten Motorbewegung
|-
|locked||[0 1]||Steht auf 1 während der Motor gerade läuft (Calibrate oder gewünsche Position per set).

Neue Kommandos werden während lock nur in eine Warteschleife (reading: command_queue) genommen.

Zeigt im im Frontend, dass der Motor gerade läuft.
|-
|queue_lastdiff||||abhängig von der FHEM-Last oder anderen blockierenden Kommandos wird das Stopp-Kommando nur nahe an der kalkulierten Stoppzeit ausgeführt, vermutlich nie exakt. STELLMOTOR merkt sich die Zeitdifferenz, zu der der Motor wirklich gestoppt wurde und addiert bei der nächsten Bewegung des Motors die Differenz, um möglichst präzise die wirkliche Motorstellung zu erreichen.
|-
|stopTime||||Null oder die errechnete Zeit zum Stopp der Motorbewegung
|-
|command_queue||||Position einer anstehenden neuen Motorposition, die angefordert wurde als die letzte Motorbewegung noch ausgeführt oder das Modul disabled war
|-
|OutType||||Bei der Defintion gewählte Arbeitsart: PiFace,Gpio,FhemDev,SysCmd
|-
|DoResetAtStop||||Zeitstempel des Ende der letzten Kalibrierfahrt
|}

== Weblinks ==
* [http://forum.fhem.de/index.php/topic,23933.msg174400.html#new Thread im Forum], in dem dieses Modul vorgestellt wurde
* to be continued

[[Kategorie:Regelungstechnik]]
[[Kategorie:Examples]]
[[Kategorie:Heizungssteuerung]]

HMW-IO-12-Sw14-DR Wired RS485 I/O-Modul 12 Eingänge 14 Ausgänge

2014-08-12T19:48:13Z

Kamischi:

Das ''' HMW-IO-12-Sw14-DR ''' ist ein 14CH in / 12 CH out-Aktor für die HMW485-Reihe. Das ganze gibts als Bausatz oder fertig aufgebaut vom Händler. Es besitzt 6 digitale Eingänge, die direkt Ports des Mikrocontrollers ansteuern und somit TTL-Kompatibel sind. Die Eingänge sind intern auf High-Potential gelegt und lassen sich auch mit Tastern gegen GND schalten. Die 6 analogen Eingänge können mit Eingangsspannungen von 0-10V beschaltet werden. Hier können Sensoren oder z.B. Potentiometer angeschlossen werden. Als Versorgungsspannung können die +24V des Netzteils verwendet werden, es ist allerdings zu beachten, dass am Eingang die Spannung von 10V nicht überschritten wird.

Ausgangsseitig sind 8 Open-Collector-Transistor-Schaltausgänge vorhanden. Über diese sind Verbraucher mit +24V bis zu 50mA ansteuerbar, z.B. Relais, Optokoppler oder LED's.Hiermit können z.B. Eltako-Leistungsrelais angesteuert werden. Ausserdem sind noch 6 Relais-Schaltausgänge vorhanden, die mit +24V/0,8A belastet werden können. Hierüber kann z.B.ein Türöffner, ein Garagentormotor o.ä. direkt angesteuert werden.

Das Gerät erfordert die Bereitstellung einer 24V Gleichspannung, z.B. durch das zum System gehörige Netzteil. Ebenso ist ein Busabschlussmodul erforderlich (IIRC ein Widerstand mit 120R?)

== Einbindung in FHEM ==
=== Einbindung mit einem [[HomeMatic Wired RS485 LAN Gateway]] ===

Bei mir funktioniert das Discovery nicht. Der einfachste Weg scheint, an einen Eingang (bsp I12) gegen GND einen Schalter anzuschliessen. Durch Betätigung entsteht ein Device bei FHEM.

Mit einem

get <name> info

werden die grundsätzlichen Geräteeingenschaften abgefragt. Also Typ, Seriennummer, Firmware-Version. Ausserdem legt fhem die Schalter funktionsfähig an.

get config all
liest den gesamten benutzten EEprom aus, ju je 16 Byte Blöcken. TODO: wozu braucht man das?

== Kommunikation mit dem Device ==
=== set on/off ===

5.11.2013

es gibt ein neues Update im Master
Bei Geräten wie HMW-IO-12-Sw14-DR, HMW_IO_4_FM usw. können die Ein/Ausgangskanäle nun konfiguriert und per set on / off geschaltet werden. Auch der Status wird von FHEM entsprechend ausgewertet.

Das Ganze funktioniert derzeit ausschließlich für auf Ausgang konfigurierte Kanäle.

=== Konfiguration der Ausgänge ===
(Frequenz, On/Off)
... TODO

=== RAW-Daten senden ===
''' Beispiele'''

set HM485_LAN RAW TTTTTTTT 98 00000001 73AAVVVV

* TTTTTTTT: Target Adresse
* AA: Nummer des Ausgangs (00 - 0C) wobei die Zählung bei 0 beginnt und ein HEX-Wert ist

Aus der HMW-Doku:
* VVVV: Value ans HEX-Zahl
** 00-05 = Relaisausgänge
0x0000 -> Aus, 0x0100 - 0xFE00 -> Ein (Homematic sendet 0xC8), 0xFF -> Toggle

** 06-0C = OpenCollector-Ausgänge
- Schalt-Ausgang:
0x0000 -> Aus, 0x0001 - 0xFFFF -> Ein (Homematic sendet 0x03FF)

- Analog-Digital Ausgang: Frequenz in Milliherz als unsigned long (0x1000 -> 1Hz)
1000, also 03E8 Hex entspricht z.B. 1 Hertz
50000 also C350 Hex entspricht 50 Hertz

=== notifies ===

define Licht_an notify HMW_IO_12_Sw14_DR_JEQ0459634_XX:

== Links ==
* [[HomeMatic Wired]]
* [[HomeMatic Wired RS485 LAN Gateway]]

[[Kategorie:HomeMatic Components]]

HM-CFG-LAN: Überwachung der 1%-Regel

2014-08-12T19:46:54Z

Kamischi:

== Einleitung ==
Gerade in der Entwicklungsphase kann es passieren, dass z.B. durch den Einsatz von Testroutinen der Bereich der [[1% Regel]] erreicht wird und dadurch ein Gerät vorübergehend nicht mehr senden kann.

In solchen Situationen kann es von Nutzen sein, mittels Plot einen Überblick über die aktuelle Auslastung zu bekommen, um eigene Codefehler von dem werksseitig eingebauten Sendestopp zu unterscheiden. Am Beispiel eines [[HomeMatic]]-Gerätes wird im Folgenden gezeigt, wie eine derartige "Überwachung" erreicht werden kann.

=== "ERROR-Overload" und "Warning-HighLoad" ===
Der Sendestopp der HMLAN-unit wird durch die Werte "ERROR-Overload" angezeigt bzw. durch "Warning-HighLoad" vorgewarnt. Dabei handelt es sich um direkte Readings der HMLAN-unit und sind auf alle Fälle als richtig bzw. "absolut" anzusehen. Sollte die HMLAN-unit in diesen Zustand sein, wird sie keine Telegramme mehr senden, jedoch wird sie weiterhin alle Telegramme empfangen.

=== "msgLoadEst 1hour" ===
Die angezeigten "msgLoadEst" - Werte stellen keine 100%ige Genauigkeit dar, da sie "nur" annähernd berechnet werden können. Es kann daher theoretisch vorkommen, dass der Plot die 100% - Marke noch nicht erreicht hat, aber der "ERROR-Overload" Indikator bereits anzeigt, dass die HMLAN-unit seine Sendungen eingestellt hat.

<pre>
msgLoadEst 1hour:44% 10min steps: 12/2/7/23/0/0
</pre>

besagt, dass in der aktuellen Stunde 44% der Sendekapazität verbraucht sind. Im aktuellen 10min-Rahmen sind es 12%, in den 10min davor waren es 2%, davor 7% und davor 23%.

Dieser Zähler befindet sich direkt in der HMLAN-unit somit kann FHEM diesen Zähler nicht zurücksetzen. Nur durch Warten oder einen Reset der HMLAN-unit ist ein Rückstellen möglich.

== Einschränkungen ==

Man muss die folgenden Einschränkungen hinsichtlich des Plots immer beachten:

* Nach dem (shutdown)-restart fängt FHEM wieder bei 0 an zu zählen. Da die HMLAN-unit aber nicht zwangsläufig ebenfalls reseted wurde, kann bereits eine messageload in der HMLAN-unit vorliegen die fhem aufgrund des restarts nicht erfassen kann.

* FHEM kann nicht zwischen einem reboot und einem disconnect der HMLAN-unit unterscheiden. Daher wird ein disconnect als reboot gewertet. Dies führt unter Umständen ebenfalls zu einer "ERROR-Overload" - Nachricht obwohl der Plot die 100%-Marke noch nicht erreicht hat.

* FHEM kann die automatischen Wiederholungen der HMLAN-unit nicht erfassen und können daher nicht berücksichtigt werden.

* Die AES Verschlüsselung, die weitere Telegramme sendet, kann aktuell nicht gezählt werden

== Versions Updates ==
[http://forum.fhem.de/index.php/topic,21678.msg151621.html#msg151621 Version 5278]: Die Länge des Nachrichtentelegrams wird berücksichtigt.

== Plot von Highload/Overload und msgLoadEst-Werten ==

[[Datei:Msgloadest_2_2.png|mini|350px|rechts|Beispiel-Plot mit einer Auslastung von ca. 80%]]
Dazu muss im Einzelnen wie folgt vorgegangen werden:
* Um einen Plot erzeugen zu können, wird ein Log benötigt.
* Um ein Log erzeugen zu können, wird ein Event benötigt, das geloggt werden kann.
* Um das Event loggen zu können, wird ein [http://de.wikipedia.org/wiki/Cronjob CronJob] benötigt, der dieses Event wiederholt im Abstand x bereitstellt.

Der CronJob wird mittels "at" im Zeitabstand x= 1 Minute als Reading bereitgestellt, das den Wert von "msgLoadEst-1hour" erhält. Hierdurch werden 60 Werte pro Stunde in die Logdatei geschrieben. Sollte dies zu Performanceeinbußen auf Seiten des [[Systemübersicht#Server|Fhem-Trägersystems]] führen, kann der "+*00:01:00"-Wert entsprechend erhöht werden.

Erforderliche Definition in der [[Konfiguration]] (fhem.cfg):
<pre>
define a_hmlan_internals at +*00:01:00 {\
my $trafficStr = InternalVal("HMLAN1","msgLoadEst","???");;\
my $trafficHour = $1 if($trafficStr =~ m/1hour:(.*)% 10min steps/);;\
fhem("setreading HMLAN1 hmTrfHour ".$trafficHour." %" );;\
}
</pre>

Dadurch wird ein Event ausgelöst, das (z.B. mit den folgenden Definitionen) geloggt werden kann:
<pre>
define FileLog_Technik_IO FileLog %L/Technik_IO-%Y-%M.log global:.*|HMLAN1:cond:.*|HMLAN1:hmTrfHour:.*
attr FileLog_Technik_IO logtype text
attr FileLog_Technik_IO room Log
</pre>

Die graphische Darstellung (Plot) wird durch die Definition
<pre>
define SVG_FileLog_Technik_IO_1 SVG FileLog_Technik_IO:SVG_FileLog_Technik_IO_1:CURRENT
attr SVG_FileLog_Technik_IO_1 alias 10. hmlan attr SVG_FileLog_Technik_IO_1 label "traffic: min [$data{min1}] - avg [$data{avg1}] - max [$data{max1}] - last [$data{currval1}] ----- [".localtime()."]"
attr SVG_FileLog_Technik_IO_1 room 90_Technik
</pre>

... in Verbindung mit folgenden [[Plots erzeugen|Plot]]-Anweisungen (im vorgestellten Beispiel in der SVG_FileLog_Technik_IO_1.gplot Datei) erzeugt:
<pre>
# Created by FHEM/98_SVG.pm, 2014-03-22 12:11:58 set terminal png transparent size <SIZE> crop set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics "init" 6,"err" 4,"wng" 3,"?" 1,"ok" 0 set y2tics set grid y2tics set ylabel "condition"
set y2label "msgLoadEst % / hr"
set yrange [0:7]

#FileLog 4:HMLAN1.hmTrfHour\x3a::
#FileLog 4:HMLAN1.cond\x3a::$fld[3]=~"init"?6:$fld[3]=~"ERROR-Overload"?4:$fld[3]=~"Warning-HighLoad"?3:$fld[3]=~"ok"?0:1
#FileLog 3:global.*::$fld[2]=~"SHUTDOWN"?6:$fld[2]=~"INITIALIZED"?0:0

plot "<IN>" using 1:2 axes x1y2 title 'msgLoadEst' ls l6fill lw 1 with steps,\
"<IN>" using 1:2 axes x1y1 title 'condition' ls l0 lw 1 with steps,\
"<IN>" using 1:2 axes x1y1 title 'shutdown' ls l2fill lw 1 with steps
</pre>

== Links ==
* Beitrag / Diskussion zu diesem Thema im [http://forum.fhem.de/index.php/topic,21678.msg151772.html#msg151772 Fhem Forum]

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Pushover

2014-08-12T19:46:28Z

Kamischi:

{{Infobox Modul
|ModPurpose=Senden von sogenannten Push-Nachrichten auf Tablets oder Smartphones
|ModType=d


|ModTechName=70_Pushover.pm
|ModOwner=Johannes B
}}

[[Pushover]] ist ein Dienst, mit dem es möglich ist, sogenannte "Push" Nachrichten auf ein Apple oder Android Gerät zu schicken (Link zum Dienst: [https://pushover.net pushover.net]).
Der Dienst in grundlegend kostenlos. Um die Pushnachrichten zu empfangen muss die dazu passende App installiert werden, die leider nicht kostenlos ist.
Es fallen keinen Abo gebühren an. (Stand 28.6.2014)

== Installation ==
Es muss zwingend eine Pushover Account erstellen werden. Ist der Account angelegt muss auch auf der Pushover Website eine Application angelegt werden.
Die Application dient dazu die Nachrichten FHEM zuzuweisen und sie leichter erkennbar zu machen. (hier bekommt man dann den Token)
Auf dem Endgerät muss die Applikation "pushover" installiert werden. Dies geschieht z.B. bei Apple-Geräten mit Hilfe des AppStores. Momentan kostet diese Anwendung im AppStore 4,49€.
Danach müssen (nach erfolgter Registrierung auf der Webseite) die einzelnen Geräte, auf denen Nachrichten gesendet werden sollen, registriert werden.
Die Registrierung der Geräte erfolgt nach anmelden in der App auf dem Endgerät automatisch.

* Apple Geräte: [https://itunes.apple.com/de/app/pushover-notifications/id506088175?mt=8 Pushover App im Apple Store]
* Android Geräte: [https://play.google.com/store/apps/details?id=net.superblock.pushover&hl=de Pushover App im Google Playstore]

'''Wichtig für Debian Nutzer'''
Für das Modul ist noch eine Library notwendig:
<pre>sudo apt-get install libio-socket-ssl-perl</pre>

== Einbinden des Dienstes in Fhem ==
Das Modul wird mit dem folgenden Befehl in fhem definiert:
:<code>define pushmsg Pushover <TOKEN> <USER></code>

Die Tokens werden von der Pushover Seite entnommen.
TOKEN = Api Token / Key (zu finden unter der angelegten App)
USER = Your User Key (wird direkt nach dem Einloggen benötigtet)

== Senden eine Nachricht mit Fhem ==
Syntax:
<pre>You can send messages via the following command:
# set <Pushover_device> msg <title> <msg> <device> <priority> <sound> [<retry> <expire>]
</pre>

Beispiel:
:<code>fhem("set pushmsg msg 'fhem' 'Das Fenster wurde geschlossen!' '' 0 ''");</code>

Nachricht, sobald Fhem neu geladen wurde, mit Hilfe eines "notify":
:<code>define notify_fhem_reload notify global:INITIALIZED set pushmsg msg 'fhem' 'Ich wurde neu geladen! - $EVENT' '' 0 '' </code>

== Erinnerungsfunktion mit Hilfe des Kalendermoduls ==
Zuerst wird eine Textdatei mit den Daten für die Erinnerung im Fhem Hauptverzeichnis erzeugt. Hier das Beispiel für den Fall, dass Fhem auf einer Fritzbox läuft:

<pre>
telnet fritz.box
cd /var/media/ftp/fhem/opt/fhem/FHEM/
vi events.holiday

# ESC-i drücken um in den vi-Editmodus zu gelangen

# Format fur einzelne Tage: 1 MM-DD <Text>
1 03-23 Schwarze Tonne rausstellen
1 03-24 Gelbe Tonne rausstellen

# mit ESC:wq die Datei speichern
</pre>
[[Datei:Define_events_holiday.png|mini|400px|rechts|Details des definierten Kalenders]]
In Fhem muss der Kalender folgendermaßen definiert werden:
:<code>define events holiday</code>

Das im Bild gezeigte ''Device'' sollte erscheinen.

Der Befehl für die Zeitsteuerung wird mit dem folgenden '''at''' definiert (dieser Befehl muss ohne Zeilenumbrüche in die [[Konfiguration]] übernommen werden, vorzugsweise durch Eingabe in das Befehlsfeld):
:<code>define CheckEventToday at *20:15:00 {my $Eventname;;my $EventHeute;;$EventHeute=fhem("get events today");;print $EventHeute;;if ($EventHeute ne "none"){ $Eventname="Ereignis: $EventHeute";;fhem("set pushmsg msg 'fhem' 'Erinnerung an: $Eventname' '' 0 ''");;}}</code>

== Links ==
* Fhem Commandref [http://fhem.de/commandref_DE.html#Pushover Pushover]
* Thread über das Modul im [http://forum.fhem.de/index.php/topic,16215.0.html Fhem Forum]
* Pushover API [https://pushover.net/api https://pushover.net/api]

[[Kategorie:Code Snippets]]

Z-Wave

2014-08-12T19:46:11Z

Kamischi:

[[Z-Wave]] ist ein drahtloser Kommunikations-Standard, der von der Firma Sigma Designs und der Z-Wave Alliance für die Heimautomatisierung entwickelt wurde (Quelle: [http://de.wikipedia.org/wiki/Z-Wave Wikipedia]).



Auf dieser Seite wird das Einrichten eines '''Z-Wave''' Systems in FHEM beschrieben.
== Konfiguration ==
=== Einrichten eines Z-Wave USB Sticks ===
Das Einrichten eines Z-Wave USB Sticks teilt sich in 2 Schritte.
* Laden des Kernelmoduls
* Definieren des USB Sticks
==== Laden des Kernelmoduls ====
Zuerst muss sichergestellt werden, dass das entsprechende Kernelmodul <code>cp2101.ko</code> geladen wird.
Diese Datei ist bei einer [[FHEM und FritzBox 7390]] Installation über das Image von [http://www.fhem.de fhem.de] bereits enthalten.
Um den Z-Wave USB Stick zu verwenden muss dieses Kernelmodul vor oder beim Starten des FHEM Servers geladen sein. Dies erreicht man durch einen Eintrag in der Datei <code>startfhem</code>.

Die entsprechende Zeile kann direkt unterhalb der modprobe Anweisungen eingefügt werden.
<pre>insmod $home/lib/cp2101.ko</pre>
==== Definieren des USB Sticks ====
Nach einem FHEM Neustart wird der USB Stick nun erkannt.
Falls der USB Stick nicht automatisch in der <code>fhem.cfg</code> hinzugefügt wurde, ist die Log-Datei zu durchsuchen. Sie enthält den entsprechenden Eintrag, der in der <code>fhem.cfg</code> hinzugefügt werden muss.

Ein '''Aeon Labs Z-Stick''' wird an der Fritzbox wie folgend definiert:
<pre>define zwaveStick ZWDongle /dev/ttyUSB0@115200</pre>
==== Informationen zu dem USB Stick auslesen ====
Zum Definieren von Z-Wave Aktoren und Sensoren ist die <code>homeId</code> notwendig.

Die <code>homeId</code> des USB Sticks kann man mit folgendem Befehl auslesen:
<pre>get zwaveStick homeId</pre>
Die aktuelle Liste der Z-Wave Knoten, die bereits an dem Stick registriert sind, kann mit dem folgendem Befehl ausgelesen werden:
<pre>get zwaveStick nodeList</pre>
=== Hinzufügen eines neuen Z-Wave Geräts ===
Zuerst wird der Z-Wave Stick in den Modus zum Aufnehmen neuer Geräte gesetzt:
<pre>set zwaveStick addNode on</pre>
Danach wird das Gerät in den Aufnahmemodus versetzt. dies geschieht zumeist durch dreimaliges Drücken einer Taste am Gerät.

Abschließend wird der Z-Wave Stick wieder in den Normalmodus versetzt:
<pre>set zwaveStick addNode off</pre>
=== Erneutes Hinzufügen eines bereits registrierten Z-Wave Geräts ===
Es können die bereits an dem Z-Wave Stick registrierten Geräte abgerufen werden:
<pre>get zwaveStick nodeList</pre>
Es werden die verschiedenen IDs zurückgeliefert, wobei 1 der Z-Wave Stick selbst ist.

Mit dem folgenden Befehl wird das bereits registrierte Gerät mit der ID 2 eingerichtet:
<pre>set zwaveStick createNode 2</pre>

== Glossar ==
=== Was ist eine Association? ===
Devices die die Association unterstützen sind in der Lage, direkt mit anderen Devices zu kommunizieren. Dies können zum einen direkte Befehle sein, als auch Meldungen über den Status und Zustand der Devices.

Zum Beispiel kann damit ein Bewegungsmelder bei entdeckter Bewegung direkt eine Lampe ein oder ausschalten oder die aktuelle Temperatur an den Controller senden.

Devices können mehrere Association Groups haben, die für vom Hersteller vorgesehene unterschiedliche Aktionen definiert sind. Welche das sind, geht aus der jeweiligen Beschreibung hervor.

Damit FHEM auf Statusmeldungen von Sensoren reagieren (und auch Anzeigen) kann, muss der Controller (ZW_Dongle, DeviceID = 1) mit dem jeweiligen Device assoziiert werden.

<pre>set associationAdd <associationGroup> <deviceID></pre>

Nahezu alle in Europa erhältlichen Devices unterstützen die Rückmeldung des Status via Association. Daher ist diese Konfiguration in der Regel Pflicht, um ein Device sinnvoll mit FHEM nutzen zu können.

Ausnahmen gibt es in Nordamerika, wo aufgrund von Patentansprüchen einige Hersteller auf die Statusrückmeldungen verzichten. Diese Geräte unterstützen in der Regel die Command Class ASSOCIATION nicht.

== Tipps und Tricks ==
=== Batterie betriebene Geräte ===
Um die Batterielaufzeit zu erhöhen, legen sich batteriebetriebene Geräte „schlafen“ und wachen in konfigurierbaren Intervallen auf um einen "wakeup Report" zu senden. Daraufhin senden andere Devices ihre bis daher gesammelten Anfragen, die daraufhin beantwortet werden.

Dies wird in FHEM wie folgt konfiguriert.
<pre>set wakeupInterval <time> <nodeId></pre>
<time> ist die Zeit in Sekunden zwischen den Intervallen und <nodeID> der gewünschte Empfänger des wakupReports. In der Regel ist dies wieder der Controller (NodeId=1). Viele Geräte kommen im Auslieferungszustand mit der NodeID 255 (der wakeup report wird als Broadcast an alle erreichbaren Devices gesendet). Hier empfiehlt es sich die Konfiguration auf nodeID 1 zu ändern, da dies robuster ist und zusätzlich noch Batterielaufzeit spart.

== Geräte Spezifika ==
=== Fibaro ===
Bei den bisher erschienenen Devices Devices wird die Association Group 3 für die Übermittlung von Sensor Werten verwendet.
<pre>set associationAdd 3 1</pre>

==== FGSS-001 ====
Dieser Rauchmelder scheint einen Falschen Batterie Level (0%) zu senden wenn er Außerhalb des wakeup intervals abgefragt wird.

Workaround: Den Batterie Level nicht direkt via get anfordern sondern per notify auf den wakeup Report anfordern.
===== FGK-101 =====
Der Tür/Fensterkontakt sendet Änderungen am Zustand nur als basicReport (ff oder 00). Der Status (open / closed) wird nur nach explizitem GET gemeldet.

=== GE ===
==== GE (Model t.b.d) ====
Dieser Schalter unterstützt keine Statusrückmeldungen.

[[Kategorie:HOWTOS]]
[[Kategorie:Transceiver]]

JSONMETER

2014-08-12T19:44:48Z

Kamischi:

Dieses FHEM-Modul liest Daten von Messgeräten (z.B. Stromzähler, Gaszähler oder Wärmezähler, so genannte Smartmeter),
die OBIS kompatible Daten im JSON-Format auf einem Webserver oder auf dem FHEM-Dateisystem zur Verfügung stellen.

Das Modul liest derzeit die Werte folgender Smartmeter mit LAN Anschluss
*ITF Eintarifzähler von N-ENERGY Netz GmbH (ITF Fröschl)
*EFR Smart Grid Hub für Stromzähler von EON, N-ENERGY, EnBW
*YouLess LS110 - Netzwerkfähiger Sensor für elektromechanische Stromzähler

== Hinweise zum Betrieb mit FHEM ==
Definition in fhem.cfg:

<nowiki>define <name> JSONMETER <Gerätetyp> [<IP-Adresse>] [Abfrageinterval]</nowiki>

[http://www.fhem.de/commandref_DE.html#JSONMETER Link auf FHEM commandref]

[[Kategorie:Energieverbrauchsmessung]]
[[Kategorie:Energieerzeugungsmessung]]

Luxtronik 2.0

2014-08-12T19:44:27Z

Kamischi:

Die Luxtronik 2.0 ist eine Heizungssteuerung, die in Wärmepumpen von Alpha Innotec, Siemens Novelan (WPR NET) und Wolf Heiztechnik (BWL/BWS) verbaut ist.
Sie besitzt einen Ethernet Anschluss, so dass sie direkt in lokale Netzwerke (LAN) integriert werden kann.
== Hinweise zum Betrieb mit FHEM ==
Definition in fhem.cfg:

<nowiki>define <name> LUXTRONIK2 <IP-Adresse> [Abfrageinterval]</nowiki>

[http://www.fhem.de/commandref_DE.html#LUXTRONIK2 Link auf FHEM commandref]

=== Zusätzliche Perl-Module ===
Das FHEM-Modul benutzt das CPAN-Modul "net::Telnet". Dieses ist standardmäßig auf Fritz!Boxen installiert. Auf anderen Servern muss es eventuell nachinstalliert werden. Unter Debian z.B. mit
sudo apt-get install libnet-telnet-perl

== Erläuterung der Readings ==
===Allgemeine Wärmepumpenwerte===
* '''ambientTemperature''' - Temperatur des Außensensors in °C
* '''averageAmbientTemperature''' - Gemittelte Außentemperatur der letzten 24 h in °C (für Heizgrenze im Sommer)
* '''heatSourceIN''' - Wärmequelle Eingangstemperatur in °C
* '''heatSourceOUT''' - Wärmequelle Ausgangstemperatur in °C
* '''hotGasTemperature''' - Heißgastemperatur in °C, Temperatur, die hinter dem Kompressor der Wärmepumpe anfällt
* '''flowTemperature''' - Vorlauftemperatur (Rücklauf plus Spreizung) in °C
* '''returnTemperature''' - Rücklauftemperatur in °C
* '''flowRate''' - Durchfluss in l/h
* '''thermalPower''' - aktuelle Heizleistung (berechnet) in kW
* '''COP''' - Coefficient Of Performance, Wirkungsgrad der Wärmepumpe (Leistungszahl ε). Eine Leistungszahl von z.B. 4,2 bedeutet, dass von der eingesetzten elektrischen Leistung des Kompressors das 4,2- fache an Wärmeleistung bereitgestellt wird. Anders formuliert, kann mit dieser Wärmepumpe aus einem Kilowatt elektrischer Leistung 4,2 kW Wärmeleistung zur Verfügung gestellt werden. ''Bei der Berechnung des COPs wird die elektrische Leistung aus dem Attribut "heatPumpElectricalPowerWatt" benutzt.''
* '''deviceTimeCalc''' - Beim Abrufen der Gerätewerte wird von der Luxtronik-Steuerung auch der Zeitpunkt der internen Ermittlung übergeben.
* '''delayDeviceTimeCalc''' - Abweichung Gerätesystemzeit zur FHEM-Zeit. Dieser kann bis zu 2 s in der Vergangenheit liegen. Höhere Werte weisen auf eine ungenaue Systemzeit in der Steuerung hin.
* '''durationFetchReadings''' - Dauer (in s) des Abrufes der Gerätewerte von der Steuerung

=== Heizung ===
* '''returnTemperatureTarget''' - Rücklaufsolltemperatur (wird durch Heizkurve und Außensensor bestimmt, kann über in der Steuerung eingegebene Zeiten und auch manuell gezielt abgesenkt)
* '''heatingLimit''' - Heizgrenze wird ausgewertet (on, off)
* '''thresholdHeatingLimit''' - Heizgrenze in °C, '''über'''schreitet die gemittelte Außentemperatur diesen Wert, wird nicht mehr geheizt
* '''thresholdTemperatureSetBack''' - '''unter'''schreitet die Außentemperatur diesen Wert, wird die Heizungssolltemperatur nicht mehr abgesenkt

=== Warmwasserbereitung ===
* '''hotWaterTemperature''' - aktuelle Warmwasser-Boiler-Temperatur in °C (Achtung, die Temperatur im Boiler ist sehr unterschiedliche, es wird also nur die Temperatur am Sensor angezeigt. Typischerweise sackt die Temperaturkurve beim Aufheizen des Boilers etwas ab, weil es durch den Wärmeeintrag zu Strömungen kommt.)
* '''hotWaterTemperatureTarget''' - obere Solltemperatur des Boilers
=== Solarthermie ===
* solarBufferTemperature
* solarCollectorTemperature
=== Zähler ===
* '''counterHours2ndHeatSource1''' - Betriebsstunden der zweite Wärmequelle (normalerweise elektrische Heizstäbe)
* '''counterHoursHeatPump''' - Betriebsstunden des Wärmepumpenkompressors
* '''counterHoursHeating''' - Betriebsstunden des Wärmepumpenkompressors die zur Heizung benutzt wurden
* '''counterHoursHotWater''' - Betriebsstunden des Wärmepumpenkompressors die zur Warmwasserbereitung benutzt wurden
* '''counterHeatQHeating''' - von der Wärmepumpe produzierte Wärmemenge (kWh) zur Heizung (nur bei vorhandenem Wärmemengenzähler und ohne Wärmeeintrag durch zweite Wärmequelle wie z.B. Heizstäbe)
* '''counterHeatQHotWater''' - von der Wärmepumpe produzierte Wärmemenge (kWh) zur Warmwasserbereitung (nur bei vorhandenem Wärmemengenzähler und ohne Wärmeeintrag durch zweite Wärmequelle wie z.B. Heizstäbe)
* '''counterHeatQTotal''' - von der Wärmepumpe produzierte Wärmemenge (kWh) insgesam (nur bei vorhandenem Wärmemengenzähler und ohne Wärmeeintrag durch zweite Wärmequelle wie z.B. Heizstäbe)

=== Ein- und Ausgänge ===
* '''heatingSystemCircPump''' - Umlaufpumpe in der Wärmepumpe
* '''hotWaterCircPumpExtern''' - Zirkulationspumpe im Warmwasserstrang des Hauses (wenn genutzt)
* '''hotWaterSwitchingValve''' - Ventil zur Umschaltung auf die Heizspirale im Boiler

=== Sonstiges ===
* Firmware
* typeHeatpump

== Tipps zum ökonomischen Betrieb ==
=== Sperrzeiten ===
Die Luxtronik 2.0 erlaubt es, sich mit Hilfe von Sperrzeiten an zeitabhängige Strompreise anzupassen. Die Uhr der Steuerung geht jedoch sehr ungenau. Durch Setzen des Attributes "autoSynchClock" wird die Uhr der Steuerung regelmäßig mit der FHEM-Zeit abgeglichen. Die Funktion muss über das Attribut "allowSetParameter" freigegeben werden.
attr <device> allowSetParameter 1
attr <device> autoSynchClock 10
=== Warmwasserbereitung bei Luft-Wasser-Wärmepumpen ===
Die Kosten der Warmwasserbereitung durch Luft-Wasser-Wärmepumpen hängen von zwei Faktoren ab:
# den Energiekosten: Bei Zweitarifzählern ist der Strom im Nebentarif (z.B. Mo-Fr von 22:00 - 06:00, Sa ab 13:00 und den ganzen So) billiger als im Haupttarif.
# der Lufttemperatur: Die Heizleistung der Wärmepumpe steigt bei höherer Lufttemperatur trotz konstantem Stromverbrauchs. Die Außentemperatur erreicht ihr Maximum an einem sonnigen '''Durchschnittstag''' gegen 15:00 Uhr. Ihr Minimum hat sie kurz vor Sonnenaufgang.
Das FHEM Modul erlaubt es, durch zeitweises Anheben der Solltemperatur ein Aufheizen des Boilers auszulösen.
set <device> hotWaterTemperaturTarget 50
Es gilt nun den kostengünstigsten Zeitpunkt für diesen Vorgang zu bestimmen. Die nachfolgenden Ausführungen setzen voraus, dass Aufgrund der Boilerisolierung und der Boilergrösse nur ein- oder zweimal pro Tag aufgeheizt werden muss. Zur Vereinfachung wird die Abhängigkeit der Wärmeverluste von der Boilertemperatur vernachlässigt.

Bei den aktuellen Wärmepumpentarifen ist der Strom des Haupttarifes etwa 17 % teurer als der des Nebentarifes. Es liegt also nahe, den Boiler in der Woche zu Beginn des Nebentarifes gleich für die nächsten 24 h aufzuheizen, weil dann die Aussentemperatur höher ist und man dann am billigsten und effizientesten die entsprechende Wärme produziert.
# Sollwert 5 K über Standardwert setzen
define Boilertemperatur_hoch at *22:05:00 {\
if ($we != 1) { fhem ("set WP hotWaterTemperaturTarget 47");; }\
}
# Sollwert auf Standwert zurücksetzen
define Boilertemperatur_normal at *23:00:00 set WP hotWaterTemperaturTarget 42

==== Detailliertere Berücksichtigung der Temperaturabhängigkeit====

Damit die Warmwasserbereitung vor 6 Uhr nicht startet, muss die Warmwassertemperatur um 22 Uhr eigentlich nur ausreichend hoch über der Auslöseschwelle liegen. Bei einer Auslöseschwelle von 40 °C und einem Wärmeverlust (''statBoilerGradientCoolDownMin'') von 0,25 K/h sind dies z.B. 42 °C. Beträgt die Solltemperatur-Hysterese 2 K, so muss um 22 Uhr die Solltemperatur kurzzeitig auf 44 °C angehoben werden bzw. eigentlich nur 2 K oberhalb der aktueller Warmwassertemperatur.

Die obigen 47 °C machen zudem nur Sinn, wenn tagsüber die Effektivitätsverbesserung durch die höheren Außentemperaturen den höheren Strompreis nicht wieder ausgleicht. Zudem muss berücksichtigt werden, dass sich bei höherer Vorlauftemperatur auch die Leistungsaufnahme der Wärmepumpe und damit ihre Arbeitszahl ändert. Diese Veränderung beträgt üblicherweise 2 %/K. 
Geht man von einer durchschnittlichen Erhöhung der Vorlauftemperatur von 4 K aus, so erhält man dadurch eine Verschlechterung der Arbeitszahl um 8 %. Das heißt, die 17 % Preisunterschied müssen um den Effektivitätsverlust von 8 % korrigiert werden (1,17/1,08=1,08). In unserem Fall reicht also die Temperaturdifferenz aus, die zu einer 8 % höheren Heizleistung führt.

Die ungefähre, theoretische Temperaturabhängigkeit der Heizleistung erhält man am schnellsten aus den Grafiken der Betriebsanleitung der Wärmepumpe. Empirisch und genauer lassen sich die Wert durch Loggen der Werte ''thermalPower'' oder besser ''statThermalPowerBoiler'' bestimmen. Liest man die Log-Datei in ein Tabellenkalkulationsprogramm (MS Excel, OO Calc), kann man mit diesem auch gleich eine Regressionsgrade berechnen. Auf diesem Wege erhält man für jede Temperaturdifferenz die prozentuale Änderung der Heizleistung. Nehmen wir an, sie beträgt für 8 % 4 K.

Über das [http://www.fhem.de/commandref_DE.html#Weather Wettermodul] von FHEM kann man nun Mo-Fr um 22:00 die aktuelle Aussentemperatur ''ambientTemperature'' mit der maximalen Aussentemperatur des nächsten Tages vergleichen. Rechnen wir noch eine Sicherheit von 2 K hinzu, dann kann man z.B. festlegen, dass ab 5 K Temperaturunterschied und jeden Samstag der Boiler nur noch so weit aufgeheizt wird, dass er bis 06:00 nicht mehr auslöst.
define Boilertemperatur_hoch at *22:05:00 {\
my $delta = ReadingsVal("Wetter","fc2_high_c",0) - ReadingsVal("Heizung","ambientTemperature",0);;\
if ($delta >=5.0 || $wday == 6) {}
my $newTemp = int(ReadingsVal("Heizung","hotWaterTemperature",42)*2+5)/2;;\
if ($newTemp<42.0) {$newTemp = 42;;}\
if ($newTemp>44.0) {$newTemp = 44;;}\
fhem( "set Heizung hotWaterTemperatureTarget $newTemp" );;\
}\
else { fhem( "set Heizung hotWaterTemperatureTarget 47" );; }\
}

Mit Hilfe der Sperrzeitensteuerung der Luxtronik 2.0 kann man die nächste, zweite Aufheizung dann erst wieder um 15:00 erlauben, da dann Aufgrund der hohen Aussentemperaturen der Strompreisunterschied mehr als ausgeglichen wird. Natürlich kann das Aufheizen auch hier durch ein gezieltes Anheben der Solltemperatur erreicht werden (z.B. am Wochenende).
define Boilertemperatur_WE_Hoch at *15:00:00 {\
if ($we == 1) {fhem( "set Heizung hotWaterTemperatureTarget 47" );; }\
}
define Boilertemperatur_WE_Normal at *16:00:00 {\
if ( ReadingsVal("Heizung","hotWaterTemperatureTarget", 42 ) != 42.0 ) {fhem ("set Heizung hotWaterTemperatureTarget 42");;}\
}

===Frostschutz bei Erreichen der Heizungsgrenze===
Wenn die mittlere Temperatur "averageAmbientTemperature" die Heizgrenze "thresholdHeatingLimit" überschreitet, so schaltet die Anlage in den Sommermodus, indem sie die Rücklaufsolltemperatur "returnTemperatureTarget" auf 15 °C absenkt.

Allerding gibt es ein undokumentiertes Anheben der Rücklaufsolltemperatur auf 20 °C, sobald die Außentemperatur "ambientTemperature" 10 °C unterschreitet. Ob es bei eine abgekühlten Haus (z.B. wegen Urlaub oder Nachts) dann auch zum ungewollten Heizen kommen kann, ist noch nicht geklärt.

==Abschätzung des elektrischen Verbrauches==
Über die Attribute "heatPumpElectricalPowerWatt", "heatPumpElectricalPowerFactor" und "heatRodElectricalPowerWatt" wird der elektrische Verbrauch während der Wärmeerzeugungen (Kompressormotor, Motor(en) der Wärmequelle) und der Heizstäbe festgelegt. Ist zudem das Attribute "doStatistics" auf 1 und der Werte "activeTariff" auf einen Wert zwischen 1 und 9 gesetzt, so berechnet das Modul anhand der Betriebsstunden automatisch den elektrischen Verbrauch innerhalb des angegebenen Stromtarifes.

Normalerweise wird eine Wärmepumpe mit einem zeitabhängigen Stromtarif betrieben (Doppeltarifzähler). Hierbei muss der Werte "activeTariff" zum jeweiligen Zeitpunkt über ein FHEM-Script gesetzt werden.
Beispiel:
define Strom_HT_W at *06:00 { if ( $wday != 0 ) {fhem( "set Heizung activeTariff 1" );;} }
define Strom_NT_W at *22:00 set Heizung activeTariff 2
define Strom_NT_Sa at *13:00 { if ( $wday == 6 ) {fhem( "set Heizung activeTariff 2" );;} }

[[Kategorie:Other Components]]
[[Kategorie:Heizungssteuerung]]

HMinfo

2014-08-12T19:44:11Z

Kamischi:

'''HMInfo''' ist ein Modul, das alle [[HomeMatic]] repräsentiert. Es bietet Funktionen zur Übersicht, Kontrolle, Archivierung und, begrenzt, zur Programmierung der Homematic Komponenten. Somit soll es eine Hilfestellung bei Konfiguration und Fehlerbehandlung geben.

== Definition ==
HMInfo wird erstellt / angelegt mit dem Befehl
:<code>define hm HMinfo</code>

Danach können alle Funktionen aufgelistet werden mit
:<code>get hm help</code>

== Integritätsprüfungen ==
Befehle, um die Gültigkeit von verschiedenen HomeMatic Eigenschaften zu überprüfen:
{| class="wikitable"
! Erläuterungen !! Definition
|-
| Überprüfen, ob alle peerings auch beidseitig sind:
| <code>set hm peerCheck</code>
|-
| Überprüfen, ob alle register korrekt gelesen wurden:
| <code>set hm regCheck</code>
|-
| Kombination von peerCheck und regCheck
| <code>set hm configCheck</code>
|}

== Anzeigen zur Übertragungssituation ==
===RSSI ===
;<code>get hm rssi [<filter>]</code>
:Erzeugt eine Tabelle aller RSSI Werte.
;<code>set hm clear [<filter>] rssi</code>
:setzt die RSSI Werte aller devices gemäß filter zurück. Eine neue Messung kann beginnen

===protoEvents ===
;<code>get hm protoEvents [<filter>][short|long] </code>
:Es wird eine Tabelle mit allen wichtigen Ereignissen zur Datenübertragung erzeugt. Dies beinhaltet Wiederholungen sowie Übertragungsfehler.
short ist eine Fassung ohne Zeitstempel und lässt sich besser am Bildschirm darstellen.
Ausserdem kann man sehen, welche Abfragen noch in der queue sind, z.B. durch autoReadReg erzeugt.
Die Zustände aller für HM zuständigen IOs sind beinhaltet.
Alles in allen ist hier ein kompletter Überblick zur Kommunikation zu sehen. Insbesondere bei
:<code>set hm clear [<filter>] Protocol </code>
setzt die Protokol Einträge aller gemäß Filter zurück. Kann gut vor einer Konfigurationsaktion genutzt werden, um hinterher zu kontrollieren, ob Fehler aufgetreten sind.

===msgStat===
;<code>set hm msgStat </code>
:Statistic der Übertragenen Messages insgesamt. Es gibt eine Tabelle über die letzten 24h und eine über die letzte Woche.

== Speichern von Konfigurationen==
HMInfo speichert Konfigurationen der Geräte in Files. Mit dem Attribut configDir kann man ein Verzeichnis festlegen, in das alles geschrieben wird.

=== saveConfig===
Peers und Register werden in eine Datei geschrieben. Die Daten kann man ggf. wieder in ein Gerät oder ein Austauschgerät schreiben. Die Speicherung erfolgt kumulativ, man kann alles in eine Datei schreiben.
:<code>set hm saveConfig [<filter>] [<file>] </code>

=== archConfig ===
Arbeitet prinzipiell wie saveConfig. Es werden jedoch nur vollständige Registersätze gespeichert, was einen höheren Level an Sicherheit der Dateninhalte gewährt.
:<code>set hm archConfig [-a] [<file>] </code>
Mit dem '''Attribut autoArchive''' kann man einstellen, dass automatisch nach erfolgreichem Lesen einer Device-Konfiguration diese archiviert wird.
Das Speichern erfolgt kumulativ. Ab einer Dateigröße von 1MB wird gepurged, also alles bis auf den neusten Eintrag jeder Entity gelöscht.

Um eine Konfiguration zu sichern, sollte eine Kopie des Archivs gemacht werden. Das Archiv wird bei Gelegenheit überschrieben.

Template erstellen:
:<code>set hm saveConfig -f ^meinDevice$ <myTempalteFile> </code>

=== loadConfig ===
;<code>set hm loadConfig [<filter>] [<filename>] </code>
:Liest die Registerwerte, die für eine Entity in einem File gespeichert sind, zurück in die Readings. Sollten die Register schon in FHEM vorhanden sein, wird '''nicht''' überschrieben.
Sinn macht dies beispielsweise für remotes, die nicht automatisch gelesen werden sollen. Man kann somit nach einem system-reboot die Register "rekonstruieren" und wieder darstellen.
Es liegt im ermessen des User, eine bekannt aktuelle Version der Register einzulesen.

=== purgeConfig===
;<code>set hm purgeConfig [<filename>] </code>
:Löscht alle älteren Datensätze in einem File.

== Konfigurationen bearbeiten ==
=== Templates ===
HMInfo erlaubt das Erstellen und Nutzen von Templates. Das sind Schablonen, die das Setzen von Registern abstrahieren und auf eine höhere Ebene heben. So kann man das Setzen der Konfiguration eines Aktors beispielsweise um mit einem Bewegungsmelder zusammen zu arbeiten in einem Kommando zusammenfassen.
Faktisch setzt das Template also eine Gruppe von Registern auf einmal.

====templateList ====
Die vorhandenen templates kann man mit templateList sehen.
get hm templateList

SwOnCond params:level cond Info:switch: execute only if condition [geLo|ltLo] level is below limit
SwToggle params: Info:Switch: toggle on trigger
autoOff params:time Info:staircase - auto off after <time>, extend time with each trigger
motionOnDim params:ontime brightness Info:Dimmer: on for time if MDIR-brightness below level
motionOnSw params:ontime brightness Info:Switch: on for time if MDIR-brightness below level
Die Liste der verfügbaren Tempaltes, deren Parameter falls nötig und eine kurze Info, was das Template bewirken soll

get hm templateList autoOff

autoOff params:time Info:staircase - auto off after <time>, extend time with each trigger
ActionType :jmpToTarget
OffTime :111600
OnTime :time
SwJtDlyOff :dlyOn
SwJtDlyOn :no
SwJtOff :dlyOn
SwJtOn :on
Ein templateList auf ein einzelnes Template zeigt im Detail, was das Template verändern wird.

====templateSet ====
Um ein Template auf einen Aktor anzuwenden, muss man neben den spezifischen Parametern angeben, für welchen Peer es gelten soll und ob es bei einem kurzen oder langen Tastendruck angewendet werden soll.
set hm templateSet <entity> <templateName> <peer:[long|short]> [<param1> ...]
set hm templateSet Licht1 autoOff FB1_Btn2:short 10
set hm templateSet Licht1 SwOn FB1_Btn2:long
Licht1 soll, wenn ein kurzer Trigger von FB1_Btn2 kommt für 10 sec eingeschaltet werden, dann ausgehen (Treppenhausfunktion). Kommt aber ein langer Tastendruck wird das Licht dauerhaft eingeschaltet.
set hm templateSet Licht1 motionOnSw MD1:short 30 20
Der Switch Aktor Licht1 soll mit einem Bewegungsmelder betrieben werden. Der Bewegungsmelder sendet keine 'langen' Trigger sondern nur kurze. Im Beispiel wird Licht1 für 30 Sekunden eingeschaltet, wenn der Bewegungsmelder einen Trigger sendet UND es dunkler ist als "20" (Brightness level).

====templateDef ====
Neben den vorbereiteten Templates kann der User eigene definieren oder von anderen Usern sich Templates geben lassen. Die Definition von Templates ist für erfahrene User gedacht, im Gegensatz zur Nutzung eines Templates mit set - das ist für Anfänger gedacht.
set hm templateDef <templateName> <param1[:<param2>...] <description> <reg1>:<val1> [<reg2>:<val2>] ...
set hm templateDef myTemplate anzeit:auszeit "licht schaltet ständig an und aus" OnTime:anzeit OffTime:auszeit OnDly:0
Mit diesem Template wird die Anzeit und die Auszeit eines Schalt-Aktors auf den vom User gewünschten Wert gesetzt. Die Verzögerung OnDly wird auf 0 gesetzt.

====templateChk ====
Man kann prüfen, ob ein Aktor/Peer gemäss einem Template programmiert ist.
get hm templateChk [<filter>] <templateName> <peer:[long|short]> [<param1> ...]
get hm templateChk -f Rollo RolloHoch self01 5
Es wird geprüft für alle HM-Komponenten, die "Rollo" im Namen haben (siehe [[Homematic HMInfo#Filter|Filter]]) dem (hoffentlich vorhandenen) template "RolloHoch" verglichen. Geprüft wird nur der Peer "self01", aber für long UND short.
get hm templateChk -f Rollo RolloHoch self01:sort 5
das selbe, nur für short Einträge

===Temperaturlisten===
HMInfo bietet verschiedene Methoden, Temperaturlisten für Thermostate (CC-TC, TC-IT oder RT) zu verwalten und zu nutzen. Prinzip ist, dass die Temperaturlisten in einer Konfigurationsdatei abgelegt werden. Der Dateiname ist frei wählbar.
Für alle Kommandos können die [[Homematic HMInfo#Filter|Filter]] genutzt werden.
Beim Prüfen und Speichern wird davon ausgegangen, dass die Register und Daten in FHEM aktuell sind. Die Funktionen speichern und vergleichen aus Performancegründen nicht direkt im Device sondern die Daten, die FHEM schon gelesen hat.
Siehe auch '''autoReadReg''' Attribut der HM Komponenten.

====Speichern ====
;<code>set hm tempList save <filename> <code>
:Die in FHEM vorhandenen Temperaturlisten aller devices (hier ist kein Filter gesetzt, also alle) werden in die Datei <filename> geschrieben. Man kann dieses als Basis nehmen, um seine Temperaturlisten zu bearbeiten.
====Prüfen====
;<code>set hm tempList verify <filename> </code>
:HMInfo vergleicht die in der Datei abgelegten Temperaturlisten mit den in FHEM vorliegenden. Unterschiede werden gemeldet. Es wird nichts in das Device geschrieben oder verändert.

====Restore====
;<code>set hm tempList restore <filename> </code>
:Es werden alle Temperaturlisten aus der Datei in die dafür eingerichteten Komponenten eingetragen. Dabei werden ausschließlich die Änderungen geschrieben. Liegen keine Unterschiede zwischen Dateiinhalt und aktuellen Daten vor, wird auch nichts geschrieben. Ein mehrfaches anwenden des Kommandos ist also keine Belastung des Systems.
Will man das '''Schreiben''' ungeachtet der vorhandenen Daten '''erzwingen''' sollte man mit "clear Register" die in FHEM vorhandenen Einträge löschen und dann ein tempList restore ausführen.

====Defaults====
Der Default-Dateiname ist '''tempList.cfg'''.
Die Datei steht im fhem-root Verzeichnis. Hat man das Attribut configDir gesetzt und gibt kein Verzeichnis an, wird die Datei im spezifizierten Verzeichnis gesucht.
Das default-template ist der Name des Device. Ist im Device das '''Attribut tempListTmpl''' gesetzt, wird dies zum Vergleich oder Setzen genutzt.

====Aufbau Tempfile====
Zum erstmaligen Erstellen einer Datei nutzt man am einfachsten das Kommando tempList save.

entities:HK1,HK2
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0
entities:HK3
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0

Die Zeile '''entities''' legt fest, für welche Komponenten die nachfolgende Liste gültig sein soll. Die Erste ist also gültig für HK1 und HK2, die Zweite für HK3.
Will man identische Listen für mehrere Komponenten nutzen, schreibt man deren Namen einfach in die Liste der Entities.
Zu Beachten ist, dass nach Ändern der Liste ein erneutes templistSave auf den gleichen Dateinamen die Daten verändern kann. Es ist daher ratsam, den Dateinamen einer manuell bearbeiteten Konfiguration nicht beim Default zu belassen.

====tempList Templates====
User möchten möglicherweise die Temperaturlisten einer Komponente über das Jahr verändern (Sommer- und Winterprofil). Dazu kann man Templates festlegen. Das ganze funktioniert wie das Kommando tempList mit dem Unterschied, dass der Namen des Templates angegeben werden kann.

In der Datei wird der Name des Templates in der Zeile Entities eingegeben, identisch wir(?) der Name einer Komponente.
:<code>set hm tempListTmpl -f hkWZ wzSommer restore tempListFile.cfg <code>
Alle Thermostate mit hkWZ im Namen wird die Templiste, die im File tempListFile.cfg unter entity "wzSommer" abgelegt ist überschrieben. Wie bei tempList restore wird auch hier nur geschrieben, wenn ein Unterschied erkannt wird.

=== Registersätze kopieren ===
HMInfo erlaubt das Kopieren von Register-Listen. Über Register wird ein HM-Gerät eingestellt und die Register sind in Listen gruppiert. Die Reaktion und das Verhalten eines Aktors auf einen Trigger eines Sensors wird in dem Registersatz zu diesem Peer komplett beschrieben.
Durch die Möglichkeit einen solchen Registersatz im Device zu kopieren kann man das Verhalten, das man für einen Knopf/Sensor festgelegt hat identisch in einen zweiten kopieren.
HMInfo geht davon aus, dass die vom Gerät gelesene Konfiguration vor dem Kommando aktuell und komplett ist.
set hm cpRegs Licht1:FB3_Btn2 Licht3:FB1_Btn4
set hm cpRegs Licht2:FB3_Btn2 Licht2:FB1_Btn4
set hm cpRegs Licht4:FB3_Btn2 Licht4:FB5_Btn2
Die obigen Beispiele bewirken der Reihe nach:
Duplizieren das Verhalten, das Fernbedienungsknopf 2 der Fernbedienung 3 bei Aktor Licht1 hervorruft auch nach Licht3 für Fernbedienungsknopf4 der Fernbedienung 1.
Duplizieren das Verhalten, das Fernbedienungsknopf 2 der Fernbedienung 3 bei Aktor Licht2 hervorruft auch nach Licht2 (selber Aktor) für Fernbedienungsknopf4 der Fernbedienung 1.

== Web Einträge und Readings ==
Readings und Internals von HMInfo bieten eine Zusammenfassung des Zustands aller HM Komponenten. Diese sind in Fehler '''ERR' , Warnungen '''W_''' und Information '''I_''' untergliedert. Die Prüfung und Erneuerung der Zähler und Werte wird mit:
:<code>set hm update </code>
erreicht. Mit dem Attribut autoUpdate kann man es automatisch regelmäßig starten.

=== Fehlermeldungen ===
Als Fehler erkannte Zustände werden in Variablen beginnend mit '''ERR''' dargestellt. Erfasste Fehler sind kritische RSSI Werte und Protokoll-/Übertragungsfehler. Ausserdem kann man im Attribut sumERROR eintragen, welche Readings zu einer Fehlermeldung führen sollen. Eingetragen werden:
Reading:<gutwert>. Wenn ein Reading mit einen anderen als dem "gutwert" gefunden wird, wird dies alarmiert.
Beispiel:
:<code>battery:ok </code>
hat eine HM Komponente ein Reading "battery" und dieses hat einen anderen Wert als "ok" wird dies alarmiert.
In den Readings von HMInfo würde im Feherfall
internal:
ERR_names <devicename1>,<devicename2>
Readings:
ERR_battery low:2

Der default aller Error-meldungen ist
battery:ok,sabotageError:off,powerError:ok,overload:off,overheat:off,reduced:off,motorError:no,error:none,uncertain:yes,smoke_detect:none,cover:closed

Diese Zusammenfassung der Fehlermeldungen könnte man nutzen, um über notify einen Alarm auszulösen oder eine E-Mail zu senden.

=== Warnungen===
Hierzu gehören Wiederholungen von Nachrichten (nicht aber Abbrüche, das sind Fehler). Es wird auch ausstehendes Lesen der Konfiguration, das durch autoReadReg getriggert wird, hier angezeigt.

=== Statusmeldungen ===
Analog zu den Fehlermeldungen kann man mit dem Attribut sumStatus gewisse Readings zählen lassen. Beipiel wäre
attr HM sumStatus motor
HMInfo zeigt in dem Reading I_sum_motor dann an, welcher Inhalt des Readings "motor" wie oft gefunden wurde. Es könnte so aussehen
stop:on:4;stop:1;
Vier Komponenten stehen auf motor: stop:on und eine steht auf motor: stop

Das Internal '''I_HM_IOdevices''' zeigt die von HM Komponenten genutzten IOs und deren State.

== Infos ==
get hm models [-f <regexp>]
get hm models
get hm models -f remote
get hm models -f HM_RC
Zeigt alle in FHEM unterstützten Modelle und deren wesentliche Parameter. Man kann mittels regexp die Liste filtern.

get hm param [<typefilter>] [-f <nameFilter>] parameter1 parameter2
get hm param -d IODev DEF model
get hm param -c -f Rollo peerList
man kann sich listen von Parametern anzeigen lassen

get hm register [<typefilter>] [-f <nameFilter>]
zeigt Register in tabellarischer Form.

get hm peerXref[<typefilter>] [-f <nameFilter>]
gibt an, wer mit wem gepeert ist

== Rücksetzen von Variablen und Zählern ==
set HM clear [<typeFilter>] [Protocol|readings|msgStat|register|rssi]
*register löscht alle Register-readings
*readings löscht '''alle''' readings
*Protocol löscht alle Protokol-einträge, pending Kommandos und Protokoll-fehler.
*rssi löscht alle ermittelten RSSI Werte
*msgStat setzt die Message Statistik zurück

== Filter ==
Kommandos in HMInfo wirken auf alle HM Komponenten. Man kann dies mit Hilfe der Filter einschränken. Zum einen gibt es '''modelsFilter''', womit man nur devices, nur channels, nur virtuelle Entities bearbeiten kann
set <name> <cmd> '''[-dcasevi]''' [params]
entities according to list will be processed"
d - device :include devices"
c - channels :include channels"
i - ignore :include devices marked as ignore"
v - virtual :supress fhem virtual"
p - physical :supress physical"
a - aktor :supress actor"
s - sensor :supress sensor"
e - empty :include results even if requested fields are empty"

Ein auf '''-d''' gefiltertes Kommando wird nur auf devices, nicht aber auf channels angewendet.

Dann gibt es noch den '''nameFilter''', mit dem mittels regexp auf den Namen der Entity gefiltert werden kann
-f Rollo # alle Entities mit Rollo im Namen
-f ^Rollo$ # nur Entity mit Namen "Rollo"
-f Rollo$ # nur Entity deren Name auf Rollo endet

Die Filter kann man kombinieren mit
-c -f Rollo # alle Kanäle mit Rollo im Namen

Beispiel:
Zeige mir die Parameter IODev und room der Devices mit Rollo im Namen
set hm param -d -f Rollo IODev room

== Attribute ==
* '''configDir''' bietet die Möglichkeit, ein Verzeichnis zu definieren, in das HMInfo Dateien ablegen und von dem es die Dateien lesen wird.
* '''configFilename''' legt einen default Namen fest, der bei save und archive genutzt wird.
* '''autoArchive ''' automatisch archivieren von vollständigen Konfigurationen.
* '''autoUpdate''' startet regelmäßig das Komamndo "update". Die Wiederholzeit wird eingestellt mit hh:mm. Sinnvoll erscheint z.B. alle 5 Minuten, also 00:05.

== Quellen ==
* Thread [http://forum.fhem.de/index.php?topic=11035.0 HMinfo] im Fhem Forum
* Thread [http://forum.fhem.de/index.php/topic,20119.0.html HMINfo, Intention, Sinn und Zweck] im Fhem Forum

[[Kategorie:HomeMatic Components]]
[[Kategorie:HOWTOS]]

PDF Datei darstellen

2014-08-12T19:42:13Z

Kamischi:

= PDF Dateien unter FHEM darstellen =

Mit den folgenden Zeilen kann man eine PDF Datei direkt in seiner FHEM Webseite darstellen. Der PDF
Reader wird in dem entsprechenden Frame des Computers geöffnet.

'''Für fhem.cfg'''
<nowiki>### Aufruf der FHEM Anfänger Anleitung via https
define FhemDoc weblink iframe https://fhem:8083/fhem/docs/fhem-floorplan-installation-guide_de.pdf
attr FhemDoc room Anleitung
attr FhemDoc htmlattr width="600" height="900" frameborder="0" marginheight="0" marginwidth="0"
</nowiki>

Mittels des "htmlattr" kann man die Größe des PDF-Viewers innerhalb der Webseite bestimmen.

Hierbei wird bei Anwahl des Menüpunkt "Fhemdoc" innerhalb des gleichen Frames ein PDF Reader geöffnet und
dieser zeigt dann die entsprechende PDF Seite an.
== PC basierend ==
=== Linux ===
Das Darstellen oder Einbinden von Dokumentation ist auf linux PC ist generell einfach, da durch den Aufruf automatisch ein entsprechender Reader geladen wird. Unter Linux (kubuntu) wird automatisch okula geöffnet.
=== Windows/Mac ===
Auf einer Windows-Maschine oder Mac Maschine ist meist der Acrobat Reader installiert und sollte daher auch sofort arbeitet. Sollte die Darstellung nicht arbeiten, fehlt meistens das Acrobat Reader Plug-in des Internet Browsers.
== Android basierend ==
=== Standard Browser ===
Standardmäßig stellt der WEB Browser eines Android Handy's oder Tablet keine PDF Dateien dar. Die Datei wird automatisch gedownloaded und muss dann manuell mit einem PDF Reader geöffnet.
=== FireFox ===
Der Browser "FireFox" biete die Möglichkeit von Addons, die den Browser um weitere Funktionen erweitert.

Nachdem man im Google Play Store das Programm-Paket "Fire Fox" hinzugefügt hat und diesen nach seinen Wünschen konfiguiert hat, muss hier noch das Addon für "Fire Fox" namens "PDF Viewer" zu Firefox hinzugefügt werden.

;HInweis zum Browser FireFox
*Firefox scheint ein Problem mit dem "iFrame" Code zu haben, da ein entsprechender Code nicht auf der Webseite darstellt wird.
*Firefox ist generell nicht der schnellste Browser

; Nachteile der PDF Viewer Lösung
* Die Software wandelt die PDF Datei beim Öffnen der PDF-Datei diese in HTML5 um. Hierdurch ist die Darstellung der PDF Datei sehr langsam. Leider ist dies derzeit die einzige Lösung (Stand 12.2013), wie man in Webseiten eine PDF Datei unter Fire Fox darstellen kann.

=== Dolphin Browser ===
Infos fehlen noch
=== Boat Browser ===
Infos fehlen noch
=== Maxthon Browser ===
Infos fehlen noch
=== Opera Browser ===
Infos fehlen noch
=== UC Browser ===
Infos fehlen noch
=== Chrome Browser ===
Infos fehlen noch

[[Kategorie:HOWTOS]]

GW1 Gewitterwarner

2014-08-12T19:41:59Z

Kamischi:

'''GW1 - Gewitterwarner'''
Der '''GW1 Gewitterwarner''' von ELV ist ein Sensor zur Erkennung von heranziehenden Gewittern.

== Eigenschaften ==
=== Allgemeines ===
Der Gewitterwarner wird als Bausatz geliefert, dessen Zusammenbau nicht besonders schwierig ist, da alle SMD-Teile bereits fertig gelötet sind. Der Bausatz enthält alle notwendigen Teile inklusive eines fertig bearbeiteten und bedruckten Gehäuses. Er besitzt 3 Schaltausgänge, die je nach Konfiguration des GW1 per Lötbrücke (J2 offen = statisches Signal, Blitz mit 1 Sekunde oder J2 geschlossen = Impuls von 300 ms Länge) mit einem der folgenden Sender

* HM-SCI-3-FM
* [[HM-PBI-4-FM]]
* HMW-Sen-SC-12-FM
* HMW-Sen-SC-12-DR
* HMW-IO-4-FM
* HMW-IO-12-FM
* HMW-IO-12-Sw7-DR
* HMW-IO-12-Sw14-DR
* FS20 S4M
* FS20 S8M
* FS20 S4UB
* FS20 TFK

zur Integration in Fhem genutzt werden können. Es kommt also darauf an, ob der Sender einen Schalt- oder Tastimpuls verarbeiten kann.

Im folgenden Beispiel wird die Nutzung mit einem [[HM-PBI-4-FM]] dargestellt (J2 also geschlossen). Dabei erfolgt die Verbindung zwischen GW1 und HM-PBI-4-FM nach folgendem Schema:

* schwarz: Masse
* 1: Entwarnung
* 2: Blitz
* 3: Warnung

'''Hinweise:'''

* Der GW1 ist <ins>kein</ins> Blitzorter wie er z.B. bei [http://www.blitzortung.org/Webpages/index.php Blitzortung.org] verwendet wird. Er kann also nicht die Richtung der detektierte Blitze bestimmen.
* Um die Empfindlichkeitswerte (z.B. in einer Umgebung mit stärkeren Störeinflüssen) oder andere Einstellungen zu verändern, sind auf der Platine insgesamt 18 DIP-Schalter angebracht. Die von ELV mitgelieferte (Auf-)Bauanleitung geht nur grob auf die Parameterveränderung ein und verweist auf das [http://www.ams.com/eng/Products/Lightning-Sensor/Franklin-Lightning-Sensor/AS3935 Datenblatt des Herstellers].

=== Techn. Daten ===
Der GW1 beruht auf einem [http://www.elv.de/controller.aspx?cid=758&detail=10&detail2=148 Franklin Lightning Sensor AS3935]. Zu diesem Sensor gibt es einige Links im WWW, vor allem auch zu einer Umsetzung mittels ''Arduino'', jedoch scheint keine dieser Umsetzungen "von Erfolg gekrönt zu sein" (Stand November 2013).

'''Bausatz:'''

* Versorgungsspannung: 5 - 12 V DC (Hohlstecker 3,5 x 1,3 mm, Plus innen)
* Stromaufnahme: 10 mA
* Schaltausgänge: 3 x Open Collector (30 V max., 100 mA max.)
* Schutzart: IP20
* Abmessungen (BxHxT): 40 x 70 x 16 mm
* Gewicht: 33 g

'''Ausgangsmodi''' (nur für alle 3 Ausgänge gemeinsam):

* Dauersignal (statisch, bei Blitz für 1 Sekunde)
* Schaltimpuls mit 300 ms Länge

== Alternativen ==
<ggfls. ergänzen>

== Hinweise zum Betrieb mit FHEM ==
Wie oben geschrieben, wird der GW1 über entsprechende HM- oder FS20-Sender in Fhem eingebunden.

=== HomeMatic ===
Nach dem Zusammenbau des GW1 wurde er nach obigem Schema mit dem [[HM-PBI-4-FM]] verbunden. Die Belegung ist natürlich wahlfrei, nur Masse des GW1 muss mit Masse des HM-PBI-4-FM (schwarzes Kabel) Verbindung haben.

=== FS20 ===
<bitte ergänzen>

=== Test ===
Das "Problem" liegt darin, dass nicht immer Gewitter ist. Es gibt ein Entwickler-Kit vom Hersteller des Sensor-ICs, dem auch ein "Blitzgenerator" beiliegt. Dieses Kit liegt preislich aber "jenseits von Gut und Böse". Schaltnetzteile und Piezo-Feuerzeuge funktionierten auch nicht. Diese erzeugten hier maximal ein Aufleuchten der Störimpuls-LED.

Was hier zum Testen funktioniert hat, ist ein normaler (etwas älterer) Schnurschalter (Wippe), der ein Meanwell-Schaltnetzteil ein- und ausgeschaltet hat. Beim Ein- und Ausschalten kommt es in dem Schalter wohl zu Abriss- bzw. Einschaltfunken. Alternativ zum Schaltnetzteil kann man auch eine Glühlampe (getestet mit einer alten 100 W Glüh"birne") mit dem Wippenschalter betätigen, denn wichtig ist der Wippenschalter, der in der Nähe des GW1 gehalten werden sollte (einige Zentimeter) bzw. dessen Abrissfunken.

'''Vorgehensweise:'''

Beim Einschalten bzw. Anschließen der Spannungsversorgung des GW1 wird nach der Initialisierung zunächst die Meldung "Entwarnung" abgesetzt und von Fhem gelogt.

Nun den GW1 direkt neben dem Wippenschalter legen/halten. Ein Ausschalten erzeugte hier ein kurzes Aufleuchten der Störimpuls-LED am GW1. Ein Einschalten brachte aber (mit ca. 1-sekündiger Verzögerung) die Blitz-LED zum Aufleuchten. Dies konnte mehrmals reproduziert werden. Zudem wurde der Ausgang "Warnung" aktiv.

Nach ca. 15 Minuten ohne Blitzerkennung schaltet der GW1 wieder auf "Entwarnung".

Hier ein Mitschnitt der entsprechenden Log-Datei:

<pre>
2013-12-11_21:13:42 Gewitterwarner battery: ok
2013-12-11_21:13:42 Gewitterwarner CUL_HM_HM_PBI_4_FM_1EFBFC_Btn_01 Short (to broadcast)
2013-12-11_21:14:10 Gewitterwarner battery: ok
2013-12-11_21:14:10 Gewitterwarner CUL_HM_HM_PBI_4_FM_1EFBFC_Btn_03 Short (to broadcast)
2013-12-11_21:14:20 Gewitterwarner battery: ok
2013-12-11_21:14:20 Gewitterwarner CUL_HM_HM_PBI_4_FM_1EFBFC_Btn_02 Short (to broadcast)
2013-12-11_21:14:27 Gewitterwarner battery: ok
2013-12-11_21:14:27 Gewitterwarner CUL_HM_HM_PBI_4_FM_1EFBFC_Btn_02 Short (to broadcast)
2013-12-11_21:14:40 Gewitterwarner battery: ok
2013-12-11_21:14:40 Gewitterwarner CUL_HM_HM_PBI_4_FM_1EFBFC_Btn_02 Short (to broadcast)
2013-12-11_21:14:48 Gewitterwarner battery: ok
2013-12-11_21:14:48 Gewitterwarner CUL_HM_HM_PBI_4_FM_1EFBFC_Btn_02 Short (to broadcast)
2013-12-11_21:30:45 Gewitterwarner battery: ok
2013-12-11_21:30:45 Gewitterwarner CUL_HM_HM_PBI_4_FM_1EFBFC_Btn_01 Short (to broadcast)
</pre>

* Btn_01 => Entwarnung
* Btn_03 => Warnung
* Btn_02 => Blitz wurde erkannt

Der GW1 mitsamt HM-PBI-4-FM wird nun an einen Ort "verfrachtet", wo er weitestgehend ungestört ist und sobald Erfahrungen mit realen Gewittern vorliegen, wird dieser Beitrag entsprechend ergänzt.

== Probleme ==
<ggfls. ergänzen>

== Tipps ==
<ggfls. ergänzen>

== Links ==
* [http://www.elv.de/output/controller.aspx?cid=74&detail=10&detail2=43718 ELV-Bausatz]
* [http://forum.fhem.de/index.php/topic,15319.0.html Thread im Fhem-Forum]
* [http://www.mikrocontroller.net/search?query=AS3935 Beiträge zum AS3935 auf Mikrocontroller.net]

[[Kategorie:Gewittersensor]]

ReadingsGroup

2014-08-12T19:41:21Z

Kamischi:

{{SEITENTITEL:readingsGroup}}
{{Infobox Modul
|ModPurpose=Einfache zusammenfassende Darstellung von Informationen über mehrere Geräte
|ModType=h

|ModCmdRef=readingsGroup
|ModTechName=33_readingsGroup.pm
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=430 Andre / justme1968]}}
Das Fhem-[[:Kategorie:Hilfsmodul|Hilfsmodul]] [[readingsGroup]] bietet eine einfache Möglichkeit, ''readings'' und ''internal values'' von einem oder mehreren ''Devices'' darzustellen und flexibel zu formatieren.

Hier soll eine Sammlung von Beispielen zur Verwendung der ''readingsGroup'' mitsamt der zugehörigen Screenshots entstehen.

== Definition ==
Siehe commandref.

== Attribute ==
Weitergehende Erläuterungen zu einzelnen Attributen:

=== noheading ===
[[Datei:ReadingsGroup_noheading.png|mini|rechts|400px|ReadingsGroup: rechts mit "noheading" Attribut, links der anklickbare Titel]]
Das Attribut <code>noheading</code> führt dazu, dass der Alias der ReadingsGroup nicht mehr als Titel angezeigt wird. Das kann wünschenswert sein, wenn die ReadingsGroup auf einer [[Dashboard]]-Seite angezeigt werden soll, hat allerdings den Nachteil, dass die Detail-Ansicht der ReadingsGroup nicht mehr über einen Klick auf den Titel aufgerufen werden kann. Der Einstellungsdialog der ReadingsGroup ist dann nur noch (z. B.) über
* einen "Probably associated with"-Link eines anderen Objekts oder über
* manuelle Modifikation der URL eines anderen Objekts (<code>http:.../fhem?detail=<objektname></code>)
erreichbar.

== Beispiele ==
Achtung: Die Beispiele enthalten keine Maskierungen oder Verdoppelungen für ; und Zeilenende, sondern sind so angegeben, wie sie in Fhemweb, in der command box oder nach Klick auf DEF eingegeben werden. Beim manuellen Einfügen in eine [[Konfiguration|Konfigurationsdatei]] sind diese Maskierungen oder Verdoppelungen natürlich vorzunehmen.

=== Einfache Auswahl über Reading-Namen ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define battStatus readingsGroup .*:[Bb]attery</code>
| Alle readings mit Namen '''Battery''' oder '''battery''' von allen Devices.
| rowspan=3 | [[Datei:rgBattery.png|thumb]]
|-
| <code>attr battStatus alias FHT Batteriestatus </code>
| Der Alias wird als Zeilentitel verwendet
|-
| <code>attr battStatus mapping %ROOM </code>
| ''Mapping %ROOM'' führt dazu, dass der Raumname als Zeilentitel angezeigt wird.
|}

=== Auswahl über Reading-Namen, Status als Symbol dargestellt ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg_battery readingsGroup .*:battery</code>
| Alle readings mit Namen '''battery''' von allen Devices.
| rowspan=4 | [[Datei:rgBattery2.png|thumb]]
|-
| <code>attr rg_battery alias Batteriestatus </code>
| Der Alias wird als Überschrift verwendet
|-
| <code>attr rg_battery valueIcon {'battery.ok' => 'batterie', 'battery.low' => 'batterie@red'}</code>
| Statt der reading Werte "ok" und "low" soll ein Icon angezeigt werden.
|-
|<code>attr rg_battery commands { "battery.low" => "set %DEVICE replaceBatteryForSec 60" }</code>
| Für LaCrosse devices kann man beim Klick auf ein rotes "battery low icon" direkt replaceBatteryForSec setzen.
|}

=== Reading-Werte zuordnen (Icon / Text) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define rg readingsGroup Contact.Dachboden_gross:sensed.*</code>
| Alle sensedreadings des Contact.Dachboden_gross device.
| rowspan=4 | [[Datei:rgFenster.png|thumb]]
|-
| <code>attr rg mapping { 'sensed.A' => 'links', 'sensed.B' => 'rechts' }</code>
| Die Zuordnung rechts/links
|-
| <code>attr rg valueFormat {($VALUE eq '1')?"fts_window_roof":"fts_window_roof_open_2"}</code>
| Die Zuordnung von reading Wert zu Icon Namen.
|-
| <code>attr rg_battery valueIcon %VALUE </code>
| Statt des reading Werts soll ein Icon angezeigt werden.
|}

=== Formatvorgabe für Ausgabewerte ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define TempHygro readingsGroup TYPE=CUL_WS:temperature,humidity,dewpoint</code>
| Alle readings mit Namen '''temperature''', '''humidity''', '''dewpoint''' von allen Devices des Typs '''CUL_WS'''
| rowspan=4 | [[Datei:rgTemperatur.png|thumb|[[S300TH]]-Werte in einer readingsGroup]]
|-
| <code>attr TempHygro alias Temperatur / rel. Feuchte / Taupunkt</code>
| Der Alias der readingsGroup wird als Überschrift verwendet
|-
| <code>attr TempHygro mapping %ALIAS</code>
| ''Mapping %ALIAS'' führt dazu, dass der Alias des Geräts als Zeilentitel angezeigt wird.
|-
| <code>attr TempHygro valueFormat { temperature => "%.1f&deg;C", humidity => "%.1f %%", dewpoint => "%.1f&deg;C"}</code>
| Formatierung der Ausgabewerte. '''Achtung:''' "%" die in der Ausgabe erscheinen sollen, müssen verdoppelt werden!
|}

=== Ausgabestil (hier rechtsbündig) ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Wetter readingsGroup WetterXXX:<%temp_temperature>,<Temperatur>,temperature WetterXXX:<%weather_humidity>,<Luftfeuchte>,humidity WetterXXX:<%weather_baraometric_pressure>,<Luftdruck>,pressure
</code>
| Die readings mit Namen '''temperature''', '''humidity''' und '''pressure''' vom Device WetterXXX jeweils mit einem Icon und einem Label davor.
| rowspan=3 | [[Datei:rgWetter.png|thumb]]
|-
| <code>attr Wetter valueFormat { temperature => '%1.f &deg;C', humidity => '%1.f %%', pressure => '%i mbar' }</code>
| Die Formatierung der Readingswerte
|-
| <code>attr Wetter valueStyle style="text-align:right"</code>
| Die Readings sollen rechtsbündig dargestellt werden.
|}

=== Internal Value ausgeben ===
Diese Beispiel könnte entfallen (nächstes Beispiel ist sehr ähnlich; es wird lediglich ein weiterer Wert ausgegeben).
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI</code>
| Den cul_RSSI Wert aller Devices die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau.
| rowspan=1 | [[Datei:rgculRSSI.png|thumb]]
|}

=== Internal Values ausgeben ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI,+cul_TIME</code>
| Den cul_RSSI Wert mit der zugehörigen Zeit aller Devices die einen solchen haben anzeigen. '''Achtung''': "internal values" werden nicht per longpoll aktualisiert, sondern nur beim Seitenaufbau. "Internal Values" werden durch das vorangestellte '''+''' (Pluszeichen) identifiziert.
| rowspan=1 | [[Datei:rgculRSSI2.png|thumb]]
|}

=== Alle Readings eines Gerätes, mit Ausnahme von... ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Systemstatus readingsGroup sysstat</code>
| Alle readings des sysstat Device
| rowspan=4 | [[Datei:rgSysstat.png|thumb]]
|-
| <code>attr Systemstatus nostate 1</code>
| Ohne state
|-
| <code>attr Systemstatus notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Systemstatus mapping {'load' => 'Systemauslastung', 'temperature' => 'Systemtemperatur in &deg;C'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|}

=== Anzeige auf einem Floorplan ===
{| class="wikitable"
! Definition !! Erläuterungen !! Aussehen
|-
| style="width:40%" |<code>define Heizung readingsGroup t(1|2|3):temperature</code>
| Die Temperatur readings der Devices t1, t2 und t3
| rowspan=6 | [[Datei:rgHeizung.png|thumb]]
|-
| <code>attr Heizung mapping {'t1.temperature' => 'Vorlauf', 't2.temperature' => 'R&ücklauf', 't3.temperature' => 'Zirkulation'}</code>
| Die Zuordnung der reading Namen zu den Zeilentiteln
|-
| <code>attr Heizung nameStyle style="text-align:left"</code>
| Zeilentitel linksbündig wegen floorplan
|-
| <code>attr Heizung style style="font-size:20px;color:lightgray"</code>
| Großer Font und Farbe passend für den floorplan
|-
| <code>attr Heizung notime 1</code>
| Ohne readings timestamp
|-
| <code>attr Heizung valueFormat : %.1f &deg;C</code>
| Doppelpunkt zwischen Zeilentitel und Wert, eine Nachkommastelle plus Einheit
|}

=== Schriftgrößen, Farben, Icons ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgVerbrauchPCA301.png|links|mini|400px|Schriftgröße, Farbe, Icons...]]
|-
| style="width:40%" |<code>define Verbrauch readingsGroup TYPE=PCA301:state,power,consumption</code>
| Die readings state, power und consumption aller [[PCA301 Funkschaltsteckdose mit Energieverbrauchsmessung|PCA301]] Devices mit einer Zeile pro Device.
|-
| <code>attr Verbrauch mapping %ROOM %ALIAS</code>
| Der Raumname und der Alias werden als Zeilentitel verwendet
|-
| <code>attr Verbrauch nameStyle style="font-weight:bold"</code>
| Der Zeilentitel soll fett sein
|-
| <code>attr Verbrauch style style="font-size:20px"</code>
| Alles in einem größeren Font
|-
| <code>attr Verbrauch valueFormat {power => "%.1f W", consumption => "%.2f kWh"}</code>
| Die Formatierung für die power und consumption readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr Verbrauch valueIcon { state => '%devStateIcon' }</code>
| Für die Dosen, die schaltbar sind, soll das anklickbare device icon gezeigt werden.
|-
|<code>attr Verbrauch valueStyle {($READING eq "power" && $VALUE > 40)?'style="color:red"':'style="color:green"'}</code>
|Wenn das power reading >40 ist, soll es in rot angezeigt werden, alle anderen Werte und readings in grün
|}

=== Wertabhängige Farbgebung ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:TemperaturenRG.png|600px|mini|links|Wertabhängige Farben]]
[[Datei:TemperaturenRG2.png|600px|mini|links|Andere Werte - andere Farben]]
|-
| style="width:40%" |<code>define wzTemperaturenRG readingsGroup Aussen:,<Temperatur>,temperature,<Luftfeuchte>,humidity Wohnzimmer:,<Temperatur>,temperature,<Luftfeuchte>,humidity Kasten_E_Geraete:,<Temperatur>,temperature,<Luftfeuchte>,humidity</code>
| Die readings temperatur und humidity der Devices Aussen, Wohnzimmer und Kasten_E_Geraete in einer Zeile pro Device.
|-
| <code>attr wzTemperaturenRG group 3. Temperaturen</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzTemperaturenRG noheading 1</code>
| noheading
|-
| <code>attr wzTemperaturenRG nostate 1</code>
| nostate
|-
| <code>attr wzTemperaturenRG notime 1</code>
| notime
|-
| <code>attr wzTemperaturenRG valueFormat {temperature => "%.1f °C", humidity =>"%.1f %%" }</code>
| Die Formatierung für die temperatur und humidity readings: eine Nachkommastelle plus Einheit.
|-
|<code>attr wzTemperaturenRG valueStyle { if($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE > 20) { 'style="color:orange"'}elsif($DEVICE eq "Aussen" && $READING eq "temperature" && $VALUE < 5) { 'style="color:blue"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 23) { 'style="color:red"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE > 21) { 'style="color:orange"'}elsif($DEVICE eq "Wohnzimmer" && $READING eq "temperature" && $VALUE < 20) { 'style="color:blue"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 30) { 'style="color:red"'}elsif($DEVICE eq "Kasten_E_Geraete" && $READING eq "temperature" && $VALUE > 28) { 'style="color:orange"'}elsif($READING eq "humidity" && $VALUE > 65) { 'style="color:red"'}elsif($READING eq "humidity" && $VALUE > 60) { 'style="color:orange"'}else{'style="color:green"'} }</code>
| Diverse Farbkombinationen sind möglich
|}

=== Enigma Receiver ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:ReceiverRG.jpg|600px|mini|links|Wertabhängige Farben]]
[[Datei:ReceiverRGmute.jpg|600px|mini|links|Wertabhängige Farben]]
|-
| style="width:40%" |<code>define wzReceiverRG readingsGroup wzReceiver:,<Aktuell>,eventtitle,<Rest>,eventremaining_hr,<Dauer>,eventduration_hr wzReceiver:<Beschreibung>,eventdescription wzReceiver:,<Nächste>,eventtitle_next,<Start>,eventstart_next_hr,<Dauer>,eventduration_next_hr wzReceiver:,<HDD Kapazität>,hdd1_capacity,<Frei>,wzReceiver:hdd1_free wzReceiver:,<Lautstärke>,volume,<HDD>,hdd1_capacity,<Frei>,hdd1_free</code>
| Mehrere readings des Device wzReceiver in mehreren Zeilen. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke, mute angezeigt. Farbige Anzeige des freien Speicherplatzes
'''Benötigt:''' ENIGMA2 Receiver, 70_ENIGMA2.pm - Siehe: [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern]]
|-
| <code>attr wzReceiverRG group Fernseher Receiver</code>
| Die readingsGroup kommt in eine Gruppe
|-
| <code>attr wzReceiverRG mapping &nbsp;</code>
| mapping wird auf &nbsp; (Leerzeichen) gesetzt, damit der Device Name nicht angezeigt wird
|-
| <code>attr wzReceiverRG noheading 1</code>
| noheading
|-
| <code>attr wzReceiverRG nostate 1</code>
| nostate
|-
| <code>attr wzReceiverRG notime 1</code>
| notime
|-
|-
| <code>attr wzReceiverRG valueColumns { eventdescription => 'colspan="4"' }</code>
| Die Beschreibung soll über 4 Spalten gehen
|-
| <code>attr wzReceiverRG valueFormat { wzReceiverRGvalueFormat($DEVICE,$READING,$VALUE);; }</code>
| Die Formatierung wird in die 99_myUtils.pm ausgelagert. Siehe: [[99 myUtils anlegen]]
|-
|<code>attr wzReceiverRG valueStyle { if($READING eq "hdd1_free" && $VALUE < 200){ 'style="color:red"' }elsif( $READING eq "hdd1_free" && $VALUE < 500 ){ 'style="color:orange"' }elsif( $READING eq "volume" && ReadingsVal($DEVICE, "mute", "") eq "on" ){ 'style="color:red"' }else{ 'style="color:green"' } }</code>
| Diverse Farbkombinationen sind möglich. Wenn der Receiver auf mute ist, wird anstatt der Lautstärke mute angezeigt.
|-
| <code>
sub wzReceiverRGvalueFormat($$$)
{
my ($DEVICE,$READING,$VALUE) = @_;

if($READING eq 'hdd1_capacity') {
return "%.2f MB";
} elsif( $READING eq 'hdd1_free') {
return "%.2f MB";
} elsif( $READING eq 'volume' ) {
if( ReadingsVal($DEVICE, "mute", "") eq "on") {
return "mute";
} else {
return "%i %%";
}
}
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]
|}

=== Heizungswerte inklusive Batterie- und Fensterstatus ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung3.png|thumb|links|500px|Heizungswerte inklusive Batterie- und Fensterstatus]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<%18>,<%20>,<%22>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte commands { 'Heizungswerte.18' => 'set $DEVICE desired-temp 18', 'Heizungswerte.20' => 'set $DEVICE desired-temp 20', 'Heizungswerte.22' => 'set $DEVICE desired-temp 22' }</code>
| Die Links/Kommandos die hinter den 18, 20 und 22 liegen sollen.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte inklusive Ventilposition ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:Rg_Heizung_Valveposition.png|thumb|links|500px|Heizungswerte inklusive Statusinformationen (MAX!)]]
|-
| style="width:40%" |<code>define Heizungswerte readingsGroup <%sani_heating>,<Ventil>,<Soll>,<Ist>,<MaxV>,<GID>,<Mode>,<Batterie> type=CUL_HM:ValvePosition,desired-tempe,measured-temp,R-valveMaxPos,groupid,mode,battery</code>
| Diverse readings aller Devices des Typs MAX.
|-
| <code>attr Heizungswerte mapping %ROOM</code>
| Die Raumnamen werden angezeigt.
|-
| <code>attr Heizungswerte nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb (fett) sein.
|-
| <code>attr Heizungswerte room Heizung</code>
| Die "readingsgroup" wird dem Ruam "Heizung" zugeordnet.
|-
| <code>attr Heizungswerte valueFormat {temperature => "%.0f °C", desiredTemperature => "%.0f °C", valveposition =>"%.0f %%",maxValveSetting =>"%.0f %%" }</code>
| Es wird noch die Einheit °C hinter den Temperaturwerten angezeigt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batterzustand werden Icons anstatt Klartextwerte genommen!
|-
| <code>attr Heizungswerte valueStyle { if($READING eq "temperature" && $VALUE > 20){ 'style="color:green;;font-weight:bold"' }elsif( $READING eq "temperature" && $VALUE <= 20 ){ 'style="color:blue"' }elsif( $READING eq "temperature" && $VALUE > 23 ){ 'style="color:red"' }else{ 'style="color:gray"' } }</code>
| Die Temperaturwerte werden abhängig vom Wert farbig dargestellt.
|-
| <code>attr Heizungswerte valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|}

=== Heizungswerte, Status und Regelmöglichkeit ===
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung2.png|thumb|500px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define Heizungswerte2 readingsGroup <%sani_heating>,< >,<Act>,<Soll>,<Ist> TYPE=FHT:actuator,desired-temp,measured-temp,<{myUtils_HeizungUpDown($DEVICE,"up")}@desired-temp>,desired-new,<{myUtils_HeizungUpDown($DEVICE,"down")}@desired-temp>,window,battery</code>
| Diverse readings aller Devices des Typs FHT.
|-
| <code>attr Heizungswerte2 nameStyle style="color:yellow;font-weight:bold"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr Heizungswerte2 valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red', 'window.closed' => 'fts_window_1w@lightgreen', 'window.open' => 'fts_window_1w_open@red'}</code>
| Für den Batteriestand und den Zustand der Fenster sollen jeweils Icons angezeigt werden.
|-
| <code>attr Heizungswerte2 valueStyle {($VALUE eq "00")?'style="visibility:hidden"':''}</code>
| Nach dem Einstellen den Wert wieder ausblenden.
|-
| <code>
#Heizung regeln in readingsGroup
sub
myUtils_HeizungUpDown($$)
{
my($DEVICE,$CMD) = @_;

my $icon = $CMD;
my $VALUE = ReadingsVal($DEVICE,"desired-new","20" );
$VALUE = ReadingsVal($DEVICE,"desired-temp","20" )
if( !$VALUE || $VALUE == 0 );
my $link;

if( $CMD eq "up" ) {
$icon = "control_arrow_upward";
$VALUE += 1;

if( $VALUE <= 24 ) {
$icon .= "\@red";
$link = "setreading $DEVICE desired-new $VALUE";
}
} elsif( $CMD eq "down" ) {
$icon = "control_arrow_downward";
$VALUE -= 1;

if( $VALUE >= 18 ) {
$icon .= "\@blue";
$link = "setreading $DEVICE desired-new $VALUE";
}
}

my $notify = "notifyHeizungUpDown";
if( !defined($defs{$notify}) ) {
CommandDefine(undef,
"$notify notify .*:desired-new.* "
."{ myUtils_HeizungUpDownNotify(\$NAME,\$EVTPART1); }" );
}

my $ret = "%$icon";
$ret .= "%$link" if( $link );

return $ret;
}
sub
myUtils_HeizungUpDownNotify($$)
{
my($DEVICE,$VALUE) = @_;

return if( $VALUE == 0 );

my $at = "triggerHeizungUpDown_$DEVICE";
CommandDelete(undef, $at) if( defined($defs{$at}) );
CommandDefine(undef,
"$at at +00:00:03 "
."{my \$v = ReadingsVal(\"$DEVICE\",\"desired-new\",undef);"
."fhem(\"set $DEVICE desired-temp \$v\") if( \$v );"
."fhem(\"setreading $DEVICE desired-new 00\");}" );

return undef;
}
</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit werden die Icons zum Ändern der gewünschten Temperatur dargestellt und im Bereich >=18 und <= 24 Grad anklickbar gemacht. Zwischen den Pfeilen wird der gerade eingestellte Wert angezeigt. Wenn dieser drei Sekunden nicht mehr geändert wurde wird die desired-temp auf diesen Wert gesetzt und die Anzeige zwischen den Pfeilen ausgeblendet.
|}

=== Readings aus zusätzlichen Devices ===
Im folgenden Beispiel wird gezeigt wie sich Readings zusätzlicher Devices zu einer Zeile mit mehreren Readings hinzufügen lassen. Diese zusätzlichen Devices können z.b. die unterschiedlichen Channel eines HomeMatic Gerätes sein. Im folgenden Beispiel wird der Name des zugehörigen Geräts dynamisch bestimmt.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rgHeizung4.png|thumb|500px|links|Anzeige + Regelmöglichkeit]]
|-
| style="width:40%" |<code>define myTemp readingsGroup <Raum>,<Tist>,<Tsoll>,<Mode>,<Tnight>,<Tday>,<Hum>,<BatTC>,<Vist>,<Vsoll>,<Verr>,<BatVD> Thermostat.(WZ|OZ|AZ|Bad|Kueche|SZ|GZ|Bad.OG):measured-temp,desired-temp,controlMode,night-temp,day-temp,humidity,battery,ValvePosition@{valveOfDevice($DEVICE)},ValveDesired@{valveOfDevice($DEVICE)},R-valveErrorPos@{valveOfDevice($DEVICE)},battery@{valveOfDevice($DEVICE)} Broetje:ToutIst </code>
| Diverse Readings aller Thermostat Devices und des jeweils zugehörigen Ventilanriebs.
|-
| <code>attr myTemp mapping { 'Broetje' => 'Garten','Thermostat.AZ' => 'EG Arbeitszimmer','Thermostat.SZ' => 'OG Schlafzimmer','Thermostat.WZ'=>'EG Wohnzimmer','Thermostat.Kueche' => 'EG Küche','Thermostat.GZ' => 'OG Gästezimmer','Thermostat.Bad' => 'EG Bad','Thermostat.Bad.OG' => 'OG Bad','Thermostat.OZ' => 'EG Kaminzimmer','desired-temp' => <nowiki>''</nowiki> }</code>
| Die Benennung der Zeilentitel (Das ist je nach Konfiguration auch über $ALIAS und/oder $ROOM lösbar).
|-
| <code>attr myTemp commands { 'desired-temp' => 'desired-temp:' }</code>
| desired-temp soll per dropDown einstellbar sein.
|-
| <code>attr myTemp nameStyle style="color:yellow"</code>
| Die Überschriften sollen gelb sein.
|-
| <code>attr myTemp valueIcon {'battery.ok' => 'batterie@lightgreen', 'battery.low' => 'batterie@red'}</code>
| Für den Batteriestand sollen jeweils Icons angezeigt werden.
|-
| <code>attr myTemp valueFormat { 'measured-temp' => "%0.1f &deg;C",'ToutIst' => "%.1f &deg;C",'night-temp' => "%.1f &deg;C",'day-temp' => "%.1f &deg;C",'humidity' => "%.0f
%%",'ValvePosition' => "%.0f %%",'ValveDesired' => "%.0f %%",'R-valveErrorPos' => "%.0f %%" }</code>
| Die Formatierung der Werte.
|-
| <code>
#namen des ventil device aus thermostat device ableiten
sub valveOfDevice ($) {
my ($DEVICE) = @_;

if ($DEVICE =~ m/AZ/) {
return "Ventil.".substr($DEVICE,11).".Nord";
} else {
return "Ventil.".substr($DEVICE,11);
}
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hier wird aus dem Namen des Thermostaten der Name des zugehörigen Ventilantriebs abgeleitet.
|}
Da im {...} Teil des <reading>@<device> Arguments keine Leerzeichen oder Kommas vorkommen dürfen ist er in der Regel das Einfachste die Funktionalität wie in diesem Beispiel in eine eigene Routine auszulagern. Mit ein paar 'Tricks' lässt es sich aber manchmal auch ohne Leerzeichen oder Kommas lösen und dann direkt in die Definition schreiben:<code>...,ValvePosition@{$DEVICE=~s/Thermostat/Ventil/;$DEVICE;},...</code>

=== Dynamische Inhalte ===
[[Datei:rgDynamic-1.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 1]]
[[Datei:rgDynamic-2.png|mini|450px|readingsGroup mit umschaltbarem Inhalt 2]]
Es ist möglich, den in einer readingsGroup dargestellten Inhalt dynamisch von zusätzlichen Bedingungen abhängig zu machen. Im folgenden Beispiel lässt sich
einstellen, dass nur die Devices angezeigt werden, die einen bestimmten Zustand (hier: on/off, open/tilted/closed) haben. Hier wird zum Umschalten ein dummy, der direkt über der readingsGroup dargestellt wird, verwendet. Über das links und/oder commands lässt sich auch eine Darstellung erzeugen, bei der das Umschalten direkt innerhalb der readingsGroup möglich ist.

<pre>
define LXrg dummy
attr LXrg group -
attr LXrg setList mode1:on,off mode2:open,closed,tilted
attr LXrg stateFormat 1=mode1 2=mode2
attr LXrg webCmd mode1:mode2

define rg readingsGroup Window.*:state Light.*:state
attr rg group -
attr rg valueFormat { return $VALUE if ( $VALUE eq ReadingsVal("LXrg","mode1","") || $VALUE eq ReadingsVal("LXrg","mode2","") );; return undef;;}

define Watch_LX notify LX.*:.* {my $value = ReadingsVal($NAME,'state','');;;;fhem("setreading $NAME $value")}
</pre>

=== Enable/Disable Button am Beispiel eines WeekdayTimer ===
Dieses Beispiel zeigt die Anwendung einer readingsGroup, um im Frontend einen Enable/Disable Button für ein Objekt darzustellen. Für den WeekdayTimer gibt es hier spezielle Erweiterungen (set Routinen, um das disable Attribut zu setzen, Reading "disabled"). Es gibt aber auch eine allgemeinere Variante (siehe [http://forum.fhem.de/index.php/topic,23655.msg169141.html#msg169141 diesen Forumsbeitrag]) für alle Objekte, die das FHEM Attribut "disable" unterstützen.
{| class="wikitable"
! Definition !! Erläuterungen
|-
| colspan=2 | [[Datei:rg_scheduling.png|thumb|500px|links|Enable/Disable Button]]
|-
| style="width:40%" |<code>define rg_Timer_Wasser readingsGroup timer_Wasser_..:disabled,+DEF,<{rg_timer_Wasser_show_conditional($DEVICE,"nextUpdate")}@disabled>,<{rg_timer_Wasser_show_conditional($DEVICE,"nextValue")}@disabled></code>
| Definition der angezeigten Readings. Das Reading disabled wird mit den u.a. Attributen zum Button, +DEF zeigt die Definition, d.h. die Schaltzeiten, des Timers an. Die Readings nextUpdate und nextValue sollen nur angezeigt werden, falls der Timer aktiv ist. Hierfür sorgt eine Routine <code>rg_timer_Wasser_show_conditional</code>, die in der 99_myUtils.pm definiert wird. Das abschließende @disabled sorgt dafür, daß der LongPoll Mechanismus die Anzeige sofort ändert, wenn der Button betätigt wird.
|-
| <code>attr rg_Timer_Wasser valueFormat { if ( $READING =~ m/.*DEF/ ) { my @text = split(" ", $VALUE); shift @text; return join(" ", @text) }}</code>
| Der Name des Timers wird aus dem interal Reading "+DEF" vorne abgeschnitten. Damit werden nur die definierten Schaltpunkte angezeigt.
|-
| <code>attr rg_Timer_Wasser valueIcon { 'disabled.0' => 'Restart', 'disabled.1' => 'Shutdown' }</code>
| Die beiden Zustände für den Button werden durch zwei Standard-Icons angezeigt.
|-
| <code>attr rg_Timer_Wasser commands { 'disabled.0' => 'set $DEVICE disable', 'disabled.1' => 'set $DEVICE enable' }</code>
| Toggle-Funktion für den Button. Wenn der Timer aktiv ("disabled.0") sorgt ein Klick auf den Button, daß der Timer deaktiviert wird ("set $DEVICE disable").
|-
|<code>
sub rg_timer_Wasser_show_conditional($$)
{
my ($DEVICE,$READING) = @_;
return ( ReadingsVal($DEVICE, "disabled", "1") eq "0" )?
ReadingsVal($DEVICE, $READING, "reading_undef") : "disabled";
}</code>
| Dieser Teil kommt in die [[99_myUtils_anlegen|99_myUtils.pm]]: Hiermit wird das übergebene Reading des Timers nur angezeigt, wenn der Timer aktiv ist. Andernfalls wird der String "disabled" stattdessen angezeigt.
|}

== Links und Trigger ==
[[Datei:rgPCA-detail.png|mini|400px|readingsGroup mit Link]]
Das PCA301 Beispiel oben lässt sich mit einem ans Ende des define angehängten
:<code><{appendTrigger($DEVICE,"clear","Alle löschen")}></code>
und der folgenden appendTrigger Definition in 99_myUtils.pm um einen Link erweitern, der ein Event auslöst, an das z.B. ein notify gehängt werden kann, um die Verbrauchszähler der PCA301 Dosen zurückzusetzen.
:<code>define clearVerbrauch notify Verbrauch:clear set TYPE=PCA301 clear</code>

<pre>use vars qw($FW_ME);
use vars qw($FW_subdir);
sub
appendTrigger($$$)
{
my ($name,$trigger,$label) = @_;

my $ret .= "</table></td></tr>";

my $link = "cmd=trigger $name $trigger";
my $txt = "<a onClick=\"FW_cmd('$FW_ME$FW_subdir?XHR=1&$link')\">$label</a>";
$ret .= "<td colspan=\"99\"><div style=\"cursor:pointer;color:#888888;text-align:right\">$txt</div></td>";

return ($ret,0);
}</pre>

Ein weiteres Beispiel für 'custom links und trigger' findet sich im [http://forum.fhem.de/index.php/topic,14425.msg109383.html#msg109383 Forum]: dort wird damit eine readingsGroup dynamisch umgeschaltet, um nur die eingeschalteten, nur die ausgeschalteten oder alle Lampen anzuzeigen.

== Sonstiges ==
In der Regel werden die Parameter zu einem reading in den mappings unter <$DEVICE> und dann <$DEVICE>.<$READING> und dann unter <$READING>.<$VALUE> gesucht.

===Lesbar machen===
Für die meisten Attribute gilt:

*Wenn es komplexer wird ist es einfacher den Code in eine sub in 99_myUtils auszulagern und diese aufzurufen:
<code> attr <name> valueStyle {myValueToFormat($READING,$VALUE)}</code>

*code für unterschiedliche readings kann man auch im mapping schon aufteilen:
<code>attr <name> valueStyle { SuperE5 => '{perl code}', Diesel => '{perl code}' }</code>

*Ifs lassen sich verschachteln und sortieren. So kann die Anzahl der Klammern und Else-Zweige reduziert werden:
<code>if( $READING eq ... ) {
return xxx if( $VALUE < 1 );
return yyy if( $VALUE < 1.5 );
return zzz;
} elsif( $READING eq ... ) {
...
}</code>

Da alles lässt sich natürlich auch kombinieren und so viel lesbarer machen als ein einziger langer Bandwurm.

===group===
Wenn der doppelte Rahmen um eine readingsGroup in eine group stört, lässt er sich mit dem passenden style entfernen:
<code>attr <device> style style="border:0px;background:none;box-shadow:none"</code>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Serial/Netzwerk-RS485-Adapter

2014-08-12T19:41:02Z

Kamischi:

== Vorbemerkungen ==
Alternativ zum [[HomeMatic_Wired_RS485_LAN_Gateway]], können einfache Serial/Netzwerk-RS485-Adaptern für die Kommunikation von FHEM zu HomeMatic-Wired-Geräten eingesetzt werden.
In diesem Artikel werden sowohl RS232-RS485-Adapter, USB-RS485-Adapter als auch Netzwerk-RS485-Adapter als Serial-RS485-Adaptern bezeichnet, denn in jedem Fall wird ein serieller Datenstrom an den RS485 Tranceiver weitergeleitet.

Da diese hier beschriebenen Interfaces keine "Intelligenz" besitzen, also die Daten lediglich auf den RS485-Bus umsetzen, wird zur Ansteuerung noch der ''hm485d.pm''-Daemon benötigt. Dieser Prozess setzt die RAW-Befehle in das HomeMatic-Wired-Protokoll um. Der hm485d kann dabei transparent im Hintergrund arbeiten.

=== Liste der aktuell getesteten Adapter / Schnittstellen (bitte ggf. ergänzen) ===

* DIGITUS DA-70157: USB-Serial Adapter mit RS485 Schnittstelle, funktioniert auch an der FritzBox [http://www.reichelt.de/USB-Konverter/DIGITUS-DA-70157/3//index.html?ARTICLE=122187]
* Wiznet - WIZ108SR Compact RS422/RS485-to-Ethernet module [http://tigal.at/product/2276]
* Wiznet - WIZ108SR im Hutschienengehäuse [http://forum.fhem.de/index.php/topic,14096.msg88557.html#msg88557]

== Einbindung in FHEM ==
Zum Einbinden des HMW-LAN-GW müssen folgend Zeilen in die fhem.cfg eintragen werde:

define HM485_LAN HM485_LAN localhost:2000
attr HM485_LAN hmwId 00000001
attr HM485_LAN HM485d_device <SerialDevice>
attr HM485_LAN HM485d_bind 1
attr HM485_LAN room HM485

Der Name HM485_LAN kann frei vergeben werden.
Bei <SerialDevice> muss der Gerätename angegeben werden unter dem das serielle Device anzusprechen ist.

'''Beispiele:'''
# Serieller USB-RS485-Adapter
attr HM485_LAN HM485d_device /dev/ttyUSB0

# Netzwerk-RS485-Adapter
attr HM485_LAN HM485d_device 192.168.1.15:5000

HM485d_bind 1 sorgt dafür, dass der hm485d beim FHEM-Start automatisch mit gestartet wird und durch FHEM auch gesteuert, also auch beendet werden kann.

HM485_LAN kennt weitere Attribute, die zur Kontrolle des hm485d dienen.
Wichtig ist vor allem, für HM485_LAN eine Adresse festzulegen. Die HMW-ID muss eine 8-stellige Hexadezimalzahl sein.
Theoretisch könnten die bis zu 256 HMW-LAN-GW angelegt werden. Diese Annahme ist aktuell aber nur Theorie und noch nicht getestet und ggf. mit einigen Problemen verbunden. Die HMW-ID's für die HMW-Interfaces könnten dafür im Bereich von 00000001 - 000000FF gewählt werden.
Da in den HMW-Geräten die HMW-ID der Zentrale aber mit 00000001 vordefiniert ist, sollte hier aktuell nur diese ID verwendet werden.

Zu beachten ist auch, dass der hm485d '''gleichzeitig''' nur eine Netzwerkverbindung erlaubt. Somit ist ein Gateway auch nur mit einer Zentrale / FHEM-Instanz zur gleichen Zeit nutzbar.

=== HM485_LAN Attribute ===
* '''hmwId''' Hier muss die HMW-ID angegeben werden. Standardmäßig wird die 00000001 benutzt.
* '''do_not_notify''' FileLog/notify/inform Benachrichtigung für das Gerät ist abgeschaltet.
* '''HM485d_bind''' Startet den hm485d automatisch beim Start von FHEM und ermöglicht FHEM zudem die Prozesskontrolle
* '''HM485d_startTimeout''' Manchmal, z.B. auf langsameren Geräten wie der FritzBox oder dem Raspberry Pi, ist es erforderlich den hm485d verzögert zu starten. Hier kann die Verzögerung in Sekunden angegeben werden.
* '''HM485d_device''' Das serielle Gerät zum Interface (siehe Beispiel oben).
* '''HM485d_serialNumber''' Die Seriennummer die der hm485d an die Zentrale (FHEM) melden soll.
* '''HM485d_logfile''' Der hm485d kann ein eigenes Logfile schreiben. Hier kann dafür ein Dateiname angegeben werden.
* '''HM485d_detatch''' Wenn der hm485d mit FHEM zusammen gestartet wird (siehe HM485d_bind) so kann der Prozess hier von FHEM entkoppelt werden. Der Prozess wird dann auch nicht zusammen mit FHEM beendet.
* '''HM485d_logVerbose''' Der Loglevel vom hm485d.

Die folgenden drei Attribute können verwendet werden, wenn der hm485d über einen einfachen UART ohne Flusskontrolle z.B. über den UART des Raspberry Pi, an einen RS485 Tranceiver angeschlossen wird. Dafür müssen ggf. GPIO-Pins zur Steuerung des RS485 Tranceivers (Senden/Empfangen) definiert werden:
* '''HM485d_gpioTxenInit''' Shell-Befehl zum initialisieren des benutzten GPIO-Pins für die Sendekontrolle
* '''HM485d_gpioTxenCmd0''' Shell-Befehl um den Sende-GPIO-Pin zurück zu setzen
* '''HM485d_gpioTxenCmd1''' Shell-Befehl um den Sende-GPIO-Pin zu setzen

'''Hinweis'''
Da auch der hm485d sich noch in Entwicklung befindet, ist es möglich dass es in einigen Fällen noch zu Fehlverhalten kommen kann.

== Pairen von Geräten ==
Jedes HM Geräte muss vor Verwendung mit der Zentrale, hier also FHEM, gepairt werden. Anders als bei den HomeMatic-Funk-Geräten erfolgt das Pairing bei HMW automatisch, sobald ein Gerät das erste Mal eine Nachricht über den Bus versendet. Alternativ kann das Pairing auch durch das Absetzen eines Discovery-Befehls ausgelöst werden.
Beim Pairen werden die Geräteadressen FHEM bekannt gemacht. Die Adresse der HMW Geräte ist nicht frei wählbar, sondern fest in den Geräten eingestellt. Alle HMW-Geräte haben standardmäßig die Adresse 00000001 als Zentralen-Adresse gespeichert.

=== Discovery ===
Mit dem discovery-Befehl wird der gesamte RS485-Bus nach unbekannten HMW Geräten durchsucht.
set HM485_LAN discovery start

Nachdem neue Geräte gefunden worden, werden diese automatisch mit FHEM gepairt.

== RAW-Befehle ==
Über den HM485_LAN können so genannte RAW-Befehle an die am Bus angeschlossenen Geräte gesendet werden. Mit diesen RAW-Befehlen können z.B. Funktionen ausgelöst werden, die aktuell für ein Gerät noch nicht in FHEM implementiert sind.

'''Beispiel:'''
set HM485_LAN RAW 01234567 98 00000001 DDDDDD

* 01234567 - entspricht hier der Adresse des Gerätes an das der Befehl gesendet werden soll
* 98 - das so genannte Steuerzeichen (Siehe HMW-Protokoll-Dokumentation)
* 00000001 - die HMW-ID der Zentrale (FHEM)
* DDDDDD - das sind die zu sendenden Daten.

Da zum Senden von RAW-Befehlen Kenntnisse über das HMW-Protokoll vorhanden sein sollten, lohnt sich ein Blick in die [http://forum.fhem.de/index.php?action=dlattach;topic=10027.0;attach=2441 HMW-Protokoll-Doku]

'''Funktionale Beispiele:'''
# Rollladenaktor öffnen
set HM485_LAN RAW 01234567 98 00000001 7802C8

# Rollladenaktor stoppen
set HM485_LAN RAW 01234567 98 00000001 7802C9

# Rollladenaktor schließen
set HM485_LAN RAW 01234567 98 00000001 780200

# erster Ausgang (Relais) eines HMW-IO-12-Sw14-DR ein
set HM485_LAN RAW 01234567 98 00000001 730003FF

# erster Ausgang (Relais) eines HMW-IO-12-Sw14-DR aus
set HM485_LAN RAW 01234567 98 00000001 73000000

== Wechsel von Serial/Netzwerk-RS485-Adaptern zu HMW-LAN-GW ==
Der Wechsel zwischen den verschiedenen Interface-Typen geht einfach und bedarf kein neues Pairing.
Ggf. müssen einige interfacespezifische Attribute in der fhem.cfg hinzugefügt bzw. gelöscht werden.

== Links ==

* [http://www.reichelt.de/USB-Konverter/DIGITUS-DA-70157/3//index.html?ARTICLE=122187 DIGITUS DA-70157: USB-Serial Adapter]
* [http://tigal.at/product/2276 Wiznet - WIZ108SR Compact RS422/RS485-to-Ethernet module]
* [http://forum.fhem.de/index.php/topic,14096.msg88557.html#msg88557 Wiznet - WIZ108SR im Hutschienengehäuse]
* [http://forum.fhem.de/index.php?action=dlattach;topic=10027.0;attach=2441 HMW-Protokoll-Doku]

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

HomeMatic Wired RS485 LAN Gateway

2014-08-12T19:40:40Z

Kamischi:

== Vorbemerkungen ==
Das [http://www.eq-3.de/produkt-detail-wired/items/homematic-wired-rs485-lan-gateway.html HomeMatic Wired RS485 LAN Gateway], kurz HMW-LAN-GW, stellt eine Alternative zum [[Serial/Netzwerk-RS485-Adapter]] dar. Laut Hersteller arbeitet das HMW-LAN-GW zwar nur mit der CCU2 als HomeMatic Wired Interface zusammen. Das stimmt so aber nicht. Daher kann das Modul ohne Probleme zusammen mit FHEM zur Kommunikation mit HomeMatic Wired Geräten benutzt werden.

=== HMW-LAN-GW versus Serial/Netzwerk-RS485-Adapter ===

Auf dem freien Markt gibt es jede Menge Serial / USB / Netzwerk zu RS485 Adapter. Diese Adapter gibt es teilweise bereits für wenige Euro und können zumeist als HMW Interface eingesetzt werden. Eine Liste dieser Adapter gibt es hier: [[Serial/Netzwerk-RS485-Adapter]]
Da diese Adapter keine eigene "Intelligenz" besitzen, ist hier zum Betrieb zusätzlich ein Daemon (hm485d.pl) erforderlich. Dieser wird aber, wenn entsprechend konfiguriert, automatisch gestartet und läuft in der Regel unbemerkt im Hintergrund.

== Vorbereitung ==
Bevor man das HMW-LAN-GW mit FHEM nutzen kann, müssen noch Einstellungen vorgenommen werden. Dazu braucht man die Software [http://www.eq-3.de/Downloads/eq3/downloads/HM-Cen-O-TW-x-x-2_Usersoftware_V1_1_eQ-3_130816.zip NetFinder]. Diese Java-Anwendung sollte plattformübergreifend funktionieren. Mit diesem Programm muss die netzwerkseitige AES-Verschlüsselung am HMW-LAN-GW abgeschaltet werden. Ansonsten kann FHEM derzeit nicht mit dem Gateway kommunizieren.
Mit dieser Software lässt sich auch die IP-Adresse des Gateways ändern, falls kein DHCP benutzt werden soll.

== Einbindung in FHEM ==
Zum Einbinden des HMW-LAN-GW müssen folgende Zeilen in die ''fhem.cfg'' eintragen werde:

define HM485_LAN HM485_LAN <IP Adresse>:1000
attr HM485_LAN hmwId 00000001
attr HM485_LAN room HM485

Der Name HM485_LAN kann frei vergeben werden.

HM485_LAN kennt mehrere Attribute, wichtig ist vor allem, für das HMW-LAN-GW eine Adresse festzulegen. Die HMW-ID muss eine 8-stellige Hexadezimalzahl sein.
Theoretisch könnten bis zu 256 HMW-LAN-GW angelegt werden. Diese Annahme ist aktuell aber nur Theorie und noch nicht getestet und ggf. mit einigen Problemen verbunden. Die HMW-ID's für die HMW-Interfaces könnten dafür im Bereich von 00000001 - 000000FF gewählt werden.
Da in den HMW-Geräten die HMW-ID der Zentrale aber mit 00000001 vordefiniert, sollte hier aktuell nur diese ID verwendet werden.

Zu beachten ist auch, dass das HMW-LAN-GW '''gleichzeitig''' nur <ins>eine Netzwerkverbindung</ins> erlaubt. Somit ist ein Gateway auch nur mit einer Zentrale / FHEM-Instanz zur gleichen Zeit nutzbar.

=== HM485_LAN Attribute ===
* hmwId: Hier muss die HMW-ID angegeben werden. Standardmäßig wird die 00000001 benutzt.
* do_not_notify: FileLog/notify/inform Benachrichtigung für das Gerät ist abgeschaltet.

Die folgenden Attribute sind für das HMW-LAN-GW irrelevant:
* HM485d_bind
* HM485d_startTimeout
* HM485d_device
* HM485d_serialNumber
* HM485d_logfile
* HM485d_detatch
* HM485d_logVerbose
* HM485d_gpioTxenInit
* HM485d_gpioTxenCmd0
* HM485d_gpioTxenCmd1

== Pairen von Geräten ==
Jedes HM Geräte muss vor Verwendung mit der Zentrale, hier also FHEM, gepairt werden. Anders als bei den HomeMatic-Funk-Geräten erfolgt das Pairing bei HMW automatisch, sobald ein Gerät das erste Mal eine Nachricht über den Bus versendet. Alternativ kann das Pairing auch durch das Absetzen eines Discovery-Befehls ausgelöst werden.
Beim Pairen werden die Geräteadressen FHEM bekannt gemacht. Die Adresse der HMW Geräte ist nicht frei wählbar, sondern fest in den Geräten eingestellt. Alle HMW-Geräte haben standardtmäßig die Adresse 00000001 als Zentralen-Adresse gespeichert.

=== Discovery ===
Mit dem Discovery-Befehl wird der gesamte RS485-Bus nach unbekannten HMW Geräten durchsucht.

;<code>set HM485_LAN discovery start</code>
:Nachdem neue Geräte gefunden worden, werden diese automatisch mit Fhem gepairt.

;<code>get <name> info</code>
:fragt die Grundsätzlichen Geräteeigenschaften ab. Also Typ, Seriennummer, Firmware-Version und legt die Schalter funktionsfähig in Fhem an.

;<code>get config all</code>
:liest den gesamten benutzten EEprom aus. Zu je 16 Byte Blöcken. TODO: wozu braucht man das?

== RAW-Befehle ==
Über das HMW-LAN-GW können so genannte RAW-Befehle an die am Bus angeschlossenen Geräte gesendet werden. Mit diesen RAW-Befehlen können z.B. Funktionen ausgelöst werden, die aktuell für ein Gerät noch nicht in Fhem implementiert sind.

'''Beispiel:'''
set HM485_LAN RAW 01234567 98 00000001 DDDDDD

* 01234567 - entspricht hier der Adresse des Gerätes an das der Befehl gesendet werden soll
* 98 - das so genannte Steuerzeichen (Siehe HMW-Protokoll-Dokumentation)
* 00000001 - die HMW-ID der Zentrale (Fhem)
* DDDDDD - das sind die zu sendenden Daten.

Da zum Senden von RAW-Befehlen Kenntnisse über das HMW-Protokoll vorhanden sein sollten, lohnt sich ein Blick in die [http://forum.fhem.de/index.php?action=dlattach;topic=10027.0;attach=2441 HMW-Protokoll-Doku]

'''Funktionale Beispiele:'''
# Rollladenaktor öffnen
set HM485_LAN RAW 01234567 98 00000001 7802C8

# Rollladenaktor stoppen
set HM485_LAN RAW 01234567 98 00000001 7802C9

# Rollladenaktor schließen
set HM485_LAN RAW 01234567 98 00000001 780200

# erster Ausgang (Relais) eines HMW-IO-12-Sw14-DR ein
set HM485_LAN RAW 01234567 98 00000001 730003FF

# erster Ausgang (Relais) eines HMW-IO-12-Sw14-DR aus
set HM485_LAN RAW 01234567 98 00000001 73000000

== Wechsel von HMW-LAN-GW zu Serial/Netzwerk-RS485-Adaptern ==
Der Wechsel zwischen den verschiedenen Interface-Typen geht einfach und bedarf kein neues Pairing.
Ggf. müssen einige interfacespezifische Attribute in der fhem.cfg hinzugefügt bzw. gelöscht werden.

Allerdings ist bei "nicht original"-Adaptern der Einsatz der [[hm485d.pl]] notwendig!

== Links ==
* [[HomeMatic Wired]]
* [http://www.eq-3.de/produkt-detail-wired/items/homematic-wired-rs485-lan-gateway.html HomeMatic Wired RS485 LAN Gateway (Hersteller Homepage)]
* [http://www.eq-3.de/Downloads/eq3/downloads/HM-Cen-O-TW-x-x-2_Usersoftware_V1_1_eQ-3_130816.zip NetFinder Software]
* [http://forum.fhem.de/index.php?action=dlattach;topic=10027.0;attach=2441 HMW-Protokoll-Dokumentation]

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

Dashboard

2014-08-12T19:40:17Z

Kamischi:

{{Infobox Modul
|ModPurpose=Beliebiges anordnen von Gruppen
|ModType=h


|ModTechName=95_Dashboard.pm
|ModOwner=svenson08
}}

'''Dieser Artikel wird überarbeitet'''

Das '''Dashboard''' ist ein [[:Kategorie:Hilfsmodul|Hilfsmodul]], das umfangreiche Gestaltungsmöglichkeiten für das [[PGM2]] Web-Frontend bietet. So z.B. die Anordnung von Gerätegruppen in mehreren Tabs und jeweils in mehreren Spalten mittels Drag'n Drop.

== Voraussetzungen ==
Keine speziellen Voraussetzungen erforderlich.

== Anwendung ==

=== Define ===
Die Syntax für die Definition eines Dashboards:
:<code>define <name> Dashboard</code>
Parameterbedeutung:
;name
:Eindeutiger Name des anzulegenden Dashboards.

=== Attribute ===
Das Dashboard unterstützt die folgenden Attribute:

;dashboard_activetab
:Bestimmt welches der Tabs beim Aufruf des Dashboards ausgewählt ist.
;dashboard_customcss
:Über dieses Attribut können CSS Definitionen eingegeben werden, um z.B. mit dem Wert ''body {background-image: none !important;}'' das Hintergrundbild im Dashboard zu deaktiviert werden.
;dashboard_tabcount
:Bestimmt die Anzahl der verfügbaren Tabs im Dashboard.
;dashboard_showtabs
:Bestimmt die Position der Tabs. Diese kann oben oder unten angezeigt oder komplett ausgeblendet werden. Letzteres führt dazu das dass Dashboard den Lockstate auf lock ändert.
;dashboard_showfullsize
:Zeigt das Dashboard ohne die Raumliste von FHEMWEB. Es wird dabei der gesamte linke Bereich (inkl. Raumliste und evtl. gesetzten Logo) und dem Header der Seite (inkl. Eingabezeile) ausgeblendet.
;dashboard_showtooglebuttons
:Wer die vergrößern/verkleinern nicht nutzen möchte kann dies mittels diesem Attribut deaktivieren.
;dashboard_width
:Bestimmt die Breite des Dashboards. Die Breite kann in Prozent (z.B. 80%) oder in Pixel (z.B. 1200) angegeben werden.
;dashboard_tab1groups (dashboard_tab2groups dashboard_tab3groups dashboard_tab4groups dashboard_tab5groups dashboard_tab6groups dashboard_tab7groups)
:Enthält die Auflistung der Gruppen, die im Dashboardtab angezeigt werden. Die Gruppen sind mit einem Komma zu trennen. Einer Gruppe kann ein Icons zugewiesen werden. Hierzu muss nach dem Gruppennamen '':<icon>@<farbe>'' eingefügt werden. z.B. <code>Light:Icon_Fisch@blue,AVIcon_Fisch@red,Single Lights:Icon_Fisch@yellow</code>
;dashboard_tab1name (dashboard_tab2name dashboard_tab3name dashboard_tab4name dashboard_tab5name dashboard_tab6name dashboard_tab7name)
:Bestimmt den Titel des Tabs.
;dashboard_tab1icon (dashboard_tab2icon dashboard_tab3icon dashboard_tab4icon dashboard_tab5icon dashboard_tab6icon dashboard_tab7icon)
:Anzuzeigendes Icon neben dem Titel des Tabs.
;dashboard_rowtopheight
:dashboard_webfrontendfilter
;Dem Attribut ist der Name einer FHEMWEB Instanz zu hinterlegen(z.B. WEB), möchte man das Dashboard darauf beschränken. Es können mehrere Instanzen, durch Komma getrennt, angegeben werden.
:Festlegen der Höhe der oberen Reihe des Dashboards.
;dashboard_rowbottomheight
:Festlegen der Höhe der unteren Reihe des Dashboards.
;dashboard_rowcenterheight
:Festlegen der Höhe der mittleren Reihe des Dashboards.
;dashboard_row
:Bestimmt welche Reihen im Dashboard angezeigt werden.
;dashboard_rowcentercolwidth
:Bestimmt die Breite der einzelnen Spalten der mittleren Dashboardreihe. Je Spalte kann ein separater Wert, durch Komma getrennt, hinterlegt werden. Jeder Wert bestimmt die Spaltenbreite in %.
;dashboard_colcount
:Legt die Anzahl der Spalten in der mittleren Reihe des Dashboards festgelegt.
;dashboard_tab1sorting (dashboard_tab2sorting dashboard_tab3sorting dashboard_tab4sorting dashboard_tab5sorting dashboard_tab6sorting dashboard_tab7sorting)
:Enthält die Positionierung der Gruppen im jeweiligen Tab. Es wird nicht empfohlen, dieses Attribut zu editieren.

== Anwendungsbeispiel(e) ==

== Allgemeine Hinweise ==

;Unterstützte Styles
Es werden die Styles Default, Dark und IOS7 unterstützt.

{| class="wikitable"
|Dashboard-Styles
|-
|[[Datei:dashboard_dark.png|thumb|500px|Dashboard im Style Dark]]
|-
|[[Datei:dashboard_default.png|thumb|500px|Dashboard im Default Style]]
|-
|[[Datei:dashboard_ios.png|thumb|500px|Dashboard im IOS7]]

|}

;Benötigte Dateien
Wenn vom Dashboard benötigte Dateien fehlen zeigt der STATUS des Dashboards den Hinweis ''Missing File, see LogFile for Details''. Weitere Einzelheiten zu diesem Fehler finden sich dann im Logfile. Es sollte klar sein, dass das Dashboard dann nicht (richtig) funktionieren kann.

== Erklärung / Internes ==
[[Datei:Dashboard_Menulink.png|mini|120px|Darstellung des Dashboard Menüs]]

Das Dashboard besteht in FHEM eigentlich aus zwei "Komponenten". Dem eigentlichen definierten Dashboard und einem Weblink. Es muss sich aber nicht um den Weblink für das Dashboard kümmern werden, da dieser bei Bedarf vom Dashboard eigenständig erstellt wird.

== Kleines Howto ==
;Schritt 1: Erstellen des Dashboards
:<code>define anyViews Dashboard</code>
FHEM neu starten.

;Schritt 2: Grundkonfiguration
:attr dashboard_width anyViews 80%
:attr dashboard_tabcount anyViews 3
:attr dashboard_tab1groups anyViews <GRUPPE1>,<GRUPPE2>,<GRUPPE3>

<GRUPPE1>, etc. sind durch richtige Gruppennamen zu ersetzen, z.B. Licht,Wetter oder ähnliches

[[Datei:Dashboard-KeinGruppe.png|mini|250px|"Objekt" ohne Gruppe]]
[[Datei:Dashboard-Gruppe.png|mini|250px|"Objekt" in einer Gruppe]]

Danach sollen die beiden Gruppen im 1. Tab im Dashboard angezeigt werden. Zwar noch etwas chaotisch, aber das wird in den nächsten Schritten bearbeitet. 
[[#dashboard_tab1groups| Siehe dashboard_tab1groups]]

Das Dashboard zeigt neben den beiden Gruppen bereits einiges andere mit an. Hier werden erst einmal diese "Nebensächlichkeiten" erklärt. Für die weiteren Schritte dieser Anleitung sollten die nun genannten Einstellungen unverändert bleiben.

[[Datei:Dashboard_FirstGroup.png|mini|300px|Erste Gruppe im Dashboard]]
Am rechten Rand des Dashboards erscheinen einige Schalter ("Set", "Detail"). Der Schalter "Detail" springt in die Detailansicht des Dashboards um dort z.B. weiter Attribute hinzuzufügen. 
Der Schalter "Set" speichert die per Drag'n Drop vorgenommenen Änderungen '''temporär''' (diese sind dann noch nicht gespeichert!). "Set" wird in rot geschrieben wenn die Positionierung einer Gruppe geändert wurde, aber noch nicht mit dem "Set"-Schalter gesichert wurden! Ebenso wird mit dem Schalter "Set" das aktuell [[#dashboard_activetab|aktive Tab]] gesichert 
Die Schalterleiste kann über das Attribut ''dashboard_showtabs'' deaktiviert werden, oder wahlweise über oder unter dem Dashboard platziert werden. 
[[#dashboard_showtabs| Siehe dashboard_showtabs]]
 
Im Gruppentitel erscheint an deren rechten Rand ein Symbol (+/-). Mit diesem kann man die Gruppe minimieren oder die voreingestellte Größe wieder herstellen. 
[[#dashboard_showtooglebuttons| Siehe dashboard_showtooglebuttons]]
 
[[Datei:Dashboard_Helper.png|mini|300px|Dashboard Helper]]
Zum besseren Ausrichten der einzelnen Gruppen werden zur Unterstützung einige Hilfen angezeigt. Die Erste ist die Anzeige eines Rahmens um das Dashboard. Genauer gesagt um die einzelnen Reihen/Spalten des Dashboards. Eine weitere Hilfe ist der Hintergrund der Gruppen. Dieser kann über die Mindestgröße der Gruppe hinaus gezogen werden. Damit können beliebig große Abstände zwischen den einzelnen Gruppen eingestellt werden. 
[[#dashboard_showhelper| Siehe dashboard_showhelper]]

Da nun die ersten Gruppen im Dashboard angezeigt werden, geht es nun darum, diese an die gewünschten Stellen zu platzieren. Dazu werden erst noch die verschiedenen Reihen und Spalten eingerichtet. 

Das Dashboard verfügt über drei Reihen. Oben, Mitte und Unten. In der Standardeinstellung wird nur die mittlere Reihe angezeigt. Die mittlere Reihe sollte auch immer eingesetzt werden, da diese die Breite des Dashboard vorgibt. Für dieses kleine HowTo werden aber die obere und die mittlere Reihe eingeblendet, indem das Attribut '''dashboard_row''' auf '''top-center''' gestellt wird. Diese Einstellung gilt für das gesamte Dashboard und somit für alle verwendeten Tabs. Es ist nicht möglich, je Tab eine andere Einstellung zu wählen. 
[[#dashboard_row| Siehe dashboard_row]] 

Die Breite, die das Dashboard auf dem Bildschirm einnimmt, kann über das Attribut '''dashboard_width''' festgelegt werden. Standard ist die Breite von 100%. Es kann neben einem Prozentwert auch eine Breite in Pixel angegeben werden. 
[[#dashboard_width| Siehe dashboard_width]] 

Die Höhe der einzelnen Reihen kann über die Attribute dashboard_rowtopheight für die obere Reihe, dashboard_rowbottomheight für die untere Reihe und dashboard_rowcenterheight für die mittlere Reihe festgelegt werden. Damit können die Reihen nach den eigenen Bedürfnissen angepasst werden. Für dieses HowTo wird '''dashboard_rowtopheight''' auf '''300''' und '''dashboard_rowcenterheight''' auf '''400''' eingestellt. Diese Einstellung gilt für das gesamte Dashboard und somit für alle verwendeten Tabs. Es ist nicht möglich je Tab eine andere Einstellung zu wählen. 
[[#dashboard_rowtopheight| Siehe dashboard_rowtopheight]] 
[[#dashboard_rowbottomheight| Siehe dashboard_rowbottomheight]] 
[[#dashboard_rowcenterheight| Siehe dashboard_rowheight]] 

Die mittlere Reihe hat (historisch bedingt) eine Besonderheit. Diese kann in maximal 5 Spalten unterteilt werden. Für unser Beispiel setzten wird das Attribut '''dashboard_colcount''' auf '''2'''. Diese Einstellung gilt für das gesamte Dashboard und somit für alle verwendeten Tabs. Es ist nicht möglich je Tab eine andere Einstellung zu wählen. Weiter legen wir mit dem Attribut [[#dashboard_rowcentercolwidth|dashboard_rowcentercolwidth]] die Breite der ersten Spalte mit 30% und die der zweiten Spalte mit 70% fest in dem wir dem Attribut '''dashboard_rowcentercolwidth''' den Wert '''30,70''' zuteilen. 
[[#dashboard_colcount | Siehe dashboard_colcount ]] 

Sicherlich ist das positionieren einfach, und jeder wird das hin bekommen. Zwei, drei Worte möchte ich trotzdem darüber verlieren. 

:<ins>Verschieben</ins> 
:Gruppen können in andere Reihen oder Spalten des Dashboards verschoben werden. Dazu muss in die Gruppe angeklickt werden und die Maustaste gedrückt gehalten werden. Los lässt man diese wenn man an der richtige Stelle ist. Das war wohl schon jedem klar. 
:Ein möglicher Zielort wird mit einem abgerundeten Platzhalter markiert. Dieser verschiebt auch, falls notwendig, andere Gruppen. Manchen wundert es warum dieser Zielort manchmal recht spät angezeigt wird. Dies hängt von der Position des Mauszeigers ab. Aha?! Je weiter oben man eine Gruppe anpackt, desto höher muss man die Maus schieben. Oder anders formuliert, wenn sich ca. 50% der Gruppenfläche im Zielbereich befinden wird dieser Zielort erst markiert. Das verschieben eine Gruppe von einem Tab in das andere ist nicht möglich. Letztendlich bleibt jedem nur <ins>ausprobieren</ins>. 

:Gruppen können über, unter, neben und vor anderen Gruppen verschoben werden. Auch das erfolgt wie bereits oben aufgeführt. Dies ist für viele nicht neues. Zu beachten ist aber das sich eine Gruppe nur dann vor oder neben eine anderen positionieren lässt wenn diese von der Breite in das Dashboard passen. Wenn Ihr also Gruppen nebeneinander positionieren wollt dürfen diese in Summe nicht breiter als das Dashboard sein. 
:Dies gilt nicht für die Höhen der Gruppen. Diese können in Summe höher als das Dashboard und höher als eine Reihe sein. Hier findet keine Begrenzung statt wie bei der Breite. Um jedoch das ein oder andere optisch nicht so schöne Ergebnis zu bekommen sollte darauf geachtet werden das keine Gruppe über eine Reihe hinaus ragt. 

Für unser Beispiel verschieben wir zum Testen die Gruppen in beliebige Reihen bzw. Spalten der mittleren Reihe. Danach bitte den "Set" Schalter drücken, dieser hat sich durch die verschiebe Aktionen bereits rot markiert.

[[Datei:Dashboard_Positionieren.png|mini|200px|Ausrichtung von einzelnen Gruppen]]
Das Ausrichten ist gleichermaßen einfach wie das Positionieren und sollte auch nichts Neues sein. Aber auch hier möchte ich darüber zwei, drei Worte verlieren. 

:Das Positionieren ist nur möglich, wenn das Dashboard nicht gesperrt ist (Lock/Unlock). Dann wird ein abgeschrägte Ecke an der Gruppe angezeigt, mit der die Größe gezogen werden kann.
:Jede Gruppe kann in Höhe und Breite beliebig gezogen werden, wobei genau das wieder einen Hacken hat: Das Größerziehen ist nur bedingt möglich. Die Breite/Höhe ist auf die Breite/Höhe der Dashboard Reihe (oder Spalte) begrenzt. Damit kann man eine Gruppe nicht über den Rand des Dashboards hinaus vergrößern. 
:Das Kleinerziehen ist auch nur bis zu einer Mindestgröße möglich. Die Mindestgröße ist abhängig vom Inhalt der Gruppe, kann also von Gruppe zu Gruppe unterschiedlich sein. 
:Ein Sonderverhalten beim Vergrößern/Verkleinern gibt es auch: Ist ein Gruppe höher als die Reihe, lässt sich die Gruppe zwar dort positionieren. Beim Ausrichten springt dann der untere Rand nicht auf die Mindesthöhe der Gruppe, sondern auf die maximale Höhe der Reihe. In diesem Fall sollte die Höhe der Reihe geändert werden. Ähnliches kann auch in der Breite auftreten. 
:Ändert sich der Inhalt einer Gruppe (wird z.B. ein Dummy dazugepackt), ändert sich die Positionierung der Gruppe '''nicht''' automatisch. In diesem Fall ist man immer gezwungen auch die Größe der Gruppe im Dashboard an die neue Gegebenheit anzupassen.

Für unser Beispiel ziehen wir die Gruppen beliebig größer. Danach bitte den "Set"-Schalter drücken. Dieser hat sich durch die Verschiebeaktionen bereits rot markiert.

Wie bereits etwas weiter oben erklärt wird die Positionierung der Gruppen im Dashboard durch die Betätigung des Schalters "Set" temporär zwischengespeichert. Dadurch wird die Positionierung bereits für einen Seitenrefresh gespeichert. Solange bis das Browserfenster geschlossen wird. Danach wären diese Einstellungen verloren. 
Darum ist es notwendig die Positionierung permanent zu speichern, damit auch nach einem Neustart von Fhem die getroffenen Einstellungen und Positionierungen vorhanden sind. Dies geht über den in Fhem bekannten weg über ''Save config''. 
Wird der Schalter "Set" nicht betätigt, wird auch über ''Save config'' die Positionierung nicht gespeichert. Daher ist es wichtig, immer '''zuerst''' mit dem Schalter '''"Set"''' die Einstellung zwischenzuspeichern und '''danach mit ''Save config''''' den Zwischenspeicher permanent zu sichern. 

Durch den Schalter "Set" wird für jedes Tab die Einstellung in das für das jeweilige Tab zuständige Attribut geschrieben. Für Tab 1 ist das Attribut ''dashboard_tab1sorting'' zuständig, für Tab 2 das Attribut ''dashboard_tab2sorting'', usw. '''Diese Attribute sollten nicht editiert werden!'''

Es ist möglich jedem Tab einen eigenen individuellen Namen zu vergeben. Dazu ist für das jeweilige Tab das entsprechende Attribut zu befüllen. Z.B. für Tab 1 ist das Attribut ''dashboard_tab1name'' mit dem gewünschten Titel zu füllen. 
[[#dashboard_tab1name| Siehe dashboard_tab1name]]

== Letzte Änderungen / Dashboard-Historie ==

* (03.03.2014) Anzeigefehler bei readingGroups in einem Hiddenroom behoben
* (17.03.2014) Fehlerausgabe durch dashboard_webfrontendfilter behoben
* (26.03.2014) dashboard_showfullsize wird nicht im Raum "all" bzw. Everything angewendet
* (18.04.2014) Attribut dashboard_lock State entfernt. Kann nur noch in der Detailansicht verändert werden.
* (24.04.2014) Attribut dashboard_showhelper wird nicht mehr genutzt. Der Helper wird nur angezeigt wenn lockstate unlock ist.
* (24.04.2014) Schalter Detail und Set werden nun rechts angezeigt.
* (24.04.2014) Attribut dashboard_showtabs kann nicht mehr tabs-at-the-top-buttonbar-hidden oder tabs-on-the-bottom-buttonbar-hidden sein.

== Links ==
* [http://forum.fhem.de/index.php/topic,16503.0.html Forenthread] über ''Dashboard''

[[Kategorie:Hilfsmodul]]
[[Kategorie:HOWTOS]]

WebViewControl

2014-08-12T19:39:38Z

Kamischi:

[[File:WebViewControl_Icon.png|mini|rechts|WebViewControl]]
'''WebViewControl''' ist eine APP, die auf Phonegap basiert und per WebView einen Fullscreen-Browser zur Verfügung stellt. Dieser kommuniziert zusätzlich per Javascript mit dem Android-Gerät und stellt so einige Geräteeigenschaften zur Verfügung.

Darüber können dann einige Funktionen wie z.B. die Bildschirmhelligkeit und der Batteriestatus per Fhem-Modul zur Verfügung gestellt, ausgewertet und auch gesteuert werden.


Im Fhem-Forum ist im ersten Beitrag [http://forum.fhem.de/index.php/topic,10628 dieses Threads] jeweils die aktuelle Version zu finden.

== Anforderungen ==
Grundsätzlich kann die APP mit jeder Website zusammen benutzt werden. Für Fhem ist jedoch ein Modul verfügbar, damit Fhem einfach mit der APP zusammenarbeiten kann. Dafür sind folgende Anforderungen zu erfüllen:
* Ein laufendes Fhem.
* aktiviertes Longpoll (Die Kommunikation zwischen Fhem zur APP erfordert aktiviertes Longpoll).
* Android ab Verion 2.3.3 besser jedoch Android ab Version 4

== Screenshots ==
<gallery>
File:WebViewControl_screenshot_01.png|Aktive Spracherkennung
File:WebViewControl_screenshot_02.jpg|Eine Toastmessage
File:WebViewControl_screenshot_03.jpg|Menü
</gallery>

== Verfügbare Funktionen ==
=== Fullscreen Browser ===
{{Randnotiz|RNText=Der Fullscreen-Mode wird nicht von allen Geräten unterstützt.}}
Ab Android 4 Ice Cream Sandwich (ICS) (oder auch schon seit Version 3?) ist auf den meisten Geräten die "System-Bar" am unteren Rand nicht ausblendbar. Es sei denn, das ROM des Gerätes unterstützt das. Das geht zwar auch mit einem gerooteten Gerät, das wollte ich hier aber nicht vorraussetzen. Beim "Archos 10D G3" wird das Ausblenden der "System-Bar" z.B. unterstützt.

=== Eigene APP-ID ===
Jeder APP kann eine eigene APP-ID zugewiesen werden. So können im Netzwerk mehrere APPs direkt adressiert werden.

Nach dem Ändern der APP-ID muss die App neu gestartet werden.

=== Autostart ===
Im Menü kann eingestellt werden, ob die APP nach einem Booten des Gerätes automatisch startet.

=== Bildschirm eingeschaltet lassen ===
Per Menüeinstellung, per Javascript bzw. per Fhem kann eingestellt werden, ob der Bildschirm bei laufender App eingeschaltet bleibt.

=== Ändern der Bildschirmhelligkeit ===
Die Bildschirmhelligkeit kann per Javascript und über FHEM eingestellt werden.

=== Toast Nachrichten ===
Kurze, sogenannte Toast-Nachrichten, können an das Gerät per Javascript und per Fhem gesendet werden.

=== Netzwerk- und Batteriestatus ===
Der Batterie- und Netzwerkstatus kann vom Gerät per Javascript abgefragt werden. Mit diesen Informationen wird z.B. in der rechten unteren Ecke der Fhem-Weboberfläche ein entsprechendes Icon angezeigt. (Netzwerk wird derzeit nur grün, wenn eine WIFI- oder Ethernet-Verbindung aktiv ist.)

=== Abspielen von Audio Dateien ===
Es können Audiodateien vom Netzwerk oder internen Speicher / von SD-Karte abgespielt werden.

=== TTS (Text To Speach) ===
Es können Sprachausgaben per Javascript bzw. von FHEM aus ausgelöst werden. Damit können z.B. Statusinformation per Sprache ausgegeben werden.

=== Spracherkennung ===
Nutzung der Spracherkennungs-API. Somit ist es möglich, die angezeigte Webseite und auch Fhem per Sprache zu steuern. Es kann dann ein Wort bzw. eine Wortgruppe gesprochen werden (z.B. "Wohnzimmer Licht an"), das direkt per ''Notify'' in Fhem ausgewertet werden kann. Per Fhem und per Tap auf das Batterie-Icon wird am Gerät die Spracherkennung gestartet. Der "Tap" auf das Batteriesymbol ist derzeit eine "Notlösung", weil es noch keine bessere Idee gab.
Zusätzlich kann die Erkennung durch Fhem gestartet werden.

== Installation ==
Im Zip-Archiv befinden sich folgende Dateien:
* 95_WebViewControl.pm - kommt in den Ordner Fhem (als Kopie oder als Symlink)
* webviewcontrol.css und webviewcontrol.js - kommen in den Ordner /www/pgm2
* WebViewControl.apk - das ist die APP und muss auf dem Android Gerät installiert werden.
* Die Phonegap JS-Library wurden von der WebViewControl-JS-Datei entkoppelt. Daher muss cordova-2.3.0.js in www/pgm2.
* mic_sprite.png muss in den Images-Ordner.

Da die APP noch nicht aus dem Playstore kommt und auch keine qualifizierte Signatur hat, muss zum Installieren der APP in den Einstellungen des Android Gerätes im Punkt Sicherheit die Einstellung "Unbekannte Quellen" aktiviert sein. Das kann nach der Installation wieder deaktiviert werden.

== Angeforderte Berechtigungen ==
Die App verlangt bei der Installation die folgenden Berechtigungen
* Netzkommunikation (sonst könnte die App keine Webseiten öffnen)
* System-Tools (für das Deaktivieren des Standby-Modus)
* Netzwerkkommunikation (zum Abfragen des Netzwerkstatus)
* System-Tools (für den Autostart nach dem Booten)

== Konfiguration der APP ==
Beim ersten Start der APP muss diese an einigen Punkten konfiguriert werden.
* Start-URL (die komplette URL, unter der die Fhem-Weboberfläche erreichbar ist)
{{Randnotiz|RNTyp=y|RNText=Die Start-URL muss derzeit komplett mit Protokoll eingegeben werden, also beispielsweise als '''http://'''192.168.1.1:8083/fhem}}
* APP-ID (die APP-ID unter der FHEM die APP finden kann; Standard=12345)
* Username / Password (falls die FHEM-Weboberfläche passwortgeschützt ist, muss das hier entsprechend eingegeben werden)
* Autostart (falls dieser Punkt aktiviert ist, startet die APP nach dem Booten von Android automatisch)
* Bildschirm eingeschaltet lassen (der Bildschirm bleib an, wenn die externe Stromversorgung angeschlossen ist)
* Cache löschen (die Webview der App hat einen internen Cache. Wenn dieser Punkt aktiv ist wird der Cache beim Starten der APP und beim Neuladen gelöscht)
* URL Timeout (hier kann (in Millisekunden) eingestellt werden, wie lange die APP beim Laden einer URL wartet, bevor eine Fehlermeldung angezeigt wird)
* Entwickler-Optionen im Hauptmenü (wenn diese Option aktiv ist, werden einige zusätzliche Menüpunkte im Hauptmenü eingeblendet (Cache löschen / Display Helligkeit testen))

== Konfiguration in Fhem ==
Die folgenden Definitionen sind in der Fhem [[Konfiguration]] vorzunehmen:
:<code>define <name> WebViewControl <app-id></code>

Beispiel
:<code>define androidTablet WebViewControl 12345</code>
Die app-id (hier 12345) ist dieselbe Zeichenfolge, die auch in der APP eingestellt wird. So können unterschiedliche APPs mit Fhem adressiert werden. Standardmässig ist als APP-ID in der APP 12345 eingestellt.

== Steuerungsmöglichkeiten per Fhem (set) ==
Bildschirm bei aktiver APP eingeschaltet lassen:
:<code>set androidTablet keepScreenOn [on|off]</code>

Aktuelle Seite im der Weboberfläche neu laden. Kann während der Entwicklung ganz nützlich sein:
:<code>set androidTablet reload</code>

Bildschirmhelligkeit ändern:
:<code>set androidTablet screenBrightness [WERT]</code>
Der Wert kann mit 1-255 eingegeben werden. Allerdings ist es geräteabhängig, was z.B. als Maximalhelligkeit angesehen wird. Hier muss ggf. experimentiert werden. Üblich sind Werte von 1 bis 100 oder auch 1 bis 255. Sollte die Helligkeit nach 100 z.B. wieder abnehmen, dann wäre 100 der Maximalwert.

Kurze Nachrichten auf dem Gerät anzeigen:
:<code>set androidTablet toastMessage [NACHRICHT]

URL der angezeigten Seite wechseln:
:<code>set <webViewControl_Name> newUrl <url></code>

Die URL muss auch hier komplett angegeben werden. Also http://...
Man kann hier übrigens JEDE URL angeben. Auch z.b. die von Google.
Dabei verlässt man dann aber den "Einflussbereich" von FHEM. Somit ist anschließend keine weitere Kommunikation möglich.
Daher ist es Sinnvoll hier NUR FHEM URLs anzugeben.

Da man hier beliebige URLs an die APP übergeben kann, auch so was hier:
:<code>set <webViewControl_Name> newUrl javascript:alert('Huhu!')</code>
Hiermit könnte man hier natürlich auch "bösartigen" JS-Code einschleusen.
Natürlich kann man über diesen Weg auch einfach Benutzer definierten Javascript-Code ausführen.
Hier können wir noch mal diskutieren ob ich die Eingaben hier noch entsprechend filtern soll.

Spracherkennung per FHEM starten:
:<code>set androidTablet voiceRec start</code>
Nachdem die Erkennung gestartet wurde, gibt es ein Tonsignal und ein Overlay (siehe Screenshot oben). Wenn die Erkennung erfolgreich war, also was erkannt wurde, gibt es ein anderes Tonsignal und kurz eine entsprechende Grafik im Overlay. Bei einem Fehler gibt es auch einen Ton und eine entsprechende Grafik mit einem Fehlertext. Der Fehlertext wird genau wie das erkannte Wort/Wortgruppe an FHEM gemeldet und kann dort z.B. mit einem Notify ausgewertet werden. Nach einer erfolgreichen Erkennung bzw. einem Fehler wird das Overlay automatisch wieder geschlossen, es ist also keine Benutzerinteraktion notwendig.

Beispiel für den Notify für die Spracherkennung
:<code># Licht im Wohnzimmer einschalten</code>
:<code>define speechRecognizer_wzLich_ein notify .*voiceRecognitionLastResult.*licht.*wohnzimmer.*(ein|an).* set wzLicht on;; set @ ttsSay Licht im Wohnzimmer eingeschaltet</code>

:<code># Licht im Wohnzimmer ausschalten</code>
:<code>define speechRecognizer_wzLich_aus notify .*voiceRecognitionLastResult.*licht.*wohnzimmer.*aus.* set wzLicht off;; set @ ttsSay Licht im Wohnzimmer ausgeschaltet</code>

:<code># Einfaches echo</code>
:<code>define speechRecognizer_echo notify .*voiceRecognitionLastResult.* {my @@a=split(": ","%");; fhem "set @ ttsSay $a[1]"}</code>

Beide Beispiele zusammen funktionieren anscheinend nicht. Das echo-Notify "drängelt" sich immer vor, die anderen werden dann nicht mehr ausgeführt. Vielleicht hat ja jemand eine Idee.

Die Spracherkennung ist übrigens noch experimentell:
* Ein Abschalten einer laufenden Erkennung ist noch nicht implementiert. Die Erkennung stoppt aber, wenn keiner mehr was sagt.
* Vermutlich gibt es noch einige Bugs

== Informationen per FHEM abrufen (get) ==
Akku-Ladestand abrufen:
:<code>get androidTablet powerLevel</code>

Einige Geräte, speziell das "Archos 10D G3" haben hier allerdings Probleme. Der "echte" Akkuzustand wird hier nur angezeigt, wenn keine externe Stromversorgung angeschlossen ist. Mit externer Versorgung zeigt das Gerät immer 100% an.

Energie-Status abrufen:
:<code>get androidTablet powerPlugged</code>
Zeigt an ob das Gerät an einer externen Energieversorgung angeschlossen ist.

== Links ==
* [http://forum.fhem.de/index.php/topic,10628 Thread] im Fhem-Forum zu dieser Applikation
* [http://forum.fhem.de/index.php?action=dlattach;topic=10628.0;attach=12329 aktuelle Version 0.4 der APP]

[[Kategorie:FHEM Frontends]]