Zugriff auf Items

Zugriff auf den Wert eines Items

Um Zugriff auf Items zu erhalten, müssen Sie über die zentrale Instanz sh des Smarthome Objektes angesprochen werden. Um zum Beispiel den Wert des Items path.item zu erhalten, muss der Aufruf sh.path.item() lauten. Der Wert wird über eine Methode des Items aufgerufen, weshalb der Name des Item Objektes um () ergänzt werden muss. Um dem Item einen neuen Wert zuzuweisen, wird dieser einfach als Argument angegeben: sh.path.item(neuer_wert).

Achtung

Zuweisung von Item-Werten:

Es ist sehr wichtig, immer mit Klammern () auf die Items zuzugreifen! Wenn (fehlerhafter weise) das Item direkt zugewiesen wird, z.B. mit sh.path.item = Wert, dann wird das item-Objekt in SmartHomeNG überschrieben. Anschließend ist sh.path.item eine normale Variable und kein Item Objekt mehr.

In diesem Fall kann die mitgelieferte Logik check_items.py verwendet werden, um auf Vorhandensein entsprechend beschädigter Items zu prüfen und diese wiederherzustellen. Alternativ werden die Items durch einen Neustart von SmartHomeNG neu erstellt.

Alternativ kann auch über die Item-Properties auf den Wert zugegriffen werden: sh.path.item.propery.value gibt den Wert zurück, mit sh.path.item.property.value = Wert kann der Wert zugewiesen werden. Diese Variante lässt sich wie eine normale Variablenzuweisung nutzen.

Beispiel

Eine Logik sieht prinzipiell folgendermaßen aus:

/usr/local/smarthome/logics/testlogik1.py

#!/usr/bin/env python3
# testlogik1.py

#Code der Logik:

# Das Deckenlicht im Büro einschalten, falls es nicht eingeschaltet ist
if not sh.buero.deckenlicht():
    sh.buero.deckenlicht('on')

Properties eines Items

Jedes definierte Item bietet die folgenden Properties an, die unter anderem in eval Ausdrücken genutzt werden können. Alle Properties sind zumindest lesend (r/o) zugreifbar. Einige Properties können auch beschrieben (r/w) werden.

Properties sind ab SmartHomeNG v1.6 verfügbar. Die Properties last/prev_trigger(_by/_age) sind ab SmartHomeNG v1.9.1 verfügbar.

Properties werden in Logiken und eval-Ausdrücken folgendermaßen abgerufen:

var = sh.<Item-Pfad>.property.<Property-Name>

# Beispiel zur Abfrage des Names eines Items:
var = sh.wohnung.testitem.property.name

Werte für Properties, die auch geschrieben werden können (z.B. in Logiken), werden folgendermaßen gesetzt:

sh.<Item-Pfad>.property.<Property-Name> = value

# Beispiel zur Abfrage des Names eines Items:
sh.wohnung.testitem.property.name = 'Neuer Name'

