Nov 17, 20267 min read

IoT Firmware Update Backend: Signed Bundles, Rollout Waves and Rollback

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

Illustration for IoT Firmware Update Backend: Signed Bundles, Rollout Waves and Rollback

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.

Firmware updates at a glance

PieceWhat it stores or does
BundleA private object, uploaded through a signed URL, with size and checksum recorded after Attrs
ReleaseA version string, a signature, a pointer at the object key, and a status of draft, rolling_out, paused, rolled_back or stable
WaveA named subset or percentage of device ids assigned to a release
AssignmentThe release a device should boot, plus the time it was told
AcknowledgementThe version the device reports after boot, which may differ from what it was assigned

Waves, signatures and rollback

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.

How do you build this with Encore?

Encore

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.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

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.

Signed URLs and a releases table by hand

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.

How to choose

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.

Frequently asked questions

How should an IoT firmware update be delivered?

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.

What is a rollout wave?

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.

How do I roll back a bad firmware release?

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.

How do I build this with Encore?

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.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders