Halloween/SOFTWARE.md

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. Hand, Atemmotor, Lampen und Lautsprecher bleiben simuliert. Der separate Farbpunkt-Test kann die beiden Kameraservos am PCA9685 nach bewusstem Start tatsächlich bewegen. Eine lokale SQLite-Datenbank speichert Testereignisse und Profilkennungen. Lokale Personenerkennung mit Linienauslösung ist implementiert, muss aber am Pi installiert und kalibriert werden. Bei automatischer Auslösung wird ein Bild des grünen Bereichs lokal gespeichert. Profilzuordnung per Kamera, Clips und zusätzliche frei zeichnbare Masken sind noch nicht umgesetzt. Die 30-Tage-Löschung ist für künftige Auto-Profile vorbereitet. 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:

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. Beim Start über run.py bindet der Server nur an 127.0.0.1 auf dem Pi. Der versionierte Dienst nutzt dagegen die beim Upload gewählte Bind-Adresse (siehe unten); mit 0.0.0.0 ist die WebUI direkt im Heimnetz erreichbar.

WebUI beim Hochfahren starten

Das versionierte Uploadskript richtet den systemd-Autostart jetzt bei jedem Update mit --apply ein und prüft den gestarteten Webdienst. Anleitung, Rückfall und Datensicherung stehen in UPLOAD.md. Der Updateablauf verwendet eine gemeinsame SSH-Verbindung und einen einzigen sudo-Aufruf für Umschaltung und möglichen Rückfall; das Passwort wird nicht gespeichert. Python-Prüfungen laufen als Pi-Benutzer.

Der Dienst nutzt current/.venv, startet die WebUI beim Hochfahren und verweist für alle Laufzeitdaten auf den gemeinsamen Basisordner data/. Mit --web-host 0.0.0.0 beim Upload wird direkter Heimnetzzugriff aktiviert; ohne Angabe gilt die gespeicherte Wahl, anfänglich Loopback.

Auf dem Pi prüfen:

systemctl status halloween-grab.service
systemctl is-enabled halloween-grab.service

Der einzelne Installer bleibt für manuelle Einrichtung verfügbar: bash tools/install_pi_service.sh --project-dir /home/BENUTZER/halloween --apply. Er prüft keinen vollständigen Versionsrückfall; Updates deshalb vom Laptop über das Uploadskript durchführen. Autostart ist am echten Pi noch zu prüfen. 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:

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.

Direkt im Heimnetz ansehen

Auf Nutzerwunsch ist für den aktuellen Test auch direkter Zugriff im Heimnetz vorgesehen. Dafür auf dem Pi den laufenden Server mit Strg+C beenden und im Ordner ~/halloween starten:

.venv/bin/python -m uvicorn halloween.web:create_app --factory --host 0.0.0.0 --port 8000

Auf dem Laptop anschließend http://raspi5wlan.local:8000 öffnen; kein SSH-Tunnel nötig. 0.0.0.0 ist die Bind-Adresse, keine Browseradresse. Die WebUI hat noch keinen Login: Geräte im erreichbaren Heimnetz können Kamera und Bedienoberfläche nutzen. Eine öffentliche Internetfreigabe ist damit nicht beauftragt. Direkter Browserzugriff im Heimnetz ist noch nicht bestätigt. run.py bleibt bei Loopback; der neue systemd-Dienst unterstützt die beim Upload gewählte Bind-Adresse.

Ohne Kamera testen

Auf einem Rechner mit den Paketen aus requirements.txt:

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.

Ereignisdatenbank und Profile

Beim Start wird data/events.sqlite3 angelegt. Erfolgreiche manuelle Testauslösungen werden mit Zeitpunkt und Modus gespeichert und in der WebUI aufgelistet. Profilkennungen lassen sich anlegen, Ereignissen zum Testen zuordnen und wieder löschen. Beim Löschen eines Profils bleibt das Ereignis ohne Zuordnung erhalten. Die Daten bleiben bei einem Neustart und bei weiteren Uploads bestehen, weil das Uploadskript data/ auslässt.

Der Nutzer wünscht später automatische Wiedererkennung per Kamera. Diese Version erstellt noch keine Profile aus Kamerabildern. Gesichtsmerkmale und Clips werden nicht aufgenommen; Auslösebilder liegen als separate lokale JPEGs mit einem Verweis in der Ereignisdatenbank. Für künftig automatisch erstellte Profile sind Merkmalsvektoren und eine 30-Tage-Frist ab letzter Sichtung vorbereitet. Beim Start, stündlich und beim Lesen der Ereignisse/Profile werden abgelaufene Auto-Profile mitsamt Merkmalsvektoren entfernt. Manuelle Profile bleiben bis zur manuellen Löschung bestehen; Ereignisse bleiben ohne Profilzuordnung erhalten. Eine echte Zuordnung braucht noch Kameratests und eine Prüfung von Fehlzuordnungen.

Lokal prüfen

Für die Webtests zusätzlich httpx installieren:

.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, FastAPI-StreamingResponse.

Bilder zu automatischen Auslösungen

