FHEMWiki - Benutzerbeiträge [de]

FRITZBOX

2025-02-18T11:47:02Z

Bernd zwo: Smart-Home Hinweis hinzugefügt

{{Infobox Modul
|ModPurpose=Steuerung einer Fritz!Box über FHEM
|ModType=d
|ModForumArea=FRITZ!Box
|ModTechName=72_FRITZBOX.pm
|ModOwner=Jörg/JoWiemann ({{Link2FU|94|Forum}} / [[Benutzer Diskussion:JoWiemann|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, es müssen also die TR-064 Funktionen genutzt werden.}}
{{Randnotiz|RNTyp=y|RNText='''Fork seit Januar 2021'''</br>
Im Januar 2021 wurde von einem anderen Autor ({{Link2FU|94|JoWiemann}}) ein Fork begonnen, der Korrekturen und Weiterentwicklungen enthält. Beschreibungen und Modulversionen sind in {{Link2Forum|Topic=118150|LinkText=diesem Forenbeitrag}} zu finden.

Seit Januar 2023 sind beide Versionen wieder im Modul 72_FRITZBOX.pm zusammengeführt.}}

== 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 (wird vom Modul nicht mehr unterstütz) ===
<s>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:</s>

# <s>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</s>
# <s>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</s>
::<code><s>sudo apt-get install libnet-telnet-perl</s></code>

== Installation ==
=== Erste Schritte ===
Zur Erstinstallation reicht ein einfaches <code>define FritzBox FRITZBOX < ip oder Hostname> </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 < IP oder Hostname ></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

== 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. In der Web-Oberfläche der FritzBox muss die TR064 Schnittstelle explizit freigeschaltet sein. Ist dies nicht der Fall, werden entsprechende Informationen und Funktionen des Moduls deaktiviert. Der aktuelle Status wird im Device im Bereich Internals durch das Reading TR064 dargestellt.

Mit dem 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).

=== Smart-Home-Devices sind nicht in FHEM sichtbar ===
das Attribut 'enableSmartHome' muss gesetzt sein; zur Nutzung der Devices in FHEM eventuell noch das Modul FBAHAHTTP einrichten

Auch ZigBee-Devices werden dann als FBDECT-Devices gemappt.

Links
* {{Link2Forum|Topic=29725|LinkText=Forenthread}} zu diesem Modul
* Neuer Support Thread im Forum, {{Link2Forum|Topic=70064|LinkText=ab April 2017}}

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

DbLog

2023-03-17T12:23:17Z

Bernd zwo: Hinweis auf mysql_secure_installation

{{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]])<br />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.

Eine erste Konfiguration von MariaDB / mySQL kann mit <pre>
# sudo mysql_secure_installation
</pre>vorgenommen 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><br><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><br><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]]

HM-CC-VD Funk-Stellantrieb

2018-05-07T20:11:14Z

Bernd zwo: Absatz 4 neu: "Betrieb mit FHEM, ohne (physischen) HM-CC-TC"

'''HM-CC-VD Funk-Stellantrieb'''

'''Achtung: Dieses Gerät ist abgekündigt (wird nicht mehr hergestellt). Nachfolgeprodukt ist der [[HM-CC-RT-DN]].'''

= Allgemeines =

Stellantrieb für den [[HM-CC-TC Funk-Wandthermostat|HM-CC-TC]]. Es können maximal 4 HM-CC-VD an ein HM-CC-TC angelernt werden.

Aktuelle Firmware: 2.0

Der HM-CC-VD '''misst nicht selbst''' die Temperatur. Diese wird von dem [[HM-CC-TC Funk-Wandthermostat]], mit dem der Stellantrieb [[Peering (HomeMatic)|gepeert]] wurde, gemessen.

= Probleme =

Bei Firmwareversionen vor 2.0 kann es vorkommen, dass sich der Stellantrieb bei einer bestimmten Stellung "festfährt" (z.B. 4%) und der Raum sich kontinuierlich erhitzt, obwohl eine niedrigere Temperatur am Wandthermostat eingestellt ist. Erst nach einem Reset des Stellantriebs oder manuellen Erhöhung der Temperatur am Wandthermostat/FHEM verrichtet der Stellantrieb wieder wie gewohnt seine Arbeit.

