RCP v3.1 - Advanced Access Control System

📋 Overview

RCP v3.1 is a professional access control system built on ESP32-S3 platform with touchscreen interface, supporting both online (WiFi + API) and offline (local SQLite database) operation modes. The system features multilingual UI (Polish/English), RFID card authentication, PIN code verification, and comprehensive event logging.

🔌 Hardware Schematic

Complete wiring diagram showing ESP32-S3 connections to display, touch, RFID, SD card, and peripherals.

✨ Key Features

🌐 Dual Operation Modes

Online Mode: WiFi connectivity with REST API integration
Offline Mode: Standalone operation with local SQLite database on SD card
Seamless mode switching via settings menu

🔐 Authentication Methods

RFID Cards: MFRC522 reader with UID authentication
PIN Codes: 11-digit secure PIN entry with lockout protection
Multi-attempt lockout system (3 failed attempts = 15s lockout)

🌍 Multilingual Interface

Polish and English language support
Language selection at startup
All UI elements translated via i18n system

⚙️ Advanced Settings

PIN-protected settings menu (default: 00000000000)
Configurable API endpoint URL
Offline/Online mode toggle
System information display
Factory reset functionality

💾 Data Management

Online: Real-time API communication with event logging
Offline: Local SQLite database with sync capability
- User records (name, RFID tags, PIN)
- Event logging with timestamps
- Sync queue for later upload

📱 Hardware Features

320x240 TFT touchscreen (ILI9341)
Capacitive touch interface (XPT2046)
RFID card reader (MFRC522)
Buzzer for audio feedback
SD card storage (4-bit SD_MMC mode)
Optional camera integration (ESP32-CAM style)

🛠️ Hardware Requirements

Core Components

MCU: ESP32-S3-DevKitC-1 (N8 variant, 8MB Flash)
Display: ILI9341 TFT LCD 320x240 (SPI)
Touch: XPT2046 touch controller
RFID: MFRC522 reader (SPI)
Storage: microSD card (any size, FAT32)
Audio: Passive buzzer

Pin Configuration

Display (ILI9341 - SPI)

TFT_MISO  = GPIO 12
TFT_MOSI  = GPIO 11
TFT_SCLK  = GPIO 10
TFT_CS    = GPIO 9
TFT_DC    = GPIO 8
TFT_RST   = GPIO 7
TFT_BL    = GPIO 6

Touch (XPT2046 - Shared SPI)

TOUCH_CS  = GPIO 5
TOUCH_IRQ = GPIO 4

RFID (MFRC522 - Shared SPI)

RFID_SS   = GPIO 17
RFID_RST  = GPIO 16

SD Card (SD_MMC - 4-bit mode)

SD_CLK    = GPIO 14
SD_CMD    = GPIO 15
SD_D0     = GPIO 45
SD_D1     = GPIO 46
SD_D2     = GPIO 47
SD_D3     = GPIO 48
CD        = GPIO 3

Audio & Camera

BUZZER    = GPIO 2
CAM_PWDN  = GPIO 1 (optional)

📦 Software Architecture

Directory Structure

RCP_V3.1/
├── include/
│   ├── config.h              # Hardware pin definitions
│   ├── states.h              # State machine definitions
│   ├── i18n.h                # Multilingual translations
│   └── database/
│       └── offline_db.h      # SQLite database wrapper
├── src/
│   ├── main.cpp              # Main application & state machine
│   ├── i18n.cpp              # Translation system
│   ├── hal/                  # Hardware abstraction layer
│   │   ├── display.cpp       # TFT display driver
│   │   ├── touch.cpp         # Touch controller
│   │   ├── rfid.cpp          # RFID reader
│   │   ├── buzzer.cpp        # Audio feedback
│   │   └── camera.cpp        # Camera interface (optional)
│   ├── network/              # Network communication
│   │   ├── api_client.cpp    # REST API client
│   │   └── wifi_manager.cpp  # WiFi connection handler
│   ├── storage/              # Persistent storage
│   │   └── preferences.cpp   # NVS key-value storage
│   ├── database/             # Offline database
│   │   └── offline_db.cpp    # SQLite operations
│   └── ui/                   # User interface
│       ├── screen_*.cpp      # UI screens
│       └── keyboard.cpp      # Virtual keyboard
├── lib/                      # External libraries
└── platformio.ini            # Build configuration

State Machine Flow

BOOT → CALIBRATION (if needed) → LANGUAGE_SELECT → MODE_CHECK
                                                        ↓
                                    ┌───────────────────┴──────────────────┐
                                    ↓                                      ↓
                               OFFLINE_INIT                        WIFI_CONNECTING
                                    ↓                                      ↓
                                    └──────────────→ IDLE ←───────────────┘
                                                      ↓
                                            ┌─────────┴─────────┐
                                            ↓                   ↓
                                       PIN_ENTRY          RFID_DETECTED
                                            ↓                   ↓
                                            └──→ PROCESSING ←───┘
                                                      ↓
                                            ┌─────────┴─────────┐
                                            ↓                   ↓
                                    RESULT_SUCCESS      RESULT_ERROR
                                            ↓                   ↓
                                            └──────→ IDLE ←─────┘