Bei jeder akzeptierten automatischen Auslösung (Linienüberquerung oder Bewegungs-Test) wird der grüne Auslösebereich des tatsächlich ausgewerteten Kamerabildes als JPEG unter data/event-images/ gespeichert. Außerhalb des gewählten Rechtecks wird nichts gespeichert. Der Bereich muss vor Aktivierung auf den vorgesehenen privaten Testbereich beschränkt sein. Keine zusätzliche Ton-/Clipaufnahme, keine Gesichtsmerkmale und keine Profilautomatik.

In Gespeicherte Ereignisse erscheinen eine kleine Vorschau und „Bild ansehen“ (öffnet das Bild in einem eigenen Tab). Die Liste aktualisiert sich alle 15 Sekunden; „Ereignisse aktualisieren“ lädt sie sofort neu. Bisherige Ereignisse und manuelle Testauslösungen haben kein gespeichertes Bild.

Auf ausdrückliche Nutzerwahl bleiben Bilder bis zur manuellen Löschung erhalten. „Bild löschen“ verlangt eine Bestätigung und entfernt das JPEG im aktiven Datenbestand. Ereignis, Zeitpunkt und Profilzuordnung bleiben erhalten. Es gibt keine automatische Alterslöschung dieser Bilder. Speicherbelegung am Pi beobachten; die vorhandenen Upload-Sicherungen können ältere Bilder enthalten und werden durch diesen Knopf nicht verändert.

JPEGs haben Dateirechte 0600, der Bildordner 0700. Abruf nur über die Ereignis-ID, keine statische Freigabe des gesamten data/-Ordners. GET /api/events liefert image_url oder null; GET /api/events/{id}/image liefert JPEG mit no-store, DELETE benötigt den vorhandenen UI-Header. Diese Schranke ersetzt keinen Login: Wie das Livebild sind Bilder im erreichbaren Heimnetz zugänglich. Keine öffentliche Freigabe. Upload und Versionswechsel bewahren data/ einschließlich Bilder.

Schreib-/Datenbankfehler werden angezeigt und sperren die Automatik bis zum bewussten Rücksetzen. Teilweise fehlgeschlagene Speichervorgänge räumen temporäre Bilder auf. Lokale Tests prüfen beschnittene Bilder, Trigger-Frame, Neustart, Alt-Datenbankmigration, Abruf/Löschen und Fehlerfälle mit synthetischen Bildern. Das Speichern und Anzeigen nach echter Pi-Auslösung ist noch zu prüfen.

Personenerkennung und Linienauslösung

Nach einem versionierten Update im aktiven Versionsordner auf dem Pi installieren:

cd ~/halloween/current
sudo apt update
sudo apt install python3-opencv python3-numpy
.venv/bin/python -c "import cv2, numpy; print(cv2.__version__, cv2.__file__); print(numpy.__version__)"
HALLOWEEN_STATE_DIR=/home/marcinator_2/halloween/data \
  .venv/bin/python tools/install_detection_model.py

Das Skript lädt ausschließlich das unquantisierte Modell object_detection_nanodet_2022nov.onnx des offiziellen OpenCV Zoo. Version, URL, Größe und SHA-256 stehen in halloween/nanodet-model.json. Das Modell liegt unter data/models/; ein bestehendes korrektes Modell wird nicht erneut geladen. Download erfolgt nur auf diesen ausdrücklichen Aufruf, HTTPS-Zertifikatsprüfung bleibt aktiv. Der Server lädt nichts aus dem Internet. Bei abweichendem HALLOWEEN_STATE_DIR diesen beim Installer ebenfalls setzen oder --state-dir angeben. Modellgewichte bleiben unversioniert und werden nicht vom Upload überschrieben. Auf dem Pi das fertige Systempaket verwenden; Picamera2 bleibt ebenfalls das Raspberry-Pi-Systempaket. OpenCV muss mindestens 4.10 sein; die tatsächliche installierte Version und Inferenz am Pi prüfen. Für andere Entwicklungsrechner kann requirements-detection.txt genutzt werden: Es erlaubt ausschließlich fertige Wheels und bricht ohne passende Pakete ab. Ein vorheriger pip-Installationsversuch kann lokale Pakete hinterlassen, die Systempakete überdecken; bei Importfehlern die ausgegebenen Pfade prüfen.

Server anschließend wie oben starten. In der Liveansicht:

1. Orange Linienendpunkte und die zwei grünen Bereichsecken ziehen. Die Linie muss vollständig innerhalb des Rechtecks liegen. Außerhalb des privaten Testbereichs darf die Auslösung nicht eingerichtet werden.
2. Mit „Richtung umkehren“ den Pfeil zum Grab ausrichten.
3. „Automatisch auslösen“ auswählen und „Linie und Bereich speichern“ drücken.
4. Mindestens zwei Sekunden den gesamten Bereich freihalten. Danach auf der Ankunftsseite beginnen und über die Linie zum Grab gehen.

Zunächst bleibt die automatische Auslösung aus. Gespeicherte Konfiguration und Aktivierung bleiben nach normalem Neustart erhalten, aber die Bereichsfreigabe und Tracking-IDs werden immer neu aufgebaut. Bei ungültiger Konfiguration bleibt die Automatik aus; der Fehler wird angezeigt.

