Zum Inhalt

Systemarchitektur

Diese Seite zeigt das Innenleben jeder Komponente und die Schnittstellen dazwischen. Jede Schnittstelle hat einen EigentĂĽmer, der sie in seinem Repository dokumentiert:

Schnittstelle Transport EigentĂĽmer Referenz
Station → Host: Ergebnisse und Live-Daten MQTT (JSON) nestris-core (docs/STATION.md) MQTT-Schnittstelle
Station → Host: Aufzeichnung HTTP PUT …/ngf nestris-core / NestrisLTM NGF-Aufzeichnungen
Terminal ↔ Host REST, Bearer-Token NestrisLTM Terminal-API
Leser ↔ Station / Terminal USB-Seriell, JSON-Zeilen, Protokoll v2 nestris-rfid-reader (docs/PROTOCOL.md) Leser-Protokoll
Aufbau der Spielerkarte MIFARE Classic Sektor 1 nestris-rfid-reader (docs/CARD_FORMAT.md) Kartenformat

NestrisLTM (Host)

NestrisLTM ist ein einziger Python-Prozess mit zwei Hälften. Eine Qt-Shell läuft im Haupt-Thread. Ein asyncio-Hintergrund-Thread betreibt Webserver, MQTT-Ingest und Worker. Mit --headless läuft derselbe Kern ohne Qt, zum Beispiel auf einem Linux-Server.

flowchart LR
    subgraph EXT["AuĂźerhalb des Prozesses"]
        MQ["<span style='color:#ffffff'>Mosquitto<br/>:1883</span>"]:::ext
        PG[("<span style='color:#ffffff'>PostgreSQL<br/>:5432</span>")]:::ext
        BR["<span style='color:#ffffff'>Browser · OBS ·<br/>Terminal · Stationen</span>"]:::ext
        GH["<span style='color:#ffffff'>GitHub Releases</span>"]:::ext
    end

    subgraph PROC["NestrisLTM-Prozess"]
        direction TB
        subgraph QT["Haupt-Thread · PySide6"]
            TRAY["<span style='color:#111111'>Tray-Icon<br/>Statusfarben</span>"]:::ltm
            WIN["<span style='color:#111111'>Fenster mit<br/>eingebettetem Browser</span>"]:::ltm
        end
        subgraph CORE["Hintergrund-Thread · asyncio"]
            ING["<span style='color:#111111'>MQTT-Ingest<br/>(aiomqtt, persistente Session)</span>"]:::ltm
            HUB["<span style='color:#111111'>LiveHub<br/>Live-Zustand im Speicher</span>"]:::ltm
            SPOOL["<span style='color:#111111'>Spool auf Platte +<br/>Ingest-Worker</span>"]:::ltm
            FR["<span style='color:#111111'>Frame-Writer<br/>(gebĂĽndelt je 1 s)</span>"]:::ltm
            API["<span style='color:#111111'>FastAPI / uvicorn<br/>:7990 REST + WebSocket</span>"]:::ltm
            WS["<span style='color:#111111'>WebSocket-Hub</span>"]:::ltm
            UPD["<span style='color:#111111'>Update-PrĂĽfung</span>"]:::ltm
        end
    end

    MQ -- "status · player · live" --> ING --> HUB
    ING -- "event/*" --> SPOOL --> PG
    HUB --> FR --> PG
    HUB --> WS
    PG <--> API
    WS --> API
    API <--> BR
    API -- "cmd → Leser" --> MQ
    UPD --> GH
    TRAY & WIN -.-> API

    classDef ltm fill:#f5b800,stroke:#7a5c00,color:#111,stroke-width:2px
    classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px

Wichtige Eigenschaften

  • Ausfallsicherer Ingest. Spielereignisse (game_start, cheat, game_end) landen zuerst in einem Spool auf der Platte und erst dann in der Datenbank. Schreibvorgänge sind idempotent ĂĽber die game_id der Station, doppelte Zustellungen schaden also nicht.
  • Live-Pfad. live-Frames (bis 60 Hz pro Station) gehen in den LiveHub im Speicher und von dort direkt an die WebSocket-Clients. Sie werden auĂźerdem einmal pro Sekunde gespeichert, bis die vollständige Aufzeichnung von der Station ankommt und sie ersetzt.
  • Datenbank migriert sich selbst. Die Datenbank nestrisltm wird automatisch angelegt, und Alembic-Migrationen laufen bei jedem Start.
  • Events bestimmen die Ansicht. Jedes Event hat ein Zeitfenster, und genau ein Event ist aktiv. Highscore, Turnierbaum und Overlays zeigen immer das aktive Event.
  • Sicherheitsmodell. Die Admin-Oberfläche braucht ein Login, und jede schreibende API braucht ein Token mit passendem Scope (admin, players:write, games:write, stations, scenes, terminal). Overlays und Anzeigen sind nur lesend und im LAN offen.

