Projektübersicht

Nur für privaten, experimentellen Gebrauch. Bau, Download und Nutzung erfolgen auf eigene Verantwortung. Niemals an Unternehmensrechner, Produktivsysteme, Industrieanlagen oder sicherheitskritische Systeme anschließen oder diese bedienen. Experimenteller Referenzprototyp ohne freiwillige Funktions- oder Sicherheitsgarantie. Haftung und Gewährleistung werden nur im gesetzlich zulässigen Umfang ausgeschlossen; zwingende Ansprüche bleiben unberührt. Vollständiger Nutzungshinweis und Haftungsausschluss.

Ein eigenständiger, beaufsichtigter Referenzprototyp für Raspberry Pi 5 + Pico 2. Der Zielrechner liefert nur sein HDMI-Bild und empfängt normale USB-HID-Eingaben. Auf dem Zielrechner wird keine Fernsteuerungssoftware installiert. Die Implementierung umfasst UVC-Capture, Astra-Responses-Adapter, Agentenloop, lokale Sicherheitsprüfung, Webleitstand und Pico-C-Firmware.

Status: Software mit simulierten Geräten testbar; Pico-2-Firmware erfolgreich crosskompiliert; physischer Aufbau und reale OpenAI-Verbindung müssen vor privatem Testbetrieb geprüft werden. Eine universelle, unbeaufsichtigte Bediengarantie gibt es nicht. Die sichere Voreinstellung verlangt für jede HID-Eingabe eine einzelne Benutzerfreigabe. Eine rein lokale Klick-/Tastenprüfung kann die Bedeutung „Kaufen“, „Löschen“ oder „Senden“ in beliebigen Anwendungen nicht zuverlässig erkennen. Mehr Autonomie braucht einen ausdrücklich begrenzten, getesteten privaten Testbereich und eine zusätzliche überprüfbare Fachregel; daraus entsteht keine Freigabe für Produktivsysteme.

Schnell zum Ergebnis

• Hardwareliste und vollständige Verkabelung
• Installation auf dem Pi und Firmwarebau
• Bereits gebaute Pico-2-Firmware
• HB1-Protokoll und USB-Deskriptoren
• OpenAI-Integration und Beispielablauf
• Sicherheitsmodell und technische Grenzen
• Testplan für Software und echte Hardware
• Prüfergebnisse dieses Entwicklungsstands

Demo ohne Hardware und ohne API-Key

Python 3.11 oder neuer. Im Projektordner:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/hardware-box --demo

Leitstand öffnen. Den beim Start ausgegebenen zufälligen Sitzungstoken eingeben. „Starten“ führt ein festes Demonstrationsskript aus; Freigaben lösen nur protokollierte Dry-HID-Reports aus. Das angezeigte Excel-Bild ist simuliert, es wird keine echte Datei verändert. Demo ist auch in config/example.toml die Voreinstellung.

1. Referenzhardware

Die genaue Beschaffungsliste einschließlich Isolatorpinout, Hubkandidat und Grenzen des unabhängigen USB-Trenners steht in HARDWARE.md. 4K60 am HDMI-Eingang ist keine Zusage für 4K60-Capture. Die Herstellerdaten unterscheiden diese beiden Pfade. Magewell Spezifikation

2. Signalwege

flowchart LR
    PC[Ziel-PC HDMI OUT] --> CAP[Capture: HDMI IN]
    CAP -->|HDMI LOOP THRU| MON[Normaler Monitor]
    CAP -->|USB3 über gespeisten Hub| PI[Raspberry Pi 5]
    PI -->|Screenshot / HTTPS| API[OpenAI Responses / GPT-6 Astra]
    API -->|Strukturierte Aktionen| PI
    PI --> SAFE[Lokale Prüfung + Freigabe]
    SAFE -->|HB1 / isolierte UART| PICO[Pico 2]
    PICO -->|Standard USB HID| TARGET[Ziel-PC USB HOST]
    ESTOP[Physischer Not-Aus] --> PICO
    ESTOP --> DISCONNECT[Unabhängige USB-Datentrennung]
    DISCONNECT --- TARGET

