Halloween/AGENTS.md

# Halloween – Projektregeln

## Ziel und aktueller Auftrag

Interaktives atmendes Grab für Halloween im Vorgarten der Schwester bauen.
Gewünscht sind ein kräftiger Schreckeffekt, Kamera, Weboberfläche und lokal
gespeicherte Bilder/Videoclips. Der Nutzer hat nun eine erste Pi-Software mit
Liveansicht und simuliertem Effektablauf beauftragt; das allgemeine
Uploadskript und die Blender-Konzeptvorschau wurden ebenfalls freigegeben.
Hardwarebau und Anschluss echter Aktoren folgen nach Klärung der Mechanik,
Versorgung und Sicherheit im Plan.

## Arbeitsweise

- Auf Deutsch, klar und knapp kommunizieren.
- `PLAN.md` als Arbeitsplan pflegen; erledigte Punkte, offene Entscheidungen
  und verifizierte Ergebnisse getrennt dokumentieren.
- Diese `AGENTS.md` nach dauerhaften Änderungen an Architektur, Betrieb,
  Sicherheit oder Werkzeugen im selben Arbeitsgang aktualisieren.
- Vor Änderungen in `halloween/`, `tools/`, `tests/` oder `preview/` die dortige
  `instructions.md` lesen und bei geänderten Verträgen oder Abläufen
  aktualisieren. Neue Modulordner erhalten eine eigene `instructions.md`.
- Vor Änderungen vorhandene Dateien und tatsächliche Hardware prüfen.
- Vorschläge und Annahmen ausdrücklich kennzeichnen; keine Kameramodelle,
  Motorleistungen, Anschlüsse, Netzwerkadressen oder Preise erfinden.
- Produktvorschläge und Kaufverweise ausschließlich für Reichelt oder
  Amazon; technische Herstellerunterlagen dürfen zur Prüfung dienen.
- Klein anfangen: einen vollständigen Effektablauf zuverlässig umsetzen,
  anschließend zusätzliche Effekte ergänzen.
- Dokumentation übersichtlich halten; diese Datei unter 400 Zeilen halten.
- Im lokalen Git Code, Planung und bearbeitbare Blender-Szenen versionieren;
  Renderdateien, Referenzclip, `.venv` und `data/` bleiben unversioniert.
- Gitea-Ziel für dieses Projekt: `https://gitea.fritz.box/marcinator_2/Halloween`;
  Branch `main`, Repository zunächst privat. HTTPS-Zertifikatsprüfung aktiv
  halten; das öffentliche Zertifikat nur lokal in Git konfigurieren.
  Zugangsdaten gehören nicht in Git oder Chat.

## Hardware und Architektur

- Vorhanden laut Nutzer: Raspberry Pis 3–5; Pi 5 auf Nutzerfoto bestätigt,
  RAM vermutlich 8 GB laut Nutzer, noch nicht am Gerät geprüft;
  außerdem „2mini“ (genaue Geräte unbekannt), Camera Module 3 NoIR
  (Beschriftung auf Nutzerfoto bestätigt), eventuell Display,
  LEDs, Servos und Lötwerkzeug. 3D-Drucker laut Nutzer vorhanden;
  Modell, Bauraum und Druckmaterial noch unbekannt.
  PCA9685-Modul mit 16 Kanälen laut Nutzer vorhanden; konkrete Platine
  und Anschlüsse noch nicht geprüft, kein Neukauf nötig.
  Buchse/Buchse-Steuerleitungen laut Nutzer reichlich vorhanden;
  kein Neukauf nötig, nicht für Servolast verwenden.
  Weitere Teile dürfen vorgeschlagen werden.
  Weiteres Nutzerfoto bestätigt einen 28BYJ-48-Schrittmotor mit 5-V-DC-
  Beschriftung und OPITEC-Werkpackung 224105 mit Getriebeteilen.
  Vollständigkeit, Treiber, Funktion und Lastfestigkeit noch ungeprüft.
  OPITEC nennt für Werkpackung 224105 Motor R20 mit 1,5–4,5 V und
  ca. 350–500 mA; Drehmoment fehlt. Fotografierter Einzelmotor nicht
  unabhängig als R20 bestätigt; 6-V-Servoversorgung nicht direkt anschließen.
