Die Items

date:

    month:
        since:
            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.month.since.year
                    eval: str(sh.date.month.since.year()) + 'm'

        until:
            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.month.until.year
                    eval: str(sh.date.month.until.year()) + 'm'

    week:
        since:
            month:
                type: num
                cache: 'yes'
            year:
                type: num
                cache: 'yes'
        until:
            month:
                type: num
                cache: 'yes'
            year:
                type: num
                cache: 'yes'

    day:
        since:
            week:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.day.since.week
                    eval: str(sh.date.day.since.week()) + 'd'

            month:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.day.since.month
                    eval: str(sh.date.day.since.month()) + 'd'
            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.day.since.year
                    eval: str(sh.date.day.since.year()) + 'd'

        until:
            week:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.day.since.week
                    eval: str(sh.date.day.since.week()) + 'd'

            month:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.day.until.month
                    eval: str(sh.date.day.until.month()) + 'd'

            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.day.until.year
                    eval: str(sh.date.day.until.year()) + 'd'

    hour:
        since:
            midnight:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.since.midnight
                    eval: str(sh.date.hour.since.midnight()) + 'h'

            week:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.since.week
                    eval: str(sh.date.hour.since.week()) + 'h'

            month:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.since.month
                    eval: str(sh.date.hour.since.month()) + 'h'

            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.since.year
                    eval: str(sh.date.hour.since.year()) + 'h'

        until:
            midnight:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.until.midnight
                    eval: str(sh.date.hour.until.midnight()) + 'h'

            week:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.until.week
                    eval: str(sh.date.hour.until.week()) + 'h'

            month:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.until.month
                    eval: str(sh.date.hour.until.month()) + 'h'

            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.hour.until.year
                    eval: str(sh.date.hour.until.year()) + 'h'

    minute:
        since:
            hour:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.since.hour
                    eval: str(sh.date.minute.since.hour()) + 'i'

            midnight:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.since.midnight
                    eval: str(sh.date.minute.since.midnight()) + 'i'

            week:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.since.week
                    eval: str(sh.date.minute.since.week()) + 'i'

            month:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.since.month
                    eval: str(sh.date.minute.since.month()) + 'i'

            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.since.year
                    eval: str(sh.date.minute.since.year()) + 'i'

        until:
            hour:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.until.hour
                    eval: str(sh.date.minute.until.hour()) + 'i'

            midnight:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.until.midnight
                    eval: str(sh.date.minute.until.midnight()) + 'i'

            week:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.until.week
                    eval: str(sh.date.minute.until.week()) + 'i'

            month:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.until.month
                    eval: str(sh.date.minute.until.month()) + 'i'

            year:
                type: num
                cache: 'yes'
                dbstr:
                    type: str
                    cache: 'yes'
                    eval_trigger: date.minute.until.year
                    eval: str(sh.date.minute.until.year()) + 'i'

    second:
        since:
            minute:
                type: num

            hour:
                type: num

            midnight:
                type: num

            week:
                type: num

            month:
                type: num

            year:
                type: num

        until:

            minute:
                type: num

            hour:
                type: num

            midnight:
                type: num

            week:
                type: num

            month:
                type: num

            year:
                type: num

Die Logik

Als Logik wird unter logics/zeit.py die nachfolgende Datei angelegt.

# /logics/zeit.py
# !/usr/bin/env python3


from lib.shtime import Shtime

sh_now = Shtime.get_instance().now()

# Funktionen

def days_of_month(month, year):
    if month in [1, 3, 5, 7, 8, 10, 12]:
        days = 31
    elif month in [4, 6, 9, 11]:
        days = 30
    elif (year % 400 == 0) or ((year % 4 == 0) and not (year % 100 == 0)):  # Schaltjahr
        days = 29
    else:
        days = 28
    return days

def days_of_year(year):
    period_end = datetime.datetime(year, 12, 31)
    days_of_year = (period_end - datetime.datetime(period_end.year, 1, 1)).days + 1
    return (days_of_year)

def day_of_year(year, month, day):
    period_end = datetime.datetime(year, month, day)
    day_of_year = (period_end - datetime.datetime(period_end.year, 1, 1)).days + 1
    return (day_of_year)

# Sekunde/Minute
sh.date.second.since.minute(sh_now.second)
sh.date.second.until.minute(60 - sh_now.second - 1)

# Minute/Stunde
sh.date.minute.since.hour(sh_now.minute)
sh.date.minute.until.hour(60 - sh_now.minute - 1)

# Stunde/Tag
sh.date.hour.since.midnight(sh_now.hour)
sh.date.hour.until.midnight(24 - sh_now.hour - 1)

# Tag/Woche
sh.date.day.since.week(sh_now.isoweekday())
sh.date.day.until.week(7 - sh_now.isoweekday())

# Stunde/Woche
sh.date.hour.since.week(sh.date.hour.since.midnight() + (24 * (sh.date.day.since.week() - 1)))
sh.date.hour.until.week(sh.date.hour.until.midnight() + (24 * sh.date.day.until.week()))

# Kalenderwoche/Jahr
sh.date.week.since.year(sh_now.isocalendar()[1])
sh.date.week.until.year(52-sh_now.isocalendar()[1])

