Skip to the content
2 layersRFID, the printed circuit board in 3D

Local-First & Offline-Resilient RFID Attendance System built with ESP32-S3, PlatformIO, Custom KiCad PCB, and FastAPI Backend.

Copper layers
2
Thickness
1.6 mm
Parts
28
Nets
54
Pads
154
Tracks, vias
0, 0
Routed
Not yet
KiCad
KiCad 10.0 (file 20260206)
Created
12 Sep 2026
Updated
27 Oct 2026

Overview

RFID is an open-source printed circuit board by LeafCodes, from the LeafCodes/esp32s3-rfid-attendance repository on GitHub. It is a 2-layer board with 28 parts on 54 nets.

It is built around the ESP32-S3-WROOM-1-N8, AMS1117 and BCV29, with the LESD5D5.0CT1G among its other parts. Its parts include 8 capacitors, 8 resistors, 5 connectors, 2 ICs and 2 transistors. It belongs with the radio and wireless boards and the ESP32 boards of this library.

Main components

4

README

README.md

📇 ESP32-S3 RFID Attendance System

Sistem Presensi RFID Mandiri Berbasis IoT & Local-First Architecture
Solusi presensi cerdas, hemat biaya, dan tahan kendala jaringan dengan integrasi end-to-end: Custom PCB (KiCad) + Embedded C++ (ESP32-S3) + Modern Web Backend (FastAPI & SQLite).

PlatformIO ESP32-S3 FastAPI Python SQLite KiCad License: MIT


📌 Latar Belakang & Masalah (Problem Statement)

Banyak institusi, sekolah, laboratorium, maupun startup menghadapi berbagai kendala dalam pencatatan kehadiran:

  1. Absensi Manual / Kertas: Rawan manipulasi, rawan hilang, dan memakan waktu rekapitulasi yang tinggi.
  2. Mesin Biometrik (Fingerprint) Konvensional: Sering gagal mengenali sidik jari yang kotor, berminyak, atau basah; menimbulkan antrean panjang di jam sibuk kerja/sekolah.
  3. Sistem Cloud Murni (Pure Cloud-Dependent): Jika koneksi internet ISP luar mati (down) atau latensi tinggi, seluruh proses absensi di kantor menjadi lumpuh dan karyawan tidak bisa tap kartu.
  4. Konfigurasi Jaringan yang Rumit: Perangkat IoT tradisional sering mengharuskan pengaturan IP statis (hardcoded) pada firmware setiap kali berpindah router/jaringan.

💡 Solusi yang Ditawarkan (The Engineering Solution)

Proyek ini menghadirkan arsitektur presensi lokal-mandiri (Local-First & Offline-Resilient) yang andal dan mudah dioperasikan tanpa ketergantungan pada internet publik:

  • 🛡️ Offline-First & Auto-Synchronization:
    ESP32-S3 menyimpan daftar UID kartu aktif di memori EEPROM/Flash. Jika server PC atau jaringan mati, proses tap tetap berhasil dicatat ke dalam memori offline buffer lokal (LittleFS/RAM). Begitu server kembali online, data transaksi otomatis terkirim tanpa ada absensi yang hilang.
  • 🔍 Zero-Configuration Network (mDNS Discovery):
    ESP32 secara cerdas mencari keberadaan server PC lokal di jaringan menggunakan protokol mDNS (absensi-pc.local). Pengguna tidak perlu mengubah kode atau mengatur IP statis saat berganti router.
  • 📶 WiFi Captive Portal (WiFiManager):
    Konfigurasi SSID dan password dilakukan melalui halaman web portal saat ESP32 pertama kali dinyalakan atau saat jaringan berubah, tanpa perlu flash ulang firmware.
  • ⏱️ Double-Tap Debounce Protection:
    Backend FastAPI dilengkapi proteksi logika selisih waktu (<10 detik) untuk mencegah terjadinya duplikasi data saat karyawan menempelkan kartu berulang kali tanpa sengaja.
  • 🔊 Feedback Visual & Audio Real-Time:
    Respon instan kepada pengguna melalui LCD 16x2 I2C (nama karyawan dan status Masuk/Pulang), lampu status Dual LED, dan nada Buzzer spesifik (sukses vs ditolak).
  • 📊 Dashboard Interaktif & One-Click Excel Export:
    Admin dapat memantau log kehadiran secara real-time, mendaftarkan kartu baru via browser, dan mengekspor laporan lengkap ke format Microsoft Excel (.xlsx) siap olah.
  • 🛠️ Full-Stack Hardware-to-Software:
    Dirancang dari level sirkuit elektronik (desain skematik & PCB di KiCad), enclosure 3D print, hingga full-stack software.

