Zum Inhalt

MQTT-Schnittstelle

Stationen veröffentlichen unterhalb von <topic_prefix>/<station.id>/, zum Beispiel retroverse/nestris/station-1/. Die Nachrichten sind kompaktes JSON. Zeitstempel sind RFC 3339 in UTC mit Millisekunden. Eigentümer dieser Schnittstelle ist nestris-core (docs/STATION.md im Repository).

Topic QoS / retain Wann Richtung
status 1, retained bei Änderung und alle status_interval_s; Last Will = offline Station → Host
player 1, retained Karte aufgelegt oder abgenommen, Leser verbunden oder verloren Station → Host
live 0 bei Änderung, bis live_max_hz (60) Station → Host
event/game_start 1, ausfallsicher ein Spiel wurde erkannt Station → Host
event/cheat 1, ausfallsicher ein Cheat wurde bestätigt Station → Host
event/game_end 1, ausfallsicher ein Spiel ist zu Ende, mit Ergebnis Station → Host
cmd 1 Befehle, die an den RFID-Leser weitergereicht werden Host → Station

Ausfallsichere Zustellung

Ausfallsichere Nachrichten werden vor dem Senden in den Spool der Station auf der Platte geschrieben und erst gelöscht, wenn der Broker sie mit PUBACK bestätigt. Sie überstehen Netzausfälle und Neustarts von Broker oder Station. Die Zustellung erfolgt mindestens einmal, und der Host erkennt Duplikate über game_id und Topic.

flowchart LR
    subgraph ST["retroverse/nestris/station-1/"]
        direction TB
        s["<span style='color:#111111'>status</span>"]:::core
        p["<span style='color:#111111'>player</span>"]:::core
        l["<span style='color:#111111'>live</span>"]:::core
        e1["<span style='color:#111111'>event/game_start</span>"]:::core
        e2["<span style='color:#111111'>event/cheat</span>"]:::core
        e3["<span style='color:#111111'>event/game_end</span>"]:::core
        c["<span style='color:#111111'>cmd</span>"]:::ltm
    end
    s & p & l --> HUB["<span style='color:#111111'>LiveHub (im Speicher)</span>"]:::ltm
    e1 & e2 & e3 --> SP["<span style='color:#111111'>Spool → PostgreSQL</span>"]:::ltm
    LTM["<span style='color:#111111'>NestrisLTM</span>"]:::ltm --> c --> RD["<span style='color:#111111'>RFID-Leser</span>"]:::rfid

    classDef ltm fill:#f5b800,stroke:#7a5c00,color:#111,stroke-width:2px
    classDef core fill:#22d3ee,stroke:#0e7490,color:#111,stroke-width:2px
    classDef rfid fill:#f472b6,stroke:#be185d,color:#111,stroke-width:2px

Nachrichten

{"state":"online","station":"station-1","name":"Station 1","version":"0.2.0",
 "capture":"ok","capture_detail":"1280x720","lock":"locked","game_state":"in_game",
 "rfid":"ok","reader_fw":"1.0.0","reader_serial":"A4CF12B3C4D5",
 "game_id":"station-1-1790241008228","fps":60.0,"dropped_frames":0,
 "uptime_s":3605,"ts":"2026-09-24T09:10:08.228Z"}
  • capture: ok, opening, waiting_for_device, reconnecting
  • rfid: ok, offline, outdated (Leser braucht neue Firmware), disabled
  • Beim Herunterfahren und als Last Will: {"state":"offline","station":"station-1","ts":…}
{"present":true,"player":{"uid":"A1B2C3D4","name":"Erv"},"rfid":"ok","ts":"…"}

name ist null bei einer leeren Karte.

{"game_id":"station-1-1790241008228","player":{"uid":"A1B2C3D4","name":"Erv"},
 "game_state":"in_game","score":22800,"lines":4,"level":18,"next_piece":"I",
 "tetris_rate":1.0,"burn":0,"drought":3,"max_drought":9,"pps":0.9876,"pieces":12,
 "cheated":0,"confidence":0.95,
 "playfield":["0000000000","…","0000000110","2221103311"],"ts":"…"}

