Halloween/PLAN.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.

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.

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

Pi-Installation nach unterbrochenem OpenCV-Quellbuild

• Nutzer bestätigt Raspbian 13/trixie, Python 3.13.5, Kernel aarch64 und get_throttled=0x0. Paketarchitektur ist damit noch nicht nachgewiesen.
• SSH nach Netzteilwechsel wieder möglich; Prozessliste zeigt nur PipeWire, keinen laufenden pip-/Compiler-Build. Ausfallursache bleibt ungeklärt.
• Pi-Anleitung auf fertige Systempakete umgestellt; pip-Requirements erlauben nur Wheels und brechen andernfalls ab. Kein weiterer Quellbuild vorgesehen.
• Offen: installierte OpenCV-Version/-Herkunft und echte Modellinferenz am Pi prüfen. Dell-Netzteil laut Nutzer passend, Ausgangsprofile nicht verifiziert.

Updateauftrag vom 14. Oktober 2026

• Erledigt: Versionsordner, eigene Python-Umgebung, gemeinsames data/, systemd-Neustart und Autostart, HTTP-Prüfung und automatischer Rückfall einschließlich Datensicherung; Anleitung in UPLOAD.md.
• Lokal verifiziert: simulierte Dienst-/Installationsfehler und erfolgreiche Umschaltung, Erhalt von Einstellungen/Daten und Rückfall zur Altinstallation.
• Nutzer bestätigt: bisheriger Updateaufruf hat funktioniert.
• Offen am Pi: tatsächlichen Neustart/Autostart und Rückfall testen; keine Hardwareprüfung durch den Agenten erfolgt.
• Betriebsgrenze: keine automatische Wiederherstellung nach Stromverlust während des Updates; Speicherbedarf und Aufräumen alter Sicherungen manuell prüfen.

Nahbereichstest vom 14. Oktober 2026

• Erledigt: auswählbarer Bewegungs-Test in Pfeilrichtung ohne Personenmodell; keine Überquerung nötig, getrennte Testereignisse, gespeicherte Auswahl.
• Lokal verifiziert: synthetische Richtungs-/Störungs-/Sperrtests, modellfreier Worker und vorhandene Softwaretests. Browser-Demo: Auswahl, Speicherung und Wiederherstellung nach Neuladen in UI-Struktur; Screenshot nicht verfügbar.
• Offen: neue Version auf Pi übertragen und tatsächliche Nahbereichbewegung kalibrieren/prüfen. Bewegungstest ist kein Nachweis für Personenauslösung oder menschenfreie Bereiche im späteren Gartenbetrieb.

Rückmeldung: Nahbereich löst nicht aus

• Nutzer-Screenshot: Pi-Livebild, Testmodus aktiviert, 5 Auswertungen/s und Automatik bereit. Nutzer bewegt Hand/Kopf nach rechts passend zum Bildpfeil; keine Auslösung gemeldet. Manuelles Bereich-frei beeinflusste nur die separate Controlleranzeige, nicht die automatische Freigabe.
• Lokal reproduziert: kleiner/langsamer Stimulus im großen Bereich scheitert an alter Bildänderungsschwelle. Schwellen reduziert, Richtung und Doppelbestätigung beibehalten. Derselbe Stimulus löst nun ohne manuelles Freigeben aus; Gegenrichtung wird verworfen. Diagnoserückmeldung und Automatikstatus in der UI ergänzt.
• Offen am Pi: erneuter Upload und tatsächlicher Nahbereichstest. Synthetische Tests und JS-Rendererprüfung sind keine Bestätigung einer echten Auslösung.

Automatische Auslösebilder vom 14. Oktober 2026

• Erledigt: lokal gespeichertes JPEG pro automatischem akzeptierten Trigger, auf grünen Bereich begrenzt; Bildvorschau/Ansehen/Löschen in Ereignisliste. Aufbewahrung laut Nutzer bis manueller Löschung. Ereignis/Profil bleiben.
• Lokal geprüft: identischer Trigger-Frame, Bereichsbeschnitt, Dateirechte, Persistenz, Migration, Fehlerbereinigung, Bild-API und manuelles Bildlöschen ausschließlich mit synthetischen Daten.
• Offen: neue Version hochladen, echte Auslösung und Bildvorschau am Pi prüfen. Bestehende Ereignisse bleiben bildlos; Sicherungsbilder gesondert verwalten.
• Liveprüfung vor diesem Auftrag: Pi-Ereignisliste zeigte drei automatische Bewegungs-Testauslösungen (13:07:54, 13:08:26, 13:08:53) ohne Bilder; daraus folgt kein Nachweis für neue Bildspeicherung oder Erkennungsqualität.

Einmalige sudo-Abfrage beim Update

• Erledigt: ein sudo-Aufruf nach Vorbereitung der Python-Umgebung. Umschaltung, systemd und Rückfall laufen im selben privilegierten Teil; Python und Unit-Renderer als Pi-Benutzer über runuser. Besitzer von Link/Konfiguration/ neuen Sicherungen bleiben beim Pi-Benutzer. Keine Passwortablage/sudoersänderung.
• Lokal verifiziert: 12 Update-Simulationstests einschließlich Ablehnung jedes zweiten sudo-Aufrufs, erfolgreichem Rückfall und abgelehnter sudo-Anmeldung.
• Offen am Pi: aktualisierten Upload ausführen und tatsächliche Anzahl der Passwortabfragen sowie Dienst/Python-Benutzer prüfen; kein echter PAM-Test.