🏗️ Arsitektur Sistem

Berikut adalah gambaran interaksi antara komponen perangkat keras dan aplikasi server:

mermaid
flowchart LR
    subgraph EdgeDevice[" Perangkat Keras (Edge Device) "]
        RFID["RFID MFRC522\n(13.56MHz SPI)"] --> ESP["ESP32-S3 MCU\n(Dual-Core Xtensa)"]
        ESP --> LCD["LCD 16x2 I2C\n(Visual Info)"]
        ESP --> BUZZ["Buzzer & LED\n(Audio-Visual Status)"]
        ESP -. Buffer Luring .-> FS["Internal Flash / EEPROM\n(Offline Buffer & Card DB)"]
    end

    subgraph LocalNetwork[" Jaringan Area Lokal (WiFi / LAN) "]
        ESP -- "mDNS Service Discovery" --- MDNS["Resolusi: absensi-pc.local"]
        ESP -- "REST API (JSON / HTTP)" --- API["POST /api/attendance\nGET /api/cards"]
    end

    subgraph HostPC[" Server Lokal (PC / Mini PC) "]
        API --> FastAPI["FastAPI Backend Server\n(Uvicorn ASGI Engine)"]
        FastAPI --> SQLite[("SQLite Database\n(Cards, Logs, Settings)")]
        FastAPI --> WebUI["Web Dashboard & Reports\n(Jinja2 + Tailwind)"]
        FastAPI --> Excel["Export Engine\n(OpenPyXL .xlsx)"]
    end

📖 Pelajari detail alur sistem & flowchart lengkap: docs/architecture_flowchart.md


✨ Fitur-Fitur Utama

1. Sisi Firmware (ESP32-S3)

  • Dual-State Attendance Toggle: Menentukan otomatis pergantian status IN (Masuk) atau OUT (Keluar).
  • NTP Clock Synchronization: Jam internal tersinkronisasi otomatis via NTP (Network Time Protocol).
  • Smart Offline Buffer Recovery: Mengirim antrean data luring secara otomatis begitu koneksi ke server pulih.
  • Modular Codebase: Kode C++ tertata rapi dalam modul terpisah (wifi_manager, rfid_handler, pc_client, offline_buffer, lcd_display, led_buzzer).

2. Sisi Server & Web App (FastAPI)

  • Realtime Dashboard: Menampilkan status kehadiran hari ini, waktu tap, serta rincian karyawan.
  • Interactive Enrollment Mode: Pendaftaran kartu baru langsung dari web browser. Saat mode aktivasi menyala, kartu yang di-tap otomatis terdaftar ke profil pegawai baru.
  • Audit & Export Excel: Unduh rekapitulasi presensi harian/bulanan dengan format rapi dan siap cetak.
  • Lightweight & High Performance: Dibangun menggunakan FastAPI asynchronous dengan SQLite yang ringan dan mudah di-backup.

3. Sisi Hardware & PCB

  • Custom KiCad Design: Skematik dan layout 2-layer siap cetak (home-etching toner transfer atau fabrikasi JLCPCB/PCBWay).
  • Decoupling Protection: Dilengkapi kapasitor peredam noise pada jalur suplai daya MFRC522 dan ESP32.
  • Mounting Enclosure Ready: Dimensi PCB 100×80 mm dirancang presisi untuk box/casing 3D print.

🧰 Kebutuhan Komponen (Hardware & Software)

Komponen Elektronika

KomponenSpesifikasi / TipeFungsi
MicrocontrollerESP32-S3 DevKitC-1 (WiFi + BLE)Pemroses utama, konektivitas, buffer memori
RFID ReaderMFRC522 (13.56 MHz, SPI Interface)Pembaca kartu RFID MIFARE
DisplayLCD 16x2 Karakter dengan I2C BackpackPenampil jam, sapaan nama, dan status
Audio-VisualActive Buzzer 5V, LED Hijau, LED MerahIndikator status sukses / ditolak
Kartu/TagMIFARE Classic 1K Card / KeyfobIdentitas pengguna / karyawan
Catu Daya5V DC (USB-C atau Adaptor 5V 1A)Sumber daya sistem

