Manage firmware

Build, sign, upload, and manage firmware in NervesHub: metadata, delta-updatable images, and deletion rules.

Written By Josh Kalderimis

Last updated About 2 months ago

Firmware is a signed .fw image built from your Nerves project. Each image is identified by a UUID and carries metadata that NervesHub uses to match it to devices and deployment groups.

Firmware metadata

Every firmware records:

Field

Meaning

UUID

Unique identifier for this exact image.

Version

The version from your project (mix.exs).

Platform

The firmware platform.

Architecture

The CPU architecture.

Delta updatable

Whether this image supports firmware deltas.

Platform and architecture matter because a deployment group is locked to one of each: a group only accepts firmware that matches.

Read a built image's UUID with fwup:

fwup -i my_project.fw -m --metadata-key meta-uuid

Build and sign

Firmware must be signed before NervesHub will accept it. Build, then sign with your key:

export FW_PATH="./_build/${MIX_TARGET}_dev/nerves/images/my_project.fw"

mix firmware

nh firmware sign "$FW_PATH" --key my-key

See Firmware signing & fwup for how signing keys work.

Upload (publish)

Publish a signed image to a product from the CLI:

nh firmware publish "$FW_PATH"

Or upload it in the web UI under Firmware → Upload.

To publish and roll it out in one step, target a deployment group:

nh firmware publish "$FW_PATH" --deploy "My deployment"

List and inspect

nh firmware list

The web UI's Firmware page shows all published images with their version, platform, architecture, and UUID.

Deleting firmware

You can delete firmware you no longer need:

nh firmware delete <uuid>

Firmware attached to a release can't be deleted. Because a deployment group's releases reference specific firmware, remove or supersede the release first, then delete the image. This prevents deleting firmware that devices may still be told to run.

Related