please login first!

login

Projekt · Elektronik und Web

Zeiterfassung mit RFID, ESP32 und PHP

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.

So hängt alles zusammen

KarteMIFARE Classic
13,56 MHz
TerminalESP32 · PN532
LCD · Buzzer · Tasten
SchnittstelleHTTPS + Geräte-Token
/api/buchung.php
ServerPHP 8.4 · MariaDB
Weboberfläche

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).

BauteilPinESP32
PN532VCC / GND3V3 / GND
PN532SDA / SCLGPIO 21 / GPIO 22
PN532IRQGPIO 4
LCD (FC-113)VCC / GND5V / GND
LCD (FC-113)SDA / SCLGPIO 21 / GPIO 22
BuzzerVCC / I/O / GND3V3 / GPIO 25 / GND
Taster (optional)Kommen / Gehen / Pause / DienstgangGPIO 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:

ModusI0I1
HSU00
I2C1 (ON)0
SPI01

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:

Ausschnitt rfid_reader.ino
Adafruit_PN532 nfc(4, -1, &Wire);      // IRQ an GPIO 4, Reset frei

void setup() {
  Wire.begin(21, 22);
  nfc.begin();
  if (!nfc.getFirmwareVersion()) { /* PN532 fehlt: Schalter, Kabel */ }
  nfc.SAMConfig();                      // bereit fuer ISO14443A-Karten
}

void loop() {
  uint8_t uid[7], len;
  if (nfc.readPassiveTargetID(PN532_MIFARE_ISO14443A, uid, &len, 200)) {
    // UID anzeigen und piepen
  }
}

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:

KarteFrequenzPN532
MIFARE Classic, NTAG, DESFire13,56 MHzja
LEGIC advant13,56 MHzUID ja
LEGIC prime, HID iCLASS13,56 MHznein (eigene Protokolle)
EM4102 / EM4200, Hitag, HID Prox125 kHznein, dafür z. B. RDM6300
Smartphone (NFC)13,56 MHzja, 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:

TabelleInhalt
mitarbeiterName, Soll pro Tag, Urlaubstage, Eintritt, aktiv
kartenUID → Mitarbeiter, sperrbar
terminalsName und Hash des Geräte-Tokens, letzte Meldung
buchungenZeitpunkt, Art (kommen/gehen), Grund (normal/pause/dienstgang), Quelle (terminal/offline/korrektur), Storno mit Grund
antraegeUrlaub und Korrekturen mit Status und Antwort

Daraus berechnet der Server jeden Tag:

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.

Anfrage und Antwort
POST /api/buchung.php
X-Terminal-Token: <64 Zeichen>

{"uid":"DF1CA61D", "art":"auto", "ref":"a1b2c3-17"}

-> {"status":"ok", "name":"Anna", "art":"Kommen", "zeit":"07:58", "heute":"0:00"}
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

RolleSieht und kann
VerwaltungWer 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
MitarbeiterNur die eigenen Daten: heute, Woche, Monat, Jahr, Gleitzeit seit 1.1., Resturlaub, Urlaub und Korrekturen beantragen

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.

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

Weiterlesen