Karte an das Terminal halten, es piept, auf dem Display steht „Hallo Anna – Kommen 07:58“, und im Browser sieht die Verwaltung, wer da ist. In diesem Projekt baust du ein Zeiterfassungs-Terminal aus einem ESP32 und einem NFC-Leser und den Server dazu, mit Pausenregeln, Urlaubsanträgen und Jahresübersicht.
ca. 1–2 Tage Arduino- und PHP-Grundlagen ESP32 · PN532 · PHP 8.4 · MariaDB
Das brauchst du
Einen ESP32 (DevKit mit 38 Pins, USB) und ein Steckbrett mit Kabeln. Löten ist nicht nötig.
Ein PN532-NFC-Modul (13,56 MHz) mit DIP-Schalter für I2C/SPI, dazu MIFARE-Classic-Karten oder Schlüsselanhänger.
Ein LCD 1602 mit I2C-Adapter (PCF8574) und ein Buzzer-Modul, optional vier Taster.
Die Arduino IDE 2 mit dem ESP32-Boardpaket.
Für den Server einen Linux-Container oder eine VM mit Apache, PHP 8.4 und MariaDB, erreichbar über HTTPS (Reverse Proxy mit Let’s-Encrypt-Zertifikat).
Das Ergebnis
Ein Terminal: Karte auflegen, Doppelton, auf dem Display „Hallo Anna – Kommen 07:58“.
Automatisch Kommen und Gehen im Wechsel, oder mit Taste Kommen, Gehen, Pause und Dienstgang.
Buchungen gehen auch ohne WLAN nicht verloren und werden später nachgesendet.
Eine Weboberfläche mit Anwesenheit, Monat und Jahr mit Saldo, Urlaubsanträgen und CSV-Export.
Ein Mitarbeiterbereich: eigene Zeiten, Gleitzeit, Resturlaub, Anträge stellen.
Pausenabzug nach § 4 Arbeitszeitgesetz und Feiertage in Thüringen werden automatisch berücksichtigt.
Das Terminal kennt keine Namen und rechnet nichts. Es schickt nur „Karte X wurde aufgelegt“ an den Server. Der Server entscheidet, wem die Karte gehört, ob das ein Kommen oder ein Gehen ist und wie viele Stunden zusammenkommen. Deshalb lassen sich Karten sperren oder neu zuordnen, ohne das Terminal anzufassen.
Live ausprobieren
Eine Demo mit erfundenen Daten läuft unter zeit.micha-it.de. Es gibt zwei Zugänge, einen für die Verwaltung und einen für die Mitarbeitersicht. Die Zugangsdaten bekommst du auf Anfrage. Jede volle Stunde wird alles automatisch zurückgesetzt, du kannst also gefahrlos ausprobieren: als Mitarbeiterin Urlaub beantragen und ihn danach als Verwaltung genehmigen.
1Bauteile verkabeln
PN532 und LCD teilen sich einen I2C-Bus, also nur zwei Datenleitungen. Der ESP32 nutzt dafür standardmäßig GPIO 21 (SDA) und 22 (SCL).
Bauteil
Pin
ESP32
PN532
VCC / GND
3V3 / GND
PN532
SDA / SCL
GPIO 21 / GPIO 22
PN532
IRQ
GPIO 4
LCD (FC-113)
VCC / GND
5V / GND
LCD (FC-113)
SDA / SCL
GPIO 21 / GPIO 22
Buzzer
VCC / I/O / GND
3V3 / GPIO 25 / GND
Taster (optional)
Kommen / Gehen / Pause / Dienstgang
GPIO 32 / 33 / 26 / 27, jeweils gegen GND
Achtung
Pin-Reihenfolge prüfen. Auf dem PN532 steht SCL SDA VCC GND, auf dem LCD-Adapter genau umgekehrt GND VCC SDA SCL. Wer beide Module gleich verkabelt, vertauscht beim PN532 SDA und SCL.
Mit 3,3 V ist das Display meist zu blass, deshalb hängt es an 5 V. Die Pull-up-Widerstände auf dem Adapter ziehen die I2C-Leitungen dann auf 5 V. In der Praxis läuft das meistens, offiziell verträgt der ESP32 aber nur 3,3 V. Sauber wird es mit einem I2C-Pegelwandler.
2Den PN532 auf I2C stellen
Das Modul spricht drei Protokolle: HSU (seriell), I2C und SPI. Welches gilt, legt ein kleiner DIP-Schalter mit zwei Hebeln fest. Die Tabelle steht direkt daneben auf der Platine:
Modus
I0
I1
HSU
0
0
I2C
1 (ON)
0
SPI
0
1
Schalter 1 gehört zu I0, Schalter 2 zu I1. ON ist die Seite mit der Aufschrift „ON“. Danach den Strom ganz trennen, also den USB-Stecker ziehen. Der Chip liest den Schalter nur beim Einschalten, ein Reset reicht nicht.
Hinweis
Antwortet das Modul nicht, hilft ein I2C-Scan: Der PN532 meldet sich auf Adresse 0x24, das LCD meist auf 0x27 oder 0x3F. Fehlt 0x24, liegt es an Schalter, Kabel oder Strom und nicht an der Software.
3Erster Test: Karte lesen und piepen
In der Arduino IDE die Bibliotheken Adafruit PN532 (zieht Adafruit BusIO mit) und LiquidCrystal I2C installieren. Als Board „ESP32 Dev Module“ wählen. Der Kern des Lesers:
Ein passiver Buzzer braucht eine Frequenz (tone(25, 2000)), ein aktiver piept, sobald Strom anliegt (digitalWrite). Viele blaue 3-Pin-Module schalten außerdem bei LOW ein. Am einfachsten macht man beides im Sketch umschaltbar.
So erkennst du, dass es klappt
Der serielle Monitor (115200 Baud) zeigt beim Start PN532 gefunden, Chip PN532, Firmware 1.6. Liegt eine Karte auf, kommt ein Doppelton und das Display zeigt „Karte erkannt!“ mit der UID, zum Beispiel DF1CA61D.
4Welche Karten funktionieren?
Der PN532 arbeitet mit 13,56 MHz. Viele Ausweise in Firmen funken mit 125 kHz, die erkennt er schlicht nicht:
Karte
Frequenz
PN532
MIFARE Classic, NTAG, DESFire
13,56 MHz
ja
LEGIC advant
13,56 MHz
UID ja
LEGIC prime, HID iCLASS
13,56 MHz
nein (eigene Protokolle)
EM4102 / EM4200, Hitag, HID Prox
125 kHz
nein, dafür z. B. RDM6300
Smartphone (NFC)
13,56 MHz
ja, aber mit zufälliger UID bei jedem Auflegen
Eine MIFARE Classic 1K hat 16 Sektoren mit je 4 Blöcken zu 16 Byte. Jeder Sektor ist mit einem Schlüssel geschützt. Bei neuen Karten ist das FF FF FF FF FF FF, Karten aus alten Systemen haben oft eigene Schlüssel. Für die Zeiterfassung reicht die UID, der Inhalt wird nicht gebraucht.
Achtung
Eine 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 dort auf und wird korrigiert. Für ein Türschloss reicht die UID allein nicht. Fremde Karten wie Firmenausweise bitte nicht kopieren oder auslesen.
5Server: Datenmodell und Regeln
Der Server ist schlichtes PHP 8.4 mit PDO und MariaDB, ohne Framework. Die wichtigsten Tabellen:
Tabelle
Inhalt
mitarbeiter
Name, Soll pro Tag, Urlaubstage, Eintritt, aktiv
karten
UID → Mitarbeiter, sperrbar
terminals
Name und Hash des Geräte-Tokens, letzte Meldung
buchungen
Zeitpunkt, Art (kommen/gehen), Grund (normal/pause/dienstgang), Quelle (terminal/offline/korrektur), Storno mit Grund
antraege
Urlaub und Korrekturen mit Status und Antwort
Daraus berechnet der Server jeden Tag:
Automatik: Die erste Buchung am Tag ist Kommen, danach geht es immer im Wechsel.
Pause ist ein Gehen mit dem Grund Pause und wird nicht bezahlt. Die Zeit auf einem Dienstgang zählt als Arbeit.
§ 4 ArbZG: Bei mehr als 6 Stunden Arbeit werden 30 Minuten abgezogen, bei mehr als 9 Stunden 45 Minuten, soweit die Pause nicht gebucht wurde.
Soll gilt von Montag bis Freitag ab dem Eintritt. Feiertage in Thüringen sind frei, auch Weltkindertag und Reformationstag. Ostern wird mit der Gaußschen Osterformel berechnet.
Korrekturen gehen nur mit Grund. Gelöscht wird nie, eine stornierte Buchung bleibt durchgestrichen sichtbar.
So erkennst du, dass es klappt
Die Rechenregeln sind mit kleinen Tests abgesichert, zum Beispiel: 8:00–16:30 ohne Pause ergibt 8:00 Ist mit 30 Minuten Abzug, und Ostersonntag 2027 ist der 28.03. php tests/zeit_test.php meldet „Alle Tests bestanden“.
6Die Schnittstelle zum Terminal
Das Terminal schickt bei jeder Karte eine kleine JSON-Nachricht. Es meldet sich mit einem Token an, das in der Weboberfläche erzeugt und nur einmal angezeigt wird. Auf dem Server liegt davon nur der SHA-256-Hash.
HTTPS mit Zertifikatsprüfung: Die Firmware enthält das Wurzelzertifikat von Let’s Encrypt (ISRG Root X1). Ein setInsecure() gibt es nicht.
Offline: Ist der Server nicht erreichbar, speichert der ESP32 die Buchung mit Uhrzeit (NTP) in seinem Flash (LittleFS) und sendet sie alle 30 Sekunden erneut.
Doppelte erkennen: Jede Buchung trägt eine eindeutige ref. Kommt sie zweimal an, etwa nach einer Zeitüberschreitung, speichert der Server sie nur einmal.
Zweimal aufgelegt: Dieselbe Karte innerhalb einer Minute ergibt „Schon gebucht“ und keine zweite Buchung.
Unbekannte Karte: Sie erscheint in der Weboberfläche und wird mit einem Klick zugeordnet. So lernt man neue Karten an.
So erkennst du, dass es klappt
Ohne Token antwortet die Schnittstelle mit 401, eine gesperrte Karte mit 403. Zieht man dem Router den Stecker, zeigt das Display „Offline gespeichert“, und nach dem Wiederverbinden steht die Buchung mit der richtigen Uhrzeit und der Quelle „offline“ in der Tagesansicht.
7Weboberfläche: Verwaltung und Mitarbeiter
Rolle
Sieht und kann
Verwaltung
Wer ist da (anwesend, Pause, Dienstgang, Urlaub), Monat und Jahr je Mitarbeiter mit Saldo und CSV-Export, Jahreskalender, Anträge genehmigen oder ablehnen, Mitarbeiter, Karten und Terminals verwalten
Mitarbeiter
Nur die eigenen Daten: heute, Woche, Monat, Jahr, Gleitzeit seit 1.1., Resturlaub, Urlaub und Korrekturen beantragen
Eine genehmigte Korrektur wird automatisch als Buchung mit Antragsnummer eingetragen. An genehmigten Urlaubstagen entfällt das Soll.
Ein Urlaubsantrag wird geprüft: nur Arbeitstage zählen, keine Überschneidung mit anderem Urlaub, nicht mehr als der Resturlaub.
Der Zugang für einen Mitarbeiter bekommt ein Startpasswort, das bei der ersten Anmeldung geändert werden muss.
Sicherheit: Passwörter mit password_hash, CSRF-Token in jedem Formular, gebundene SQL-Parameter, Sitzungscookie mit Secure, HttpOnly und SameSite. Fehlversuche landen im Log, damit fail2ban sie auswerten kann.
8Betrieb: Container, Testkopie, Backup
Die Anwendung läuft in einem eigenen, unprivilegierten LXC-Container auf Proxmox, getrennt von anderen Webseiten. Personaldaten gehören nicht in denselben Container wie ein Blog.
config.php, der Programmcode und die Werkzeuge liegen außerhalb des Webordners. Nur public/ ist erreichbar.
Neue Versionen gehen zuerst in eine Testkopie mit eigener Datenbank, die nur intern über einen SSH-Tunnel erreichbar ist. Erst danach kommen sie live. Das Einspielskript prüft vorher die PHP-Syntax und sichert den alten Stand.
Der Container ist im nächtlichen Proxmox-Backup enthalten.
Für die Demo setzt ein Cron-Job jede volle Stunde alle Daten zurück. Ein gemeinsamer Demo-Zugang kann sein Passwort nicht ändern, damit sich die Testenden nicht gegenseitig aussperren.
Testkopie über den Tunnel ansehen
ssh -N -L 18084:10.20.30.123:8082 admin@pve.example.org
# danach im Browser: http://127.0.0.1:18084/
9Endkontrolle
Häufige Stolpersteine
„PN532 nicht gefunden“, aber das LCD geht? Fast immer der DIP-Schalter: falscher Hebel oder kein echter Neustart. Danach vertauschte SDA/SCL.
LCD leuchtet, zeigt aber nichts? Das blaue Potentiometer auf dem Adapter regelt den Kontrast.
Firmenkarte wird nicht erkannt? Wahrscheinlich 125 kHz (EM, Hitag) oder ein proprietäres Verfahren. Das liegt nicht an der Verkabelung.
Handy piept, aber jedes Mal mit anderer UID? Android sendet aus Datenschutzgründen eine Zufalls-UID. Als Schlüssel taugt das nicht.
Buzzer knackt nur oder piept dauernd? Aktiv und passiv verwechselt, oder das Modul schaltet bei LOW ein.
Die Uhrzeit fehlt nach dem Start? Ohne WLAN gibt es kein NTP. Das Terminal speichert dann nichts mit falscher Zeit, sondern zeigt „Keine Uhrzeit“.