RFID-Zeiterfassung mit ESP32: vom Kartenleser zur Web-App

Angefangen hat es mit einer einfachen Frage: Ein ESP32, ein roter NFC-Leser, ein kleines Display und ein Buzzer lagen auf dem Tisch. Kann man damit eine Zeiterfassung bauen, wie man sie aus dem Betrieb kennt? Karte an das Terminal, es piept, „Hallo Anna – Kommen 07:58“, und im Browser sieht die Verwaltung, wer da ist.

Es geht, und der erste Stand war an einem Feiertag fertig. Dieser Beitrag erzählt nicht jeden Schritt nach (das macht das Projekt mit der Schritt-für-Schritt-Anleitung), sondern sammelt die Dinge, die ich dabei gelernt habe.

1. Der Fehler sitzt oft nicht in der Software

Das erste Ergebnis auf dem Display war: PN532 FEHLER. Das LCD lief, der NFC-Leser schwieg. Software, Bibliothek und Kabel waren schnell im Verdacht. Die Ursache war ein winziger DIP-Schalter auf dem Modul. Er legt fest, ob der Chip HSU, I2C oder SPI spricht, und es war der falsche Hebel umgelegt. Statt I2C stand SPI.

ModusI0I1
HSU00
I2C10
SPI01

Zwei Dinge haben geholfen. Erstens ein I2C-Scan beim Start: Er zeigt, welche Geräte am Bus antworten. Fehlt die Adresse 0x24 des PN532, braucht man den Code gar nicht erst zu durchsuchen. Zweitens ein vergrößertes Foto des Schalters. Und der Chip liest den Schalter nur beim Einschalten, also Strom ganz weg, ein Reset reicht nicht.

Merksatz: Erst messen, wer am Bus antwortet, dann Code lesen. Eine Zeile Diagnose spart eine Stunde Raten.

2. Nicht jede Karte ist eine RFID-Karte für diesen Leser

Die weiße Karte und der blaue Anhänger aus dem Set gingen sofort. Der Firmenausweis nicht, ein alter Schlüsselanhänger nur halb. Der Grund ist die Frequenz:

KarteFrequenzPN532
MIFARE Classic, NTAG, DESFire13,56 MHzja
EM4102 / EM4200, Hitag, HID Prox125 kHznein
LEGIC prime, HID iCLASS13,56 MHznein (eigene Protokolle)
Smartphone mit NFC13,56 MHzja, aber jedes Mal eine andere UID

Zeiterfassungen in Firmen nutzen häufig 125 kHz (EM, Hitag) oder LEGIC. Dass der Leser einen Ausweis nicht erkennt, heißt also nicht, dass etwas kaputt ist. Das Handy wird zwar erkannt, sendet aber aus Datenschutzgründen bei jedem Auflegen eine zufällige Kennung. Als Schlüssel taugt es dadurch nicht.

Interessant war auch ein Blick in die Karten. Eine MIFARE Classic 1K hat 16 Sektoren, jeder mit einem eigenen Schlüssel. Neue Karten nutzen den Standardschlüssel FF FF FF FF FF FF, alle Sektoren waren leer. Der alte Anhänger dagegen hatte in allen Sektoren fremde Schlüssel. Lesbar war nur die Seriennummer (UID).

Die UID ist kein Geheimnis. Sie lässt sich auslesen und mit passenden Karten nachbilden. Für eine Zeiterfassung ist das vertretbar, denn Manipulation fällt auf und wird korrigiert. Für eine Tür reicht die UID allein nicht. Fremde Karten wie den eigenen Firmenausweis kopiert man nicht.

3. Das Terminal sollte dumm sein

Die wichtigste Entscheidung im Aufbau: Das Terminal kennt keine Namen und rechnet nichts. Es meldet nur „Karte X wurde aufgelegt“ und zeigt an, was der Server antwortet. Kommen oder Gehen, wem die Karte gehört, ob sie gesperrt ist, wie viele Stunden es heute sind: Das entscheidet alles der Server.

POST /api/buchung.php
X-Terminal-Token: …