Quelle: [[http://www.elv.de/output/controller.aspx?cid=834&detail=2&detail2=582 1]]

Ein Firmwareupdate kann derzeit nur mittels Einschicken des Stellantriebs erfolgen.

Ist der Stellantrieb mit dem HM-CC-TC gepairt (zu sehen im Menü des HM-CC-TC als VST Nummer X), erscheint aber nicht in FHEM (hier mit HMLAN), dann hilft der Befehl ''set <HMLAN-Name> hmPairForSec 300'' und das Drücken des Anlernknopfes am HM-CC-VD für mind. 5 Sekunden.

= Betrieb mit FHEM =

HM-CC-VDs werden mit dem für ihren Betrieb/Raum zuständigen HM-CC-TC [[Peering (HomeMatic)|gepeert]]. Dadurch ist der TC für die Ansteuerung der Ventiltriebe da.

== Log-Daten ==
=== Device-Log ===

Zur Behebung des "1 bzw. 4 % Fehlers" wurde die Raumtemperatur über die Ansteuerung des HM-CC-TC temporär auf 28 °C erhöht. Nachdem das Thermostat (VD) laut Logs das Ventil auf hier 68 % geöffnet hat, wurde die Temperatur wieder auf die gewünschte (desired) Temperatur (am TC) gesetzt. Diese Befehle mussten allerdings einige Male wiederholt werden und es bedurfte einiger Minuten Wartezeit zwischen den Umstellungen.
<pre>
2013-03-18_22:34:57 OG.AZ.Thermostat set_0 %
2013-03-18_22:34:57 OG.AZ.Thermostat ValveDesired: 0 %
2013-03-18_22:34:58 OG.AZ.Thermostat ValvePosition: 1 %
2013-03-18_22:34:58 OG.AZ.Thermostat 1 %
2013-03-18_22:34:58 OG.AZ.Thermostat battery: ok
2013-03-18_22:34:58 OG.AZ.Thermostat motorErr: ok
2013-03-18_22:34:58 OG.AZ.Thermostat motor: stop
2013-03-18_22:34:58 OG.AZ.Thermostat operState: errorTargetNotMet
2013-03-18_22:34:58 OG.AZ.Thermostat operStateErrCnt: 1
2013-03-18_22:37:42 OG.AZ.Thermostat set_68 %
2013-03-18_22:37:42 OG.AZ.Thermostat ValveDesired: 68 %
2013-03-18_22:37:43 OG.AZ.Thermostat ValvePosition: 1 %
2013-03-18_22:37:43 OG.AZ.Thermostat 1 %
2013-03-18_22:40:20 OG.AZ.Thermostat set_68 %
2013-03-18_22:40:20 OG.AZ.Thermostat ValveDesired: 68 %
2013-03-18_22:40:22 OG.AZ.Thermostat ValvePosition: 68 %
2013-03-18_22:40:22 OG.AZ.Thermostat 68 %
2013-03-18_22:40:22 OG.AZ.Thermostat battery: ok
2013-03-18_22:40:22 OG.AZ.Thermostat motorErr: ok
2013-03-18_22:40:22 OG.AZ.Thermostat motor: stop
2013-03-18_22:40:22 OG.AZ.Thermostat operState: onTarget
2013-03-18_22:42:31 OG.AZ.Thermostat set_0 %
2013-03-18_22:42:31 OG.AZ.Thermostat ValveDesired: 0 %
2013-03-18_22:42:33 OG.AZ.Thermostat ValvePosition: 68 %
2013-03-18_22:42:33 OG.AZ.Thermostat 68 %
2013-03-18_22:42:33 OG.AZ.Thermostat battery: ok
2013-03-18_22:42:33 OG.AZ.Thermostat motorErr: ok
2013-03-18_22:42:33 OG.AZ.Thermostat motor: closing
2013-03-18_22:42:33 OG.AZ.Thermostat operState: adjusting
2013-03-18_22:44:34 OG.AZ.Thermostat set_0 %
2013-03-18_22:44:34 OG.AZ.Thermostat ValveDesired: 0 %
2013-03-18_22:44:36 OG.AZ.Thermostat ValvePosition: 0 %
2013-03-18_22:44:36 OG.AZ.Thermostat 0 %
</pre>

=== Event monitor ===
<pre>
2013-03-18 22:42:33 CUL_HM OG.AZ.Thermostat motor: closing
2013-03-18 22:42:33 CUL_HM OG.AZ.Thermostat operState: adjusting
</pre>

== Batteriealarme des HM-CC-VD in Verbindung mit HM-CC-TC ==
1. bei U-Bat. < 2,4 V erscheint im Display des VD und des TC das Batteriesymbol mit battery: low in den Readings und Events!
2. bei U-Bat. < 2,3 V erscheint im Display des VD zusätzlich F4 mit battery: critical in den Readings und Events!
Es wird dringend geraten, die Batterien bei battery: low zu tauschen!

= Betrieb mit FHEM, ohne (physischen) HM-CC-TC =

Alternativ kann der HM-CC-VD auch über einen virtuellen HM-CC-TC betrieben werden.
Damit diese Lösung stabil funktioniert, sollte die Kommunikation (nach Nutzererfahrung aus dem Forum) als IO-Device ein HMLAND oder ein HM-MOD-UART (Raspi-Modul) nutzen.
Ein CUL im RF-Mode 'Homematic' scheint das nötige präzise Timing (s.o.) nicht immer zu halten.

== Einrichtung ==
=== Vorbereitung ===
- der HM-CC-VD sollte zurückgesetzt sein - ca. 20 s den Button drücken und die Einfahrprozedur am Heizkörperventil abschließen.
- das Pairing durchführen: am HMLAND oder HM-MOD-UART (oder besser einer VCCU) 'set <HMIO> hmPairForSec nnn' und am HM-CC-VD den Button 5-10 s drücken, es sollte im Display des VD kurz von 20 s rückwärts gezählt werden und dann das Antennensymbol dauerhaft stehen.
Der HM-CC-VD sollte jetzt in der Liste der FHEM-Devices als HM_xxxxxx sichtbar sein.
Wichtig: Am neu eingerichteten Device HM-CC-VD muss noch das Attribut msgRepeat = 0 gesetzt werden, sonst führt ein Zuviel an Kommunikation zwischen HM-CC-VD und IO-Device zum Verlust der Verbindung. Quelle: [[https://forum.fhem.de/index.php/topic,41588.msg339484.html#msg339484 1]]

<pre>
set HM_xxxxxx deviceRename <HM_CC_VD>
attr <HM_CC_VD> msgRepeat 0
</pre>

=== Einrichten virtueller HM-CC-TC ===
Der zur Kommunikation mit dem Stellantrieb HM-CC-VD nötige Virtuelle Controller wird wie folgt eingerichtet:
<pre>
define <HM-VIRT-TC> CUL_HM 112233*
attr <HM-VIRT-TC> expert 2_raw
attr <HM-VIRT-TC> model virtual_1
attr <HM-VIRT-TC> msgRepeat 0
attr <HM-VIRT-TC> subType virtual

set <HM-VIRT-TC> virtual 1
</pre>
* oder eine andere noch nicht vergebene ID

Weil es sich nicht um einen virtuellen Button, sondern um den Kanal eines virtuellen HM-CC-TC handelt, kann man den Kanal umbenennen:
<pre>
rename <HM-VIRT-TC>_Btn1 <HM-VIRT-TC>_c1
</pre>

In diesem Beispiel wird ein virtueller TC einem VD zugeortnet. Wenn man einen TC mit mehreren Kanälen nutzt (z.B. set <HM-VIRT-TC> virtual 2),
kann man den einzelnen VD nachher nicht kontrollieren, es wird nur der Status des zuletzt angesteuerten Kanals am <HM-VIRT-TC> ausgewertet.

Bei Einsatz einer VCCU kontrollieren, ob das richtige IO-Device genutzt wird (s. VCCU) - falls nicht, per IOgrp-Attribut setzen.
Ohne VCCU sollte IODev auf das richtige Device zeigen.

Hier z.B. ein HM-MOD-UART "UART-HM" an der VCCU "VIRTCCU1"
<pre>
attr <HM-VIRT-TC> IOgrp VIRTCCU1:UART_HM
</pre>

=== Peering von HM-CC-VD und virtuellem HM-CC-TC ===
<pre>
set <HM-VIRT-TC>c1 peerChan 0 <HM_CC_VD> single set
</pre>

Danach den Button am HM-CC-VD drücken, bis die 20-Sekunden-Anzeige anfängt zu laufen.

mit
<pre>
set <HM-VIRT-TC>c1 valvePos 55
</pre>
kann man den VD jetzt testen.

mit
<pre>
define heizung_regler PID20 <thermosensor>:temperature <HM-VIRT-TC>c1:valvePos
</pre>

lässt sich die Kombination aus HM-CC-VD und virtuellem HM-CC-TC im Regelmodul PID20 als Heizungsregler nutzen.

Quellen:
https://forum.fhem.de/index.php?topic=60296.0
https://forum.fhem.de/index.php?topic=22419.0
https://forum.fhem.de/index.php?topic=30738.0
https://forum.fhem.de/index.php?topic=54911.0
https://forum.fhem.de/index.php?topic=41588.0

= Links =
Anleitung: [http://www.eq-3.de/Downloads/eq3/downloads_produktkatalog/homematic/bda/HM-CC-VD_UM_GE_eQ-3_081013.pdf HM-CC-VD Funk-Stellantrieb]

[[Kategorie:HomeMatic Components]]
[[Kategorie:Heizungsventile]]