Initiales Halloween-Projekt

SOFTWARE.md

@@ -0,0 +1,89 @@
+# Erste Pi-Softwareversion
+
+Diese Version implementiert ein Livebild des vorhandenen Camera Module 3 NoIR
+über Picamera2, eine lokale WebUI, Moduswahl mit Speicherung und eine
+**Simulation** des Effektablaufs. Sie steuert noch keine GPIOs, Motoren,
+Servos, Lampen oder Lautsprecher. Automatische Personenerkennung, Clips,
+Maskierung und Löschfristen sind noch nicht umgesetzt. Daher vorerst nur
+im privaten Testbereich verwenden; die Kamera nicht auf öffentliche Flächen
+richten.
+
+## Auf dem Raspberry Pi 5 vorbereiten
+
+Die Kamera mit passendem Kabel anschließen und mit `rpicam-hello --list-cameras`
+prüfen. Danach im Projektordner:
+
+```bash
+sudo apt update
+sudo apt install python3-picamera2 python3-venv
+python3 -m venv --system-site-packages .venv
+.venv/bin/python -m pip install -r requirements.txt
+```
+
+Picamera2 wird über die Raspberry-Pi-Pakete installiert; die virtuelle
+Umgebung kann dieses Systempaket durch `--system-site-packages` verwenden.
+Der Server bindet nur an `127.0.0.1` auf dem Pi. So ist das Livebild nicht
+direkt im WLAN sichtbar.
+
+### WebUI beim Hochfahren starten
+
+Nach der Vorbereitung kann `tools/install_pi_service.sh` auf dem Pi einen
+systemd-Dienst einrichten. Erst eine Vorschau ansehen, dann anwenden:
+
+```bash
+bash tools/install_pi_service.sh
+bash tools/install_pi_service.sh --apply
+systemctl status halloween-grab.service
+```
+
+Der Dienst läuft unter dem aktuellen Pi-Benutzer, startet `run.py` beim
+Hochfahren und wird bei einem Fehler neu gestartet. Das Skript benötigt für
+die Einrichtung `sudo` und überschreibt keine fremde Unit gleichen Namens.
+Nach Code-Updates kann derselbe `--apply`-Aufruf den Dienst neu starten.
+Zum Deaktivieren: `sudo systemctl disable --now halloween-grab.service`.
+Bei Startproblemen: `sudo journalctl -u halloween-grab.service -n 80 --no-pager`.
+Ein Browserfenster auf dem Laptop öffnet sich dadurch nicht automatisch.
+
+## Vom Laptop aus ansehen
+
+Mit dem geprüften Pi-Benutzer und Hostnamen ein SSH-Terminal offen lassen:
+
+```bash
+ssh -L 8000:127.0.0.1:8000 BENUTZER@HOST
+```
+
+Dann auf dem Laptop `http://127.0.0.1:8000` öffnen. Ein SSH-Passwort reicht;
+ein Schlüssel ist nicht nötig. Ist Port 8000 auf dem Laptop belegt, links
+vom ersten Doppelpunkt einen anderen freien Port wählen; rechts bleibt der
+Pi-Port 8000, solange `run.py` dort mit dem Standardport läuft.
+
+## Ohne Kamera testen
+
+Auf einem Rechner mit den Paketen aus `requirements.txt`:
+
+```bash
+python3 run.py --demo
+```
+
+Die Bildfläche trägt deutlich „DEMO – KEINE ECHTE KAMERA“. Über „Bereich
+frei (Test)“ und danach „Testauslösung“ lässt sich die Zustandsfolge ohne
+Aktoren durchspielen. „Stopp“ sperrt weitere Auslösungen bis „Zurücksetzen“
+und erneuter Freigabe des Bereichs. Der Modus „voller Schreck“ ist nur bei
+noch nicht vorhandenen Einstellungen der Standard. Ein WebUI-Wechsel wird
+unter `data/settings.json` gespeichert und bleibt bei normalem Neustart
+erhalten. Das Uploadskript überträgt diesen Laufzeitordner nicht.
+
+## Lokal prüfen
+
+Für die Webtests zusätzlich `httpx` installieren:
+
+```bash
+.venv/bin/python -m pip install -r requirements-dev.txt
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+Der Host-Test prüft Demo-Bild und Webendpunkte. Kamera, Nachtbild, WLAN,
+SSH-Tunnel und GPIOs müssen am echten Pi bzw. Aufstellort geprüft werden.
+
+Technische Grundlagen: [Picamera2-Handbuch](https://datasheets.raspberrypi.com/camera/picamera2-manual.pdf),
+[FastAPI-StreamingResponse](https://fastapi.tiangolo.com/advanced/stream-data/).