Dieser Artikel ist Work in Progress und wird nach und nach die Alexa Doku im README des Plugins und im KNX-User-Forum (https://knx-user-forum.de/forum/supportforen/smarthome-py/1021150-amazon-alexa-plugin) ablösen. Ein Teil der Originalanleitung war zudem unter https://developer.amazon.com/de/blogs/post/Tx4WG410EHXIYQ/Five-Steps-Before-Developing-a-Smart-Home-Skill dokumentiert.

Zuerst muss unter https://developer.amazon.com/home.html ein Entwicklerzugang erstellt werden. Trotz später notwendiger Angabe einer Kreditkarte kann davon ausgegangen werden, dass die anfallenden Request bei normaler Nutzung deutlich unterhalb der Grenze für die „Free Tier“ bleiben werden. Trotzdem sollte man gelegentlich im Billing nachsehen. Auch ist zu empfehlen, den Zugang als 2-Factor-Authentifizierung einzurichten, anstatt das auch im „Shopping“ Amazon verwendete Passwort alleine zu verwenden!

OAuth2 Credentials anlegen

Über https://developer.amazon.com/home.html –> „Login with Amazon“ muss zuerst via „Create a New Security Profile“ ein neues Security Profile erzeugt werden.

Hier sind ein Name, eine Beschreibung und ein Link auf eine „privacy.htm“ Seite (bspw. via Dyndns – die Seite muss meines Wissens nicht erreichbar sein) anzugeben.

Über den Reiter Web Settings kann man nun noch seine Client ID und seinen Client Secret einsehen, die für den nächsten Schritt notiert werden müssen. Im unten stehenden Screenshot sind die Informationen entfernt worden:

Alexa Skill anlegen

Als Nächstes muss im Alexa Entwicklerportal ein neuer Skill angelegt werden. Hierzu unter https://developer.amazon.com/alexa/console/ask „Create Skill“ auswählen.

Hier ist die korrekte geographische Region als Default Endpoint zu wählen (in meinem Fall eu-west bzw. Europe/India). Als Payload ist für die alten Version des Plugins v2 zu wählen, für die aktuell in Entwicklung befindliche neue (derzeit noch nicht im DEV Branch, dafür unter https://github.com/Andrek01/Alexa4PayloadV3) v3.

Wichtig: Das was neben „amzn1.ask.skill.“ bei „Your Skill ID“ steht, kopieren. Diese UUID wird später für den nächsten Schritt (Lambda-Funktion) benötigt!

Unter Account Linking sind nun die OAuth2 Daten zu hinterlegen, die im vorherigen Schritt generiert wurden:

Lambda-Funktion anlegen.

Um Aktionen gegen SmartHomeNG ausführen zu können, muss über https://aws.amazon.com (und dann in die AWS Management Console gehen) eine sog. Lambda-Funktion angelegt werden (Link Compute -> Lambda).

Legt man diese über „Funktion erstellen“ an, müssen ein Name (bspw. SmartHomeNGFunction), eine Laufzeitumgebung (Node.js 8.10) und eine Vorhandene Rollen (lambda_basic_execution) gewählt werden.

Der neu erstellten Lambda-Funktion wird nun ein Alexa Smart Home Skill zugeordnet. Klickt man diesen unter „Auslöser hinzufügen“ an, so gibt man nun die Anwendungs-ID (die UUID aus dem vorherigen Schritt) ein! Der Auslöser wird als aktiviert gesetzt!

Das Ganze ist in unten stehendem Screenshot zu sehen.

Als Code muss folgendes eingetragen werden:

/*
You need to specify the following environmental variables in the lambda function:
- SMARTHOME_HOST
		foobar.dyndns.tld
- SMARTHOME_PORT
		443 - endpoint must be https enabled!
- SMARTHOME_PATH
		'/'
- SMARTHOME_AUTH
		'user:password'
*/
exports.handler = function(event, context, callback) {
	var data = JSON.stringify(event)

	var options = {
		hostname: process.env.SMARTHOME_HOST,
		port: process.env.SMARTHOME_PORT,
		path: process.env.SMARTHOME_PATH,
		method: 'POST',
		auth: process.env.SMARTHOME_AUTH,
		headers: {
			'Content-Type': 'application/json',
			'Content-Length': Buffer.byteLength(data)
		}
	};

	var https = require('https');
	var req = https.request(options, (res) => {
		console.log(`HTTP ${res.statusCode}`);
		res.setEncoding('utf8');

		var responseData = '';
		res.on('data', (dataChunk) => {
		    responseData += dataChunk
		});
		res.on('end', () => {
			console.log('raw response:', responseData)

			var response = JSON.parse(responseData);
			if (res.statusCode == 200) {
				console.info('OK', JSON.stringify(response))
				callback(null, response);
			} else {
				console.error('Failed', JSON.stringify(response))
				callback('DependentServiceUnavailableError');
			}
		});
	});
	req.on('error', (e) => {
		console.error('request failed', e);
		callback(e);
	});

	console.log('requesting', data)
	req.write(data);
	req.end();
}

Unterhalb des Codeblocks sind nun noch die vier Variablen SMARTHOME_AUTH (im Stil <user>:<passwort>), SMARTHOME_HOST, SMARTHOME_PATH und SMARTHOME_PORT zu definieren. Wird ein ReverseProxy mit HTTPS verwendet (siehe bspw. im Artikel NGINX als ReverseProxy), so sollte der User und das Passwort dort als Basic Authentication gesetzt werden. Der ReverseProxy muss in Folge dann eine Weiterleitung auf das SmartHomeNG Alexa Plugin (SmartHomeNG URL und Alexa Port) definieren. Port wäre in diesem Fall 443 (https) und URL die Dyndns URL über die das Heimnetzwerk erreichbar ist.

Im develop Branch (also für SmartHomeNG v1.6) ist eine allgemein gültige Lösung implementiert. (Danke an ohinckel für die Idee).

Ab der Version muss der Fehler nicht mehr im einzelnen Plugin abgefangen werden, es sei denn, man möchte nicht das Laden des Plugins unterbinden, sondern vielleicht nur einzelne Funktionen des Plugins deaktivieren.

Wenn ein Plugin ein spezielles Python Package benötigt (Requirement) und dieses auf dem System des Anwenders nicht installiert ist, wird im Log beim ersten Zugriff auf Funktionen dieses Packages eine Exception in das Logfile geschrieben.

Für viele Anwender ist es schwierig, aus der Fehlermeldung auf die eigentliche Ursache zu schließen.

Durch einen kleinen Kniff im Plugin, kann im Logfile eine klare Fehlermeldung geschrieben werden. Außerdem kann das Laden des Plugins unterbunden werden, um Folgefehler zu vermeiden.

Vorgehen

Die zwei notwendigen Änderungen sind hier Beispiel des homematic Plugins und des benötigten Packages pyhomematic beschrieben.

Normalerweise wird das Package folgendermaßen importiert:

from pyhomematic import HMConnection

Um den Fehler zu behandeln, werden folgende zwei Änderungen vorgenommen:

1. Um den Fehler zu erkennen, wird die import Anweisung in ein try/except Konstrukt eingebettet und abhängig vom Ergebnis eine Variable gesetzt. (Zeilen 8 bis 12 im folgenden Beispiel)
2. Um den erkannten Fehler auszuwerten, wird eine If-Anweisung zur__init__ Methode hinzugefügt (Zeilen 37 bis 41), die Im Fehlerfall einen sinnvollen Log-Eintrag schreibt und durch das setzen der Variable self._init_complete signaliseiert, dass das Plugin sich nicht fehlerfrei initialisieren konnte. Das anschließende return sorgt dann noch für den Abbruch der Initialisierung.

#  You should have received a copy of the GNU General Public License
#  along with SmartHomeNG. If not, see <http://www.gnu.org/licenses/>.
#
#########################################################################

import logging

try:
    from pyhomematic import HMConnection
    REQUIRED_PACKAGE_IMPORTED = True
except:
    REQUIRED_PACKAGE_IMPORTED = False

from lib.module import Modules
from lib.model.smartplugin import *

from time import sleep


class Homematic(SmartPlugin):
    """
    Main class of the Plugin. Does all plugin specific stuff and provides
    the update functions for the items
    """
    
    PLUGIN_VERSION = '1.5.0'
    
    connected = False
    

    def __init__(self, sh, *args, **kwargs):
        """
        Initalizes the plugin. The parameters descriptions for this method are pulled from the entry in plugin.yaml.
        """
        self.logger = logging.getLogger(__name__)

        # Exit if the required package(s) could not be imported
        if not REQUIRED_PACKAGE_IMPORTED:
            self.logger.error("{}: Unable to import Python package 'pyhomematic'".format(self.get_fullname()))
            self._init_complete = False
            return

        # get the parameters for the plugin (as defined in metadata plugin.yaml):
        #   self.param1 = self.get_parameter_value('param1')

Im Logfile wird der Fehler dann durch zwei Zeilen, wie im folgenden Beispiel angezeigt:

2018-08-12  09:59:03 ERROR    plugins.homematic   homematic_hm1: Unable to import Python package 'pyhomematic'
2018-08-12  09:59:03 ERROR    lib.plugin          Plugins: Plugin 'homematic' initialization failed, plugin not loaded

ich möchte Euch kurz vorstellen, wie man Sensoren schnell und einfach in shNG einbinden kann. Das Ganze basiert auf der Verwendung eines ESP8266 (bspw. Wemos D1 mini), der Firmware ESPEasy und des shNG Webservices-Plugins.

Die Firmware ESPEasy bietet viele Konfigurationsmöglichkeiten, dies betrifft sowohl Sensoren also auch Kommunikationsschnittstellen.

Teil 0: Allgemeine Informationen

• ESPEasy arbeitet auch im Github.
• Die Liste der unterstützten Sensoren gibt es hier.
• Bei ESPEasy wird jede Nacht automatisch ein Release erzeugt. Diese sind hier zu finden. Es gibt 2 Ausführungen der ESPEasy: A) Released aktuell in der Version 2.0 und B) Develop. als mit mehr Plugins aber auch noch in der Testphase.

