FHEMWiki - Benutzerbeiträge [de]

HM-CFG-LAN LAN Konfigurations-Adapter

2021-08-17T05:57:54Z

Rosti: Unpair methode hinzugefügt

{{Infobox Hardware
|Bild=HM-CFG-LAN.jpg
|Bildbeschreibung=HM-CFG-LAN, Draufsicht und Seitenansicht
|HWProtocol=HomeMatic
|HWType=[[Interface]]
|HWCategory=
|HWComm=868,3 MHz
|HWChannels=n/a
|HWVoltage=7,5 VDC
|HWPowerConsumption=ca. 100 mA
|HWPoweredBy=Steckernetzteil
|HWSize=100x30mm (ø x H)
|HWDeviceFHEM= {{Link2CmdRef|Anker=HMLAN|Label= 00_HMLAN.pm}}
|ModOwner={{Link2FU|251|Martin / martinp876}}
|HWManufacturer=ELV / eQ-3
}}

Der [[HM-CFG-LAN LAN Konfigurations-Adapter]] ([http://www.eq-3.de/produkt-detail-zentralen-und-gateways/items/hm-cfg-lan.html HM-CFG-LAN]), kurz HMLAN Konfigurator, ist ein [[Interface|Schnittstellengerät]] (IO) ohne wesentliche Intelligenz. Die Aufgabe ist, ein Interface von der Zentrale zu den Geräten bereitzustellen. Ein HMLAN Konfigurator selbst steuert keine Geräte, er überträgt nur Nachrichten in beide Richtungen.

== Alternativen ==
Alternativen zu einem HMLAN Konfigurator sind [[HM-CFG-USB USB Konfigurations-Adapter]], [[CUN]], [[CUNO]] und [[CUL]].

;HMUSB
:Ein HMUSB hat nahezu identische Eigenschaften wie ein HMLAN Konfigurator. Der wesentliche Unterschied ist die Anbindung über USB anstatt Ethernet. Es hat sich erwiesen, dass USB eine bessere Latenz hat als LAN - also eine kürzere Verzögerung. Damit hat ein HMUSB leichte Vorteile zu HMLAN Konfigurator, was aber in den bei Weitem meisten Fällen durch die interne Timing Kalkulation abgefangen wird. Zudem können über den HMUSB (ab Version 2) auch Firmware-Updates OTA (over-the-air, also per Funkverbindung) auf entsprechende HM-Geräte (z.B. den HM-CC-RT-DN) durchgeführt werden.
:Dafür bietet der HMLAN Konfigurator mit seinem Netzwerkanschluss Vorteile bei der Platzierung und bei der Ansteuerung (teilweise Timing-Probleme beim Anschluss von USB-Geräten an langsamere Raspberrys und beim Durchschleifen von USB an FHEM in einer virtuellen Maschine).

; CUL/CUN(O)
* Die Devices liefern keine eigenen Zeitstempel, wodurch eine Timingkorrektur durch FHEM nicht möglich ist. Je nach Systemgeschwindigkeit kann dies zu Problemen, Nachrichtenwiederholung und ggf. auch Nachrichtenverlust führen
* Da USB kurze Reaktionszeiten und geringe Timingschwankungen hat, ist der Einsatz von [[CUL]] und [[CUNO]] mit HM möglich. <br>Die Timingschwankungen der Ethernet-Schnittstelle hingegen können in FHEM nicht ausgeglichen werden. Daher kann der Einsatz der [[CUNO]] über Ethernet '''nicht empfohlen''' werden.
* Der Übertragungsmodus ''lazyConfig'' wird nicht unterstützt

== Funktionen ==
=== AES ===
siehe [[AES Encryption]].

=== Übertragungsmodus ===
Es werden alle HM-Modi unterstützt. Diese sind Always, Burst, Wakeup und Config. Weiter gibt es lazyConfig und conditionalBurst. Siehe [[HomeMatic]] für Details.

=== KeepAlive ===
Der HMLAN Konfigurator baut eine Verbindung zur Zentrale über das LAN Interface auf. Der HMLAN Konfigurator erwartet alle 30 Sekunden eine keep-alive Nachricht von der Zentrale. Sollte diese ausbleiben, baut der HMLAN Konfigurator die LAN-Verbindung ab. Das führt zu einem Disconnect, der in State gemeldet wird. Die Verbindung wird automatisch wieder aufgebaut.
FHEM sendet den keep-alive alle 25 Sekunden, was einen 5 Sekunden Puffer einräumt. In Internals '''msgKeepAlive''' kann man sehen, wie hoch die maximale Verzögerung der Zentrale beim Senden war und wie viel Puffer (in Sekunden) noch verfügbar war.
Die Wiederholrate von 25 Sekunden des keep-alive kann mit dem Attribut '''wdTimer''' reduziert werden, was den Puffer erhöht. Es wird jedoch dringend geraten, im Problemfall die Ursache der Verzögerung zu suchen und zu eliminieren.

=== Nachrichtenübertragung - Performance ===
* Mit Internal ''msgParseDly'' kann man ablesen, welche Verzögerung eine Nachricht vom Empfang im HMLAN Konfigurator bis zur Verarbeitung in der Zentrale hat.
* Der HMLAN Konfigurator hält sich an den Funkstandard, der einem Sender maximal 36 Sekunden Sendezeit je Stunde erlaubt ([[1%25_Regel]]). Wird dieser Wert überschritten, stellt der HMLAN Konfigurator das Senden ein. Empfangen wird weiter. Ist eine Nutzung des Zeitslots zu 90% erreicht, wird im Reading ''cond'' ''Warning-HighLoad'' gemeldet. Bei cond ''ERROR-Overload'' wird das Senden eingestellt.

=== Loggen/Mitschneiden ===
Es stehen die üblichen Funktionen des Attribute [[verbose]] zu Verfügung. Darüber hinaus gibt es die Attribute ''hmProtocolEvents'' und ''logIDs''. Siehe auch [[Homematic Nachrichten sniffen]].

== Vorbereitung ==
{{Randnotiz|RNText='''"Usersoftware"/Firmware'''
* V1.512 / 19.12.2013 / [http://files.elv.de/Assets/Produkte/8/851/85128/Downloads/hm_cfg_lan_software_v1_512.zip Download]
* V1.515 / 12.08.2014 / [http://files.elv.de/Assets/Produkte/8/851/85128/Downloads/hm_cfg_lan_software_v1_515.zip Download]
* V1.520 / 10.12.2015 / [http://www.eq-3.de/Downloads/Software/Konfigurationsadapter/Konfigurationsadapter_LAN/HM-CFG-LAN_Usersoftware_V1_520_eQ-3_151207.zip Download]
'''Firmware Update Tool / Firmware / Datum'''
* V1.2 / 0.965 / 11.02.2016 / [http://www.eq-3.de/Downloads/Software/Firmware%20Update%20Tool/HM-Firmware-Update-Tool_V1_2_eQ-3_160211.zip Download]

}}
[[Datei:HMLAN_CONFIG_IP_AES.png|300px|thumb|right|HomeMatic Lan-Interface Configurator]][[Datei:HMLAN_CONFIG_AES.png|300px|thumb|right|HomeMatic Konfigurator]]
Bevor man den HMLAN mit FHEM nutzen kann, müssen noch Einstellungen vorgenommen werden. Dazu braucht man die Konfigurationsadapter-LAN-Usersoftware, die bei [http://www.eq-3.de/service/downloads.html HomeMatic] herunter zu laden ist und nach der Installation mit der Verknüpfung "HomeMatic-Lan-Interface konfigurieren" oder "HomeMatic-Komponenten konfigurieren" gestartet wird und unter Windows läuft. Für andere Betriebssysteme (siehe Anhang im Beitrag {{Link2Forum|Topic=11506|Message=67417|LinkText=Anleitung für OS X}}) braucht man eine Windows-Emulation. Dem HMLAN liegen zwei Konfigurationsprogramme bei, bitte darauf achten, das richtige zu verwenden. Wenn das Konfigurationsprogramm den HMLAN-Konfigurator nicht findet, sollten alle nicht benutzten Netzwerkinterfaces vorübergehend deaktiviert werden, siehe {{Link2Forum|Topic=10933|Message=62960|LinkText=Beitrag im FHEM Forum}} und [[HM-CFG-LAN_LAN_Konfigurations-Adapter#Bekannte_Probleme|bekannte Probleme]].

=== Firmware ===
Die aktuelle Firmware Version des HMLAN Konfigurators ist 0.965 (Stand Februar 2016). Ein Update ist mit dem ''"Firmware Update Tool"'' möglich, die aktuelle Firmware ist Bestandteil des Tools.

'''Achtung''': Das zum download angebotene '''Firmware Update Tool''' installiert drei Tools:
* Home Matic Firmware Updater Tool - das ist zum Firmware Update von Komponenten mittels CFG-USB!
* '''HomeMatic-Lan-Interface konfigurieren''' - damit kann man auch die '''Firmware des CFG-LAN aktualisieren''' (Rechts im Bild)
* HomeMatic-CFG-USB aktualiseren -- damit kann man auch die Firmware des CFG-USB aktualisieren
Um einen mit FHEM benutzten HM-LAN zu aktualisieren, reicht es,
# im HMLAN-Device mit <code>attr <myHMLAN> dummy 1</code> den Adapter vorübergehend zu deaktivieren,
# mit dem (Windows) Firmware Update Tool die Firmware auf den HM-LAN aufzuspielen
# nach dem Stoppen des Update Tools mit <code>deleteattr <myHMLAN> dummy</code> das Device in FHEM wieder zu aktivieren.

Version 1.2 des Firmware Update Tools läuft auch unter Windows 10.

Allerdings kann es unter Umständen passieren, dass sich das Programm mit folgender Fehlermeldung nicht starten lässt:
"Die Anwendung konnte nicht gestartet werden, da die Side-by-Side Konfiguration ungültig ist."

Dann fehlt die Microsoft Visual C++ 2008 SP1 Redistributable Package (x86). Diese kann dann unter dieser Adresse heruntergeladen und anschließend installiert werden: https://download.microsoft.com/download/d/d/9/dd9a82d0-52ef-40db-8dab-795376989c03/vcredist_x86.exe

=== IP Adresse ===
Der HMLAN Konfigurator ist ähnlich wie der CUN(O) ein Netzwerkgerät. Er beherrscht DHCP und bezieht bei einem im Netzwerk erreichbaren DHCP Server von diesem eine IP-Adresse. Da FHEM zwecks Kommunikation die IP-Adresse wissen muss, ist es sinnvoll, dem HMLAN Konfigurator eine statische (feste) Adresse zuzuweisen.
* mit der auf der CD mitgelieferten ''"HomeMatic Lan-Interface Configurator"'' Software unter ''"Change IP Settings"'' oder
* im DHCP-Server (sofern dies vom gegebenen DHCP Server als Konfigurationsoption unterstützt wird).

=== AES Encrypted LAN Communication ===
Wichtig ist, dass vor Verwendung die "AES Encrypted LAN Communication" abgeschaltet wird, da diese von FHEM nicht unterstützt wird. Dies ist unter ''"Change IP Settings"'' der ''"HomeMatic Lan-Interface Configurator"'' Software möglich. AES auf dem LAN ist zu unterscheiden von HMLAN auf der Funkschnittstelle. siehe [[AES Encryption]].

== Einbindung in FHEM ==
Der HMLAN-Konfigurator muss in FHEM [[Konfiguration|konfiguriert]] werden. Das erfolgt mit diesen Befehlen:
:<code>define HMLAN1 HMLAN <IP Adresse>:1000</code>
Der Name (im obigen Beispiel ''HMLAN1'') kann frei vergeben werden. Standard IP-Port des HMLAN-Konfigurators ist 1000.

HMLAN kennt mehrere Attribute ({{Link2CmdRef|Anker=HMLAN}}).
Äußerst wichtig ('''''Sicherheit!!''''') ist es außerdem, die '''hmId''' zu vergeben, siehe [[HomeMatic_Devices_pairen#hmId]].

Ein '''gleichzeitiger''' Zugriff von FHEM und der HomeMatic-Software auf den HMLAN-Konfigurator ist nicht möglich, da letzterer nur eine einzige Verbindung zulässt. Wollen Sie temporär z.B. mit der Windows-Software von HomeMatic zugreifen, ist FHEM zu deaktivieren.
Sinnvoll ist es, die hmId mit der hmId der PC-Software gleichzusetzen. Dann kann man von beiden Zentralen alternativ zugreifen ohne pairen zu müssen.

=== Nutzung mehrere IOs ===
==== Empfangen ====
Man kann an einem FHEM mehrere IOs (HMLAN/USB, CUL/CUNO) betreiben. Generell empfangen alle IOs von allen Geräten in ihrem Empfangsbereich - unabhängig von der hmId.

==== Senden ====
An ein Gerät wird nur über das IO gesendet, das in Internals->IODev angezeigt wird. Nutzt man mehrere IOs sollte man im HM Device das Attribut IODev auf das gewünschte IO setzen. Ansonsten sucht FHEM zufällig ein IO aus.

==== hmId bei mehreren IOs ====
Man kann allen IOs die gleiche hmId setzen. Das erlaubt die wahlfreie Umschaltung des Sende-IOs für das Device. Sollte man unterschiedliche hmIds wählen, simuliert dies mehrere Zentralen. Das Device, an das man sendet, muss über ein IO angesprochen werden, mit einer hmId, auf die das Device gepairt ist.

=== Virtueller Controller VCCU ===
Speziell wenn mehrere IOs verwendet werden sollen, empfiehlt sich die Verwendung einer [[Virtueller Controller VCCU|VCCU]], da eine redundante Nutzung mehrerer Schnittstellen dann wesentlich einfacher einzurichten ist. Das Einrichten einer VCCU lohnt sich aber schon bei der Benutzung nur eines HomeMatic I/O, also wenn man z.B. nur einen HMLAN Konfigurator einsetzen will. Zum Einen ist es wesentlich einfacher ggf. später weitere Schnittstellen dazu zu konfigurieren, zum Anderen adressiert die VCCU die auch bereits bei einer Schnittstelle auftauchenden Probleme wie die "<code>Unknown code</code>" Meldungen im Log.

Die Einrichtung einer VCCU ist nicht sehr aufwändig und wird dringend empfohlen.

=== Attribute ===
* '''hmId''': Adresse, die das IO auf der Funkstrecke nutzt. Siehe [[HomeMatic_Devices_pairen#hmId]].
* '''hmKey, hmKey2..3''': bis zu 3 AES keys, die auf der Funkstrecke genutzt werden. Siehe [[AES Encryption]]
* '''hmLanQlen''' legt fest, wie viele Nachrichten parallel gesendet werden dürfen, also auf wie viele Antworten die Zentrale parallel warten darf. Ein Wert von 1 ist max defensiv, erzeugt aber eine höhere Verzögerung. Wählt man einen höheren Wert kann es zu Nachrichten-Wiederholungen kommen.
* '''hmProtocolEvents''': alle Nachrichten werden dekodiert ausgegeben. Diese Einstellung benötigt einige Performance insbesondere bei höherem Level. Man sollte es vorsichtig nutzen.
* '''logIDs''': zeichnet Rohmessages auf und bietet die genaueste Methode bei der Fehlersuche. Da Nachrichten undekodiert ausgegeben werden, ist es im Wesentlichen für Spezialisten von Bedeutung. Man gibt eine Komma-getrennte Liste von IDs an, die geloggt werden sollen. Mit '''all''' werden alle IDs aufgezeichnet. '''sys''' zeichnet zusätzlich Systemmessages auf. '''sys,all''' somit alles.
* '''respTime''': Antwortzeit des HMLAN auf ein keep-alive kann hier eingestellt werden. Normalerweise sollte das HMLAN innerhalb einer Sekunde der Zentrale antworten. Sollte dies nicht passieren, wird die Message wiederholt. Der Wert sollte nur in Ausnahmefällen verändert werden.

=== Readings ===
* '''Xmit-Events''': Anzahl der Ereignisse
* '''cond''': aktueller Zustand des IO.
** ok
** Warning-HighLoad: 90% der 1h Sendekapazität sind erreicht
** ERROR-Overload: 100% der Sendekapazität sind erreicht, '''das IO sendet nicht mehr'''
** timeout
** disconnected: die Verbindung FHEM / IO ist unterbrochen
** Overload-released: das IO ist aus ERROR-Overload zurück im Sendebetrieb
** init: Das IO wurde neu initialisiert.
* '''prot_ERROR-Overload''': Anzahl des Events, Zeitstempel des letzten Auftretens
* '''prot_Warning-HighLoad''': Anzahl des Events, Zeitstempel des letzten Auftretens
* '''prot_disconnected''': Anzahl des Events, Zeitstempel des letzten Auftretens
* '''prot_init''': Anzahl des Events, Zeitstempel des letzten Auftretens
* '''prot_ok''': Anzahl des Events, Zeitstempel des letzten Auftretens
* '''prot_timeout''': Anzahl des Events, Zeitstempel des letzten Auftretens

=== Internals ===
* '''XmitOpen''': 1 = HMLAN ist sendebereit
* '''assignedIDs''': hmIds der HM Devices, die über dieses IO bedient werden
* '''assignedIDsCnt''': Anzahl der zugewiesenen hmIds von FHEM
* '''assignedIDsReport''': Anzahl der hmIds, die das HMLAN angibt zu bedienen. Die Zahl sollte identisch sein mit assignedIDsCnt
* '''msgKeepAlive''': dlyMax: maximale Verzögerung, die ein keep-alive hatte. bufferMin: der minimale Zeitpuffer, der übrig blieb, bis das keep-alive zu spät gekommen wäre. Der Puffer sollte 2 oder größer sein, sonst könnte man gelegentlich disconnects bekommen.
* '''msgLoadEst''': Funkbelastung des HMLAN. Der Wert wird über 1 Stunde akkumuliert. Sollten 100% erreicht sein, wird das HMLAN den Sendebetrieb einstellen. Der Wert ist eine Hochrechnung in FHEM. Es ist möglich, dass das HMLAN mehr belastet ist. Die 10 min Werte zeigen die Belastung in den letzten 10min Perioden an.
* '''msgParseDly''': Verzögerung der Message Verarbeitung vom Empfang im IO bis zur Verarbeitung in FHEM, gemessen in Millisekunden. Eine Verzögerung kann durch Prozesse an LAN, durch FHEM Prozesse oder sonstige Prozesse/Applikationen der CPU hervorgerufen werden.

== Pairen von Geräten ==
Jedes HM Gerät muss vor Verwendung mit der HM-Zentrale [[Pairing (HomeMatic)|gepairt]] werden. Hierfür ist Wahl einer hmId nötig (alle Details siehe [[HomeMatic_Devices_pairen#hmId]]).
Alle Geräte haben eine eigene Seriennummer, die nicht änderbar ist. Details zum Pairen auf der Seite [[HomeMatic Devices pairen]].

== Bekannte Probleme ==
=== Verbindung wird abgelehnt ===
Selten lehnt der HMLAN-Adapter ohne erkennbaren Grund nach monatelangem störungsfreiem Betrieb die Verbindung ab:
<pre style="width:400px;">
Opening HMLAN1 device 192.168.168.60:1000
192.168.168.60:1000 connection refused
</pre>
Der HMLAN-Adapter kann aber über die mitgelieferte Konfigurationssoftware problemlos erreicht werden. Der Zustand lässt sich auch durch einen Reboot des HMLAN-Adapters (oder FHEM) nicht beheben, wohl aber durch eine Aktualisierung der Firmware des HMLAN-Adapters, '''selbst wenn die installierte Version aktuell ist'''.

=== Homematic-Geräte-Konfigurationsprogramm verbindet sich nicht mit LAN-Adapter ===
Damit das Konfigurationsprogramm auf den LAN-Adapter zugreifen kann, muss das FHEM-Modul deaktiviert werden. (Attribute dummy=1 oder FHEM herunterfahren) Hat das Konfigurationsprogramm trotzdem Probleme, den LAN-Adapter zu finden, sollten vorübergehend alle bis auf das aktuell genutze Netzwerkinterfaces deaktiviert werden. Unter Windows 7 reicht es eventuell nicht, die Netzwerkverbindungen im "Netzwerk- und Freigabecenter" zu deaktivieren, sondern die Netzwerkadapter müssen auch im Gerätemanager deaktiviert werden.

Unter Windows 10 scheint das Programm nicht mehr zu funktionieren. Der Konfigurationsadapter wird nicht gefunden. Auch nicht bei deaktivierten Netzwerkverbindungen.

=== Häufiger automatischer Neustart ("Reboot") ===
Der HMLAN Adapter startet ohne erkennbaren äußeren Anlass häufig neu. Das Problem ist auch im Forum unter der Überschrift {{Link2Forum|Topic=20776|LinkText=HMLAN Adapter wechselt permanent zwischen disconnected / connected}} beschrieben. Im FHEM Log erscheinen in diesem Fall folgende Meldungen:
<pre style="width:600px;">
... HMLAN_Parse: myHMLAN new condition timeout (je nach Timing, manchmal)
... HMLanHostname:1000 disconnected, waiting to reappear (myHMLAN)
... HMLAN_Parse: myHMLAN new condition disconnected
... HMLanHostname:1000 reappeared (myHMLAN)
... HMLAN_Parse: myHMLAN new condition init
... HMLAN_Parse: myHMLAN new condition ok
</pre>
Dieses Problem ist bei ELV [http://www.elv.de/topic/hm-lan-reboots.html bekannt] und soll mit der [http://www.eq-3.de/Downloads/Software/Konfigurationsadapter/Konfigurationsadapter_LAN/HM-CFG-LAN_Usersoftware_V1_520_eQ-3_151207.zip Konfigurationsadapter LAN Usersoftware V1.520 (10.12.2015)], bzw. der darin enthaltenen Firmware Version, behoben sein. Stand 05.08.2016 12:32 Auch mit der aktuellen Firmware (v0.965 - Link siehe oben) und der aktuellen Version von HMLAN (Rev 11645 vom 2016-06-11) tritt der Fehler noch auf.

=== Kompletter und/oder sporadischer Totalausfall ===
Sollten die oben genannten softwareseitigen Problemlösungen zu keinem erwünschten Ergebnis führen, kann gegebenenfalls ein Austausch der verbauten Elektrolytkondensatoren (Elkos) Abhilfe schaffen.<BR>
Zumindest ist dies eine Alternative zur Verschrottung. <BR>
Siehe Forumsbeitrag https://forum.fhem.de/index.php/topic,62442.msg538982.html#msg538982<BR>

== Verbesserung der Antennenleistung ==
Die Sende- und Empfangsleistung kann man verbessern.

Ein relativ einfache Methode ist, die Antenne aus dem Gehäuse herauszuführen. Dies bringt in der Regel bereits einen spürbar verbesserten RSSI und eine verminderte Einstrahlung der Elektronik in die Antenne. Als Kosten fallen der Kaufpreis des 5er TORX an, der üblicherweise nicht vorhanden ist und ca. 6 € kostet (es ist u.U. empfehlenswert, gleich ein ganzes Kombi-Set für Handy-Reparatur etc. zu kaufen).

* HM-CFG-LAN aufschrauben. Innen sieht er so aus:

[[Datei:HM-CFG-LAN Innen.jpeg]]

Der schwarze Draht im oberen Bereich unter den Lichtleitern ist die Antenne.

* Lichtleiter entfernen (Bleibt machmal auch im Deckel hängen)

[[Datei:HMLAN Antenne.JPG]]

Rechts ist das Funkmodull zu erkennen, der schwarze Draht ist die Antenne. Es ist gut zu sehen, dass die Antenne sehr nahe an der Elektronik ist, die HF-Signale in die Antenne einstrahlt und die Empfangsleistung dadurch vermindert.

* Das Gehäuse an passender Stelle mit einer kleinen Feile oder einem Drehmel oder ähnlich einkerben.

[[Datei:HMLAN schlitz.JPG]]

* Die Antenne einfach nach aussen biegen. Der Winkel ist egal, und kann später durch die Positionierung des HM-CFG-LAN optimal eingestellt werden. Der Draht sollte aber gerade sein, also keinen Knick oder keine Krümmung haben.

[[Datei:Antenne nach aussen.JPG]]

Man kann die Antenne auch verlängern, sinnvoll ist aber nur eine Verdopplung (von L/4 auf L/2). Geringere Verlängerungen verschlechtern die Leistung.

* Gehäuse wieder zusammenbauen und zuschrauben, fertig.

[[Datei:HMLANAntenneextern.JPG]]

Dieser Umbau (ohne Antennenverlängerung) bringt in der Regel einen um 4-5 Zähler verbesserten RSSI und verringert die Einstrahlung der Elektronik. Dies ist nur der einfachste Schritt eines Antennenumbaus. Mit nur wenig mehr Aufwand lassen sich wesentlich bessere Ergebnisse erzielen.

Links zu weitergehenden Maßnahmen [[Trick_der_Woche#HM_LAN_Konfig-Adapter_Antenne_verbessern|hier]].

== Wechsel von CUL zu HMLAN ==
{{Randnotiz|RNTyp=y|RNText=Der hier beschriebene Wechsel sollte mittlerweile einfacher über die [[Virtueller Controller VCCU|VCCU]] realisierbar sein, indem erst ein weiteres IO-Device hinzugefügt und anschließend das zu ersetzende entfernt wird.}}
Sollten ein [[CUL]] als IO für HomeMatic-Geräte dienen und ein Wechsel auf den HMLAN Konfigurator geplant sein, kann die folgende Vorgehensweise gewählt werden:

* deaktivieren Sie das CUL in der ''fhem.cfg''.
* konfigurieren Sie den HMLAN Konfigurator '''von Hand'''
* Ändern Sie das Attribut IODev aller HM-Devices vom Namen der CUL auf den Namen des HMLAN
* sollten Sie das Attribut IODev nicht nutzen (nicht empfohlen), achten Sie darauf, dass im fhem.cfg das IO vor allen HM-devices definiert wird. Eine automatischen Zuweisung des IO zu den Devices ist sonst nicht möglich.
** der HMLAN '''muss''' die gleiche ''hmId'' wie das bisherige CUL erhalten. Ansonsten müssen alle Geräte neu gepairt / angelernt werden.
** AES muss im HMLAN abgeschaltet werden.
* verbinden Sie den HMLAN Konfigurator mit ihrem Netzwerk und ziehen das CUL aus der USB-Buchse.
* geben Sie in der FHEM-Befehlszeile ''shutdown restart'' gefolgt von <Enter> (nicht "save") ein (evtl. reicht auch ein ''rereadcfg'').
* kontrollieren Sie im Event-Monitor und in den HM-Device-Logs von FHEM die Kommunikation.

Bitte beachten: Falls dem CUL keine explizite hmId per Attribut zugewiesen wurde, wird diese ID aus "F1<FHT-ID>" zusammengebaut. Die hmId muss auf dem HMLAN explizit gesetzt werden.

== Deregistrierung (Unpair) der Geräte ==
Manche Homematic Geräte lassen sich nur dann am neuem Gateway anlernen wenn die zuerst vom altem abgelernt wurden. Dies wird zum Beispiel beim Umzug auf ccu3 gebraucht. Dies wird insbesondere durch nicht immer funktionierende Konfigurationssoftware erschwehrt.

Vorgehensweise:
- FHEM GUI in 2 tabs öffnen - 1 für das abzulehrnendes Gerät, zweites für HMLAN.
- Ein set unpair an das Gerät absetzen und warten bis der Status vom CMD_pending wechselt, dabei fängt meistens die Orange LED zu blinken wie bei Factory reset (das abholen der Befehle kann durch das drücken der Knöpfe am Gerät meistens beschleunigt werden.
- Sobal das unpair und Reset am Gerät angelaufen ist, muss der HMLAN auf close mit "set close" gesetzt werden, damit wird verhindert, das das Gerät neu gepaired wird.
- Jetzt kann das Gerät an en anderes Gateway (z.b. ccu3) neu angelernt werden.

== Links ==

* [http://www.eq-3.de/service/downloads.html Software] für den Konfigurationsadapter von der eQ-3 Site
* [https://download.microsoft.com/download/d/d/9/dd9a82d0-52ef-40db-8dab-795376989c03/vcredist_x86.exe Download] für das Microsoft Visual C++ 2008 SP1 Redistributable Package (x86)
* [[Trick_der_Woche#HM_LAN_Konfig-Adapter_Antenne_verbessern|HM LAN Konfig-Adapter Antenne verbessern]]

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

DbLog

2021-04-08T10:52:15Z

Rosti: /* Beispiel: Anlegen und Nutzung einer Mysql-Datenbank - Partitionierung hinzugefügt*/

{{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 wirklick 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]]

;Hinweis:
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 ===
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!
chown fhem:dialout /opt/fhem/db.conf

=== 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, das File 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):
<pre>
# 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
</pre>

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</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 1 File erzeugt statt einem gemeindamen File 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 ''/var/www/html/fhemdb.php'' und ist mit ''<IP>/fhemdb.php'' aufrufbar. Wenn ihr den 2. 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 insb. auch dann hilfreich, wenn man eigenen 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]]

[[Kategorie:Logging]]