Zum Inhalt

nestris-rfid-reader Firmware für den Kartenleser

Latest release CI Board Protocol Preview

nestris-rfid-reader ist die Firmware des selbstgebauten Retroverse-Kartenlesers. Er steht an jeder Station und am Anmelde-Terminal und hat drei Aufgaben:

  1. Karten sofort melden. Er sendet present- und removed-Ereignisse in rund 300 ms.
  2. Den Text des Hosts anzeigen. Das OLED zeigt den Nickname und eine Zeile wie „Platz 3 · 159.867“.
  3. Karten sicher beschreiben. Er schreibt den Nickname, liest ihn zurück und prüft ihn per CRC.

Der Leser hat bewusst kein WLAN. Er spricht nur JSON-Zeilen über USB-Seriell. Das hält ihn einfach, robust und leicht testbar.

Repository Neueste Version laden

Preview-Status

Die Firmware für Protokoll v2 ist vollständig und durch native Unit-Tests abgedeckt. Die Erprobung auf echter Leser-Hardware läuft noch. Stationen und Terminals weisen Leser ab, auf denen noch die alte v1-Firmware läuft.

Hardware

Teil Hinweise
ESP32 DevKit (ESP32-WROOM-32) Board esp32dev, USB-Brücke CP2102 oder CH340
RC522-RFID-Modul SPI, 13,56 MHz
SSD1306-OLED I²C, 128×32 oder 128×64, Adresse 0x3C (0x3D wird ebenfalls probiert), optional
Karten MIFARE Classic 1K / 4K

Verdrahtung

flowchart LR
    RC["<span style='color:#111111'>RC522<br/>RFID-Modul</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 oder 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 nicht verbunden
3,3 V / GND 3,3 V / GND

Note

Die Pinbelegung ist dieselbe wie beim Leser der ersten Generation. Vorhandene Leser brauchen also nur neue Firmware.

Verhalten

stateDiagram-v2
    direction LR
    [*] --> LEER
    LEER --> KARTE: Karte erkannt / sendet card present
    KARTE --> KARTE: gleiche UID (entprellt)
    KARTE --> LEER: 300 ms weg / sendet card removed
OLED-Anzeige Wann
RETROVERSE / Reader x.y.z Start
Karte auflegen (animiert) Leerlauf
Name + Zeile vom Host Karte am Leser
Neue Karte / am Terminal anmelden Leere Karte
Karte defekt · Karte nicht unterstützt Beschädigte oder nicht unterstützte Karte
Schreibe … / Karte liegen lassen → Gespeichert / Fehler Karte wird beschrieben
PC getrennt 10 s kein Host
Leser-Fehler RC522 antwortet nicht

Die Texte sind standardmäßig deutsch, Englisch ist einstellbar. Ein 128×64-Display zeigt zusätzlich eine Statusleiste und bis zu vier Zeilen. Der Einbrennschutz verschiebt die Leerlaufanzeige jede Minute und dimmt sie nach 10 Minuten. Ein 5-s-Watchdog und eine RC522-Zustandsprüfung initialisieren die Hardware neu, wenn sie nicht mehr reagiert.

Protokoll v2 auf einen Blick

USB-Seriell mit 115200 Baud, 8N1, ein JSON-Objekt pro Zeile (höchstens 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}

Vollständige Nachrichtenliste, Fehler und Regeln für Hosts: Leser-Protokoll. Aufbau der Karte: Kartenformat.

Flashen

# Neuer Leser oder Umstieg von der Firmware der ersten Generation: komplettes Factory-Image (löscht Einstellungen)
esptool --chip esp32 --port COM5 --baud 921600 write_flash 0x0 nestris-rfid-reader-<v>-esp32dev.bin

# Update: nur das App-Image (Display- und Spracheinstellungen bleiben)
esptool --chip esp32 --port COM5 --baud 921600 write_flash 0x10000 nestris-rfid-reader-<v>-esp32dev-app.bin
pio test -e native                    # Unit-Tests am PC
pio run -e esp32dev -t upload         # App bauen + flashen
uv run tools/reader_cli.py COM5       # interaktiv: hello, write, show, config, rohes JSON

Geplant

Geplant Die Leser-Firmware direkt vom Terminal oder von der Station aus zu aktualisieren ist geplant, aber noch nicht verfügbar.

Release-Dateien

Datei Zweck
nestris-rfid-reader-<v>-esp32dev.bin Factory-Image für Offset 0x0 (neue Leser; löscht Einstellungen)
nestris-rfid-reader-<v>-esp32dev-app.bin App-Image für Offset 0x10000 (Updates; Einstellungen bleiben)
nestris-rfid-reader-<v>-manifest.json Maschinenlesbares Release-Manifest
SHA256SUMS.txt / .sig Prüfsummen und Ed25519-Signatur