From: Benjamin Braatz Date: Wed, 16 Nov 2022 08:38:53 +0000 (+0100) Subject: Add documentation. X-Git-Url: http://git.graph-it.com/?a=commitdiff_plain;ds=sidebyside;p=graphit%2Fcontrolpi-pinio.git Add documentation. --- diff --git a/README.md b/README.md index 612edab..d77ff87 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,13 @@ # ControlPi Plugin for GPIO Pins and I2C I/O Cards -This distribution package contains a plugin for the +This distribution package contains plugins for the [ControlPi system](https://docs.graph-it.com/graphit/controlpi), that -<…> +allow to use the GPIO pins of a Raspberry Pi, setting them with commands +and getting events when their state changes. +Moreover, it contains plugins for I2C I/O cards based on the PCF 8574 chip +that register clients for all input or output channels of the card. 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-pinio/](https://docs.graph-it.com/graphit/controlpi-pinio/). 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-pinio/controlpi_plugins/](https://docs.graph-it.com/graphit/controlpi-pinio/controlpi_plugins/). diff --git a/conf.json b/conf.json index 55d7cf8..86c2a6a 100644 --- a/conf.json +++ b/conf.json @@ -7,47 +7,35 @@ "location": "Debug" } } }, - "Output Card 1": { - "plugin": "OutputCard", - "address": 56, - "pins": { "T1-1": 0, "T1-2": 1, "T1-3": 2, "T1-4": 3, - "T1-5": 4, "T1-6": 5, "T1-7": 6, "T1-8": 7 } + "Aktor": { + "plugin": "OutputPin", + "pin": 23 }, - "Output Card 2": { - "plugin": "OutputCard", - "address": 57, - "pins": { "T1-9": 0, "T1-10": 1, "T1-11": 2, "T1-12": 3, - "T1-13": 4, "T1-14": 5, "T1-15": 6, "T1-16": 7 } + "Relais": { + "plugin": "HackPin", + "pin": 24 }, - "Input Card 1": { - "plugin": "InputCard", - "address": 32, - "interrupt pin": 4, - "pins": { "T1-18": 0, "T1-19": 1, "T1-20": 2, "T1-21": 3, - "T1-22": 4, "T1-23": 5, "T1-24": 6, "T1-25": 7 } + "Sensor": { + "plugin": "InputPin", + "pin": 25, + "glitch filter": 10000, + "pullup": true }, - "Input Card 2": { - "plugin": "InputCard", - "address": 33, - "interrupt pin": 17, - "pins": { "T1-26": 0, "T1-27": 1, "T1-28": 2, "T1-29": 3, - "T1-30": 4, "T1-31": 5, "T1-32": 6, "T1-33": 7 } + "Dimmer": { + "plugin": "PWMPin", + "pin": 18, + "freq": 10000000, + "duty": 0 }, - "Input Card 3": { - "plugin": "InputCard", - "address": 34, - "interrupt pin": 27, - "pins": { "T2-1": 0, "T2-2": 1, "T2-3": 2, "T2-4": 3, - "T2-5": 4, "T2-6": 5, "T2-7": 6, "T2-8": 7 } + "Ausgangskarte 1": { + "plugin": "OutputCard", + "address": 56, + "pins": { "Aktor 1": 0, "Aktor 2": 2, "Aktor 3": 4 } }, - "Input Card 3": { + "Eingangskarte 1": { "plugin": "InputCard", - "address": 35, - "interrupt pin": 22, - "pins": { "T2-9": 0, "T2-10": 1, "T2-11": 2, "T2-12": 3, - "T2-13": 4, "T2-14": 5, "T2-15": 6, "T2-16": 7 } - }, - "Example State": { - "plugin": "State" + "address": 32, + "interrupt pin": 4, + "pins": { "Sensor 1": 0, "Sensor 2": 2, "Sensor 3": 4 } } } diff --git a/doc/index.md b/doc/index.md index 0913b50..69b4eaa 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,8 +1,12 @@ -# ControlPi-Plugin für <…> -Dieses Paket enthält ein Plugin für das ControlPi-System, mit dem <…> - -## Benutzung -… +# ControlPi-Plugin für GPIO-Pins und I2C-I/O-Karten +Dieses Paket enthält Plugins für das ControlPi-System, mit denen die +GPIO-Pins eines Raspberry Pi als Klienten am ControlPi-Bus angemeldet +werden können, bei denen Ausgangs-Pins durch Kommandos gesetzt werden +können und sowohl Ausgangs- als auch Eingangs-Pins Ereignisse senden, wenn +sich ihr Zustand ändert. +Desweiteren enthält es Plugins für I2C-I/O-Karten auf Basis des +PCF-8574-Chips für die Klienten für alle Input- oder Output-Kanäle der +Karten registriert werden können. ## Installation Eine ausführliche Dokumentation ist in der Dokumentation der @@ -11,7 +15,7 @@ finden. Der Code dieses Plugins kann mit git geclonet werden: ```sh -$ git clone git://git.graph-it.com/graphit/controlpi-.git +$ git clone git://git.graph-it.com/graphit/controlpi-pinio.git ``` (Falls Zugang zu diesem Server per SSH besteht und Änderungen gepusht werden sollen, sollte stattdessen die SSH-URL benutzt werden.) @@ -24,5 +28,109 @@ Dann kann es editierbar in ein virtuelles Environment installiert werden: Auf dem Raspberry Pi (oder wenn keine Code-Änderungen gewünscht sind) kann es auch direkt, ohne einen git-Clone installiert werden: ```sh -(venv)$ pip install git+git://git.graph-it.com/graphit/controlpi-.git +(venv)$ pip install git+git://git.graph-it.com/graphit/controlpi-pinio.git +``` + +## Benutzung +Für die Benutzung der GPIO-Pins des Pi selbst, gibt es die Plugins +`OutputPin`, `HackPin`, `InputPin` und `PWMPin`. + +`OutputPin` und `HackPin` werden einfach nur mit der Angabe des Pins +(GPIO-Nummer zwischen 0 und 31) konfiguriert: +```json + "Aktor": { + "plugin": "OutputPin", + "pin": 23 + }, + "Relais": { + "plugin": "HackPin", + "pin": 24 + }, +``` +Diesen Plugins können dann Kommandos +`{"target": "Aktor", "command": "set state", "new state": true}` bzw. +`{"target": "Relais", "command": "set state", "new state": false}` gesendet +werden. +Der Unterschied zwischen `OutputPin` und `HackPin` ist, dass `OutputPin` +die Versorgungsspannung des Pi auf den Pin legt, während `HackPin` den Pin +auf Masse zieht, was für das Schalten einiger Arten von Relais notwendig +ist. +Außerdem kann beiden das Kommando +`{"target": "Aktor", "command": "get state"}` gesendet werden, welches den +momentanen Zustand als Nachricht auf den Bus legt. +Die Nachrichten von den Plugins haben die Form +`{"sender": "Aktor", "event": "changed", "state": true}` bzw. +`{"sender": "Relais", "state": false}`. +`"event": "changed"` wird nur aufgenommen, wenn sich der Zustand +tatsächlich geändert hat. + +Für `InputPin` kann zusätzlich zur Angabe des Pins optional der +Glitch-Filter (zwischen 0 und 300 000 Mikrosekunden, Default sind 5000 +Mikrosekunden) und der Pull-Up-Widerstand konfiguriert werden (Default ist +Benutzung des Pull-Down-Widerstands): +```json + "Sensor": { + "plugin": "InputPin", + "pin": 25, + "glitch filter": 10000, + "pullup": true + }, +``` +Ein `InputPin`-Plugin verarbeitet nur `get state`-Kommandos. +Die Nachrichten, die das Plugin sendet, haben die gleiche Form wie bei +`OutputPin` und `HackPin`. + +Das `PWMPin`-Plugin ermöglicht es, auf den GPIO-Pins 12 und 13 bzw. 18 und +19 Pulse-Width-Modulation zu benutzen. +Hierfür kann eine Frequenz zwischen 1 MHz und 125 MHz gewählt werden (wobei +die `pigpio`-Dokumentation Werte kleiner als 30 MHz empfiehlt. +Der aktive Anteil wird mit dem Parameter `duty` gewählt, der zwischen 0 +(aus) und 1 000 000 (durchgehend an) liegen kann: +```json + "Dimmer": { + "plugin": "PWMPin", + "pin": 18, + "freq": 10000000, + "duty": 0 + }, +``` +Die initialen Werte können durch die Kommandos +`{"target": "Dimmer", "command": "set freq", "new freq": 20000000}` und +`{"target": "Dimmer", "command": "set duty", "new duty": 500000}` geändert +werden. +Die Kommandos `get freq` und `get duty` fragen die aktuellen Werte ab. +Die Nachrichten vom Plugin haben die Form +`{"sender": "Dimmer", "freq": 10000000}` bzw. +`{"sender": "Dimmer", "event": "changed", "duty": 500000}`, wobei +`"event": "changed"` wiederum nur enthalten ist, wenn es tatsächlich eine +Änderung gab. + +Für die Benutzung der I2C-I/O-Karten, gibt es die Plugins `OutputCard` und +`InputCard`. + +Eine `OutputCard` wird konfiguriert, indem die I2C-Adresse angegeben wird +und einer Auswahl der Pins der Karte (diejenigen, die für die Anwendung +interessant sind) Namen zugewiesen werden: +```json + "Ausgangskarte 1": { + "plugin": "OutputCard", + "address": 56, + "pins": { "Aktor 1": 0, "Aktor 2": 2, "Aktor 3": 4 } + }, +``` +Die Kommandos an und Nachrichten von `"Aktor 1"`, `"Aktor 2"` und +`"Aktor 3"` sind dann genau die gleichen wie für `OutputPin` oben. + +Für eine `InputCard` wird zusätzlich ein `"interrupt pin"` (GPIO-Pin auf +dem Pi selbst) konfiguriert, auf dem die Karte meldet, wenn sich einer der +Karten-Pins geändert hat: +```json + "Eingangskarte 1": { + "plugin": "InputCard", + "address": 32, + "interrupt pin": 4, + "pins": { "Sensor 1": 0, "Sensor 2": 2, "Sensor 3": 4 } + } ``` +Kommandos und Nachrichten für `"Sensor 1"`, `"Sensor 2"` und `"Sensor 3"` +sind dann die gleichen wie für `InputPin` oben.