Teil 1: Flashen der Firmware

• Download des letzten (Pre-)Releases der V2.0 von hier als zip (heute wäre das Release v2.0-20180321)
• Entpacken des ZIP. Darin sind diverse Binaries und das Flashtool selbst.
  Zu den Binaries: Hier gibt es 3 Ausbaustufen und das ganze für 2 SpeicherGrößen: normal – enthält nur die getesteten und freigegebenen Teile von ESPeasy; test – enthält zusätzlich noch die getesteten; dev – enthält zusätzlich noch die sich in Entwicklung befindlichen; Die Speichergrößen sind 1MB und 4MB. Der erwähnte WEMOS D1 mini hat 4MB Speicher.
• Verbinde den ESP via USB mit einem Windows PC.
• Firmware mit Hilfe des Flashtools auf dem ESP schreiben, dabei Serielle Schnittstelle (COM-Port) und das entsprechende Binary auswählen. Ich nutze immer die Dev-Version. Die COM Schnittstelle kann man auch über den Windows-Gerätemanager in Erfahrung bringen.
  
  
• Neustart des ESP (Reset Taste).
• Der ESP öffnet einen WLAN AccessPoint „ESP_Easy_0“; Passwort: configesp
  Wenn man nicht automatisch zur Anmeldeseite kommt, dann nach 192.168.4.1 browsen
