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
pingevery 3 s. Treat the reader as lost after 6 s of silence and reopen the port. - For
write, use the reader'stimeout_msplus 3 s as the host-side timeout. - Identify a player by the card UID, never by the name on the card.