1. Datenlücken statt „Wert unverändert“

Wenn eine Datenquelle zeitweise ausfällt (offline, Verbindung nicht da) oder keine Daten liefert, behält das Item derzeit einfach seinen letzten Wert. Ohne Korrekturen wird dieser Wert für die gesamte Zeitspanne in der Datenbank gespeichert. Neben verfälschten Berechnungen haben auch Plots/Graphen dabei durchgehende Linien, obwohl ggf. keine Daten vorlagen.

Das ist ein altes Thema, über das in den Issues schon viel diskutiert wurde, und es gibt eine Lösung. Genaugenommen – zwei. item.db_mark_invalid() / item.db_mark_valid().

# Verbindung verloren
sh.solar.leistung.db_mark_invalid(caller='solar_plugin', source='connection_lost')

# Verbindung wieder da
sh.solar.leistung.db_mark_valid(caller='solar_plugin', source='connection_restored')
sh.solar.leistung(neuer_wert, 'solar_plugin')

Wichtig dabei: das passiert nicht von allein. Das jeweilige Plugin muss den Ausfall selbst erkennen und db_mark_invalid() aktiv aufrufen. Unterstützt ein Plugin das (noch) nicht, bleibt der letzte Wert wie bisher einfach unverändert stehen. Aktuell macht das noch kein Plugin von Haus aus – Gateway-Plugins wie MQTT (Verbindung zum Broker verloren) oder KNX (Bus-Timeout, knxd nicht erreichbar) wären die ersten Kandidaten, die ich in absehbarer Zeit angehen möchte. Wer Lust hat, das für sein Lieblings-Plugin nachzurüsten: immer her damit.

Neu und ohne Plugin-Unterstützung nutzbar: das Item-Attribut database_invalid_after. Bekommt ein Item über die angegebene Zeitspanne keine Änderung/kein Update, wird automatisch eine Lücke geöffnet:

solar:
    leistung:
        type: num
        database: init
        enforce_updates: true
        database_invalid_after: 10m

enforce_updates muss gesetzt sein, sonst zählt ein unverändertes Update nicht als Lebenszeichen. Und: das ist nur für Items sinnvoll, die ohnehin regelmäßig aktualisiert werden (cycle/crontab o.ä.) – bei unregelmäßig/ereignisgesteuert aktualisierten Items gibt’s sonst nur Fehlalarme.

Sobald wieder ein Wert gesendet wurde, wird automatisch db_mark_valid() aufgerufen und die Werte „zählen“ wieder.

Lückeneinträge werden bei avg/sum/integrate/on/min/max automatisch ausgeschlossen, tauchen bei Rohwertabfragen als NULL (aus der Datenbank) auf (für Lücken in Plots), und lassen sich im Webinterface pro Datensatz auch manuell setzen/zurücknehmen.

Beispiel: KNX-Item und MQTT-Item

Zwei Items, zwei Transportwege, aber beide mit demselben eigentlichen Risiko: die Verbindung zur Außenwelt kann abreißen, ohne dass shng selbst oder das jeweilige Plugin davon groß Notiz nimmt – Telegramme bzw. Nachrichten bleiben einfach aus:

heizung:
    vorlauftemperatur:
        type: num
        database: init
        knx_dpt: 9
        knx_listen: 1/2/3
        enforce_updates: true
        database_invalid_after: 15m

garage:
    aussentemperatur:
        type: num
        database: init
        mqtt_topic_in: garage/aussentemperatur
        enforce_updates: true
        database_invalid_after: 3m

heizung.vorlauftemperatur kommt vom Sensor selbst zyklisch (in ETS am Gerät eingestellt, z.B. alle 5 Minuten senden, unabhängig von einer Wertänderung) – komplett unabhängig von shngs eigenem Scheduler. Fällt knxd aus oder bricht die Verbindung zum Bus ab, bleiben die Telegramme einfach aus. Das KNX-Plugin selbst muss dabei nicht abstürzen oder für dieses eine Item einen auffälligen Fehler werfen – andere Items mit zwischenzeitlich gecachten Werten sehen auf den ersten Blick unauffällig aus. Genau diesen Fall fängt database_invalid_after ab, ohne dass jemand ins Log schauen muss.

garage.aussentemperatur kommt per MQTT rein, mit demselben Prinzip: viele Sensoren (Zigbee2MQTT, Tasmota, …) senden zyklisch, unabhängig davon ob sich der Wert geändert hat – hier alle 60s angenommen, daher 3m als Schwelle. Bleibt der Sensor tot oder der Broker weg, bleibt auch das MQTT-Update aus, ohne dass shng selbst etwas falsch macht.

