Logiken
Einführung
Logiken in SmartHomeNG sind in Python geschriebene Skript. Sie werden im Unterordner logics/
abgelegt
und definiert in etc/logic.yaml
.
Die Konfigurationsdatei etc/logic.yaml
beschreibt für SmartHomeNG unter welchen Bedingungen eine bestimmte Logik auszuführen ist.
Die folgende Beispielkonfiguration definiert 4 Logiken:
Die erste Logik mit Namen
InitSmartHomeNG
befindet sich in der Dateilogics/InitSmartHomeNG.py
. Das Attributcrontab: init
weist SmartHomeNG an diese Logik direkt nach dem Start auszuführen.Die zweite Logik mit dem Namen
Hourly
befindet sich in der Dateilogics/time.py
und das Attributcycle: 3600
weist SmartHomeNG an die Logik alle 3600 Sekunden (eine Stunde) auszuführen.Die dritte Logik mit Namen
Gate
befindet sich in der Dateilogics/gate.py
und das Attributwatch_item: gate.alarm
weist SmartHomeNG an die Logik auszuführen, wenn der Wert des Items gate.alarm sich ändert.Die vierte Logik mit Namen
disks
befindet sich in der Dateilogics/disks.py
. Der crontab Eintrag weist SmartHomeNG an diese Logik alle 5 Minuten auszuführen.
InitSmarthomeNG:
filename: InitSmartHomeNG.py
crontab: init
Hourly:
filename: time.py
cycle: 3600
Gate:
filename: gate.py
watch_item: gate.alarm # monitor for changes
disks:
filename: disks.py
# 'crontab: run at start and every 5 minutes'
crontab:
- init
- '0,5,10,15,20,25,30,35,40,45,50,55 * * *'
usage_warning: 500
Konfigurations Parameter
Die folgenden Parameter können genutzt werden um eine Logik und ihre Ausführungsumstände festzulegen:
watch_item
Die Liste der angegebenen Items wird auf Änderungen überwacht
logicnamehere:
watch_item:
- house.alarm
- garage.alarm
Jede Änderung bei den Items house.alarm und garage.alarm löst die Ausführung der angegebenen Logik aus. Es ist möglich einen Stern * für einen Pfadbestandteil zu setzen, ähnlich eines regulären Ausdrucks:
watch_item: '*.door'
Eine Änderung von garage.door oder auch house.door wird die Ausführung der Logik auslösen aber nicht eine Änderung von house.hallway.door
cycle
Sorgt für eine zyklische Ausführung der Logik
cycle: 60
Optional kann ein Argument übergeben werden
cycle: 60 = 100
Dadurch wird die Logik alle 60 Sekunden ausgeführt und der Wert 100 an die Logik übergeben.
Innerhalb der Logik kann auf den Wert über trigger['value']
zugegriffen werden
Seit SmartHomeNG v1.3 gibt es erweiterte Konfigurations Optionen.
Die Zeitspanne für die zyklische Ausführung kann auf zwei Arten angegeben werden:
Eine Zahl die die Zeitspanne in Sekunden angibt, kann optional mit einem
s
gekennzeichnet werden odereine Zahl gefolgt von
m
die eine Zeitspanne in Minuten angibt
crontab
Ähnlich wie Unix crontab mit den folgenden Optionen:
crontab: init
Ausführung der Logik beim Start von SmartHomeNG
crontab: Minute Stunde Tag Wochentag
Siehe Beschreibung von Unix crontab und Online Generatoren für Details
Minute: Wert im Bereich [0…59], oder Komma getrennte Liste, oder * (jede Minute)
Stunde: Wert im Bereich [0…23], oder Komma getrennte Liste, oder * (jede Stunde)
Tag: Wert im Bereich [0…28], oder Komma getrennte Liste, oder * (jeden Tag) Achtung: Derzeit keine Werte für Tage größer 28 nutzen
Wochentag: Wert im Bereich [0…6] (0 = Montag), oder Komma getrennte Liste, oder * (jeden Wochentag)
crontab: sunrise
Startet die Logik bei Sonnenaufgang
crontab: sunset
Startet die Logik bei Sonnenuntergang
Für Sonnenaufgang oder Sonnenuntergang können folgende Erweiterungen genutzt werden:
Ein Offsetwert zum Horizont in Grad. Beispiel
crontab: sunset-6
Dazu muss in der smarthome.yaml Längen und Breitengrad eingestellt sein.Ein Offsetwert in Minuten der durch ein angehängtes m gekennzeichnet wird Beispiel:
crontab: sunset-10m
Eine Beschränkung der Zeit für die Ausführung
Konfiguration mit YAML Syntaxcrontab: '17:00<sunset' # Sonnenuntergang, aber nicht vor 17:00 Uhr (lokaler Zeit) crontab: sunset<20:00 # Sonnenuntergang, aber nicht nach 20:00 (lokaler Zeit) crontab: '17:00<sunset<20:00' # Sonnenuntergang, zwischen 17:00 Uhr und 20:00 Uhr crontab: '15 * * * = 50' # Ruft die Logik mit dem Wert ``50`` auf, also nach Aufruf der Logik hat ``trigger['value']`` den Wert ``50``
Mehrere crontab Einträge können auch als Liste angegeben werden:
crontab:
- init = start
- sunrise-2
- '0 5 * *'
enabled
enabled
kann auf False
gesetzt werden um die Ausführung der Logik auszusetzen
Der Ausführungsstatus der Logik kann über das CLI-Plugin oder das Admin Interface gesetzt werden
prio
Setzt die Priorität der Logik im Kontext des Schedulers.
Jeder Wert zwischen 1
und 10
ist erlaubt mit 1
für die höchste Priorität und 10
die niedrigste.
Im Normalfall ist eine Angabe der Priorität nicht notwendig, die Vorgabe für alle Logiken ohne
Prioritätsangabe ist 5
Andere Parameter
Weitere Parameter können innerhalb der Logik mit self.parameter_name
abgefragt werden.
Im ersten Beispiel ist für die vierte definierte Logik ein Parameter usage_warning: 500
angelegt worden.
Grundstruktur einer Logik
Das wichtigste Objekt einer Logik ist das Smarthome Objekt sh
.
Über dieses Objekt kann auf alle Items, Plugins und Funktionen von SmartHomeNG
zugegriffen werden.
Um den Wert eines Items abzufragen kann zum Beispiel sh.area.itemname()
verwendet werden.
Um dem gleichen Item einen neuen Wert mitzugeben, kann dieser Wert als Argument
übergeben werden sh.area.itemname(new\_value)
#!/usr/bin/env python
# put on the light in the living room, if it is not on
if not sh.living_room.light():
sh.living_room.light('on')
Auf Items muß unter Nutzung von Klammern ()
zugegridden werden sonst wird eine Ausnahme
erzeugt.
sh
kann genutzt werden um über alle Items durchzulaufen:
for item in sh:
print item
for child_item in item:
print child_item
Bereits geladene Python Module
Innerhalb von Logiken sind folgende Python Module bereits geladen:
sys
os
time
datetime
ephem
random
Queue
subprocess
Weitere Module können mit import <modulname>
zusätzlich geladen werden.
Vorhandene Objekte und Methoden
Ausser dem Smarthome Objekt sh
gibt es weitere vordefinierte Objekte und Methoden innerhalb von Logiken
logic
Dieses Objekt bietet Zugriff auf das aktuelle Logik Objekt.
Es ist möglich die Attribute wie crontab
, cycle
, etc. während der Laufzeit zu ändern.
Die Änderungen werden aber nicht in die logic.yaml
geschrieben und sind nach einem
Neustart von SmartHomeNG verloren.
logic.alive
Der Code
while logic.alive:
erzeugt eine Endlos-Schleife die bis zum Beenden von SmartHomeNG läuft.logic.name
:Liefert den Namen der Logik wie in
logic.yaml
definiertlogic.last\_time()
:Diese Funktion liefert die letzte Ausführungszeit der Logik vor dem aktuellen Aufruf
logic.prio
:Lesen und setzen der Priorität dieser Logik
logic.trigger()
:Wie
sh.trigger()
, aber triggert nur die aktuelle Logik. Diese Funktion ist nützlich um die Logik zu einem späteren Zeitpunkt (noch einmal) auszuführen
trigger
Das Dictionary trigger
liefert Informationen zur Laufzeit der Logik
über das Ereignis, das zum Aufruf der Logik geführt hat.
trigger['by']
:Ursprung
trigger['source']
Quelle
trigger['dest']
:Ziel
trigger['value']
:Wert
logger und sh.log
Das logger
Objekt wird zum Generieren von Log Mitteilungen verwendet.
Es stellt fünf unterschiedliche Logging Einstufungen (level) bereit:
debug
, info
, warning
, error
und critical
.
Die Angabe logger.info('42')
schreibt einen Eintrag 42
in den zugehörigen Logger.
Damit Logging Einträge auch in Logs auftauchen, muß in der logging.yaml
eine entsprechende Logging Einstellung vorhanden sein.
Die Grundeinstellung in der logging.yaml
sorgt dafür, das die Einstufungen
warning
, error
und critical
aufgezeichnet werden.
Achtung
Die Zeitangabe in den Log Mitteilungen beziehen sich immer auf die lokal eingestellte Zeit
SmartHomeNG Methoden
sh.now und sh.utcnow
Diese beiden Funktionen geben ein datetime
Objekt zurück das die lokale Zeitzone berücksichtigt.
Es ist möglich mit anderen Zeitzonen zu rechnen.
sh.tzinfo()
und sh.utcinfo()
geben die lokale Zeitzone und die UTC Zeitzone zurück.
sh.sun
Dieses Modul gibt Zugriff auf das Sonnenobjekt.
Vorbedingung ist die Definition von Längen- und Breitengrad in smarthome.yaml
.
sh.sun.pos([offset], [degree=False])
Gibt die aktuelle Position der Sonne zurück, optional einen Offset in Minuten and und ob der Rückgabe in Grad anstatt in Rad erfolgen soll
azimut, altitude = sh.sun.pos()
:liefert die aktuelle Position der Sonne
azimut, altitude = sh.sun.pos(degree=True)
:liefert die aktuelle Position der Sonne in Grad
azimut, altitude = sh.sun.pos(30)
liefert die Position, die die Sonne in 30 Minuten haben wird
sh.sun.set([offset])
:Gibt den nächsten Sonnenuntergang zurück, optional mit einem Offset in Grad.
sunset = sh.sun.set()
:Liefert ein auf UTC basierendes
datetime
Objekt mit dem nächsten Sonnenuntergangsunset_tw = sh.sun.set(-6)
:Liefert ein auf UTC basierendes
datetime
Objekt mit der Zeitangabe des nächsten Sonnenuntergangs zuzüglich der Zeit bis die Dämmerung beendet ist.
sh.sun.rise([offset])
:Gibt analog zu
set
den nächsten Sonnenaufgang zurück, optional mit einem Offset in Grad.
sh.moon
Neben den drei Funktionen pos
, set
und rise
(wie beim Objekt sh.sun
) gibt es noch
zwei weitere Funktionen:
sh.moon.light(offset)
:liefert einen Wert im Bereich [0…100] der hellen Oberfläche zur aktuellen Zeit plus einen Offset
sh.moon.phase(offset)
:Liefert die Mondphase als Ganzzahl Wert im Bereich [0…7]: 0 = Neumond 4 = Vollmond 7 = abnehmender Halbmond
Scheduler
sh.scheduler.trigger() / sh.trigger()
Diese globale Funktion triggert eine gegebene Logik unter Angabe ihres Namens
sh.trigger(name [, by] [, source] [, value] [, dt])
name
:der Name der zu triggernden Funktion
by
:Name einer aufrufenden Logik, der Vorgabewert ist
Logic
source
:der Grund für das triggern
value
eine Variable
dt
:ein datetime Objekt das die Triggerzeit angibt (lokale Zeitzone berücksichtigt)
sh.scheduler.change()
Diese Methode ändert Optionen zur Laufzeit der Logiken. Beispiel:
sh.scheduler.change('alarmclock', active=False)
deaktiviert die Logik alarmclock
Zusätzlich zum active
parameter können auch cron
und cycle
geändert werden.
sh.tools Objekt
Das sh.tools
Objekt stellt folgende nützliche Funktionen zur Verfügung:
sh.tools.ping()
Sendet ein Ping an einen Computer und liefert das Ergebnis. Beispiel:
sh.office.laptop(sh.tools.ping('hostname'))
setzt das Item office.laptop
entsprechend der Rückmeldung ob ein Ping erfolgreich war oder nicht.
sh.tools.dewpoint()
Berechnet den Taupunkt für eine gegebene Temperatur und Feuchtigkeit. Beispiel:
sh.office.dew(sh.tools.dewpoint(sh.office.temp(), sh.office.hum())
setzt das Item office.dew
auf das Ergebnis der Taupunktberechnung der Itemwerte von office.temp
und office.hum
sh.tools.fetch_url()
Liefert dem Inhalt einer Webseite als String oder False
wenn ein Fehler auftritt.
sh.tools.fetch_url('https://www.regular.com')
Es ist möglich als Parameter den Benutzernamen und ein Password anzugeben um die Abfrage bei der zu authentifizieren.
sh.tools.fetch_url('https://www.special.com', 'username', 'password')
Weiterhin kann ein Parameter für eine Zeitüberschreitung bestimmt werden:
sh.tools.fetch_url('https://www.regular.com', timeout=4)
bricht nach 4 Sekunden ohne Ergebnis ab
sh.tools.dt2ts(dt)
Wandelt ein datetime Objekt in einen Unix Zeitstempel um.
sh.tools.dt2js(dt)
Wandelt ein datetime Objekt in einen json Zeitstempel um.
sh.tools.rel2abs(temp, hum)
Wandelt einen relativen Feuchtigkeitswert in einen absoluten Feuchtigkeitswert um.
Zugriffe auf Items
Die Nutzung des sh
Objektes für Items wird nicht weitergeführt. Es ist besser das Item API wie folgt zu nutzen:
from lib.item import Items
items = Items.get_instance()
Mit dem items
Objekt können nun die folgenden Funktionen verwendet werden:
items.return_item(path)
Liefert ein Item Objekt für den angegebenen Pfad zurück. Beispiel:
items.return_item('first_floor.bath')
items.return_items()
Liefert alle Item Objekte zurück
for item in items.return_items():
logger.info(item.id())
items.match_items(regex)
Liefert alle Item Objekte deren Pfad mit einem regulären Ausdruck gefunden wird und die optional ein bestimmtes Attribut aufweisen.
for item in items.match_items('*.lights'): # selects all items ending with 'lights'
logger.info(item.id())
for item in items.match_items('*.lights:special'): # selects all items ending with 'lights' and attribute 'special'
logger.info(item.id())
items.find_items(configattribute)
Abhängig von configattribute
werden die folgenden Items zurückgegeben:
Attribut |
Ergebnis |
---|---|
|
Nur Items bei denen keine Instanz ID angegeben ist |
|
Items mit oder ohne Instanz ID |
|
Items mit einem bestimmten Attribut und einer Instanz ID |
|
Items mit einer bestimmten Instanz ID |
for item in items.find_items('my_special_attribute'):
logger.info(item.id())
find_children(parentitem, configattribute):
Liefert alle Kind Item Objekte eines Elternitems mit einem gegebenen configattribute
.
Die Suche nach dem configattribute
wird genauso durchgeführt wie in find_items(configattribute)
weiter oben.