esp32-bluetooth-relay/docs/TROUBLESHOOTING.md

# Troubleshooting Guide

Common issues and solutions for the ESP32 Bluetooth Relay Controller.

## Table of Contents

1. [Bluetooth Issues](#bluetooth-issues)
2. [Relay Problems](#relay-problems)
3. [Upload/Programming Issues](#uploadprogramming-issues)
4. [Power Supply Problems](#power-supply-problems)
5. [Serial Communication](#serial-communication)
6. [Home Assistant Integration](#home-assistant-integration)
7. [Hardware Verification](#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:**

1. **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
   ```

2. **ESP32 already paired with another device**
   ```
   Solution: 
   - Unpair ESP32 from all devices
   - Power cycle the ESP32
   - Try scanning again
   ```

3. **ESP32 not running/crashed**
   ```
   Solution:
   - Check serial monitor for boot messages
   - Look for "Bluetooth device ready to pair" message
   - Press reset button on ESP32
   ```

4. **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:**

1. **Clear pairing and re-pair**
   ```
   Steps:
   - Forget/unpair the device
   - Restart ESP32
   - Restart your phone/computer
   - Pair fresh
   ```

2. **Check serial monitor**
   ```
   Look for error messages indicating:
   - Memory issues
   - Bluetooth stack errors
   - Connection timeouts
   ```

3. **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:**

1. **Distance issue**
   ```
   - Move closer to ESP32 (< 10 meters)
   - Remove obstacles between devices
   - ESP32 should have clear line of sight
   ```

2. **Power supply instability**
   ```
   - Use quality USB cable
   - Try different power adapter
   - Add capacitor (100-1000µF) across power
   ```

3. **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:**

1. **Check wiring**
   ```
   Verify connections:
   ESP32 GPIO → Relay IN pin
   ESP32 GND → Relay GND
   ESP32 5V → Relay VCC
   ```

2. **Measure voltage at relay input**
   ```
   Using multimeter:
   - When relay should be ON: measure ~0V (LOW)
   - When relay should be OFF: measure ~3.3V (HIGH)
   ```

3. **Test with serial monitor**
   ```
   Open Serial Monitor (115200 baud)
   Send commands manually:
   - Type: ON1
   - Watch for confirmation messages
   - Check if relay clicks
   ```

4. **Verify GPIO pin assignment**
   ```cpp
   // 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:

```cpp
// 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:**

1. **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)
   ```

2. **Damaged relay channels**
   ```
   - Swap relay positions
   - If problem follows relay: relay is bad
   - If problem stays with pin: GPIO issue
   ```

3. **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:**

1. **Check relay manually**
   ```
   - Disconnect from ESP32
   - Apply 5V directly to relay input
   - If still doesn't work: relay is damaged
   ```

2. **GPIO pin may be damaged**
   ```
   - Try different GPIO pin
   - Update pin assignment in code
   ```

3. **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:**

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

2. **Check USB cable**
   ```
   - Use data cable (not charge-only)
   - Try different USB cable
   - Try different USB port
   ```

3. **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
   ```

4. **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:**

1. **Serial monitor for errors**
   ```
   - Open Serial Monitor at 115200 baud
   - Press ESP32 reset button
   - Look for boot messages or errors
   ```

2. **Partition scheme**
   ```
   Arduino IDE:
   - Tools → Partition Scheme
   - Select "Default 4MB with spiffs"
   ```

3. **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:**

1. **Board selection**
   ```
   Ensure correct board:
   - Tools → Board → ESP32 Dev Module
   - Or your specific ESP32 variant
   ```

2. **Missing libraries**
   ```
   Required libraries (usually included):
   - BluetoothSerial (ESP32 core)
   - Preferences (ESP32 core)
   ```

3. **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:**

1. **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
   ```

2. **Voltage drop when relays activate**
   ```
   Solution:
   - Power relay module separately
   - Use dedicated 5V supply for relays
   - Add bulk capacitors (1000-2200µF)
   ```

3. **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:**

1. **Load wiring**
   ```
   Verify connections:
   - Power → Relay COM
   - Relay NO → Load positive
   - Load negative → Power negative
   ```

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

3. **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:**

1. **Check power connections**
   ```
   Multimeter check:
   - 5V pin should read ~5V
   - 3.3V pin should read ~3.3V
   - GND should read 0V
   ```

2. **USB cable/port**
   ```
   - Try different USB cable
   - Try different USB port
   - Try different computer
   - Use external 5V power supply
   ```

3. **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:**

1. **Baud rate mismatch**
   ```
   - Ensure Serial Monitor set to 115200 baud
   - Match baud rate in code: Serial.begin(115200);
   ```

2. **Wrong COM port**
   ```
   - Tools → Port → Select correct port
   - Unplug/replug ESP32 to see which port appears
   ```

3. **Reset ESP32**
   ```
   - Press reset button
   - Should see boot messages
   ```

### Garbled/Random Characters

**Symptoms:** Serial Monitor shows gibberish

**Solutions:**

1. **Baud rate mismatch**
   ```
   - Double check 115200 baud
   - Try 9600 baud as test
   ```

2. **Loose USB connection**
   ```
   - Reseat USB cable
   - Try different cable
   ```

3. **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:**

1. **Check HA has Bluetooth**
   ```
   - Raspberry Pi with built-in Bluetooth
   - Or USB Bluetooth adapter
   - Run: hcitool scan
   ```

2. **Find ESP32 MAC address**
   ```bash
   sudo hcitool scan
   # Note MAC address of ESP32-Relay-8CH
   ```

3. **Pair manually first**
   ```bash
   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
   ```

4. **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:**

1. **Check YAML syntax**
   ```
   - Indentation matters (use 2 spaces)
   - No tabs allowed
   - Validate YAML online
   ```

2. **GPIO pin conflicts**
   ```
   - Don't use reserved pins
   - Ensure no duplicate pin assignments
   ```

3. **Update ESPHome**
   ```bash
   pip install --upgrade esphome
   ```

---

## Hardware Verification

### Step-by-Step Hardware Test

**Basic Test Procedure:**

1. **Visual Inspection**
   ```
   Check:
   - No loose wires
   - No shorts (touching wires)
   - Proper connections
   - LEDs on boards light up
   ```

2. **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
   ```

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

4. **Bluetooth Test**
   ```
   - Pair with phone
   - Send STATUS command
   - Verify response
   - Send ON1 command
   - Verify relay activates
   ```

5. **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:

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

### Issue Template

```markdown
**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!