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 diegame_idder 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
nestrisltmwird 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.gzauf 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 |