Funktionsweise von KNX-Szenen

Um Szenen in KNX nutzen zu können, müssen Aktoren verwendet werden, die Szenen unterstützen. Diese Aktoren verfügen über ein Kommunikationsobjekt, über welches Szenen angesteuert werden können. Szenen werden ausgelöst, indem auf die Gruppenadresse (GA) die mit diesem Kommunikationsobjekt verbunden ist, ein numerischer 8-Bit Wert gesendet wird. Gültige Werte sind hierfür 0 bis 63. Über eine Szene können also nur Aktoren angesteuert werden, die mit der selben Gruppenadresse verbunden sind.

Auf welche Werte (Szenennummern) der jeweilige Aktor reagiert, muss mit der ETS konfiguriert werden. In der ETS wird auch festgelegt, welchen Zustand der Aktor einnehmen soll, wenn über die Gruppenadresse eine Szene angesteuert wird.

Optional kann in der ETS eingestellt werden, dass Aktoren die Zustände die zu einer Szene gehören lernen kann. Das geschieht folgendermaßen: Die Aktoren werden manuell in den Zustand gebracht, den sie für eine Szene einnehmen sollen. Anschließend wird auf die Guppenadresse der Wert Szenennummer+128 (also 128 bis 191) gesendet. Dadurch werden die Aktoren, bei denen das „Lernen“ aktiviert ist veranlasst, sich den aktuellen Zustand als Zustand für die entsprechende Szene zu merken.

Ansteuerung von KNX-Szenen aus SmartHomeNG

Um KNX-Szenen aus SmartHomeNG anzusteuern, muss ein numerisches Item angelegt werden und es muss den Wert auf die Gruppenadresse senden, die zur Szenensteuerung verwendet wird:

meine_items:
    knx_szenen:
        name: Beispiel für KNX-Szenen
        type: num
        enforce_updates: True
        knx_dpt: 5
        knx_send: 0/0/3

enforce_updates muss auf True gesetzt werden, damit wenn mehrfach hintereinander die selbe Szene angesteuert werden soll, der Wert auch auf den KNX Bus geschrieben wird.
Der knx_dpt Wert 5 (8 Bit 0-255) ist die ursprüngliche Art Szenen in KNX Anzusteuern. Hier werden die Szenen über Werte von 0 bis 63 angesteuert.

Es gibt inzwischen in KNX eigene DPT Werte um Szene anzusteuern (DPT 17 und 18). Bei diesen DPTs werden die Szenen von 1 bis 64 nummeriert. Es ist zu beachten, dass ganz alte KNX Aktoren diese DPTs eventuell nicht kennen (weshalb ich mir angewöhnt habe immer DPT 5 zu verwenden).

Szenen in SmartHomeNG

Szenen in SmartHomeNG funktionieren nach dem gleichen Prinzip wie KNX-Szenen. Damit SmartHomeNG erkennt, dass ein Item die Ansteuerung einer Szene bewirken soll, muss der Item-Type scene gewählt werden. Ein Szenen Item für SmartHomeNG Szenen sieht somit folgendermaßen aus:

meine_items:
    szenen:
        name: Beispiel für SmartHomeNG-Szenen
        type: scene
        enforce_updates: True

Die Festlegungen, welche Items auf die Szene reagieren sollen und welchen Zustand sie einnehmen sollen (was bei KNX in der ETS festgelegt wird), erfolgt im Verzeichnis ../scenes in einer YAML Datei, die den Namen des Szenen-Items trägt. Im obigen Beispiel also meine_items.szenen.yaml. Detals zum Aufbau dieser Datei sind in der Anwender Dokumentation in der Beschreibung der Konfigurationsdateien zu finiden.

Die Ansteuerung der Szenen erfolgt analog zur Ansteuerung von KNX-Szenen durch Zuweisung eines Wertes zwischen 0 und 63 zum Abruf (und 128 bis 191 zum speichern) von Szenen.

Gemischte Szenen in SmartHomeNG und KNX

Es ist auch möglich, Szenen zwischen SmartHomeNG und KNX zu mischen, ohne die Items der KNX Aktoren in die SmartHome Szenen Definition im ../scenes Verzeichnis aufnehmen zu müssen. Es kann dabei auf die KNX Funktionalität zurück gegriffen werden. Dazu muss das Szenen Item einer SmartHomeNG Szene nur um die KNX Attribute erweitert werden:

meine_items:
    szenen:
        name: Beispiel für gemischte Szenen
        type: num
        enforce_updates: True
        knx_dpt: 5
        knx_send: 0/0/3

Wenn die Szenen Ansteuerung auch aus dem KNX Bus heraus erfolgen soll, also z.B. über einen Tastsensor der Szenen abruft oder speichert, muss das Beispiel nur noch um den KNX Listen-Befehl auf die Szenen-GA erweitert werden:

