jessikitty/esp32-bluetooth-relay

Fork 0

Files

jessikitty ac379ed2ac Add comprehensive troubleshooting guide

2025-12-15 16:17:27 +11:00

13 KiB

Raw Permalink Blame History

Troubleshooting Guide

Common issues and solutions for the ESP32 Bluetooth Relay Controller.

Bluetooth Issues
Relay Problems
Upload/Programming Issues
Power Supply Problems
Serial Communication
Home Assistant Integration
Hardware Verification

Bluetooth Issues

ESP32 Not Appearing in Bluetooth Scan

Symptoms: Device "ESP32-Relay-8CH" doesn't show up in Bluetooth devices list

Possible Causes & Solutions:

Bluetooth not enabled in firmware

Solution: Ensure CONFIG_BT_ENABLED is set in Arduino IDE
- File → Preferences → Check "Enable Bluetooth"
- Or use PlatformIO with correct platformio.ini

ESP32 already paired with another device

Solution: 
- Unpair ESP32 from all devices
- Power cycle the ESP32
- Try scanning again

ESP32 not running/crashed

Solution:
- Check serial monitor for boot messages
- Look for "Bluetooth device ready to pair" message
- Press reset button on ESP32

Bluetooth module disabled on your device

Solution:
- Enable Bluetooth on your phone/computer
- Ensure airplane mode is off
- Restart your device

Can't Connect After Pairing

Symptoms: Device pairs but won't connect or immediately disconnects

Solutions:

Clear pairing and re-pair

Steps:
- Forget/unpair the device
- Restart ESP32
- Restart your phone/computer
- Pair fresh

Check serial monitor

Look for error messages indicating:
- Memory issues
- Bluetooth stack errors
- Connection timeouts

Interference

- Move away from WiFi routers
- Disable WiFi on ESP32 if not needed
- Try in different location

Connection Keeps Dropping

Symptoms: Bluetooth disconnects randomly

Solutions:

Distance issue

- Move closer to ESP32 (< 10 meters)
- Remove obstacles between devices
- ESP32 should have clear line of sight

Power supply instability

- Use quality USB cable
- Try different power adapter
- Add capacitor (100-1000µF) across power

Radio interference

- Turn off nearby 2.4GHz WiFi
- Move away from microwaves
- Change Bluetooth channel if possible

Relay Problems

Relays Not Switching

Symptoms: Commands sent but relays don't click/switch

Diagnostic Steps:

Check wiring

Verify connections:
ESP32 GPIO → Relay IN pin
ESP32 GND → Relay GND
ESP32 5V → Relay VCC

Measure voltage at relay input

Using multimeter:
- When relay should be ON: measure ~0V (LOW)
- When relay should be OFF: measure ~3.3V (HIGH)

Test with serial monitor

Open Serial Monitor (115200 baud)
Send commands manually:
- Type: ON1
- Watch for confirmation messages
- Check if relay clicks

Verify GPIO pin assignment

// Check this matches your wiring
const int relayPins[8] = {13, 12, 14, 27, 26, 25, 33, 32};

Relays Switch Opposite (ON is OFF, OFF is ON)

Symptoms: Relay activates when you send OFF command

Cause: Active HIGH relay module instead of active LOW

Solution:

Edit the setRelay() function in code:

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

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

Or check if your relay module has a jumper for HIGH/LOW trigger selection.

Only Some Relays Work

Symptoms: Some relays work, others don't

Check:

GPIO pin conflicts

