diff --git a/README.md b/README.md new file mode 100644 index 0000000..7abb158 --- /dev/null +++ b/README.md @@ -0,0 +1,131 @@ +# ButtonCtl +ButtonCTL im oberen Stockwerk des Chaospott zur vereinfachenden Steuerung der via SSH kontrollierbaren Türen mithilfe +von physischen Buttons genutzt. Er ersetzt ein gleichnamiges älteres System. +In seiner momentanen Version ist es nicht mit der zweiten Button-Installation neben der Kellertür +kompatibel, und kann dort somit nicht eingesetzt werden. + +## Installation +### Software +Zur Installation der im nächsten Abschnitt besprochenen Abhängigkeiten öffnen sie zunächst eine Shell. +An diesem Punkt ist es ratsam das ihr System mit `sudo apt update && sudo apt upgrade` +zu aktualieren. Nun nutzen sie `sudo apt install python3-rpi-gpio` zur Installation der Python-RPi Library und +`sudo pip3 install adafruit-circuitpython-neopixel` zur Installation der ebenfalls notwendigen Neopixel-Library. +### Hardware +Zum Ausführen von ButtonCtl ist die korrekte Verkabelung aller Komponenten notwendig. Um +die Verkabelung in der aktuellen Installation des Systems im Club zu verändern, öffnen sie +den unteren, in der rechts neben der Tür im Bällebad befindlichen Wand verbauten Kasten. +Um den Raspberry Pi zu erreichen, müssen sie nun die dort verbauten Schrauben lösen, und die Abdeckung abnehmen. + +
+ +Das Programm kommuniziert mit dem LED-Strip über die Pins 7 (BCM 4) und 12 (BCM 18). Die Buttons sind den +Pins 23 (Aerie), 24 (Center), 22 (Keller) zugeordnet. + +## Abhängigkeiten +### Libraries +Zur Implementierung einiger zentraler Features werden folgende nicht-standard Libraries genutzt: +- RPi (raspbian: python3-rpi.gpio) +- neopixel (pypi: adafruit-circuitpython-neopixel) + +Da die Buttons nicht etwa über einzelne LEDs, sondern über einen einzelnen LED-Strip verläuft, angesteuert +werden müssen, wird die ```neopixel``` Library dazu genutzt, den aus 36 (3 * 12) Leds bestehenden Strip anzsuteuern +und auf Basis dessen zu einem Button-orientierten Interfcae zu abstrahieren. +Die LEDs sind folgendermaßen über die Buttons verteilt: +``` +(25-36) (13-24) (1-12) + AERIE KELLER +``` + +Um das dazu - und zur Button-Press Erkennung - benötigte GPIO-Board zu kontrollieren nutzt ButtonCtl die ```RPi.gpio``` +Library. + +### API +ButtonCtl greift auf die vom Chaospott bereitgestellte [SpaceAPI](http://spaceapi.net/)-Instanz, die - wie es die +Spezifikation vorsieht - neben den benötigten Sensor-Daten ebenfalls allgemeine Information +sowie Metadaten über den Hackerspace überträgt. +Die Statusinformationen befinden sich im `sensor` Bereich der JSON-Daten: +```json +{ + "door_locked": [ + { + "location": "aerie", + "value": false + }, + { + "location": "cellar", + "value": false + } + ] +} +``` + +### Türsteuerung +Zum Öffnen und Schließen der beiden Türen werden die jeweiligen SSH-Endpunkte genutzt: +- Keller + - `ssh unlock@10.42.1.20` + - `ssh lock@10.42.1.20` +- Aerie: open / close @ 10.42.1.28 + - `ssh open@10.42.1.28` + - `ssh close@10.42.1.28` + +## Benutzung +Wie durch wiederholte Ausfälle indiziert, sind die durch die API bereitgestellten Daten nicht immer zuverlässig, +und sollen somit Grund keinen Einfluss auf die Funktionalität der Buttons haben. In der Vergangenheit +erfolgte das Öffnen oder Schließen einer Tür durch einen einfachen Click auf den mit dieser assoziierten Knopf. +Unter der Voraussetzung, dass der gespeicherte Türstatus korrekt ist, wurde dieser dann geändert, das heißt die +Tür wurde geöffnet oder geschlossen. + +Um jenes Vorgehen trotz der Unwissenheit über den aktuellen Zustand der Türen zu ermöglichen, leuchtet in der neuen +Version, nach dem Drücken eines Türknopfes (1. / 3. Knopf für Aerie / Keller), ein Button grün und ein anderer rot auf. +Nach erneutem Drücken auf den grünen (roten) Button wird die Tür daraufhin geöffnet (geschlossen). + +Im Normalzustand leuchtet der mittlere Button nicht und die Tür-Buttons tragen die mit ihrem API-Status +assoziierten Farben. + +### Beispiele + +![Rot](https://placehold.it/15/ff0000/000000?text=+) +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) +→ Linker Button + +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Grün](https://placehold.it/15/00ff00/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) +→ Mittlerer Button + +![Rot](https://placehold.it/15/ff0000/000000?text=+) +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) +→ Kurze Wartezeit + +![Grün](https://placehold.it/15/00ff00/000000?text=+) +![Schwarz](https://placehold.it/15/000000j/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) + +---------- + +![Rot](https://placehold.it/15/ff0000/000000?text=+) +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) +→ Linker Button + +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Grün](https://placehold.it/15/00ff00/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) +→ Linker Button + +![Rot](https://placehold.it/15/ff0000/000000?text=+) +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) + +----------- + +![Rot](https://placehold.it/15/ff0000/000000?text=+) +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+) +→ Mittlerer Button + +![Rot](https://placehold.it/15/ff0000/000000?text=+) +![Schwarz](https://placehold.it/15/000000/000000?text=+) +![Rot](https://placehold.it/15/ff0000/000000?text=+)