playfield enthält 20 Zeilen mit je 10 Zell-IDs, oberste Zeile zuerst: 0 leer, 1 weiß, 2/3 die zwei Akzentfarben des Levels. Außerhalb eines Spiels ist es null, auch während der Pause, weil die Konsole das Spielfeld in der Pause verbirgt. Mit Spielfeld braucht der Stream rund 18 KB/s pro Station.

{"game_id":"station-1-1790241008228","station":"station-1",
 "player":{"uid":"A1B2C3D4","name":"Erv"},"started_at":"…","start_level":18}
{"game_id":"station-1-1790241008228","station":"station-1","player":{…},
 "cheated":1,"count":1,"points":10000,"score_before":45600,"score_after":55612,
 "lines_delta":0,"ts":"…"}

cheated ist die laufende Summe im Spiel, count diese eine Erkennung.

{"schema":1,"game_id":"station-1-1790241008228","station":"station-1",
 "player":{"uid":"A1B2C3D4","name":"Erv"},
 "started_at":"…","ended_at":"…","duration_s":431.2,"active_seconds":402.9,
 "end_reason":"game_over","start_level":18,"end_level":21,
 "score":216560,"lines":134,"clears":{"single":31,"double":11,"triple":3,"tetris":18},
 "tetris_rate":0.5373,"burn":64,"max_drought":21,"pieces":527,"pps":1.31,
 "cheated":0,"cheat_points":0,"valid":true,
 "validation":{"issues":[],"metrics":{"frames":25876,"ingame_frames":24190,"mean_confidence":0.93}}}
  • end_reason: game_over, reset, signal_lost, shutdown
  • valid: false heiĂźt, dass ein PrĂĽffehler gefunden wurde. Siehe die PrĂĽfcodes.
# Text am Display des Lesers, solange diese Karte aufliegt
mosquitto_pub -t retroverse/nestris/station-1/cmd \
  -m '{"type":"show","uid":"04A1B2C3","lines":["Erv","Bestwert 159.867"]}'
# einen Namen auf die Karte am Leser schreiben
mosquitto_pub -t retroverse/nestris/station-1/cmd \
  -m '{"type":"write","id":1,"name":"Erv","timeout_ms":15000}'
# Display-Einstellungen des Lesers (im Leser gespeichert)
mosquitto_pub -t retroverse/nestris/station-1/cmd \
  -m '{"type":"config","display":"128x64"}'

Nur show, write und config werden angenommen.

Cheat-Erkennung

Legale Punkte gibt es in NES Tetris nur für abgeräumte Reihen, nämlich 40 / 100 / 300 / 1200 × (Level + 1), plus ein paar Punkte für Soft Drop. Der Select-Trick bringt pauschal 10 000. Jede stabile Score-Änderung wird zerlegt in:

ΔSCORE = Punkte für ΔLINES  +  k × 10 000  +  Soft Drop

und k zählt als Cheat-Eingaben. Der Detektor ist so gebaut, dass er nie ein sauberes Spiel markiert:

  • Ein Wert zählt erst, wenn er mehrere Frames lang stabil ist.
  • Ă„nderungen von Score und Lines werden ĂĽber Frames hinweg zusammengefĂĽhrt.
  • Level-Wechsel und eine um eins falsch gelesene Level-Ziffer werden toleriert.
  • Eine Erkennung wird 1,5 s zurĂĽckgehalten und verworfen, wenn der Score zurĂĽckfällt, denn eine falsch gelesene Zehntausender-Ziffer macht genau ±10 000 aus.
  • Was weder legal noch ein ganzes Vielfaches von 10 000 ist, wird als Anomalie gemeldet, nie als Cheat.

Den Bus beobachten

mosquitto_sub -v -t 'retroverse/nestris/#'