Der Monitorpfad passiert weder Pi noch API. „Praktisch verzögerungsfrei“ ist für den Hardware-Loop eine sinnvolle Anforderung, aber die tatsächliche Verzögerung wird gemessen. Die Agentenlatenz hängt zusätzlich von UVC, Bildkompression, Internet, Modell und Benutzerfreigabe ab; 60 Capture-Frames pro Sekunde bedeuten keine 60 Modellentscheidungen pro Sekunde.

3. Softwarearchitektur

src/hardware_box/
  capture/device.py     UVC-Reader-Thread, jeweils neuestes Bild, DemoCapture
  vision/frame.py       PNG, Zeitstempel, Seitenverhältnis, Letterboxing, Hash
  openai/client.py      Responses computer-Tool, vollständiger Gesprächsverlauf
  controller/agent.py   Zustände, Loop, Einzelbesitzer, Abbruch und Ergebnisprüfung
  safety/policy.py      Schema, echte HID-Kürzel, Raten-/Sitzungs-/Aktionslimits
  hid/protocol.py       CRC-Framing und Antwortprüfung
  hid/mapping.py        Screenshot → normalisierte absolute HID-Koordinaten
  hid/keyboard.py       US-/DE-/AT-PC-Layouts, Shift/AltGr, gesamte Textvorprüfung
  hid/driver.py         UART, 100-ms-Heartbeat, ACK, RealHID und DryHID
  logging/audit.py      JSONL, Hashkette, optionale PNG-/API-Archive
  web/                 Authentifizierter lokaler Webleitstand
pico/                  C-Firmware, TinyUSB, Parser, Not-Aus und Watchdogs
config/example.toml    Sichere Voreinstellungen
deploy/                Beispiel für systemd
tests/                 Hosttests mit simuliertem UART/Capture/API

Ein einziger Controller besitzt den HID-Ausgang. Manuelle Tests können eine aktive Agentensitzung nicht überholen. Die UART ist unabhängig von der Pico-USB-Verbindung: Der Pico wird am Ziel als Boot-Tastatur, absolute Maus und relative Maus enumeriert. Es gibt auf dem Pico weder USB-CDC-Kanal zum Ziel noch Massenspeicher oder Netzwerk.

4. Agentenloop

1. Aktuelles HDMI-Bild erfassen und Screenshot vorbereiten.
2. Auftrag, Screenshot und seine Geometrie an gpt-6-astra senden; nur tools: [{"type":"computer"}] bereitstellen.
3. API-Status und jeden computer_call prüfen; alle Aktionen eines Calls vor dessen erster Eingabe vollständig vorprüfen.
4. Bei API-Sicherheitschecks eine gesonderte Freigabe einholen. Kein automatisches Bestätigen.
5. Nächste Aktion anhand Schema, Koordinaten, Tastaturlayout und Sperrregeln prüfen.
6. Aktuellen Screenshot samt konkreter Aktion im Leitstand zeigen. Eine Freigabe enthält einmaligen Token und Bildhash.
7. Vor der Ausgabe nochmals den aktuellen Screenshot prüfen: Bei geändertem Bild verfällt die Freigabe. Dann Aktionsrate und Zeitlimit prüfen, Absicht protokollieren und HID ausgeben.
8. Pico-ACK kontrollieren. Ein ACK bestätigt USB-Transfer, keine erfolgreiche Anwendungshandlung.
9. Mindestens 350 ms warten; anschließend ein frisch aufgenommenes Bild liefern, nicht einen alten Queue-Frame.
10. computer_call_output mit derselben call_id und computer_screenshot zurückgeben. Falls ein Call mehrere Aktionen enthält, bleiben sie geordnet; jede Eingabe wird einzeln freigegeben.
11. Wiederholen, bis keine Computer-Calls vorliegen. Modelltext als Ergebnis zur Prüfung anzeigen und HID disarmen. Erst der Benutzer bestätigt den tatsächlichen Erfolg.

Ein unabhängiger Hostmonitor kontrolliert Capture und Sitzungsdeadline auch während API-/Freigabewartezeiten. Der Pico überwacht zusätzlich seinen eigenen Heartbeat. Nach Pause/Stop wird der Auftrag auf Grundlage des sichtbaren Restzustands neu geplant; alte Eingaben werden nicht blind nachgeholt.

5. Koordinaten und Maus

