Troubleshooting

Diagnose the most common WakeLink problems across flashing, provisioning, relay connectivity, and wake delivery.

agent Won't Wake Up

1 Check Wake-on-LAN in BIOS

Enter BIOS/UEFI setup (usually Del or F2 during boot) and look for "Wake on LAN", "WOL", or "Resume by PCI-E agent". 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.

2 Verify MAC Address

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"

Warning

Common mistake: Using the WiFi MAC instead of the Ethernet MAC. Wake-on-LAN requires a wired connection.

3 Confirm Power Supply Connected

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.

4 Disable Fast Startup (Windows)

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.

5 Check ESP32 Agent Status

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

ESP32 Agent Shows Offline

1 Check WiFi Connection

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

2 Verify Server Connection

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

3 Check Router/Firewall Settings

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

4 Power Cycle ESP32

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

WiFi Connection Problems

1 Can't See WakeLink-Setup AP

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

2 ESP32 Won't Connect to 5 GHz WiFi

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.

3 Frequent Disconnections

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 agents)
Update router firmware or try a different WiFi channel

ESP32 Flashing Failures

1 Fix "Failed to connect" Error

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)

2 Fix "A fatal error occurred" During Flash

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

3 Fix "Hash of data verified" Never Appears

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.

App & Dashboard Issues

1 Can't Log In

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

2 agents Not Showing Up

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

3 "Network Error" When Waking agent

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

Performance & Latency

1 Slow Wake Response (>5 seconds)

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

2 ESP32 High Memory Usage

# 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.

Warning

Free heap below 50 KB is concerning and may cause instability. Update to the latest firmware — it includes memory optimisations.

Enable Debug Logging

Note

For detailed troubleshooting, enable verbose logs. Debug output appears in the serial console (ESP32) or terminal (CLI).

1 ESP32 Serial Console

screen /dev/ttyUSB0 115200
# Power-cycle or reboot the board and capture the boot logs

2 CLI Help and Command Shape

wakelink --help
wakelink wake --help
wakelink info --help

Still Need Help?

Community support: Gitea Discussions for questions, or open a Gitea Issue to report a bug.

When asking for help, include:

Information	Description
ESP32 firmware version	Check via serial console: > version
App / CLI version	Check app About page or run wakelink --version
Operating system	Windows 10/11, Linux distro, macOS version
Serial console output	If applicable - copy error messages
Steps to reproduce	Exact steps that cause the issue
Screenshots	Visual proof of error messages or unexpected behavior

Quick Reference Commands

# ESP32 serial console
screen /dev/ttyUSB0 115200

# CLI registry and diagnostics
wakelink list
wakelink ping desk
wakelink info desk
wakelink capabilities desk
wakelink wake desk AA:BB:CC:DD:EE:FF

# Firmware flashing / hardware detection
ping <agent-ip>
esptool.py --port /dev/ttyUSB0 flash_id