OTA Firmware Updates

Signed binary uploads, staged rollouts, and Ed25519 verification — push firmware to your fleet from the dashboard or API.

Overview

jettyd OTA has three layers of safety:

1. SHA-256 integrity — every upload stores the hash; the device verifies the downloaded binary matches before flashing.
2. Ed25519 signature (optional) — when a signing key is configured, the platform signs the SHA-256 digest and includes the signature in the command params. The device verifies the signature against the tenant public key before accepting the update.
3. Staged rollout — you control what percentage of the target fleet receives the update in the first batch. The platform's background worker dispatches remaining devices only when the current batch reaches a terminal state.

Step-by-step

curl -X POST https://api.jettyd.com/v1/firmware \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@build/firmware.bin" \
  -F "version=1.2.0" \
  -F "device_type=sensor-v2" \
  -F "notes=Adds BLE power-save mode"

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": "1.2.0",
  "sha256": "e3b0c44298fc1c149afb4c8996fb92427ae41e4649b934ca495991b7852b855",
  "size": 524288,
  "signature": "a1b2c3d4…",
  "signature_alg": "ed25519"
}

curl -X POST https://api.jettyd.com/v1/firmware/{firmware_id}/rollout \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type": "group",
    "target_id": "your-device-group-uuid",
    "rollout_percentage": 20
  }'

curl https://api.jettyd.com/v1/firmware/rollouts \
  -H "Authorization: Bearer $API_KEY"

curl https://api.jettyd.com/v1/devices/{device_id}/firmware-status \
  -H "Authorization: Bearer $API_KEY"

curl -X POST https://api.jettyd.com/v1/firmware/rollouts/{rollout_id}/cancel \
  -H "Authorization: Bearer $API_KEY"

Device Groups

Group devices logically for targeted rollouts — for example, a staging-fleet group for canary testing before rolling out to all production devices.

Create a group

curl -X POST https://api.jettyd.com/v1/groups \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging-fleet"}'

Add devices

curl -X POST https://api.jettyd.com/v1/groups/{group_id}/members \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "your-device-uuid"}'

You can also manage groups from the dashboard at Device Groups in the left nav.

Ed25519 Signature Verification

When a firmware signing key is configured in the platform, every upload generates an Ed25519 signature over the SHA-256 digest of the binary. The signature is included in the OTA command params as a hex-encoded 64-byte string.

Get the public key

curl https://api.jettyd.com/v1/firmware/public-key \
  -H "Authorization: Bearer $API_KEY"

{
  "algorithm": "ed25519",
  "public_key": "abc123…"
}

Bake this 64-hex-character public key into your firmware at build time. It never changes for a given tenant.

Verification (ESP-IDF / C example)

On-device verification pseudocode using mbedTLS or a minimal Ed25519 library:

/* 1. Download binary and compute SHA-256 */
mbedtls_sha256(firmware_buf, firmware_len, digest, 0);  /* digest = 32 bytes */

/* 2. Decode hex fields from the OTA command params */
uint8_t pub_key[32];   hex_decode(pub_key_hex, pub_key, 32);
uint8_t sig[64];        hex_decode(sig_hex, sig, 64);

/* 3. Verify Ed25519 signature over the digest (NOT the full binary) */
if (ed25519_verify(sig, digest, 32, pub_key) != 0) {
    ESP_LOGE(TAG, "OTA signature verification FAILED — rejecting update");
    return ESP_FAIL;
}

/* 4. Flash the verified binary */
esp_ota_write(ota_handle, firmware_buf, firmware_len);

Verification (Python / CI example)

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
import hashlib, requests

pub_key_hex = "abc123…"  # from /v1/firmware/public-key
sig_hex = "a1b2c3d4…"   # from OTA command params

firmware = open("firmware.bin", "rb").read()
digest = hashlib.sha256(firmware).digest()

pub_key = Ed25519PublicKey.from_public_bytes(bytes.fromhex(pub_key_hex))
sig = bytes.fromhex(sig_hex)

pub_key.verify(sig, digest)  # raises InvalidSignature on failure
print("Signature valid")

Configuring the Signing Key

Generate a random 32-byte seed and set it as the FIRMWARE_SIGNING_KEY environment variable on the platform. The platform derives the Ed25519 signing key and verifying key from this seed.

# Generate a secure random seed (32 bytes = 64 hex chars)
openssl rand -hex 32

Set FIRMWARE_SIGNING_KEY=<output> in your platform environment variables. Treat this like a private key — rotate it only if compromised, and never expose it outside the server. The corresponding public key is available via GET /v1/firmware/public-key at any time.

API Quick Reference