Absolute USB-Reports enthalten X/Y in 0..32767, keine Desktoppixel. Für einen Screenshot mit Inhaltsrechteck (left, top, cw, ch) gilt:

fx = (x - left) / (cw - 1)
fy = (y - top)  / (ch - 1)
hid_x = round(fx * 32767)
hid_y = round(fy * 32767)
target_x = round(fx * (target_width  - 1))
target_y = round(fy * (target_height - 1))

Für Screenshot 1920×1080, Ziel 3840×2160 und (1250,620) ergeben sich ungefähr Zielpixel (2501,1241) und HID (21344,18828). Der Faktor ist wegen der Pixelendpunkte minimal größer als exakt 2. Die tatsächliche Mauszuordnung bestimmt der HID-Treiber des Zielsystems. Die Software kennt die native Zielauflösung aus bestätigter Konfiguration; ein auf 1080p skalierter Capture-Frame verrät nicht automatisch, ob die Quelle 1080p oder 4K sendet.

Schwarze Ränder werden bei der Pi-seitigen Skalierung berechnet und aus dem Mapping ausgeschlossen. Bereits im HDMI-Signal vorhandene Ränder, Overscan, Capture-Crop, Rotation und Mehrschirmanordnungen erfordern weitere Kalibrierung; automatische Erkennung wird nicht behauptet. Punkte außerhalb des bestätigten Inhalts werden abgewiesen, niemals still geklemmt.

Der Referenzagent stoppt bei ungeeigneter absoluter Mauszuordnung. Eine relative Cursorregelung ist eine klar getrennte Ausbauoption, keine bereits implementierte Garantie. Scrollwerte der API sind Pixel; USB-Wheel sendet Raster. Das Beispiel nutzt 120 angeforderte Pixel pro Raster mit Restwertakkumulation. Die tatsächliche Strecke bleibt OS-/Anwendungsabhängig und wird im nächsten Screenshot beurteilt.

6. Tastatur

Boot-Keyboard mit sechs gleichzeitig gedrückten Tasten und acht Modifierbits. Unterstützt normale ASCII-Texte, DE/AT-Umlaute und ß, €, Groß-/Kleinschreibung, Enter, Escape, Tab, Backspace, Delete, Pfeile und Ctrl/Alt/Shift/GUI. Ctrl+C, Ctrl+V, Ctrl+S usw. werden als physische Tasten erzeugt. DE/AT berücksichtigt Y/Z, AltGr und tote Akzenttasten.

Das konfigurierte Profil muss dem Ziel entsprechen. DE/AT ist hier Standard-PC-Layout unter Windows/Linux; deutsches macOS hat andere Sonderzeichen. US am Mac ist nach Abnahme möglich; Command wird als GUI gesendet. Unbekannte Unicodezeichen, IMEs, US International und wechselnde Layouts werden nicht erraten. Gesamten Text vorab prüfen, damit ein nicht unterstütztes Zeichen keine schon eingegebene Teilzeichenfolge hinterlässt. CapsLock/NumLock müssen lokal bekannt sein; diese Version verarbeitet keine LED-Rückmeldung.

7. Sicherheits- und Bedienmodell

Der Webleitstand bietet Auftrag, Screenshot, nächste Aktion, Start/Pause/Stop, separate Freigaben, Ergebnisprüfung, manuellen JSON-Eingabetest, Modellzugriffsprüfung, Auflösung/Layout, Aktions-/Zeitlimits, zusätzliche gesperrte Kürzel, optionale Kürzel-Freigabeliste und laufende Logs. Kürzeländerungen gelten nach Neustart; die feste Sperrliste bleibt bestehen.

Weitere Regeln: keine ungeprüfte Codeausführung, keine externen Webassets, Bearer-Token, Origin-/Host-Prüfung, standardmäßig nur Loopback. Für Fernzugriff SSH-Tunnel verwenden. Jede bewusste ARM-Freigabe benötigt den lokalen Pico-Taster; PING kann niemals armen. GPIO-Not-Aus ist gelatcht und erfordert bewussten Pico-Neustart. Ein unabhängiger Datenkontakt ergänzt ihn bei MCU-Hängern. Die vorgeschlagene Laborschaltung benötigt noch elektrische Abnahme und eine qualifizierte Wiederanlaufsperre.

