Allgemeines zur Konfiguration

Die Codebasis von SmartHomeNG ist in der Programmiersprache Python geschrieben. Python ist

kostenlos
einfach zu erlernen
elegant in der Anwendung
objektorientiert
Open-Source-Software
plattformunabhängig (allerdings werden derzeit bei SmartHomeNG Linux-Besonderheiten genutzt so dass z.B. Windows derzeit nur bedingt genutzt werden kann)
multi-threaded

Wichtig für den Einsteiger ist es zu wissen, dass Python peinlich genau auf Einrückungen achtet. Etwas wie

def foo(a):
    bar = a
  d = 5
    x = a
    s = 'text'

führt unweigerlich zu Fehlern. Auch ist ein Mischen von TAB und Leerzeichen oftmals eine Fehlerquelle. Um diese Quellen von Ärgernissen auszuschalten, macht es Sinn einen Editor zu verwenden, den man von vorne herein auf UTF-8 ohne BOM und umwandeln von TAB in 4 Leerzeichen einstellen kann.

Für Konfigurationsdateien gilt analog das Gleiche. Die Konfiguration erfolgt über YAML Dateien. Wichtig für den Einsteiger ist es zu wissen, dass auch YAML peinlich genau auf Einrückungen achtet und das Einrückungen nur durch Leerzeichen erfolgen dürfen. TAB**s sind in YAML Dateien unzulässig. Der Übersichtlichkeit halber wird empfohlen Einrückungen jeweils mit **4 Leerzeichen vorzunehmen.

Passende Editoren für Python und YAML Dateien sind z.B.

Plattform

Editor

Linux

Linux (GUI)

emacs (nano oder vi ginge zur Not auch)

Windows

Mac

Ein guter Editor unterstützt dann auch mit der richtigen Syntaxeinfärbung.

def foo(a):
   bar = a
   d = 5
   x = a
   s = 'text'

Verzeichnisse in SmartHomeNG