Frontend. Admin-Oberfläche und Overlays sind Svelte-5-Apps. Ein gemeinsames Paket zeichnet NES-Spielfelder und dekodiert NGF-Aufzeichnungen. Dasselbe Paket nutzt auch das Spieler-Terminal.

nestris-core (Erkennungs-Engine und Station)

nestris-core ist ein Rust-Workspace. Es ist eine hochperformante Portierung der ursprĂĽnglichen Python-Erkennungs-Engine, mit ihr drahtkompatibel. Die Engine nutzt klassische Bildverarbeitung, kein Machine Learning:

flowchart LR
    SRC["<span style='color:#f8fafc'>Videoquelle<br/>Capture-Karte · Datei · Stream</span>"]:::hw --> FF["<span style='color:#111111'>ffmpeg<br/>dekodieren → 1280×720</span>"]:::core
    FF --> LOCK["<span style='color:#111111'>Geometrie-Lock<br/>Spielfeld + Beschriftungsanker<br/>RANSAC-Homographie</span>"]:::core
    LOCK --> WARP["<span style='color:#111111'>Entzerren auf kanonisches<br/>NES-Bild 256Ă—240</span>"]:::core
    WARP --> REC["<span style='color:#111111'>Erkennung<br/>Score · Lines · Level · Next ·<br/>Spielfeld · Teilestatistik</span>"]:::core
    REC --> FUS["<span style='color:#111111'>Zustandsfusion<br/>Plausibilität · Ereignisse</span>"]:::core
    FUS --> STATS["<span style='color:#111111'>Statistiken<br/>Tetris-Rate · Burn · Drought · Pace</span>"]:::core
    STATS --> SINK["<span style='color:#111111'>Ausgaben</span>"]:::core
    SINK --> J["<span style='color:#ffffff'>JSONL / NDJSON /<br/>WebSocket</span>"]:::ext
    SINK --> NGF["<span style='color:#ffffff'>NGF-Aufzeichnung<br/>.ngf.gz</span>"]:::ext
    SINK --> MQTT["<span style='color:#ffffff'>MQTT<br/>(nur Station)</span>"]:::ext

    classDef core fill:#22d3ee,stroke:#0e7490,color:#111,stroke-width:2px
    classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px
    classDef hw fill:#1f2937,stroke:#94a3b8,color:#f8fafc,stroke-dasharray:4 3

Der Geometrie-Lock ist ein kleiner Zustandsautomat. Er findet das Spielfeld selbstständig und rechnet im Hintergrund neu, wenn das Bild wandert:

stateDiagram-v2
    direction LR
    [*] --> UNLOCKED
    UNLOCKED --> ACQUIRING: Kandidat gefunden
    ACQUIRING --> LOCKED: Homographie bestätigt
    ACQUIRING --> UNLOCKED: verworfen
    LOCKED --> DRIFT: Bild verschoben
    DRIFT --> LOCKED: neu berechnet
    DRIFT --> LOST: keine Lösung
    LOST --> ACQUIRING: erneut suchen

Crate-Struktur

flowchart BT
    V["<span style='color:#111111'>nestris-vision<br/><small>CV-Grundfunktionen, kein I/O</small></span>"]:::core
    E["<span style='color:#111111'>nestris-engine<br/><small>Erkennung, Fusion, Statistik, Integrität</small></span>"]:::core
    N["<span style='color:#111111'>nestris-ngf<br/><small>NGF-Codec, Recorder, Replay</small></span>"]:::core
    H["<span style='color:#111111'>nestris-host<br/><small>ffmpeg-Capture, Ausgaben</small></span>"]:::core
    GC["<span style='color:#111111'>nestris-gui-core</span>"]:::core
    CLI["<span style='color:#111111'>nestris-cli<br/><small>Programm nestris</small></span>"]:::core
    GUI["<span style='color:#111111'>nestris-gui<br/><small>egui-Desktop</small></span>"]:::core
    QT["<span style='color:#111111'>nestris-qt-gui<br/><small>Qt 6 / QML</small></span>"]:::core
    WASM["<span style='color:#111111'>nestris-wasm<br/><small>Browser-GUI</small></span>"]:::core
    STN["<span style='color:#111111'>nestris-station<br/><small>Turnier-Dienst</small></span>"]:::core

    E --> V
    N --> E
    H --> N
    GC --> H
    CLI --> H
    GUI --> GC
    QT --> GC
    WASM --> N
    STN --> H

    classDef core fill:#22d3ee,stroke:#0e7490,color:#111,stroke-width:2px

nestris-station ist der Dienst ohne Bildschirm, der auf jeder Turnierstation läuft. Die Station ist ein kleiner Debian-PC mit USB-Capture-Stick und RFID-Leser:

  • Sie ordnet jedes Spiel der Karte am Leser zu.
  • Sie erkennt den Select-Score-Trick (+10 000 Punkte) und prĂĽft jedes Ergebnis.
  • Sie veröffentlicht Live-Zustand und Ergebnisse ĂĽber MQTT. Wichtige Nachrichten bleiben im Spool, bis der Broker sie bestätigt.
  • Sie zeichnet jedes Spiel als .ngf.gz auf und lädt es zu NestrisLTM hoch.
  • Sie läuft als systemd-Dienst mit Watchdog, startet die Erfassung mit Backoff neu und verbindet Leser und Broker selbstständig wieder.

