nestris-rfid-reader Firmware für den Kartenleser¶
nestris-rfid-reader ist die Firmware des selbstgebauten Retroverse-Kartenlesers. Er steht an jeder Station und am Anmelde-Terminal und hat drei Aufgaben:
- Karten sofort melden. Er sendet
present- undremoved-Ereignisse in rund 300 ms. - Den Text des Hosts anzeigen. Das OLED zeigt den Nickname und eine Zeile wie „Platz 3 · 159.867“.
- 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
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 |