Es werden nur Personen ausgewertet (Startschwelle 0,6). Mindestens drei aufeinanderfolgende Erkennungen bestätigen einen Track. Der Fußpunkt ist die Mitte der unteren Rahmenkante. Er muss von der Ankunftsseite über das endliche Liniensegment auf die Grabseite wechseln, jeweils mindestens 3 % der Bildhöhe von der Linie entfernt. Kurz auftauchende Personen hinter der Linie, Rückwege, Bewegung entlang der Linie und Überquerungen außerhalb des Segments lösen nichts aus. Verdeckung oder zu schnelles Überqueren kann zur Nichterkennung führen; die Startwerte sind praktisch zu kalibrieren.

Eine Gruppe erhält einen Effekt: Nach Auslösung sind zehn Sekunden Sperrzeit und mindestens zwei Sekunden freier Auslösebereich nötig. Auch unbestätigte Personenrahmen im Rechteck verhindern die Freigabe. Überquerungen während Sperre werden verworfen. Start, Moduswechsel, Rücksetzen und Änderungen der Konfiguration verlangen erneut einen freien Bereich. Stopp bleibt wirksam; ein manueller Testbutton umgeht keine Fehlersperre.

Kamera-/Modellfehler und mehr als zwei Sekunden ohne gültige Auswertung sperren die aktivierte Automatik und stoppen den simulierten Ablauf. Nach Beheben des Fehlers „Grab zurücksetzen“ verwenden und Bereich freihalten. Modellprobleme bei deaktivierter Automatik verhindern keine manuellen Tests. Der Demo-Livefeed und manuelle Tests brauchen weder OpenCV noch Modell; der Bewegungs-Test benötigt auch im Demo-Modus OpenCV. Synthetische Bilder sind kein Test der echten Personenerkennung.

Die Auswertung arbeitet im Hintergrund mit dem jeweils neuesten Bild, Ziel fünf Auswertungen/s. Die UI zeigt die gemessene Verarbeitungsrate. Bei Erkennungsergebnissen zeigt sie das zugehörige Bild statt des unabhängigen MJPEG-Bildes, damit Rahmen und Bild zusammenpassen. Nach zwei Sekunden sind Ergebnisse veraltet und die Rahmen verschwinden. Ohne Erkennungsbild bleibt der normale MJPEG-Stream verfügbar. /api/detection liefert Frame-Nummer, JPEG als Base64, normierte Personenrahmen, flüchtige Tracking-IDs und Status; GET/POST /api/detection/config liest/speichert Aktivierung, Linie, Richtung und Rechteck. POST benötigt wie andere Schreibaufrufe X-Halloween-UI: 1. /api/status enthält zusätzlich detection. Der Header ersetzt keinen Login.

Automatische Auslösungen werden als person_line_crossing ohne Profil in der bestehenden Datenbank gespeichert, mit lokalem Bild des grünen Bereichs aus dem auslösenden Frame. Tracking-IDs werden nicht gespeichert; Profil-Wiedererkennung und Altersentscheidung fehlen. Die Aktoren des Grabablaufs bleiben simuliert; Kameraservos haben einen eigenen Testmodus.

Nahbereich testen: Bewegung in Pfeilrichtung

In der WebUI unter Automatische Auslösung → Erkennung wählen den Modus „Test: Bewegung in Pfeilrichtung“ auswählen, „Automatisch auslösen“ anhaken und „Linie und Bereich speichern“ drücken. Der Modus wird lokal in data/detection.json gespeichert. Bisherige Einstellungen ohne Methodenfeld werden als Personenerkennung übernommen; diese bleibt der Standard.

Dieser Test benötigt OpenCV und NumPy aus den oben beschriebenen Pi-Systempaketen, aber kein NanoDet-Modell. Wenn OpenCV fehlt, auf dem Pi ausführen:

sudo apt install python3-opencv python3-numpy
sudo systemctl restart halloween-grab.service

Zuerst die Kamera fest abstellen und das Bild im grünen Bereich mindestens zwei Sekunden ruhig halten. Dann eine Hand, den Kopf oder einen Gegenstand sichtbar in Pfeilrichtung bewegen. Eine Person muss weder vollständig sichtbar sein noch wird eine Linienüberquerung verlangt: Die Linie legt in diesem Modus nur den Pfeil fest. Für Bewegung nach links/rechts die Linie entsprechend senkrecht stellen; mit „Richtung umkehren“ die Pfeilrichtung wechseln.

Es müssen zwei aufeinanderfolgende Auswertungen gerichtete Bildbewegung im gewählten Bereich bestätigen. Der Test wertet auch kleine, langsame Änderungen im Nahbereich aus. Unter der Statuszeile stehen der geänderte Bildanteil, die Richtungsbewertung und „Bestätigung 0/2“, „1/2“ oder „2/2“. So lassen sich zu kleine Änderungen von fehlender Richtung unterscheiden. Eine Auslösung setzt außerdem die vorherige automatische Freigabe voraus.