Alle Eingaben werden lokal mit Absicht, Freigabe, ACK und Screenshot-Hash protokolliert. Texte können Geheimnisse enthalten; deshalb 0700-Sitzungsverzeichnisse und 0600-Dateien. Screenshot-/API-Dateien sind opt-in. Hashketten machen Änderungen erkennbar, sind ohne externen vertrauenswürdigen Anker nicht manipulationssicher. store:false verhindert gespeicherten Responses-Anwendungszustand, bedeutet aber nicht automatisch Zero Data Retention. OpenAI Datenkontrollen

8. Beispiel Excel

Im echten Aufbau plant Astra anhand des Bildes: Excel öffnen → Datei sichtbar auswählen → Zelle B7 adressieren → Wert 250 eingeben → speichern → Ergebnis visuell kontrollieren. Dafür existiert keine Excel-Datei- oder Office-API im Projekt. Jede Navigation erfolgt über HID. Bereits der vollständige Auftragswortlaut ist keine technische Zusicherung, dass Fokus, Datei oder Speichern erfolgreich sind.

Die sichere Referenz bittet vor den jeweiligen Eingaben um Freigabe, insbesondere auch vor Ctrl+S/Speichern. Zum Abnahmetest ausschließlich eine Kopie der Arbeitsmappe verwenden und nach Abschluss B7 sowie den gespeicherten Zustand lokal prüfen. Der Demo-Modus zeigt nur die Schleifenmechanik; er testet kein Excel.

9. Betriebsgrenzen und Entwicklungsschritte

Implementiert: modularer Python-Host, native computer-Integration für Astra, laufender Screenshot-Feedbackloop, absolute Geometrie, getestete Tastaturtabellen, HB1-Protokoll, Pico-Quellcode und gebaute UF2, Sicherheitsprüfung, Weboberfläche, Demo, Installations-/Testunterlagen.

Vor echter Nutzung offen: Firmwareflash, elektrische Prüfung, UVC-60-fps-/Passthroughmessung, Betriebssystem-Kalibrierung, reale API-/Computer-Tool-Kontoabnahme, Interlock- und Wiederanlauftests. Es liegt keine fertige geprüfte Leiterplatte oder zertifizierte Not-Halt-Schaltung vor.

Ausbau: fertige USB-Datentrennerplatine mit Hardware-Rearm, Tastatur-LED-Rückkanal, zusätzliche macOS-/Unicodeprofile, präzise Capture-Metadaten/EDID-Wechselkontrolle, visuelle Cursorregelung für relative Maus und begrenzte automatisch erlaubte Arbeitsbereiche. Jede Erweiterung braucht eigene Fehler-/Abnahmetests.

HDCP-Inhalte sind nicht erfassbar und werden nicht umgangen. HDMI-Ausgabe, USB-Annahme, sichtbare Oberfläche und Internet sind Voraussetzungen. Zielseitige USB-Sperren, Firmwarepasswörter, sicherer Desktop, UEFI, Remote-Sitzungen, Fokusverlust, Bildschirmwechsel, CAPTCHAs und MFA können den Ablauf stoppen. Ein Not-Aus macht bereits ausgeführte Eingaben nicht rückgängig. Pixelgenaue Bildfreigaben verfallen auch bei harmloser Animation oder blinkendem Cursor; dieser konservative Mechanismus begrenzt derzeit die Alltagstauglichkeit und vollständige Autonomie.

10. Tests ausführen

.venv/bin/python -m pytest -q
bash pico/tests/run_native.sh

Die Tests verwenden für Hardware und OpenAI lokale Ersatzgeräte. Sie belegen Kontrolllogik und Protokoll, nicht reale USB-Kompatibilität oder API-Verfügbarkeit. Die vollständige praktische Abnahme steht in TESTPLAN.md.

Die OpenAI-Modellseite führt gpt-6-astra mit Computer Use. Die offizielle Anleitung empfiehlt für Astra allgemein Codeausführung und unterstützt weiterhin das strukturierte computer-Tool. Hier wird dieses Tool gewählt, damit jede Aktion lokal begrenzt und geprüft werden kann. Astra-Modell, Computer Use