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
8
Nets
42
Pads
65
Tracks, vias
84, 0
Routed
Yes
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 8 parts on 42 nets, routed with 84 tracks and 0 vias.

It is built around the ESP32-S3-DEVKITC-1-N8. Its parts include 2 resistors, 2 diodes, 2 connectors and 1 IC. It belongs with the radio and wireless boards and the ESP32 boards of this library.

Main components

1

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

8
QtyValueFootprintReferences
2330Resistor_THT:R_Axial_DIN0204_L3.6mm_D1.6mm_P1.90mm_VerticalR1, R2
2LEDLED_THT:LED_D1.8mm_W3.3mm_H2.4mmD1, D2
1BuzzerBuzzer_Beeper:Buzzer_12x9.5RM7.6BZ1
1Conn_01x04_PinConnector_PinHeader_1.00mm:PinHeader_1x04_P1.00mm_VerticalJ2
1Conn_01x07_PinConnector_PinHeader_1.00mm:PinHeader_1x07_P1.00mm_VerticalJ1
1ESP32-S3-DevKitCPCM_Espressif:ESP32-S3-DevKitCU1

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.

    28 parts

Similar boards

  • 4 layers95 × 95 mmCube motherboard, the printed circuit board in 3D

    Cube motherboard

    willem-pennings/balancing-cube

    A cube that balances itself in a corner or edge using reaction wheels

    52 parts1.1kGPL-3.0
  • 2 layers129.9 × 63.6 mmTraeger rev 2.3.0.kicad pro, the printed circuit board in 3D

    Traeger rev 2.3.0.kicad pro

    jazzmonger/Traeger-PID-Controller

    Traeger Smoker/Grill Controller based on an

    45 parts36
  • 2 layers168.8 × 78.9 mmGameboy3, the printed circuit board in 3D

    Gameboy3

    ohasanov-hbrw/tribit32-advanced

    A tri-microcontroller, overengineered GameBoy Advance clone. More value was given to the controls and the exterior look, which is cool!

    61 parts8
  • 2 layers134.6 × 49.5 mmMem esp, the printed circuit board in 3D

    Mem esp

    fread/visvitalis

    A very simple modular relay computer

    71 parts7
  • 2 layers90 × 102 mmPL Toon, the printed circuit board in 3D

    PL Toon

    pl-toon/pl-toon-codes

    PL-TOON material

    39 parts7
  • 2 layers119.4 × 98.9 mmPCB Pami, the printed circuit board in 3D

    PCB Pami

    FIPATECH/CDFR26_PAMI

    Open source firmware and PCB for a differential mobile robot (PAMI) based on ESP32-S3 - Coupe de France de Robotique

    25 parts6
  • 2 layers76.2 × 40.6 mmEspressifESP32toExpressAdaptor, the printed circuit board in 3D

    EspressifESP32toExpressAdaptor

    dnhutchins/ETC_Express_Reverse_Eng

    The ultimate goal of this work is to develop an interface to use the control surface from a legacy ETC Express 24/48 lighting controller as a modern EOSNomad compatible programming and fader wing.

    3 parts5
  • 2 layersE ink multi sensor, the printed circuit board in 3D

    E ink multi sensor

    heckler/esphome-device-configs

    Configuration definitions for local ESPHome files

    11 parts4Apache-2.0

Questions

What parts does the Rfid use?

8 parts, built around the ESP32-S3-DEVKITC-1-N8. 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 rfid-kicad/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.