Vermix-Sense/README.md

# 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