From: Benjamin Braatz <benjamin.braatz@graph-it.com>
Date: Wed, 16 Nov 2022 12:08:34 +0000 (+0100)
Subject: Add documentation.
X-Git-Tag: v0.3.0~7
X-Git-Url: http://git.graph-it.com/?a=commitdiff_plain;h=bcada2071b94711a1ac7eb1cc6448dabc0758c9c;p=graphit%2Fcontrolpi-wsserver.git

Add documentation.
---

diff --git a/conf.json b/conf.json
index f814b0d..af7b467 100644
--- a/conf.json
+++ b/conf.json
@@ -13,7 +13,8 @@
         "plugin": "State"
     },
     "Waiter": {
-        "plugin": "GenericWait"
+        "plugin": "Wait",
+        "seconds": 3
     },
     "Delay Start after On": {
         "plugin": "Alias",
@@ -24,17 +25,14 @@
         },
         "to": {
             "target": "Waiter",
-            "command": "wait",
-            "seconds": 3.0,
-            "id": "off delay"
+            "command": "wait"
         }
     },
     "State Off after Delay": {
         "plugin": "Alias",
         "from": {
             "sender": { "const": "Waiter" },
-            "event": { "const": "finished" },
-            "id": { "const": "off delay" }
+            "event": { "const": "finished" }
         },
         "to": {
             "target": "Example State",
diff --git a/doc/DebugView.png b/doc/DebugView.png
new file mode 100644
index 0000000..1303d98
Binary files /dev/null and b/doc/DebugView.png differ
diff --git a/doc/index.md b/doc/index.md
index 86a5e32..42c1c0f 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -31,4 +31,97 @@ es auch direkt, ohne einen git-Clone installiert werden:
 ```
 
 ## 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:
+```json
+{
+    "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:
+![Debug-Oberfläche](graphit/controlpi-wsserver/DebugView.png)
+
+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.