Ein rein shng-internes cycle+eval-Item wäre dagegen kein gutes Beispiel: solange shng überhaupt läuft, feuert dessen Scheduler garantiert, und stünde der Scheduler wirklich still, würde auch die Prüfung selbst (invalid_check_cycle) nicht mehr laufen – es gäbe also niemanden mehr, der Alarm schlagen könnte.

Der Haken liegt nicht bei MQTT als Transportweg, sondern bei Quellen, die nur bei Zustandsänderung senden – klassisch Tür-/Fensterkontakte, viele Taster. Da ist „seit 30 Minuten kein Update“ der absolute Normalfall, wenn eben nichts passiert ist, kein Ausfall. database_invalid_after ist nur sinnvoll, wenn die Quelle nachweislich regelmäßig sendet – egal ob per MQTT, KNX oder sonstwie -, und die Schwelle muss zu genau diesem Intervall passen, nicht zu einer geschätzten „sollte doch mal was kommen“-Zeit.

Das Risiko bei Fehlkonfiguration – falscher Itemtyp ohne regelmäßige Updates, oder zu kurz gewählte database_invalid_after-Zeit – sind Zeiträume, die in der Datenbank als „nicht vorhanden“ eingetragen sind, obwohl eigentlich ein gültiger Wert vorlag. Das fällt seinerseits nur auf, wenn man es regelmäßig auf Plots überprüft.

2. Aggregierung statt Löschen – die Optionen im Überblick

database_maxage ist ein bekanntes Item-Attribut und löscht alte Werte ersatzlos. Über database_maxage_action lässt sich jetzt stattdessen ein „Ersatzwert“ zu einem Intervall verdichten:

Das läuft komplett Python-seitig im Plugin, identisch auf SQLite3, MySQL/MariaDB und PostgreSQL. Wer zusätzlich zum Mittelwert auch Min/Max eines Intervalls dauerhaft behalten will, kann dafür die mitgelieferten Structs database.min/database.max nutzen (legen automatisch eigene Kind-Items mit den jeweiligen Werten an).

Beispiel: vier Items, vier verschiedene Konfigurationen

In den Konfigurationen fehlen die eigentlichen Datenquellen, die darf sich jeder dazu denken.

# plugin.yaml
database:
    plugin_name: database
    driver: sqlite3
    default_maxage_interval: 24h

# items/beispiel.yaml
wohnzimmer:
    temperatur:
        type: num
        database: init
        database_maxage: 90
        database_maxage_action: avg
        database_maxage_interval: 1h

pv:
    leistung:
        type: num
        database: init
        database_maxage: 365
        database_maxage_action: integrate
        database_maxage_interval: 1d

haustuer:
    kontakt:
        type: bool
        database: init
        database_maxage: 30
        database_maxage_action: countall

heizung:
    status:
        type: str
        database: init
        database_maxage: 14
        database_maxage_action: last
        database_maxage_interval: 6h

• wohnzimmer.temperatur: nach 90 Tagen werden die Rohwerte je Stunde zu einem Mittelwert verdichtet – Langzeitverlauf bleibt Jahre erhalten, die minütlichen Rohdaten nicht.
• pv.leistung: nach einem Jahr wird aus der Momentanleistung je Tag die tatsächlich erzeugte Energie integriert – klassischer Fall für integrate.
• haustuer.kontakt: setzt kein eigenes database_maxage_interval – fällt auf den Plugin-Parameter default_maxage_interval: 24h zurück. Nach 30 Tagen bleibt pro Tag nur noch die Anzahl der Türöffnungen übrig.
• heizung.status: ein str-Item – hier funktionieren avg/sum/etc. nicht, aber last schon. Nach 14 Tagen bleibt je 6h-Intervall nur noch der letzte bekannte Status übrig.

Effekt in der Praxis: Die Kompaktierung läuft im selben Zyklus wie das bisherige Löschen (removeold_cycle) und arbeitet sich – genau wie das – in begrenzten Schritten durch alte Daten (max_aggregate_intervals), pro Item. Bei vier Items mit doch recht unterschiedlichem Alter blockiert also keines der anderen den Durchlauf.

Ein Punkt, den man im Hinterkopf behalten sollte: Ändert man später bei einem Item mit countall (hier haustuer.kontakt) nachträglich das database_maxage_interval, werden schon kompaktierte alte Intervalle beim nächsten Durchlauf mit in ein neues, anders breites Intervall gezogen – für avg/sum/min/max/integrate/duty_cycle rechnerisch unproblematisch, bei countall zählt ein bereits kompaktiertes Intervall dann aber nur noch als „1“ statt als die ursprüngliche Anzahl Rohwerte. Kein Bug, nur eine Ungenauigkeit, die man bei countall + nachträglicher Intervalländerung kennen sollte.