Perangkat Lunak & Library

  • Firmware: PlatformIO IDE, Arduino Framework for ESP32, LittleFS, ArduinoJson, MFRC522, LiquidCrystal_I2C, WiFiManager.
  • PC Backend: Python 3.12+, FastAPI, Uvicorn, SQLAlchemy, SQLite, OpenPyXL, python-zeroconf.
  • EDA / PCB Tool: KiCad 8.0+.

🚀 Panduan Memulai Cepat (Quick Start)

1. Flash Firmware ke ESP32-S3

Pastikan Anda telah memasang PlatformIO Core / IDE.

bash
# Masuk ke direktori firmware
cd firmware

# Compile dan upload ke board ESP32-S3
pio run -t upload

# Buka Serial Monitor untuk memantau proses boot
pio device monitor

2. Menjalankan Server PC (FastAPI)

Buka terminal baru di komputer yang terhubung ke jaringan WiFi/LAN yang sama:

bash
# Masuk ke direktori pc-app
cd pc-app

# Buat virtual environment (opsional namun disarankan)
python -m venv venv
# Windows:
venv\Scripts\activate
# Linux/macOS:
# source venv/bin/activate

# Install dependensi
pip install -r requirements.txt

# Jalankan server FastAPI
uvicorn app.main:app --host 0.0.0.0 --port 8000

3. Mengakses Web Dashboard

Buka browser web di komputer Anda lalu akses salah satu alamat berikut:

  • 🌐 http://localhost:8000
  • 🌐 http://absensi-pc.local:8000

📂 Struktur Repositori

text
projek_absensi_rfid/
├── firmware/                  # Proyek Firmware PlatformIO (ESP32-S3)
│   ├── src/                   # Source code modular C++
│   │   ├── main.ino           # Logika utama (setup & loop)
│   │   ├── config.h           # Pemetaan pin hardware & parameter sistem
│   │   ├── rfid_handler.cpp   # Driver komunikasi MFRC522 (SPI)
│   │   ├── pc_client.cpp      # Klien HTTP REST API ke server PC
│   │   ├── mdns_client.cpp    # Resolusi nama server otomatis (mDNS)
│   │   ├── offline_buffer.cpp # Manajemen buffer antrean offline
│   │   ├── card_storage.cpp   # Cache UID kartu lokal pada Flash
│   │   └── ...
│   ├── include/               # Header deklarasi
│   └── platformio.ini         # Konfigurasi board & dependensi library
├── pc-app/                    # Aplikasi Server & Web (FastAPI)
│   ├── app/
│   │   ├── main.py            # Entry point FastAPI & zeroconf mDNS advertiser
│   │   ├── database.py        # Konfigurasi database SQLite & ORM engine
│   │   ├── models.py          # Model database: Card & AttendanceLog
│   │   ├── routes/            # REST API endpoints (cards, attendance, reports)
│   │   ├── services/          # Layanan mDNS broadcast & sync logic
│   │   ├── templates/         # UI Dashboard HTML (Jinja2)
│   │   └── static/            # Styling CSS & aset web
│   ├── tests/                 # Unit testing (Pytest)
│   └── requirements.txt       # Daftar dependensi Python

📚 Panduan Dokumentasi Lengkap

Untuk eksplorasi teknis yang lebih komprehensif, silakan pelajari dokumen-dokumen berikut:


👨‍💻 Kontribusi & Lisensi

Proyek ini dirilis di bawah lisensi terbuka MIT License. Bebas digunakan, dimodifikasi, dan dikembangkan untuk keperluan riset, edukasi, maupun implementasi komersial.

Parts

