Skip to content

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, reconnecting
  • rfid: ok, offline, outdated (reader needs new firmware), disabled
  • On shutdown and as last will: {"state":"offline","station":"station-1","ts":…}
{"present":true,"player":{"uid":"A1B2C3D4","name":"Erv"},"rfid":"ok","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":{"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 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, shutdown
  • valid: false means 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:

ΔSCORE = clear points for ΔLINES  +  k × 10 000  +  soft-drop

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.

Watching the bus

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