MQTT contract¶
Stations publish below <topic_prefix>/<station.id>/, for example retroverse/nestris/station-1/. Payloads are compact JSON. Timestamps are RFC 3339 UTC with milliseconds. nestris-core owns this contract (docs/STATION.md in the repository).
| Topic | QoS / retain | When | Direction |
|---|---|---|---|
status |
1, retained | on change and every status_interval_s; last will = offline |
station → host |
player |
1, retained | card placed or removed, reader connected or lost | station → host |
live |
0 | on change, up to live_max_hz (60) |
station → host |
event/game_start |
1, durable | a game was recognised | station → host |
event/cheat |
1, durable | a cheat was confirmed | station → host |
event/game_end |
1, durable | a game ended, with the result | station → host |
cmd |
1 | commands forwarded to the RFID reader | host → station |
Durable delivery
Durable messages are written to the station's on-disk spool before they are published, and deleted only after the broker's PUBACK. They survive network outages and restarts of the broker or station. Delivery is at least once, and the host deduplicates by game_id and 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 (in memory)</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 reader</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
Payloads¶
{"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(reader needs new firmware),disabled- On shutdown and as last will:
{"state":"offline","station":"station-1","ts":…}
name is null for a blank card.
{"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 contains 20 rows of 10 cell IDs, top row first: 0 empty, 1 white, 2/3 the level's two accent colours. It is null outside a game, including while paused, because the console hides the board during a pause. With the board included, the stream is about 18 KB/s per 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 is the running total for the game; count is this detection.
{"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: falsemeans a validation error was found. See the validation codes.
# text on the reader's display while this card is on it
mosquitto_pub -t retroverse/nestris/station-1/cmd \
-m '{"type":"show","uid":"04A1B2C3","lines":["Erv","Bestwert 159.867"]}'
# write a name onto the card on the reader
mosquitto_pub -t retroverse/nestris/station-1/cmd \
-m '{"type":"write","id":1,"name":"Erv","timeout_ms":15000}'
# reader display settings (stored in the reader)
mosquitto_pub -t retroverse/nestris/station-1/cmd \
-m '{"type":"config","display":"128x64"}'
Only show, write and config are accepted.
Cheat detection¶
Legal score gains in NES Tetris come from line clears, worth 40 / 100 / 300 / 1200 × (level + 1), plus a few soft-drop points. The Select trick adds a flat 10 000. Every settled score change is explained as:
and k is counted as cheat inputs. The detector is built to never flag a clean game:
- A value counts only after it has been stable for several frames.
- Score and lines changes are paired across frames.
- Level-ups and a level digit misread by one are tolerated.
- A detection is held back for 1.5 s and dropped if the score falls back, because a misread ten-thousands digit is also exactly ±10 000.
- Anything that is neither legal nor whole multiples of 10 000 is reported as an anomaly, never as a cheat.