Files

jessikitty cdb415374e Add comprehensive documentation with wiring, setup, and usage instructions

2025-12-15 16:09:57 +11:00

8.4 KiB

Raw Blame History

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

ESP32 Development Board
- Any ESP32 board with Bluetooth (ESP32-DevKitC, ESP32-WROOM, etc.)
- Minimum 8 GPIO pins available
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
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
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

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
Configure Board Settings
- Board: "ESP32 Dev Module" (or your specific board)
- Upload Speed: 115200
- Flash Frequency: 80MHz
- Partition Scheme: "Default 4MB with spiffs"
Upload the Code
- Open esp32_bluetooth_relay.ino
- Select your ESP32 board and COM port
- Click Upload

PlatformIO Setup (Alternative)

If using PlatformIO:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
lib_deps = 
    BluetoothSerial

Usage

Connecting via Bluetooth

Power on the ESP32
- The device will appear as "ESP32-Relay-8CH"
Pair the Device
- On your phone/computer, search for Bluetooth devices
- Connect to "ESP32-Relay-8CH"
- Default PIN: 1234 (if prompted)
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:

const int relayPins[8] = {13, 12, 14, 27, 26, 25, 33, 32};

Changing Bluetooth Device Name

Edit the deviceName constant:

const char* deviceName = "YourCustomName";

Changing Relay Names

Edit the relayNames array:

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:

// 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

Install the Bluetooth Serial integration in Home Assistant
Add to configuration.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

8.4 KiB Raw Blame History