init
This commit is contained in:
@@ -0,0 +1,304 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user