added point mode

SOFTWARE.md

@@ -2,8 +2,9 @@
 
 Diese Version implementiert ein Livebild des vorhandenen Camera Module 3 NoIR
 über Picamera2, eine lokale WebUI, Moduswahl mit Speicherung und eine
-**Simulation** des Effektablaufs. Sie steuert noch keine GPIOs, Motoren,
-Servos, Lampen oder Lautsprecher. Eine lokale SQLite-Datenbank speichert
+**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,
@@ -258,7 +259,7 @@ 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.
-Aktoren bleiben ausschließlich simuliert.
+Die Aktoren des Grabablaufs bleiben simuliert; Kameraservos haben einen eigenen Testmodus.
 
 ### Nahbereich testen: Bewegung in Pfeilrichtung
 
@@ -338,3 +339,150 @@ HALLOWEEN_TEST_MODEL="$PWD/data/models/object_detection_nanodet_2022nov.onnx" .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
+
+In der WebUI gibt es einen eigenen 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](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. **Automatisch auslösen** ausschalten und **Linie und Bereich speichern**
+   drücken. Farbtest und automatische Auslösung schließen sich gegenseitig aus.
+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 Start der echten Nachführung setzt beide Servos sofort auf **1500 µs**.
+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 **Servogrenzen und Richtung
+einstellen** die betreffende Richtung umkehren und speichern. Grenzen pro Achse
+schrittweise ermitteln; absolut erlaubt sind 1100–1900 µs mit 1500 innerhalb
+des Bereichs. Gleiche Minimum-/Maximumwerte von 1500 sperren eine Achse auf die
+Mittelstellung. Diese Werte sind Pulsbreiten, keine garantierten Winkel.
+
+Die Regelung hat eine Totzone um die Bildmitte und ändert die Pulse um maximal
+80 µs/s. Bei fehlendem oder uneindeutigem Ziel wird nicht weiter nachgeführt;
+nach einer Sekunde wird die Hardware-Sitzung beendet. Es gibt keine Suchfahrt.
+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**, der allgemeine **Stopp** und **Nach Stopp
+zurücksetzen** beenden die Nachführung und setzen CH0/CH1 auf PWM aus.
+Der Grabablauf bleibt nach dem Farbtest bis zum bewussten Zurücksetzen
+angehalten. 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](https://pillow.readthedocs.io/en/stable/handbook/concepts.html),
+[NXP PCA9685](https://www.nxp.com/docs/en/data-sheet/PCA9685.pdf),
+[smbus2](https://smbus2.readthedocs.io/en/latest/api.html).
+
+
+## Endpunkte der Kamerahalterung manuell einrichten
+
+Im Farbpunkt-Abschnitt **Endpunkte einrichten · manuell** öffnen. Die
+Servomittelstellung muss wie oben beschrieben vorab geprüft sein. Die
+Automatik bleibt ausgeschaltet. Bewegungsraum bestätigen und **Einrichtmodus
+starten** drücken. Der Start setzt wieder beide Achsen auf 1500 µs. 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 der allgemeine Stopp die Ausgabe beendet.
+- **Links-Grenze speichern**, **Rechts-Grenze speichern**, **Oben-Grenze
+  speichern** oder **Unten-Grenze speichern** übernimmt den zuletzt
+  angeforderten Wert mit 10 µs Abstand nach innen. Die gespeicherten Grenzen
+  sind unter den Tasten dauerhaft sichtbar und 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; die absoluten Softwaregrenzen bleiben **1100–1900 µs**.
+  Ist damit nicht genug Weg verfügbar, stoppen und Mechanik/Servodaten klären,
+  nicht die Halterung gewaltsam verstellen. Die Grenzen müssen weiterhin die
+  1500-µs-Startposition einschließen.
+
+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. 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.