- Vorgeschlagene Aufteilung: Pi 5 für Kamera/WebUI/Ereignisse und Pi 3/4
  für Effektsteuerung. Noch keine verbindliche Hardwareentscheidung.
- Für die NoIR-Kamera IR-Beleuchtung bei Dunkelheit und ein passendes
  Standard-auf-Mini-Kamerakabel für Pi 5 einplanen; vorhandenes Kabel prüfen.
- GPIOs steuern geeignete Treiber; Motoren, Servos und größere LED-Lasten
  erhalten eine passend dimensionierte Versorgung.
- Aktueller Nutzerumfang: zwei Antriebe, einer für die Hand und einer
  für die Atemrotation. Nutzer sieht nun 230 V mit Relais für Rotation
  vor; CHANCS 60KTYZ (Amazon B07WXFWYBZ, 220–240 V, ca. 2,5 U/min)
  ist nun ausgewählt, Kauf noch nicht bestätigt. Waveshare RPI RELAIS 3CH
  ist im aktuellen Warenkorb; Motorlastfreigabe noch offen. Versorgungsleitung
  laut Nutzer vorhanden; Eignung vor Anschluss prüfen. Für die
  Hand ist der Miuzei-35kg-/270°-Servo der aktuelle Kandidat, mit
  separater stabilisierter 6-V-/5-A-Versorgung und Delock 65485 als
  Anschlussadapter. Langsames Hervorkommen ist ausdrücklich akzeptiert.
  Hub, Last, PWM-Steuerung und sichere Bewegungsgrenzen noch festlegen.
  Motoren nicht gekauft oder praktisch geprüft.
  GM40,5 625 12V / E192.12.625 war die vorherige Reserveoption für
  Rotation; GM27 90 12V der frühere Kandidat für direkten Handhub.
  Beide sind historische Vorschläge, keine verbindliche Auswahl.
  Separate Pi-5-Versorgung ist der aktuelle Vorschlag;
  Netzteilreserve anhand beider Anlauf-/Blockierströme prüfen.
- Atemrotation laut Nutzer: ca. 1,5 m lange waagerechte Stange mit zwei
  leeren Kunststoffflaschen; vorgesehen ist Rotation um die Längsachse.
  Abdeckungs- und Lagerwiderstand mitmessen, keine schwere Hubfläche
  als Last voraussetzen.
  Stangenlänge ist dabei kein Drehmomenthebel; wirksamen Abstand zur
  Drehachse und Last über eine ganze Umdrehung prüfen. Keine
  abgeschlossene Dimensionierung aus den früheren Kandidaten ableiten.
- Mechanik erst nach Klärung von Abmessungen, Gewicht, Hub und Bewegungsraum
  auswählen. Atembewegung und kurzer Schreckimpuls getrennt bewerten.
- Neue Handidee: Gummizug für schnellen Hub, langsamer Motor zum
  Rückspannen. Verriegelung mit vorab abgewickelter Schnurreserve oder
  schaltbarer Kupplung ist noch ein Vorschlag. Ein zusätzlicher
  Entriegelungsaktor wäre beim Riegelvorschlag nötig; nicht ausgewählt.
  Motor muss die Spannkraft aufbringen; Gummizug ersetzt diese Last nicht.
- Elektrischer Linearantrieb ist eine zusätzliche Handoption; direktes
  Ausfahren und langsames Spannen eines getrennten Federhubs unterscheiden.
  Selbsthemmender Spindelantrieb gibt einen schnellen Federhub nicht
  automatisch frei. Hand bleibt befestigt, geführt und im Grab begrenzt.
