From: Benjamin Braatz Date: Wed, 16 Nov 2022 13:31:14 +0000 (+0100) Subject: Add documentation. X-Git-Tag: v0.3.0~4 X-Git-Url: http://git.graph-it.com/?a=commitdiff_plain;h=72cc36dd21b30222df6368872c9b5c83438ae2fc;p=graphit%2Fcontrolpi-wsclient.git Add documentation. --- diff --git a/README.md b/README.md index fb01570..25c0ae0 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,11 @@ # ControlPi Plugin for Websocket Clients This distribution package contains a plugin for the [ControlPi system](https://docs.graph-it.com/graphit/controlpi), that -<…> +allows to connect via websocket to another ControlPi instance with a +[WSServer](https://docs.graph-it.com/graphit/controlpi-wsserver) plugin. Documentation (in German) can be found at [doc/index.md](doc/index.md) in the source repository and at [https://docs.graph-it.com/graphit/controlpi-wsclient/](https://docs.graph-it.com/graphit/controlpi-wsclient/). Code documentation (in English) including doctests is contained in the source files. -An API documentation generated by pdoc3 can be found at -[doc/controlpi_plugins/index.html](doc/controlpi_plugins/index.html) in the source -repository and at -[https://docs.graph-it.com/graphit/controlpi-wsclient/controlpi_plugins/](https://docs.graph-it.com/graphit/controlpi-wsclient/controlpi_plugins/). diff --git a/conf-controller.json b/conf-controller.json index e123b75..0ebaa8e 100644 --- a/conf-controller.json +++ b/conf-controller.json @@ -7,11 +7,28 @@ "location": "Debug" } } }, - "Engine Clearance": { - "plugin": "State" + "Machine on": { + "plugin": "Alias", + "from": { + "original sender": { "const": "switch/Switch" }, + "state": { "const": true } + }, + "to": { + "target": "machine/Machine", + "command": "set state", + "new state": true + } }, - "Connection Logger": { - "plugin": "Log", - "filter": [ { "sender": { "const": "Machine" } } ] + "Machine off": { + "plugin": "Alias", + "from": { + "original sender": { "const": "switch/Switch" }, + "state": { "const": false } + }, + "to": { + "target": "machine/Machine", + "command": "set state", + "new state": false + } } } diff --git a/conf-machine.json b/conf-machine.json index cba238d..9d9cc58 100644 --- a/conf-machine.json +++ b/conf-machine.json @@ -1,7 +1,7 @@ { - "Machine": { + "Debug": { "plugin": "WSServer", - "port": 8081, + "port": 8082, "web": { "/": { "module": "controlpi_plugins.wsserver", "location": "Debug" } @@ -10,25 +10,12 @@ "Controller": { "plugin": "WSClient", "url": "ws://localhost:8080", - "interface": "enp0s25", - "client": "Machine", - "up filter": [ { "sender": { "const": "Engine" } } ], - "down filter": [ { "sender": { "const": "Engine Clearance" } } ] - }, - "Engine Clearance": { - "plugin": "Alias", - "from": { "original sender": { "const": "Controller/Engine Clearance" } }, - "to": { } + "interface": "eno1", + "client": "machine", + "up filter": [], + "down filter": [ { "target": { "const": "Machine" } } ] }, - "Engine Switch": { + "Machine": { "plugin": "State" - }, - "Engine": { - "plugin": "AndState", - "states": [ "Engine Clearance", "Engine Switch" ] - }, - "Connection Logger": { - "plugin": "Log", - "filter": [ { "sender": { "const": "Controller" } } ] } } diff --git a/conf-switch.json b/conf-switch.json new file mode 100644 index 0000000..b5993dc --- /dev/null +++ b/conf-switch.json @@ -0,0 +1,20 @@ +{ + "Debug": { + "plugin": "WSServer", + "port": 8081, + "web": { + "/": { "module": "controlpi_plugins.wsserver", + "location": "Debug" } + } + }, + "Controller": { + "plugin": "WSClient", + "url": "ws://localhost:8080", + "client": "switch", + "up filter": [ { "sender": { "const": "Switch" } } ], + "down filter": [] + }, + "Switch": { + "plugin": "State" + } +} diff --git a/doc/DebugConnection.png b/doc/DebugConnection.png new file mode 100644 index 0000000..0cfe510 Binary files /dev/null and b/doc/DebugConnection.png differ diff --git a/doc/DebugController.png b/doc/DebugController.png new file mode 100644 index 0000000..e44064e Binary files /dev/null and b/doc/DebugController.png differ diff --git a/doc/DebugMachine.png b/doc/DebugMachine.png new file mode 100644 index 0000000..05acfa2 Binary files /dev/null and b/doc/DebugMachine.png differ diff --git a/doc/DebugSwitch.png b/doc/DebugSwitch.png new file mode 100644 index 0000000..4945842 Binary files /dev/null and b/doc/DebugSwitch.png differ diff --git a/doc/index.md b/doc/index.md index cded302..837110e 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,8 +1,8 @@ # ControlPi-Plugin für Websocket-Client -Dieses Paket enthält ein Plugin für das ControlPi-System, mit dem <…> - -## Benutzung -… +Dieses Paket enthält ein Plugin für das ControlPi-System, mit dem eine +Websocket-Verbindung zu einer anderen ControlPi-Instanz mit einem +[WSServer](https://docs.graph-it.com/graphit/controlpi-wsserver)-Plugin +hergestellt werden kann. ## Installation Eine ausführliche Dokumentation ist in der Dokumentation der @@ -26,3 +26,131 @@ es auch direkt, ohne einen git-Clone installiert werden: ```sh (venv)$ pip install git+git://git.graph-it.com/graphit/controlpi-wsclient.git ``` + +## Benutzung +Als Beispiel bauen wir eine kleine übergeordnete Steuerung auf. +Es verbinden sich dabei zwei `WSClient`-Instanzen, `switch` und `machine`, +mit einem Controller, und dieser sorgt dafür dass das Schalten des `switch` +zur `machine` weitergeleitet wird. + +Die Konfiguration des Controller ist: +```json +{ + "Controller": { + "plugin": "WSServer", + "port": 8080, + "web": { + "/": { "module": "controlpi_plugins.wsserver", + "location": "Debug" } + } + }, + "Machine on": { + "plugin": "Alias", + "from": { + "original sender": { "const": "switch/Switch" }, + "state": { "const": true } + }, + "to": { + "target": "machine/Machine", + "command": "set state", + "new state": true + } + }, + "Machine off": { + "plugin": "Alias", + "from": { + "original sender": { "const": "switch/Switch" }, + "state": { "const": false } + }, + "to": { + "target": "machine/Machine", + "command": "set state", + "new state": false + } + } +} +``` +Sie enthält nur das `WSServer`-Plugin, mit dem sich beide untergeordneten +ControlPi-Instanzen verbinden und die beiden `Alias`-Plugins, die +Zustände des Schalters an die Maschine weiterleiten. +Hierbei wird davon ausgegangen, dass die untergeordneten Instanzen sich +jeweils mit dem richtigen Namen anmelden und auch eine Plugin-Instanz des +richtigen Namens enthalten. +Dabei wird auf den Schlüssel `"original sender"` gematcht, da der +`"sender"` innerhalb der übergeordneten Instanz die Websocket-Verbindung +ohne weitere Unterscheidung ist, wir uns aber für genau eine Instanz auf +der anderen Seite interessieren. + +Die Konfiguration des Schalters ist: +```json +{ + "Debug": { + "plugin": "WSServer", + "port": 8081, + "web": { + "/": { "module": "controlpi_plugins.wsserver", + "location": "Debug" } + } + }, + "Controller": { + "plugin": "WSClient", + "url": "ws://localhost:8080", + "client": "switch", + "up filter": [ { "sender": { "const": "Switch" } } ], + "down filter": [] + }, + "Switch": { + "plugin": "State" + } +} +``` +Und die Konfiguration der Maschine ist: +```json +{ + "Debug": { + "plugin": "WSServer", + "port": 8082, + "web": { + "/": { "module": "controlpi_plugins.wsserver", + "location": "Debug" } + } + }, + "Controller": { + "plugin": "WSClient", + "url": "ws://localhost:8080", + "interface": "eno1", + "client": "machine", + "up filter": [], + "down filter": [ { "target": { "const": "Machine" } } ] + }, + "Machine": { + "plugin": "State" + } +} +``` +Ein `WSClient`-Plugin wird mit der `"url"` zur übergeordneten Instanz, +einem `"client"`-Namen, unter dem sie sich dort anmeldet, und einem +`"up filter"` und einem `"down filter"` konfiguriert, die angeben welche +Nachrichten über den Websocket weitergeleitet werden sollen. +In diesem Fall sollen vom Schalter nur Nachrichten des `Switch` nach oben +weitergeleitet werden und von der Maschine nur Nachrichten an die +`Machine` nach unten. + +Außerdem kann optional ein `interface` angegeben werden, was zur Folge hat, +dass im `"connection opened"`-Ereignis die MAC-Adresse dieses Interfaces +mitgesendet wird. +Dies kann z.B. genutzt werden, um der untergeordneten Instanz daraufhin +automatisch ihre Konfiguration zu übermitteln. +In der Debug-Oberfläche des Controllers sehen die beiden +Verbindungs-Ereignisse demzufolge so aus: +![Verbindungen in der Debug-Oberfläche](graphit/controlpi-wsclient/DebugConnection.png) + +Jetzt wird in der Debug-Oberfläche des Schalters dieser geschaltet: +![Debug-Oberfläche Schalter](graphit/controlpi-wsserver/DebugSwitch.png) +Wir sehen dies in der Debug-Oberfläche des Controllers ankommen, was den +entsprechenden Alias auslöst, der wiederum eine Nachricht an die Maschine +auslöst: +![Debug-Oberfläche Controller](graphit/controlpi-wsserver/DebugController.png) +Und in der Oberfläche der Maschine sehen wir schließlich, wie dieses dazu +führt, dass die Maschine tatsächlich geschaltet wird: +![Debug-Oberfläche Maschine](graphit/controlpi-wsserver/DebugMachine.png)