Troubleshooting

Enter BIOS/UEFI setup (usually Del or F2 during boot) and look for "Wake on LAN", "WOL", or "Resume by PCI-E Device". Enable it — it may be under Power Management or Advanced settings. Some boards also require "PME Event Wake Up" to be enabled. Save and exit BIOS.

Ensure the MAC address registered in WakeLink matches your network adapter:

# Windows
ipconfig /all
# Look for "Physical Address" under your ethernet adapter

# Linux / macOS
ip addr show
# or: ifconfig
# Look for "ether" or "HWaddr"

The power supply must remain connected (not unplugged or switched off at the wall). The motherboard LED should be lit (standby power). Some PSUs have an eco-mode that cuts all power — disable it.

Disable Fast Startup: Control Panel → Power Options → Choose what the power buttons do → Change settings that are currently unavailable → uncheck "Turn on fast startup" → Save.

Go to Dashboard → Agents and verify the agent shows "Online". If offline, check WiFi and power — see Agent Shows Offline below.

Connect to the agent via serial to see status messages:

screen /dev/ttyUSB0 115200

# Expected output when connected:
[I] WiFi: Connecting to "MyNetwork"...
[I] WiFi: Connected, IP: 192.168.1.4

If stuck on "Connecting...", check:

• WiFi password is correct (case-sensitive)
• You're using a 2.4 GHz network — ESP32 doesn't support 5 GHz
• WiFi has DHCP enabled
• Router MAC filtering is not blocking the ESP32

If WiFi is connected but agent still shows offline:

• Verify API token is correct and not expired
• Confirm server URL: wss://wakelink-project.org/wss (not https://)
• Check firewall allows outbound WebSocket connections on port 443

Some routers block WebSocket connections. Temporarily disable "SPI Firewall" to test. Allow outbound port 443. Try a different WiFi network to isolate the issue.

Unplug ESP32 for 10 seconds, plug back in, and wait 30 seconds. Check the dashboard for the updated status.

• Wait 30–60 seconds after power-on for the setup AP to appear
• LED should blink slowly in setup mode
• The AP only activates when ESP32 can't connect to a saved WiFi network
• Try factory reset: hold BOOT button for 10 seconds
• Ensure you're within 10 m of the ESP32

ESP32 supports 2.4 GHz only. Check if your router has a 2.4 GHz band enabled. Some routers use the same SSID for both bands — create a separate 2.4 GHz SSID if needed.

• Check WiFi signal strength (should be stronger than −70 dBm)
• Move ESP32 closer to the router or use a WiFi extender
• Reduce interference (keep away from microwave, Bluetooth devices)
• Update router firmware or try a different WiFi channel

• Hold the BOOT button while connecting the USB cable
• Try a different USB cable (some are charge-only, no data)
• Reduce baud rate: --baud 115200 instead of 460800
• Install or update USB-to-serial drivers (CP210x or CH340)
• Try a different USB port (USB 2.0 is sometimes more reliable)

Erase flash first, then reflash:

esptool.py --port /dev/ttyUSB0 erase_flash

esptool.py --chip esp32 --port /dev/ttyUSB0 \
write_flash 0x0 wakelink-esp32.bin

Re-download the firmware file (it may be corrupted). Verify the file size matches the expected size (~1.2 MB). Check the SHA256 checksum if provided.

• Double-check email and password — both are case-sensitive
• Use "Forgot Password" to reset if needed
• Clear browser cache or app data
• Try a different browser or incognito mode

• Pull down to refresh (mobile app) or hard refresh the browser (Ctrl+Shift+R)
• Log out and log back in
• Confirm devices exist in the web dashboard

• Check your internet connection
• Check that the API token hasn't expired — rotate if needed
• Wait a few seconds and retry; may be a temporary server issue

Normal latency is 1–3 seconds. If slower: check ESP32 WiFi signal strength, test internet speed on both the mobile device and ESP32 network, and if self-hosted — check server load and database performance.

# Check memory in serial console
[I] Free heap: 45230 bytes  # <50 KB is concerning

If free heap is low, disable debug logging, update to the latest firmware, or reduce WebSocket message frequency.