diff --git a/README.md b/README.md index a4d9449..9390423 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,332 @@ -# esp32-bluetooth-relay +# ESP32 8-Channel Bluetooth Relay Controller -ESP32 8-channel Bluetooth-controlled power relay with mobile app support \ No newline at end of file +A comprehensive ESP32-based 8-channel relay controller with Bluetooth connectivity for wireless control via smartphone or computer. + +## Features + +- ✅ Control 8 independent relays via Bluetooth +- ✅ Simple text-based command protocol +- ✅ Individual relay on/off/toggle control +- ✅ All relays on/off commands +- ✅ Status query for all relays +- ✅ Persistent state memory (remembers relay states after reboot) +- ✅ Easy integration with mobile apps (Serial Bluetooth Terminal, etc.) +- ✅ Compatible with Home Assistant via Bluetooth Serial integration + +## Hardware Requirements + +### Essential Components + +1. **ESP32 Development Board** + - Any ESP32 board with Bluetooth (ESP32-DevKitC, ESP32-WROOM, etc.) + - Minimum 8 GPIO pins available + +2. **8-Channel Relay Module** + - 5V or 3.3V trigger relay module + - Recommended: Active LOW trigger relays + - Options: + - Single 8-channel relay board + - Two 4-channel relay boards + - Individual relay modules + +3. **Power Supply** + - 5V power supply for ESP32 (USB or external) + - Separate power for relay coils if using high-current loads + - Recommended: 5V 2A+ power supply + +4. **Wiring Components** + - Jumper wires (male-to-male, male-to-female) + - Breadboard (optional for prototyping) + - Terminal blocks (for AC/DC load connections) + +### Optional Components + +- Enclosure/project box +- Status LEDs (already on most relay modules) +- Fuse holders for safety +- PCB for permanent installation + +## Wiring Diagram + +### GPIO Pin Assignments (Default) + +| Relay # | ESP32 GPIO | Relay Module Pin | +|---------|------------|------------------| +| Relay 1 | GPIO 13 | IN1 | +| Relay 2 | GPIO 12 | IN2 | +| Relay 3 | GPIO 14 | IN3 | +| Relay 4 | GPIO 27 | IN4 | +| Relay 5 | GPIO 26 | IN5 | +| Relay 6 | GPIO 25 | IN6 | +| Relay 7 | GPIO 33 | IN7 | +| Relay 8 | GPIO 32 | IN8 | + +### Power Connections + +``` +ESP32 8-Channel Relay Module +----- ---------------------- +GND -----------------> GND +5V -----------------> VCC (or separate 5V supply) + +GPIO13 -----------------> IN1 +GPIO12 -----------------> IN2 +GPIO14 -----------------> IN3 +GPIO27 -----------------> IN4 +GPIO26 -----------------> IN5 +GPIO25 -----------------> IN6 +GPIO33 -----------------> IN7 +GPIO32 -----------------> IN8 +``` + +### Load Connections (Per Relay) + +Each relay has three terminals: +- **COM (Common)**: Connect to power source +- **NO (Normally Open)**: Connects to COM when relay is ON +- **NC (Normally Closed)**: Connects to COM when relay is OFF + +**Example for controlling AC devices:** +``` +AC Live Wire --> Relay COM +Relay NO --> Device Live Wire +AC Neutral --> Device Neutral (direct connection) +``` + +⚠️ **WARNING**: Working with AC power is dangerous! Only attempt if you're qualified. Consider using DC loads for initial testing. + +## Software Setup + +### Arduino IDE Setup + +1. **Install ESP32 Board Support** + - Open Arduino IDE + - Go to File → Preferences + - Add to "Additional Board Manager URLs": + ``` + https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json + ``` + - Go to Tools → Board → Board Manager + - Search for "ESP32" and install + +2. **Configure Board Settings** + - Board: "ESP32 Dev Module" (or your specific board) + - Upload Speed: 115200 + - Flash Frequency: 80MHz + - Partition Scheme: "Default 4MB with spiffs" + +3. **Upload the Code** + - Open `esp32_bluetooth_relay.ino` + - Select your ESP32 board and COM port + - Click Upload + +### PlatformIO Setup (Alternative) + +If using PlatformIO: + +```ini +[env:esp32dev] +platform = espressif32 +board = esp32dev +framework = arduino +monitor_speed = 115200 +lib_deps = + BluetoothSerial +``` + +## Usage + +### Connecting via Bluetooth + +1. **Power on the ESP32** + - The device will appear as "ESP32-Relay-8CH" + +2. **Pair the Device** + - On your phone/computer, search for Bluetooth devices + - Connect to "ESP32-Relay-8CH" + - Default PIN: 1234 (if prompted) + +3. **Use a Serial Bluetooth Terminal** + - Android: "Serial Bluetooth Terminal" app + - iOS: "Bluetooth Terminal" app + - Windows: PuTTY with Bluetooth COM port + - Linux: `bluetoothctl` and `minicom` + +### Command Reference + +| Command | Description | Example | +|---------|-------------|---------| +| `ON1` - `ON8` | Turn on specific relay | `ON1` turns on Relay 1 | +| `OFF1` - `OFF8` | Turn off specific relay | `OFF5` turns off Relay 5 | +| `TOGGLE1` - `TOGGLE8` | Toggle specific relay | `TOGGLE3` toggles Relay 3 | +| `ALL_ON` | Turn all relays on | `ALL_ON` | +| `ALL_OFF` | Turn all relays off | `ALL_OFF` | +| `STATUS` | Get status of all relays | `STATUS` | +| `HELP` | Show available commands | `HELP` | + +Commands are **case-insensitive** and should be sent with a newline character. + +### Example Session + +``` +> STATUS +=== Relay Status === +Relay 1: OFF +Relay 2: OFF +Relay 3: ON +Relay 4: OFF +Relay 5: OFF +Relay 6: OFF +Relay 7: OFF +Relay 8: OFF +=================== + +> ON1 +Relay 1 is now ON + +> TOGGLE3 +Relay 3 is now OFF + +> ALL_ON +All relays turned ON +``` + +## Customization + +### Changing GPIO Pins + +Edit the `relayPins` array in the code: + +```cpp +const int relayPins[8] = {13, 12, 14, 27, 26, 25, 33, 32}; +``` + +### Changing Bluetooth Device Name + +Edit the `deviceName` constant: + +```cpp +const char* deviceName = "YourCustomName"; +``` + +### Changing Relay Names + +Edit the `relayNames` array: + +```cpp +const char* relayNames[8] = { + "Living Room", "Bedroom", "Kitchen", "Bathroom", + "Garden", "Garage", "Office", "Workshop" +}; +``` + +### Active HIGH vs Active LOW Relays + +Most relay modules are **active LOW** (relay turns ON when GPIO is LOW). If you have active HIGH relays, change: + +```cpp +// In setRelay() function, change: +digitalWrite(relayPins[relayIndex], state ? LOW : HIGH); +// to: +digitalWrite(relayPins[relayIndex], state ? HIGH : LOW); +``` + +## Home Assistant Integration + +### Method 1: Bluetooth Serial Integration + +1. Install the Bluetooth Serial integration in Home Assistant +2. Add to `configuration.yaml`: + +```yaml +bluetooth_serial: + - address: "XX:XX:XX:XX:XX:XX" # ESP32 MAC address + name: "ESP32 Relay Controller" + +switch: + - platform: template + switches: + relay_1: + friendly_name: "Relay 1" + turn_on: + service: bluetooth_serial.send + data: + address: "XX:XX:XX:XX:XX:XX" + message: "ON1\n" + turn_off: + service: bluetooth_serial.send + data: + address: "XX:XX:XX:XX:XX:XX" + message: "OFF1\n" +``` + +### Method 2: ESPHome (Alternative Firmware) + +For better Home Assistant integration, consider using ESPHome firmware instead. (Separate implementation recommended) + +## Troubleshooting + +### Bluetooth Not Showing Up +- Ensure Bluetooth is enabled in your ESP32 build +- Check if device is already paired with another device +- Try restarting the ESP32 + +### Relays Not Switching +- Verify wiring connections +- Check if relay module requires 5V and you're providing it +- Test with a multimeter +- Verify GPIO pins are correctly defined + +### Intermittent Connection +- Move closer to ESP32 +- Check power supply stability +- Ensure no interference from other Bluetooth devices + +### Relays Switching Opposite Direction +- Your relay module might be active HIGH instead of active LOW +- See "Active HIGH vs Active LOW Relays" section above + +## Safety Warnings + +⚠️ **ELECTRICAL SAFETY** +- Never work on AC wiring while powered +- Use proper insulation and enclosures +- Follow local electrical codes +- Consider hiring a licensed electrician for permanent installations +- Test with low voltage DC loads first + +⚠️ **RELAY RATINGS** +- Don't exceed relay current/voltage ratings +- Use appropriate fuses +- Account for inductive loads (motors, transformers) + +## License + +This project is open source and available under the MIT License. + +## Contributing + +Contributions are welcome! Please feel free to submit issues or pull requests. + +## Support + +For questions or issues: +- Open an issue on the repository +- Check existing issues for solutions +- Consult ESP32 and Arduino forums + +## Future Enhancements + +Potential additions: +- [ ] Web interface (ESP32 web server) +- [ ] MQTT support for Home Assistant +- [ ] Scheduling/timers +- [ ] Mobile app development +- [ ] WiFi connectivity option +- [ ] Scene/macro support +- [ ] Energy monitoring + +--- + +**Version:** 1.0.0 +**Last Updated:** December 2025