- Weitere Handoption auf Nutzerwunsch: Schwenkhebel nach einer
  Industrieservo-Videovorlage. Günstiger Kandidat für direkten Handhub
  ist JOY-IT COM-MOTOR02 (Reichelt GRABIT SERVO); noch nicht ausgewählt
  oder getestet. Maximales Servomoment und Leerlaufgeschwindigkeit
  sind keine zugesicherte kombinierte Lastleistung. Eigenes passendes
  Servonetzteil und PWM-Steuerung vorsehen; keine Geschossfunktion.
- Neuer stärkerer Handkandidat vom Nutzer: Amazon Miuzei 35kg/270°,
  ASIN B0CBBS6KX6. Anbieterwerte/Spitzenstrom und reale Last prüfen;
  PWM-Winkelzuordnung und Bewegungsgrenzen für 270° auslegen.
  Versorgungsvorschlag: getrenntes stabilisiertes 6-V-Netzteil mit
  mindestens 5 A, Anlaufverhalten noch prüfen. Pi behält eigenes Netzteil;
  bei nicht isolierter Steuerung gemeinsame Masse, Versorgungsplus getrennt.
  ZHITING DS3235 ist laut Nutzer nicht lieferbar, SAIA-230-V-Kandidat
  zu teuer; beide für die aktuelle Auswahl zurückgestellt.
  Langsamen direkten Hub zuerst bewerten;
  kein schneller Federimpuls zwingend erforderlich.
- Nutzer weist auf Verheddern abgewickelter Schnur hin. Die Variante mit
  Schnurreserve ist erst nach Auslegung einer geführten Aufnahme sinnvoll.
  Kurvenscheibe mit Hebel als schnurlose Alternative prüfen;
  recherchierte Druck-/CAD-Vorlagen sind noch keine passende Handmechanik.

## Betriebsregeln

- Bewegung bleibt im Grab und außerhalb des Besucherwegs; Quetschstellen
  abdecken. Leichte bewegte Bauteile und mechanische Anschläge vorsehen.
- Elektronik für Außeneinsatz geschützt planen; Kleinspannung am Grab
  bleibt der bisherige Vorschlag. Für die neue 230-V-Relaisalternative
  Netzspannungsseite geschlossen, berührungsgeschützt und für Außeneinsatz
  auslegen; durch eine Elektrofachkraft aufbauen/prüfen lassen.
  Pi-kompatible Steuerschnittstelle, geeignete Motorlastkontakte,
  Zugentlastung und passende Stromversorgung vorsehen.
- Bei Start, Verbindungsverlust oder Fehler keine neue Schrecksequenz
  auslösen; definierte sichere Zustände und lokalen Stopp vorsehen.
- Bei Gummizugmechanik stromlos haltende mechanische Verriegelung und
  kontrollierte Entspannung für Wartung vorsehen. Motor-Stopp nimmt die
  gespeicherte Energie nicht weg und hält einen entriegelten Hub nicht
  sofort an; Führung, Befestigung und gedämpfte Anschläge begrenzen ihn.
- Sperrzeit und belegten Auslösebereich berücksichtigen.
- Kinder-/Sanftmodus anbieten. Kamerabasierte Größenhinweise sind unsicher
  und dürfen nicht als zuverlässige Altersbestimmung gelten.
- Nutzerwunsch: „voller Schreck“ ist der anfängliche Standard und wird nach
  neuem gültigem Trigger automatisch ausgelöst, ohne Einzelfreigabe.
  Modi sind in der WebUI umstellbar; eine gewählte Einstellung soll einen
  normalen Neustart überdauern. Nach Start erst freien Auslösebereich
  abwarten; nach Stopp oder Fehler bewusst zurücksetzen. Kamerahinweise
  gelten nicht als verlässliche Altersentscheidung; automatische Reaktion
  auf Hinweise zu kleinen Besuchern vor Implementierung abstimmen.

## Kamera, Aufnahmen und Zugriff

- Personenerkennung für Auslösung und Profilzuordnung als getrennte Schritte
  behandeln; unsichere Zuordnungen keinem Profil zuschreiben.
