Add comprehensive README documentation for RFID-SENSOR-GEN2 project, detailing features, hardware/software requirements, installation, configuration, usage, and development guidelines.
This commit is contained in:
@@ -0,0 +1,344 @@
|
||||
# RFID-SENSOR-GEN2
|
||||
|
||||
A comprehensive RFID sensor system built for ESP8266 microcontrollers, featuring LED control, RFID card detection, serial communication via Protocol Buffers, and over-the-air (OTA) update capabilities.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Hardware Requirements](#hardware-requirements)
|
||||
- [Software Requirements](#software-requirements)
|
||||
- [Installation](#installation)
|
||||
- [Configuration](#configuration)
|
||||
- [Building and Uploading](#building-and-uploading)
|
||||
- [Usage](#usage)
|
||||
- [API/Message Protocol](#apimessage-protocol)
|
||||
- [OTA Updates](#ota-updates)
|
||||
- [Development](#development)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
## Features
|
||||
|
||||
- **RFID Detection**: Reads RFID cards/tags using MFRC522 module
|
||||
- **LED Control**: Advanced LED animations including static, pulse, fade, and flicker effects
|
||||
- **Serial Communication**: Protocol Buffer-based messaging system for reliable data exchange
|
||||
- **OTA Updates**: Over-the-air firmware updates for remote maintenance
|
||||
- **Modular Architecture**: Clean separation of hardware components (LED, RFID, Serial)
|
||||
- **Configurable**: Extensive configuration options via protobuf messages
|
||||
- **ESP8266 Compatible**: Optimized for ESP8266 microcontrollers
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
- **Microcontroller**: ESP8266 (ESP-12E module recommended)
|
||||
- **RFID Reader**: MFRC522 RFID/NFC module
|
||||
- **LED Strip**: WS2812B or compatible addressable LED strip (NeoPixel)
|
||||
- **Power Supply**: 3.3V-5V DC power supply (depending on LED strip requirements)
|
||||
- **Connections**:
|
||||
- RFID SS pin → GPIO4 (D2)
|
||||
- RFID RST pin → GPIO5 (D1)
|
||||
- LED data pin → GPIO2 (D4)
|
||||
- Serial communication via USB/UART
|
||||
|
||||
## Software Requirements
|
||||
|
||||
- **PlatformIO**: For project management and building
|
||||
- **Arduino Framework**: ESP8266 core
|
||||
- **Dependencies**:
|
||||
- MFRC522 (RFID library)
|
||||
- FastLED (LED control library)
|
||||
- Nanopb (Protocol Buffers for embedded systems)
|
||||
|
||||
## Installation
|
||||
|
||||
1. **Clone the repository**:
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd RFID-SENSOR-GEN2
|
||||
```
|
||||
|
||||
2. **Install PlatformIO** (if not already installed):
|
||||
|
||||
```bash
|
||||
pip install platformio
|
||||
```
|
||||
|
||||
3. **Install dependencies**:
|
||||
```bash
|
||||
pio pkg install
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### PlatformIO Configuration
|
||||
|
||||
The project uses `platformio.ini` for configuration. Key settings:
|
||||
|
||||
```ini
|
||||
[platformio]
|
||||
default_envs = esp8285
|
||||
|
||||
[env]
|
||||
framework = arduino
|
||||
monitor_speed = 9600
|
||||
board_build.filesystem = littlefs
|
||||
|
||||
[env:esp8285]
|
||||
platform = espressif8266
|
||||
board = esp12e
|
||||
|
||||
[env:esp8285-ota]
|
||||
platform = espressif8266
|
||||
board = esp12e
|
||||
upload_protocol = espota
|
||||
upload_port = 192.168.20.41
|
||||
```
|
||||
|
||||
### Hardware Pin Configuration
|
||||
|
||||
Modify pin assignments in `src/main.cpp`:
|
||||
|
||||
```cpp
|
||||
// LED pin (default: GPIO2)
|
||||
HardwareLed<2> led;
|
||||
|
||||
// RFID pins (SS=D2/GPIO4, RST=D1/GPIO5)
|
||||
HardwareRfid rfid(4, 5);
|
||||
```
|
||||
|
||||
## Building and Uploading
|
||||
|
||||
### Standard Upload (USB)
|
||||
|
||||
1. Connect ESP8266 to computer via USB
|
||||
2. Build and upload:
|
||||
```bash
|
||||
pio run -t upload
|
||||
```
|
||||
|
||||
### OTA Upload
|
||||
|
||||
1. Ensure device is connected to network
|
||||
2. Use OTA environment:
|
||||
```bash
|
||||
pio run -e esp8285-ota -t upload
|
||||
```
|
||||
|
||||
### Monitor Serial Output
|
||||
|
||||
```bash
|
||||
pio device monitor
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Operation
|
||||
|
||||
The device continuously monitors for RFID cards and controls LED animations based on received commands. It communicates with a control system via serial interface using Protocol Buffer messages.
|
||||
|
||||
### LED Control
|
||||
|
||||
The system supports multiple LED animation types:
|
||||
|
||||
- **Static**: Solid color display
|
||||
- **Pulse**: Breathing effect with configurable speed
|
||||
- **Fade**: Smooth color transitions
|
||||
- **Flicker**: Random intensity variations
|
||||
|
||||
### RFID Detection
|
||||
|
||||
When an RFID card is detected, the system:
|
||||
|
||||
1. Reads the card ID
|
||||
2. Sends a `SensorToControlMessage` with RFID reading
|
||||
3. Can trigger LED animations based on configuration
|
||||
|
||||
## API/Message Protocol
|
||||
|
||||
The system uses Protocol Buffers for all communication. Messages are defined in `proto/hardware.proto`.
|
||||
|
||||
### Message Types
|
||||
|
||||
#### Sensor to Control Messages
|
||||
|
||||
```protobuf
|
||||
message SensorToControlMessage {
|
||||
uint32 sensor_id = 1;
|
||||
oneof payload {
|
||||
RfidReading rfid_reading = 2;
|
||||
SensorOTAEnableResponse ota_response = 3;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Control to Sensor Messages
|
||||
|
||||
```protobuf
|
||||
message ControlToSensorMessage {
|
||||
uint32 control_id = 1;
|
||||
oneof payload {
|
||||
LedConfig led_config = 2;
|
||||
SensorOTAEnable ota_enable = 3;
|
||||
SensorRestart restart = 4;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### LED Configuration
|
||||
|
||||
```protobuf
|
||||
message LedConfig {
|
||||
uint32 brightness = 1; // 0-255
|
||||
uint32 duration_ms = 2; // 0 for indefinite
|
||||
|
||||
oneof animation_params {
|
||||
StaticParams static_params = 3;
|
||||
PulseParams pulse_params = 4;
|
||||
FadeParams fade_params = 5;
|
||||
FlickerParams flicker_params = 6;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example Usage
|
||||
|
||||
Send LED configuration via serial:
|
||||
|
||||
```cpp
|
||||
// Create LED config message
|
||||
hardware_ControlToSensorMessage msg = {0};
|
||||
msg.control_id = 1;
|
||||
msg.which_payload = hardware_ControlToSensorMessage_led_config_tag;
|
||||
|
||||
// Configure static green LED
|
||||
msg.payload.led_config.brightness = 128;
|
||||
msg.payload.led_config.which_animation_params = hardware_LedConfig_static_params_tag;
|
||||
msg.payload.led_config.animation_params.static_params.color = 0x00FF00;
|
||||
|
||||
// Send via serial
|
||||
serial.sendMessage(msg);
|
||||
```
|
||||
|
||||
## OTA Updates
|
||||
|
||||
### Enabling OTA
|
||||
|
||||
Send an OTA enable message:
|
||||
|
||||
```protobuf
|
||||
message SensorOTAEnable {
|
||||
string ssid = 1;
|
||||
string password = 2;
|
||||
uint32 timeout_seconds = 3;
|
||||
bool as_station_mode = 4;
|
||||
bool use_static_ip = 5;
|
||||
string static_ip = 6;
|
||||
string netmask = 7;
|
||||
string gateway = 8;
|
||||
}
|
||||
```
|
||||
|
||||
### OTA Response
|
||||
|
||||
The device responds with:
|
||||
|
||||
```protobuf
|
||||
message SensorOTAEnableResponse {
|
||||
bool success = 1;
|
||||
string ip_address = 2;
|
||||
string error_message = 3;
|
||||
}
|
||||
```
|
||||
|
||||
### Performing OTA Update
|
||||
|
||||
1. Enable OTA mode on device
|
||||
2. Use PlatformIO OTA environment:
|
||||
```bash
|
||||
pio run -e esp8285-ota -t upload
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
RFID-SENSOR-GEN2/
|
||||
├── lib/
|
||||
│ ├── hardware/
|
||||
│ │ ├── hardware_led.cpp/hpp # LED control
|
||||
│ │ ├── hardware_rfid.cpp/hpp # RFID reading
|
||||
│ │ ├── hardware_serial.cpp/hpp # Serial communication
|
||||
│ │ └── library.json
|
||||
│ └── ota/
|
||||
│ ├── ota_update.cpp/hpp # OTA functionality
|
||||
│ └── library.json
|
||||
├── proto/
|
||||
│ ├── hardware.proto # Protocol definitions
|
||||
│ └── hardware.options # Nanopb options
|
||||
├── src/
|
||||
│ └── main.cpp # Main application
|
||||
├── test/ # Unit tests
|
||||
├── platformio.ini # PlatformIO config
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. **Hardware Components**: Add new classes in `lib/hardware/`
|
||||
2. **Message Types**: Extend `proto/hardware.proto`
|
||||
3. **Regenerate Protobuf**: Run `pio run -t build` to regenerate C++ files
|
||||
4. **Integration**: Update `src/main.cpp` to include new components
|
||||
|
||||
### Testing
|
||||
|
||||
Run unit tests:
|
||||
|
||||
```bash
|
||||
pio test
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
- Use `Serial.println()` for debug output
|
||||
- Monitor via `pio device monitor`
|
||||
- Check LED patterns for status indication
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch: `git checkout -b feature-name`
|
||||
3. Make your changes
|
||||
4. Add tests if applicable
|
||||
5. Run tests: `pio test`
|
||||
6. Commit changes: `git commit -am 'Add feature'`
|
||||
7. Push to branch: `git push origin feature-name`
|
||||
8. Submit a pull request
|
||||
|
||||
### Code Style
|
||||
|
||||
- Use consistent naming conventions
|
||||
- Add Doxygen-style comments for classes and methods
|
||||
- Follow Arduino coding standards
|
||||
- Keep functions focused and modular
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
|
||||
## Support
|
||||
|
||||
For questions, issues, or contributions:
|
||||
|
||||
- Create an issue on GitHub
|
||||
- Check the PlatformIO documentation
|
||||
- Review ESP8266 Arduino documentation
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0.0**: Initial release with basic RFID detection, LED control, and OTA support
|
||||
- **Future versions**: Enhanced animations, additional sensors, improved error handling
|
||||
|
||||
---
|
||||
|
||||
Built with ❤️ using PlatformIO and ESP8266
|
||||
Reference in New Issue
Block a user