Store a signed firmware bundle, roll it out in waves, collect device acknowledgements, and roll back a bad version without leaving devices half-updated.

A firmware update backend has a different shape from a command queue. The file is large, it has to be signed, it has to reach a subset of the fleet first, and a bad version has to be withdrawn without leaving devices stuck between two images.
AWS IoT Jobs and similar vendor features already cover some of that on a single cloud. This guide designs a backend you own: signed bundles in object storage, releases, waves, acknowledgements and rollback, then builds it in Go with Encore in your own AWS or GCP account.
The API never streams the firmware through the application process. It issues a signed upload URL for a key it chooses, then confirms the object with size and checksum before the release can be assigned. Devices pull a short-lived signed download URL for their current assignment.
A wave is a filter on device ids (a group tag or a random percentage). You mark the release rolling_out, assign the first wave, and wait for acknowledgements. If the error rate crosses a threshold you set, you pause and assign the previous stable version to that wave. Rollback is a new assignment, not an in-place edit of the bad object.
Encore is a backend framework with built-in infrastructure. You declare the database and a private bucket in the same package as the handlers, and encore run starts local Postgres and stores objects on disk so you can upload a bundle and assign a wave before opening a pull request. On deploy to your own AWS or GCP account, Encore provisions those resources and Encore provisions an IAM role for the service, or a service account on GCP.
Run in your terminal to get started locally.
-- ota/migrations/1_firmware.up.sql
CREATE TABLE releases (
id TEXT PRIMARY KEY,
version TEXT NOT NULL UNIQUE,
object_key TEXT NOT NULL,
checksum TEXT NOT NULL,
signature TEXT NOT NULL,
status TEXT NOT NULL CHECK (status IN ('draft', 'rolling_out', 'paused', 'rolled_back', 'stable')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE devices (
id TEXT PRIMARY KEY,
device_group TEXT NOT NULL,
token_hash TEXT NOT NULL UNIQUE, -- SHA-256 of the device API token
reported TEXT,
assigned TEXT REFERENCES releases (id),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE wave_events (
id BIGSERIAL PRIMARY KEY,
release_id TEXT NOT NULL REFERENCES releases (id),
wave TEXT NOT NULL,
action TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
// ota/ota.go
package ota
import (
"context"
"crypto/sha256"
"encoding/hex"
"strconv"
"strings"
"time"
"encore.dev/beta/errs"
"encore.dev/storage/objects"
"encore.dev/storage/sqldb"
)
var db = sqldb.NewDatabase("ota", sqldb.DatabaseConfig{Migrations: "./migrations"})
var bundles = objects.NewBucket("firmware", objects.BucketConfig{})
type AssignIn struct {
ReleaseID string `json:"release_id"`
Wave string `json:"wave"` // a device_group, or "percent:5"
}
//encore:api private method=POST path=/releases/:id/waves
func AssignWave(ctx context.Context, id string, in AssignIn) error {
var err error
if pctStr, ok := strings.CutPrefix(in.Wave, "percent:"); ok {
pct, convErr := strconv.Atoi(pctStr)
if convErr != nil || pct < 1 || pct > 100 {
return &errs.Error{Code: errs.InvalidArgument, Message: "wave must be a device group or percent:1-100"}
}
// md5(id) is stable, so a retry of the same percentage assigns the same devices.
_, err = db.Exec(ctx, `
UPDATE devices SET assigned = $1, updated_at = now()
WHERE (assigned IS DISTINCT FROM $1)
AND (('x' || substr(md5(id), 1, 8))::bit(32)::bigint % 100) < $2`, id, pct)
} else {
_, err = db.Exec(ctx, `
UPDATE devices SET assigned = $1, updated_at = now()
WHERE device_group = $2
AND (assigned IS DISTINCT FROM $1)`, id, in.Wave)
}
if err != nil {
return err
}
_, err = db.Exec(ctx, `
INSERT INTO wave_events (release_id, wave, action)
VALUES ($1, $2, 'assigned')`, id, in.Wave)
return err
}
type deviceAuth struct {
Token string `header:"X-Device-Token"`
}
func checkDevice(ctx context.Context, id, token string) error {
if token == "" {
return &errs.Error{Code: errs.Unauthenticated, Message: "unknown device or token"}
}
sum := sha256.Sum256([]byte(token))
var found string
err := db.QueryRow(ctx, `
SELECT id FROM devices WHERE id = $1 AND token_hash = $2`,
id, hex.EncodeToString(sum[:])).Scan(&found)
if err != nil {
return &errs.Error{Code: errs.Unauthenticated, Message: "unknown device or token"}
}
return nil
}
type BundleOut struct {
URL string `json:"url"`
Version string `json:"version"`
Checksum string `json:"checksum"`
Signature string `json:"signature"`
}
//encore:api public method=GET path=/devices/:id/firmware
func DeviceFirmware(ctx context.Context, id string, auth deviceAuth) (*BundleOut, error) {
if err := checkDevice(ctx, id, auth.Token); err != nil {
return nil, err
}
var key, version, checksum, signature string
err := db.QueryRow(ctx, `
SELECT r.object_key, r.version, r.checksum, r.signature
FROM devices d JOIN releases r ON r.id = d.assigned
WHERE d.id = $1 AND r.status IN ('rolling_out', 'stable')`, id).Scan(&key, &version, &checksum, &signature)
if err != nil {
return nil, err
}
signed, err := bundles.SignedDownloadURL(ctx, key, objects.WithTTL(15*time.Minute))
if err != nil {
return nil, err
}
return &BundleOut{URL: signed.URL, Version: version, Checksum: checksum, Signature: signature}, nil
}
type AckIn struct {
Token string `header:"X-Device-Token"`
Version string `json:"version"`
}
//encore:api public method=POST path=/devices/:id/ack
func Ack(ctx context.Context, id string, in AckIn) error {
if err := checkDevice(ctx, id, in.Token); err != nil {
return err
}
res, err := db.Exec(ctx, `
UPDATE devices SET reported = $2, updated_at = now()
WHERE id = $1 AND assigned IN (SELECT id FROM releases WHERE version = $2)`,
id, in.Version)
if err != nil {
return err
}
if res.RowsAffected() == 0 {
return &errs.Error{Code: errs.FailedPrecondition, Message: "version is not the assigned release"}
}
return nil
}
Confirm the uploaded object with Attrs and store the checksum before the release leaves draft. A rollback is AssignWave with the previous stable release id, plus a wave_events row with action rolled_back. Device pull and acknowledgement require the per-device token in X-Device-Token, and an acknowledgement is recorded only when it matches the assigned release. A percent:N wave selects devices with a stable hash of the device id, so a retry assigns the same set. This is the opposite direction from an IoT device command backend, which pushes commands; this backend lets the device pull a bundle.
Best fit: a fleet that needs signed, waved firmware updates in private object storage.
Keep the bundle in a private S3 or Cloud Storage bucket, and store release rows (version, signature, object key) and assignment rows (device or wave, target version) in Postgres. Authenticate the device with a per-device credential before issuing a download URL or recording an acknowledgement. The device pull endpoint looks up the assignment, signs a short-lived download URL with the bucket's IAM credentials, and records the version the device reports after boot only when it matches that assignment. Pause a wave by stopping new assignments when error reports cross a threshold you define. The same model works if the bucket and database already live in Terraform.
Use Encore when you want the bucket, the release tables and the device pull API in one Go service, with local objects and Postgres under encore run. Use AWS IoT Jobs or a similar vendor feature when the fleet is already enrolled there and you are happy to keep update state in that product. In both cases, trust the version the device reports after boot, not only the download.
Store a signed bundle in private object storage, record a release with a version and a signature, and let devices pull a short-lived signed download URL for the bundle they are assigned. The device reports the version it booted, not only that it downloaded the file.
A wave is a subset of devices, often a percentage or a device group, that is assigned a release before the rest of the fleet. If health checks or error reports from that wave fail a threshold, you pause or roll back instead of continuing.
Create a new assignment back to the last known good version, or to a dedicated rollback bundle, and have devices pull that package the same way they pull a forward update. Do not delete the bad object until you are sure no device needs it for diagnosis.
Declare a private bucket, a Postgres database and a topic for assignment events in Go. The upload path returns a signed URL, the assign path writes wave membership, and the device path returns a signed download URL. encore run stores objects on disk and starts Postgres locally. On deploy, Encore provisions those resources in your own AWS or GCP account.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.