- Neuer Nutzerwunsch: Personenprofile und später automatische Zuordnung
  wiederkehrender Besucher per Kamera. Aktuell ist nur die lokale Datenbank
  mit manueller Zuordnung umgesetzt; automatische Erkennung nicht als
  funktionsfähig ausgeben, bevor Verfahren und echte Kamera geprüft sind.
- Automatisch erzeugte Profile samt Merkmalsvektoren 30 Tage nach der letzten
  Sichtung löschen. Manuell angelegte Profile bleiben bis zur Löschung bestehen.
- Clips mit Zeit, Vorschaubild und Ereignistyp zum manuellen Prüfen anbieten.
- Neu beauftragt: bei jeder akzeptierten automatischen Auslösung ein JPEG
  des grünen Bereichs aus dem Trigger-Frame lokal unter data/event-images/
  speichern; Vorschau/Ansehen und bestätigtes Bildlöschen in der Ereignisliste.
  Nutzerwahl: bis manuelle Löschung behalten, keine automatische Bilderfrist.
  Ereignis/Profilzuordnung bleiben beim Bildlöschen; Upload-Sicherungen separat.
  Keine Bilder bei manuellen Testauslösungen oder nachträglich für alte Ereignisse.
  Lokale synthetische Tests bestanden; echter Pi-Speicher-/Anzeigetest noch offen.
- Aufnahmebereich auf den vorgesehenen privaten Bereich begrenzen;
  Maskierung, Aufbewahrung und Löschfrist vor Umsetzung festlegen.
- Tonwiedergabe und Tonaufnahme unterscheiden; Tonaufnahme standardmäßig aus.
- WebUI zunächst nur im lokalen Netz; keine öffentliche Freigabe ohne
  ausdrücklichen Auftrag. Zugangsschutz einplanen.

## Erste Softwareversion

- `run.py` startet die FastAPI-WebUI nur auf `127.0.0.1`; Laptop-Zugriff
  erfolgt per SSH-Tunnel. `--demo` kennzeichnet ein synthetisches Bild.
- Nutzer wünscht nun direkten Zugriff im Heimnetz. Manueller Start über
  Uvicorn mit `--factory --host 0.0.0.0` ist in `SOFTWARE.md` beschrieben.
  Aktuell ohne Login; keine öffentliche Internetfreigabe beauftragt.
  `run.py` bleibt bei Loopback; systemd nutzt die beim Upload gewählte
  Bind-Adresse, initial Loopback.
- Picamera2 liefert das MJPEG-Livebild; auf dem Entwicklungsrechner wurde
  nur der Demo-Feed geprüft, nicht die echte Pi-Kamera.
- Moduswahl, simulierte Sequenz und lokale NanoDet-Personendetektion mit
  gerichteter Linienüberquerung sind implementiert. Erkennung benötigt optional
  OpenCV und ausdrücklich installiertes SHA-256-geprüftes Modell unter data/.
  Am Pi fertige Systempakete python3-opencv/python3-numpy in einer Umgebung
  mit --system-site-packages verwenden; OpenCV mindestens 4.10 prüfen.
  requirements-detection.txt erlaubt nur Wheels, keinen impliziten Quellbuild.
  Erkennung startet deaktiviert; Linie/Bereich/Richtung in der UI einstellen.
  Gruppen verlangen neuen freien Bereich und Sperrzeit; Erkennungsfehler bei
  aktivierter Automatik sperren bis zum bewussten Rücksetzen. Frames und
  Personenrahmen werden synchron angezeigt; Tracks sind flüchtig, keine Profile.
  Echte Personenauslösung am Pi, GPIO und Clip-Speicherung sind noch offen.