meine_items:
    szenen:
        name: Beispiel für gemischte Szenen
        type: num
        enforce_updates: True
        knx_dpt: 5
        knx_send: 0/0/3
        knx_listen: 0/0/3

Nun bewirkt ein Szenen Abruf durch einen KNX Taster, dass auch die Items der SmartHomeNG Szene mit angesteuert werden.

Beispiel Implementierung

Im folgenden wird die Implementierung der Lichtsteuerung gezeigt, bei der fast alle Leuchten über KNX-Szenen gesteuert werden. Allerdings soll eine Philips HUE Leuchte mit angesteuert werden, welche aus SmartHomeNG heraus mit dem hue Plugin gesteuert wird.

Das Szenen Item wird azu folgendermaßen definiert:

wohnung:
    buero:
        szenen_knx:
            comment: 0=aus, 1=Ambiente, 2=hell, 3=Putzen, 4=Party
            name: Beleuchtungsszenen Büro
            type: scene
            enforce_updates: 'on'
            knx_dpt: 5
            knx_send: 1/0/16
            knx_listen: 1/0/16

Die KNX Aktoren (Dimmer) sind entsprechend konfiguriert, dass sie auf der GA 1/0/16 auf die Szenennummern 0 bis 4 (gemäß KNX Definition Szenen 1 bis 5) reagieren und dass sie für die Szenennummern 1 und 2 das lernen zulassen.

Die SmartHomeNG Szene ist im Verzeichnis ../scenes in der Datei wohnung.buero.szenen_knx.yaml folgendermaßen definiert:

0:
    name: Aus
    # Leuchte Dreieckschrank ausschalten, falls die Schreibtischleuchte nicht eingeschaltet ist, sonst level 126 setzen
    actions:
        - {item: wohnung.buero.dreieckschrank.level, value: 0 if (sh.wohnung.buero.schreibtischleuchte.status() < 2) else 126}
        - {item: wohnung.buero.dreieckschrank.ct, value: 345, learn: false}
        - {item: wohnung.buero.dreieckschrank.onoff, value: False if (sh.wohnung.buero.schreibtischleuchte.status() < 2) else True}

1:
    name: Ambiente
    actions:
        - {item: wohnung.buero.dreieckschrank.level, value: sh...dreieckschrank.ambiente_level()+3, learn: false}
        - {item: wohnung.buero.dreieckschrank.ct, value: 345, learn: true}
        - {item: wohnung.buero.dreieckschrank.onoff, value: True, learn: true}

2:
    name: Hell
    actions:
        - {item: wohnung.buero.dreieckschrank.level, value: 126, learn: true}
        - {item: wohnung.buero.dreieckschrank.ct, value: 345, learn: true}

3:
    name: Putzen
    actions:
        - {item: wohnung.buero.dreieckschrank.onoff, value: True, learn: false}
        - {item: wohnung.buero.dreieckschrank.level, value: 255, learn: false}
        - {item: wohnung.buero.dreieckschrank.ct, value: 345, learn: false}

4:
    name: Party
    actions:
        - {item: wohnung.buero.dreieckschrank.level, value: 200, learn: false}
        - {item: wohnung.buero.dreieckschrank.hue, value: 59635, learn: false}
        - {item: wohnung.buero.dreieckschrank.sat, value: 230, learn: false}
        - {item: wohnung.buero.dreieckschrank.onoff, value: True, learn: false}

Zur Ansteuerung der Hue Leuchte über die Szene werden 3 Items gesteuert, welche die Leuchte ein- und ausschalten, den Dimmwert und die Farbe setzen.

Für jede der Szenen (0 bis 4) wird über value für diese Werte ein Wert gesetzt (der bei Abruf der Szene eingestellt werden soll) und über learn wird festgelegt, ob andere Werte gelernt werden können/dürfen. Für value können dabei nicht nur konstante Werte festgelegt werden, sondern auch eval Ausdrücke. Wenn ein eval Ausdruck angegeben wird, ist learn zwangsweise false. In diesem Fall können also keine Szenen Zustände gelernt werden.

Ein Beispiel für die Nutzung von eval Ausdrücken in Szenen ist bei Szene Nummer 0 zu finden, welche die Beleuchtung ausschalten soll. Falls im Büro die Schreibtisch Leuchte (die nicht Teil der Szenen ist) eingeschaltet ist, wird die HUE Leuchte jedoch nicht ausgeschaltet, sondern als Hintergrund Beleuchtung in einem gedimmten warmen Weiss eingeschaltet.

Bei Szene Nummer 1 wird eine andere eval Nutzung mit Anwendung relativer Item Adressierung gezeigt. Hier wird der Wert auf den Wert eines anderen Items plus 3 gesetzt. Hier kann nur der Weisston und Ein/Aus über die Szene gelernt werden.

