Add comprehensive troubleshooting guide
This commit is contained in:
639
docs/TROUBLESHOOTING.md
Normal file
639
docs/TROUBLESHOOTING.md
Normal file
@@ -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!
|
||||
Reference in New Issue
Block a user