From: Benjamin Braatz Date: Wed, 9 Nov 2022 13:43:32 +0000 (+0100) Subject: Add documentation. X-Git-Url: http://git.graph-it.com/?a=commitdiff_plain;h=90385c774a68b59df343d6141ecd42be9cf97c85;p=graphit%2Fcontrolpi-graph.git Add documentation. --- diff --git a/README.md b/README.md index cdc7855..2dcbc94 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,11 @@ # ControlPi Plugin for Graph Connections This distribution package contains a plugin for the [ControlPi system](https://docs.graph-it.com/graphit/controlpi), that -<…> +connects to a given graph and pushes the messages matching the given filter +to it. 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-graph/](https://docs.graph-it.com/graphit/controlpi-graph/). 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-graph/controlpi_plugins/](https://docs.graph-it.com/graphit/controlpi-graph/controlpi_plugins/). diff --git a/conf.json b/conf.json index a0754fc..0fb89eb 100644 --- a/conf.json +++ b/conf.json @@ -1,73 +1,35 @@ { - "Example Server": { - "plugin": "WSServer", - "port": 8080, - "web": { - "/": { "module": "controlpi_plugins.wsserver", - "location": "Debug" } - } - }, - "Test Graph": { - "plugin": "GraphConnection", - "url": "tls://graph.example.com", - "crt": "graph.crt" - }, - "Example State": { - "plugin": "State" - }, - "State to Graph On": { - "plugin": "Alias", - "from": { "sender": { "const": "Example State" }, - "state": { "const": true } }, - "to": { "target": "Test Graph", - "command": "set", - "node": "testnode", - "guid": "0123456789", - "attribute": "testboolean", - "value": true } - }, - "State to Graph Off": { - "plugin": "Alias", - "from": { "sender": { "const": "Example State" }, - "state": { "const": false } }, - "to": { "target": "Test Graph", - "command": "set", - "node": "testnode", - "guid": "0123456789", - "attribute": "testboolean", - "value": false } - }, - "Get from Graph": { - "plugin": "Alias", - "from": { "target": { "const": "Get from Graph" }, - "command": { "const": "execute" } }, - "to": { "target": "Test Graph", - "command": "get", - "node": "testnode", - "guid": "0123456789", - "attribute": "testboolean" } - }, - "Set with Key": { - "plugin": "Alias", - "from": { "target": { "const": "Set with Key" }, - "command": { "const": "execute" } }, - "to": { "target": "Test Graph", - "command": "set key", - "node": "testnode", - "key attribute": "name", - "key value": "test", - "attribute": "testnumber", - "value": 42000 } - }, - "Get with Key": { - "plugin": "Alias", - "from": { "target": { "const": "Get with Key" }, - "command": { "const": "execute" } }, - "to": { "target": "Test Graph", - "command": "get key", - "node": "testnode", - "key attribute": "name", - "key value": "test", - "attribute": "testnumber" } + "Master": { + "plugin": "WSServer", + "port": 8080, + "web": { + "/": { + "module": "controlpi_plugins.wsserver", + "location": "Debug" + } } + }, + "Example State": { + "plugin": "State" + }, + "Graph": { + "plugin": "Graph", + "url": "tls://graph.example.com", + "crt": "graph.crt", + "name": "te", + "filter": [ + { + "sender": { "const": "Example State" }, + "state": { "const": true } + } + ] + }, + "Graph-Sync": { + "plugin": "Periodic", + "seconds": 10, + "message": { + "target": "Graph", + "command": "sync" + } + } } diff --git a/doc/DebugView.png b/doc/DebugView.png new file mode 100644 index 0000000..fd5b412 Binary files /dev/null and b/doc/DebugView.png differ diff --git a/doc/coMessage.png b/doc/coMessage.png new file mode 100644 index 0000000..97978ab Binary files /dev/null and b/doc/coMessage.png differ diff --git a/doc/index.md b/doc/index.md index d891071..1cc6fbf 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,8 +1,7 @@ # ControlPi-Plugin für Graph-Connections -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 +Verbindung zu einem gegebenen Graphen aufgebaut werden kann, um die +Nachrichten, die den gegebenen Filter erfüllen, zu diesem zu übertragen. ## Installation Eine ausführliche Dokumentation ist in der Dokumentation der @@ -26,3 +25,77 @@ es auch direkt, ohne einen git-Clone installiert werden: ```sh (venv)$ pip install git+git://git.graph-it.com/graphit/controlpi-graph.git ``` + +## Benutzung +Eine minimale ControlPi-Konfiguration, die dieses Plugin benutzt, ist im +git-Repository enthalten: +```json +{ + "Master": { + "plugin": "WSServer", + "port": 8080, + "web": { + "/": { + "module": "controlpi_plugins.wsserver", + "location": "Debug" + } + } + }, + "Example State": { + "plugin": "State" + }, + "Graph": { + "plugin": "Graph", + "url": "tls://graph.example.com", + "crt": "graph.crt", + "name": "te", + "filter": [ + { + "sender": { "const": "Example State" }, + "state": { "const": true } + } + ] + }, + "Graph-Sync": { + "plugin": "Periodic", + "seconds": 10, + "message": { + "target": "Graph", + "command": "sync" + } + } +} +``` + +Die Verbindung zum Graphen wird über das `Graph`-Plugin hergestellt, wobei +das Attribut `url` die TLS-URL des Graphen enthält, das Attribut `crt` den +Pfad zum TLS-Client-Zertifikat (vom Verzeichnis, in dem `controlpi` +gestartet wird aus navigiert) und das Attribut `name` den Namen der +`coRoot`-Instanz im Graphen, an der die Nachrichten verknüpft und +verarbeitet werden sollen. +Der `filter` bestimmt, welche Nachrichten an den Graphen weitergeleitet +werden sollen, in diesem Fall nur Nachrichten, in denen der +Beispiel-Zustand `true` meldet. + +Auf dem Graphen muss das `controlpi`-Modul installiert und eine +`coRoot`-Instanz mit dem gegebenen Namen vorhanden sein, damit die +Strukturen, an denen die Nachrichten abgelegt werden, vorhanden sind. + +Die Nachrichten werden durch das Plugin gesammelt und an den Graphen +geliefert, wenn das Kommando `sync` and das `Graph`-Plugin gesendet wird. +Ein übliches Pattern ist, dass das `sync`-Kommando wie in diesem Beispiel +regelmäßig von einem `Periodic`-Plugin aufgerufen wird. + +In der Debug-Oberfläche sieht das Minimal-Beispiel so aus: +![Debug-Oberfläche](graphit/controlpi-graph/DebugView.png) + +Im Graphen können wir sehen, dass wegen des Filters nur die Nachrichten, +bei denen der Beispiel-Zustand auf `true` gesetzt wird, aber nicht +diejenigen, bei denen er auf `false` gesetzt wird, ankommen: +![coMessage im Graphen](graphit/controlpi-graph/coMessage.png) + +Um in umgekehrter Richtung Nachrichten aus dem Graphen an diese +ControlPi-Instanz zu schicken, wird das `WSServer`-Plugin benutzt. +Die URL zu diesem, z.B. `ws://graph.example.com:8080`, ist an der +`coRoot`-Instanz im Graphen hinterlegt, damit dort der Graphmodul-Service +`service('controlpi.send','te',['key'=>'value']);` verwendet werden kann.