305 lines
7.0 KiB
Markdown
305 lines
7.0 KiB
Markdown
# 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.
|