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.
• 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.

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. Weitere Teile dürfen vorgeschlagen werden.
• 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.
• Mechanik erst nach Klärung von Abmessungen, Gewicht, Hub und Bewegungsraum auswählen. Atembewegung und kurzer Schreckimpuls getrennt bewerten.

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, Zugentlastung und geeignete Stromversorgung vorsehen.
• Bei Start, Verbindungsverlust oder Fehler keine neue Schrecksequenz auslösen; definierte sichere Zustände und lokalen Stopp vorsehen.
• 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.
• 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.
• Picamera2 liefert das MJPEG-Livebild; auf dem Entwicklungsrechner wurde nur der Demo-Feed geprüft, nicht die echte Pi-Kamera.
• Moduswahl und simulierte Sequenz sind implementiert. GPIO, automatische Personenauslösung und Clip-Speicherung sind noch offen.
• 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.
• Optionaler systemd-Autostart der WebUI wird mit --install-service beim Upload eingerichtet; auf einem echten Pi noch nicht geprü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.