{"uid":"DF1CA61D", "art":"auto", "ref":"a1b2c3-17"}
-> {"status":"ok", "name":"Anna", "art":"Kommen", "zeit":"07:58"}

Dadurch kann man eine verlorene Karte im Browser sperren oder einen Anhänger einer anderen Person zuordnen, ohne das Gerät anzufassen. Neue Karten lernt man an, indem man sie einmal auflegt. Danach tauchen sie in der Weboberfläche als „unbekannt“ auf und werden mit einem Klick zugeordnet.

4. Offline ist der Normalfall, nicht die Ausnahme

WLAN fällt aus, der Router startet neu, der Server wird aktualisiert. Wer in genau dieser Minute kommt, darf trotzdem nicht verloren gehen. Deshalb speichert das Terminal jede Buchung, die nicht durchkommt, mit Uhrzeit in seinem Flash und sendet sie später nach. Dabei gibt es zwei Fallen:

  • Die Uhrzeit. Ohne Netz gibt es kein NTP. Hat das Terminal noch nie eine Zeit bekommen, speichert es lieber nichts, statt mit „1. Januar 1970“ zu buchen.
  • Doppelte Buchungen. Antwortet der Server zu langsam, sendet das Terminal erneut, obwohl die erste Buchung schon angekommen ist. Abhilfe ist eine eindeutige Kennung ref je Buchung. Kommt dieselbe zweimal an, speichert der Server sie nur einmal (Idempotenz).

5. Arbeitszeit ist Regelwerk

Den meisten Code hat nicht der Kartenleser gebraucht, sondern die Frage, was eigentlich als Arbeitszeit zählt:

  • Eine Pause wird nicht bezahlt, ein Dienstgang schon. Beides ist technisch ein „Gehen“, nur mit anderem Grund.
  • Nach § 4 Arbeitszeitgesetz gehören zu mehr als 6 Stunden 30 Minuten Pause, zu mehr als 9 Stunden 45 Minuten. Wurde sie nicht gebucht, wird sie abgezogen.
  • Feiertage sind Ländersache. Thüringen hat zum Beispiel den Weltkindertag (20.9.) und den Reformationstag. Ostern und alles, was daran hängt, berechnet die Gaußsche Osterformel.
  • Urlaub zählt in Arbeitstagen. Ein Antrag von Freitag bis Montag sind zwei Tage, nicht vier.
  • Korrekturen braucht man immer: Karte vergessen, Akku leer. Wichtig ist, dass nie gelöscht wird. Eine stornierte Buchung bleibt mit Grund, Name und Uhrzeit sichtbar.

Diese Regeln sind mit kleinen Tests abgesichert. Ein Test hat mich dabei selbst korrigiert: Ich hatte das Ergebnis falsch erwartet, der Code hatte recht.

6. Eine Demo, die sich selbst aufräumt

Zum Zeigen gibt es unter zeit.micha-it.de eine Demo mit erfundenen Mitarbeitern, Buchungen seit Januar, Urlauben und offenen Anträgen. Es gibt einen Zugang für die Verwaltung und einen für die Mitarbeitersicht. Damit sich die Testenden nicht gegenseitig im Weg stehen:

  • Jede volle Stunde setzt ein Cron-Job alles auf den Ausgangszustand zurück. Ein Banner zeigt, wann.
  • Die gemeinsamen Demo-Zugänge können ihr Passwort nicht ändern, und der Demo-Admin kann den Demo-Mitarbeiter nicht deaktivieren.
  • Eine offene Sitzung übersteht den Reset, weil sie über den Benutzernamen neu geladen wird und nicht über die (neue) Datenbank-ID.

Fazit

Die Hardware lief schnell. Die eigentliche Arbeit steckte in drei Fragen: Wie bleibt das Terminal einfach? Was passiert ohne Netz? Und was ist eigentlich Arbeitszeit? Wer selbst so etwas baut, sollte mit genau diesen Fragen anfangen, nicht mit dem Kartenleser.

Wie es Schritt für Schritt geht, von der Verkabelung über die Schnittstelle bis zum Betrieb im eigenen Container, steht im Projekt „Zeiterfassung mit RFID, ESP32 und PHP“.