28
QtyValueFootprintReferences
410uF/25V(20%)Capacitor_SMD:C_0201_0603Metric_Pad0.64x0.40mm_HandSolderC1, C3, C4, C7
30(1%)Resistor_SMD:R_0201_0603MetricR1, R4, R5
310k(1%)Resistor_SMD:R_0201_0603MetricR2, R3, R6
20.1uF/25V(20%)Capacitor_SMD:C_0201_0603Metric_Pad0.64x0.40mm_HandSolderC5, C6
2220Resistor_SMD:R_0201_0603MetricR7, R8
2BCV29Package_TO_SOT_SMD:SOT-89-3Q1, Q2
10.1uF/25V(10%)Capacitor_SMD:C_0201_0603Metric_Pad0.64x0.40mm_HandSolderC2
11uF/16V(10%)Capacitor_SMD:C_0201_0603Metric_Pad0.64x0.40mm_HandSolderC8
1AMS1117Package_TO_SOT_SMD:SOT-223-3_TabPin2U2
1BuzzerBuzzer_Beeper:Buzzer_12x9.5RM7.6BZ1
1ESP32-S3-WROOM-1PCM_Espressif:ESP32-S3-WROOM-1U1
1LCD_SocketConnector_PinSocket_1.00mm:PinSocket_1x04_P1.00mm_VerticalJ2
1LED_SocketConnector_PinSocket_1.00mm:PinSocket_1x03_P1.00mm_VerticalJ1
1LESD5D5.0CT1GDiode_SMD:Nexperia_DSN0603-2_0.6x0.3mm_P0.4mmD2
1PolyfuseFuse:Fuse_Bourns_MF-RG300F2
1Power_SocketConnector_PinSocket_1.00mm:PinSocket_1x02_P1.00mm_VerticalJ4
1RFID_SocketConnector_PinSocket_1.00mm:PinSocket_1x08_P1.00mm_VerticalJ3
1Test_PointConnector_PinSocket_1.00mm:PinSocket_1x06_P1.00mm_VerticalJ5

More from LeafCodes/esp32s3-rfid-attendance

1
  • 2 layersRfid, the printed circuit board in 3D

    Rfid

    LeafCodes/esp32s3-rfid-attendance

    Local-First & Offline-Resilient RFID Attendance System built with ESP32-S3, PlatformIO, Custom KiCad PCB, and FastAPI Backend.

    8 parts

Similar boards

  • 2 layers134.4 × 99.6 mmLine sensor, the printed circuit board in 3D

    Line sensor

    Potato-eater/Legacy2026

    github repo for Robocup Junior Australia lightweight soccer team

    79 parts2
  • 2 layers86 × 54 mmLLM Business Card, the printed circuit board in 3D

    LLM Business Card

    pham-tuan-binh/bouija

    Running LLM on a Business Card LITERALLY

    84 parts60
  • 4 layers115 × 55 mmRoamr motors, the printed circuit board in 3D

    Roamr motors

    uw-roamr/roamr

    turn your phone into a robot running SLAM with two motors, two control boards, and a bluetooth chip

    110 parts6
  • 2 layers33 × 50 mmHema console, the printed circuit board in 3D

    Hema console

    rapha-tech/ESP32-hema-console

    New PCB for the small console from hema to use an ESP32

    59 parts4
  • 2 layers96.2 × 129.6 mmPendant, the printed circuit board in 3D

    Pendant

    cumhuronat/mr-1-openpendant

    An opensource pendant project MR-1 CNC

    62 parts1
  • 2 layers55 × 70 mmSumo hardware, the printed circuit board in 3D

    Sumo hardware

    equipe-paralela/sumo-hardware

    3Kg Sumo Hardware

    96 parts1GPL-3.0
  • 2 layers36.6 × 57.1 mmESP32 S3 devkit test, the printed circuit board in 3D

    ESP32 S3 devkit test

    FrWA14/KiCad8_ESP32S3_DevModule_wroom-1_DevelopementBoard

    Contient tout les fichier KiCad nécessaire pour faire une carte ESP32S3 avec un module Wroom-1.

    44 parts1
  • 2 layers85 × 65 mmFuente regulable, the printed circuit board in 3D

    Fuente regulable

    iowlabs/camara_electroforesis

    Dispositivo para la instrumentación de experimentos de electroforesis. Considera tanto el diseño de un modelo 3D para el tanque, como la electrónica para una fuente generadora de voltaje.

    80 parts1GPL-3.0

Questions

What parts does the RFID use?

28 parts, built around the ESP32-S3-WROOM-1-N8, AMS1117, BCV29 and LESD5D5.0CT1G. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the RFID KiCad files?

From the LeafCodes/esp32s3-rfid-attendance repository on GitHub, at the commit this page was made from: the board is pcb/RFID/RFID.kicad_pcb and its schematic pcb/RFID/Power_management_n_Protection_sch.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the RFID design in my own project?

Its repository states no licence, so its author keeps all rights: ask LeafCodes before reusing the design.