FHEMWiki - Benutzerbeiträge [de]

Mi vacuum

2019-04-03T13:00:11Z

Arne: Alternative Installation von 72_XiaomiDevice.pm

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

:Alternativer Weg: (als User fhem angemeldet) wget -O /opt/fhem/FHEM/72_XiaomiDevice.pm https://raw.githubusercontent.com/mhop/fhem-mirror/master/fhem/FHEM/72_XiaomiDevice.pm; chown fhem:dialout /opt/fhem/FHEM/72_XiaomiDevice.pm

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

Wie kommt das Modul nun auf den eigenen RasPi?

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

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

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

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

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

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

bringt die Datei in euer FHEM Verzeichnis.

Jetzt noch die Rechte anpassen:

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

Fertig.

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

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

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

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

attr Mi_Vacuum subType VacuumCleaner
</pre>

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

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

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

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

Mein DOIF:

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

Das Attribut do always nicht vergessen!

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

Fertig.

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

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

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

Entweder direkt über die Werte:

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

Oder über die passenden Attribute erst ein Alias anlegen:

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

Ein Alias kann dann wie folgt genutzt werden:

<pre>
set vacuum zone home
</pre>

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

Raspberry Pi

2018-07-14T22:09:52Z

Arne: Info, wie SSH notfalls auch später aktiviert werden kann, eingefügt.