• In der Config seine eigenen WLAN-Daten eingeben und den ESP wieder neu starten. Nun sollte er sich in eigenen Netzwerk anmelden.
  (Über den Weg, das fertige Binary der Firmware zu flashen, muss man immer den Weg über den Hotspot zur Konfiguration und damit zu Einbindung in das eigene Netzwerk machen.)
• Eine detaillierte Beschreibung ist hier
• Nun ist der ESP vorbereitet und kann konfiguriert werden

Teil 2: Verbinden der Sensoren mit dem ESP8266 (Wemos D1 Mini)

• Der verwendetete Sensor DHT22 wird wie folgt mit dem Wemos D1 Mini verbunden:
  
  Den verwendeten GPIO könnt ihr frei wählen. Er muss später in ESPEasy angegeben werden. Hier im Bild ist D0 (GPIO16) verwendet.

Teil 3: Konfiguration in ESPEasy

• Mit dem Aufruf der IP des ESP kommt man zur Konfigurationsseite
• Die Möglichkeiten der Konfiguration sind hier beschrieben.
• Auf der Seite Devices muss der entsprechende Sensor konfiguriert werden. Dabei wird definiert, welcher Sensor an welchem Eingang angeschlossen wurde.
  
• In meinem Beispiel ist es ein DHT22 an GPIO16 (D0).
  
  Im Beispiel sendet er seine Werte an den 3. definierten Controller mit einer Verzögerung von 30sec. Es werden 2 Werte übermittelt, Termperatur und Humidity, jeweils mit 1 Dezimalstelle.
