Zum Inhalt

Leser-Protokoll v2

Leser und Host (Station oder Terminal) tauschen ein JSON-Objekt pro Zeile über USB-Seriell aus.

Eigenschaft Wert
Verbindung USB-Seriell, 115200 Baud, 8N1
Rahmen ein JSON-Objekt pro Zeile, höchstens 512 Bytes; Zeilen ohne JSON werden ignoriert
Version proto: 2 im hello; Hosts lehnen andere Versionen ab
Start Öffnen des Ports setzt den ESP32 zurück, hello folgt nach rund 2 s

Leser → Host

Typ Wann Inhalt
hello beim Start und auf Anfrage proto, fw, build, board, serial (MAC), display, lang, reader (ok/missing), chip, card
card sofort bei jeder Änderung state (present/removed), uid, name, format
status Herzschlag alle 2 s card, reader, uptime_s, host
result Antwort auf einen Befehl wiederholt id, ok, bei Fehler error + detail
log Diagnose level (debug, info, warn, error), Meldung

format ist einer der Werte retroverse, legacy, blank, corrupt, unreadable oder unsupported. Siehe Kartenformat.

{"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 → Leser

Befehl Zweck Beispiel
hello Identifikation anfordern {"type":"hello","id":1}
ping Lebenszeichen (alle 3 s) {"type":"ping","id":2}
show Text am OLED, solange diese Karte aufliegt (optional ttl_ms) {"type":"show","id":9,"uid":"04A1B2C3","lines":["Erv","Bestwert 159.867"]}
write Namen auf die Karte schreiben (optional nur auf Karte uid) {"type":"write","id":7,"name":"Erv","uid":"04A1B2C3","timeout_ms":15000}
config Einstellungen im NVS (überstehen Updates) {"type":"config","id":4,"display":"128x64","lang":"en"}
cancel laufendes Schreiben abbrechen {"type":"cancel","id":5}
reboot Leser neu starten {"type":"reboot","id":6}

config-Optionen: display (128x32, 128x64, none) · lang (de, en) · removed_after_ms (150–2000, Standard 300) · brightness (0–255, Standard 200) · flip (um 180° drehen) · debug (Debug-Logzeilen senden).

Fehlercodes: bad_request, unknown_type, busy, timeout, wrong_card, no_card, unsupported_card, auth, write, verify, cancelled, line_too_long, bad_json.

Verhalten des Hosts

sequenceDiagram
    participant H as Host (Station / Terminal)
    participant R as Leser

    H->>R: Port öffnen (setzt ESP32 zurück)
    R-->>H: hello (proto 2)
    alt proto ≠ 2
        H-->>H: ablehnen: Leser-Firmware veraltet
    end
    loop alle 3 s
        H->>R: ping
        R-->>H: result ok
    end
    R-->>H: status (alle 2 s)
    R-->>H: card present / removed (sofort)
    H->>R: write {name, timeout_ms}
    Note over R: schreiben → zurücklesen → CRC prüfen
    R-->>H: result ok / Fehler
    Note over H: 6 s keine Zeile → Port neu öffnen
  • Alle 3 s ein ping senden. Nach 6 s Stille gilt der Leser als verloren, und der Port wird neu geöffnet.
  • Für write das timeout_ms des Lesers plus 3 s als eigenes Timeout nehmen.
  • Spieler immer über die UID der Karte erkennen, nie über den Namen auf der Karte.