FHEMWiki - Benutzerbeiträge [de]

ODROID XU4

2023-02-11T20:23:05Z

AlanBlack:

Beim ODROID XU4 handelt es sich um einen Einplatinencomputer von [http://www.hardkernel.com/main/products/prdt_info.php Hardkernel] mit dem Exynos5422 Octa Core Prozessor bestehend aus 4x Cortex(TM) -A15 2Ghz und 4x Cortex(TM) -A7 1.4Ghz. 
der XU4 ist der Nachfolger des XU3 und ist von der Systemebene kompatibel. Es sind aus diesem Grund viele System Images des XU4 mit der Endung XU3 versehen.
Zum Vergleich ist in der Tabelle [[Cubieboard 3|Cubieboard]] und [[Raspberry Pi|Raspberry Pi 4b]] aufgeführt. Die Tabelle soll nur einen Überblick darstellen und erhebt keinen Anspruch auf Vollständigkeit.
{| class="wikitable zebra toptextcells" style="text-align:center"
! Eigenschaft !! ODROID XU4 !! Cubieboard '''3''' || Raspberry Pi '''4''' Model B
|-
| SOC || Exynos5422 || AllWinnerTech SOC A20 || Broadcom BCM2711
|-
| ARM Cortex || 4x A15 + 4x A7 || A7 || A72
|-
| Takt || 2Ghz + 1.4Ghz || 0.9GHz || 1.5GHz
|-
| RAM || 2Gbyte DDR 3 || 1GB/2GB DDR3@480MHz || 4Gbyte
|-
| Arbeitsspeicher || eMMC 5.0 Slot microSD Slot || NAND+MicroSD TSD+ MicroSD 2x MicroSD || microSD
|-
| RTC || Ja, Battery Buffered || Ja, Battery Buffered || Nein
|-
| Peripherie || 2x USB 3.0 Host 1x USB 2 Host Gigabit Ethernet HDMI 1.4a PWM für Lüfter 30 PIN GPIO/IRQ/SPI/ADC 12PIN GPIO/I2S/I2C UART für serial console || 4x USB 2 Host 2 x USB HOST 1 x OTG HDMI&VGA 1080P 1 x Toslink (SPDIF Optical) 1 x IR 1 Headphone Wifi+BT wireless|| 2x USB 2 Host 2x USB 3 Host Stereo Ausgang und HDMI Wifi+BT wireless 40-pin extended GPIO
|-
| Power || 5V 4A Stecker innen 2.1mm und außen 5.5mm|| 5V 2.5A || 5V 2.5A micro USB
|-
| Preis ca. (Stand Februar 2023) || ca 80€ || ca 140€ || 210€
|-
|}
Das XU4 Board gibt es in zwei Versionen. Einmal der XU4 mit PWM gesteuertem Lüfter auf einem Kühlkörper und dann die XU4Q Version ohne Lüfter aber dafür mit einem größeren Kühlkörper. Der Prozessor hat mehrere Profile zur Auswahl wie die einzelnen Kern Gruppen (A15 oder A7) Takten. Es kann dabei die maximale Taktfrequenz der BIG Cores (A15) eingestellt werden oder auch das Leistungsprofil der gesamten CPU (interactive, conservative, ondemand, powersave, performance).
Der Prozessor bewegt sich bei beiden Hardware Versionen mehr auf der warmen Seite. Temperaturen bis 80°C sind unter last keine Seltenheit aber auch kein Problem da der Prozessor bei 105°C automatisch heruntertaktet oder wenn nötig die BIG Cores offline schaltet.

__TOC__

== Vefügbare Betriebssysteme ==
Stand 12/2017 
Im Odroid Forum oder direkt von der Hardkernel WIKI zu beziehen. 
Zusätzlich gibt es noch ein monatlich erscheinendes Magazin mit Projekten und HowTo's

=== Offizielle Images ===
Android 4.4.4 
Ubuntu 16.04 (Kernel 3.10.y), Ubuntu 16.04.2 (LTS Kernel 4.9.y), Ubuntu 16.04.2 (LTS Kernel 4.14.y) 
=== Third Party ===
Debian/Jessie, DietPi, Armbian Ubuntu/Debian 
Arch Linux, Kali Linux 
Android 7.1 Nougat, LineageOS-14.1, Android TV OS 
OpenmediaVault, RecalBox, Lakka 
GameStation Turbo mit XBMC 

== Erste Inbetriebnahme ==
Als Betriebssystem eignet sich, wegen die Nähe zum RaspberryPi System, ein Debian Betriebssystem. Ein gut gepflegtes System das auch für Anfänger geeignet sein sollte (Viele Scrpits die per SSH alle konfiguartionen und installationen automatisieren) ist DietPi. 
Momentan ist DietPi in der Version 6.15 und enthält den Stretch Kernel in der Version 4.14.66+.
In diesem Artikel wird die Installation auf SD Karte mit hilfe eines Windown PC beschrieben.

=== Download von DietPi und Vorbereitung der SD Karte ===
Von der [http://dietpi.com/ DietPi Homapage] kann nach Auswahl der XU4 das System heruntergeladen werden.
Nach dem Auspacken unter Windows wird das Image mit dem Win32Diskmanager (bei Hardkernel gibt es eine extra Version mit Verify Funktion) oder mit der Software Etcher auf die SD Karte geschrieben.
 

Falls direkt mit einem WIFI USB Stick gearbeitet werden soll kann das System vor dem ersten Boot darauf vorbereitet werden:
 
<syntaxhighlight lang="bash">
Die SD karte in den Kartenleser am PC stecken (Warnungen der nicht lesbaren Partition ignorieren)
Die lesbare Partition öffnen und darin die datei dietpi.txt öffnen
Darin (Kommentar Zeichen # vor den zeilen entfernen):

Wifi_Enabled=1
Wifi_SSID=DeineSSID
Wifi_KEY=DeinWIFIKey

Vor dem ersten Start den USB Wifi Adapter einstecken
SD karte in die XU4 stecken.
Stromversorgung einschalten.
Warten bis DietPi das Dateisystem vorbereitet hat, es kommt dabei auch zwei mal zu einem Reboot.
</syntaxhighlight>

=== Weiteres bearbeiten des Systems über SSH ===
DietPi kommt mit Dropbear SSH Server vorinstalliert. Man sollte sich nach der installation über Putty mit dem System verbinden können.
<syntaxhighlight lang="bash">
username = root
password = dietpi

Über den Befehl:
dietpi-config
Hat man auf umfangreiche Einstellungen zugriff.
z.B.
Zeitzone einstellen
Router Verbindungen einstellen DHCP/Static etc.

</syntaxhighlight>

== Installation von FHEM ==
Die FHEM installation kann danach von der Bash aus gestartet werden.
Dazu über Putty Verbindung aufbauen und FHEM Installieren. Laut der FHEM for Debian Seite ist folgendes zu tun.
<syntaxhighlight lang="bash">
wget -qO - http://debian.fhem.de/archive.key | apt-key ad
</syntaxhighlight>

Zu der Datei /etc/apt/sources.list folgendes anfügen:
<syntaxhighlight lang="bash">
deb http://debian.fhem.de/nightly/ /
</syntaxhighlight>

danach
<syntaxhighlight lang="bash">
apt-get update
apt-get install fhem
reboot now
</syntaxhighlight>

Danach sollte FHEM unter eurer XU4 IP erreichbar sein.
Als erstes in die FHEM Commandozeile folgendes eingeben
<syntaxhighlight lang="bash">
update all
</syntaxhighlight>

==Weitere Konfiguartion==
Zusätzlich zu der Grundinstallation lassen sich noch weitere Einstellungen vornhemen. Grundsätzlich sind alle Änderungen auch mit der Linux bash und spt-get etc. durchzuführen. Da DietPi aber viele scripte mitbringt die auch in allen Parameter an das System angepasst sind sollte zuerst die Installation oder Einrichtung darüber durchgeführt werden. 
Alle Scripts von DietPi sind über folgenden Befehl zu erreichen
<syntaxhighlight lang="bash">
dietpi-launcher
</syntaxhighlight>
Ich gehe hier nur auf einige Module direkt ein, die anderen können je nach Aufbau des Heimsystems auch noch nützlich sein.
===Backup===
Nach erfolgreicher Installation kann von dem komplette System (Linux inklusive aller User dateien) ein Backup angelegt werden. 
Dazu per SSH verbinden und folgendes starten
<syntaxhighlight lang="bash">
dietpi-backup
</syntaxhighlight>
Danach kann dort der Speicherort, der Umfang (System oder System und User data) oder ob ein Backup bzw. ein Restore gemacht werden soll, ausgewählt werden.
Im Falle eines System crash, einfach DietPi neu installieren und über das Dietpi-backup ein restore durchführen.
Das Backup ist inkrementell und ändert bei erneutem durchführen nur die veränderten oder neuen Dateien ab. Möchten man ein komplett neues Backup anlegen so ist ein anderer Speicherort (Ordner) zu wählen. Beim Restore kann dann die Version (Ordner) ausgesucht werden.

===RootFS auslagern===
Ein angeschlossene HDD/SSD oder auch ein USB Stick können dazu benutzt werden das RootFS darauf auszulagern. Die SD karte ist dann leider immer noch notwendig wird aber nur zum Bootvorgang benutzt 
Zum Start der Umlagerung gibt man folgendes ein
<syntaxhighlight lang="bash">
dietpi-drive_manager
</syntaxhighlight>
Es wird dann eine Auflistung der mounted drives angezeigt.
<syntaxhighlight lang="bash">
Von der SD Karte
/dev/mmcblklp1 ist das Boot Drive
/deb/mmcblklp2 ist die System Partition

und

/dev/sda/1 ist zum Beispiel dann eine angeschlossene HDD/SSD
</syntaxhighlight>
Dann wählt man das Drive aus auf den man das RootFS auslagern möchte 
Es werden dann einige Details der Partition angezeigt, zusätzlich gibt es noch mal ein Auswahlmenü. 
<syntaxhighlight lang="bash">
Unmount : Allows you to physically remove the drive
Move User data : Move your DietPi user data to this drive
Mount Method : Change from UUID to dev/sd
Read only : Disabled | Select to set read only
Format : Wipe all data and format drive with ext4
Transfer RootFS : Transfer RootFS to this drive
</syntaxhighlight>
Um den Transer zu starten wird das letzte Menu ausgewählt und mit return gestartet. sollte das Drive noch zu formatieren sein kann dies ebenso im Drive Manager geschehen. Das Menu ist ja oben schon aufgeführt. 
Alle Menüs sund Dialog geführt und geben einen Hinweiß wenn etwas nicht funktionieren sollte bzw. noch etwas zu ändern ist. 
Nach dem Ende des Vorgangs und einem Reboot startet das System nun von der Platte. 
Falls nötig kann jederzeit das System wieder auf die SD Karte umgelagert werden. Dazu im Drive manager Menü als zu bearbeitende Partition die SD System Partition auswählen. Ein Backup danach nicht vergessen.

==Zusätzliche Perl Module==
Falls, je nach Nutzung von FHEM, noch zusätzliche FHEM Module installiert werden müssen konnte ich dies immer mit den Debian Paket Manager nach den Anleitungen aus dem FHEM Forum oder der WIKI für debian-jessie tun. 
Zum Beispiel
<syntaxhighlight lang="bash">
JSON
apt-get install libjson-perl

AES
apt-get install libcrypt-cbc-perl
apt-get install libcrypt-rijndael-perl
apt-get install libssl-dev
apt-get install libcrypt-openssl-rsa-perl
apt-get install make
apt-get install gcc
apt-install libc6-dev
cpan Crypt/OpenSSL/AES.pm
</syntaxhighlight>
Einige Module sind schon vorhanden andere müssen eben wie gezeigt nachinstalliert werden.

==Fehlersuche==
Hier noch der eine oder andere Tip für die Fehlersuche am XU4 
===Heartbeat===
Das Board hat eine rote und eine blaue LED. Die rote LED ist die Anzeige für die Stromversorgung. Diese Leuchtet sobald der Strom verfügbar ist. Auch wenn das Board nicht aktiv ist. 
Die blaue LED Leuchtet dauerhaft während des Boot Vorgangs und fängt dann im Sekundentakt (Heartbeat) an zu zu blinken sobald der Kernel läuft.
<syntaxhighlight lang="bash">
blink-blink -> 1 sec pause -> blink-blink usw.
</syntaxhighlight>
Sollte die LED nicht blinken wurde der Bootvorgang nicht sauber durchgeführt un der Kernel nicht gestartet. 
Dies kann verschiedene Ursachen haben. 
Unter anderem 
 
Stromversorgung defekt 
SD karte defekt 
 
Die Stromversorgung MUSS 5V und mindestens 4A haben, falls weniger Leistung zur Verfügung steht kommt es zu Boot Problemen. 
Es kann aber auch ein Problem mit der SD karte existieren (System, Boot Partition, SD defekt). Abhilfe bringt meist ein flashen der SD Karte. Wenn ein Backup erstellt wurde ist dies natürlich kein Problem.
<syntaxhighlight lang="bash">
SD karte neu flashen
eventuell RootFS wieder auslagern

FHEM neu Aufspielen
FHEM Backup einspielen
Rechte anpassen
oder
Komplettes XU4 Backup über dietpi-backup wieder einspielen.
</syntaxhighlight>

==Links==
Link zum Ordoid [https://forum.odroid.com/ Forum] 
Link zur Odroid [https://wiki.odroid.com/ WIKI] 
Link zum Odroid [https://magazine.odroid.com/ Magazin] 
Link zur [https://debian.fhem.de/ FHEM for Debian] Seite 
Link zu DietPi [https://dietpi.com/]

[[Kategorie:Server Hardware]]

ODROID XU4

2023-02-11T20:14:49Z

AlanBlack:

Beim ODROID XU4 handelt es sich um einen Einplatinencomputer von [http://www.hardkernel.com/main/products/prdt_info.php Hardkernel] mit dem Exynos5422 Octa Core Prozessor bestehend aus 4x Cortex(TM) -A15 2Ghz und 4x Cortex(TM) -A7 1.4Ghz. 
der XU4 ist der Nachfolger des XU3 und ist von der Systemebene kompatibel. Es sind aus diesem Grund viele System Images des XU4 mit der Endung XU3 versehen.
Zum Vergleich ist in der Tabelle [[Cubieboard 3|Cubieboard]] und [[Raspberry Pi|Raspberry Pi 3b]] aufgeführt. Die Tabelle soll nur einen Überblick darstellen und erhebt keinen Anspruch auf Vollständigkeit.
{| class="wikitable zebra toptextcells" style="text-align:center"
! Eigenschaft !! ODROID XU4 !! Cubieboard '''3''' || Raspberry Pi '''4''' Model B
|-
| SOC || Exynos5422 || AllWinnerTech SOC A20 || Broadcom BCM2711
|-
| ARM Cortex || 4x A15 + 4x A7 || A7 || A72
|-
| Takt || 2Ghz + 1.4Ghz || 0.9GHz || 1.2GHz
|-
| RAM || 2Gbyte DDR 3 || 1GB/2GB DDR3@480MHz || 4Gbyte
|-
| Arbeitsspeicher || eMMC 5.0 Slot microSD Slot || NAND+MicroSD TSD+ MicroSD 2x MicroSD || microSD
|-
| RTC || Ja, Battery Buffered || Ja, Battery Buffered || Nein
|-
| Peripherie || 2x USB 3.0 Host 1x USB 2 Host Gigabit Ethernet HDMI 1.4a PWM für Lüfter 30 PIN GPIO/IRQ/SPI/ADC 12PIN GPIO/I2S/I2C UART für serial console || 4x USB 2 Host 2 x USB HOST 1 x OTG HDMI&VGA 1080P 1 x Toslink (SPDIF Optical) 1 x IR 1 Headphone Wifi+BT wireless|| 2x USB 2 Host 2x USB 3 Host Stereo Ausgang und HDMI Wifi+BT wireless 40-pin extended GPIO
|-
| Power || 5V 4A Stecker innen 2.1mm und außen 5.5mm|| 5V 2.5A || 5V 2.5A micro USB
|-
| Preis ca. (Stand Februar 2023) || ca 80€ || ca 140€ || 210€
|-
|}
Das XU4 Board gibt es in zwei Versionen. Einmal der XU4 mit PWM gesteuertem Lüfter auf einem Kühlkörper und dann die XU4Q Version ohne Lüfter aber dafür mit einem größeren Kühlkörper. Der Prozessor hat mehrere Profile zur Auswahl wie die einzelnen Kern Gruppen (A15 oder A7) Takten. Es kann dabei die maximale Taktfrequenz der BIG Cores (A15) eingestellt werden oder auch das Leistungsprofil der gesamten CPU (interactive, conservative, ondemand, powersave, performance).
Der Prozessor bewegt sich bei beiden Hardware Versionen mehr auf der warmen Seite. Temperaturen bis 80°C sind unter last keine Seltenheit aber auch kein Problem da der Prozessor bei 105°C automatisch heruntertaktet oder wenn nötig die BIG Cores offline schaltet.

__TOC__

== Vefügbare Betriebssysteme ==
Stand 12/2017 
Im Odroid Forum oder direkt von der Hardkernel WIKI zu beziehen. 
Zusätzlich gibt es noch ein monatlich erscheinendes Magazin mit Projekten und HowTo's

=== Offizielle Images ===
Android 4.4.4 
Ubuntu 16.04 (Kernel 3.10.y), Ubuntu 16.04.2 (LTS Kernel 4.9.y), Ubuntu 16.04.2 (LTS Kernel 4.14.y) 
=== Third Party ===
Debian/Jessie, DietPi, Armbian Ubuntu/Debian 
Arch Linux, Kali Linux 
Android 7.1 Nougat, LineageOS-14.1, Android TV OS 
OpenmediaVault, RecalBox, Lakka 
GameStation Turbo mit XBMC 

== Erste Inbetriebnahme ==
Als Betriebssystem eignet sich, wegen die Nähe zum RaspberryPi System, ein Debian Betriebssystem. Ein gut gepflegtes System das auch für Anfänger geeignet sein sollte (Viele Scrpits die per SSH alle konfiguartionen und installationen automatisieren) ist DietPi. 
Momentan ist DietPi in der Version 6.15 und enthält den Stretch Kernel in der Version 4.14.66+.
In diesem Artikel wird die Installation auf SD Karte mit hilfe eines Windown PC beschrieben.

=== Download von DietPi und Vorbereitung der SD Karte ===
Von der [http://dietpi.com/ DietPi Homapage] kann nach Auswahl der XU4 das System heruntergeladen werden.
Nach dem Auspacken unter Windows wird das Image mit dem Win32Diskmanager (bei Hardkernel gibt es eine extra Version mit Verify Funktion) oder mit der Software Etcher auf die SD Karte geschrieben.
 

Falls direkt mit einem WIFI USB Stick gearbeitet werden soll kann das System vor dem ersten Boot darauf vorbereitet werden:
 
<syntaxhighlight lang="bash">
Die SD karte in den Kartenleser am PC stecken (Warnungen der nicht lesbaren Partition ignorieren)
Die lesbare Partition öffnen und darin die datei dietpi.txt öffnen
Darin (Kommentar Zeichen # vor den zeilen entfernen):

Wifi_Enabled=1
Wifi_SSID=DeineSSID
Wifi_KEY=DeinWIFIKey

Vor dem ersten Start den USB Wifi Adapter einstecken
SD karte in die XU4 stecken.
Stromversorgung einschalten.
Warten bis DietPi das Dateisystem vorbereitet hat, es kommt dabei auch zwei mal zu einem Reboot.
</syntaxhighlight>

=== Weiteres bearbeiten des Systems über SSH ===
DietPi kommt mit Dropbear SSH Server vorinstalliert. Man sollte sich nach der installation über Putty mit dem System verbinden können.
<syntaxhighlight lang="bash">
username = root
password = dietpi

Über den Befehl:
dietpi-config
Hat man auf umfangreiche Einstellungen zugriff.
z.B.
Zeitzone einstellen
Router Verbindungen einstellen DHCP/Static etc.

</syntaxhighlight>

== Installation von FHEM ==
Die FHEM installation kann danach von der Bash aus gestartet werden.
Dazu über Putty Verbindung aufbauen und FHEM Installieren. Laut der FHEM for Debian Seite ist folgendes zu tun.
<syntaxhighlight lang="bash">
wget -qO - http://debian.fhem.de/archive.key | apt-key ad
</syntaxhighlight>

Zu der Datei /etc/apt/sources.list folgendes anfügen:
<syntaxhighlight lang="bash">
deb http://debian.fhem.de/nightly/ /
</syntaxhighlight>

danach
<syntaxhighlight lang="bash">
apt-get update
apt-get install fhem
reboot now
</syntaxhighlight>

Danach sollte FHEM unter eurer XU4 IP erreichbar sein.
Als erstes in die FHEM Commandozeile folgendes eingeben
<syntaxhighlight lang="bash">
update all
</syntaxhighlight>

==Weitere Konfiguartion==
Zusätzlich zu der Grundinstallation lassen sich noch weitere Einstellungen vornhemen. Grundsätzlich sind alle Änderungen auch mit der Linux bash und spt-get etc. durchzuführen. Da DietPi aber viele scripte mitbringt die auch in allen Parameter an das System angepasst sind sollte zuerst die Installation oder Einrichtung darüber durchgeführt werden. 
Alle Scripts von DietPi sind über folgenden Befehl zu erreichen
<syntaxhighlight lang="bash">
dietpi-launcher
</syntaxhighlight>
Ich gehe hier nur auf einige Module direkt ein, die anderen können je nach Aufbau des Heimsystems auch noch nützlich sein.
===Backup===
Nach erfolgreicher Installation kann von dem komplette System (Linux inklusive aller User dateien) ein Backup angelegt werden. 
Dazu per SSH verbinden und folgendes starten
<syntaxhighlight lang="bash">
dietpi-backup
</syntaxhighlight>
Danach kann dort der Speicherort, der Umfang (System oder System und User data) oder ob ein Backup bzw. ein Restore gemacht werden soll, ausgewählt werden.
Im Falle eines System crash, einfach DietPi neu installieren und über das Dietpi-backup ein restore durchführen.
Das Backup ist inkrementell und ändert bei erneutem durchführen nur die veränderten oder neuen Dateien ab. Möchten man ein komplett neues Backup anlegen so ist ein anderer Speicherort (Ordner) zu wählen. Beim Restore kann dann die Version (Ordner) ausgesucht werden.

===RootFS auslagern===
Ein angeschlossene HDD/SSD oder auch ein USB Stick können dazu benutzt werden das RootFS darauf auszulagern. Die SD karte ist dann leider immer noch notwendig wird aber nur zum Bootvorgang benutzt 
Zum Start der Umlagerung gibt man folgendes ein
<syntaxhighlight lang="bash">
dietpi-drive_manager
</syntaxhighlight>
Es wird dann eine Auflistung der mounted drives angezeigt.
<syntaxhighlight lang="bash">
Von der SD Karte
/dev/mmcblklp1 ist das Boot Drive
/deb/mmcblklp2 ist die System Partition

und

/dev/sda/1 ist zum Beispiel dann eine angeschlossene HDD/SSD
</syntaxhighlight>
Dann wählt man das Drive aus auf den man das RootFS auslagern möchte 
Es werden dann einige Details der Partition angezeigt, zusätzlich gibt es noch mal ein Auswahlmenü. 
<syntaxhighlight lang="bash">
Unmount : Allows you to physically remove the drive
Move User data : Move your DietPi user data to this drive
Mount Method : Change from UUID to dev/sd
Read only : Disabled | Select to set read only
Format : Wipe all data and format drive with ext4
Transfer RootFS : Transfer RootFS to this drive
</syntaxhighlight>
Um den Transer zu starten wird das letzte Menu ausgewählt und mit return gestartet. sollte das Drive noch zu formatieren sein kann dies ebenso im Drive Manager geschehen. Das Menu ist ja oben schon aufgeführt. 
Alle Menüs sund Dialog geführt und geben einen Hinweiß wenn etwas nicht funktionieren sollte bzw. noch etwas zu ändern ist. 
Nach dem Ende des Vorgangs und einem Reboot startet das System nun von der Platte. 
Falls nötig kann jederzeit das System wieder auf die SD Karte umgelagert werden. Dazu im Drive manager Menü als zu bearbeitende Partition die SD System Partition auswählen. Ein Backup danach nicht vergessen.

==Zusätzliche Perl Module==
Falls, je nach Nutzung von FHEM, noch zusätzliche FHEM Module installiert werden müssen konnte ich dies immer mit den Debian Paket Manager nach den Anleitungen aus dem FHEM Forum oder der WIKI für debian-jessie tun. 
Zum Beispiel
<syntaxhighlight lang="bash">
JSON
apt-get install libjson-perl

AES
apt-get install libcrypt-cbc-perl
apt-get install libcrypt-rijndael-perl
apt-get install libssl-dev
apt-get install libcrypt-openssl-rsa-perl
apt-get install make
apt-get install gcc
apt-install libc6-dev
cpan Crypt/OpenSSL/AES.pm
</syntaxhighlight>
Einige Module sind schon vorhanden andere müssen eben wie gezeigt nachinstalliert werden.

==Fehlersuche==
Hier noch der eine oder andere Tip für die Fehlersuche am XU4 
===Heartbeat===
Das Board hat eine rote und eine blaue LED. Die rote LED ist die Anzeige für die Stromversorgung. Diese Leuchtet sobald der Strom verfügbar ist. Auch wenn das Board nicht aktiv ist. 
Die blaue LED Leuchtet dauerhaft während des Boot Vorgangs und fängt dann im Sekundentakt (Heartbeat) an zu zu blinken sobald der Kernel läuft.
<syntaxhighlight lang="bash">
blink-blink -> 1 sec pause -> blink-blink usw.
</syntaxhighlight>
Sollte die LED nicht blinken wurde der Bootvorgang nicht sauber durchgeführt un der Kernel nicht gestartet. 
Dies kann verschiedene Ursachen haben. 
Unter anderem 
 
Stromversorgung defekt 
SD karte defekt 
 
Die Stromversorgung MUSS 5V und mindestens 4A haben, falls weniger Leistung zur Verfügung steht kommt es zu Boot Problemen. 
Es kann aber auch ein Problem mit der SD karte existieren (System, Boot Partition, SD defekt). Abhilfe bringt meist ein flashen der SD Karte. Wenn ein Backup erstellt wurde ist dies natürlich kein Problem.
<syntaxhighlight lang="bash">
SD karte neu flashen
eventuell RootFS wieder auslagern

FHEM neu Aufspielen
FHEM Backup einspielen
Rechte anpassen
oder
Komplettes XU4 Backup über dietpi-backup wieder einspielen.
</syntaxhighlight>

==Links==
Link zum Ordoid [https://forum.odroid.com/ Forum] 
Link zur Odroid [https://wiki.odroid.com/ WIKI] 
Link zum Odroid [https://magazine.odroid.com/ Magazin] 
Link zur [https://debian.fhem.de/ FHEM for Debian] Seite 
Link zu DietPi [https://dietpi.com/]

[[Kategorie:Server Hardware]]

DbLog

2023-01-26T18:09:23Z

AlanBlack: /* Beispiel: Anlegen und Nutzung einer SQLite-Datenbank */

{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Automatisierung
|ModTechName=93_DbLog.pm
|ModOwner=tobiasfaust ({{Link2FU|118|Forum}}/[[Benutzer Diskussion:Tobias.faust|Wiki]]) DS_Starter ({{Link2FU|16933|Forum}}/[[Benutzer Diskussion:DS_Starter|Wiki]])
}}
== Einleitung ==
Mit der Zeit entstehen in FHEM recht umfangreiche Log-Daten für die verschiedensten konfigurierten Devices. Die übliche Einstiegs-[[Konfiguration]] sieht vor, dass die Logs als {{Link2CmdRef|Lang=de|Anker=FileLog|Label=FileLog}} gespeichert werden - je nach Einstellung in wenigen sehr großen oder vielen kleineren Dateien. Der Datei-basierte Zugriff ist allerdings nicht wirklich performant und kann schnell zum Flaschenhals werden (z.B. bei der Darstellung von Graphen über einen längeren Zeitraum).

Alternativ kann FHEM die Log-Daten mittels {{Link2CmdRef|Lang=de|Anker=DbLog|Label=DbLog}} in einer Datenbank speichern. Diese kann lokal als einfache SQLite- oder als zentrale Server-Datenbank (s.u.) gestaltet sein. Schon eine lokale einfache SQLite-Datenbank ist in der Regel deutlich performanter als File-basierte Logs.

Damit eine Datenbank-Nutzung möglich ist, müssen folgende Anpassungen gemacht werden:
# [[#Datenbank|Erstellen einer entsprechenden Datenbank]]
# [[#Datenbank-Anbindung mittels db.conf|Konfiguration der Datenbank-Anbindung in FHEM]]
# [[#Konfiguration als Device in fhem.cfg|Anpassen aller (oder einzelner) Konfigurationen von FileLog nach DbLog]]
# [[#Anpassen der gplot-Konfigurationen|Ggf. Anpassen der gplot-Konfigurationen]]

Eine weitere Alternative bietet das Modul [[InfluxDBLogger]].

Reporting und Management von DbLog-Datenbankinhalten kann mit dem Modul [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] stattfinden.

== Konfiguration ==
=== Datenbank-Anbindung mittels db.conf ===
{{Randnotiz|RNTyp=y|RNText='''Anmerkung''': MariaDB10 nutzt nicht Port 3306 sondern 3307. Dies ist zum Beispiel bei Synology NAS der Fall.}}
DbLog wird durch 2 verschiedene Einträge aktiviert/definiert. In einer Datei namens '''db.conf''' werden die Parameter für eine Verbindung zur Datenbank (host, username, password, etc.) hinterlegt. Diese Datei kann in einem beliebigen Verzeichnis angelegt werden. Für eine MySQL-Datenbank sieht die db.conf folgendermaßen aus:

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

Im Verzeichnis '''contrib/dblog''' der FHEM-Installation befindet sich eine Beispielkonfiguration mit der Syntax für jeden unterstützen Datenbanktyp.
Es wird empfohlen, diese Datei zu kopieren und erst dann entsprechend zu bearbeiten. Am Besten kopiert man diese Datei in das FHEM Home Directory /opt/fhem/ und achtet auf die entsprechenden Rechte!
<syntaxhighlight lang="bash">chown fhem:dialout /opt/fhem/db.conf</syntaxhighlight>

=== Konfiguration als Device ===
Das DbLog Device wird dann definiert mit
:<code>define <name> DbLog <configfilename> <regexp> </code>
wobei ''<configfilename>'' dem Pfad zur zuvor angelegten db.conf entspricht.
Ein Beispiel hierfür wäre:
:<code>define logdb DbLog ./db.conf .*:.* </code>
Die Angabe von <code>.*:.*</code> bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit vielen teils irrelevanten Werten gefüllt wird. Man kann daher die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Dies ist in [[#Finetuning des Loggings]] beschrieben.

Unbedingt beachten: bei Verwendung des Moduls configdb wird die Konfigurationsdatei aus der '''''Datenbank''''' gelesen. Deshalb ist es erforderlich, die Datei mittels <code>configdb fileimport db.conf </code> vorher zu importieren !

=== Finetuning des Loggings ===
Bei der Konfiguration des Log-Devices werden die zu loggenden Daten definiert - in der einfachsten Form sieht das so aus: <code>define logdb DbLog ./db.conf .*:.* </code>. Die Angabe von <code>.*:.*</code> bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit sehr vielen und teils nicht benötigten Werten gefüllt wird und schnell wächst. Die Datenbank ist zwar deutlich leistungsfähiger, was große Datenmengen angeht, Datensparsamkeit kann aber schnell sinnvoll werden...

Um das Log-Aufkommen einzugrenzen gibt es mehrere Ansätze:
* Einschränkung über den <code>define</code>-Eintrag
* Einschränkung über DbLogExclude-Einträge der jeweiligen Devices
* Einschränkung über DbLogInclude-Einträge des jeweiligen Devices
* Ausschluß von Device/Reading-Kombinationen über das Attribut "excludeDevs". Es können {{Link2CmdRef|Anker=devspec|Lang=de|Label=devspec}} verwendet werden.

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
Man kann die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Die erste Wildcard, also das erste <code>.*</code>, entspricht dem in FHEM verwendeten Device-Namen. Die zweite Wildcard entspricht dem vom Device ausgegebenen zu loggenden Wert. Separiert werden beiden Angaben durch einen Doppelpunkt.

Ein Beispiel, um zwar alle definierten Devices zu erfassen, aber nur die Werte Temperatur, Ventilposition und Luftfeuchte in die Datenbank zu schreiben wäre:
:<code>define myDbLog DbLog ./db.conf .*:(temperature|valveposition|humidity).* </code>

==== Einschränkung über die jeweiligen Devices ====
Man kann die zu loggenden Werte für einzelne Devices separat einschränken, ohne dies im zentralen define-Eintrag machen zu müssen. Dies kann interessant sein, wenn beispielsweise ein Device Fehlerwerte meldet, die uninteressant sind, oder es meldet unnötig häufig Werte - beides ist z.B. bei 1-wire-Temperatursensoren gerne der Fall.

Um das einzuschränken gibt es 2 Stellparameter, die als Attribute direkt zum jeweiligen Device konfiguriert werden:
* DbLogExclude - definiert Werte, die nicht geloggt werden sollen
* DbLogInclude - definiert Werte, die geloggt werden sollen ( siehe attr DbLogSelectionMode )
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})

Eine konkrete Konfiguration für einen sehr gesprächigen 1-wire-Temperatursensor könnte wie folgt aussehen:
<pre>
define EG_Balkon GPIO4 BUSMASTER
attr EG_Balkon DbLogExclude failures,T,85 # logge keine "failures", "T"-Werte und "85"-Werte (default-Werte, wenn keine Temperatur gelesen werden kann)
attr EG_Balkon event-on-change-reading state # logge nur, wenn sich ein Wert ändert (wenn sich die Temperatur nicht ändert, logge das nicht)
attr EG_Balkon event-min-interval state:900 # logge spätestens alle 900sec = 15min
attr EG_Balkon event-on-update-reading .* # logge alle Werte, die aktualisiert werden

attr <1-Wire-Device vom Typ OWTHERM oder OWSWITCH> DbLogExclude data.* # verhindert das Logging der state-Eintragungen
</pre>

Eine in diesem {{Link2Forum|Topic=33697|Message=264127}} vorgestellte Strategie zur Vermeidung unnötigen Loggings ist, dass bei der Definition von Devices durch das nachfolgende <code>notify</code> automatisch ein DbLogExclude für alle Werte (.*) des Devices zugewiesen wird und dies nur bei Interesse an geloggten Werten gelöscht bzw. angepasst wird:
<code>define nDbLogExclude notify global:DEFINED.* attr $EVTPART1 DbLogExclude .*</code>

Ebenso ist es mittlerweile möglich, lediglich erwünschte Werte (Positiv-Liste) zu loggen und alle anderen zu verwerfen. Hierfür wird im LogDevice das attribut DbLogSelectionMode Include verwendet. Nun kann für jedes Device mit DbLogInclude <Reading1>,<Reading2>,... angegeben werden, welche Readings geloggt werden sollen.
Integriert ist ebenfalls ein "min-interval", siehe {{Link2CmdRef}}.

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

=== Tabellen ===
Die Datenbank ist relativ simpel gestaltet und besteht lediglich aus den folgenden beiden Tabellen:
* current
* history

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

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

==== current ====
Die Tabelle current enthält für jedes zu loggende Device lediglich den letzten Wert. Falls noch kein Wert geloggt wurde, ist diese Tabelle leer.
Falls der Inhalt gelöscht wird, bauen sich die Daten automatisch wieder auf. Es gehen durch das löschen der Tabelle current keine Log-Informationen verloren.
Der Inhalt wird aber u.a. für die Dropdown-Felder beim Plot-Editor verwendet.

Um doppelte Einträge in der Tabelle zu vermeiden, wurden die Möglichkeit geschaffen Primary Keys zu definieren. Da in der Spalte <code>READING</code> u.U. bei verschiedenen Geräten gleiche Namen vorkommen können, sollte der Primary Key um den Gerätenamen erweitert werden. Der Primary Key sollte also aus <code>DEVICE</code> und <code>READING</code> bestehen. Um in der Datenbank ''fhem'' diesen PK zu setzen, kann folgender SQL Code verwendet werden:

<syntaxhighlight lang="sql">
ALTER TABLE `fhem`.`current`
CHANGE COLUMN `DEVICE` `DEVICE` VARCHAR(64) CHARACTER SET 'utf8' COLLATE 'utf8_bin' NOT NULL ,
CHANGE COLUMN `READING` `READING` VARCHAR(64) CHARACTER SET 'utf8' COLLATE 'utf8_bin' NOT NULL ,
ADD PRIMARY KEY (`DEVICE`, `READING`);
</syntaxhighlight>Achtung: Die Tabelle "current" wird nur befüllt, wenn das Attribut DbLogType auf Current oder Current/History gesetzt ist.

==== history ====
Die Tabelle history enthält alle bisher geloggten Daten. Löschen in dieser Tabelle bedeutet automatisch Datenverlust (gewollt oder nicht ... )
Der Inhalt dieser Tabelle wird verwendet, um die Plots zu zeichnen oder Auswertungen mit [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] anzufertigen

{{Todo|Ausbauen}}

Um Problem beim Import von cacheFiles zu vermeiden, kann in der Datenbank ein PK angelegt werden, welcher Timestamp, Device und Reading umfasst. Dadurch werden doppelte Einträge wirksam verhindert.

== Anpassen der gplot-Konfigurationen ==
Die meisten gplot-Konfigurationen sind bisher lediglich auf FileLog-Konfigurationen ausgelegt. Deshalb müssen sie für die Verwendung mit DbLog angepasst werden. Glücklicherweise beschränkt sich dies auf die reinen FileLog-Zeilen - es müssen die DbLog-Äquivalente hinzugefügt werden. Die FileLog-Einträge müssen zwar nicht gelöscht werden, wenn man aber FileLog und DbLog parallel betreibt, sollte man getrennte gplot-Dateien für beide Logging-Typen haben um Auswertungsprobleme erkennen zu können.

Für die fht.gplot Konfiguration sähe die Anpassung wie folgt aus (lediglich die vier DbLog-Zeilen wurden hinzugefügt):
<syntaxhighlight lang="Perl">
# Created by FHEM/98_SVG.pm, 2014-12-25 21:53:30
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics nomirror
set y2tics
set grid y2tics
set ylabel "Actuator/Window (%)"
set y2label "Temperature in C"
set yrange 0:100
set y2range 5:25

#FileLog 4:.measured-temp\x3a:0:
#FileLog 4:.actuator\x3a:0:int
#FileLog 4:.desired-temp::
#FileLog 4:.window\x3a::

#DbLog <SPEC1>:.measured-temp:0:
#DbLog <SPEC1>:.actuator:0:int
#DbLog <SPEC1>:.desired-temp::
#DbLog <SPEC1>:.window::

plot "<IN>" using 1:2 axes x1y2 title 'Measured temperature' ls l0 lw 1 with lines,\
"<IN>" using 1:2 axes x1y1 title 'Actuator (%)' ls l1 lw 1 with lines,\
"<IN>" using 1:2 axes x1y2 title 'Desired Temperature' ls l2 lw 1 with steps,\
"<IN>" using 1:2 axes x1y1 title 'Window' ls l3 lw 1 with steps
</syntaxhighlight>

Des Weiteren ist zu beachten:

On-Off-Plots

EG_Bad:window:::$val=~s/(on|off)(\d*).*/$1eq"on"?1:0/eg

unter Berücksichtigung von dim-Werten:

EG_WoZi_Licht:value:::$val=~s/(on|off)(\d*).*/$1eq"on"?1:($1eq"dim"?$2*0.01:0)/eg

== Beispiel: Anlegen und Nutzung einer SQLite-Datenbank ==
Im folgenden wird eine lokale SQLite-Datenbank auf einen Ubuntu-System angelegt (nach Quelle: http://www.tatsch-it.de/fhem-dblog/)
<ol>
<li>''Installation von SQLite:''
<pre>sudo aptitude install sqlite3 libdbi-perl libdbd-sqlite3-perl

oder auf aktuellerem Stand

sudo apt install sqlite3</pre>
</li>
<li>''Anlegen der SQLite-Datenbank fhem.db'' (öffnet auch direkt eine SQL-Kommandozeile):
<pre>sudo sqlite3 /opt/fhem/fhem.db</pre>
In der geöffneten SQL-Kommandozeile eingeben:
<pre>
CREATE TABLE history (TIMESTAMP TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
CREATE TABLE current (TIMESTAMP TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
CREATE INDEX Search_Idx ON `history` (DEVICE, READING, TIMESTAMP);
</pre>
Die Kommandozeile verlässt man mit <code>.exit</code>.
</li>
<li>''Anpassen des Besitzers und der Rechte der Datenbank-Datei:''
<pre>
sudo chown fhem /opt/fhem/fhem.db
sudo chmod 600 /opt/fhem/fhem.db
</pre>
</li>
<li>''Datenbank-Anbindung des FHEM konfigurieren:''
<pre>sudo nano /opt/fhem/db.conf</pre>
Inhalt:
<pre>
%dbconfig= (
connection => "SQLite:dbname=/opt/fhem/fhem.db",
user => "",
password => ""
);
</pre>
</li>
<li>''Logging des FHEM auf die Datenbank konfigurieren:'' (hier sind nur die Anpassungen aufgeführt)
<pre>sudo nano /opt/fhem/fhem.cfg</pre>
<pre>
...
attr global userattr DbLogExclude ... # erlaubt es einzelne Einträge nicht zu loggen
...
define logdb DbLog ./db.conf .*:.* # logt alle(!) auflaufenden Events aller Konfigurationen
...
</pre>
Da durch diese <code>define</code>-Definition alle auflaufenden Events gelogt werden, müssen keine weiteren Anpassungen in der Konfiguration gemacht werden. Die FileLog-Einträge können bedenkenlos bestehen bleiben - dann wird in Datenbank und FileLog gelogt und man verliert keine Daten, falls etwas nicht klappt. Wenn alles wie geplant läuft, können die FileLog-Definitionen gelöscht werden (ebenso die Log-Dateien). Ebenso können die zu loggenden Daten später eingegrenzt werden (s. [[#Finetuning des Loggings]]).
</li>
<li>''FHEM neu starten:''
<pre>
sudo service fhem stop
sudo service fhem start
</pre>
</li>
<li>''Kontrollieren, ob Logs in die Datenbank geschrieben werden:''
<pre>sudo sqlite3 /opt/fhem/fhem.db</pre>
In der geöffneten SQL-Kommandozeile eingeben:
<pre>
select * from history order by TIMESTAMP; # dies gibt alle(!) Logs chronologisch aus (kann nach längerem Betrieb recht lange dauern)
</pre>
Die Kommandozeile verlässt man mit <code>.exit</code>.
</li>
<li>''Anpassung der glot-Dateien:'' siehe [[#Anpassen der gplot-Konfigurationen]]
</li>
</ol>

== Beispiel: Anlegen und Nutzung einer Mysql-Datenbank ==
Hierfür gibt es eine [[DbLog-MySQL|extra Seite]], die die Unterschiede und Feinheiten zwischen den verschiedenen Versionen berücksichtigt

Anstatt nano kann jeder andere kompatible Editor verwendet werden. Weiterhin bitte beachten, dass die hier genannten Befehle teilweise root-Rechte voraussetzen. Entweder komplett als root arbeiten, oder mittels sudo.

Unter Ubuntu/debian:
apt-get update && apt-get install mysql-server mysql-client libdbd-mysql libdbd-mysql-perl

Bei der Installation sollte man aus Sicherheitsgründen ein Passwort für den mysql-root vergeben, wenn man nicht sogar ganz den Login verbietet.

Hinweis: im Folgenden ist "#" der normale Prompt und "mysql>" der prompt innerhalb mysql, dieser kann mit exit verlassen werden.

Zum Test mal mit mysql verbinden:
# mysql -p -u root
Enter password:
mysql> exit

Jetzt die Tabellenstruktur anlegen.
Hierfür kann die Datei /opt/fhem/contrib/dblog/db_create_mysql.sql als Vorlage verwendet und das Passwort und der Benutzername geändert werden.
cd /opt/fhem/contrib/dblog/
nano db_create_mysql.sql
Dann wird die Datei eingelesen (root Passwort wird abgefragt):

# mysql -u root -p < db_create_mysql.sql

Jetzt kann man den Zugang testen:

# mysql -p -u <fhemuser>
Enter password: <fhempassword>
mysql> show databases;

Nun müsste eine Datenbank "fhem" angezeigt werden, die die Tabellen current und history enthält.

Nun in der Datei db.conf den mysql-Block auskommentieren und ebenfalls Benutzername, Passwort UND HOST anpassen. Leider ist hier nicht standardmäßig localhost eingestellt.
nano /opt/fhem/db.conf

Jetzt kann unter FHEM ein DbLog-Device angelegt werden (mit dem beispiel wird alles geloggt:
define logdb DbLog ./db.conf .*:.*
Als State muss ein "connected" angezeigt werden.

Ein rereadcfg in FHEM stellt sicher, dass die neue Konfiguration übernommen wird - ein Neustart ist nicht erforderlich.

Nun kann die Funktion noch einmal überprüft werden:
<syntaxhighlight lang="sql">
# mysql -u <fhemuser> -p
Enter password: <fhempassword>
mysql> use fhem;
Database changed
mysql> show tables;
+----------------+
| Tables_in_fhem |
+----------------+
| current |
| history |
+----------------+
2 rows in set (0,00 sec)
mysql> select * from history; # Achtung, kann sehr groß werden .... #
</syntaxhighlight>

Anscheinend gibt es bei der neuen Version MariaDB (im Gegensatz zu mysql) ein neues Anmeldeverfahren, so dass in der Datenbank selbst Veränderungen vorgenommen werden müssen, damit der Zugriff durch FHEM funktioniert: https://kofler.info/root-login-problem-mit-mariadb/

Die Daten im MySQL können auch für die längere Aufbewahrung partitioniert werden. Dabei wird pro Partition eine Datei erzeugt statt einer gemeinsamen Datei für alle Daten. Je nach Wunsch zum Beispiel partitioniert nach Jahr.
<syntaxhighlight lang="sql">
Alter table history PARTITION BY RANGE ( UNIX_TIMESTAMP(timestamp) ) (
PARTITION p0 VALUES LESS THAN ( UNIX_TIMESTAMP('2019-01-01 00:00:00') ),
PARTITION p1 VALUES LESS THAN ( UNIX_TIMESTAMP('2020-01-01 00:00:00') ),
PARTITION p2 VALUES LESS THAN ( UNIX_TIMESTAMP('2021-01-01 00:00:00') ),
PARTITION p3 VALUES LESS THAN ( UNIX_TIMESTAMP('2022-01-01 00:00:00') ),
PARTITION p4 VALUES LESS THAN ( UNIX_TIMESTAMP('2023-01-01 00:00:00') ),
PARTITION p5 VALUES LESS THAN ( UNIX_TIMESTAMP('2024-01-01 00:00:00') ),
PARTITION p6 VALUES LESS THAN ( UNIX_TIMESTAMP('2025-01-01 00:00:00') ),
PARTITION p7 VALUES LESS THAN (MAXVALUE) );
</syntaxhighlight>

== Beispiel: Abfragescript PHP/MySQL ==
Um eine schnelle Übersicht zu bekommen habe ich mir dieses Script geschrieben:
<syntaxhighlight lang="php">
<?php $pdo = new PDO('mysql:host=localhost;dbname=fhem', 'fhemuser', 'fhempasswort');
echo '<h2>Tabelle Current</h1> <table border="1">';
echo "<tr><th>Anzahl</th><th>Name</th><th>Readings</th></tr>";
$sql = "SELECT COUNT(*), DEVICE, GROUP_CONCAT(DISTINCT READING ORDER BY READING DESC SEPARATOR '</li><li>') FROM current GROUP BY DEVICE;"; foreach ($pdo->query($sql) as
$row) {
echo "<tr><td>" . $row[0] . "</td><td>" . $row[1] . "</td><td><ol><li>" . $row[2] . "</li></ol></td></tr>";
}
echo "</table>";

echo '<h2>Tabelle History</h1> <table border="1">';
echo "<tr><th>Anzahl</th><th>Name</th></tr>";
$sql = "SELECT COUNT(*), DEVICE FROM history GROUP BY DEVICE;"; foreach ($pdo->query($sql) as
$row) {
echo "<tr><td>" . $row[0] . "</td><td>" . $row[1] . "</td></tr>";
}
echo "</table>";
?>
</syntaxhighlight>

Bitte passt ''fhemuser'' und ''fhempasswort'' an. Das Ganze kommt dann nach <code>/var/www/html/fhemdb.php</code> und ist mit <code><nowiki><IP>/fhemdb.php</nowiki></code> aufrufbar. Wenn ihr den zweiten Block für die history Tabelle ausklammert oder entfernt, läuft das Script viel schneller ab - klar die history Tabelle ist meist randvoll.

== Integration von DBLog in eigene Module ==
=== Bereitstellung der UNITS ===
Mit der DbLog_splitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten.

Dazu muss der Modulautor in der [[DevelopmentModuleIntro#X_Initialize|Initialize-Funktion]] eine <code>DbLog_splitFn</code> bereitstellen:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{DbLog_splitFn} = "X_DbLog_splitFn";
}
</syntaxhighlight>

Die genaue Aufrufsyntax und Funktionweise einer DbLog_split-Funktion findet man [[DevelopmentModuleIntro#X_DbLog_split|hier]].

== Werte auslesen ==
Manchmal möchte man Daten aus den Logs abrufen ohne händisch in der Datenbank herumzuwühlen (s.u.). Dies ist insbesondere auch dann hilfreich, wenn man eigene Funktionen, Notifys oder spezielle Plots entwirft, bei denen man auf Logdaten zugreifen möchte.

Grundsätzlich beschrieben ist dies in der {{Link2CmdRef|Lang=de|Anker=DbLog}} und unterscheidet sich minimal (aber entscheidend) von der Struktur bei [[FileLog#Werte_auslesen|FileLogs]].

Hier ein paar Beispiele, was man damit anstellen kann:

* <code>get meineDB - - 2016-10-01 2016-10-03 meinSensor</code> alle Einträge des meinSensor vom 01.10.-03.10.2016
* <code>get meineDB - - 2016-10-01_08:00:00 2016-10-01_16:00:00 meinSensor</code> alle Einträge des meinSensor von 8-16 Uhr am 01.10.2016
* <code>get meineDB - - 2016-10-01_08:00:00 2016-10-01_16:00:00 meinSensor:temperature</code> nur die temperature Werte
* <code>{ ReadingsTimestamp("meinSensor","state","0") }</code> Timestamp des aktuellen state des meinSensor
* <code>{ OldTimestamp("meinSensor") }</code> Timestamp des letzten state des FHT_3a32
* <code>{ time_str2num(OldTimestamp("meinSensor")) }</code> Timestamp in Sekunden des letzten state des meinSensor
* ...

== Bearbeitung von Datenbank-Einträgen ==
{{Hinweis|Dieser Abschnitt soll lediglich eine kleine Einführung in die Datenbank-Bearbeitung liefern. Für vertiefende Informationen sollte man sich grundsätzlich mit SQL beschäftigen. Eine umfassende und gut verständliche Anleitung zu SQL bietet bspw. [http://www.w3schools.com/sql/default.asp w3schools].}}
Irgendwann wird der Fall eintreten, dass in der Datenbank Einträge drinstehen, die geändert oder gelöscht werden sollen (zB. fehlerhafte Sensor-Rückmeldungen, umbenannte Readings). In klassischen Log-Dateien würde man diese einfach bearbeiten und löschen/anpassen (wobei man aber tunlichst zuvor FHEM stoppt, um Datenfehler zu vermeiden). Eine Datenbank kann bearbeitet werden, ohne FHEM stoppen zu müssen.

Datenbanken kann man ohne weitere Hilfsmittel direkt von der Kommandozeile/Shell aus bearbeiten. Alternativ gibt es auch verschiedenste Tools (webbasiert oder als Applikation), die einen dabei unterstützen (Bsp. findet man u.a. [https://wiki.ubuntuusers.de/SQLite/#Grafische-Benutzeroberflaechen hier]). Für einfache Arbeiten reicht allerdings idR. Shell.

=== SQLite-Datenbanken ===
'''Öffnen der DB unter Linux:'''

(Es werden Schreibrechte benötigt,ohne kann man die DB zwar öffnen, aber nichts machen)
sudo sqlite3 fhem.db
Dadurch öffnet sich ein SQL-Konsole, auf der alle weiteren Befehle ausgeführt werden.

'''Schliessen der DB:'''

sqlite> .exit

'''Hilfe anzeigen:'''

sqlite> .help

'''Alle Tabellen anzeigen:'''

sqlite> .tables

'''Das Schema der DB anzeigen:'''

(vgl. oben [[DbLog#Datenbanken]] und [[DbLog#Beispiel: Anlegen und Nutzung einer SQLite-Datenbank]])

sqlite> .schema

'''Alle Eintäge anzeigen:'''

Die Einträge liegen alle in der Tabelle "History".

'''Ganz wichtig''' ist immer das ";" am Ende Zeile (bei allen Kommandos, die nicht mit einem "." anfangen). Wenn es vergessen wurde zeigt die Konsole solange neue Zeilen bis ein ";" eingegeben wird. So kann ein Befehl auch bequem über mehrere Zeilen geschrieben werden.

sqlite> select * from HISTORY;

Dies kann sehr lange dauern und kann ggf. mit <code>STRG-C</code> abgebrochen werden.

'''Alle Einträge eines Geräts anzeigen:'''

In <code>where</code>-Statements werden Strings in einfache Anführungsstriche gesetzt, Zahlen nicht.

sqlite> select * from HISTORY where DEVICE='Pollenflug';

'''Alle Einträge eines Readings eines Geräts anzeigen:'''

sqlite> select * from HISTORY where DEVICE='Pollenflug' and READING='Graeser';

'''Alle Einträge eines bestimmten Wertes eines Readings eines Geräts anzeigen:'''

sqlite> select * from HISTORY where DEVICE='Pollenflug' and READING='Graeser' and VALUE>1;

'''LÖSCHEN aller Einträge eines bestimmten Wertes eines Readings eines Geräts anzeigen:'''

'''Achtung:''' Löschen kann nicht rückgängig gemacht werden!! Also IMMER erst die entsprechenden SELECT-Statements solange verfeinern bis wirklich nur die gewünschten Einträge angezeigt werden. Dann das <code>select *</code> durch <code>delete</code> ersetzen.

sqlite> delete from HISTORY where DEVICE='Pollenflug' and READING='Graeser' and VALUE>1;

== Datenbank reparieren ==
Es kann immer wieder mal vorkommen, dass Datenbanken Fehler enthalten. Das muss im Alltag garnicht auffallen und auch nicht immer schlimm enden. Wenn man auf der SQL-Konsole aber bspw. eine Meldung <code>Error: database disk image is malformed</code> erhält, sollte man ein Reparatur vornehmen.

'''Hinweis:''' Ist ein DbRep-Device definiert, kann eine Reparatur einfach mit dem eingebauten Befehl '''set <name> repairSQlite''' ausgeführt werden.

=== SQLite-Datenbanken ===
Die folgenden Schritte beschreiben, wie man eine SQLite-DB reparieren kann (Quelle: [http://techblog.dorogin.com/2011/05/sqliteexception-database-disk-image-is.html]):

<ol>
<li>DB öffnen:
<pre>sudo sqlite3 fhem.db</pre>
</li>
<li>Integritäts-Check durchführen:
<pre>sqlite> pragma integrity_check;</pre>
Kommt hier ein "ok" ist die DB gesund. Ansonsten erscheint etwas wie
<pre>
*** in database main ***
On tree page 118786 cell 1: Rowid 75 out of order (previous was 816660)
On tree page 118786 cell 4: Rowid 815704 out of order (previous was 816727)
Corruption detected in cell 0 on page 118786
Multiple uses for byte 132 of page 118786
...
</pre>
</li>
<li>Datenbank-Dump erstellen (Export gesamten DB in die Datei "dump_all_20160516_1043.sql") und DB verlassen:
<pre>
sqlite> .mode insert
sqlite> .output dump_all_20160516_1043.sql
sqlite> .dump
sqlite> .exit
</pre>
</li>
<li>Neue Datenbank erstellen und den Dump einlesen, Integritäts-Check machen und verlassen:
<pre>sudo sqlite3 fhem-neu.db</pre>
<pre>
sqlite> .read dump_all_20160516_1043.sql
sqlite> pragma integrity_check;
ok
sqlite> .exit
</pre>
</li>
<li>Spätestens jetzt FHEM stoppen:
<pre>sudo service fhem stop</pre>
</li>
<li>Alte DB sichern und neue aktivieren:
<pre>
sudo mv fhem.db fhem.db.sv_20160516
sudo mv fhem-neu.db fhem.db
</pre>
</li>
<li>Kontrollieren, dass die neue DB die gleichen Rechte wie die alte DB hat (und ggf. korrigieren):
<pre>
~/fhem$ ls -lha
insgesamt 6,3G
drwxr-xr-x 12 fhem root 4,0K Mai 16 11:07 .
drwxr-xr-x 4 root root 4,0K Dez 25 17:50 ..
...
-rw-r--r-- 1 root root 1,4G Mai 16 11:04 fhem.db
-rw-r--r-- 1 fhem root 2,6G Mai 16 10:59 fhem.db.sv_20160516
...

~/fhem$ sudo chown fhem:root fhem.db

~/fhem$ ls -lha
insgesamt 6,3G
drwxr-xr-x 12 fhem root 4,0K Mai 16 11:07 .
drwxr-xr-x 4 root root 4,0K Dez 25 17:50 ..
...
-rw-r--r-- 1 fhem root 1,4G Mai 16 11:04 fhem.db
-rw-r--r-- 1 fhem root 2,6G Mai 16 10:59 fhem.db.sv_20160516
...
</pre>
</li>
<li>FHEM wieder starten (und natürlich kontrollieren):
<pre>sudo service fhem start</pre>
</li>
</ol>

=== Hinweise für sehr große Datenbanken ===
Wenn die SQLite-DB sehr groß wird, kann es sein, dass der oben beschriebene Weg nicht ohne manuelle Anpassungen funktioniert. Konkret war dies bei einem Nutzer für eine 15 GB große DB nicht möglich, der Prozess hat sich immer nach mehreren Stunden aufgehängt. Die Ursache liegt darin, dass ein Dump alle Daten in einer einzigen Transaktion einfügt. Das Problem kann man lösen, indem man den Dump in mehreren Transaktionen einfügt, also aufteilt. Konkret konnte eine 23GB große DB erfolgreich eingelesen und damit repariert werden, indem alle 10.000.000 Zeilen folgende 2 Zeilen eingefügt wurden:
<pre>BEGIN TRANSACTION;
COMMIT;
</pre>
* Hinweis 1: Mit dem Editor joe kann man unter Linux auch sehr große Dateien flüssig bearbeiten, das Springen zu hohen Zeilennumer dauert trotzdem.
* Hinweis 2: joe verwendet eine temporäre Kopie der Datei. Diese liegt per default unter /tmp. Der Ort kann aber auch durch <code>export TEMP=...</code> geändert werden. Falls also unter /tmp nicht Platz für eine Kopie des Datenbank-Dumps ist, sollte diese Variable vor dem Starten von joe entsprechend gesetzt werden.
* Hinweis 3: Beim Speichern legt joe im gleichen Verzeichnis eine Sicherungskopie an, d.h. im Verzeichnis des Datenbank-Dumps sollte weiterer Platz in Höhe der Dateigröße frei sein.
* Hinweis 4: Der reopen Mechanismus von DbLog kann verwendet werden, um eine manuelle Datenbankreparatur ohne Logunterbrechung durchzuführen (vor dem Wieder-Öffnen der DbLog Datei- und Verzeichnisrechte prüfen!). Damit kann man das harte Stoppen und Starten von FHEM in obiger Anleitung umgehen.
* Letzter Hinweis: Weiter gilt: bei großen DbLog-Datenbanken sollte man immer darüber nachdenken,
** Welche dieser Logdaten man wirklich braucht und im Zweifel per DbRep ausdünnen
** Zu einer echten Datenbank wie MySQL/MariaDB zu wechseln.

== Datenbank migrieren ==
Eine schöne Anleitung zur Migration von SQLite zu MySQL/MariaDB mit Hilfe von [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] findet sich hier: [https://demaya.de/fhem-umzug-sqlite-mysql-mariadb/].

== Nützliche Codeschnipsel ==
Anbei ein paar nützliche Codeschnipsel rund um DbLog

=== Dateigrösse mitloggen ===
Da die Datenbank ins Unermessliche wachsen kann, empfiehlt es sich - je nach Speicherplatz - ab einer bestimmten Grösse tätig zu werden. Dazu muss diese Grösse allerdings ermittelt werden. Diese geschieht mittels des Userreadings, welches man vorteilshafterweise mit im DbLog-device anlegt:

<pre>attr myDbLog userReadings DbFileSize:reduceLogState.* { (split(' ',`du -m fhem.db`))[0] }</pre>

Mittels dieses Attributs wird die Grösse der .db-Datei immer nach dem Ausführen des ReduceLog in das Reading "DbFileSize" in ganzzahligen MByte abgelegt.

Basierend auf diesem Reading können dann weitere Aktionen, beispielsweise ein Plot, erstellt werden.

Die oben beschriebene Möglichkeit ist für SQLite verwendbar. Zur Ermittlung der DB-Größe andere DB-Typen (aber auch für SQLite nutzbar) kann wie [[DbRep_-_Reporting_und_Management_von_DbLog-Datenbankinhalten#Gr.C3.B6.C3.9Fe_der_FHEM-Datenbank_ermitteln | hier]] beschrieben vorgegangen werden.

== Performance-Optimierung ==
Auch eine Datenbank kann mit der Zeit langsamer werden. Dies hängt von mehreren Faktoren ab:
* Menge der gelogten Daten (zB. > 4-5 GB)
* Eingesetzte Hardware (zB. langsame SD-Karte vs. schnelle SSD)
* Eingesetztes Datenbanksystem (zB. SQLite, MySQL)
* Komplexität der Abfragen (zB. für aufwändige Graphen oder Berechnungen)

Diese Punkte sollen im folgenden diskutiert werden:

=== Komplexität der Abfragen ===
Dies ist kein Problem der Datenbank, sondern rein der Abfrage. Dem entsprechend muss die Optimierung auch in der Abfrage oder im Skript gesucht werden. Dies ist nicht Ziel dieses Abschnittes und wird hier nicht weiter behandelt.

=== Eingesetztes Datenbanksystem ===
Welches Datenbanksystem eingesetzt wird (zB. SQLite oder MySQL) hat auf die Performance der Datenbank gar keinen so großen Einfluss, wie vielleicht zuerst gedacht. Selbst SQLite kann problemlos Datenbanken mit etlichen GB Größe performant verarbeiten. Der Flaschenhals ist hier viel mehr die darunter liegende Hardware (s.u.).

Die Performance der Datenbank an sich, kann aber durch verschiedene Maßnahmen verbessert werden:
* Pflegemaßnahmen bzgl. der Daten
* '''Erstellung von Indizes'''

==== Menge der Daten und Pflegemaßnahmen bzgl. der Daten ====
Die Menge der geloggten Daten hat natürlich Einfluss auf die Geschwindigkeit von Abfragen - je mehr Daten vorhanden sind, desto mehr Daten müssen auch durchforstet werden um eine Abfrage zu bedienen. Die Reduzierung der geloggten Datenmenge hat also direkten Einfluss auf die Größe und damit auch die Geschwindigkeit der Datenbank. Die Menge der zu loggenden Daten lässt sich an zwei Stellen einschränken:
* bei der Definition jedes Devices (s. Kapitel oben)
* bei der Festlegung des FHEM-weiten Log-Levels (s. [[Loglevel]])

Die Menge der bereits geloggten Daten kann zB. mit Hilfe von [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] verringert und optimiert werden, bspw.
* löschen unnötiger Daten
* vacuum der Datenbank

Insgesamt haben diese Maßnahmen aber nur einen eingeschränkten Effekt auf die Performance der DB. Deutlich effektiver ist die Erstellung eines Index (s.u.).

==== Erstellung von Indizes ====
Die Erstellung von Indizes hat mit Abstand den größten Einfluss auf die Performance einer Datenbank (auf unveränderter Hardware). Extrem zusammengefasst ist ein Index eine extrem optimiertes Nachschlageverzeichnis für einen bestimmten Typ Daten (ein Index wie im Buch halt). Eine wunderbare Einführung in Indizes bietet [[https://use-the-index-luke.com/de|https://use-the-index-luke.com]].

In FHEM sind Indizes sogar sehr einfach einzurichten da die Datenbank-Nutzung sehr stark vorgegeben ist. Nahezu jede Abfrage folgt dem Schema ''Device -> Reading -> Datum -> Wert''. Ein Index kann genau diese Abfrage bedienen und beschleunigen. Ein Index nur über die Devices wäre ein erster Schritt, brächte aber noch keinen großen Gewinn (wie um Link oben gut beschrieben). Über die gesamten ersten drei Schritte erstellt (Device -> Reading -> Datum) bringt der Index aber sofort eine deutliche Geschwindigkeitssteigerung.

Die Erstellung eines Index erfolgt direkt in der Datenbank (und nicht aus FHEM heraus), hier am Beispiel einer SQLite-DB:

Öffnen der DB:
<pre> sudo sqlite3 fhem.db </pre>

Erzeugen des Index auf der DB-Konsole (das Semikolon am Ende ist wichtig):
<pre> create index idx_device_reading_timestamp on history (device, reading, timestamp); </pre>

Verlassen der DB:
<pre> .exit </pre>

Einzig zu berücksichtigen ist, dass dieser Index die Datenbank um bis zu 1/3 vergrößert. Er kann aber bei Bedarf auch wieder entfernt werden. Bei meiner 15 GB SQLite-Datei (auf einem Mac Mini mit SSD) hat dies ca. 15 min gedauert (den FHEM hatte ich vorsichtshalber währenddessen deaktiviert).

Sollte jemand spezielle Berechnungen oder Skripte ausführen, die nach einem anderen Abfrage-Schema arbeiten, könnte man dafür spezialisierte zusätzliche Indizes erstellen. Das sollte aber dann mit dem Wissen des obigen Links erarbeitet werden, da dann etwas mehr Hintergrundwissen sehr hilfreich ist.

==== DB-Backup ====
Ein anderer Aspekt, der eigentlich nichts mit der Performance der DB zu tun hat, ist der Einfluss aufs Backup. Wird bspw. ein Systembackup per RSYNC gemacht, muss bei SQLite immer die komplette ggf. riesige Datei gesynct werden - bei MySQL würden nur die veränderten DB-Elemente gesynct. Dies soll hier nicht weiter vertieft werden, sollte aber bei einer Gesamtstrategie bedacht werden.

=== Eingesetzte Hardware ===
FHEM hat grundsätzlich sehr viele kleine Datenzugriffe, unabhängig davon ob FileLog oder DbLog eingesetzt wird. Deshalb ist der absolut größte Performance-Gewinn durch den Einsatz schneller Festplatten zu erreichen - ganz einfache Aussage: ''je schneller desto besser ;-)''. Konkret bietet eine SSD mit mind. 250MB/s Datenzugriff eine ordentliche Basis für jedes datengestützte System, wie den FHEM.

Wenn die Datenmenge größer und die Abfragen komplexer werden, müssen natürlich irgendwann auch die Prozessorleistung und der Arbeitsspeicher mit wachsen. Aber auch an einem Raspi wird eine SSD deutlich performanter sein, als eine einfache SD-Karte oder eine klassische rotierende Festplatte.

== Links ==
* [[Heizleistung_und_Gasverbrauch|Beispiel das DbLog-Daten für SVG-Plots verwendet]]
* [[SVG-Plots von FileLog auf DbLog umstellen]]
* Manchmal bereitet die Engine von mysql auf einem Raspberry Probleme: [https://forum.fhem.de/index.php/topic,131164.msg1253589.html#msg1253589|Link zum Forum]

[[Kategorie:Logging]]

FRITZBOX

2022-04-03T16:59:38Z

AlanBlack:

{{Infobox Modul
|ModPurpose=Steuerung einer Fritz!Box über FHEM
|ModType=d
|ModForumArea=FRITZ!Box
|ModTechName=72_FRITZBOX.pm
|ModOwner=tupol/Topos ({{Link2FU|5432|Forum}} / [[Benutzer Diskussion:Topos|Wiki]])}}

Das Modul [[FRITZBOX]] ermöglicht die Steuerung einer [[AVM Fritz!Box]] und von AVM FRITZ!WLAN Repeatern durch FHEM . An Fritzboxen können sowohl Geräte abgefragt werden, auf denen FHEM selbst läuft (lokaler Modus), als auch entfernte (externe) Geräte.

{{Randnotiz|RNTyp=r|RNText= Ab FRITZ!OS 6.25 wird das zwingend benötigte Telnet nicht mehr unterstützt.}}
== Voraussetzungen ==
=== Remote-Zugang ===
Für den Remote-Zugang müssen die Module JSON:XS, LWP und SOAP::Lite installiert sein; auf einem [[Raspberry Pi]] oder unter Ubuntu z. B. mit dem Befehl
:<code>sudo apt-get install libjson-perl libwww-perl libsoap-lite-perl libjson-xs-perl</code>

Teilweise ist derzeit zusätzlich die Installation der telnet Libraries erforderlich, auch wenn der Telnet-Zugang nicht genutzt werden soll. Siehe dazu den nachfolgenden Abschnitt.

=== Telnet ===
Das Modul basierte ursprünglich auf dem Zugriff auf die Fritzbox per Telnet. Ab FRITZ!OS 6.2x baut AVM den abgekündigten Telnet-Zugang sowie die webcm-Schnittstelle sukzessive zurück bzw. hat dies, je nach Firmware, schon ganz abgestellt (siehe {{Link2Forum|Topic=38586|LinkText=dieses Forenthema}}). Der zukunftssichere Zugriff auf die Fritzbox sollte also per TR-064 erfolgen. Der Vollständigkeit halber und für ältere Firmwareversionen:

# Wer den Zugang per Telnet (noch) nutzen (kann und) möchte, muss dies zuerst freischalten. Üblicherweise durch Eingabe von #96*7* an einem direkt an der entsprechenden FritzBox angeschlosssenen Telefon
# Auf dem System, auf dem FHEM läuft ([[Systemübersicht#Server|Server]]) muss Telnet installiert sein; auf einem [[Raspberry Pi]] und unter Ubuntu z. B. mit dem Befehl
::<code>sudo apt-get install libnet-telnet-perl</code>

== Installation ==
=== Erste Schritte ===
Zur Erstinstallation reicht ein einfaches <code>define FritzBox FRITZBOX</code>, dieses Modul funktioniert lokal (FHEM auf Fritzbox) sowie per Fernzugriff (FHEM auf einem anderen Server im Netz, siehe nächsten Schritt).

==== TR-064: Modul FRITZBOX für Zugriff auf einem externen Server einrichten ====
Für den Fernzugriff über TR-064 auf eine oder mehrere Fritzboxen und/oder einen FRITZ!WLAN Repeater sind die folgenden Schritte nötig (für jedes Gerät):

Fritzbox definieren:
:<code>define FritzBox FRITZBOX</code>

Wenn die Fritzbox nicht unter <nowiki>http://fritz.box</nowiki> erreichbar ist, IP im define setzen:
:<code>define FritzBox FRITZBOX 192.168.168.168</code>
192.168.168.168 dabei natürlich durch die passende IP ersetzen... Alternativ kann statt der IP auch der Hostname eingegeben werden.

Wenn ('''und nur wenn''') das Login auf der Benutzeroberfläche der FritzBox mit User und Passwort (und nicht nur per Passwort) geschieht, den User konfigurieren:
:<code>attr FritzBox boxUser ''Benutzername'' </code>
In der Fritzbox muss dann auch "Anmeldung mit FRITZ!Box-Benutzernamen und Kennwort" ausgewählt sein.

Passwort konfigurieren:
:<code>set FritzBox password ''Passwort''</code> - legt das zugehörige Passwort fest (nur einmal --> gehört nicht in die cfg-Datei)

Manuelle TR-064 Kommandos erlauben (Das Auslesen der Readings per TR-064 funktioniert auch ohne dieses Attribut.):
:<code>attr FritzBox allowTR064Command 1</code>

==== Telnet: Modul FRITZBOX für Zugriff auf einem externen Server einrichten ====
[[Datei:Screenshot_FritzBox_TelnetUser.png|mini|300px|rechts|Anlegen des Attributs telnetUser]]
Bei Fernzugriff über Telnet sind weitere Schritte nötig:
# Telnet auf der Fritzbox freischalten (Tastenkombination #96*7* am angeschlossenen Telefon (auch FritzFon)
# TelnetUser definieren (wie im Screenshot gezeigt)
# Passwort zum Benutzer auf der Fritzbox definieren

[[Datei:Screenshot_FritzBox_Passwort.png|mini|300px|rechts|Passwort definieren]]

(bitte die Buttons {{Taste|set}} und {{Taste|attr}} bei der Definition der jeweiligen Einträge nicht vergessen)

Wer stattdessen lieber das [[Konfiguration|Befehl-Eingabefeld]] verwendet:

:<code>define FritzBox FRITZBOX</code>
:<code>attr FritzBox telnetUser ''Benutzername'' </code> - legt den Benutzer fest
:<code>set FritzBox password ''Passwort'' </code> - legt das zugehörige Passwort fest

Wer keinen User konfiguriert hat, kann das Feld "telnetUser" leer lassen.

Wer sicher gehen möchte, dass auch tatsächlich Telnet und nicht andere Zugriffe benutzt werden, sollte außerdem noch setzen:

:<code>attr FritzBox forceTelnetConnection 1</code>

=== mögliche Fehlermeldungen ===
Sollte schon bei <code>define FritzBox FRITZBOX</code> die Fehlermeldung kommen, dass dieses Modul nicht existiert, dann bitte prüfen, ob FHEM auf dem aktuellen Stand ist und ggf. [[Update|aktualisieren]].

Kommt jetzt bei der erneuten Definition die Fehlermeldung <code>Error: Perl modul Net::Telnet is missing on this system</code> bitte wie oben schon erwähnt den Befehl
:<code>sudo apt-get install libnet-telnet-perl</code>
direkt per Telnet/SSH auf dem FHEM-Server ausführen und neu starten.
Sollte alles geklappt haben, seht ihr nun eure Fritzbox und könnt diverse Einstellungen manuell vornehmen und/oder automatisch vornehmen lassen.

== Anwendung ==
=== Define ===
Siehe {{Link2CmdRef|Lang=de|Anker=FRITZBOXdefine}}

=== Attribute ===
Siehe {{Link2CmdRef|Lang=de|Anker=FRITZBOXattr}}

=== TR-064 ===
Die offizielle Programmier-Schnittstelle der Fritz!Box läuft über das Protokoll TR-064.

Mit dem Attribut
:<code>attr <device> allowTR064Command 1</code>
kann man den Befehl
:<code>get <device> tr064Command <service> <control> <action> [[parameterName1 parameterValue1] ...]</code>
freischalten und damit auf diese Schnittstelle zugreifen.

AVM hat die Schnittstellenbeschreibung unter [http://avm.de/service/schnittstellen/] veröffentlicht. Diese wird jedoch nur sehr sporadisch gepflegt.

Ein besserer Einstiegspunkt befindet sich auf der Box unter http://fritz.box:49000/tr64desc.xml.
Die möglichen TR-064-Aktionen kann man auch über den Befehl
:<code>get <device> tr064ServiceList</code>
auslesen.

Folgende Services und Controls existieren (für den get-Befehl ''tr064Command'' werden nur die fett formatierten Wörter benötigt)

{| class="wikitable"
|-
!serviceType!!controlURL!!XML!!Dokument bei AVM
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceInfo:1'''||/upnp/control/'''deviceinfo'''||[http://fritz.box:49000/deviceinfoSCPD.xml deviceinfoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceinfoSCPD.pdf deviceinfoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceConfig:1'''||/upnp/control/'''deviceconfig'''||[http://fritz.box:49000/deviceconfigSCPD.xml deviceconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceconfigSCPD.pdf deviceconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Layer3Forwarding:1'''||/upnp/control/'''layer3forwarding'''||[http://fritz.box:49000//layer3forwardingSCPD.xml layer3forwardingSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/layer3forwardingSCPD.pdf layer3forwardingSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANConfigSecurity:1'''||/upnp/control/'''lanconfigsecurity'''||[http://fritz.box:49000//lanconfigsecuritySCPD.xml lanconfigsecuritySCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanconfigsecuritySCPD.pdf lanconfigsecuritySCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''ManagementServer:1'''||/upnp/control/'''mgmsrv'''||[http://fritz.box:49000//mgmsrvSCPD.xml mgmsrvSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/mgmsrvSCPD.pdf mgmsrvSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Time:1'''||/upnp/control/'''time'''||[http://fritz.box:49000//timeSCPD.xml timeSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/timeSCPD.pdf timeSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''UserInterface:1'''||/upnp/control/'''userif'''||[http://fritz.box:49000//userifSCPD.xml userifSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/userifSCPD.pdf userifSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_VoIP:1'''||/upnp/control/'''x_voip'''||[http://fritz.box:49000//x_voipSCPD.xml x_voipSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_voipSCPD.pdf x_voipSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Storage:1'''||/upnp/control/'''x_storage'''||[http://fritz.box:49000//x_storageSCPD.xml x_storageSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_storageSCPD.pdf x_storageSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_OnTel:1'''||/upnp/control/'''x_contact'''||[http://fritz.box:49000//x_contactSCPD.xml x_contactSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_contactSCPD.pdf x_contactSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_WebDAVClient:1'''||/upnp/control/'''x_webdav'''||[http://fritz.box:49000//x_webdavSCPD.xml x_webdavSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_webdavSCPD.pdf x_webdavSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_UPnP:1'''||/upnp/control/'''x_upnp'''||[http://fritz.box:49000//x_upnpSCPD.xml x_upnpSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_upnp.pdf x_upnp.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_RemoteAccess:1'''||/upnp/control/'''x_remote'''||[http://fritz.box:49000/x_remoteSCPD.xml x_remoteSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_remoteSCPD.pdf x_remoteSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_MyFritz:1'''||/upnp/control/'''x_myfritz'''||[http://fritz.box:49000/x_myfritzSCPD.xml x_myfritzSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_myfritzSCPD.pdf x_myfritzSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_TAM:1'''||/upnp/control/'''x_tam'''||[http://fritz.box:49000/x_tamSCPD.xml x_tamSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_tam.pdf x_tam.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_AppSetup:1'''||/upnp/control/'''x_appsetup'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_appsetupSCPD.pdf x_appsetupSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Homeauto:1'''||/upnp/control/'''x_homeauto'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_homeautoSCPD.pdf x_homeautoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:1'''||/upnp/control/'''wlanconfig1'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:2'''||/upnp/control/'''wlanconfig2'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:3'''||/upnp/control/'''wlanconfig3'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Hosts:1'''||/upnp/control/'''hosts'''||[http://fritz.box:49000/hostsSCPD.xml hostsSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/hostsSCPD.pdf hostsSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANEthernetInterfaceConfig:1'''||/upnp/control/'''lanethernetifcfg'''||[http://fritz.box:49000/lanifconfigSCPD.xml lanifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanifconfigSCPD.pdf lanifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANHostConfigManagement:1'''||/upnp/control/'''lanhostconfigmgm'''||[http://fritz.box:49000/lanhostconfigmgmSCPD.xml lanhostconfigmgmSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanhostconfigmgmSCPD.pdf lanhostconfigmgmSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANCommonInterfaceConfig:1'''||/upnp/control/'''wancommonifconfig1'''||[http://fritz.box:49000/wancommonifconfigSCPD.xml wancommonifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wancommonifconfigSCPD.pdf wancommonifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLInterfaceConfig:1'''||/upnp/control/'''wandslifconfig1'''||[http://fritz.box:49000/wandslifconfigSCPD.xml wandslifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandslifconfigSCPD.pdf wandslifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLLinkConfig:1'''||/upnp/control/'''wandsllinkconfig1'''||[http://fritz.box:49000/wandsllinkconfigSCPD.xml wandsllinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandsllinkconfigSCPD.pdf wandsllinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANEthernetLinkConfig:1'''||/upnp/control/'''wanethlinkconfig1'''||[http://fritz.box:49000/wanethlinkconfigSCPD.xml wanethlinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanethlinkconfigSCPD.pdf wanethlinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANPPPConnection:1'''||/upnp/control/'''wanpppconn1'''||[http://fritz.box:49000/wanpppconnSCPD.xml wanpppconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanpppconnSCPD.pdf wanpppconnSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANIPConnection:1'''||/upnp/control/'''wanipconnection1'''||[http://fritz.box:49000/wanipconnSCPD.xml wanipconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanipconnSCPD.pdf wanipconnSCPD.pdf]
|-
|}

=== Status-Symbol ===
<code>attr <device> devStateIcon .*on.*off:WLAN_on_gWLAN_off .*on.*on.*:WLAN_on_gWLAN_on WLAN..off.*:WLAN_off</code>

Im Verzeichnis www/images/default müssen die passenden Dateien "WLAN_on_gWLAN_off.png", "WLAN_on_gWLAN_on.png" und "WLAN_off.png" liegen. Wenn die PNGs fehlen, können sie {{Link2Forum|Topic=29725|Message=318113|LinkText=hier}} heruntergeladen werden.

== Anwendungsbeispiele ==
[[Datei:Screenshot_FritzBox1.png|mini|300px|rechts|FRITZBOX Gerät auf der FHEM Oberfläche]]
Sollte alles geklappt haben, seht ihr nun unter "Unsortiert" den im nebenstehenden Screenshot gezeigten Eintrag für das "Gerät" (hier mit dem Icon "it_router").

=== TR-064 Beispiele ===
*Box Reboot: <code>get <device> tr064Command DeviceConfig:1 deviceconfig Reboot</code>
*Internet Reconnect: <code>get <device> tr064Command WANIPConnection:1 wanipconnection1 ForceTermination</code>
*Daten eines Smart-Home-Gerätes auslesen: <code>get <device> tr064Command X_AVM-DE_Homeauto:1 x_homeauto GetGenericDeviceInfos NewIndex 0</code>

=== Klingel- und Sprachausgabe per TR-064 ===
Das geht derzeit nicht, da entsprechende Kommandos per TR-064 nicht verfügbar sind. Da Telnet sukzessive abgestellt wird, sollten sich Interessenten per Feature-Request an AVM wenden, wie {{Link2Forum|Topic=38586|LinkText=hier}} beschrieben.

Eine Alternative um Telefone klingeln zu lassen, ist die Nutzung des [[SIP-Client]]s.

=== Anwesenheitserkennung per regelmäßiger Abfrage über das PRESENCE Modul ===
Fritzboxen und die FRITZ!WLAN Repeater speichern den Status angemeldeter Geräte. Dieser Status lässt sich mittels des FRITZBOX Moduls über Readings abfragen, die das Format mac_AA_AA_AA_AA_AA_AA haben und die MAC-Adressen der jeweils angemeldeten Geräte (AA:AA:AA:AA:AA:AA) enthalten. Das Reading existiert, wenn das Gerät angemeldet ist. Wenn das Gerät abgemeldet ist, existiert es nicht mehr. Es gibt auch noch den Zwischenstatus "inactive", der anscheinend gesetzt wird, bevor das Reading gelöscht wird.

Mit Hilfe des [[PRESENCE]] Moduls (vgl. [[Anwesenheitserkennung]]) kann man auf diese Weise den Anwesenheitsstatus abfragen. Anregungen dazu gibt es im zugehörigen {{Link2Forum|Topic=39433|LinkText=Forenthread}} zur Anwesenheitserkennung und in [http://heinz-otto.blogspot.de/2015/07/die-zeiten-andern-sich.html diesem Blogpost]. Auf dieser Basis könnte eine einfache Implementierung zum Beispiel so aussehen:

Funktion in [[99_myUtils anlegen|99_myUtils]]:
'''(Bitte beim Speichern darauf achten, dass nicht der Name 99_Utils gewählt wird.)'''

<syntaxhighlight lang="perl">sub checkFritzMACpresent($$) {
# Benötigt: Name der zu testenden Fritzbox ($d),
# zu suchende MAC ($m),
# Rückgabe: 1 = Gerät gefunden
# 0 = Gerät nicht gefunden
my ($d,$m) = @_;
$m =~ s/:/_/g;
$m = "mac_".uc($m);
return (ReadingsVal($d,$m,"inactive") ne "inactive") ? 1 : 0;
}</syntaxhighlight>

Nutzung dieser Funktion mit dem PRESENCE Modul definieren:
:<code>define <Name> PRESENCE function {checkFritzMACpresent("Fritzbox","AA:BB:CC:DD:EE:FF")} 60 60</code>
wobei
*<Name> ein beliebig zu wählender Name für die PRESENCE-Funktion ist,
*Fritzbox der Name ist, mit dem ihr die abzufragende Fritzbox als FRITZBOX definiert habt,
*AA:BB:CC:DD:EE:FF die MAC-Adresse des gesuchten Geräts ist.
* "60 60" sagt, dass der Anwesenheitsstatus im 60-Sekunden-Takt abgefragt wird. Das macht natürlich nur Sinn, wenn ihr mit <code>attr Fritzbox INTERVAL 60</code> den Abfrageinterval bei der Fritzbox auch entsprechend hochgesetzt habt. Der Standard ist 300.
* "Log 1" führt immer zum Loggen. Das ist zum Einrichten praktisch, ohne dass man gleich für das ganze Modul oder ganz FHEM <code>attr <device> verbose 5</code> setzen muss. Wenn es läuft, können die "Log 1"-Zeilen gelöscht, auskommentiert (# an den Zeilenanfang) oder in "Log 5" geändert werden.

=== Anwesenheitserkennung über mehrere Fritzboxen oder AVM Repeater und Fritzbox ===
Existiert ein AVM Repeater im Netzwerk, kann der als eigenständiges Gerät mit FRITZBOX definiert werden. WLAN Geräte an der Fritzbox werden in der Instanz der Fritzbox gelistet und WLAN Geräte am Repeater in der Repeater Instanz. Um trotzdem die Anwesenheit im Netzwerk einfach zu erkennen, muss die Subroutine in 99_myUtils.pm abgewandelt werden. (Siehe auch [https://forum.fhem.de/index.php/topic,39433.msg1075247.html#msg1075247 Forum Beitrag])

Existiert eine zweite Fritzbox im Accesspointmodus, werden die WLAN Geräte im Netzwerk alle in der Hauptfritzbox an einem LAN Anschluss gelistet. D.h. man sieht an der Hauptfritzbox nicht, dass sie im WLAN sind. Eine zweite Instanz mit dem FRITZBOX Modul muss wegen der Anwesenheitserkennung nicht gemacht werden. Die folgende Routine kann aber universell eingesetzt werden, unabhängig von der Anzahl der FRITZBOX Instanzen. Wer mitloggen will, kann das analog zur obigen Routine einbauen

<syntaxhighlight lang="perl">sub checkAllFritzMACpresent($) {
# Benötigt: nur die zu suchende MAC ($MAC),
# Es werden alle Instanzen vom Type FRITZBOX abgefragt
#
# Rückgabe: 1 = Gerät gefunden
# 0 = Gerät nicht gefunden
my ($MAC) = @_;
# Wird in keiner Instanz die MAC Adresse gefunden bleibt der Status 0
my $Status = 0;
$MAC =~ tr/:/_/;
$MAC = "mac_".uc($MAC);
my @FBS = devspec2array("TYPE=FRITZBOX");
foreach( @FBS ) {
my $StatusFritz = ReadingsVal($_, $MAC, "weg");
if ($StatusFritz eq "weg") {
# Dieser Zweig testet ob das Reading vorhanden ist
} elsif ($StatusFritz eq "inactive") {
# Dieser Zweig testet ob im Reading inactive steht
} elsif ($StatusFritz =~ /(.*)s, 0/) {
# Dieser Zweig testet auf "<geraetename> (WLAN, 0 / 0 Mbit/s, 0)"
} else { $Status = 1}
}
return $Status
}</syntaxhighlight>

Da hiermit nach allen Instanzen mit dem TYPE=FRITZBOX durchsucht wird, braucht der Name der Fritzbox nicht angegeben werden.

:<code>define <Name> PRESENCE function {checkAllFritzMACpresent("AA:BB:CC:DD:EE:FF")} 60 60</code>

Weitere Hinweise zu komplexeren Abfragen mehrere Boxen auf einmal etc. findet ihr auch im diesem {{Link2Forum|Topic=39433|LinkText=Forenthread}}.

=== Anwesenheitserkennung per Notify ===
Der von Fritzboxen und Fritz!WLAN Repeatern gespeicherte Status zum Status angemeldeter Geräte lässt sich (statt per PRESENCE, s.o.) auch per [[notify]] anfragen:

<syntaxhighlight lang="perl">define n_PRESENCE_mac_AA_BB_CC_DD_EE_FF notify Fritzbox:mac_AA_BB_CC_DD_EE_FF:.* {
my $s = "absent";
$s = "present" if (ReadingsVal($NAME,"mac_AA_BB_CC_DD_EE_FF","inactive") ne "inactive");
fhem("set anwesend_smartphone $s");
}</syntaxhighlight>

Hinweise:
* <code>fhem("set anwesend_smartphone $s");</code> ist nur ein Beispiel, das einen Dummy auf den Status "absent" bzw. "present" setzt. Man kann hier natürlich auch gleich entsprechende Aktionen durchführen. Wer das Beispiel übernehmen möchte, sollte den Dummy vorher definieren (<code>define anwesend_smartphone dummy</code>).
* mac_AA_BB_CC_DD_EE_FF ist die MAC-Adresse des gesuchten Geräts.
* "Fritzbox" ist der Name, unter dem die Fritzbox als FRITZBOX-Modul definiert wurde.
* Das Notify funktioniert, weil Geräte, wenn sie sich abgemeldet haben, erst den Status "inactive" erhalten. Ist das Gerät ganz abgemeldet, verschwindet das mac_.*-Reading. Dabei löst das Notify nicht mehr aus. Da das mac-.*-Reading aber vorher auf "inactive" stand, wurde die Abwesend-Aktion schon ausgeführt.
* Damit der Notify nicht andauernd losgeht, sollte man mittels <code>attr Fritzbox [[event-on-change-reading]] mac_AA_BB_CC_DD_EE_FF</code> Events nur auslösen, wenn sich der Status des Gerätes ändert. Will man mehrere Geräte abfragen, sollte man <code>attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF,mac_GG_HH_II_JJ_KK_LL</code> setzen, damit bei der Änderung jedes Readings ein Event ausgelöst wird.

Ein alternativer Ansatz mit einem [[DOIF]]:
<syntaxhighlight lang="perl">
define di_PRESENCE_handy DOIF (\
[Fritzbox:mac_AA_BB_CC_DD_EE_FF,"inactive"] eq "inactive"\
)\
( msg Tschuess )\
DOELSE\
( msg Hallo )

attr di_PRESENCE_handy cmdState absent|present
</syntaxhighlight>Für das DOIF gelten im Wesentlichen dieselben Hinweise wie für das notify oben und auch die im nächsten Abschnitt beschriebenen Vor- und Nachteile. Man bekommt allerdings dank dem <code>attr cmdState</code> auch gleichzeitig noch ein Device mit dem passenden Status "frei Haus", kann sich also das oben beschriebene dummy-Device sparen und auch das <code>event-on-change-reading</code> sollte nicht nötig sein.

=== Vergleich Anwesenheitserkennung PRESENCE/Notify ===
Die Anwesenheitserkennung per regelmäßiger PRESENCE-Abfrage hat den Vorteil, dass sie im Turnus der regelmäßigen Abfragen immer einen aktuellen Status produziert. Sie hat dafür den Nachteil, dass die PRESENCE-Funktionen regelmäßig abgearbeitet werden müssen, auch wenn sich gar nichts ändert. Außerdem aktualisiert sich der Status nicht sofort, sondern erst bei der nächsten regelmäßigen Abfrage. Durch häufiges Abfragen kann dieser Nachteil verringert werden (bei entsprechend höherer Systemlast).

Die Anwesenheitserkennung per Notify hat den Vorteil, dass ein sich ändernder Status sofort abgebildet wird. Ändert sich kein Status, werden keine Routinen ausgeführt, was die Systemlast gering hält. Der Nachteil ist, dass - z.B. nach einem Systemstart - die entsprechende Aktion erst bei einer Änderung des Status ausgeführt wird. D.h. ist das zu testende Gerät anwesend, wird dann FHEM beendet, das Gerät entfernt und FHEM wieder gestartet, ist der Status in FHEM immer noch "anwesend". Da das Reading für das Gerät nicht existiert, wird darauf auch erst wieder ein Notify ausgeführt, wenn sich der Status des Geräts wieder ändert, d.h. es wieder ankommt. Bis dahin ist der Status im System falsch.
Der Nachteil des Notify kann verringert werden, wenn man statt <code>attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF</code> ein <code>attr Fritzbox [[event-on-update-reading]] mac_AA_BB_CC_DD_EE_FF</code> setzt. Das erhöht allerdings die Systemlast und funktioniert auch nur für den Status "anwesend". Bei "abwesend" ist kein Reading vorhanden, so dass auch event-on-update-reading nicht ausgeführt wird.
Eine weitere Möglichkeit, den Nachteil der Notify-Methode auszugleichen, ist, die Statusabfrage beim Systemstart einmal manuell auszuführen, durch ein notify auf "GLOBAL:initialized":
<syntaxhighlight lang="perl">global:INITIALIZED {
my $s = "absent";
$s = "present" if (ReadingsVal("Fritzbox","mac_AA_BB_CC_DD_EE_FF","inactive") ne "inactive");
fhem("set anwesend_smartphone $s");
}</syntaxhighlight>
Das hilft allerdings nur beim Systemstart. Nicht, wenn FHEM aufgrund irgendwelcher Hänger eine Aktualisierung des Status verpasst hat.

=== userReadings per ''get tr064Command'' oder ''get luaQuery'' ===
Um dem Gerätewert <userReadingName> den Wert von <VariabelName> aus der Rückgabe des get-Befehls ''tr064Command'' oder ''luaQuery'' zuzuordnen
<pre>
attr <device> userReadings <userReadingName> {my $resp=fhem("get <device> tr064Command <service> <control> <action> [[<argName1> <argValue1>] ...]",1);;$resp =~/\'<VariabelName>\' => '(.*)'/;;return $1;;}
</pre>
{{Randnotiz|RNTyp=r|RNText='''VORSICHT''': man sollte einen genaueren Trigger für diese userReadings setzen, sonst wird bei jeder Aktualierung von jedem Reading das get Kommando ausgeführt, was ganz schnell ein (für fhem blockierende) Dauerlaufer werden kann.}}

Beispielsweise
<pre>attr Fritzbox userReadings urMobilteil_1 {my $resp=fhem("get Fritzbox tr064Command X_AVM-DE_OnTel:1 x_contact GetDECTHandsetInfo NewDectID 1",1);;$resp =~/'NewHandsetName' => '(.*)'/;;return $1;;},
urDownstreamDSLRate {my $resp=fhem("get Fritzbox tr064Command WANDSLInterfaceConfig:1 wandslifconfig1 GetInfo",1);;$resp =~/'NewDownstreamCurrRate' => '(.*)'/;;return $1;;},
urUpstreamDSLRate {my $resp=fhem("get Fritzbox tr064Command WANDSLInterfaceConfig:1 wandslifconfig1 GetInfo",1);;$resp =~/'NewUpstreamCurrRate' => '(.*)'/;;return $1;;}</pre>
oder bei einzelnen Werte über ''get luaQuery''<pre>attr Fritzbox userReadings sip1_connect {my $resp=fhem("get Fritzbox luaQuery sip:settings/sip1/connect",1);;$resp =~/([0-9])$/;;return $1;;}</pre>

=== Klingelton-Einstellung und Abspielen von Sprachnachrichten bei Fritz!OS-Versionen >6.24 ===
Wenn die Fritzbox weder die Telnet- noch die webcmd-Schnittstelle hat, kann der Klingelton der Fritz!Fons nicht mehr verstellt und auch keine Sprachnachricht über ein Fritz!Fon ausgegeben werden.

Es gibt eine Behelfslösung über das Attribut ''useGuiHack''. Dadurch wird eine Eingabe in die WebGUI der Fritzbox simuliert.

'''ACHTUNG''': Vor allem nach einem Update der FritzBox kann es durch dieses Attribut zu ungewolltem Verstellen von Werten in der Fritzbox kommen.

Bei Verwendung der ring-Parameter "play:" und "say:" wird die abzuspielende URL in die M3U-Datei, die unter dem Internal ''M3U_LOCAL'' steht, eingetragen.

Standardmäßig wird versucht, diese Datei im image-Verzeichnis von FHEM abzulegen. Diese kann dann vom Fritz!Fon über [[FHEMWEB]] abgespielt werden (IP-Freigaben beachten). Direkt nach dem ersten Anlegen der m3u-Datei kennt [[FHEMWEB]] diese noch nicht, daher bitte entweder ''set <webdevice> rereadicons'' ausführen oder FHEM neu starten.

Aufgrund der Beschränkungen von [[FHEMWEB]] oder auch bei Authentifizierungsanforderungen ist es empfehlenswert, die Datei über das Attribute ''m3uFileLocal'' selber vorzugeben. Am besten auf einem Webserver, der auf dem FHEM-Server läuft und dessen Seiten-Verzeichnis durch FHEM beschreibbar ist. Beispiel:
:<code>attr Fritzbox m3uFileLocal /var/www/mp3/Fritzbox.m3u</code>

In dem Radioeintrag ''FHEM'' muss dann '''auf der FritzBox''', die '''Web'''-Adresse der entsprechenden Datei eingetragen werden. Dieser Sender sollte zu Testzwecken dann auch einmal am Fritz!Fon von Hand gestartet werden.

Das Modul versucht, beim Start die einzutragende Radio-URL im image-Verzeichnis selber zu ermitteln (IP-Freigabe beachten). Gelingt dies, so steht diese im Internal ''M3U_URL''.

=== Ring auf mehreren Telefonen gleichzeitig ===
Damit mehrere Telefone per ring gleichzeitig klingeln, muss in der Fritzbox eine Rufgruppe definiert werden.
Sollte eine Türsprechanlage schon in Benutzung sein, kann die eventuell hierfür bereits eingerichtete Gruppe verwendet werden.

Das Anlegen der Gruppe kann wie in folgender AVM Anleitung beschrieben erledigt werden. [https://avm.de/service/fritzbox/fritzbox-7390/wissensdatenbank/publication/show/1148_Interne-Rufgruppe-in-FRITZ-Box-einrichten-Gruppenruf/ AVM Interne Rufgruppe anlegen]

Es muss eine Kurzwahl bei der Gruppe zwingend hinterlegt sein. Danach kann mit folgendem Beispielcode gearbeitet werden:
:<code>set FritzBox ring 791 15 show:Türklingel</code>

Name des Devices, Rufgruppen Nummer, Länge und gezeigter Text auf das Gewünschte anpassen.

== Bekannte Probleme / Fehlersuche ==
=== Fehler nach Firmware Update ===
Typischer Fehler ist hier "Error: 403 Forbidden".
Nach einem Firmwareupdate der Fritzbox am besten auch FHEM neu starten.

=== Modul bleibt im Status "Check APIs" hängen===
Im Log steht die Meldung: "Error: Timeout when reading Fritz!Box data.".

Mögliche Ursache: Nutzung des FHEM-Befehls [[rereadcfg]]. Dieser verträgt sich nicht mit dem Modul "blocking.pm", das für parallel laufende FHEM-Prozesse genutzt wird.

Abhilfe schafft ein Neustart <code>shutdown restart</code> oder das Einfügen eines zusätzlichen, lokalen Telnet-Ports z.B. durch <code>define tPortLocal telnet 7073</code>

=== Nachtschaltung Doppel-WLAN ===
Beim Abschalten des WLAN über das Modul wird (über TR064) zuerst das 2.4 GHz und dann das 5 GHz WLAN ausgeschaltet. Bei der gleichzeitigen Nutzung der WLAN-Nachtschaltung (Anschalten über das Fritz!OS) wird dann jedoch nur noch das 5 GHz WLAN wieder angeschaltet. Die Box interpretiert den TR064-Befehl anscheinend als ein komplettes Abwählen des 2.4 GHz WLAN.

Abhilfe schafft hier nur ein notify auf das 5 GHz WLAN mit einem nachträglichem Anschalten des 2.4 GHz WLAN.

Alternativ kann das Ausschalten des WLANs nicht direkt über TR064-Kommandos, sondern über einen indirekten Weg erfolgen: über TR064 ein set call abzusetzen und hier den Tastencode zum Ausschalten des WLANs einzugeben, bei einer FritzBox 7490 wäre dies z. B. #96*0*.
Schaltet man über diese Methode das WLAN aus, kann es über die Nachtschaltung wieder automatisch auf beiden Frequenzen angeschaltet werden.

=== Kabelboxen ===
Bei Fritz!Boxen für den Kabelanschluss (z.B. Kabel Deutschland) scheint neben Telnet auch die TR064-API nicht zu funktionieren. Vermutlich wurde die API von AVM auf Betreiberwunsch deaktiviert, da man sonst Dinge ändern kann, die das gesamte Kabelnetz stören können.

Zumindest für Unitymedia und einer FRITZ!Box 6490 Cable (lgi) mit FRITZ!OS:06.50 funktioniert TR064.

Eine Rufumleitung bei Abwesenheit (Modul PRESENCE) funktioniert mit einer vorher eingerichten Telefonnummer wie folgt:
<code>define Rufumleitung DOIF ([Anwesenheit.dum:state] eq "off") (set FritzBox6490 diversity 1 on) DOELSEIF ([Anwesenheit.dum:state] eq "on") (set FritzBox6490 diversity 1 off)</code>

=== Wenn's nicht klingelt ===
Das Klingeln erfolgt über die Wählhilfe. Eventuell muss über die Weboberfläche der Fritz!Box ein anderer Port eingestellt werden. Der aktuelle steht in "box_stdDialPort".

=== TR064-Transport-Error: 500 Can't connect to ...:49443 (certificate verify failed) ===
Eventuell hilft es, die Perl Module Net::HTTPS, Net::SSL und IO::Socket::SSL zu aktualisieren.

=== "Error: Old SID not valid anymore." nach Erlauben von IPv6 auf der Fritzbox ===
Ohne hier den genauen Grund zu kennen - es hilft die Angabe der IPv4-Adresse: also statt <code>define FritzBox FRITZBOX</code> dann <code>define FritzBox FRITZBOX <IP></code> (z.B. <code>define FritzBox FRITZBOX 192.168.10.1</code>), so dass das Modul nicht über IPv6 geht.

=== "Didn't get a session ID" ===
Bei gleichzeitiger Nutzung anderer Module für die Fritzbox (z.B. {{Link2CmdRef|Anker=FBAHAHTTP|Lang=en|Label=FBAHAHTTP}}) muss der Zugang über Benutzername und Password erfolgen.
:<code>attr <DEVICE> boxUser <USER></code>
Da das FRITZBOX-Modul eine inoffizielle Schnittstelle benutzt, muss dann auch der normale Zugang zur Box auf "Benutzername und Password" eingestellt sein.

In der Firmware 6.92 wird der Zugang über die Menüs "System"->"Fritz!Box-Benutzer"->"Anmeldung im Heimnetz" eingestellt.

Oft wird aber auch ein falsches oder gar kein Passwort gesetzt.

:<code>set <DEVICE> password <PASSWORD></code>

=== TR064-Error 401:invalid action ===
Eventuell ist auf der Fritzbox ein Benutzer gesetzt und im Modul nicht korrekt angegeben bzw. mit falschen Rechten versehen (attribut boxUser).

== Links ==
* {{Link2Forum|Topic=29725|LinkText=Forenthread}} zu diesem Modul

[[Kategorie:FritzBox]]
[[Kategorie:Akustische Ausgabe]]

Event-on-update-reading

2022-02-23T16:36:15Z

AlanBlack: /* Wechselwirkungen */

{{SEITENTITEL:event-on-update-reading}} 

Mit dem Attribut [[event-on-update-reading]] kann für Readings eines Gerätes festgelegt werden, dass bei jeder Aktualisierung ein Event (und damit in der Regel auch ein Log-Eintrag) erzeugt werden soll. Da dies das Defaultverhalten von FHEM ist, ist event-on-update-reading nur dann sinnvoll einsetzbar, wenn das Defaultverhalten vorher mit dem Attribut [[event-on-change-reading]] eingeschränkt wurde.

Wird ''event-on-update-reading'' für ein einzelnes Reading gesetzt, werden zunächst alle übrigen Readings nicht mehr protokolliert, erzeugen also keine Events mehr.
== Einführung ==
FHEM erzeugt für jedes gemeldete Reading ein Event, egal, ob das Reading sich geändert hat, oder nur Intervallweise per Update aktualisiert wurde. Dieses Verhalten kann Nachteile haben und daher mit [[event-on-change-reading]] für ein Gerät abgestellt werden.

[[event-on-update-reading]] dient dazu, für '''einzelne''' Readings des Gerätes das Standardverhalten wieder herzustellen, sollte es für bestimmte Readings in einer gegeben FHEM Installation sinnvoll sein, doch bei jedem Update auch ohne Werteänderung ein Event zu erhalten. Dies kann z.b. bei der Erzeugung von Graphen notwendig sein.
== Syntax ==
Das ''event-on-update-reading'' Attribut wird in der folgenden Weise spezifiziert:
:<code><nowiki>attr <device> event-on-update-reading reading1[,reading2...n]</nowiki></code>
Die zu berücksichtigenden Readings sind als durch Kommata getrennte Werte anzugeben, können aber auch über reguläre Ausdrücke zusammengefasst werden.

== Wechselwirkungen ==
Dieses Attribut steht in Wechselwirkung mit den Attributen [[event-on-change-reading]] und [[event-min-interval]], bitte beim Einsatz berücksichtigen. Ein Einsatz ohne gleichzeitige event-on-change-reading ist idR. nicht sinvoll.

Sind bei einem Device weder ''event-on-update-reading'' noch ''event-on-change-reading'' spezifiziert, werden für alle Readings sowohl bei Aktualisierung (mit dem gleichen Wert) als auch bei der Änderung Events erzeugt, dies ist das Standardverhalten. Sobald jedoch eines der beiden Attribute gesetzt ist, müssen alle Readings, die protokolliert werden sollen bei (mindestens) einem der Attribute berücksichtigt sein.

Ist für ein Reading sowohl ''event-on-change-reading'' als auch ''event-on-update-reading'' spezifiziert, wird bei jeder Aktualisierung des Readings ein Event erzeugt, das ''event-on-change'' wird für dieses Reading also außer Kraft gesetzt bzw. "überschrieben". Das ist erforderlich in allen Fällen, in denen ein Reading naturgemäß immer den gleichen Wert liefert oder liefern kann bspw. bei Tastern (toggle), oder in den Fällen, bei denen die Aktualisierung mit dem gleichen Readings-Wert geprüft wird wie bspw. ein Watchdog mit "SAME".

== Beispiele ==
Hat man durch
:<code>attr <device> event-on-change-reading .*</code>
erreicht, dass alle Readings des Gerätes nur noch bei Werteänderung eine Event erzeugen (und somit auch nur dann geloggt werden), kann mit
:<code><nowiki>attr <device> event-on-update-reading temperature, humidity</nowiki></code>
dafür gesorgt werden, das für Temperatur und Luftfeuchte dennoch mit jedem Update (intervallweise Aktualisierung auch ohne Werteänderung) ein Event erzeugt und geloggt wird.

== Praktische Anwendung ==
Da mit [[event-min-interval]] ebenfalls dafür gesorgt werden kann, dass Readings auch ohne Werteänderungen ein Event erzeugen, muss beim Einsatz geprüft werden, ob event-min-interval nicht sinnvoller als event-on-update-reading ist. Da die Updateintervalle einiger Geräte recht kurz sind, kann der Einsatz event-on-update-reading immer noch sehr viele (ggf. nutzlose) Events für das gegebene Reading erzeugen.

== Siehe auch ==
*[[event-on-change-reading]]
*[[event-min-interval]]

== Links ==
* Benutzungstipps (''Best Practice'') für das Attribut in {{Link2Forum|Topic=36522|LinkText=diesem Forenthread}}

[[Kategorie:Attribut (allgemeingültig)]]

Event-on-change-reading

2022-02-05T18:33:05Z

AlanBlack: /* Beispiel */

{{SEITENTITEL:event-on-change-reading}} 


Mit dem Attribut [[event-on-change-reading]] kann für Readings eines Gerätes festgelegt werden, dass nur bei einer Wertänderung ein Event (und damit in der Regel auch ein Log-Eintrag) erzeugt werden soll und nicht bei jedem turnusmäßigen Update des Gerätes.

Wird ''event-on-change-reading'' für ein einzelnes Reading gesetzt, werden zunächst alle übrigen Readings nicht mehr protokolliert, erzeugen also keine Events mehr.

== Einführung ==
Grundsätzlich senden Geräte ihre Readings dann, wenn ein Ereignis zu einer Statusänderung führt, also z.b. ein Schalter betätig wird. Allerdings senden die meisten Geräte auch immer Zusatzinformationen, etwa den Batteriestatus, Zieltemperatur, Pairingstatus, PeerList etc.etc.; meist sogar in bestimmten Intervallen (Update) auch ohne das das Reading sich ändert. Einige Geräte wie z.b. Shelly Plugs sind sehr "gesprächig" und senden auch den Status des Tasters mit jedem Update, selbst wenn der Schaltzustand sich nicht ändert.

Dies hat einige Nachteile:
* Aufblähen des Logfiles
* höhere Last der FHEM-Installation, da ein Event vom GeraetXXXX zunächst alle Notifys in FHEM benachrichtigt (d.h. notify, FileLog, sequence, watchdog, DOIF, etc), auch wenn diese mit dem Event nichts anfangen können.
* Konstrukte der Art <code><nowiki>… notify GeraetXXXX:wert …</nowiki></code> werden unter Umständen immer wieder im Update-Intervall ausgelöst, obwohl der Schaltzustand sich nicht geändert hat. (z.b. bei Shelly Plugs)
* EvenMonitor bzw. Telnet ''Info Timer'' mitunter unübersichtlich

Mit event-on-change-reading lässen sich für Readings eines Gerätes festgelegt, dass nur bei einer Wertänderung ein Event erzeugt wird und nicht mit jedem Update. Dies adressiert alle oben genannten Nachteile.

Allerdings kann die Nutzung von ''event-on-change-reading'' auch selbst Probleme erzeugen:
* Es muss überlegt werden, ob die eigene FHEM Installation an manchen Stellen in bestimmten Intervallen Meldungen benötigt, auch wenn die Werte sich nicht ändern. Dies sind typischerweise Graphen.
* Wird ''event-on-change-reading'' für ein einzelnes Reading gesetzt, erzeugen alle übrigen Readings des Gerätes keine Events mehr, '''auch nicht wenn Werte sich ändern'''.

Um das Verhalten von event-on-change-reading zu modifizieren und diese Probleme zu lösen, stehen ausserdem die Attribute [[event-on-update-reading]] (Reading soll mit jedem Update gesendet werden, auch wenn es sich nicht geändert hat) und [[event-min-interval]] ((Reading soll mit Update gesendet werden, wenn seit der letzten Meldung ZeitspanneX vergangen ist) zur Verfügung.

== Syntax ==
Das ''event-on-change-reading'' Attribut wird in der folgenden Weise spezifiziert:
:<code><nowiki>attr <device> event-on-change-reading reading1[:threshold][,reading2[:threshold]...n]</nowiki></code>
Die zu berücksichtigenden Readings sind als durch Komma getrennte Werte anzugeben, können aber auch über reguläre Ausdrücke zusammengefasst werden.

Insbesondere sinnvoll ist der reguläre Ausdruck .* , der alle Readings umfasst:
:<code><nowiki>attr <device> event-on-change-reading .*</nowiki></code>
So formuliert führt das Attribut dazu, dass alle Readings noch Events erzeugen, aber nur wenn diese sich im Wert ändern.

Mit Threshold ist optional ein Wert angebbar, um den das "neue" Reading größer oder kleiner sein soll als das vorherige, um ein Event auszulösen. So löst
:<code>attr event-on-change-reading temperature:0.4,humidity:2 </code>
nur bei Änderungen der Temperatur um mindestens 0,4 Grad oder Änderung der Luftfeuchtigkeit von 2 % ein Event aus (und damit einen Eintrag ins Logfile). Threshold ist besonders sinnvoll bei sehr fein auflösenden Sensoren, um z.B. zu verhindern, dass jede Temperaturschwankung um 0,1 Grad ein Event auslöst.

== Wechselwirkungen ==
Wie oben erwähnt, steht das Attribut in Wechselwirkung mit den Attributen ''timestamp-on-change-reading'' [[event-on-update-reading]] und [[event-min-interval]], die das Verhalten modifizieren. Dies ist beim Einsatz zu berücksichtigen.

Sind bei einem Device weder ''event-on-change-reading'' noch ''event-on-update-reading'' spezifiziert, werden für alle Readings sowohl bei Änderung als auch bei der Aktualisierung (Update mit dem gleichen Wert) Events erzeugt (Default Verhalten). Sobald jedoch eines der beiden Attribute gesetzt ist, müssen alle Readings, die protokolliert werden sollen, bei (mindestens) einem der Attribute berücksichtigt sein.

Ist für ein Reading sowohl ''event-on-change-reading'' als auch ''event-on-update-reading'' spezifiziert, wird bei jeder Aktualisierung des Readings ein Event erzeugt, das ''event-on-change'' wird für dieses Reading also außer Kraft gesetzt bzw. "überstimmt".

== timestamp-on-change-reading ==
Ist nur event-on-change-reading für ein Reading spezifiziert, entfällt zunächst einmal nur der Trigger, der Zeitstempel wird weiter aktualisiert. Benötigt man jedoch den Zeitstempel der letzten Änderung (z.B. die Ein- oder Ausschaltzeit eines Relais), kann man mithilfe von ''timestamp-on-change-reading'' auch die Aktualisierung des Zeitstempels unterbinden, falls der Wert sich nicht geändert hat.

== Beispiel ==
In einer einfachen Anwendung kann, um alle Readings eines Gerätes nur bei Änderungen zu verarbeiten, das Attribut folgendermaßen gesetzt werden:
:<code><nowiki>attr <device> event-on-change-reading .*</nowiki></code>
Zusätzlich kann mit
:<code><nowiki>attr <device> event-min-interval .*:3600</nowiki></code>
dafür gesorgt werden, dass jede Stunde auch ohne Werteänderung die Readings dennoch verarbeitet werden, also in z.b. in das Logfile geschrieben werden (findet FHEM zu wenige Ereignisse pro betrachteter Zeitspanne, bleiben Graphen leer oder werden nur teilweise gezeichnet (Plotabriss)).

Das obige Kombination der Attribute führt also dazu, dass ein Event erzeugt wird, wenn der neue Wert wirklich abweichend vom alten Wert ist '''oder''' mindestens ''min-interval'' Sekunden seit dem letzten Event vergangen sind.

Achtung: dies löst wie oben beschrieben ggf. Konstrukte wie <code><nowiki>… notify GeraetXXXX:wert …</nowiki></code> aus.

Falls ein Reading namens "unwanted" KEINE Events erzeugen soll, lässt sich das mit
:<code><nowiki>attr <device> event-on-change-reading (?!unwanted).*</nowiki></code>
unterdrücken.

Wenn KEIN Event bei einem Gerät erzeugt werden soll, lässt sich das mit
:<code><nowiki>attr <device> event-on-change-reading $</nowiki></code>
erreichen.

Um ein Threshold für nur ein Reading zu setzen:
:<code>attr <device> event-on-change-reading Temp.*:0.4,.*</code>
Alle Readings, die mit Temp beginnen, erzeugen nur ein Event, wenn die Änderung >0.4 Grad ist. Alle anderen Readings erzeugen bei jeder Änderung ein Event.

Nur ein Reading mit Threshold berücksichtigen:
:<code><nowiki>attr <device> event-on-change-reading Temp.*:0.4</nowiki></code>
Alle Readings, die mit Temp beginnen, erzeugen nur ein Event, wenn die Änderung >0.4 Grad ist. Alle anderen Readings erzeugen keine Event, auch nicht bei Werteänderung.

Mit [[event-on-update-reading]] und [[event-min-interval]] kann das Verhalten verfeinert werden.

== Siehe auch ==
*{{Link2Forum|Topic=26694|Message=196955|LinkText=Forenbeitrag}}
*[[event-on-update-reading]]
*[[event-min-interval]]
*[[event-aggregator]]
* Benutzungstipps (''Best Practice'') für das Attribut in {{Link2Forum|Topic=36522|LinkText=diesem Forenthread}}

[[Kategorie:Attribut (allgemeingültig)]]

Modul Alarm

2021-12-07T23:14:04Z

AlanBlack: Begonnen Abweichungen zwischen Beschreibung im Wiki und Verhalten des Moduls zu entfernen.

{{Infobox Modul
|ModPurpose=Das Modul stellt eine komfortable Oberfläche bereit, um per Webinterface Sensoren mit Aktoren zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar
|ModType=h
|ModCmdRef=Alarm
|ModForumArea=Unterstuetzende Dienste
|ModTechName=95_Alarm.pm
|ModOwner=Prof. Dr. Peter A. Henning
}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 95_Alarm.pm. Die nachfolgende Dokumentation ist nicht ganz aktuell, aber vollkommen hinreichend für die Installation.
Weitere Tipps und Hinweise findet man im Buch [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks].
Für Supportanfragen bitte ''{{Link2Forum|Topic=117581.0|LinkText=diesen Forenthread}}'' verwenden.

=Allgemeines=
Das Modul ''95_Alarm.pm'' stellt eine komfortable Oberfläche bereit, um per Webinterface bestimmte auslösende Elemente (nachfolgend 'Sensoren' genannt) mit bestimmten Aktionen (nachfolgend 'Aktoren' genannt) zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar ("scharf/armed" bzw. "unscharf/disarmed"). Diese Verknüpfungen werden als "normale" FHEM-Definitionen gespeichert.
==Erste Schritte==
Damit FHEM-Devices als Aktoren oder Sensoren für die Alarmanlage genutzt werden können, müssen zwei neue globale Attribute namens <nowiki>alarmDevice</nowiki> und <nowiki>alarmSettings</nowiki> eingeführt werden. Dazu muss in der Grundkonfiguration von FHEM die Definition der nutzerspezifischen Attribute via ''userattr'' angepasst werden. Bei Konfiguration über FHEMWEB ist es ratsam dazu die folgenden beiden Befehle zu nutzen:

{ addToAttrList("alarmDevice:Actor,Sensor") }
{ addToAttrList("alarmSettings") }

'''Alternativ:''' Möchte man dies direkt im ''global'' device ändern, so sollten die weiteren Attribute beibehalten werden, dies sieht etwa so aus:

attr global userattr '''alarmDevice:Actor,Sensor alarmSettings''' devStateIcon devStateStyle ...''(hier folgen weitere Attribute)''

Zur Erläuterung:
*Soll ein FHEM-Device als Sensor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Sensor' gesetzt.
*Soll ein FHEM-Device als Aktor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Actor' gesetzt
*Das Attribut ''alarmSettings'' wird beim Setzen der Alarme auf der Alarmkonfigurationsseite automatisch befüllt.
Ferner muss das Modul ''95_Alarm.pm'' im Modulpfad installiert werden, ebenso die JavaScript-Datei ''alarm.js'' in www/pgm2.
==Definition==
Die Alarmanlage - hier mit dem Namen ''AAA'' versehen - selbst wird über
define AAA Alarm
definiert. Diese Definition legt einen versteckten Raum "AlarmRoom" an, welcher über einen Weblink ''Alarm System'' im oberen Menü des Webinterfaces erreichbar ist.
*Der Name dieses Raumes kann durch das Attribut ''hiddenRoom'' geändert werden.
*Es wird ein weiterer Raum benötigt, der in der gegenwärtigen Fassung des Moduls den Namen ''Alarm'' trägt. Dieser wird automatisch erstellt, sobald die Alarme wie unten konfiguriert werden.
*Dieses Modul verwendet das globale Attribut ''language'' zur Bestimmung der Anzeigedaten (Standard: EN=english). Für deutsche Ausgabedaten muss in FHEM '''vor''' der Definition der Alarmanlage das Attribut
attr global language DE
gesetzt werden. Für dieses Wiki werden die englischen Ausgabedaten verwendet.

Beim Anklicken des Begriffes ''Alarm System'' im oberen Menü des Webinterfaces wird dieser versteckte Raum angezeigt. Er enthält an erster Stelle das Alarm-Device. Für die Konfiguration dieses Devices siehe den nächsten Abschnitt, für die Bedienung siehe den Abschnitt [Bedienung].

==Konfiguration des Alarm-Device==
Das Alarm-Device kennt nur wenige Set- und Get-Befehle.

Hinreichend beschrieben in der [https://commandref.fhem.de/#Alarm CommandRef].
==Bedienung im FHEMWEB Frontend==
In diesem Abschnitt wird die Bedienung der Weboberfläche und damit die Konfiguration der Alarmanlage beschrieben. Um sie zu erreichen, klickt man auf den Begriff ''Alarm System'' im oberen Menü des Webinterfaces.
===Settings===
Im oberen Bereich sind drei Eingabefelder zu sehen:
*''Wait Action'' ist ein FHEM-Befehl, der beim Scharfschalten des Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage wird in Kürze scharf geschaltet''.
*''Arm Delay'' ist eine Verzögerungszeit, die zwischen dem Scharfschalten des Alarms und der tatsächlichen Wirksamkeit vergeht. Diese Zeit kann beispielsweise genutzt werden, um das Haus ohne Auslösung des Alarms zu verlassen.
*''Arm Action'' ist ein FHEM-Befehl, der beim Scharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage scharf geschaltet''.
*''Disarm Action'' ist ein FHEM-Befehl, der beim Unscharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage unscharf geschaltet''.
*''Cancel Action'' ist ein FHEM-Befehl, der beim Widerrufen eines Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarm widerrufen''.

'''Achtung, das nachfolgende Bild ist nicht ganz up to date''', wird demnächst ersetzt

[[Datei:alarm_settings.png]]

8 Alarmlevel sind für das Modul normalerweise möglich (kann durch Setzen eines einzelnen Parameters im Modulcode verändert werden).
In der Tabelle 'Settings' können für jeden Level eine Bedingung, die Startzeit ''ts'' und Endzeit ''te'' sowie die Zeit ''tc' für das automatische Widerrufen des Alarmlevels gesetzt werden. ''

Die Bedingung wird als Perl-Code eingegeben, nur wenn sie den Wert 1 ergibt, wird der Alarm ausgeführt. Will man keine zusätzliche Bedingung prüfen lassen, muss hier einfach eine 1 stehen.

Formate für die Zeitangaben können sein:
* hh:mm - direkte Eingabe einer festen Zeit.
* {''funktion''} - eine beliebige Perl-Funktion in geschweiften Klammern, die einen gültigen Zeitwert hh:mm zurückliefert. Die Gültigkeit wird erst zur Laufzeit überprüft. Beispielsweise "30 Minuten vor Sonnenuntergang" als {sunset_abs(-1800)}.
Diese Aktivierungszeiten wirken sich wie folgt auf den Alarmlevel aus:
*Wenn ''ts'' < ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit < ''te''.
*Wenn ''ts'' >= ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit <= 23:59 sowie wenn 0:00 < Zeit <= ''te''.
Der Alarmlevel wird automatisch nach der Zeit für den Autowiderruf widerrufen. Setzt man diese Zeit auf 0:00, erfolgt kein automatischer Widerruf.

Ferner kann für jeden Alarmlevel gesetzt oder bedient werden
*Eine Nachricht zur Erläuterung des Alarms (Teil 2)
*Eine Checkbox ''Armed'' = scharf
*Ein Button ''Cancel'' zum Canceln = Aufheben des Alarms

===Sensors===
Danach wird die Tabelle der Sensoren angezeigt. Für jeden Sensor kann gesetzt werden:
*Alarmlevel, die hierdurch ausgelöst werden
*Ein regulärer Ausdruck, bei dessen Erkennung die Auslösung erfolgt
*Eine Nachricht zur Erläuterung des Alarms (Teil 1)
*Ein Selektor, um festzulegen, ob dieser Sensor den Alarm
**auslöst (=Raise),
**widerruft (=Cancel),
**scharf schaltet (=Arm) oder
**unscharf schaltet (=Disarm).
'''Achtung: Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.'''

Die insgesamt in den ''STATE'' der Alarmanlage geschriebene Nachricht besteht dann aus
(Anzeige der Zustände) (Nachricht Teil 1)' '(Nachricht Teil 2).
Bitte weiter unten nachlesen, was mit der [[#Anzeige der Zustände|Anzeige der Zustände]] gemeint ist.
In diesen Nachrichten werden die folgenden Ersetzungen vorgenommen
* $NAME vird durch den Namen des auslösenden Devices ersetzt
* $EVENT wird durch den kompletten Event ersetzt
* $EVTPART1... wird durch den 1. Teilstring des Events gefüllt, etc.

[[Datei:alarm_sensors.png]]

===Actors===
Anschließend wird die Tabelle der Aktoren angezeigt. Für jeden Aktor kann gesetzt werden:
*Alarmlevel, die diesen Aktor starten
*Ein FHEM-Kommando zum Starten des Aktors
*Ein FHEM-Kommando zum Stoppen des Aktors
*Eine Zeitverzögerung - entweder als Angabe von Sekunden (<60) oder im Format mm:ss
In den Strings für diese Aktionen werden folgende Ersetzungen vorgenommen:
* $NAME vird durch den Namen des auslösenden Devices ersetzt
* $EVENT wird durch den kompletten Event ersetzt
* $EVTPART1... wird durch den 1. Teilstring des Events gefüllt, etc.
* $SHORT wird durch die vollständige Kurznachricht der Alarmauslösung ersetzt

[[Datei:alarm_actors.png]]
==Bedienung mit anderen Frontends==
===Tablet-UI===
Eine Anleitung, wie das Modul mittels eines Keypads über das Tablet-UI scharf und unscharf geschaltet werden kann, findet sich auf [[Alarm und FTUI|dieser Seite]]

==Aktivierung==
Durch Anklicken des Buttons ''Set Alarms'' werden die ''alarmSettings''-Attribute befüllt.
'''Achtung, Folgendes beachten'''
*Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.
*Der Button ''Set Alarms'' wird nur funktionieren, wenn keine [[#Sperrung|Sperrung]] vorliegt, siehe unten.
*Es empfiehlt sich, danach ein ''Save Config'' auszuführen, damit die Attribute und Notifier permanent sind.

===Anzeige der Zustände===
Auf Wunsch können die Zustände der Alarmanlage zusammen mit der konkreten Meldung im internal ''STATE'' (bzw. reading ''state'', beide sind in diesem Modul identisch) angezeigt werden.
Hierfür gibt es ein Attribut ''statedisplay'' mit den folgenden möglichen Werten, die nachfolgend am Beispiel für den Zustand "Alarm Level 1 ausgelöst" erläutert sind:
* ''none'' - keine Anzeige
* ''simple'' - OXOOOOOO
* ''color'' - 0 1 2 3 4 5 6 7
* ''table'' - <table><tr style="height:1ex"><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:red"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td></tr></table>

Das Problem ist, dass möglicherweise das internal ''STATE'' an anderer Stelle verwendet werden soll - z.B. beim Versenden von Mails als ''Value('AAA')''
Es macht natürlich keinen Sinn, eine HTML-Tabelle in eine Mail zu packen. Deshalb sollte für die Weiterverarbeitung statt des obigen Code die Abkürzung ''$SHORT'' in den Feldern des Alarm-Moduls verwendet werden. Sie wird vor der Ausführung ersetzt durch ''$defs{'AAA'}{READINGS}{"short"}{VAL}''
Dies enthält nur die Meldung, nicht aber die Anzeige aller Zustände.

Alternativ kann man auch die Zustandsanzeige durch Wahl des Attributwertes ''none'' komplett abstellen.
===Sperrung===
Das Reading ''lockstate'' muss den Wert ''unlocked'' haben, damit durch Anklicken des Buttons ''Set Alarms'' die ''alarmSettings''-Attribute befüllt werden können. Das ist in der Regel beim ersten Laden des Moduls '''nicht''' der Fall, hierzu muss also das Reading von Hand auf den richtigen Wert gesetzt werden. Dazu muss der Befehl '''set ... unlocked''' ausgeführt werden.

=Sensoren=
==Rauchalarm==
'''Dieser Alarm ist mit Lebensgefahr verbunden und wird deshalb unabhängig von FHEM ausgelöst, und von FHEM nur registriert und mit weiteren Aktoren verbunden'''.

Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet. Deren Teamleader erhalten das Attribut ''alarmDevice Sensor'', so dass sie in der Sensorenliste der Alarmanlage auftauchen. Sie lösen den Alarm mit dem höchsten Level aus. Diese Einbindung in die Alarmanlage lässt sich aber auch für beliebige andere in FHEM eingebundene Rauchmelder erreichen.

[[Datei:alarm_smoke.png]]

==Öffnung von Fenstern oder Türen ==
Dies dient der Überwachung von '''Zustandsänderungen''', ebenso wie zur '''Überprüfung eines statischen Zustands'''
===Szenarien===
====Kontrollrunde====
Dieses Alarmszenario (Alarmlevel 4) liegt vor, wenn die Hausbewohner anwesend sind, aber irgendwann zu Bett gehen wollen und vorher noch überprüfen, ob auch alle Türen und das Garagentor geschlossen sind. Sagen wir, beginnend um 22:00 bis 23:59. Man könnte diesen Alarmlevel aber auch durch einen externen Regensensor auslösen, der die Dachfenster auf ihren Öffnungszustand untersucht. Jedenfalls sollte dieser Alarmlevel immer scharf sein.

Durch einen externen Auslöser (sagen wir, beginnend um 22:00 Uhr) wird in periodischen Abständen eine Hilfsroutine gestartet, welche die Zustandsprüfung vornimmt und registriert. Nur wenn diese Registrierung eine Öffnung ergibt, wird der Alarm ausgelöst. Dieser Alarmlevel gehört also zur Kategorie ''Warnung'' und wird deshalb nur eine moderate Signalisierung benötigen - beispielsweise
*eine Sprachmeldung wird auf einem wandhängenden Tablet ausgegeben
*eine Nachricht mit gelbem Hintergrund erscheint auf einem [[Digitaler_Bilderrahmen_mit_lcd4linux|Digitalen Bilderrahmen]]
*eine Nachricht erscheint auf einem [[1-Wire_Textdisplay]]
*eine LED geht an auf dem [[1-Wire LED-Statusmonitor]]

====Zutritt====
Dieses Alarmszenario (Alarmlevel 5) liegt vor, wenn die Hausbewohner anwesend sind, aber vermutlich schlafen gegangen sind. Sagen wir, von 0:00 bis 5:00.

Wenn morgens um 4:00 die Haustür geöffnet wird, handelt es sich entweder um ein spätes Heimkommen eines Hausbewohners von einer Party - oder um einen Einbruchsversuch. Der Partygeher sollte also eine gewisse Warnungszeit bekommen, bevor ein moderater akustischer Aktor (sagen wir, ein Funkgong) losgeht. Dieser Aktor muss deshalb mit einer Verzögerung eingeschaltet werden, und der Partygeher erhält eine Warnung. Diese Warnung - sagen wir, eine bestimmte Lampe geht an - informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa den für genau diese Lampe, um sie auszuschalten. Der Einbrecher kennt diesen Schalter nicht, der moderate Alarm wird also die schlafenden Hausbewohner wecken und ihn abschrecken.

Zusätzlich verfügt dieser Level auch noch über einen Partymodus: Mit diesem kann er für 24 Stunden abgestellt werden, so dass man auch um 3:00 in der Frühe die eigenen Partygäste aus dem Haus lassen kann, ohne ihn auszulösen.
====Einbruch====
Dieses Alarmszenario (Alarmlevel 6) liegt vor, wenn die Hausbewohner abwesend sind und diesen Level vorher scharf geschaltet haben - und idealerweise von 0:00 bis 23:59. Jeder Zutritt zu Haus löst diesen Alarm aus, und der akustische Aktor kann durchaus kräftig sein (etwa Einschalten der Rauchmelder für 1 Minute).

Da die Auslösung auch erfolgt, wenn der Hausbesitzer heimkommt, muss der akustische Aktor eine Verzögerung haben und innerhalb dieser einer Warnung gegeben werden, z.B. indem zunächst eine bestimmte Lampe angeht. Dies informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa die Kombination, um diesen Alarmlevel unscharf zu schalten. Der Einbrecher kennt diese Kombination nicht, die Beleuchtung wird ihn also zunächst abschrecken und der nachfolgende laute akustische Aktor auch die Nachbarn wecken.
===Zustandsänderung===
Dazu werden alle überwachten Fenster- und Türkontakte mit dem Attribut ''alarmDevice Sensor'' versehen, so dass sie in der Sensorenliste der Alarmanlage auftauchen. In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_tf.png]]

===Zustandsprüfung===
Dies dient der Überprüfung eines '''statischen Zustands''', konkret ob und welche Fenster oder Türen offen sind - z.B. abends, oder bei Regenwetter. Dazu benötigen wir drei ''dummy'' Devices, von denen zwei als ''alarmDevice Sensor'' und einer als ''alarmDevice Actor'' attributiert werden und somit in der Sensoren- bzw. Aktorenliste der Alarmanlage auftauchen.

define TFOpen.warn dummy
attr TFOpen.warn alarmDevice Sensor
'''attr TFOpen.warn alarmSettings alarm4,|TFOpen.warn:.*[TF].*|$EVENT|on''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.warn group windowDetector
attr TFOpen.warn room Alarm

define TFClose.warn dummy
attr TFClose.warn alarmDevice Sensor
'''attr TFClose.warn alarmSettings alarm4,|TFClose.warn:yes|Alle zu|off''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFClose.warn group windowDetector
attr TFClose.warn room Alarm

define TFOpen.check dummy
attr TFOpen.check alarmDevice Actor
'''attr TFOpen.check alarmSettings alarm4,|{HouseOpen()}||10:00''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.check group windowDetector
attr TFOpen.check room Alarm

[[Datei:TFAlarm.png|left|thumb|200px|]]Als nächstes muss eine Überwachungsroutine geschrieben werden. Das kann entweder als FHEM-Skript geschehen, oder in der Datei 99_myUtils.pm als perl-Code. Dieses Unterprogramm muss
*den obigen ''dummy'' TFOpen.warn setzen, und zwar auf den oder die Namen der geöffneten Fenster und Türen oder "none", wenn keine geöffnet sind.
*den obigen ''dummy'' TFClose.warn setzen, und zwar auf den Wert "no", wenn irgendeine geöffnet ist und "yes", wenn keine geöffnet sind.
Ein Beispiel für eine solche Überwachungsroutine ist weiter unten zu sehen.

Diese Doppelung ist nötig, weil jeder Sensor nur mit einem notify in den Alarmen auftauchen kann - das dient der Sicherheit gegen Fehlkonfiguration und ist beabsichtigt.

In dem nebenstehenden Flussdiagramm wird der Ablauf dargestellt, der sich mit diesem System ergibt. Dabei wird um 22:00 der erste Test auf ein ordnungsgemäß geschlossenes Haus gestartet - und bis Mitternacht alle 10 Minuten wiederholt. Alternativ könnte man das auch mit einem Regensensor als Erstauslöser koppeln.

Beispielcode für eine Überwachungsroutine:
<source lang="perl">
sub HouseOpen()
{
my $kfo = 0;
my $kfs = "";
my $kto = 0;
my $kts = "";
my $str = "";
if( Value("BK.F") ne "Closed" ){
$kfo++;
$kfs = "BK/";
}
if( Value("WK.F") ne "Closed" ){
$kfo++;
$kfs = $kfs."WK/";
}
if( Value("VK.T") ne "Closed" ){
$kto++;
$kts = "VK/";
}
if( Value("WZ.T') ne "Closed" ){
$kto++;
$kts = $kts."WZ/";
}
if( ($kfo >= 1) && ($kto == 0) ){
$kfs = substr($kfs,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kfs Fenster");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo == 0) && ($kto >= 1) ){
$kts = substr($kts,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts Tür");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo >= 1) && ($kto >= 1)){
$kts = substr($kts,0,-1);
$kfs = substr($kfs,0,-1);
$str = "$kts Tür + $kfs Fenster";
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts T / $kfs F");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}else{
fhem("set TFOpen.warn none");
fhem("set TFClose.warn yes");
}
return $str;
}
</source>

==Batterie schwach bei FHEM-Devices==
Dieser Sensor besteht aus einem ''notify'' und einem ''dummy'', der bei einer 'battery low'-Meldung eines beliebigen FHEM-Device auf dessen Namen gesetzt wird. Der ''dummy'' wird als ''alarmDevice Sensor'' attributiert, so dass er in der Sensorenliste der Alarmanlage auftaucht.

define LBatt.N notify .*:[Bb]attery.*[Ll]ow.* set LBatt.warn $NAME
attr LBatt.N room Alarm
attr LBatt.N group deviceDetector

define LBatt.warn dummy
attr LBatt.warn alarmDevice Sensor
attr LBatt.warn room Alarm
attr LBatt.warn group deviceDetector
Auf einen Test, ob gleichzeitig bei anderen FHEM-Devices die Batterie ebenfalls schwach ist, wird hier verzichtet. Für diesen Sensor wird ein eigener Alarmlevel (niedriger Priorität) erzeugt. Bei einem beliebigen 'battery low' Event wird somit der STATE der Alarmanlage gesetzt auf '''Batt. <devicename> schwach'''. Dieser Alarm muss manuell zurückgesetzt werden (schließlich sollten die Batterien ja erst gewechselt werden...)

[[Datei:alarm_lbatt.png]]

=Aktoren=
Aktoren können natürlich real existierende Devices sein. Man kann aber auch einfach Dummy-Devices anlegen und ihnen das Attribut ''alarmDevice Actor'' geben. Bei beiden Arten von Aktoren kann man dann als Aktion
* real existierende Devices schalten,
* ein Perl-Unterprogramm aufrufen oder
* einen Dummy auf einen bestimmten Wert setzen. Das löst einen Event aus, den man z.B. mit einem notify abfangen kann (eher umständlich...), oder der auf einer entfernten FHEM-Instanz mit FHEM2FHEM registriert wird.
Nachfolgend drei Beispiele
==Rauchmelder als Alarmsignal==
Für Alarme, bei denen es wirklich auf schnelle Reaktionen ankommt, kann man auch Rauchdetektoren verwenden, die über Funk aktivierbar sind. Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet.

'''Achtung: Es ist sehr empfehlenswert, diesen Alarm auch wieder automatisch auszuschalten.'''

Dazu wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht:

define SD.alarm dummy
attr SD.alarm alarmDevice Actor
'''attr SD.alarm alarmSettings alarm7,|set TH.SD0 alarmOn|set TH.SD0 alarmOff|30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr SD.alarm group alarmActor
attr SD.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_smokeactor.png]]

==Funk-Türgong / MP3-Türgong als Alarmsignal==
Hier wird ein FS20-Türgong als akustisches Alarmsignal verwendet.

define WZ.Gong FS20 <adresse>
attr WZ.Gong IODev CUL
attr WZ.Gong alarmDevice Actor
'''attr WZ.Gong alarmSettings alarm5,alarm6,|set WZ.Gong on||30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr WZ.Gong group alarmActor
attr WZ.Gong room Alarm,Erdgeschoss
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_gongactor.png]]

Bei Verwendung eines MP3-Funkgongs (z.B. aus dem Homematic-Programm) kann man auf diesem eine ganze Menge verschiedene MP3-Dateien speichern, die z.B. Stimmenmeldungen "Alarmanlage scharf geschaltet" abgeben. Zur Erstellung dieser Meldungen hat es sich bewährt, einen kostenlosen Online-TTS (Text-to-Speech) Service zu nutzen, z.B. Ivona.
==Alarmierung per SMS==
Für Alarme, die man auch im Urlaub auf das Handy bekommen möchte, bedarf es natürlich eines Providers, der eine bestimmte Mailadresse als SMS weiterleitet. Ferner einer FHEM-Konfiguration, die Mails versenden kann. Dann wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht. Die Abkürzung ''$SHORT'' wird vor der Ausführung durch die Kurzbeschreibung des Alarms ersetzt.
define Mail.alarm dummy
attr Mail.alarm alarmDevice Actor
'''attr Mail.alarm alarmSettings alarm6,alarm7,|{DebianMail(<mailadresse>,'Alarm','$SHORT'}||30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr Mail.alarm group alarmActor
attr Mail.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_mailactor.png]]

== Links ==
* {{Link2Forum|Topic=117581.0|LinkText=Forenthread}}
[[Kategorie:Examples]]

Modul Alarm

2021-12-07T22:26:20Z

AlanBlack: Link inzwischen nicht mehr gültig

{{Infobox Modul
|ModPurpose=Das Modul stellt eine komfortable Oberfläche bereit, um per Webinterface Sensoren mit Aktoren zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar
|ModType=h
|ModCmdRef=Alarm
|ModForumArea=Unterstuetzende Dienste
|ModTechName=95_Alarm.pm
|ModOwner=Prof. Dr. Peter A. Henning
}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 95_Alarm.pm. Die nachfolgende Dokumentation ist nicht ganz aktuell, aber vollkommen hinreichend für die Installation.
Weitere Tipps und Hinweise findet man im Buch [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks].
Für Supportanfragen bitte ''{{Link2Forum|Topic=117581.0|LinkText=diesen Forenthread}}'' verwenden.

=Allgemeines=
Das Modul ''95_Alarm.pm'' stellt eine komfortable Oberfläche bereit, um per Webinterface bestimmte auslösende Elemente (nachfolgend 'Sensoren' genannt) mit bestimmten Aktionen (nachfolgend 'Aktoren' genannt) zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar ("scharf/armed" bzw. "unscharf/disarmed"). Diese Verknüpfungen werden als "normale" FHEM-Definitionen gespeichert.
==Erste Schritte==
Damit FHEM-Devices als Aktoren oder Sensoren für die Alarmanlage genutzt werden können, müssen zwei neue globale Attribute namens <nowiki>alarmDevice</nowiki> und <nowiki>alarmSettings</nowiki> eingeführt werden. Dazu muss in der Grundkonfiguration von FHEM die Definition der nutzerspezifischen Attribute via ''userattr'' angepasst werden. Bei Konfiguration über FHEMWEB ist es ratsam dazu die folgenden beiden Befehle zu nutzen:

{ addToAttrList("alarmDevice:Actor,Sensor") }
{ addToAttrList("alarmSettings") }

'''Alternativ:''' Möchte man dies direkt im ''global'' device ändern, so sollten die weiteren Attribute beibehalten werden, dies sieht etwa so aus:

attr global userattr '''alarmDevice:Actor,Sensor alarmSettings''' devStateIcon devStateStyle ...''(hier folgen weitere Attribute)''

Zur Erläuterung:
*Soll ein FHEM-Device als Sensor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Sensor' gesetzt.
*Soll ein FHEM-Device als Aktor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Actor' gesetzt
*Das Attribut ''alarmSettings'' wird beim Setzen der Alarme auf der Alarmkonfigurationsseite automatisch befüllt.
Ferner muss das Modul ''95_Alarm.pm'' im Modulpfad installiert werden, ebenso die JavaScript-Datei ''alarm.js'' in www/pgm2.
==Definition==
Die Alarmanlage - hier mit dem Namen ''AAA'' versehen - selbst wird über
define AAA Alarm
definiert. Diese Definition legt einen versteckten Raum "AlarmRoom" an, welcher über einen Weblink im oberen Menü des Webinterfaces erreichbar ist.
*Der Name dieses Raumes kann durch das Attribut ''hiddenRoom'' geändert werden.
*Es wird ein weiterer Raum benötigt, der in der gegenwärtigen Fassung des Moduls den Namen ''Alarm'' trägt. Dieser wird automatisch erstellt, sobald die Alarme wie unten konfiguriert werden.
*Dieses Modul verwendet das globale Attribut ''language'' zur Bestimmung der Anzeigedaten (Standard: EN=english). Für deutsche Ausgabedaten muss in FHEM das Attribut
attr global language DE
gesetzt werden. Für dieses Wiki werden die deutschen Ausgabedaten verwendet.

Beim Anklicken des Begriffes ''Alarmanlage'' im oberen Menü des Webinterfaces wird dieser versteckte Raum angezeigt. Er enthält an erster Stelle das Alarm-Device. Für die Konfiguration dieses Devices siehe den nächsten Abschnitt, für die Bedienung siehe den Abschnitt [Bedienung].

==Konfiguration des Alarm-Device==
Das Alarm-Device kennt nur wenige Set- und Get-Befehle.

==Bedienung im FHEMWEB Frontend==
In diesem Abschnitt wird die Bedienung der Weboberfläche und damit die Konfiguration der Alarmanlage beschrieben. Um sie zu erreichen, klickt man auf den Begriff ''Alarmanlage'' im oberen Menü des Webinterfaces.
===Settings===
Im oberen Bereich sind drei Eingabefelder zu sehen:
*''Wait Action'' ist ein FHEM-Befehl, der beim Scharfschalten des Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage wird in Kürze scharf geschaltet''.
*''Arm Delay'' ist eine Verzögerungszeit, die zwischen dem Scharfschalten des Alarms und der tatsächlichen Wirksamkeit vergeht. Diese Zeit kann beispielsweise genutzt werden, um das Haus ohne Auslösung des Alarms zu verlassen.
*''Arm Action'' ist ein FHEM-Befehl, der beim Scharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage scharf geschaltet''.
*''Disarm Action'' ist ein FHEM-Befehl, der beim Unscharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage unscharf geschaltet''.
*''Cancel Action'' ist ein FHEM-Befehl, der beim Widerrufen eines Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarm widerrufen''.

'''Achtung, das nachfolgende Bild ist nicht ganz up to date''', wird demnächst ersetzt

[[Datei:alarm_settings.png]]

8 Alarmlevel sind für das Modul normalerweise möglich (kann durch Setzen eines einzelnen Parameters im Modulcode verändert werden).
In der Tabelle 'Settings' können für jeden Level eine Bedingung, die Startzeit ''ts'' und Endzeit ''te'' sowie die Zeit ''tc' für das automatische Widerrufen des Alarmlevels gesetzt werden. ''

Die Bedingung wird als Perl-Code eingegeben, nur wenn sie den Wert 1 ergibt, wird der Alarm ausgeführt. Will man keine zusätzliche Bedingung prüfen lassen, muss hier einfach eine 1 stehen.

Formate für die Zeitangaben können sein:
* hh:mm - direkte Eingabe einer festen Zeit.
* {''funktion''} - eine beliebige Perl-Funktion in geschweiften Klammern, die einen gültigen Zeitwert hh:mm zurückliefert. Die Gültigkeit wird erst zur Laufzeit überprüft. Beispielsweise "30 Minuten vor Sonnenuntergang" als {sunset_abs(-1800)}.
Diese Aktivierungszeiten wirken sich wie folgt auf den Alarmlevel aus:
*Wenn ''ts'' < ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit < ''te''.
*Wenn ''ts'' >= ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit <= 23:59 sowie wenn 0:00 < Zeit <= ''te''.
Der Alarmlevel wird automatisch nach der Zeit für den Autowiderruf widerrufen. Setzt man diese Zeit auf 0:00, erfolgt kein automatischer Widerruf.

Ferner kann für jeden Alarmlevel gesetzt oder bedient werden
*Eine Nachricht zur Erläuterung des Alarms (Teil 2)
*Eine Checkbox ''Armed'' = scharf
*Ein Button ''Cancel'' zum Canceln = Aufheben des Alarms

===Sensors===
Danach wird die Tabelle der Sensoren angezeigt. Für jeden Sensor kann gesetzt werden:
*Alarmlevel, die hierdurch ausgelöst werden
*Ein regulärer Ausdruck, bei dessen Erkennung die Auslösung erfolgt
*Eine Nachricht zur Erläuterung des Alarms (Teil 1)
*Ein Selektor, um festzulegen, ob dieser Sensor den Alarm
**auslöst (=Raise),
**widerruft (=Cancel),
**scharf schaltet (=Arm) oder
**unscharf schaltet (=Disarm).
'''Achtung: Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.'''

Die insgesamt in den ''STATE'' der Alarmanlage geschriebene Nachricht besteht dann aus
(Anzeige der Zustände) (Nachricht Teil 1)' '(Nachricht Teil 2).
Bitte weiter unten nachlesen, was mit der [[#Anzeige der Zustände|Anzeige der Zustände]] gemeint ist.
In diesen Nachrichten werden die folgenden Ersetzungen vorgenommen
* $NAME vird durch den Namen des auslösenden Devices ersetzt
* $EVENT wird durch den kompletten Event ersetzt
* $EVTPART1... wird durch den 1. Teilstring des Events gefüllt, etc.

[[Datei:alarm_sensors.png]]

===Actors===
Anschließend wird die Tabelle der Aktoren angezeigt. Für jeden Aktor kann gesetzt werden:
*Alarmlevel, die diesen Aktor starten
*Ein FHEM-Kommando zum Starten des Aktors
*Ein FHEM-Kommando zum Stoppen des Aktors
*Eine Zeitverzögerung - entweder als Angabe von Sekunden (<60) oder im Format mm:ss
In den Strings für diese Aktionen werden folgende Ersetzungen vorgenommen:
* $NAME vird durch den Namen des auslösenden Devices ersetzt
* $EVENT wird durch den kompletten Event ersetzt
* $EVTPART1... wird durch den 1. Teilstring des Events gefüllt, etc.
* $SHORT wird durch die vollständige Kurznachricht der Alarmauslösung ersetzt

[[Datei:alarm_actors.png]]
==Bedienung mit anderen Frontends==
===Tablet-UI===
Eine Anleitung, wie das Modul mittels eines Keypads über das Tablet-UI scharf und unscharf geschaltet werden kann, findet sich auf [[Alarm und FTUI|dieser Seite]]

==Aktivierung==
Durch Anklicken des Buttons ''Set Alarms'' werden die ''alarmSettings''-Attribute befüllt.
'''Achtung, Folgendes beachten'''
*Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.
*Der Button ''Set Alarms'' wird nur funktionieren, wenn keine [[#Sperrung|Sperrung]] vorliegt, siehe unten.
*Es empfiehlt sich, danach ein ''Save Config'' auszuführen, damit die Attribute und Notifier permanent sind.

===Anzeige der Zustände===
Auf Wunsch können die Zustände der Alarmanlage zusammen mit der konkreten Meldung im internal ''STATE'' (bzw. reading ''state'', beide sind in diesem Modul identisch) angezeigt werden.
Hierfür gibt es ein Attribut ''statedisplay'' mit den folgenden möglichen Werten, die nachfolgend am Beispiel für den Zustand "Alarm Level 1 ausgelöst" erläutert sind:
* ''none'' - keine Anzeige
* ''simple'' - OXOOOOOO
* ''color'' - 0 1 2 3 4 5 6 7
* ''table'' - <table><tr style="height:1ex"><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:red"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td><td style="width:1ex;background-color:green"></td></tr></table>

Das Problem ist, dass möglicherweise das internal ''STATE'' an anderer Stelle verwendet werden soll - z.B. beim Versenden von Mails als ''Value('AAA')''
Es macht natürlich keinen Sinn, eine HTML-Tabelle in eine Mail zu packen. Deshalb sollte für die Weiterverarbeitung statt des obigen Code die Abkürzung ''$SHORT'' in den Feldern des Alarm-Moduls verwendet werden. Sie wird vor der Ausführung ersetzt durch ''$defs{'AAA'}{READINGS}{"short"}{VAL}''
Dies enthält nur die Meldung, nicht aber die Anzeige aller Zustände.

Alternativ kann man auch die Zustandsanzeige durch Wahl des Attributwertes ''none'' komplett abstellen.
===Sperrung===
Das Reading ''lockstate'' muss den Wert ''unlocked'' haben, damit durch Anklicken des Buttons ''Set Alarms'' die ''alarmSettings''-Attribute befüllt werden können. Das ist in der Regel beim ersten Laden des Moduls '''nicht''' der Fall, hierzu muss also das Reading von Hand auf den richtigen Wert gesetzt werden. Dazu muss der Befehl '''set ... unlocked''' ausgeführt werden.

=Sensoren=
==Rauchalarm==
'''Dieser Alarm ist mit Lebensgefahr verbunden und wird deshalb unabhängig von FHEM ausgelöst, und von FHEM nur registriert und mit weiteren Aktoren verbunden'''.

Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet. Deren Teamleader erhalten das Attribut ''alarmDevice Sensor'', so dass sie in der Sensorenliste der Alarmanlage auftauchen. Sie lösen den Alarm mit dem höchsten Level aus. Diese Einbindung in die Alarmanlage lässt sich aber auch für beliebige andere in FHEM eingebundene Rauchmelder erreichen.

[[Datei:alarm_smoke.png]]

==Öffnung von Fenstern oder Türen ==
Dies dient der Überwachung von '''Zustandsänderungen''', ebenso wie zur '''Überprüfung eines statischen Zustands'''
===Szenarien===
====Kontrollrunde====
Dieses Alarmszenario (Alarmlevel 4) liegt vor, wenn die Hausbewohner anwesend sind, aber irgendwann zu Bett gehen wollen und vorher noch überprüfen, ob auch alle Türen und das Garagentor geschlossen sind. Sagen wir, beginnend um 22:00 bis 23:59. Man könnte diesen Alarmlevel aber auch durch einen externen Regensensor auslösen, der die Dachfenster auf ihren Öffnungszustand untersucht. Jedenfalls sollte dieser Alarmlevel immer scharf sein.

Durch einen externen Auslöser (sagen wir, beginnend um 22:00 Uhr) wird in periodischen Abständen eine Hilfsroutine gestartet, welche die Zustandsprüfung vornimmt und registriert. Nur wenn diese Registrierung eine Öffnung ergibt, wird der Alarm ausgelöst. Dieser Alarmlevel gehört also zur Kategorie ''Warnung'' und wird deshalb nur eine moderate Signalisierung benötigen - beispielsweise
*eine Sprachmeldung wird auf einem wandhängenden Tablet ausgegeben
*eine Nachricht mit gelbem Hintergrund erscheint auf einem [[Digitaler_Bilderrahmen_mit_lcd4linux|Digitalen Bilderrahmen]]
*eine Nachricht erscheint auf einem [[1-Wire_Textdisplay]]
*eine LED geht an auf dem [[1-Wire LED-Statusmonitor]]

====Zutritt====
Dieses Alarmszenario (Alarmlevel 5) liegt vor, wenn die Hausbewohner anwesend sind, aber vermutlich schlafen gegangen sind. Sagen wir, von 0:00 bis 5:00.

Wenn morgens um 4:00 die Haustür geöffnet wird, handelt es sich entweder um ein spätes Heimkommen eines Hausbewohners von einer Party - oder um einen Einbruchsversuch. Der Partygeher sollte also eine gewisse Warnungszeit bekommen, bevor ein moderater akustischer Aktor (sagen wir, ein Funkgong) losgeht. Dieser Aktor muss deshalb mit einer Verzögerung eingeschaltet werden, und der Partygeher erhält eine Warnung. Diese Warnung - sagen wir, eine bestimmte Lampe geht an - informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa den für genau diese Lampe, um sie auszuschalten. Der Einbrecher kennt diesen Schalter nicht, der moderate Alarm wird also die schlafenden Hausbewohner wecken und ihn abschrecken.

Zusätzlich verfügt dieser Level auch noch über einen Partymodus: Mit diesem kann er für 24 Stunden abgestellt werden, so dass man auch um 3:00 in der Frühe die eigenen Partygäste aus dem Haus lassen kann, ohne ihn auszulösen.
====Einbruch====
Dieses Alarmszenario (Alarmlevel 6) liegt vor, wenn die Hausbewohner abwesend sind und diesen Level vorher scharf geschaltet haben - und idealerweise von 0:00 bis 23:59. Jeder Zutritt zu Haus löst diesen Alarm aus, und der akustische Aktor kann durchaus kräftig sein (etwa Einschalten der Rauchmelder für 1 Minute).

Da die Auslösung auch erfolgt, wenn der Hausbesitzer heimkommt, muss der akustische Aktor eine Verzögerung haben und innerhalb dieser einer Warnung gegeben werden, z.B. indem zunächst eine bestimmte Lampe angeht. Dies informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa die Kombination, um diesen Alarmlevel unscharf zu schalten. Der Einbrecher kennt diese Kombination nicht, die Beleuchtung wird ihn also zunächst abschrecken und der nachfolgende laute akustische Aktor auch die Nachbarn wecken.
===Zustandsänderung===
Dazu werden alle überwachten Fenster- und Türkontakte mit dem Attribut ''alarmDevice Sensor'' versehen, so dass sie in der Sensorenliste der Alarmanlage auftauchen. In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_tf.png]]

===Zustandsprüfung===
Dies dient der Überprüfung eines '''statischen Zustands''', konkret ob und welche Fenster oder Türen offen sind - z.B. abends, oder bei Regenwetter. Dazu benötigen wir drei ''dummy'' Devices, von denen zwei als ''alarmDevice Sensor'' und einer als ''alarmDevice Actor'' attributiert werden und somit in der Sensoren- bzw. Aktorenliste der Alarmanlage auftauchen.

define TFOpen.warn dummy
attr TFOpen.warn alarmDevice Sensor
'''attr TFOpen.warn alarmSettings alarm4,|TFOpen.warn:.*[TF].*|$EVENT|on''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.warn group windowDetector
attr TFOpen.warn room Alarm

define TFClose.warn dummy
attr TFClose.warn alarmDevice Sensor
'''attr TFClose.warn alarmSettings alarm4,|TFClose.warn:yes|Alle zu|off''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFClose.warn group windowDetector
attr TFClose.warn room Alarm

define TFOpen.check dummy
attr TFOpen.check alarmDevice Actor
'''attr TFOpen.check alarmSettings alarm4,|{HouseOpen()}||10:00''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.check group windowDetector
attr TFOpen.check room Alarm

[[Datei:TFAlarm.png|left|thumb|200px|]]Als nächstes muss eine Überwachungsroutine geschrieben werden. Das kann entweder als FHEM-Skript geschehen, oder in der Datei 99_myUtils.pm als perl-Code. Dieses Unterprogramm muss
*den obigen ''dummy'' TFOpen.warn setzen, und zwar auf den oder die Namen der geöffneten Fenster und Türen oder "none", wenn keine geöffnet sind.
*den obigen ''dummy'' TFClose.warn setzen, und zwar auf den Wert "no", wenn irgendeine geöffnet ist und "yes", wenn keine geöffnet sind.
Ein Beispiel für eine solche Überwachungsroutine ist weiter unten zu sehen.

Diese Doppelung ist nötig, weil jeder Sensor nur mit einem notify in den Alarmen auftauchen kann - das dient der Sicherheit gegen Fehlkonfiguration und ist beabsichtigt.

In dem nebenstehenden Flussdiagramm wird der Ablauf dargestellt, der sich mit diesem System ergibt. Dabei wird um 22:00 der erste Test auf ein ordnungsgemäß geschlossenes Haus gestartet - und bis Mitternacht alle 10 Minuten wiederholt. Alternativ könnte man das auch mit einem Regensensor als Erstauslöser koppeln.

Beispielcode für eine Überwachungsroutine:
<source lang="perl">
sub HouseOpen()
{
my $kfo = 0;
my $kfs = "";
my $kto = 0;
my $kts = "";
my $str = "";
if( Value("BK.F") ne "Closed" ){
$kfo++;
$kfs = "BK/";
}
if( Value("WK.F") ne "Closed" ){
$kfo++;
$kfs = $kfs."WK/";
}
if( Value("VK.T") ne "Closed" ){
$kto++;
$kts = "VK/";
}
if( Value("WZ.T') ne "Closed" ){
$kto++;
$kts = $kts."WZ/";
}
if( ($kfo >= 1) && ($kto == 0) ){
$kfs = substr($kfs,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kfs Fenster");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo == 0) && ($kto >= 1) ){
$kts = substr($kts,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts Tür");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo >= 1) && ($kto >= 1)){
$kts = substr($kts,0,-1);
$kfs = substr($kfs,0,-1);
$str = "$kts Tür + $kfs Fenster";
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts T / $kfs F");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}else{
fhem("set TFOpen.warn none");
fhem("set TFClose.warn yes");
}
return $str;
}
</source>

==Batterie schwach bei FHEM-Devices==
Dieser Sensor besteht aus einem ''notify'' und einem ''dummy'', der bei einer 'battery low'-Meldung eines beliebigen FHEM-Device auf dessen Namen gesetzt wird. Der ''dummy'' wird als ''alarmDevice Sensor'' attributiert, so dass er in der Sensorenliste der Alarmanlage auftaucht.

define LBatt.N notify .*:[Bb]attery.*[Ll]ow.* set LBatt.warn $NAME
attr LBatt.N room Alarm
attr LBatt.N group deviceDetector

define LBatt.warn dummy
attr LBatt.warn alarmDevice Sensor
attr LBatt.warn room Alarm
attr LBatt.warn group deviceDetector
Auf einen Test, ob gleichzeitig bei anderen FHEM-Devices die Batterie ebenfalls schwach ist, wird hier verzichtet. Für diesen Sensor wird ein eigener Alarmlevel (niedriger Priorität) erzeugt. Bei einem beliebigen 'battery low' Event wird somit der STATE der Alarmanlage gesetzt auf '''Batt. <devicename> schwach'''. Dieser Alarm muss manuell zurückgesetzt werden (schließlich sollten die Batterien ja erst gewechselt werden...)

[[Datei:alarm_lbatt.png]]

=Aktoren=
Aktoren können natürlich real existierende Devices sein. Man kann aber auch einfach Dummy-Devices anlegen und ihnen das Attribut ''alarmDevice Actor'' geben. Bei beiden Arten von Aktoren kann man dann als Aktion
* real existierende Devices schalten,
* ein Perl-Unterprogramm aufrufen oder
* einen Dummy auf einen bestimmten Wert setzen. Das löst einen Event aus, den man z.B. mit einem notify abfangen kann (eher umständlich...), oder der auf einer entfernten FHEM-Instanz mit FHEM2FHEM registriert wird.
Nachfolgend drei Beispiele
==Rauchmelder als Alarmsignal==
Für Alarme, bei denen es wirklich auf schnelle Reaktionen ankommt, kann man auch Rauchdetektoren verwenden, die über Funk aktivierbar sind. Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet.

'''Achtung: Es ist sehr empfehlenswert, diesen Alarm auch wieder automatisch auszuschalten.'''

Dazu wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht:

define SD.alarm dummy
attr SD.alarm alarmDevice Actor
'''attr SD.alarm alarmSettings alarm7,|set TH.SD0 alarmOn|set TH.SD0 alarmOff|30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr SD.alarm group alarmActor
attr SD.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_smokeactor.png]]

==Funk-Türgong / MP3-Türgong als Alarmsignal==
Hier wird ein FS20-Türgong als akustisches Alarmsignal verwendet.

define WZ.Gong FS20 <adresse>
attr WZ.Gong IODev CUL
attr WZ.Gong alarmDevice Actor
'''attr WZ.Gong alarmSettings alarm5,alarm6,|set WZ.Gong on||30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr WZ.Gong group alarmActor
attr WZ.Gong room Alarm,Erdgeschoss
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_gongactor.png]]

Bei Verwendung eines MP3-Funkgongs (z.B. aus dem Homematic-Programm) kann man auf diesem eine ganze Menge verschiedene MP3-Dateien speichern, die z.B. Stimmenmeldungen "Alarmanlage scharf geschaltet" abgeben. Zur Erstellung dieser Meldungen hat es sich bewährt, einen kostenlosen Online-TTS (Text-to-Speech) Service zu nutzen, z.B. Ivona.
==Alarmierung per SMS==
Für Alarme, die man auch im Urlaub auf das Handy bekommen möchte, bedarf es natürlich eines Providers, der eine bestimmte Mailadresse als SMS weiterleitet. Ferner einer FHEM-Konfiguration, die Mails versenden kann. Dann wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht. Die Abkürzung ''$SHORT'' wird vor der Ausführung durch die Kurzbeschreibung des Alarms ersetzt.
define Mail.alarm dummy
attr Mail.alarm alarmDevice Actor
'''attr Mail.alarm alarmSettings alarm6,alarm7,|{DebianMail(<mailadresse>,'Alarm','$SHORT'}||30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr Mail.alarm group alarmActor
attr Mail.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_mailactor.png]]

== Links ==
* {{Link2Forum|Topic=117581.0|LinkText=Forenthread}}
[[Kategorie:Examples]]

Z-Wave

2021-09-04T20:11:01Z

AlanBlack: /* Links */

<div style="float:right">{{Infobox Modul
|Name=ZWDongle
|ModPurpose=Einbindung Z-Wave-Gateways
|ModType=d
|ModCmdRef=ZWDongle
|ModForumArea=ZWave
|ModTechName=00_ZWDongle.pm
|ModOwner=Rudolf König ([http://forum.fhem.de/index.php?action=profile;u=8 Forum])
}}
{{Infobox Modul
|Name=ZWave
|ModPurpose=Ansteuerung Z-Wave-Geräte über ZWDongle
|ModType=d
|ModCmdRef=ZWave
|ModForumArea=ZWave
|ModTechName=10_ZWave.pm
|ModOwner=Rudolf König ([http://forum.fhem.de/index.php?action=profile;u=8 Forum])
}}
</div>

[[Z-Wave]] ist ein drahtloser Kommunikations-Standard im 868 Mhz-Band (Europa), der von der Firma Sigma Designs und der Z-Wave Alliance, einen Zusammenschluss von mehreren Hundert Herstellern, für die Heimautomatisierung entwickelt wurde. Es existieren mehr als [http://products.z-wavealliance.org 1400 zertifizierte Produkte] verschiedenster Hersteller, die innerhalb eines gemeinsamen Z-Wave-Netzes einsetzbar sind. (Quelle: [http://de.wikipedia.org/wiki/Z-Wave Wikipedia])

Auf dieser Seite werden Grundlagen eines '''Z-Wave''' Systems und dessen Einrichtung in FHEM beschrieben.
== Z-Wave ==
=== Nodes - Controller und Slaves ===
Ein Z-Wave-Netz besteht aus mindestens 2 Geräten, den sogenannten '''Nodes''' (Knoten). Es setzt sich zusammen aus dem steuernden '''Controller''' (Zentrale) und min. 1 bis max. 231 gesteuerten '''Slaves''' (Geräten).

=== Home-Id und Node-ID ===
Innerhalb eines Z-Wave-Netzes gibt es zu 2 Identifikationsnummern zur Kennzeichnung der Netzstruktur:
# '''Home-ID:''' Gemeinsame Identifikationsnummer aller Nodes in einem Netz zur Abgrenzung gegenüber anderen Netzen. Nur Nodes mit der gleichen Home-ID können miteinander kommunizieren.
# '''Node-ID:''' Identifikationsnummer zur eindeutigen Kennzeichnung von jedem Node im Netz.

Die Home-ID ist im Controller (fest) hinterlegt und seine Node-ID ist typischerweise 1. Die Slaves haben zunächst keine Home-ID und Node-ID. Bei der '''Inklusion''' (Aufnahme) der Slaves in das Z-Wave-Netz überträgt der Controller seine Home-ID auf die Slaves und weist den Slaves eine eindeutige Node-ID im Netz zu, mit der Sie direkt angesprochen werden.

Besondere Node-ID ist die 255. Eine Nachricht an die Node-ID 255 kann von allen Z-Wave-Nodes ausgewertet werden (Broadcast).

=== Primär- und Sekundärcontroller ===
Der Controller, der durch Zuteilung seiner Home-ID auf die Slaves, das Netz aufbaut, ist der '''Primärcontroller'''. Grundsätzlich können in einem Netz mehrere Controller existieren, aber immer nur ein Primärcontroller. Weitere in das Netz eingebundene Controller werden zum '''Sekundärcontroller'''. Ohne besondere Maßnahmen kann nur der Primärcontroller die Inklusion (Einbindung) der Nodes in das Netz durchführen. Hingegen können sowohl Primär- als auch Sekundärcontroller die '''Exklusion''' (Ausschluss) eines Nodes aus dem Netz vornehmen.

Der Controller speichert intern diverse Informationen (Home-ID, Node-IDs,..) über das ZWave-Netz. Hierdurch kann unter anderem die Haussteuerungssoftware bei einem PC-Controller relativ unkompliziert gewechselt werden, da die wesentlichen ZWave-Netzinformationen vom Controller selbst verwaltet und gespeichert werden. Andererseits muß bei einem Controllerdefekt das gesamte Netz grundsätzlich neu aufgebaut werden, wenn kein Backup der internen Controllerdaten vorhanden ist.

=== Acknowledge ===
Im Z-Wave-Netz werden Nachrichten vom Empänger-Node an den Sender-Node rückbestätigt (Acknowledge). Bei ausbleibendem Acknowledge wiederholt der Sender-Node die Nachricht automatisch auf Protokollebene bis zu 2 mal. Hierdurch wird eine höhere Betriebssicherheit des Z-Wave-Netzes erreicht. Bei Broadcast-Nachrichten an die Node-ID 255 findet keine Rückbestätigung statt.

=== Vermaschtes Netzwerk mit Routing ===
Z-Wave nutzt als Netzwerktopologie ein '''mesh network''' (vermaschtes Netzwerk), d. h. jeder Node ist mit einem oder mehreren anderen Nodes verbunden. Das hat den Vorteil, dass eine Nachricht zwischen zwei Nodes übermittelt werden kann, selbst wenn diese nicht direkt miteinander kommunizieren können, z. B. weil sie zu weit voneinander entfernt sind. In diesem Fall wird die Funk-Nachricht über einen oder mehrere „Zwischen-Nodes“ übertragen; dieser Vorgang wird '''Routing''' genannt. Nur netzgespeiste Z-Wave-Geräte sind Router. Batteriebetriebe Z-Wave-Geräte sind grundsätzlich keine Router und dienen somit auch nicht zur Reichweitenerhöhung. (Quelle: [http://de.wikipedia.org/wiki/Z-Wave Wikipedia]) Einzelne Geräte, die alternativ per Batterie oder USB-Anschluss betrieben werden können, werden bei USB-Anschluss automatisch ({{Link2Forum|Topic=40393|Message=328080}}) oder durch Konfigurationsänderungen ({{Link2Forum|Topic=40393|Message=327331}}) zu Routern.

Informationen über das optimale Routing werden bei der Inklusion der Nodes in einer Routing-Tabelle des Primärcontrollers gespeichert. Dies geschieht durch Abfrage des Nodes, welche weiteren Nodes er erreichen kann. Durch örtliche Änderung oder Defekte von Nodes können die in der Routing-Tabelle gespeicherten Informationen fehlerhaft bzw. suboptimal werden. Dies kann sich in Funkkommunikationsproblemen im Netzwerk äußern. Hier kann ein per Software manuell angeforderter Neuaufbau der Routing-Tabelle gegebenenfalls Abhilfe schaffen. Bei Geräten und Controllern mit aktuellen Firmware-Versionen (SDK 4.5x und SDK 6.xx oder größer, aber ''nicht'' SDK 5.x) und Unterstützung von Explorer Frames kann sich die Routing-Tabelle unter bestimmten Bedingungen auch automatisch aktualisieren ("Selbstheilung")[https://web.archive.org/web/20160319202135/http://wiki.zwaveeurope.com/index.php?title=SDK_Versions_and_Explorer_Frames].

=== Command Classes ===
Die Steuerung und Kommunikation der Nodes erfolgt über Befehle die funktionsbezogen in verschiedene '''Command Classes''' (Kommandoklassen) zusammengefasst sind.

Alle Z-Wave-Geräte haben als gemeinsame kleinste Übereinstimmung die '''Class Basic'''.

Z-Wave-Geräte haben im Originalzustand eine bestimmte arbeitsfähige Grund-Konfiguration. Anpassbar an individuelle Bedürfnisse ist die Konfiguration über die '''Class Configuration'''.

Durch eine Assoziation wird definiert, welche Geräte miteinander direkt -ohne Umweg über den Controller- kommunizieren können. Auch bei Ausfall des Controllers können diese Geräte ihre gemeinsame Funkton ausüben. Zudem dienen Assoziationen der Geschwindigkeitssteigerung und Funklastreduzierung innerhalb des Netzes. Angelegt werden Assoziationen über die '''Class Association'''.

Dies sind nur die allerwichtigsten Command Classes. Weitere Command Classes sind den Handbüchern zu entnehmen. Zudem enthält die Wiki-Seite [[Z-Wave Command Classes]] weitergehende Informationen.

=== Hinweise zur Z-Wave-Geräteauswahl ===
Aufgrund der vielen Z-Wave-Gerätehersteller mit jeweils eigenem Z-Wave-Gerätesortiment existiert eine große Produktauswahl. Jedoch gibt es auch große Unterschiede hinsichtlich Produkteigenschaften, Pflege der Produkte, Häufigkeit der Aktualisierung der Produktpalette und so weiter. Schwierigkeiten bereitet insbesondere, dass neben den aktuellesten Chipsätzen und SDKs auch die älteren Chipsätze und SDKs weiterhin in Produkten im Handel verfügbar sind. Neuere Chipsätze und aktuelle SDKs bieten gerade bei der Netzwerkstabilität (Explorer Frames, Reichweite usw.) Vorteile zu älteren Chipsätzen und SDKs. Beispielsweise beherrschen nur Geräte mit SDK 4.5x und 6.x oder neuer die für automatische Routenkorrekturen wichtigen Explorer Frames. Das ältere SDK 5.0, das verwirrenderweise auch noch eine höhere Versionsnummer als das neuere SDK 4.5 besitzt, beherrscht unter anderem keine Explorer Frames. Details hierzu enthält das [https://web.archive.org/web/20160319202135/http://wiki.zwaveeurope.com/index.php?title=SDK_Versions_and_Explorer_Frames wiki.zwaveeurope.com]. Aktuellstes SDK ist Stand 10/2017 das SDK 6.7x, das in ZWave Plus - zertifizierten Produkten zum Einsatz kommt.

Gerade Einsteiger beachten die Unterschiede bei den Chipsätze/SDKs aus Unkenntnis manchmal nicht und ärgern sich im Nachhinein über Probleme bei der Netzwerkstabilität und Reichweite. Darum nachfolgend allgemeine, aber sehr einfache Empfehlungen zur Geräteauswahl. Selbstverständlich wird hier nicht von anderen Produkten abgeraten, wenn man die Unterschiede kennt und Vorteile bei deren Produkteigenschaften sieht. Zudem kann man (leider) schlechtere Produkteigenschaften bei Geräten mit aktuelleren Chipsätzen/SDKs nie ausschließen.

Gateway
# [http://z-wavealliance.org/z-wave_plus_certification Z-Wave Plus-Zertifizierung]. Diese ist mittlerweile bei nahezu allen erhältlichen Gateways gegebenen.

Endgeräte
# Z-Wave Plus-Zertifizierung (aktuellste Technik, höhere theoretische Reichweite, SDK 6.5x oder höher) oder
# zumindest Explorer Frames-Unterstützung (SDK 4.5x und 6.0x) oder
# zuletzt -bei Kenntnis der Besonderheiten und Auswirkungen- Produkte ohne Explorer Frames (SDK 5.0x)

'''Kurz''': Produkte mit Z-Wave Plus-Zertifizierung einsetzen.

Bitte unbedingt beachten, dass Z-Wave Plus-Vorteile bei einem Mischbetrieb mit älteren (ohne Plus) Geräten teilweise verloren gehen. Zum negativen Effekt des Einsatzes eines älteren, aber weiterhin erhältlichen Z-Wave-Repeaters mit aktuellen Z-Wave Plus-Geräten siehe beispielsweise den Hinweis in diesem {{Link2Forum|Topic=42591|Message=350066}}.

Bei Fragen zu bestimmten Geräten bitte -nach Durchsicht der Hinweise hier im Wiki- im Forum suchen oder anschließend nachfragen.

== Z-Wave in FHEM ==
=== Allgemein ===
FHEM wird fortwährend weiterentwickelt und verbessert. Daher ist es zwingend notwendig, dass FHEM auf dem aktuellsten Stand ist. Dazu nach der FHEM-Installation den Befehl <code>update</code> ausführen und anschließend <code>shutdown restart</code> durchführen. Genauso auch vor [[#Welche_Infos_sollten_Anfragen_im_ZWave-Forum_enthalten.3F|Anfragen im Forum]] die Aktualität von FHEM überprüfen.

Die Einbindung von Z-Wave in FHEM ist (nicht nur für den Anfänger) ausschließlich mit der standardmäßig eingeschalteten [[autocreate|autocreate-Funktion]] einfach möglich. Die Kenntnis der FHEM-Grundlagen und Durcharbeitung der Anfänger-Lektüren wird im Folgenden vorausgesetzt. Insbesondere sind [[Erste_Schritte_in_FHEM|Erste Schritte in FHEM]] und [http://fhem.de/Heimautomatisierung-mit-fhem.pdf Heimautomatisierung mit FHEM] Pflicht, auch wenn sie nicht speziell Z-Wave behandeln, so werden doch wesentliche Punkte für ein Verständnis von FHEM vermittelt.

Nachfolgend und auf den [[:Kategorie:Z-Wave Components|Wiki-Seiten der Einzelgeräte]] werden immer wieder Auszüge aus der [[Konfiguration]] dargestellt. Diese dienen zur Erläuterung und Veranschaulichung. Die Bearbeitung der Konfiguration sollte -zur Verhinderung von Fehlern- nach Möglichkeit immer über das "[[Konfiguration#Befehl-Eingabefeld|Befehl-Eingabefeld]]" und die "[[Konfiguration#Objektdetails|Objektdetails]]" erfolgen.

=== Vorbereitung ===
Die Bedienungsanleitungen (Handbücher) sind zwingende Voraussetzung zur korrekten Einbindung und Konfiguration von Z-Wave-Geräten in FHEM. Sie müssen daher vorliegen.
Den ZWave-Geräten liegen teilweise nur gekürzte, gedruckte Fassungen der Handbücher bei (beispielsweise Devolo, AEOTEC). Man sollte bei allen Produkten auf folgenden Seiten nach eventuellen ausführlicheren Handbüchern suchen:
* Herstellerseite des ZWave-Gerätes
* http://www.zwave.de/handbuecher/ (deutsch)
* http://products.z-wavealliance.org (englisch)
Insbesondere auf http://products.z-wavealliance.org, der Datenbank der ZWave-zertifizierten Produkte, sind regelmäßig ausführliche Informationen zu den Geräten zu finden.

== Definition des Gateways / Controllers ==
{{Randnotiz|RNText='''Tester für ZWave@culfw gesucht!'''
Z-Wave-Controllerfunktionen werden derzeit in die Firmware [http://www.culfw.de culfw] für den [[CUL]] implementiert. Weitere Informationen im [[ZWCUL]] - Artikel.}}
=== Autocreate des Gateways ===
FHEM kann mit einem Funkgateway Z-Wave-Funk empfangen und senden. Z-Wave-Gateways (Controller) existieren von verschiedenen Herstellern.

Folgende Gateways wurden unter anderem bereits erfolgreich mit FHEM eingesetzt:
* AEON Labs Z-Stick S2 (SDK 5.x; [https://aeotec.freshdesk.com/support/solutions/articles/6000091809-z-stick-s2-v3-08-firmware-update Firmwareupdate auf 3.08 aus 2016])
* Aeotec Z-Stick Gen5 (Z-Wave Plus; SDK 6.5; [https://aeotec.freshdesk.com/support/solutions/articles/6000108806-z-stick-gen5-backup-software Backup-Software)] ({{Link2Forum|Topic=47000}})
* Goodway WD6001 (SDK 5.03 {{Link2Forum|Topic=40594|Message=332235}})
* Vision Z-Wave USB Stick ZU 1401 EU (SDK 6.0x)
* Vision Z-Wave USB Stick ZU 1401-5 EU (Z-Wave Plus; SDK 6.5x)
* Z-Wave.Me Z-StickC ({{Link2Forum|Topic=29930|Message=226530}})
* Z-Wave.Me USB Stick ZME_UZB1 (SDK 6.5x; Z-Wave Plus; [http://razberry.z-wave.me/z-way-server/ Firmwareupdate und Backup über z-way])
* Z-Wave.Me Razberry in Verbindung mit Raspberry Pi (1. Generation: Z-Wave, 2. Generation: Gen5-Razberry mit Z-Wave Plus[http://forum.z-wave.me/viewtopic.php?f=3419&t=21327#p55404])
** Die seriellen Schnittstelle /dev/ttyAMA0 muss am Raspberry Pi freigeschaltet werden, damit das Razberry-Modul funktionsfähig ist: {{Link2Forum|Topic=78248|Message=702044}})
** Beim Raspberry Pi 3 muss der GPIO-Port auf den Hardware-UART0 umgestellt werden: [[Raspberry Pi 3: GPIO-Port Module und Bluetooth]]

Folgende Gateways sind '''nicht''' mit FHEM einsetzbar:
* Merten Funk-USB-Datenschnittstelle CONNECT

Sollte das eigene Gateway hier nicht aufgeführt sein, ist aufgrund der Standardisierung dennoch die Chance für eine erfolgreiche Einbindung des Gateways in FHEM vorhanden. Bitte dies hier oder im Forum entsprechend vermerken.

Das Z-Wave-Gateway wird unter Linux nach Anschluss an den FHEM-Rechner beim nächsten FHEM-Start oder ohne FHEM-Neustart durch Aufruf des Befehls <code>usb scan</code> zumeist automatisch erkannt und das zugehörige FHEM-Device nach dem Namensschema <code>ZWDongle_<[https://forum.fhem.de/index.php/topic,92885.msg854533.html#msg854533 Anhang]></code> angelegt. Ein manuelles Anlegen des ZWDongle-Moduls oder Eingriffe in die Konfiguration sind unter Linux normalerweise nicht notwendig.

Unter Windows ist ein manuelles Anlegen der Definition des ZWave-Gateways wegen fehlender Unterstützung des Befehls <code>usb scan</code> erforderlich (Beispiel für Z-Wave.Me USB Stick ZME_UZB1 unter Windows: <code>define ZWDongle_1 ZWDongle COM1@115200</code>).

Das FHEM-Gateway-Device ist nach der Definition in FHEM im Raum "Everything" zu finden.

Beispiele der automatisch erzeugten define-Zeile in der Konfiguration:

Aeon Labs Z-Stick an der Fritzbox:
define ZWDongle_1 ZWDongle /dev/ttyUSB1@115200

Vision Z-Wave USB Stick ZU 1401 EU am Raspberry Pi (Raspbian):
define ZWDongle_1 ZWDongle /dev/ttyACM1@115200

Insbesondere wenn am FHEM-Server unter Linux mehrere USB-Gateways eingesetzt werden, empfiehlt es sich zur Erhöhung der Betriebsstabilität das Z-Wave-Gateway über [[Trick_der_Woche#CUL_.26_CO_.C3.BCber_Serial_ID-einbinden|Serial-by-Id]] oder [[LinuxDeviceNaming|uDev-Regeln]] anzusprechen.

Bei einem statischen Controller wird die Einrichtung als SUC -sofern der Controller als solcher nicht bei Auslieferung eingerichtet ist- vor der ersten Inklusion von Geräten empfohlen.

=== homeId und nodeList des Gateways ===
Zur manuellen Definition von Z-Wave Aktoren und Sensoren ist die <code>homeId</code> notwendig. Bei der hier bevorzugten Definition der Geräte durch autocreate ist die Kenntnis der <code>homeId</code> nicht zwingend. Jedoch sollte durch Abfrage der <code>homeId</code> direkt nach Einbindung des Zwave-Gateways dessen Funktionsfähigkeit getestet werden.

Die <code>homeId</code> und <code>CtrlNodeId</code> des Gateways wird mit folgendem Befehl ausgelesen (<ZWDongle> ist im folgenden durch den Namen des FHEM-Devices des eigenen Gateways zu ersetzen):
get <ZWDongle> homeId
ergibt beispielsweise bei einem Gateway mit dem FHEM-Devicenamen ZWDongle_1:
ZWDongle_1 homeId => HomeId:e345c456 CtrlNodeId:01
In diesem Beispiel ist die Home-Id des Gateways ZWDongle_1 e345c456 und das Gateway hat die Node-Id 1.

Die aktuelle Liste der Z-Wave Nodes, die bereits am Gateway registriert/inkludiert sind, wird mit dem folgendem Befehl ausgelesen:
get <ZWDongle> nodeList
ergibt beispielsweise:
ZWDongle_1 nodeList => ZWDongle_1 UNKNOWN_2

== Definition von Geräten / Slaves ==
=== Hinzufügen eines neuen Z-Wave Geräts / Inklusion ===
Zur Verfolgung von Inklusionsablauf und Meldungen des Controllers während der Inklusion sollte der [[Event monitor]] in einem 2. Browserfenster vor Aktivierung des Inklusionsmodus geöffnet werden.

Das Z-Wave Gateway wird in den Standard-Modus zur Inklusion (zum Aufnehmen) neuer Geräte gesetzt:
set <ZWDongle> addNode on
Bei der Standard-Inklusion muss direkter Funkkontakt zwischen Gateway und zu inkludierendem Z-Wave Gerät bestehen.

Sofern Z-Wave Gateway und Z-Wave Geräte Explorer Frames unterstützen, sollte statt des obigen Befehls besser der Network-Wide-Modus für die Inklusion genutzt werden:
set <ZWDongle> addNode onNw
Bei der Network-Wide-Inklusion muss kein direkter Funkkontakt zwischen Gateway und zu inkludierendem Z-Wave Gerät bestehen. Es reicht, wenn das zu inkludierende Gerät über andere bereits inkludierte, netzgespeiste Geräte mit Explorer Frames-Unterstützung erreicht werden kann. Die Network-Wide-Inklusion ist zu bevorzugen, da die Z-Wave-Geräte regelmäßig an Ihren örtlichen Endpositionen inkludiert werden können. Dadurch werden bei der Inklusion direkt die korrekten Routen gespeichert.

Nachdem das Gateway in den Inklusionmodus geschaltet wurde, muss das Gerät in den Inklusionsmodus (Aufnahmemodus) versetzt werden. Wie dies zu erfolgen hat, ist im Handbuch des Geräte nachzulesen. Typisch sind ein- oder dreimaliges Drücken einer Taste am Gerät oder beim Anlegen der Versorgungsspannung. Durch die Inklusion werden Home-ID und Node-ID im Gerät gespeichert. Zudem teilt das Gerät über ein spezielle Funknachricht (NIF=Node Information Frame) dem Controller seinen Gerätetyp und seine Geräteeigenschaften mit. Hierbei werden dem Controller auch die vom Gerät unterstützten Command Classes mitgeteilt. Aus diesen Informationen erzeugt FHEM automatisch durch autocreate das FHEM-Geräte-Device nach dem Namensschema <code><nowiki>ZWave_<Geräteklasse laut NIF des Gerätes>_<NodeID></nowiki></code> (an eigene Wünsche anpassbar mit {{Link2CmdRef|Anker=rename|Label=rename}}). Die vom Geräte unterstützen Command Classes, die die in FHEM verfügbaren Befehle bestimmen, werden automatisch im Attribut <code>classes</code> des FHEM-Geräte-Device gespeichert. Das Gerät ist damit grundlegend in FHEM definiert und im Raum "ZWave" zu finden.

Nach der Inklusion schaltet FHEM den Inklusionsmodus des Z-Wave Gateway automatisch durch Absetzen des Befehls <code>set <ZWDongle> addNode off</code> aus und zeigt eine Dialogbox mit dem Ergebnis der Inklusion:
* <code><nowiki>created ZWave_<Geräteklasse laut NIF des Gerätes>_<NodeID></nowiki></code> = Inklusion war erfolgreich und es wurde das bezeichnete FHEM-Device durch autocreate angelegt.
* <code><nowiki>addNode failed</nowiki></code> = Inklusion ist fehlgeschlagen

Eine erfolgreiche Inklusion ist zudem am Event "ZW_ADD_NODE_TO_NETWORK protocolDone" im Event monitor und natürlich der Anlage des entsprechenden FHEM-Devices durch autocreate zu erkennen. Das Scheitern einer Inklusion führt typischerweise zur Ausgabe des Events "ZW_ADD_NODE_TO_NETWORK failed". Häufigste Ursache sind Controllerprobleme, die sich oftmals durch kurzes Ein- und Ausstecken des Controllers, Neustart des Systems oder Ein- und Ausschalten des FHEM-Server-Computers beheben lassen.

HINWEISE: 
* Die Network-Wide-Inklusion kann nach derzeitiger Kenntnis auch bei Gateways und Geräten ohne Explorer Frames Unterstützung genutzt werden, da bei diesen Geräten grundsätzlich automatisch auf die Standard-Inklusion umgestellt wird.
* Bei der Standard-Inklusion ist unter Umständen nur ein geringer Abstand zwischen Gateway und Gerät möglich. Sollte die Inklusion daher nicht durchführbar sein, wenn Gateway und Gerät an ihren örtlichen Endpositionen sind (bevorzugte Variante), dann ist der Abstand zwischen diesen versuchsweise zu verringern. Anschließend bei örtlicher Veränderung die Routen mit <code><nowiki>set <ZWave-Devicename> neighborUpdate</nowiki></code> bzw. <code><nowiki>set TYPE=ZWave:FILTER=ZWaveSubDevice=no neighborUpdate</nowiki></code> neu ermitteln lassen. Unter Umständen kann der Abstand nur schrittweise erhöht werden. Dann ist bei jeder Abstandsänderung eine Neuermittlung der Routen notwendig.
* Der NIF enthält bei manchen Geräten fälschlicherweise nicht alle unterstützten Command Classes. FHEM identifiziert während der Inklusion das Gerät und ergänzt die fehlenden Command Classes aufgrund manuell gepflegter, gerätespezifischer [[#Welche_Funktion_haben_die_XML-Config-Dateien_in_FHEM.3F|XML-Config-Dateien]]. Weiterhin fehlende Command Classes können im Attribut <code>classes</code> manuell am Anfang der Liste entsprechend ergänzt werden. Informationen liefern die unter [[#Links|Links]] aufgeführten Datenbanken. Häufig fehlt die Pflicht-Class BASIC.
* Bei der hier beschriebenen Inklusion findet die Kommunikation zwischen Controller und Gerät anschließend dauerhaft unverschlüsselt statt. Manche Geräte bieten mit der Command Class SECURITY eine AES-verschlüsselte Kommunikation an. Da die Verschlüsselung zu einer höheren Funklast und Latenzen führt, sollte eine verschlüsselte Kommunikation nur mit Bedacht eingesetzt werden (bspw. bei Schlössern). Als Sonderfall ist das Vorgehen zur secure-Inklusion in der [[#Wie_kann_eine_verschl.C3.BCsselte_Kommunikation_unter_Nutzung_der_Command_Class_SECURITY_eingerichtet_werden.3F|FAQ]] beschrieben.

Nächster Schritt ist die [[#Assoziation|Assoziation]] des Gerätes mit dem Gateway.

=== Assoziation ===
{{Randnotiz|RNText=Bitte unbedingt die Besonderheiten bei [[#batteriebetriebene_Ger.C3.A4te|batteriebetriebenen Geräten]] beachten!}}
Z-Wave-Geräte können über Assoziationen direkt mit anderen Z-Wave-Geräten kommunizieren. Dies können zum einen Meldungen über den Status und Zustand der Geräte, als auch direkte Befehle sein. Zum Beispiel kann damit ein Bewegungsmelder eine entdeckte Bewegung an den Controller senden und/oder bei entdeckter Bewegung direkt eine Lampe ein- oder ausschalten.

Die Assoziation zwischen zwei Geräten wird durch Aufnahme des zu steuernden Gerätes in eine oder mehrere Assoziationsgruppe(n) des steuernden Gerätes angelegt. Durch die Wahl der Assoziationsgruppe wird festgelegt, bei welchen Ereignissen welche Nachricht an das assoziierte Gerät verschickt wird. Angaben zu den Ereignissen und versandten Nachrichten an die Geräte in einer bestimmten Assoziationsgruppe stehen in der Bedienungsanleitung des jeweiligen Gerätes.

Damit FHEM Statusmeldungen von Sensoren/Aktoren anzeigen und auch darauf reagieren kann, '''muss''' der Controller (<ZWDongle>-Device, <code>CtrlNodeId</code> = typischerweise 1) immer in der/den passenden Assoziationsgruppe(n) des jeweiligen Gerätes <code><name></code> aufgenommen werden:

set <name> associationAdd <associationGroup> <CtrlNodeId>

Typischerweise ist die Assoziationsgruppe 1 der Geräte für die Statusmeldungen an den Controller vorgesehen (Ausnahme: [[#Fibaro|Fibaro-Geräte ohne ZWave Plus - Zertifizierung]]). Daher nimmt FHEM die Assoziation von Controller mit der Assoziationsgruppe 1 des Gerätes bei der Inklusion immer automatisch vor. Zudem identifiziert FHEM während der Inklusion das Gerät und setzt weitere Assoziationen mit dem Controller für von 1 abweichende Assoziationsgruppen aufgrund manuell gepflegter, gerätespezifischer [[#Welche_Funktion_haben_die_XML-Config-Dateien_in_FHEM.3F|XML-Config-Dateien]]. Ist keine XML-Config-Datei für das Gerät vorhanden, sind Assoziationen des Controllers mit von 1 abweichenden Assoziationsgruppen oder weiteren Assoziationsgruppen mit dem zuvor genannten Befehl grundsätzlich manuell anzulegen.

Die richtige Anlage der Assoziation(en) des Controllers mit dem Gerät immer prüfen, da dies eine Hauptfehlerquelle bei Funktionsproblemen mit FHEM ist.

Abruf der assoziierten Geräte in einer bestimmten Assoziationsgruppe <associationGroup>:
get <name> association <associationGroup>

Abruf der assozierten Geräte für alle Assoziationsgruppen eines Gerätes:
get <name> associationAll

Nahezu alle in Europa erhältlichen aktuellen Geräte unterstützen die Rückmeldung des Status via Association. Ausnahmen gibt es in Nordamerika, wo aufgrund von Patentansprüchen einige Hersteller auf die Statusrückmeldungen verzichten. Diese Geräte unterstützen in der Regel die Command Class ASSOCIATION nicht.

Nächster Schritt ist die [[#Konfiguration|Konfiguration]] des Gerätes.

=== Konfiguration ===
{{Randnotiz|RNText=Bitte unbedingt die Besonderheiten bei [[#batteriebetriebene_Ger.C3.A4te|batteriebetriebenen Geräten]] beachten!}}
Die Standard-Konfiguration eines Gerätes entspricht oftmals nicht den eigenen Wünschen und Anforderungen (Einheiten usw.). Mit den Befehlen der Class CONFIGURATION lässt sich die Konfiguration anpassen. Die zur Konfiguration eines Gerätes notwendigen Angaben zu den Parameternummern, -größen und -werten sind im jeweiligen Geräte-Handbuch bzw. entsprechenden Datenbanken (bspw. [http://devel.pepper1.net/zwavedb/ pepper1-ZWave-Datenbank] oder [http://products.zwavealliance.com/ products.zwavealliance.com]) enthalten.

Die Konfiguration beispielsweise bei Parametergröße 1 lässt sich mit diesem Befehl anpassen:
set <name> configByte <Parameternummer> <Parameterwert>
Für weitere Parametergrößen gibt es die Befehle <code>configWord</code> und <code>configLong</code>

Die im Gerät hinterlegten Konfiguration kann pro Parameternummer mit folgendem Befehl abgerufen werden:
get <name> config <Parameternummer>

Zudem bietet FHEM basierend auf den manuell gepflegten XML-Config-Dateien die Möglichkeit, die speziellen Parameternummern des Gerätes mit ihren Parametergrößen und -werte als eigenständige config-Befehle mit Hilfsinformationen einzubinden. Ein manuelles Suchen im Geräte-Handbuch und Nutzung der configByte-, configWord- und configLong-Befehle ist dadurch in vielen Fällen unnötig. Für diese Funktion muss das Gerät von FHEM einmalig durch folgenden Befehl, der bei der Inklusion automatisch ausgeführt wird, identifiziert werden:
get <name> model
Die Readings <code>model</code>, <code>modelID</code> und <code>modelConfig</code> werden dadurch erzeugt. In <code>model</code> sollte der Klartextname des Gerätes stehen. Zudem sind dann -soweit eine XML-Config Datei für das Gerät existiert- die speziellen set/get-Kommandos configXYZ für das Geräte im Auswahldialog der Detailansicht mit Hilfsinformationen verfügbar:
[[Datei:Z-Wave_confighelp.PNG|900px|thumb|center|config-Befehl mit Hilfstext]]

Bei vorhandener XML-Config-Datei kann die komplette Konfiguration eines Gerätes abgerufen werden:
get <name> configAll

Außerdem wird durch den <code>get <name> model</code> -Befehl geprüft, ob das Gerät in der [http://devel.pepper1.net/zwavedb/ pepper1-ZWave-Datenbank] und/oder [http://products.zwavealliance.com/ products.zwavealliance.com] enthalten ist. Im Erfolgsfall wird ein Link "Details in pepper DB" und/oder "Details in alliance DB" zum entsprechenden Geräteeintrag in der jeweiligen Datenbank unten in der Detailansicht des FHEM-Geräte-Devices angelegt und ein Bild des Gerätes in die Detailansicht eingebunden.

Der Aufruf von <code>get <name> model</code> ist auch für die Nutzung der Class MANUFACTURER_PROPRIETARY zwingende Einsatzvoraussetzung.

=== Entfernen eines Z-Wave-Geräts / Exklusion ===
Durch die Exklusion wird die Home-ID und Node-ID aus dem Gerät und das Gerät selbst aus der Node-List des Controllers gelöscht. Erst nach einer Exklusion kann das Gerät in ein anderes Z-Wave-Netz aufgenommen werden.

Zuerst wird der Z-Wave Gateway in den Standard-Modus zur Exklusion (Ausschluss) von Geräten gesetzt:
set <ZWDongle> removeNode on

Sofern Z-Wave Gateway und Z-Wave Geräte Explorer Frames unterstützen, sollte statt dem obigen Befehl besser der Network-Wide-Modus für die Exklusion genutzt werden (siehe auch Erläuterungen zu Standard- versus Network-Wide-Inklusion unter [[#Hinzufügen eines neuen Z-Wave Geräts / Inklusion|Inklusion]]):
set <ZWDongle> removeNode onNw

Danach muss das Gerät in den Exklusionsmodus (Ausschlussmodus) versetzt werden. Wie dies zu erfolgen hat, ist im Handbuch des Geräte nachzulesen.

Abschließend wird der Exklusionsmodus am Z-Wave Gateway wieder ausgeschaltet:
set <ZWDongle> removeNode off

Das FHEM-Device muss nach der Exklusion manuell durch <code>delete <name></code> gelöscht werden.

Die durch die Exklusion frei gewordene NodeID wird nicht bei der nächsten Inklusion wiederverwendet, sondern es wird die höchste noch nicht verwendete NodeID genutzt.

=== Erneutes Hinzufügen eines bereits registrierten Z-Wave Geräts ===
Die an einem Z-Wave-Gateway bereits registrierten/inkludierten Geräte sind im Gateway selbst abgespeichert und können durch FHEM jederzeit wieder abgerufen werden. Dies kann man in folgenden Fällen sinnvoll nutzen:
* Inklusion mit einem batteriegespeisten ZWave-Gateway (bspw. Aeon Labs Z-Stick) ohne FHEM-Server-Anschluss während der Inklusion
* Umstieg eines ZWave-Netzwerkes von Fremdsoftware auf FHEM
* Vollständiger oder teilweiser Verlust der FHEM-Konfiguration

Eine Node-Liste aller inkludierten Geräte des Gateways wird abgerufen durch:
get <ZWDongle> nodeList
Es wird eine Liste aller im Gateway inkludierten Gerät inklusive Gateway selbst zurückgeliefert. Sofern ein Gerät bereits als FHEM-Device angelegt wurde, wird der FHEM-Device-Name in der nodeList angezeigt. Dies ist für das Gateway selbst immer der Fall. Alle noch nicht in FHEM angelegten Geräte, werden als "UNKNOWN_x" ausgegeben, wobei x die ID des betreffenden Gerätes ist.

Mit dem folgenden Befehl wird beispielsweise das bereits im Gateway inkludierte Gerät mit der ID 2 (in der nodeList angezeigt als "UNKNOWN_2") in FHEM durch autocreate definiert:
set <ZWDongle> createNode 2

Batteriebetriebene Geräte müssen bei Absetzen des <code>createNode</code>-Befehls wach sein, damit der Befehl verarbeitet werden kann. Dies erreicht man, indem man das Gerät auf "permanent wach" stellt. Falls das Gerät diese Funktion nicht anbietet, muss man es manuell aufwecken und max. 2 Sekunden später den <code>createNode</code>-Befehl absetzen. Alternativ kann das batteriebetriebene Gerät durch Versand des NIF vom Gerät aus automatisch in FHEM erzeugt werden: Hierzu am Gerät die Taste zum Versand des NIF drücken und <code>autocreate</code> legt das FHEM-Device an; der Aufruf von <code>createNode</code> entfällt dann.

== Geräte-Besonderheiten ==
=== batteriebetriebene Geräte ===
Batteriebetriebenen Geräten können hinsichtlich ihrer Empfangsbereitschaft unterschieden werden in

* Wakeup-Geräte
* FLIRS-Geräte

==== Wakeup-Geräte ====
Wakeup-Geräte sind momentan die häufigste Art von batteriebetriebenen Z-Wave Geräten. Sie sind erkennbar an der Unterstützung der Command Class WAKE_UP.
Zur Verlängerung der Batterielaufzeit legen sich batteriebetriebene Wakeup-Geräte „schlafen“ und wachen (Wakeup) nur in konfigurierbaren Intervallen auf, um Befehle zu verarbeiten. Das Aufwachen signalisieren die Geräte durch den Versand einer Nachricht "wakeup notification". Daraufhin senden FHEM und andere Geräte ihre bis dahin gesammelten Befehle, die dann verarbeitet bzw. beantwortet werden. Anschließend gehen die batteriebetriebenen Geräte wieder in den Schlafmodus.

FHEM teilt bei set/get-Befehlen an batteriebetriebene Geräte über einen Hinweis der Form
:<code>Scheduled for sending after WAKEUP</code>
::oder
:<code>Scheduled get requests for sending after WAKEUP</code>
mit, dass der Befehl im Sendstack des FHEM-Geräte-Devices abgespeichert wurde und bei der nächsten "wakeup notification" an das Gerät versendet wird. Ein Versand der Befehle im Sendstack findet grundsätzlich ausschließlich nach Erhalt der "wakeup notification"-Nachricht statt, selbst wenn das Gerät zwischendurch andere Telegramme (bspw. Bewegungsmeldung, Temperatur) an den Controller verschickt. Nur nach Versand der "wakeup notification" ist das batteriebetriebene Gerät grundsätzlich in der Lage ("wach genug"), Telegramme korrekt zu empfangen und zu verarbeiten.

Wie viele Nachrichten im Sendstack auf einen Versand an das Gerät warten, ist im Internal <code>cmdsPending</code> des zugehörigen FHEM-Devices ersichtlich. Welche Nachrichten (Befehle) im Sendstack warten, ist in der Ausgabe des Befehls <code>[[list]] <device></code> erkennbar: Unter der Überschrift Sendstack sind alle wartenden Nachrichten als Rohnachrichten aufgeführt. Der Sendstack wird beim Beenden von FHEM nicht gespeichert. Durch Beenden von FHEM (beispielsweise durch <code>shutdown restart</code>) geht der Sendstack der Geräte daher verloren.

Das Wakeup-Interval und der Empfänger der "wakeup notification" wird wie folgt konfiguriert:
<nowiki>set <name> wakeupInterval <time> <NodeId></nowiki>
<nowiki><time></nowiki> ist die Zeit in Sekunden zwischen den Intervallen und <nodeID> der gewünschte Empfänger der "wakeup notification"; in der Regel ist dies '''immer''' der Controller <CtrlNodeId>. Viele Geräte kommen im Auslieferungszustand mit der NodeID 255. Die "wakeup notification" wird dann als Broadcast ohne Nutzung von Routing an alle erreichbaren Geräte gesendet. Hier sollte die Konfiguration auf die NodeID des Controllers geändert werden, da dadurch die "wakeup notification" geroutet wird und größere Entfernungen zwischen Gerät und Controller möglich sind. Zudem ist dies robuster und spart zusätzlich noch Batterielaufzeit. Darum setzt FHEM bei der Inklusion von WakeUp-Geräten '''automatisch''' den Befehl <code><nowiki>set <name> wakeupInterval 86400 <ControllerNodeId></nowiki></code> ab. Bei abweichenden eigenen Vorstellungen ist dies gegebenenfalls anzupassen. Bei Geräten mit V2 der Command Class WAKE_UP kann das vom Hersteller vorgesehene Standard-wakeupInterval mit <code><nowiki>get <name> wakeupIntervalCapabilities</nowiki></code> vom Gerät abgerufen werden. Die Einstellungen von wakeupInterval nach Inklusion und nach jeder Änderung immer mit der Abfrage <code><nowiki>get <name> wakeupInterval</nowiki></code> überprüfen.

Ein Aufwachen und Versand der "wakeup notification" von batteriebetriebenen Geräten kann für die [[#Assoziation|Assoziation]] und [[#Konfiguration|Konfiguration]] manuell erzwungen werden. Hierzu bringt man das Gerät normalerweise in den Inklusionsmodus oder findet in der Bedienungsanleitung gegebenenfalls andere Informationen. Bitte beachten, dass dann je nach Gerät nur eine geringe Entfernung von Gateway und Gerät vorhanden sein darf (direkte Erreichbarkeit). Alternativ kann für die Dauer der Assoziation und Konfiguration das Wakeup-Interval verkürzt werden (beispielsweise auf 60 Sekunden), wodurch das Routing genutzt werden kann und größere Entfernungen zwischen Gateway und Gerät überbrückt werden können. Anschließend das Wakeup-Interval wieder auf eine batterieschonenende Dauer einzustellen.

Einzelne batteriebetriebene Gerät lassen sich für längere Zeit auf "wach" bzw. permanent "wach" stellen. Dann aus dem Attribut <code>classes</code> <code>WAKE_UP</code> entfernen, damit Befehle in diesem Gerätemodus von FHEM direkt verschickt werden. Nach Ausschalten des "wach"-Modus <code>WAKE_UP</code> wieder im Attribut <code>classes</code> aufnehmen.

Bei Konfigurationsänderungen an batteriebetriebenen Geräten mit <code>set <name> config...</code> sollte die korrekte Verarbeitung der Befehle immer mit dem entsprechenden <code>get <name> config...</code> oder -falls vorhanden- mit <code>get <name> configAll</code> überprüft werden, um eventuelle Funk-Telegrammverluste sofort festzustellen.

==== FLIRS-Geräte ====
Ein batteriebetriebene FLIRS (frequently listening routing slave) Gerät wacht in sehr kurzen Zeitabständen (250ms oder 1000ms) auf und prüft, ob ein Funksignal vorliegt. Liegt kein Funksignal vor geht das Gerät wieder in Tiefschlaf. Zum Aufwecken eines FLIRS-Gerätes ist ein dauerhaftes Funksignal -der Wakeup-Beam-, notwendig, das etwas länger als die Aufweckzeitabstände sein muss. Näher beschrieben unter anderem [http://library.ademconet.com/MWT/fs2/VAM/Introductory-Guide-to-Z-Wave-Technology.PDF hier].

FLIRS-Geräte haben nicht die Command Class WAKE_UP und arbeiten deshalb nicht mit "wakeup notification". Aus Sicht des FHEM-Nutzers sind die bekannten FLIRS-Geräte (Sirenen von Vision und Popp) nicht anders zu bedienen/einzurichten als netzgespeiste Geräte. Wakeup-Beam und andere Besonderheiten werden unsichtbar für den Nutzer automatisch abgewickelt.

=== Aeon Labs / Aeotec ===
Ausführliche Handbücher und technische Informationen auf https://aeotec.freshdesk.com/support/home

==== Multi Sensor 5 ====
* aktuellste Firmware installieren
* Attribut <code>classes</code> um <code>BASIC</code> ergänzen (ab [[version|Modulversion]] 8824/25.6.2015 wird das automatisch bei der Inklusion durchgeführt)
* bei USB-Anschluss aus Attribut <code>classes</code> <code>WAKE_UP</code> entfernen
* Parameter 101 auf 225 (oder 224 bei USB-Anschluss) setzen mit <code>set <name> configGroup1Reports 225</code> oder <code>set <name> configLong 101 225</code>, um Batteriezustand (nicht bei 224), Temperatur, Feuchte und Helligkeit regelmäßig zu erhalten. Das Sende-Intervall wird duch <code><nowiki>set <name> configGroup1Interval <time/s></nowiki></code> festgelegt (Standard 720 Sek).
* [http://devel.pepper1.net/zwavedb/device/407 Paramterübersicht pepper-Datenbank]
siehe {{Link2Forum|Topic=34505|Message=268913}}

==== Multisensor 6 ====
siehe {{Link2Forum|Topic=40393}}
* arbeitet bei USB-Anschluß als Router
* bei USB-Anschluss aus Attribut <code>classes</code> <code>WAKE_UP</code> entfernen
* die <code>configGroupxInterval</code> und <code>configxxxReportingThreshold</code> Einstellungen wirken nur bei USB-Anschluss, im reinen Batteriebetrieb werden die Sensordaten nur bei einem <code>wakeup</code> übertragen

==== Aeotec LED Bulb ZW098-C55 ====
siehe {{Link2Forum|Topic=40504}}

=== Danfoss ===
==== DAN_LC-13 Heizungsthermostat LC-13 (014G0013) ====
Das Danfoss Heizungsthermostat LC-13 muss derzeit zur korrekten Funktion mit FHEM regelmäßig mit folgendem <code>at</code> abgefragt werden ({{Link2Forum|Topic=32145|Message=260795}}):
define Atdanfoss at +*00:30 get <name> battery
Auf dem Markt sind mehrere Varianten des Thermostates LC-13 erhältlich. Darum beim Kauf unbedingt auf die genaue Bezeichnung LC-13 (014G0013) achten ({{Link2Forum|Topic=38041|Message=303146}}).

=== devolo ===
Ausführliche Handbücher auf http://products.z-wavealliance.org

==== MT02648 Tür-/Fenster Kontakt 3in1 ====
siehe {{Link2Forum|Topic=41337}}

=== DüWI ===
Geräte von DÜWI liefern bei örtlicher Betätigung kein automatisches Funk-Signal über die Statusänderung. Das liese sich nur durch eine regelmäßige Statusabfrage durch FHEM (beispielsweise <code>define Status_Abfrage at +*00:03:00 get <name> swmStatus</code>) beheben.
Einige Produkte von [http://zwave.me Z-Wave.Me] basieren auf DÜWI-Geräten. Diese Z-Wave.Me Produkte haben jedoch eine erweiterte Firmware, welche die genannte und weitere Firmware-Schwächen der Original-Produkte von DÜWI behebt.

=== Everspring ===
==== AN145 Sockelmodul E27 ====
Statusabfrage ohne permanente Abfrage: {{Link2Forum|Topic=48864|Message=405545|Beitrag}}

=== Fibaro ===
Association Group für Übermittlung von Statusinformationen an den Controller:
* "alte" ZWave-Geräte (kein ZWave-Plus): häufig Association Group 3
: <code><nowiki>set <name> associationAdd 3 <CtrlNodeId></nowiki></code>
: Bei diesen Geräten empfiehlt es sich zur Funklastreduzierung und Problemminimierung zu prüfen, ob die von FHEM automatisch vorgenommene Assoziation des Controllers mit der Association Group 1 gelöscht werden kann (<code><nowiki>set <name> associationDel 1 <CtrlNodeId></nowiki></code>). Nahezu immer werden in Association Group 1 die gleichen Infos, nur mit einer anderen Command Class, wie in der Association Group 3 an den Controller übermittelt.
* ZWave Plus-Geräte: Association Group 1 ("lifeline")

==== FGSS-001 / FGSD-002 Rauchmelder ====
* nicht untereinander vernetzbar
* keine Alarmauslösung/Sirenenfunktion durch ZWave-Zentralen

==== FGS-222 Relais Unterputzeinsatz ====
Bei der Inklusion werden von FHEM 3 Devices angelegt:
* Hauptdevice (Steuerung und automatischer Status für Kanal 1 und kanalübergreifende Funktionen)
* Device für Endpoint 1 (Steuerung Kanal 1)
* Device für Endpoint 2 (Steuerung und automatischer Status von Kanal 2)
Die Firmware des FGS-222 übermittelt den Status für Kanal 1 automatisch immer ausschließlich an das Hauptdevice. Die Steuerung von Kanal 1 kann hingegen sowohl über das Hauptdevice als auch über das Device für Endpoint 1 erfolgen. Das Device für Endpoint 1 ist somit nicht zwingend erforderlich und kann grundsätzlich gelöscht oder in den room hidden verschoben werden.

Details: {{Link2Forum|Topic=50176}}

Hinweis zum Reset: {{Link2Forum|Topic=55190|Message=469393}}

==== FGK-101 Tür/Fensterkontakt ====
* Besonderheiten bei Anschluss eines Temperatursensors: {{Link2Forum|Topic=38012}}

=== GE ===
==== GE (Model t.b.d) ====
Dieser Schalter unterstützt keine Statusrückmeldungen.

=== Merten ===
Laut {{Link2Forum|Topic=38133}} müssen bei einigen Merten-Geräten, die mit Fremdsoftware inkludiert wurden, gegebenenfalls die Geräte wieder exkludiert und dann erneut mit FHEM inkludiert werden, damit Assoziationen mit FHEM gesetzt werden können.

=== Philio ===
==== PHI_PAN04 Relais Unterputzeinsatz 2 Schalter a 1.5kW mit Messfunktion ====
siehe {{Link2Forum|Topic=28046}}

=== Popp ===
==== POPE004001 Z-Wave Rauchmelder mit Innensirene ====
siehe {{Link2Forum|Topic=39856}}
==== POPE005107 Z-Wave Außensirene ====
siehe {{Link2Forum|Topic=42736}} 
Alte Firmwareversionen haben einen Bug bei der Übermittlung von negativen Temperaturen. Eine Lösungsvariante über ein <code>userReadings</code> findet sich auch im verlinkten Thema.
==== POPE009006 Z-Wave Wall Plug Switch ====
siehe {{Link2Forum|Topic=40771}}
==== POPE009402 10Year Smoke Detector ====
Die erste Firmwareversion hat eine fehlerhafte modelID. Diese Rauchmelder wird dadurch fälschlich als [[Z-Wave#POPE005107_Z-Wave_Au.C3.9Fensirene|Popp Aussensirene]] in FHEM angezeigt. Neuere Geräte werden laut Popp mit der korrekten modelID ausgeliefert.

=== Z-Wave.Me ===
==== ZME_RC2 Fernbedienung ====
siehe {{Link2Forum|Topic=35513}} 
Das Forenthema enthält eine detaillierte Beschreibung der Nutzung der Class MULTI_CHANNEL_ASSOCIATION.

== Geräte-Vergleich ==
=== Doppel-Relais ===
{| class="wikitable"
|-
! Eigenschaft !! FIBARO Double Switch 2-FGS-223 !! Qubino Flush 2 relays !! Philio-PAN04 1
|-
| Funktion || Doppel-Relais || Doppel-Relais || Doppel-Relais
|-
| Standby-Leistung || ca. 0.4W || ca. 0.4W || ca. 0.5W
|-
| Reaktion beim Schalten am Tastereingang || schnell, kaum merkliche Verzögerung || schnell, kaum merkliche Verzögerung || langsam, unangenehm langes drücken des Tasters nötig >1 Sekunde
|-
| Geräte in FHEM || 3 x Hauptgerät x.01 Relais 1 x.02 Relais 2 || 3 x Hauptgerät x.01 Relais 1 x.02 Relais 2 || 4 x Hauptgerät x.01 Relais 1 x.02 Relais 2 x.03 Summengerät (ähnlich Hauptgerät, überflüssig)
|-
| Zustand Hauptgerät || Oder-Verknüpfung der beiden Relais || Oder-Verknüpfung der beiden Relais || Oder-Verknüpfung der beiden Relais
|-
| Statuswechsel Report vom Gerät zum FHEM || ca. 1 Sekunde || ca. 3 Sekunden || ca. 3-4 Sekunden
|-
| Empfänger des Status Reports || Hauptgerät und Untergeräte || Hauptgerät und Untergeräte || Nur Hauptgerät Aktualisierung der Untergeräte nur bei aktiver Abfrage
|-
| Leistungsmessung || Separat für Untergeräte || Separat für Untergeräte || Nur Summe
|-
| Sicherung nötig / Strom || ja, 2x 6.5A, Summe max 10A || ja, max 2x 4A || nein, 2x 6.5A
|}
Beim Qubino Flush 2 relays muss eine MULTI_CHANNEL_ASSOCIATION mit dem Controller (Endpoint root) statt einer "normalen" Assoziation gesetzt werden, damit die Status der Untergeräte einzeln signalisert werden:

set associationDel 1 <controllerNodeId>
set <device> mcaAdd 1 0 <controllerNodeId> 0

Bei einem FHEM-Updatestand ab 20.09.2019 erfolgt diese Einstellung automatisch.

== Links ==
=== Allgemein ===
* Grundlageninformation "Z-Wave-Haupt-Anleitung": [http://www.zwave.de/z-wave-funknetz-einrichten-und-betreiben/ Wie errichte und betreibe ich ein Z-Wave basiertes Funknetz]{{Randnotiz|Links teilweise nicht mehr aktuell|RNText=zwave.de existiert nicht mehr. Es erfolgt ein Forward auf zwave.eu/de. Die hier angegebenen Links darauf werden aber nicht abgebildet und liefern einen 404.Ich suche noch nach den korrekten Seiten.|RNTyp=Fehl}}
* [http://www.zwave.de/buch-z-wave-grundlagen/ Buch] "Z-Wave: Die Funktechnologie für das Smart Home" von Dr. Christian Paetz (Paetz "is the primary European representative for the Z-Wave Alliance" [http://z-wavealliance.org/global-contacts/])
* Z-Wave-Produktdatenbank mit Angabe zur Zertifizierung, Handbüchern und weiteren Detailinfos (Z-Wave oder [http://z-wavealliance.org/z-wave_plus_certification Z-Wave Plus]): http://products.z-wavealliance.org (englisch)
* herstellerübergreifende Datenbank mit Bedienungsanleitungen zu Z-Wave-Geräten: http://www.zwave.de/handbuecher/ oder http://manuals.zwaveeurope.com (mehrsprachig)
* herstellerübergreifende Datenbank mit technischen Informationen zu Z-Wave-Geräten (Z-Wave Device Library): http://devel.pepper1.net/zwavedb/ (englisch; wird derzeit nicht mehr aktualisiert)
* informative Webseiten zu Z-Wave:
** http://www.z-wavealliance.org/ (englisch)
** http://www.zwaveeurope.com/ (englisch)
** http://www.zwave.de/ (deutsch)
** [http://library.ademconet.com/MWT/fs2/VAM/Introductory-Guide-to-Z-Wave-Technology.PDF Introductory Guide to Z-Wave-Technology von Honeywell] (englisch; nicht auf aktuellem Stand)

=== Informationsquellen zur Einbindung von Command Classes ===
Offizielle und ausführliche Informationen von Sigma Designs (veröffentlicht am 31.08.2016):
* [http://z-wave.sigmadesigns.com/design-z-wave/z-wave-public-specification/ Z-Wave Public Specification]

Weitere Informationen (seit Veröffentlichung der Z-Wave Spezifikationen am 31.08.2016 geringe Relevanz)
* [https://github.com/yepher/RaZBerry Infos zu Command Classes (ausführlich; insbesondere im Verzeichnis "docs"), RaZBerry und Z-Wave allgemein], englisch
* [http://220.135.186.178/zwave/example/ Übersicht von Command Classes und deren Rückgabewerten mit Unterscheidung der Class-Versionen], englisch
* Code von http://www.openzwave.org (https://github.com/OpenZWave/open-zwave) und http://www.openhab.org (Z-Wave binding: https://github.com/cdjackson/openhab)
* eine Java-API-Beschreibung mit Hinweisen zu Unterschieden von Class-Versionen: http://dz.prosyst.com/pdoc/mBS_SH_SDK_8.1/modules/zwave/api/driver/index.html

== FAQ ==
=== Welche Infos sollten Anfragen im ZWave-Forum enthalten? ===
* Anfragen bitte nur zur aktuellsten FHEM-Version: Befehl <code>update</code> ergibt Ausgabe "nothing to do..."
* detaillierte Beschreibung des Problems
* beteiligte Komponenten (genaue Bezeichnung und evtl. Link auf Hersteller-Dokumentation)
* list des jeweiligen FHEM-Devices (Ausgabe von <code>list <device></code>)
::Bitte vor Aufruf des list-Befehls -wenn vorhanden/möglich- folgende Befehle ausführen und Ergebnis abwarten:
::*<code>get <device> associationAll</code>
::*<code>get <device> configAll</code>
::*<code>get <device> versionClassAll</code>
::*<code>get <device> mcaAll</code>
::*<code>get <device> wakeupInterval</code> (nur bei batteriebetriebenen Geräten)
* passender Ausschnitt aus dem Logfile (siehe Link im FHEM-Menü links) generiert mit den gesetzten Attributen
::*<code>attr <ZWDongle> verbose 5</code> und
::*<code>attr global mseclog 1</code>

=== Welche Schritte sind für die Einbindung von ZWave-Geräten in FHEM mindestens durchzuführen? ===
Voraussetzung: ZWave-Gateway ist erfolgreich eingebunden!
# [[#Hinzufügen eines neuen Z-Wave Geräts / Inklusion|Inklusion]] des Gerätes
# [[#Assoziation|Assoziation]] der Assoziationsgruppe(n) des Gerätes mit dem Gateway
# [[#Konfiguration|Konfiguration]] des Gerätes

=== Warum bleibt der Status (STATE) des neu inkludierten Gerätes dauerhaft auf "associationAdd <associationGroup> <CtrlNodeId>" stehen? ===
FHEM setzt das Reading "state", das den STATE bestimmt, nicht bei allen ZWave-Devices mit vordefinierten Standardwerten. Daher bleibt der bei der Inklusion automatisch abgesetzte "associationAdd"-Befehl unter Umständen im STATE stehen, bis der Anwender den STATE über die Vergabe des Attributes <code>{{Link2CmdRef|Anker=stateFormat|Label=stateFormat}}</code> manuell an seine Bedürfnisse angepasst hat.
(weitergehende Info zum state/STATE/stateFormat: [[DevelopmentState]])

=== Wie können bei mehrkanaligen Aktoren die zusätzlichen Kanäle (>1) angesprochen werden? ===
* Bei der [[#Hinzufügen eines neuen Z-Wave Geräts / Inklusion|Inklusion]] des Gerätes wird das Hauptdevice mit dem Namen <code><nowiki>ZWave_<Geräteklasse laut NIF des Gerätes>_<NodeID></nowiki></code> und die Devices für alle Kanäle (Endpoints) nach dem Namensschema <code><nowiki>ZWave_<Geräteklasse laut NIF des Gerätes>_<NodeID>.<EndpointNr></nowiki></code> automatisch angelegt. Jedes dieser FHEM-Devices spricht regelmäßig einen bestimmten Kanal des Gerätes an; einige Geräte sprechen mit dem Hauptdevice jedoch das gesamte Gerät mit allen Kanälen an (Bedienungsanleitung beachten).
* Manuell werden Devices für zusätzliche Kanäle mit Hilfe der Befehle <code>get <device> mcEndpoints</code> und <code>get <device> mcCapability <chid></code> aus der Class MULTI_CHANNEL ermittelt bzw. einzeln über autocreate angelegt (Details und Beispiel siehe {{Link2CmdRef|Anker=ZWaveget}}). Mit dem Befehl <code>set <device> mcCreateAll</code> werden automatisch alle Kanäle des Gerätes durch autocreate als eigene Devices in FHEM angelegt.

=== Wie kann man die SDK-Version eines Gerätes herausfinden? ===
Mit FHEM alleine kann eine [[#Grobermittlung|Grobermittlung]] der SDK-Version vorgenommen werden, die aber für einige Zwecke bereits ausreichend ist. Soll eine [[#Detailermittlung|Detailermittlung]] der genauen SDK-Version erfolgen, dann müssen die mit FHEM ermittelten Werte anhand externer Quellen übersetzt werden.
==== Grobermittlung ====
Der Befehl <code><nowiki>get <ZWDongle> nodeInfo <dezimale nodeId></nowiki></code> liefert das Reading <code><nowiki>nodeInfo_<dezimale nodeId></nowiki></code> zurück.
Die Angabe im Reading hinter <code>ProtocolVers:</code> lässt grobe Rückschlüsse zu. Mögliche (bekannte) Werte:
* <code>2</code> -> bspw. keine Explorer Frames, keine SUC-Unterstützung (veraltet, keine bekannten Geräte mehr im Handel)
* <code>SDK5.0x+4.2x</code> -> bspw. keine Explorer Frames, teilweise SUC-Unterstützung
* <code>SDK4.5x+6.0x</code> -> bspw. Explorer Frames- und SUC-Unterstützung (Reading-Wert wird auch bei SDK 6.5x = Z-Wave Plus angezeigt)
==== Detailermittlung ====
Durch den Befehl <code><nowiki>get <name> version</nowiki></code> kann man die ZWave-Protokoll-Version von Geräten und Controller abfragen. Mit Unterstützung von Übersetzungstabellen
* http://wiki.micasaverde.com/index.php/ZWave_Protocol_Version
* Suche nach sdkids.xml in einer Suchmaschine
kann aus der Protokoll-Version das genutzte SDK festgestellt werden.

Beispielsweis entspricht das Reading eines Gerätes "Lib 6 '''Prot 2.64''' App 1.6" dem SDK 5.02 Patch 2 oder eines Controller "Z-Wave '''3.41''' STATIC_CONTROLLER" dem SDK 6.02.00.

HINWEIS: Bei der Vergabe der Protokoll-Version und zugehörigem SDK gibt es keine erkennbare Logik: Eine höhere Protokoll-Version steht nicht notwendig für eine höheres SDK.

=== Wie kann eine verschlüsselte Kommunikation unter Nutzung der Command Class SECURITY eingerichtet werden? ===
{{Randnotiz|RNText=FHEM unterstützt derzeit ausschließlich SECURITY 1 und nicht das mit dem SDK 6.7 neu eingeführte SECURITY 2 (S2). Soweit bekannt, sind S2-Geräte rückwärtskompatibel zu SECURITY 1.}}
Die verschlüsselte Kommunikation zwischen Controller und Endgerät setzt eine secure-Inklusion voraus. Bereits mit der Inklusion wird entschieden, ob die Kommunikation von Controller und Endgerät dauerhaft verschlüsselt oder unverschlüsselt erfolgt. Ist ein Gerät bereits normal inkludiert und entscheidet man sich nachträglich für eine verschlüsselte Kommunikation, so ist das nur möglich, indem das Gerät exkludiert und dann wieder secure inkludiert wird.

Ob die Verschlüsselung bei einem Gerät mit Unterstützung der Command Class SECURITY genutzt werden soll, sollte genau überlegt werden. Die Verschlüsselung führt zu einem deutlich größeren Funkverkehr zur Ausführung eines Befehls und teilweise auch zu spürbaren Latenzen.

Vorarbeiten:
* Das Perl-Modul Crypt-Rijndael muss installiert sein.
* Das Attribut <code>networkKey</code> muss mit einem 32-Zeichen langen Hexzahl beim ZWDongle angelegt werden. Dieser Schlüssel sollte nicht veröffentlicht werden und auch zusätzlich separat (bspw. auf Papier) festgehalten werden. Bei Verlust des Attributes und Schlüssels ist eine Kommunikation nur nach erneuter Inklusion möglich.

Ablauf der secure-Inklusion:
* Controller in den Modus zur secure-Inklusion schalten:
: <code>set <ZWDongle> addNode onSec</code> für die Standard-secure-Inklusion
: oder alternativ
: <code>set <ZWDongle> addNode onNwSec</code> für die Nework-Wide-secure-Inklusion
* Gerät gemäß Handbuch in den Modus zur secure-Inklusion bringen (teilweise ist jeweils für secure- und normale Inklusion ein anderes Vorgehen notwendig!)
* Das Gerät sollte jetzt automatisch erkannt und das FHEM-Device durch <code>autocreate</code> angelegt werden. Die secure-inkludierten Geräte haben ein zusätzliches Attribut <code>secure_classes</code> in dem die Command Classes deren Kommunikation verschlüsselt abläuft aufgelistet sind. Nicht in diesem Attribut, aber in <code>classes</code> aufgeführte Command Classes wickeln die Kommunikation weiterhin unverschlüsslt ab.
* Inklusionsmodus des Controllers ausschalten:
: <code>set <ZWDongle> addnode off</code>
* Das Vorgehen in FHEM unterscheidet sich von nun an nicht von normal (unverschlüsselt) inkludierten Geräten. Die Verschlüsselung läuft für den Anwender transparent ab. Darum anschließend [[#Assoziation|Assoziation]] und [[#Konfiguration|Konfiguration]] vornehmen.

=== Wie kann man ohne Exklusion Nodes des Controllers löschen? ===
HINWEIS: Geräte sollten grundsätzlich immer über eine Exklusion aus der Nodelist des Controllers gelöscht werden. Das nachfolgend geschilderte Vorgehen ist nur in Sonderfällen (bspw. Gerätedefekt, gebraucht gekauftes Gateway) anzuwenden.

Nicht mehr zu erreichende/reagierende Nodes (Geräte) können manuell mit dem Befehl <code>removeFailedNode</code> gelöscht werden. Dazu muss sich der betroffene Node auf der FailedNodeList des Controllers befinden. Auf die FailedNodeList kommen netzbetriebene Geräte automatisch, wenn sie vom Controller nicht mehr per Funk erreicht werden. Batteriebetriebene Geräte müssen manuell auf die FailedNodelist gesetzt werden, da der Controller nicht feststellen kann, ob sie nur langfristig "schlafen".

Der Befehl <code>removeFailedNode</code> löscht nur Nodes auf der FailedNodeList, die erst vor Kurzem nicht erreicht werden konnten. Darum muss sowohl das manuelle Verschieben von batteriebetriebenen als auch das Nicht-Erreichen der netzbetriebenen Geräte erst Kurz vor Aufruf des <code>removeFailedNode</code>-Befehls erfolgt sein.

Vorgehensweise für den Node <NodeId>:
# An den betroffenen Node eine Telegramm mit <code><nowiki>set <ZWDongle> sendNIF <NodeId></nowiki></code> verschicken, um ihn auf FailedNodeList zu verschieben bzw. Zeitstempel zu aktualisieren.
# Abfragen, ob der Node auf der FailedNodeList steht: <code><nowiki>get <ZWDongle> isFailedNode <NodeId></nowiki></code>. Wenn der Rückgabewert der Abfrage "yes" ist, steht der Node korrekt auf der FailedNodeList und kann mit <code>removeFailedNode</code> gelöscht werden.
# Befehl zum Löschen des Nodes absetzen: <code><nowiki>set <ZWDongle> removeFailedNode <NodeId></nowiki></code>. Der Befehl testet vor dem Löschen noch einmal, dass der Node nicht erreicht werden kann und entfernt erst dann den Node.
# Prüfen, der Ergebnisse des <code>removeFailedNode</code>-Befehls im Log oder [[Event monitor]]. Die verschiedenen Ergebnisse werden durch die in der {{Link2CmdRef}} dokumentierten Events signalisiert. Tritt das Ergebnis "failedNodeRemoveProcessBusy" mehrfach hintereinander auf, muss das ZWDongle kurz stromlos gemacht werden.
# Prüfen, ob der Node nicht mehr auf der Nodelist des Controllers ist: <code><nowiki>get <ZWDongle> nodeList</nowiki></code>

siehe auch {{Link2Forum|Topic=32823|Message=292626}}

=== Wie ist der einfachste Weg ein (defektes) Gerät durch ein gleiches Ersatzgerät auszutauschen? ===
Tauscht man ein defektes Gerät durch ein gleiches Ersatzgerät und inkludiert das Ersatzgerät per <code>addNode</code>, so erhält das Ersatzgerät eine neue NodeId. Soll das Ersatzgerät die gleiche NodeId wie das alte Gerät erhalten, so muss statt <code>addNode</code> der Befehl <code>replaceFailedNode</code> zur Inklusion des Ersatzgerätes (=gleiches Modell) verwendet werden.

Vorgehensweise für den Node <NodeId>:
# sofern das alte Gerät noch ansprechbar ist, die Konfiguration und Assoziationen abfragen, damit man die Werte im Ersatzgerät einfach wieder setzen kann:
## <code><nowiki>get <device> configAll</nowiki></code>
## <code><nowiki>get <device> associationAll</nowiki></code>
# defektes Gerät aus- und neues einbauen
# Befehl <code><nowiki>set <ZWDongle> sendNIF <NodeId></nowiki></code> absetzen, damit das Dongle die NodeId auf die FailedNodeList setzt.
# Abfragen, ob der Node auf der FailedNodeList steht: <code><nowiki>get <ZWDongle> isFailedNode <NodeId></nowiki></code>. Wenn der Rückgabewert der Abfrage "yes" ist, steht der Node korrekt auf der FailedNodeList und das Ersatzgerät kann mit <code>replaceFailedNode</code> inkludiert werden.
# <code><nowiki>set <zwdongle> replaceFailedNode <NodeId></nowiki></code> für die NodeId des defekten Gerätes aufrufen und das Ersatzgerät in den Inklusionsmodus bringen
# Korrekte Inklusion prüfen und beim alten Aktor ausgelesene Werte beim neuen Aktor wieder setzen.

=== Bei einer Inklusion wird eine durch Exklusion/removeFailedNode frei gewordenen NodeId nicht mehr vergeben. Ist das korrekt? ===
Ja, das ist richtig.

Bei der Inklusion über addNode vergibt der Controller die höchste bisher noch nie verwendete NodeID. Durch Exklusion oder removeFailedNode frei gewordene NodeIDs werden hierbei zunächst nicht erneut vergeben. Diese frei gewordenen NodeIds werden bei Inklusionen in aufsteigender Reihenfolge erst wieder vergeben, nachdem die höchste verfügbare NodeId (232?) inkludiert wurde. Sie sind somit grundsätzlich nicht verloren.

=== Welche Funktion haben die XML-Config-Dateien in FHEM? ===
In den XML-Config-Dateien sind Informationen zu einzelnen ZWave-Geräten enthalten, die der Erleichterung der Gerätenutzung und -einbindung in FHEM dienen. Dies sind unter anderem Erläuterungen zu den Parameternummer/-werten, Assoziationsgruppen und Besonderheiten eines Gerätes. Ob eine zum Zwave-Gerät passende XML-Config Datei existiert, wird im Rahmen der Inklusion oder durch manuellen Aufruf des Befehls <code>get <name> model</code> ermittelt. Wird eine passende XML-Config-Datei gefunden, wird sie automatisch in FHEM eingebunden. Das Reading <code>modelConfig</code> enthält dann den zugehörigen XML-Config-Dateinamen. Stehen keine XML-Config-Informationen bereit, enthält das Reading <code>modelConfig</code> den Wert "unknown". Die Funktionsfähigkeit von FHEM mit ZWave-Geräten ist auch bei fehlender XML-Config-Datei gegeben. Es gibt dadurch keine funktionalen Einschränkungen in FHEM; es entfallen "nur" Erleichterungen und es sind unter Umständen mehr manuelle Schritte bei der Gerätenutzung/-einbindung notwendig.

Erleichterungen bei vorhandener XML-Config für ein ZWave-Gerät:
* Bei der Inklusion:
** Assoziationen mit dem Controller bei von Gruppe 1 abweichenender Assoziationsgruppe werden automatisch gesetzt
** vom NIF nicht gemeldete, aber vom Gerät unterstützte Classes, werden im Attribut <code>classes</code> ergänzt
* Bei der Konfiguration:
** die Parameternummern stehen als configXY-Befehle zur Verfügung und werden mit Hilfetexten -auch zu den Parameterwerten- in der Detailansicht des FHEM-Device erläutert.

HINWEIS: Bitte auch bei vorhandener XML-Config-Datei nach der Inklusion und bei der Konfiguration die Assoziationen und Parameter prüfen. Von den eigenen Vorstellungen abweichende Vorgaben oder gar Fehler in der Config-Datei können nie ausgeschlossen werden. Fehler bitte im Forum ({{Link2Forum|Area=ZWave}}) melden.

=== Wie können fehlende XML-Config-Informationen für mein ZWave-Gerät in FHEM eingebunden werden? ===
Die XML-Config-Informationen von FHEM sind in folgenden Dateien im Ordner fhem/FHEM/lib gespeichert:
* openzwave_manufacturer_specific.xml
* openzwave_deviceconfig.xml.gz
* fhem_zwave_deviceconfig.xml.gz
Die in den Dateien enthaltenen Informationen beruhen in großen Teilen auf Daten von openzwave und übernehmen daher das openzwave-Datenformat, das unter https://github.com/OpenZWave/open-zwave/wiki/Adding-Devices näher beschrieben wird.

Die Datei "openzwave_manufacturer_specific.xml" enthält die eindeutige Kennung des ZWave-Gerätes, die in FHEM nach Aufruf des Befehls <code>get <name> model</code> im Reading <code>modelId</code> des FHEM-ZWave-Devices steht. Weiterhin wird der Klartextname dieses Gerätes, der im Reading <code>model</code> angezeigt werden soll, festgelegt. Zudem wird der Dateiname der eigentlichen XML-Config-Datei für das ZWave-Gerät angegeben, der später informativ im Reading <code>modelConfig</code> steht.

Die Dateien "openzwave_deviceconfig.xml.gz" und "fhem_zwave_deviceconfig.xml.gz" enthalten in komprimierter Form die eigentlichen XML-Config-Dateien für die ZWave-Geräte. FHEM durchsucht beide Dateien nach der passenden XML-Config-Datei. Ist in beiden Dateien eine XML-Config für ein Gerät vorhanden, so werden die XML-Daten aus der "fhem_zwave_deviceconfig.xml.gz" bevorzugt.

Falls ein ZWave-Gerät von FHEM nicht erkannt wird, bitte auf folgenden Seiten nachschauen, ob es schon XML-Config-Dateien gibt, die nur nicht in FHEM eingebunden sind:
# https://github.com/OpenZWave/open-zwave/tree/master/config in manufacturer_specific.xml und dem herstellerspezifischen Unterordner
# https://github.com/jeedom/plugin-openzwave/tree/beta/resources/openzwaved/config in manufacturer_specific.xml und dem herstellerspezifischen Unterordner
# http://www.cd-jackson.com/index.php/zwave/zwave-device-database
Sofern auf den genannten Seiten Daten vorhanden sind, postet eine Aktualisierungsbitte mit genauem Link zur entsprechenden Seite im Forum ({{Link2Forum|Area=ZWave}}).

Gibt es auf keiner der Seiten Infos zu dem Gerät, dann entsprechend https://github.com/OpenZWave/open-zwave/wiki/Adding-Devices die XML-Config-Datei für das Gerät erstellen und unkomprimiert zusammen mit der zu ergänzenden Info für die Datei "openzwave_manufacturer_specific.xml" im Forum ({{Link2Forum|Area=ZWave}}) zur Verfügung stellen.

=== Wie führt man eine Komplett-Sicherung der ZWave-Installation durch? ===
Zu einer Komplett-Sicherung der ZWave-Konfiguration gehören:

1. [[Backup]] der FHEM-Installation
::'''und'''
2. Backup des NVRAM des Controllers

Es genügt nicht nur die FHEM-Installation/Konfiguration zu sichern, da der Controller im NVRAM Daten über HomeID, NodeIDs usw. speichert, die in der FHEM-Installation nicht enthalten sind und auch nicht durch FHEM rekonstruierbar sind.

zu 2.) Backup des NVRAM des Controllers

Einige Controllerhersteller bieten eine eigenständige Software zum Backup/Restore an (siehe Hinweise zu den Controllern unter [[#Autocreate_des_Gateways]]).

FHEM kann mit den ZWDongle-Befehlen <code>backupCreate</code> das NVRAM der Controller sichern und mit <code>backupRestore</code> zurückschreiben. Da das Speicherlayout des NVRAM unter anderem von Controller-Hersteller, SDK und Firmwareversion abhängig sein kann, sollte man die Sicherung und Wiederherstellung des eigenen Controllers (auf eigenes Risiko) testen und sinnvollerweise einen gleichen Ersatzcontroller wie den Controller des Produktivsystem besitzen. Erfolgreiche Sicherung/Wiederherstellung wurde im Forum von den ZWavePlus-Controllern UZB1 (256k), Razberry (256k), Vision ZU 1401-5 EU (128k)und AEOTEC Z-Stick Gen5 (256k) berichtet.
(Weitergehende Infos - neben der {{Link2CmdRef}} - im Forum: {{Link2Forum|Topic=52364}}, {{Link2Forum|Topic=52914}}, {{Link2Forum|Topic=53023}})

=== Wie kann ich zur Fortentwicklung der ZWave-Module beitragen? ===
* Erfolgreichen Einsatz von neuen/bisher nicht gemeldeten ZWave-Geräten im Forum mitteilen
* Codeschnipsel und Ideen im Forum posten
* Fehler und Probleme im Forum melden
* [[How_to_write_a_patch|Patches]] für 00_ZWDongle.pm und 10_ZWave.pm erstellen
* Wiki: Ergänzungen und Korrekturen vornehmen; neue Geräte ins Wiki aufnehmen; Codeschnipsel und Beispiele einpflegen

=== Wie wird ein fehlendes Kernelmodul (Fritzbox) eingebunden? ===
Auf der Fritzbox (und evtl. auch anderen Systemen) muss sichergestellt werden, dass das Kernelmodul für das Gateway geladen wird. Ansonsten scheitert die Einbindung des Gateways in FHEM.

Für den Aeon Labs Z-Stick muss beispielsweise auf der Fritzbox das Kernelmodul <code>cp2101.ko</code> geladen werden.
Diese Datei ist bei einer [[FHEM und FritzBox 7390]] Installation über das Image von [http://www.fhem.de fhem.de] bereits enthalten.
Um den Aeon Labs Z-Stick zu verwenden, muss dieses Kernelmodul vor oder beim Starten des FHEM-Servers geladen sein. Dies erreicht man durch einen Eintrag in der Datei <code>startfhem</code>.

Die entsprechende Zeile kann direkt unterhalb der modprobe Anweisungen eingefügt werden.
insmod $home/lib/cp2101.ko

Nach einem FHEM-Neustart sollte das Gateway (der USB Stick) nun erkannt werden.

=== Wie ist der Aufbau der Z-Wave Messages bzw. wie finde ich bei einem Sendefehler die NodeId des Empfängers heraus? ===

Es könnte natürlich hin und wieder vorkommen, dass man im FHEM-Log folgende Fehler vorfindet:

<code><nowiki>ZWDongle_ProcessSendStack: no ACK, resending message 010a00130603320110259277</nowiki></code>

In diesem Fall gab es aus irgendeinem Grund einmalig das Problem, dass der Empfang einer Nachricht vom Empfänger nicht bestätigt wurde.
Will man dem auf die Spur kommen, so wäre es natürlich von Vorteil, die NodeId des Empfängers herauszufinden. Also muss man sich die Message näher anschauen:

<code><nowiki>010a00130603320110259277</nowiki></code>
* 01: data to controller
* 0a: length of msg
* 00: ?
* 13: ZW_SEND_DATA
* 06: NodeId

* 03: length of msg
* 32: Command Class 32 (METER, siehe %zwave_class in 10_ZWave.pm)
* 01: METER get scale command
* 10: scale parameter

* 25: send flags, explorer frames on
* 92: callbackId (um ACK zu identifizieren)
* 77: checkSum

In diesem Fall hat der Z-Wave-Controller 01 eine Nachricht an die NodeId 06 geschickt, welche vom Node nicht bestätigt wurde.

[[Kategorie:HOWTOS]]
[[Kategorie:Z-Wave Components|!]]
[[Kategorie:868MHz]]

HM-CFG-USB USB Konfigurations-Adapter

2019-12-17T19:39:23Z

AlanBlack: /* Einrichtung unter Linux */

{{Infobox Hardware
|Bild=HM-CFG-USB-2.jpg
|Bildbeschreibung=HomeMatic USB Konfigurationsadapter (Version 2)
|HWProtocol=HomeMatic
|HWType=Interface/Gateway
|HWCategory=HomeMatic
|HWComm=868,3 MHz
|HWChannels=
|HWVoltage=5 V
|HWPowerConsumption=
|HWPoweredBy=USB-Bus
|HWSize=V1: 40 x 90 x 25 mm V2: 28 x 84 x 11,5 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]

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

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

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

{{Randnotiz|RNTyp=Info|RNText='''Skript zur Kompletteinrichtung unter Linux'''
Dieser {{Link2Forum|Topic=13071|Message=190887|LinkText=Bericht}} im Forum stellt ein Script vor, das ''hmland'' herunterlädt, übersetzt (kompiliert), installiert sowie ein init-Script anlegt, so dass fast keine manuellen Eingriffe mehr notwendig sind.}}
Die nachfolgenden Angaben in diesem Abschnitt sind rein zu Informationszwecken (noch) enthalten:

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

Danach kann der Dienst (zu Testzwecken sind Debugging-Ausgaben mit <code>-D</code> aktiviert) gestartet werden:
:<code> /opt/hmcfgusb/hmland -p 1234 -D</code>

==== Start als Daemon ====
Um ''hmland'' automatisch als Daemon bei '''init.d Systemen''' zu starten, kann ein init-Script genutzt werden. Die Quellen von ''hmland'' enthalten ein solches Script im <code>debian/</code> Unterverzeichnis:

<syntaxhighlight lang="bash">
cp /opt/hmcfgusb/debian/hmland.init /etc/init.d/hmland
cp /opt/hmcfgusb/debian/hmland.default /etc/default/hmland
</syntaxhighlight>

Einstellungen, beispielsweise der Port, auf dem ''hmland'' hört, können (und sollten) in der Datei <code>/etc/default/hmland</code> vorgenommen werden. Wichtig: Wenn diese Anleitung befolgt wurde, muss in der Datei <code>/etc/init.d/hmland</code> die folgende Zeile wie folgt angepasst werden (<code>/hm</code> aus dem Pfad entfernen), damit der automatische Start des Daemon klappt:
<syntaxhighlight lang="bash">
DAEMON=/opt/hmcfgusb/$NAME # Introduce the server's location here
</syntaxhighlight>

Die kopierte Datei mit <code>chmod 755 /etc/init.d/hmland</code> ausführbar machen, anschließend kann ''hmland'' mit folgendem Befehl gestartet werden:
:<code>/etc/init.d/hmland start</code>

Bei Distributionen, die '''systemd''' einsetzen (z.B. Debian Stretch) kann folgende Konfigurationsdatei verwendet werden:
<syntaxhighlight lang="bash">
[Unit]
Description=Homematic LAN Adapter service
After=network.target

[Service]
ExecStart=/opt/hmcfgusb/hmland -p 1234

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Dabei muss dann natürlich der Port (1234) an die eigene Konfiguration angepasst werden und auch der Pfad wo sich der <Code> hmland</code> befindet, wenn man sich an oben stehendem Beispiel orientiert wäre das dann <Code>/opt/hmcfgusb/</code>
Diese Datei muss dann als <Code>hmland.service</code> unter <syntaxhighlight lang="bash">/etc/systemd/system</syntaxhighlight> abgelegt werden.
Nun muss einmalig der Befehl
<syntaxhighlight lang="bash">systemctl daemon-reload</syntaxhighlight> ausgeführt werden damit die neuen Dateien eingelesen werden.
Mit dem Befehl <syntaxhighlight lang="bash">systemctl enable hmland</syntaxhighlight> wird dafür gesorgt, dass bei einem Systemstart hmland automatisch gestartet wird
Mit <syntaxhighlight lang="bash">systemctl status hmland </syntaxhighlight> kann dann noch geprüft werden ob der Service läuft

Bei Distributionen, die '''Upstart''' einsetzen (z.B. xbian) kann folgende Konfigurationsdatei verwendet werden:
<syntaxhighlight lang="bash">
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

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

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

==== Start über FHEM Startskript ====
Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

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

Dann geht es weiter:
:<code>sudo cp hmcfgusb.rules /etc/udev/rules.d/ </code>

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

Damit editiert man das FHEM Startskript:
:<code>sudo nano /etc/init.d/fhem </code>

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)
<syntaxhighlight lang="bash">
'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

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

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

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

=== Einrichtung auf Synology DiskStations ===
Packages für DSM5.2 finden sich hier:
https://github.com/mkunzmann/spksrc/releases/tag/0.101-3

Welches Package für welche DS kann man hier sehen:
https://github.com/SynoCommunity/spksrc/wiki/Architecture-per-Synology-model

Einfach das passende Package installieren und dann kann man den hmland über den Synology Package-Manager starten und stoppen. Während der Installation kann man den Port für hmland festlegen. Bitte einen Port > 1024 wählen, da der hmland nicht als root läuft. Außerdem kann ein Logfile angegeben werden. Hier am besten eine Datei auf einem USB Stick angeben die für jedermann schreibbar sein muss. Damit sollten die Platten nach wie vor in den Standby gehen.

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

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

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

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

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:
<syntaxhighlight lang="text">
Datum Zeit: Client 127.0.0.1 connected!
Can't claim interface: Access denied (insufficient permissions)
Can't find/open hmcfgusb!
Datum Zeit: Connection to 127.0.0.1 closed!
</syntaxhighlight>

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

<syntaxhighlight lang="text">
idProduct: 49167
idVendor: 6943
</syntaxhighlight>

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:
<syntaxhighlight lang="bash">
chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext
</syntaxhighlight>

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

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

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

=== Definition(en) in der FHEM-Konfiguration ===
In der FHEM [[Konfiguration]] muss noch, sofern/sobald der ''hmland'' läuft, das Device eingerichtet werden mit den folgenden Anweisungen:
:<code>define '''hmusb''' HMLAN 127.0.0.1:1234 </code>
wobei '''hmusb''' der frei wählbare Devicename ist. Anschließend sollte bzw. muss noch mit
:<code>attr '''hmusb''' hmId <'''hmId'''> </code>
eine '''hmId''' zugeordnet werden (dabei bitte auch die Hinweise und Regeln beachten, die im Zusammenhang mit der [[Virtueller Controller VCCU|VCCU]] beschrieben sind!

== Firmware Update ==
Der Firmware Update (unter Linux) ist ebenfalls auf der [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland-Internetseite] beschrieben. Auch die letzte bekannte Firmware-Version (0.967) steht dort zur Verfügung.

== Bekannte Probleme ==
=== Verbindung zu neueren hmland-Versionen nicht stabil ===
Seit Version 0.100 meldet sich die HMLAN-Emulationssoftware als USB-Interface bei FHEM. Ältere FHEM-Versionen (vor dem 19.6.2015) brechen deshalb die Verbindung ab, da sie nur ein LAN-Interface erwarten.

Lösung: Kommandozeilenparameter <code>-I</code> dem hmland-Aufruf hinzufügen, dann meldet sich dieser wieder als LAN-Interface.

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

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

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

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
{{Randnotiz|RNTyp=r|RNText=Stand März 2016 ist allem Anschein nach kein HM-CFG-USB mehr im ELV Programm enthalten!}}
* HM-CFG-USB-2: die aktuelle Version; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

== Links ==
* Bedienungsanleitung [http://www.eq-3.de/Downloads/eq3/pdf_produkte/HM-CFG-USB-2_-UM-eQ-3-150129-web.pdf HM-CFG-USB-2, PDF]
* FHEM-Forums {{Link2Forum|Topic=13071}}: HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in FHEM nutzen
* [http://www.eq-3.de/produkt-detail-zentralen-und-gateways/items/homematic-funk-konfigurationsadapter-usb.html eQ-3 Produktseite] zum "HomeMatic Funk-Konfigurationsadapter USB"; Downloads, technische Daten, etc.

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

ZigBee

2019-07-11T21:27:50Z

AlanBlack: Nur etwas Rechtschreibung und Grammatik

== Allgemeines ==
[[ZigBee]] ist eine Spezifikation für drahtlose Netzwerke mit geringem Datenaufkommen, wie beispielsweise Hausautomation, Sensornetzwerke oder Lichttechnik. Der Schwerpunkt von ZigBee liegt in kurzreichweitigen Netzwerken (bis 100 Meter). Es sind via vermaschtem Netz (auch Meshnetzwerk) aber auch Reichweiten von mehreren Kilometern möglich.

Die Spezifikation ist eine Entwicklung der ZigBee-Allianz, die Ende 2002 gegründet wurde. Die Allianz ist ein Zusammenschluss von derzeit mehr als 230 Unternehmen, welche die weltweite Entwicklung dieser Technologie vorantreiben.

== Gerätetypen ==
=== Endgerät (ZigBee End Device, ZED) ===
Geräte, wie zum Beispiel Steuerungs- oder Sensormodule, werden meist mit Batterien betrieben. Diese können als ZigBee-Endgeräte implementiert werden und benötigen nur einen Teil der Funktionen der ZigBee-Spezifikation. Sie nehmen nicht am Routing im Netzwerk teil und können in einen Schlafmodus gehen. Sie melden sich an einem Router ihrer Wahl an und treten so dem ZigBee-Netzwerk bei. Sie können ausschließlich mit dem Router kommunizieren, über den sie dem Netzwerk beigetreten sind. Werden Daten an ein solches Endgerät geschickt, welches sich im Schlafmodus befindet, speichert der Router diese Pakete, bis das Endgerät sie abruft.

=== Router (ZigBee-Router, ZR) ===
ZigBee-Router nehmen am Routing der Pakete durch das Netzwerk teil. Sie benötigen einen größeren Funktionsumfang und damit auch etwas mehr Hardwareressourcen. ZigBee-Router treten einem Netzwerk bei, indem sie sich an einem im Netzwerk befindlichen Router anmelden. Das Routing im Netzwerk erfolgt entweder entlang eines sich so bildenden Baumes (Stackprofil ZigBee) oder durch dynamisches Routing als Meshnetzwerk.

'''Ein ZigBee Router hat so ungefähr die Funktion wie ein WLAN Repeater...'''

=== Koordinator (ZigBee coordinator, ZC) ===
Ein ZigBee-Koordinator startet das Netzwerk mit festgelegten Parametern. Nach dem Start übernimmt er dieselben Aufgaben wie ein ZigBee-Router.
Es kann nur einen Koordinator in einem ZigBee Netz geben.
'''In FHEM wird ein solches Gerät Gateway genannt.'''

== Mischen von Komponenten unterschiedlicher Hersteller ==
Prinzipiell ist es möglich, die Komponenten unterschiedlicher Hersteller zu mischen. Dies kann interessant sein, da jeder Hersteller andere Schwerpunkte in der Modellpalette hat, nicht jeder Hersteller alle Leuchtmittel-Typen vertreibt und sich auch die Eigenschaften und Preise für vergleichbare Leuchtmittel unterscheiden. Auch der in FHEM verfügbare Funktionsumfang unterscheidet sich je nach Bridge.

Leuchtmittel sind in der Regel am unproblematischsten. Taster auch wenn sie direkt die Leuchtmittel steuern. Über die Bridge sind in der Regel aber oft nur die Taster des jeweiligen Herstellers direkt abfragbar bzw. in FHEM einzubinden. Dies gilt auch für Bewegungsmelder und sonstige Sensoren.

Im einzelnen sollte man sich also vor dem Kauf informieren, welche Komponenten tatsächlich problemlos zusammen arbeiten.

Beim Vergleich der Kosten muss aber die jeweilige Bridge des Herstellers zusätzlich mit berücksichtigt werden (siehe [[#Firmware updates]]).

=== Firmware updates ===
Es ist sinnvoll oder sogar zwingend nötig, neue Leuchtmittel zumindest einmal bei der Inbetriebnahme auf den aktuellen Firmwarestand zu bringen. Gerade wenn Komponenten herstellerübergreifend verwendet werden sollen, ist sonst oft mit Einschränkungen oder sogar Problemen zu rechnen.

Hierzu ist aktuell in der Regel<ref>Der Diskussionsstand 11/2018 hierzu ist diesem {{Link2Forum|Topic=93836|LinkText=Forenthread}} zu entnehmen.</ref> die zugehörige original Bridge (und oft auch die App) des jeweiligen Herstellers nötig, d.h., auch wenn man z.B. Osram LIGHTIFY oder IKEA Trådfri Leuchtmittel an einer Hue Bridge betreiben möchte, braucht man zumindest am Anfang einmal auch noch die Osram und IKEA Bridge und muss das Leuchtmittel jeweils an- und ab- und wieder anlernen.

Aktualisierungen der Hue Bridge und Hue Leuchtmittel lassen sich auch aus FHEM heraus anstoßen.

== Einbindung in FHEM ==
Prinzipiell lässt sich hier vorwegschicken, dass die FHEM Hue-Module (ob mit einer Philips Hue Bridge oder mit der Dresden Elektronik Software) den größten Funktionsumfang ermöglichen.

=== Hersteller-Bridges ===
Wir benötigen also zur Einbindung ein Gateway. Manche Nutzer haben sich gleich ein Starterkit wie Philips Hue oder IKEA Trådfri gekauft.
Diese Lösungen haben den Vorteil, dass Alexa-Integration etc. sowie die Smartphone-App gleich mitkommen, und das Einbinden der Endgeräte, aber vor allem aber Softwareupdates i.d.R. herstellerproprietär gelöst wurden.

Der Nachteil ist, dass die Lösungen bis hin zum gut dokumentierten Hue-System mit API in anderer Hinsicht geschlossene Systeme sind. So ist z.B. über die Hue-Bridge die Abfrage von Hue-Bewegungssensoren oder -Tastern nur per Polling durch FHEM möglich - es gibt keinen Event-Mechanismus, der FHEM notifizieren könnte (siehe [[#Freie Lösungen]]). Alle 5 Minuten die Bridge fragen (= Pollen), ob der Bewegungsmelder jemanden gesehen hat und ggf. das Licht ausschalten, ist also per Polling machbar, auf einen ZigBee-Tasterdruck oder Bewegung hin via FHEM die WiFi-Steckdose schalten hingegen eher zu verzögert.

Außerdem ist unser Ziel ja, die Steckerleiste der Steuergeräte kurz zu halten.

Auch die native HomeKit- (Siri) oder Alexa-Integration ist mit kleinen oder größeren Problemen und Einschränkungen behaftet, diese sind unter anderem:
* nur Steuerung der herstellereigenen Leuchtmittel
* Verzögerung der Statusaktualisierung in FHEM, wenn an FHEM vorbei geschaltet wird
* Eventuell 'Cloud-Zwang' des jeweiligen Herstellers
* Eventuell erhöhter Ressourcenverbrauch auf der jeweiligen Bridge durch zusätzliche Verbindungen
Diese Nachteile gibt es bei einer Integration über FHEM nicht.

==== Hue Bridge von Philips ====
Siehe [[Hue]]. Eine gute Dokumentation kompatibler Geräte findet sich [https://iconnecthue.com/supported-devices/ hier]. Hue ist wohl die meist verbreitete Bridge und hat auch ein dokumentiertes REST-API. Jedoch ist die Anzahl der Endgeräte (offiziell: 50) und Regeln (ca. 200) stärker als bei anderen Lösungen begrenzt und Events können nicht zu FHEM weitergeleitet werden.

==== Trådfri von IKEA ====
Siehe {{Link2Forum|Topic=70653}} und [[TRÅDFRI]].

==== Lightify von Osram ====
Siehe {{Link2Forum|Topic=28339}}. Auch hier geht nur Polling von Events, ebenfalls max. 50 Geräte, und der Nutzerkreis ist kleiner.

=== Andere Lösungen ===
Die Alternative sind Lösungen, die spezielle Hardware erfordern, wie den RaspBee (Aufsteckmodul für Raspberry) oder Conbee (USB-Gateway) von Dresden Elektronik oder manche Module mit Chips des Herstellers [https://github.com/Koenkk/zigbee2mqtt/wiki/Supported-sniffer-devices Texas Instruments], und die zusätzlich nötige Software auf dem Raspberry etc. mitlaufen lassen. Eine reine Hardware-Lösung ohne Zusatzsoftware, in der FHEM die Software-Funktionen des Gateway vollständig abbildet, gibt es nicht - FHEM kommuniziert lediglich mit einer Software, die ebenfalls auf dem - ggf. gleichen - Computer mitläuft.

==== Dresden Elektronik ====
Das Dresden Elektronik System ermöglicht aktuell als einziges der 'fertigen' Systeme auch das aktive Senden von Events und somit eine 'fast Echtzeit' Reaktion auf Taster, Bewegungsmelder oder Ähnliches. Realisiert ist das über eine Push Erweiterung im ansonsten weitgehend Hue kompatiblen API. Auch die Integration von Tastern und anderen Sensoren unterschiedlichster Hersteller ist mit der DE Software gut möglich. Die Anbindung an FHEM (inklusive Push) erfolgt über die HUE-Module.

==== Direkt per MQTT ====
Siehe [[MQTT2-Module - Praxisbeispiele#zigbee2mqtt]]

==== Das Modul von Neumann ====
Siehe diesen Forenbeitrag: {{Link2Forum|Topic=84790}}

== Funkübertragung ==

=== Reichweite erhöhen ===
* Eine brauchbare WLAN Antenne (2,4GHz) an einen CC2531 "Stick" oder ein anderes Gateway anbauen (eher für Experten)
* ein CC2530 als Gateway oder in der Mitte als Repeater (Achtung verschiedene Firmwares erforderlich. Gute Antenne muss meist gesondert gekauft werden, anstatt der beigelegten)
* ZigBee ist ein Mesh-Netz, daher irgendwo auf dem Weg ein ZigBee-Gerät verbauen, welches immer eingeschaltet ist (z.B. ZigBee Funksteckdose)
{{Hinweis|Da derselbe Frequenzbereich wie WLAN genutzt wird, kann es auch zu Interferenzen mit diesem kommen. In diesen Fall kann es sinnvoll sein, für eine der beiden Techniken einen anderen Kanal zu wählen.}}

== Sicherheit ==
=== Sicherheitsrelevante Geräte ===
Welche Geräte sicherheitsrelevant sind, ist eine sehr schwierige Frage. Beim Türschloss ist das klar. Wenn ein Temperatursensor dafür sorgt, dass ein Raum nicht mehr beheizt und daraufhin wegen geplatztem Heizkörper die Wohnung geflutet wird, so ist dies schon etwas schwerer zu erkennen...

=== Bekannte Sicherheitslücken ===
==== Insecure Rejoin ====
Insecure Rejoin ist eine der Schwachstellen im Protokoll. ZigBee 3.0 wurde 2015 freigegeben und soll das Problem lösen. Allerdings ist ZigBee 3.0 (Stand Ende 2018) noch immer recht wenig verbreitet.

Ablauf des Insecure Rejoin aus Angreifersicht:
* einen Node aus dem Netz werfen, um nicht auf die Aktivierung neuer Geräte warten zu müssen
* der Node versucht erneut Mitglied im Netz zu werden. Schlüsselaustausch erfolgt mittels dem Key "ZigBeeAlliance09"
* Mitsniffen des neuen Schlüssels

Quelle: Link zu Golem.de über die Forschung von Tobias Zillner

==== DDOS ====
* manipulierte Counter (können sogar manche HW zerstören)
* Jamming (einfach die Frequenz belegen mit beliebigem Signal)
* Flutung mit ZigBee Messages

Quelle: https://research.kudelskisecurity.com/2017/11/21/zigbee-security-basics-part-3/

== Links ==
* https://www.golem.de/news/smart-home-sicherheitsluecken-im-zigbee-protokoll-demonstriert-1511-117657-2.html

[[Kategorie:ZigBee|!]]

Reading

2018-09-18T15:04:09Z

AlanBlack: Die Seite wurde neu angelegt: „{{Baustelle}} Readings sind i.d.R. modulabhängig und geben zusammen mit Attributen und Internals den aktuellen Zustand des dahinter liegenden phy…“

{{Baustelle}}
Readings sind i.d.R. modulabhängig und geben zusammen mit [[Attribut|Attributen]] und Internals den aktuellen Zustand des dahinter liegenden physischen oder virtuellen [[Gerät|Gerats]] wieder.

== Allgemeines ==
Readings geben in FHEM wieder, welche Einstellungen oder Messwerte (allg. Gerätedaten) am jeweiligen Gerät vorliegen. So hat ein Temperatursensor ein Reading für die Temperatur, ein Lichtsensor hat ein Reading für die Helligkeit und ein Schalter ein Reading für An/Aus. Je nach Gerätefamilie (zWave, FS20, Homematic,...) werden Readings in FHEM und Gerätedaten möglichst synchron gehalten. Zu Ausnahmen später mehr.

Readings werden mit dem <code>define</code>-Befehl des jeweiligen [[Gerät|Devices]] oder bei den ersten Übertragungen mit jenem angelegt und mit Werten gefüllt.

Beim Herunterfahren von FHEM werden die bekannten Werte aller Readings entweder in das statefile oder die Konfigurationsdatenbank geschrieben. So können sie beim Start von FHEM wieder ausgelesen und in die entsprechenden Readings der Geräte geschrieben werden. Damit entsteht ein wahrscheinlich halbwegs aktueller Zustand aller Geräte, ohne dass beim Start von FHEM erst alle Geräte abgefragt werden müssen, was aber bei den meisten per Funk angesprochenen Gerätefamilien wegen der 1%-Regel mitunter sehr lange dauern würde.

Alle [[Gerät|Geräte]] haben Readings, deren Werte entweder vom Modulcode oder mit dem Befehl <code>setreading</code> verändert werden können. Werden dabei moduleigene Readings gesetzt, können mitunter unerwünschte Nebenwirkungen auftreten. Es können aber auch mit diesem Befehl neue Readings erzeugt werden, die bspw. zum Zwischenspeichern dienen sollen. So können Readings auch mit dem Kommando <code>deletereading</code> entfernt werden. Wobei hier durch das Löschen von modulinternen Readings sehr sicher Fehler in der Ausführung von FHEM auftreten werden. Dazu können Readings über userreadings {{Link2CmdRef}} erstellt werden.

== ReadingsGroup ==
[[ReadingsGroup]] stellt eine Möglichkeit dar, neben Readings auch [[Attribut|Attribute] strukturiert darzustellen.
Mit Hilfe dieses [[Modul|Moduls]] können auch den End-Anwendern auf einfache Weise vielfältige Einstellmöglichkeiten zur Verfügung gestellt werden.

== ToDo ==
Zusammenhänge mit event-on.+, DOIF(?), devState.+,...

Artikel "Internal"

Akualität und Ausnahmen

<references />
[[Kategorie:FHEM]]
[[Kategorie:FHEM-Verwendung]]
[[Kategorie:Glossary]]

HM-LC-SW1-FM Schaltaktor 1-fach UP

2018-09-13T17:55:47Z

AlanBlack: Bild eing., "Technische Daten" in Infobox versch., Hinweis Netzspannung eing.

Homematic Funk-Schaltaktor 1-fach (Unterputz)
{{Infobox Hardware
|Bild=HM-LC-SW1-FM.jpg
|Bildbeschreibung=HomeMatic Funk-Schaltaktor
|HWProtocol=HomeMatic
|HWType=Aktor
|HWCategory=HomeMatic
|HWComm=868MHz
|HWChannels=1
|HWVoltage=230V AC
|HWPowerConsumption=0,5W
|HWPoweredBy=Netzspannung
|HWSize=53x53x30mm
|HWDeviceFHEM=[[CUL_HM]]
|HWManufacturer=ELV / eQ-3
}}
== Features ==

Schalten eines angeschlossenen Verbrauchers mittels [[CUL]]/[[CUN]]/[[HMLAN Konfigurator]] und über einen mechanischen spannungsfesten Taster.

== Hinweise zur Hardware-Installation ==

'''WICHTIG''': die Installation von Komponenten mit Netzspannung darf nur von Fachpersonal durchgeführt werden.

Will man die Funk-Schaltaktoren auch manuell betreiben, d.h. man upgradet eine vorhandene Elektroinstallation, so sind Taster notwendig. Schalter können notfalls mittels einer zusätzlichen Feder zu Taster umgebaut werden, Tastschalter sind leider nicht geeignet. Schalter und Tastschalter führen dazu, dass der Aktor nach Betätigung des Schalters in den Anlernmodus versetzt wird und auch in diesem verbleibt.

Je nach vorhandenen Schalterdosen empfiehlt es sich bestehende Schalterdosen nach hinten auszuweiten, d.h. die Abdeckung nach hinten heraus zu brechen, da die Aktoren und Kabel nicht gerade sparsam mit dem Platz umgehen. Alternativ könnte man den Aktor auch in eine zusätzliche Schalterdosen unterbringen und diese mit einem Federdeckel abschließen. Dies hat den Vorteil, dass man auch durch relativ dicke Tapete die LED und somit den Zustand des Aktors ablesen kann.

Der Aktor kann auch gänzlich ohne Taster, also nur per ''set''-Befehlen durch FHEM oder per gepeerten Geräten gesteuert werden, jedoch muss zumindest für das Anlernen zeitweise ein Taster angeschlossen werden.

== Hinweise zum Betrieb mit FHEM ==

Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Hierfür wird ein am Aktor temporär angeschlossener spannungsfester Taster zwingend benötigt.

# Sicherstellen, dass ''autocreate'' aktiv ist
# Am CUL/HMLAN o.ä. <code>set HMLAN hmPairForSec 60</code>
# Binnen 60 Sekunden Aktor in Anlernmodus bringen (Taster 4s festhalten bis LED blinkt) -> Device wird in fhem angelegt, z.B. als CUL_HM_HM_LC_SW1_FM_2BAD45
# <code>rename <Aktor> <AktorNameNeu></code> -> richtigen Namen zuordnen

=== FHEM Config-Auszug ===

Ein exemplarischer Auszug aus der fhem.cfg:

<pre>
define LichtTerasse CUL_HM 17AEA6
attr LichtTerasse devInfo 010100
attr LichtTerasse firmware 1.9
attr LichtTerasse hmClass receiver
attr LichtTerasse model HM-LC-SW1-FM
attr LichtTerasse room Terasse
attr LichtTerasse serialNr IEQ00xxxx
attr LichtTerasse subType switch
</pre>

=== Mögliche Schaltoperationen ===

Der Aktor versteht folgende Aktionen:
<pre>
set <name> on -> Schaltet den Aktor ein
set <name> off -> Schaltet den Aktor aus
set <name> toggle -> Ändert den Zustand des Aktors, d.h. ein eingeschalteter Aktor wird ausgeschaltet
</pre>

=== Log-Auszug ===

In FHEM ist nach dem Schalten des HM-LC-SW1-FM folgendes Log zu sehen:
<pre>
2012.02.05 16:51:44 2: CUL_HM set LichtTerasse on
2012.02.05 16:52:14 2: CUL_HM set LichtTerasse off
2012.02.05 16:52:15 2: CUL_HM set LichtTerasse toggle
</pre>

== Nützliches Zubehör ==

Wer den Schaltaktor im Sicherungskasten selbst einbauen möchte, z.B. um einen Stromstossschalter zu ersetzen, dem kann folgendes Zubehör empfohlen werden: Hutschienengehäuse CNMB-4V-Kit, Bestellnr. 532659 bei conrad. Das ist zwar sicher auch nicht VdE-konform, aber besser wie ohne. Alternativ kann auch der [[HM-LC-Sw1-DR 1fach Schaltaktor Hutschiene]] zur direkten Montage auf Hutschienen eingesetzt werde.

== Probleme ==

Um den HM-LC-SW1-FM in den Anlernmodus zu versetzen, soll man lt. Anleitung den (temporär) angeschlossenen Taster für 4 Sekunden gedrückt halten. Falls dies bei Ihnen nicht funktioniert, so versuchen Sie den Taster einfach mal ca. 7 bis 8 Sekunden gedrückt zu halten (bis die LED des SW1-FM kurz aufleuchtet).

Wenn das Pairing nicht komplett durchläuft (Device zeigt als Status MissingACK und kann nicht von FHEM aus gesteuert werden), dann hilft ggf. ein weiteres Pairing über hmPairSerial.

== Links ==

Ein Integrationsbeispiel ist in [[Jalousie und Beleuchtung in mehreren Räumen]] zu finden.

[http://files.elv.de/Assets/Produkte/7/767/76793/Downloads/76793_HM_LC_Sw1_FM_um.pdf Anleitung (PDF)]

[[Kategorie:HomeMatic Components]]
[[Kategorie:Schalter (Empfänger)]]

Datei:HM-LC-SW1-FM.jpg

2018-09-13T17:48:06Z

AlanBlack: HM-LC-SW1-FM Homematic 1-fach Schaltaktor unterputz

== Beschreibung ==
HM-LC-SW1-FM Homematic 1-fach Schaltaktor unterputz

HM-Sen-MDIR-SM Außen-Bewegungsmelder

2018-09-13T17:41:00Z

AlanBlack: Bild eingefügt, regList akt., Hinw. Bausatz

{{Infobox Hardware
|Bild=HM-Sen-MDIR-SM.jpg
|Bildbeschreibung=HM-Sen-MDIR-SM
|HWProtocol=[[HomeMatic]]
|HWType=[[HomeMatic Type motionDetector|motionDetector]]
|HWCategory=HomeMatic
|HWComm=868,3 MHz
|HWChannels=1
|HWVoltage=3,0V
|HWPowerConsumption=1Jahr
|HWPoweredBy=Batterie, 2x LR06 (Micro)
|HWSize=64x58x35mm
|HWDeviceFHEM=[[CUL_HM]]
|HWManufacturer=eQ-3
}}

[[HM-Sen-MDIR-SM Außen-Bewegungsmelder|HM-Sen-MDIR-SM]] ist ein batteriebetriebener PIR-Bewegungsmelder, der in einem wetterfesten Gehäuse (IP65) eingebaut ist.

== Aufbau ==
Das Gerät ist sowohl nutzungsbereit als auch als Bausatz verfügbar. Letzterer muss selbst gelötet werden, wobei etwas mehr Erfahrung erforderlich ist als bspw. beim HM-Sec-SCo. Die Arbeitszeit sollte für erfahrende Personen unter 30 Minuten liegen.

== Hinweise zum Betrieb mit FHEM ==
Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Der Sensor muss hierfür geöffnet und die Anlerntaste betätigt werden. Hierbei gibt es zwei Konfigurationsmöglichkeiten:
* Anlerntaste kurz betätigen, um den Bewegungsmelder ohne Helligkeitsschwelle anzulernen
* Anlerntaste für ca. 4s betätigen, um den Bewegungsmelder bei einer festen Helligkeitsschwelle (10 Lux) anzulernen (vgl. Handbuch)

=== FHEM Config-Auszug ===
Ein exemplarischer Auszug aus der fhem.cfg:

<nowiki>define Aussen_Bewegungssensor CUL_HM 18xxx
attr Aussen_Bewegungssensor devInfo 010100
attr Aussen_Bewegungssensor firmware 1.2
attr Aussen_Bewegungssensor hmClass sender
attr Aussen_Bewegungssensor model HM-SEN-MDIR-SM
attr Aussen_Bewegungssensor room Outdoor
attr Aussen_Bewegungssensor serialNr IEQ0xxxxx
attr Aussen_Bewegungssensor subType motionDetector</nowiki>

=== Konfiguration über Register ===
==== Anzeige aller dekodierten Register ====
Mit dem Befehl
:<code>get <name> regList</code>
werden alle möglichen 'dekodierten' Register angezeigt. Für den HM-Sen-MDIR-SM sind dies alle, die Liste sollte also komplett sein. Hier findet man sowohl den Wertebereich als auch eine kurze Beschreibung.

<pre>
list: register | range | peer | description
0: pairCentral | 0 to 16777215 | | pairing to central
1: brightFilter | 0 to 7 | | 7: filter fast changes to 0: no filter of light changes
1: captInInterval | literal | | capture motion in interval, send result in next trigger options:on,off
1: evtFltrNum | 1 to 15 | | sensitivity - read each n-th puls
1: evtFltrPeriod | 0.5 to 7.5s | | event filter period
1: ledOnTime | 0 to 1.275s | | LED ontime
1: minInterval | literal | | interval in sec options:240,60,120,30,15
1: sign | literal | | signature (AES) options:on,off
4: peerNeedsBurst | literal | required | peer expects burst options:on,off
</pre>

==== Auslesen der Register aus dem Device ====
Mit dem Befehl
:<code>set <name> getConfig</code>
werden die Register aus dem Device ausgelesen. Die wichtigsten Register werden direkt in den Readings angezeigt. Bei Anwendung auf ein "device" werden auch die Kanäle ausgelesen, bei Kanal nur der Kanal.
Die Anzeige der Register in den Readings ist R-<regname>. Der "R-" Präfix dient zur Sortierung und auch zur einfacheren Identifizierung, dass es ein Register ist.

==== Editieren von Registerwerten ====
Die Inhalte von Registern können mit dem Befehl
:<code>set <name> regSet <regname> <value></code>
modifiziert werden.

== Mögliche Zustände ==
=== Log-Auszug ===
In FHEM sind folgende Zustände des HM-Sen-MDIR-SM im Log zu sehen:

<nowiki>2012-05-30_16:17:26 Aussen_Bewegungssensor motion
2012-05-30_16:17:26 Aussen_Bewegungssensor motion: on (to broadcast)
2012-05-30_16:18:34 Aussen_Bewegungssensor brightness: 43
2012-05-30_16:18:34 Aussen_Bewegungssensor alive
2012-05-30_16:18:34 Aussen_Bewegungssensor cover: closed</nowiki>

== Bekannte Probleme ==
Einem ELV Forenbeitrag mit dem Titel "[http://www.elv.de/topic/problem-mit-helligkeitsmessung.html Problem mit Helligkeitsmessung]" zufolge sendet HM-Sen-MDIR-SM den Helligkeitswert nur bei Erkennung einer Bewegung, womit er - anders als z.B. [[HM-Sen-MDIR-O Funk-IR-Bewegungsmelder außen|HM-Sen-MDIR-O]] - nicht als permanenter Helligkeitssensor eingesetzt werden kann.

== Links ==
* Montage- und Bedienungsanleitung ({{DocLink|elv|/service/manuals/84579_HM_Sen_MDIR_SM_um.pdf}})

[[Kategorie:HomeMatic Components]]
[[Kategorie:Bewegungs- und Anwesenheitsmelder]]
[[Kategorie:Lichtsensoren]]
[[Kategorie:868MHz]]

Datei:HM-Sen-MDIR-SM.jpg

2018-09-13T17:31:08Z

AlanBlack: HM-Sen-MDIR-SM Homematic Bewegungsmelder für den Außenbereich

== Beschreibung ==
HM-Sen-MDIR-SM Homematic Bewegungsmelder für den Außenbereich

HM-MOD-RPI-PCB HomeMatic Funkmodul für Raspberry Pi

2018-09-12T09:07:44Z

AlanBlack: Hinweis auf nur ein GPIO-Modul pro Raspi eingefügt

{{Infobox Hardware
|Bild=HM-MOD-RPI-PCB.jpg
|Bildbeschreibung=HomeMatic Funkmodul für Raspberry Pi
|HWProtocol=HomeMatic
|HWType=Gateway
|HWCategory=HomeMatic
|HWComm=868,3/869,525 MHz
|HWChannels=n/a
|HWVoltage=1,8–3,6 V DC
|HWPowerConsumption=50 mA max.
|HWPoweredBy=RasPi
|HWSize=19x41x14mm
|HWDeviceFHEM=[[HMUARTLGW]]
|HWManufacturer=ELV / eQ-3
}}

Das [[HM-MOD-RPI-PCB HomeMatic Funkmodul für Raspberry Pi]] ist eine Platine, die auf die GPIO-Schnittstelle des [[Raspberry Pi]] aufgesteckt werden und damit als [[Interface]] zu [[HomeMatic]] Geräten dienen kann.

== Aufbau, Einsatz und grundsätzliche Funktionsweise ==
Das Modul besteht aus zwei Teilplatinen, die von eQ-3 über den Internetshop von ELV (als Bausatz ab etwa 20€, fertig montiert ab etwa 30€) verkauft werden.

Das eigentliche Funkmodul wird mit HM-MOD-RPI-UART bezeichnet (und trägt den Aufdruck UART, im obigen Bild hinten teilweise verdeckt und mit der umrandeten 7 versehen), sie hat fünf einpolige Buchsen mit dem Rastermaß 2mm. Die Zusatzplatine zum Anschluss an die GPIO wird mit TRX1 bezeichnet (im obigen Bild vorn sichtbar mit dem Aufdruck HM-MOD-RPI-PCB), sie hat zwei sechspolige Buchsen mit dem Rastermaß 2,54mm. Die Zusatzplatine enthält im Wesentlichen Stützkondensatoren und erlaubt einen direkten Anschluss an die GPIO eines Raspberry Pi.
* Der vorgesehene Einsatz als Aufsteckmodul auf den GPIO Port des Raspberry erfordert eine Modell abhängige Konfiguration. Diese wird im Setupbereich des Wiki Artikel zum [[Raspberry_Pi]] beschrieben.

{{Randnotiz|RNText=Neben der hier beschriebenen Option das HM-MOD-RPI-PCB zu verwenden, besteht auch die Möglichkeit, damit auf demselben Raspberry eine virtuelle CCU zu betreiben, welche dann mit [[HMCCU]] eingebunden werden kann. Hierfür stehen mehrere Virtualisierungsvarianten zur Verfügung; eine kurze Darstellung, wie das mittels YAHM funktioniert, ist in diesem {{Link2Forum|Topic=79670|Message=718289|Forenbeitrag}} zu finden.}}Mit dieser Platine in Verbidnung mit dem FHEM-Modul [[HMUARTLGW]] ist nur der Betrieb von BidCoS-Geräten möglich. Zur Einbindung von Geräten, die HM-IP verwenden, ist derzeit (Stand Juni 2018) noch zwingend eine (ggf. virtualisierte) CCU2 oder neuer erforderlich.

Das Funkmodul stellt auf dem 868MHz-Frequenzband eine Verbindung zu Homematic-Geräten her. Das Modul wird über die serielle Schnittstelle an ein Gerät gekoppelt, dass diese serielle Schnittstelle auswerten und die Information dann weiterverarbeiten kann. Hier kommen beispielsweise in Frage: Raspberry Pi, WeMos mini, ESP8266-Module, USB-serielle Adapter. Bereits das UART-Funkmodul erlaubt eine serielle Anbindung (die entsprechenden Schnittstellen Tx und Rx sind vorhanden, sie basieren auf 3,3V), es kann aber auch die zusätzliche TRX1-Platine seriell verbunden werden. Des weiteren gibt es im Forum einen ([https://forum.fhem.de/index.php/topic,56606.0.html Thread]), in dem PeMue eine eigene Platinenversion (Schaltplan, Stückliste und vieles mehr) vorstellt.
=== Platine 1 -PCB-Modul ===
[[Datei:Hm-uart trx1.png|thumb|right|200px|Verkabelung beim HM-MOD-PCB]]
Am einfachsten ist es sicherlich, das kombinierte PCB-Modul (also beide Platinen UART und TRX1 durch eine Pfostenleiste miteinander verlötet) direkt auf die GPIO des Raspberry Pi aufzustecken. Das Bild rechts zeigt die entsprechende Verkabelung. Dabei ist zu beachten, dass sich nicht zwei Module die GPIO teilen können. Steckt schon ein Modul im Raspberry Pi, muss der Anschluss per USB, in einem zweiten Raspberry Pi oder per WLAN gewählt werden.
 
=== Platine 2 -UART-Modul ===
[[Datei:Verkabelung-HM-MOD-uart.png|thumb|right|200px|Verkabelung beim HM-MOD-UART]]
Will man das TRX1-Modul nicht verwenden, so kann man auch das UART-Modul direkt mit Rx/Tx des Raspberry Pi verbinden. Das Bild rechts zeigt die entsprechende Verkabelung. Hier sollten allerdings Stützkondensatoren an die Stromversorgung des UART angebracht werden, da Spannungsschwankungen sonst zu schwer interpretierbaren Fehlern führen können. Die Anschlüsse sind dem nachstehenden Bild zu entnehmen, allerdings ist hier nicht die UART-Platine, sondern das TRX1-Gegenstück zu sehen!

Sowohl serielle Schnittstelle des Raspberry Pi als auch das UART-Modul arbeiten mit 3,3V arbeitet, so dass man keine Spannungsteiler benötigt. Mehr Informationen zu den GPIOs findet man unter diesem [http://www.netzmafia.de/skripten/hardware/RasPi/RasPi_GPIO.html Link].

=== Zusammenbau und Verwendung ===
Man sollte die Antenne aus dem Gehäuse schauen lassen oder möglichst weit weg von jeder Elektronik positionieren. Außerdem bitte das Ende der Drahtantenne mit einem Klecks Heißkleber oder ähnlichem isolieren. Eine Berührung vor allem mit dem Innenleben des Raspberry Pi muss vermieden werden!

Bitte auf die richtige Lage (Bilder) beim Zusammenbau und auf Lötzinnbrücken achten. Das sind häufige Fehler beim Zusammenbau!

Beide Platinen können zusammengebaut oder auch nur das UART Modul getrennt verwendet werden.
[[Datei:HM-MOD-UART-Unten.jpg|thumb|left|200px|Montage des Moduls HM-MOD-UART unten]]
[[Datei:HM-MOD-UART-Oben.jpg|thumb|right|200px|Montage des Moduls HM-MOD-UART oben]]
Die originale Montage in der Anleitung von eq3 sieht den Zusammenbau PCB Modul unten und UART Modul oben vor(rechts). Damit passen die kleineren Pi Gehäuse nicht, das Gesamtmodul klemmt am Deckel.

Man kann ohne weiteres das UART Modul unter dem PCB Modul montieren (links), damit wird die Gesamthöhe geringer und es passt problemlos in jedes Gehäuse. Es kann sein das jetzt aber Kühlkörper oder ähnliches seitens der Pi Platine stören.
 

== Verwendung mit Raspberry Pi ==

=== Originaler Einsatzzweck im Raspberry ===
Die notwendige Konfiguration der Schnittstelle ist hier beschrieben: [[Raspberry_Pi#Verwendung_UART_f.C3.BCr_Zusatzmodule|Verwendung UART für Zusatzmodule]].
* Der Einsatz in FHEM für CUL_HM erfolgt mit dem Modul [[HMUARTLGW]]

=== Remoteanbindung - Pi + RPI Modul = LAN Modul ===

Mit einem vorhandene Pi kann man HM-MOD-RPI-PCB Modul auch im Netzwerk verfügbar machen. Dieser Pi kann beliebige Aufgaben erledigen, nur das HM-MOD-RPI-PCB Modul selbst darf nicht lokal verwendet werden.

Somit kann man bei einem Umzug des FHEM Servers das HM-MOD-RPI-PCB Modul einfach weiterhin nutzen oder einen vorhandene RaspberryPi zum "HMLAN" umbauen.
Sollte man aber ausschließlich Zugriff auf das HM-MOD-RPI-PCB Modul im Netzwerk benötigen empfiehlt sich auch aus Kostengründen (Stromverbrauch) eine andere Lösung.

Achtung! Auch über das Netzwerk darf immer '''nur eine Instanz auf das freigegebene Modul zugreifen'''!

Die Konfiguration der Schnittstelle ist in jedem Fall gleich: [[Raspberry_Pi#Verwendung_UART_f.C3.BCr_Zusatzmodule|Verwendung UART für Zusatzmodule]]. Die [[HM-MOD-RPI-PCB_HomeMatic_Funkmodul_für_Raspberry_Pi#Definition_in_FHEM_2|Definition in FHEM]] erfolgt dann mit dem Parameter uart:// .

==== Variante mit ser2net ====
Diese Installation auf dem Pi mit dem HM-MOD-RPI-PCB Modul bitte im Kontext <code>sudo su</code> ausführen.

<pre>apt-get install ser2net
echo "4000:raw:0:/dev/ttyAMA0:115200 NONE 1STOPBIT 8DATABITS HANGUP_WHEN_DONE" >> /etc/ser2net.conf
# Den Dienst neu starten
systemctl restart ser2net</pre>

==== Variante mit socat ====
Installation auf dem Pi wo das Modul steckt bitte so installieren.

sudo apt-get install socat

Zum Test kann man socat in der Kommandozeile starten

sudo socat TCP4-LISTEN:2000,fork,reuseaddr /dev/ttyAMA0,raw,echo=0,b115200

Für den dauerhaften Betrieb muss der Start von socat automatisch erfolgen.
Auf einen Debian Jessie mit systemd legt man z.B. einen Dienst durch folgende Datei an:
/etc/systemd/system/hmlangw.service

[Install]
WantedBy=multi-user.target
Type=forking

[Service]
ExecStart=/usr/bin/socat TCP4-LISTEN:2000,fork,reuseaddr /dev/ttyAMA0,raw,echo=0,b115200
User=root
Restart=always
RestartSec=10

Dann kann mit

sudo systemctl enable hmlangw

der Service zum Autostart konfiguriert werden.

== Verwendung mit anderer Hardware ==
=== Anbindung mit USB-Adapter ===
{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Es sind immer wieder Exemplare mit [[CP2102]] im Umlauf, die mehr als 3.3V Spannung liefern! Vor dem Verbinden mit dem HM-Modul sollte daher geprüft werden, ob der interne Spannungswandler ordnungsgemäß funktioniert und wirklich nur 3.3V liefert. Bei den blauen Micro-Modulen kann man den Fehler nach dieser Anleitung beheben: [https://www.silabs.com/community/interface/forum.topic.html/cp2102_3_3v_outputi-EaVr Beitrag von PBudmark vom 08.07.2017].}}
[[Datei:PL2102 Modul.png|200px|thumb|right|Mod zur Herstellung der korrekten Spannung]]
Das UART-Modul kann ebenfalls mit einem USB-Adapter an ein USB-fähiges Gerät angeschlossen werden. Allerdings ist hier wieder auf den Spannnungspegel zu achten, unbedingt einen USB-Adapter mit 3,3 Volt Pegel nehmen! Grundsätzlich bewährt haben sich z.B. Modelle mit einem [[CP2102]], der auch ausreichend Stromreserven zum Betrieb des Moduls bietet. Dabei ist die serielle Schnittstelle wie üblich zu kreuzen, also

'''Verschaltung'''
3.3V <-> 3.3V
GND <-> GND
Rx <-> Tx
Tx <-> Rx

=== Anbindung mit ESP8266 ===
Es kann ein beliebiger ESP8266 verwendet werden. Beim ESP8266 gibt es zwei verschiedene Firmware-Möglichkeiten: ESPLink oder ESPEasy. Ebenso sind zwei verschiedene Schnittstellen möglich: Entweder direkt die serielle Schnittstelle (da die ESP auf 3,3V laufen, sind keine Spannungsteiler erforderlich, Verschaltung siehe oben) oder aber durch eine ''swapped'' Schnittstelle, bei der auf die digitalen Pins D7/D8 zurückgegriffen wird (siehe unten). Die letztere Verschaltung erfordert aber eine entsprechende Implementierung der Schnittstelle in der Firmware selbst (''serieller Server'' genannt), die beispielsweise bei ESPEasy nicht gegeben ist oder selbst kompiliert werden muss.

'''Verschaltung bei einem WeMos D1 mini'''
(UART) <-> (Wemos)
3.3V <-> 3.3V
GND <-> GND
Rx <-> D8
Tx <-> D7

Es gibt eine ausführliche Erläuterung für die Software unter [https://forum.fhem.de/index.php?action=dlattach;topic=56606.0;attach=68630].

Verwendet man ESP-Link, so muss neben der WLAN Konfiguration nur das Pin Assignment konfiguriert werden. Alle Pins auf disabled und UART pins auf swapped stellen.

Im Forum gibt es mehr Informationen zu diesen Adaptern, zum Beispiel {{Link2Forum|Topic=62651|LinkText="(amunra)-Platine für HM-MOD-UART-RPI..."}} oder {{Link2Forum|Topic=79559|LinkText="3. Sammelbestellung - Homematic WLAN Gateway"}}.

=== Betrieb mit einem LAN-TTL-Wandler ===
[[Datei:Hm-uart und usr-tcp232-T2.png|thumb|right|400px|Anschluß an die gängige Variante USR-TCP232-T2]]Auf gängigen Marktplätzen sind für etwas weniger als 10 Euro Module erhältlich, die einen seriellen Anschluss im LAN bereitstellen können. Näher Hinweise sind in den Artikeln [[Serial TTL to Ethernet Module]] sowie [[1W-IF-ETH]] zu finden.

Die Module melden sich per DHCP<ref>jedenfalls neuere firmware-Versionen</ref> im Netzwerk an, die Konfiguration erfolgt je nach Variante über ein Web-Interface, ein Windows-Tool oder eine Management-Software.

=== Betrieb mit MapleCUx ===

Auch die seriellen Schnittstellen, die ein MapleCUL oder [[MapleCUN]] bereitstellen, können zum Anschluß des Moduls verwendet werden. Der MapleCUN stellt beide seriellen Schnittstellen je unter einem eigenen Port ins Netz.

== Definition in FHEM ==

Je nach physischem Anschluss erfolgt eine Anbindung in FHEM in unterschiedlicher Weise. Wurde ein USB-Adapter auf dem FHEM-Gerät selbst verwendet, definiert man das Gerät in FHEM wie folgt
define USB_HmUART HMUARTLGW /dev/ttyUSBx
Wurde dagegen das Gerät über WLAN oder LAN durch das UART-Modul angebunden, erfolgt die Einbindung in FHEM durch
define WLAN_HmUART HMUARTLGW uart://<IP-Adresse>:<Portnummer>
Portnummern:
*ser2net 4000 (bzw. entsprechend gewählter Einstellung)
*socat 2000 (bzw. entsprechend gewählter Einstellung)
*esp-link 23
*MapleCUN 2324 bzw. 2325
*USR-TCP232-T2 entspr. Konfiguration.

=== Logbeispiel ===
Typischerweise meldet sich das Modul beim Start so:
2016.10.06 17:11:16 3: Opening myHmUART device /dev/ttyAMA0
2016.10.06 17:11:16 3: Setting myHmUART serial parameters to 115200,8,N,1
2016.10.06 17:11:16 3: myHmUART device opened
2016.10.06 17:11:17 3: HMUARTLGW myHmUART currently running Co_CPU_BL
2016.10.06 17:11:17 3: HMUARTLGW myHmUART currently running Co_CPU_App

=== Verwendung AES in FHEM===
Das Modul beherrscht AES.
Für weitere Informationen gibt es einen separaten Wiki Eintrag [[AES Encryption]]

=== Firmware Update des UART-Moduls mit FHEM ===

Die Module werden mit einer Firmware 1.2.1 ausgeliefert. Dies Firmware ist nicht für einen stabilen Betrieb geeignet,
die Firmware 1.4.1 ist die minimal lauffähige Version.

Die ersten zwei Schritte werden in der Kommandozeile auf Betriebssystemebene ausgeführt, also im "Terminal". Punkt 3 ist bis auf die Pfadeingabe in der FHEM Web Oberfläche auswählbar.

1. Firmware herunterladen
# Version 1.4.1
wget https://raw.githubusercontent.com/eq-3/occu/28045df83480122f90ab92f7c6e625f9bf3b61aa/firmware/HM-MOD-UART/coprocessor_update.eq3
# Alternativ die aktuellste
wget https://raw.githubusercontent.com/eq-3/occu/HEAD/firmware/HM-MOD-UART/coprocessor_update.eq3

2. Kopieren an einen Ort wo FHEM Zugriff hat, am Besten nach /opt/fhem/FHEM/firmware
sudo cp coprocessor_update.eq3 /opt/fhem/FHEM/firmware/

3. Flashen der neuen Firmware aus FHEM
set myHmUART updateCoPro /opt/fhem/FHEM/firmware/coprocessor_update.eq3

=== Firmware Update des UART-Moduls ohne FHEM ===

Sollte das Update über FHEM nicht funktionieren oder FHEM nicht verfügbar sein, kann die Firmware auch wie folgt eingespielt werden (Quelle: [http://heinz-otto.blogspot.com/2016/07/raspberry-pi-homematic-modul.html Ottos Technik Blog])

sudo su
apt-get update && apt-get -y install libusb-1.0-0-dev build-essential git
systemctl stop fhem
git clone git://git.zerfleddert.de/hmcfgusb
cd hmcfgusb/
make
# Firmware runterladen
wget https://raw.githubusercontent.com/eq-3/occu/ee68faf77e42ed5e3641790b43a710a3301cea7e/firmware/HM-MOD-UART/coprocessor_update.eq3
# eigentliches flashen:
./flash-hmmoduart -U /dev/ttyAMA0 coprocessor_update.eq3

=== Bekannte Probleme ===
Sollten beim Flashen der Firmware hartnäckige Probleme auftreten (kein Erfolg aber auch gar keine Fehlermeldungen) ist das Modul vom Strom zu trennen, ein Neustart des Pi reicht nicht!

Ein {{Link2Forum|Topic=41203|Message=340320|LinkText=Beitrag}} aus dem genannten Forenthread: ''Das Ding ist anscheinend wirklich einfach das Funkmodul aus der CCU2 (wird zumindest in der eQ-3 SW als CCU2 angesprochen) und spricht ein für FHEM vollkommen neues Protokoll.''

== Links ==
* {{Link2Forum|Topic=41203|LinkText=Forenthread}} mit Nachfrage zur Unterstützung dieses Geräts in FHEM
* {{Link2Forum|Topic=54511|LinkText=Modul für HomeMatic UART-Modul (RPi) und HomeMatic LAN Gateway}}
* [http://www.elv.de/homematic-funkmodul-fuer-raspberry-pi-bausatz.html Produktseite] bei ELV
* {{DocLink|elv|/Assets/Produkte/10/1040/104029/Downloads/104029_lan_gateway_um.pdf Bedienungsanleitung}}
* {{Link2Forum|Topic=56606|LinkText=Forenthread}} Hardware Thread mit vielen Varianten der Anbindung. In Post #26 gibt es die Detailbeschreibung in der angehängten PDF.

[[Kategorie:HomeMatic Components]]
[[Kategorie:Interfaces]]
[[Kategorie:Raspberry Pi]]
[[Kategorie:868MHz]]

HM-CFG-USB USB Konfigurations-Adapter

2018-09-12T08:20:51Z

AlanBlack:

{{Infobox Hardware
|Bild=HM-CFG-USB-2.jpg
|Bildbeschreibung=HomeMatic USB Konfigurationsadapter (Version 2)
|HWProtocol=HomeMatic
|HWType=Interface/Gateway
|HWCategory=HomeMatic
|HWComm=868,3 MHz
|HWChannels=
|HWVoltage=5 V
|HWPowerConsumption=
|HWPoweredBy=USB-Bus
|HWSize=V1: 40 x 90 x 25 mm V2: 28 x 84 x 11,5 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]

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

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

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

{{Randnotiz|RNTyp=Info|RNText='''Skript zur Kompletteinrichtung unter Linux'''
Dieser {{Link2Forum|Topic=13071|Message=190887|LinkText=Bericht}} im Forum stellt ein Script vor, das ''hmland'' herunterlädt, übersetzt (kompiliert), installiert sowie ein init-Script anlegt, so dass fast keine manuellen Eingriffe mehr notwendig sind.}}
Die nachfolgenden Angaben in diesem Abschnitt sind rein zu Informationszwecken (noch) enthalten:

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

Danach kann der Dienst (zu Testzwecken sind Debugging-Ausgaben mit <code>-D</code> aktiviert) gestartet werden:
:<code> /opt/hmcfgusb/hmland -p 1234 -D</code>

==== Start als Daemon ====
Um ''hmland'' automatisch als Daemon zu starten, kann ein init-Script genutzt werden. Die Quellen von ''hmland'' enthalten ein solches Script im <code>debian/</code> Unterverzeichnis:

<syntaxhighlight lang="bash">
cp /opt/hmcfgusb/debian/hmland.init /etc/init.d/hmland
cp /opt/hmcfgusb/debian/hmland.default /etc/default/hmland
</syntaxhighlight>

Einstellungen, beispielsweise der Port, auf dem ''hmland'' hört, können (und sollten) in der Datei <code>/etc/default/hmland</code> vorgenommen werden. Wichtig: Wenn diese Anleitung befolgt wurde, muss in der Datei <code>/etc/init.d/hmland</code> die folgende Zeile wie folgt angepasst werden (<code>/hm</code> aus dem Pfad entfernen), damit der automatische Start des Daemon klappt:
<syntaxhighlight lang="bash">
DAEMON=/opt/hmcfgusb/$NAME # Introduce the server's location here
</syntaxhighlight>

Die kopierte Datei mit <code>chmod 755 /etc/init.d/hmland</code> ausführbar machen, anschließend kann ''hmland'' mit folgendem Befehl gestartet werden:
:<code>/etc/init.d/hmland start</code>

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgende Konfigurationsdatei verwendet werden:
<syntaxhighlight lang="bash">
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

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

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

==== Start über FHEM Startskript ====
Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

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

Dann geht es weiter:
:<code>sudo cp hmcfgusb.rules /etc/udev/rules.d/ </code>

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

Damit editiert man das FHEM Startskript:
:<code>sudo nano /etc/init.d/fhem </code>

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)
<syntaxhighlight lang="bash">
'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

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

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

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

=== Einrichtung auf Synology DiskStations ===
Packages für DSM5.2 finden sich hier:
https://github.com/mkunzmann/spksrc/releases/tag/0.101-3

Welches Package für welche DS kann man hier sehen:
https://github.com/SynoCommunity/spksrc/wiki/Architecture-per-Synology-model

Einfach das passende Package installieren und dann kann man den hmland über den Synology Package-Manager starten und stoppen. Während der Installation kann man den Port für hmland festlegen. Bitte einen Port > 1024 wählen, da der hmland nicht als root läuft. Außerdem kann ein Logfile angegeben werden. Hier am besten eine Datei auf einem USB Stick angeben die für jedermann schreibbar sein muss. Damit sollten die Platten nach wie vor in den Standby gehen.

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

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

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

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

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:
<syntaxhighlight lang="text">
Datum Zeit: Client 127.0.0.1 connected!
Can't claim interface: Access denied (insufficient permissions)
Can't find/open hmcfgusb!
Datum Zeit: Connection to 127.0.0.1 closed!
</syntaxhighlight>

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

<syntaxhighlight lang="text">
idProduct: 49167
idVendor: 6943
</syntaxhighlight>

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:
<syntaxhighlight lang="bash">
chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext
</syntaxhighlight>

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

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

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

=== Definition(en) in der FHEM-Konfiguration ===
In der FHEM [[Konfiguration]] muss noch, sofern/sobald der ''hmland'' läuft, das Device eingerichtet werden mit den folgenden Anweisungen:
:<code>define '''hmusb''' HMLAN 127.0.0.1:1234 </code>
wobei '''hmusb''' der frei wählbare Devicename ist. Anschließend sollte bzw. muss noch mit
:<code>attr '''hmusb''' hmId <'''hmId'''> </code>
eine '''hmId''' zugeordnet werden (dabei bitte auch die Hinweise und Regeln beachten, die im Zusammenhang mit der [[Virtueller Controller VCCU|VCCU]] beschrieben sind!

== Firmware Update ==
Der Firmware Update (unter Linux) ist ebenfalls auf der [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland-Internetseite] beschrieben. Auch die letzte bekannte Firmware-Version (0.967) steht dort zur Verfügung.

== Bekannte Probleme ==
=== Verbindung zu neueren hmland-Versionen nicht stabil ===
Seit Version 0.100 meldet sich die HMLAN-Emulationssoftware als USB-Interface bei FHEM. Ältere FHEM-Versionen (vor dem 19.6.2015) brechen deshalb die Verbindung ab, da sie nur ein LAN-Interface erwarten.

Lösung: Kommandozeilenparameter <code>-I</code> dem hmland-Aufruf hinzufügen, dann meldet sich dieser wieder als LAN-Interface.

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

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

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

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
{{Randnotiz|RNTyp=r|RNText=Stand März 2016 ist allem Anschein nach kein HM-CFG-USB mehr im ELV Programm enthalten!}}
* HM-CFG-USB-2: die aktuelle Version; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

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

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