Bei Szene Nummer 4 wird eine vorgewählte Farbe und Helligkeit der HUE Leuchte eingestellt, die bewusst nicht durch „Lernen“ geändert werden kann.

Ansteuerung der Szenen über smartVISU

Die Ansteuerung der Szenen kann am besten über Buttons in der smartVISU erfolgen. Für das obige Beispiel wird die folgende Definition für die Autogenerierung verwendet:

wohnung:
    buero:
        sv_page: room
        name: Büro
        sv_img: scene_office.svg

        visu:
            szenen_beleuchtung:
                name: Szenen Beleuchtung

                sv_widget: 'Szenen abrufen:
                    <span data-role="controlgroup" data-type="horizontal">
                    {{ basic.button(''szenen_buero0'', ''wohnung.buero.szenen_knx'', ''Aus'', icon0~"control_standby.svg", ''0'', ''midi'') }}
                    {{ basic.button(''szenen_buero1'', ''wohnung.buero.szenen_knx'', ''Ambiente'', icon0~"light_light_dim_00.svg", ''1'', ''midi'') }}
                    {{ basic.button(''szenen_buero2'', ''wohnung.buero.szenen_knx'', ''Hell'', icon0~"light_ceiling_light.svg", ''2'', ''midi'') }}
                    {{ basic.button(''szenen_buero3'', ''wohnung.buero.szenen_knx'', ''Putzen'', icon0~"scene_cleaning.svg", ''3'', ''midi'') }}
                    {{ basic.button(''szenen_buero6'', ''wohnung.buero.szenen_knx'', ''Party'', icon0~"light_party.svg", ''4'', ''midi'') }}
                    </span><br>
                    <div style="line-height: 30%;">
                         <br>br>
                    </div>
                    <div>Szenen speichern:<br>
                    <span data-role="controlgroup" data-type="horizontal">
                    {{ basic.button(''szenen_bueroS0'', ''wohnung.buero.szenen_knx'', ''Aus'', icon0~''control_standby.svg'', ''128'', ''midi'', ''#4176a9'') }} 
                    {{ basic.button(''szenen_bueroS1'', ''wohnung.buero.szenen_knx'', ''Ambiente'', icon0~"light_light_dim_00.svg", ''129'', ''midi'', ''#4176a9'') }} 
                    {{ basic.button(''szenen_bueroS2'', ''wohnung.buero.szenen_knx'', ''Hell'', icon0~''light_ceiling_light.svg'', ''130'', ''midi'', ''#4176a9'') }} 
                    {{ basic.button(''szenen_bueroS3'', ''wohnung.buero.szenen_knx'', ''Putzen'', icon0~''scene_cleaning.svg'', ''131'', ''midi'', ''#4176a9'') }} 
                    {{ basic.button(''szenen_bueroS6'', ''wohnung.buero.szenen_knx'', ''Party'', icon0~''light_party.svg'', ''132'', ''midi'', ''#4176a9'') }} 
                    </span></div>

Das erzeugt in der Visu:

• eine Seite „Büro“ in der normalen Raum-Navigation.
• auf dieser Seite einen Block mit dem Namen ‚Szenen Beleuchtung‘
• in diesem Block erzeuge ich zwei Button Reihen zur Szenen Steuerung: Der obere Block zum Abruf der Szenen, der untere Block zum Speichern von Szenen

Das sieht dann so aus:

Das ursprüngliche Item dessen Maximalwert ich speichern hat folgenden Aufbau.

Wetterstation:
    Temperatur:
        type: num
        visu_acl: ro

Um jetzt zusätzlich zum aktuellen Messwert den maximalen Messwert zu speichern habe ich das Item etwas angepasst:

Wetterstation:
    Temperatur:
        Aktuell:
            type: num
            visu_acl: ro
        Maximum_Heute:
            type: num
            visu_acl: ro

Für Wetterstation.Tempertatur.Maximum_Heute müssen jetzt noch folgende Dinge hinzufefügt werden:

• Überprüfen auf Änderungen
  Immer wenn sich der Wert von Wetterstation.Temperatur.Aktuell ändert, soll überprüft werden, ob Wetterstation.Temperatur.Maximum_Heute aktualisiert werden muss.
• Aktualisieren des Wertes
  Wenn bei dieser Überprüfung der aktuelle Wert höher ist als der bisher in Wetterstation.Temperatur.Maxiumum_Heute gespeicherte Wert, soll der Wert aktualisiert werden.
• Zurücksetzen des Wertes
  Einmal am Tag muss Wetterstation.Temperatur.Maximum_Heute zurückgesetzt werden.

Überprüfen auf Änderungen

Das überprüfen, ob sich die aktuelle Temperatur ändert, geht ganz einfach indem man Wetterstation.Temperatur.Maximum_Heute einen eval_trigger auf das Item Wetterstation.Temperatur.Aktuell hinzufügt. Seit SmartHomeNG kann man das Item auch relativ angeben: ..Aktuell.
es entsteht also folgender eval_trigger:

eval_trigger: ..Aktuell

Aktualisieren des Wertes

Wenn bei der Überprüfung der aktuelle Wert höher ist als der bisher in Wetterstation.Temperatur.Maxiumum_Heute gespeicherte Wert, soll der Wert aktualisiert werden.
Das geht über ein eval:

eval: sh...Aktuell() if float(sh..self()) > sh...Aktuell() else sh..self.property.value

Zurücksetzen des Wertes

Der Wert soll einmal pro Tag und bei einem Neustart zurückgesetzt werden. Das wird über ein crontab und ein Magic Value (99.9) erledigt. Es wird davon ausgegangen, dass ein Temperaturwert von 99.9 nie vorkommt und deshalb zum Zurücksetzen verwendet werden kann.

Verzögerung bei der Initialisierung: Meine Wetterstation liefert nur alle 5 Minuten (alle 300 Sekunden) einen neuen Temperaturwert. Das heisst nach einem Neustart von SmartHomeNG steht also für maximal 5 Minuten kein aktueller Messwert in Wetterstation.Temperatur.Aktuell sondern 0.0. Deshalb wird nach 5 Minuten und 10 Sekunden Wetterstation.Temperatur.Maximum_Heute auf die aktuelle Temperatur zurückgesetzt.

crontab:
 -init+310 = 99.9
 -0 0 * *  = 99.9

Auch der eval Ausdruck muss für das Zurücksetzen erweitert werden:

eval: sh...Aktuell() if value == 99.9 or float(sh..self()) > sh...Aktuell() else sh..self.property.value

Natürlich kann dieses Prinzip Minimal-Werte angewendet werden. Dafür muss nur der Vergleich im eval Ausdruck angepasst werden.

Das endgültige Item sieht dann so aus:

Wetterstation:
    Temperatur:
        Aktuell:
            type: num
            visu_acl: ro
        Maximum_Heute:
            type: num
            visu_acl: ro
            eval: sh...Aktuell() if value == 99.9 or float(sh..self()) < sh...Aktuell() else sh..self.property.value
            eval_trigger: ..Aktuell
            # Reset am Ende des Tages durch "MagicValue" 99.9. Es wird angenommen, 
            # dass dieser Temperaturwert in der Praxis niemals auftritt. 
            crontab: 
             - 0 3 * * = 99.9
             # +310 weil die Wetterstation mindestens alle 300 Sekunden einen aktualisierten Temperatur Wert sendet
             # dadurch wird sichergestellt, dass nach einem Neustart von SmartHomeNG in ..Aktuell auf jeden Fall ein gültiger Wert steht. 
             - init+310 = 99.9

Wenn etwas anderes als Temperaturwerte gespeichert werden sollen, kann es auch sein, dass als Magic Value eine andere Zahl verwendet werden muss.

Structs aus Plugins

Die „struct“ Vorlagen ermöglichen es zum einen, vorgegebene Item-Strukturen aus Plugins zu integrieren, zum anderen aber auch, eigene Vorlagen für immer wiederkehrende Item-Bäume bereitzustellen.

Bei gleichen Gerätetypen ist die Struktur oft sehr ähnlich, was zu sehr vielen gleich aufgebauten Item-Definitionen führt. Leuchten, Jalousien, Bewegungsmelder können dabei ähnlich leicht vereinfacht werden wie Sollwerte, Vorgaben für Zustände des stateengine Plugins und vieles mehr. Zuerst ein Beispiel, wie mit nur einer Zeile ein Zeitschalt-Unteritem aus dem UZSU Plugin eingefügt werden kann. Da diese Vorlage bereits mit dem Plugin mitgeliefert wird, ist nichts weiter zu tun, also mittels struct Attribug darauf zuzugreifen. Welche Vorlagen von welchen Plugins bereitgestellt werden, ist zum einen in den jeweiligen plugin.yaml Dateien, zum anderen im Admin Tool einzusehen.

    # item.yaml
    item:
        struct: uzsu.child

Durch diese Angabe entsteht beim Start von SmartHomeNG folgende Struktur, die zuvor noch bei jedem Item, das die Zeitschaltuhr nutzt, manuell angegeben werden musste:

  # item.yaml
  item:
        uzsu:
            type: dict
            uzsu_item: ..
            cache: True
            visu_acl: rw
            
            active:
                type: bool
                eval: sh...activate(value)
                visu_acl: rw

Eigene Vorlagen

Folgendes Beispiel zeigt, wie Vorlagen selbst in der Datei etc/struct.yaml hinterlegt werden können. Generell bedarf es keinerlei besonderer Syntax. Strukturen werden dort genauso angelegt wie normale Item-Bäume. Die jeweils oberste Hierarchieebene definiert den Namen der Vorlage. Und genau auf dieses Item wird dann in der eigentlichen item.yaml Datei durch das Attribut struct verwiesen. Zuerst der Inhalt der struct.yaml für ein dimmbares Licht mit einigen Zusatzfunktionen:

    # struct.yaml
    dimmervorlage:
        name: Vorlage für dimmbare Leuchten
	knx_dpt: 1
	visu_acl: rw
	type: bool
        knx_send: 0/0/0
        knx_cache: 0/0/0

	bwm:
		knx_dpt: 1
		visu_acl: rw
		type: bool

	zwangvalue:
		knx_dpt: 5001
		visu_acl: rw
		type: num
		cache: True

		zwangsstellung:
			knx_dpt: 2
			visu_acl: rw
			type: list
			enforce_updates: yes

	dimmen:
		knx_dpt: 5001
		visu_acl: rw
		type: num
		database: yes
		influxdb: yes
		sim: track

		sollwert:
			knx_dpt: 5001
			visu_acl: rw
			type: num
			enforce_updates: yes
			cache: True

Und hier die Einbindung in die yaml Datei im items Verzeichnis für ein Licht mit separaten warm- und kaltweißen Leuchtmitteln:

# item.yaml
licht1:
    warm:
        struct: dimmervorlage
	knx_send: 3/0/21
	knx_cache: 3/0/27

	bwm:
		knx_send: 3/3/67
		knx_cache: 3/3/67

	zwangvalue:
		zwangsstellung:
			knx_send: 3/0/50
			knx_cache: 3/0/50

	dimmen:
		knx_send: 3/0/23
		knx_cache: 3/0/28

		sollwert:
			knx_send: 3/3/53

    kalt:
        struct: dimmervorlage
	knx_send: 3/0/24
	knx_cache: 3/0/29

	bwm:
		knx_send: 3/3/68
		knx_cache: 3/3/68

	zwangvalue:
		zwangsstellung:
			knx_send: 3/0/51
			knx_cache: 3/0/51

	dimmen:
		knx_send: 3/0/26
		knx_cache: 3/0/30

		sollwert:
			knx_send: 3/3/54

Was passiert hier? Es wird jeweils zuerst die Vorlage geladen, in der die Grundinformationen zu den Items verankert ist. Also Infos zu Typ, Cache, KNX DPT, Visu, Datenbank, etc. Diese Vorlage wird nun im tatsächlichen Item nur noch durch die KNX Adressen ergänzt. Etwaige gleich benannte Attribute werden dabei überschrieben (im Beispiel knx_send: 0/0/0).

In der Version 1.6.0 ist zu beachten, dass auch tatsächlich alle bereits definierten Attribute überschrieben werden, also beispielsweise auch Listeneinträge für eval_trigger. Möchte man also verschiedene Vorlagen mit verschiedenen eval_trigger Einträgen miteinander kombinieren, muss das Attribut nach den struct Einträgen manuell mit allen gewünschten Listeneinträgen überschrieben werden.

Zum Abschluss noch ein weiteres Beispiel, das neben einer klassischen Schaltfunktion für das entsprechende Item auch die Einschaltdauer über die Datenbankeinträge evaluiert. Dank relativer Item-Angaben können somit komplexere Konfigurationsblöcke problemlos wiederverwendet werden. Zum einen erleichtert dieser Ansatz ein Aktualisieren und Erweitern von Itemconfigs ungemein, zum anderen bleibt in den yaml Files die Übersicht bewahrt (auch wenn Letzteres Dank Admin Tool zukünftig weniger Relevanz haben wird). Folgend zwei separate Vorlagen:

#struct.yaml
schaltervorlage:
    name: einfache Vorlage für Schalter
    sa:
        knx_dpt: 1
        visu_acl: rw
        type: bool
        database: yes
        cache: yes

    sperren:
        knx_dpt: 1
        visu_acl: rw
        type: bool

laufzeitvorlage:
    name: Vorlage für Laufzeitmessung
    laufzeit_1w:
        type: num
        visu_acl: ro
        crontab: init
        eval: (sh...sa.db('on', '1w') or 0) * 10080
        eval_trigger:
          - ..sa

    laufzeit_24h:
        type: num
        visu_acl: ro
        crontab: init
        eval: (sh...sa.db('on', '24h') or 0) * 1440
        eval_trigger:
          - ..sa

Die tatsächlichen Items benötigen schließlich wieder nur eine Angabe der KNX Adressen, alle anderen Funktionalitäten und Definition werden über die Vorlage eingebunden:

#item.yaml
schalter1:
    struct: schaltervorlage
    sa: 
        knx_send: 1/1/1
    sperren:
        knx_send: 1/1/2

schalter2:
    struct: 
      - schaltervorlage
      - laufzeitvorlage

    sa: 
        knx_send: 1/1/3

    sperren:
        knx_send: 1/1/4

    laufzeit_1w:
        eval_trigger:
          - ..sa
          - ..sperren

schalter3:
    struct: schaltervorlage

    laufzeit:
          struct: laufzeitvorlage

Schalter1 greift ledigilich auf eine Vorlage (schaltervorlage) zurück, während Schalter2 mehrere Vorlagen als Liste miteinander kombiniert. Für Schalter2 existieren also auch die Einträge laufzeit_1w und laufzeit_24h, die eben die Einschaltdauer während der letzten Woche bzw. 24 Stunden von der Datenbank auslesen. Die Triggerung der laufzeit_1w soll in diesem Fall auch vom Sperritem erfolgen, während dies bei Schalter3 lediglich durch das in der Vorlage angegebene Schaltitem geschieht. Da Schalter3 keine Angaben zu den KNX Gruppenadressen macht, handelt es sich hier auch nicht um einen KNX Schalter, sondern z.B. ein Item, das nur über eine Logik oder die Visu geschalten werden kann/soll. Das schalter3 Beispiel zeigt auch, dass die Structs auf jeder beliebigen Hierarchieebene eingebunden werden können.

Limitierungen

Aktuell (inkl. Version 1.9) ist es nicht möglich, structs beliebig zu verschachteln. Das Einbeziehen von anderen structs in einem selbst kreierten struct ist nur auf Rootebene möglich, also beispielsweise so:

    # struct.yaml
    beispielstruct1:
        test1:
            type: bool
            initial_value: True

    beispielstruct2:
        test2:
            type: bool
            initial_value: False

    combinedstruct:
        struct:
          - beispielstruct1
          - beispielstruct2

Debugging

Im Admin Interface sind alle structs, sowohl die von den aktiven Plugins als auch die selbst erstellten einsehbar. Hier lässt sich somit auch prüfen, wie die Structs miteinander kombiniert wurden. Ob und wie der Merge mit Attributen aus den Items geklappt hat, lässt sich am besten im Item Baum nachvollziehen.

Anzahl und Position der eingeschalteten Lampen ermitteln und visualisieren.

Logik

Es werden alle Lichter gesucht, die nicht auf Taster oder Level enden und die nicht in Zentral definiert sind. Die eingeschalteten Lichter werden als Link zum Ausschalten gespeichert, so dass sie bequem später ausgeschaltet werden können.

/usr/local/smarthome/logics/light.py

#!/usr/bin/env python

counter = []

# finde alle Lichter, die eingeschaltet sind (und nicht auf taster oder level enden)
for item in sh.match_items('*.licht.*'):
	if item() and not item.id().endswith('taster') and not item.id().endswith('level') and not item.id().startswith('zentral') and not item.id().endswith('aussen'):
		counter.append(item)

# ermittle licht bool wert
if len(counter) > 0:
	sh.zentral.zaehler.licht(1)
else:
	sh.zentral.zaehler.licht(0)

# setze licht anzahl wert
sh.zentral.zaehler.licht.anzahl(len(counter))
	
# ermittle Namen der Lichter, die eingeschaltet sind
namen = "<ul class='logik_licht'>"
for item in counter:
	parent_item = item.return_parent()
	namen += "<li><a href=\"#\" class=\"ui-link\" onclick=\"io.write(\'"+item.id()+"\',0);\">{0} {1}</a></li>".format(str(parent_item), str(item))
	
namen += "</ul>"
	
# setze Namen der eingeschalteten Lichter
sh.zentral.zaehler.licht.namen(namen.strip())
		
# Logging
logger.info("Es sind {0} Lichter an. ( {1})".format(str(sh.zentral.zaehler.licht.anzahl()), sh.zentral.zaehler.licht.namen()))

Die Logik aktiviert man unter etc/logic.conf mit dem Eintrag von:

/usr/local/smarthome/etc/logic.yaml

In der Zentral.conf habe ich Elemente definiert, die die ermittelten Werte aufnehmen.

lichter:
    filename: light.py
    watch_item: *.licht.*

/usr/local/smarthome/items/Zentral.yaml

# /usr/local/smarthome/items/Zentral.conf
zentral:
    name: Zentral

    zaehler:
        name: Zähler
        sv_page: room

        licht:
            name: Licht an
            type: bool
            visu: yes

            anzahl:
                name: Anzahl eingeschalteter Lichter
                type: num
                visu: yes

            namen:
                name: Eingeschaltete Lichter
                type: str
                visu: yes

Items

Folgende Items werden benötigt.

/usr/local/smarthome/items/EG.yaml

eg:
    name: Erdgeschoß

    flur:
        name: Flur
        sv_page: room
        sv_img: scene_hall.png

        licht:
            name: Flur

            decke:
                name: Dimmer
                type: bool
                visu: yes
                visu_acl: rw
                sv_img: light_ceiling_light.png

                level:
                    type: num
                    visu: yes
                    visu_acl: rw

HTML-Seite

Die ermittelten Werte können nun in einer HTML-Seite wie folgt angezeigt werden:

Es sind <strong>{{ basic.value('zentral.zaehler.licht.anzahl.1', 'zentral.zaehler.licht.anzahl', '', '') }}</strong> Lichter an
<br/>
( {{ basic.value('zentral.zaehler.licht.namen.1', 'zentral.zaehler.licht.namen', '', '') }} )

15.02.2014: Original Wiki Beitrag von ReneHezser
19.05.2015: Überarbeitung durch cstrassburg 

Eine Reihe von Devices liefert Antworten bzw. Stati in Form von JSON formatierten Daten zurück. Diese Daten können in Items verwendet werden, wenn sie in Items vom Typ dict oder vom Typ list eingelesen werden können.

Einlesen von JSON Messages in dicts mit dem MQTT Plugin

Besonders einfach ist das Einlesen von Daten in Items der Typs dict, wenn man MQTT Messages mit dem aktuellen MQTT Plugin empfängt. Das MQTT Protokoll bis zur Version 3.1x unterstützt keine Datentypen. Die Payload, also die übertragenen Daten, werden immer als Array of Byte übertragen.

Das aktuelle MQTT Plugin unterstützt das Casting in den Datentyp des Items. Wenn also z.B. das Item vom Typ str ist, wird beim Empfang das Array of Byte in einen String gewandelt.

Wenn man in der Payload der MQTT Message JSON formatierte Daten in ein Item vom Typ dict empfängt, werden die Daten in Form eines Python dict gespeichert und können in Logiken und eval-Ausdrücken entsprechend weiter verarbeitet werden.

Bei komplexen JSON Strukturen ist die Weiterverarbeitung mit einer Logik zu empfehlen. Bei einfacheren Strukturen kann die Weiterverarbeitung jedoch auch sehr gut in Items mit Hilfe von eval oder on_change erfolgen.

Ein einfaches JSON Beispiel

Wenn eine MQTT Message z.B. folgende Daten liefert:

{  
   "key1":"value1",
   "key2":"value2",
   "key3":"value3"
}

und Du nur den Wert von key2 benötigst, kannst Du das über ein Hilfs-Item lösen, in dem Du die MQTT Payload einliest und den entsprechenden Wert in das Ziel-Item schreibst. Dazu musst Du die Items folgendermaßen definieren:

test:
    hilfs_item:
        type: dict
        mqtt_topic_in: test/test
        on_change: ..ziel_item = value['key2']

    ziel_item:
        type: str

Das MQTT Topic musst Du durch einen sinnvollen Wert ersetzen. Natürlich kann im on_change Attribut anstelle der relativen Item Adressierung auch die absolute Adressierung (test.ziel_item) verwendet werden.

Alternativ kannst Du das auch mit eval / eval_trigger lösen:

test:
    hilfs_item:
        type: dict
        mqtt_topic_in: test/test

    ziel_item:
        type: str
        eval: sh.test.hilfs_item()['key2']
        eval_trigger: test.hilfs_item

Diese Variante kannst Du natürlich auch mit relativer Item-Adressierung realisieren.

Einlesen von JSON Messages in lists mit dem MQTT Plugin

Wenn man in der Payload der MQTT Message JSON formatierte Daten in ein Item vom Typ list empfängt, werden die Daten in Form eines Python list gespeichert und können in Logiken und eval-Ausdrücken entsprechend weiter verarbeitet werden.

Ein einfaches JSON Beispiel

Wenn eine MQTT Message z.B. folgende Daten liefert:

[  
   "value1",
   "value2",
   "value3"
]

und Du nur den zweiten Wert von benötigst, kannst Du das über ein Hilfs-Item lösen, in dem Du die MQTT Payload einliest und den entsprechenden Wert in das Ziel-Item schreibst.

Listen sind so definiert, dass das ersten Element den Index 0 hat. Um den zweiten Wert zu adressieren, musst Du den Index 1 verwenden. Dazu musst Du die Items folgendermaßen definieren:

test:
    hilfs_item:
        type: list
        mqtt_topic_in: test/test
        on_change: ..ziel_item = value[1]

    ziel_item:
        type: str

Auswertung komplexerer Datenstrukturen

Ein dict oder eine list kann statt einfacher Daten auch dicts oder lists enthalten. Auch diese Daten lassen sich auswerten und es können Einzelwerte dieser Datenstruktur in Items gespeichert werden.

Wenn eine MQTT Message z.B. folgende Daten liefert:

{  
   "key1":"value1",
   "key2":[  
      "value21",
      "value22",
      "value23"
   ],
   "key3":{  
      "key31":"value31",
      "key32":"value32",
      "key33":"value33"
   }
}

kannst Du folgendermaßen auf den value22 oder den value33 zugreifen:

test:
    hilfs_item:
        type: dict
        mqtt_topic_in: test/test
        on_change: 
          - ..ziel_item1 = value['key2'][0]
          - ..ziel_item2 = value['key3']['key33']

    ziel_item1:
        type: str

    ziel_item2:
        type: str

Es gibt jeweils einen eigenen Namensraum für Scheduler, die durch

• Items
• Logiken
• Scheduler

erzeugt wurden. Die Scheduler sind im Backend auf unterschiedlichen Reitern auf der Seite Scheduler zu sehen. Auf einem vierten Reiter sind die Scheduler zu sehen, die nicht in diese drei Namensräume fallen.

Das erweiterte API um diese Scheduler sauber anzusprechen ist noch auf der To Do Liste.

Zur Zeit können diese Scheduler über die bisherigen Scheduler Methoden angesprochen werden. Den Namen muss dabei jeweils ein Präfix vorangestellt werden.

Für:

• items   ->   items.<scheduler name>
• Logiken   ->   logics.<scheduler name>
• Plugins   ->   plugins.<scheduler name>

Ein Attribut eval enthält eine Zeile Python die genau einen Wert zurückliefert. Es ist quasi eine Einzeilenfunktion. Der Syntax entspricht einer Python conditional expression.

Wenn in dieser Funktion Werte von Items genutzt werden sollen, dann müssen die Aufrufe die Form sh….<Item-Name>() haben. Sollte man sh. am Anfang vergessen funktioniert es genauso wenig, wie wenn man die Klammern am Ende wegläßt.

Ein Attribut eval_trigger ist nur eine Auflistung von Itemnamen, diese werden jedoch ohne sh. am Anfang aufgeführt.

eval Syntax

Ein Beispiel für einen eval Ausdruck:

eval=value if value>0 else 0

Achtung: Ein if-Statement in einem eval-Ausdruck muss auch einen else-Zweig haben.

Beispiele

Richtig:

myitem:
    eval: sh.my.value()
    eval_trigger: my.value|my.other.value

 
Falsch:

myitem:
    eval: sh.my.value
    eval_trigger: sh.my.value|sh.my.other.value)

08.04.2018: Ergänzt um Informationen aus einem Wiki Beitrag von henfri.

Bei der Wahl von Itemnamen ist folgendes zu beachten: Plugin-Instanzen und Items der obersten Ebene (Top-Level) teilen sich den Namensraum.

Es sollte vermieden werden, Top-Level Items einen Namen zu geben, der in ../etc/plugin.yaml (bzw. ../etc/plugin.conf) bereits für eine Plugin-Instanz gewählt wurde. Dieses kann zu unvorhergesehenen Problemen führen. (z.B.: Wenn ein Plugin Funktionen implementiert hat, wird dies beim Aufruf dieser Funktionen zu Problemen führen, da SmartHomeNG dann versucht auf eine (nicht existierende) Methode des Items zuzugreifen, statt auf das Plugin.)

sql:
    plugin_name: database

Anschliessend wird im Item die Aufzeichnung aktiviert mit ‚database: yes‘ bzw. ‚database: init‘. Nun können weitere Items angelegt werden, die mit Hilfe einer Funktion, die das database-Plugin bereitstellt, die benötigten Werte erhalten.

Das ganze sieht dann in etwa wie folgt aus:

sensor:
    carport:
        temp:
            type: num   
            knx_dpt: 9  
            knx_send: 3/4/11  
            knx_reply: 3/4/11
            ow_addr: '28.52F1AA030000'
            ow_sensor: T 
            database: init  # Aufzeichnung der Daten aktivieren
            min:
                type: num
                knx_dpt: 9
                knx_send: 3/4/14
                knx_reply: 3/4/14
                eval: "sh.sensor.carport.temp.db('min', '28h')"  # Mimium über die letzten 28h berechnen
                eval_trigger: sensor.carport.temp  # Änderungen der Temperatur triggern die Neuberechnung
            max:
                type: num
                knx_dpt: 9
                knx_send: 3/4/15
                knx_reply: 3/4/15
                eval: "sh.sensor.carport.temp.db('max', '28h')"  # Maximum über die letzten 28h berechnen
                eval_trigger: sensor.carport.temp   # Änderungen der Temperatur triggern die Neuberechnung