ESP32 Firmware
Build, flash, provision, and maintain the WakeLink firmware that bridges encrypted relay traffic to local Wake-on-LAN packets.
agent_id) and relies on locally provisioned E2E secrets to securely interact with the relay. Hardware Requirements
| Item | Details |
|---|---|
| MCU | ESP32 (tested on ESP32-WROOM-32) |
| Flash | 4 MB recommended |
| Wi-Fi | 2.4 GHz 802.11 b/g/n |
| Status LED | GPIO2 by default |
Agent Provisioning
Provisioning is the process of loading the unique configuration into the ESP32's NVS (Non-Volatile Storage).
| Provisioning Data | Source | Storage |
|---|---|---|
| Agent ID | Hardware (MAC) | ESP32 NVS |
| Relay Access Token (wla_) | Relay Dashboard | ESP32 NVS (Hashed) |
| EWSP E2E Secret | Client (Wizard) | ESP32 NVS (Plaintext) |
| Wi-Fi Credentials | User | ESP32 NVS |
agent_token) must be generated by your client and never sent to the relay server. The Relay Access Token (wla_...) is provided by the relay for WebSocket authentication. Build
WakeLink firmware is built with emdformer (emdf) — our Cargo-style build & package manager for embedded firmware. It vendors the ESP32 toolchain and libraries per project into a local cache, so there are no global Arduino IDE or PlatformIO installs to manage. One tool covers resolve, build, flash and serial monitor.
# From the firmware project directory (contains emdformer.toml)
emdf install # resolve + fetch toolchain, core and libraries
emdf build --profile release # compile the firmware
emdf flash # auto-detects the serial port
emdf flash --port /dev/ttyUSB0
emdf monitor --baud 115200 # open the serial consoleProvisioning
On first boot, the agent starts an AP named WakeLink-Setup. The AP password is an 8-character random string stored in NVS and printed to the serial console on first boot.
Browser portal
Open http://192.168.4.1 and fill in:
| Field | Description |
|---|---|
| wifi_ssid | Your Wi-Fi network name |
| wifi_pass | Wi-Fi password |
| server_host | WakeLink relay hostname |
| server_port | Usually 443 |
| tls_enabled | Enable WSS/TLS |
| agent_id | Registered agent identifier |
| agent_token | EWSP shared secret |
| api_token | Relay API token used for the WebSocket auth step |
JSON API
The Android wizard authenticates to the AP JSON API with the AP password and then sends the same fields programmatically.
{
"wifi_ssid": "MyNetwork",
"wifi_pass": "secret",
"server_host": "wakelink-project.org",
"server_port": 443,
"tls_enabled": true,
"agent_id": "esp32-living-room",
"agent_token": "your-ewsp-secret",
"api_token": "wla_your_device_relay_token"
}Local Interfaces
| Interface | Details |
|---|---|
| TCP command port | Port 7625 for direct LAN EWSP commands |
| Status HTTP endpoint | GET /api/info for discovery and health checks |
| Provisioning portal | http://192.168.4.1 while AP mode is active |
| Local WebSocket server | Port 81 for LAN EWSP sessions when enabled |
Supported Commands
| Command | Description |
|---|---|
| ping | Round-trip latency test |
| info | Return firmware version, uptime, and identifiers |
| status | Return Wi-Fi RSSI, heap, and connection state |
| wake | Send a Wake-on-LAN magic packet |
| reboot | Restart the ESP32 |
| ota | Download and flash a new firmware image |
| update_token | Replace the stored per-agent relay token used for WebSocket auth |
OTA Signing
Production OTA images are verified with an Ed25519 public key baked into the firmware.
pip install pynacl
python3 scripts/sign_ota.py --gen-key ota_private.key
python3 scripts/sign_ota.py --key ota_private.key \
--bin .emdformer/build/release/firmware.bin Use -DWAKELINK_OTA_PUBKEY_HEX=... to embed the matching public key. Developer builds can bypass signature checks with -DWAKELINK_OTA_ALLOW_UNSIGNED=1, but that should never be enabled in production.
Source Layout
| File / Directory | Purpose |
|---|---|
| WakeLink.ino | Firmware entry point |
| config.* | Persistent configuration and NVS helpers |
| provisioning.* | AP portal and JSON provisioning API |
| cloud.* | Relay WebSocket client and reconnect logic |
| commands.* | EWSP command handlers |
| ota_manager.* | OTA download and verification |
| ws_server.* | Local WebSocket server |
| web_server.* | Status and provisioning HTTP endpoints |