working camera movement

SOFTWARE.md

@@ -27,8 +27,9 @@ python3 -m venv --system-site-packages .venv
 
 Picamera2 wird über die Raspberry-Pi-Pakete installiert; die virtuelle
 Umgebung kann dieses Systempaket durch `--system-site-packages` verwenden.
-Der Server bindet nur an `127.0.0.1` auf dem Pi. So ist das Livebild nicht
-direkt im WLAN sichtbar.
+Beim Start über `run.py` bindet der Server nur an `127.0.0.1` auf dem Pi.
+Der versionierte Dienst nutzt dagegen die beim Upload gewählte Bind-Adresse
+(siehe unten); mit `0.0.0.0` ist die WebUI direkt im Heimnetz erreichbar.
 
 ### WebUI beim Hochfahren starten
 
@@ -238,7 +239,7 @@ ein manueller Testbutton umgeht keine Fehlersperre.
 
 Kamera-/Modellfehler und mehr als zwei Sekunden ohne gültige Auswertung
 sperren die aktivierte Automatik und stoppen den simulierten Ablauf. Nach
-Beheben des Fehlers „Nach Stopp zurücksetzen“ verwenden und Bereich
+Beheben des Fehlers „Grab zurücksetzen“ verwenden und Bereich
 freihalten. Modellprobleme bei deaktivierter Automatik verhindern keine
 manuellen Tests. Der Demo-Livefeed und manuelle Tests brauchen weder OpenCV
 noch Modell; der Bewegungs-Test benötigt auch im Demo-Modus OpenCV. Synthetische
@@ -303,7 +304,7 @@ Sperrzeit und erneut mindestens zwei Sekunden ruhiges Bild. Ein ruhiges Bild
 beweist **keinen menschenfreien Bereich**. Stopp, Fehler-Watchdog, bewusstes
 Rücksetzen und erneute Freigabe nach Start/Konfigurationswechsel bleiben wirksam.
 Bei bereits gesetzter Fehlersperre nach Auswahl und Speichern bewusst
-„Nach Stopp zurücksetzen“ drücken.
+„Grab zurücksetzen“ drücken.
 
 Dies ist ein **Bewegungs-Test für die Simulation**, keine Personenerkennung
 für den späteren Gartenbetrieb. Auch Kamera-/Hintergrundbewegung kann auslösen.
@@ -343,8 +344,8 @@ 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
+Auf der Seite **Kamera / Finger** (`/kamera`) gibt es den 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
@@ -372,8 +373,10 @@ 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.
+1. Oben **Kamera / Finger** öffnen. Das Livebild erscheint sofort. Für eine
+   Farbvorschau muss die Grabautomatik nicht ausgeschaltet werden. Nur vor
+   echter Servobewegung auf **Grab** die automatische Auslösung ausschalten
+   und **Linie und Bereich speichern** drücken.
 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
@@ -388,7 +391,12 @@ Vor Updates/Neustarts die Servoversorgung abziehen.
 
 ### Erste echte Bewegung
 
-Der Start der echten Nachführung setzt beide Servos sofort auf **1500 µs**.
+Der bewusste Start der echten Nachführung oder des Einrichtmodus setzt jede
+Achse auf **(gespeichertes Minimum + gespeichertes Maximum) / 2** ihrer
+Bewegungsgrenzen. Halbe Mikrosekunden werden aufgerundet. Beispiel: PAN
+1000–1800 → 1400 µs, TILT 1300–1800 → 1550 µs. Die WebUI zeigt die Werte unter
+**Beim nächsten Start**. Ohne angepasste Grenzen ergibt sich weiterhin 1500 µs.
+Beim Hochfahren des Pi wird keine Kamerasitzung gestartet.
 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
@@ -397,25 +405,96 @@ 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
+Bewegt sich eine Achse vom Punkt weg, stoppen, unter **Farbe, Drehrichtung, Tempo und Suche
 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.