Die Betriebsanzeige nutzt bei eingeschalteter Automatik deren Freigabe („Bereit (Automatik)“ oder „Ruhiges Bild abwarten (Automatik)“). Der Knopf „Bereich frei (manueller Test)“ ist dafür nicht erforderlich und hebt die automatische Freigabeprüfung nicht auf. Die manuellen Testknöpfe bleiben für separate Versuche verfügbar.

Sehr langsame, zu schnelle, winzige oder strukturarme Bewegung kann übersehen werden. Nach Auslösung gelten zehn Sekunden Sperrzeit und erneut mindestens zwei Sekunden ruhiges Bild. Ein ruhiges Bild beweist keinen menschenfreien Bereich. Stopp, Fehler-Watchdog, bewusstes Rücksetzen und erneute Freigabe nach Start/Konfigurationswechsel bleiben wirksam. Bei bereits gesetzter Fehlersperre nach Auswahl und Speichern bewusst „Grab zurücksetzen“ drücken.

Dies ist ein Bewegungs-Test für die Simulation, keine Personenerkennung für den späteren Gartenbetrieb. Auch Kamera-/Hintergrundbewegung kann auslösen. Lichtwechsel werden nicht als Richtung behandelt, können aber die Ruhefreigabe verzögern. Bei akzeptiertem Trigger wird ein Bild des grünen Bereichs gespeichert; Besuchermerkmale werden nicht gespeichert. Testereignisse erscheinen separat als „Bewegungs-Test“ (motion_direction_test). /api/detection liefert zusätzlich flüchtige Bewegungswerte unter motion; Config/Status enthalten method (person_line oder motion_test).

Lokal mit synthetischen Bildern getestet: Richtung/Umkehr/gedrehte Linie, Gegenrichtung, seitliche Bewegung, Helligkeitswechsel, Bereichsgrenzen, Bestätigung, Bildlücken, Sperrzeit und Stopp. Browser-Demo bestätigt Auswahl, Speichern und Wiederherstellung nach Neuladen über die sichtbare UI-Struktur. Echte Pi-Kamera und Nahbereich noch nicht geprüft.

Abnahme am echten Pi (noch offen)

• Angezeigte Rate und Reaktionsverzögerung prüfen; Livebild und Stopp müssen bedienbar bleiben. Zehn Annäherungen und zehn Rückwege ausprobieren.
• Gruppe, Verdeckung, Stehenbleiben, Linie entlanggehen, Neustart mit Person im Bereich sowie Kamera-/Erkennungsausfall und bewusstes Rücksetzen testen.
• Danach Kostüme, tatsächliche Dunkelheit und IR-Beleuchtung am Aufstellort testen. Nachtbetrieb und Zuverlässigkeit sind noch nicht bestätigt.

Modellgrundlage: OpenCV Zoo NanoDet.

Optionaler echter Modell-Smoke-Test auf einem Rechner mit OpenCV und Modell:

HALLOWEEN_TEST_MODEL="$PWD/data/models/object_detection_nanodet_2022nov.onnx" .venv/bin/python -m unittest discover -s tests -v

Ohne diese Variable wird nur der optionale Modell-Smoke-Test übersprungen; die Linien-/API-/Installer-Tests benötigen weder Modell noch OpenCV.

Kamera folgt einem Farbpunkt

Auf der Seite Kamera / Finger (/kamera) gibt es den Abschnitt Kamera folgt einem Farbpunkt · Testmodus. Er verfolgt einen deutlich gefärbten Aufkleber oder Punkt, auch am Finger. Eine nackte Hand beziehungsweise ein Finger wird nicht als solcher erkannt. Die Farbe wird lokal mit Pillow ausgewertet, ohne Modelltraining, OpenCV oder Internet. NoIR-Farben, IR-Licht und wechselnder Weißabgleich können vom Tageslichtbild abweichen; unter dem späteren Licht neu auswählen.

Vorbereitung am Pi

Die Abhängigkeit smbus2 steht in requirements.txt und wird beim normalen versionierten Upload in die neue Umgebung installiert. Bei manueller Installation dieselbe Datei in der verwendeten Umgebung installieren. I²C muss am Pi aktiviert sein: sudo raspi-config → Interface Options → I2C. Der Dienstbenutzer benötigt Zugriff auf /dev/i2c-1 (Gruppe i2c). Fehlende Berechtigung nicht mit einem Webserver als root umgehen.

Der Treiber verwendet Bus 1, Adresse 0x40, 50 Hz (nominal), PAN=CH0, TILT=CH1. Die Frequenz gilt für die ganze PCA9685-Platine. Nur eine WebUI-Instanz/ein Worker darf den Treiber steuern; in diesem Test darf sie ausschließlich die beiden Kameraservos versorgen. Alle anderen Kanäle bleiben unbestückt. Verdrahtung siehe VERDRAHTUNG.md.

Aktuell laut Nutzer: Aufbau verdrahtet, separate Powerbank als Servoversorgung; diese hat bereits zwei Servos betrieben. Modell, 5-V-Ausgangsstrom, Spannungseinbrüche, Leitungsstärke und Dauerbetrieb noch nicht geprüft. Vor Updates/Neustarts die Servoversorgung abziehen.

Farbe auswählen und ohne Bewegung prüfen