Beim '''Raspberry Pi''' handelt es sich um einen postkartengroßen Einplatinen-Computer, der von der Raspberry Pi Foundation entwickelt wird. Die Hardware basiert auf dem BCM 283x SoC (System-on-Chip) von Broadcom, einem ARM-Prozessor. Zu Hardwaredetails und den verschiedenen Modellen sowie Produktentwicklungen siehe [http://de.wikipedia.org/wiki/Raspberry_Pi#Hardware Wikipedia].
Dank der kleinen Abmessungen, dem recht geringen Energieverbrauch (bis ca. 4 Watt) sowie der günstigen Anschaffungskosten (ca. 30€) ist der Raspberry Pi eine attraktive Hardware für die Heimautomatisierung mit FHEM. Er ist dank dem Linux-Betriebssystem vollständig kompatibel zur aktuell vorhandenen und von FHEM unterstützen Hardware. Das derzeit empfohlene Standard-Image zum Betrieb des Raspberry Pi ist die auf Debian basierende Raspbian Distribution.

== Installation / Setup ==
=== Betriebssystem ===
====Vorbemerkung====
Raspbian ist direkt bei raspberrybi.org unter [https://www.raspberrypi.org/downloads/raspbian/ https://www.raspberrypi.org/downloads/raspbian/] herunterladbar. Die folgende Anleitung gilt für die lite-Version ohne grafischen Desktop und für die Modelle für B, B+, B2, B3, B3+, Zero W. (Stand Juni 2018)

Alle in diesem Abschnitt verwendeten Code Blöcke benötigen root Rechte. Deshalb bitte immer am Besten im Kontext <code>sudo su</code> ausführen. Man kann auch einzelne Befehle mit sudo davor ausführen, allerdings wird die Berechtigung bei Pipe Befehlen nicht durchgereicht.

Alle Dateien müssen im Linux Format (nur lf als Zeilenende) erzeugt/editiert werden! Unbedingt einen geeigneten Editor verwenden und auf das Format beim speichern achten!

====SD-Karte vorbereiten====
Die heruntergeladene Datei muss entpackt und auf die Speicherkarte geschrieben werden. Es gibt dazu verschiedene Tools je nach Betriebssystem. Für Windows ist windisk32imager zu empfehlen Projektseite [https://sourceforge.net/projects/win32diskimager/].

Detaillierte Anleitungen zur Vorgehensweise finden sich für die Betriebssysteme Linux, Mac OS und Windows unter [https://www.raspberrypi.org/documentation/installation/installing-images/README.md Writing an image to the SD card]

Die SD Card enthält nun zwei Partitionen/Laufwerke, das erste Laufwerk ist unter alle Betriebssystemen lesbar. In diesem Laufwerk (/boot) müssen jetzt noch zwei Dateien erzeugt werden:
* eine leere Datei mit dem Namen ssh um den (headless) Zugriff per ssh zu ermöglichen. Hinweis: Eine spätere Aktivierung von SSH ist mit <code>sudo raspi-config</code> (Punkt 5 "Interfacing Options", dann Punkt 2 SSH) möglich, erfordert dann aber Tastatur und Monitor am RPi.
* eine Textdatei im Linux Format mit Namen wpa_supplicant.conf und folgendem Inhalt wenn der Pi sofort mit wlan starten soll.

<pre>country=DE
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
ssid="FRITZ!Box 7490"
psk="12345678901234567890"
</pre>
* SD Karte auswerfen.
* SD Karte in Raspberry Pi stecken und booten.

Alternativ kann auch Monitor und Tastatur verwendet werden.

====Anmeldung und Grundkonfiguration====
Mit einem Terminal Programm verbindet man sich per ssh (z.B. Windows -> Putty) auf den Host <code>raspberrypi</code> und meldet sich mit User pi und Passwort raspberry an.
* Unbedingt Passwort ändern! -> Dem Sicherheitshinweis folgen und <code>passwd</code> eingeben.

Jetzt muss noch Zeitzone, Sprache und Hostname angepasst werden.
Entweder Menügeführt mit <code>sudo raspi-config</code>
oder per Script / Shell Befehle:

<source lang="bash"># Zeitzone
timedatectl set-timezone Europe/Berlin

# Konfigurieren lokale Sprache deutsch
sed -i -e 's/# de_DE.UTF-8 UTF-8/de_DE.UTF-8 UTF-8/' /etc/locale.gen
locale-gen
localectl set-locale LANG=de_DE.UTF-8 LANGUAGE=de_DE

# Hostname
hostnamectl set-hostname mymachine

#Neustart
reboot</source>

====Verwendung UART für Zusatzmodule====
Einige Aufsteckmodule (z.B. HM-MOD-RPI-PCB) für den GPIO Port verwenden dort die serielle Schnittstelle UART. Der Zugriff auf diese serielle Schnittstelle erfordert eine modellabhängige Konfiguration.

Bei allen Modellen muss die Verwendung der seriellen Linux console an ttyAMA0 deaktiviert werden:
<source lang="bash"># seriell-getty Dienst für ttyAMA0 dauerhaft deaktivieren
systemctl stop serial-getty@ttyAMA0.service
systemctl disable serial-getty@ttyAMA0.service
systemctl mask serial-getty@ttyAMA0.service
</source>
Bei den Modellen mit Bluetooth muss die UART aktiviert und umkonfiguriert werden:
<source lang="bash"># serielle Schnittstelle aktivieren und mit BT Schnittstelle tauschen
echo "enable_uart=1" >> /boot/config.txt
echo "dtoverlay=pi3-miniuart-bt" >> /boot/config.txt
echo "core_freq=250" >> /boot/config.txt
</source>
Um die Konfiguration abzuschließen ist ein Neustart erforderlich
<source lang="bash">#Neustart erforderlich
reboot</source>

====Troubleshooting====
'''Kontrolle der seriellen Schnittstelle'''

Der Befehl <code>ls -l /dev/ttyAMA0</code> muss folgende Ausgabe liefern.
crw-rw---- 1 root dialout 204, 64 Jun 7 22:56 /dev/ttyAMA0
Sollte dies nicht der Fall sein, muss der Dienst serial-getty@ttyAMA0.service deaktiviert werden!

Kontrolle der Verlinkung von /dev/serial*

Der Befehl <code>ls -l /dev/serial*</code> muss folgende Ausgabe liefern.
* Bei Modellen mit BT und richtiger Konfiguration
lrwxrwxrwx 1 root root 7 Jun 7 22:55 /dev/serial0 -> ttyAMA0
lrwxrwxrwx 1 root root 5 Jun 7 22:55 /dev/serial1 -> ttyS0
* Bei den Modellen ohne BT und richtiger Konfiguration
lrwxrwxrwx 1 root root 7 Jun 8 18:30 /dev/serial0 -> ttyAMA0
Sollte das nicht der Fall sein, sind die Einträge in der /boot/config.txt fehlerhaft.

'''Kontrolle Bluetooth'''

Die Funktion von Bluetooth kann mit dem hcitool überprüft werden. Mit <code>hcitool dev</code> wird das interne BT Gerät mit MAC Adresse angezeigt. Mit <code>hcitool scan</code> bzw. <code>hcitool lescan</code> kann nach sichtbaren Geräten gesucht werden.

Weitergehende Informationen zur Anpassung der Konfiguration von Raspbian sind nachzulesen auf [https://www.raspberrypi.org/documentation/configuration/ https://www.raspberrypi.org/documentation/configuration/].

=== FHEM ===
Die Installation von FHEM kann nach der Raspbian-Installation sehr einfach über das Debian-Repository [http://debian.fhem.de] erfolgen.
* Es wird unbedingt empfohlen zur Grundinstallation zunächst keine Module, USB Sticks oder ähnliche Zusatzbaugruppen an den IO Ports des Raspberry gesteckt zu haben.
* Dieser Abschnitt beschreibt nur die Grundinstallation von FHEM auf einem Raspberry Pi mit Raspbian!
* Weitere Installationsschritte sind je nach verwendeten FHEM-Modulen notwendig.
** Informationen hierzu liefert üblicherweise die {{Link2CmdRef}} zum jeweiligen Modul.
** Den weiteren Einstieg in FHEM findet man im Artikel [[Quick-Start]]

==== Der einfache Weg zum aktuellen System ====
Der folgende Befehlsblock ist die praktische Umsetzung der Beschreibung auf [http://debian.fhem.de http://debian.fhem.de]. Bitte unbedingt vor Installation rückversichern, ob es dort Aktualisierungen gab.
* Dieser Befehlsblock erfordert erhöhte Rechte also bitte als Erstes <code>sudo su</code> ausführen!
<source lang="bash"># von debian.fhem.de installieren - siehe aktuelle Anleitung dort https://debian.fhem.de/
wget -qO - http://debian.fhem.de/archive.key | apt-key add -
echo "deb http://debian.fhem.de/nightly/ /" >> /etc/apt/sources.list
apt-get update
apt-get install fhem
</source>

==== Das offizielle Release ====
Alternativ kann FHEM mit dem Debian-Paket von fhem.de installiert werden. Dieser Weg führt zu einem offiziellen Release, welches aber unter Umständen erheblich vom aktuellen Versions- und Diskussionsstand im Forum abweicht.

Je nach Release Stand sind grundlegenden Perl-Pakete notwendig. Deshalb wird die Installation hier über die Auflösung von Abhängigkeiten beschrieben.
<source lang="bash"># fhem-X.Y.deb bitte mit der auf http://fhem.de/fhem.html#Download aktuellsten, stabilen Version ersetzen
wget http://fhem.de/fhem-5.8.deb
sudo apt-get update
# Der nächste Schritt erzeugt einen zu erwartenden Fehler, erst mit dem letzten Schritt wird wirklich installiert
sudo dpkg -i fhem-5.8.deb
sudo apt-get install -f
</source>
Ein aktuelles FHEM System erhält man nur durch ein manuelles <code>update</code> in der FHEM Umgebung - oder gleich nach dem Setup in der Kommandozeile des System.
<source lang="bash"># Ausführung des update Kommandos in FHEM ueber ein Shell Kommando
/opt/fhem/fhem.pl 7072 "update"
</source>

==== Empfohlener Patch ====
Da gerade auf dem Raspberry die automatische Erkennung der USB Schnittstellen zu 100% CPU Last führt (FHEM träge und reagiert nicht), wird empfohlen sofort nach der Installation noch diesen "Patch" auszuführen. Sollte an dieser Stelle schon der USB Check beim automatischen Start von FHEM nach der Installation zum Problem geführt haben, hilft nach dem Patch ein einfacher <code>reboot</code> des Systems.
<source lang="bash"># Den USB Check abschalten
/opt/fhem/fhem.pl 7072 "attr initialUsbCheck disable 1"
/opt/fhem/fhem.pl 7072 "save"
</source>

==== Deinstallation ====
Man kann FHEM auch wieder spurlos vom System entfernen und ganz von vorn beginnen. Allerdings sollte man sich im Klaren sein, damit ensteht kein jungfräuliches System!
<source lang="bash">sudo apt-get purge fhem
sudo apt-get autoremove
</source>

=== Nützliche Zusatzpakete ===
Nachdem der Rpi eingerichtet ist, können weitere Pakete installiert werden. Keines davon ist zwingend erforderlich, um FHEM grundsätzlich betreiben zu können. Einige Pakete erhöhen aber den Bedienungskomfort oder sind zur Nutzung bestimmter FHEM-Module (siehe {{Link2CmdRef}}) erforderlich. Hier eine Übersicht.
{| class="wikitable"
! style="width:10%" | Beschreibung
! style="width:10%" | Paketname
! style="width:50%" | Kontext
! style="width:30%" | Installieren
|-
|Zeitserver
|ntpdate
|Setzt die Systemzeit bei Start des RPi. Wird für FHEM benötigt, da es sonst nicht startet.
|<code>sudo apt-get install ntpdate
sudo ntpdate -u de.pool.ntp.org</code>
|-
|Perl JSON
|JSON
|Wird von einigen Modulen benötigt, z.B. harmony, iTunes
|<code>sudo apt-get install libjson-perl</code>
|-
|Samba-Server
|samba
|Mittels Samba kann man z.B. den Ordner /opt/fhem als Share freigeben. Dieser Share kann z.B. im Windows-Explorer als Laufwerk verbunden werden, so dass die Bearbeitung von config- und Programmdateien bequem möglich ist. Hier eine hilfreiche [https://www.elektronik-kompendium.de/sites/raspberry-pi/2007071.htm Kurzanleitung] aus der (wenn man auf einen speziellen user verzichtet) nur die Einträge für smb.conf gesetzt werden müssen.
|<code>sudo apt-get install samba cifs-utils</code>
Danach muss der share definiert werden mittels

<code>sudo nano /etc/samba/smb.conf</code>
|-
|Mailversand
|sendEmail (bzw. sendemail)
|Wird benötigt, um Mails versenden zu können, bspw. für Alarm-Benachrichtigungen.
Nach Installation des Paketes benötigt man noch eine Routine in FHEM gemäß [[E-Mail senden#Raspberry Pi]]
|<code>sudo apt-get install sendEmail</code> bzw. <code>sudo apt-get install sendemail</code>
|-
|Wake-on-LAN
|etherwake
|Wird z.B. für das Modul WOL benötigt.
|<code>sudo apt-get install etherwake</code>
|-
|Perl Telnet
|telnet
|Wurde vor Fritz!OS 6.2x z.B. für das Modul [[FRITZBOX]] benötigt, da es eine im Netzwerk vorhandene Fritzbox über deren Telnet-Port ansprach. Mittlerweile wird TR-64 und SOAP verwendet.
|<code>sudo apt-get install libnet-telnet-perl</code>
|-
|Socat
|socat
|Kann verwendet werden, um auf anderen Rechnern im Netzwerk Linux-Befehle oder Skripts auszuführen. Auch können auf Slave-FHEM-Installationen Befehl ausgeführt werden, z.B. mit

<code><nowiki>system("echo 'set lampe on' | /usr/bin/socat - TCP:1.2.3.4:7072");</nowiki></code>

1.2.3.4 muss natürlich durch die IP-Adresse des Zielrechners ersetzt werden.
|<code>sudo apt-get install socat</code>
|-
|Libcrypt
|Libcrypt
|Perl libcrypt, erforderlich falls Homematic-devices mit AES verwendet werden sollen.
|<code>sudo apt-get install libcrypt-rijndael-perl</code>
|-
|libdatetime
|libdatetime
|Perl libdatetime, erforderlich für das Weather-Modul.
|<code>sudo apt-get install libdatetime-format-strptime-perl</code>
|}

== Bekannte Probleme ==
=== Netzteil ===
Der RPi verwendet ein USB Netzteil als Spannungsversorgung. Gemessen kann der RPi allein bereits um die 900mA Strom fordern. Das bringt kleine Netzteile, besonders wenn noch CULs oder WLAN Sticks an USB hängen schnell an die Grenze. Die Fehler die daraus resultieren sind Abstürze, Netzwerkprobleme uvm. Daher bitte ein ausreichend starkes Netzteil mit mind. 2000mA oder einen aktiven USB-HUB für die Periperie verwenden.

=== Echtzeituhr ===
Der RPi hat keine [http://de.wikipedia.org/wiki/Echtzeituhr Real-Time-Clock] (RTC), das heißt, dass er nach einem Neustart keine gültige (im Sinne von aktuell) Systemzeit hat, sondern ein Datum in der Vergangenheit. Dieses Problem wird sinnvollerweise mit einer [http://de.wikipedia.org/wiki/Network_Time_Protocol NTP-Konfiguration] oder durch [[Raspberry Pi: RTC Hat|Installation einer Echtzeituhr]] umgangen.

Dabei muss Sorge getragen werden, dass der [http://wiki.debian.org/NTP ntpd] schon einen Datums-/Zeitabgleich gemacht hat, bevor FHEM gestartet wird. Geschieht der Abgleich nicht vorher, sondern erst nachdem FHEM schon läuft, stellt FHEM die Logs zwar auf das nun aktuelle Datum um (die "alten" Logs mit dem eigentlich ungültigen Datum werden natürlich behalten), aber irgendetwas scheint FHEM dabei so zu belasten, dass es eine Last von über 0.8 bis 0.9 erzeugt. Diese Last besteht auf Dauer und verschwindet erst, wenn man das Ganze sauber durchkonfiguriert und FHEM neu gestartet hat. Die hohe Systemauslastung zeigt sich auch in einem sehr trägen Laden der FHEM-Webseiten in einem beliebigen Browser. (siehe {{Link2Forum|Topic=70741}})

=== Last durch Backup (während update) ===
Bei einen [[Update]] von FHEM durch den Befehl <code>update</code> kann durch Setzen des Attributs "<code>attr global backup_before_update 1</code>" automatisch vorab ein [[Backup]] durchgeführt werden. Die (ggf. großen) Log-Dateien werden dabei ebenfalls archiviert. Während der Archivierung ist FHEM blockiert. Durch die beschränkte Leistungsfähigkeit des Raspberry Pi kann das Backup zudem lange dauern. Durch ein "<code>attr global updateInBackground 1</code>" wird ein Backup im Hintergrund ausgeführt (Quelle: {{Link2Forum|Topic=15729}}).

Alternative Möglichkeiten:
* Backup ausschalten und manuell durchführen
* Backup-Befehl anpassen und so große Dateien bzw. Verzeichnisse (log/) nicht archivieren

== Watchdog einrichten ==
Man kann den RPi alle halbe Stunde prüfen lassen, ob FHEM noch läuft und gegebenenfalls einen Neustart durchführen lassen. Eine mögliche Vorgehensweise ist in diesem {{Link2Forum|Topic=20553|LinkText=Forumsthema}} beschrieben.

== Interne Links ==
* [[CUL am Raspberry Pi flashen]]
* [[Raspberry Pi und 1-Wire]]

== Externe Links ==
* {{Link2Forum|Topic=33460|Message=264679}} zum Umzug von Raspberry B auf Raspberry Pi 2
* [http://www.raspberrypi.org/ Offizielle Webseite der Raspberry Pi Foundation]
* [http://www.raspberrypi.org/downloads Offizielle Downloads der Raspberry Pi Foundation]

[[Kategorie:Raspberry Pi]]
[[Kategorie:HOWTOS]]

EIB FAQ

2017-02-15T20:03:14Z

Arne: Weiteren Link hinzugefügt

Antworten auf häufig gestellte Fragen im Bereich [[:Kategorie:EIB/KNX|EIB (/KNX)]]

;Alle Lampen wurden automatisch erkannt und können nun geschaltet werden. Wie erkenne ich aber nun die Schalter?
:Im EIB sind alle Geräte intelligent und kommunizieren im Normalfall dezentral. Das heisst, ein Taster steuert direkt eine Lampe an, indem er den entsprechenden Befehl auf den Bus sendet. Somit kann FHEM nur erkennen, dass ein entsprechender Schaltbefehl für eine Lampe von einem anderen Gerät gesendet wurde, aber nicht von welchem.
:Diese Kommunikation lässt sich aber auch zentralisieren. Ein Taster sendet dann einen Befehl an eine Adresse, die keiner Lampe zugeordnet ist. Diesen Befehl kann dann eine zentrale Steuerung (wie FHEM) aufgreifen und in Befehle für die Lampen umwandeln. Nachteil: fällt die zentrale Steuerung aus, fällt das ganze System aus.
:Oftmals ist der Mittelweg der richtige: alle Lampen werden direkt von Tastern gesteuert, man benutzt aber zusätzliche Taster um spezielle Funktionalitäten (z.B. Lichtzenen) zu realiseren. Ein Ausfall der zentralen Steuerung legt somit nicht das komplette System lahm.
:Um das Verhalten der Taster zu ändern, müssen jedoch die Taster direkt umprogrammiert werden. Dies ist nicht mit FHEM möglich, sondern nur mit der Zusatzsoftware [https://redaktion.knx-user-forum.de/lexikon/ets/ ETS]. Siehe auch [https://de.wikipedia.org/wiki/KNX-Standard#Steuerung_und_Programmierung KNX Programmierung (Wikipedia)]

;Ist es möglich den Status von EIB-Sensoren direkt abzufragen anstatt warten zu müssen, bis ein neuer Wert auf dem Bus auftaucht?
:Der EIB und entsprechende Geräte verfügen über dieses Feature, allerdings habe ich noch nicht herausgefunden, wie man mit FHEM den Status abfragt. Einige EIB-Sensoren erlauben jedoch auch eine Programmierung über die ETS, so dass sie in regelmässigen Abständen ihren aktuellen Status an den Bus senden.

[[Kategorie:FAQ]]
[[Kategorie:EIB/KNX]]

EIB FAQ

2017-02-15T19:59:11Z

Arne: Link aktualisiert

Antworten auf häufig gestellte Fragen im Bereich [[:Kategorie:EIB/KNX|EIB (/KNX)]]

;Alle Lampen wurden automatisch erkannt und können nun geschaltet werden. Wie erkenne ich aber nun die Schalter?
:Im EIB sind alle Geräte intelligent und kommunizieren im Normalfall dezentral. Das heisst, ein Taster steuert direkt eine Lampe an, indem er den entsprechenden Befehl auf den Bus sendet. Somit kann FHEM nur erkennen, dass ein entsprechender Schaltbefehl für eine Lampe von einem anderen Gerät gesendet wurde, aber nicht von welchem.
:Diese Kommunikation lässt sich aber auch zentralisieren. Ein Taster sendet dann einen Befehl an eine Adresse, die keiner Lampe zugeordnet ist. Diesen Befehl kann dann eine zentrale Steuerung (wie FHEM) aufgreifen und in Befehle für die Lampen umwandeln. Nachteil: fällt die zentrale Steuerung aus, fällt das ganze System aus.
:Oftmals ist der Mittelweg der richtige: alle Lampen werden direkt von Tastern gesteuert, man benutzt aber zusätzliche Taster um spezielle Funktionalitäten (z.B. Lichtzenen) zu realiseren. Ein Ausfall der zentralen Steuerung legt somit nicht das komplette System lahm.
:Um das Verhalten der Taster zu ändern, müssen jedoch die Taster direkt umprogrammiert werden. Dies ist nicht mit FHEM möglich, sondern nur mit der Zusatzsoftware [https://redaktion.knx-user-forum.de/lexikon/ets/ ETS].

;Ist es möglich den Status von EIB-Sensoren direkt abzufragen anstatt warten zu müssen, bis ein neuer Wert auf dem Bus auftaucht?
:Der EIB und entsprechende Geräte verfügen über dieses Feature, allerdings habe ich noch nicht herausgefunden, wie man mit FHEM den Status abfragt. Einige EIB-Sensoren erlauben jedoch auch eine Programmierung über die ETS, so dass sie in regelmässigen Abständen ihren aktuellen Status an den Bus senden.

[[Kategorie:FAQ]]
[[Kategorie:EIB/KNX]]

TelegramBot

2016-05-05T21:30:40Z

Arne:

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das perl JSON modul installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

Beispiel: <code>attr teleBot pollingTimeout 120</code>

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

Der Versand ist nicht direkt über das Device möglich, jedoch über den Perl-Befehl 'TelegramBot_ExecuteCommand':

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

Hierbei ist die Ziel-ID ohne das @-Zeichen, Anführungszeichen o.ä. anzugeben. Das Ziel kann auch eine Gruppen-ID (beginnend mit dem Minus-Zeichen) sein. Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message \@meine_ZielID Mein Text" ;; TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

==== Favoriten für Kommandos anlegen ====

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

/short1 = set TYPE=ROLLADEN pos 100

/short2 = set TYPE=ROLLADEN pos 0

</pre>

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen.
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

<code>[Rollaeden zu ]=set TYPE=ROLLADEN pos 100;[Rollaeden auf]=set TYPE=ROLLADEN pos 0</code>

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

<pre>
Favorites

/short1 = Rollaeden zu

/short2 = Rollaeden auf

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

DevelopmentModuleIntro

2014-11-18T22:26:50Z

Arne: /* Zweistufiges Modell für Module */

== 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|The FHEM two-level model]
* [http://forum.fhem.de/index.php/topic,13438.msg83643.html#msg83643|Zum Initialize bei physikalischen und logischen Geräten]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Noch zu beschreiben ==
* Zweistufiges Modell für Module
* Funktion X_Ready ...
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* DevIO

[[Kategorie:Development]]

YAF

2013-10-28T02:07:27Z

Arne: Installationsbefehl für openSUSE

'''YAF''' ist ein Floorplan, der es erlaubt, Geräte per Drag&Drop zu platzieren.

[[Datei:YAF_Beispielansicht.png|600px|thumb|right|YAF mit mehreren Widgets]]

== Projekt YAF ==

YAF entstand als Projektarbeit von Daniel Weisensee und Markus Mangei an der Hochschule Karlsruhe Technik und Wirtschaft.

Es steht für “Yet Another Floorplan” und soll eine Alternative zum bisher vorhandenen Floorplan bieten. YAF basiert auf ClientSeite
aus den JavaScript Frameworks JQuery und JQuery UI, serverseitig werden die CPAN Module <strike>XML::LibXML (bindet libxml2 an Perl an) und</strike> JSON::XS verwendet, um die Konfiguration zu persisitieren und um Daten zwischen der Oberfläche und dem Server austauschen zu können.

Durch die Erweiterbarkeit von Widgets soll YAF flexibel gehalten werden. Mit Hilfe dieser Schnittstelle können problemlos Widgets von verschiedenen Entwicklern veröffentlicht werden, ohne dass sich diese über gewünschte Änderungen am YAF Code mit der Community
abstimmen müssen. Es soll ähnlich dem Prinzip der Widgets unter Android oder Windows funktionieren. Widgets sollen speziell für FHEM Plugins geschrieben werden, um somit möglichst komfortable Oberflächen bieten zu können.

* Das Projekt ist freie Software unter der GNU General Public License und befindet sich auf dem offiziellen FHEM SourceForge.net Repository: https://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/YAF/

* Im FHEM Forum gibt es einen Thread mit dem Titel [http://forum.fhem.de/index.php/topic,12629.0.html Yet Another Floorplan YAF]

== Installation==
=== Installation mit FHEM Update ===
<pre>update thirdparty http://svn.code.sf.net/p/fhem/code/trunk/fhem/contrib/YAF/ yaf</pre>
=== Voraussetzungen ===
Das PERL Modul JSON::XS [http://search.cpan.org/~mlehmann/JSON-XS-2.34/XS.pm] ist notwendig.

Installation z.B. über den Befehl
/opt/bin/cpanm JSON::XS
oder
sudo apt-get install libjson-xs-perl
oder
zypper in perl-JSON-XS (für PCs mit openSUSE)

(Der korrekte Befehl ist von der verwendeten Hardware abhängig)

== Konfiguration ==

YAF wird durch die folgende Definition aktivert:

define yaf YAF

Die weitere Konfiguration kann komplett über das YAF Interface erfolgen.

Gespeichert wird die Konfiguration in den Attributen des YAF Device:
attr yaf backgrounds 1,1,1,/path/to/local/image;;2,1,1,http://path.to/remote/image.png
attr yaf refresh_interval 10
attr yaf views 1,Haus;;2,Test

== Widgets ==

Ein Widget ist die Darstellung eines Gerätes (Device) auf dem Floorplan. Die Konfiguration des Widget wird im Device unter der Eigenschaft <code>yaf_#</code> gespeichert, wobei <code>#</code> die Nummer des YAF-View ist, in der das Widget angezeigt wird.

Beispiel:
attr somedevice yaf_1 id=3,fhemname=somedevice,x_pos=432,y_pos=205,name=fhttk,

=== fhttk ===

Zur Anzeige von [[FHT80TF|FHTTK Fenstersensoren]].

==== Beispiel ====

define CUL_FHTTK_xxxxxx CUL_FHTTK xxxxxx
attr CUL_FHTTK_xxxxxx devStateIcon Closed:signal_Fenster_Offen.off Open:signal_Fenster_Offen.on
attr CUL_FHTTK_xxxxxx yaf_2 id=10,showlabel=0,fhemname=CUL_FHTTK_xxxxxx,y_pos=410,x_pos=379,name=fhttk,showicon=1,

=== fs20st ===

=== fs20easylamp ===

=== generic ===
Erlaubt das Einfügen beliebiger Geräte im Plan.

==== Beispiele ====
Die Widgets im Beispielplan auf dieser Seite sind "generic"-Widgets (Bis auf die FHT80-Heizungsanzeigen).

'''Anzeige eines [[FS20_ST_Steckdosenfunkschalter|FS20 Steckdosenschalters]] mit Schaltfunktion im Plan'''
define FS20_xxxxyy FS20 xxxx yy
attr FS20_xxxxyy alias Testlampe
attr FS20_xxxxyy devStateIcon on:FS20.on off:FS20.off toggle:toggle
attr FS20_xxxxyy yaf_2 id=12,name=generic,showicon=1,fhemname=FS20_xxxxyy,showlabel=1,y_pos=209,x_pos=403,labeltype=alias,_on=off,_off=on

'''Anzeige der Ist-Temperatur einer [[FHT80b|FHT80 Heizungssteuerung]] mit dem Inhalt des "comment" Felds als Label'''
define FHT_xxxx FHT xxxx
attr FHT_xxxx comment Eltern
attr FHT_xxxx yaf_2 id=14,name=generic,fhemname=FHT_xxxx,showlabel=1,x_pos=415,y_pos=431,labeltype=comment,statetype=measured-temp,

'''Anzeige eines [[FHT80TF|FHTTK Fenstersensors]]'''
define CUL_FHTTK_xyz CUL_FHTTK xyz
attr CUL_FHTTK_xyz devStateIcon Closed:signal_Fenster_Offen.off Open:signal_Fenster_Offen.on
attr CUL_FHTTK_xyz yaf_2 id=4,fhemname=CUL_FHTTK_xyz,x_pos=27,y_pos=261,name=generic,showlabel=0

'''Präsenzanzeige eines Handies im WLAN mit [[PRESENCE]]'''
define presence_android PRESENCE lan-ping 10.1.2.3
attr presence_android devStateIcon present:WLAN_Status.1 absent:WLAN_Status.0
attr presence_android yaf_2 id=1,fhemname=presence_android,showlabel=0,y_pos=266,x_pos=46,name=generic,showicon=1,labeltype=alias,

'''Anzeige eines Homematic [[HM-Sec-WDS Funk-Wassermelder]]'''
define CUL_HM_HM_SEC_WDS_xyz CUL_HM xyz
attr CUL_HM_HM_SEC_WDS_xyz alias WassermelderHeizung
attr CUL_HM_HM_SEC_WDS_xyz devStateIcon dry:wasseralarm wet:wasseralarm_rot damp:wasseralarm_rot
attr CUL_HM_HM_SEC_WDS_xyz yaf_2 id=5,fhemname=CUL_HM_HM_SEC_WDS_xyz,x_pos=324,y_pos=139,name=generic,labeltype=alias,

==== Parameter ====
{|
|<code>id</code>
|interne ID des Widgets, immer der erste Parameter
|-
|<code>fhemname</code>
|interner Name des Geräte im FHEM
|-
|<code>x_pos</code>
|X-Koordinate des Widget
|-
|<code>y_pos</code>
|Y-Koordinate des Widget
|-
|<code>name</code>
|Typ des Widgets
|-
|<code>labeltype</code>
|Welcher Eigenschaftswert soll als Label angezeigt werden?
|-
|<code>statetype</code>
|Welches Reading soll als Wert angezeigt werden?
|-
|<code>showlabel</code>
|Soll das Label angezeigt werden? (1/0)
|-
|<code>showicon</code>
|Soll das devStateIcon angezeigt werden? (1/0)
|}

==== Schaltfunktion ====
Mit zusätzlichen Parametern kann eine Schaltfunktion konfiguriert werden, womit im Plan durch Klicken auf das Widget eine Aktion des Gerätes durchgeführt werden kann.

Beispiel:
_on=off,_off=on
Im Beispiel wird nach dem Klick auf das Widget der aktuelle Status des Gerätes geprüft. Ist der Status "on", wird der "off" Befehl gesendet. Ist der Status "off", wird der "on" Befehl gesendet. Zwischen dem Unterstrich "_" und dem Gleichheitszeichen (=) können zur Definition des Status reguläre Ausdrücke verwendet werden.

=== fht80 ===
Zeigt Informationen über eine [[FHT80b|FHT80]] Heizungssteuerung an.

==== Aussehen des Widgets ====
----

<div aria-disabled="true" style="text-align:center">Heizung Kinderzimmer 22.9 °C ⊗ 16.0 °C</div>

----
Links: Ist-Temperatur (Tooltip: Timestamp des Readings)
Mitte: Automatischer Modus (⊗) oder manueller Modus (⊕)
Rechts: Zieltemperatur (Tooltip: Öffnungsgrad des Stellmotors)

Die Konfiguration unterstützt nicht alle Parameter über das YAF Interface, einige müssen über FHEMWeb gesetzt werden.

==== Beispiele ====
attr FHT_abcd yaf_1 id=14,fhemname=FHT_abcd,y_pos=235,x_pos=239,name=fht80,labeltype=Alias,
attr FHT_wxyz yaf_1 id=4,fhemname=FHT_wxyz,y_pos=241,x_pos=434,name=fht80,labeltype=Alias,size=0.8,
attr FHT_lmno yaf_1 id=10,fhemname=FHT_lmno,nomode=1,y_pos=183,x_pos=533,name=fht80,labeltype=Comment,size=0.7,

==== Parameter ====

{|
|<code>id</code>
|interne ID des Widgets, immer der erste Parameter
|-
|<code>fhemname</code>
|interner Name des Geräte im FHEM
|-
|<code>x_pos</code>
|X-Koordinate des Widget
|-
|<code>y_pos</code>
|Y-Koordinate des Widget
|-
|<code>name</code>
|Typ des Widgets
|-
|<code>labeltype</code>
|Welcher Eigenschaftswert soll als Label angezeigt werden?
|-
|<code>nomode</code>
|Ausblenden der Modusanzeige
|-
|<code>size</code>
|Relative Textgröße
|}

=== webcam ===

Blendet ein Webcambild im Floorplan ein, basierend auf einem [[dummy]] oder [[PRESENCE]] Device.

Das Widget kann aktuell nur über FHEMWeb konfiguriert werden.

==== Beispiel ====
'''Anzeige des statischen Bildes einer Webcam, deren Status per PRESENCE ping überprüft wird'''
define webcam PRESENCE lan-ping 10.x.y.z
attr webcam yaf_2 id=15,fhemname=webcam,showmethod=img,x_pos=224,y_pos=88,name=webcam,path=/image.jpg,hover=0,user=username,pass=password

Die Definition führt zur Anzeige des Bildes unter <nowiki>http://username:password@10.x.y.z/image.jpg</nowiki>

Bei Einsatz eines Dummy device muss im yaf-Attribut zusätzlich der Parameter "address" gesetzt werden.

==== Parameter ====
{|
|<code>id</code>
|interne ID des Widgets, immer der erste Parameter
|-
|<code>fhemname</code>
|interner Name des Geräte im FHEM
|-
|<code>x_pos</code>
|X-Koordinate des Widget
|-
|<code>y_pos</code>
|Y-Koordinate des Widget
|-
|<code>name</code>
|Typ des Widgets
|-
|<code>showmethod</code>
|Welche Anzeigemethode soll verwendet werden. Zur Zeit implementiert: <code>img</code> (Anzeige mit dem HTML <code>img</code> Tag)
|-
|<code>path</code>
|absoluter Pfad zur anzuzeigenden Ressource
|-
|<code>hover</code>
|''reserviert''
|-
|<code>user</code>
|Benutzername
|-
|<code>pass</code>
|Passwort '''Achtung! Passwort wird im Klartext gespeichert!'''
|-
|<code>address</code>
|Hostname (nur bei Dummy Device notwendig)
|-
|<code>proto</code>
|Protokoll. Standard: <code>http</code>
|}

[[Kategorie:FHEM Frontends]]

Raspberry Pi

2013-10-27T17:32:28Z

Arne: Problem: FHEM-Blockierung bei Update

Beim '''Raspberry Pi''' handelt es sich um einen kreditkartengroßen Einplatinen-Computer, der von der Raspberry Pi Foundation entwickelt wird. Die Hardware basiert auf dem BCM 2835 SoC (System-on-Chip) von Broadcom, einem 700 MHz ARM-Prozessor der ARMv6-Architektur/ARM11-Familie. Derzeit verfügbar ist das Modell B mit u.a. 256 MB RAM (ab Auslieferung Oktober 512 MB), zwei USB 2.0 Anschlüssen und 10/100 MBit Ethernet-Controller.
Dank der kleinen Abmessungen, dem recht geringen Energieverbrauch (ca. 3,5 Watt) sowie der günstigen Anschaffungskosten (ca. 33€) ist der Raspberry Pi eine attraktive Hardware für die Heimautomatisierung mit FHEM. Er ist dank dem Linux-Betriebssystem vollständig kompatibel zur aktuell vorhandenen und von FHEM unterstützen Hardware. Das derzeit empfohlene Standard-Image zum Betrieb des Raspberry Pi ist die auf Debian 7.0 Wheezy basierende Raspbian Distribution.

==Installation / Setup ==
Das Betriebssystem sollte direkt bei Raspberry unter dem Link [http://www.raspberrypi.org/downloads http://www.raspberrypi.org/downloads] ([http://downloads.raspberrypi.org/raspbian_latest Raspbian], ca. 577 MB) geholt werden.

Nach dem Herunterladen des entsprechenden Archivs muss das Image entpackt und auf die SD-Karte geschrieben werden.

Unter Unix/Linux erfolgt dies via dd-Befehl. Zum Beispiel:
:<code>sudo dd bs=1M if=2012-08-16-wheezy-raspbian.img of=/dev/sdz</code>

'''Achtung:''' Bei Angabe eines falschen Device hinter of= kann der Anfang der eigenen Festplatte überschrieben werden. (Datenverlust!)

Je nach System/Distribution und vorhandenen Festplatten variiert das Device, z.B. /dev/mmcblk0 (Ubuntu), /dev/sdb, /dev/sdc oder /dev/rdisk1 (OSX). Folgende Möglichkeiten können helfen, das richtige Device zu ermitteln:
* Mit dem Befehl <code>df</code> erhält kann eine Übersicht aller angeschlossenen und gemounteten(!) Speichermedien.
* Beim Einstecken der Speicherkarte in den PC wird in die Log-Datei <code>/var/log/messages</code> ein Eintrag gemacht. Beispiel: <code>kernel: [2077612.776470] sd 14:0:0:0: ['''sdb'''] 7954432 512-byte logical blocks: ('''4.07 GB'''/3.79 GiB)</code>
* Mit dem Befehl fdisk kann die Größe eines bestimmten Devices geprüft werden: <code>fdisk -l /dev/sdb</code> Beispielausgabe: <code>Platte /dev/sdb: 4072 MByte, 4072669184 Byte</code>
* Unter Windows kann das Tool [https://launchpad.net/win32-image-writer Win32DiskImager] genutzt werden.

Nach der Installation des Images sollte der Raspberry Pi von der SD Karte booten.

Um eventuell eine größere SD-Karte komplett zu nutzen, kann dies per folgendem Menu erledigt werden:
:<code>sudo raspi-config</code>

Es kann erforderlich sein, einen KernelUpdate einzuspielen, um einen USB-Bug zu beheben. Dieses Update ist zu finden auf [https://github.com/Hexxeh/rpi-update github].

Die Installation von fhem auf dem Raspberry Pi kann mit dem fertigen debian-package erledigt werden. Lediglich das Perl-Modul "Serialport" wird benötigt - Perl ist in der Regel bereits installiert, kann aber sicherheitshalber einfach mit dem apt-get-Befehl zugefügt werden:

sudo apt-get install perl libdevice-serialport-perl
sudo apt-get install libio-socket-ssl-perl
# fhem-X.Y.deb bitte mit der [http://fhem.de/fhem.html#Download aktuellsten, stabilen Version] ersetzen
wget [http://fhem.de/fhem-X.Y.deb http://fhem.de/fhem-X.Y.deb]
sudo dpkg -i fhem-X.Y.deb

Möglicherweise ist es noch nötig, fehlende Abhängigkeiten aufzulösen. Das kann mit folgendem Befehl erledigt werden:
:<code>sudo apt-get install -f</code>

== Bekannte Probleme ==
Der RPi hat keine [http://de.wikipedia.org/wiki/Echtzeituhr Real-Time-Clock] (RTC), das heißt, dass er nach einem Neustart keine gültige (im Sinne von aktuell) Systemzeit hat, sondern ein Datum in der Vergangenheit. Dieses Problem wird sinnvollerweise mit einer [http://de.wikipedia.org/wiki/Network_Time_Protocol NTP-Konfiguration] umgangen.

Dabei muss Sorge getragen werden, dass der [http://wiki.debian.org/NTP ntpd] schon einen Datums-/Zeitabgleich gemacht hat, bevor FHEM gestartet wird. Geschieht der Abgleich nicht vorher, sondern erst nachdem FHEM schon läuft, stellt FHEM die Logs zwar auf das nun aktuelle Datum um (die "alten" Logs mit dem eigentlich ungültigen Datum werden natürlich behalten), aber irgendetwas scheint FHEM dabei so zu belasten, dass es einen "load" von über 0.8 bis 0.9 erzeugt. Diese Last besteht auf Dauer und verschwindet erst, wenn man das Ganze sauber durchkonfiguriert und FHEM neu gestartet hat. Die hohe Systemauslastung zeigt sich auch in einem sehr trägen Laden der FHEM-Web-Seiten in einem beliebigen Browser.

Bei einen Update von FHEM durch den Befehl <tt>update</tt> wird standardmäßig ein Backup durchgeführt. Die (ggf. großen) Log-Dateien werden dabei ebenfalls archiviert. Während der Archivierung ist FHEM blockiert. Durch die beschränkte Leistungsfähigkeit eine Raspberry Pi kann das Backup lange dauern. Durch ein "<tt>attr global updateInBackground</tt>" wird ein Backup im Hintergrund ausgeführt. Diese Einstellung ist seit FHEM 5.5. Standard. <nowiki>[</nowiki>Quelle: [http://forum.fhem.de/index.php/topic,15729.0.html FHEM-Forum]<nowiki>]</nowiki>.

Alternative Möglichkeiten: Backup ausschalten und manuell durchführen; Backup-Befehl anpassen und so große Dateien bzw. Verzeichnisse (log/) nicht archivieren; ...

== Externe Links ==
* [http://www.raspberrypi.org/ Offizielle Webseite der Raspberry Pi Foundation]
* [http://www.raspberrypi.org/downloads Offizielle Downloads der Raspberry Pi Foundation]
* Blog mit dem Thema [http://www.meintechblog.de/2013/05/fhem-server-auf-dem-raspberry-pi-in-einer-stunde-einrichten/ Fhem auf RaspBerry Pi in einer Stunde]

[[Kategorie:Raspberry Pi]]

Raspberry Pi

2013-10-21T13:36:27Z

Arne: Möglichkeiten für Device-Ermittlung ergänzt + Warnhinweis

Beim '''Raspberry Pi''' handelt es sich um einen kreditkartengroßen Einplatinen-Computer, der von der Raspberry Pi Foundation entwickelt wird. Die Hardware basiert auf dem BCM 2835 SoC (System-on-Chip) von Broadcom, einem 700 MHz ARM-Prozessor der ARMv6-Architektur/ARM11-Familie. Derzeit verfügbar ist das Modell B mit u.a. 256 MB RAM (ab Auslieferung Oktober 512 MB), zwei USB 2.0 Anschlüssen und 10/100 MBit Ethernet-Controller.
Dank der kleinen Abmessungen, dem recht geringen Energieverbrauch (ca. 3,5 Watt) sowie der günstigen Anschaffungskosten (ca. 33€) ist der Raspberry Pi eine attraktive Hardware für die Heimautomatisierung mit FHEM. Er ist dank dem Linux-Betriebssystem vollständig kompatibel zur aktuell vorhandenen und von FHEM unterstützen Hardware. Das derzeit empfohlene Standard-Image zum Betrieb des Raspberry Pi ist die auf Debian 7.0 Wheezy basierende Raspbian Distribution.

==Installation / Setup ==
Das Betriebssystem sollte direkt bei Raspberry unter dem Link [http://www.raspberrypi.org/downloads http://www.raspberrypi.org/downloads] ([http://downloads.raspberrypi.org/raspbian_latest Raspbian], ca. 577 MB) geholt werden.

Nach dem Herunterladen des entsprechenden Archivs muss das Image entpackt und auf die SD-Karte geschrieben werden.

Unter Unix/Linux erfolgt dies via dd-Befehl. Zum Beispiel:
:<code>sudo dd bs=1M if=2012-08-16-wheezy-raspbian.img of=/dev/sdz</code>

'''Achtung:''' Bei Angabe eines falschen Device hinter of= kann der Anfang der eigenen Festplatte überschrieben werden. (Datenverlust!)

Je nach System/Distribution und vorhandenen Festplatten variiert das Device, z.B. /dev/mmcblk0 (Ubuntu), /dev/sdb, /dev/sdc oder /dev/rdisk1 (OSX). Folgende Möglichkeiten können helfen, das richtige Device zu ermitteln:
* Mit dem Befehl <code>df</code> erhält kann eine Übersicht aller angeschlossenen und gemounteten(!) Speichermedien.
* Beim Einstecken der Speicherkarte in den PC wird in die Log-Datei <code>/var/log/messages</code> ein Eintrag gemacht. Beispiel: <code>kernel: [2077612.776470] sd 14:0:0:0: ['''sdb'''] 7954432 512-byte logical blocks: ('''4.07 GB'''/3.79 GiB)</code>
* Mit dem Befehl fdisk kann die Größe eines bestimmten Devices geprüft werden: <code>fdisk -l /dev/sdb</code> Beispielausgabe: <code>Platte /dev/sdb: 4072 MByte, 4072669184 Byte</code>
* Unter Windows kann das Tool [https://launchpad.net/win32-image-writer Win32DiskImager] genutzt werden.

Nach der Installation des Images sollte der Raspberry Pi von der SD Karte booten.

Um eventuell eine größere SD-Karte komplett zu nutzen, kann dies per folgendem Menu erledigt werden:
:<code>sudo raspi-config</code>

Es kann erforderlich sein, einen KernelUpdate einzuspielen, um einen USB-Bug zu beheben. Dieses Update ist zu finden auf [https://github.com/Hexxeh/rpi-update github].

Die Installation von fhem auf dem Raspberry Pi kann mit dem fertigen debian-package erledigt werden. Lediglich das Perl-Modul "Serialport" wird benötigt - Perl ist in der Regel bereits installiert, kann aber sicherheitshalber einfach mit dem apt-get-Befehl zugefügt werden:

sudo apt-get install perl libdevice-serialport-perl
sudo apt-get install libio-socket-ssl-perl
# fhem-X.Y.deb bitte mit der [http://fhem.de/fhem.html#Download aktuellsten, stabilen Version] ersetzen
wget [http://fhem.de/fhem-X.Y.deb http://fhem.de/fhem-X.Y.deb]
sudo dpkg -i fhem-X.Y.deb

Möglicherweise ist es noch nötig, fehlende Abhängigkeiten aufzulösen. Das kann mit folgendem Befehl erledigt werden:
:<code>sudo apt-get install -f</code>

== Bekannte Probleme ==
Der RPi hat keine [http://de.wikipedia.org/wiki/Echtzeituhr Real-Time-Clock] (RTC), das heißt, dass er nach einem Neustart keine gültige (im Sinne von aktuell) Systemzeit hat, sondern ein Datum in der Vergangenheit. Dieses Problem wird sinnvollerweise mit einer [http://de.wikipedia.org/wiki/Network_Time_Protocol NTP-Konfiguration] umgangen.

Dabei muss Sorge getragen werden, dass der [http://wiki.debian.org/NTP ntpd] schon einen Datums-/Zeitabgleich gemacht hat, bevor FHEM gestartet wird. Geschieht der Abgleich nicht vorher, sondern erst nachdem FHEM schon läuft, stellt FHEM die Logs zwar auf das nun aktuelle Datum um (die "alten" Logs mit dem eigentlich ungültigen Datum werden natürlich behalten), aber irgendetwas scheint FHEM dabei so zu belasten, dass es einen "load" von über 0.8 bis 0.9 erzeugt. Diese Last besteht auf Dauer und verschwindet erst, wenn man das Ganze sauber durchkonfiguriert und FHEM neu gestartet hat. Die hohe Systemauslastung zeigt sich auch in einem sehr trägen Laden der FHEM-Web-Seiten in einem beliebigen Browser.

== Externe Links ==
* [http://www.raspberrypi.org/ Offizielle Webseite der Raspberry Pi Foundation]
* [http://www.raspberrypi.org/downloads Offizielle Downloads der Raspberry Pi Foundation]
* Blog mit dem Thema [http://www.meintechblog.de/2013/05/fhem-server-auf-dem-raspberry-pi-in-einer-stunde-einrichten/ Fhem auf RaspBerry Pi in einer Stunde]

[[Kategorie:Raspberry Pi]]

Raspberry Pi als Zahlenschloss

2013-10-21T12:40:21Z

Arne: Link eingefügt

So ein [Raspberry Pi] (RPi) ist ein klasse Universalgerät. In Kombination mit diversen Dingen, wie hier einer Zahlentastatur, wird das ein fertiges FHEM-fähiges '''Zahlenschloss'''. Die Gesamtkosten sind sicherlich nicht höher als ein fertiges Gerät kosten würde -- wenn es denn zu kaufen wäre.

Diese Zahlentastatur kann man nicht nur als Schloss, sondern auch zum beliebigen Schalten von Aufgaben verwenden.

== Überblick über die Vorgehensweise ==
* Eine RPi unter Debian Wheezy wird ohne Monitor z.B. an der Haustüre montiert.
* Eine wetterfeste USB-Zahlen-Tastatur wird nach außen geführt.
* Die RPi ist so eingestellt, dass nach dem Booten keine Desktop-Umgebung (Grafik) gestartet wird, sie daher mit der Konsole (/dev/tty1) startet.
* tty1 wird so eingestellt, dass sich automatisch ein nicht privilegierter User einloggt.
* Mit dem Einloggen startet sich ein Shell-Skript, das in einer Endlosschleife Zahlencodes einliest und das Ergebnis an FHEM schickt (FHEM muss nicht auf dem selben Rechner laufen)
* FHEM schaltet mit dem als dummy-Device angelegten Zahlencode über notify beliebige Anwendungen/Logiken.

== Sicherheit ==
Für professionelle Aufgaben ist das nicht der Standard, den man erwarten würde.

* eine RPi ist auch nur ein Rechner und kann abstürzen
* eine USB-Tastatur vor die Haustür zu verlegen ist auch nicht jedermanns Sache. Eine USB-Buchse sollte auf jeden Fall nicht erreichbar sein, ein USB-Keylogger wäre sonst schnell installiert.
* wenn man diese Lösung zum Schalten von sicherheitskritischen Dingen, wie der [[HM-SEC-KEY KeyMatic|Keymatic]] (Haustüre) oder der Alarmanlage verwendet, sollte man wissen, was man tut.

== Benötigte Hardware ==
Analog zur NFC-Variante [[Raspberry Pi & NFC]] benötigt man anstatt NFC nur eine 8-Euro USB-Zahlentastatur. Für diesen Einsatzzweck eignet sich die '''Keysonic ACK-118 BK Numpad''' ([http://keysonic.de/de/products/details.php?we_objectID=8300]). Sie ist komplett in Silikon eingearbeitet und somit für den Außenbereich geeignet. Bei der Bestellung darauf achten, dass es sie in grau und in schwarz gibt.

Natürlich kann man auch edle wetterfeste Edelstahl-Tastaturen (möglichst mit Eingabe-Taste) verbauen - sie kosten aber auch gleich ein Vermögen.

== Betriebssystem/Shell-Skript auf RPi ==
=== Zusätzliche Software ===
Aufbauend auf der oben genannten NFC-Variante (ohne NFC-Teil) wird nur das Paket mingetty benötigt
:<code>sudo apt-get install mingetty</code>

=== Tastaturprellschutz (optional) ===
Bei der Zahleneingabe lösen Anfänger schnell ein Tastaturprellen aus. Wir setzen die Tastatur auf maximalen Delay-Wert. Da dies in der Praxis trotzdem evtl. nicht ausreicht, wird ein Tastaturprellen im Skript (s.u.) selbst abgefangen. Insofern ist diese Einstellung hier nur noch optional und für den Fall gedacht, dass man das Skript abändern möchte.

Eingabe in ''/etc/rc.local'' in der vorletzten Zeile (vor exit 0)
:<code>kbdrate -d 1000 /dev/tty1</code>
:<code>exit 0</code>

=== Neuer nicht privilegierter User ===
Es werden nicht viele Rechte benötigt. Ein einfacher User, der keinen besonderen Gruppen angehört, reicht aus.
:<code>sudo useradd -m rpi</code>

=== Automatisches Login ===
Beim Standard-Loginprogramm kann man sich nicht automatisch einloggen. Daher wird in der /etc/inittab das Standard getty gegen mingetty für tty1 ausgetauscht.

alt
:<code>1:2345:respawn:/sbin/getty --noclear 38400 tty1</code>
neu
:<code>1:2345:respawn:/sbin/mingetty --autologin rpi --noclear tty1</code>

=== Starten des Einlese-Skriptes ===
Am einfachsten ändern wir die /home/rpi/.bashrc

Einfach am Ende folgende Zeilen einfügen:
:<code># Codeschloss fuer fhem</code>
:<code>/usr/local/bin/kbd2fhem.sh</code>

=== Einleseskript kbd2fhem.sh ===
/usr/local/bin/kbd2fhem.sh

<nowiki>#!/bin/bash
# provided by Martin Haas 3/2013
# Skript, um Zahleneingaben von Tastatur an FHEM zu schicken
FhemIP="192.168.0.x"
LogFile="/home/rpi/kbd2fhem.log"

while true
do
# NumLock vorsorglich aktivieren
/usr/bin/setleds -D +num < /dev/tty1
# Zahlencode einlesen
printf "Zahlencode: "
read code
# Eingabe
echo 'Eingabe: '$code
# nur Zahlen zulassen (nicht alles wird abgefangen)
code=$(echo $code | tr -d "[:alpha:][:space:][:cntrl:][:punct:]äüöß")
echo 'Verwendeter Zahlencode: '$code

# Um prellende Tastaturen auszuschliessen, wird keine Doppelzahl
# akzeptiert. Beispiel: aus 3333553311 wird 3531
finalcode=${code:0:1}

while [[ ${#code} -gt '' ]]
do
last=${code:0:1}
code=${code/${code:0:1}}
next=${code:0:1}
[[ $next != $last ]] && finalcode=$finalcode${code:0:1}
done

# fuer FHEM vorbereiten
code='kbd'$finalcode

# nur bei erkanntem Zahlencode verschicken
[[ $finalcode != '' ]] &&
echo "set $code irgendwas" | nc -w5 $FhemIP 7072

# ...aber alles loggen
echo "`date`: $code detected" >>$LogFile

# optisches Feedback
/usr/bin/setleds -D -num < /dev/tty1 #NumLock-LED kurz ausschalten
sleep 1
done</nowiki>
Das Skript muss ausführbar sein
:<code>sudo chmod +x /usr/local/bin/kbd2fhem.sh</code>
Nach dem nächsten Booten ist die RPi bereit Zahlencodes an FHEM zu schicken.

== FHEM vorbereiten ==
=== Zahlencode einem Dummy zuordnen ===
Beispiel Eintrag in der fhem.cfg

<nowiki># Keyboard. Eingegebener Zahlencode: 12345 (Beispiel)
define kbd12345 dummy
define kbdnot01 notify kbd12345 set lampe toggle</nowiki>

=== FHEM-Zugriff von extern ===
Sollte auf der RPi nicht auch FHEM laufen, so muss FHEM den Remote-Zugriff erlauben:
Eintrag in fhem.cfg
:<code>define telnetPort telnet 7072 '''global'''</code>

== Hilfe/Support ==
* Fragen werden gerne im FHEM-Forum auf [http://forum.fhem.de http://forum.fhem.de] beantwortet.
* Für Feedback ist [http://forum.fhem.de/index.php/topic,11521.msg67529.html#msg67529 dieser Beitrag] im Forum vorgesehen.

[[Kategorie:HOWTOS]]
[[Kategorie:Raspberry Pi]]

MAX

2013-10-20T17:12:53Z

Arne: Einleitung, Autocreate+Definition für Fensterkontakt

MAX! ist eine Heizungssteuerung, die die Raumtemperatur durch funkvernetzte Heizkörperthermostate an den Heizkörpern regelt. MAX! stellt eine Alternative zur FHT und HomeMatic Heizungsteuerung dar.
== Features ==
* Bidirektionale Kommuniktion (jeder Befehl wird mit ACK quittiert)
* Heizkörperthermostate übertragen auch die gemessene Temperatur
== FHEM Module ==
Die MAX Komponenten können über den MAX!Cube per Modul 00_MAXLAN,
oder über einen [[CUL]] oder [[CUNO]] per 14_CUL_MAX gesteuert werden.
In beiden Fällen werden die einzelnen MAX! Geräte vom Modul 10_MAX
bereitgestellt.

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

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

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

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

und das Auslesen

* der gemessenen Temperatur. (Hinweis: Wird bei Verwendung des MAX CUBE nicht regelmäßig aktualisiert)
=== Fensterkontakte ===
Der aktuelle Status (offen/geschlossen) wird (praktisch ohne Verzögerung) angezeigt. '''[[Nur bei CUL, oder?]]'''

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

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

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

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

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

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

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

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

und das Auslesen

* der gemessenen Temperatur.
=== Eco-Taster ===
'''Achtung''': Zumindest über MAXLAN lässt sich der Zustand weder auslesen, noch wird
man über Veränderungen informiert. 
Per CUL_MAX funktioniert der Eco-Taster problemlos.

==== Beispielhafte Definition ====
define BUTTON.EG MAX PushButton 069d33

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

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

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

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

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

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

=== MAXLAN ===
Minimale Konfiguration:

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

=== CUL_MAX ===
Minimale Konfiguration:

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
attr CUL0 rfmode MAX
define cm CUL_MAX 123456</nowiki>
=== Anlernen ===
Dazu muss der "pairmode" auf MAXLAN/CUL_MAX per

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

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

Wenn ich z.B.
set MAXFensterKontakt0 associate MaxHeizkörperthermostat3
ausführe, dann
sendet der MAXFensterKontakt0 jede Änderung zusätzlich (direkt über Funk, ohne Cube oder FHEM)
an das MaxHeizkörperthermostat3.

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

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

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

=== Temperatursturzerkennung ===
Die Heizkörperthermostate verfügen über eine interne "Fenster-offen Erkennung" (Temperatursturzerkennung). Wird diese ausgelöst regeln sie für die Zeit die unter "windowOpenDuration" festgelegt wurde auf die als "windowOpenTemperature" festgelegt Temperatur herunter und danch wieder auf die zuvor eingestellte Temperatur zurück.
Nachteil: Die Erkennung benötigt etwas Zeit und reagiert nicht sofort wie es beim Fensterkontakt oben der Fall ist
Vorteil: Es ist kein Fensterkontakt erforderlich

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

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

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>
Wir müssen einmalig den internen Fake-Fensterkontakt mit dem Heizkörper assozieren

<nowiki>set Heizung associate fakeShutterContact</nowiki>
damit dieser die Nachrichten vom Fensterkontakt akzeptiert.

Nun können wir per

<nowiki>set cm fakeSC Heizung 1</nowiki>
die Nachricht "Fenster offen" an die Heizung senden und per

<nowiki>set cm fakeSC Heizung 0</nowiki>
die Nachricht "Fenster zu".

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

<nowiki>define CUL0 CUL /dev/ttyACM0@9600 0000
define cm CUL_MAX 123456
define Heizung MAX HeatingThermostat abcdef
attr Heizung IODev cm</nowiki>
Wir müssen einmalig das interne Fake-Wandthermostat mit dem Heizkörper assozieren:

<nowiki>set Heizung associate fakeWallThermostat</nowiki>
damit dieser die Nachrichten vom Wandthermostat akzeptiert. Achtung: Dies schaltet im
Heizkörperthermostat die Regelung mit dem internen Temperaturfühler aus. Ohne die gleich kommenden "fakeWT" Nachrichten wird das Heizkörperthermostat nicht mehr regeln.

Nun können wir per

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

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

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

<nowiki>define SendExtTemp notify WS300:temperature.* {
MaxFakeWallThermostat("Heizung", %EVTPART1);
}</nowiki>
Dazu die Funktion, bitte in 99_MyUtils.pm eintragen:

<nowiki>sub MaxFakeWallThermostat($$)
{
my ($heizung, $aktTemp) = @_;
my $CULMAX = $defs{$heizung}{LASTInputDev};
my $desiredTemp = ReadingsVal($heizung, "desiredTemperature", undef);
my $windowOpenTemp = ReadingsVal($heizung, "windowOpenTemperature", undef);
my $lastTemp = ReadingsVal($heizung, "LastExtTemperature", 0);
my $lastSet = ReadingsTimestamp($heizung, "LastExtTemperature", 0);
if($desiredTemp && $windowOpenTemp &&
$desiredTemp != $windowOpenTemp &&
(time()-time_str2num($lastSet) >= 600 || abs($aktTemp-$lastTemp)>=0.2 )) {
Log 3, "set $CULMAX fakeWT $heizung $desiredTemp $aktTemp";
readingsSingleUpdate($defs{$heizung}, "LastExtTemperature", $aktTemp, 0);
fhem("set $CULMAX fakeWT $heizung $desiredTemp $aktTemp");
}
}</nowiki>
In diesem Beispiel heißt das zu steuernde Thermostat "Heizung". Die vom externen Sensor gemessene Temperatur wird nur unter den folgenden Voraussetzungen gesendet:
- Das Thermostat befindet sich nicht im "Fenster-offen" Modus, und
- das letzte Senden liegt mindestens 10min zurück
- oder die gemessene Temperatur weicht um mindestens 0.2°C von der letzten gesendeten Temperatur ab

=== Wochenheizplan für Wandthermostat erstellen ===
Ein Heizplan, den der Wandthermostat versteht und speichern kann, sieht folgendermaßen aus:

<nowiki>set WZ_Wandthermostat weekProfile
Mon 17,17:30,20,23:00,17
Tue 17,17:30,20,23:00,17
Wed 17,17:30,20,23:00,17
Thu 17,17:30,20,23:00,17
Fri 17,15:00,20,23:00,17
Sat 17,11:00,20,23:00,17
Sun 17,11:00,20,23:00,17</nowiki>
Genauer erläutert wird die Funktionsweise auch unter [http://fhem.de/commandref.html#MAX http://fhem.de/commandref.html#MAX].
Der gesamte Block kann kopiert und als FHEM Befehl abgesetzt werden. Unter Umständen benötigt das Speichern, bzw Übertragen wegen der Größe etwas Zeit, bevor die aktuellen, neu gesetzten Werte wieder ausgelesen werden können.

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

Inhalt der LOG-Datei eines Heizkörperthermostates:

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

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

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

<nowiki>#Werte plotten
define MAX_017840_weblink weblink fileplot FileLog_MAX_017840:max_temp:CURRENT
attr MAX_017840_weblink label "Kueche Soll-Temperatur Min $data{min1}, Max $data{max1}, Last $data{currval1}"
attr MAX_017840_weblink room MAX</nowiki>
=== Nützliche kleine Erweiterungen ===
'''Einen Alias-Namen vergeben für eine bessere Lesbarkeit im Webinterface'''
<nowiki>attr MAX_018d3f alias Kueche</nowiki>
'''Die Anzeigen für die einzelnen File-Logs füllen das Webinterface schnell und machen es unübersichtlich.''' Die File-Logs können einfach in einen separaten Raum verbannt werden.
<nowiki>attr FileLog_MAX_018d3f room LOG</nowiki>
'''Einstellmöglichkeit für die Soll-Temperatur direkt in der „Raum-Seite“ schaffen.''' Die Temperatur wird dauerhaft auf einen bestimmten Wert gestellt. Das Wochenprogramm in dem Thermostat wird deaktiviert.

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

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

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

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

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

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

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

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

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

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

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

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

<nowiki>2013.03.20 15:21:43 5: Got matching ack</nowiki>
auftauchen.

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