Sign inSign up
Sign in

OTA Updates

Ship signed ESP32 firmware updates over Wi-Fi with SHA-256 verification, Ed25519 signatures, and safe rollout practices.

Overview

The firmware can update itself when a client sends the EWSP ota command (or when an ota_url is stored in configuration). A normal OTA flow looks like this:

1Send the OTA command

A client such as the WakeLink CLI sends the firmware URL to the agent.

2Download the binary

The ESP32 fetches the image over HTTP or HTTPS.

3Verify the payload

The agent optionally verifies a SHA-256 checksum and, in production builds, verifies the detached Ed25519 signature.

4Flash and reboot

If verification succeeds, the firmware is written and the board restarts into the new image.

Trigger an Update

Use the CLI with a registered agent entry:

bash
wakelink ota desk https://wakelink-project.org/downloads/wakelink-esp32.bin

wakelink ota desk https://wakelink-project.org/downloads/wakelink-esp32.bin --sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Any other client that speaks EWSP can send the same OTA command format.

Signing Images

The firmware repository includes a helper for generating a signing key and producing detached signatures:

bash
pip install pynacl

# One-time key generation
python3 scripts/sign_ota.py --gen-key ota_private.key

# Sign a built firmware image
python3 scripts/sign_ota.py --key ota_private.key --bin WakeLink/.pio/build/esp32/firmware.bin

Embed the matching public key with -DWAKELINK_OTA_PUBKEY_HEX=... in your build flags. Unsigned developer builds are possible with -DWAKELINK_OTA_ALLOW_UNSIGNED=1, but that flag is only for local development.

Security Model

FeatureDetails
Command transport
OTA requests travel over EWSP, so the relay never sees plaintext command data
Checksum verification
The CLI can supply a SHA-256 digest for integrity checking
Detached signatures
Production firmware can require an Ed25519 signature before flashing
TLS support
Use HTTPS-hosted binaries whenever possible

Troubleshooting

⚠️Warning
  • Make sure the firmware URL is reachable from the ESP32's network
  • Re-check the --sha256 value if checksum verification fails
  • Confirm the public signing key in the firmware matches the private key used to sign the image
  • Keep a known-good release available so you can push it again if a new build is bad

Continue reading

Device ProvisioningOverview