1. Oben Kamera / Finger öffnen. Das Livebild erscheint sofort. Für eine Farbvorschau muss die Grabautomatik nicht ausgeschaltet werden. Nur vor echter Servobewegung auf Grab die automatische Auslösung ausschalten und Linie und Bereich speichern drücken.
2. Grün wählen oder Rot wählen drücken. Alternativ Beispielfoto aufnehmen und im eingefrorenen Foto auf die Mitte des Farbpunkts tippen. Ein ausreichend heller und gesättigter Farbton ist nötig. Das Foto und die Auswertungsbilder bleiben ausschließlich im Arbeitsspeicher; gespeichert werden nur Farbwert, Toleranz, Richtungen und Pulsgrenzen in data/follow.json.
3. Nur Farbvorschau starten. Im eigenen Bild markiert ein Kreis den ausgewerteten Farbpunkt; das Kreuz ist die gewünschte Bildmitte. Dabei erfolgt keinerlei Zugriff auf den PCA9685. Zu kleine oder großflächige Farbflächen und zwei ähnlich große Kandidaten ergeben kein eindeutiges Ziel.
4. Kameraservos stoppen. Änderungen an Farbe und Grenzen sind nur bei gestoppter Nachführung erlaubt.

Erste echte Bewegung

Der bewusste Start der echten Nachführung oder des Einrichtmodus setzt jede Achse auf (gespeichertes Minimum + gespeichertes Maximum) / 2 ihrer Bewegungsgrenzen. Halbe Mikrosekunden werden aufgerundet. Beispiel: PAN 1000–1800 → 1400 µs, TILT 1300–1800 → 1550 µs. Die WebUI zeigt die Werte unter Beim nächsten Start. Ohne angepasste Grenzen ergibt sich weiterhin 1500 µs. Beim Hochfahren des Pi wird keine Kamerasitzung gestartet. Das kann aus einer unbekannten bisherigen Stellung eine größere Bewegung sein. Für die erste Zentrierung Servohörner/Gestänge lösen, lose Teile sichern und freie Mittelstellung prüfen. Danach spannungsfrei montieren. Die anfänglichen Grenzen 1400–1600 µs sind ein enger Testbereich, keine für die vorhandene Halterung bestätigten Winkel. Das Kamerakabel darf nicht unter Zug geraten.

Nach Prüfung den Hinweis zum freien Bewegungsraum bestätigen und Echte Kameranachführung starten drücken. PAN- und TILT-Pulsbreiten werden angezeigt. Bewegt sich eine Achse vom Punkt weg, stoppen, unter Farbe, Drehrichtung, Tempo und Suche einstellen die betreffende Richtung umkehren und speichern. Grenzen pro Achse schrittweise ermitteln; die Nachführgrenzen müssen im gespeicherten Einrichtbereich liegen; Minimum darf nicht größer als Maximum sein. Gleiche Minimum-/Maximumwerte sperren eine Achse bei der Nachführung auf diesen Wert. Diese Werte sind Pulsbreiten, keine garantierten Winkel.

Die Regelung hat eine Totzone um die Bildmitte. Nachführtempo stellt die maximale Pulsänderung zwischen 40 und 800 µs/s ein; nahe der Mitte wird langsamer nachgeführt. Zum ersten schnelleren Test: Kameraservos stoppen, 400 eintragen, Farbe, Richtung, Tempo und Suche speichern, anschließend bewusst neu starten. 400 ist der Standard für neue Konfigurationen. Alte Einstellungen behalten beim Update zunächst 80; Endpunkte bleiben erhalten. Die Regelverstärkung ist auf 600 µs/s je Bildbreite/-höhe begrenzt (Bildverzögerung lässt höhere Werte pendeln); das Tempo wirkt als Obergrenze, mehr als ca. 300 µs/s wird dadurch bei Zielen nahe der Bildmitte/-rand nicht mehr erreicht. Bei Pendeln Tempo reduzieren. Einrichtung und Mittelstellungsbutton bleiben auf 40 µs/s begrenzt. Der bewusste Sitzungsstart gibt hingegen unmittelbar die gespeicherte Mitte als Sollwert aus; dessen reale Servogeschwindigkeit wurde nicht gemessen.

Die Pi-Kamera zielt jetzt auf 15 Bilder/s bei 640×480, die synthetische Demo bleibt bei etwa 5. Die Konfiguration nutzt Picamera2-FrameDurationLimits (Herstellerhandbuch). Über dem Bild stehen gemessene Kamerabilder/s, Nachführ-Auswertungen/s und die Dauer der Farberkennung. Das sind Softwaremessungen, keine CPU-Auslastung oder Bestätigung der realen mechanischen Geschwindigkeit. Die Vorschau fragt etwa alle 100 ms plus Antwort-/Darstellungszeit ab; die Regelung läuft unabhängig davon. Bei verzögerten Bildern werden maximal 100 ms Bewegung nachgeholt. Ob der Pi 15 Bilder/s unter jeder Last erreicht, bleibt zu prüfen. Am 16. Oktober meldet seine Status-API 15,0 Bilder/s bei inaktiver Nachführung.

Übersichtliche Bedienung

