Halloween/halloween/instructions.md

Modul halloween/

Hier liegt die erste Pi-WebUI. run.py im Projektstamm startet sie.

• camera.py liefert ein gemeinsames MJPEG-Bild für mehrere Betrachter. --demo erzeugt ausdrücklich gekennzeichnete Testbilder; echte Kamera läuft nur über Picamera2 auf dem Pi. Kamerafehler sichtbar melden.
• controller.py enthält bislang ausschließlich die simulierte Effekt-Zustandslogik. Stopp bleibt bis zum Rücksetzen bestehen; nach Start oder Rücksetzen muss erst der Bereich frei sein und dann ein neuer Trigger kommen. Beschädigte Einstellungen schalten auf aus.
• web.py bietet WebUI und API; index.html ist die Oberfläche. run.py bindet an 127.0.0.1, Zugriff vom Laptop erfolgt per SSH-Tunnel. Für den vom Nutzer gewünschten direkten Heimnetzzugriff kann Uvicorn halloween.web:create_app als Factory auf 0.0.0.0:8000 starten; siehe SOFTWARE.md. run.py bleibt bei Loopback; systemd nutzt die beim Upload gewählte Bind-Adresse, initial Loopback.
• event_store.py verwaltet data/events.sqlite3. Erfolgreiche manuelle Testauslösungen werden als Ereignisse gespeichert; Profile besitzen Kennungen und können Ereignissen zugeordnet werden. Profil-Löschen entfernt die Zuordnung, nicht das Ereignis. Auto-Profile können Merkmalsvektoren aufnehmen und verfallen 30 Tage nach letzter Sichtung. Start, stündlicher Lauf und Lesezugriffe räumen abgelaufene Profile auf; die Kamera liefert derzeit noch keine Merkmalsvektoren.
• Automatische Profilzuordnung per Kamera ist ein neuer Nutzerwunsch, aber noch nicht implementiert. Eine künftige Erkennung muss Unsicherheit und mögliche Fehlzuordnungen sichtbar machen und am echten Pi geprüft werden.
• Der Header X-Halloween-UI ist nur eine einfache Schranke für Schreibaufrufe, kein echter Zugangsschutz. Der direkte Heimnetzzugriff ist auf Nutzerwunsch für den aktuellen Test ohne Login vorgesehen; öffentliche Internetfreigabe ist nicht beauftragt. Zugangsschutz bleibt offen.
• Laufzeitdaten liegen standardmäßig unter data/ und werden weder hochgeladen noch in Git aufgenommen.
• Echte GPIO-/Grabaktorsteuerung erst nach geklärter Mechanik, Versorgung, sicherem Stopp und den Hardwaretests aus PLAN.md ergänzen.

Bei Änderungen an Zustandsübergängen oder Endpunkten die zugehörigen Tests unter tests/ und die Bedienhinweise in SOFTWARE.md prüfen.

Personendetektion

• detection.py wertet den gemeinsamen Kamerastream mit OpenCV DNN/NanoDet aus. Optionales Modell und OpenCV fehlen im Demo-Grundsetup bewusst. Kein Download im Server; geprüfte Modellmetadaten in nanodet-model.json.
• Nur neue, zeitlich gültige Frames auswerten. Hintergrundinferenz hält keine UI-/Zustandssperre; separater Watchdog sperrt aktivierte Automatik nach zwei Sekunden ohne gültiges Ergebnis. Fehler verlangen bewusstes Rücksetzen.
• Linienüberquerung nutzt bestätigte flüchtige Tracks und Fußpunkte, Richtung, endliches Segment und 3-%-Hysterese. Gruppen verlangen freien Bereich und Sperrzeit; Konfigurations-/Controllerwechsel verwerfen alte Beobachtungen.
• /api/detection liefert synchrones Bild und Rahmen; /api/detection/config speichert normierte Geometrie und Aktivierung unter data/. Erste Aktivierung ist bewusst, nach Neustart immer neue Bereichsfreigabe. UI zeichnet/editiert mit Canvas; keine Tracking-ID als Besucherprofil verwenden.
• Automatische Ereignisse tragen person_line_crossing, ohne Profilzuordnung. Die vorhandene Steuerung bleibt ausschließlich simuliert.

Bewegungs-Test

• motion.py bietet OpenCV-Optical-Flow im gewählten Bereich ohne Personenmodell. Zwei aufeinanderfolgende gerichtete Bewegungen entlang der Pfeilnormalen bestätigen einen Trigger; die Linie muss dabei nicht überquert werden.

• method=motion_test ausdrücklich als Test kennzeichnen; person_line bleibt der Default und die Migration für alte gespeicherte Konfigurationen/Clients. Beide Methoden speichern Geometrie/Aktivierung unter data/detection.json.

• Beim Test bedeutet Bereichsfreigabe zwei Sekunden Bildruhe, KEINE bestätigte Personenfreiheit. Zehn Sekunden Sperrzeit, Stopp, bewusster Reset und Watchdog beibehalten. Nach Konfigurations-/Controllerwechsel neue Bildbasis verlangen; veraltete Inferenzfehler und Resultate dürfen den neuen Modus nicht beeinflussen.

