From: Benjamin Braatz Date: Wed, 23 Aug 2023 04:31:26 +0000 (+0200) Subject: Initial commit X-Git-Url: http://git.graph-it.com/?a=commitdiff_plain;h=294d431cf9d84101d669bd4e0e79cd60758945ac;p=tutorials%2Fcontrolpi-plugin.git Initial commit --- 294d431cf9d84101d669bd4e0e79cd60758945ac diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..a40b26c --- /dev/null +++ b/doc/index.md @@ -0,0 +1,149 @@ +# Wie schreibe ich ein ControlPi-Plugin? + +## Ziel des Tutorials +Das ControlPi-System soll um ein neues Plugin erweitert werden. + +In diesem Tutorial wird anhand eines kleinen Beispiels demonstriert, wie +ein ControlPi-Plugin entwickelt wird. + +Unser Beispiel soll einen Nachlauf implementieren, also beispielsweise, +dass ein Arbeitslicht, eine Schmierung oder eine Kühlung noch einige Zeit +weiter läuft, bevor sie tatsächlich ausgeschaltet wird. + +## Vorlage und Übersicht über Dateien +Im Repository `graphit/controlpi-template` befindet sich eine Vorlage eines +Controlpi-Plugins. +Dieses kann mit +`git clone git://git.graph-it.com/graphit/controlpi-template.git` oder +`git clone ssh://git@git.graph-it.com:44022/graphit/controlpi-template.git` +ausgecheckt werden. + +Dann kann es mit `mv controlpi-template controlpi-` oder `cp -r +controlpi-template controlpi-` (falls das Template wiederverwendet +werden soll) in das Verzeichnis für das neue Plugin verschoben oder kopiert +werden. +In diesem Verzeichnis löschen wir zunächst das `.git`-Verzeichnis (`rm -rf +.git/`), da wir Änderungen nicht das Template-Repository, sondern (falls +überhaupt) in ein neues Repository für das neue Plugin einchecken wollen. + +Für unser Beispiel führen wir also +```shell +$ cp -R controlpi-template controlpi-overshoot +$ cd controlpi-overshoot +$ rm -rf .git/ +``` +aus. + +Die Verbindung zu einem neuen, bisher leeren Repository kann durch +```shell +$ git init +$ git remote add origin ssh://git@git.graph-it.com:44022/graphit/controlpi-.git +$ git add . +$ git commit -m "Initial commit: Template" +$ git push --set-upstream origin master +``` +hergestellt werden. + +In diesem Repository befinden sich zunächst die folgenden Dateien: +```shell +$ tree -a +. +├── LICENSE +├── README.md +├── conf.json +├── controlpi_plugins +│   └── example.py +├── doc +│   └── index.md +└── setup.py +``` + +Das eigentliche Plugin ist in `controlpi_plugins`. +In diesem Package werden alle Plugins implementiert, egal in welchem +Repository sie entwickelt werden. +Namens-Kollisionen sowohl beim Namen der Python-Datei als auch beim Namen +der darin enthaltenen Plugin-Klasse sollten vermieden werden. + +Wir benennen also zunächst die Datei um: +```shell +$ git mv controlpi_plugins/example.py controlpi_plugins/overshoot.py +``` +Der Inhalt der Datei wird weiter unten besprochen. + +`setup.py` enthält die Metadaten, die Python bzw. `pip` zur Installation +des Paketes braucht. +Hierbei wird auch die sehr kurze Beschreibung (auf Englisch) in `README.md` +verwendet. +Beide sollten für unser Projekt angepasst werden. +In `setup.py` können auch Abhängigkeiten zu anderen Python-Bibliotheken +deklariert werden. + +In `doc/index.md` befindet sich die längere Dokumentation unseres neuen +Plugins (auf Deutsch). +In `conf.json` befindet sich eine minimale Beispiel-Konfiguration für +dieses Plugin. +Die Beispiel-Konfiguration sollte mit möglichst wenig Abhängigkeiten zu +anderen Plugins auskommen und auch in der Dokumentation erläutert werden. + +## Einrichten eines Virtual Environments zum Entwickeln und Testen +Um die Installation von Paketen und Abhängigkeiten lokal zu halten, werden +in Python “Virtual Environments” eingesetzt. +Es bietet sich an, ein solches im Projekt-Verzeichnis anzulegen: +```shell +$ python3 -m venv venv/ +``` +Es wird mit +```shell +$ source venv/bin/activate +``` +aktiviert, wodurch die Python- und `pip`-Versionen auf der aktuellen Shell +diejenigen genau dieser virtuellen Umgebung werden. + +Zunächst bringen wir die in einem Venv immer installierten Pakete auf den +neuesten Stand: +```shell +$ pip install -U pip setuptools wheel +``` +Dann installieren wir das aktuelle Paket in editierbarer Form: +```shell +$ pip install -e . +``` +„In editierbarer Form“ bzw. `-e` bedeutet dabei, dass Änderungen an den +Quell-Dateien in `controlpi_plugins` sofort wirksam werden. + +Da in `setup.py` eine Abhängigkeit auf das `controlpi`-Basispaket +deklariert ist, hat dieser Befehl auch dieses und all seine Abhängigkeiten +installiert: +```shell +$ pip list -v +Package Version Editable project location Location Installer +------------------- ------- ----------------------------- --------------------------------------------------------------- --------- +controlpi 0.3.0 /home/.../controlpi-overshoot/venv/lib/python3.11/site-packages pip +controlpi-overshoot 0.1.0 /home/.../controlpi-overshoot /home/.../controlpi-overshoot +fastjsonschema 2.18.0 /home/.../controlpi-overshoot/venv/lib/python3.11/site-packages pip +pip 23.2.1 /home/.../controlpi-overshoot/venv/lib/python3.11/site-packages pip +pyinotify 0.9.6 /home/.../controlpi-overshoot/venv/lib/python3.11/site-packages pip +setuptools 68.1.2 /home/.../controlpi-overshoot/venv/lib/python3.11/site-packages pip +wheel 0.41.2 /home/.../controlpi-overshoot/venv/lib/python3.11/site-packages pip +``` + +Solange das Venv aktiviert ist, kann das ControlPi-System jetzt theoretisch +gestartet werden: +```shell +$ python -m controlpi conf.json +Given configuration JSON file is not a JSON file! +^CShutting down on signal SIGINT. +``` + +Da wir aber noch nichts entwickelt, die `conf.json` noch nicht angepasst +haben und diese noch einen Platzhalter enthält, passiert hier noch nichts. + +## Implementierung des Plugins selbst + + + +### Konfigurations-Schema + +### Registrierung am Message-Bus + +### Callbacks