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:

1 Send the OTA command

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

2 Download the binary

The ESP32 fetches the image over HTTP or HTTPS.

3 Verify the payload

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

4 Flash 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: 

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: 

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 transportOTA requests travel over EWSP, so the relay never sees plaintext command data
Checksum verificationThe CLI can supply a SHA-256 digest for integrity checking
Detached signaturesProduction firmware can require an Ed25519 signature before flashing
TLS supportUse 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