nestris-rfid-reader Player-card reader firmware¶
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:
- Report cards instantly. It sends
presentandremovedevents within about 300 ms. - Show the host's text. The OLED displays the nickname and a line such as "Platz 3 · 159.867".
- 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.
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
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 |