• Auf der Seite Controller wird die Schnittstelle konfiguriert.
  Im Beispiel sind 3 Controller (also Schnittstellen definiert), wobei nur die dritte aktiv ist.
• Wir nutzen „Generic HTTP“, tragen als Controller IP die IP-Adresse von shNG ein und bei Controller Port den Port, den wir für das Webservices-Plugin nutzen.
  Bei Controller Publish setzen wir:
  /shNG/ws/items/ESP_Easy.%sysname%.%tskname%.%valname%/%value%
• Verwendet wird das einfachere „Simple Webservices“ HTTP-Interface, bei dem der eigentliche Wert Teil der HTTP-Adresse ist (kein Payload).
• Zur Erklärung von /shNG/ws/items/ESP_Easy.%sysname%.%tskname%.%valname%/%value%:
  • /shNG/: wird von ESPEasy beim Versenden verschluckt und dient somit nur als „Futter“
  • /ws/items/: Wird vom WebservicePlugin erwartet, um den Inhalt einem Item zuzuordnen
  • /ESP-Easy/: verwende ich als „root“ des Items, so dass alle folgenden Items Kinder von ESP-Easy sind.
  • %sysname%: Name des ESP8266, definiert im Reiter „Config“ unter „Unit Name“  (Im Beispiel: „Wemos_1“)
  • %tskname%: Name des Sensors, definiert im Reiter „Devices“ unter „Name“ (Im Beispiel: „Umwelt“)
  • %valname%: Name des Wertes des Sensors, definiert im Reiter „Devices“ unter „Value“ (Im Beispiel: „Temperature“)
  • %value%: ist der eigentliche Wert
    Damit ergibt sich das Item: ESP_Easy.Wemos_1.Umwelt.Temperature. Der Wert selbst ist 17.36

Teil 4: Konfiguration shNG

• Damit wir in shNG auch etwas empfangen, muss das Webservices-Plugin aktiviert und konfiguriert werden. Man kann die Standardkonfiguration, wie in der Anwenderdokumentation beschrieben, verwenden, d.h. der Port ist 8384.
• Dazu gibt es auch bereits einen Blog-Artikel.
• Nach der Aktivierung und Konfiguration des Plugins sowie einem Neustart müssten im Logfile bereits die Items und Werte sichtbar sein.
  Bspw.: CP Server Thread-19 192.168.2.25 - - [18/Apr/2018:21:41:48] "GET /ws/items/ESP_Easy.Wemos_1.Umwelt.Humidity/64.0 HTTP/1.1" 200 80 "" ""
• Nun noch die Items in einer yaml-Datei im Ordner /items/ definieren: (Beispiel: ESP-Easy.Wemos_1.Umwelt.Temperatur) und shNG neu starten.

  
  ESP_Easy:
      Wemos_1:
          Umwelt:
              Temperature:
                  type: num 
              Humidity:
                  type: num
  

• Nun müssten über das „Simple Webservices“ HTTP-Interface des Webservices-Plugins den Items die Werte zugwiesen werden.

Viel Spaß beim Anwenden!

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>

Es gibt zurzeit drei verschiedene Datenbank Plugins:

• database
• sqlite
• sqlite_visu2_8

Wenn Du neu mit SmartHomeNG beginnst, solltest Du das Plugin database verwenden. Das database Plugin unterstützt sowohl MySQL Datenbanken, als auch SQLite Datenbanken. Welcher Datenbank-Typ verwendet wird, wird in ../etc/plugin.yaml konfiguriert.