- Zusätzlicher Testmodus „Bewegung in Pfeilrichtung“ ist implementiert:
  Optical Flow im gewählten Bereich, kein Personenmodell/keine Überquerung nötig.
  Auswahl und Aktivierung gespeichert; Personenerkennung bleibt der Standard.
  Zwei gerichtete Beobachtungen bestätigen; zwei Sekunden Bildruhe und zehn
  Sekunden Sperrzeit. Bildruhe ist keine Personenfreiheit. Nur Simulation,
  separates motion_direction_test-Ereignis ohne Profil, mit lokalem Auslösebild.
  Nutzer-Screenshot bestätigt Testmodus mit Pi-Bild und 5 Auswertungen/s,
  aber bisher keine Auslösung. Kleine/langsame Nahbereichbewegung war im
  synthetischen Regressionstest zu schwach für die alte Schwelle; korrigiert.
  UI zeigt Bildänderung/Richtungsbestätigung und automatische Bereitschaft
  getrennt von manuellen Tests. Echte Auslösung am Pi bleibt zu prüfen.
- SQLite speichert Testereignisse und Profilkennungen unter `data/`;
  automatische Kamera-Zuordnung fehlt noch. Die Datenbank kann bereits
  Merkmalsvektoren für Auto-Profile mit 30-Tage-Frist speichern; die Kamera
  schreibt derzeit keine solchen Datensätze.
- Laufzeitdaten unter `data/` nicht mit dem Uploadskript überschreiben.
- Nutzer meldet am 14. Oktober 2026 die Pi-Kamera als angeschlossen;
  Ausgabe von `rpicam-hello --list-cameras` bestätigt `imx708_noir`
  mit 4608×2592 Pixeln. Nutzer bestätigt anschließend echtes Livebild
  in der WebUI nach Einrichtung von Picamera2.
- Nutzer-Screenshot vom 14. Oktober 2026 bestätigt SSH-Zugang als
  `marcinator_2` auf `raspi5wlan.local` und Projektdateien unter `~/halloween`.
  Standgleichheit, Python-Einrichtung und laufende WebUI noch prüfen.
- Versionierter Upload richtet systemd-Autostart bei jedem `--apply` ein.
  Neue Version samt eigener `.venv` unter `releases/`, atomarer `current`-Link,
  gemeinsames `data/` über `HALLOWEEN_STATE_DIR`. Nach Dienststopp Daten sichern;
  bei Start-/HTTP-Fehlern Code, Unit und Daten zurücksetzen. `--web-host` wählt
  Loopback oder ausdrücklich Heimnetz; gespeicherte Wahl bleibt erhalten.
  Update mit genau einem sudo-Aufruf für Umschaltung und Rückfall; Paketsetup
  unprivilegiert, Python-/Unitprüfung per runuser als Pi-Benutzer. Passwort und
  sudoers/Zeitstempel bleiben unverändert; echte Passwortabfrage noch prüfen.
  Alte Versionen/Sicherungen nicht automatisch löschen. Lokale Simulationstests
  bestanden; Nutzer bestätigt erfolgreichen Upload. Autostart nach tatsächlichem
  Reboot und automatischer Rückfall am Gerät noch ungeprüft.

- Nutzer-Ausgaben bestätigen Raspbian GNU/Linux 13 (trixie), Python 3.13.5
  und Kernelarchitektur aarch64; Paket-/Python-Bitness noch nicht geprüft.
  Nach Netzteilwechsel SSH wieder erreichbar, get_throttled=0x0;
  keine Diagnose des vorherigen Ausfalls daraus ableiten. Kein OpenCV-Build
  in der übermittelten Prozessliste; Dell-Netzteilwerte bleiben ungeprüft.

## Prüfung

- Softwareprüfungen, Hardwaretests und Außentests getrennt berichten.
- Erst ohne angeschlossene Aktoren simulieren, dann einzelne Aktoren testen,
  anschließend Gesamtablauf und Fehlerfälle prüfen.
- Kamera bei tatsächlicher Dunkelheit, Beleuchtung und Verkleidungen testen.
- Sicheren Zustand bei Netzwerkausfall, Neustart und Stopp verifizieren.
- Dokumentationsänderungen erfordern keine zusätzlichen Softwaretests.

## Fiktive Videoeinblendungen

Scan-/Datenbankdarstellungen in Vorschauvideos verwenden erfundene
Avatare und IDs, mit sichtbarer Simulationskennzeichnung. Externe
Bildsequenzen eines Blender-Schnittprojekts bei Weitergabe mitnehmen.