webservices

Das Webservices Plugin stellt ein REST basiertes API für SmartHomeNG bereit. Es werden PUT und GET Kommandos unterstützt.

Anforderungen

Das Plugin benötigt CherryPy um zu laufen, sowie ein konfiguriertes http Modul in SmartHomeNG. Grundsätzlich ist das http Modul in SmartHomeNG bereits konfiguriert. Die Konfiguration kann über das Admin Interface geändert werden oder durch direkte Änderung in der Datei etc/module.yaml jeweils mit anschließendem Neustart von SmartHomeNG.

Konfiguration

Die Informationen zur Konfiguration des Plugins sind unter Plugin ‚webservices‘ Konfiguration beschrieben.

plugin.yaml

Bitte die Dokumentation lesen, die aus den Metadaten der plugin.yaml erzeugt wurde.

items.yaml

Bitte die Dokumentation lesen, die aus den Metadaten der plugin.yaml erzeugt wurde.

logic.yaml

Bitte die Dokumentation lesen, die aus den Metadaten der plugin.yaml erzeugt wurde.

Funktionen

Bitte die Dokumentation lesen, die aus den Metadaten der plugin.yaml erzeugt wurde.

Beispiele und Nutzungshinweise

Das Webservices Plugin unterstützt drei leicht unterschiedliche Arten von Zugriffen, die im Folgenden beschrieben werden.

Mit einer URL http://{SmartHomeNG IP}:{http_modul_services_port}/ws/items/{item_path} wird ein Datensatz inklusive Metadaten abgefragt.

Beispielsweise liefern Abfragen wie http://192.168.1.1:8384/ws/items/knx.gf.office.light folgende JSON formatierte Daten:

{"changed_by": "Cache", "enforce_updates": "False", "age": 1896.412548, "triggers": ["bound method KNX.update_item of plugins.knx.KNX", "bound method WebSocket.update_item of plugins.visu_websocket.WebSocket", "bound method Simulation.update_item of plugins.simulation.Simulation"], "last_change": "2017-12-02 06:53:56.310862+01:00", "autotimer": "False", "eval": "None", "value": true, "previous_age": "", "previous_value": true, "type": "bool", "config": {"alexa_actions": "turnOn turnOff", "alexa_name": "Lampe B\u00fcro", "knx_dpt": "1", "knx_init": "2/3/50", "knx_listen": "2/3/50", "knx_send": ["2/3/10"], "nw": "yes", "sim": "track", "visu_acl": "rw"}, "name": "knx.gf.office.light", "path": "knx.gf.office.light", "threshold": "False", "cache": "/python/smarthome/var/cache/knx.gf.office.light", "cycle": "", "last_update": "2017-12-02 06:53:56.310862+01:00", "previous_change": "2017-12-02 07:18:22.911165+01:00", "eval_trigger": "False", "crontab": "", "logics": ["LightCheckLogic"]}

Sollte das Attribut webservices_data des Items auf val gesetzt sein, liefert die Abfrage nur den Wert des Items.

Wenn ein Fehler auftritt (z.B. Item nicht gefunden) liefert das Plugin eine JSON formatierte Fehlermeldung aus:

{"Error": "No item with item path <itemname> found."}

Eine erfolgreiche Wertänderung eines Items dagegen liefert eine JSON formatierte Rückgabe der Art:

{"Success": "Item with item path <itemname> set to <value>."}

Web Interface

Das webservices Plugin verfügt über ein Webinterface, mit dessen Hilfe die Items, die das Plugin nutzen kann, übersichtlich dargestellt werden.

Wichtig

Das Webinterface des Plugins kann mit SmartHomeNG v1.4.2 und davor nicht genutzt werden. Es wird dann nicht geladen. Diese Einschränkung gilt nur für das Webinterface. Ansonsten gilt für das Plugin die in den Metadaten angegebene minimale SmartHomeNG Version.

Aufruf des Webinterfaces

Das Plugin kann aus dem Admin Interface aufgerufen werden. Dazu auf der Seite Plugins in der entsprechenden Zeile das Icon in der Spalte Web Interface anklicken.

Außerdem kann das Webinterface direkt über http://\<SmartHomeNG_IP\>:\<http_modul_port\>/plugin/\<webservices\> aufgerufen werden.

http_modul_port steht in diesem Fall für den im http Modul definierten Port. webservices steht für den Namen mit dem das Plugin in etc/plugin.yaml definiert worden ist.

Beispiele

Folgende Informationen können im Webinterface angezeigt werden:

Oben rechts werden allgemeine Parameter zum Plugin angezeigt.

Im unteren Teil werden die Items angezeigt, die per REST Interface abgefragt werden können:

../../_images/webif19.jpg