Skip to content

nestris-rfid-reader Player-card reader firmware

Latest release CI Board Protocol Preview

nestris-rfid-reader is the firmware for the self-built Retroverse card reader. It sits at every station and at the registration terminal, and it has three jobs:

  1. Report cards instantly. It sends present and removed events within about 300 ms.
  2. Show the host's text. The OLED displays the nickname and a line such as "Platz 3 · 159.867".
  3. Write cards safely. It writes the nickname, reads it back and verifies it with a CRC.

The reader has no Wi-Fi on purpose. It talks only JSON lines over USB serial, which keeps it simple, robust and easy to test.

Repository Download latest

Preview status

Protocol v2 firmware is feature-complete and covered by native unit tests. Validation on real reader hardware is still in progress. Stations and terminals refuse readers that still run the old v1 firmware.

Hardware

Part Notes
ESP32 DevKit (ESP32-WROOM-32) Board esp32dev, CP2102 or CH340 USB bridge
RC522 RFID module SPI, 13.56 MHz
SSD1306 OLED I²C, 128×32 or 128×64, address 0x3C (0x3D is probed too), optional
Cards MIFARE Classic 1K / 4K

Wiring

flowchart LR
    RC["<span style='color:#111111'>RC522<br/>RFID module</span>"]:::rfid -- "SPI<br/>SS → GPIO 5 · SCK → GPIO 18<br/>MOSI → GPIO 23 · MISO → GPIO 19<br/>RST → GPIO 4" --> ESP["<span style='color:#111111'>ESP32 DevKit</span>"]:::rfid
    OL["<span style='color:#111111'>SSD1306<br/>OLED</span>"]:::rfid -- "I²C<br/>SDA → GPIO 21 · SCL → GPIO 22" --> ESP
    PWR["<span style='color:#f8fafc'>3.3 V / GND</span>"]:::hw -.- RC & OL
    ESP -- "USB · 115200 8N1" --> HOST["<span style='color:#ffffff'>Station or terminal</span>"]:::ext

    classDef rfid fill:#f472b6,stroke:#be185d,color:#111,stroke-width:2px
    classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px
    classDef hw fill:#1f2937,stroke:#94a3b8,color:#f8fafc,stroke-dasharray:4 3
RC522 ESP32 SSD1306 ESP32
SDA (SS) GPIO 5 SDA GPIO 21
SCK GPIO 18 SCL GPIO 22
MOSI GPIO 23 VCC 3.3 V
MISO GPIO 19 GND GND
RST GPIO 4
IRQ not connected
3.3 V / GND 3.3 V / GND

Note

The pin assignment is the same as in the first-generation reader, so existing readers only need new firmware.

Behaviour

stateDiagram-v2
    direction LR
    [*] --> EMPTY
    EMPTY --> PRESENT: card detected / send card present
    PRESENT --> PRESENT: same UID (debounced)
    PRESENT --> EMPTY: absent for 300 ms / send card removed
OLED screen When
RETROVERSE / Reader x.y.z Boot
Karte auflegen (animated) Idle
Name + line from the host Card on the reader
Neue Karte / am Terminal anmelden Blank card
Karte defekt · Karte nicht unterstützt Corrupt or unsupported card
Schreibe … / Karte liegen lassen → Gespeichert / Fehler Writing a card
PC getrennt No host for 10 s
Leser-Fehler RC522 not answering

German texts are the default and English is configurable. A 128×64 display adds a status bar and up to four lines. Burn-in protection moves the idle screen every minute and dims it after 10 minutes. A 5 s watchdog and an RC522 health check re-initialise the hardware if it stops responding.

Protocol v2 at a glance

USB serial at 115200 baud, 8N1, one JSON object per line (≤ 512 bytes).

{"type":"hello","proto":2,"fw":"1.0.0","board":"esp32dev","display":"128x32","lang":"de","reader":"ok","card":null}
{"type":"card","state":"present","uid":"04A1B2C3","name":"Erv","format":"retroverse"}
{"type":"show","id":9,"uid":"04A1B2C3","lines":["Erv","Bestwert 159.867"]}
{"type":"write","id":7,"name":"Erv","uid":"04A1B2C3","timeout_ms":15000}
{"type":"result","id":7,"ok":true}

Full message list, errors and host rules: Reader protocol. On-card layout: Card format.

Flashing

# New reader or upgrade from first-generation firmware: full factory image (erases settings)
esptool --chip esp32 --port COM5 --baud 921600 write_flash 0x0 nestris-rfid-reader-<v>-esp32dev.bin

# Update: app image only (keeps display/language settings)
esptool --chip esp32 --port COM5 --baud 921600 write_flash 0x10000 nestris-rfid-reader-<v>-esp32dev-app.bin
pio test -e native                    # unit tests on the PC
pio run -e esp32dev -t upload         # build + flash the app
uv run tools/reader_cli.py COM5       # interactive: hello, write, show, config, raw JSON

Planned

Planned Updating the reader firmware directly from the terminal or the station is planned and not available yet.

Release artifacts

File Purpose
nestris-rfid-reader-<v>-esp32dev.bin Factory image for offset 0x0 (new readers; erases settings)
nestris-rfid-reader-<v>-esp32dev-app.bin App image for offset 0x10000 (updates; keeps settings)
nestris-rfid-reader-<v>-manifest.json Machine-readable release manifest
SHA256SUMS.txt / .sig Checksums and Ed25519 signature