Property	Access	Type	Beschreibung
attributes	r/o	list	Liefert die Namen der plugin-spezfischen Attribute als Liste Auf die Werte dieser Attribute kann über dynamische Properties zugegriffen werde. (Siehe Ende dieser Tabelle)
defined_in	r/o	str	Liefert den Dateinamen in dem das Item definiert wurde zurück
enforce_updates	r/w	bool	Setzt oder löscht den enforce_updates Status
eval	r/w	str	Erlaubt das Abfragen oder Setzen der eval Expression
eval_unexpanded	r/w	str	Erlaubt das Abfragen oder Setzen der eval Expression. Beim Beschreiben des Properties werden evtl. enthaltene relative Item Referenzen zur Nutzung expandiert (analog zum Laden aus Item Konfigurationsdateien).
last_change	r/o	datetime	Liefert ein datetime Objekt mit dem Zeitpunkt der letzten Änderung des Items zurück.
last_change_age	r/o	float	Liefert das Alter des Items seit der letzten Änderung des Wertes in Sekunden zurück.
last_change_by	r/o	str	Liefert einen String zurück, der auf das Objekt hinweist, welches das Item zuletzt geändert hat.
last_trigger	r/o	datetime	Liefert ein datetime Objekt mit dem Zeitpunkt der letzten eval Triggerung des Items zurück. Hat das Item kein eval Attribut oder wurde es nicht getriggert, wird der Zeitpunkt des letzten Updates übermittelt.
last_trigger_age	r/o	float	Liefert das Alter der letzten Eval Triggerung in Sekunden zurück.
last_trigger_by	r/o	str	Liefert einen String zurück, der auf das Objekt hinweist, durch welches eine eventuell vorhandene eval Expression getriggert wurde.
last_update	r/o	datetime	Liefert ein datetime Objekt mit dem Zeitpunkt des letzten Updates des Items zurück. Im Gegensatz zu last_change() wird dieser Zeitstempel auch verändert, wenn sich bei einem Update der Wert des Items nicht ändert.
last_update_age	r/o	float	Liefert das Alter des Items seit dem letzten Update in Sekunden zurück. Das Update Age wird auch gesetzt, wenn sich bei einem Update der Wert des Items nicht ändert.
last_update_by	r/o	str	Liefert einen String zurück, der auf das Objekt hinweist, durch welches das Item zuletzt ein Update erfahren hat.
last_value	r/o	str	Liefert den Wert des Items zurück, den es vor der letzten Änderung hatte.
name	r/w	str	Erlaubt das Abfragen oder Setzen des Namens des Items
on_change	r/o	list	Liefert die Liste der on_change Ausdrücke des Items zurück
on_change_unexpanded	r/w	list	Liefert die Liste der on_change Ausdrücke des Items zurück, in der relative Item Referenzen nicht expandiert sind. Beim Beschreiben des Properties werden evtl. enthaltene relative Item Referenzen zur Nutzung expandiert (analog zum Laden aus Item Konfigurationsdateien).
on_update	r/o	list	Liefert die Liste der on_update Ausdrücke des Items zurück
on_update_unexpanded	r/w	list	Liefert die Liste der on_update Ausdrücke des Items zurück, in der relative Item Referenzen nicht expandiert sind. Beim Beschreiben des Properties werden evtl. enthaltene relative Item Referenzen zur Nutzung expandiert (analog zum Laden aus Item Konfigurationsdateien).
path	r/o	str	Liefert den Pfad des Items zurück
prev_change	r/o	datetime	Liefert ein datetime Objekt mit dem Zeitpunkt der vorletzten Änderung des Items zurück.
prev_change_age	r/o	float	Liefert das Alter des vorangegangenen (geänderten) Wertes in Sekunden zurück.
prev_change_by	r/o	str	Liefert einen String zurück, der auf das Objekt hinweist, welches das Item das vorletzte Mal geändert hat.
prev_trigger	r/o	datetime	Liefert ein datetime Objekt mit dem Zeitpunkt der vorletzten eval Triggerung des Items zurück.
prev_trigger_age	r/o	float	Liefert das Alter der vorletzten Eval Triggerung in Sekunden zurück.
prev_trigger_by	r/o	str	Liefert einen String zurück, der auf das Objekt hinweist, durch welches eine eventuell vorhandene eval Expression das vorletzte Mal ausgelöst wurde.
prev_update	r/o	datetime	Liefert ein datetime Objekt mit dem Zeitpunkt des vorletzten Updates des Items zurück. Im Gegensatz zu prev_change() wird dieser Zeitstempel auch verändert, wenn sich bei einem Update der Wert des Items nicht ändert.
prev_update_age	r/o	float	Liefert das Alter des vorangegangenen Updates in Sekunden zurück.
prev_update_by	r/o	str	Liefert einen String zurück, der auf das Objekt hinweist, durch welches das Item das vorletzte Mal ein Update erfahren hat.
prev_value	r/o	str	Liefert den Wert des Items zurück, den es vor der vorletzten Änderung hatte.
trigger	r/w	list	Erlaubt das Abfragen oder Setzen der Liste der Trigger (eval_trigger) des Items.
trigger_unexpanded	r/w	list	Erlaubt das Abfragen oder Setzen der Liste der nicht expandierten Trigger (eval_trigger) des Items. Beim Beschreiben des Properties werden evtl. enthaltene relative Item Referenzen zur Nutzung expandiert (analog zum Laden aus Item Konfigurationsdateien).
type	r/o	str	Liefert den Typ des Items zurück
value	r/w	str	Das Property value stellt eine Alternative zur Abfrage/Zuweisung durch var= item() / item( value ) dar.
<dynamic property>	r/o	str	Als dynamische Properties werden die plugin-spezifischen Attribute unter- stützt. So kann z.B. aus der smartVISU auf die KNX Sendeadresse eines Items schaltaktor zugegriffen werden: schaltaktor.property.knx_send Dyn. Properties sind erst in SmartHomeNG Releases nach v1.6.1 implementiert.

Der folgende Beispiel eval Ausdruck sorgt dafür, dass ein Item den zugewiesenen Wert nur dann übernimmt, wenn die Wertänderung bzw. das Anstoßen der eval Funktion über das Admin Interface erfolgt ist und das letzte Update vor der aktuellen Triggerung über 10 Sekunden zurück liegt.

eval: value if sh..self.property.last_trigger_by == 'admin' and sh..self.property.last_update_age > 10 else None

Methoden zum Zugriff auf Items

Die im folgenden beschriebenen Methoden waren ursprünglich Teil des smarthome Objektes sh. 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()

Bemerkung

Bei Ausführung einer Logik ist das items Objekt bereits initialisiert und kann ohne die oben beschriebene Initialisierung dirket genutzt werden.

Mit dem items Objekt können nun die folgenden Funktionen verwendet werden:

return_item(path)

Liefert ein Item Objekt für den angegebenen Pfad zurück. Beispiel:

logger.info(items.return_item('first_floor.bath'))

return_items()

Liefert alle Item Objekte zurück

for item in items.return_items():
   logger.info(item.id())

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())

find_items(configattribute)

Abhängig von configattribute werden die folgenden Items zurückgegeben:

Attribut	Ergebnis
attribute	Nur Items bei denen keine Instanz ID angegeben ist
attribute@	Items mit oder ohne Instanz ID
attribute@instance	Items mit einem bestimmten Attribut und einer Instanz ID
@instance	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.

for item in items.find_children('my_special_attribute'):
    logger.info(item.id())