sqlite und sqlite_visu2_8

Die beiden SQLite Plugins dienen nur der Rückwärts-Kompatibilität für bestehende SmartHomeNG bzw. smarthome.py Umgebungen und werden nicht mehr weiterentwickelt.

Das Plugin sqlite unterstützt smartVISU bis zur Version v2.7.

Zur Unterstützung von smartVISU v2.8 und v2.9 muss das Plugin sqlite_visu2_8 verwendet werden. Das Plugin führt beim ersten Start eine Konvertierung der Datenbank von sqlite auf das sqlite_visu2_8 Format durch. Einen Weg zurück gibt es dann nicht. Es sollte also vorher eine Sicherung der Datenbank Datei ../var/db/smarthome.db durchgeführt werden.

Wichtig: Vor Beginn der Sicherung SmartHomeNG beenden.

Eine Routine zur Konvertierung der Datenbanken der sqlite Plugins zu einer Datenbank für das database Plugin gibt es (noch) nicht.

Der Support-Thread für das Backend-Plugin im knx-user-forum findet sich unter http://knx-user-forum.de/forum/supportforen/smarthome-py/959964-support-thread-f%C3%BCr-das-backend-plugin. Die automatisch generierte Dokumentation kann unter https://www.smarthomeng.de/user/plugins/backend/user_doc.html eingesehen werden.

Die im Folgenden dargestellten Screenshots stellen den zum Zeitpunkt dieses Artikels aktuellen Entwicklungsstand für SmartHomeNG 1.5 dar. Sie sind jedoch sehr ähnlich zum bestehenden Master-Branch (1.4.x), so dass die Informationen Allgemeingültigkeit haben.

Installation

Damit das Backend-Plugin läuft, ist die Installation zweier Python Pakete erforderlich:

sudo pip3 install cherrypy
sudo pip3 install jinja2

CherryPy ist ein Python-Webserver, Jinja2 die zugehörige Template-Engine.
In der /etc/module.yaml muss zudem das http Modul aktiviert sein. Bei Bedarf kann hier auch der Port definiert werden:

BackendServer:
    plugin_name: backend

Nach Neustart von SmartHomeNG ist das Backend nun unter http://«ip_addresse_von_shng»:«port» erreichbar.

Überblick

Die Backend-GUI besteht im Wesentlichen aus den Seiten Dienste, Items, Logiken, Scheduler, Plugins, Szenen, Threads und Logging. Im aktuellen Master-Branch gibt es zudem die Seite System, welche in der Entwicklungsversion für 1.5 über das SmartHomeNG Icon erreichbar ist.

System

Auf der System-Seite, werden Informationen über die aktuellen Systemdaten angezeigt. Hier ist die SmartHomeNG Version und die des Plugin-Repositories zu finden.

Weiterhin gibt es Daten zum Host, Betriebssystem, der verwendeten Python-Version, dem freien Festplattenspeicher, der Server- und Betriebszeit.

Wartet man kurz ab, kann über einen zweiten Reiter der PyPI Check eingesehen werden, der einen aktuellen Überblick über die via pip3 installierten Pakete gibt.

Hier kann man sich einen Überblick machen, ob es aktuellere von SmartHomeNG unterstützte Paketversionen gibt. Fährt man mit der Maus über das Icon (grüner Haken, rotes Info-Symbol), so bekommt man zusätzliche Informationen.

Im unten gezeigten Beispiel gibt es eine neuere python-dateutil Version, die von SmartHomeNG unterstützt wird, während die neuste Version von ruamel.yaml nicht unterstützt wird.

Dienste

Über die Dienste lässt sich die Sprache des Backends umstellen und - bei Bestimmten Systemen -  der KNXD neu starten. Des Weiteren kann das Cache-Verzeichnis auf ungültige Dateien überprüft werden, etwa wenn ein Item nicht mehr existiert.

Wird bspw. für die module.yaml ein verschhlüsseltes Passwort benötigt, so kann dieses hier erstellt werden. Auch ein Prüf-Tool für YAML Syntax, sowie ein CONF-YAML Konverter stehen zur Verfügung.

