Tutorial 25: Common Connection Issues and Fixes

Diagnostic Checklist (Before Troubleshooting)

Before diving into specific issues, check these basics:

1. ✅ Is your device powered? (Check LED)
2. ✅ Is your USB cable data-capable (not charge-only)?
3. ✅ Is the correct port selected in Arduino IDE?
4. ✅ Is the correct board selected?
5. ✅ Did the firmware upload successfully? (Check Serial Monitor)
6. ✅ Is your 2.4GHz WiFi working? (ESP8266/ESP32/Pico W don't support 5GHz)
7. ✅ Is your account confirmed? (Check email)

Section 1: WiFi Connection Issues

Problem: "WiFi Connecting... Failed" in Serial Monitor

Serial Monitor Output (WiFi Failure):
[WiFi] Connecting... ........ Failed!
[ERROR] Cannot connect to WiFi - restarting

Serial Monitor Output (WiFi Success):
[WiFi] Connecting... Connected!
[WiFi] IP: 192.168.1.100

Problem: WiFi connects but drops frequently

• Cause: Interference or weak signal
• Fix:
  • Move device closer to router
  • Change WiFi channel on router (avoid congested channels)
  • Add external antenna to ESP32 (if supported)
  • Use WiFi repeater/extender

Section 2: Device Not Showing in Dashboard

Problem: Device registers but doesn't appear

1. Check Serial Monitor for registration message:

   [REG] Response: 200
   [REG] ✓ Registered!

2. Check your dashboard after 10-15 seconds (may take time to appear)
3. Refresh the page (Ctrl+F5)
4. Check if device appears in "Pending Devices" section
5. Verify you're logged into the same account used to generate firmware

Problem: "Registration failed" error

Section 3: Relay Problems

Problem: Relay doesn't click when button is pressed

1. Check VCC connection (relay needs 5V, not 3.3V)
2. Check GND connection
3. Check IN pin connection to correct GPIO
4. Verify relay logic (Positive vs Negative) in dashboard
5. Test GPIO pin with a multimeter or LED

Test GPIO Pin with Multimeter:
1. Set multimeter to DC voltage (20V range)
2. Connect black probe to GND, red probe to GPIO pin
3. Click relay button in dashboard
4. Voltage should change: 0V → 3.3V (or 3.3V → 0V depending on logic)

Problem: Relay clicks but connected device doesn't turn on

• Check COM and NO/NC wiring
• Most loads connect to COM and NO (Normally Open)
• Verify the connected device is powered
• Check relay contact rating (don't exceed maximum current)

Relay Terminal Explanation:
┌─────────────────────────────────────────────┐
│  COM (Common)    → Connected to device power│
│  NO (Normally Open)   → Connected to device │
│  NC (Normally Closed) → Connected to device │
│                     (opposite of NO)        │
│                                             │
│  Relay OFF: COM connected to NC             │
│  Relay ON:  COM connected to NO             │
└─────────────────────────────────────────────┘

Problem: Relay chatters or buzzes

• Cause: Insufficient power or electrical noise
• Fix:
  • Add 100µF capacitor across VCC and GND of relay module
  • Use external power supply for relays
  • Check if GPIO pin is floating (should be driven HIGH or LOW)

Problem: Wrong relay activates (e.g., Relay 2 activates when clicking Relay 1)

• Check IN pin wiring (IN1 → GPIO for relay 1, etc.)
• Verify pin mapping in firmware matches your wiring
• Check for short circuits between IN pins

Section 4: Sensor Problems

Problem: DHT22 shows "Invalid resistance" or no readings

Problem: DS18B20 shows -127°C

• Cause: Missing pull-up resistor
• Fix: Add 4.7kΩ resistor between DATA and 3.3V
• Alternative: Enable internal pull-up in software (less reliable)

Problem: NTC Thermistor shows incorrect temperature

• Check voltage divider circuit (NTC between 3.3V and A0, 10kΩ resistor between A0 and GND)
• Verify Beta value matches your NTC (common values: 3950, 3435, 4250)
• Check R25 value (usually 10kΩ or 100kΩ)
• Use calibration offset in dashboard

Section 5: Power Problems

Problem: Device resets when turning on relay

• Cause: Power supply cannot provide enough current
• Fix:
  • Use external 5V 2A+ power supply for relays
  • Add 1000µF capacitor across power supply
  • Use separate power supplies for microcontroller and relays (connect grounds)

Separate Power Supply Wiring:
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  USB Power (5V)         External 5V Power Supply (2A+)      │
│  ┌─────────┐            ┌──────────────┐                    │
│  │ ESP8266 │            │ Relay Module │                    │ 
│  ├─────────┤            ├──────────────┤                    │
│  │   VIN   │            │     VCC      │                    │
│  │   GND   ├────────────┤     GND      │                    │
│  └─────────┘            └──────────────┘                    │
│                                                             │
│  Connect GND of both power supplies together!               │
└─────────────────────────────────────────────────────────────┘

Problem: Device randomly resets or crashes

• Check power supply stability
• Add 100µF capacitor near the microcontroller's power pins
• Check for electrical interference (keep high-voltage wires away)
• Update to latest firmware version

Section 6: Upload Problems

ESP8266: "Timed out waiting for packet header"

• Hold FLASH button on board while uploading
• Lower upload speed to 115200
• Try different USB cable
• Check port selection

ESP32: "Failed to connect to ESP32: Timed out"

• Hold BOOT button while uploading
• Release when you see "Connecting..."
• Lower upload speed to 115200
• Press EN/RST after upload attempt

Pico W: "RPI-RP2" drive not appearing

• Hold BOOTSEL for 5 seconds before connecting USB
• Try different USB cable (many are charge-only)
• Try different USB port
• Press RUN button after connecting

Section 7: Serial Monitor Debugging

What to look for in Serial Monitor:

✅ GOOD (Working Device):
########################################
# OceanicRemote v4.4 - ESP8266 D1 Mini #
########################################
[SYSTEM] Device ID: ESP_AABBCCDDEEFF
[WiFi] Connecting... Connected!
[WiFi] IP: 192.168.1.100
[REG] Registering...
[REG] ✓ Registered!
[SESSION] Got session: a1b2c3d4
[SENSOR] DHT22 - Temp: 23.5°C, Hum: 45.2%
.... (dots indicate polling)

❌ BAD (Common Errors):
[WiFi] Connecting... Failed!
[ERROR] Cannot connect to WiFi - restarting

[REG] Response: 401
[REG] Invalid token

[SENSOR] DHT22 read failed!
[SENSOR] Temp: -999°C

[STATE] Token invalid
[STATE] Device not found

Section 8: Dashboard Debugging

Check Device Status Colors:

• 🟢 ONLINE (Green) - Device communicating (last 10 seconds) → Good
• 🟡 AWAY (Yellow) - Device missed 1-2 polls (10-300 seconds) → Check WiFi
• 🔴 OFFLINE (Red) - No communication for 5+ minutes → Power cycle device

Browser Console Debugging (F12):

• Open browser developer tools (F12)
• Go to Console tab
• Look for red error messages
• Check Network tab for API call responses

Quick Reference Troubleshooting Table

Next Steps

Now that you know how to troubleshoot common issues:

• Tutorial 26: Understanding Device Status (Online/Away/Offline)
• Tutorial 27: How to Claim and Manage Devices
• Tutorial 29: WiFi Connection Troubleshooting
• Return to Tutorial 02: Generate fresh firmware if needed