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,reconnectingrfid:ok,offline,outdated(Leser braucht neue Firmware),disabled- Beim Herunterfahren und als Last Will:
{"state":"offline","station":"station-1","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":{…},
"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,shutdownvalid: falseheiĂź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:
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.