# 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**:

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

2. **Install PlatformIO dependencies**:

   ```bash
   pio pkg install
   ```

3. **Install web UI dependencies**:

   ```bash
   cd ui
   npm install
   cd ..
   ```

4. **Generate protobuf files**:
   ```bash
   cd ui
   npm run proto
   cd ..
   ```

## Build and Flash

### Development Environment

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

### Production Environment

```bash
pio run -e prod
pio run -e prod -t upload
```

### Build Web UI

```bash
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

```bash
# Unit tests (if implemented)
pio test

# Web UI tests
cd ui
npm run check
```

## Deployment

1. **Build firmware**:

   ```bash
   pio run -e prod
   ```

2. **Build and copy web UI**:

   ```bash
   cd ui
   npm run build
   npm run copy
   cd ..
   ```

3. **Flash**:

   ```bash
   pio run -e prod -t upload
   ```

4. **Flash filesystem** (for web UI):
   ```bash
   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](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.