First Agent Setup

Flash an ESP32, provision it onto Wi-Fi, register it with the relay, and wake your first computer through WakeLink.

What You Need

ItemRequirement
ESP32 boardESP32-WROOM-32, ESP32-DevKitC, or similar
USB cableData-capable cable for flashing
ComputerPython 3.7+ and pip
WakeLink accountCreate one for free
2.4 GHz Wi-FiESP32 provisioning uses 2.4 GHz networks
Target computerWake-on-LAN enabled in BIOS/UEFI and OS
Note
Enable Wake-on-LAN on the target computer first. On Windows, open agent Manager → Network Adapters → Properties → Power Management and allow the adapter to wake the system. In BIOS/UEFI, look for Wake on LAN, Power On By PCI-E, or similar labels.

1 Install esptool

pip install esptool
esptool.py version
Use pip3 instead of pip if your system requires it.

2 Download the Firmware

  1. Open the Downloads page
  2. Download wakelink-esp32.bin
  3. Save it somewhere easy to find
Note
Verify the SHA-256 checksum shown on the downloads page before flashing a production agent.

3 Flash the Firmware

# Linux / macOS
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 \
  write_flash 0x0 wakelink-esp32.bin

# Windows
esptool.py --chip esp32 --port COM3 --baud 460800 \
  write_flash 0x0 wakelink-esp32.bin
If the board stalls at Connecting..., hold BOOT (or IO0) until the flash starts.

4 Connect to the Setup Hotspot

After the first boot, the ESP32 starts AP provisioning mode.
  1. Connect to the Wi-Fi network named WakeLink-Setup
  2. Use the AP password shown on the serial console banner
  3. Open http://192.168.4.1 in a browser, or continue in the Android setup wizard
  4. Expect the network to say No internet while provisioning

5 Configure Provisioning

The browser portal and Android setup wizard write the same configuration values.
FieldDescription
WiFi SSIDYour 2.4 GHz network name
WiFi PasswordPassword for that network
Server HostRelay hostname, for example wakelink-project.org
Server PortUsually 443
Use TLSEnable WSS for normal deployments
Agent IDHardware-generated identifier (shown in the setup portal banner)
E2E SecretThe shared EWSP agent_token generated by the setup wizard
Relay TokenThe per-agent relay token (wla_…) issued by the dashboard
Note
The setup wizard discovers the Agent ID from the hardware, registers it with the relay to receive a Relay Token (wla_...), and generates a unique E2E Secret (agent_token) locally. All three values must be saved to the agent.
Click Save & Connect. The agent stores the configuration in NVS, reboots, connects to Wi-Fi, and then opens its relay session.

6 Add the Computer to WakeLink

  1. Open the Dashboard
  2. Click Add agent
  3. Enter the target computer's MAC address and a friendly name
  4. Select the ESP32 agent you just provisioned
  5. Save the agent
# Windows
ipconfig /all

# Linux
ip link show eth0
# or: cat /sys/class/net/eth0/address

# macOS
ifconfig en0 | grep ether

7 Send Your First Wake Command

Android app

  1. Open WakeLink on your phone
  2. Sign in
  3. Tap Wake next to the agent

CLI

wakelink add desk --ip 192.168.1.50 --token "$AGENT_TOKEN"
wakelink wake desk AA:BB:CC:DD:EE:FF
Wake commands are issued by the client and encrypted end-to-end with EWSP before being forwarded through the relay.

Common Issues

ESP32 does not appear as a USB agent

Install the CP2102 or CH340 USB-UART driver used by your development board.

Setup hotspot is not visible

Open a serial monitor at 115200 baud and check the provisioning banner. If the board already has configuration saved, perform a factory reset and boot again.

Agent shows offline in the dashboard

Verify Wi-Fi credentials, relay host and port, and the provisioned token values. The LED should be solid once the board is connected.

Computer does not wake

Re-check BIOS/UEFI Wake-on-LAN settings, OS adapter power settings, and the MAC address saved in WakeLink.

Continue reading