+schrittweise ermitteln; die Nachführgrenzen müssen im gespeicherten
+Einrichtbereich liegen; Minimum darf nicht größer als Maximum sein. Gleiche
+Minimum-/Maximumwerte sperren eine Achse bei der Nachführung auf diesen Wert. Diese Werte sind Pulsbreiten, keine garantierten Winkel.
+
+Die Regelung hat eine Totzone um die Bildmitte. **Nachführtempo** stellt die
+maximale Pulsänderung zwischen 40 und 800 µs/s ein; nahe der Mitte wird langsamer
+nachgeführt. Zum ersten schnelleren Test: Kameraservos stoppen, **400** eintragen,
+**Farbe, Richtung, Tempo und Suche speichern**, anschließend bewusst neu starten.
+400 ist der Standard für neue Konfigurationen. Alte Einstellungen behalten beim
+Update zunächst 80; Endpunkte bleiben erhalten. Die Regelverstärkung ist auf 600 µs/s je Bildbreite/-höhe begrenzt (Bildverzögerung
+lässt höhere Werte pendeln); das Tempo wirkt als Obergrenze, mehr als ca. 300 µs/s
+wird dadurch bei Zielen nahe der Bildmitte/-rand nicht mehr erreicht. Bei Pendeln Tempo reduzieren.
+Einrichtung und Mittelstellungsbutton bleiben auf 40 µs/s begrenzt. Der bewusste
+Sitzungsstart gibt hingegen unmittelbar die gespeicherte Mitte als Sollwert aus;
+dessen reale Servogeschwindigkeit wurde nicht gemessen.
+
+Die Pi-Kamera zielt jetzt auf **15 Bilder/s** bei 640×480, die synthetische Demo
+bleibt bei etwa 5. Die Konfiguration nutzt Picamera2-`FrameDurationLimits`
+([Herstellerhandbuch](https://datasheets.raspberrypi.com/camera/picamera2-manual.pdf)).
+Über dem Bild stehen gemessene Kamerabilder/s, Nachführ-Auswertungen/s und die
+Dauer der Farberkennung. Das sind Softwaremessungen, keine CPU-Auslastung oder
+Bestätigung der realen mechanischen Geschwindigkeit. Die Vorschau fragt etwa
+alle 100 ms plus Antwort-/Darstellungszeit ab; die Regelung läuft unabhängig davon.
+Bei verzögerten Bildern werden maximal 100 ms Bewegung nachgeholt. Ob der Pi
+15 Bilder/s unter jeder Last erreicht, bleibt zu prüfen. Am 16. Oktober meldet
+seine Status-API 15,0 Bilder/s bei inaktiver Nachführung.
+
+### Übersichtliche Bedienung
+
+Die Seiten nutzen bis zu 1800 Pixel Breite. Ab 1000 Pixel Bildschirmbreite
+stehen Kamerabild und Bedienung nebeneinander; darunter untereinander.
+Auf der Kameraseite sind Status, Vorschau, echte Nachführung und Kamerastopp
+rechts direkt sichtbar. **Farbe, Drehrichtung, Tempo und Suche einstellen**
+öffnet die Detailparameter. **Endpunkte & manuelle Einrichtung** unter den
+beiden Hauptbereichen öffnet Grenzwerte, Richtungstasten und Mittelstellung.
+Am Desktop bleibt **Alles stoppen** im Seitenkopf beim Scrollen erreichbar.
+
+Auf der Grabseite sind **Automatische Auslösung einstellen**, **Gespeicherte
+Ereignisse** und **Personenprofile** aufklappbar. Die Auswertungs- und
+Betriebsstatus bleiben sichtbar. Auf-/Zuklappen speichert keine Einstellungen
+und startet oder stoppt keine Sitzung.
+
+### Farbpunkt nach Verlust suchen
+
+Unter **Farbe, Drehrichtung, Tempo und Suche einstellen** die Option
+**Bei Punktverlust automatisch suchen** aktivieren und **Farbe, Richtung,
+Tempo und Suche speichern** drücken. Danach den Punkt vor die Kamera halten
+und **Echte Kameranachführung starten**. Vorschau bewegt keine Servos.
+Die gewählte Farbe bleibt in `data/follow.json` gespeichert, bis du bewusst
+Rot, Grün oder einen neuen Punkt im Beispielfoto wählst; auch ein Neustart
+löscht sie nicht. Gespeichert wird die Farbe, keine eindeutige Objektidentität.
+Die Suchoption ist zunächst aus, bleibt nach dem Speichern erhalten und
+verändert keine Endpunkte. Auch mit gespeicherter Option startet die Sitzung nie selbst.
+
+Nach erster eindeutiger Erkennung hält die Kamera bei Punktverlust kurz still.
+Nach 1,5 Sekunden beginnt sie in der zuletzt gesehenen Richtung zu suchen,
+unter Berücksichtigung der Achsumkehr. Sie schwenkt einmal auf der aktuellen
+Höhe und an den beiden gespeicherten TILT-Grenzen hin und her. Nur gespeicherte
+**Bewegungsgrenzen** gelten, niemals der größere Einrichtbereich. Suchtempo:
+höchstens 200 µs/s beziehungsweise das kleinere eingestellte Nachführtempo.
+Die tatsächliche Sichtfeldabdeckung hängt von Optik und Mechanik ab; der
+Suchweg garantiert keine lückenlose Erfassung des gesamten Bereichs.
+
+Bei einem wieder sichtbaren Punkt hält die Suche sofort an. Zwei aufeinander-
+folgende eindeutige Erkennungen übernehmen wieder die normale Nachführung.
+Ohne Fund endet nur die Suchfahrt nach einem Durchlauf oder spätestens
+60 Sekunden. Die Kamera wartet danach unbegrenzt auf die gespeicherte Farbe,
+solange Kamerabild und Bedienverbindung funktionieren. Die Servos halten ihre
+letzte Position; es werden keine weiteren Suchrunden gestartet. Sobald der
+Punkt in zwei aufeinanderfolgenden Bildern wieder eindeutig erkannt wird,
+folgt die Kamera weiter. Gesperrte Achsen bleiben unverändert.
+**Kameraservos stoppen**, **Alles stoppen** und die bisherigen Bild-/Verbindungs-
+und Auswertungswatchdogs brechen auch die Suche ab. Ohne aktivierte Suche oder
+wenn seit Sitzungsstart noch kein Punkt erkannt wurde, wartet die Kamera
+an ihrer Position ebenfalls weiter. Im manuellen Einrichtmodus
+findet keine Farbpunktsuche statt.
 
-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
+**Kameraservos stoppen** und **Alles stoppen** beenden die Nachführung und
+setzen CH0/CH1 auf PWM aus. **Grab stoppen** und **Grab zurücksetzen** wirken
+nur auf den Grabablauf. Die Kamera verändert dessen Modus und Stoppzustand
+nicht. Die Farbvorschau darf parallel zur Grabautomatik laufen; nur echte
+Kamerabewegung bleibt bei eingeschalteter Grabautomatik gesperrt. 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
@@ -448,9 +527,9 @@ Technische Referenzen: [Pillow HSV](https://pillow.readthedocs.io/en/stable/hand
 ## 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-
+Servomittelstellung muss wie oben beschrieben vorab geprüft sein. Für echte Bewegung muss die
+Grabautomatik ausgeschaltet sein. Bewegungsraum bestätigen und **Einrichtmodus
+starten** drücken. Der Start fährt jede Achse in die Mitte ihrer gespeicherten Bewegungsgrenzen. Im Demo-
 Betrieb heißt der Knopf **Einrichtmodus als Demo starten** und bewegt nur
 virtuelle Werte; es gibt keinen I²C-Zugriff.
 
@@ -462,17 +541,31 @@ virtuelle Werte; es gibt keinen I²C-Zugriff.
   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.
+  beziehungsweise **Alles stoppen** die Ausgabe beendet.
+- **In Mittelstellung fahren** ist im aktiven Einrichtmodus verfügbar. Einmal
+  klicken: beide Achsen fahren mit maximal 40 µs/s zur Mitte ihrer aktuell
+  gespeicherten Bewegungsgrenzen. Die Endpunkte bleiben unverändert. Kein
+  Gedrückthalten nötig; Kamera und Bedienverbindung müssen verfügbar bleiben.
+  **Bewegung anhalten** bricht die Fahrt ab und hält die erreichte Sollposition.
+  Eine Richtungstaste übernimmt ebenfalls die Bedienung. Kamerastopp beendet PWM.
+  Während der Fahrt sind Endpunktspeicherknöpfe gesperrt. Zum Zentrieren aus der
+  Farbnachführung zuerst Kameraservos stoppen und Einrichtmodus starten.
+- Unter den Richtungstasten zeigt jede der vier Karten **Links**, **Rechts**,
+  **Oben** und **Unten** den tatsächlich gespeicherten Wert. **Diese Position
+  als … speichern** übernimmt den aktuellen Sollwert dieser Achse mit 10 µs
+  Abstand nach innen. Der vorgesehene neue Wert steht schon vor dem Speichern
+  dabei; die Bestätigung nennt danach Richtung und gespeicherten Wert.
+- Ein Speicherknopf ist erst freigegeben, wenn die Achse ausreichend in die
+  zugehörige Richtung von der Mittelstellung gefahren ist. Bei falscher Seite
+  steht direkt an der Karte, was zu tun ist. Fehler beim Speichern erscheinen
+  im Einrichtbereich. Die Bestätigung bleibt sichtbar, bis eine neue Aktion
+  sie ersetzt. Die Grenzen 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.
+  überschreiten; er hält sich an den **Einrichtbereich** pro Achse. Dieser
+  beginnt bei 1100–1900 µs und kann gestoppt über die WebUI geändert werden.
+  Nur schrittweise erweitern, vor dem mechanischen Anschlag loslassen. Die
+  Nachführgrenzen müssen innerhalb des Einrichtbereichs liegen.
 
 Es gibt keine automatische Anschlagfahrt und keine Endschalterauswertung.
 Angezeigte Werte sind **Sollwerte**, keine gemessene Position. Ohne Encoder,
@@ -482,7 +575,71 @@ 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
+Sitzungsschlüssel, eine Richtung und eine steigende Sequenznummer. `center`
+beauftragt die Mittelstellungsfahrt nur in einer bestehenden Einrichtsitzung
+und verwendet dieselbe Sequenzfolge wie `jog`. 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.
+
+
+## Getrennte Seiten für Grab und Kamera
+
+- **Grab** unter `/` oder `/grab`: Livebild mit Erkennungsbereich, Betriebsmodus,
+  Auslösung, Ereignisse und Profile. Die Knöpfe **Grab stoppen** und **Grab
+  zurücksetzen** beeinflussen nur diesen Bereich.
+- **Kamera / Finger** unter `/kamera`: eigenes Livebild, Farbwahl,
+  Nachführung und manuelle Endpunkte. Farbvorschau und Einrichtung haben
+  getrennte Startknöpfe; beides gehört zur Kamerasitzung.
+- Oben auf beiden Seiten: Navigation und **Alles stoppen** für Grab und
+  Kameraservo-PWM gemeinsam. Die Stromversorgung wird damit nicht getrennt.
+
+Kamera und Grab speichern ihre bisherigen Einstellungen weiterhin getrennt.
+Die Seiten laden nur ihre eigenen Abfragen und Bedienelemente. Beide verwenden
+physisch dieselbe Kamera: Farbvorschau parallel ist möglich, echte Bewegung
+bei aktivierter Grabautomatik wird abgelehnt, ohne den Grabzustand umzustellen.
+Nach einer Kamerabewegung vor erneutem Aktivieren der Automatik Bildausschnitt,
+Linie und Bereich prüfen.
+
+Beim Verlassen der Kameraseite endet die Kamerasitzung über Stopp/Heartbeat,
+spätestens nach Ausbleiben der Bedienverbindung gemäß den bisherigen Regeln.
+Navigation startet keine Servos und ändert keinen gespeicherten Grabmodus.
+Die alten API-Aufrufe `/api/stop` und `/api/reset` bleiben als globale
+Abschaltung für ältere Clients bestehen; neue Grabknöpfe verwenden
+`/api/grave/stop` beziehungsweise `/api/grave/reset`.
+
+
+## Eindeutige Speicherung der Endpositionen
+
+Zusätzlich zu den vier Endpunktkarten gibt es auf **Kamera / Finger** den
+sichtbaren Bereich **Bewegungsgrenzen manuell eingeben** mit PAN Minimum,
+PAN Maximum, TILT Minimum und TILT Maximum. Nur bei gestoppter Kamerasitzung
+bearbeiten, dann **Bewegungs- und Einrichtgrenzen speichern** drücken. Darunter stehen
+immer die tatsächlichen Serverwerte; geänderte Eingaben werden ausdrücklich
+als ungespeichert markiert und bleiben beim Aktualisieren der Anzeige erhalten.
+**Eingaben verwerfen** stellt die gespeicherten Werte wieder her.
+
+Die manuelle Grenzspeicherung verändert Farbe/Drehrichtung nicht. Deren
+separater Speichern-Knopf verändert umgekehrt keine Grenzen. Ein Start speichert
+nichts; offene Grenzänderungen müssen zuerst gespeichert oder verworfen werden.
+Die Endpunktkarten und ihre Speicherung im aktiven Einrichtmodus bleiben
+zusätzlich erhalten. Manuelle Zahlenfelder sind während einer Sitzung gesperrt.
+Unter **Einrichtbereich zum Anfahren der Endpunkte** stehen zusätzlich PAN/TILT
+Einrichtung Minimum und Maximum. Diese Werte begrenzen die Richtungstasten,
+auch wenn die bisherigen Nachführgrenzen enger sind. Bei zu wenig Weg: stoppen,
+den betreffenden Einrichtwert in kleinen Schritten erweitern, speichern und
+Einrichtmodus erneut starten. Der Start berechnet die Mitte aus den gespeicherten Endpunkten neu. Dann die reale
+gewünschte Endposition langsam anfahren, loslassen und in der Richtungskarte
+speichern. Das übernimmt den Sollwert mit 10 µs Innenabstand für die Nachführung.
+
+Technische Eingabehülle: **500–2500 µs**, kein bestätigter mechanischer Bereich
+für diese Servos/Halterung. Die Nachführgrenzen müssen im Einrichtbereich liegen;
+bei einer direkten Zahleneingabe gegebenenfalls beide zusammen ändern. Speichern
+löst keine Bewegung aus. Alte Konfigurationen behalten alle Endpunkte und den
+bisherigen Einrichtbereich 1100–1900 µs; keine automatische Erweiterung.
+
+
+Die Startmitte einer Einrichtsitzung bleibt während dieser Sitzung der Bezug
+für die Links-/Rechts-/Oben-/Unten-Speicherknöpfe, auch nach dem Speichern eines
+Endpunkts. Speichern löst keine Zentrierfahrt aus. Erst beim nächsten bewussten
+Start wird die Mitte aus den dann gespeicherten Endpunkten neu berechnet.