3. PostgreSQL+TimescaleDB als neues Backend

Neben SQLite3 und MySQL/MariaDB unterstützt das Plugin jetzt auch PostgreSQL, optional mit der TimescaleDB-Erweiterung. Die Treiber-Auswahl ist jetzt auch komfortabler: driver akzeptiert neben den echten Modulnamen (psycopg2/psycopg) auch sprechende Namen wie postgres, postgresql, timescale, timescaledb (und mysql/mariadb statt pymysql) – welches Python-Modul installiert ist, wird automatisch erkannt.

database_timescale:
    plugin_name: database
    driver: timescaledb
    connect:
    -   host:127.0.0.1
    -   port:5432
    -   user:shng
    -   password:shng_password
    -   database:shng

Was TimescaleDB bringt:

• Hypertables – die log-Tabelle wird automatisch in Zeitpartitionen (Dateien für einzelne Zeiträume) aufgeteilt, macht zeitbereichsbasierte Abfragen auf großen Tabellen deutlich schneller.
• Native Kompression (timescale_compress: true) – TimescaleDBs eigene Doku nennt 10-20x (90-95% Speicherplatzersparnis) als üblich für Zeitreihendaten; im eigenen Test gegen einen echten 22-Millionen-Zeilen-Datensatz kamen 17,39x raus.
• Native Aggregation (timescale_native_aggregation: true) – statt Python-seitiger Aggregierung übernimmt TimescaleDB das über Continuous Aggregates, direkt auf dem Server. Dieselben Item-Attribute (database_maxage_action etc.) steuern das weiterhin.
• Native Retention (timescale_native_retention: true) – alte Rohdaten-Zeitpartitionen werden automatisch server-seitig fallengelassen statt Item für Item gelöscht.

Und die Nachteile, ehrlich gesagt:

• Mehr Aufwand als SQLite3 (extra Server, extra Python-Paket psycopg2-binary oder psycopg).
• Native Retention ist ein globaler Schwellwert für die ganze Tabelle, kein Wert pro Item mehr – auch Items mit database_maxage_action: delete warten dann auf denselben globalen Schwellwert.
• Wichtig: Items ohne database_maxage sind davon nicht ausgenommen. ALLE Items werden nach der längsten eingestellten Zeit aggregiert – oder gelöscht. Wenn keine default_maxage_action eingestellt ist, werden alle nicht ausdrücklich anders konfigurierten Datenbankwerte der Items gelöscht. Wer native Retention nutzt, sollte default_maxage und default_maxage_action setzen.
• Der Wechsel von nativer Aggregation zurück zu Plugin-Aggregierung ist nicht vorgesehen (nicht implementiert, da alles andere als trivial) und nicht verlustfrei möglich.
• Auch die einmal aktivierte Kompression lässt sich über das Plugin nicht mehr rückgängig machen.

Warum gerade TimescaleDB

Es gibt schon ein InfluxDB-Plugin, und Influx gilt seit Langem als die Referenz für Zeitreihen-Datenbanken. Das Problem mit InfluxDB ist dabei zweierlei: zum Einen hat sich die API mit jeder größeren Version komplett geändert, was ständigen Updateaufwand mit sich bringt und für jede Version ein eigenes Plugin erfordern würde. Zum Anderen ist die aktuelle Open-Source-Linie (InfluxDB 3 Core) explizit als Edge-/Echtzeit-Collector positioniert – Compactor und Optimierungen für Langzeit-Speicherung fehlen, und genau die wären für unseren Stats-/Grafik-Anwendungsfall am wichtigsten. Für brauchbare Abfrage-Performance über die Historie braucht es InfluxDB Enterprise. Es gibt zwar eine kostenlose Hobby-Stufe, aber damit hängt man an einer Hersteller-Lizenzstufe statt an einer eigenständigen Open-Source-Installation – für uns als reines Community-Projekt nicht ideal.

TimescaleDB basiert auf PostgreSQL, einer seit Langem gepflegten, gut getesteten und leistungsfähigen Datenbank, die auf den meisten System problemlos verfügbar ist. Die TimescaleDB-Erweiterung bringt mit der nativen Kompression einen großen Platzvorteil mit (siehe oben, 10-20x laut Timescale, 17,39x im eigenen Test), und die nativen Aggregations- und Retentionsfunktionen entlasten SmartHomeNG von Routineaufgaben, die sonst Python-seitig laufen müssten.

Beispiel: dieselben vier Items, jetzt nativ auf TimescaleDB

An den Items selbst ändert sich nichts – dieselbe Konfiguration wie oben. Nur plugin.yaml bekommt zwei zusätzliche Zeilen:

