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
pingsenden. Nach 6 s Stille gilt der Leser als verloren, und der Port wird neu geöffnet. - Für
writedastimeout_msdes Lesers plus 3 s als eigenes Timeout nehmen. - Spieler immer über die UID der Karte erkennen, nie über den Namen auf der Karte.