nestris-terminal (Anmelde-Kiosk)

Das Terminal greift nie auf die Datenbank zu. Es ist ein Client der REST-API von NestrisLTM. Das Token bleibt in einem lokalen Bridge-Prozess, die Touch-Oberfläche bekommt es nie zu sehen.

flowchart LR
    subgraph PC["Touch-PC"]
        direction TB
        KIOSK["<span style='color:#111111'>Kiosk-Fenster<br/>PySide6 + QWebEngine<br/>Vollbild</span>"]:::term
        UI["<span style='color:#111111'>Svelte-Touch-Oberfläche</span>"]:::term
        subgraph BRIDGE["Lokale Bridge · FastAPI 127.0.0.1:7991"]
            direction TB
            PX["<span style='color:#111111'>/api/* Proxy</span>"]:::term
            LOC["<span style='color:#111111'>/local/* Karte schreiben · Admin</span>"]:::term
            WSB["<span style='color:#111111'>/ws Ereignisse fĂĽr die UI</span>"]:::term
            DRV["<span style='color:#111111'>RFID-Treiber<br/>(seriell / simuliert)</span>"]:::term
            CL["<span style='color:#111111'>Host-Client<br/>Bearer-Token</span>"]:::term
        end
        KIOSK --> UI
        UI <--> PX & LOC & WSB
        PX --> CL
        LOC --> DRV
        DRV --> WSB
    end
    RD["<span style='color:#111111'>RFID-Leser</span>"]:::rfid <-- "USB-Seriell · Protokoll v2" --> DRV
    CL -- "HTTP · /api/terminal/v1" --> LTM["<span style='color:#111111'>NestrisLTM :7990</span>"]:::ltm

    classDef ltm fill:#f5b800,stroke:#7a5c00,color:#111,stroke-width:2px
    classDef term fill:#a78bfa,stroke:#6d28d9,color:#111,stroke-width:2px
    classDef rfid fill:#f472b6,stroke:#be185d,color:#111,stroke-width:2px

nestris-rfid-reader (Firmware)

Der Leser ist bewusst einfach gehalten. Er hat kein WLAN und spricht nur USB-Seriell. Er meldet Kartenwechsel in rund 300 ms, zeigt Texte des Hosts am OLED und schreibt Namen sicher auf Karten (schreiben, zurĂĽcklesen, prĂĽfen).

flowchart LR
    CARD["<span style='color:#f8fafc'>MIFARE Classic<br/>Spielerkarte</span>"]:::hw -. "13,56 MHz" .-> RC["<span style='color:#111111'>RC522<br/>(SPI)</span>"]:::rfid
    subgraph ESP["ESP32 DevKit"]
        direction TB
        FW["<span style='color:#111111'>Firmware<br/>Karten-Tracker · Protokoll v2 ·<br/>Watchdog · NVS-Einstellungen</span>"]:::rfid
    end
    RC --> FW
    FW --> OLED["<span style='color:#111111'>SSD1306-OLED<br/>(I²C) 128×32 / 128×64</span>"]:::rfid
    FW <-- "USB-Seriell 115200 · JSON-Zeilen" --> HOSTAPP["<span style='color:#ffffff'>nestris-station oder<br/>nestris-terminal</span>"]:::ext

    classDef rfid fill:#f472b6,stroke:#be185d,color:#111,stroke-width:2px
    classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px
    classDef hw fill:#1f2937,stroke:#94a3b8,color:#f8fafc,stroke-dasharray:4 3

Technologie-Stack

Ebene NestrisLTM nestris-core nestris-terminal nestris-rfid-reader
Sprache Python 3.13 Rust (Edition 2024) Python 3.13 C++ (Arduino)
Laufzeit / Framework FastAPI, SQLAlchemy, Alembic, aiomqtt, PySide6 ffmpeg, egui, Qt 6, wasm-bindgen FastAPI, httpx, pyserial, PySide6 PlatformIO, ESP32-Arduino-Core
Oberfläche Svelte 5 egui / QML / TypeScript + wasm Svelte 5 SSD1306-OLED
Speicher PostgreSQL 14+ NGF-Dateien, Spool auf Platte TOML-Konfiguration ESP32-NVS
Paketierung PyInstaller + Inno Setup .deb, ZIP-Bundles, AppImage, .app PyInstaller + Inno Setup .bin-Images
CI / Release GitHub Actions, Ed25519-signiert GitHub Actions, Ed25519-signiert GitHub Actions, Ed25519-signiert GitHub Actions, Ed25519-signiert