esp32-bluetooth-relay/docs/QUICK_START.md

Quick Start Guide

Get your ESP32 8-channel relay controller up and running in 15 minutes!

What You Need

• ESP32 development board
• 8-channel relay module (5V)
• 8+ jumper wires (male-to-female)
• USB cable for ESP32
• Computer with Arduino IDE

Step 1: Wire It Up (5 minutes)

Power Connections

ESP32 5V  ──→ Relay Module VCC
ESP32 GND ──→ Relay Module GND

GPIO Connections (Default Configuration)

ESP32 GPIO → Relay Module
------------------------
GPIO 13    → IN1
GPIO 12    → IN2
GPIO 14    → IN3
GPIO 27    → IN4
GPIO 26    → IN5
GPIO 25    → IN6
GPIO 33    → IN7
GPIO 32    → IN8

Quick Tip: Use different colored wires to avoid confusion!

Step 2: Install Software (5 minutes)

Option A: Arduino IDE (Recommended for Beginners)

1. Install ESP32 Board Support

   File → Preferences → Additional Board Manager URLs
   Add: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   
   Tools → Board → Board Manager → Search "ESP32" → Install
   

2. Configure Board

   Tools → Board → "ESP32 Dev Module"
   Tools → Upload Speed → "115200"
   

3. Open the Sketch

   • Open esp32_bluetooth_relay.ino

Option B: PlatformIO (For Advanced Users)

# Navigate to project folder
cd esp32-bluetooth-relay

# Build and upload
pio run --target upload

# Monitor serial output
pio device monitor

Step 3: Upload Code (2 minutes)

1. Connect ESP32 to computer via USB
2. Select correct COM port: Tools → Port
3. Click Upload button (→)
4. Wait for "Done uploading" message

Troubleshooting Upload:

• Hold BOOT button on ESP32 while uploading starts
• Try different USB cable/port
• Check driver installation

Step 4: Test Connection (3 minutes)

On Mobile (Easiest)

1. Download a Bluetooth Terminal App

   • Android: "Serial Bluetooth Terminal"
   • iOS: "Bluetooth Terminal"

2. Pair and Connect

   • Open Bluetooth settings
   • Look for "ESP32-Relay-8CH"
   • Pair (PIN: 1234 if asked)

3. Open Terminal App

   • Connect to ESP32-Relay-8CH
   • Type: STATUS (press Enter)
   • You should see relay status!

On Computer

Windows:

1. Pair with ESP32 via Bluetooth settings
2. Note the COM port number
3. Open PuTTY or Arduino Serial Monitor
4. Connect to the COM port at 115200 baud

Linux:

# Find ESP32 MAC address
hcitool scan

# Pair
bluetoothctl
> pair XX:XX:XX:XX:XX:XX
> trust XX:XX:XX:XX:XX:XX
> connect XX:XX:XX:XX:XX:XX

# Connect with screen or minicom
sudo rfcomm bind /dev/rfcomm0 XX:XX:XX:XX:XX:XX
screen /dev/rfcomm0 115200

First Commands to Try

STATUS      # See all relay states
ON1         # Turn on relay 1
OFF1        # Turn off relay 1
TOGGLE1     # Toggle relay 1
ALL_ON      # Turn all relays on
ALL_OFF     # Turn all relays off
HELP        # Show all commands

Quick Troubleshooting

"Can't find ESP32-Relay-8CH"

• Power cycle the ESP32
• Check if Bluetooth is enabled on your device
• Unpair and re-pair if previously connected
• Check Serial Monitor for "Bluetooth device ready" message

"Relays not switching"

• Verify wiring matches the pin assignments
• Check relay module power (VCC and GND)
• Try different GPIO pins
• Test with multimeter

"Upload failed"

• Hold BOOT button during upload
• Check USB cable (data cable, not charge-only)
• Install CP210x or CH340 drivers
• Try different USB port

"Wrong direction" (relay ON when should be OFF)

• Your relay module is Active HIGH
• Change code in setRelay() function:

  digitalWrite(relayPins[relayIndex], state ? HIGH : LOW);
  

Safety First! ⚠️

Before connecting any loads:

1. ✅ Test with low voltage (12V DC LED strip, for example)
2. ✅ Verify relay is switching correctly
3. ✅ Double-check wiring
4. ✅ Use proper fuses
5. ⚠️ NEVER work on AC wiring while powered

For AC loads:

• Consider hiring an electrician
• Use proper electrical enclosures
• Follow local electrical codes
• Add fuses or circuit breakers

What's Next?

Customize Your Setup

• Edit relay names in code
• Change GPIO pins if needed
• Modify Bluetooth device name
• Add custom commands

Integration Ideas

• Control via Home Assistant
• Add scheduling/timers
• Create scenes (groups of relays)
• Add web interface
• MQTT integration

Upgrade Options

• Add WiFi control
• Use ESPHome firmware
• Add temperature sensors
• Energy monitoring
• Remote access via VPN

Need Help?

Check these resources:

1. Full README.md - Comprehensive documentation
2. Shopping list - Hardware recommendations
3. Troubleshooting section in README
4. Open an issue on repository
5. ESP32 community forums

Cheat Sheet

Common Commands:

ON1-8      Turn on relay 1-8
OFF1-8     Turn off relay 1-8
TOGGLE1-8  Toggle relay 1-8
ALL_ON     All on
ALL_OFF    All off
STATUS     Show states
HELP       Show commands

Serial Monitor Commands:

Upload Code: Ctrl+U (Arduino IDE)
Open Monitor: Ctrl+Shift+M
Clear Monitor: Click trash icon

Useful GPIO Pins (ESP32):

Safe for output: 13,12,14,27,26,25,33,32
Avoid: 6-11 (flash), 0,2 (boot), 34-39 (input only)

Success Checklist

• ESP32 powered on
• Relay module powered
• All GPIOs connected
• Code uploaded successfully
• Can pair via Bluetooth
• STATUS command works
• Relay clicks when toggled
• Tested with safe load (LED/bulb)

Congratulations! Your ESP32 relay controller is ready to use! 🎉

---

Version: 1.0
Last Updated: December 2025