ESP8266SmartRelay

A feature-rich ESP8266-based relay controller with web interface and Alexa integration using FauxmoESP.

Features

• 🌐 Web Interface: Modern, responsive control panel
• 🎤 Alexa Integration: Voice control through FauxmoESP
• 🔄 OTA Updates: Over-the-air firmware updates
• 🔐 Secure Configuration: Environment-based credentials (no hardcoded secrets)
• ⚡ Relay Inversion: Support for active-low/active-high relays
• 📡 WiFi Monitoring: Automatic reconnection with connection health checks
• 📊 Real-time Status: Live relay state feedback

Hardware Requirements

• ESP8266 (ESP-01 or similar)
• Relay module (5V/3.3V compatible)
• Power supply

Configuration

All configuration is managed through the .env file. Copy .env.example to .env and customize according to your needs.

Installation

Prerequisites

• PlatformIO installed
• Python 3.x (for build scripts)

Setup

1. Clone the repository:

   git clone https://github.com/alixti/ESP8266SmartRelay.git
   cd ESP8266SmartRelay

2. Create your .env file:

   cp .env.example .env

3. Edit .env with your configuration

4. Build and upload:

   # Initial upload via USB
   pio run -e usb -t upload
   
   # Subsequent uploads via OTA
   pio run -e ota -t upload

Usage

Web Interface

Access the device at http://<DEVICE_IP> to:

• View real-time relay status
• Turn relay ON/OFF
• Reset the device

Alexa Integration

1. Say "Alexa, discover devices"
2. Control with voice: "Alexa, turn on [FAUXMO_DEVICE_NAME]"

API Endpoints

• GET / - Web interface
• GET /status - Get relay state (JSON)
• GET /on - Turn relay ON
• GET /off - Turn relay OFF
• GET /reset - Restart device

Development

Project Structure

ESP8266SmartRelay/
├── src/
│   ├── main.cpp          # Main application code
│   └── config.h          # Configuration header (IDE hints)
├── .env                  # Your configuration
├── .env.example          # Configuration template
├── load_env.py           # Build script for loading .env
├── platformio.ini        # PlatformIO configuration
└── README.md

Build Environments

• usb: Upload via serial (COM port)
• ota: Upload over-the-air (WiFi)

Adding New Configuration Variables

Simply add them to .env:

MY_NEW_VARIABLE="value"

They're automatically available in code as MY_NEW_VARIABLE define.

Troubleshooting

Device won't connect to WiFi

• Check SSID and password in .env
• Verify WiFi network is 2.4GHz (ESP8266 doesn't support 5GHz)

OTA upload fails

• Ensure OTA_UPLOAD_PORT matches device IP
• Check that device is on the same network
• Verify OTA_PASSWORD is correct

Relay doesn't respond correctly

• Check RELAY_PIN matches your hardware
• Try toggling RELAY_INVERTED (some relays use active-low logic)

Alexa can't find device

• Ensure device and Echo are on the same network
• Wait 20-30 seconds after device boot before discovering
• Try "Alexa, forget all devices" then rediscover

Dependencies

• FauxmoESP - Alexa integration
• ESPAsyncWebServer - Async web server
• ESPAsyncTCP - Async TCP library
• ArduinoOTA - Over-the-air updates

License

MIT License - see LICENSE file for details

Contributing

Pull requests are welcome! For major changes, please open an issue first.