RFID-Master-Client

A comprehensive RFID access control system based on ESP32, providing a web UI for management, OTA updates, and synchronization with an external server.

Overview

The RFID-Master-Client project is an embedded system for access control using RFID cards. It combines hardware control with a modern web interface, enabling management of users, settings, and logs through a user-friendly interface.

Features

• RFID Access Control: Management of RFID cards and access logging
• Web UI: Modern SvelteKit-based user interface for configuration and monitoring
• WiFi Management: Support for Station and Access Point modes
• OTA Updates: Over-the-Air firmware updates for easy maintenance
• Server Synchronization: Automatic data synchronization with an external server via RPC
• Hardware Configuration: Customizable hardware settings (relays, sensors, pins)
• Logging and Debugging: Comprehensive logging system with various levels
• TFT Display: Local display for status and interaction
• Protobuf Communication: Efficient serial communication between components

Architecture

The system consists of several modules:

Backend (C++ on ESP32)

• Core Modules: Logger, Settings, Hardware Configuration
• RFID Module: Database and processing of RFID cards
• WebUI Module: HTTP server for the web interface
• WiFi Manager: Network management
• OTA Manager: Firmware updates
• RPC Module: Communication with external server
• Device Manager: Hardware control (relays, LEDs)

Frontend (SvelteKit)

• Dashboard: Overview of system status
• User Management: RFID cards and permissions
• Settings: System and hardware configuration
• Logs: Display of system logs

Communication

• Protobuf: Binary serial communication between ESP32 and connected sensors
• HTTP/REST: Web API for the user interface
• WebSocket: Real-time updates in the web UI

Prerequisites

Hardware

• ESP32 development board (e.g., AZ-Delivery-DevKit-V4)
• RFID reader (MFRC522 or compatible)
• TFT display (ST7735/ST7789)
• Relay module for access control
• RTC module for timestamps

Software

• PlatformIO (for ESP32 development)
• Node.js 18+ (for web UI)
• protoc (Protocol Buffers Compiler)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd RFID-Master-Client
   

2. Install PlatformIO dependencies:

   pio pkg install
   

3. Install web UI dependencies:

   cd ui
   npm install
   cd ..
   

4. Generate protobuf files:

   cd ui
   npm run proto
   cd ..
   

Build and Flash

Development Environment

pio run -e dev
pio run -e dev -t upload
pio run -e dev -t monitor

Production Environment

pio run -e prod
pio run -e prod -t upload

Build Web UI

cd ui
npm run build
npm run copy
cd ..

Configuration

Hardware Configuration

Edit lib/data/hardware_config.hpp for pin assignments and hardware parameters.

System Settings

Configure via the web UI:

• WiFi settings
• Server synchronization
• Log level
• Hardware parameters

Partitioning

• partitions_custom.csv: For development (more memory for debugging)
• partitions_prod.csv: For production (optimized for size)

Usage

1. Initial Configuration:

   • Start device in AP mode
   • Connect to WiFi "RFID-Master"
   • Open web UI at http://192.168.4.1
   • Configure WiFi and server settings

2. Add RFID Cards:

   • Navigate to "Users" in web UI
   • Scan new RFID card or enter manually
   • Assign permissions

3. Monitoring:

   • Dashboard for system status
   • Logs for debugging
   • View access logs

API Reference

REST API Endpoints

• GET /api/status: Retrieve device status
• GET /api/users: Retrieve user list
• POST /api/users: Add new user
• GET /api/logs: Retrieve system logs
• POST /api/settings: Update settings

Protobuf Messages

• device.proto: Device information and status
• webui.proto: Web UI communication
• control_communication.proto: Control messages
• settings.proto: Configuration settings
• hardware.proto: Hardware configuration

Development

Code Structure

src/
├── main.cpp                 # Main entry point
├── webui/                   # Web server and API
├── wifi/                    # WiFi management
├── device/                  # Device management
lib/
├── data/                    # Data models and configuration
├── hardware/                # Hardware abstractions
├── log/                     # Logging system
├── ota/                     # OTA updates
├── rpc/                     # Server communication
├── tft/                     # Display control
ui/                          # Web UI (SvelteKit)
proto/                       # Protocol Buffer definitions

Debugging

• Use pio run -e dev -t monitor for serial logs
• Adjust log level via web UI
• Core dumps are enabled in dev environment

Tests

# Unit tests (if implemented)
pio test

# Web UI tests
cd ui
npm run check

Deployment

1. Build firmware:

   pio run -e prod
   

2. Build and copy web UI:

   cd ui
   npm run build
   npm run copy
   cd ..
   

3. Flash:

   pio run -e prod -t upload
   

4. Flash filesystem (for web UI):

   pio run -e prod -t uploadfs
   

Troubleshooting

Common Issues

• WiFi connection failed: Check SSID/password, verify signal strength
• RFID not recognized: Check hardware connections, test MFRC522 module
• Web UI unreachable: Check firewall settings, verify IP address
• OTA update failed: Check network connection, verify firmware size

Analyze Logs

• Set log level to DEBUG for detailed output
• Use serial monitor for real-time logs
• Web UI logs for HTTP requests

Hardware Debugging

• Verify pin assignments in hardware_config.hpp
• Ensure proper power supply to modules
• Test I2C/serial connections

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Code Standards

• Use C++17 for ESP32 code
• TypeScript for web UI
• Protobuf for serial communication
• Document new features and API changes

License

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

Support

For questions or issues:

• Open an issue in the GitHub repository
• Check logs for error indications
• Ensure all prerequisites are met

Changelog

[Unreleased]

• Initial release of the RFID-Master-Client system
• Complete RFID access control
• Web UI with SvelteKit
• OTA update functionality
• Server synchronization

---

For detailed information about specific modules, see the corresponding README files in the subdirectories.