Pins to avoid on ESP32:
- GPIO 6-11 (connected to flash)
- GPIO 0, 2 (used for boot mode)
- GPIO 34-39 (input only, can't drive relays)

Damaged relay channels

- Swap relay positions
- If problem follows relay: relay is bad
- If problem stays with pin: GPIO issue

Insufficient current

- Some relays may not get enough current
- Use external power for relay module
- Check power supply rating

Relays Stuck ON or OFF

Symptoms: Relay won't change state regardless of command

Solutions:

Check relay manually

- Disconnect from ESP32
- Apply 5V directly to relay input
- If still doesn't work: relay is damaged

GPIO pin may be damaged

- Try different GPIO pin
- Update pin assignment in code

Relay contacts welded

- Possible if relay switched high current
- Replace relay module
- Use relay with higher current rating

Upload/Programming Issues

"Failed to connect to ESP32"

Symptoms: Upload fails with connection error

Solutions:

Hold BOOT button during upload

Steps:
- Click Upload in Arduino IDE
- When "Connecting..." appears
- Press and hold BOOT button
- Release after upload starts

Check USB cable

- Use data cable (not charge-only)
- Try different USB cable
- Try different USB port

Install drivers

Windows:
- CP210x driver (Silicon Labs)
- CH340 driver (WCH)

Download from:
- https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
- http://www.wch-ic.com/downloads/CH341SER_ZIP.html

Check COM port

Arduino IDE:
- Tools → Port
- Select correct COM port (try different ones)
- Should show "ESP32 Dev Module" or similar

Upload Succeeds but ESP32 Doesn't Boot

Symptoms: Upload completes but ESP32 doesn't run program

Check:

Serial monitor for errors

- Open Serial Monitor at 115200 baud
- Press ESP32 reset button
- Look for boot messages or errors

Partition scheme

Arduino IDE:
- Tools → Partition Scheme
- Select "Default 4MB with spiffs"

Flash frequency

- Tools → Flash Frequency → 80MHz
- Try 40MHz if 80MHz doesn't work

Code Compiles but Has Errors

Symptoms: Build succeeds but runtime errors occur

Check:

Board selection

Ensure correct board:
- Tools → Board → ESP32 Dev Module
- Or your specific ESP32 variant

Missing libraries

Required libraries (usually included):
- BluetoothSerial (ESP32 core)
- Preferences (ESP32 core)

Memory issues

If you see watchdog resets:
- Reduce buffer sizes
- Add delay() calls in tight loops
- Check for infinite loops

Power Supply Problems

ESP32 Keeps Rebooting

Symptoms: ESP32 restarts randomly, especially when relays switch

Causes & Solutions:

Insufficient power supply

Solution:
- Use 5V 2A+ power adapter
- Don't power from computer USB (limited to 500mA)
- Add 1000µF capacitor across ESP32 power

Voltage drop when relays activate

Solution:
- Power relay module separately
- Use dedicated 5V supply for relays
- Add bulk capacitors (1000-2200µF)

Ground loops

Solution:
- Ensure all grounds connected (ESP32, relay, power)
- Use star grounding (all grounds to single point)

Relays Click but Don't Switch Load

Symptoms: Relay audibly clicks but load doesn't turn on

Check:

Load wiring

Verify connections:
- Power → Relay COM
- Relay NO → Load positive
- Load negative → Power negative

Relay contact rating

- Check relay specs (usually 10A @ 250VAC)
- Ensure load doesn't exceed rating
- For high current, use contactor instead

Load requires neutral

For AC loads:
- Switch only hot/live wire
- Neutral connects directly to load

ESP32 Won't Power On

Symptoms: No lights, no serial output, completely dead

Solutions:

Check power connections

Multimeter check:
- 5V pin should read ~5V
- 3.3V pin should read ~3.3V
- GND should read 0V

USB cable/port

- Try different USB cable
- Try different USB port
- Try different computer
- Use external 5V power supply

Board may be damaged

- Check for burnt components
- Check for shorts with multimeter
- May need replacement

Serial Communication

No Output in Serial Monitor

Symptoms: Serial Monitor opens but shows nothing

Solutions:

Baud rate mismatch

- Ensure Serial Monitor set to 115200 baud
- Match baud rate in code: Serial.begin(115200);

Wrong COM port

- Tools → Port → Select correct port
- Unplug/replug ESP32 to see which port appears

Reset ESP32

- Press reset button
- Should see boot messages

Garbled/Random Characters

Symptoms: Serial Monitor shows gibberish

Solutions:

Baud rate mismatch

- Double check 115200 baud
- Try 9600 baud as test

Loose USB connection

- Reseat USB cable
- Try different cable

Defective USB-Serial chip

- Board may be damaged
- Try different ESP32 board

Home Assistant Integration

Bluetooth Serial Not Working

Symptoms: Can't connect ESP32 to Home Assistant via Bluetooth

Solutions:

Check HA has Bluetooth

- Raspberry Pi with built-in Bluetooth
- Or USB Bluetooth adapter
- Run: hcitool scan

Find ESP32 MAC address

sudo hcitool scan
# Note MAC address of ESP32-Relay-8CH

Pair manually first

bluetoothctl
scan on
# Wait for ESP32 to appear
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX

Check integration installed

- Settings → Devices & Services
- Add Integration → Bluetooth Serial
- May need HACS for some integrations

ESPHome Won't Compile

Symptoms: ESPHome configuration has errors

Solutions:

Check YAML syntax

- Indentation matters (use 2 spaces)
- No tabs allowed
- Validate YAML online

GPIO pin conflicts

- Don't use reserved pins
- Ensure no duplicate pin assignments

Update ESPHome
```
pip install --upgrade esphome
```

Hardware Verification

Step-by-Step Hardware Test

Basic Test Procedure:

Visual Inspection

Check:
- No loose wires
- No shorts (touching wires)
- Proper connections
- LEDs on boards light up

Power Test

Using multimeter:
- ESP32 5V pin: ~5V
- ESP32 3.3V pin: ~3.3V
- Relay VCC: ~5V
- All GNDs connected: 0V between any GND points

GPIO Test

Upload blink sketch to test GPIO:
- Use single_relay_test.ino example
- Test one relay at a time
- Confirm relay clicks

Bluetooth Test

- Pair with phone
- Send STATUS command
- Verify response
- Send ON1 command
- Verify relay activates

Load Test (CAREFUL!)

Start with low voltage:
- 12V LED strip (safe)
- Then 24V device
- Finally AC device (with proper safety)

Multimeter Quick Reference

Testing Relay Module:

Measure between relay VCC and GND: Should read 5V ±0.5V
Measure between ESP32 GPIO and GND when OFF: Should read 3.3V
Measure between ESP32 GPIO and GND when ON: Should read 0V
Measure relay coil when triggered: Should have low resistance (< 100Ω)
Measure relay contacts NO-COM when OFF: Should be open (infinite resistance)
Measure relay contacts NO-COM when ON: Should be closed (< 1Ω)

Getting More Help

If none of these solutions work:

Check serial monitor output - Copy exact error messages
Take photos of your wiring - Visual inspection helps
Document your setup - Board model, relay model, power supply
Open an issue on the repository with all above information

Issue Template

**Problem Description:**
[Brief description]

**Hardware:**
- ESP32 Board: [model]
- Relay Module: [model]  
- Power Supply: [voltage/current]

**Software:**
- Arduino IDE: [version]
- ESP32 Core: [version]

**Serial Output:**

[paste serial monitor output here]


**Photos:**
[Attach clear photos of wiring]

**What I've Tried:**
- [List troubleshooting steps attempted]

Document Version: 1.0
Last Updated: December 2025

Found a solution not listed here? Please contribute to this guide!

13 KiB Raw Permalink Blame History

Troubleshooting Guide

Table of Contents

Bluetooth Issues

ESP32 Not Appearing in Bluetooth Scan

Can't Connect After Pairing

Connection Keeps Dropping

Relay Problems

Relays Not Switching

Relays Switch Opposite (ON is OFF, OFF is ON)

Only Some Relays Work

Relays Stuck ON or OFF

Upload/Programming Issues

"Failed to connect to ESP32"

Upload Succeeds but ESP32 Doesn't Boot

Code Compiles but Has Errors

Power Supply Problems

ESP32 Keeps Rebooting

Relays Click but Don't Switch Load

ESP32 Won't Power On

Serial Communication

No Output in Serial Monitor

Garbled/Random Characters

Home Assistant Integration

Bluetooth Serial Not Working

ESPHome Won't Compile

Hardware Verification

Step-by-Step Hardware Test

Multimeter Quick Reference

Getting More Help

Issue Template

13 KiB

Raw Permalink Blame History