Die Oberfläche nutzt Schwarz/Blau und dezente statische CSS-Leuchteffekte. Diese werden vom Browser gezeichnet; keine zusätzlichen Kameraberechnungen, Animationsschleifen oder externen Schrift-/Grafikabrufe. Stopp bleibt rot und Warnhinweise bleiben farblich erkennbar. Die Seiten nutzen bis zu 1800 Pixel Breite. Ab 1000 Pixel Bildschirmbreite stehen Kamerabild und Bedienung nebeneinander; darunter untereinander. Auf der Kameraseite sind Status, Vorschau, echte Nachführung und Kamerastopp rechts direkt sichtbar. Farbe, Drehrichtung, Tempo und Suche einstellen öffnet die Detailparameter. Endpunkte & manuelle Einrichtung unter den beiden Hauptbereichen öffnet Grenzwerte, Richtungstasten und Mittelstellung. Am Desktop bleibt Alles stoppen im Seitenkopf beim Scrollen erreichbar.

Auf der Grabseite sind Automatische Auslösung einstellen, Gespeicherte Ereignisse und Personenprofile aufklappbar. Die Auswertungs- und Betriebsstatus bleiben sichtbar. Auf-/Zuklappen speichert keine Einstellungen und startet oder stoppt keine Sitzung.

Farbpunkt nach Verlust suchen

Unter Farbe, Drehrichtung, Tempo und Suche einstellen die Option Bei Punktverlust automatisch suchen aktivieren und Farbe, Richtung, Tempo und Suche speichern drücken. Danach den Punkt vor die Kamera halten und Echte Kameranachführung starten. Vorschau bewegt keine Servos. Die gewählte Farbe bleibt in data/follow.json gespeichert, bis du bewusst Rot, Grün oder einen neuen Punkt im Beispielfoto wählst; auch ein Neustart löscht sie nicht. Gespeichert wird die Farbe, keine eindeutige Objektidentität. Die Suchoption ist zunächst aus, bleibt nach dem Speichern erhalten und verändert keine Endpunkte. Auch mit gespeicherter Option startet die Sitzung nie selbst.

Nach erster eindeutiger Erkennung hält die Kamera bei Punktverlust kurz still. Nach 1,5 Sekunden beginnt sie in der zuletzt gesehenen Richtung zu suchen, unter Berücksichtigung der Achsumkehr. Sie schwenkt einmal auf der aktuellen Höhe und an den beiden gespeicherten TILT-Grenzen hin und her. Nur gespeicherte Bewegungsgrenzen gelten, niemals der größere Einrichtbereich. Suchtempo: höchstens 200 µs/s beziehungsweise das kleinere eingestellte Nachführtempo. Die tatsächliche Sichtfeldabdeckung hängt von Optik und Mechanik ab; der Suchweg garantiert keine lückenlose Erfassung des gesamten Bereichs.

Bei einem wieder sichtbaren Punkt hält die Suche sofort an. Zwei aufeinander- folgende eindeutige Erkennungen übernehmen wieder die normale Nachführung. Ohne Fund endet nur die Suchfahrt nach einem Durchlauf oder spätestens 60 Sekunden. Die Kamera wartet danach unbegrenzt auf die gespeicherte Farbe, solange Kamerabild und Bedienverbindung funktionieren. Die Servos halten ihre letzte Position; es werden keine weiteren Suchrunden gestartet. Sobald der Punkt in zwei aufeinanderfolgenden Bildern wieder eindeutig erkannt wird, folgt die Kamera weiter. Gesperrte Achsen bleiben unverändert. Kameraservos stoppen, Alles stoppen und die bisherigen Bild-/Verbindungs- und Auswertungswatchdogs brechen auch die Suche ab. Ohne aktivierte Suche oder wenn seit Sitzungsstart noch kein Punkt erkannt wurde, wartet die Kamera an ihrer Position ebenfalls weiter. Im manuellen Einrichtmodus findet keine Farbpunktsuche statt.

Sehr schnelle Bewegung oder ein enger eingestellter Bereich kann dazu führen, dass der Punkt aus dem Bild läuft. Der Modus ersetzt keine zuverlässige Personen- oder Fingererkennung.

Stopp und Fehler

Kameraservos stoppen und Alles stoppen beenden die Nachführung und setzen CH0/CH1 auf PWM aus. Grab stoppen und Grab zurücksetzen wirken nur auf den Grabablauf. Die Kamera verändert dessen Modus und Stoppzustand nicht. Die Farbvorschau darf parallel zur Grabautomatik laufen; nur echte Kamerabewegung bleibt bei eingeschalteter Grabautomatik gesperrt. Schließen/Neuladen des Browserfensters oder ein Wechsel in den Hintergrund beendet die Sitzung über Stopp beziehungsweise den Heartbeat: nach 1,5 Sekunden ohne die startende Bedienseite wird abgeschaltet. Die Nachführung benötigt neue Kamerabilder und neue Auswertungen innerhalb einer Sekunde. Fehler verlangen einen neuen bewussten Start. Einstellungen bleiben erhalten, aktive Nachführung und Hardwarefreigabe werden nie gespeichert. Im --demo-Betrieb wird echte Servoansteuerung grundsätzlich abgelehnt.

