Skip to content

Reader protocol v2

The reader and its host (station or terminal) exchange one JSON object per line over USB serial.

Property Value
Link USB serial, 115200 baud, 8N1
Framing one JSON object per line, at most 512 bytes; lines that are not JSON are ignored
Version proto: 2 in hello; hosts refuse other versions
Start-up opening the port resets the ESP32, and hello follows within about 2 s

Reader → host

Type When Content
hello boot and on request proto, fw, build, board, serial (MAC), display, lang, reader (ok/missing), chip, card
card immediately on every change state (present/removed), uid, name, format
status heartbeat every 2 s card, reader, uptime_s, host
result answer to a command echoes id, ok, on failure error + detail
log diagnostics level (debug, info, warn, error), message

format is one of retroverse, legacy, blank, corrupt, unreadable or unsupported. See the card format.

{"type":"hello","proto":2,"fw":"1.0.0","build":"2026-10-04T12:00:00Z","board":"esp32dev","serial":"A4CF12B3C4D5","display":"128x32","lang":"de","reader":"ok","chip":"0x92","card":null,"id":3}
{"type":"card","state":"present","uid":"04A1B2C3","name":"Erv","format":"retroverse"}
{"type":"card","state":"removed","uid":"04A1B2C3"}
{"type":"status","card":{"uid":"04A1B2C3","name":"Erv","format":"retroverse"},"reader":"ok","uptime_s":3711,"host":true}
{"type":"result","id":8,"ok":false,"error":"timeout","detail":"no card within 15000 ms"}

Host → reader

Command Purpose Example
hello request identification {"type":"hello","id":1}
ping keep-alive (every 3 s) {"type":"ping","id":2}
show text on the OLED while this card is on the reader (optional ttl_ms) {"type":"show","id":9,"uid":"04A1B2C3","lines":["Erv","Bestwert 159.867"]}
write write a name to the card (optionally only to card uid) {"type":"write","id":7,"name":"Erv","uid":"04A1B2C3","timeout_ms":15000}
config settings stored in NVS (survive updates) {"type":"config","id":4,"display":"128x64","lang":"en"}
cancel abort a pending write {"type":"cancel","id":5}
reboot restart the reader {"type":"reboot","id":6}

config options: display (128x32, 128x64, none) · lang (de, en) · removed_after_ms (150–2000, default 300) · brightness (0–255, default 200) · flip (rotate 180°) · debug (send debug log lines).

Error codes: bad_request, unknown_type, busy, timeout, wrong_card, no_card, unsupported_card, auth, write, verify, cancelled, line_too_long, bad_json.

Host behaviour

sequenceDiagram
    participant H as Host (station / terminal)
    participant R as Reader

    H->>R: open port (resets ESP32)
    R-->>H: hello (proto 2)
    alt proto ≠ 2
        H-->>H: refuse: reader firmware outdated
    end
    loop every 3 s
        H->>R: ping
        R-->>H: result ok
    end
    R-->>H: status (every 2 s)
    R-->>H: card present / removed (immediately)
    H->>R: write {name, timeout_ms}
    Note over R: write → read back → verify CRC
    R-->>H: result ok / error
    Note over H: no line for 6 s → reopen the port
  • Send ping every 3 s. Treat the reader as lost after 6 s of silence and reopen the port.
  • For write, use the reader's timeout_ms plus 3 s as the host-side timeout.
  • Identify a player by the card UID, never by the name on the card.