database_timescale:
    plugin_name: database
    driver: timescaledb
    connect:
    -   host:127.0.0.1
    -   port:5432
    -   user:shng
    -   password:shng_password
    -   database:shng
    default_maxage_interval: 24h
    timescale_hypertable: true
    timescale_native_aggregation: true
    timescale_native_retention: true

Was jetzt passiert: TimescaleDB legt ein Continuous Aggregate je tatsächlich genutzter Intervallbreite an, nicht eines je Item. Die Continuous Aggregates werden intern als virtuelle Tabelle über der log-Tabelle eingeblendet. Bei den vier Beispiel-Items sind das genau drei: 1h (wohnzimmer.temperatur), 6h (heizung.status) und 1d (pv.leistung und haustuer.kontakt über den default_maxage_interval-Fallback teilen sich hier eines, weil beide auf dieselbe Intervallbreite kommen). Die Aggregation selbst läuft weiter pro Item korrekt nach dessen eigener Konfiguration.

Der eigentliche Unterschied, konkret an diesem Beispiel: pv.leistung hat mit 365 Tagen das mit Abstand längste database_maxage. Unter nativer Retention wird genau dieser Wert (plus eine Zeitpartition Sicherheitsspanne) zum einzigen Schwellwert für die gesamte Tabelle. Die Rohdaten von haustuer.kontakt – eigentlich für 30 Tage konfiguriert – bleiben deswegen faktisch bis zu ein Jahr lang liegen, weil TimescaleDB pro Zeitpartition löscht und diese Item-übergreifend geteilt werden. Im Plugin-Modus (Abschnitt 2) würde haustuer.kontakt dagegen zuverlässig nach 30 Tagen kompaktiert. Das ist genau der „globaler statt Item-genauer Schwellwert“-Nachteil von oben, nur diesmal mit echten Zahlen dahinter. Durch die Kompression schrumpft der Platzbedarf für die eigentlich nicht erforderlichen Daten so weit, dass der zusätzliche Speicherplatz in der Praxis kein Problem darstellt. Trotzdem lässt sich dieses Feature optimal nutzen, wenn database_maxage bei allen Items in derselben Größenordnung liegt.

Für die meisten Home-Installationen reicht SQLite3 grundsätzlich aus. Da ich aber gehört habe, wie viele Millionen Zeilen viele Leute im Forum in ihren Datenbanken haben, wird TimescaleDB schon wieder interessant – und sei es nur aufgrund der Kompression, selbst ohne native Aggregation/Retention.

Migration von Datenbanken

Wer bestehende Daten zwischen Backends umziehen will (z.B. SQLite3 → TimescaleDB, oder umgekehrt): dafür gibt’s jetzt tools/db_migrate.py als eigenständiges Skript (läuft nur bei gestopptem SmartHomeNG). Migriert Item- und Log-Daten direkt zwischen zwei beliebigen unterstützten Backends, unterstützt Resume und --dry-run. Aber vorsicht – selbst auf einem schnellen Rechner sollte man für 22 Millionen Zeilen schon gute drei Stunden reine Transferzeit einplanen.

Es gibt zurzeit drei verschiedene Datenbank Plugins:

• database
• sqlite
• sqlite_visu2_8

Wenn Du neu mit SmartHomeNG beginnst, solltest Du das Plugin database verwenden. Das database Plugin unterstützt sowohl MySQL Datenbanken, als auch SQLite Datenbanken. Welcher Datenbank-Typ verwendet wird, wird in ../etc/plugin.yaml konfiguriert.

sqlite und sqlite_visu2_8

Die beiden SQLite Plugins dienen nur der Rückwärts-Kompatibilität für bestehende SmartHomeNG bzw. smarthome.py Umgebungen und werden nicht mehr weiterentwickelt.

Das Plugin sqlite unterstützt smartVISU bis zur Version v2.7.

Zur Unterstützung von smartVISU v2.8 und v2.9 muss das Plugin sqlite_visu2_8 verwendet werden. Das Plugin führt beim ersten Start eine Konvertierung der Datenbank von sqlite auf das sqlite_visu2_8 Format durch. Einen Weg zurück gibt es dann nicht. Es sollte also vorher eine Sicherung der Datenbank Datei ../var/db/smarthome.db durchgeführt werden.

Wichtig: Vor Beginn der Sicherung SmartHomeNG beenden.

Eine Routine zur Konvertierung der Datenbanken der sqlite Plugins zu einer Datenbank für das database Plugin gibt es (noch) nicht.