PWM aus trennt nicht die Versorgung. Ein festhängender Pi, verlorener I²C-Bus oder ein harter Prozessabbruch kann die letzte Ausgabe im PCA9685 stehen lassen; es gibt noch keine unabhängige OE-/Hardwareabschaltung. Servoversorgung bei unerwartetem Verhalten sofort abziehen und diesen Versuchsmodus nur beaufsichtigt verwenden. Ein Neustart setzt eine vor einem harten Abbruch verbliebene PWM-Ausgabe nicht verlässlich zurück.

API: GET /api/follow liefert Status und synchrones Auswertungsbild. POST /api/follow/{config,capture,select,start,heartbeat,stop} benötigt den bestehenden UI-Header. Nur die startende Seite erhält den flüchtigen Heartbeat-Schlüssel. Farbtests erzeugen weder Ereignisse noch Profile.

Lokal geprüft: synthetische Farbbilder, Begrenzung/Richtung, Sitzungsablauf, Fehlerfälle, API-Sperren und simulierte I²C-Registerzugriffe. Browserprüfung mit Demo-Kamera: Farbwahl, Vorschau, Stopp und Beispielfoto. Keine Aussage über echte Servobewegung, Stromreserve oder Nachführqualität am Pi.

Technische Referenzen: Pillow HSV, NXP PCA9685, smbus2.

Endpunkte der Kamerahalterung manuell einrichten

Im Farbpunkt-Abschnitt Endpunkte einrichten · manuell öffnen. Die Servomittelstellung muss wie oben beschrieben vorab geprüft sein. Für echte Bewegung muss die Grabautomatik ausgeschaltet sein. Bewegungsraum bestätigen und Einrichtmodus starten drücken. Der Start fährt jede Achse in die Mitte ihrer gespeicherten Bewegungsgrenzen. Im Demo- Betrieb heißt der Knopf Einrichtmodus als Demo starten und bewegt nur virtuelle Werte; es gibt keinen I²C-Zugriff.

• Links, Rechts, Hoch oder Runter gedrückt halten. Immer nur eine Achse wird mit maximal 40 µs/s verstellt. Mit der Tastatur funktioniert das über fokussierte Richtungstaste plus Leertaste/Enter. Loslassen, Fokusverlust oder abgebrochene Zeigergeste beendet die Verstellung.
• Vor dem mechanischen Anschlag loslassen, auch links/rechts. Bei fehlendem Tastensignal endet die Verstellung nach 0,35 s; bei Verbindungsverlust gilt zusätzlich die bisherige Abschaltung der ganzen Sitzung. Die Position wird nach dem Loslassen weiter per PWM gehalten, bis Kameraservos stoppen beziehungsweise Alles stoppen die Ausgabe beendet.
• In Mittelstellung fahren ist im aktiven Einrichtmodus verfügbar. Einmal klicken: beide Achsen fahren mit maximal 40 µs/s zur Mitte ihrer aktuell gespeicherten Bewegungsgrenzen. Die Endpunkte bleiben unverändert. Kein Gedrückthalten nötig; Kamera und Bedienverbindung müssen verfügbar bleiben. Bewegung anhalten bricht die Fahrt ab und hält die erreichte Sollposition. Eine Richtungstaste übernimmt ebenfalls die Bedienung. Kamerastopp beendet PWM. Während der Fahrt sind Endpunktspeicherknöpfe gesperrt. Zum Zentrieren aus der Farbnachführung zuerst Kameraservos stoppen und Einrichtmodus starten.
• Unter den Richtungstasten zeigt jede der vier Karten Links, Rechts, Oben und Unten den tatsächlich gespeicherten Wert. Diese Position als … speichern übernimmt den aktuellen Sollwert dieser Achse mit 10 µs Abstand nach innen. Der vorgesehene neue Wert steht schon vor dem Speichern dabei; die Bestätigung nennt danach Richtung und gespeicherten Wert.
• Ein Speicherknopf ist erst freigegeben, wenn die Achse ausreichend in die zugehörige Richtung von der Mittelstellung gefahren ist. Bei falscher Seite steht direkt an der Karte, was zu tun ist. Fehler beim Speichern erscheinen im Einrichtbereich. Die Bestätigung bleibt sichtbar, bis eine neue Aktion sie ersetzt. Die Grenzen gelten für die Farbnachführung. Richtungsumkehr wird bei Bewegung und Speicherung gleich berücksichtigt.
• Der Einrichtmodus darf die bisher gespeicherten Farbtest-Grenzen bewusst überschreiten; er hält sich an den Einrichtbereich pro Achse. Dieser beginnt bei 1100–1900 µs und kann gestoppt über die WebUI geändert werden. Nur schrittweise erweitern, vor dem mechanischen Anschlag loslassen. Die Nachführgrenzen müssen innerhalb des Einrichtbereichs liegen.

Es gibt keine automatische Anschlagfahrt und keine Endschalterauswertung. Angezeigte Werte sind Sollwerte, keine gemessene Position. Ohne Encoder, Strommessung oder Endschalter kann die Software eine Blockade nicht erkennen. Der 10-µs-Abstand ist ein kleiner zusätzlicher Puffer, keine mechanische Sicherheitsgarantie. Die Einrichtung braucht keinen Farbpunkt; frische Kamera, Sitzungs-Heartbeat und Abschaltregeln bleiben erforderlich.