🚀 Getting Started

Prerequisites

PlatformIO (VSCode extension or CLI)
ESP32-S3 board definitions
USB cable for programming

Installation

Clone the repository

git clone https://github.com/Piotr19881/RCP_V3.1_Public.git
cd RCP_V3.1_Public

Install dependencies
```
pio lib install
```
Configure hardware pins (optional)
- Edit include/config.h if your pin configuration differs
Build the project
```
pio run
```
Upload to ESP32-S3
```
pio run --target upload
```
Monitor serial output
```
pio device monitor
```

First Run Setup

Touch Calibration: Follow on-screen prompts to calibrate touchscreen
Language Selection: Choose Polish or English interface
WiFi Setup (Online mode):
- Select WiFi network from list
- Enter password using on-screen keyboard
Settings Access: Hold "Back" button for 3 seconds, enter PIN 00000000000

🔧 Configuration

API Configuration (Online Mode)

Enter settings menu (PIN: 00000000000)
Select "API Settings"
Enter API base URL (e.g., https://api.example.com/rcp)
API endpoints:
- POST /auth-rfid - RFID authentication
- POST /auth-pin - PIN authentication
- GET /sync-events - Event synchronization

Offline Database Setup

Format SD card as FAT32
System will auto-create /rcp_offline.db on first run

Database schema:

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    rfid_tag_1 TEXT,
    rfid_tag_2 TEXT,
    rfid_tag_3 TEXT,
    pin TEXT
);

CREATE TABLE events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER,
    timestamp INTEGER NOT NULL,
    event_type INTEGER NOT NULL,
    auth_method TEXT,
    is_synced INTEGER DEFAULT 0
);

Import users via CSV (optional):
- Create test_users.csv on SD card root
- Format: id,name,rfid1,rfid2,rfid3,pin

📖 API Integration

Authentication Request Format

RFID Authentication

POST /auth-rfid
Content-Type: application/json

{
  "uid": "AB:CD:EF:12",
  "timestamp": 1735401234
}

PIN Authentication

POST /auth-pin
Content-Type: application/json

{
  "pin": "12345678901",
  "timestamp": 1735401234
}

Expected Response Format

{
  "success": true,
  "name": "John Doe",
  "type": "WEJSCIE",
  "message": "Access granted",
  "timestamp": 1735401234
}

🌐 Translations

The system uses a key-based translation system. All UI strings are defined in include/i18n.h:

enum TranslationKey {
    T_WELCOME,
    T_GOODBYE,
    // ... more keys
};

// Usage in code
displayPrintCentered(T(T_WELCOME), 100, FONT_SIZE_LARGE, COLOR_GREEN);

Add new languages by extending the translations array in i18n.h.

🔒 Security Features

PIN Protection: Settings menu secured with 11-digit PIN
Lockout Protection: Failed attempt tracking with exponential backoff
Secure Storage: Credentials stored in NVS (encrypted flash)
Event Logging: Complete audit trail of all access attempts
Offline Security: Local SQLite database with sync queue

📊 Memory Usage

RAM: ~58KB / 320KB (17.8%)
Flash: ~1.37MB / 3MB (43.5%)
PSRAM: Not required (works without)

🐛 Troubleshooting

Display Issues

Verify SPI connections and pin definitions in config.h
Check TFT_BL (backlight) is connected to GPIO 6
Ensure 3.3V power supply is stable

Touch Not Working

Run calibration routine (delete NVS if needed)
Check TOUCH_CS and TOUCH_IRQ connections
Verify touch controller is XPT2046 compatible

RFID Not Reading

Check MFRC522 connections (shared SPI bus)
Ensure RFID_RST is properly pulled up
Test with known good RFID cards (13.56MHz)

SD Card Errors

Format as FAT32 (not exFAT)
Check 4-bit SD_MMC connections
Verify card detect (CD) pin on GPIO 3

WiFi Connection Fails

Check WiFi credentials in settings
Ensure 2.4GHz network (ESP32 doesn't support 5GHz)
Verify API URL is accessible

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Links

📧 Contact

For questions or support, please open an issue on GitHub.

Built with ❤️ using ESP32-S3 and PlatformIO

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
docs		docs
include		include
lib		lib
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
platformio.ini		platformio.ini
test_psram_only.ini		test_psram_only.ini
test_users.csv		test_users.csv

License

Piotr19881/RCP_V3.1_Public

Folders and files

Latest commit

History

Repository files navigation