Es existiert ein neues InfluxDB Plugin für SmartHomeNG, das es ermöglicht Meßwerte in eine Influx Datenbank zu schreiben. Die Influx Datenbank wurde entwickelt als quasi eine SQL-ähnliche Datenbank für zeitabhängige Meßreihen. Viele Nutzer des Smarthome.py bemängelten, das eine RRD Datenbank einfach Werte ausdünnt im Laufe der Zeit und andererseits der Ansatz mit der SQLite nicht genau genug ist.

Achtung: Debian Jessie (8.x) Die neueren Linux Versionen setzen zunehmend auf systemd. Start/Stop Skripte werden nicht mehr gebraucht. Diese Anleitung berücksichtigt den systemd derzeit nicht.

Vorbedingung

Die folgende Anleitung geht davon aus, das ein stabiles System vorliegt mit Ubuntu 14.04.3 oder Debian als 64-bit Variante. Ihr könnt testen, welches System bei Euch installiert ist mit:

uname -i

Das ergibt für ein 64 Bit System x86_64. Alternativ geht auch

getconf -a | grep LONG_BIT

(Alternativ kann man auch die Sourcen für InfluxDB holen und eine 32 Bit Version bauen. Allerdings sprengt das den Rahmen dieses How-to.

Für alle weiteren Installationsschritte nutzen wir eine Root Shell

sudo -i

Nun installieren die InfluxDB Datenbank mit

wget https://s3.amazonaws.com/influxdb/influxdb_0.9.4.1_amd64.deb
dpkg -i influxdb_0.9.4.1_amd64.deb

Jetzt muß Influx noch einmalig gestartet werden:

/etc/init.d/influxdb start

Damit das Plugin später auch Daten in eine Datenbank schreiben kann, legen wir eine Datenbank an. Dazu startet wir das influx command line interface:

/opt/influxdb/influx

Um die existierenden Datenbanken aufzulisten, geben wir das Kommando SHOW DATABASES ein. Da wir frisch installiert haben, sollten lediglich name und _internal gelistet werden. Nun erstellen wir eine neue Datenbank mit CREATE DATABASE smarthome

Installieren des InfluxDB Python Clients

pip install influxdb

Installieren des Plugins

Am einfachsten ladet ihr Euch das Plugin als ZIP runter und kopiert den Inhalt in ein neues Unterverzeichnis /smarthome.py/plugins/influx

Konfiguration des Plugins

plugin.conf

influxdb:
    class_name: InfluxDB
    class_path: plugins.influx
#   influx_host: localhost
#   influx_port: 8083
#   influx_user: root
#   influx_pass: root
#   influx_db: smarthome
    influx_keyword: influx

Der Eintrag influx_keyword legt fest, welche Daten in die Datenbank geschrieben werden. Ihr könnt entweder z.B. influx wählen und dann würde dieses item in die Datenbank geschrieben werden:

Vorlauftemperatur:
    name: Vorlaufemperatur
    type: num
    knx_dpt: 9
    influx: true
    visu_acl: rw
    knx_init: 8/1/1
    cache: on

Eine Superidee des Entwicklers ist es jedoch als influx_keyword nun sqlite auszuwählen, dann werden alle Daten die in die SQLite Datenbank geschrieben werden zugleich auch in die Influx Datenbank geschrieben.

Nun müßt ihr noch smarthome.py neu starten, damit das Plugin auch genutzt wird.

Installieren von Grafana

Damit die Daten nun auch hübsch präsentiert werden können, installieren wir uns noch ein grafisches Frontend Grafana.

Wir nutzen wieder unsere Root Shell und erweitern unsere Liste für Repositories:

sudo -i
nano /etc/apt/sources.list

Dorthin idealerweise ganz unten einfügen:

deb https://packagecloud.io/grafana/stable/debian/ wheezy main

Jetzt müssen wir noch den Schlüssel holen damit wir signierte Packages installieren können:

curl https://packagecloud.io/gpg.key | sudo apt-key add -

Nächste Schritte sind aktualisieren der APT Datenbank und installieren von grafana

apt-get update
apt-get install grafana

Details der Grafana Installation:

Programm zu finden in /usr/sbin/grafana-server Das Init.d Skript liegt unter /etc/init.d/grafana-server, eine defaults Datei mit Umgebungsvariablen findet sich in /etc/default/grafana-server und eine Konfigurationsdatei in /etc/grafana/grafana.ini. Weiter gibt es noch ein Logfile zu finden unter /var/log/grafana/grafana.log und eine SQLite3 Datenbank als Basis für Grafana wird installiert unter /var/lib/grafana/grafana.db. Falls systemd vorhanden wird noch ein service installiert mit Namen grafana-server.service

Jetzt gilt es den Grafana Server zu starten mit

service grafana-server start

Jetzt könnt ihr auf den Grafana Server zuzugreifen mit der IP-Adresse und Port 3000. Benutzer und Passwort sind admin.

Damit der Grafana Server bei jedem Systemstart mitstartet, müssen wir ihn noch eintragen:

update-rc.d grafana-server defaults 95 10

So, nun sollte das ganze funktionieren. Bevor ihr an das Frontend vom Grafana geht, solltet ihr erstmal ein wenig Daten sammeln.

Datenverbindung zur Influx Datenbank

Wie oben müßt ihr mit Eurem Browser nun auf Port 3000 auf den Grafana Server zugreifen. Dort könnt ihr Euch dann mit Benutzer admin und Passwort admin anmelden. Der nächste Schritt ist die Einrichtung der Datenverbindung. Dazu wählt ihr Data Sources aus und dann oben in der Leiste Add New. Danach gebt Ihr als Name influxdb ein und als Type influxDB 0.9.x; den Haken bei default setzt man zweckmäßigerweise auch. Bei den http-Settings gebt Ihr diehttp://<IP>:8086, Access auf direct. Bei den InfluxDB Details als Datenbank smarthomemit User = root und Passwort root. Jetzt sollte Test Connection erfolgreich sein. Mit Klick auf Save seid Ihr jetzt einsatzfähig.

Erstes Dashboard anlegen

Ihr klickt jetzt auf Dashboards und anschließend auf Home. Weiter unten könnt Ihr nun +Newauswählen um ein neues Dashboard zu erzeugen. Wenn das geschehen ist, gibt es ein kleines grünes Rechteck. Darauf klickt ihr und dann weiter auf Add Panel und im Submenü Graph. Jetzt erscheint ein leeres Feld mit einem roten Ausrufezeichen in der oberen linken Ecke und einer Überschrift no title (click here). Darauf klickt ihr nun und wählt aus dem Popup Dialog Edit aus.

Unter Metrics ist jetzt eine Abfrage. Dort könnt Ihr – wenn bis dato alles richtig verlaufen ist und schon Werte in der Influx Datenbank zu finden sind – unter FROM select measurement eure erste Datenreihe eintragen. Ein Klick ganz oben auf das Diskettensymbol speichert nun das dashboard. Der Rest geht am besten über ausprobieren. Ein Klick auf den Farbstrich der Datenreihenlegende erlaubt es zu wählen ob die linke oder rechte Achse zur Anzeige genommen und welche Farbe zur Anzeige verwendet wird.

Viel Spaß!

Leitfaden zur Umstellung auf das Database Plugin in Kombination mit MySQL/MariaDB

Motivation

Das Database Plugin setzt auf einer Neuimplementierung der Datenbankanbindung auf, bei der nicht wie beim bisherigen SQLite Plugin alte Daten „aufgeräumt“ werden, sondern jeder Datensatz behalten wird. Dies kann zu sehr großen Datenbeständen führen, für die eine „echte“ Datenbank wie MySQL oder MariaDB sinnvoller ist. Auch können diese Datenbanken mit PhpMyAdmin sehr leicht administriert / betrachtet werden.

Wichtig: Eine Nutzung mit SQLite ist auch weiterhin mit dem Database Plugin möglich, so dass ein Wechsel zu anderen Datenbanken nicht zwingend notwendig ist.

Dieser Leitfaden soll trotzdem dazu dienen, den Umstieg zu erleichtern und motivieren.

Installation von MariaDB

Eine sinnvolle Alternative zu SQLite ist Maria DB (ein Fork von MySQL). Mit dem Database Plugin sind jedoch auch andere Datenbanken mit Kompatibilität zur Python DB API 2 möglich. Auch das klassische MySQL kann verwendet werden.

sudo apt-get update
sudo apt-get install mariadb-server
# alternativ
# sudo apt-get install mysql-server

Die Installationsroutine fordert dabei zur Eingabe eines Passworts für den User „root“ auf. Hier ist darauf zu achten, ein möglichst sicheres Passwort zu wählen.

Einrichtung einer DB und eines DB Users für SmartHomeNG

Als nächstes sollte eine eigene MariaDB Datenbank mit eigenem User für SmartHomeNG erstellt werden, da die Verwendung des Root Users aus Sicherheitsgründen (globale root Rechte) nicht zu empfehlen ist.

Dazu sollte wie folgt vorgegangen werden:

Einloggen in MariaDB als root (befehl „mysql“) mit vergebenem Passwort

mysql -u root -p

Datenbank / User für SmartHomeNG erstellen

In der nun folgenden Shell – jede Zeile mit den jeweiligen Werten befüllen und mit ENTER bestätigen:

CREATE DATABASE smarthome_db;
CREATE USER 'smarthome'@'«ip of your SmartHomeNG server»' IDENTIFIED BY '«password»';
GRANT ALL PRIVILEGES ON smarthome_db.* TO 'smarthome'@'«ip of your SmartHomeNG server»';
FLUSH PRIVILEGES;

Wichtig: Falls die Datenbank auf dem gleichen Server wie SmartHomeNG betrieben wird, muss anstatt der IP die 127.0.0.1 und ggf. localhost via jeweiligen GRANT ALL ... Statements freigegeben werden.

(Optional) Prüfen der Einstellungen:

Auf die Datenbank lokal als root einloggen, mysql -u root -p. Mittels show databases; kann man nun prüfen, ob eine Datenbank namens smarthome_db erstellt wurde. Der neue User ist in der Datenbank mysql in der Tabelle users zu finden:

use mysql;
select Host, User from user;

Im Output sollte nun eine Zeile mit IP des SmartHomeNG Servers und dem User „smarthome“ sichtbar sein.

Die vergebenen PRIVILEGES auf die smarthome_db sind via

select Host, Db, USer from db; 

zu sehen. Auch hier sollten der Username, die IP und die Datenbank auftauchen.

Mit exit geht es zurück zur Shell.

SmartHomeNG und Datenbank auf getrennten Maschinen/IPs

Sind SmartHomeNG und Datenbank getrennt, muss zusätzlich der Eintrag bind-address in der /etc/mysql/my.cnf angepasst werden. Dieser kann entweder auskommentiert werden (jeder Rechner kann mit Angabe von User und Passwort auf die DB verbinden) oder explizit die IP des SmartHomeNG Servers gesetzt werden. Mehrere IPs sind nicht möglich. Soll daher auch vom Datenbank-Server zugegriffen werden (bspw. für ein dort installiertes PhpMyAdmin) hilft nur auskommentieren und das setzen entsprechender Firewall Regeln.

...
[mysqld]
...
# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
#bind-address           = 127.0.0.1 (auskommentiert)
#oder alternativ
bind-address            = «IP des SmartHomeNG Servers»
...

Nach dem Speichern muss der Dienst mit sudo service mysql restart neu gestartet werden.

Vorbereitung des SmartHomeNG Servers für die Nutzung via Database Plugin:

Detaillierte Informationen siehe https://github.com/smarthomeNG/plugins/tree/master/database

Nach erfolgter Installation der Datenbank, muss auf dem SmartHomeNG Server das entsprechende Paket für Python3 installiert werden:

sudo pip3 install --upgrade pymysql

Achtung: Das sehr ähnlich klingende pymsql3 sollte nicht mehr verwendet werden (würde theoretisch mit dem Plugin aber auch funktionieren).

Das Database Plugin wird nun wie folgt in der plugin.yaml eingerichtet:

database:
    plugin_name: database
    driver: pymysql
    connect:
      - 'host:«ip des mariadb/mysql servers»'
      - 'user:smarthome'
      - 'passwd:«passwort des users smarthome»'
      - 'db:smarthome_db'

In den jeweiligen Items muss dann ein database@mysqldb: init erfolgen (oder das alte sqlite: init ersetzen).

Datenkonvertierung von SQLite

Das Datenbank Plugin nutzt intern ein anderes Format als die alte smarthome.db Datenbank. Wenn die Daten weiterhin genutzt werden sollen (historische Daten), dann müssen sie konvertiert werden ins neue Format.

Dazu muß auf der Shell ins SmartHomeNG Basisverzeichnis gewechselt und dann ein Konvertierungsscript aufgerufen werden:

cd /usr/local/smarthome
python3 plugins/database/>convert ./var/db/smarthome.db ... . # gibt es leider noch nicht ;)

todo: Skript schreiben für die Migration

Abschluß

Nachdem die Änderungen an den Items durchgeführt sind und die Konvertierung erfolgt ist, muß SmartHomeNG neu gestartet werden.

Installation der InfluxDB Datenbank

Damit SmarthomeNG Meßwerte loggen kann existiert eine Schnittstelle zur SQLite Datenbank. Als Alternative für umfangreichere Auswertungen und mehr Performance gibt es ein neues Plugin um Meßdaten in eine Influx Datenbank zu schreiben. Die Influx Datenbank wurde speziell entwickelt für Meßwerte mit Zeitstempeln. Sie verfügt über Schnittstellen zu gängigen Programmiersprachen und es gibt eine interaktives Command Line Interface.

Vorbedingung

Die folgende Anleitung geht davon aus, das ein Debian Jessie System als 64-bit Variante vorliegt und damit der systemd benutzt wird um Dienste zu starten und zu beenden. Ihr könnt testen, welches System bei Euch installiert ist mit:

getconf -a | grep LONG_BIT

Das ergibt für ein 64 Bit System LONG_BIT 64.

(Alternativ kann man auch die Sourcen für InfluxDB holen und eine 32 Bit Version bauen. Allerdings sprengt das den Rahmen dieses How-to.

Zunächst der Download der InfluxDB Datenbank mit

wget https://dl.influxdata.com/influxdb/releases/influxdb_0.12.2-1_amd64.deb
sudo dpkg -i influxdb_0.12.2-1_amd64.deb 

Jetzt muß Influx noch einmalig gestartet werden:

sudo systemctl start influxdb.service

Ob die Datenbank nun im Hintergrund läuft, läßt sich prüfen mit

sudo systemctl status influxdb.service

Damit das Plugin später auch Daten in eine Datenbank schreiben kann, legen wir eine Datenbank an. Dazu starten wir das influx command line interface:

influx

Um die existierenden Datenbanken aufzulisten, geben wir das Kommando SHOW DATABASES ein. Da wir frisch installiert haben, sollten lediglich name und _internal gelistet werden. Nun erstellen wir eine neue Datenbank mit

CREATE DATABASE smarthome

Zur Prüfung geben wir erneut das Kommando SHOW DATABASES ein. Das Ergebnis sollte nun sein:

name: databases
---------------
name
_internal
smarthome

>

Mit quit kann das Command Line Interface wieder verlassen werden.

Installieren des InfluxDB Python Clients

Um die InfluxDB mit Python und damit mit SmarthomeNG nutzen zu können, bmuß noch ein passendes Zugriffsmodul installiert werden:

sudo pip3 install influxdb

Installieren des Plugins

In den nächsten Versionen von SmarthomeNG (> V1.1) wird das Plugin sicher Bestandteil des Masters werden. Bis es soweit ist, muss es nachinstalliert werden:

cd /usr/local/smarthome/plugins
mkdir influx
cd influx
wget https://github.com/SgtSeppel/smarthome-influxdb/archive/master.zip
unzip -j master.zip
rm master.zip

Konfiguration des Plugins

plugin.yaml

influxdb:
    class_name: InfluxDB
    class_path: plugins.influx
#   influx_host: localhost
#   influx_port: 8083
#   influx_user: root
#   influx_pass: root
#   influx_db: smarthome
    influx_keyword: influx

Der Eintrag influx_keyword legt fest, welche Daten in die Datenbank geschrieben werden. Ihr könnt entweder z.B. influx wählen und dann würde dieses item in die Datenbank geschrieben werden:

Vorlauftemperatur:
    name: Vorlaufemperatur
    type: num
    knx_dpt: 9
    influx: true
    visu_acl: rw
    knx_init: 8/1/1
    cache: on

Eine Superidee des Entwicklers ist es jedoch als influx_keyword nun sqlite auszuwählen, dann werden alle Daten die in die SQLite Datenbank geschrieben werden zugleich auch in die Influx Datenbank geschrieben.

Nun müßt ihr noch smarthome.py neu starten, damit das Plugin auch genutzt wird.

Wenn nun das Frontend Grafana genutzt werden soll um unabhängig von einer Visu auf dir nun frisch geloggten Daten zuzugreifen, dann bitte bei der Anleitung für Grafana fortfahren.

sql:
    plugin_name: database

Anschliessend wird im Item die Aufzeichnung aktiviert mit ‚database: yes‘ bzw. ‚database: init‘. Nun können weitere Items angelegt werden, die mit Hilfe einer Funktion, die das database-Plugin bereitstellt, die benötigten Werte erhalten.

Das ganze sieht dann in etwa wie folgt aus:

sensor:
    carport:
        temp:
            type: num   
            knx_dpt: 9  
            knx_send: 3/4/11  
            knx_reply: 3/4/11
            ow_addr: '28.52F1AA030000'
            ow_sensor: T 
            database: init  # Aufzeichnung der Daten aktivieren
            min:
                type: num
                knx_dpt: 9
                knx_send: 3/4/14
                knx_reply: 3/4/14
                eval: "sh.sensor.carport.temp.db('min', '28h')"  # Mimium über die letzten 28h berechnen
                eval_trigger: sensor.carport.temp  # Änderungen der Temperatur triggern die Neuberechnung
            max:
                type: num
                knx_dpt: 9
                knx_send: 3/4/15
                knx_reply: 3/4/15
                eval: "sh.sensor.carport.temp.db('max', '28h')"  # Maximum über die letzten 28h berechnen
                eval_trigger: sensor.carport.temp   # Änderungen der Temperatur triggern die Neuberechnung