• Ereignisse getrennt als motion_direction_test, ohne Profile; mit Auslösebild gemäß den folgenden Bildregeln. Aktoren bleiben simuliert; keine Zusage für Außenbetrieb, Licht oder Kostüme.

• Kleine Nahbereichbewegung nicht durch einen prozentual großen Mindestanteil am gesamten Rechteck verwerfen; Schwellen mit kleinem/langsamem synthetischem Stimulus regressionsprüfen, Gegenrichtung/Lichtwechsel weiter ablehnen.

• Bewegungswerte enthalten flüchtige Bildänderung, Hinweis und bestätigte Frames. UI zeigt diese zur Diagnose und verwendet bei aktivierter Automatik deren Freigabe für die Bereitschaftsanzeige. Manuelles Bereich-frei ersetzt diese nicht; Sequenz, Stopp und Sperrzeit behalten ihren Vorrang.

Auslösebilder

• Automatische akzeptierte Trigger speichern den grünen Bereich des auslösenden Frames als JPEG unter data/event-images/, ohne EXIF/Originalbild außerhalb des Rechtecks. Konfiguration beim Trigger kopieren; keine neuere Kameraaufnahme oder später geänderte Geometrie verwenden. Manuelle Tests speichern kein Bild.
• SQLite migriert image_filename; öffentlicher Abruf nur über Ereignis-ID und geprüfte generierte Dateinamen. Keine statische Freigabe des data/-Ordners. Ordner 0700, Dateien 0600; Bilder nicht cachen. Bildspeicherung/SQLite außerhalb des Detection-Locks, Fehler nutzen die bestehende Fehlersperre.
• Nutzerwahl: bis manuelle Löschung behalten. UI bietet Vorschau, Ansehen und bestätigtes Bildlöschen; Ereignis/Profilzuordnung bleiben bestehen. Löschen betrifft den aktiven Bestand, keine Upload-Sicherungen. Keine automatische Alterslöschung von Bildern und keine Änderung der Auto-Profil-Frist.

Kamera folgt einem Farbpunkt

• follow.py bietet lokale Pillow-HSV-Erkennung ohne OpenCV/Training und einen optional bewusst gestarteten PCA9685-Kameratest. Vorschau und Demo greifen niemals auf I²C zu; Demo lehnt Hardwarestart ab. Echte Ausgabe nur CH0/CH1, Bus 1 / 0x40, nominal 50 Hz. Platine für diesen Test ausschließlich dafür nutzen.

• Farbwert, Toleranz, Achsrichtungen und Pulsgrenzen atomar in data/follow.json; Beispielfoto und Analysebilder nur flüchtig. Bildauswahl nutzt Token und exakt das fotografierte Bild; keine neuen Ereignisse, Profile oder Trainingsbilder.

• Automatische Auslösung und Follow-Sitzung gegenseitig ausschließen. Follow hält Controller an; allgemeiner Stopp und Reset müssen zuerst Follow stoppen. Danach bleibt bewusste Rücksetzung des Grabablaufs nötig.

• Start braucht frische Kamera und explizite Hardware-/Mechanikbestätigung. Beide Achsen starten bei 1500 µs (möglicher Sprung, vorab entkoppelt prüfen). Defaults 1400–1600, absolute Eingabegrenzen 1100–1900 inklusive 1500, maximal 80 µs/s, keine Suchfahrt; Richtungswechsel nur gestoppt.

• Sitzung startet nie automatisch. Startender Browser erneuert geheimen Sitzungsschlüssel; 1,5 s ohne Heartbeat, 1 s ohne Bild/Auswertung oder 1 s ohne eindeutigen Marker im Hardwarebetrieb schaltet PWM aus. Stale Resultate und alte Heartbeats dürfen keine neu gestartete Sitzung steuern.

• PWM-Abschaltfehler sichtbar melden; keine sichere Hardwareabschaltung aus Softwaretests ableiten. I²C-Ausfall/harter Prozessabbruch können PWM stehen lassen. Keine unabhängige OE-Sperre; nur beaufsichtigter Test.

• operation=setup ist ein eigener manueller Einrichtmodus derselben exklusiven Kamerasitzung. Kein Farbzielsuchen/-verluststopp; Kamera und Heartbeat bleiben erforderlich. Richtungstaste halten: maximal 40 µs/s, Lease 0,35 s und steigende Sequenznummer gegen verspätete Befehle. Loslassen hält die Sollposition per PWM; globaler/Kamerastopp beendet PWM.

• Einrichtung darf bisherige Follow-Grenzen überschreiten, niemals 1100–1900 µs. Grenzspeicherung braucht passende Sitzung und beendete Bewegung; Richtungs- umkehr beachten, 10 µs nach innen speichern, atomar in follow.json. Keine Anschlagerkennung behaupten; nur Sollwerte, beide Achsen vor Anschlag stoppen.