From ac379ed2aceabec05f122d13c7fa6ac81b301e5d Mon Sep 17 00:00:00 2001 From: jessikitty Date: Mon, 15 Dec 2025 16:17:27 +1100 Subject: [PATCH] Add comprehensive troubleshooting guide --- docs/TROUBLESHOOTING.md | 639 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 639 insertions(+) create mode 100644 docs/TROUBLESHOOTING.md diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..30857fc --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,639 @@ +# 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!