# Monat/Jahr
sh.date.month.since.year(sh_now.month)
sh.date.month.until.year(12 - sh_now.month)

# Sekunde/Stunde
sh.date.second.since.hour(sh.date.second.since.minute() + (60 * sh.date.minute.since.hour()))
sh.date.second.until.hour(sh.date.second.until.minute() + (60 * sh.date.minute.until.hour()))

# Sekunde/Tag
sh.date.second.since.midnight(sh.date.second.since.minute() + (3600 * sh.date.hour.since.midnight()))
sh.date.second.until.midnight(sh.date.second.until.minute() + (3600 * sh.date.hour.until.midnight()))

# Minute/Tag
sh.date.minute.since.midnight(sh.date.minute.since.hour() + (60 * sh.date.hour.since.midnight()))
sh.date.minute.until.midnight(sh.date.minute.until.hour() + (60 * sh.date.hour.until.midnight()))

# Minute/Woche
sh.date.minute.since.week(sh.date.minute.since.hour() + (60 * sh.date.hour.since.week()))
sh.date.minute.until.week(sh.date.minute.until.hour() + (60 * sh.date.hour.until.week()))

# Sekunde/Woche
sh.date.second.since.week(sh.date.second.since.minute() + (60 * sh.date.minute.since.week()))
sh.date.second.until.week(sh.date.second.until.minute() + (60 * sh.date.minute.until.week()))

# Tage/Monat
sh.date.day.since.month(sh_now.day)
sh.date.day.until.month(days_of_month(sh_now.month, sh_now.year) - sh.date.day.since.month() - 1)

# Wochen/Monat
sh.date.week.since.month((sh.date.day.since.month()-1)//7+1)
sh.date.week.until.month((sh.date.day.until.month())//7)

# Tage/Jahr
sh.date.day.since.year(day_of_year(sh_now.year, sh_now.month, sh_now.day) - 1)
sh.date.day.until.year(days_of_year(sh_now.year) - sh.date.day.since.year() - 1)

# Stunde/Monat
sh.date.hour.since.month((24 * sh.date.day.since.month()) + sh.date.hour.since.midnight())
sh.date.hour.until.month((24 * days_of_month(sh_now.month, sh_now.year)) - sh.date.hour.since.month() - 1)

# Stunde/Jahr
sh.date.hour.since.year((24 * sh.date.day.since.year()) + sh.date.hour.since.midnight())
sh.date.hour.until.year((24 * days_of_year(sh_now.year)) - sh.date.hour.since.year() - 1)

# Minute/Monat
sh.date.minute.since.month((60 * sh.date.hour.since.month()) + sh.date.minute.since.hour())
sh.date.minute.until.month(sh.date.minute.since.month() - (60 * sh.date.hour.until.month()) - 1)

# Minute/Jahr
sh.date.minute.since.year((60 * sh.date.hour.since.year()) + sh.date.minute.since.hour())
sh.date.minute.until.year((60 * sh.date.hour.until.year()) + sh.date.minute.until.hour())

# Sekunde/Monat
sh.date.second.since.month((60 * sh.date.minute.since.month()) + sh.date.second.since.minute())
sh.date.second.until.month((60 * sh.date.minute.until.month()) + sh.date.second.until.minute())

# Sekunde/Jahr
sh.date.second.since.year((60 * sh.date.minute.since.year()) + sh.date.second.since.minute())
sh.date.second.until.year((60 * sh.date.minute.until.year()) + sh.date.second.until.minute())

In der etc/logic.yaml wird sie wie folgt eingebunden:

zeitberechnung:
    filename: zeit.py
    crontab:
        -   init
        -   '* * * *'

Anwendungsbeispiel: Database Plugin

Neben der Anzeige der Daten, macht es vor allem Sinn, die Werte im Zusammenspiel mit (historischen) Datenbank-Daten zu verwenden. Ein Beispiel wäre wie folgt:

consumption_since_midnight:
	type: num
	eval: sh.knx.cellar.utility_room.water_meter.db('count>0', sh.date.minute.since.midnight.dbstr(), 'now')
	eval_trigger: knx.cellar.utility_room.water_meter
	database@mysqldb: init

Im Eval-Ausdruck wird die Anzahl der Werte > 0 ermittelt, die zwischen Mitternacht und dem IST-Zeitpunkt erfasst wurden. Da für 1 Liter jedes Mal ein Impuls mit einer „1“ erfasst wird, erhält man so minutengenau die Anzahl der Liter seit Mitternacht. Die Methode dbstr() in sh.date.minute.since.midnight.dbstr() liefert direkt den Wert, den das Database-Plugin benötigt. Präziser gesagt, hängt sie dem numerischen Wert noch ein „i“ an, so dass die Angabe auf Ebene des Plugins korrekt interpretiert wird.
Über die Methode .db auf dem Item, wird die Datenbankabfrage gestartet. Das Item muss dazu mit dem Database-Plugin verknüpft sein database@mysqldb: init und bereits Daten im abgefragten Zeitraum erfasst haben.

(Das Titelbild ist unter der Creative Commons Zero (CC0) Lizenz veröffentlicht und wurde von www.pexels.com bezogen.)

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.

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.