Zuletzt kann auch die Syntax von EVAL-Ausdrücken geprüft werden.

Items

Im Menüpunkt Items wird eine Baustruktur der aktuellen Items angezeigt, die man sehr einfach über Klick auf das + bzw. - Symbol betrachten kann. In der Anzeige rechts sieht man die Details des jeweiligen Items und kann über das Eingabefeld den Wert des Items ändern.

Zusätzlich werden sämtliche Metadaten des Items angezeigt, die in SmartHomeNG vorliegen.

Über die Suche über der Anzeige lassen sich gezeigt Item-Pfade durchsuchen oder der gesamte Baum auf-/zuklappen.

Logiken

Im Menüpunkt Logiken wird eine Übersicht der aktuellen Logiken angezeigt.

Die Logiken können hier zur Laufzeit ausgeführt werden (Hand Icon). Daneben können sie neu geladen werden (etwa wenn man die zugehörige Datei bearbeitet hat),  deaktiviert werden (die Logik "HostsList" ist im Beispiel deaktiviert), entladen werden (die Logik ist SHNG zur Ausführung nicht mehr bekannt) oder gelöscht werden (Logik wird entladen, aus der logics.yaml ausgetragen und die Datei gelöscht).

Daneben kann über die GUI auch eine neue Logik erstellt (Button über der Liste) oder bestehende Logiken editiert werden (Klick auf den Dateinamen).

In der Editieransicht kann nun der Python-Code modifiziert und die Logik direkt gespeichert und neu geladen werden. Auch ein Zwischenspeichern ist möglich. Hier ist aber darauf zu achten, dass zum Zeitpunkt eines Neustarts von SHNG die modifizierte Logik direkt geladen wird, also der Python-Code lauffähig sein sollte.

Neben dem Code können hier auch das Cycle-Intervall, ein Ausführungszeitpunkt, die zugehörigen Items (die die Logik bei Wertänderung auslösen) und die Rechte zur Ausführung aus der smartVISU bearbeitet werden.

Der Editor erlaubt eine Reihe an Tastaturkürzeln, die über den Hilfe-Knopf eingesehen werden können.

Plugins

Im Menüpunkt Plugins wird die Liste der aktuell laufenden Plugin-Instanzen angezeigt.

Klickt man auf eine Zeile, so werden Detailinformationen geöffnet. Zudem wird im Fall eines Webinterfaces ein Link auf dieses eingeblendet.

Die Knöpfe unter Aktionen sind derzeit noch ohne Funktionalität.

Szenen

Unter Szenen ist die Liste der aktuellen Szenen zu sehen.

Threads

Threads gibt einen Überblick über die aktuell laufenden Threads innerhalb SmartHomeNG.

Logging

Unter Logging wird die aktuelle Logging-Konfiguration angezeigt. Die jeweils konfigurierten Logfiles können direkt mit Klick auf den Dateinamen angezeigt werden.

Per Klick auf den Dateinamen kann das Logfile eingesehen, gefiltert und lokal gespeichert werden. Das hilft massiv bei der Problemlösung im Forum

Urheberrechtshinweise

Über diesen Link findet man Informationen zu den verbauten 3rd Party Komponenten, den Versionen und den jeweiligen Open Source Lizenzen.

Zusammenfassung

Das Backend-Plugin ist ein wichtiges Hilfsmittel um den Überblick über sein System zu behalten. Es hilft bei der Wartung und Aktualisierung, aber auch bei der Problemlösung.

Speziell beim Einfügen neuer Items kann sichergestellt werden, ob diese auch korrekt eingelesen wurden. Tauchen Sie im Itembaum nicht auf, so liegt mit hoher Wahrscheinlichkeit ein Fehler vor.

Die Systeminformationen und die Logfiles helfen, speziell bei Supportproblemen die Problemlösung deutlich zu beschleunigen.

Wir sind immer für neue Features und Ideen offen. Also einfach im Forum im zugehörigen Thread äußern.

(Die in diesem Artikel verwendeten Screenshots wurden selber erstellt. Das Titelbild ist unter der Creative Commons Zero (CC0) Lizenz veröffentlicht und wurde von www.pexels.com bezogen.)

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