API-Ergänzung: start nimmt operation=setup an; jog benötigt den privaten Sitzungsschlüssel, eine Richtung und eine steigende Sequenznummer. center beauftragt die Mittelstellungsfahrt nur in einer bestehenden Einrichtsitzung und verwendet dieselbe Sequenzfolge wie jog. Verspätete Tastenbefehle dürfen einen neueren Loslassbefehl nicht überholen. remember speichert eine Grenze erst nach beendeter Bewegung. Einstellungen und Verdrahtung sind weiterhin im selben Plan dokumentiert.

Getrennte Seiten für Grab und Kamera

• Grab unter / oder /grab: Livebild mit Erkennungsbereich, Betriebsmodus, Auslösung, Ereignisse und Profile. Die Knöpfe Grab stoppen und Grab zurücksetzen beeinflussen nur diesen Bereich.
• Kamera / Finger unter /kamera: eigenes Livebild, Farbwahl, Nachführung und manuelle Endpunkte. Farbvorschau und Einrichtung haben getrennte Startknöpfe; beides gehört zur Kamerasitzung.
• Oben auf beiden Seiten: Navigation und Alles stoppen für Grab und Kameraservo-PWM gemeinsam. Die Stromversorgung wird damit nicht getrennt.

Kamera und Grab speichern ihre bisherigen Einstellungen weiterhin getrennt. Die Seiten laden nur ihre eigenen Abfragen und Bedienelemente. Beide verwenden physisch dieselbe Kamera: Farbvorschau parallel ist möglich, echte Bewegung bei aktivierter Grabautomatik wird abgelehnt, ohne den Grabzustand umzustellen. Nach einer Kamerabewegung vor erneutem Aktivieren der Automatik Bildausschnitt, Linie und Bereich prüfen.

Beim Verlassen der Kameraseite endet die Kamerasitzung über Stopp/Heartbeat, spätestens nach Ausbleiben der Bedienverbindung gemäß den bisherigen Regeln. Navigation startet keine Servos und ändert keinen gespeicherten Grabmodus. Die alten API-Aufrufe /api/stop und /api/reset bleiben als globale Abschaltung für ältere Clients bestehen; neue Grabknöpfe verwenden /api/grave/stop beziehungsweise /api/grave/reset.

Eindeutige Speicherung der Endpositionen

Zusätzlich zu den vier Endpunktkarten gibt es auf Kamera / Finger den sichtbaren Bereich Bewegungsgrenzen manuell eingeben mit PAN Minimum, PAN Maximum, TILT Minimum und TILT Maximum. Nur bei gestoppter Kamerasitzung bearbeiten, dann Bewegungs- und Einrichtgrenzen speichern drücken. Darunter stehen immer die tatsächlichen Serverwerte; geänderte Eingaben werden ausdrücklich als ungespeichert markiert und bleiben beim Aktualisieren der Anzeige erhalten. Eingaben verwerfen stellt die gespeicherten Werte wieder her.

Die manuelle Grenzspeicherung verändert Farbe/Drehrichtung nicht. Deren separater Speichern-Knopf verändert umgekehrt keine Grenzen. Ein Start speichert nichts; offene Grenzänderungen müssen zuerst gespeichert oder verworfen werden. Die Endpunktkarten und ihre Speicherung im aktiven Einrichtmodus bleiben zusätzlich erhalten. Manuelle Zahlenfelder sind während einer Sitzung gesperrt. Unter Einrichtbereich zum Anfahren der Endpunkte stehen zusätzlich PAN/TILT Einrichtung Minimum und Maximum. Diese Werte begrenzen die Richtungstasten, auch wenn die bisherigen Nachführgrenzen enger sind. Bei zu wenig Weg: stoppen, den betreffenden Einrichtwert in kleinen Schritten erweitern, speichern und Einrichtmodus erneut starten. Der Start berechnet die Mitte aus den gespeicherten Endpunkten neu. Dann die reale gewünschte Endposition langsam anfahren, loslassen und in der Richtungskarte speichern. Das übernimmt den Sollwert mit 10 µs Innenabstand für die Nachführung.

Technische Eingabehülle: 500–2500 µs, kein bestätigter mechanischer Bereich für diese Servos/Halterung. Die Nachführgrenzen müssen im Einrichtbereich liegen; bei einer direkten Zahleneingabe gegebenenfalls beide zusammen ändern. Speichern löst keine Bewegung aus. Alte Konfigurationen behalten alle Endpunkte und den bisherigen Einrichtbereich 1100–1900 µs; keine automatische Erweiterung.

Die Startmitte einer Einrichtsitzung bleibt während dieser Sitzung der Bezug für die Links-/Rechts-/Oben-/Unten-Speicherknöpfe, auch nach dem Speichern eines Endpunkts. Speichern löst keine Zentrierfahrt aus. Erst beim nächsten bewussten Start wird die Mitte aus den dann gespeicherten Endpunkten neu berechnet.