Seit SmartHomeNG 1.4.x besteht die Möglichkeit, das Webservices Plugin zu nutzen. Das Webservices Plugin stellt zwei unterschiedliche Möglichkeiten bereit lesend (und schreibend) auf Items zuzugreifen: REST und das Simple Webservice Interface.

Daneben verfügt das Webservices Plugin über eine webbasierte GUI, über die alle Items und die dazugehörigen Webservice-URLs angesehen werden können.

Die automatisch generierte Dokumentation findet sich unter http://smarthomeng.de/user/plugins_doc/config/webservices.html.

Der Sourcecode im Master-Branch von SmartHomeNG unter https://github.com/smarthomeNG/plugins/tree/master/webservices.

Support findet ihr im Forum unter: https://www.smarthomeng.de/?category_name=plugins&s=webservicessupport: https://knx-user-forum.de/forum/supportforen/smarthome-py/1163886-support-thread-f%C3%BCr-das-webservices-plugin.

Beispiele zur Nutzung sind in den Artikeln „SmartHomeNG on a Watch – Anbindung des Garmin ConnectIQ SSK an SmartHomeNG“ und „Entfernungsmessung auf Basis eines ESP32 und SmartHomeNG“ dargestellt.

Konfiguration

In der Datei etc/module.yaml sollte der Port für das Webservice-Interface gesetzt werden. Dies geschieht über die Angabe des servicesport:

# etc/module.yaml
http:
    class_name: http
    class_path: modules.http
    port: '1234'
    user: admin
    password: ''
    hashed_password: '...'
    servicesport: '4321'
    starturl: backend

Bei Bedarf eines Schutzes via Basic Authentication, kann zusätzlich noch der service_user, das service_password bzw. das service_hashed_password gesetzt werden:

    service_user: serviceuser
    service_password: ''
    service_hashed_password: 'xxx'

In der etc/plugin.yaml wird nun das Plugin aktiviert:

WebServices:
    class_name: WebServices
    class_path: plugins.webservices
    mode: set

Der mode lässt sich alternativ auf all setzen. Damit werden automatisch alle Items via Webservice-API verfügbar gemacht. Ist wie oben set gesetzt, müssen Items explizit freigegeben und zu sogenannten „Itemsets“ (Mengen von Items) gruppiert werden.

Ist dies geschehen, so wird das Plugin nach einem Neustart aktiv und kann verwendet werden. Im Beispiel set ist nun noch folgendes zu tun:

In der Definition der Items, muss das Attribut webservices_set gesetzt werden. Die Idee des Itemsets ist, dass man beispielsweise bei der Verwendung in einer Android oder iOS App nur einen Request pro Seite machen muss, auch wenn es mehrere Items gibt, die angezeigt werden soll. Items die zu einem Set gruppiert werden, lassen sich also über dieses gemeinsam via Webservice auslesen. Eine Seite der GUI in der App entspräche also einem Itemset.
Schreibend ist nur der Zugriff auf einzelne Items möglich. Alle Items die in Sets sind, sind auch einzeln lesend zugreifbar.

Ein Item kann zudem mehrere Sets haben, wie im Item MyItem2 unten verdeutlicht ist:

MyItem:
    type: str
    webservices_set: 'MySet1'
    webservices_data: 'val'

MyItem2:
    type: num
    webservices_set:
     - 'MySet1'
     - 'MySet2'
    webservices_data: 'full'

Das optionale Attribut webservices_data bedeutet folgendes: Ist hier nur val gesetzt, wird nur der Wert und der Pfad des Items im JSON Format zurückgeliefert. Dies dient bspw. bei mobilen Anwendungen der Reduzierung der Datenmenge.

Will man auch sämtliche Metadaten des Items haben, so setzt man full

Zugriff auf Items

Simple Webservice Interface

Das „Simple Webservices Plugin“ erlaubt lesenden und schreibenden Zugriff auf Items ausschliesslich über URLs als GET Request.

