ControlPi-Plugin für Websocket-Server

Dieses Paket enthält ein Plugin für das ControlPi-System, mit dem ein Websocket-Server zur Verfügung gestellt wird, der eine Verbindung mit dem System durch verschiedene Clients ermöglicht. Außerdem stellt er eine einfache Debug-Oberfläche zur Verfügung, die alle auf dem System vorhandenen Komponenten, ihren momentanen Zustand und die zuletzt von ihnen gesandten Nachrichten darstellt und es ermöglicht, ihre Kommandos direkt aufzurufen.

Installation

Eine ausführliche Dokumentation ist in der Dokumentation der ControlPi-Infrastruktur zu finden.

Der Code dieses Plugins kann mit git geclonet werden:

$ git clone git://git.graph-it.com/graphit/controlpi-wsserver.git

(Falls Zugang zu diesem Server per SSH besteht und Änderungen gepusht werden sollen, sollte stattdessen die SSH-URL benutzt werden.)

Dann kann es editierbar in ein virtuelles Environment installiert werden:

(venv)$ pip install --editable <Pfad zum Code-Repository>

Auf dem Raspberry Pi (oder wenn keine Code-Änderungen gewünscht sind) kann es auch direkt, ohne einen git-Clone installiert werden:

(venv)$ pip install git+git://git.graph-it.com/graphit/controlpi-wsserver.git

Benutzung

Das Plugin WSServer stellt zum einen einen Websocket bereit, mit dem sich unterschiedliche Clients mit dem Bus der ControlPi-Instanz, auf der das Plugin benutzt wird, verbinden können. Zum anderen wird auch ein sehr einfacher Webserver zur Verfügung gestellt.

Die Konfiguration ist in folgendem Beispiel zu sehen:

{
    "Example Server": {
        "plugin": "WSServer",
        "port": 8080,
        "web": {
            "/": {"location": "web"},
            "/Debug": {"module": "controlpi_plugins.wsserver",
                       "location": "Debug"},
            "/Proxy": {"url": "http://localhost:8080/Debug"}
        }
    },
    "Example State": {
        "plugin": "State"
    },
    "Waiter": {
        "plugin": "Wait",
        "seconds": 3
    },
    "Delay Start after On": {
        "plugin": "Alias",
        "from": {
            "sender": { "const": "Example State" },
            "event": { "const": "changed" },
            "state": { "const": true }
        },
        "to": {
            "target": "Waiter",
            "command": "wait"
        }
    },
    "State Off after Delay": {
        "plugin": "Alias",
        "from": {
            "sender": { "const": "Waiter" },
            "event": { "const": "finished" }
        },
        "to": {
            "target": "Example State",
            "command": "set state",
            "new state": false
        }
    }
}

Auf welchem Interface und welchem Port der Websocket-Server registriert wird, wird durch die Attribute "host" und "port" festgelegt (Defaults: alle Interfaces und Port 80). Das Attribut "web" enthält eine Map von Locations auf den im jeweiligen Pfad zur Verfügung gestellten Inhalt. Die drei Möglichkeiten sind:

• Einzelner "location"-Schlüssel: Es wird ein Verzeichnis (ausgehend vom Verzeichnis, in dem die ControlPi-Instanz gestartet wurde) ausgeliefert. Hier können HTML-, CSS- und Javascript-Dateien wie in einem vollwertigen Webserver liegen.
• "location"-Schlüssel mit "module"-Schlüssel: Es wird ein Verzeichnis innerhalb eines installierten Python-Moduls ausgeliefert. Das wsserver-Modul liefert eine generische Debug-Oberfläche mit, die von den meisten Beispielen auch bei anderen Paketen verwendet wird.
• "url"-Schlüssel: Der Websocket-Server fungiert als Proxy zur gegebenen URL. Alle Anfragen werden auf Pfade unterhalb dieser URL umgeschrieben und weitergeleitet. Dies kann z.B. für Services verwendet werden, die selbst nur von der ControlPi-Instanz, aber nicht von außen erreichbar sind.

Die Ansicht der Debug-Oberfläche in diesem Beispiel (weitergeleitet durch den Proxy) ergibt dann Folgendes:

Die Debug-Oberfläche verbindet sich mit dem Bus der ControlPi-Instanz über den zur Verfügung gestellten Websocket (den auch andere Clients verwenden können). Dies ist der WSServer-Client auf der linken Seite. Der Websocket stellt alle Nachrichten, die auf dem Bus gesendet werden, zur Verfügung und kann selbst beliebige Nachrichten auf den Bus schreiben. Die Debug-Oberfläche nutzt das, um das Senden aller bei den Clients definierten Kommandos anzubieten.

In dem Beispiel im Bild wurde der Beispiel-Zustand über die Debug-Oberfläche einmal auf true gesetzt, woraufhin der Delay Start after On-Alias den Waiter gestartet hat und dieser nach drei Sekunden über den State Off after Delay-Alias den Zustand wieder auf false gesetz hat.

Ein Client kann durch Senden eines "configure websocket"-Kommandos mit Schlüsseln "up filter" und "down filter" einschränken, welche Nachrichten er erhalten möchte und welche er ankündigt, über den Websocket zu senden.