Die Verzeichnisse sind im Hauptverzeichnis von SmartHomeNG zu finden, für gewöhnlich im Verzeichnis /usr/local/smarthome`.

Verzeichnis	Beschreibung / Inhalt
`bin`	Hauptmodul von SmarthomeNG
`dev`	Grundgerüst und Infos zur Pluginentwicklung
`doc`	Wird einmal die Dokumentation enthalten
`etc`	enthält mindestens smarthome.yaml, plugin.yaml und logic.yaml. In diesen Dateien befindet sich die Konfiguration des Grundsystems
`examples`	Beispiele für Items
`functions`	In diesem Verzeichnis werden benutzerdefinierte Funktionen (Userfunctions) gespeichert (*)
`items`	Items (*)
`lib`	Modulbibliothek für das Hauptprogramm
`logics`	Jede Logik bekommt hier eine kleine Datei mit Python Code (*)
`plugins`	Modulbibliothek für die Plugins. Jedes Plugin hat sein eigenes Unterverzeichnis
`scenes`	Gespeicherte Szenen (*)
`structs`	Benutzerdefinierte Structs (*)
`tests`	Hilfsprogramme zum Testen von Modulen des Systems
`tools`	enthält Hilfsprogramme
`var`	Daten die vom SmartHomeNG zur Laufzeit gespeichert und gelesen werden also z.B. Logdateien, cache, sqlite Datenbank, etc.

Mit (*) gekennzeichnete Verzeichnisse enthalten die vom Benutzer zu erstellenden/zu ändernden Daten (Konfiguration).

Durch Verwenden der Konfigurationsoption -e bzw. --config_etc wird SmartHomeNG angewiesen, diese Verzeichnisse nicht im Hauptverzeichnis von SmartHomeNG (z.B. /usr/local/smarthome/) zu suchen, sondern im Unterverzeichnis etc. So wären Item-Dateien beispielsweise nicht in /usr/local/smarthome/items/, sondern in /usr/local/smarthome/etc/items/ abzulegen.

Der Vorteil ist, dass sich alle vom Benutzer zu ändernden Daten innerhalb eines Verzeichnisses (mit Unterverzeichnissen) befinden (etc/) und dieses damit einfach nach eigenen Wünschen verwaltet werden kann. Weiterhin wird mit dieser Option die Nutzung der Verzeichnisstruktur stärker an die im Unix-Bereich übliche Aufteilung angepasst - in etc/ befinden sich Konfigurationsdateien (die der Benutzer ändert), in var/ befinden sich Dateien, die durch SmartHomeNG geändert werden, und die restlichen Dateien sind statisch, d.h. im Programmablauf unverändert.

Da bestehende Referenzen aber auf die seit Beginn von SmartHomeNG festgelegten Pfade verweisen, ist diese Konfiguration optional und kein Standard.

Dateien im Verzeichnis ../etc

Während der Installation sind im Unterverzeichnis etc bereits drei Dateien erstellt worden: smarthome.yaml, plugin.yaml und logic.yaml.

smarthome.yaml

In der Datei smarthome.yaml wird notiert, wo sich die Installation befindet und welche Zeitzone als Basis genommen werden soll:

../etc/smarthome.yaml

# smarthome.yaml
lat: '50.123'
lon: '14.67'
elev: 36
tz: Europe/Berlin

# ab Version 1.3
# module_paths = /usr/local/python/lib    # list of path-entries is possible

# ab Version 1.3: control type casting when assiging values to items
# assign_compatibility = latest            # latest or compat_1.2 (compat_1.2 is default for shNG v1.3)

Mit dieser Version können auch zusätzliche Modulpfade konfiguriert werden, in denen Drittanbieter-Bibliotheken abgelegt sind (module_paths Einstellung). Somit können Bibliotheken, beispielsweise in Logiken, verwendet werden die nicht direkt mit ausgeliefert bzw. installiert werden. Es kann ein oder mehrere absolute Pfade angegeben werden.

Außerdem kann der Datentyp einer Wertzuweisung bei der Nutzung von autotimer und cycle beeinflusst werden. Weiterführende Informationen gibt es im Abschnitt Datentyp der Wertzuweisung auf der Seite autotimer

plugin.yaml

Die Datei plugin.yaml enthält die Konfigurationsanweisungen für alle Plugins, die benutzt werden sollen.

../etc/plugin.yaml

# plugin.yaml
knx:
   plugin_name: knx
   host: 127.0.0.1
   port: 6720
#   send_time: 600 # update date/time every 600 seconds, default none
#   time_ga: 1/1/1 # default none
#   date_ga: 1/1/2 # default none
visu:
    plugin_name: visu_websocket
cli:
    plugin_name: cli
    ip: 0.0.0.0
    update: True
sql:
    plugin_name: sqlite_visu2_8

Seit Version 1.2 (Master Branch) gibt es ein neues Plugin (Backend) für SmartHomeNG. Dabei kann man über einen Browser das gleiche (und mehr) erreichen, wie früher über das CLI-Plugin.

Allerdings ist das Plugin inzwischen veraltet und wird in einer der kommenden Versionen von SmartHomeNG entfernt, da es inzwischen ein erheblich leistungsfähigeres Administrationsinterface für SmartHomeNG gibt.

Das Backend Plugin bindet man folgendermaßen ein:

Auszug aus ../etc/plugin.yaml

BackendServer:
    plugin_name: backend
    updates_allowed: True
    user: admin
    password: xxxx
    language: de
    threads: 8
    #ip: 0.0.0.0
    #port: 8383

Die weitere Einrichtung und Konfiguration von Plugins ist unter Plugins beschrieben.

logic.yaml

In der Datei logic.yaml werden die Logiken eingetragen. Der Name jeder Logik kommt zwischen zwei eckige Klammern, der Eintrag filename verweist auf die Python-Datei die dann aufgerufen wird, wenn die Logik abgearbeitet werden soll. crontab schreibt fest, dass die Logik zu bestimmten Zeiten ausgeführt werden soll. watch_item bestimmt, welche Items die Logik aufrufen können:

../etc/logic.yaml

# logic.yaml
InitSmarthomeNG:
    filename: InitSmartHomeNG.py
    crontab: init

Beispiellogik:
    # Umgebungsvariablen des Systems werden aktualisiert, z.B. Diskusage
    filename: Beispiel.py
    watch_item:
    - '*:Logikaufruf'
    - item1.*
    - parent.item2
    # run on start of SmartHomeNG and every 5 minutes afterwards
    crontab:
    - init
    - 0,5,10,15,20,25,30,35,40,45,50,55 * * *

Detaillierte Infos zur crontab Konfiguration finden sich unter crontab Update.

Für die weitere Konfiguration von Logiken geht es unter Logiken weiter.

Weitere Dateien

Zusätzlich sind ab der Version 1.2 auch noch logging.yaml, plugin.yaml.default und smarthome.yaml.default zu finden. Während sich der Inhalt der .default Dateien als Beispieldatei selbst erklärt, ist die logging.yaml noch erklärungsbedürftig: Im gesamten Programmcode sind Anweisungen verteilt, die bestimmte Programmzustände loggen, also mit notieren.

Im einfachsten Fall sind das einfache Meldungen die z.B. den Start eines Plugins melden oder aber das setzen eines Items durch die Visu oder aber das Ausführen einer Datenbank Komprimierung. Es sind aber auch Meldungen dabei, die über Fehler berichten, z.B. wenn ein Item das über die Visu aktualisiert werden soll, gar nicht existiert oder wenn zum Beispiel ein Plugin einen Fehler bei der Abfrage von Daten eines Stromzählers meldet.

Mit der logging.yaml kann man ziemlich fein steuern von welchen Modulen man welche Meldungen bekommen möchte. Sucht man beispielsweise einen hartnäckigen Fehler in einem neuen Plugin Foo, dann kann man das Logging für alle anderen Plugins gezielt reduzieren so das man sich aufs Wesentliche konzentrieren kann.

Weitere Informationen gibt es unter Konfiguration - Logging

Dateien im Verzeichnis ../functions

Hier werden benutzerdefinierte Funktionen (Userfunctions) gespeichert.

Dateien im Verzeichnis ../items

Hier finden sich die Dateien mit den Items. Es ist egal, wie viele Dateien hier abgelegt wurden. Alle Dateien die die Endung .yaml besitzen, werden beim Start von SmartHomeNG gelesen und in die Struktur von SmartHomeNG eingebaut. Eine genaue Beschreibung des Aufbaus findet sich unter eval und eval_trigger .

Aus Gründen der Übersichtlichkeit macht es durchaus Sinn, die .yaml-Dateien nach Räumen oder nach thematischen Gesichtspunkten aufzusplitten und die jeweiligen Items dort zu parametrieren.

Beispielsweise:

eg_kueche.yaml
eg_wohnzimmer.yaml
og_schlafzimmer_eltern.yaml
og_schlafzimmer_ryan.yaml
terrasse.yaml
kwl.yaml
zentralheizung.yaml
…

Wichtig: Wenn eine Item-Datei oder eine Logic-Datei neu erstellt oder geändert worden ist oder ein neues Plugin implementiert werden soll, muss SmartHomeNG neu gestartet werden.

SmartHomeNG kann über die Option -r neu gestartet werden.

cd /usr/local/smarthome
python3 bin/smarthome.py -r

Wenn SmartHomeNG als Dienst eingerichtet ist, kann der Dienst kann über den entsprechenden Befehl „systemctl“ neu gestartet werden.

sudo systemctl restart smarthome.service

Bemerkung

Der Service smarthome.service muss vorher eingerichtet werden. Die Einrichtung ist in der Komplettanleitung unter SmartHomeNG als Dienst update beschrieben.