Lesend wird dabei nach folgendem Schema zugegriffen:

http://«your_server_ip»:«your_services_port»/ws/items/«item_path»

Ein Beispiel ist http://192.168.178.100:1234/ws/items/knx.gf.office.light

Will man einen Wert schreiben, so hängt man diesen URL-codiert einfach hinten an:

http://«your_services_port»/ws/items/«item_path»/«value»

Also beispielsweise http://192.168.178.100:1234/ws/items/office.light/0 oder http://192.168.178.100:1234/ws/items/office.light/False, was das Licht ausschaltet.

REST (compliant) Interface

Um auch den REST Standard zu unterstützen, gibt es weiterhin auch das REST Interface. Dieses verhält sich leicht anders, als das Simple Webservices Interface.

Lesend bleibt bis auf die URL alles beim Gleichen:

http://«your_server_ip»:«your_services_port»/rest/items/«item_path»

Analog zu oben also im Beispiel http://192.168.178.100:1234/rest/items/knx.gf.office.light

Schreibend müssen die Daten aber als HTTP Body in einem PUT oder POST Request übergeben werden, so wie es durch den REST Standard vorgegeben wird. Dabei ist sicherzustellen, dass im HTTP Header der Content-Type: application/json gesetzt ist.
Der Request wird dann direkt gegen die Basis URL des Items gesendet:

http://«your_server_ip»:«your_services_port»/rest/items/«item_path»

Ein POST/PUT Request mit 0 im HTTP Body an http://192.168.178.100:1234/rest/items/office.light ebenfalls das Licht ausschalten.

Testen lässt sich das Ganze dann beispielsweise mit dem Plugin Postman aus dem Chrome App Store (Link):

Die HTTP Methoden PATCH und DELETE werden zur Zeit noch nicht unterstützt!

Fehlerfall

Im Fehlerfall, etwa bei einem falschen oder nicht freigegebenen Itempfad, wird bei beiden Interfaces (REST und Simple) eine JSON Fehlermeldung zurückgegeben:

Itemsets (lesend) zugreifen

Sowohl via REST, als auch das Simple Webservices Interface lassen sich Itemsets lesend zugreifen.

Dies geschieht über folgende URL:

http://«your_server_ip»:«your_services_port»/ws/itemset/«set_name»

bzw.

http://«your_server_ip»:«your_services_port»/rest/itemset/«set_name»

Das Ergebnis sind die jeweiligen Daten der enthaltenen Items als Dictionary. Der key für den Zugriff ist dabei jeweils der Pfad des Items. Je nachdem, ob val oder full gesetzt ist, werden die Daten entsprechend gemerged:

Neben dem expliziten Zugriff auf die Itemsets, lassen sich auch alle (erlaubten) Items auf einmal abfragen:

http://«your_server_ip»:«your_services_port»/ws/items

bzw.

http://«your_server_ip»:«your_services_port»/rest/items

Für den Zugriff auf die Items im resultierenden JSON Dictionary, wird ebenfalls der Pfad des jew. Items verwendet.

Web GUI

Die Liste der zugreifbaren Items und Itemsets kann wie oben geschrieben auch via WebGUI abgerufen werden. Diese ist aus dem Backend-Plugin in der Pluginliste verlinkt.

In zukünftigen Artikeln wird die Nutzung des Webservices Plugins in Beispielapplikationen beschrieben.

Ein Proof of Concept existiert bereits für die ConnectIQ IDE (Garmin Uhren) und ein Projekt auf Basis eines ESP32. Hier kann unter https://www.smarthomeng.de/entfernungsmessung-auf-basis-eines-esp32-und-smarthomeng auch nachgelesen werden, wie sich die Daten via REST und Simple Webservices Interface aus C-Code heraus übertragen lassen. Auch ein erster Ansatz für ESPEasy wurde bereits umgesetzt.

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