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