Initial commit

diff --git a/doc/index.md b/doc/index.md
new file mode 100644 (file)
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-<NAME>` oder `cp -r
+controlpi-template controlpi-<NAME>` (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-<NAME>.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