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