# ESP32 8-Channel Bluetooth Relay Controller

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